dsh-single-terminal 0.1.0

package/lib/types/client/controller.js

@@ -0,0 +1,235 @@
+/**
+ * dsh-single-terminal —— 客户端控制器（模块级单例）：
+ * WebSocket 生命周期、帧路由、sink 注册（xterm 实例）、UI 状态 store。
+ *
+ * 会话输出在 sink 注册前先积压到 pending（React 挂载/重连时序下不丢字节）；
+ * 抽屉关闭不卸载组件（display:none），xterm 缓冲与会话保持。
+ */
+import { useSyncExternalStore } from 'react';
+import { loadJson, saveJson } from "./storage.js";
+import { TerminalSocket } from "./ws.js";
+class DrawerStore {
+    state = {
+        open: false,
+        mode: loadJson('mode', 'overlay'),
+        height: loadJson('height', 360),
+        conn: 'connecting',
+        tabs: [],
+        activeId: null,
+        shells: [],
+        defaultShell: 'powershell',
+        fontSize: 13,
+        fontFamily: 'Consolas, "Cascadia Mono", "Courier New", monospace',
+        notice: null,
+    };
+    listeners = new Set();
+    subscribe = (listener) => {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    };
+    getSnapshot = () => this.state;
+    set(patch) {
+        this.state = { ...this.state, ...patch };
+        for (const listener of this.listeners)
+            listener();
+    }
+    setOpen(open) {
+        this.set({ open });
+    }
+    setMode(mode) {
+        saveJson('mode', mode);
+        this.set({ mode });
+    }
+    setHeight(height) {
+        saveJson('height', height);
+        this.set({ height });
+    }
+    setConn(conn) {
+        this.set({ conn });
+    }
+    setNotice(notice) {
+        this.set({ notice });
+    }
+    applyHello(frame) {
+        this.set({ defaultShell: frame.defaultShell, fontSize: frame.fontSize, fontFamily: frame.fontFamily });
+    }
+    applyInventory(shells, sessions) {
+        const known = new Set(this.state.tabs.map((tab) => tab.id));
+        const adopted = sessions.filter((session) => !known.has(session.id));
+        if (adopted.length > 0) {
+            const tabs = [...this.state.tabs, ...adopted.map(toTab)];
+            const activeId = this.state.activeId ?? tabs[tabs.length - 1]?.id ?? null;
+            this.set({ shells, tabs, activeId });
+        }
+        else {
+            this.set({ shells });
+        }
+        return { adopted };
+    }
+    addSession(session) {
+        if (this.state.tabs.some((tab) => tab.id === session.id))
+            return;
+        this.set({ tabs: [...this.state.tabs, toTab(session)], activeId: session.id });
+    }
+    setActive(id) {
+        this.set({ activeId: id });
+    }
+    markDead(id, exitCode) {
+        this.set({
+            tabs: this.state.tabs.map((tab) => (tab.id === id ? { ...tab, alive: false, exitCode } : tab)),
+        });
+    }
+    removeTab(id) {
+        const tabs = this.state.tabs.filter((tab) => tab.id !== id);
+        const activeId = this.state.activeId === id ? tabs[tabs.length - 1]?.id ?? null : this.state.activeId;
+        this.set({ tabs, activeId });
+    }
+}
+function toTab(session) {
+    return { id: session.id, shellId: session.shellId, label: session.label, cwd: session.cwd, alive: session.alive, exitCode: session.exitCode };
+}
+class TerminalController {
+    store = new DrawerStore();
+    socket = null;
+    sinks = new Map();
+    pending = new Map();
+    noticeTimer = null;
+    toggle() {
+        this.setOpen(!this.store.getSnapshot().open);
+    }
+    setOpen(open) {
+        this.store.setOpen(open);
+        if (open) {
+            this.ensureStarted();
+            this.maybeAutoOpen();
+        }
+        else {
+            this.autoOpening = false;
+        }
+    }
+    ensureStarted() {
+        if (this.socket !== null)
+            return;
+        this.socket = new TerminalSocket({
+            onFrame: (frame) => { this.onFrame(frame); },
+            onState: (state) => {
+                this.store.setConn(state);
+                // 每次连上（含重连）都拉取会话清单：adopt 存活会话 + attach 回放，
+                // 完成页面刷新后的标签恢复。
+                if (state === 'connected')
+                    this.socket?.send({ type: 'list' });
+            },
+        });
+        this.socket.connect();
+    }
+    // 打开抽屉且没有任何终端时自动新建默认 shell；清单未就绪时由 shells 帧兜底。
+    autoOpening = false;
+    maybeAutoOpen() {
+        const state = this.store.getSnapshot();
+        if (!state.open || state.conn !== 'connected' || state.shells.length === 0)
+            return;
+        if (state.tabs.length > 0 || this.autoOpening)
+            return;
+        this.autoOpening = true;
+        this.newTerminal(state.defaultShell);
+    }
+    newTerminal(shellId) {
+        this.ensureStarted();
+        this.socket?.send({ type: 'open', shellId, cols: 80, rows: 24 });
+    }
+    closeTab(id) {
+        this.sinks.delete(id);
+        this.pending.delete(id);
+        this.store.removeTab(id);
+        this.socket?.send({ type: 'close', id });
+    }
+    setActive(id) {
+        this.store.setActive(id);
+    }
+    setMode(mode) {
+        this.store.setMode(mode);
+    }
+    setHeight(height) {
+        this.store.setHeight(height);
+    }
+    showNotice(message) {
+        this.store.setNotice(message);
+        if (this.noticeTimer !== null)
+            clearTimeout(this.noticeTimer);
+        this.noticeTimer = setTimeout(() => {
+            this.noticeTimer = null;
+            this.store.setNotice(null);
+        }, 6000);
+    }
+    sendInput(id, data) {
+        this.socket?.send({ type: 'input', id, data });
+    }
+    sendResize(id, cols, rows) {
+        this.socket?.send({ type: 'resize', id, cols, rows });
+    }
+    registerSink(id, sink) {
+        this.sinks.set(id, sink);
+        const buffered = this.pending.get(id);
+        if (buffered !== undefined) {
+            this.pending.delete(id);
+            sink.write(buffered);
+        }
+        return () => {
+            if (this.sinks.get(id) === sink)
+                this.sinks.delete(id);
+        };
+    }
+    dispose() {
+        this.socket?.dispose();
+        this.socket = null;
+    }
+    writeData(id, data) {
+        const sink = this.sinks.get(id);
+        if (sink !== undefined) {
+            sink.write(data);
+            return;
+        }
+        this.pending.set(id, (this.pending.get(id) ?? '') + data);
+    }
+    onFrame(frame) {
+        switch (frame.type) {
+            case 'hello':
+                this.store.applyHello(frame);
+                break;
+            case 'shells': {
+                const { adopted } = this.store.applyInventory(frame.shells, frame.sessions);
+                for (const session of adopted) {
+                    this.socket?.send({ type: 'attach', id: session.id });
+                }
+                this.maybeAutoOpen();
+                break;
+            }
+            case 'opened':
+                this.autoOpening = false;
+                this.store.addSession(frame.session);
+                break;
+            case 'data':
+            case 'replay':
+                this.writeData(frame.id, frame.data);
+                break;
+            case 'exit':
+                if (frame.closed === true) {
+                    this.sinks.delete(frame.id);
+                    this.pending.delete(frame.id);
+                    this.store.removeTab(frame.id);
+                }
+                else {
+                    this.store.markDead(frame.id, frame.exitCode);
+                }
+                break;
+            case 'error':
+                this.autoOpening = false;
+                this.showNotice(frame.message);
+                break;
+        }
+    }
+}
+export const terminal = new TerminalController();
+export function useDrawerState() {
+    return useSyncExternalStore(terminal.store.subscribe, terminal.store.getSnapshot);
+}

