@tiphareth/dsh-hardssh 0.1.2-alpha

package/src/client/ssh/panel/TerminalTab.tsx

@@ -0,0 +1,176 @@
+/**
+ * Terminal tab: an xterm.js PTY view over the host's WebSocket terminal route.
+ * A host <select> plus connect/disconnect controls; the terminal container is
+ * sized by FitAddon (default 80x24 before first fit). On remote exit the last
+ * output stays visible and input is disabled. xterm's stylesheet is injected
+ * once per page load (module-level guard).
+ */
+import { useEffect, useRef, useState } from 'react'
+import { Terminal } from '@xterm/xterm'
+import { FitAddon } from '@xterm/addon-fit'
+import type { SshApi, TerminalConnection } from '../api.ts'
+import type { SshHostSummary } from '../../../ssh/protocol.ts'
+import { XTERM_CSS } from './xterm.css.ts'
+import { errorMessage, tt } from './helpers.ts'
+import css from './panel.module.css'
+
+/** Terminal tab props. */
+export interface TerminalTabProps {
+  api: SshApi
+  /** Alias preselected by a "connect" action from the hosts tab. */
+  presetAlias?: string
+  /** Monotonic id of the connect request (re-applies presetAlias). */
+  requestId?: number
+}
+
+/** The terminal session lifecycle state shown in the status banner. */
+type TerminalStatus =
+  | { kind: 'idle' }
+  | { kind: 'connecting' }
+  | { kind: 'connected'; alias: string }
+  | { kind: 'exited'; alias: string; detail?: string }
+  | { kind: 'error'; detail: string }
+
+/** Injected-once guard for the xterm stylesheet (one tag per page load). */
+let xtermCssInjected = false
+
+function ensureXtermCss(): void {
+  if (xtermCssInjected || typeof document === 'undefined') return
+  xtermCssInjected = true
+  if (document.querySelector('style[data-dsh-ssh-xterm]') !== null) return
+  const style = document.createElement('style')
+  style.dataset.dshSshXterm = ''
+  style.textContent = XTERM_CSS
+  document.head.appendChild(style)
+}
+
+/** The xterm terminal view. */
+export function TerminalTab({ api, presetAlias, requestId }: TerminalTabProps) {
+  const [hosts, setHosts] = useState<SshHostSummary[]>([])
+  const [alias, setAlias] = useState(presetAlias ?? '')
+  const [status, setStatus] = useState<TerminalStatus>({ kind: 'idle' })
+  const containerRef = useRef<HTMLDivElement | null>(null)
+  const termRef = useRef<Terminal | null>(null)
+  const fitRef = useRef<FitAddon | null>(null)
+  const connRef = useRef<TerminalConnection | null>(null)
+
+  useEffect(() => { ensureXtermCss() }, [])
+
+  // Fetch the host list on tab activation.
+  useEffect(() => {
+    let disposed = false
+    void (async () => {
+      try {
+        const list = await api.listHosts()
+        if (!disposed) setHosts(list)
+      } catch (cause) {
+        if (!disposed) setStatus({ kind: 'error', detail: errorMessage(cause) })
+      }
+    })()
+    return () => { disposed = true }
+  }, [api])
+
+  // A hosts-tab connect action preselects its alias here.
+  useEffect(() => {
+    if (presetAlias !== undefined) setAlias(presetAlias)
+  }, [presetAlias, requestId])
+
+  const teardown = (): void => {
+    const connection = connRef.current
+    connRef.current = null
+    if (connection !== null) {
+      connection.onReady = undefined
+      connection.onOutput = undefined
+      connection.onExit = undefined
+      connection.close()
+    }
+    termRef.current?.dispose()
+    termRef.current = null
+    fitRef.current = null
+  }
+
+  // Unmount cleanup (never touches state on an unmounting component).
+  useEffect(() => () => { teardown() }, [])
+
+  // Keep the terminal fitted to its container while connected.
+  useEffect(() => {
+    const onResize = (): void => {
+      const term = termRef.current
+      const fit = fitRef.current
+      if (term === null || fit === null) return
+      fit.fit()
+      connRef.current?.resize(term.cols, term.rows)
+    }
+    window.addEventListener('resize', onResize)
+    return () => { window.removeEventListener('resize', onResize) }
+  }, [])
+
+  const connect = (): void => {
+    const target = alias
+    const container = containerRef.current
+    if (target === '' || container === null) return
+    if (status.kind === 'connecting' || status.kind === 'connected') return
+    teardown()
+    setStatus({ kind: 'connecting' })
+    const term = new Terminal({
+      convertEol: false,
+      cursorBlink: true,
+      fontSize: 13,
+      fontFamily: 'Menlo, Consolas, "Liberation Mono", monospace',
+      theme: { background: '#0b0e14', foreground: '#d8dee9', cursor: '#a3b8d0' },
+    })
+    const fit = new FitAddon()
+    term.loadAddon(fit)
+    term.open(container)
+    fit.fit()
+    const connection = api.openTerminal(target, term.cols, term.rows)
+    termRef.current = term
+    fitRef.current = fit
+    connRef.current = connection
+    let settled = false
+    const dataSub = term.onData(data => { connection.send(data) })
+    connection.onReady = () => { setStatus({ kind: 'connected', alias: target }) }
+    connection.onOutput = data => { term.write(data) }
+    connection.onExit = (code, error) => {
+      if (settled) return
+      settled = true
+      dataSub.dispose()
+      term.options.disableStdin = true
+      connRef.current = null
+      // Keep the last output visible; input is now disabled.
+      setStatus({ kind: 'exited', alias: target, detail: error })
+    }
+  }
+
+  const disconnect = (): void => {
+    teardown()
+    setStatus({ kind: 'idle' })
+  }
+
+  const active = status.kind === 'connecting' || status.kind === 'connected'
+
+  return (
+    <div className={css.termBody}>
+      <div className={css.controls}>
+        <select className={css.input} value={alias} onChange={event => { setAlias(event.target.value) }}>
+          <option value="">{tt('terminal.selectHost')}</option>
+          {hosts.map(host => <option key={host.alias} value={host.alias}>{host.alias} ({host.host})</option>)}
+        </select>
+        <button type="button" className={css.primaryButton} disabled={alias === '' || active} onClick={connect}>{tt('terminal.connect')}</button>
+        <button type="button" className={css.ghostButton} disabled={!active} onClick={disconnect}>{tt('terminal.disconnect')}</button>
+      </div>
+      {status.kind === 'connecting' && <div className={css.banner} data-kind="info">{tt('terminal.connecting')}</div>}
+      {status.kind === 'connected' && <div className={css.banner} data-kind="ok">{tt('terminal.ready', { alias: status.alias })}</div>}
+      {status.kind === 'exited' && (
+        <div className={css.banner} data-kind="info">{tt('terminal.exited', { alias: status.alias })}{status.detail !== undefined ? ' (' + status.detail + ')' : ''}</div>
+      )}
+      {status.kind === 'error' && <div className={css.banner} data-kind="error">{tt('terminal.error', { error: status.detail })}</div>}
+      <div className={css.termWrap}>
+        <div ref={containerRef} className={css.termContainer} />
+        {status.kind === 'idle' && (
+          <div className={css.termPlaceholder}>{hosts.length === 0 ? tt('hosts.empty') : tt('terminal.placeholder')}</div>
+        )}
+      </div>
+    </div>
+  )
+}

