silvery 0.11.1 → 0.11.3

package/README.md

@@ -2,9 +2,7 @@
 
 **Powerful apps. Polished UIs. Proudly terminal.**
 
-Ink-compatible React renderer for interactive terminal apps. Same `Box`, `Text`, `useInput` API you know.
-
-> **Work in progress.** APIs may change. Feedback welcome.
+Ink-compatible React renderer for interactive terminal apps. Same `Box`, `Text`, `useInput` API you know. 3–6× faster in mounted rerender benchmarks.
 
 ```console
 $ npm install silvery react
@@ -33,24 +31,37 @@ await render(<Counter />).run()
 
 - **React 18 + 19** — hooks, refs, effects, suspense — all works
 - **Flexbox layout** — `Box` with `flexDirection`, `padding`, `gap`, `flexGrow`, just like Ink
-- **Ink/Chalk compatible** — [`@silvery/ink`](https://silvery.dev/guide/silvery-vs-ink) and `@silvery/chalk` drop-in compat layers. 99% of Ink's + 100% of Chalk's test suites pass. See the [full feature comparison](https://silvery.dev/guide/silvery-vs-ink)
+- **[Ink-compatible](https://silvery.dev/guide/silvery-vs-ink#compatibility)** — most code works with just an import change. 918/931 Ink 7.0 tests pass on silvery's compat layer. Drop-in migration via [`@silvery/ink`](https://silvery.dev/guide/silvery-vs-ink). See the [full feature comparison](https://silvery.dev/guide/silvery-vs-ink)
 
 ### Shiny new stuff
 
-- **[Layout-first rendering](https://silvery.dev/guide/silvery-vs-ink#responsive-layout)** — `useBoxRect()` returns actual dimensions during render. No post-render measurement, no two-pass layout cycle. Enables `overflow="scroll"`, `position="sticky"`, and ANSI-aware compositing with color blending
-- **[Dynamic scrollback](https://silvery.dev/examples/scrollback)** — live React zone at the bottom, completed items graduate to terminal-owned scrollback. Cmd+F and text selection work natively. Inline mode gets fullscreen-level performance; fullscreen mode gets inline-level UX (app-managed scrollback). No hard split between the two
-- **Pure TypeScript, zero native deps** — no WASM, no build steps. Works on Alpine, CI, Docker, everywhere
-- **[Ink-compatible](https://silvery.dev/guide/silvery-vs-ink#compatibility)** — 918/931 Ink 7.0 tests pass on silvery's compat layer. Drop-in migration via [`@silvery/ink`](https://silvery.dev/guide/silvery-vs-ink). See the [full feature comparison](https://silvery.dev/guide/silvery-vs-ink)
-- **[Theme system](https://silvery.dev/guide/styling)** — 38 palettes, semantic design/color tokens (`$primary`, `$error`), auto-detects terminal colors
-- **[45+ components](https://silvery.dev/guides/components)** — TextInput, TextArea, SelectList, ListView, Table, TreeView, Console, Tabs, CommandPalette, ModalDialog, Toast, and more
-- **[Focus system](https://silvery.dev/guide/silvery-vs-ink#focus-system)** — scoped focus, arrow-key directional nav, click-to-focus
-- **Text selection** — mouse drag, word/line selection, `userSelect` boundaries, Alt+drag override. Works out of the box with `withDomEvents()`
-- **Find** — `Ctrl+F` buffer search with match highlighting and `n`/`N` navigation. Works out of the box with `withFocus()`
-- **Copy-mode** — `Esc, v` for vim-style keyboard-driven text selection and yanking
-- **Drag-and-drop** — mouse drag with hit testing, automatic via `withDomEvents()`
-- **Extremely composable** — use as just a renderer (`render`), add a runtime (`run`), or build full apps with any React state library (useState, Zustand, Jotai, Redux). Swap terminal backends (real TTY, headless, xterm.js emulator) for [testing](https://silvery.dev/guide/testing). Embed silvery components in existing CLIs. Use the layout engine standalone. Render to terminal, or (experimental) Canvas, or DOM
-- **[Terminal protocol support](https://silvery.dev/guide/silvery-vs-ink#terminal-protocol-coverage)** — 100+ escape sequences, all auto-negotiated: 12 OSC (hyperlinks, clipboard, palette, text sizing, semantic prompts, notifications), 35+ CSI (cursor, mouse modes, paste, focus, sync output, device queries), 50+ SGR (6 underline styles, underline colors, truecolor, 256-color), full Kitty keyboard (5 flags), full SGR mouse (any-event, drag, wheel)
-- **[Incremental rendering](https://silvery.dev/guide/silvery-vs-ink#performance-size)** — cell-level dirty tracking, only changed cells emit to the terminal. Works in inline mode with native scrollback, not just fullscreen
+- **[Best-in-class performance](https://silvery.dev/guide/silvery-vs-ink#performance-size)** — 3–6× faster than Ink in mounted rerender benchmarks, 10–20× less terminal output. Cell-level dirty tracking, only changed cells emit. Per-node skip for unchanged subtrees. Works in inline mode with native scrollback, not just fullscreen
+- **Pure TypeScript, zero native deps** — no WASM, no build steps. [Layout via Flexily](https://silvery.dev/guide/layout-engine) (or Yoga). Works on Alpine, CI, Docker, everywhere
+- **[Web-like responsive layout](https://silvery.dev/guide/silvery-vs-ink#responsive-layout)** — `useBoxRect()` returns actual dimensions during render. No post-render measurement, no two-pass layout cycle. Enables:
+  - [Scroll containers](https://silvery.dev/guide/scrolling) — `overflow="scroll"` with virtualization
+  - [Sticky positioning](https://silvery.dev/guide/layout-coordinates) — `position="sticky"` for headers and footers
+  - [ANSI-aware compositing](https://silvery.dev/guide/ansi-layering) — color blending with alpha across overlapping layers
+- **[Inline, fullscreen, or both](https://silvery.dev/guide/runtime-layers)** — same components, one-line switch. All with incremental rendering:
+  - [Fullscreen](https://silvery.dev/guide/runtime-getting-started) — alt screen, traditional TUI
+  - [Inline with dynamic scrollback](https://silvery.dev/examples/scrollback) — live React zone at bottom, completed items graduate to terminal-owned scrollback. Native Cmd+F and text selection
+  - [Virtual inline](https://silvery.dev/design/dynamic-scrollback) — alt screen + app-managed scrollback history, scrollable and searchable
+- **[Web-like interaction](https://silvery.dev/guide/event-handling)** — full keyboard and mouse events that just work. Modifier keys, mouse buttons, and drag all combine seamlessly into a single event model. Enables:
+  - [Focus scopes](https://silvery.dev/guide/silvery-vs-ink#focus-system) — spatial arrow-key nav, Tab/Escape, click-to-focus
+  - [Text selection](https://silvery.dev/guide/text-selection) — mouse drag, word/line, `userSelect` boundaries, Alt+drag override
+  - [Find](https://silvery.dev/guide/find) — `Ctrl+F` with match highlighting and `n`/`N` navigation
+  - [Copy-mode](https://silvery.dev/guide/clipboard) — `Esc, v` for vim-style keyboard selection and yanking
+  - [Drag-and-drop](https://silvery.dev/guide/event-handling) — mouse drag with hit testing
+- **[Rich component library](https://silvery.dev/guides/components)** — 45+ components: TextInput, SelectList, ListView, Table, TreeView, Tabs, CommandPalette, ModalDialog, Toast, and more. Every component automatically participates in focus, mouse, and keybindings (readline, vim) — no wiring needed. [38 theme palettes](https://silvery.dev/guide/styling) with semantic tokens (`$primary`, `$error`) and auto-detected terminal colors
+- **[Playwright-style testing](https://silvery.dev/guide/testing)** — 3,000+ tests. Full access to terminal internals (scrollback buffer, cursor position, cell styles, window dimensions):
+  - `createRenderer` — fast unit tests with auto-refreshing CSS locators, cell-level color assertions, frame-by-frame inspection
+  - [Termless](https://termless.dev) — like Playwright for terminals. Full ANSI fidelity with [10 swappable backends](https://termless.dev/guide/backends) (xterm.js, Ghostty, Alacritty, WezTerm, Kitty, and more)
+  - [`SILVERY_STRICT`](https://silvery.dev/guide/debugging) — multi-level verification: buffer (incremental vs fresh), ANSI (internal parser), terminal (cross-backend), and accumulated replay
+- **[Composable architecture](https://silvery.dev/guide/providers)** — every layer is independently swappable. [DI](https://silvery.dev/guide/providers) via `pipe()` providers:
+  - [Layout](https://silvery.dev/guide/layout-engine) — Flexily or Yoga
+  - [State](https://silvery.dev/guide/runtime-layers) — BYO (useState, Zustand, Jotai, Redux)
+  - [Term](https://silvery.dev/guide/runtime-layers) — real, headless, emulator
+  - [App](https://silvery.dev/guide/runtime-layers) — from stringify to rich app (withFocus, withDomEvents, withCommands). Render to terminal, Canvas, or DOM
+- **[All modern terminal protocols](https://silvery.dev/guide/silvery-vs-ink#terminal-protocol-coverage)** — [60 years of terminal protocols](https://terminfo.dev/about), unified into clean APIs. 100+ escape sequences you'll never have to write — auto-negotiated and gracefully degraded: [Kitty keyboard](https://terminfo.dev) + [SGR mouse](https://terminfo.dev) become rich events with modifiers; [hyperlinks](https://terminfo.dev) are just props; [clipboard](https://terminfo.dev) is a function call. Truecolor, underline styles, synchronized output, bracketed paste, focus reporting, resize detection, inline images, and [more](https://silvery.dev/guide/silvery-vs-ink#terminal-protocol-coverage)
 
 ### Why Silvery?
 
@@ -60,6 +71,12 @@ Along the way, three principles emerged. Take the best from the web, stay true t
 
 [The Silvery Way](https://silvery.dev/guide/the-silvery-way) · [Silvery vs Ink](https://silvery.dev/guide/silvery-vs-ink) · [About](https://silvery.dev/about)
 
+### Next steps
+
+- [Quick start](https://silvery.dev/getting-started/quick-start) — install, first app, deploy
+- [Interactive examples](https://silvery.dev/examples) — `npx silvery examples` to try them locally
+- [Silvery vs Ink](https://silvery.dev/guide/silvery-vs-ink) — feature comparison and migration guide
+
 ## Packages
 
 | Package                           | Description                                                       |
@@ -90,11 +107,11 @@ Standalone projects Silvery builds on — each stands on its own:
 - **Frameworks** — Svelte, Solid.js, Vue adapters
 - **@silvery/create** — Structured state management with commands, keybindings, effects-as-data
 
-**Runtimes:** Bun >= 1.0 and Node.js >= 18. CLI (`silvery` command) requires Bun.
+**Runtimes:** Bun >= 1.0 and Node.js >= 23.6. CLI (`silvery` command) requires Bun.
 
 ## Inspirations
 
-Silvery builds on ideas from [Ink](https://github.com/vadimdemedes/ink) (React for terminals), [Ratatui](https://ratatui.rs/) (cell-level buffer model), [SlateJS](https://www.slatejs.org/) (plugin composition, operations-as-data), [The Elm Architecture](https://guide.elm-lang.org/architecture/) / [BubbleTea](https://github.com/charmbracelet/bubbletea) (TEA state machines), the CSS/Web platform (flexbox, container queries, DOM events, focus scopes), [VS Code](https://code.visualstudio.com/) (command palette, keybindings), [Playwright](https://playwright.dev/) (locator-based testing), [ProseMirror](https://prosemirror.net/) (selection model), [Blessed](https://github.com/chjj/blessed) (rich terminal UIs in JS), and [Textual](https://textual.textualize.io/) (CSS-like terminal theming).
+Silvery builds on ideas from [Ink](https://github.com/vadimdemedes/ink) (React for terminals), [Ratatui](https://ratatui.rs/) (cell-level buffer model), [shadcn/ui](https://ui.shadcn.com/) (polished defaults, semantic theming), [SlateJS](https://www.slatejs.org/) (plugin composition, operations-as-data), [The Elm Architecture](https://guide.elm-lang.org/architecture/) / [BubbleTea](https://github.com/charmbracelet/bubbletea) (TEA state machines), the CSS/Web platform (flexbox, container queries, DOM events, focus scopes), [VS Code](https://code.visualstudio.com/) (command palette, keybindings), [Playwright](https://playwright.dev/) (locator-based testing), [ProseMirror](https://prosemirror.net/) (selection model), [Blessed](https://github.com/chjj/blessed) (rich terminal UIs in JS), and [Textual](https://textual.textualize.io/) (CSS-like terminal theming).
 
 ## License
 

package/bin/silvery.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+/**
+ * silvery CLI — delegates to @silvery/examples
+ * Works on both Node.js 23.6+ and Bun.
+ */
+import { resolve, dirname, join } from "node:path"
+import { readFileSync, existsSync } from "node:fs"
+import { spawn } from "node:child_process"
+import { fileURLToPath } from "node:url"
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+// Find package root by walking up looking for package.json with name "silvery"
+function findPackageRoot(startDir: string): string {
+  let dir = startDir
+  for (let i = 0; i < 10; i++) {
+    const pkg = join(dir, "package.json")
+    if (existsSync(pkg)) {
+      try {
+        const json = JSON.parse(readFileSync(pkg, "utf8"))
+        if (json.name === "silvery") return dir
+      } catch {}
+    }
+    const parent = dirname(dir)
+    if (parent === dir) break
+    dir = parent
+  }
+  return dirname(startDir)
+}
+
+// Detect runtime for spawning child processes
+const runtime = typeof globalThis.Bun !== "undefined" ? "bun" : "node"
+
+const root = findPackageRoot(__dirname)
+const args = process.argv.slice(2)
+const examplesCli = resolve(root, "packages/examples/bin/cli.ts")
+
+if (args.includes("--version") || args.includes("-v")) {
+  const pkg = JSON.parse(readFileSync(resolve(root, "package.json"), "utf8"))
+  console.log(`silvery ${pkg.version}`)
+  process.exit(0)
+}
+
+// Strip "examples" subcommand — the examples CLI handles bare args as example names
+const delegateArgs = args[0] === "examples" ? args.slice(1) : args
+
+const runArgs = runtime === "bun" ? ["run", examplesCli, ...delegateArgs] : [examplesCli, ...delegateArgs]
+const proc = spawn(runtime, runArgs, {
+  stdio: "inherit",
+})
+proc.on("exit", (code) => process.exit(code ?? 1))