package/lib/types/client/drawer.d.ts

@@ -0,0 +1,10 @@
+/**
+ * dsh-single-terminal —— 底部抽屉（shell.overlay 插槽）。
+ *
+ * - 两种模式：docked（占高度：对 AppFrame 根元素设 inline padding-bottom，把
+ *   主内容顶起；找不到 [data-shell-overlay] 锚点时静默降级为浮层）/ overlay（浮层）；
+ * - 顶部拖拽条调高度（pointer capture + 帧节流），localStorage 持久化 mode/height；
+ * - 组件常挂载（关闭时 display:none），保证 xterm 缓冲与会话不因抽屉开合丢失。
+ */
+export declare function TerminalDrawer(): import("react").JSX.Element;
+//# sourceMappingURL=drawer.d.ts.map

package/lib/types/client/drawer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"drawer.d.ts","sourceRoot":"","sources":["../../../src/client/drawer.tsx"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAeH,wBAAgB,cAAc,gCA+J7B"}

package/lib/types/client/drawer.js

@@ -0,0 +1,84 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * dsh-single-terminal —— 底部抽屉（shell.overlay 插槽）。
+ *
+ * - 两种模式：docked（占高度：对 AppFrame 根元素设 inline padding-bottom，把
+ *   主内容顶起；找不到 [data-shell-overlay] 锚点时静默降级为浮层）/ overlay（浮层）；
+ * - 顶部拖拽条调高度（pointer capture + 帧节流），localStorage 持久化 mode/height；
+ * - 组件常挂载（关闭时 display:none），保证 xterm 缓冲与会话不因抽屉开合丢失。
+ */
+import { useEffect, useRef, useState } from 'react';
+import { terminal, useDrawerState } from "./controller.js";
+import { t } from "./i18n.js";
+import { TerminalView } from "./term.js";
+const HEIGHT_MIN = 140;
+function findFrameElement() {
+    const overlay = document.querySelector('[data-shell-overlay]');
+    const frame = overlay?.parentElement;
+    return frame instanceof HTMLElement ? frame : null;
+}
+export function TerminalDrawer() {
+    const state = useDrawerState();
+    const [menuOpen, setMenuOpen] = useState(false);
+    const menuRef = useRef(null);
+    // 首次挂载即建立 WS 连接（空闲连接开销极小；页面刷新后由 list 帧恢复标签）。
+    useEffect(() => { terminal.ensureStarted(); }, []);
+    // 占高度模式：把 AppFrame 根元素顶起（border-box + padding-bottom）。
+    useEffect(() => {
+        if (!state.open || state.mode !== 'docked')
+            return;
+        const frame = findFrameElement();
+        if (frame === null)
+            return;
+        frame.style.boxSizing = 'border-box';
+        frame.style.paddingBottom = `${state.height}px`;
+        return () => {
+            frame.style.paddingBottom = '';
+            frame.style.boxSizing = '';
+        };
+    }, [state.open, state.mode, state.height]);
+    // 菜单外点关闭。
+    useEffect(() => {
+        if (!menuOpen)
+            return;
+        const onPointerDown = (event) => {
+            if (menuRef.current !== null && !menuRef.current.contains(event.target)) {
+                setMenuOpen(false);
+            }
+        };
+        document.addEventListener('pointerdown', onPointerDown);
+        return () => { document.removeEventListener('pointerdown', onPointerDown); };
+    }, [menuOpen]);
+    const availableShells = state.shells.filter((shell) => shell.available);
+    const startDrag = (event) => {
+        event.preventDefault();
+        const handle = event.currentTarget;
+        const startY = event.clientY;
+        const startHeight = state.height;
+        try {
+            handle.setPointerCapture(event.pointerId);
+        }
+        catch { /* 指针已失效（如合成事件）：仅失去拖出把手的跟随能力 */ }
+        let lastAt = 0;
+        const onMove = (move) => {
+            if (move.timeStamp - lastAt < 16)
+                return;
+            lastAt = move.timeStamp;
+            const next = Math.min(window.innerHeight - 100, Math.max(HEIGHT_MIN, startHeight + (startY - move.clientY)));
+            terminal.setHeight(next);
+        };
+        const onUp = () => {
+            handle.removeEventListener('pointermove', onMove);
+        };
+        handle.addEventListener('pointermove', onMove);
+        handle.addEventListener('pointerup', onUp, { once: true });
+        handle.addEventListener('pointercancel', onUp, { once: true });
+    };
+    return (_jsxs("div", { className: "dst-drawer", style: { display: state.open ? 'flex' : 'none', '--dst-height': `${state.height}px` }, children: [_jsx("div", { className: "dst-drag", onPointerDown: startDrag, title: t('terminal.mode.toggle') }), _jsxs("div", { className: "dst-head", children: [_jsx("div", { className: "dst-tabs", children: state.tabs.map((tab) => (_jsxs("button", { className: `dst-tab${tab.id === state.activeId ? ' active' : ''}`, onClick: () => { terminal.setActive(tab.id); }, title: tab.cwd, children: [_jsx("span", { className: `dst-dot${tab.alive ? '' : ' dead'}` }), _jsx("span", { children: tab.label }), !tab.alive && _jsx("span", { children: t('terminal.exited') }), _jsx("span", { className: "dst-tabclose", role: "button", title: t('terminal.closeTab'), onClick: (event) => {
+                                        event.stopPropagation();
+                                        terminal.closeTab(tab.id);
+                                    }, children: "\u2715" })] }, tab.id))) }), _jsx("span", { className: `dst-conn ${state.conn}`, title: t(`terminal.status.${state.conn}`) }), _jsxs("div", { className: "dst-actions", children: [_jsx("button", { className: "dst-modebtn", onClick: () => { terminal.setMode(state.mode === 'docked' ? 'overlay' : 'docked'); }, title: t('terminal.mode.toggle'), children: state.mode === 'docked' ? `⬓ ${t('terminal.mode.dock')}` : `◫ ${t('terminal.mode.overlay')}` }), _jsxs("div", { style: { position: 'relative' }, ref: menuRef, children: [_jsx("button", { className: "dst-iconbtn", onClick: () => { terminal.newTerminal(state.defaultShell); }, title: `${t('terminal.new')}（${availableShells.find((shell) => shell.id === state.defaultShell)?.name ?? state.defaultShell}）`, children: "\uFF0B" }), _jsx("button", { className: "dst-iconbtn", style: { width: 18 }, onClick: () => { setMenuOpen((open) => !open); }, title: t('terminal.new'), children: "\u25B8" }), menuOpen && (_jsxs("div", { className: "dst-menu", children: [availableShells.length === 0 && (_jsx("div", { className: "dst-menuitem", style: { cursor: 'default', opacity: 0.6 }, children: "\u2014" })), availableShells.map((shell) => (_jsx("button", { className: "dst-menuitem", onClick: () => {
+                                                    setMenuOpen(false);
+                                                    terminal.newTerminal(shell.id);
+                                                }, children: shell.name }, shell.id)))] }))] }), _jsx("button", { className: "dst-iconbtn", onClick: () => { terminal.setOpen(false); }, title: t('terminal.closeDrawer'), children: "\u25BE" })] })] }), _jsxs("div", { className: "dst-body", children: [state.tabs.map((tab) => (_jsx(TerminalView, { tab: tab, active: tab.id === state.activeId, fontSize: state.fontSize, fontFamily: state.fontFamily }, tab.id))), state.tabs.length === 0 && _jsx("div", { className: "dst-empty", children: t('terminal.empty') }), state.notice !== null && _jsx("div", { className: "dst-notice", children: state.notice })] })] }));
+}

package/lib/types/client/i18n.d.ts

@@ -0,0 +1,8 @@
+/**
+ * dsh-single-terminal —— 双语字典（zh/en），语言由宿主 locale 服务驱动。
+ */
+export type Lang = 'zh' | 'en';
+export declare function setLang(next: Lang): void;
+export declare function getLang(): Lang;
+export declare function t(key: string): string;
+//# sourceMappingURL=i18n.d.ts.map

package/lib/types/client/i18n.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"i18n.d.ts","sourceRoot":"","sources":["../../../src/client/i18n.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,MAAM,IAAI,GAAG,IAAI,GAAG,IAAI,CAAA;AAI9B,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAExC;AAED,wBAAgB,OAAO,IAAI,IAAI,CAE9B;AAyCD,wBAAgB,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAErC"}

package/lib/types/client/i18n.js

@@ -0,0 +1,51 @@
+/**
+ * dsh-single-terminal —— 双语字典（zh/en），语言由宿主 locale 服务驱动。
+ */
+let lang = 'en';
+export function setLang(next) {
+    lang = next;
+}
+export function getLang() {
+    return lang;
+}
+const DICT = {
+    zh: {
+        'terminal.title': '终端',
+        'terminal.toggleTip': '打开终端面板 Alt+C',
+        'terminal.new': '新建终端',
+        'terminal.closeTab': '关闭终端',
+        'terminal.closeDrawer': '收起抽屉',
+        'terminal.mode.dock': '占高度',
+        'terminal.mode.overlay': '浮层',
+        'terminal.mode.toggle': '切换抽屉模式',
+        'terminal.status.connected': '已连接',
+        'terminal.status.connecting': '连接中…',
+        'terminal.status.reconnecting': '重连中…',
+        'terminal.status.disconnected': '已断开',
+        'terminal.exited': '已退出',
+        'terminal.empty': '暂无终端会话，点击右上角 + 新建',
+        'terminal.error.limit': '终端数量已达上限',
+        'terminal.error.spawn': '终端启动失败',
+    },
+    en: {
+        'terminal.title': 'Terminal',
+        'terminal.toggleTip': 'Open terminal panel Alt+C',
+        'terminal.new': 'New terminal',
+        'terminal.closeTab': 'Close terminal',
+        'terminal.closeDrawer': 'Collapse drawer',
+        'terminal.mode.dock': 'Docked',
+        'terminal.mode.overlay': 'Overlay',
+        'terminal.mode.toggle': 'Toggle drawer mode',
+        'terminal.status.connected': 'Connected',
+        'terminal.status.connecting': 'Connecting…',
+        'terminal.status.reconnecting': 'Reconnecting…',
+        'terminal.status.disconnected': 'Disconnected',
+        'terminal.exited': 'Exited',
+        'terminal.empty': 'No terminal sessions yet — click + to create one',
+        'terminal.error.limit': 'Terminal session limit reached',
+        'terminal.error.spawn': 'Failed to spawn terminal',
+    },
+};
+export function t(key) {
+    return DICT[lang][key] ?? DICT.en[key] ?? key;
+}

package/lib/types/client/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * dsh-single-terminal —— 浏览器半边入口（tsdown 打包为 __ModuleLoader__ 工厂）。
+ *
+ * 本文件为纯 ESM 模块，直接导出插件形状 { name, inject, apply }；
+ * window.__ModuleLoader__.load 工厂包装由 tsdown 的 banner/footer 在构建时生成
+ * （见 tsdown.config.ts）。外部依赖（react / react/jsx-runtime）构建时保持
+ * external，运行时经 factory 的 require 解析宿主模块表（seed）。
+ */
+export declare const name: string;
+export declare const inject: string[];
+export declare const apply: (ctx: import("./plugin.tsx").ClientCtx) => void;
+export type { ClientCtx, ClientPluginModule } from './plugin.tsx';
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/client/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAMH,eAAO,MAAM,IAAI,QAAc,CAAA;AAC/B,eAAO,MAAM,MAAM,UAAgB,CAAA;AACnC,eAAO,MAAM,KAAK,iDAAe,CAAA;AACjC,YAAY,EAAE,SAAS,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA"}

package/lib/types/client/index.js

@@ -0,0 +1,13 @@
+/**
+ * dsh-single-terminal —— 浏览器半边入口（tsdown 打包为 __ModuleLoader__ 工厂）。
+ *
+ * 本文件为纯 ESM 模块，直接导出插件形状 { name, inject, apply }；
+ * window.__ModuleLoader__.load 工厂包装由 tsdown 的 banner/footer 在构建时生成
+ * （见 tsdown.config.ts）。外部依赖（react / react/jsx-runtime）构建时保持
+ * external，运行时经 factory 的 require 解析宿主模块表（seed）。
+ */
+import { createPlugin } from "./plugin.js";
+const plugin = createPlugin();
+export const name = plugin.name;
+export const inject = plugin.inject;
+export const apply = plugin.apply;

package/lib/types/client/plugin.d.ts

@@ -0,0 +1,23 @@
+/**
+ * dsh-single-terminal —— 浏览器半边插件主体（slots 注册）。
+ *
+ * - shell.overlay：底部终端抽屉；
+ * - conversation.session.header.utilities：会话头部开关按钮（宿主 Tooltip 气泡）；
+ * - Alt+C 快捷键开关抽屉（ctx.effect 挂窗级监听，卸载自动清理；焦点在终端
+ *   输入区时放行，让 shell 收到 ESC c 而不误触）；
+ * - 语言跟随宿主 locale 服务（软依赖，缺失时回退 en）。
+ */
+/** 浏览器侧插件上下文（宿主注入）。 */
+export interface ClientCtx {
+    get<T = unknown>(name: string): T | undefined;
+    /** 注册随插件卸载自动清理的副作用（回调返回 disposer）。 */
+    effect(fn: () => (() => void) | void): unknown;
+    on?(event: string, listener: (payload: unknown) => void): unknown;
+}
+export interface ClientPluginModule {
+    name: string;
+    inject: string[];
+    apply(ctx: ClientCtx): void;
+}
+export declare function createPlugin(): ClientPluginModule;
+//# sourceMappingURL=plugin.d.ts.map

package/lib/types/client/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../src/client/plugin.tsx"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAmBH,uBAAuB;AACvB,MAAM,WAAW,SAAS;IACxB,GAAG,CAAC,CAAC,GAAG,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS,CAAA;IAC7C,sCAAsC;IACtC,MAAM,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,IAAI,CAAC,GAAG,IAAI,GAAG,OAAO,CAAA;IAC9C,EAAE,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,GAAG,OAAO,CAAA;CAClE;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAA;IACZ,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,KAAK,CAAC,GAAG,EAAE,SAAS,GAAG,IAAI,CAAA;CAC5B;AAED,wBAAgB,YAAY,IAAI,kBAAkB,CAkDjD"}

