@linxin666/dsh-ssh 0.4.1 → 0.4.3

package/src/client/index.ts

@@ -21,12 +21,11 @@ import type {} from '@deepseek-ai/dsh-client-ui-renderer/client'
 import type {} from '@deepseek-ai/dsh-client-ui-slots'
 import { SshApi } from './api.ts'
 import { en, zh, type SshKey } from './locales.ts'
-import { mountPanel } from './mount.tsx'
-import { PanelController } from './panel/controller.ts'
+import { registerSshPanel } from './native-panel.tsx'
+import { PanelController, SSH_PANEL_ID } from './panel/controller.ts'
 import type { TerminalFontSource } from './panel/helpers.ts'
 import { setRuntimeTranslate } from './panel/helpers.ts'
 import { bindSettingsReader } from './settings-binding.ts'
-import { mountSidebarEntry } from './sidebar-entry.ts'
 import { reportDailyHeartbeat } from './telemetry.ts'
 
 /** Locale namespace this plugin owns. */
@@ -90,7 +89,20 @@ export function apply(ctx: ClientContext): void {
   // follow the Language setting without a reload.
   try { setRuntimeTranslate(ctx.locale.bind(NS)) } catch { /* locale missing: document-language fallback stays */ }
 
-  const controller = new PanelController()
+  // Panel navigation belongs to the layout service: the panel asks it to
+  // select its own panel id (or the conversation) instead of taking over the
+  // center column at the DOM level. The lookup stays lazy so a selection
+  // issued before the service settles still lands once it does, and the face
+  // throws by contract before the layout root entry mounts, which the
+  // controller tolerates.
+  const controller = new PanelController({
+    panel: {
+      select: panelId => {
+        const layout = ctx.get('layout') as { selectPanel?: (id: string | null) => void } | undefined
+        layout?.selectPanel?.(panelId)
+      },
+    },
+  })
   const api = new SshApi()
   // Live terminal-font preference (issue #577): the field lives in this
   // plugin's own profile entry, whose settings page the Host generates from
@@ -107,11 +119,21 @@ export function apply(ctx: ClientContext): void {
   ctx.effect(() => () => { settings.dispose() }, 'dsh-ssh: settings binding')
   const disposers: Array<() => void> = []
   try {
-    disposers.push(mountSidebarEntry(controller, ctx.locale))
-    disposers.push(mountPanel(controller, api, terminalFont, ctx.locale))
+    disposers.push(registerSshPanel(ctx, controller, api, terminalFont))
+    // The layout's panel selection is reconciled back into the controller, so
+    // the panel follows the user clicking another panel row.
+    const layoutFace = ctx.get('layout') as { panelInfo?: { subscribe(listener: () => void): () => void; getSnapshot(): { activePanelId: unknown } } } | undefined
+    if (layoutFace?.panelInfo !== undefined) {
+      const sync = (): void => {
+        const active = layoutFace.panelInfo!.getSnapshot().activePanelId
+        controller.syncPanelSelection(active === SSH_PANEL_ID ? SSH_PANEL_ID : null)
+      }
+      sync()
+      disposers.push(layoutFace.panelInfo.subscribe(sync))
+    }
   } catch (error) {
-    // DOM failures degrade the panel, never the GUI.
-    console.warn('[dsh-ssh] mount failed:', error)
+    // Registration failures degrade the panel, never the GUI.
+    console.warn('[dsh-ssh] panel registration failed:', error)
   }
   ctx.effect(() => () => {
     for (const dispose of disposers.splice(0)) dispose()

package/src/client/native-panel.tsx

@@ -0,0 +1,141 @@
+/**
+ * Native panel registration for the SSH panel.
+ *
+ * The panel is an official-style center-column page, not a DOM takeover: it
+ * contributes a row into the sidebar shell's own global panel list
+ * (`sidebar.panellist`) and its page into the layout's keyed `main` slot. The
+ * shell then owns the row box, the label, the active highlight, the collapsed
+ * rail and the panel switch, exactly as it does for the shipped Plugins and
+ * Schedule pages and for the task board and the skill center.
+ *
+ * Both registrations go through `ctx.slots.inject`, which fires only once the
+ * owning shell entry has declared the seat: load order between this plugin and
+ * ui-layout / ui-sidebar therefore does not matter, and neither does a shell
+ * that cannot serve the seats (the callback simply never runs).
+ *
+ * The terminal's PTY shell lives on the host and outlives this page (see
+ * engine/terminal-sessions.ts), so the layout unmounting a deselected page
+ * costs the view its xterm instance, not the remote session: the terminal tab
+ * reattaches by session id when the page mounts again.
+ *
+ * @module @linxin666/dsh-client-ssh/client
+ */
+import type { Context as ClientContext } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-client-ui-slots'
+import type {} from '@deepseek-ai/dsh-client-ui-layout/client'
+import type {} from '@deepseek-ai/dsh-client-ui-sidebar/client'
+import type { SshApi } from './api.ts'
+import { SSH_PANEL_ID, type PanelController } from './panel/controller.ts'
+import { tt, type TerminalFontSource } from './panel/helpers.ts'
+import { SshPanel } from './panel/SshPanel.tsx'
+import css from './panel/panel.module.css'
+
+/** The panel id shared by the sidebar row and the main-slot occupant. */
+export { SSH_PANEL_ID }
+
+/** Row order among the shell's global panel rows (Plugins 0, Schedule 10, board 20, skill center 30). */
+const PANEL_ORDER = 40
+
+/**
+ * The sidebar row glyph the shell asks for at its own size and active state.
+ * The shell owns the button, label, tooltip and rail geometry; this component
+ * draws only the glyph, like every other panel row.
+ *
+ * The glyph carries `data-dsh-panel-entry` because it is the only DOM this
+ * panel's own code owns inside that shell-owned row: the L2 contract (skins)
+ * resolves which row belongs to which plugin through it, since the shell
+ * stamps no per-entry hook of its own (see contracts/semantic-attrs-v1.md).
+ * @param props - the shell's icon share: square edge and selection state.
+ * @returns the decorative terminal glyph.
+ */
+export function SshPanelIcon({ size }: { size: number; active: boolean }): React.ReactElement {
+  return (
+    <svg
+      data-dsh-panel-entry={SSH_PANEL_ID}
+      viewBox="0 0 16 16"
+      width={size}
+      height={size}
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="1.5"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden="true"
+    >
+      <rect x="1.75" y="2.25" width="12.5" height="11.5" rx="1.75" />
+      <path d="M4.25 5.25l2.75 2.75-2.75 2.75" />
+      <path d="M8.5 10.75h3.25" />
+    </svg>
+  )
+}
+
+/**
+ * The main-slot page. The layout mounts it only while this panel is selected;
+ * the wrapper carries the pinned `data-dsh-ssh-view` semantic anchor (L2
+ * contract, skins) the takeover container used to own.
+ * @param props - the framework main-slot share plus this entry's injected face.
+ * @returns the SSH panel page.
+ */
+export function SshPanelPage({ controller, api, terminalFont }: {
+  controller: PanelController
+  api: SshApi
+  terminalFont?: TerminalFontSource
+}): React.ReactElement {
+  return (
+    <div className={css.view} data-dsh-ssh-view="" data-dsh-plugin="ssh">
+      <SshPanel controller={controller} api={api} terminalFont={terminalFont} />
+    </div>
+  )
+}
+
+/** The injected face both registrations receive. */
+interface PanelFace {
+  controller: PanelController
+  api: SshApi
+  terminalFont?: TerminalFontSource
+}
+
+/**
+ * Register the SSH panel's sidebar row and center-column page.
+ *
+ * Both seats are declared by shell plugins this package does not depend on at
+ * runtime, so each registration is wrapped in `ctx.slots.inject`: the callback
+ * runs only after the owning entry declares the seat, and a shell that never
+ * declares it leaves the panel simply absent instead of failing boot.
+ * @param ctx - client root context (services: slots).
+ * @param controller - the controller the page and the row drive.
+ * @param api - the SSH API client the page operates through.
+ * @param terminalFont - live terminal-font setting source (issue #577).
+ * @returns disposer releasing both registrations.
+ */
+export function registerSshPanel(
+  ctx: ClientContext,
+  controller: PanelController,
+  api: SshApi,
+  terminalFont?: TerminalFontSource,
+): () => void {
+  const slots = ctx.slots as {
+    inject(key: string, callback: () => () => void): () => void
+    register(options: Record<string, unknown>, component: unknown): () => void
+  }
+  const disposers: Array<() => void> = []
+
+  disposers.push(slots.inject('sidebar.panellist', () => slots.register({
+    name: 'sidebar.panellist',
+    id: SSH_PANEL_ID,
+    order: PANEL_ORDER,
+    // The shell resolves this through resolveSlotLabel on every locale change,
+    // so the module-level translate reads the active language at call time.
+    label: () => tt('entry.label'),
+  }, SshPanelIcon)))
+
+  disposers.push(slots.inject('main', () => slots.register({
+    name: 'main',
+    key: SSH_PANEL_ID,
+    inject: (): PanelFace => ({ controller, api, terminalFont }),
+  }, SshPanelPage as never)))
+
+  return () => {
+    for (const dispose of disposers.splice(0)) dispose()
+  }
+}

package/src/client/panel/SshPanel.tsx

@@ -1,13 +1,17 @@
 /**
  * The SSH operations panel shell: a header with a close control, a five-tab
- * bar, and the active tab's content. Tab state lives here (browser session
- * state); inactive tabs unmount, so each tab fetches its own data on
- * activation. The hosts tab's connect action switches here to the terminal
- * tab with the chosen alias preselected.
+ * bar, and the active tab's content.
+ *
+ * The active tab, the pending connect request and the live terminal session id
+ * live in the controller, not in component state: the layout mounts this page
+ * only while the panel is selected, so local state would reset the tab on
+ * every panel switch and lose the id the terminal tab needs to reattach its
+ * host-side session. Inactive tabs unmount, so each tab fetches its own data
+ * on activation.
  */
-import { useCallback, useState, useSyncExternalStore } from 'react'
+import { useCallback, useSyncExternalStore } from 'react'
 import type { SshApi } from '../api.ts'
-import type { PanelController } from './controller.ts'
+import type { PanelController, SshTab } from './controller.ts'
 import { tt, type TerminalFontSource } from './helpers.ts'
 import { ClusterTab } from './ClusterTab.tsx'
 import { HostsTab } from './HostsTab.tsx'
@@ -16,12 +20,9 @@ import { TransferTab } from './TransferTab.tsx'
 import { TunnelsTab } from './TunnelsTab.tsx'
 import css from './panel.module.css'
 
-/** The panel's tab identifiers. */
-export type SshTab = 'hosts' | 'terminal' | 'transfer' | 'tunnels' | 'cluster'
-
 /** Panel shell props. */
 export interface SshPanelProps {
-  /** The panel state owner (open/close/toggle). */
+  /** The panel state owner (open/close/toggle, active tab, terminal session). */
   controller: PanelController
   /** The SSH API client every tab operates through. */
   api: SshApi
@@ -38,25 +39,12 @@ const TABS: ReadonlyArray<{ id: SshTab; label: () => string }> = [
   { id: 'cluster', label: () => tt('tab.cluster') },
 ]
 
-/** A pending "connect this host" request handed to the terminal tab. */
-interface ConnectRequest {
-  alias: string
-  nonce: number
-}
-
 /** The tabbed SSH panel. */
 export function SshPanel({ controller, api, terminalFont }: SshPanelProps) {
-  const panelOpen = useSyncExternalStore(
+  const { panelOpen, activeTab, connectRequest, terminalSessionId } = useSyncExternalStore(
     useCallback(listener => controller.subscribe(listener), [controller]),
-    useCallback(() => controller.getSnapshot().panelOpen, [controller]),
+    useCallback(() => controller.getSnapshot(), [controller]),
   )
-  const [activeTab, setActiveTab] = useState<SshTab>('hosts')
-  const [connectRequest, setConnectRequest] = useState<ConnectRequest | null>(null)
-
-  const handleConnect = (alias: string): void => {
-    setActiveTab('terminal')
-    setConnectRequest(prev => ({ alias, nonce: (prev?.nonce ?? 0) + 1 }))
-  }
 
   return (
     <div className={css.panel} data-dsh-plugin="ssh">
@@ -76,14 +64,23 @@ export function SshPanel({ controller, api, terminalFont }: SshPanelProps) {
       </div>
       <div className={css.tabBar} role="tablist" data-dsh-part="tab-bar">
         {TABS.map(tab => (
-          <button key={tab.id} type="button" role="tab" aria-selected={activeTab === tab.id} data-active={activeTab === tab.id ? '' : undefined} data-dsh-part="tab" className={css.tab} onClick={() => { setActiveTab(tab.id) }}>
+          <button key={tab.id} type="button" role="tab" aria-selected={activeTab === tab.id} data-active={activeTab === tab.id ? '' : undefined} data-dsh-part="tab" className={css.tab} onClick={() => { controller.setActiveTab(tab.id) }}>
             {tab.label()}
           </button>
         ))}
       </div>
       <div className={css.panelContent}>
-        {activeTab === 'hosts' && <HostsTab api={api} onConnect={handleConnect} />}
-        {activeTab === 'terminal' && <TerminalTab api={api} presetAlias={connectRequest?.alias} requestId={connectRequest?.nonce} terminalFont={terminalFont} />}
+        {activeTab === 'hosts' && <HostsTab api={api} onConnect={alias => { controller.requestConnect(alias) }} />}
+        {activeTab === 'terminal' && (
+          <TerminalTab
+            api={api}
+            controller={controller}
+            presetAlias={connectRequest?.alias}
+            requestId={connectRequest?.nonce}
+            sessionId={terminalSessionId}
+            terminalFont={terminalFont}
+          />
+        )}
         {activeTab === 'transfer' && <TransferTab api={api} />}
         {activeTab === 'tunnels' && <TunnelsTab api={api} active={panelOpen} />}
         {activeTab === 'cluster' && <ClusterTab api={api} />}

package/src/client/panel/TerminalTab.tsx

@@ -10,6 +10,7 @@ import { Terminal, type IDisposable } from '@xterm/xterm'
 import { FitAddon } from '@xterm/addon-fit'
 import type { SshApi, TerminalConnection } from '../api.ts'
 import type { SshHostSummary } from '../../protocol.ts'
+import type { PanelController } from './controller.ts'
 import { XTERM_CSS } from './xterm.css.ts'
 import { errorMessage, resolveTerminalFontFamily, tt, type TerminalFontSource } from './helpers.ts'
 import css from './panel.module.css'
@@ -17,6 +18,10 @@ import css from './panel.module.css'
 /** Terminal tab props. */
 export interface TerminalTabProps {
   api: SshApi
+  /** The panel controller that owns the live host session id across mounts. */
+  controller: PanelController
+  /** Host session to reattach to on mount (survives a panel switch). */
+  sessionId?: string
   /** Alias preselected by a "connect" action from the hosts tab. */
   presetAlias?: string
   /** Monotonic id of the connect request (re-applies presetAlias). */
@@ -63,7 +68,7 @@ const NO_FONT_SOURCE: TerminalFontSource = {
 }
 
 /** The xterm terminal view. */
-export function TerminalTab({ api, presetAlias, requestId, terminalFont }: TerminalTabProps) {
+export function TerminalTab({ api, controller, sessionId, presetAlias, requestId, terminalFont }: TerminalTabProps) {
   const [hosts, setHosts] = useState<SshHostSummary[]>([])
   const [alias, setAlias] = useState(presetAlias ?? '')
   const [status, setStatus] = useState<TerminalStatus>({ kind: 'idle' })
@@ -111,7 +116,12 @@ export function TerminalTab({ api, presetAlias, requestId, terminalFont }: Termi
     if (presetAlias !== undefined) setAlias(presetAlias)
   }, [presetAlias, requestId])
 
-  const teardown = (): void => {
+  /**
+   * Tear the view down.
+   * @param leave - `detach` leaves the host session alive for a reattach
+   *   (panel switch, unmount); `close` ends it (the disconnect control).
+   */
+  const teardown = (leave: 'detach' | 'close'): void => {
     setAuthPrompt(undefined)
     setAuthInputs([])
     const connection = connRef.current
@@ -121,7 +131,8 @@ export function TerminalTab({ api, presetAlias, requestId, terminalFont }: Termi
       connection.onOutput = undefined
       connection.onExit = undefined
       connection.onAuthPrompt = undefined
-      connection.close()
+      if (leave === 'detach') connection.detach()
+      else connection.close()
     }
     // Release the xterm input subscription explicitly and dispose the
     // terminal so no listener (or the terminal Renderer) survives a
@@ -133,8 +144,9 @@ export function TerminalTab({ api, presetAlias, requestId, terminalFont }: Termi
     fitRef.current = null
   }
 
-  // Unmount cleanup (never touches state on an unmounting component).
-  useEffect(() => () => { teardown() }, [])
+  // Unmount cleanup (never touches state on an unmounting component). The
+  // host keeps the shell alive, so returning to this tab reattaches to it.
+  useEffect(() => () => { teardown('detach') }, [])
 
   // Keep the terminal fitted to its container. A window resize is only one
   // trigger: the status banner appearing after connect, panel resizes, and
@@ -170,12 +182,15 @@ export function TerminalTab({ api, presetAlias, requestId, terminalFont }: Termi
     }
   }, [])
 
-  const connect = (): void => {
-    const target = alias
+  /**
+   * Build the xterm view and bind one connection to it.
+   * @param open - opens the transport once the terminal has a size.
+   */
+  const startSession = (open: (cols: number, rows: number) => TerminalConnection): void => {
     const container = containerRef.current
-    if (target === '' || container === null) return
+    if (container === null) return
     if (status.kind === 'connecting' || status.kind === 'connected') return
-    teardown()
+    teardown('detach')
     setStatus({ kind: 'connecting' })
     const term = new Terminal({
       convertEol: false,
@@ -188,20 +203,25 @@ export function TerminalTab({ api, presetAlias, requestId, terminalFont }: Termi
     term.loadAddon(fit)
     term.open(container)
     fit.fit()
-    const connection = api.openTerminal(target, term.cols, term.rows)
+    const connection = open(term.cols, term.rows)
     termRef.current = term
     fitRef.current = fit
     connRef.current = connection
     let settled = false
+    let connectedAlias = ''
     dataSubRef.current = term.onData(data => { connection.send(data) })
     connection.onAuthPrompt = (name, instructions, prompts) => {
       setAuthPrompt({ name, instructions, prompts })
       setAuthInputs(prompts.map(() => ''))
     }
-    connection.onReady = () => {
+    connection.onReady = (id, readyAlias) => {
+      // Remember the host session so a later mount of this tab reattaches to
+      // the same shell instead of opening a second one.
+      connectedAlias = readyAlias
+      controller.setTerminalSession(id)
       setAuthPrompt(undefined)
       setAuthInputs([])
-      setStatus({ kind: 'connected', alias: target })
+      setStatus({ kind: 'connected', alias: readyAlias })
     }
     connection.onOutput = data => { term.write(data) }
     connection.onExit = (_code, error) => {
@@ -213,13 +233,33 @@ export function TerminalTab({ api, presetAlias, requestId, terminalFont }: Termi
       dataSubRef.current = null
       term.options.disableStdin = true
       connRef.current = null
+      // The session is gone: drop the id so the next mount starts fresh.
+      controller.clearTerminalSession()
       // Keep the last output visible; input is now disabled.
-      setStatus({ kind: 'exited', alias: target, detail: error })
+      setStatus({ kind: 'exited', alias: connectedAlias !== '' ? connectedAlias : alias, detail: error })
     }
   }
 
+  const connect = (): void => {
+    const target = alias
+    if (target === '') return
+    startSession((cols, rows) => api.openTerminal(target, cols, rows))
+  }
+
+  // Reattach to a host session that outlived this view (panel switch or a
+  // remount of the page). The host replays its scrollback before ready, so
+  // the terminal comes back with its history instead of a blank screen.
+  const reattachedRef = useRef<string | undefined>(undefined)
+  useEffect(() => {
+    if (sessionId === undefined || connRef.current !== null) return
+    if (reattachedRef.current === sessionId) return
+    reattachedRef.current = sessionId
+    startSession((cols, rows) => api.attachTerminal(sessionId, cols, rows))
+  }, [sessionId])
+
   const disconnect = (): void => {
-    teardown()
+    teardown('close')
+    controller.clearTerminalSession()
     setStatus({ kind: 'idle' })
   }
 

package/src/client/panel/controller.ts

@@ -1,23 +1,77 @@
 /**
- * SSH panel controller: the single owner of the panel's open/closed state.
+ * SSH panel controller: the single owner of the panel's view state.
  *
  * Framework-free (structural runtime faces, task-board core/controller.ts
- * style) so the DOM mounts and the React panel share one tiny subscription
+ * style) so the sidebar row and the React panel share one tiny subscription
  * surface. The state lives only for the browser session (no persistence).
+ *
+ * The active tab, the hosts-tab connect request and the live terminal session
+ * id live here rather than inside the panel components: the layout mounts a
+ * keyed page only while its panel is selected, so component-local state would
+ * reset the tab on every panel switch and lose the id a reattach needs.
  */
 
+/** The panel's tab identifiers. */
+export type SshTab = 'hosts' | 'terminal' | 'transfer' | 'tunnels' | 'cluster'
+
+/** A "connect" action from the hosts tab, handed to the terminal tab. */
+export interface ConnectRequest {
+  alias: string
+  /** Monotonic id so a repeated connect for the same alias still re-applies. */
+  nonce: number
+}
+
+/** Stable id shared by the sidebar panel row and the main-slot page. */
+export const SSH_PANEL_ID = 'ssh'
+
 /** Immutable controller snapshot for UI subscriptions. */
 export interface PanelControllerSnapshot {
+  /** Whether the center column shows this panel. */
   panelOpen: boolean
+  /** The tab the panel is showing. */
+  activeTab: SshTab
+  /** Pending hosts-tab connect request, or null. */
+  connectRequest: ConnectRequest | null
+  /** Host-side terminal session the terminal tab should reattach to, if any. */
+  terminalSessionId: string | undefined
 }
 
-/** The panel state owner the sidebar entry toggles and the view renders from. */
+/**
+ * The layout's panel-navigation face: selecting the panel is the layout's
+ * business, and this is the one call that asks for it (null returns the column
+ * to the conversation). Optional, so a shell-less composition keeps the pure
+ * state transitions testable.
+ */
+export interface PanelNavigationFace {
+  /** Select this panel, or null to hand the column back to the conversation. */
+  select(panelId: string | null): void
+}
+
+/** Controller dependencies. */
+export interface PanelControllerDeps {
+  /** Layout panel selection; absent keeps the controller state-only. */
+  panel?: PanelNavigationFace
+}
+
+/** The panel state owner the sidebar row and the view both read. */
 export class PanelController {
   private panelOpen = false
+  private activeTab: SshTab = 'hosts'
+  private connectRequest: ConnectRequest | null = null
+  private terminalSessionId: string | undefined
   private listeners = new Set<() => void>()
+  /** Cached so getSnapshot is referentially stable between changes. */
+  private snapshot: PanelControllerSnapshot = {
+    panelOpen: false,
+    activeTab: 'hosts',
+    connectRequest: null,
+    terminalSessionId: undefined,
+  }
+
+  constructor(private readonly deps: PanelControllerDeps = {}) {}
 
   getSnapshot(): PanelControllerSnapshot {
-    return { panelOpen: this.panelOpen }
+    return this.snapshot
   }
 
   subscribe(fn: () => void): () => void {
@@ -25,16 +79,25 @@ export class PanelController {
     return () => { this.listeners.delete(fn) }
   }
 
+  /**
+   * Show the panel. The layout owns which panel the column renders, so the
+   * state flip and the selection travel together; the selection is requested
+   * after the snapshot flips, so a subscriber never observes "open" while the
+   * shell still shows the conversation.
+   */
   open(): void {
     if (this.panelOpen) return
     this.panelOpen = true
-    this.notify()
+    this.commit()
+    this.selectPanel(SSH_PANEL_ID)
   }
 
+  /** Return the column to the conversation, asking the layout explicitly. */
   close(): void {
     if (!this.panelOpen) return
     this.panelOpen = false
-    this.notify()
+    this.commit()
+    this.selectPanel(null)
   }
 
   toggle(): void {
@@ -42,7 +105,63 @@ export class PanelController {
     else this.open()
   }
 
-  private notify(): void {
+  /**
+   * Reflect a selection made outside this controller (the user clicked another
+   * sidebar row, or the layout dropped the panel id).
+   * @param panelId - the layout's current panel id, or null for the conversation.
+   */
+  syncPanelSelection(panelId: string | null): void {
+    const open = panelId === SSH_PANEL_ID
+    if (open === this.panelOpen) return
+    this.panelOpen = open
+    this.commit()
+  }
+
+  /** Switch tabs, keeping every other piece of view state. */
+  setActiveTab(tab: SshTab): void {
+    if (this.activeTab === tab) return
+    this.activeTab = tab
+    this.commit()
+  }
+
+  /** Hand the terminal tab a host to connect to (hosts-tab "connect" action). */
+  requestConnect(alias: string): void {
+    this.connectRequest = { alias, nonce: Date.now() }
+    this.activeTab = 'terminal'
+    this.commit()
+  }
+
+  /** Record the host-side session so a later page mount can reattach. */
+  setTerminalSession(sessionId: string): void {
+    if (this.terminalSessionId === sessionId) return
+    this.terminalSessionId = sessionId
+    this.commit()
+  }
+
+  /** Forget the session (it exited, or the user disconnected). */
+  clearTerminalSession(): void {
+    if (this.terminalSessionId === undefined) return
+    this.terminalSessionId = undefined
+    this.commit()
+  }
+
+  private commit(): void {
+    this.snapshot = {
+      panelOpen: this.panelOpen,
+      activeTab: this.activeTab,
+      connectRequest: this.connectRequest,
+      terminalSessionId: this.terminalSessionId,
+    }
     for (const fn of [...this.listeners]) fn()
   }
+
+  /** Ask the layout to select a panel; a shell without the face is a no-op. */
+  private selectPanel(panelId: string | null): void {
+    try {
+      this.deps.panel?.select(panelId)
+    } catch {
+      // The layout service throws by contract before its root entry mounts;
+      // the state flip above already stands and the next selection retries.
+    }
+  }
 }