Feedback

TerminalFrame

Frame a consumer-owned real PTY with terminal chrome, connection status, reload handling, and character-cell resize reporting.

import { TerminalFrame } from '@lostgradient/cinder';
terminalptyshell
01

Overview

Reference usage

TerminalFrame supplies chrome, connection state, recovery UI, and character-cell resize reporting around a consumer-owned real PTY renderer. It does not implement a terminal emulator or own a transport. Resize callbacks receive { cols, rows }.

Use TerminalOutput for read-only ANSI streams. Use TerminalFrame when the child content is an interactive terminal implementation whose backend needs { cols, rows } resize updates.

Usage

svelte 
<script lang="ts">
  import { TerminalFrame, type TerminalFrameDimensions } from '@lostgradient/cinder';

  let dimensions = $state<TerminalFrameDimensions>({ cols: 80, rows: 24 });
</script>

<TerminalFrame
  title="Build shell"
  status="connected"
  onDimensionsChange={(nextDimensions) => (dimensions = nextDimensions)}
>
  <textarea
    aria-label="Interactive shell"
    rows={dimensions.rows}
    cols={dimensions.cols}
    value="$ bun run dev"></textarea>
</TerminalFrame>
Live preview

Basic terminal frame

Build shell

connected
$ bun run build
Build complete.

02

When to use

Use when
  • Hosting a real interactive terminal implementation that needs consistent chrome and resize dimensions.
Avoid when
  • Rendering a read-only stream — use TerminalOutput.
03

Examples

Basic terminal frame

Frame a connected terminal surface with status chrome.

04

Props

Props for terminal-frame
Name
Type
Default
Description
title required text Title shown in the frame chrome.
status 'connecting' | 'connected' | 'disconnected' | 'error' 'connecting' Connection status shown in the frame chrome. Defaults to 'connecting'.
error text Recovery error message. The recovery UI is gated on error being a non-empty string ({#if error}), not on status—error="" shows nothing, the same as undefined, even though the prop is set. If error stays non-empty after status moves away from 'error' (for example to 'connected'), the recovery UI remains visible until the caller clears error too.
onReloadRequest () => void Called when the user requests a reload from the recovery UI. The recovery UI (and this button) show whenever error is a non-empty string, regardless of the current status—see that prop.
onDimensionsChange (dimensions: TerminalFrameDimensions) => void Called with { cols, rows } whenever the character-cell size changes, so the host can resize its PTY. A new measurement is never taken—and this never fires from one—while columnWidth or rowHeight is non-finite or <= 0. That's not an absolute guarantee this never fires while invalid, though: the component replays the last valid measurement whenever the onDimensionsChange reference itself changes (e.g. a parent passing a new inline handler each render), and that replay doesn't re-check columnWidth/rowHeight—so a stale measurement can still reach a newly-passed handler even after the cell size becomes invalid.
columnWidth number 8 Character-cell width, in pixels, used to compute { cols, rows } on resize. Must be positive and finite for a new measurement to run (see onDimensionsChange for the one exception). Defaults to 8.
rowHeight number 18 Character-cell height, in pixels, used to compute { cols, rows } on resize. Must be positive and finite for a new measurement to run (see onDimensionsChange for the one exception). Defaults to 18.
children required snippet Consumer-owned PTY renderer.