package/lib/types/client/plugin.js

@@ -0,0 +1,60 @@
+/**
+ * dsh-single-terminal —— 浏览器半边插件主体（slots 注册）。
+ *
+ * - shell.overlay：底部终端抽屉；
+ * - conversation.session.header.utilities：会话头部开关按钮（宿主 Tooltip 气泡）；
+ * - Alt+C 快捷键开关抽屉（ctx.effect 挂窗级监听，卸载自动清理；焦点在终端
+ *   输入区时放行，让 shell 收到 ESC c 而不误触）；
+ * - 语言跟随宿主 locale 服务（软依赖，缺失时回退 en）。
+ */
+import { terminal } from "./controller.js";
+import { TerminalDrawer } from "./drawer.js";
+import { setLang } from "./i18n.js";
+import { injectStyles } from "./styles.js";
+import { TerminalToggle } from "./toggle.js";
+export function createPlugin() {
+    return {
+        name: 'dsh-single-terminal',
+        inject: ['slots', 'locale'],
+        apply(ctx) {
+            const toLang = (active) => (/^zh/i.test(active) ? 'zh' : 'en');
+            const locale = ctx.get('locale');
+            if (locale !== undefined) {
+                const syncLang = () => { setLang(toLang(locale.getSnapshot().active)); };
+                syncLang();
+                locale.subscribe(syncLang);
+            }
+            else if (typeof ctx.on === 'function') {
+                ctx.on('locale/change', (snapshot) => {
+                    const active = snapshot?.active;
+                    if (typeof active === 'string')
+                        setLang(toLang(active));
+                });
+            }
+            const slots = ctx.get('slots');
+            if (slots === undefined)
+                return;
+            injectStyles();
+            // 底部终端抽屉（frame 级浮层，additive list 插槽）。
+            slots.inject('shell.overlay', () => slots.register({ name: 'shell.overlay', id: 'dsh-single-terminal', order: 50 }, TerminalDrawer));
+            // 会话头部开关按钮（utilities 区，会话标题行右侧）。
+            slots.inject('conversation.session.header.utilities', () => slots.register({ name: 'conversation.session.header.utilities', id: 'dsh-single-terminal-toggle', order: 100 }, TerminalToggle));
+            // Alt+C 开关抽屉；焦点在抽屉内（终端输入）时放行，Alt+C 作为 ESC c 发给 shell。
+            ctx.effect(() => {
+                const onKeyDown = (event) => {
+                    if (!event.altKey || event.ctrlKey || event.metaKey || event.code !== 'KeyC')
+                        return;
+                    if (event.repeat)
+                        return;
+                    const target = event.target;
+                    if (target instanceof Element && target.closest('.dst-drawer') !== null)
+                        return;
+                    event.preventDefault();
+                    terminal.toggle();
+                };
+                window.addEventListener('keydown', onKeyDown);
+                return () => { window.removeEventListener('keydown', onKeyDown); };
+            });
+        },
+    };
+}

