API reference / @jsprismarine/console

@jsprismarine/console

Terminal user interface for the JSPrismarine server console, built on OpenTUI.

The server entry point in @jsprismarine/server imports this package lazily, and only when it has decided to run the UI: stdin and stdout are a terminal, JSP_NO_TUI and --no-tui are absent, and Node can load node:ffi (26.9 or newer, or 26.4 with --experimental-ffi). In every other situation the server uses its plain line console and this package is never loaded, so a Docker image or a hosting panel pays nothing for it. The UI talks to the server over the messages in @jsprismarine/console-protocol; nothing outside this package imports @opentui/core.

Requires Node.js 26.9 or later, or 26.4 and later started with --experimental-ffi: OpenTUI calls its native renderer through node:ffi, which shipped in 26.4 behind a flag and is on by default from 26.9. Older versions can't load the renderer, which is why the server falls back to the plain console instead of failing.

Layout

Each component is a factory in its own file, create<Name>(ctx, props), with a sibling *.test.ts. Logic that doesn't need a renderer (log windowing, history, completion, segment truncation) lives in plain modules with their own tests.

Directory	Owns
src/theme/	Color roles resolved against the terminal's capabilities, and styled text with Minecraft § codes
src/log/	Bounded log storage with filter-aware retention, windowed rendering, line formatting, and badges
src/input/	The input bar, command history, and completion state
src/status/	The status bar, its segments, and toasts
src/help/	The help overlay generated from the key map
src/tps/	TPS history, the braille line chart shared by the details pane, and the TPS page
src/app/	Layout, breakpoints, focus, and wiring; exports startConsole

Tests

From the repository root, pnpm exec vitest run packages/console runs this package's tests. They render into OpenTUI's test renderer, so they need a Node that loads node:ffi too.

Interfaces

ConsoleHandle

Defined in: startConsole.ts:58

A running console.

Methods

close()

close(): Promise<void>

Defined in: startConsole.ts:60

Saves history, destroys the renderer, waits for the terminal to be restored, and removes the fallback handlers.

Returns

Promise<void>

---

StartConsoleOptions

Defined in: startConsole.ts:39

Everything startConsole needs from the host.

Properties

createRenderer?

optional createRenderer?: (config) => Promise<CliRenderer>

Defined in: startConsole.ts:54

Builds the renderer. Tests inject createTestRenderer; production uses createCliRenderer.

Parameters

config

CliRendererConfig

Returns

Promise<CliRenderer>

env?

optional env?: ProcessEnv

Defined in: startConsole.ts:48

Environment read for NO_COLOR, JSP_DIR, VISUAL, and EDITOR; defaults to process.env.

historyFile?

optional historyFile?: string

Defined in: startConsole.ts:42

Where command history is read and written. Defaults to ${JSP_DIR ?? 'jsp'}/.console_history.

serverName?

optional serverName?: string

Defined in: startConsole.ts:44

Server name for the title bar.

stdin?

optional stdin?: ReadStream

Defined in: startConsole.ts:52

Terminal input; defaults to process.stdin.

stdout?

optional stdout?: WriteStream

Defined in: startConsole.ts:50

Terminal output; defaults to process.stdout. Its color depth picks the theme.

supervisor

supervisor: ConsoleSupervisor

Defined in: startConsole.ts:40

version?

optional version?: string

Defined in: startConsole.ts:46

Server version for the title bar.

Variables

CONSOLE_VERSION

const CONSOLE_VERSION: string = pkg.version

Defined in: version.ts:6

Version of the console package, read from its package.json at build time.

Functions

startConsole()

startConsole(options): Promise<ConsoleHandle>

Defined in: startConsole.ts:113

Starts the TUI console on the current terminal and wires it to the host's supervisor.

The renderer never exits on Ctrl+C or signals; the app decides what Ctrl+C means and the host owns signals. Each new server link gets a subscribe for every level, and commands and completions travel over it with request ids that the matching result resolves. A fallback on process exit, uncaughtException, and unhandledRejection writes the terminal reset sequence and leaves raw mode when renderer.destroy() never ran. It does nothing else: the host's own fatal handler kills the child, closes the console, prints the error once, and exits, so a second print or process.exit here would race it.

Parameters

options

StartConsoleOptions

Returns

Promise<ConsoleHandle>

Throws

Error when the renderer cannot start, for example because OpenTUI's native library is missing. The message names the cause so the host can print it and fall back.