---
url: /getting-started/quick-start.md
---
# Quick Start
Polished terminal apps in React.
Silvery is a React renderer for terminal applications — use it as just a renderer, or add optional packages for a complete framework. The core API (`Box`, `Text`, `useInput`) works like other React terminal renderers. What's different: responsive layout, native scrolling, and per-node incremental rendering.
## Installation
::: code-group
```bash [bun]
bun add silvery
```
```bash [npm]
npm install silvery
```
```bash [yarn]
yarn add silvery
```
```bash [pnpm]
pnpm add silvery
```
:::
> **One package is all you need.** `silvery` includes everything to build terminal apps — components, hooks, and rendering. The `@silvery/*` scoped packages exist for advanced users who want finer-grained imports.
## Your First App
Create a file called `app.tsx`:
```tsx
import { render, Box, Text } from "silvery"
function App() {
return (
Hello from Silvery!
)
}
await render().run()
```
Run it:
```bash
bun app.tsx
# or: npx tsx app.tsx
```
You should see a rounded box with "Hello from Silvery!" inside.
> **Power users:** `render()` and `run()` are sugar over composable plugins. For full control over terminal I/O, focus, events, and commands, use `pipe()` — see [Building an App](/guides/terminal-apps).
## Responsive Layout
Components can query their own dimensions during render — no prop drilling needed:
```tsx
import { render, Box, Text, useBoxRectDangerously } from "silvery"
function SizedBox() {
const { width, height } = useBoxRectDangerously()
return (
I am {width}x{height}
)
}
function App() {
return (
)
}
await render().run()
```
Each `SizedBox` will display its actual computed dimensions. No prop threading needed!
## Interactive Lists
`SelectList` gives you keyboard-navigable selection out of the box — arrow keys, j/k, Home/End, disabled items, and scroll windowing. No manual `useInput()` or cursor state needed:
```tsx
import { render, Box, Text, SelectList } from "silvery"
function App() {
return (
Pick a framework: console.log(`Selected: ${item.value}`)}
maxVisible={5}
/>
)
}
await render().run()
```
For large datasets, use `VirtualList` with `interactive` mode — it renders only visible items and handles keyboard navigation (j/k, Page Up/Down, Home/End):
```tsx
import { render, Box, VirtualList, Text } from "silvery"
const items = Array.from({ length: 1000 }, (_, i) => `Item ${i + 1}`)
function App() {
return (
{item} }
onSelect={(index) => console.log(`Selected: ${items[index]}`)}
/>
)
}
await render().run()
```
## Next Steps
* [Components](/guides/components) -- Learn about Box, Text, and other components
* [Terminal Apps](/guides/terminal-apps) -- Build a full terminal application step by step
* [API Reference](/api/box) -- Complete API documentation
---
---
url: /getting-started/migrate-from-ink.md
description: >-
Switch an Ink 7.0 app to Silvery — drop-in @silvery/ink compat layer, then opt
into Silvery-native features at your own pace.
---
# Migrate from Ink
Silvery is a drop-in for Ink. Change one import line and your app keeps running — same `Box`, `Text`, `useInput`, `useApp`, `useFocus`, `usePaste`, `useAnimation`, `useWindowSize`, `useStdout`, `Static`. **918 of Ink 7.0's 931 tests (~98.6%) pass on the compat layer.** Then opt into Silvery-native features (responsive layout, scroll containers, mouse, find, clipboard, 45+ components) one at a time.
## The 60-second migration
::: code-group
```bash [bun]
bun remove ink && bun add silvery react
```
```bash [npm]
npm uninstall ink && npm install silvery react
```
```bash [pnpm]
pnpm remove ink && pnpm add silvery react
```
```bash [yarn]
yarn remove ink && yarn add silvery react
```
:::
Change every `from "ink"` import to `from "silvery/ink"`:
```diff
- import { Box, Text, render, useInput } from "ink"
+ import { Box, Text, render, useInput } from "silvery/ink"
```
That's it. Your app should compile and run.
If you used Chalk, swap that too:
```diff
- import chalk from "chalk"
+ import chalk from "silvery/chalk"
```
The Chalk compat layer passes **32 of 32 tests (100%)**.
## What changes (and what doesn't)
**Nothing changes about your component code.** ``, ``, `useInput`, `useFocus`, `useFocusManager`, `useApp`, `useStdout`, `useStdin`, `useAnimation`, `useWindowSize`, `useCursor`, `usePaste`, `Static`, `Transform`, `render()` — all the same names, same props, same behavior.
**What's different** — 13 intentional design choices in the compat layer:
* **W3C flexbox spec over Yoga quirks** (4 tests) — Silvery's [Flexily](https://beorn.codes/flexily) layout engine follows the W3C spec strictly. Yoga has non-standard behaviors around `flex-wrap` and `aspect-ratio` that some Ink tests expect. If you need exact Yoga parity, [Silvery supports Yoga as a pluggable layout engine](/guide/layout-engine).
* **Build artifact format** (2 tests) — Ink expects a `./build/` directory. Silvery ships TypeScript source (for Bun) plus pre-built `dist/` (for Node).
* **Minor rendering edge cases** (~7 tests) — SGR attribute emission order (dim+bold), `measureElement` timing in synchronous render, `renderToString` effect ordering. Produces identical visual output.
[Full compatibility table →](/guide/silvery-vs-ink#compatibility)
## What you gain (opt-in, when you're ready)
Once the import swap works, you can adopt Silvery-native features incrementally. None of these break your existing Ink-style code.
### Switch one component to native imports
```diff
- import { Box, Text } from "silvery/ink"
+ import { Box, Text } from "silvery"
```
The native `silvery` exports are the same `Box` and `Text` — the compat layer is a thin shim. Imports from `silvery` give you access to the broader API (`useBoxRectDangerously`, native focus, scroll containers, etc.) in the same file.
### Responsive layout — `useBoxRectDangerously()` returns real dimensions during render
In Ink, `useBoxMetrics()` returns `{ width: 0, height: 0 }` on the first render and updates via `useEffect`. That means N nesting levels = N visible flickers.
Silvery's `useBoxRectDangerously()` returns actual dimensions on the first render — no `width: 0` flash:
```tsx
import { Box, Text, useBoxRectDangerously } from "silvery"
function Card({ title }: { title: string }) {
const { width } = useBoxRectDangerously()
return (
{width >= 32 ? title : title.slice(0, width - 1) + "…"}
)
}
```
[Responsive Layout guide →](/guide/responsive-layout)
### Scroll containers — `overflow="scroll"` with virtualization
Ink core has `visible` / `hidden` only ([#222](https://github.com/vadimdemedes/ink/issues/222), open since 2019). Silvery has true scroll containers with virtualization, sticky positioning, and native arrow-key/wheel scrolling:
```tsx
```
[Scrolling guide →](/guide/scrolling) · [Sticky positioning →](/guide/layout-coordinates)
### Mouse, text selection, find, clipboard
Ink has none of these in core. Silvery ships them all:
* **Mouse events** — `onClick`, `onWheel`, drag-and-drop, hit testing. [Event Handling →](/guide/event-handling)
* **Text selection** — mouse drag, word/line selection, `userSelect` boundaries. [Text Selection →](/guide/text-selection)
* **Find** — `Ctrl+F` with match highlighting and `n`/`N` navigation. [Find guide →](/guide/find)
* **Clipboard** — OSC 52 paste/copy, `Esc, v` copy-mode for vim-style yanking. [Clipboard guide →](/guide/clipboard)
### 45+ built-in components
Ink core has 6 components. The [`@inkjs/ui`](https://github.com/vadimdemedes/ink-ui) package adds 13 more. Silvery ships 45+ in core — `SelectList`, `TextInput`, `TextArea`, `Table`, `TreeView`, `Tabs`, `CommandPalette`, `ModalDialog`, `PickerDialog`, `Toast`, `Spinner`, `ProgressBar`, `Form`, `SplitView`, and more. Every component participates in focus, mouse, and keybindings automatically.
[Components overview →](/guides/components)
### Performance — 3–27× faster on mounted rerenders
Cell-level dirty tracking, per-node skip for unchanged subtrees, cell-level buffer diff. Native scrollback preserved in inline mode. Typical interactive update on a 1000-node tree: ~169 microseconds.
[Benchmarks →](/guide/silvery-vs-ink#performance)
## What about Ink plugins?
Some Ink ecosystem packages (`ink-select-input`, `ink-text-input`, `ink-spinner`, etc.) work unchanged against `silvery/ink`. Others rely on Ink's private DOM-tree internals and may need a compat shim or replacement.
When swapping an Ink ecosystem component, check if Silvery has a native equivalent first — it usually does, and the native version is faster and more featureful.
| Ink ecosystem | Silvery native | Notes |
| ---------------------- | ------------------- | -------------------------------------------------------------------------- |
| `ink-select-input` | `SelectList` | Search, multi-select, virtualization, keyboard + mouse |
| `ink-text-input` | `TextInput` | Readline binding, full Unicode, paste, IME |
| `ink-spinner` | `Spinner` | Built-in; `Spinner.start("…")` CLI helper too |
| `ink-table` | `Table` | Responsive columns, search/filter |
| `ink-progress-bar` | `ProgressBar` | Full-featured, theme-aware |
| `ink-syntax-highlight` | `SyntaxHighlighter` | Use `languageForPath` from `@silvery/syntax` when inferring from filenames |
## Want the full feature comparison?
The [Silvery vs Ink](/guide/silvery-vs-ink) page has the full feature matrix, performance numbers, compatibility breakdown, and migration scenarios:
* [Compatibility coverage](/guide/silvery-vs-ink#compatibility) — exactly which Ink tests pass, which 13 fail and why
* [Performance & size](/guide/silvery-vs-ink#performance-size) — benchmarks for mounted rerender, cold render, bundle
* [Compat Layer Architecture](/reference/compatibility#compat-layer-architecture) — how the adapters bridge Ink APIs to silvery-native systems
## Need help?
* Open an [issue on GitHub](https://github.com/beorn/silvery/issues) — happy to look at your migration
* See [Troubleshooting](/guide/troubleshooting) for common gotchas
* Browse [Imports & Subpaths](/guide/imports) for the full mapping between `silvery`, `silvery/ink`, `silvery/chalk`, and `silvery/runtime`
---
---
url: /guide/the-silvery-way.md
---
# The Silvery Way
*How to build the shiniest Silvery apps*
Silver tarnishes when you don't take care of it. So does your code. These are the principles that keep Silvery apps **shiny** (best practices) — and the anti-patterns that let them go **tarnished** (common pitfalls).
Each principle is something people get wrong. If you're coming from Ink, Blessed, or raw ANSI — we've all been there. These patterns are natural starting points, but Silvery gives you better tools. If you're already doing the shiny thing, skip ahead.
## Three foundations
The ten principles below all flow from three broader convictions:
1. **Take the best from the web.** Flexbox, scroll containers, DOM-style events, focus scopes, Playwright-style testing, design tokens — thirty years of web UI produced ideas worth keeping. If you'd reach for it on the web, reach for it in Silvery.
2. **Stay true to the terminal.** Cells, screens, buffers, ANSI, scrollback. The terminal is the medium, and Silvery embraces it. When a feature maps onto a terminal protocol — Kitty keyboard, OSC 52 clipboard, DEC mode 2026 — we expose it honestly, not as a polyfill.
3. **Raise the bar.** For developer ergonomics, architecture composability, and performance. The ten principles below are what this looks like in practice — each one exists because a shiny path is worth building and maintaining.
## 1. Use the Built-in Components
Silvery ships 45+ components — all available from `import { ... } from "silvery"`. They handle keyboard navigation, theming, mouse support, kill ring, word movement, scroll indicators, and dozens of edge cases you haven't thought of yet. When you reimplement them, you lose all of that.
::: tip ✨ Shiny
```tsx
Are you sure?
```
All themed. All mouse-aware. All keyboard-navigable out of the box — saving you time and bugs.
:::
::: danger 🩶 Tarnished
```tsx
// Manual cursor tracking — loses j/k wrapping, mouse, scroll, selection theming
const [cursor, setCursor] = useState(0)
useInput((input) => {
if (input === "j") setCursor((c) => Math.min(c + 1, items.length - 1))
if (input === "k") setCursor((c) => Math.max(c - 1, 0))
})
// Manual text handling — no Ctrl+A/E/K/U/W, no Alt+B/F, no kill ring, no clipboard
useInput((input, key) => {
if (key.backspace) setText((t) => t.slice(0, -1))
else if (!key.ctrl) setText((t) => t + input)
})
```
You'll spend a week reimplementing what [`SelectList`](/guides/components#selectlist) and [`TextInput`](/guides/components#textinput) give you in one line.
:::
→ [Components guide](/guides/components) · [Components & hooks reference](/reference/components-hooks)
## 2. Think in Flexbox
Silvery uses CSS flexbox via [Flexily](/guide/layout-engine) — same mental model as web development. Let the layout engine compute positions and sizes. For responsive layout, reach for [`useResponsiveBoxProps`](/api/use-responsive-box-props) (declarative, no measurement reads). When you genuinely need a component's measured size, [`useBoxRectDangerously()`](/api/use-box-rect) returns the deferred (committed) rect — invariant across every convergence pass within one event batch, so layout decisions can't form feedback loops.
::: tip ✨ Shiny
```tsx
// Fill remaining space
I expand
// Spacing with gap, not margins on every child
// Responsive layout — declarative, no measurement reads.
function AppShell({ sidebar, main }) {
const layout = useResponsiveBoxProps({
default: { flexDirection: "column" },
md: { flexDirection: "row" },
})
return {main}
}
// Measured-rect decisions — when the parent's measured size is the input.
function Panel() {
const { width } = useBoxRectDangerously() // committed rect, batch-invariant
return width < 40 ? :
}
```
`flexGrow` fills space. `padding`/`paddingX` for internal spacing. `gap` between children. `justifyContent="flex-end"` pins to bottom. `useResponsiveBoxProps` for global-viewport responsive layout. `useBoxRectDangerously()` when the decision depends on the parent's measured size.
:::
::: tip ⚠ Reading layout on mount
The reactive layout hooks (`useBoxRectDangerously`, `useScrollRect`, `useScreenRect`) return the COMMITTED rect — the value as of the most recent event-batch commit. On the very first render the rect is `{0,0,0,0}`; the measured value arrives one batch later. For layout decisions that need to be correct on the first paint, prefer `useResponsiveBoxProps` — it reads the global viewport directly, no layout-pass dependency.
For framework primitives that must publish positioned terminal escapes on the same frame the host node lays out (e.g. `Image` writing Kitty graphics escapes), read `node.boxRect` from `useAgNode()` inside a `useLayoutEffect`. That's the in-flight value, written every layout pass. This is recommended only for leaf primitives in silvery itself, not application code.
:::
::: danger 🩶 Tarnished
```tsx
// Manual arithmetic — breaks on resize, breaks with padding, breaks with borders
// Fake padding with spaces
{" "}Hello{" "}
// Prop-drilling dimensions through 5 components
```
If you're doing arithmetic with widths, you're fighting the layout engine instead of using it.
:::
→ [Layout engine](/guide/layout-engine) · [Responsive layout](/guide/responsive-layout) · [useBoxRectDangerously](/api/use-box-rect) · [useResponsiveBoxProps](/api/use-responsive-box-props) · [Box](/api/box) · [Layout examples](/examples/layout)
## 3. Let the Framework Scroll
`overflow="scroll"` measures children, determines visibility, renders only what fits, responds to wheel input, and shows scroll indicators. It handles variable heights. Supplying `onWheel` replaces the default kinetic scroll owner for specialized or virtualized surfaces.
::: tip ✨ Shiny
```tsx
// Automatic scrolling — just tell it what to keep visible
{items.map((item, i) => )}
// Streaming content — chat, logs, agent output
{messages}
// Clip without scroll indicators
{longContent}
```
:::
::: danger 🩶 Tarnished
```tsx
// Manual slicing — wrong heights, no indicators, no variable-height items
const visible = items.slice(scrollOffset, scrollOffset + pageSize)
// ... 40 lines of offset tracking, boundary clamping, page-up/page-down ...
{
scrollOffset > 0 && ▲ {scrollOffset} more
}
```
Manual scroll offset tracking is the #1 source of off-by-one bugs in terminal apps. Let the framework handle it.
:::
→ [Scrolling guide](/guide/scrolling) · [Scroll regions reference](/reference/scroll-regions) · [Scrollback examples](/examples/scrollback)
## 4. Focus Control
[`silvery`](/reference/packages) provides tree-based focus with spatial navigation. Focus determines which component receives input. Without focus management, overlapping key handlers create chaos — a modal opens but the background still handles keys.
::: tip ✨ Shiny
```tsx
// Calling useFocus() registers this component in the focus tree
function SearchBox() {
const { isFocused } = useFocus() // isFocused can be used for styling
return
}
// Input layer stack — modals automatically consume input
;
{/* No guards needed — background input is automatically blocked */}
This cannot be undone.
// Programmatic focus navigation
focusNext() // Tab-like cycling
focusPrev() // Shift-Tab
setFocus(id) // Jump to specific component
```
:::
::: danger 🩶 Tarnished
```tsx
// Guard clauses in every handler — easy to forget one
useInput((input) => {
if (isDialogOpen) return // Forgot this? Background responds to keys
if (isSearching) return // Another guard
if (isPanelOpen) return // And another
// actual logic buried under guards
})
// Manual focus boolean threaded through props
```
If you're writing `if (isDialogOpen) return` in your input handlers, you don't have focus management — you have guard clauses pretending to be focus management.
:::
→ [Focus hooks](/api/use-focus) · [Input features](/reference/input-features)
## 5. Command System
Named, serializable, introspectable actions. Commands make your app automatable (AI agents invoke commands by name), testable (fire commands in tests), and discoverable ([`CommandPalette`](/guides/components#shadcn-style-components) lists them all).
> Part of [`@silvery/create`](https://www.npmjs.com/package/@silvery/create) — the optional app architecture layer. `@silvery/create` is under active development; the command system API is evolving.
::: tip ✨ Shiny
```tsx
// Declare commands with metadata
const app = withCommands({
"file.save": { label: "Save File", handler: save },
"file.open": { label: "Open File", handler: open },
"view.toggle-sidebar": { label: "Toggle Sidebar", handler: toggleSidebar },
})
// Keybindings reference command names
withKeybindings({
"ctrl+s": "file.save",
"ctrl+o": "file.open",
"ctrl+b": "view.toggle-sidebar",
})
// AI agent can invoke by name
agent.executeCommand("file.save")
// All commands discoverable via palette
```
:::
::: danger 🩶 Tarnished
```tsx
// Anonymous handlers — can't list, can't replay, can't automate
useInput((input, key) => {
if (key.ctrl && input === "s") save()
if (key.ctrl && input === "o") open()
if (key.ctrl && input === "b") toggleSidebar()
})
// AI agent forced to simulate keypresses
// No way to list available actions
// No command palette possible
```
Keybindings are a UI detail. Commands are the API. Build on commands; bind keys to them.
:::
→ [Event handling](/guide/event-handling)
## 6. Style using Design Tokens
Components express semantic intent — color, hierarchy, state — via **tokens and presets**. The token system decides the concrete rendering details: which hex value, which SGR attributes, which tier-appropriate fallback. Components never reach for raw rendering primitives (hex colors, ANSI escapes, or SGR modifiers like `dim` / `bold` / `italic` / `underline`).
[`silvery/theme`](/reference/packages) auto-detects your terminal's palette via OSC queries — no configuration needed. [Sterling](/reference/sterling) — silvery's canonical design system — derives nested roles + flat tokens (`$fg-accent`, `$fg-muted`, `$bg-surface-*`, `$border-focus`, …) plus typography presets that adapt to every terminal theme. 84 color schemes (Catppuccin, Nord, Dracula, Tokyo Night, Solarized, …) work automatically.
### Why not SGR in components
Terminal SGR codes (`bold`, `dim`, `italic`, `underline`, `inverse`, `strikethrough`) have **uneven support** across emulators — `dim` does alpha-blending on some, intensity-reduction on others, nothing on older terminals. `bold` sometimes brightens color, sometimes only affects font weight. Writing these in components guarantees inconsistent results.
Tokens avoid this. At truecolor, `$fg-muted` resolves to a specific pre-dimmed hex — deterministic on any terminal. At ANSI 16 where we can't express intermediate intensities, the renderer emits SGR 2 as a necessary concession. Components never make that choice; derivation does.
::: tip ✨ Shiny
```tsx
// Semantic tokens — adapt to any theme automatically
Selected item✓ Saved✗ FailedLast modified 2h ago
// Typography presets — semantic intent, not manual attrs
Page title
// $fg-accent + bold (composed by preset)
urgent // bold
aside // italic
fine print // pre-dimmed $fg-muted at truecolor
clickable // $fg-link + brightened, underlined hover affordance
// Status indicators: shape + color (colorblind-safe)
✓ // done
○ // pending
✗ // failed
```
:::
### Interactive treatments are semantic too
Use the shared interaction language instead of assembling hover colors at the call site:
```tsx
const interaction = useInteractionTreatment("control", "surfaceHover")
Open
```
Roles own reveal policy: content links reveal their destination on Cmd/Super-hover, controls reveal on plain hover, and regions reveal on plain hover with a structural gutter cue. `` and action-only `` derive the first two roles automatically, while both gain `$fg-link-hover` plus an underline on plain hover. An explicit `underline` choice wins. Use `` for a self-contained regional treatment, or pass `interactionTreatment` when a parent owns the hover state.
Named surfaces are the normal path. Exported recipe factories such as `actionFill()`, `textPair()`, `cardOutline()`, and `togglePillSurface()` centralize parameterized families; only genuinely runtime-computed visuals use `customInteractionSurface()`. Raw surface objects are rejected by the resolver types so a new one-off treatment cannot silently reintroduce the old pattern.
`DocumentView` also resolves style precedence semantically. A heading's
structural foreground wins over element foregrounds inside it, while link
decoration remains visible through the `link` typography variant's dotted
underline. A selected block's background wins over nested element backgrounds
such as inline code. Adapters provide semantic blocks and inline elements; they
do not manually reapply heading or selection colors.
::: danger 🩶 Tarnished
```tsx
// Hardcoded colors — wrong in light themes, wrong in high-contrast
ErrorError
// ANSI escapes in strings — bypasses the theme entirely
console.log("\x1b[31;1mError\x1b[0m")
// Raw SGR attrs in component code — unreliable across terminals
Last modified 2h ago // → use $fg-muted or
Warning // → use
or semantic token
aside // → use
// Manual composition of tokens with attrs — double trouble
Fine print // → use
// Color-only status (colorblind users can't distinguish)
● // done? pending? who knows without color
```
Hardcoded colors marry one theme. Raw SGR marries whatever that specific terminal does with SGR 2 and SGR 1. **Semantic tokens and typography presets marry them all.**
:::
→ [Styling guide](/guide/styling) · [Theming reference](/guide/styling) · [Themes gallery](/themes)
## 7. Compose with Factory Functions
Classes encourage hidden state and rigid hierarchies. Factory functions return plain objects with explicit deps — composable, testable, swappable.
::: tip ✨ Shiny
```tsx
// render() takes explicit deps — term is optional, options are plain objects
const app = render(, term, { incremental: true })
// createRenderer() for tests — explicit config, no global state
const render = createRenderer({ cols: 80, rows: 24 })
const app = render()
expect(app.text).toContain("Hello")
```
With `@silvery/create`, this extends to app-level composition via `pipe()`:
```tsx
// Each function adds a capability — explicit, composable, no inheritance
const app = pipe(createApp(), withFocus(), withDomEvents(), withCommands(opts))
```
:::
::: danger 🩶 Tarnished
```tsx
// Class hierarchy — rigid, hard to test, hard to compose
class MyApp extends BaseApp {
constructor() {
super() // What does this do? Who knows
this.state = {} // Hidden mutable state
}
}
// Global singletons — untestable, can't run two instances
const app = GlobalApp.getInstance()
```
Composition scales. Inheritance doesn't.
:::
→ [Plugins](/reference/plugins)
## 8. Compose and Clean Up with `using`
Silvery uses factory functions that return disposable objects. `using` (TC39 Explicit Resource Management) ties their lifetime to scope — no leaked terminals, no orphaned processes, no hung event loops. Composition and cleanup are the same pattern: build up resources, and `using` tears them down in reverse order.
::: tip ✨ Shiny
```tsx
// Compose resources — each one is automatically cleaned up on any exit
using term = createTerm()
term.console?.capture({ suppress: true }) // redirect console.log into term's buffer
using app = render(, term)
await app.run()
// On exit (success, error, Ctrl+C):
// 1. app unmounted 2. term.console restored + term sub-owners disposed
// Reverse order, guaranteed, every path
```
:::
::: danger 🩶 Tarnished
```tsx
// Manual cleanup — forgotten in error paths, Ctrl+C leaves terminal broken
const term = createTerm()
const console = patchConsole(term)
try {
const app = render(, term)
await app.run()
} finally {
console.dispose() // Did you remember both?
term.dispose() // In the right order?
}
```
`using` is one keyword per resource. Manual cleanup is a bug waiting to happen.
:::
Silvery objects that support `using`:
| Object | What it cleans up |
| -------------------------------------------- | -------------------------------------------------- |
| `createTerm()` | Restores terminal mode, cursor, alternate screen |
| `render()` / `app.run()` | Unmounts React tree, stops event loop |
| `createScope()` | Cancels child tasks, clears timers |
| `createEditContext()` | Releases input layer bindings |
| `term.console.capture()` (on `createTerm()`) | Restores original console methods via term dispose |
| `Spinner` / `ProgressBar` / `MultiProgress` | Stops animation, clears interval |
| `createScreenshot()` | Closes screenshot file handle |
The pattern extends to your own code — any factory that returns `{ [Symbol.dispose]() { ... } }` works with `using`. Silvery's plugin composition (`pipe()`, `withScope()`) uses the same mechanism internally.
→ [render()](/api/render) · [Lifecycle](/reference/lifecycle)
## 9. Gradually Sip TEA
Simple apps work great with `useState` and `useInput`. But as complexity grows — undo/redo, customizable keybindings, command palettes, collaborative editing, AI-driven automation — you need structured state management. Silvery makes this graduation seamless.
The idea: [The Elm Architecture](https://guide.elm-lang.org/architecture/) models every interaction as `(action, state) → [state, effects]`. Actions are data (serializable, replayable, undoable). Effects are data (testable, interceptable). You adopt it gradually — no big rewrite, just replace one `setState` at a time.
::: tip ✨ Shiny — sip at your own pace
```tsx
// Level 1: useState + useInput — just React, nothing extra
const [count, setCount] = useState(0)
useInput((input) => {
if (input === "j") setCount((c) => c + 1)
})
// Level 2: useReducer — actions as data, one step toward TEA
const [state, dispatch] = useReducer(reducer, initialState)
// Now you can log actions, replay them, test the reducer in isolation
// Level 3: Zustand / external store — shared state across components
// Level 4: @silvery/create — commands, keybindings, effects-as-data (coming soon)
```
Each level works independently. Some apps never need more than `useState`. Others need undo from day one — start at Level 2. The framework doesn't force a choice; it makes graduation painless.
:::
**When to graduate:**
* **Need undo/redo?** → actions as data (Level 2+)
* **Need customizable keybindings?** → named commands (Level 4)
* **Need a command palette?** → discoverable command registry (Level 4)
* **Need replay/recording?** → serializable actions + effects (Level 4)
* **Need AI automation?** → commands as a tool surface (Level 4)
::: warning Coming Soon
`@silvery/create` (Level 4 — commands, keybindings, composable plugins) is under active development. Levels 1-3 work today with any React state library.
:::
## 10. Test Against What the User Sees
[`@silvery/test`](/reference/packages) gives you headless rendering with Playwright-style locators. State assertions pass while the screen is garbled — `selectedIndex === 2` doesn't catch the selection rendering on the wrong row, or the border overlapping content, or the scroll indicator showing the wrong count. Test what the user actually sees.
For full ANSI verification (colors, cursor positioning, scrollback), use [Termless](https://termless.dev) — headless terminal testing, like Playwright for terminals. It runs a real terminal emulator in-process so you can assert on exactly what would appear on screen, including escape sequences and wide characters. See [terminfo.dev](https://terminfo.dev) for how different terminals handle the same sequences — useful when your app needs to work across Ghostty, iTerm2, Windows Terminal, and more.
::: tip ✨ Shiny
```tsx
// Headless rendering with Playwright-style locators
const app = createRenderer()
app.press("j")
app.press("j")
expect(app.text).toContain("▶ Third item") // What the user sees
// Full buffer assertions — catches rendering bugs
expect(app.getByText("Third item")).toHaveStyle({ inverse: true })
// Resize the virtual terminal — test responsive layouts
app.resize(40, 10) // narrow terminal
expect(app.text).not.toContain("Sidebar") // collapsed at small widths
app.resize(120, 40) // wide terminal
expect(app.text).toContain("Sidebar") // visible again
// Inspect the scrollback buffer — chat apps, logs, streaming output
// Content that scrolled off-screen is still in the buffer
expect(app.scrollback).toContain("Message from 10 minutes ago")
```
Things you can't easily test any other way: terminal resize behavior, scrollback buffer contents, incremental rendering correctness.
:::
::: danger 🩶 Tarnished
```tsx
// State-only test — passes even if rendering is broken
expect(store.getState().selectedIndex).toBe(2)
// Screen could show index 0 selected. Test still passes.
// Snapshot of ANSI strings — brittle, unreadable diffs
expect(output).toMatchInlineSnapshot(`"\u001b[1m\u001b[34m..."`)
// Manual resize testing — drag the terminal corner, squint at the output
// "Looks fine to me" — until it doesn't, and you can't reproduce the bug
// Manual scrollback checking — scroll up, visually scan for the right line
// Hope you remember what it's supposed to look like
```
Manual visual testing is slow, unrepeatable, and doesn't catch regressions. If you're resizing your terminal by hand to check layouts, that's a test you should automate.
:::
→ [Testing guide](/guide/testing) · [Testing examples](/examples/testing) · [Termless](https://termless.dev) · [terminfo.dev](https://terminfo.dev)
## 11. Let the Term Own I/O
Silvery owns terminal I/O. `Term` is the umbrella, and each class of shared-global state has a typed sub-owner — set once at session start, restored once on dispose, never toggled mid-flight by app code. When you reach for `process.stdin` or `process.stdout` directly, you're racing every other tenant in the session.
::: tip ✨ Shiny
```tsx
using term = createTerm()
// Raw mode, alt screen, bracketed paste — one authority, reactive signals
term.modes.altScreen(true)
term.modes.rawMode(true)
term.modes.bracketedPaste(true)
// Dimensions — live reads, coalesced reactive subscriptions via effect()
const { cols, rows } = term.size.snapshot()
effect(() => relayout(term.size.cols(), term.size.rows()))
// Terminal query — probe through the owner, no stdin-wrestling
const bg = await term.input?.probe({
query: "\x1b]11;?\x07",
parse: parseOsc11,
timeoutMs: 50,
})
// Capture stray console.log so it doesn't corrupt the alt screen
term.console?.capture({ suppress: true })
```
One owner per resource. Race-free by construction.
:::
::: danger 🩶 Tarnished
```tsx
// ❌ wasRaw capture/restore — races under async, kills the host TUI
const wasRaw = process.stdin.isRaw
if (!wasRaw) process.stdin.setRawMode(true)
try {
await doProbe()
} finally {
if (!wasRaw) process.stdin.setRawMode(false) // undoes whatever ran during the await
}
// ❌ Direct stdout dimensions — stale under concurrent resize, no coalescing
const cols = process.stdout.columns
process.stdout.on("resize", () => relayout(process.stdout.columns, process.stdout.rows))
// ❌ Ad-hoc mode toggles — scattered ownership, unreliable restore on crash
process.stdout.write("\x1b[?1049h") // enter alt screen
process.stdout.write("\x1b[?1003h\x1b[?1006h") // enable mouse
// …forgot the disable sequences on one of the error paths, terminal is broken
```
The fix is not "be more careful with capture/restore." It's "have one owner per resource." See [Term — the I/O umbrella](/reference/term).
:::
→ [Term — the I/O umbrella](/reference/term) · [term.input](/api/term-input) · [term.output](/api/term-output) · [term.modes](/api/term-modes) · [term.size](/api/term-size) · [term.console](/api/term-console)
## The Silvery Way, at a Glance
1. **Use the built-in components** — don't reimplement what silvery already ships
2. **Think in flexbox** — let the layout engine do the math
3. **Let the framework scroll** — `overflow="scroll"`, not manual slicing
4. **Control focus** — use the focus tree, not guard clauses
5. **Use the command system** — named actions, not anonymous handlers
6. **Use semantic theme colors** — `$tokens`, not hardcoded values
7. **Compose with factory functions** — `pipe()`, not class hierarchies
8. **Compose and clean up with `using`** — factory functions + scope-bound lifetime
9. **Gradually sip TEA** — hooks → reducer → store → @silvery/create, at your own pace
10. **Test what the user sees** — render the buffer, not just the state
11. **Let the Term own I/O** — sub-owners, not `process.stdin`/`stdout`
Keep it shiny. ✨
---
---
url: /guides/components.md
---
# Components
Silvery provides layout, text, input, and display components for building terminal UIs.
## Box
The primary layout component. Uses CSS flexbox for layout.
```tsx
import { Box, Text } from "silvery"
function Layout() {
return (
LeftRight
)
}
```
### Scrolling
Use `overflow="scroll"` with `scrollTo` for automatic scrolling:
```tsx
{items.map((item, i) => (
{item}
))}
```
See [Scrolling Guide](/guide/scrolling) for details.
### Props
| Prop | Type | Default | Description |
| ---------------- | ----------------------------------------------------------------------------- | -------------- | --------------------------- |
| `flexDirection` | `"row" \| "column" \| "row-reverse" \| "column-reverse"` | `"row"` | Main axis direction |
| `flexGrow` | `number` | `0` | Grow factor |
| `flexShrink` | `number` | `1` | Shrink factor |
| `flexBasis` | `number \| string` | - | Initial size |
| `justifyContent` | `"flex-start" \| "flex-end" \| "center" \| "space-between" \| "space-around"` | `"flex-start"` | Main axis alignment |
| `alignItems` | `"flex-start" \| "flex-end" \| "center" \| "stretch"` | `"stretch"` | Cross axis alignment |
| `padding` | `number` | `0` | Padding on all sides |
| `paddingX` | `number` | `0` | Horizontal padding |
| `paddingY` | `number` | `0` | Vertical padding |
| `margin` | `number` | `0` | Margin on all sides |
| `width` | `number \| string` | - | Fixed or percentage width |
| `height` | `number \| string` | - | Fixed or percentage height |
| `minWidth` | `number` | - | Minimum width |
| `minHeight` | `number` | - | Minimum height |
| `borderStyle` | `"single" \| "double" \| "round" \| "bold" \| "classic"` | - | Border style |
| `borderColor` | `string` | - | Border color |
| `overflow` | `"visible" \| "hidden" \| "scroll"` | `"visible"` | Overflow behavior |
| `scrollTo` | `number` | - | Child index to keep visible |
## Text
Renders text with styling. Supports Chalk strings.
```tsx
import { Text } from "silvery"
import chalk from "chalk"
// Basic styling
Success!
// Chalk strings work too
{chalk.red.bold("Error!")}
```
### Auto-Truncation
Text automatically truncates to fit available width:
```tsx
This is a very long text that will be truncated
// Output: "This is a very lon…"
```
Opt out with `wrap={false}` if you need overflow behavior.
### Props
| Prop | Type | Default | Description |
| ----------------- | --------------------------------------------------------------------------------- | ------------ | -------------------------- |
| `color` | `string` | - | Text color |
| `backgroundColor` | `string` | - | Background color |
| `bold` | `boolean` | `false` | Bold text |
| `italic` | `boolean` | `false` | Italic text |
| `underline` | `boolean` | `false` | Underlined text |
| `strikethrough` | `boolean` | `false` | Strikethrough text |
| `dimColor` | `boolean` | `false` | Dimmed color |
| `inverse` | `boolean` | `false` | Swap foreground/background |
| `wrap` | `"wrap" \| "truncate" \| "truncate-start" \| "truncate-middle" \| "truncate-end"` | `"truncate"` | Text wrapping behavior |
## Newline
Renders a newline character.
```tsx
import { Newline, Text } from "silvery"
Line 1Line 2
```
## Spacer
Flexible space that expands to fill available room.
```tsx
import { Box, Spacer, Text } from "silvery"
function Layout() {
return (
LeftRight
)
}
```
## Static
Renders content that won't be updated. Useful for logs or output that scrolls up.
```tsx
import { Static, Box, Text } from "silvery"
function App() {
const [logs, setLogs] = useState([])
return (
{(log, i) => {log}}Current status...
)
}
```
### Props
| Prop | Type | Description |
| ---------- | --------------------------------------- | ------------------------ |
| `items` | `T[]` | Array of items to render |
| `children` | `(item: T, index: number) => ReactNode` | Render function |
## Input Components
### TextInput
Single-line text input with full readline shortcuts (Ctrl+A/E, Ctrl+K/U, Alt+B/F, Ctrl+Y with kill ring).
```tsx
import { TextInput } from "silvery"
function MyInput() {
return (
)
}
```
### TextArea
Multi-line text editing with cursor navigation, line wrapping, and text selection.
```tsx
import { TextArea } from "silvery"
function MyEditor() {
return (
)
}
```
| Prop | Type | Default | Description |
| -------------- | ----------------------------------------- | -------------- | ----------------------------------------------- |
| `value` | `string` | - | Current value (controlled) |
| `defaultValue` | `string` | - | Initial value (uncontrolled) |
| `onChange` | `(value: string) => void` | - | Called when value changes |
| `onSubmit` | `(value: string) => void` | - | Called on submit key press |
| `submitKey` | `"ctrl+enter" \| "enter" \| "meta+enter"` | `"ctrl+enter"` | Key combo to trigger submit |
| `height` | `number` | **required** | Visible height in rows |
| `placeholder` | `string` | - | Placeholder text when empty |
| `isActive` | `boolean` | - | Override focus system |
| `cursorStyle` | `"block" \| "underline"` | `"block"` | Unfocused cursor style |
| `scrollMargin` | `number` | `1` | Context lines above/below cursor when scrolling |
| `disabled` | `boolean` | `false` | Ignore input and dim text |
| `maxLength` | `number` | - | Maximum character count |
| `testID` | `string` | - | Test ID for focus system |
Features: Shift+Arrow selection, Ctrl+A select all, Ctrl+Home/End document navigation, word-wise movement (Ctrl+Arrow), readline shortcuts (Ctrl+K/U/Y), column memory for vertical movement.
### SelectList
Single-select list with keyboard navigation (arrow keys, j/k, Home/End), disabled item support, and `maxVisible` for scroll windowing.
```tsx
import { SelectList } from "silvery"
function MyList() {
return (
console.log(item.value)}
/>
)
}
```
### Toggle, Button
Simple interactive primitives for boolean toggles and clickable buttons.
## Display Components
| Component | Description |
| ------------- | -------------------------------------------------------------------------------------------- |
| `Spinner` | Animated spinner with presets (dots, line, arc, bounce) |
| `ProgressBar` | Determinate and indeterminate progress with custom fill |
| `Table` | Column-aligned table with header, per-column alignment |
| `Badge` | Styled label/tag |
| `Divider` | Horizontal rule |
| `VirtualList` | O(1) scroll for thousands of items — see [List Components](/guide/scrolling#list-components) |
| `VirtualView` | Virtualized arbitrary content |
| `Console` | Captures `console.log` output via `patchConsole()` |
| `Transform` | Per-line string transformation on children |
| `Image` | Kitty graphics / Sixel with text fallback |
| `Link` | OSC 8 hyperlink |
## Shadcn-Style Components
Higher-level pre-styled components using `$token` semantic colors. Import from `silvery`:
| Component | Description |
| --------------------------------------- | ---------------------------------------------------------------- |
| `Form` / `FormField` | Form layout with label, description, error message |
| `Toast` / `useToast()` | Auto-dismiss notifications with severity levels |
| `CommandPalette` | Fuzzy-search command palette (Ctrl+K pattern) |
| `TreeView` | Expandable/collapsible tree with keyboard navigation |
| `Breadcrumb` | Actionable path trail with mouse, keyboard, and focus navigation |
| `SyntaxHighlighter` | Shiki-backed live source-code presentation |
| `Tabs` / `TabList` / `Tab` / `TabPanel` | Tabbed interface with keyboard navigation |
| `Tooltip` | Contextual tooltip overlay |
| `Skeleton` | Loading placeholder with configurable width/lines |
| `ErrorBoundary` | React error boundary with `resetKeys` and `fallback` |
| `ModalDialog` | Modal overlay with focus trapping |
| `PickerDialog` / `PickerList` | Selection dialog |
These components use the theming system — wrap your app in `ThemeProvider` with `defaultDarkTheme` or `defaultLightTheme` and the components will use semantic colors automatically. Any color prop starting with `$` is resolved against the active theme (e.g. `color="$primary"`, `backgroundColor="$surface-bg"`).
## @silvery/ag-react/ui — Progress & Input Package
`@silvery/ag-react/ui` is a separate package with progress indicators and ergonomic async wrappers. It works both as standalone CLI output (no React) and as React components inside Silvery apps.
::: code-group
```bash [npm]
npm install @silvery/ag-react/ui
```
```bash [bun]
bun add @silvery/ag-react/ui
```
```bash [pnpm]
pnpm add @silvery/ag-react/ui
```
```bash [yarn]
yarn add @silvery/ag-react/ui
```
:::
**CLI mode** (direct stdout, no React):
```ts
import { Spinner, ProgressBar, MultiProgress } from "@silvery/ag-react/ui/cli"
const stop = Spinner.start("Loading...")
await doWork()
stop()
```
**Wrappers** (ergonomic async adapters):
```ts
import { withSpinner, withProgress } from "@silvery/ag-react/ui/wrappers"
const data = await withSpinner(fetchData(), "Loading data...")
```
**Declarative steps**:
```ts
import { steps } from "@silvery/ag-react/ui/progress"
const loader = steps({ loadModules, parseConfig, validate })
await loader.run({ clear: true })
```
**React components** (for Silvery/Ink apps):
```tsx
import { Spinner, ProgressBar, Tasks, Task } from "@silvery/ag-react/ui/react"
import { TextInput, SelectList } from "silvery"
```
See the [@silvery/ag-react/ui README](https://github.com/beorn/silvery/tree/main/packages/ag-react/src/ui) for full documentation.
---
---
url: /guides/terminal-apps.md
---
# Terminal Apps
Every level in this guide turns something invisible into data. Local state hides transitions inside function calls. Callbacks hide what the user intended. Each level you adopt makes one more category of hidden behavior visible — as serializable, inspectable, testable data. You adopt each level only when you need it, never rewrite, and never pay for what you don't use.
The app evolves: Counter → Todo list → Board. At each level, both state management and event handling advance together — because in a real app, they're inseparable.
| Level | App | State | Events | What becomes data |
| ------------------------------------- | ----------------------- | ------------------------------------------- | ------------------------------------------- | ------------------------------- |
| **1 — Starting Simple** | Counter | `useState` | `useInput` callback | *(nothing yet)* |
| **2 — Shared State + Spatial Events** | Todo list | `createApp`/Zustand store | `withDomEvents()` — onClick, onKeyDown | Shared state, spatial targeting |
| **3 — Everything is Data** | Board | `createSlice` + ops-as-data | `withCommands` — named serializable actions | State transitions + user intent |
| **4 — Pure Functions** | Board + I/O | Effects as data (return `[state, effects]`) | Custom plugins (vim modes, file watchers) | Side effects + event processing |
| **5 — Composable Machines** | Board + Dialog + Search | Multiple slices, dispatch effects | Plugin composition (`pipe()`) | Cross-module communication |
::: tip Start at Level 1
Most apps only need Levels 1-2. Levels 3-5 are for apps that need undo, AI automation, or multi-pane composition — most apps never need them. Start simple and advance only when you feel a specific pain.
:::
The patterns are general — ops as data, effects as data, composable state machines work in any React framework. You arrive there incrementally — one step at a time.
## Level 1: Starting Simple
You're building a counter. One component, one piece of state, one input handler. This is React at its simplest.
```tsx
import { useState } from "react"
import { Text } from "silvery"
import { run, useInput } from "silvery/runtime"
function Counter() {
const [count, setCount] = useState(0)
useInput((input) => {
if (input === "j") setCount((c) => c + 1)
if (input === "k") setCount((c) => c - 1)
})
return Count: {count}
}
await run()
```
```
Count: 0
```
Press `j` a few times:
```
Count: 3
```
`useState` is standard React. `useInput` is Silvery's keyboard hook — a callback that receives raw key data; `run` starts the app and manages terminal I/O.
At Level 1, state lives inside a component and input handling is a function call — both invisible to everything outside this component.
**The wall**: A second component needs the same state — and threading it through props means every intermediate component has to know about data it doesn't use. And you want click targets — but `useInput` doesn't know about spatial coordinates.
## Level 2: Shared State + Spatial Events
The counter grows into a todo list. You add a sidebar that shows how many items are done, and suddenly two components need the same data. Meanwhile, you want clickable items — `` like React DOM.
### Shared store
The standard solution is a shared store. [Zustand](https://github.com/pmndrs/zustand) is a great fit — lightweight, hook-based, no boilerplate. You put state and actions in one object, and components subscribe to only the slices they care about.
The double-arrow `() => (set, get) => ({...})` is Zustand's [state creator](https://github.com/pmndrs/zustand#updating-state) pattern — `set` merges new state, `get` reads current state:
```tsx
import { Box, Text } from "silvery"
import { createApp, useApp } from "silvery/runtime"
const clamp = (v: number, min: number, max: number) => Math.max(min, Math.min(v, max))
const app = createApp(
() => (set, get) => ({
cursor: 0,
items: [
{ id: "1", text: "Buy milk", done: false },
{ id: "2", text: "Write docs", done: true },
{ id: "3", text: "Fix bug", done: false },
],
moveCursor(delta: number) {
set((s) => ({ cursor: clamp(s.cursor + delta, 0, s.items.length - 1) }))
},
toggleDone() {
set((s) => ({
items: s.items.map((item, i) => (i === s.cursor ? { ...item, done: !item.done } : item)),
}))
},
}),
{
key(input, key, { store }) {
if (input === "j") store.moveCursor(1)
if (input === "k") store.moveCursor(-1)
if (input === "x") store.toggleDone()
if (input === "q") return "exit"
},
},
)
```
Components access the store via `useApp(selector)`. Selectors are a widespread pattern — Redux, Zustand, MobX, Recoil all use them. The idea: a function that extracts the slice of state a component cares about. Zustand tracks which slice each component selected and only re-renders when that slice changes:
```tsx
function TodoList() {
const cursor = useApp((s) => s.cursor)
const items = useApp((s) => s.items)
return (
{items.map((item, i) => (
{cursor === i ? "> " : " "}
{item.done ? "[x] " : "[ ] "}
{item.text}
))}
)
}
function StatusBar() {
const items = useApp((s) => s.items)
const done = items.filter((i) => i.done).length
return (
{done}/{items.length} done
)
}
await app.run(
,
)
```
```
> [ ] Buy milk
[x] Write docs
[ ] Fix bug
1/3 done
```
> **Why Zustand over React Context?** Context re-renders every consumer when *any* part changes. Zustand only re-renders components whose selected slice actually changed — critical for high-frequency updates like cursor movement and typing.
> **Silvery:** `createApp()` is a Zustand middleware that bundles the store with centralized key handling, terminal I/O, and exit handling into a single `app.run()` call.
### Component event handlers
The `withDomEvents()` plugin adds React-style event handlers to Silvery components. Events bubble up the tree, components can stop propagation, and hit testing maps mouse coordinates to nodes:
```tsx
import { pipe, withDomEvents, withReact } from "@silvery/create/plugins"
function ItemList() {
const items = useApp((s) => s.items)
const cursor = useApp((s) => s.cursor)
return (
{items.map((item, i) => (
store.setCursor(i)}
onDoubleClick={() => store.startEdit(i)}
>
{i === cursor ? "> " : " "}
{item.text}
))}
)
}
const app = pipe(createApp(store), withReact(), withDomEvents())
```
`withDomEvents()` intercepts events before the base handler. Keyboard events dispatch through the focus tree (capture → target → bubble). Mouse events are hit-tested against the render tree — the deepest node at `(x, y)` receives the event, which bubbles up through ancestors. Same event model as React DOM: `onClick`, `onDoubleClick`, `onMouseDown`, `onMouseUp`, `onMouseMove`, `onMouseEnter`, `onMouseLeave`, `onWheel`, `onKeyDown`, `onKeyDownCapture`.
State is shared and renders are efficient. Clicks resolve to components and events bubble. But the transitions and handlers are still invisible.
**The wall**: You want undo — but `store.toggleDone()` mutated state and vanished. You want customizable keybindings — but `onClick={() => selectCard()}` has no name to show in a command palette, no binding to remap. Both problems have the same root: behavior is function calls that execute and disappear. You need to turn behavior into data.
::: warning Coming Soon
Levels 3-5 below document the Silvertea app architecture, which is currently in development. For now, use `useState`, `useReducer`, or Zustand for state management. The APIs shown below will ship in a future release.
:::
## Level 3: Everything is Data
This is the level where Silvery's architecture clicks. Two invisible things become data at once — because they're the same insight applied to two domains.
### State side: ops as data
In Level 2, store methods are function calls that mutate and disappear. **The fix**: turn operations into data. Instead of calling functions that mutate state, call functions that produce a serializable description of *what happened*:
```tsx
store.apply({ op: "moveCursor", delta: 1 })
store.apply({ op: "toggleDone", index: 2 })
```
These are just JSON — plain objects you can inspect, store, and manipulate. Once operations are data:
* **Undo/redo** — push ops onto a stack, pop to undo
* **Collaboration** — send ops over the wire
* **Time-travel debugging** — record every op, scrub through history
* **AI automation** — ops are structured data an LLM can emit
* **Testing** — assert on what ops were produced, not on internal state mutations
Silvery provides `createSlice` — you write only the handlers, it infers the op union from your handler names and parameter types:
```tsx
import { createSlice } from "@silvery/create/core"
const TodoList = createSlice(
() => ({ cursor: signal(0), items: signal([...]) }),
{
moveCursor(s, { delta }: { delta: number }) {
s.cursor.value = clamp(s.cursor.value + delta, 0, s.items.value.length - 1)
},
toggleDone(s, { index }: { index: number }) {
s.items.value = s.items.value.map((item, i) =>
i === index ? { ...item, done: !item.done } : item
)
},
},
)
type TodoOp = typeof TodoList.Op
// { op: "moveCursor"; delta: number } | { op: "toggleDone"; index: number }
```
Now undo is trivial — define an `inverse` function that returns the op which would undo a given op:
```tsx
function inverse(op: TodoOp): TodoOp {
switch (op.op) {
case "moveCursor":
return { op: "moveCursor", delta: -op.delta }
case "toggleDone":
return op // toggling is its own inverse
}
}
const undoStack: TodoOp[] = []
function applyWithUndo(op: TodoOp) {
undoStack.push(inverse(op))
TodoList.apply(state, op)
}
```
TypeScript's exhaustive narrowing ensures every op has an inverse — add an op to `createSlice` and forget to handle it in `inverse`, the compiler tells you.
### Event side: commands
Meanwhile, event handlers have the same problem. `if (input === "j") moveCursor(1)` is a function call — there's no data to serialize, no name for a command palette, no binding to remap.
**The fix**: turn input into named, serializable commands. Declare that `j` maps to the command `cursor_down`, and `cursor_down` produces the action `{ op: "moveCursor", delta: 1 }`:
```tsx
import {
pipe,
withDomEvents,
withCommands,
withReact,
createCommandRegistry,
} from "@silvery/create/plugins"
const registry = createCommandRegistry({
cursor_down: {
name: "Move Down",
execute: (ctx) => ({ op: "moveCursor", delta: 1 }),
},
cursor_up: {
name: "Move Up",
execute: (ctx) => ({ op: "moveCursor", delta: -1 }),
},
toggle_done: {
name: "Toggle Done",
execute: (ctx) => ({ op: "toggleDone", index: ctx.cursor }),
},
select_node: {
name: "Select",
execute: (ctx) => ({ op: "select", nodeId: ctx.clickedNodeId }),
},
})
const app = pipe(
createApp(store),
withReact(),
withDomEvents(),
withCommands({
registry,
getContext: () => buildContext(store),
handleAction: (action) => store.apply(action),
bindings: {
key: { j: "cursor_down", k: "cursor_up", x: "toggle_done" },
mouse: {
click: (node) => "select_node",
doubleClick: () => "enter_edit",
},
},
}),
)
```
Once input is data:
* **Customizable keybindings** — the binding table is data, users can remap
* **Command palette** — `app.cmd.all()` lists every command with name, description, and current keys
* **AI automation** — `await app.cmd.cursor_down()` drives the app programmatically
* **Mouse commands** — clicks resolve to the same named actions as keys
### Same insight, both sides
Notice the pattern: Level 2 had function calls on both sides — `store.toggleDone()` and `onClick={() => selectCard()}`. Level 3 turns both into data — ops describe state changes, commands describe user intent. Both are serializable, inspectable, replayable.
Together they make the entire app automatable: commands describe input, ops describe state changes. The pipeline is now visible end to end:
```
keypress/click → command → op → state change → screen
```
The driver pattern makes this concrete for testing and AI:
```tsx
const driver = pipe(app, withKeybindings(bindings), withDiagnostics())
driver.cmd.all() // list available commands
await driver.cmd.cursor_down() // execute by name
driver.getState() // inspect state
```
### Hybrid: components + commands
Component handlers and commands coexist naturally. `withDomEvents()` fires first; if a component handles an event (stopPropagation), commands never see it. Unhandled events fall through to command resolution. `TextInput` handles its own keys via `onKeyDown`, while navigation and actions go through commands.
Behavior is data now — serializable, reversible, replayable on both the state and event sides. But our domain functions still perform I/O directly.
**The wall**: You want to test `toggleDone` — but it calls `fs.writeFile()` and `showToast()` directly. You want vim-style modal input — but the built-in command resolution is single-key. Both sides need the same thing: make the processing itself visible.
## Level 4: Pure Functions
### State side: effects as data
In Level 3, state transitions are visible — but functions still perform I/O directly. **The fix** is the same trick: make effects into data. Instead of *doing* I/O, domain functions *describe* what should happen:
```tsx
type Effect =
| { effect: "persist"; data: unknown }
| { effect: "toast"; message: string }
const TodoList = createSlice(
() => ({ cursor: signal(0), items: signal([...]) }),
{
// Pure — same as before:
moveCursor(s, { delta }: { delta: number }) {
s.cursor.value = clamp(s.cursor.value + delta, 0, s.items.value.length - 1)
},
// Returns effects as data:
toggleDone(s, { index }: { index: number }): Effect[] {
s.items.value = s.items.value.map((item, i) =>
i === index ? { ...item, done: !item.done } : item
)
return [
{ effect: "persist", data: s.items.value },
{ effect: "toast", message: `Toggled ${s.items.value[index].text}` },
]
},
},
)
```
Tests assert on what the function *says should happen* — no mocks, no fakes, no I/O:
```tsx
test("toggleDone persists and toasts", () => {
const s = { cursor: signal(0), items: signal([{ text: "Buy milk", done: false }]) }
const effects = TodoList.toggleDone(s, { index: 0 })
expect(effects).toContainEqual({ effect: "persist", data: expect.any(Array) })
expect(effects).toContainEqual({ effect: "toast", message: "Toggled Buy milk" })
})
```
The runtime dispatches effects to actual runners — swap them per platform:
```tsx
const app = createApp(
() => { ... },
{
effects: {
persist: async ({ data }) => { await fs.writeFile("data.json", JSON.stringify(data)) },
toast: ({ message }) => { showToast(message) },
// Web: same domain logic, different runners
// persist: async ({ data }) => { localStorage.setItem("data", JSON.stringify(data)) },
},
},
)
```
For async results that need to feed back into the domain, use the **dispatch-back pattern** — the effect describes what to fetch and what op to dispatch with the result:
```tsx
type Effect =
| { effect: "persist"; data: unknown }
| { effect: "fetch"; url: string; onSuccess: TodoOp }
// Domain stays pure — no await, no callback:
loadItems(s: State): Effect[] {
return [{ effect: "fetch", url: "/api/items", onSuccess: { op: "setItems" } }]
}
// The runner does async work and dispatches the result as a new op:
effects: {
fetch: async ({ url, onSuccess }, { store }) => {
const data = await fetch(url).then(r => r.json())
store.apply({ ...onSuccess, data })
},
}
```
Step back: `apply(state, op) → [new state, effects]`. This is [The Elm Architecture](https://guide.elm-lang.org/architecture/) — Elm calls it `update msg model = (model, cmd)`. You arrived here incrementally, but you now have what Elm enforces at the language level: every state change is an explicit op, every side effect is a return value, and the entire domain is a pure function.
### Event side: app plugins
Every extension in this guide — `withDomEvents`, `withCommands`, `withKeybindings` — is the same thing: an app plugin. A function that takes an app and returns an enhanced app:
```tsx
import type { AppPlugin } from "@silvery/create/plugins"
type AppPlugin = (app: A) => B
```
This is the [SlateJS](https://docs.slatejs.org/concepts/08-plugins) editor model: `withHistory(withReact(createEditor()))`. Each plugin overrides methods on the app — `press` for input interception, `click` for mouse dispatch. You compose them with `pipe()`:
```tsx
import {
pipe,
withReact,
withTerminal,
withFocus,
withDomEvents,
withCommands,
withKeybindings,
withDiagnostics,
} from "@silvery/create/plugins"
const app = pipe(
createApp(store), // kernel: event loop + state
withReact(), // rendering: React + virtual buffer
withTerminal(process), // terminal: stdin→events, stdout→output
withFocus(), // processing: Tab navigation, focus scopes
withDomEvents(), // processing: dispatch to component tree
withCommands(opts), // processing: key/mouse → named commands
withKeybindings(bindings), // API: press() → keybinding resolution
withDiagnostics(), // API: render invariant checks
)
```
A plugin has two parts: a **slice** (pure reducer for its state) and a **plugin function** (event wiring, subscriptions, API surface):
```tsx
function withVimModes() {
return {
slice: (msg: AppEvent, vim: VimState): VimState => {
if (msg.type !== "term:key") return vim
if (vim.mode === "normal" && msg.data.input === "i") return { ...vim, mode: "insert" }
if (vim.mode === "insert" && msg.data.key.escape) return { ...vim, mode: "normal" }
return vim
},
plugin: (app) => {
const { update } = app
app.update = (msg, model) => {
if (msg.type === "term:key" && model.vim.mode === "insert") {
return update(msg, model) // skip command resolution, let it reach text input
}
return update(msg, model)
}
return app
},
}
}
```
Mode lives **in the model**, not in a closure — so it's inspectable, serializable, and survives replay.
### Three mechanisms for event sources
Not all sources need to be app plugins. Silvery provides three mechanisms:
| Mechanism | Lifecycle | Use when... |
| -------------------- | ----------------------------------- | ------------------------------------------------- |
| **App plugins** | Static — created once at app setup | Always-on sources: stdin, resize, timers |
| **React components** | Reactive — mount/unmount with state | Conditional sources: file watchers, network polls |
| **Effects** | One-shot — triggered by update | Request/response: fetch, save, notifications |
React components are the most natural way to add reactive sources:
```tsx
function FileWatcher({ path }: { path: string }) {
const dispatch = useDispatch()
useEffect(() => {
const watcher = watch(path, (ev) => dispatch({ type: "fs:change", data: ev }))
return () => watcher.close()
}, [path])
return null // renderless
}
```
Vault opens → component mounts → watcher starts. Vault closes → unmounts → stops. React's reconciler IS the subscription manager.
Both sides of Level 4 do the same thing: make processing visible. Effects-as-data makes I/O visible on the state side. Plugins make event processing visible on the event side. Everything the app does is now data.
**The wall**: Your single slice is 400 lines. A search feature change breaks the cursor because they share state and a single `apply()`.
## Level 5: Composable Machines
Everything lives in one slice. That worked when the app was small, but now board, dialog, and search are entangled.
**The fix:** Each area of concern becomes its own slice with its own state, ops, and `.apply()`. We call this a **state machine** — a slice + the state it operates on + the set of ops it accepts. The key rule: **no state machine imports another**. They communicate through dispatch effects:
```typescript
const Board = createSlice(
() => ({ cursor: signal(0), items: signal([]) }),
{
moveCursor(s, { delta }: { delta: number }) { ... },
fold(s, { nodeId }: { nodeId: string }): Effect[] { ... },
},
)
const Dialog = createSlice(
() => ({ open: signal(false), value: signal("") }),
{
open(s, { kind }: { kind: string }) { ... },
confirm(s): Effect[] {
s.open.value = false
return [{ effect: "dispatch", target: "board", op: "addItem", text: s.value.value }]
},
},
)
```
`Dialog.confirm()` doesn't call Board directly. It returns `{ effect: "dispatch", target: "board", op: "addItem" }` — a data object. The effect runner routes it:
```tsx
const app = createApp(
() => {
const board = Board.create()
const dialog = Dialog.create()
const search = Search.create()
return {
board: { ...board.state, dispatch: board.apply },
dialog: { ...dialog.state, dispatch: dialog.apply },
search: { ...search.state, dispatch: search.apply },
}
},
{
effects: {
dispatch: ({ target, op, ...params }, { store }) => {
const machine = (store as any)[target]
if (machine?.dispatch) return machine.dispatch({ op, ...params })
},
},
key(input, key, { store }) {
if (input === "/") store.dialog.dispatch({ op: "open", kind: "search" })
if (input === "j") store.board.dispatch({ op: "moveCursor", delta: 1 })
if (input === "q") return "exit"
},
},
)
```
Each state machine is independently testable — call `Dialog.confirm(dialogState)` directly and assert on the effects it returns, without touching Board.
On the event side, the full plugin architecture composes the same way:
```
using app = pipe(
createApp(store, { slices }) kernel: event loop + composed reducers
├─ withReact() rendering: React + virtual buffer
├─ withTerminal(process) terminal: stdin→events, stdout→output
├─ withFocus() processing: Tab navigation, focus scopes
├─ withDomEvents() processing: dispatch to components
├─ withVimModes() processing: modal key routing
├─ withCommands(opts) processing: key/mouse → named commands
├─ withKeybindings(bindings) API: press() → keybinding resolution
└─ withDiagnostics() API: render invariant checks
)
```
Here's the full architecture — notice it's the same shape at every scale:
```
keypress / mouse / timer
↓
dispatch(op)
↓
machine.apply(state, op)
↓
[new state, effects[]]
↓
effect runners
├─ persist → disk / localStorage
├─ toast → notification UI
├─ fetch → network → dispatch(result)
└─ dispatch → another machine.apply(...)
```
## Trade-offs: When Data Goes Too Far
The progression from functions to data is not free. Each level buys something real — but it also costs something real.
**When plain functions are fine.** At Levels 1 and 2, `store.toggleDone()` and `onClick={...}` are direct function calls. Simple, debuggable, zero indirection. If you haven't hit one of the walls, stay here. Most dashboards, list views, and CRUD apps never need more. The walls are real requirements, not aspirations; if you haven't hit the wall, don't climb it.
**The costs of Level 3+:**
* **Verbosity.** With `createSlice`, adding an op is one function. Callers write `{ op: "moveCursor", delta: 1 }` instead of `moveCursor(1)`. Command registries and binding tables add surface area.
* **Indirection.** Stack traces go through `apply()` → handler and through command resolution → action dispatch. You lose some "click to navigate" convenience. Name things well and keep modules small.
* **Type ceremony.** If you pattern-match on the op union elsewhere (e.g. `inverse`), you maintain that switch yourself. `createSlice` eliminates the union definition, but not all downstream consumers.
* **Plugin ordering.** `withVimModes()` before `withCommands()` means vim intercepts first. The override chain is a stack of closures, so debugging goes through multiple layers.
**When to use functions inside data.** Even at Level 4-5, not everything needs to be data. Effect *runners* are functions. Computed values are functions. React components are functions. The boundary: **crossing module boundaries** (between slices, between domain and I/O) should be data; **within a module** (the implementation of a single op handler), use whatever's clearest.
**How Silvery minimizes the costs:**
* **Wiring** — `createApp()` handles the store-to-effects-to-runners pipeline. Declare effect runners once.
* **Composition** — `createStore()` with plugin composition adds cross-cutting concerns without per-op boilerplate.
* **Debugging** — `withDiagnostics()` validates rendering, `SILVERY_INSTRUMENT=1` exposes per-frame counters.
* **Driver pattern** — `withCommands()` + `withKeybindings()` give you a `driver.cmd.all()` API — the dispatcher is no longer opaque.
**The honest rule of thumb**: if you can't name a specific benefit you'd get from making something data (undo? replay? testing without mocks? customizable bindings?), keep it as a function call. The progression is opt-in at every level — and opting out is a valid choice.
## Prior Art
The core ideas — making operations, effects, and events into data — have been discovered many times.
| System | What it covers | Approach |
| ------------------------------------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------- |
| **[Elm](https://guide.elm-lang.org/architecture/)** | State + Effects + Composition | `update : Msg -> Model -> (Model, Cmd Msg)` — the gold standard. Enforces this at the language level. |
| [Redux](https://redux.js.org/) | State (ops as data) | `dispatch(action)` + reducer. Effects live in middleware (thunks/sagas), not return values. |
| [redux-loop](https://github.com/redux-loop/redux-loop) | State + Effects | Extends Redux: reducer returns `[state, effects]` — completing the Elm shape. |
| **[SlateJS](https://docs.slatejs.org/)** | Event plugins | `withHistory(withReact(createEditor()))` — same `(editor) => editor` plugin shape. |
| [ProseMirror](https://prosemirror.net/) | Event plugins | Structured plugin hooks — more constrained, easier to reason about. |
| [Express](https://expressjs.com/) / [Koa](https://koajs.com/) | Event middleware | `app.use(middleware)` — onion model composition. |
| **Silvery** | All of the above | `createSlice` + `tea()` for state; `pipe()` + plugins for events. Incremental adoption. |
Redux got Level 3 right but stopped there. redux-loop completed the Elm shape. SlateJS pioneered the plugin-by-override model. This guide pieces these ideas into a single incremental progression for React.
## The Takeaway
You don't choose a framework. You choose how visible your app's behavior is.
At Level 1, keypresses enter callbacks and state changes happen inside components — both invisible. At Level 5, every event has a type, every action has a name, every state change is an op, every side effect is a return value, every plugin is a composable function. The entire pipeline is inspectable data: events → commands → ops → state → effects → screen.
The more visible your behavior is — the easier your app is to test, debug, automate, customize, and scale. But visibility has a cost: verbosity, indirection, and ceremony. The right level is the one where the benefits you actually use outweigh the boilerplate you actually write. Silvery doesn't force you into any of this. You grow into it one level at a time.
## See Also
* [Functional Core, Imperative Shell](https://web.archive.org/web/2025/https://kennethlange.com/functional-core-imperative-shell/) — the architectural principle behind Levels 3-5
* [The Elm Architecture](https://guide.elm-lang.org/architecture/) — the gold standard for ops + effects as data
---
---
url: /guide/layouts.md
---
# Building Complex Layouts
Silvery's layout is powered by [Flexily](https://beorn.codes/flexily), a pure JavaScript flexbox engine. This guide walks through building a typical TUI application layout with:
* Responsive components that know their own size
* Fixed-height top/bottom bars
* Flexible content area that fills remaining space
* Multiple scrollable columns
* Visual scroll indicators
## The Goal
A board-style layout like this:
```
┌──────────────────────────────────────────────────┐
│ Top Bar (fixed height) │
├──────────────────────────────────────────────────┤
│ ‹ │ Column 1 │ Column 2 │ Column 3 │ › │
│ │ Card 1 │ Card A │ Card X │ │
│ │ Card 2 │ Card B │ Card Y │ │
│ │ Card 3 │ ... │ ... │ │
├──────────────────────────────────────────────────┤
│ Bottom Bar (fixed height) │
└──────────────────────────────────────────────────┘
```
## Step 1: Fixed Bars with Flexible Content
Use `flexShrink={0}` for fixed elements and `flexGrow={1}` for flexible areas:
```tsx
function App() {
return (
{/* Top bar - fixed height, won't shrink */}
{" "}
My App{" "}
{/* Content area - fills remaining space */}
{/* Your columns go here */}
{/* Bottom bar - fixed height, won't shrink */}
Press q to quit
)
}
```
**Key points:**
* `flexShrink={0}` prevents bars from shrinking when space is tight
* `flexGrow={1}` makes the content area fill all remaining vertical space
* No height calculation needed - flexbox handles it automatically
## Step 2: Multiple Columns
For equal-width columns, give each the same `flexGrow`:
```tsx
Column 1
{/* cards */}
Column 2
{/* cards */}
Column 3
{/* cards */}
```
## Step 3: Scrollable Content
Use `overflow="scroll"` with `scrollTo` to automatically scroll to a selected item:
```tsx
function Column({ items, selectedIndex }) {
return (
{/* Fixed header */}
Column Title
{/* Scrollable content - fills remaining height */}
{items.map((item, i) => (
{item.title}
))}
)
}
```
**Key points:**
* `overflow="scroll"` enables virtual scrolling
* `scrollTo={selectedIndex}` keeps the selected item visible
* `flexGrow={1}` makes the scrollable area fill available space
* No height prop needed - Silvery calculates it from the flexbox layout
## Step 4: Scroll Indicators with Filled Backgrounds
For scroll indicators that fill available height with a background color:
```tsx
function ScrollIndicator({ direction }: { direction: "left" | "right" }) {
const arrow = direction === "left" ? "‹" : "›"
return (
{arrow}
)
}
```
**Key points:**
* `flexGrow={1}` fills available vertical space
* `backgroundColor="gray"` fills the entire computed area (Silvery feature)
* `justifyContent="center"` centers the arrow vertically
* No height calculation or Array.from() loops needed
## Step 5: Column Separators
For visual separators between columns:
```tsx
function ColumnSeparator() {
return (
{/* Blank line to align with column headers */}
{/* Line fills remaining space */}
│
)
}
```
## Complete Example
Putting it all together:
```tsx
import { render, Box, Text, useInput, useApp, createTerm } from "silvery"
import { useState } from "react"
function ScrollIndicator({ direction }) {
return (
{direction === "left" ? "‹" : "›"}
)
}
function Column({ title, items, selectedIndex, isActive }) {
return (
{/* Header */}
{title} ({items.length})
{/* Scrollable items */}
{items.map((item, i) => (
{item}
))}
)
}
function Board() {
const { exit } = useApp()
const [colIndex, setColIndex] = useState(0)
const [cardIndex, setCardIndex] = useState(0)
const columns = [
{
title: "To Do",
items: ["Task 1", "Task 2", "Task 3", "Task 4", "Task 5"],
},
{ title: "Doing", items: ["Task A", "Task B"] },
{ title: "Done", items: ["Task X", "Task Y", "Task Z"] },
]
// Show scroll indicators if there are more columns than visible
const showLeftIndicator = colIndex > 0
const showRightIndicator = colIndex < columns.length - 1
useInput((input, key) => {
if (input === "q") exit()
if (key.leftArrow) setColIndex((i) => Math.max(0, i - 1))
if (key.rightArrow) setColIndex((i) => Math.min(columns.length - 1, i + 1))
if (key.upArrow) setCardIndex((i) => Math.max(0, i - 1))
if (key.downArrow) {
const maxIndex = columns[colIndex].items.length - 1
setCardIndex((i) => Math.min(maxIndex, i + 1))
}
})
return (
{/* Top bar */}
My Kanban Board
{/* Content area */}
{showLeftIndicator && }
{columns.map((col, i) => (
))}
{showRightIndicator && }
{/* Bottom bar */}
←→ switch column ↑↓ select q quit
)
}
using term = createTerm()
await render(, term)
```
## Anti-Patterns to Avoid
### ❌ Don't calculate heights manually
```tsx
// Bad: manual height calculation
const contentHeight = terminalRows - topBarHeight - bottomBarHeight
...
```
### ✅ Do use flexbox
```tsx
// Good: let flexbox handle it
...
```
### ❌ Don't create arrays for filled backgrounds
```tsx
// Bad: creating array of rows for background
{Array.from({ length: height }).map((_, i) => (
{" "}
))}
```
### ✅ Do use Box backgroundColor
```tsx
// Good: Box fills its area automatically
›
```
## Responsive Layout with useBoxRectDangerously()
The killer feature for complex layouts: components can query their own dimensions during render. This is like [CSS container queries](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_containment/Container_queries) — components adapt to their container, not the viewport.
```tsx
function ResponsiveBoard({ items }) {
const { width } = useBoxRectDangerously()
// Adapt column count to available space
const columns = width > 120 ? 4 : width > 80 ? 3 : width > 40 ? 2 : 1
return (
{Array.from({ length: columns }, (_, i) => (
{items
.filter((_, j) => j % columns === i)
.map((item) => (
))}
))}
)
}
```
No prop drilling, no `measureElement` + `useEffect` dance. The layout engine computes dimensions first, then components render with correct values. This works at any nesting depth — a `Card` inside a `Column` inside a `Board` all get their own dimensions simultaneously, in one batch.
```tsx
function Card({ item }) {
const { width } = useBoxRectDangerously()
return (
{width > 30 ? item.title : truncate(item.title, width - 4)}
{width > 50 && {item.description}}
)
}
```
::: tip First render returns zeros
`useBoxRectDangerously()` returns `{ width: 0, height: 0 }` on the first render (before layout runs). Guard with `if (width === 0) return null` if your component can't render without dimensions. The framework handles the re-render automatically.
:::
## Summary
| Need | Solution |
| -------------------- | ------------------------------------------------------------ |
| Fixed-height element | `height={n}` + `flexShrink={0}` |
| Fill remaining space | `flexGrow={1}` |
| Scrollable list | `overflow="scroll"` + `scrollTo={index}` |
| Responsive columns | `useBoxRectDangerously()` + conditional rendering |
| Adaptive content | `useBoxRectDangerously()` + truncation / hide at breakpoints |
| Filled background | `backgroundColor="color"` on Box |
| Centered content | `justifyContent="center"` + `alignItems="center"` |
## Text Layout {#text-layout}
CSS gives you `fit-content` (widest wrapped line) and greedy word-wrap. There's no way to say *"find the narrowest width that still produces exactly 3 lines"* or *"break lines to minimize raggedness across the whole paragraph."*
::: tip Interactive Demo
Run `bunx @silvery/examples text layout` for a side-by-side visual comparison of snug-content bubbles, even wrapping, and the combined effect.
:::
Silvery adds these capabilities, inspired by [Pretext](https://chenglou.me/pretext/) (`@chenglou/pretext`).
### Width Sizing
`width` controls how a Box sizes itself:
| Value | What it does |
| ---------------------- | ------------------------------------------------- |
| `width={60}` | Fixed at 60 columns |
| `width="fit-content"` | Shrink to widest wrapped line (CSS `fit-content`) |
| `width="snug-content"` | Tightest width that keeps the same line count |
#### `fit-content` vs `snug-content`
`fit-content` wraps text, then sizes the box to the widest line. When the last line is short, the box has dead space:
```
┌───────────────────┐
│ Hello world, this │ ← widest line sets the width
│ is a test │ ← wasted space ─────────→
└───────────────────┘
```
`snug-content` finds the *narrowest* width that still produces the same number of lines. Pretext calls this ["shrinkwrap"](https://chenglou.me/pretext/bubbles/) — it uses [`walkLineRanges()`](https://github.com/chenglou/pretext) to binary-search over widths, comparing line counts at each candidate. Silvery uses the same algorithm adapted for terminal character-cell grids:
```
┌───────────────┐
│ Hello world, │ ← tighter: same 2 lines
│ this is a test│ ← no dead space
└───────────────┘
```
```tsx
The quick brown fox jumps over the lazy dog
```
Best for: chat bubbles, tooltips, badges, cards with final content.
::: warning
`snug-content` can cause width jitter on live-editing text — when text crosses a wrap boundary, the box width can suddenly shrink. Use `fit-content` for dynamic text; `snug-content` for static content.
:::
### Wrap Modes
`wrap` controls how text breaks when it exceeds the container width:
| Mode | What it does |
| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `wrap="wrap"` | Word-aware wrapping — each line as full as possible (default) |
| `wrap="even"` | Minimize total raggedness — [minimum-raggedness](https://en.wikipedia.org/wiki/Line_wrap_and_word_wrap#Minimum_raggedness) paragraph layout |
| `wrap="hard"` | Character-level wrapping — break anywhere |
| `wrap={false}` | Truncate with ellipsis |
| `wrap="clip"` | Hard cut at width, no ellipsis |
| `wrap="truncate-start"` | Ellipsis at start: `…end of text` |
| `wrap="truncate-middle"` | Ellipsis in middle: `start…end` |
#### Greedy vs Even
**Greedy** (`wrap="wrap"`) fills each line as much as possible, left to right. This is Pretext's default behavior via [`layoutWithLines()`](https://github.com/chenglou/pretext). Simple and predictable:
```
The quick brown fox jumps over the
lazy dog sat on the mat.
```
**Even** (`wrap="even"`) minimizes the *total* wasted space across all lines using [minimum-raggedness dynamic programming](https://en.wikipedia.org/wiki/Line_wrap_and_word_wrap#Minimum_raggedness). Pretext demonstrates this as ["Knuth-Plass paragraph layout"](https://chenglou.me/pretext/) in their justification comparison demo. Greedy optimizes each line independently; even considers all possible break combinations globally:
```tsx
Long paragraph that benefits from globally-even line breaks rather than greedy per-line
decisions.
```
Both modes have the same rendering performance (~25 microseconds for typical terminal text). The text analysis is cached per node (PreparedText) — repeated renders at the same width are free.
#### Pretext API Mapping
| Silvery | Pretext equivalent | Notes |
| --------------------- | ------------------------------------------------------------------------- | ------------------------------- |
| `buildTextAnalysis()` | [`prepare()`](https://github.com/chenglou/pretext) | One-time text analysis |
| `countLinesAtWidth()` | [`measureLineStats()`](https://github.com/chenglou/pretext) | Line count at given width |
| `shrinkwrapWidth()` | [`walkLineRanges()`](https://github.com/chenglou/pretext) + binary search | Tightest width for N lines |
| `wrap="even"` | Justification demo | Minimum-raggedness DP |
| — | [`layoutNextLineRange()`](https://github.com/chenglou/pretext) | Variable-width layout (planned) |
Pretext uses canvas-based font measurement for sub-pixel web layouts. Silvery adapts the same algorithms for terminal integer-width character cells. A future [pluggable measurement API](https://github.com/chenglou/pretext) could unify both backends.
### Width × Wrap Interaction
Width and wrap are orthogonal — they compose naturally:
```tsx
{
/* Tightest bubble, even lines — prettiest for chat */
}
;Hello world, this is a message
{
/* Fixed width, even paragraph breaking */
}
;{longParagraph}
```
`snug-content` without a wrap mode defaults to greedy wrapping. Truncation modes (`wrap={false}`, `wrap="clip"`) produce single lines, so `snug-content` has no effect with them — use `fit-content` instead.
### Convention: Floating UI vs Flow UI
Silvery's built-in floating components default to `snug-content`:
| Component | Default width | Why |
| ------------- | -------------- | -------------------------------- |
| `ModalDialog` | `snug-content` | Dialogs hug their content |
| `ToastItem` | `snug-content` | Notifications are self-contained |
| `Tooltip` | `snug-content` | Tooltip text is static |
Flow components (SelectList, TextInput, list items) use `auto` — they fill their parent's available width.
**Rule of thumb**: if a component floats over other content and wraps text, use `snug-content`. If it's part of a column or grid, use `auto` or a fixed width.
---
---
url: /guide/responsive-layout.md
---
# Responsive Layout
Silvery supports responsive layout in three layers, ordered by how often you'll reach for them:
1. **`useResponsiveBoxProps`** — declarative ``-prop spread driven by the global viewport. The canonical primitive for app chrome (sidebars, headers, multi-pane shells).
2. **`useResponsiveValue`** — pick a non-Box-prop value (string, enum, callback) keyed by viewport breakpoint.
3. **`useBoxRectDangerously` / `useScrollRect` / `useScreenRect`** — read the **committed** measured rect of the current Box. Use when the decision genuinely depends on the parent's measured size, not the global terminal width.
## The mental model
silvery uses Bootstrap/Tailwind/Polaris-style mobile-first breakpoints:
| Breakpoint | Default threshold (terminal columns) |
| ---------- | ------------------------------------ |
| `default` | applies below `xs` |
| `xs` | ≥ 30 |
| `sm` | ≥ 60 |
| `md` | ≥ 90 |
| `lg` | ≥ 120 |
| `xl` | ≥ 150 |
Each breakpoint is **cumulative** — a `lg` value applies at `lg` and `xl` unless `xl` overrides it. Specifying `default` is mandatory; every other breakpoint is optional.
## Dimension expressions
With the Flexily backend, Box, Text and Island accept length strings on `width`, `height`, `minWidth`, `minHeight`, `maxWidth`, `maxHeight` and `flexBasis`.
Use `calc()`, `min()`, `max()` and `clamp()` to combine a responsive size with a floor or ceiling:
```tsx
A bounded panel
```
| Unit | Meaning in the terminal |
| ----- | ------------------------------------------------------------------------------------------------------------------------------- |
| `ch` | One column; accepted on width and other inline-axis dimensions. |
| `lh` | One row; accepted on height and other block-axis dimensions. |
| `%` | A percentage of the corresponding containing axis. |
| `cqi` | One percent of the nearest ancestor's frozen query inline size, or the layout root's inline size when no query ancestor exists. |
Numeric props still count cells: `width={10}` is ten columns and `height={3}` is three rows.
The terminal adapter supplies the `ch` and `lh` scale. `px` strings are refused with an error pointing to `ch` and `lh`.
Cross-axis strings such as `height="2ch"`, `width="2lh"` or `height="10cqi"` are refused because this adapter has no cell aspect ratio.
For `flexBasis`, the parent direction determines the axis, so an incompatible unit is reported at first layout.
### Accepted syntax and fixes
* Function names and units are case-insensitive: `MIN(10CH, 50%)` works.
* Functions can nest and group expressions: `calc((100% - 2ch) / 2)`.
* Every length carries a unit. Write `max(50%, 2ch)` instead of `max(50%, 2)`.
* Arithmetic belongs inside a math function. Wrap `100% - 2ch` as `calc(100% - 2ch)`.
* Binary `+` and `-` require spaces on both sides. Write `calc(100% - 2ch)` instead of `calc(100%-2ch)`.
* Multiplication and division take a unitless constant: `calc(2ch*3)` and `calc(6lh/2)`. Division by zero is an error.
* Fractional lengths such as `0.5ch` are valid. Layout keeps fractional sizes; final box edges snap to whole terminal cells, so a small expression can occupy zero cells.
### Container-relative dimensions
Give the query ancestor `containerType="inline-size"` and `containSize` so its inline size does not depend on the descendants that query it:
```tsx
At least one column, otherwise ten percent of the query width
```
The size is frozen before dependent descendants lay out. A query container's own length queries its ancestor, rather than itself.
With no query ancestor, the layout root is the implicit inline-size query container: descendants use its computed inline size. The root's own query units resolve against the available size.
This is a deliberate CSS subset. Math on padding, margin, gap and position offsets is refused; numeric spacing and margin `auto` keep their existing behavior.
`cqmin`, `cqb` and `cqmax` are refused in dimension expressions until both query axes are supported. The existing `fitWidth` API retains its earlier `cqmin` behavior.
`var()` and other units are unsupported. The Yoga backend accepts its existing numbers, percentages and keywords, and reports a prop-named error for these expressions.
On Yoga, width `fit-content` and `snug-content` use its existing `auto` fallback; use Flexily when content sizing is required.
Percent dimensions against an indefinite, auto-sized parent can resolve to zero in Flexily where CSS uses auto sizing; this page does not claim browser-identical layout.
## Pattern 1: Declarative Box-prop spread
The most common case: layout chrome that switches between column and row, narrows padding on small terminals, or hides a sidebar below some width. Reach for `useResponsiveBoxProps`:
```tsx
import { useResponsiveBoxProps } from "silvery"
function AppShell({ sidebar, main }: { sidebar: React.ReactNode; main: React.ReactNode }) {
const containerLayout = useResponsiveBoxProps({
default: { flexDirection: "column" },
md: { flexDirection: "row" },
})
const sidebarLayout = useResponsiveBoxProps({
default: { width: "100%", height: 8 },
md: { width: 28, height: "100%" },
})
return (
{sidebar}{main}
)
}
```
`useResponsiveBoxProps` accepts either a flat `Partial` (no responsive variants — short-circuits without breakpoint resolution) or a `{ default, xs?, sm?, md?, lg?, xl? }` cascade. Each breakpoint variant merges on top of the previous one; you only specify the keys that change.
This is the **canonical** responsive primitive — prefer it over reading `useBoxRectDangerously` for layout decisions.
## Pattern 2: Non-Box-prop responsive values
`useResponsiveValue` handles the cases `useResponsiveBoxProps` doesn't cover — picking a string, an enum, a callback, or any non-`BoxProps` value:
```tsx
import { useResponsiveValue } from "silvery"
const panelMode = useResponsiveValue<"overlay" | "inline">({
default: "overlay",
sm: "inline",
})
const truncationLength = useResponsiveValue({
default: 20,
md: 60,
lg: 100,
})
```
## Pattern 3: Measured-rect decisions
When the responsive decision depends on the **measured rect of the current Box** (not the global terminal width), reach for `useBoxRectDangerously`:
```tsx
function ResponsiveCard() {
const { width } = useBoxRectDangerously()
const direction = width < 60 ? "column" : "row"
return (
Panel 1Panel 2
)
}
```
The reactive form of `useBoxRectDangerously` returns the **committed** rect: invariant across every convergence pass within one event batch. A render that branches on the read value produces the same output every pass — the convergence loop terminates in one pass. The historical "useBoxRectDangerously-driven width oscillation" feedback loop is impossible by construction.
The cost is **one frame late on mount**: the first paint shows the empty-rect fallback (`{ width: 0, height: 0 }`), and the measured value arrives on the next render. For app chrome decisions where this flash is visible, prefer `useResponsiveBoxProps` — it doesn't depend on layout measurement.
## Migration from the old anti-pattern
Pre-2026-05-06 silvery exposed the layout hooks with **in-flight** semantics — each rect read returned the latest measurement, which could change between convergence passes within a single batch. A render that branched on `useBoxRectDangerously` width and structurally mounted/unmounted a sidebar (`width >= 90 ? : `) could ping-pong: pass 1 measures 95 → renders WithSidebar → pass 2 measures 88 (sidebar took 7 cols) → renders NoSidebar → pass 3 measures 95 → loop until the convergence cap fired.
Under the deferred contract this can't happen. But the canonical fix for the pattern is still cleaner with `useResponsiveBoxProps`:
```tsx
// Old anti-pattern (works under deferred semantics, but flashes on mount):
function Panel() {
const { width } = useBoxRectDangerously()
return width >= 90 ? :
}
// Canonical:
function Panel() {
const layout = useResponsiveBoxProps({
default: {}, // no sidebar by default
md: {
/* sidebar visible */
},
})
// ... render driven by `layout` spread ...
}
```
The declarative form has no first-frame flash and doesn't depend on layout measurement at all.
## See also
* [`useResponsiveBoxProps`](/api/use-responsive-box-props)
* [`useResponsiveValue`](/api/use-responsive-value)
* [`useBoxRectDangerously`](/api/use-box-rect) / [`useScrollRect`](/api/use-scroll-rect) / [`useScreenRect`](/api/use-screen-rect)
---
---
url: /guide/min-width.md
---
# Minimum Width
How narrow is a component allowed to get? Silvery answers that with CSS's automatic minimum size (§4.5): **a flex item does not shrink below its own content's intrinsic minimum**. In practice that means a paragraph shrinks until its longest unbreakable word, and then stops.
You usually get this for free. This page is for the cases where you need to know the rule — and for the one prop that opts out of it.
## The short version
* A `` floors at its **longest unbreakable token**, not at its natural width.
* That floor **propagates up through wrapper Boxes** automatically. You do not thread anything through a wrap chain.
* A `` that cannot wrap (`truncate`, `clip`, `false`) floors at **1 cell** — it declares it can always collapse to an ellipsis. It needs no help to fit.
* `minWidth={0}` opts a subtree out of the floor entirely. Reach for it in exactly one situation, below.
## The floor, and where it comes from
Min-content is "the narrowest this content can be without overflowing". For text it is the longest run of characters with no break opportunity inside it:
```tsx
// The container is 12 cells. The word is 34 and cannot break.
supercalifragilisticexpialidocious
```
The inner Box lays out **34 cells wide and overflows**, rather than squeezing to 12 and shredding the word. That is the auto-min floor doing its job: overflow is visible and fixable, a mangled word is neither.
Wrap mode decides the floor, and the rules live in one place — [`intrinsicWidths`](https://github.com/beorn/silvery/blob/main/packages/ag-term/src/unicode.ts) in `@silvery/ag-term/unicode`:
| Wrap mode | min-content | max-content |
| ------------------------------------ | ------------------------------------------------------- | ------------- |
| `"wrap"` (and other wrappable modes) | longest unbreakable segment between break opportunities | natural width |
| `"hard"` | 1 cell — any character may break | natural width |
| `"truncate"` / `"clip"` / `false` | 1 cell — collapses to an ellipsis | natural width |
Break opportunities include whitespace and hyphens, and also the soft separators `/ \ . _ :` — so `.claude/skills/{claim,do}/SKILL.md` reports the longest path *segment* as its floor, not the whole path.
## It propagates — don't thread props
The floor established at a `` is the same floor several wrappers up. Nesting depth does not change it:
```tsx
// All three of these produce the same floor.
{token}{token}{token}
```
This is why the old `flexShrink={1} minWidth={0}` incantation threaded down every wrapper is no longer needed — see [Prose](/components/Prose) for that history. Containers walk their children (summing on the main axis, taking the max on the cross axis) and add their own padding, border and gap.
## `minWidth={0}` — the one escape hatch
Use it when **the container is legitimately narrower than the longest unbreakable token and you would rather clip than overflow**:
```tsx
// Without minWidth={0}: the cell is 34 wide and overflows its 12-cell parent.
// With it: the cell is 12 and the long word is clipped by overflow="hidden".
supercalifragilisticexpialidocious
```
It works on the `` itself too, via `TextFlexItemProps`.
### When NOT to reach for it
**Non-wrappable Text does not need it.** A `` already reports min-content 1, so a Box around it shrinks to its container unaided; adding `minWidth={0}` measurably changes nothing. Guidance that still prescribes the hatch for truncate/clip Text predates a fix landed 2026-05-11 — before it, non-wrappable Text reported min-content equal to max-content, the parent got pinned at natural width, and its `overflow="hidden"` hard-clipped mid-word with no ellipsis because flex never shrank the Text.
Both claims in this section are pinned by contract tests in `tests/features/min-width-protocol.test.tsx`, so this page cannot quietly drift off the code.
## Engine requirement
Recursive intrinsic min-content is a **flexily-only** capability. It rides on a measure mode (`MEASURE_MODE_MIN_CONTENT`) that Yoga does not define, so under `SILVERY_ENGINE=yoga` the adapter throws rather than silently substituting a different mode and producing a plausible wrong layout. The fix it names is `SILVERY_ENGINE=flexily`.
Container-side §4.5 (an `overflow: hidden/scroll` container gets `min-size: auto = 0`) and item-side auto-min are both implemented under the CSS preset; the Yoga preset keeps Yoga's looser `min: undefined → 0`.
## Where the rest of this is written down
This page covers the silvery-visible surface. The engine mechanics — how the automatic minimum size is derived, how `contentMinSize` relates to `baseSize`, the specified-size suggestion cap, and the per-node caching — are documented once, in flexily's [Yoga divergences guide](https://github.com/beorn/flexily/blob/main/docs/guide/yoga-divergences.md) under "Divergence 4: flex-item automatic minimum size". That is the canonical home for the algorithm; this page deliberately does not restate it.
## See also
* [Layouts](/guide/layouts) — flexbox basics in silvery
* [Responsive Layout](/guide/responsive-layout) — `containerType`, `fitWidth`, `cqi` units
* [Prose](/components/Prose) — typography primitive, and the history of the wrap-chain incantation
---
---
url: /guide/styling.md
---
# Styling
*Colors, typography, and component defaults for the shiniest Silvery apps*
Colors tarnish fast. Typography gets inconsistent. A hardcoded `"red"` here, a `"$fg-success"` where you meant "brand emphasis" there — suddenly your UI is a patchwork that breaks on every theme. These principles keep your apps **shiny**.
::: info Sterling is the system
Silvery 0.20.0 ships [Sterling](/reference/sterling) as **THE Theme**. The tokens used below — `$fg-accent`, `$fg-muted`, `$bg-surface-subtle`, `$border-focus`, `$bg-selected`, `$fg-on-error` — are Sterling's flat hyphen-keys. Every silvery component already speaks them.
Migrating from silvery 0.19.x? Legacy `$tokens` (`$primary`, `$muted`, `$selectionbg`, …) keep resolving through 0.20.x via a kebab-fallback path. Migrate during this window — they're removed in 0.21.0. The full map is in the [Sterling primer](/reference/sterling#token-migration-map).
**`$muted` is not "dim"** — it is the legacy muted-*surface* text slot (pairs with `$mutedbg`), and in dark themes it resolves to ≈`$fg`. Code that reaches for `$muted` expecting dimmed text gets full-brightness foreground and the "dimming" silently does nothing. The dim foreground slot is **`$fg-muted`**. (Found the hard way: a default elision-marker color set to `$muted` never dimmed; only a cell-color test against the resolved RGB caught it.)
:::
## 1. Don't Specify Colors
Most Silvery components already use the correct semantic colors by default. **The best color code is no color code.**
| Component | What's automatic |
| ---------------------- | -------------------------------------------------------------------------- |
| `` | `$fg` text color |
| `` | `$border-default` → `$border-focus` on focus, prompt, cursor |
| `