silvery 0.3.0 → 0.4.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "silvery",
-  "version": "0.3.0",
-  "description": "React terminal UI renderer for complex interactive apps — layout-aware rendering, flexbox, scrolling, and incremental updates",
+  "version": "0.4.1",
+  "description": "React terminal UI renderer for complex interactive apps \u2014 layout-aware rendering, flexbox, scrolling, and incremental updates",
   "keywords": [
     "ansi",
     "chalk",
@@ -25,7 +25,7 @@
     "url": "https://github.com/beorn/silvery/issues"
   },
   "license": "MIT",
-  "author": "Bjørn Stabell <bjorn@stabell.org>",
+  "author": "Bj\u00f8rn Stabell <bjorn@stabell.org>",
   "repository": {
     "type": "git",
     "url": "https://github.com/beorn/silvery.git"
@@ -38,8 +38,8 @@
   ],
   "files": [
     "src",
-    "bin",
-    "examples"
+    "dist",
+    "bin"
   ],
   "type": "module",
   "main": "src/index.ts",
@@ -49,20 +49,72 @@
       "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/compat/src/ink.ts",
-      "import": "./packages/compat/src/ink.ts"
+      "types": "./packages/ink/src/ink.ts",
+      "import": "./packages/ink/src/ink.ts"
     },
     "./chalk": {
-      "types": "./packages/compat/src/chalk.ts",
-      "import": "./packages/compat/src/chalk.ts"
+      "types": "./packages/ink/src/chalk.ts",
+      "import": "./packages/ink/src/chalk.ts"
     }
   },
   "publishConfig": {
     "access": "public"
   },
   "scripts": {
-    "build": "bun build src/index.ts --outdir dist --target node",
+    "build": "bun run scripts/build.ts",
     "test": "bunx --bun vitest run",
     "test:fast": "bunx --bun vitest run --reporter=dot",
     "typecheck": "tsc --noEmit",
@@ -76,9 +128,9 @@
     "release": "changeset publish",
     "theme": "bun packages/theme/src/cli.ts",
     "demo": "bun examples/cli.ts",
-    "compat": "bun packages/compat/scripts/compat-check.ts",
-    "compat:ink": "bun packages/compat/scripts/compat-check.ts ink",
-    "compat:chalk": "bun packages/compat/scripts/compat-check.ts chalk"
+    "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",
@@ -101,7 +153,7 @@
     "playwright": "^1.58.2",
     "react": "^19.0.0",
     "typescript": "^5.5.0",
-    "vimonkey": "github:beorn/vimonkey",
+    "vimonkey": "^0.2.0",
     "vitepress": "^1.5.0",
     "vitepress-plugin-llms": "^1.0.0",
     "vitest": "^4.0.18",
@@ -114,4 +166,4 @@
     "bun": ">=1.0",
     "node": ">=18"
   }
-}
+}

package/src/index.ts

@@ -3,4 +3,70 @@
 
 export const VERSION = "0.0.1"
 
-export * from "@silvery/react"
+// 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"

package/examples/CLAUDE.md

@@ -1,75 +0,0 @@
-# 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

@@ -1,60 +0,0 @@
-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>
-  )
-}

package/examples/cli.ts

