Bunli - The CLI Framework for Bun

Overview

@bunli/runtime provides terminal UI rendering capabilities and interactive prompt primitives for Bunli CLI applications. It is primarily used internally by @bunli/tui but also exports types and utilities used by command handlers.

Installation

bun add @bunli/runtime

Most users won't directly use @bunli/runtime. The prompt API is available through the handler context's prompt property, and TUI components are provided by @bunli/tui.

Subpath Exports

The package has 8 subpath exports:

Export	Purpose
`@bunli/runtime`	Root - type re-exports only
`@bunli/runtime/app`	React context providers (RuntimeProvider, RouteStore, CommandRegistry)
`@bunli/runtime/renderer`	TUI renderer (runTuiRender for full-screen TUI apps)
`@bunli/runtime/prompt`	Prompt primitives (text, select, confirm, etc.)
`@bunli/runtime/options`	TuiRenderOptions and OpenTuiRendererOptions
`@bunli/runtime/events`	Runtime event schemas
`@bunli/runtime/transport`	RuntimeTransport interface
`@bunli/runtime/image`	Image capability detection and rendering

Root Exports (Types Only)

The root package only exports TypeScript types:

import type {
  OpenTuiRendererOptions,
  TuiRenderOptions,
  RuntimeTransport,
  RuntimeTransportObserver,
  RuntimeEvent,
  RuntimeEventType,
} from "@bunli/runtime";

Runtime Events

Runtime events for telemetry and debugging:

type RuntimeEvent =
  | RuntimeRendererStartedEvent
  | RuntimeRendererMissingRenderEvent
  | RuntimeRendererDestroyedEvent
  | RuntimeImageRenderAttemptEvent
  | RuntimeImageRenderResultEvent
  | RuntimePromptStartedEvent
  | RuntimePromptCancelledEvent
  | RuntimeTransportErrorEvent;

TUI Options

interface TuiRenderOptions {
  exitOnCtrlC?: boolean;
  targetFps?: number;
  enableMouseMovement?: boolean;
  useMouse?: boolean;
  bufferMode?: "alternate" | "standard";
}

Image Rendering

Check terminal image capabilities:

import { detectImageCapability, renderImage } from "@bunli/runtime/image";

// Detect what image protocols the terminal supports
const capability = detectImageCapability();
// { supported: true, protocol: 'kitty' }

// Render an image
const result = await renderImage(imageData, {
  protocol: "kitty",
  width: 800,
});

Transport

Custom transport for runtime events:

interface RuntimeTransport {
  send(event: RuntimeEvent): void | Promise<void>;
}

interface RuntimeTransportObserver {
  onTransportError?(error: Error): void;
}

@bunli/runtime