silvery 0.0.1 → 0.4.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,78 @@
-# 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.
+Ink-compatible React renderer for terminals — same `Box`, `Text`, `useInput` API you know. Plus everything you wish Ink had.
+
+> **Note:** Under active development. APIs may change. Feedback welcome.
+
+```console
+$ npm install silvery react
+```
+
+```tsx
+import { useState } from "react"
+import { render, Box, Text, useInput } from "silvery"
+
+function Counter() {
+  const [count, setCount] = useState(0)
+  useInput((input) => {
+    if (input === "j") setCount((c) => c + 1)
+  })
+  return (
+    <Box borderStyle="round" padding={1}>
+      <Text>Count: {count}</Text>
+    </Box>
+  )
+}
+
+await render(<Counter />).run()
+```
+
+### Familiar
+
+- **React 18 + 19** — hooks, refs, effects, suspense — all works
+- **Flexbox layout** — `Box` with `flexDirection`, `padding`, `gap`, `flexGrow`, just like Ink
+- **Ink/Chalk compatible** — same component model, `@silvery/ink` compatibility layer for migration
+
+### Better
+
+- **Smaller install** — ~177 KB gzipped all included (Ink 6 pulls 16MB into node_modules)
+- **Pure TypeScript, zero native deps** — no WASM, no build steps — works on Alpine, CI, Docker, everywhere
+- **Incremental rendering** — per-node dirty tracking, [~100x faster interactive updates](tests/perf/render.bench.ts)
+- **Responsive layout** — `useContentRect()` returns actual dimensions synchronously during render
+- **Dynamic scrollback** — renders (and re-renders!) into the terminal's scroll history, not just alternate screen
+- **Scrollable containers** — `overflow="scroll"` with automatic measurement and clipping
+- **Theme system** — 38 palettes, semantic design/color tokens (`$primary`, `$error`), auto-detects terminal colors
+- **30+ components** — TextInput, TextArea, SelectList, VirtualList, Table, Tabs, CommandPalette, ModalDialog, Toast, and more
+- **Focus system** — scoped focus, arrow-key directional nav, click-to-focus
+- **Extremely composable** — use as just a renderer (`render`), add a runtime (`run`), or build full apps (`createApp`). Mix with any React state library (useState, Zustand, Jotai, Redux). Swap terminal backends (real TTY, headless, xterm.js emulator) for testing. Embed silvery components in existing CLIs. Use the layout engine standalone. Render to terminal, or (experimental) Canvas, or DOM
+- **Most complete terminal protocol support** — 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)
 
 ## 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`       | Components, hooks, renderer — the one package you need                                     |
