@deckbuilderkit/terminal 0.0.0-stage → 0.1.1

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@deckbuilderkit/terminal",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/adrianogpena/deckbuilder.git",
+    "directory": "packages/terminal"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.ts"
+  ],
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./protocol": "./src/protocol.ts",
+    "./session": "./src/client.ts",
+    "./options": "./src/terminalOptions.ts",
+    "./server": "./src/server/index.ts"
+  },
+  "dependencies": {
+    "@deckbuilderkit/platform": "0.1.1",
+    "@deckbuilderkit/server-core": "0.1.1",
+    "@deckbuilderkit/ui": "0.1.1",
+    "@xterm/addon-clipboard": "^0.2.0",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/addon-search": "^0.16.0",
+    "@xterm/addon-serialize": "^0.14.0",
+    "@xterm/addon-unicode11": "^0.9.0",
+    "@xterm/addon-web-links": "^0.12.0",
+    "@xterm/addon-webgl": "0.19.0",
+    "@xterm/headless": "^6.0.0",
+    "@xterm/xterm": "^6.0.0"
+  },
+  "peerDependencies": {
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.12",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "@types/react-dom": "^18.3.1"
+  }
+}

package/src/TerminalPane.tsx

@@ -0,0 +1,590 @@
+import { copyText, Icon, effectiveKeys, errorMessage, errorOf, paletteCommand, t, useDialogs, useKeybindings, type CommandDef } from '@deckbuilderkit/ui';
+import { useEffect, useMemo, useRef, useState, type CSSProperties, type KeyboardEvent as ReactKeyboardEvent } from 'react';
+import { attachSession, closeSession, isSessionGone, openSession, socketUrl, type TerminalCwd, type TerminalLaunch } from './client.ts';
+import { withAppearance, type ProfileAppearance } from './appearance.ts';
+import { PANE_COMMANDS, terminalKeyAction, type PaneCommand } from './keys.ts';
+import { pasteNeedsWarning, pasteSummary, sanitizePaste } from './paste.ts';
+import { decodeServerMessage, encodeControl } from './protocol.ts';
+import { useTerminalOptions } from './terminalOptions.ts';
+import { createXtermView, type TerminalOptions, type XtermView } from './xterm-view.ts';
+import './terminal.css';
+
+/** Server close codes (see `terminalRoutes`). */
+const BACKPRESSURE_CLOSE = 4001;
+const NO_SESSION_CLOSE = 1008;
+const NORMAL_CLOSE = 1000;
+const MAX_BACKOFF = 30_000;
+/** The command that opens the find bar (registered by the app); the key is the fallback without a keymap. */
+const FIND_COMMAND = 'terminal.find';
+const DEFAULT_FIND_KEY = 'Ctrl+Shift+F';
+/** Scroll to the previous / next prompt (shell integration); same fallback rule as find. */
+const PREV_COMMAND = 'terminal.prevCommand';
+const NEXT_COMMAND = 'terminal.nextCommand';
+const DEFAULT_PREV_KEY = 'Ctrl+ArrowUp';
+const DEFAULT_NEXT_KEY = 'Ctrl+ArrowDown';
+const MIN_FONT = 6;
+const MAX_FONT = 72;
+const DEFAULT_FONT = 13;
+
+/** What the app can make a pane do (tab menus): the pane commands. */
+export interface TerminalPaneHandle {
+  run(command: PaneCommand): void;
+}
+
+let audio: AudioContext | null = null;
+let lastBeep = 0;
+/** A short beep, at most one per 200 ms. */
+function beep() {
+  const now = Date.now();
+  if (now - lastBeep < 200) return;
+  lastBeep = now;
+  try {
+    audio ??= new AudioContext();
+    const osc = audio.createOscillator();
+    const gain = audio.createGain();
+    osc.frequency.value = 880;
+    gain.gain.setValueAtTime(0.08, audio.currentTime);
+    gain.gain.exponentialRampToValueAtTime(0.0001, audio.currentTime + 0.12);
+    osc.connect(gain).connect(audio.destination);
+    osc.start();
+    osc.stop(audio.currentTime + 0.12);
+  } catch {
+    // no audio here
+  }
+}
+
+export interface TerminalPaneProps {
+  /** The session to attach to; none opens a new one and reports it through `onSession`. */
+  session?: string;
+  /** Where a new session starts; the user's home when absent. */
+  cwd?: TerminalCwd;
+  /** A launcher the app registered on the server, instead of the configured shell. */
+  launch?: TerminalLaunch;
+  /** Profile id for a new session; none: the default one. */
+  profile?: string;
+  /** Absolute folder a new session starts in (wins over `cwd`); the server falls back when it is gone. */
+  dir?: string;
+  /** Opens a new shell when the session exits, instead of the exit overlay. */
+  restartOnExit?: boolean;
+  /** Read-only, at the session's own size, scaled to the box. */
+  preview?: boolean;
+  /** App commands whose keys still work while the terminal has focus; default: the command palette. */
+  appKeys?: CommandDef[];
+  fontSize?: number;
+  /** Look and behavior preferences; without it the app-wide ones (TerminalOptionsContext), else the built-in defaults. */
+  options?: TerminalOptions;
+  onSession?: (id: string) => void;
+  onExit?: (code: number | null) => void;
+  onTitle?: (title: string) => void;
+  /** The shell's folder changed (OSC 7). */
+  onCwd?: (cwd: string) => void;
+  onBell?: () => void;
+  /** Shell integration: a command started (true) or finished (false). */
+  onRunning?: (running: boolean) => void;
+  /** The profile's look, over `options`. */
+  appearance?: ProfileAppearance;
+  /** Shell id of the session (`SessionInfo.shell`): how a sanitized paste continues lines. */
+  shell?: string;
+  /** False dims the pane by `options.dimUnfocused` (a split pane without the focus); true focuses it. */
+  focused?: boolean;
+  /** Gets the pane's handle once mounted, null when it goes. */
+  handle?: (h: TerminalPaneHandle | null) => void;
+}
+
+type Status =
+  | { kind: 'connecting' }
+  | { kind: 'live' }
+  | { kind: 'reconnecting' }
+  | { kind: 'exited'; code: number | null }
+  | { kind: 'ended' }
+  | { kind: 'detached' }
+  | { kind: 'error'; message: string };
+
+interface Controller {
+  /** The session the pane is connected (or connecting) to. */
+  session(): string | undefined;
+  attach(id: string): void;
+  restart(): void;
+  reattach(): void;
+}
+
+/**
+ * A terminal session in a box. Unmounting only closes the socket: the shell keeps running until
+ * `closeSession`, its own exit, or app quit. While focus is inside, keys go to the program except
+ * the `appKeys` commands (the container is `data-keys="own"`).
+ */
+export function TerminalPane(props: TerminalPaneProps) {
+  const { preview = false } = props;
+  const hostRef = useRef<HTMLDivElement>(null);
+  const boxRef = useRef<HTMLDivElement>(null);
+  const latest = useRef(props);
+  latest.current = props;
+  const [status, setStatus] = useState<Status>({ kind: 'connecting' });
+  const controller = useRef<Controller | null>(null);
+  const viewRef = useRef<XtermView | null>(null);
+  const contextOptions = useTerminalOptions();
+  const baseOptions = withAppearance(props.options ?? contextOptions, props.appearance);
+  const baseKey = baseOptions === undefined ? undefined : JSON.stringify(baseOptions);
+  const [zoom, setZoom] = useState(0);
+  const options = useMemo((): TerminalOptions | undefined => {
+    if (!zoom) return baseOptions;
+    const size = (baseOptions?.fontSize ?? props.fontSize ?? DEFAULT_FONT) + zoom;
+    return { ...baseOptions, fontSize: Math.max(MIN_FONT, Math.min(MAX_FONT, size)) };
+  }, [baseKey, zoom, props.fontSize]);
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+
+  const [finding, setFinding] = useState(false);
+  const [findQuery, setFindQuery] = useState('');
+  const [matchCase, setMatchCase] = useState(false);
+  const [regex, setRegex] = useState(false);
+  const [found, setFound] = useState({ index: -1, count: 0 });
+  const findInput = useRef<HTMLInputElement>(null);
+
+  const kb = useKeybindings();
+  const appKeys = useMemo(() => props.appKeys ?? [paletteCommand()], [props.appKeys]);
+  const appChords = useRef(new Set<string>());
+  appChords.current = useMemo(() => {
+    const keys = kb ? effectiveKeys(kb.defs, kb.keymap) : new Map<string, string[]>();
+    return new Set(appKeys.flatMap((d) => keys.get(d.id) ?? d.keys).map((c) => c.split(' ')[0]));
+  }, [kb, appKeys]);
+
+  const findChords = useRef(new Set<string>());
+  findChords.current = useMemo(() => {
+    const keys = kb ? effectiveKeys(kb.defs, kb.keymap).get(FIND_COMMAND) : undefined;
+    return new Set((keys ?? [DEFAULT_FIND_KEY]).map((c) => c.split(' ')[0]));
+  }, [kb]);
+
+  const paneChords = useRef(new Map<string, PaneCommand>());
+  paneChords.current = useMemo(() => {
+    const keys = kb ? effectiveKeys(kb.defs, kb.keymap) : undefined;
+    const out = new Map<string, PaneCommand>();
+    for (const [id, fallback] of Object.entries(PANE_COMMANDS) as [PaneCommand, readonly string[]][]) {
+      for (const c of keys?.get(id) ?? fallback) out.set(c.split(' ')[0], id);
+    }
+    return out;
+  }, [kb]);
+
+  const dialogs = useDialogs();
+  const dialogsRef = useRef(dialogs);
+  dialogsRef.current = dialogs;
+
+  const navChords = useRef({ prev: new Set<string>(), next: new Set<string>() });
+  navChords.current = useMemo(() => {
+    const keys = kb ? effectiveKeys(kb.defs, kb.keymap) : undefined;
+    const set = (id: string, fallback: string) => new Set((keys?.get(id) ?? [fallback]).map((c) => c.split(' ')[0]));
+    return { prev: set(PREV_COMMAND, DEFAULT_PREV_KEY), next: set(NEXT_COMMAND, DEFAULT_NEXT_KEY) };
+  }, [kb]);
+
+  useEffect(() => {
+    const host = hostRef.current!;
+    let disposed = false;
+    let ws: WebSocket | null = null;
+    let sessionId = latest.current.session;
+    let decoder = new TextDecoder();
+    let retries = 0;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let ended = false;
+    let sessionChecked = false;
+    const encoder = new TextEncoder();
+
+    const view: XtermView = createXtermView(host, {
+      readOnly: preview,
+      fontSize: latest.current.fontSize,
+      options: optionsRef.current,
+      onCwd: (cwd) => latest.current.onCwd?.(cwd),
+      onBell: () => {
+        const style = optionsRef.current?.bellStyle ?? 'tab';
+        if (style === 'sound' || style === 'both') beep();
+        latest.current.onBell?.();
+      },
+      onCommand: (running) => latest.current.onRunning?.(running),
+      onPaste: (text) => {
+        const o = optionsRef.current;
+        if (preview || !pasteNeedsWarning(text, o?.pasteWarning ?? 'multiLine', o?.pasteLargeSize ?? 5120)) return false;
+        void askPaste(text);
+        return true;
+      },
+      onKey: (e) => {
+        if (preview || e.type !== 'keydown') return true;
+        const action = terminalKeyAction(e, view.hasSelection(), appChords.current, findChords.current, navChords.current, paneChords.current);
+        if (action.startsWith('terminal.')) {
+          e.preventDefault();
+          runPane(action as PaneCommand);
+          return false;
+        }
+        switch (action) {
+          case 'prevCommand':
+            e.preventDefault();
+            view.scrollToPrompt(-1);
+            return false;
+          case 'nextCommand':
+            e.preventDefault();
+            view.scrollToPrompt(1);
+            return false;
+          case 'find':
+            e.preventDefault();
+            setFinding(true);
+            requestAnimationFrame(() => findInput.current?.select());
+            return false;
+          case 'app':
+          case 'paste': // the browser's paste event reaches xterm
+            return false;
+          case 'copy':
+            e.preventDefault();
+            void copyText(view.getSelection());
+            return false;
+          default:
+            return true;
+        }
+      },
+    });
+
+    async function askPaste(text: string) {
+      const { lines, chars, preview: sample } = pasteSummary(text);
+      const choice = await dialogsRef.current.choose({
+        title: lines > 1 ? t('terminal.paste.title', { lines }) : t('terminal.paste.titleLarge', { chars }),
+        body: (
+          <>
+            <p>{t('terminal.paste.body', { lines, chars })}</p>
+            <pre className="terminal-paste-preview">{sample}</pre>
+            <p className="muted">{t('terminal.paste.sanitizeHint')}</p>
+          </>
+        ),
+        choices: [
+          { id: 'sanitize', label: t('terminal.paste.sanitize') },
+          { id: 'paste', label: t('terminal.paste.paste') },
+        ],
+      });
+      if (disposed || !choice) return;
+      view.paste(choice === 'paste' ? text : sanitizePaste(text, { bracketed: view.bracketedPaste(), shell: latest.current.shell }));
+      view.focus();
+    }
+
+    function runPane(command: PaneCommand) {
+      switch (command) {
+        case 'terminal.zoomIn':
+          return setZoom((z) => z + 1);
+        case 'terminal.zoomOut':
+          return setZoom((z) => z - 1);
+        case 'terminal.zoomReset':
+          return setZoom(0);
+        case 'terminal.clear':
+          view.clear();
+          return send(encodeControl({ type: 'clear' }));
+        case 'terminal.scrollLineUp':
+          return view.scroll('lineUp');
+        case 'terminal.scrollLineDown':
+          return view.scroll('lineDown');
+        case 'terminal.scrollPageUp':
+          return view.scroll('pageUp');
+        case 'terminal.scrollPageDown':
+          return view.scroll('pageDown');
+        case 'terminal.scrollTop':
+          return view.scroll('top');
+        case 'terminal.scrollBottom':
+          return view.scroll('bottom');
+      }
+    }
+    if (!preview) latest.current.handle?.({ run: runPane });
+
+    viewRef.current = view;
+    view.onFindResults((index, count) => setFound({ index, count }));
+    const send = (data: string | Uint8Array) => {
+      if (ws?.readyState === WebSocket.OPEN) ws.send(data);
+    };
+    view.onInput((data) => send(encoder.encode(data)));
+    view.onResize((cols, rows) => {
+      if (!preview) send(encodeControl({ type: 'resize', cols, rows }));
+    });
+
+    // A preview renders at the session's size, scaled down to the box.
+    const scale = () => {
+      const box = boxRef.current;
+      if (!preview || !box) return;
+      const el = view.element();
+      const s = Math.min(1, box.clientWidth / (el.offsetWidth || 1), box.clientHeight / (el.offsetHeight || 1));
+      host.style.transform = `scale(${s})`;
+    };
+    const boxObserver = new ResizeObserver(scale);
+    if (preview && boxRef.current) boxObserver.observe(boxRef.current);
+
+    const stop = (next: Status) => {
+      ended = true;
+      setStatus(next);
+    };
+
+    const retryLater = () => {
+      setStatus({ kind: 'reconnecting' });
+      const delay = Math.min(MAX_BACKOFF, 500 * 2 ** retries++);
+      timer = setTimeout(() => void connect(false), delay);
+    };
+
+    function openSocket(ticket: string) {
+      const socket = new WebSocket(socketUrl(ticket));
+      const previous = ws;
+      ws = socket;
+      previous?.close();
+      socket.binaryType = 'arraybuffer';
+      socket.onmessage = (ev) => {
+        if (ws !== socket) return;
+        const m = decodeServerMessage(ev.data as string | ArrayBuffer);
+        if (!m) return;
+        if (m.kind === 'output') {
+          view.write(decoder.decode(m.data, { stream: true }));
+          return;
+        }
+        const msg = m.msg;
+        if (msg.type === 'hello') {
+          // The replay that follows redraws the screen from scratch.
+          retries = 0;
+          view.reset();
+          decoder = new TextDecoder();
+          if (preview) {
+            view.resize(msg.cols, msg.rows);
+            requestAnimationFrame(scale);
+          } else {
+            view.fit();
+            const { cols, rows } = view.size();
+            if (cols !== msg.cols || rows !== msg.rows) send(encodeControl({ type: 'resize', cols, rows }));
+            view.focus();
+          }
+          setStatus({ kind: 'live' });
+        } else if (msg.type === 'exit') {
+          latest.current.onRunning?.(false);
+          if (latest.current.restartOnExit && !preview) {
+            ended = true;
+            latest.current.onExit?.(msg.code);
+            void connect(true);
+            return;
+          }
+          stop({ kind: 'exited', code: msg.code });
+          latest.current.onExit?.(msg.code);
+        } else {
+          latest.current.onTitle?.(msg.title);
+        }
+      };
+      socket.onclose = (ev) => {
+        if (ws !== socket) return;
+        ws = null;
+        if (disposed || ended) return;
+        if (ev.code === BACKPRESSURE_CLOSE) void connect(false);
+        else if (ev.code === NO_SESSION_CLOSE) stop({ kind: 'ended' });
+        // A plain close without an exit: another interactive view took the session.
+        else if (ev.code === NORMAL_CLOSE) stop({ kind: 'detached' });
+        else retryLater();
+      };
+    }
+
+    async function connect(fresh: boolean) {
+      clearTimeout(timer);
+      ended = false;
+      // A session id from a saved layout may belong to an earlier app run: then open a new shell instead.
+      const restored = !fresh && !!sessionId && !sessionChecked;
+      sessionChecked = true;
+      try {
+        let ticketed;
+        if (fresh || !sessionId) {
+          view.fit();
+          const { cols, rows } = view.size();
+          const { cwd, launch, profile, dir } = latest.current;
+          ticketed = await openSession({ cols, rows, cwd, launch, profile, dir });
+          if (disposed) {
+            // Unmounted while opening (React strict mode remounts): nobody holds this session.
+            void closeSession(ticketed.session).catch(() => {});
+            return;
+          }
+          sessionId = ticketed.session;
+          latest.current.onSession?.(ticketed.session);
+        } else {
+          ticketed = await attachSession(sessionId, preview ? 'preview' : 'interactive');
+          if (disposed) return;
+        }
+        openSocket(ticketed.ticket);
+      } catch (err) {
+        if (disposed) return;
+        if (isSessionGone(err)) {
+          if (restored && !preview) void connect(true);
+          else stop({ kind: 'ended' });
+        }
+        else if (errorOf(err).kind === 'offline') retryLater();
+        else stop({ kind: 'error', message: errorMessage(errorOf(err)) });
+      }
+    }
+
+    controller.current = {
+      session: () => sessionId,
+      attach: (id) => {
+        sessionId = id;
+        ws?.close();
+        ws = null;
+        setStatus({ kind: 'connecting' });
+        void connect(false);
+      },
+      restart: () => {
+        setStatus({ kind: 'connecting' });
+        void connect(true);
+      },
+      reattach: () => {
+        setStatus({ kind: 'connecting' });
+        void connect(false);
+      },
+    };
+    void connect(false);
+
+    return () => {
+      disposed = true;
+      clearTimeout(timer);
+      boxObserver.disconnect();
+      ws?.close();
+      ws = null;
+      controller.current = null;
+      viewRef.current = null;
+      if (!preview) latest.current.handle?.(null);
+      view.dispose();
+    };
+  }, [preview]);
+
+  useEffect(() => {
+    if (options) viewRef.current?.setOptions(options);
+  }, [options]);
+
+  // Focus moved to this pane (another split pane had it): the keys come here.
+  useEffect(() => {
+    if (props.focused && !preview && !boxRef.current?.contains(document.activeElement)) viewRef.current?.focus();
+  }, [props.focused]);
+
+  const dim = Math.max(0, Math.min(80, options?.dimUnfocused ?? 0));
+  const dimmed = !preview && props.focused === false && dim > 0;
+
+  const step = (dir: 1 | -1) => {
+    const view = viewRef.current;
+    if (!view || !findQuery) return;
+    const o = { caseSensitive: matchCase, regex };
+    if (dir === 1) view.findNext(findQuery, o);
+    else view.findPrevious(findQuery, o);
+  };
+  const closeFind = () => {
+    setFinding(false);
+    setFound({ index: -1, count: 0 });
+    viewRef.current?.clearFind();
+    viewRef.current?.focus();
+  };
+  // Typing or toggling an option searches again; an empty query clears the highlights.
+  useEffect(() => {
+    const view = viewRef.current;
+    if (!finding || !view) return;
+    if (findQuery) view.findNext(findQuery, { caseSensitive: matchCase, regex });
+    else {
+      view.clearFind();
+      setFound({ index: -1, count: 0 });
+    }
+  }, [finding, findQuery, matchCase, regex]);
+  const onFindKey = (e: ReactKeyboardEvent) => {
+    e.stopPropagation();
+    if (e.key === 'Escape') {
+      e.preventDefault();
+      closeFind();
+    } else if (e.key === 'Enter') {
+      e.preventDefault();
+      step(e.shiftKey ? -1 : 1);
+    }
+  };
+
+  // A new `session` prop (not the one this pane just opened and reported) switches sessions.
+  useEffect(() => {
+    const c = controller.current;
+    if (c && props.session && props.session !== c.session()) c.attach(props.session);
+  }, [props.session]);
+
+  const overlay = overlayOf(status, preview, controller);
+  return (
+    <div
+      ref={boxRef}
+      className={`terminal-pane${preview ? ' preview' : ''}${dimmed ? ' dimmed' : ''}`}
+      style={dimmed ? ({ '--terminal-dim': dim / 100 } as CSSProperties) : undefined}
+      {...(preview ? {} : { 'data-keys': 'own', 'data-keys-allow': appKeys.map((d) => d.id).join(' ') })}
+    >
+      <div ref={hostRef} className="terminal-host" />
+      {finding && !preview && (
+        <div className="terminal-find">
+          <input
+            ref={findInput}
+            autoFocus
+            type="search"
+            value={findQuery}
+            placeholder={t('terminal.find.placeholder')}
+            aria-label={t('terminal.find.placeholder')}
+            onChange={(e) => setFindQuery(e.target.value)}
+            onKeyDown={onFindKey}
+          />
+          <span className="terminal-find-count muted">
+            {findQuery ? (found.count ? `${found.index >= 0 ? found.index + 1 : 0}/${found.count}` : t('terminal.find.none')) : ''}
+          </span>
+          <button type="button" className={`chip${matchCase ? ' chip-on' : ''}`} onClick={() => setMatchCase(!matchCase)} aria-pressed={matchCase} title={t('terminal.find.matchCase')}>
+            Aa
+          </button>
+          <button type="button" className={`chip${regex ? ' chip-on' : ''}`} onClick={() => setRegex(!regex)} aria-pressed={regex} title={t('terminal.find.regex')}>
+            .*
+          </button>
+          <button type="button" className="btn btn-ghost btn-sm btn-icon" onClick={() => step(-1)} title={t('terminal.find.prev')} aria-label={t('terminal.find.prev')}>
+            <Icon name="chevron-up" />
+          </button>
+          <button type="button" className="btn btn-ghost btn-sm btn-icon" onClick={() => step(1)} title={t('terminal.find.next')} aria-label={t('terminal.find.next')}>
+            <Icon name="chevron-down" />
+          </button>
+          <button type="button" className="btn btn-ghost btn-sm btn-icon" onClick={closeFind} title={t('terminal.find.close')} aria-label={t('terminal.find.close')}>
+            <Icon name="close" />
+          </button>
+        </div>
+      )}
+      {overlay && <div className="terminal-overlay">{overlay}</div>}
+      {dialogs.element}
+    </div>
+  );
+}
+
+function overlayOf(status: Status, preview: boolean, controller: { current: Controller | null }) {
+  const action = (label: string, run: (c: Controller) => void) =>
+    preview ? null : (
+      <button type="button" className="btn btn-sm" onClick={() => controller.current && run(controller.current)}>
+        {label}
+      </button>
+    );
+  switch (status.kind) {
+    case 'live':
+      return null;
+    case 'connecting':
+      return <span>{t('terminal.connecting')}</span>;
+    case 'reconnecting':
+      return <span>{t('terminal.reconnecting')}</span>;
+    case 'exited':
+      return (
+        <>
+          <span>{status.code === null ? t('terminal.exitedNoCode') : t('terminal.exited', { code: status.code })}</span>
+          {action(t('terminal.restart'), (c) => c.restart())}
+        </>
+      );
+    case 'ended':
+      return (
+        <>
+          <span>{t('terminal.ended')}</span>
+          {action(t('terminal.restart'), (c) => c.restart())}
+        </>
+      );
+    case 'detached':
+      return (
+        <>
+          <span>{t('terminal.detached')}</span>
+          {action(t('terminal.reattach'), (c) => c.reattach())}
+        </>
+      );
+    case 'error':
+      return (
+        <>
+          <span className="terminal-error">{t('terminal.error', { message: status.message })}</span>
+          {action(t('common.retry'), (c) => c.reattach())}
+        </>
+      );
+  }
+}

package/src/app-keys.ts

@@ -0,0 +1,10 @@
+import type { CommandDef } from '@deckbuilderkit/ui';
+
+/**
+ * Of `all` (every command of the app), those whose keys reach the app while a terminal in view `scope`
+ * has focus; the rest goes to the shell. `extra` adds command ids of the view.
+ */
+export function terminalAppKeys(scope: string, all: readonly CommandDef[], extra: readonly string[] = []): CommandDef[] {
+  const ids = new Set(['palette.toggle', 'app.keybindings', `${scope}.tab.saveAll`, `${scope}.pane.maximize`, ...extra]);
+  return all.filter((d) => ids.has(d.id));
+}