valyrianjs-terminal

Terminal-first adapter for valyrian.js. It lets you render text UIs with its own primitives and, when needed, mount interactive sessions on top of stdin and stdout.

What It Solves

• terminal-first layout with Screen, Box, View, Text, Table, Row, and Td
• interactive primitives with Input, Button, List, and ScrollView
• static text rendering with renderTerminal()
• interactive runtime with mountTerminal()

Installation

npm install valyrianjs-terminal valyrian.js

Choose the Right Entrypoint

• Use renderTerminal() for snapshots, tests, or non-interactive output.
• Use mountTerminal() when you need focus, keyboard, mouse, clipboard, or writes to stdout.

Minimal Example

/** @jsx v */
/** @jsxFrag v.fragment */

import { v } from "valyrian.js";
import { Input, Screen, Text, mountTerminal } from "valyrianjs-terminal";

const state = { value: "" };

const session = mountTerminal(() => (
  <Screen title="Notes">
    <Input
      id="note"
      value={state.value}
      placeholder="Write a note"
      onchange={(event) => {
        state.value = event.value;
      }}
    />
    <Text>{state.value || "Nothing yet"}</Text>
  </Screen>
));

session.focus("note");

Docs Map

• docs/getting-started.md - first complete flow, from static rendering to an interactive session
• docs/core-concepts.md - mental model: ids, focus, hitboxes, plain output, ANSI, and cleanup
• docs/interaction-model.md - behavior of each primitive and interaction events
• docs/session-runtime.md - session lifecycle, streams, clipboard, coordinates, and runtime
• docs/cookbook.md - short recipes for concrete tasks
• docs/api-reference.md - reference for the public surface and published subpaths
• docs/local-demo.md - repo-local demo, not part of the published package

Published Package Scope

The published package includes the compiled adapter in dist/, this documentation, and supporting metadata. Files in examples/ live only in the repo and are not part of the distributed package.

Local Development

bun test
bun run typecheck
bun run build