@zhangzhian/dsh-devtools-terminal 0.0.0-stage → 0.3.0

package/client/client.js

@@ -0,0 +1,1380 @@
+window.__ModuleLoader__.load({
+	id: "@zhangzhian/dsh-devtools-terminal",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _deepseek_ai_dsh_client_ui_primitives = require("@deepseek-ai/dsh-client-ui-primitives");
+let react = require("react");
+let react_jsx_runtime = require("react/jsx-runtime");
+//#region src/client/locale/index.ts
+/** 本插件在 locale 服务里占的命名空间。 */
+const NS = "devtools-terminal";
+/** 全部中文文案。 */
+const zh = {
+	title: "终端",
+	new: "新建终端",
+	description: "在会话工作区运行命令",
+	rename: "终端名称",
+	shell: "选择 Shell",
+	shellLoading: "正在读取 Shell…",
+	shellEmpty: "没有可用的 Shell",
+	loading: "正在读取终端环境…",
+	creating: "正在启动…",
+	connecting: "正在连接…",
+	disconnected: "连接已断开。",
+	reconnect: "重新连接",
+	readonly: "此页面当前只读。",
+	control: "接管输入",
+	closed: "终端已关闭。",
+	exited: "进程已退出（{code}）",
+	failed: "终端错误：{message}",
+	unavailable: "不可用",
+	retry: "重试",
+	missingTerminal: "此终端已不存在，请新建终端。",
+	terminalLimit: "终端数量已达上限，请关闭不用的终端后重试。已退出的终端也计入数量。"
+};
+/** 全部英文文案。 */
+const en = {
+	title: "Terminal",
+	new: "New terminal",
+	description: "Run commands in the session workspace",
+	rename: "Terminal name",
+	shell: "Select shell",
+	shellLoading: "Reading shells…",
+	shellEmpty: "No shell available",
+	loading: "Reading the terminal environment…",
+	creating: "Starting…",
+	connecting: "Connecting…",
+	disconnected: "Connection lost.",
+	reconnect: "Reconnect",
+	readonly: "This page is read-only.",
+	control: "Take control",
+	closed: "Terminal closed.",
+	exited: "Process exited ({code})",
+	failed: "Terminal error: {message}",
+	unavailable: "Unavailable",
+	retry: "Retry",
+	missingTerminal: "This terminal no longer exists. Open a new one.",
+	terminalLimit: "The terminal limit has been reached. Close unused terminals and try again. Exited terminals also count toward the limit."
+};
+/** 当前绑定的 locale 运行时（未绑定前回退中文）。 */
+let bound;
+/**
+* 绑定 locale 服务。
+*
+* @param runtime - 客户端 locale 服务。
+*/
+function installLocale(runtime) {
+	bound = runtime.bind(NS);
+}
+/**
+* 取一条文案。
+*
+* @param key - 字典键。
+* @param params - `{name}` 模板参数。
+* @returns 当前语言下的文案。
+*/
+function t(key, params) {
+	if (bound === void 0) return zh[key];
+	return bound(key, params);
+}
+//#endregion
+//#region src/client/styles.ts
+/**
+* 客户端样式的幂等注入。
+*
+* DSH 的客户端 bundle 是**一个脚本**，没有 CSS 文件的概念（插件只能往
+* `<head>` 里插 `<style>`）。这里给一个按 id 幂等的小工具：同一段样式重复
+* `injectStyle` 不会插第二遍，`data-plugin` 标记方便在 DevTools 里认出是谁的。
+*
+* 为什么不直接在每个模块里 `document.head.appendChild`：插件会热重载，
+* 不按 id 去重就会在同一页里叠出好几份同 id 的样式表。
+*/
+/** 已经注入过的样式 id 集合。 */
+const injected = /* @__PURE__ */ new Set();
+/**
+* 注入一段样式（幂等）。
+*
+* @param id - 样式 id（建议用 `${包名}/${文件名}`）。
+* @param css - 样式文本。
+*/
+function injectStyle(id, css) {
+	if (injected.has(id) || typeof document === "undefined") return;
+	if (document.querySelector(`style[data-devtools-terminal-style=${JSON.stringify(id)}]`) !== null) {
+		injected.add(id);
+		return;
+	}
+	const style = document.createElement("style");
+	style.dataset.plugin = "dsh-devtools-terminal";
+	style.dataset.devtoolsTerminalStyle = id;
+	style.textContent = css;
+	document.head.appendChild(style);
+	injected.add(id);
+}
+//#endregion
+//#region src/client/guide.tsx
+/**
+* 右侧栏引导页上的「终端」卡片。
+*
+* ## 为什么不能只给一张"能点就行"的卡片
+*
+* 引导页的卡片是**两层**组成的：终端页签类型声明一条 `guide` 条目（标题 / 描述 /
+* 图标），渲染时平台按 `providerId` 去 `sidebar.right.tab.guide.entry` 槽里找同
+* id 的组件；找不到才退回平台自带的 `EntryBox`。
+*
+* 我们接管了 `terminal` kind（`priority: 'extension'`），于是**生效的类型是我们**，
+* 平台那条「新建终端 + Shell 下拉菜单」卡片（它注册在平台自己的类型 id 上）不再
+* 参与渲染。所以这一版必须把平台卡片的两个既有行为都复刻出来：
+*
+* 1. **图标用平台自己的插画**（`PluginArtworkTerminal`，26px）—— 「文件」「Git」
+*    那几张卡用的都是平台插画；自己画一个灰色 `>_` 会又小又灰，夹在同一列里
+*    一眼就不是一套（用户 2026-10-24 的反馈就是这一条）。
+* 2. **标题右边的 Shell 下拉菜单** —— 点卡片用「上次选的 shell」直接开终端；点
+*    chevron 列出宿主发现的 shell（`webTerminals.launchShells`），选一个就记成
+*    下次默认（`selectShell`）并带着 `shellPath` 打开。
+*
+* 尺寸也照平台卡片来（14px 标题 / 11px 描述 / 14px 20px 内边距 / 56px 最小高度 /
+* `--dsw-radius-xl`），不然同一列里只有这一张"瘦"一点。
+*
+* ## 为什么是手写而不是直接 import 平台组件
+*
+* 平台的 `TerminalGuide` 没有从 `@deepseek-ai/dsh-client-ui-sidebar-terminal/client`
+* 导出，而客户端 bundle 在浏览器里只能 require 9 个**种子模块** —— 直接 import
+* 平台组件就是运行时找不到模块。所以这里用同为种子模块的
+* `@deepseek-ai/dsh-client-ui-primitives` 里的 `Menu` / `Button` /
+* `PluginArtworkTerminal` 拼一张等价卡片。
+*/
+/** 卡片样式。 */
+injectStyle("dsh-devtools-terminal/guide", ".dsh-devtools-terminal-guide{box-sizing:border-box;position:relative;display:flex;align-items:center;gap:14px;width:100%;min-height:56px;padding:14px 20px;border:0.5px solid var(--dsw-alias-border-l3);border-radius:var(--dsw-radius-xl);background:var(--dsw-alias-bg-layer-1);color:var(--dsw-alias-label-primary);text-align:left;overflow:hidden}.dsh-devtools-terminal-guide:hover{background:var(--dsw-alias-interactive-bg-hover)}.dsh-devtools-terminal-guide-main{position:absolute;inset:0;width:100%;height:100%;padding:0;border-radius:0}.dsh-devtools-terminal-guide-main:focus-visible{outline-offset:-2px}.dsh-devtools-terminal-guide-icon{flex:none;display:inline-flex;align-items:center;justify-content:center;width:26px;height:26px;color:var(--dsw-alias-label-secondary);pointer-events:none;position:relative}.dsh-devtools-terminal-guide-text{display:flex;flex-direction:column;flex:1;gap:3px;min-width:0;pointer-events:none;position:relative}.dsh-devtools-terminal-guide-title-row{display:flex;align-items:center;gap:4px;min-width:0}.dsh-devtools-terminal-guide-title{font-size:14px;line-height:1.4;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}.dsh-devtools-terminal-guide-description{font-size:11px;line-height:1.4;color:var(--dsw-alias-label-tertiary);white-space:nowrap;overflow:hidden;text-overflow:ellipsis}.dsh-devtools-terminal-guide-menu{flex:none;display:flex;pointer-events:auto}.dsh-devtools-terminal-guide-trigger{flex:none;width:20px;height:20px;padding:0;border-radius:4px}.dsh-devtools-terminal-guide-trigger svg{width:14px;height:14px;color:var(--dsw-alias-label-tertiary)}.dsh-devtools-terminal-guide-shortcut{pointer-events:none;position:relative}");
+/** 平台「新建终端」命令的 id（快捷键提示读它）。 */
+const TERMINAL_NEW = "terminal.new";
+/**
+* 「终端」引导卡片。
+*
+* @param props - 槽运行时 props（标题 / 描述 / 页签动作）与 shell 注入面。
+* @returns 一张可点的卡片；宿主提供 shell 服务时标题右边还带下拉菜单。
+*/
+function TerminalGuide(props) {
+	const { useTabInfo, useShortcuts, title, description, loadShells, selectShell } = props;
+	const { tab } = useTabInfo();
+	const shortcut = useShortcuts((entries) => entries.find((entry) => entry.id === TERMINAL_NEW));
+	const [open, setOpen] = (0, react.useState)(false);
+	const [attempt, setAttempt] = (0, react.useState)(0);
+	const [state, setState] = (0, react.useState)({ phase: "loading" });
+	(0, react.useEffect)(() => {
+		if (!open || loadShells === void 0) return void 0;
+		const lifetime = new AbortController();
+		loadShells(lifetime.signal).then((choices) => {
+			if (lifetime.signal.aborted) return;
+			setState(choices.selectedShell === void 0 ? {
+				phase: "ready",
+				shells: choices.shells
+			} : {
+				phase: "ready",
+				shells: choices.shells,
+				selected: choices.selectedShell
+			});
+		}, (error) => {
+			if (lifetime.signal.aborted) return;
+			setState({
+				phase: "failed",
+				message: error instanceof Error ? error.message : String(error)
+			});
+		});
+		return () => {
+			lifetime.abort();
+		};
+	}, [
+		open,
+		attempt,
+		loadShells
+	]);
+	const items = (() => {
+		if (state.phase === "loading") return [{
+			id: "loading",
+			label: t("shellLoading"),
+			disabled: true
+		}];
+		if (state.phase === "failed") return [{
+			id: "error",
+			label: t("failed", { message: state.message }),
+			disabled: true
+		}, {
+			id: "retry",
+			label: t("retry")
+		}];
+		if (state.shells.length === 0) return [{
+			id: "empty",
+			label: t("shellEmpty"),
+			disabled: true
+		}];
+		return state.shells.map((shell) => ({
+			id: shell.path,
+			label: shell.name
+		}));
+	})();
+	/** 菜单选择：失败项是「重试」，其余是一项 shell。 */
+	const choose = (path) => {
+		if (state.phase === "failed") {
+			setState({ phase: "loading" });
+			setAttempt((value) => value + 1);
+			return;
+		}
+		selectShell?.(path);
+		setOpen(false);
+		tab.actions.openTab("terminal", {
+			replaceTab: true,
+			params: { shellPath: path }
+		});
+	};
+	const shellMenu = loadShells === void 0 ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Menu, {
+		open,
+		portal: true,
+		autoFocus: true,
+		align: "end",
+		className: "dsh-devtools-terminal-guide-menu",
+		items,
+		selectedId: state.phase === "ready" ? state.selected : void 0,
+		onClose: () => {
+			setOpen(false);
+		},
+		onSelect: choose,
+		anchor: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
+			variant: "ghost",
+			className: "dsh-devtools-terminal-guide-trigger",
+			"aria-label": t("shell"),
+			"aria-haspopup": "menu",
+			"aria-expanded": open,
+			onClick: () => {
+				setState({ phase: "loading" });
+				setOpen((value) => !value);
+			},
+			children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.IconChevronDownOutlineRegular, {})
+		})
+	});
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		className: "dsh-devtools-terminal-guide",
+		children: [
+			/* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.Button, {
+				variant: "ghost",
+				className: "dsh-devtools-terminal-guide-main",
+				"aria-label": description === void 0 ? title : `${title} ${description}`,
+				"aria-keyshortcuts": shortcut?.aria,
+				onClick: () => {
+					tab.actions.openTab("terminal", { replaceTab: true });
+				}
+			}),
+			/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+				className: "dsh-devtools-terminal-guide-icon",
+				"aria-hidden": "true",
+				children: /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.PluginArtworkTerminal, { size: description === void 0 ? 22 : 26 })
+			}),
+			/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+				className: "dsh-devtools-terminal-guide-text",
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+					className: "dsh-devtools-terminal-guide-title-row",
+					children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+						className: "dsh-devtools-terminal-guide-title",
+						"aria-hidden": "true",
+						children: title
+					}), shellMenu]
+				}), description !== void 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+					className: "dsh-devtools-terminal-guide-description",
+					"aria-hidden": "true",
+					children: description
+				})]
+			}),
+			shortcut !== void 0 && shortcut.keys.length > 0 && /* @__PURE__ */ (0, react_jsx_runtime.jsx)(_deepseek_ai_dsh_client_ui_primitives.ShortcutKeys, {
+				keys: shortcut.keys,
+				className: "dsh-devtools-terminal-guide-shortcut"
+			})
+		]
+	});
+}
+//#endregion
+//#region src/links.ts
+/**
+* 判断字符串是不是可打开的 http(s) 地址。
+*
+* @param text - 候选文本。
+* @returns http/https 且能被 URL 解析时为 true。
+*/
+function isHttpUrl(text) {
+	try {
+		const parsed = new URL(text);
+		return parsed.protocol === "http:" || parsed.protocol === "https:";
+	} catch {
+		return false;
+	}
+}
+//#endregion
+//#region src/link-target.ts
+/**
+* 终端链接的**落点决策**：Ctrl/Cmd+点击输出里的 URL，交给谁打开。
+*
+* ## 为什么单独一个纯模块
+*
+* 「面板优先、不可用回退系统浏览器」这条规则本身只有几行，但它是本功能唯一的
+* 行为契约：面板临时抛错要能回退、非 http(s) 一律不碰、普通点击根本走不到这里
+* （修饰键判断在 `link-provider.ts`）。这些分支在浏览器里验证成本高（要真 xterm +
+* 真鼠标 + 真右栏），放到 host 编译（`lib/link-target.js`）就能用 `node --test`
+* 把每条分支钉死 —— 与 `links.ts` 同一个理由。
+*
+* ## 落点只有两个
+*
+* - `panel`：DSH 右栏的**浏览器插件页签**（`@deepseek-ai/dsh-client-ui-sidebar-browser`，
+*   web 是 iframe、桌面端 carrier 是原生 `<webview>`、移动端在 WebView 里同样是
+*   iframe）。打开的 URL 由平台校验，非法地址它自己会拒绝。
+* - `external`：`window.open(..., 'noopener,noreferrer')` —— 浏览器里是新标签页，
+*   桌面端经 carrier 的 `linkBridge` 交给系统浏览器。这是**回退**：profile 没启用
+*   右栏浏览器页签（`sidebarRightTabs.get('browser')` 为 undefined）、或者面板这次
+*   真的没打开成功时走它。
+*
+* 模块本身**不碰 DOM / cordis**：`window.open` 与 `ctx.sidebarRight` 都由调用方
+* 以端口（{@link LinkOpenPorts}）注入，于是这里只剩判断。
+*/
+/**
+* 决定一次打开该落到哪儿。
+*
+* 面板可用就优先面板 —— 这是本插件要的产品行为（用户要的是"在 DSH 插件浏览器
+* 里打开"，而不是跳出去）。不可用（profile 关掉了那一行 / 平台版本没有这个页签
+* 类型）才回退系统浏览器。
+*
+* @param panelAvailable - 右栏浏览器页签当前是否可用。
+* @returns 落点。
+*/
+function linkDestination(panelAvailable) {
+	return panelAvailable ? "panel" : "external";
+}
+/**
+* 造一个「打开终端链接」的动作。
+*
+* 语义（与 VSCode 终端一致）：只认 http(s)；面板优先；面板这次没开成功就回退
+* 系统浏览器 —— **不能因为面板抛错就什么都不做**，那等于点击没反应。
+*
+* @param ports - 外部动作。
+* @returns 打开动作（非 http(s) 静默忽略）。
+*/
+function createLinkOpener(ports) {
+	return (url) => {
+		if (!isHttpUrl(url)) return;
+		let destination = "external";
+		try {
+			destination = linkDestination(ports.panelAvailable());
+		} catch {
+			destination = "external";
+		}
+		if (destination === "panel") try {
+			ports.openInPanel(url);
+			return;
+		} catch {}
+		ports.openExternal(url);
+	};
+}
+//#endregion
+//#region src/client/injection.ts
+/**
+* 探测终端服务在不在。
+*
+* 不能 `inject`：终端控制器可能没加载（用户关掉了那一行），插件仍应正常加载，
+* 只是正文显示「这个环境没有终端」。也不能读到一次 `undefined` 就放弃 —— 平台
+* 那个插件和我们同批加载，谁先跑完没有保证，所以正文在注册时再探一次。
+*
+* @param ctx - 客户端根上下文。
+* @returns 终端服务，或 undefined。
+*/
+function getTerminals(ctx) {
+	const service = ctx.get("webTerminals");
+	return service !== void 0 && typeof service.view === "function" ? service : void 0;
+}
+/**
+* 探测主题服务。
+*
+* @param ctx - 客户端根上下文。
+* @returns 主题服务，或 undefined。
+*/
+function getTheme(ctx) {
+	const service = ctx.get("theme");
+	return service !== void 0 && typeof service.getTheme === "function" ? service : void 0;
+}
+/**
+* 取一个页签 occurrence 的导航参数。
+*
+* @param ctx - 客户端根上下文。
+* @param sessionId - 会话 id。
+* @param key - 页签 occurrence key。
+* @returns 内容地址与参数。
+*/
+function occurrenceOf(ctx, sessionId, key) {
+	const navigation = ctx.sidebarRight.tabDomain.occurrence(sessionId, { id: key }).navigation.getSnapshot();
+	return {
+		contentId: navigation.address,
+		params: navigation.params
+	};
+}
+/**
+* 造正文的 `inject` 回调。
+*
+* @param ctx - 客户端根上下文。
+* @returns 槽注册时的 `inject(sessionId)`。
+*/
+function createTerminalInjection(ctx) {
+	return (sessionId) => ({
+		view: (key) => {
+			const terminals = getTerminals(ctx);
+			if (terminals === void 0) throw new Error("devtools-terminal: 终端服务不在");
+			const { contentId, params } = occurrenceOf(ctx, sessionId, key);
+			const terminalId = params !== void 0 && params !== null && typeof params === "object" && "terminalId" in params ? params.terminalId : void 0;
+			const shellPath = params !== void 0 && params !== null && typeof params === "object" && "shellPath" in params ? params.shellPath : void 0;
+			return terminals.view(sessionId, key, contentId, terminalId, shellPath);
+		},
+		keyedHooks: { terminal: (key) => {
+			const terminals = getTerminals(ctx);
+			if (terminals === void 0) throw new Error("devtools-terminal: 终端服务不在");
+			const { contentId, params } = occurrenceOf(ctx, sessionId, key);
+			const terminalId = params !== void 0 && params !== null && typeof params === "object" && "terminalId" in params ? params.terminalId : void 0;
+			const shellPath = params !== void 0 && params !== null && typeof params === "object" && "shellPath" in params ? params.shellPath : void 0;
+			return terminals.view(sessionId, key, contentId, terminalId, shellPath).state;
+		} },
+		hooks: { theme: {
+			getSnapshot: () => getTheme(ctx)?.getTheme() ?? DEFAULT_THEME,
+			subscribe: (listener) => ctx.on("theme/change", listener)
+		} },
+		openUrl: createUrlOpener(ctx)
+	});
+}
+/**
+* 造正文用的「打开链接」动作。
+*
+* 落点规则全部在纯模块 `src/link-target.ts` 里（可 `node --test`），这里只把
+* 平台服务接成端口：
+*
+* - 面板可用性：`sidebarRightTabs.get('browser')` —— 页签类型注册了就可用；
+*   profile 里 `disabled: true` / 安装没有这个包时是 `undefined`，自动回退；
+* - 面板：`sidebarRight.openTab('browser', { params: { url } })` —— 展开右栏并把
+*   浏览器页签切到前台。**它不收地址、也不去重**：参数只记进 navigation.params，
+*   由页签首次挂载时自己去校验/加载（非法地址是面板里的一条报错提示，不抛错），
+*   而 `browser` kind 是 `multiple: true`，所以每点一次是一个**新页签**
+*   （与平台自己的聊天链接行为一致；平台没有"按 URL 找页签"的公开接口）；
+* - 回退：`window.open(..., 'noopener,noreferrer')` —— 浏览器里是新标签页，
+*   桌面端 carrier 会把它交给系统浏览器（`dsh-electron` 的 `linkBridge`）。
+*
+* @param ctx - 客户端根上下文（`sidebarRight` / `sidebarRightTabs` 在静态 inject 里）。
+* @returns 打开动作。
+*/
+function createUrlOpener(ctx) {
+	return createLinkOpener({
+		panelAvailable: () => ctx.sidebarRightTabs.get("browser") !== void 0,
+		openInPanel: (url) => {
+			ctx.sidebarRight.openTab("browser", { params: { url } });
+		},
+		openExternal: (url) => {
+			window.open(url, "_blank", "noopener,noreferrer");
+		}
+	});
+}
+/**
+* 快捷键服务缺席时的空目录。
+*
+* ⚠️ 不能"没有就不注入 hooks"：`hooks` 是**注入面形状**的一部分，少一个成员会让
+* `useShortcuts` 这个 prop 从有到无，而组件里的 Hook 调用不能跟着变。所以统一注入
+* 一个空目录 —— 卡片照常渲染，只是不显示快捷键提示。
+*/
+const EMPTY_SHORTCUTS = {
+	getSnapshot: () => [],
+	subscribe: () => () => void 0
+};
+/**
+* 探测快捷键服务。
+*
+* `shortcuts` 是平台自带的浏览器命令服务（引导页本身的快捷键提示也用它）；它不在
+* 我们的静态 `inject` 里 —— 缺了不该让插件加载失败，只是少一行快捷键提示。
+*
+* @param ctx - 客户端根上下文。
+* @returns 快捷键服务，或 undefined。
+*/
+function getShortcuts(ctx) {
+	const service = ctx.get("shortcuts");
+	return service !== void 0 && service.catalog !== void 0 ? service : void 0;
+}
+/**
+* 造引导卡的 `inject` 回调。
+*
+* 引导卡是 `sidebar.right.tab.guide.entry`（session 作用域 keyed 槽）：注入面在
+* **渲染时**按会话求值，所以这里可以现探终端服务 —— 用户看到引导页时平台早就加载完了。
+* 能力探测也在这里做：宿主没有 `launchShells` 就不给 `loadShells`。
+*
+* @param ctx - 客户端根上下文。
+* @param sessionId - 当前会话 id（宿主 `launchShells` 按会话解析默认 shell）。
+* @returns 引导卡注入面。
+*/
+function createGuideInjection(ctx, sessionId) {
+	const terminals = getTerminals(ctx);
+	const launchShells = terminals?.launchShells;
+	const shortcuts = getShortcuts(ctx)?.catalog ?? EMPTY_SHORTCUTS;
+	if (terminals === void 0 || launchShells === void 0) return { hooks: { shortcuts } };
+	return {
+		hooks: { shortcuts },
+		loadShells: (signal) => launchShells.call(terminals, sessionId, signal),
+		selectShell: (path) => {
+			getTerminals(ctx)?.selectShell?.(path);
+		}
+	};
+}
+/**
+* 主题服务缺席时的兜底值。
+*
+* 只影响终端字号/字体；颜色由 CSS 令牌决定，不会变成黑底白字。
+*/
+const DEFAULT_THEME = {
+	fontFamilies: { terminal: "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" },
+	fontSizes: { terminal: 13 }
+};
+//#endregion
+//#region src/client/terminal/chunk-loader.ts
+/** 块名 → 产物文件名（必须与 `tsdown.config.ts` 和 `src/routes.ts` 白名单一致）。 */
+const SCRIPTS = { terminal: "chunk-terminal.js" };
+/** 路由前缀（必须与 `src/routes.ts` 的 `PREFIX` 一致）。 */
+const BUNDLE_PREFIX = "/devtools-terminal/bundle";
+/** 正在加载/已加载的块。 */
+const pending = /* @__PURE__ */ new Map();
+/**
+* 加载一个块（幂等）。
+*
+* @param name - 块名。
+* @returns 加载完成。
+*/
+function loadChunk(name) {
+	if (typeof globalThis.__devtoolsTerminalChunk__?.[name] === "function") return Promise.resolve();
+	const existing = pending.get(name);
+	if (existing !== void 0) return existing;
+	const guarded = new Promise((resolve, reject) => {
+		const script = document.createElement("script");
+		script.src = `${BUNDLE_PREFIX}/${SCRIPTS[name]}`;
+		script.async = true;
+		script.onload = () => {
+			if (typeof globalThis.__devtoolsTerminalChunk__?.[name] === "function") resolve();
+			else reject(/* @__PURE__ */ new Error(`分块 ${name} 加载了但没有注册`));
+		};
+		script.onerror = () => {
+			reject(/* @__PURE__ */ new Error(`分块 ${name} 加载失败`));
+		};
+		document.head.append(script);
+	}).catch((error) => {
+		pending.delete(name);
+		throw error;
+	});
+	pending.set(name, guarded);
+	return guarded;
+}
+/**
+* 加载并取回实现。
+*
+* @param name - 块名。
+* @returns 实现。
+*/
+async function useChunk(name) {
+	await loadChunk(name);
+	const implementation = globalThis.__devtoolsTerminalChunk__?.[name];
+	if (implementation === void 0) throw new Error(`分块 ${name} 未注册`);
+	return implementation;
+}
+//#endregion
+//#region src/client/terminal/styles.ts
+/**
+* 终端正文自己的样式（注入 + 类名字符串）。
+*
+* ## 为什么和平台终端长得像
+*
+* 我们这个组件接管的是平台内置的 `terminal` 页签 —— 用户看到的还是同一个面板。
+* 所以几何照着平台那份 CSS 抄（flex 列、屏幕区撑满、状态行只在需要时出现），
+* 只换类名前缀；否则同一个页签在两种实现之间切换时会跳一下。
+*
+* ## 只写令牌，不写颜色
+*
+* 皮肤契约（根仓库 `test/design-tokens.test.mjs`）要求颜色来自 `--dsw-alias-*`。
+* 这里唯一"写死"的颜色是光标对比色，由懒加载块按单元格背景实时算出来，经 CSS
+* 变量传进来（见 `chunks/terminal.ts` 的 `observeTerminalCursor`）—— 它必须
+* 是具体色值，没法用令牌表达。
+*
+* ## 注入时机
+*
+* 模块加载时注入一次（`injectStyle` 按 id 幂等，热重载不会叠样式表）。正文是
+* 本包唯一使用这些类名的组件，不需要入口再记得调一次安装函数。
+*/
+/** 样式表 id（与 `src/client/title.tsx` 的 id 风格一致）。 */
+const STYLE_ID = "dsh-devtools-terminal/body";
+/** 类名（前缀统一 `dsh-devtools-terminal-`，避免和别的插件抢样式）。 */
+const cls = {
+	/** 正文根节点（带 `data-devtools-terminal`）。 */
+	root: "dsh-devtools-terminal-root",
+	/** 状态行（loading / 重连 / 只读 / 已退出）。 */
+	status: "dsh-devtools-terminal-status",
+	/** 终端屏幕区（xterm 的容器）。 */
+	screen: "dsh-devtools-terminal-screen",
+	/** xterm 真正挂载的元素（跟随屏幕区撑满）。 */
+	host: "dsh-devtools-terminal-host",
+	/** 临时状态文字。 */
+	muted: "dsh-devtools-terminal-muted",
+	/** 占位（把右侧按钮推到行尾）。 */
+	spacer: "dsh-devtools-terminal-spacer",
+	/** 状态行 / 空态里的按钮。 */
+	button: "dsh-devtools-terminal-button",
+	/** 错误段落。 */
+	error: "dsh-devtools-terminal-error",
+	/** 空态（缺终端 / 缺服务）。 */
+	empty: "dsh-devtools-terminal-empty",
+	/** 空态主文案。 */
+	emptyMessage: "dsh-devtools-terminal-empty-message",
+	/** 空态次要说明（宿主错误原文）。 */
+	emptyDetail: "dsh-devtools-terminal-empty-detail",
+	/** xterm 初始化失败的覆盖层。 */
+	failure: "dsh-devtools-terminal-failure"
+};
+injectStyle(STYLE_ID, `
+.dsh-devtools-terminal-root {
+  box-sizing: border-box;
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  height: 100%;
+  min-height: 0;
+  padding-top: 8px;
+  color: var(--dsw-alias-label-primary);
+  font-size: 13px;
+}
+
+/* ─────────────────────── 状态行 ─────────────────────── */
+/* 只在"还没连上 / 连上但不可写 / 已经结束"时出现，连上以后一行都不画（平台同款：
+   右侧栏本来就不宽，常驻工具条是纯浪费）。 */
+.dsh-devtools-terminal-status {
+  display: flex;
+  flex: none;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 8px;
+  padding: 5px 12px;
+  background: var(--dsw-alias-bg-layer-2);
+}
+.dsh-devtools-terminal-spacer { flex: 1 1 auto; }
+.dsh-devtools-terminal-muted { color: var(--dsw-alias-label-tertiary); font-size: 11.5px; }
+.dsh-devtools-terminal-button {
+  flex: none;
+  padding: 2px 10px;
+  border: 1px solid var(--dsw-alias-border-l2);
+  border-radius: var(--dsw-radius-sm);
+  background: var(--dsw-alias-bg-layer-1);
+  color: var(--dsw-alias-label-primary);
+  font: inherit;
+  font-size: 12px;
+  line-height: 1.6;
+  cursor: pointer;
+}
+.dsh-devtools-terminal-button:hover { background: var(--dsw-alias-interactive-bg-hover); }
+
+/* ─────────────────────── 终端屏幕 ─────────────────────── */
+/* 屏幕区必须真的撑满：xterm 靠容器的盒子尺寸算行列，高度塌了就是 0 行。 */
+.dsh-devtools-terminal-screen {
+  position: relative;
+  display: flex;
+  flex: 1 1 auto;
+  min-width: 0;
+  min-height: 0;
+  padding: 8px;
+  overflow: hidden;
+  background: var(--dsw-alias-bg-base);
+  color: var(--dsw-alias-label-primary);
+}
+/* 主题色也从这里读（懒加载块读这个元素的计算样式），所以背景写在这一层。 */
+.dsh-devtools-terminal-host {
+  position: relative;
+  width: 100%;
+  height: 100%;
+  background: var(--dsw-alias-bg-base);
+}
+.dsh-devtools-terminal-host .xterm { height: 100%; }
+/* xterm 自己的 .xterm-viewport 默认是 #000，不盖掉会在浅色主题下露黑边。 */
+.dsh-devtools-terminal-host .xterm-viewport { background: var(--dsw-alias-bg-base); }
+
+/* ─────────────────────── 光标 ─────────────────────── */
+/* 光标颜色由懒加载块逐帧算（保证在任何单元格背景上都看得见），这里是消费端。
+   --dsh-devtools-terminal-cursor-* 由 chunks/terminal.ts 写在 host 的行内样式上。 */
+.dsh-devtools-terminal-host .xterm-cursor { opacity: 1; }
+.dsh-devtools-terminal-host .xterm .xterm-rows .xterm-cursor.xterm-cursor-block {
+  background-color: var(--dsh-devtools-terminal-cursor);
+  color: var(--dsh-devtools-terminal-cursor-accent);
+}
+.dsh-devtools-terminal-host .xterm .xterm-rows .xterm-cursor.xterm-cursor-block:not(.xterm-cursor-blink) {
+  background-color: var(--dsh-devtools-terminal-cursor) !important;
+  color: var(--dsh-devtools-terminal-cursor-accent) !important;
+}
+.dsh-devtools-terminal-host .xterm .xterm-rows .xterm-cursor.xterm-cursor-outline {
+  outline-color: var(--dsh-devtools-terminal-cursor);
+}
+.dsh-devtools-terminal-host .xterm .xterm-rows .xterm-cursor.xterm-cursor-bar {
+  box-shadow: 1px 0 0 var(--dsh-devtools-terminal-cursor) inset;
+}
+.dsh-devtools-terminal-host .xterm .xterm-rows .xterm-cursor.xterm-cursor-underline {
+  border-bottom-color: var(--dsh-devtools-terminal-cursor);
+}
+@keyframes dsh-devtools-terminal-cursor-blink {
+  0% {
+    background-color: var(--dsh-devtools-terminal-cursor);
+    color: var(--dsh-devtools-terminal-cursor-accent);
+  }
+  50% {
+    background-color: var(--dsh-devtools-terminal-cursor-cell-background);
+    color: var(--dsh-devtools-terminal-cursor-cell-foreground);
+  }
+}
+.dsh-devtools-terminal-host .xterm .xterm-rows.xterm-focus .xterm-cursor.xterm-cursor-block.xterm-cursor-blink {
+  animation: 1s step-end infinite dsh-devtools-terminal-cursor-blink;
+}
+
+/* ─────────────────────── 错误与空态 ─────────────────────── */
+.dsh-devtools-terminal-error {
+  flex: none;
+  margin: 0;
+  padding: 10px 12px;
+  overflow-wrap: anywhere;
+  background: var(--dsw-alias-bg-layer-2);
+  color: var(--dsw-alias-label-primary);
+}
+.dsh-devtools-terminal-empty {
+  display: flex;
+  flex: 1 1 auto;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 16px;
+  min-height: 0;
+  padding: 24px;
+  overflow: auto;
+  text-align: center;
+}
+.dsh-devtools-terminal-empty-message {
+  max-width: 28ch;
+  margin: 0;
+  line-height: 1.6;
+  overflow-wrap: anywhere;
+}
+.dsh-devtools-terminal-empty-detail {
+  max-width: 40ch;
+  margin: 0;
+  color: var(--dsw-alias-label-tertiary);
+  font-size: 11.5px;
+  line-height: 1.5;
+  overflow-wrap: anywhere;
+}
+/* xterm 建不起来（懒加载块 404 / 浏览器不兼容）时的覆盖层：终端区不能留一块
+   黑屏让人猜，要给错误原文和重试。 */
+.dsh-devtools-terminal-failure {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: 12px;
+  padding: 24px;
+  text-align: center;
+  background: var(--dsw-alias-bg-base);
+  color: var(--dsw-alias-label-primary);
+}
+`);
+//#endregion
+//#region src/client/terminal/body.tsx
+/**
+* 右侧栏终端正文：接管平台内置的 `terminal` 页签。
+*
+* ## 为什么是"接管"而不是"新写一个页签类型"
+*
+* 平台的终端正文只做「PTY → xterm」，没有 link provider —— 输出里的 URL 只是
+* 普通文字。平台把那份实现做成**私有**懒加载块，第三方插件既拿不到 xterm 实例，
+* 也换不掉它的 UI。`sidebar-right` 的页签类型注册表允许 `priority: 'extension'`
+* 顶替同 kind 的内置类型（`dsh-devtools-files` 已用同一手法接管 `files`），
+* 所以这里注册同一个 key、自己渲染正文，PTY 仍然用平台的 `ctx.webTerminals`。
+*
+* ## 和平台正文的对应关系
+*
+* 状态栏、只读 / 接管输入、重试、缺失终端、帧泵（snapshot 重置、output 追加、
+* 写完 `acknowledge`）、fit 夹宿主上限、隐藏页签不 fit、主题变化换色、卸载
+* dispose —— 全部照平台 `TerminalBody` / `TerminalScreen` 的行为搬过来。
+*
+* ## 两条不能破的规矩
+*
+* 1. **帧必须 ack**：宿主是背压发送的，不 ack 就再也不发下一帧（终端看起来
+*    永久冻住）。ack 只能写在 `xterm.write` 的回调里 —— 那才是"真的解析完"。
+* 2. **终端服务可能不在**（用户关掉了那一行）：`injection` 的 `view` 会抛。
+*    正文必须自己接住并显示成空态，不能让一个页签把渲染打挂 —— 而且**不能**
+*    用「服务不在就少调一个 hook」的写法：hook 数量随服务在不在变化，React 会
+*    在下一次渲染时直接报 hook 顺序错误。所以状态统一从 `model.state` 读。
+*/
+/** 平台终端也用的等宽字体栈；用户的主题字体栈接在它前面。 */
+const TERMINAL_FONT_STACK = "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace";
+/** 服务缺席时的空快照（同一引用，不会触发重渲染）。 */
+const EMPTY_STATE = {};
+/**
+* 服务缺席时给 uSES 的空源。
+*
+* 为什么不直接用注入的 `useTerminal`：它在服务缺席时**直接抛**，而 hook 不能
+* 因为服务在不在而少调/多调（React 会报 hook 顺序变化）。这里把「状态源」当成
+* 普通值：服务不在就拿这份空源，hook 数量永远一致，服务恢复后也能正常接上。
+*/
+const ABSENT_STATE = {
+	getSnapshot: () => EMPTY_STATE,
+	subscribe: () => () => void 0
+};
+/**
+* 终端页签正文。
+*
+* @param props - 槽运行时 props + 注入面（见 `injection.ts`）。
+* @returns 渲染结果。
+*/
+function TerminalBody(props) {
+	const { useTabInfo, useTheme, view: resolveView, openUrl } = props;
+	const { tab } = useTabInfo();
+	const theme = useTheme((value) => value);
+	let model;
+	let unavailable;
+	try {
+		model = resolveView(tab.id);
+	} catch (error) {
+		unavailable = messageOf(error);
+	}
+	const source = model?.state ?? ABSENT_STATE;
+	const subscribe = (0, react.useCallback)((listener) => source.subscribe(listener), [source]);
+	const getSnapshot = (0, react.useCallback)(() => source.getSnapshot(), [source]);
+	const state = (0, react.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
+	(0, react.useEffect)(() => {
+		if (model === void 0) return;
+		return model.mount();
+	}, [model]);
+	if (unavailable !== void 0 || model === void 0) {
+		const reason = unavailable;
+		return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("section", {
+			className: cls.root,
+			"data-devtools-terminal": true,
+			children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				className: cls.empty,
+				role: "status",
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+					className: cls.emptyMessage,
+					children: t("unavailable")
+				}), reason === void 0 ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+					className: cls.emptyDetail,
+					children: reason
+				})]
+			})
+		});
+	}
+	const view = model;
+	/** "新建终端"动作（缺失终端 / 已退出时都要给）。 */
+	const newTerminal = /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+		type: "button",
+		className: cls.button,
+		onClick: () => {
+			tab.actions.openTab("terminal", { replaceTab: true });
+		},
+		children: t("new")
+	});
+	if (state.issue === "missingTerminal") return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("section", {
+		className: cls.root,
+		"data-devtools-terminal": true,
+		children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+			className: cls.empty,
+			children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+				className: cls.emptyMessage,
+				role: "alert",
+				children: t("missingTerminal")
+			}), newTerminal]
+		})
+	});
+	const error = state.phase === "disconnected" ? void 0 : state.issue === void 0 ? state.error ?? state.info?.error : issueText(state.issue);
+	let status;
+	if (state.phase === "idle" || state.phase === "loading") status = t("loading");
+	else if (state.phase === "creating" || state.phase === "connecting" || state.phase === "disconnected") status = t(state.phase);
+	else if (state.info?.state === "exited") status = t("exited", { code: String(state.info.exitCode ?? "—") });
+	else if (state.info?.state === "failed") status = t("unavailable");
+	else if (state.phase === "closed") status = t("closed");
+	const ended = state.info?.state === "exited" || state.phase === "closed";
+	const retry = !ended && (state.phase === "failed" || state.phase === "disconnected");
+	const readOnly = state.phase === "connected" && state.info?.state === "running" && state.writable !== true;
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("section", {
+		className: cls.root,
+		"data-devtools-terminal": true,
+		children: [
+			status !== void 0 || retry || readOnly ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+				className: cls.status,
+				role: "status",
+				children: [
+					status === void 0 ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: status }),
+					readOnly ? /* @__PURE__ */ (0, react_jsx_runtime.jsxs)(react_jsx_runtime.Fragment, { children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: t("readonly") }), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+						type: "button",
+						className: cls.button,
+						onClick: () => {
+							view.connect();
+						},
+						children: t("control")
+					})] }) : null,
+					retry ? state.info === void 0 ? /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+						type: "button",
+						className: cls.button,
+						onClick: () => {
+							view.refresh();
+						},
+						children: t(state.phase === "disconnected" ? "reconnect" : "retry")
+					}) : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+						type: "button",
+						className: cls.button,
+						onClick: () => {
+							view.connect();
+						},
+						children: t("reconnect")
+					}) : null,
+					ended ? newTerminal : null
+				]
+			}) : null,
+			state.info === void 0 ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsx)(TerminalScreen, {
+				state,
+				model: view,
+				visible: tab.visible,
+				label: t("title"),
+				theme,
+				openUrl
+			}),
+			error === void 0 ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+				className: cls.error,
+				role: "alert",
+				children: t("failed", { message: error })
+			})
+		]
+	});
+}
+/**
+* 终端屏幕：xterm 实例 + 帧泵 + 尺寸同步。
+*
+* xterm 几百 KB，走懒加载块（`chunk-loader.ts`）。所以创建是**异步**的；在块
+* 到位之前帧照常会来，创建完成后用"最新一帧"把屏幕补上（`lastRevision` 是
+* 跨渲染的 ref，重复帧不会画第二遍，也不会重复 ack）。
+*
+* @param props - 见 {@link TerminalScreenProps}。
+* @returns 屏幕容器。
+*/
+function TerminalScreen({ state, model, visible, label, theme, openUrl }) {
+	const host = (0, react.useRef)(null);
+	/** 懒加载块到位后建出来的句柄。 */
+	const handle = (0, react.useRef)(void 0);
+	/** 已经画到第几版（用来丢重复帧 / 补帧）。 */
+	const lastRevision = (0, react.useRef)(0);
+	const [factory, setFactory] = (0, react.useState)(void 0);
+	/** 懒加载或建 xterm 失败时的原文。 */
+	const [failure, setFailure] = (0, react.useState)(void 0);
+	/** 创建代数：下游 effect 靠它知道"句柄刚建好，该补一次"。 */
+	const [ready, setReady] = (0, react.useState)(0);
+	/** 用户点重试时 +1（作为 effect 依赖重新触发）。 */
+	const [attempt, setAttempt] = (0, react.useState)(0);
+	const fontFamily = terminalFontFamily(theme.fontFamilies.terminal);
+	const fontSize = theme.fontSizes.terminal;
+	const size = infoSize(state.info);
+	/**
+	* 最新一份"渲染时数据"。
+	*
+	* 懒加载、ResizeObserver 的回调都发生在两次渲染之间；闭包里的 props 会过期，
+	* 所以统一从这里读最新值（平台正文同样的做法）。
+	*/
+	const current = (0, react.useRef)({
+		state,
+		visible,
+		fontFamily,
+		fontSize,
+		label,
+		openUrl
+	});
+	current.current = {
+		state,
+		visible,
+		fontFamily,
+		fontSize,
+		label,
+		openUrl
+	};
+	(0, react.useEffect)(() => {
+		if (factory !== void 0) return;
+		let alive = true;
+		useChunk("terminal").then((create) => {
+			if (alive) setFactory(() => create);
+		}).catch((error) => {
+			if (alive) setFailure(messageOf(error));
+		});
+		return () => {
+			alive = false;
+		};
+	}, [factory, attempt]);
+	(0, react.useLayoutEffect)(() => {
+		if (factory === void 0) return;
+		const element = host.current;
+		if (element === null) return;
+		const snapshot = current.current;
+		let created;
+		try {
+			created = factory(element, {
+				fontFamily: snapshot.fontFamily,
+				fontSize: snapshot.fontSize,
+				scrollback: snapshot.state.environment?.scrollback ?? 0,
+				readOnly: snapshot.state.writable !== true,
+				label: snapshot.label,
+				openUrl: (url) => {
+					current.current.openUrl(url);
+				},
+				onData: (data) => {
+					model.write(data);
+				}
+			});
+		} catch (error) {
+			setFailure(messageOf(error));
+			return;
+		}
+		handle.current = created;
+		lastRevision.current = 0;
+		const render = snapshot.state.render;
+		if (render !== void 0) {
+			lastRevision.current = render.revision;
+			paintFrame(created, render, model);
+		}
+		created.setReadOnly(snapshot.state.writable !== true);
+		if (snapshot.visible && snapshot.state.writable === true) fitScreen(element, created, snapshot.state, model);
+		else if (snapshot.state.writable !== true) resizeToHost(created, snapshot.state);
+		setFailure(void 0);
+		setReady((value) => value + 1);
+		return () => {
+			created.dispose();
+			if (handle.current === created) handle.current = void 0;
+		};
+	}, [
+		factory,
+		model,
+		attempt
+	]);
+	(0, react.useLayoutEffect)(() => {
+		const instance = handle.current;
+		if (instance === void 0) return;
+		const render = state.render;
+		if (render === void 0 || render.revision <= lastRevision.current) return;
+		lastRevision.current = render.revision;
+		paintFrame(instance, render, model);
+	}, [
+		state.render,
+		model,
+		ready
+	]);
+	(0, react.useLayoutEffect)(() => {
+		handle.current?.applyTheme();
+	}, [
+		theme,
+		model,
+		ready
+	]);
+	(0, react.useLayoutEffect)(() => {
+		const instance = handle.current;
+		if (instance === void 0) return;
+		if (!instance.setFont(fontFamily, fontSize)) return;
+		const element = host.current;
+		if (element === null) return;
+		const snapshot = current.current;
+		if (!snapshot.visible || snapshot.state.writable !== true) return;
+		fitScreen(element, instance, snapshot.state, model);
+	}, [
+		fontFamily,
+		fontSize,
+		model,
+		ready
+	]);
+	(0, react.useLayoutEffect)(() => {
+		const instance = handle.current;
+		if (instance === void 0) return;
+		instance.setReadOnly(state.writable !== true);
+		const element = host.current;
+		if (element === null) return;
+		if (visible && state.writable === true) fitScreen(element, instance, state, model);
+		else if (state.writable !== true) resizeToHost(instance, state);
+	}, [
+		visible,
+		state.writable,
+		size?.cols,
+		size?.rows,
+		model,
+		ready
+	]);
+	(0, react.useEffect)(() => {
+		handle.current?.setLabel(label);
+	}, [label, ready]);
+	(0, react.useEffect)(() => {
+		if (!visible || state.writable !== true) return;
+		handle.current?.focus();
+	}, [
+		visible,
+		state.writable,
+		ready
+	]);
+	(0, react.useLayoutEffect)(() => {
+		const element = host.current;
+		if (element === null) return;
+		const observer = new ResizeObserver(() => {
+			const instance = handle.current;
+			if (instance === void 0) return;
+			const snapshot = current.current;
+			if (!snapshot.visible || snapshot.state.writable !== true) return;
+			if (element.clientWidth === 0 || element.clientHeight === 0) return;
+			fitScreen(element, instance, snapshot.state, model);
+		});
+		observer.observe(element);
+		return () => {
+			observer.disconnect();
+		};
+	}, [model, ready]);
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+		className: cls.screen,
+		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("div", {
+			className: cls.host,
+			ref: host
+		}), failure === void 0 ? null : /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
+			className: cls.failure,
+			role: "alert",
+			children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+				className: cls.emptyMessage,
+				children: t("failed", { message: failure })
+			}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+				type: "button",
+				className: cls.button,
+				onClick: () => {
+					setFailure(void 0);
+					setAttempt((value) => value + 1);
+				},
+				children: t("retry")
+			})]
+		})]
+	});
+}
+/**
+* 画一帧。
+*
+* snapshot 是"全量"：先 reset 再按宿主给的行列开屏，然后写整屏文本；
+* output 是增量，直接追加。**两种情况都必须写完后 ack**，否则宿主不发下一帧。
+*
+* @param handle - xterm 句柄。
+* @param render - 宿主帧。
+* @param model - 宿主视图（ack 用）。
+*/
+function paintFrame(handle, render, model) {
+	const frame = render.frame;
+	if (frame.type === "snapshot") {
+		if (frame.info !== void 0) handle.reset(frame.info.cols, frame.info.rows);
+		handle.write(frame.screen ?? "", () => {
+			model.acknowledge(render.revision);
+		});
+		return;
+	}
+	handle.write(frame.data ?? "", () => {
+		model.acknowledge(render.revision);
+	});
+}
+/**
+* 按容器尺寸同步行列，并用宿主环境上限夹住。
+*
+* 不夹的话 PTY 会收到超范围的行列（宿主的 PTY 侧有上限，越界会直接拒）。
+*
+* @param host - 容器（有真实盒子尺寸才量）。
+* @param handle - xterm 句柄。
+* @param state - 当前状态（读 `environment.maxCols/maxRows`）。
+* @param model - 宿主视图（同步行列）。
+*/
+function fitScreen(host, handle, state, model) {
+	if (host.clientWidth === 0 || host.clientHeight === 0) return;
+	const proposed = handle.fit();
+	if (proposed === void 0) return;
+	const environment = state.environment;
+	const cols = environment?.maxCols === void 0 ? proposed.cols : Math.min(proposed.cols, environment.maxCols);
+	const rows = environment?.maxRows === void 0 ? proposed.rows : Math.min(proposed.rows, environment.maxRows);
+	if (cols < 2 || rows < 1) return;
+	if (cols !== proposed.cols || rows !== proposed.rows) handle.resize(cols, rows);
+	model.resize(cols, rows);
+}
+/**
+* 只读时跟随宿主给的行列（不量容器，也不反向 notify 宿主）。
+*
+* @param handle - xterm 句柄。
+* @param state - 当前状态。
+*/
+function resizeToHost(handle, state) {
+	const size = infoSize(state.info);
+	if (size !== void 0) handle.resize(size.cols, size.rows);
+}
+/**
+* 从宿主 info 里读行列。
+*
+* 契约类型（`injection.ts`）只列了正文**直接**读的字段，宿主的 `TerminalInfo`
+* 实际还带 `cols/rows`（平台正文用它做只读尺寸对齐）。这里按能力探测取，
+* 拿不到就跳过 —— 不影响可写路径。
+*
+* @param info - 状态里的 info。
+* @returns 行列，或 undefined。
+*/
+function infoSize(info) {
+	if (info === void 0) return void 0;
+	const probe = info;
+	if (typeof probe.cols !== "number" || typeof probe.rows !== "number") return void 0;
+	return {
+		cols: probe.cols,
+		rows: probe.rows
+	};
+}
+/**
+* 拼字体族：用户的终端字体栈 + 平台兜底栈。
+*
+* @param list - 主题给的字体族（可能为空）。
+* @returns xterm 的 `fontFamily`。
+*/
+function terminalFontFamily(list) {
+	return list === "" ? TERMINAL_FONT_STACK : `${list}, ${TERMINAL_FONT_STACK}`;
+}
+/**
+* 宿主 issue → 文案。
+*
+* @param issue - 宿主给的 issue（契约里是 string，实际是文案键的并集）。
+* @returns 认得的键取当前语言文案，不认得就原样显示（好过空白）。
+*/
+function issueText(issue) {
+	return Object.hasOwn(zh, issue) ? t(issue) : issue;
+}
+/**
+* 取错误原文。
+*
+* @param error - 任意抛出物。
+* @returns 可显示的文字。
+*/
+function messageOf(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+//#endregion
+//#region src/client/title.tsx
+/** 注入一次标题的样式。 */
+injectStyle("dsh-devtools-terminal/title", ".dsh-devtools-terminal-title{display:inline-flex;align-items:center;gap:6px;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}.dsh-devtools-terminal-title-icon{flex:none;display:inline-flex;color:currentColor;opacity:.8}");
+/**
+* 终端页签标题。
+*
+* @param props - 槽运行时 props。
+* @returns 图标 + 当前名称。
+*/
+function TerminalTitle(props) {
+	const { tab } = props.useTabInfo();
+	const live = props.useTerminal(tab.id, (state) => state?.info?.title ?? state?.title);
+	const title = (live !== void 0 && live !== "" ? live : void 0) ?? tab.title ?? t("title");
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("span", {
+		className: "dsh-devtools-terminal-title",
+		children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", {
+			className: "dsh-devtools-terminal-title-icon",
+			"aria-hidden": "true",
+			children: /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("svg", {
+				width: "16",
+				height: "16",
+				viewBox: "0 0 16 16",
+				fill: "none",
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("path", {
+					d: "M3 4L7 8L3 12",
+					stroke: "currentColor"
+				}), /* @__PURE__ */ (0, react_jsx_runtime.jsx)("path", {
+					d: "M9 12H13",
+					stroke: "currentColor"
+				})]
+			})
+		}), title]
+	});
+}
+//#endregion
+//#region src/client/index.tsx
+/** Cordis 插件名（= 包名）。 */
+const name = "dsh-devtools-terminal";
+/** 静态依赖门（见文件头）。 */
+const inject = [
+	"slots",
+	"locale",
+	"sidebarRight",
+	"sidebarRightTabs"
+];
+/** 页签类型的 id。**必须唯一**，用包名最省心（slot 注册的 key 也是它）。 */
+const TAB_ID = "@zhangzhian/dsh-devtools-terminal";
+/** 接管的 kind（平台内置终端的 discriminator）。 */
+const TAB_KIND = "terminal";
+/** 引导页里本卡片的排序（平台终端是 20；我们接替它，保持同一位置）。 */
+const GUIDE_ORDER = 20;
+/**
+* 挂载客户端半。
+*
+* @param ctx - 客户端根上下文。
+*/
+function apply(ctx) {
+	ctx.inject([
+		"slots",
+		"locale",
+		"sidebarRight",
+		"sidebarRightTabs"
+	], (scoped) => {
+		installLocale(scoped.locale);
+		scoped.effect(() => scoped.locale.register(NS, {
+			zh,
+			en
+		}), "dsh-devtools-terminal: locale");
+		/**
+		* 正文/标题的注入面。
+		*
+		* ⚠️ 必须在**注册时**造，不能提到外面：`ctx.inject` 的回调跑起来时
+		* `sidebarRight` 才就位；而 `inject` 回调里的 `ctx.get('webTerminals')`
+		* 是每次渲染调用时再探的（见 `injection.ts`）。
+		*/
+		const injectFace = createTerminalInjection(scoped);
+		scoped.effect(() => scoped.sidebarRightTabs.register({
+			id: TAB_ID,
+			kind: TAB_KIND,
+			multiple: true,
+			priority: "extension",
+			title: () => t("title"),
+			guide: [{
+				id: TAB_ID,
+				order: GUIDE_ORDER,
+				title: () => t("new"),
+				description: () => t("description"),
+				icon: _deepseek_ai_dsh_client_ui_primitives.PluginArtworkTerminal
+			}]
+		}), "dsh-devtools-terminal: tab type");
+		scoped.effect(() => scoped.slots.inject("sidebar.right.pane.tab", () => scoped.slots.register({
+			name: "sidebar.right.pane.tab",
+			key: TAB_ID,
+			inject: injectFace
+		}, TerminalBody)), "dsh-devtools-terminal: body");
+		scoped.effect(() => scoped.slots.inject("sidebar.right.pane.tab.title", () => scoped.slots.register({
+			name: "sidebar.right.pane.tab.title",
+			key: TAB_ID,
+			inject: injectFace
+		}, TerminalTitle)), "dsh-devtools-terminal: title");
+		scoped.effect(() => scoped.slots.inject("sidebar.right.tab.guide.entry", () => scoped.slots.register({
+			name: "sidebar.right.tab.guide.entry",
+			key: TAB_ID,
+			inject: (sessionId) => createGuideInjection(scoped, sessionId)
+		}, TerminalGuide)), "dsh-devtools-terminal: guide");
+		if (getTerminals(scoped) === void 0) console.warn("[devtools-terminal] 没有 webTerminals 服务：终端正文会显示「不可用」");
+	});
+}
+//#endregion
+exports.TAB_ID = TAB_ID;
+exports.TAB_KIND = TAB_KIND;
+exports.apply = apply;
+exports.inject = inject;
+exports.name = name;
+
+		return module.exports;
+	}
+});
+//# sourceMappingURL=client.js.map