package/lib/types/client/protocol.d.ts

@@ -0,0 +1,81 @@
+/**
+ * dsh-single-terminal —— 客户端侧 WS 帧协议视图（与 src/host/types.ts 保持一致；
+ * 双面插件不共享运行时代码，这里独立声明）。
+ */
+export interface ShellInfo {
+    id: string;
+    name: string;
+    available: boolean;
+}
+export interface SessionInfo {
+    id: string;
+    shellId: string;
+    label: string;
+    cwd: string;
+    alive: boolean;
+    pid: number;
+    exitCode: number | null;
+    signal: number | null;
+}
+export type ClientFrame = {
+    type: 'ping';
+} | {
+    type: 'list';
+} | {
+    type: 'open';
+    shellId: string;
+    cols: number;
+    rows: number;
+    cwd?: string;
+} | {
+    type: 'input';
+    id: string;
+    data: string;
+} | {
+    type: 'resize';
+    id: string;
+    cols: number;
+    rows: number;
+} | {
+    type: 'attach';
+    id: string;
+} | {
+    type: 'close';
+    id: string;
+};
+export type HostFrame = {
+    type: 'pong';
+} | {
+    type: 'hello';
+    platform: string;
+    defaultShell: string;
+    fontSize: number;
+    fontFamily: string;
+} | {
+    type: 'shells';
+    defaultShell: string;
+    shells: ShellInfo[];
+    sessions: SessionInfo[];
+} | {
+    type: 'opened';
+    session: SessionInfo;
+} | {
+    type: 'data';
+    id: string;
+    data: string;
+} | {
+    type: 'replay';
+    id: string;
+    data: string;
+} | {
+    type: 'exit';
+    id: string;
+    exitCode: number | null;
+    signal: number | null;
+    closed?: boolean;
+} | {
+    type: 'error';
+    message: string;
+    id?: string;
+};
+//# sourceMappingURL=protocol.d.ts.map

