JSVision

Appearance

@jsvision/core / HostOptions

Interface: HostOptions ​

Defined in: host/types.ts:28

Options for createHost. Only caps is required; every OS-touching input is injectable, so the same host can be driven against real streams or fakes in tests.

Properties ​

adaptAmbiguousWidth? ​

readonly optional adaptAmbiguousWidth?: boolean

Defined in: host/types.ts:74

Automatically switch to ASCII-safe chrome when the startup width probe finds that box/scroll glyphs render two cells wide: wide arrows turn on the ambiguousWide glyph flag, wide box/shade glyphs turn boxDrawing/halfBlocks off — so every frame stays aligned instead of shearing. Downgrade-only; the original caps are still used for input decoding, mode setup, and restore. Real TTY only, and it shares the single probe run with warnAmbiguousWidth. Default false (the higher-level app runner turns this on).

caps ​

readonly caps: CapabilityProfile

Defined in: host/types.ts:30

The detected capability profile; gates every terminal mode the host enables.

env? ​

readonly optional env?: ProcessEnv

Defined in: host/types.ts:81

Environment to read the JSVISION_ASCII force switch from (NO_COLOR-style: its mere presence, with any value, turns it on). When set, the host renders fully ASCII-safe chrome and skips the width probe entirely. Default process.env. Presence-checked only — the value is never parsed or logged.

exitOnSignal? ​

readonly optional exitOnSignal?: boolean

Defined in: host/types.ts:48

When false, terminating signals restore the terminal but do not call process.exit. Default true.

focus? ​

readonly optional focus?: boolean

Defined in: host/types.ts:54

Enable focus reporting (the terminal reports when it gains/loses focus). No capability models this, so it is a host policy rather than caps-gated. Default true.

input? ​

readonly optional input?: ReadStream

Defined in: host/types.ts:32

Input stream to read from. Default: process.stdin (or /dev/tty when stdout is piped).

onBeforeExit? ​

readonly optional onBeforeExit?: (code) => void

Defined in: host/types.ts:46

Runs just before the host calls process.exit on a signal or crash path (receives the exit code).

Parameters ​

code ​

number

Returns ​

void

onInput? ​

readonly optional onInput?: (event) => void

Defined in: host/types.ts:38

Called with each decoded input event. Terminal query replies are handled internally and never delivered here.

Parameters ​

event ​

InputEvent

Returns ​

void

onResize? ​

readonly optional onResize?: (event) => void

Defined in: host/types.ts:40

Called with a terminal resize, coalesced so a burst of SIGWINCH yields a single event.

Parameters ​

event ​

ResizeEvent

Returns ​

void

onResume? ​

readonly optional onResume?: () => void

Defined in: host/types.ts:44

POSIX resume (SIGCONT): fired after modes are re-asserted and the last frame is repainted.

Returns ​

void

onSuspend? ​

readonly optional onSuspend?: () => void

Defined in: host/types.ts:42

POSIX Ctrl+Z (SIGTSTP): fired just before the terminal is restored and the process suspends.

Returns ​

void

onWidthWarning? ​

readonly optional onWidthWarning?: (message) => void

Defined in: host/types.ts:87

Where the startup width warning goes (see warnAmbiguousWidth). Default: one line to process.stderr (never the terminal's output stream). Provide your own to route it into a logger or custom reporting.

Parameters ​

message ​

string

Returns ​

void

output? ​

readonly optional output?: WriteStream

Defined in: host/types.ts:34

Output stream to render to. Default: process.stdout (or /dev/tty when piped).

preferDevTty? ​

readonly optional preferDevTty?: boolean

Defined in: host/types.ts:36

When true (default) and stdout is piped but a controlling terminal exists, bind to /dev/tty.

runtime? ​

readonly optional runtime?: RuntimeAdapter

Defined in: host/types.ts:89

The OS boundary the host runs against. Defaults to the real Node runtime; inject a fake to test headlessly.

warnAmbiguousWidth? ​

readonly optional warnAmbiguousWidth?: boolean

Defined in: host/types.ts:64

Probe the terminal at startup for double-width chrome glyphs — East-Asian Ambiguous code points (e.g. ▲◄■▒) that a font fallback or CJK locale renders two cells wide, shifting box/scroll chrome — and warn via onWidthWarning when found. Real TTY only; runs after raw mode and before the alternate screen, so the probe and its erase stay off your UI. Default false (the higher-level app runner turns this on). Detection is best-effort — a silent or non-TTY terminal never warns.