Silvery

Appearance

Packages ​

Most apps only need silvery — it re-exports everything you need from the internal packages.

Public Packages ​

PackagenpmDescription
silverysilveryComponents, hooks, renderer — the one package you need
@silvery/test@silvery/testTesting utilities (virtual renderer, Playwright-style locators)
@silvery/ink@silvery/inkInk compatibility layer for migration
@silvery/create@silvery/createApp composition and state management (coming soon)

Internal Packages ​

These are implementation details — you'll only need them for advanced use cases like custom renderers or direct pipeline access.

PackagenpmDescription
@silvery/ag-react@silvery/ag-reactReact reconciler, components, and hooks
@silvery/ag-term@silvery/ag-termTerminal runtime, ANSI output, rendering pipeline
@silvery/ag-react/ui@silvery/ag-react/uiComponent library (45+ components) + CLI progress utilities
@silvery/theme@silvery/themeTheme tokens, 84 color schemes, theme CLI
@silvery/ink@silvery/inkLegacy Ink/Chalk compatibility

Import Conventions ​

Quick Start ​

Most apps import everything from silvery:

tsx
import { Box, Text, render, useBoxRect, useInput, createTerm } from "silvery"

Layered Imports ​

For fine-grained control, import from scoped packages:

tsx
// Terminal-specific APIs
import { createTerm, Pipeline } from "@silvery/ag-term"

// React reconciler and hooks
import { Box, Text, useBoxRect } from "@silvery/ag-react"

// TEA state management
import { createSlice, createStore } from "@silvery/create"

// Theme system
import { createTheme, presetTheme } from "@silvery/theme"

// Testing
import { createRenderer } from "@silvery/test"

// UI components
import { Spinner, ProgressBar, Table } from "@silvery/ag-react/ui"

Runtime Entry Points ​

tsx
// High-level app framework
import { run, createApp, useApp } from "@silvery/ag-term/runtime"

// Ink-compatible API
import { Box, Text, render } from "silvery/ink"

// Chalk-compatible styling
import chalk from "silvery/chalk"

silvery (Umbrella) ​

Re-exports everything from @silvery/ag-react. This is the primary import for most applications.

Components: Box, Text, Newline, Spacer, Static, Transform, TextInput, TextArea, SelectList, Toggle, Button, Spinner, ProgressBar, Table, Badge, Divider, VirtualList, VirtualView, Console, Image, Link, Form, FormField, Toast, CommandPalette, TreeView, Breadcrumb, Tabs, TabList, Tab, TabPanel, Tooltip, Skeleton, ErrorBoundary, ModalDialog, PickerDialog, PickerList, SplitView, ThemeProvider.

Hooks: useBoxRect, useScrollRect, useInput, useApp, useStdout, useFocus, useFocusManager, useFocusWithin, usePaste, useCursor, useAnimation, useAnimatedTransition, useScrollback, useToast.

Functions: render, renderSync, renderToString, createTerm.

@silvery/ag-term ​

Terminal runtime and rendering pipeline. Handles ANSI output, buffer management, terminal capabilities detection, and the 5-phase rendering pipeline (reconcile, measure, layout, content, output).

Key exports: createTerm, Pipeline, buffer utilities, ANSI helpers, terminal capability detection.

@silvery/ag-react ​

React reconciler adapted for terminal rendering. Provides the component model, hooks, and reconciliation logic.

@silvery/ag-react/ui ​

Component library with 45+ components plus CLI progress utilities.

CLI mode (no React needed):

ts
import { Spinner, ProgressBar } from "@silvery/ag-react/ui/cli"
const stop = Spinner.start("Loading...")

Wrapper utilities:

ts
import { withSpinner, withProgress } from "@silvery/ag-react/ui/wrappers"
const data = await withSpinner(fetchData(), "Loading...")

@silvery/create ​

App composition and state management. (Coming soon — API is in active development.)

@silvery/theme ​

Theme system with 84 color schemes, auto-generation from a single color, semantic tokens, and contrast checking.

See the Theming Guide for full documentation.

@silvery/test ​

Testing utilities with Playwright-style auto-locators, buffer assertions, and virtual rendering.

tsx
import { createRenderer } from "@silvery/test"

const render = createRenderer()
const app = render(<App />)
expect(app.text).toContain("Hello")

@silvery/ink ​

Ink and Chalk compatibility layers. Usually accessed via silvery/ink and silvery/chalk entry points rather than directly.

The Ink compat layer is decomposed into composable plugins:

PluginWhat
withInkCursor()Bridges Ink's useCursor() to silvery's CursorStore (~50 lines)
withInkFocus()Provides Ink's flat-list focus system (useFocus/useFocusManager) (~45 lines)
withInk()Convenience: composes both adapters (~10 lines)

Import from @silvery/ink/with-ink, @silvery/ink/with-ink-cursor, or @silvery/ink/with-ink-focus. Also re-exported from @silvery/create/plugins.

See Compat Layer Architecture for how the adapters bridge Ink APIs to silvery-native systems.

See Also ​