silvery 0.0.1 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Bjørn Stabell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,19 +1,182 @@
-# silvery
+# Silvery
 
-Multi-target rendering framework for React — terminal, browser, and beyond.
+**Polished Terminal UIs in React.**
 
-**Coming soon.** See [silvery.dev](https://silvery.dev) for details.
+Responsive layouts, scrollable containers, 100x+ faster incremental updates, and full support for modern terminal capabilities. 30+ components from TextInput to VirtualList. Pure TypeScript, no WASM.
+
+```
+npm install silvery react
+```
+
+> **Status:** Alpha — under active development. APIs may change. Early adopters and feedback welcome.
+
+```tsx
+import { useState } from "react"
+import { render, Box, Text, useInput, useContentRect, createTerm } from "silvery"
+
+function App() {
+  const { width } = useContentRect()
+  const [count, setCount] = useState(0)
+
+  useInput((input) => {
+    if (input === "j") setCount((c) => c + 1)
+    if (input === "k") setCount((c) => c - 1)
+    if (input === "q") return "exit"
+  })
+
+  return (
+    <Box flexDirection="column" padding={1}>
+      <Text bold>Counter ({width} cols wide)</Text>
+      <Text>Count: {count}</Text>
+      <Text dim>j/k = change, q = quit</Text>
+    </Box>
+  )
+}
+
+using term = createTerm()
+await render(<App />, term).run()
+```
+
+## Renderer
+
+### Responsive layout
+
+`useContentRect()` returns actual dimensions synchronously -- no post-layout effect, no `{width: 0, height: 0}` on first render. Components adapt to their available space immediately.
+
+```tsx
+function Responsive() {
+  const { width } = useContentRect()
+  return width > 80 ? <FullDashboard /> : <CompactView />
+}
+```
+
+### Scrollable containers
+
+`overflow="scroll"` with `scrollTo` -- the framework handles measurement, clipping, and scroll position. No manual virtualization needed.
+
+```tsx
+<Box height={20} overflow="scroll" scrollTo={selectedIndex}>
+  {items.map((item) => (
+    <Card key={item.id} item={item} />
+  ))}
+</Box>
+```
+
+### Per-node dirty tracking
+
+Seven independent dirty flags per node. When a user presses a key, only the affected nodes re-render -- bypassing React reconciliation entirely for unchanged subtrees. Typical interactive updates complete in ~170 microseconds for 1000 nodes, compared to full-tree re-renders.
+
+### Multi-target rendering
+
+Terminal today, Canvas 2D and DOM experimental. Same React components, different rendering backends.
+
+## Framework Layers (Optional)
+
+### Input layer stack
+
+DOM-style event bubbling with modal isolation. Opening a dialog automatically captures input -- no manual guard checks in every handler.
+
+```tsx
+<InputLayerProvider>
+  <Board />
+  {isOpen && <Dialog />} {/* Dialog captures input; Board doesn't see it */}
+</InputLayerProvider>
+```
+
+### Spatial focus navigation
+
+Tree-based focus with scopes, arrow-key directional movement, click-to-focus, and `useFocusWithin`. Go beyond tab-order.
+
+### Command and keybinding system
+
+Named commands with IDs, help text, configurable keybindings, and runtime introspection. Build discoverable, AI-automatable interfaces.
+
+```tsx
+const MyComponent = withCommands(BaseComponent, () => [
+  { id: "save", label: "Save", keys: ["ctrl+s"], action: () => save() },
+  { id: "quit", label: "Quit", keys: ["q", "ctrl+c"], action: () => exit() },
+])
+```
+
+### Mouse support
+
+SGR mouse protocol with DOM-style event props -- `onClick`, `onMouseDown`, `onWheel`, hit testing, drag support.
+
+### Multi-line text editing
+
+Built-in `TextArea` with word wrap, scrolling, cursor movement, selection, and undo/redo via `EditContext`.
+
+### 30+ built-in components
+
+TextArea, TextInput, VirtualList, SelectList, Table, CommandPalette, ModalDialog, Tabs, TreeView, SplitView, Toast, Image, and more -- all with built-in scrolling, focus, and input handling.
+
+### Theme system
+
+`@silvery/theme` with 38 built-in palettes and semantic color tokens (`$primary`, `$error`, `$border`, etc.) that adapt automatically.
+
+### TEA state machines
+
+Optional [Elm Architecture](https://guide.elm-lang.org/architecture/) alongside React hooks. Pure `(action, state) -> [state, effects]` functions for testable, replayable, undoable UI logic.
 
 ## Packages
 
-- `silvery` — umbrella package (re-exports all `@silvery/*` packages)
-- `@silvery/react` — core React reconciler and runtime
-- `@silvery/term` — terminal rendering target
-- `@silvery/ansi` — ANSI styling (chalk replacement)
-- `@silvery/theme` — theming system
-- `@silvery/ui` — component library
-- `@silvery/test` — testing utilities
-- `@silvery/tea` — TEA state machine store
+| Package                              | Description                               |
+| ------------------------------------ | ----------------------------------------- |
+| [`silvery`](packages/)               | Umbrella -- re-exports `@silvery/react`   |
+| [`@silvery/react`](packages/react)   | React reconciler, hooks, renderer         |
+| [`@silvery/term`](packages/term)     | Terminal rendering pipeline, ANSI styling |
+| [`@silvery/ui`](packages/ui)         | Component library (30+ components)        |
+| [`@silvery/theme`](packages/theme)   | Theming with 38 palettes                  |
+| [`@silvery/tea`](packages/tea)       | TEA state machine store                   |
+| [`@silvery/compat`](packages/compat) | Ink/Chalk compatibility layers            |
+| [`@silvery/test`](packages/test)     | Testing utilities and locators            |
+
+## Compatibility
+
+`silvery/ink` and `silvery/chalk` provide compatibility layers for existing React terminal apps. The core API (`Box`, `Text`, `useInput`, `render`) is intentionally familiar -- most existing code works with minimal changes. See the [migration guide](docs/guide/migration.md) for details.
+
+## When to Use Silvery
+
+Silvery is designed for **complex interactive TUIs** — dashboards, editors, kanban boards, chat interfaces. If you need scrollable containers, mouse support, spatial focus, or components that adapt to their size, Silvery provides these out of the box.
+
+For simple one-shot CLI prompts or spinners, mature alternatives with larger plugin ecosystems may be a better fit today.
+
+## Ecosystem
+
+| Project                                    | What                                                           |
+| ------------------------------------------ | -------------------------------------------------------------- |
+| [Termless](https://termless.dev)           | Headless terminal testing -- like Playwright for terminal apps |
+| [Flexily](https://beorn.github.io/flexily) | Pure JS flexbox layout engine (Yoga-compatible, zero WASM)     |
+| [Loggily](https://beorn.github.io/loggily) | Debug + structured logging + tracing                           |
+
+See the [roadmap](https://silvery.dev/roadmap) for what's next.
+
+## Performance
+
+_Apple M1 Max, Bun 1.3.9. Reproduce: `bun run bench:compare`_
+
+| Scenario                                | Silvery | Ink 5   |
+| --------------------------------------- | ------- | ------- |
+| Cold render (1 component)               | 165 us  | 271 us  |
+| Cold render (1000 components)           | 463 ms  | 541 ms  |
+| Typical interactive update (1000 nodes) | 169 us  | 20.7 ms |
+| Layout (50-node kanban)                 | 57 us   | 88 us   |
+
+**Why the difference?** Interactive updates (cursor move, scroll, toggle) typically change one or two nodes. Silvery's per-node dirty tracking updates only those nodes — 169 us for a 1000-node tree. Traditional full-tree renderers re-render the entire React tree and run complete layout on every state change — 20.7 ms. For the updates that dominate interactive use, Silvery is ~100x faster.
+
+Full re-renders where the entire tree changes are comparable or faster in full-tree renderers (simpler string concatenation vs Silvery's 5-phase pipeline). That trade-off is inherent to supporting responsive layout, and full re-renders are rare in interactive apps.
+
+## Documentation
+
+Full docs at [silvery.dev](https://silvery.dev) -- getting started guide, API reference, component catalog, and migration guide.
+
+## Development
+
+```bash
+bun install
+bun test
+bun run lint
+```
 
 ## License
 

package/bin/silvery.ts

@@ -0,0 +1,258 @@
+#!/usr/bin/env bun
+/**
+ * silvery CLI
+ *
+ * Usage:
+ *   silvery example              — list all available examples
+ *   silvery example <name>       — run an example by name (fuzzy match)
+ *   silvery example --list       — list all available examples
+ *   silvery --help               — show usage help
+ *
+ * Designed for: bunx silvery example <name>
+ */
+
+// =============================================================================
+// ANSI helpers (no deps — must work before anything is imported)
+// =============================================================================
+
+const RESET = "\x1b[0m"
+const BOLD = "\x1b[1m"
+const DIM = "\x1b[2m"
+const RED = "\x1b[31m"
+const GREEN = "\x1b[32m"
+const YELLOW = "\x1b[33m"
+const BLUE = "\x1b[34m"
+const MAGENTA = "\x1b[35m"
+const CYAN = "\x1b[36m"
+const WHITE = "\x1b[37m"
+
+// =============================================================================
+// Types
+// =============================================================================
+
+interface Example {
+  name: string
+  file: string
+  description: string
+  category: string
+  features?: string[]
+}
+
+// =============================================================================
+// Auto-Discovery (mirrors examples/cli.ts)
+// =============================================================================
+
+const CATEGORY_DIRS = ["layout", "interactive", "runtime", "inline", "kitty"] as const
+
+const CATEGORY_DISPLAY: Record<string, string> = {
+  kitty: "Kitty Protocol",
+}
+
+const CATEGORY_ORDER: Record<string, number> = {
+  Layout: 0,
+  Interactive: 1,
+  Runtime: 2,
+  Inline: 3,
+  "Kitty Protocol": 4,
+}
+
+const CATEGORY_COLOR: Record<string, string> = {
+  Layout: MAGENTA,
+  Interactive: CYAN,
+  Runtime: GREEN,
+  Inline: YELLOW,
+  "Kitty Protocol": BLUE,
+}
+
+async function discoverExamples(): Promise<Example[]> {
+  const { resolve } = await import("node:path")
+  const examplesDir = resolve(new URL(".", import.meta.url).pathname, "../examples")
+  const results: Example[] = []
+
+  for (const dir of CATEGORY_DIRS) {
+    const category = CATEGORY_DISPLAY[dir] ?? dir.charAt(0).toUpperCase() + dir.slice(1)
+    const glob = new Bun.Glob("*.tsx")
+    const dirPath = resolve(examplesDir, dir)
+
+    for (const file of glob.scanSync({ cwd: dirPath })) {
+      if (file.startsWith("_")) continue
+
+      try {
+        const mod = await import(resolve(dirPath, file))
+        if (!mod.meta?.name) continue
+
+        results.push({
+          name: mod.meta.name,
+          description: mod.meta.description ?? "",
+          file: resolve(dirPath, file),
+          category,
+          features: mod.meta.features,
+        })
+      } catch {
+        // Skip files that fail to import
+      }
+    }
+  }
+
+  results.sort((a, b) => {
+    const catDiff = (CATEGORY_ORDER[a.category] ?? 99) - (CATEGORY_ORDER[b.category] ?? 99)
+    if (catDiff !== 0) return catDiff
+    return a.name.localeCompare(b.name)
+  })
+
+  return results
+}
+
+// =============================================================================
+// Formatting
+// =============================================================================
+
+function printHelp(): void {
+  console.log(`
+${BOLD}${YELLOW}silvery${RESET} — React framework for modern terminal UIs
+
+${BOLD}Usage:${RESET}
+  silvery example              List all available examples
+  silvery example ${DIM}<name>${RESET}       Run an example by name (fuzzy match)
+  silvery example --list       List all available examples
+  silvery --help               Show this help
+  silvery --version            Show version
+
+${BOLD}Examples:${RESET}
+  bunx silvery example todo        Run the Todo App example
+  bunx silvery example kanban      Run the Kanban Board example
+  bunx silvery example dashboard   Run the Dashboard example
+
+${DIM}Documentation: https://silvery.dev${RESET}
+`)
+}
+
+function printExampleList(examples: Example[]): void {
+  console.log(`\n${BOLD}${YELLOW} silvery${RESET}${DIM} examples${RESET}\n`)
+
+  let currentCategory = ""
+
+  for (const ex of examples) {
+    if (ex.category !== currentCategory) {
+      currentCategory = ex.category
+      const color = CATEGORY_COLOR[currentCategory] ?? WHITE
+      console.log(`  ${color}${BOLD}${currentCategory}${RESET}`)
+    }
+
+    const nameStr = `${BOLD}${WHITE}${ex.name}${RESET}`
+    const descStr = `${DIM}${ex.description}${RESET}`
+    console.log(`    ${nameStr}  ${descStr}`)
+  }
+
+  console.log(`\n  ${DIM}Run an example: bunx silvery example <name>${RESET}\n`)
+}
+
+function findExample(examples: Example[], query: string): Example | undefined {
+  const q = query.toLowerCase()
+
+  const exact = examples.find((ex) => ex.name.toLowerCase() === q)
+  if (exact) return exact
+
+  const prefix = examples.find((ex) => ex.name.toLowerCase().startsWith(q))
+  if (prefix) return prefix
+
+  const substring = examples.find((ex) => ex.name.toLowerCase().includes(q))
+  if (substring) return substring
+
+  return undefined
+}
+
+function printNoMatch(query: string, examples: Example[]): void {
+  console.error(`\n${RED}${BOLD}Error:${RESET} No example matching "${query}"\n`)
+  console.error(`${DIM}Available examples:${RESET}`)
+
+  for (const ex of examples) {
+    console.error(`  ${WHITE}${ex.name}${RESET}`)
+  }
+
+  console.error(`\n${DIM}Run ${BOLD}bunx silvery example${RESET}${DIM} for full list with descriptions.${RESET}\n`)
+}
+
+// =============================================================================
+// Subcommands
+// =============================================================================
+
+async function exampleCommand(args: string[]): Promise<void> {
+  if (args.includes("--help") || args.includes("-h")) {
+    printHelp()
+    return
+  }
+
+  const examples = await discoverExamples()
+
+  if (args.length === 0 || args[0] === "--list" || args[0] === "-l") {
+    printExampleList(examples)
+    return
+  }
+
+  const query = args.filter((a) => !a.startsWith("--")).join(" ")
+  if (!query) {
+    printExampleList(examples)
+    return
+  }
+
+  const match = findExample(examples, query)
+  if (!match) {
+    printNoMatch(query, examples)
+    process.exit(1)
+  }
+
+  console.log(`${DIM}Running ${BOLD}${match.name}${RESET}${DIM}...${RESET}\n`)
+
+  const proc = Bun.spawn(["bun", "run", match.file], {
+    stdio: ["inherit", "inherit", "inherit"],
+  })
+  const exitCode = await proc.exited
+  process.exit(exitCode)
+}
+
+// =============================================================================
+// Main
+// =============================================================================
+
+async function main(): Promise<void> {
+  const args = process.argv.slice(2)
+
+  // Top-level flags
+  if (args.includes("--help") || args.includes("-h") || args.length === 0) {
+    printHelp()
+    return
+  }
+
+  if (args.includes("--version") || args.includes("-v")) {
+    try {
+      const { resolve } = await import("node:path")
+      const pkgPath = resolve(new URL(".", import.meta.url).pathname, "../package.json")
+      const pkg = await Bun.file(pkgPath).json()
+      console.log(`silvery ${pkg.version}`)
+    } catch {
+      console.log("silvery (version unknown)")
+    }
+    return
+  }
+
+  const subcommand = args[0]
+  const subArgs = args.slice(1)
+
+  switch (subcommand) {
+    case "example":
+    case "examples":
+    case "demo":
+      await exampleCommand(subArgs)
+      break
+    default:
+      // If user types "silvery todo", treat it as "silvery example todo"
+      await exampleCommand(args)
+      break
+  }
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})

package/examples/CLAUDE.md

@@ -0,0 +1,75 @@
+# Silvery Examples & Showcases
+
+## Directory Structure
+
+| Directory      | What                                                       |
+| -------------- | ---------------------------------------------------------- |
+| `interactive/` | Full apps — run with `bun examples/interactive/<name>.tsx` |
+| `inline/`      | Inline mode examples (no alt screen)                       |
+| `kitty/`       | Kitty protocol demos                                       |
+| `layout/`      | Layout engine examples                                     |
+| `runtime/`     | Runtime layer demos (run, createApp, createStore)          |
+| `playground/`  | Quick prototyping                                          |
+| `web/`         | Browser renderers (DOM, Canvas2D)                          |
+| `screenshots/` | Reference screenshots for visual regression                |
+
+## Making a Great Showcase
+
+### Design Principles
+
+1. **Show, don't tell.** A showcase should demonstrate Silvery features through working UI, not walls of text. Intro text is fine — but collapse it once the demo starts.
+
+2. **Auto-size to content.** `ScrollbackView`/`ScrollbackList` auto-size to their content — no manual height management. The output phase caps output at terminal height independently. Content that exceeds terminal height causes natural terminal scrolling.
+
+3. **Single status bar.** Keep the status bar to one line. Include: context bar, elapsed time, cost, and key hints. Remove anything that doesn't help the user interact.
+
+4. **Conditional headers.** Show feature bullets before the demo starts (when there's space). Collapse to a one-liner once content fills the screen.
+
+5. **Respect terminal width.** Boxes with borders at 120 cols should leave room for the border characters. Test at 80 and 120 cols.
+
+6. **Streaming feels real.** For coding agent demos: thinking spinner (1-2s) → word-by-word text reveal → tool call spinner → output. Use `setInterval` at 50ms with 8-12% fraction increments.
+
+### Scrollback Pattern
+
+Use `ScrollbackList` (or `ScrollbackView`) — they handle terminal height, footer pinning, and overflow automatically:
+
+```tsx
+function App() {
+  return (
+    <ScrollbackList
+      items={items}
+      keyExtractor={(item) => item.id}
+      isFrozen={(item) => item.done}
+      markers={true}
+      footer={<StatusBar />}
+    >
+      {(item) => <ItemView item={item} />}
+    </ScrollbackList>
+  )
+}
+
+await render(<App />, term, { mode: "inline" })
+```
+
+`ScrollbackView` auto-sizes to its content — no manual height management. The output phase independently caps output at terminal height (via `inlineFullRender()`), so content that exceeds the terminal causes natural scrolling. The footer stays pinned at the bottom of the content.
+
+### Theme Tokens
+
+Use semantic `$token` colors instead of hardcoded values:
+
+| Token      | Use for                               |
+| ---------- | ------------------------------------- |
+| `$primary` | Active elements, progress bars, links |
+| `$success` | Completed items, checkmarks           |
+| `$warning` | Caution, compaction                   |
+| `$error`   | Failures, diff removals               |
+| `$muted`   | Secondary info, timestamps            |
+| `$border`  | Default border color                  |
+
+### Testing Showcases
+
+1. **Visual check**: Run in TTY and step through all states
+2. **Resize**: Verify layout adapts to terminal resize
+3. **Scrollback**: After frozen items, scroll up — verify colors/borders preserved
+4. **Width**: Test at 80 and 120 columns
+5. **Fast mode**: `--fast` flag should skip all animation for quick validation

package/examples/_banner.tsx

@@ -0,0 +1,60 @@
+import React from "react"
+import { Box, Text, Strong, Muted, ThemeProvider, getThemeByName, type Theme } from "../src/index.js"
+
+export interface ExampleMeta {
+  name: string
+  description: string
+  /** API features showcased, e.g. ["VirtualList", "useContentRect()"] */
+  features?: string[]
+  /** Curated demo — shown in CLI viewer (`bun examples`) and web showcase */
+  demo?: boolean
+}
+
+interface Props {
+  meta: ExampleMeta
+  /** Short controls legend, e.g. "j/k navigate  q quit" */
+  controls?: string
+  /** Override theme (from viewer). Falls back to SILVERY_THEME env var. */
+  theme?: Theme
+  children: React.ReactNode
+}
+
+/**
+ * Compact header shown when examples run standalone.
+ * Wraps children in ThemeProvider for consistent theming.
+ */
+export function ExampleBanner({ meta, controls, theme, children }: Props) {
+  const resolvedTheme = theme ?? getThemeByName(process.env.SILVERY_THEME)
+
+  return (
+    <ThemeProvider theme={resolvedTheme}>
+      <Box flexDirection="column" flexGrow={1}>
+        {/* One-line header: dimmed to not compete with example UI */}
+        <Box paddingX={1} gap={1}>
+          <Text dim color="$warning">
+            {"▸ silvery"}
+          </Text>
+          <Strong>{meta.name}</Strong>
+          <Muted>— {meta.description}</Muted>
+        </Box>
+        {meta.features && meta.features.length > 0 && (
+          <Box paddingX={1}>
+            <Muted>
+              {"  "}
+              {meta.features.join(" · ")}
+            </Muted>
+          </Box>
+        )}
+        {controls && (
+          <Box paddingX={1}>
+            <Muted>
+              {"  "}
+              {controls}
+            </Muted>
+          </Box>
+        )}
+        {children}
+      </Box>
+    </ThemeProvider>
+  )
+}