package/src/client/ssh/panel/TransferTab.tsx

@@ -0,0 +1,232 @@
+/**
+ * Transfer tab: upload/download one file with progress, plus a toggleable
+ * remote directory browser (api.ls) whose file rows fill the remote path
+ * input and whose directory rows navigate.
+ */
+import { useEffect, useRef, useState, type ChangeEvent } from 'react'
+import type { SshApi } from '../api.ts'
+import type { RemoteDirEntry, SshHostSummary, TransferProgress } from '../../../ssh/protocol.ts'
+import { errorMessage, tt } from './helpers.ts'
+import css from './panel.module.css'
+
+/** Transfer tab props. */
+export interface TransferTabProps {
+  api: SshApi
+}
+
+/** One in-flight transfer (drives the progress bar). */
+interface TransferState {
+  kind: 'upload' | 'download'
+  phase: TransferProgress['phase']
+  percent: number
+  speedBps?: number
+  file: string
+}
+
+/** The last transfer's outcome line. */
+type TransferStatus = { kind: 'ok'; bytes: number } | { kind: 'error'; error: string }
+
+/** Join a directory path with a child entry name. */
+function joinRemotePath(dir: string, name: string): string {
+  const base = dir.endsWith('/') ? dir : dir + '/'
+  return base + name
+}
+
+/** Parent path of a remote directory ('/' stays '/'). */
+function parentOf(dir: string): string {
+  const trimmed = dir.replace(/\/+$/, '')
+  const index = trimmed.lastIndexOf('/')
+  if (index <= 0) return '/'
+  return trimmed.slice(0, index)
+}
+
+/** Human byte sizes through the transfer.* locale templates. */
+function formatBytes(bytes: number): string {
+  if (bytes < 1024) return tt('transfer.bytes', { value: bytes })
+  if (bytes < 1024 * 1024) return tt('transfer.kib', { value: (bytes / 1024).toFixed(1) })
+  if (bytes < 1024 * 1024 * 1024) return tt('transfer.mib', { value: (bytes / (1024 * 1024)).toFixed(1) })
+  return tt('transfer.gib', { value: (bytes / (1024 * 1024 * 1024)).toFixed(1) })
+}
+
+/** The upload/download tab. */
+export function TransferTab({ api }: TransferTabProps) {
+  const [hosts, setHosts] = useState<SshHostSummary[]>([])
+  const [listError, setListError] = useState<string | null>(null)
+  const [alias, setAlias] = useState('')
+  const [remotePath, setRemotePath] = useState('')
+  const [browseOpen, setBrowseOpen] = useState(false)
+  const [browseDir, setBrowseDir] = useState('/')
+  const [entries, setEntries] = useState<RemoteDirEntry[]>([])
+  const [browsing, setBrowsing] = useState(false)
+  const [transfer, setTransfer] = useState<TransferState | null>(null)
+  const [status, setStatus] = useState<TransferStatus | null>(null)
+  const fileRef = useRef<HTMLInputElement | null>(null)
+  const seqRef = useRef(0)
+
+  useEffect(() => {
+    let disposed = false
+    void (async () => {
+      try {
+        const list = await api.listHosts()
+        if (!disposed) setHosts(list)
+      } catch (cause) {
+        if (!disposed) setListError(errorMessage(cause))
+      }
+    })()
+    return () => { disposed = true }
+  }, [api])
+
+  const loadDir = async (path: string): Promise<void> => {
+    if (alias === '') return
+    const seq = ++seqRef.current
+    setBrowsing(true)
+    try {
+      const list = await api.ls(alias, path)
+      if (seq !== seqRef.current) return
+      const sorted = [...list].sort((a, b) => {
+        if (a.type !== b.type) return a.type === 'dir' ? -1 : 1
+        return a.name.localeCompare(b.name)
+      })
+      setEntries(sorted)
+      setBrowseDir(path)
+      setListError(null)
+    } catch (cause) {
+      if (seq === seqRef.current) setListError(errorMessage(cause))
+    } finally {
+      if (seq === seqRef.current) setBrowsing(false)
+    }
+  }
+
+  const openBrowse = (): void => {
+    if (alias === '') return
+    setBrowseOpen(true)
+    const path = remotePath.trim() === '' ? '/' : remotePath.trim()
+    void loadDir(path)
+  }
+
+  const handleFile = async (event: ChangeEvent<HTMLInputElement>): Promise<void> => {
+    const file = event.target.files?.[0]
+    event.target.value = ''
+    if (file === undefined || alias === '' || remotePath.trim() === '' || transfer !== null) return
+    setStatus(null)
+    setTransfer({ kind: 'upload', phase: 'connecting', percent: 0, file: file.name })
+    try {
+      const outcome = await api.uploadFile(file, alias, remotePath.trim(), progress => {
+        setTransfer(prev => prev === null ? prev : {
+          kind: 'upload',
+          phase: progress.phase,
+          percent: progress.percent,
+          speedBps: progress.speedBps,
+          file: progress.file,
+        })
+      })
+      setStatus({ kind: 'ok', bytes: outcome.transferredBytes })
+    } catch (cause) {
+      setStatus({ kind: 'error', error: errorMessage(cause) })
+    } finally {
+      setTransfer(null)
+    }
+  }
+
+  const handleDownload = async (): Promise<void> => {
+    if (alias === '' || remotePath.trim() === '' || transfer !== null) return
+    setStatus(null)
+    setTransfer({ kind: 'download', phase: 'connecting', percent: 0, file: remotePath.trim() })
+    try {
+      const result = await api.downloadFile(alias, remotePath.trim(), progress => {
+        setTransfer(prev => prev === null ? prev : {
+          kind: 'download',
+          phase: progress.phase,
+          percent: progress.percent,
+          speedBps: progress.speedBps,
+          file: progress.file,
+        })
+      })
+      // Streamed downloads (File System Access API) were already saved; the
+      // Blob fallback triggers a browser save here.
+      if (!result.streamed && result.blob !== undefined) {
+        const url = URL.createObjectURL(result.blob)
+        const anchor = document.createElement('a')
+        anchor.href = url
+        anchor.download = result.filename
+        document.body.appendChild(anchor)
+        anchor.click()
+        anchor.remove()
+        // Defer the revoke: some engines need the URL alive past the click.
+        setTimeout(() => { URL.revokeObjectURL(url) }, 10_000)
+      }
+      setStatus({ kind: 'ok', bytes: result.bytes })
+    } catch (cause) {
+      setStatus({ kind: 'error', error: errorMessage(cause) })
+    } finally {
+      setTransfer(null)
+    }
+  }
+
+  const ready = alias !== '' && remotePath.trim() !== '' && transfer === null
+
+  return (
+    <div className={css.tabBody}>
+      <div className={css.controls}>
+        <select className={css.input} value={alias} onChange={event => { setAlias(event.target.value) }}>
+          <option value="">{tt('transfer.selectHost')}</option>
+          {hosts.map(host => <option key={host.alias} value={host.alias}>{host.alias} ({host.host})</option>)}
+        </select>
+        <input className={css.input} placeholder={tt('transfer.remotePathHint')} value={remotePath} onChange={event => { setRemotePath(event.target.value) }} />
+        <button type="button" className={css.ghostButton} disabled={alias === ''} onClick={openBrowse}>{tt('transfer.browseRemote')}</button>
+        <div className={css.toolbarSpacer} />
+        <button type="button" className={css.primaryButton} disabled={!ready} onClick={() => { fileRef.current?.click() }}>{tt('transfer.upload')}</button>
+        <button type="button" className={css.ghostButton} disabled={!ready} onClick={() => { void handleDownload() }}>{tt('transfer.download')}</button>
+        <input ref={fileRef} type="file" className={css.hiddenFile} onChange={event => { void handleFile(event) }} />
+      </div>
+      {listError !== null && <div className={css.banner} data-kind="error">{tt('common.error', { error: listError })}</div>}
+      {browseOpen && (
+        <div className={css.browsePanel}>
+          <div className={css.browseHeader}>
+            <span className={css.browsePath}>{browseDir}</span>
+            <button type="button" className={css.linkButton} disabled={browsing} onClick={() => { void loadDir(browseDir) }}>{tt('transfer.refresh')}</button>
+          </div>
+          <div className={css.browseList}>
+            {browseDir !== '/' && (
+              <button type="button" className={css.dirRow} data-up onClick={() => { void loadDir(parentOf(browseDir)) }}>
+                <span className={css.dirName}>{tt('transfer.upLevel')}</span>
+                <span className={css.dirType} />
+                <span className={css.dirSize} />
+              </button>
+            )}
+            {entries.map(entry => (
+              <button key={entry.name} type="button" className={css.dirRow} data-type={entry.type} onClick={() => {
+                if (entry.type === 'dir') {
+                  void loadDir(joinRemotePath(browseDir, entry.name))
+                } else {
+                  setRemotePath(joinRemotePath(browseDir, entry.name))
+                }
+              }}>
+                <span className={css.dirName}>{entry.name}</span>
+                <span className={css.dirType}>{entry.type === 'dir' ? '[' + tt('transfer.dir') + ']' : entry.type === 'file' ? '[' + tt('transfer.file') + ']' : ''}</span>
+                <span className={css.dirSize}>{formatBytes(entry.size)}</span>
+              </button>
+            ))}
+          </div>
+        </div>
+      )}
+      {transfer !== null && (
+        <div className={css.transferBlock}>
+          <div className={css.progressMeta}>
+            <span>{transfer.kind === 'upload' ? tt('transfer.uploading', { file: transfer.file }) : tt('transfer.downloading')}</span>
+            <span>{tt('transfer.percent', { value: Math.round(transfer.percent) })}</span>
+            {transfer.speedBps !== undefined && transfer.phase === 'transferring' && <span>{tt('transfer.speed', { value: formatBytes(transfer.speedBps) })}</span>}
+          </div>
+          <div className={css.progressTrack}>
+            <div className={css.progressBar} style={{ width: Math.min(100, Math.max(0, transfer.percent)) + '%' }} />
+          </div>
+        </div>
+      )}
+      {status !== null && (
+        <div className={css.banner} data-kind={status.kind}>
+          {status.kind === 'ok' ? tt('transfer.done', { bytes: status.bytes }) : tt('transfer.failed', { error: status.error })}
+        </div>
+      )}
+    </div>
+  )
+}