+| `@silvery/test` | Testing utilities and locators                                                             |
+| `@silvery/ink`  | Ink compatibility layer                                                                    |
+| `@silvery/tea`  | Optional [TEA](https://guide.elm-lang.org/architecture/) state management for complex apps |
+
+## 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                          |
+
+## Coming
+
+- **Renderers** — Canvas 2D, Web DOM (experimental today, production later)
+- **Frameworks** — Svelte, Solid.js, Vue adapters
+- **@silvery/tea** — Structured state management with commands, keybindings, effects-as-data
+
+**Runtimes:** Bun >= 1.0 and Node.js >= 18. CLI (`silvery` command) requires Bun.
 
 ## 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/package.json

@@ -1,16 +1,169 @@
 {
   "name": "silvery",
-  "version": "0.0.1",
-  "description": "Multi-target rendering framework for React — terminal, browser, and beyond",
-  "keywords": ["react", "tui", "terminal", "rendering", "ui", "ink", "chalk", "cli"],
+  "version": "0.4.0",
+  "description": "React terminal UI renderer for complex interactive apps — layout-aware rendering, flexbox, scrolling, and incremental updates",
+  "keywords": [
+    "ansi",
+    "chalk",
+    "cli",
+    "flexbox",
+    "ink",
+    "ink-alternative",
+    "react",
+    "react-renderer",
+    "react-terminal",
+    "rendering",
+    "terminal",
+    "terminal-renderer",
+    "terminal-ui",
+    "text-ui",
+    "tui",
+    "ui"
+  ],
+  "homepage": "https://silvery.dev",
+  "bugs": {
+    "url": "https://github.com/beorn/silvery/issues"
+  },
   "license": "MIT",
   "author": "Bjørn Stabell <bjorn@stabell.org>",
-  "homepage": "https://silvery.dev",
   "repository": {
     "type": "git",
     "url": "https://github.com/beorn/silvery.git"
   },
+  "bin": {
+    "silvery": "./bin/silvery.ts"
+  },
+  "workspaces": [
+    "packages/*"
+  ],
+  "files": [
+    "src",
+    "dist",
+    "bin"
+  ],
   "type": "module",
   "main": "src/index.ts",
-  "files": ["src", "README.md"]
+  "types": "src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./runtime": {
+      "types": "./src/runtime.ts",
+      "import": "./src/runtime.ts"
+    },
+    "./theme": {
+      "types": "./src/theme.ts",
+      "import": "./src/theme.ts"
+    },
+    "./ui": {
+      "types": "./src/ui.ts",
+      "import": "./src/ui.ts"
+    },
+    "./ui/cli": {
+      "types": "./src/ui/cli.ts",
+      "import": "./src/ui/cli.ts"
+    },
+    "./ui/react": {
+      "types": "./src/ui/react.ts",
+      "import": "./src/ui/react.ts"
+    },
+    "./ui/progress": {
+      "types": "./src/ui/progress.ts",
+      "import": "./src/ui/progress.ts"
+    },
+    "./ui/wrappers": {
+      "types": "./src/ui/wrappers.ts",
+      "import": "./src/ui/wrappers.ts"
+    },
+    "./ui/ansi": {
+      "types": "./src/ui/ansi.ts",
+      "import": "./src/ui/ansi.ts"
+    },
+    "./ui/display": {
+      "types": "./src/ui/display.ts",
+      "import": "./src/ui/display.ts"
+    },
+    "./ui/input": {
+      "types": "./src/ui/input.ts",
+      "import": "./src/ui/input.ts"
+    },
+    "./ui/animation": {
+      "types": "./src/ui/animation.ts",
+      "import": "./src/ui/animation.ts"
+    },
+    "./ui/image": {
+      "types": "./src/ui/image.ts",
+      "import": "./src/ui/image.ts"
+    },
+    "./ui/utils": {
+      "types": "./src/ui/utils.ts",
+      "import": "./src/ui/utils.ts"
+    },
+    "./ink": {
+      "types": "./packages/ink/src/ink.ts",
+      "import": "./packages/ink/src/ink.ts"
+    },
+    "./chalk": {
+      "types": "./packages/ink/src/chalk.ts",
+      "import": "./packages/ink/src/chalk.ts"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun run scripts/build.ts",
+    "test": "bunx --bun vitest run",
+    "test:fast": "bunx --bun vitest run --reporter=dot",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint . && oxfmt --check .",
+    "fix": "oxlint --fix . && oxfmt --write .",
+    "docs:dev": "vitepress dev docs",
+    "docs:build": "vitepress build docs",
+    "docs:preview": "vitepress preview docs",
+    "changeset": "changeset",
+    "version": "changeset version",
+    "release": "changeset publish",
+    "theme": "bun packages/theme/src/cli.ts",
+    "demo": "bun examples/cli.ts",
+    "compat": "bun packages/ink/scripts/compat-check.ts",
+    "compat:ink": "bun packages/ink/scripts/compat-check.ts ink",
+    "compat:chalk": "bun packages/ink/scripts/compat-check.ts chalk"
+  },
+  "dependencies": {
+    "chalk": "^5.6.2",
+    "loggily": "github:beorn/loggily",
+    "react-reconciler": "^0.33.0",
+    "slice-ansi": "^8.0.0",
+    "string-width": "^8.2.0",
+    "zustand": "^5.0.11"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.27.0",
+    "@types/bun": "^1.1.0",
+    "@types/react": "^19.0.0",
+    "@xterm/addon-fit": "^0.11.0",
+    "@xterm/xterm": "^6.0.0",
+    "fast-check": "^4.6.0",
+    "mitata": "^1.0.34",
+    "oxfmt": "^0.36.0",
+    "oxlint": "^1.51.0",
+    "playwright": "^1.58.2",
+    "react": "^19.0.0",
+    "typescript": "^5.5.0",
+    "vimonkey": "^0.2.0",
+    "vitepress": "^1.5.0",
+    "vitepress-plugin-llms": "^1.0.0",
+    "vitest": "^4.0.18",
+    "yoga-wasm-web": "^0.3.3"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "engines": {
+    "bun": ">=1.0",
+    "node": ">=18"
+  }
 }

package/src/index.ts

@@ -1 +1,72 @@
+// silvery — multi-target rendering framework for React
+// Re-exports from @silvery/* packages
+
 export const VERSION = "0.0.1"
+
+// Re-export everything from @silvery/ag-react — local `render` below shadows the re-exported one
+export * from "@silvery/ag-react"
+
+import type { ReactElement } from "react"
+import { render as reactRender, type RenderOptions, type TermDef } from "@silvery/ag-react"
+import type { Term } from "@silvery/ag-react"
+
+/**
+ * Render a React element to the terminal.
+ *
+ * Zero-ceremony entry point — auto-detects the terminal and starts an
+ * interactive app when stdin is a TTY. No need to create a Term first.
+ *
+ * @example Hello World (2 lines)
+ * ```tsx
+ * import { render, Text } from "silvery"
+ * await render(<Text>Hello!</Text>).run()
+ * ```
+ *
+ * @example Interactive counter
+ * ```tsx
+ * import { useState } from "react"
+ * import { render, Box, Text, useInput } from "silvery"
+ *
+ * function Counter() {
+ *   const [count, setCount] = useState(0)
+ *   useInput((input) => {
+ *     if (input === "j") setCount((c) => c + 1)
+ *   })
+ *   return (
+ *     <Box borderStyle="round" padding={1}>
+ *       <Text>Count: {count}</Text>
+ *     </Box>
+ *   )
+ * }
+ *
+ * await render(<Counter />).run()
+ * ```
+ *
+ * @example Static render (explicit)
+ * ```tsx
+ * import { render, Text } from "silvery"
+ * await render(<Text>Report</Text>, { width: 120 })
+ * ```
+ *
+ * When called without a Term or TermDef:
+ * - **TTY detected** → interactive mode (stdin + stdout auto-wired)
+ * - **No TTY** → static mode (renders once and returns)
+ *
+ * Pass a Term or TermDef explicitly to override auto-detection.
+ */
+export function render(
+  element: ReactElement,
+  termOrDef?: Term | TermDef,
+  options?: RenderOptions,
+): ReturnType<typeof reactRender> {
+  // When no term/def is provided and we're in a TTY, auto-wire stdin/stdout
+  // so the app runs interactively (useInput works, app stays alive until exit).
+  if (!termOrDef && process.stdin?.isTTY && process.stdout?.isTTY) {
+    const ttyDef: TermDef = {
+      stdin: process.stdin,
+      stdout: process.stdout,
+    }
+    return reactRender(element, ttyDef, options)
+  }
+  return reactRender(element, termOrDef, options)
+}

package/src/runtime.ts

@@ -0,0 +1,4 @@
+// silvery/runtime — re-exports from @silvery/ag-term/runtime
+// run(), useInput, useExit, createRuntime, and related runtime APIs
+
+export * from "@silvery/ag-term/runtime"

package/src/theme.ts

@@ -0,0 +1,4 @@
+// silvery/theme — re-exports from @silvery/theme
+// Theme tokens, palettes, ThemeProvider, useTheme, color utilities
+
+export * from "@silvery/theme"

package/src/ui/animation.ts

@@ -0,0 +1,2 @@
+// silvery/ui/animation — animation utilities and hooks
+export * from "@silvery/ag-react/ui/animation"

package/src/ui/ansi.ts

@@ -0,0 +1,2 @@
+// silvery/ui/ansi — ANSI rendering utilities
+export * from "@silvery/ag-react/ui/ansi"

package/src/ui/cli.ts

@@ -0,0 +1,2 @@
+// silvery/ui/cli — CLI progress indicators (no React)
+export * from "@silvery/ag-react/ui/cli"

package/src/ui/display.ts

@@ -0,0 +1,2 @@
+// silvery/ui/display — display components
+export * from "@silvery/ag-react/ui/display"

package/src/ui/image.ts

@@ -0,0 +1,2 @@
+// silvery/ui/image — image display (kitty, sixel)
+export * from "@silvery/ag-react/ui/image"

package/src/ui/input.ts

@@ -0,0 +1,2 @@
+// silvery/ui/input — input components
+export * from "@silvery/ag-react/ui/input"

package/src/ui/progress.ts

@@ -0,0 +1,2 @@
+// silvery/ui/progress — task/progress wrappers
+export * from "@silvery/ag-react/ui/progress"

package/src/ui/react.ts

@@ -0,0 +1,2 @@
+// silvery/ui/react — React progress components
+export * from "@silvery/ag-react/ui/react"

package/src/ui/utils.ts

@@ -0,0 +1,2 @@
+// silvery/ui/utils — UI utilities
+export * from "@silvery/ag-react/ui/utils"

package/src/ui/wrappers.ts

@@ -0,0 +1,2 @@
+// silvery/ui/wrappers — task wrappers (fluent task API)
+export * from "@silvery/ag-react/ui/wrappers"

package/src/ui.ts

@@ -0,0 +1,4 @@
+// silvery/ui — re-exports from @silvery/ag-react/ui
+// Component library (progress, CLI, wrappers)
+
+export * from "@silvery/ag-react/ui"