Terminal Lifecycle

Silvery handles terminal lifecycle events (suspend/resume, interrupt) automatically. When stdin is in raw mode, Ctrl+Z and Ctrl+C don't generate OS signals (SIGTSTP/SIGINT). Silvery intercepts the raw bytes and manages the full terminal state save/restore cycle.

Quick Start

Both run() (Layer 2) and createApp().run() (Layer 3) enable lifecycle handling by default:

// Ctrl+Z suspends, Ctrl+C exits — no config needed
await run(<App />)

Options

Option	Type	Default	Description
suspendOnCtrlZ	boolean	true	Handle Ctrl+Z by suspending the process
exitOnCtrlC	boolean	true	Handle Ctrl+C by exiting
onSuspend	() => boolean | void	—	Called before suspend. Return false to prevent
onResume	() => void	—	Called after resume
onInterrupt	() => boolean | void	—	Called on Ctrl+C. Return false to prevent exit

Suspend/Resume Flow

When the user presses Ctrl+Z:

1. onSuspend hook is called (if provided). If it returns false, suspend is cancelled.
2. Terminal state is captured (protocols, modes, cursor visibility).
3. Terminal is restored to normal: raw mode off, alt screen exit, cursor shown, all protocols disabled.
4. SIGTSTP is sent to the process (it actually suspends).
5. On SIGCONT (resume): terminal state is restored, screen is cleared, synthetic resize triggers full redraw.
6. onResume hook is called.

Protocols Saved/Restored

• Raw mode (stdin)
• Alternate screen buffer (DEC mode 1049)
• Cursor visibility (DEC mode 25)
• Mouse tracking (modes 1003, 1006, optional 1016 SGR-Pixels)
• Kitty keyboard protocol (with original flags)
• Bracketed paste (DEC mode 2004)
• SGR attributes (reset on suspend, not restored — redraw handles this)

Interrupt Flow

When the user presses Ctrl+C:

1. onInterrupt hook is called (if provided). If it returns false, exit is cancelled.
2. The app's exit function is called, which triggers normal cleanup (unmount, restore terminal, exit).

Hooks Example

await run(<App />, {
  onSuspend: () => {
    // Pause background timers before suspend
    pauseTimers()
  },
  onResume: () => {
    // Refresh data that may have changed while suspended
    refetchData()
  },
  onInterrupt: () => {
    if (hasUnsavedChanges) {
      showConfirmDialog()
      return false // Prevent exit
    }
  },
})

Low-Level API

For custom lifecycle management (e.g., framework integrations), the building blocks are exported from silvery/runtime:

import {
  captureTerminalState,
  restoreTerminalState,
  resumeTerminalState,
  performSuspend,
  CTRL_C,
  CTRL_Z,
  type TerminalLifecycleOptions,
  type TerminalState,
} from "@silvery/ag-term/runtime"

// Capture current state
const state = captureTerminalState({
  alternateScreen: true,
  mouse: true,
  kitty: true,
  kittyFlags: 3,
  bracketedPaste: true,
})

// Manual suspend/resume
restoreTerminalState(stdout, stdin) // Before suspend
// ... process suspends ...
resumeTerminalState(state, stdout, stdin) // After resume

// Or use the all-in-one helper
performSuspend(state, stdout, stdin, () => {
  console.log("Resumed!")
})

TerminalState

interface TerminalState {
  rawMode: boolean
  alternateScreen: boolean
  cursorHidden: boolean
  mouseEnabled: boolean
  kittyEnabled: boolean
  kittyFlags: number
  bracketedPaste: boolean
}

Terminal Compatibility

Suspend/resume works on all terminals that support the standard escape sequences. Tested with:

• Ghostty
• Kitty
• WezTerm
• iTerm2
• Alacritty
• macOS Terminal.app
• tmux / screen (nested sessions work correctly)

Implementation Notes

• writeSync is used for restore sequences during signal handlers (async writes may not complete before suspend)
• The SIGCONT handler is registered as a one-time handler BEFORE sending SIGTSTP
• Screen clear (CSI 2 J + CSI H) is always included on resume to ensure a clean slate
• Synthetic resize (stdout.emit("resize")) triggers a full redraw after resume
• The runtime's invalidate() is called to force a fresh render (not incremental diff)