package/lib/types/client/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../../src/client/protocol.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,WAAW,SAAS;IACxB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,OAAO,CAAA;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,OAAO,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB;AAED,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAA;CAAE,GAC3E;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAA;AAEjC,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC/F;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,YAAY,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,EAAE,CAAC;IAAC,QAAQ,EAAE,WAAW,EAAE,CAAA;CAAE,GACtF;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,WAAW,CAAA;CAAE,GACxC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAA;CAAE,GAC9F;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,CAAA"}

package/lib/types/client/protocol.js

@@ -0,0 +1,5 @@
+/**
+ * dsh-single-terminal —— 客户端侧 WS 帧协议视图（与 src/host/types.ts 保持一致；
+ * 双面插件不共享运行时代码，这里独立声明）。
+ */
+export {};

package/lib/types/client/storage.d.ts

@@ -0,0 +1,6 @@
+/**
+ * dsh-single-terminal —— 浏览器侧 UI 状态持久化（localStorage，JSON 容错）。
+ */
+export declare function loadJson<T>(key: string, fallback: T): T;
+export declare function saveJson(key: string, value: unknown): void;
+//# sourceMappingURL=storage.d.ts.map

package/lib/types/client/storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage.d.ts","sourceRoot":"","sources":["../../../src/client/storage.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAQvD;AAED,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAI1D"}

package/lib/types/client/storage.js

@@ -0,0 +1,21 @@
+/**
+ * dsh-single-terminal —— 浏览器侧 UI 状态持久化（localStorage，JSON 容错）。
+ */
+const PREFIX = 'dsh-single-terminal.';
+export function loadJson(key, fallback) {
+    try {
+        const raw = localStorage.getItem(PREFIX + key);
+        if (raw === null)
+            return fallback;
+        return JSON.parse(raw);
+    }
+    catch {
+        return fallback;
+    }
+}
+export function saveJson(key, value) {
+    try {
+        localStorage.setItem(PREFIX + key, JSON.stringify(value));
+    }
+    catch { /* storage unavailable */ }
+}

package/lib/types/client/styles.d.ts

@@ -0,0 +1,5 @@
+/**
+ * dsh-single-terminal —— 抽屉全局样式 + 内嵌 xterm.css（构建期生成注入）。
+ */
+export declare function injectStyles(): void;
+//# sourceMappingURL=styles.d.ts.map

package/lib/types/client/styles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"styles.d.ts","sourceRoot":"","sources":["../../../src/client/styles.ts"],"names":[],"mappings":"AAAA;;GAEG;AAgGH,wBAAgB,YAAY,IAAI,IAAI,CAOnC"}