dsh-single-terminal 0.1.0

package/src/client/i18n.ts

@@ -0,0 +1,58 @@
+/**
+ * dsh-single-terminal —— 双语字典（zh/en），语言由宿主 locale 服务驱动。
+ */
+
+export type Lang = 'zh' | 'en'
+
+let lang: Lang = 'en'
+
+export function setLang(next: Lang): void {
+  lang = next
+}
+
+export function getLang(): Lang {
+  return lang
+}
+
+const DICT: Record<Lang, Record<string, string>> = {
+  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: string): string {
+  return DICT[lang][key] ?? DICT.en[key] ?? key
+}

package/src/client/index.ts

@@ -0,0 +1,17 @@
+/**
+ * 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.tsx'
+
+const plugin = createPlugin()
+
+export const name = plugin.name
+export const inject = plugin.inject
+export const apply = plugin.apply
+export type { ClientCtx, ClientPluginModule } from './plugin.tsx'

package/src/client/plugin.tsx

@@ -0,0 +1,92 @@
+/**
+ * dsh-single-terminal —— 浏览器半边插件主体（slots 注册）。
+ *
+ * - shell.overlay：底部终端抽屉；
+ * - conversation.session.header.utilities：会话头部开关按钮（宿主 Tooltip 气泡）；
+ * - Alt+C 快捷键开关抽屉（ctx.effect 挂窗级监听，卸载自动清理；焦点在终端
+ *   输入区时放行，让 shell 收到 ESC c 而不误触）；
+ * - 语言跟随宿主 locale 服务（软依赖，缺失时回退 en）。
+ */
+
+import { terminal } from './controller.ts'
+import { TerminalDrawer } from './drawer.tsx'
+import { setLang } from './i18n.ts'
+import { injectStyles } from './styles.ts'
+import { TerminalToggle } from './toggle.tsx'
+
+/** 宿主 slots 服务最小视图。 */
+interface SlotsService {
+  inject(name: string, fn: () => unknown): unknown
+  register(def: Record<string, unknown>, component: unknown): () => void
+}
+
+interface LocaleFace {
+  getSnapshot(): { active: string }
+  subscribe(fn: () => void): () => void
+}
+
+/** 浏览器侧插件上下文（宿主注入）。 */
+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 function createPlugin(): ClientPluginModule {
+  return {
+    name: 'dsh-single-terminal',
+    inject: ['slots', 'locale'],
+
+    apply(ctx: ClientCtx): void {
+      const toLang = (active: string): 'zh' | 'en' => (/^zh/i.test(active) ? 'zh' : 'en')
+      const locale = ctx.get<LocaleFace>('locale')
+      if (locale !== undefined) {
+        const syncLang = (): void => { setLang(toLang(locale.getSnapshot().active)) }
+        syncLang()
+        locale.subscribe(syncLang)
+      } else if (typeof ctx.on === 'function') {
+        ctx.on('locale/change', (snapshot: unknown) => {
+          const active = (snapshot as { active?: string } | undefined)?.active
+          if (typeof active === 'string') setLang(toLang(active))
+        })
+      }
+
+      const slots = ctx.get<SlotsService>('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: KeyboardEvent): void => {
+          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/src/client/protocol.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 }

package/src/client/storage.ts

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

package/src/client/styles.ts

@@ -0,0 +1,106 @@
+/**
+ * dsh-single-terminal —— 抽屉全局样式 + 内嵌 xterm.css（构建期生成注入）。
+ */
+
+import { XTERM_CSS } from './xterm-css.ts'
+
+const DRAWER_CSS = `
+.dst-drawer {
+  position: absolute;
+  left: 0; right: 0; bottom: 0;
+  height: var(--dst-height, 360px);
+  min-height: 140px;
+  display: flex;
+  flex-direction: column;
+  background: #1f2126;
+  border-top: 1px solid #3a3d44;
+  box-shadow: 0 -8px 24px rgba(0, 0, 0, 0.25);
+  z-index: 5;
+}
+.dst-drag { height: 5px; flex: none; cursor: row-resize; touch-action: none; }
+.dst-drag:hover { background: #4a4d55; }
+.dst-head {
+  display: flex; align-items: center; gap: 4px;
+  height: 36px; flex: none; padding: 0 8px;
+  border-bottom: 1px solid #3a3d44;
+  color: #c9cdd4;
+}
+.dst-tabs { display: flex; align-items: center; gap: 2px; flex: 1; min-width: 0; overflow-x: auto; scrollbar-width: none; }
+.dst-tabs::-webkit-scrollbar { display: none; }
+.dst-tab {
+  display: inline-flex; align-items: center; gap: 6px;
+  padding: 4px 8px; border: none; border-radius: 6px;
+  background: transparent; color: #9aa0aa; font-size: 12px;
+  cursor: pointer; white-space: nowrap;
+}
+.dst-tab:hover { background: rgba(255, 255, 255, 0.06); }
+.dst-tab.active { background: rgba(255, 255, 255, 0.1); color: #eceef1; }
+.dst-dot { width: 6px; height: 6px; border-radius: 50%; background: #3fb950; flex: none; }
+.dst-dot.dead { background: #6e7278; }
+.dst-tabclose {
+  display: inline-flex; align-items: center; justify-content: center;
+  width: 16px; height: 16px; border: none; border-radius: 4px;
+  background: transparent; color: inherit; font-size: 12px; line-height: 1;
+  cursor: pointer; padding: 0;
+}
+.dst-tabclose:hover { background: rgba(255, 255, 255, 0.14); }
+.dst-actions { display: flex; align-items: center; gap: 2px; flex: none; }
+.dst-conn { width: 8px; height: 8px; border-radius: 50%; flex: none; margin: 0 4px; }
+.dst-conn.connected { background: #3fb950; }
+.dst-conn.connecting, .dst-conn.reconnecting { background: #d29922; }
+.dst-iconbtn {
+  display: inline-flex; align-items: center; justify-content: center;
+  width: 26px; height: 26px; border: none; border-radius: 6px;
+  background: transparent; color: inherit; cursor: pointer; padding: 0;
+}
+.dst-iconbtn:hover { background: rgba(255, 255, 255, 0.1); }
+.dst-modebtn {
+  display: inline-flex; align-items: center; gap: 4px;
+  height: 26px; padding: 0 8px; border: none; border-radius: 6px;
+  background: transparent; color: #9aa0aa; font-size: 12px; cursor: pointer;
+}
+.dst-modebtn:hover { background: rgba(255, 255, 255, 0.1); color: #eceef1; }
+.dst-menu {
+  position: absolute; right: 8px; bottom: 44px; min-width: 170px;
+  background: #26282e; border: 1px solid #3a3d44; border-radius: 8px;
+  padding: 4px; z-index: 10; box-shadow: 0 8px 24px rgba(0, 0, 0, 0.45);
+}
+.dst-menuitem {
+  display: flex; width: 100%; align-items: center; gap: 8px;
+  padding: 6px 10px; border: none; border-radius: 6px;
+  background: transparent; color: #d5d8dd; font-size: 13px;
+  cursor: pointer; text-align: left;
+}
+.dst-menuitem:hover { background: rgba(255, 255, 255, 0.08); }
+.dst-body { flex: 1; min-height: 0; position: relative; padding: 2px 6px 6px; background: #1a1c20; }
+.dst-term { width: 100%; height: 100%; }
+.dst-empty {
+  position: absolute; inset: 0; display: flex;
+  align-items: center; justify-content: center;
+  color: #6e7278; font-size: 13px;
+}
+.dst-notice {
+  position: absolute; left: 50%; transform: translateX(-50%); bottom: 12px;
+  max-width: 70%; padding: 6px 12px; border-radius: 8px; z-index: 8;
+  background: #4a2226; color: #ffb4b4; font-size: 12px;
+  overflow: hidden; text-overflow: ellipsis; white-space: nowrap;
+}
+.dst-headbtn {
+  display: inline-flex; align-items: center; justify-content: center;
+  width: 26px; height: 26px; padding: 0;
+  border: none; border-radius: 6px; background: transparent;
+  color: inherit; cursor: pointer;
+}
+.dst-headbtn:hover, .dst-headbtn.active { background: rgba(128, 128, 128, 0.18); }
+`
+
+let injected = false
+
+export function injectStyles(): void {
+  if (injected) return
+  injected = true
+  const style = document.createElement('style')
+  style.setAttribute('data-plugin', 'dsh-single-terminal')
+  style.textContent = XTERM_CSS + DRAWER_CSS
+  document.head.appendChild(style)
+}

package/src/client/term.tsx

@@ -0,0 +1,95 @@
+/**
+ * dsh-single-terminal —— 单标签终端视图（xterm.js）。
+ *
+ * - Webgl 渲染器加载失败时自动回退到默认渲染；
+ * - ResizeObserver → FitAddon.fit() → onResize 帧上报宿主 resize PTY；
+ * - 输出经 controller sink 通道写入（挂载前的字节积压在 controller.pending）。
+ */
+
+import { useEffect, useRef } from 'react'
+import { Terminal } from '@xterm/xterm'
+import { FitAddon } from '@xterm/addon-fit'
+import { WebglAddon } from '@xterm/addon-webgl'
+import { terminal, type TabState } from './controller.ts'
+
+const THEME = {
+  background: '#1a1c20',
+  foreground: '#d4d4d4',
+  cursor: '#aeafad',
+  cursorAccent: '#1a1c20',
+  selectionBackground: '#264f78',
+  black: '#000000',
+  red: '#cd3131',
+  green: '#0dbc79',
+  yellow: '#e5e510',
+  blue: '#2472c8',
+  magenta: '#bc3fbc',
+  cyan: '#11a8cd',
+  white: '#e5e5e5',
+  brightBlack: '#666666',
+  brightRed: '#f14c4c',
+  brightGreen: '#23d18b',
+  brightYellow: '#f5f543',
+  brightBlue: '#3b8eea',
+  brightMagenta: '#d670d6',
+  brightCyan: '#29b8db',
+  brightWhite: '#ffffff',
+}
+
+export function TerminalView(props: {
+  tab: TabState
+  active: boolean
+  fontSize: number
+  fontFamily: string
+}) {
+  const containerRef = useRef<HTMLDivElement | null>(null)
+
+  useEffect(() => {
+    const container = containerRef.current
+    if (container === null) return
+    const id = props.tab.id
+
+    const instance = new Terminal({
+      fontSize: props.fontSize,
+      fontFamily: props.fontFamily,
+      cursorBlink: true,
+      scrollback: 2000,
+      theme: THEME,
+    })
+    const fit = new FitAddon()
+    instance.loadAddon(fit)
+    try {
+      instance.loadAddon(new WebglAddon())
+    } catch { /* no webgl: default canvas renderer */ }
+    instance.open(container)
+    instance.onData((data) => { terminal.sendInput(id, data) })
+    instance.onResize(({ cols, rows }) => { terminal.sendResize(id, cols, rows) })
+
+    const unregister = terminal.registerSink(id, { write: (data) => { instance.write(data) } })
+
+    const observer = new ResizeObserver(() => {
+      if (container.clientWidth < 10 || container.clientHeight < 10) return
+      try { fit.fit() } catch { /* not visible */ }
+    })
+    observer.observe(container)
+    requestAnimationFrame(() => {
+      if (container.clientWidth < 10 || container.clientHeight < 10) return
+      try { fit.fit() } catch { /* not ready */ }
+    })
+
+    return () => {
+      observer.disconnect()
+      unregister()
+      instance.dispose()
+    }
+    // fontSize/fontFamily 变化不重建（配置改动后刷新页面生效）
+  }, [props.tab.id])
+
+  return (
+    <div
+      ref={containerRef}
+      className="dst-term"
+      style={{ display: props.active ? 'block' : 'none' }}
+    />
+  )
+}

package/src/client/toggle.tsx

@@ -0,0 +1,43 @@
+/**
+ * dsh-single-terminal —— 会话头部开关按钮（conversation.session.header.utilities 插槽）。
+ *
+ * 图标为 panel-bottom（面板底部条填充）样式，几何取自宿主 IconPanelLeftOutline16
+ * 旋转 -90°，风格与宿主图标一致；hover 气泡用宿主 Tooltip（label 传 thunk，
+ * 气泡显示时求值，语言切换即生效）。
+ */
+
+import { Tooltip } from '@deepseek-ai/dsh-client-ui-primitives'
+import { terminal, useDrawerState } from './controller.ts'
+import { t } from './i18n.ts'
+
+const PANEL_LEFT_PATH = 'M9.67272 0.522841C10.8339 0.522841 11.76 0.522714 12.4963 0.602493C13.2453 0.683657 13.8789 0.854248 14.4264 1.25197C14.7504 1.48739 15.0355 1.77247 15.2709 2.0965C15.6686 2.64394 15.8392 3.27758 15.9204 4.02655C16.0002 4.7629 16 5.68895 16 6.85014V9.14986C16 10.3111 16.0002 11.2371 15.9204 11.9735C15.8392 12.7224 15.6686 13.3561 15.2709 13.9035C15.0355 14.2275 14.7504 14.5126 14.4264 14.748C13.8789 15.1458 13.2453 15.3163 12.4963 15.3975C11.76 15.4773 10.8339 15.4772 9.67272 15.4772H6.3273C5.16611 15.4772 4.24006 15.4773 3.50371 15.3975C2.75474 15.3163 2.1211 15.1458 1.57366 14.748C1.24963 14.5126 0.964549 14.2275 0.729131 13.9035C0.331407 13.3561 0.160817 12.7224 0.0796529 11.9735C-0.000126137 11.2371 1.25338e-09 10.3111 1.25338e-09 9.14986V6.85014C1.25329e-09 5.68895 -0.000126137 4.7629 0.0796529 4.02655C0.160817 3.27758 0.331407 2.64394 0.729131 2.0965C0.964549 1.77247 1.24963 1.48739 1.57366 1.25197C2.1211 0.854248 2.75474 0.683657 3.50371 0.602493C4.24006 0.522714 5.16611 0.522841 6.3273 0.522841H9.67272ZM5.54303 1.88715V14.1118C5.78636 14.1128 6.04709 14.1169 6.3273 14.1169H9.67272C10.8639 14.1169 11.7032 14.1164 12.3493 14.0465C12.9824 13.9779 13.3497 13.8494 13.6268 13.6482C13.8354 13.4966 14.0195 13.3125 14.1711 13.1039C14.3723 12.8268 14.5007 12.4595 14.5693 11.8264C14.6393 11.1803 14.6398 10.341 14.6398 9.14986V6.85014C14.6398 5.65896 14.6393 4.81967 14.5693 4.1736C14.5007 3.54048 14.3723 3.17318 14.1711 2.89609C14.0195 2.68747 13.8354 2.50337 13.6268 2.35179C13.3497 2.1506 12.9824 2.02212 12.3493 1.95353C11.7032 1.88358 10.8639 1.88307 9.67272 1.88307H6.3273C6.04709 1.88307 5.78636 1.8862 5.54303 1.88715ZM4.1828 1.91166C3.99125 1.9216 3.8148 1.93577 3.65076 1.95353C3.01764 2.02212 2.65034 2.1506 2.37325 2.35179C2.16463 2.50337 1.98052 2.68747 1.82895 2.89609C1.62776 3.17318 1.49928 3.54048 1.43069 4.1736C1.36074 4.81967 1.36023 5.65896 1.36023 6.85014V9.14986C1.36023 10.341 1.36074 11.1803 1.43069 11.8264C1.49928 12.4595 1.62776 12.8268 1.82895 13.1039C1.98052 13.3125 2.16463 13.4966 2.37325 13.6482C2.65034 13.8494 3.01764 13.9779 3.65076 14.0465C3.81478 14.0642 3.99127 14.0774 4.1828 14.0873V1.91166Z'
+
+function PanelBottomIcon(props: { size?: number }) {
+  return (
+    <svg width={props.size ?? 16} height={props.size ?? 16} viewBox="0 0 16 16" fill="none" aria-hidden="true">
+      <path
+        d={PANEL_LEFT_PATH}
+        transform="rotate(-90 8 8)"
+        fillRule="evenodd"
+        clipRule="evenodd"
+        fill="currentColor"
+      />
+    </svg>
+  )
+}
+
+export function TerminalToggle() {
+  const state = useDrawerState()
+  return (
+    <Tooltip label={() => t('terminal.toggleTip')} side="bottom">
+      <button
+        type="button"
+        className={`dst-headbtn${state.open ? ' active' : ''}`}
+        aria-label={t('terminal.toggleTip')}
+        onClick={() => { terminal.toggle() }}
+      >
+        <PanelBottomIcon size={16} />
+      </button>
+    </Tooltip>
+  )
+}

package/src/client/ws.ts

@@ -0,0 +1,81 @@
+/**
+ * dsh-single-terminal —— 同源 WebSocket 客户端（自动重连，指数退避）。
+ *
+ * URL 由 location.origin 推导（http→ws / https→wss），浏览器自动携带
+ * dsh-auth cookie（与宿主 /api/remote.mux 相同的鉴权路径）。
+ */
+
+import type { ClientFrame, HostFrame } from './protocol.ts'
+
+export type ConnectionState = 'connecting' | 'connected' | 'reconnecting'
+
+export interface TerminalSocketHandlers {
+  onFrame(frame: HostFrame): void
+  onState(state: ConnectionState): void
+}
+
+export class TerminalSocket {
+  private socket: WebSocket | null = null
+  private retry = 0
+  private timer: ReturnType<typeof setTimeout> | null = null
+  private disposed = false
+
+  constructor(private readonly handlers: TerminalSocketHandlers) {}
+
+  connect(): void {
+    if (this.disposed || this.socket !== null) return
+    this.handlers.onState(this.retry === 0 ? 'connecting' : 'reconnecting')
+    const origin = globalThis.location?.origin
+    const base = origin !== undefined && origin !== 'null' ? origin : 'http://localhost:3000'
+    const url = base.replace(/^http/, 'ws') + '/api/dsh-single-terminal.ws'
+    const socket = new WebSocket(url)
+    this.socket = socket
+    socket.onopen = () => {
+      this.retry = 0
+      this.handlers.onState('connected')
+    }
+    socket.onmessage = (event: MessageEvent) => {
+      let frame: HostFrame
+      try {
+        frame = JSON.parse(String(event.data)) as HostFrame
+      } catch {
+        return
+      }
+      this.handlers.onFrame(frame)
+    }
+    socket.onclose = () => {
+      this.socket = null
+      if (this.disposed) return
+      this.scheduleReconnect()
+    }
+    socket.onerror = () => {
+      try { socket.close() } catch { /* closing */ }
+    }
+  }
+
+  send(frame: ClientFrame): void {
+    if (this.socket !== null && this.socket.readyState === WebSocket.OPEN) {
+      this.socket.send(JSON.stringify(frame))
+    }
+  }
+
+  dispose(): void {
+    this.disposed = true
+    if (this.timer !== null) clearTimeout(this.timer)
+    this.timer = null
+    if (this.socket !== null) {
+      try { this.socket.close() } catch { /* closing */ }
+      this.socket = null
+    }
+  }
+
+  private scheduleReconnect(): void {
+    this.retry += 1
+    const delay = Math.min(1000 * 2 ** Math.min(this.retry - 1, 4), 15_000)
+    this.handlers.onState('reconnecting')
+    this.timer = setTimeout(() => {
+      this.timer = null
+      this.connect()
+    }, delay)
+  }
+}