@@ -1,228 +0,0 @@
-#!/usr/bin/env bun
-/**
- * silvery demo CLI
- *
- * Lists and runs interactive demos from the examples/ directory.
- *
- * Usage:
- *   bun demo              — list all available demos grouped by category
- *   bun demo <name>       — run a specific demo by name (fuzzy match)
- *   bun demo --list       — same as no argument (list all)
- *   bun demo --help       — show usage help
- */
-
-import { resolve } from "node:path"
-import type { ExampleMeta } from "./_banner.js"
-
-// =============================================================================
-// Types
-// =============================================================================
-
-interface Example {
-  name: string
-  file: string
-  description: string
-  category: string
-  features?: string[]
-}
-
-// =============================================================================
-// Auto-Discovery (matches viewer.tsx pattern)
-// =============================================================================
-
-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,
-}
-
-async function discoverExamples(): Promise<Example[]> {
-  const baseDir = new URL(".", import.meta.url).pathname
-  const results: Example[] = []
-
-  for (const dir of CATEGORY_DIRS) {
-    const category = CATEGORY_DISPLAY[dir] ?? dir.charAt(0).toUpperCase() + dir.slice(1)
-    const dirPath = resolve(baseDir, dir)
-    const files = [
-      ...new Bun.Glob("*.tsx").scanSync({ cwd: dirPath }),
-      ...new Bun.Glob("*/index.tsx").scanSync({ cwd: dirPath }),
-    ]
-
-    for (const file of files) {
-      if (file.startsWith("_")) continue // skip internal files
-
-      try {
-        const mod = await import(resolve(dirPath, file))
-        if (!mod.meta?.name) continue
-
-        const meta: ExampleMeta = mod.meta
-        results.push({
-          name: meta.name,
-          description: meta.description ?? "",
-          file: resolve(dirPath, file),
-          category,
-          features: 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 Helpers
-// =============================================================================
-
-// ANSI color codes for lightweight terminal output without importing silvery
-const RESET = "\x1b[0m"
-const BOLD = "\x1b[1m"
-const DIM = "\x1b[2m"
-const YELLOW = "\x1b[33m"
-const CYAN = "\x1b[36m"
-const GREEN = "\x1b[32m"
-const MAGENTA = "\x1b[35m"
-const BLUE = "\x1b[34m"
-const RED = "\x1b[31m"
-const WHITE = "\x1b[37m"
-
-const CATEGORY_COLOR_CODE: Record<string, string> = {
-  Layout: MAGENTA,
-  Interactive: CYAN,
-  Runtime: GREEN,
-  Inline: YELLOW,
-  "Kitty Protocol": BLUE,
-}
-
-function printHelp(): void {
-  console.log(`
-${BOLD}${YELLOW}silvery demo${RESET} — browse and run interactive examples
-
-${BOLD}Usage:${RESET}
-  bun demo              List all available demos
-  bun demo ${DIM}<name>${RESET}       Run a demo by name (case-insensitive, partial match)
-  bun demo --list       List all available demos
-  bun demo --help       Show this help
-
-${BOLD}Examples:${RESET}
-  bun demo dashboard    Run the Dashboard demo
-  bun demo kanban       Run the Kanban Board demo
-  bun demo scroll       Run the first demo matching "scroll"
-`)
-}
-
-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_CODE[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 a demo: bun demo <name>${RESET}\n`)
-}
-
-/** Find an example by name. Tries exact match first, then case-insensitive
- *  prefix match, then case-insensitive substring match. */
-function findExample(examples: Example[], query: string): Example | undefined {
-  const q = query.toLowerCase()
-
-  // Exact match (case-insensitive)
-  const exact = examples.find((ex) => ex.name.toLowerCase() === q)
-  if (exact) return exact
-
-  // Prefix match (case-insensitive)
-  const prefix = examples.find((ex) => ex.name.toLowerCase().startsWith(q))
-  if (prefix) return prefix
-
-  // Substring match (case-insensitive)
-  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 demo matching "${query}"\n`)
-  console.error(`${DIM}Available demos:${RESET}`)
-
-  for (const ex of examples) {
-    console.error(`  ${WHITE}${ex.name}${RESET}`)
-  }
-
-  console.error(`\n${DIM}Run ${BOLD}bun demo${RESET}${DIM} for full list with descriptions.${RESET}\n`)
-}
-
-// =============================================================================
-// Main
-// =============================================================================
-
-async function main(): Promise<void> {
-  const args = process.argv.slice(2)
-
-  // Handle flags
-  if (args.includes("--help") || args.includes("-h")) {
-    printHelp()
-    return
-  }
-
-  const examples = await discoverExamples()
-
-  // No argument or --list: show the list
-  if (args.length === 0 || args[0] === "--list") {
-    printExampleList(examples)
-    return
-  }
-
-  // Treat all non-flag arguments as the demo name query
-  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)
-  }
-
-  // Run the matched example
-  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().catch((err) => {
-  console.error(err)
-  process.exit(1)
-})