package/src/client/ssh/panel/TunnelsTab.tsx

@@ -0,0 +1,177 @@
+/**
+ * Tunnels tab: the live local port-forward list (auto-refresh every 5s while
+ * mounted) with per-row stop, a stop-all action scoped to the selected alias,
+ * and a new-tunnel form.
+ */
+import { useEffect, useRef, useState } from 'react'
+import type { SshApi } from '../api.ts'
+import type { SshHostSummary, TunnelInfo } from '../../../ssh/protocol.ts'
+import { errorMessage, tt } from './helpers.ts'
+import css from './panel.module.css'
+
+/** Tunnels tab props. */
+export interface TunnelsTabProps {
+  api: SshApi
+}
+
+/** The tunnels tab. */
+export function TunnelsTab({ api }: TunnelsTabProps) {
+  const [hosts, setHosts] = useState<SshHostSummary[]>([])
+  const [tunnels, setTunnels] = useState<TunnelInfo[] | null>(null)
+  const [error, setError] = useState<string | null>(null)
+  const [notice, setNotice] = useState<string | null>(null)
+  const [alias, setAlias] = useState('')
+  const [remotePort, setRemotePort] = useState('')
+  const [remoteHost, setRemoteHost] = useState('')
+  const [localPort, setLocalPort] = useState('')
+  const [busy, setBusy] = useState(false)
+
+  // Hosts for the new-tunnel form (failure does not block tunnel listing).
+  useEffect(() => {
+    let disposed = false
+    void (async () => {
+      try {
+        const list = await api.listHosts()
+        if (!disposed) setHosts(list)
+      } catch {
+        // Tunnels may still exist; keep the list usable.
+      }
+    })()
+    return () => { disposed = true }
+  }, [api])
+
+  // Live list with a 5s heartbeat while mounted. Every load carries a
+  // sequence number so stale responses never overwrite newer state.
+  const seqRef = useRef(0)
+  useEffect(() => {
+    const load = async (): Promise<void> => {
+      const seq = ++seqRef.current
+      try {
+        const list = await api.listTunnels()
+        if (seq !== seqRef.current) return
+        setTunnels(list)
+        setError(null)
+      } catch (cause) {
+        if (seq !== seqRef.current) return
+        setError(errorMessage(cause))
+      }
+    }
+    void load()
+    const timer = setInterval(() => { void load() }, 5000)
+    return () => { clearInterval(timer) }
+  }, [api])
+
+  const refresh = async (): Promise<void> => {
+    const seq = ++seqRef.current
+    try {
+      const list = await api.listTunnels()
+      if (seq !== seqRef.current) return
+      setTunnels(list)
+      setError(null)
+    } catch (cause) {
+      if (seq !== seqRef.current) return
+      setError(errorMessage(cause))
+    }
+  }
+
+  const stopTunnel = async (tunnelId: string): Promise<void> => {
+    try {
+      await api.stopTunnel(tunnelId)
+      await refresh()
+    } catch (cause) {
+      setError(errorMessage(cause))
+    }
+  }
+
+  const stopAll = async (): Promise<void> => {
+    if (!window.confirm(tt('tunnel.stopAllConfirm'))) return
+    setBusy(true)
+    try {
+      await api.stopAllTunnels(alias === '' ? undefined : alias)
+      await refresh()
+    } catch (cause) {
+      setError(errorMessage(cause))
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  const start = async (): Promise<void> => {
+    if (alias === '' || remotePort.trim() === '') return
+    const remotePortNumber = Number(remotePort)
+    const localPortNumber = localPort.trim() === '' ? undefined : Number(localPort)
+    if (!Number.isInteger(remotePortNumber) || remotePortNumber < 1 || remotePortNumber > 65535) {
+      setError(tt('form.portInvalid'))
+      return
+    }
+    if (localPortNumber !== undefined && (!Number.isInteger(localPortNumber) || localPortNumber < 1 || localPortNumber > 65535)) {
+      setError(tt('form.portInvalid'))
+      return
+    }
+    setBusy(true)
+    setNotice(null)
+    try {
+      const tunnel = await api.startTunnel({
+        alias,
+        remotePort: remotePortNumber,
+        remoteHost: remoteHost.trim() === '' ? undefined : remoteHost.trim(),
+        localPort: localPortNumber,
+      })
+      setNotice(tt('tunnel.started', { localPort: tunnel.localPort }))
+      setRemotePort('')
+      setRemoteHost('')
+      setLocalPort('')
+      await refresh()
+    } catch (cause) {
+      setError(tt('tunnel.failed', { error: errorMessage(cause) }))
+    } finally {
+      setBusy(false)
+    }
+  }
+
+  return (
+    <div className={css.tabBody}>
+      <div className={css.controls}>
+        <button type="button" className={css.ghostButton} disabled={busy} onClick={() => { void stopAll() }}>{tt('tunnel.stopAll')}</button>
+        <button type="button" className={css.ghostButton} onClick={() => { void refresh() }}>{tt('common.refresh')}</button>
+      </div>
+      {error !== null && <div className={css.banner} data-kind="error">{error}</div>}
+      {notice !== null && <div className={css.banner} data-kind="ok">{notice}</div>}
+      {tunnels !== null && tunnels.length === 0 && <div className={css.empty}>{tt('tunnel.empty')}</div>}
+      <div className={css.tunnelList}>
+        {(tunnels ?? []).map(tunnel => (
+          <div key={tunnel.id} className={css.tunnelRow} data-state={tunnel.state}>
+            <span className={css.tunnelLabel}>{tt('tunnel.row', { alias: tunnel.alias, localPort: tunnel.localPort, remoteHost: tunnel.remoteHost, remotePort: tunnel.remotePort })}</span>
+            <button type="button" className={css.ghostButton} onClick={() => { void stopTunnel(tunnel.id) }}>{tt('tunnel.stop')}</button>
+          </div>
+        ))}
+      </div>
+      <div className={css.formCard}>
+        <div className={css.formRow}>
+          <label className={css.field}>
+            <span className={css.fieldLabel}>{tt('tunnel.alias')}</span>
+            <select className={css.input} value={alias} onChange={event => { setAlias(event.target.value) }}>
+              <option value="">{tt('terminal.selectHost')}</option>
+              {hosts.map(host => <option key={host.alias} value={host.alias}>{host.alias}</option>)}
+            </select>
+          </label>
+          <label className={css.field}>
+            <span className={css.fieldLabel}>{tt('tunnel.remotePort')}</span>
+            <input className={css.input} type="number" min={1} max={65535} value={remotePort} onChange={event => { setRemotePort(event.target.value) }} />
+          </label>
+          <label className={css.field}>
+            <span className={css.fieldLabel}>{tt('tunnel.remoteHost')}</span>
+            <input className={css.input} value={remoteHost} placeholder={tt('tunnel.remoteHostHint')} onChange={event => { setRemoteHost(event.target.value) }} />
+          </label>
+          <label className={css.field}>
+            <span className={css.fieldLabel}>{tt('tunnel.localPort')}</span>
+            <input className={css.input} type="number" min={1} max={65535} value={localPort} placeholder={tt('tunnel.localPortHint')} onChange={event => { setLocalPort(event.target.value) }} />
+          </label>
+        </div>
+        <div>
+          <button type="button" className={css.primaryButton} disabled={busy || alias === '' || remotePort.trim() === ''} onClick={() => { void start() }}>{tt('tunnel.start')}</button>
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/client/ssh/panel/controller.ts

@@ -0,0 +1,48 @@
+/**
+ * SSH panel controller: the single owner of the panel's open/closed state.
+ *
+ * Framework-free (structural runtime faces, task-board core/controller.ts
+ * style) so the DOM mounts and the React panel share one tiny subscription
+ * surface. The state lives only for the browser session (no persistence).
+ */
+
+/** Immutable controller snapshot for UI subscriptions. */
+export interface PanelControllerSnapshot {
+  panelOpen: boolean
+}
+
+/** The panel state owner the sidebar entry toggles and the view renders from. */
+export class PanelController {
+  private panelOpen = false
+  private listeners = new Set<() => void>()
+
+  getSnapshot(): PanelControllerSnapshot {
+    return { panelOpen: this.panelOpen }
+  }
+
+  subscribe(fn: () => void): () => void {
+    this.listeners.add(fn)
+    return () => { this.listeners.delete(fn) }
+  }
+
+  open(): void {
+    if (this.panelOpen) return
+    this.panelOpen = true
+    this.notify()
+  }
+
+  close(): void {
+    if (!this.panelOpen) return
+    this.panelOpen = false
+    this.notify()
+  }
+
+  toggle(): void {
+    if (this.panelOpen) this.close()
+    else this.open()
+  }
+
+  private notify(): void {
+    for (const fn of [...this.listeners]) fn()
+  }
+}

package/src/client/ssh/panel/helpers.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared panel helpers: the active-dictionary pick (document-language based,
+ * task-board precedent) bound to the dsh-ssh interpolator in locales.ts, plus
+ * a small error-message extractor. All copy stays in the locale dictionaries.
+ */
+import { en, t, zh, type SshKey } from '../locales.ts'
+
+/** Template values accepted by the interpolator. */
+export type TranslateValues = Record<string, string | number>
+
+/** Active dictionary, picked by the document language at call time. */
+export function dictionary(): Record<string, string> {
+  const lang = typeof document !== 'undefined' ? document.documentElement.lang : 'zh'
+  return lang.toLowerCase().startsWith('en') ? { ...en } : { ...zh }
+}
+
+/** Translate a key with optional {name} template params (current language). */
+export function tt(key: SshKey, values?: TranslateValues): string {
+  return t(dictionary(), key, values)
+}
+
+/** Human-readable error text from an unknown thrown value. */
+export function errorMessage(error: unknown): string {
+  if (error instanceof Error) return error.message
+  return String(error)
+}