silvery 0.3.0 → 0.4.0

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)
-})

package/examples/index.md

@@ -1,101 +0,0 @@
-# Silvery Examples
-
-Interactive examples demonstrating Silvery features. Organized by category.
-
-## Running Examples
-
-Browse all examples in the interactive viewer:
-
-```bash
-bun examples
-```
-
-Run any example standalone:
-
-```bash
-bun examples/<category>/<name>.tsx
-```
-
-## Structure
-
-Examples are organized into category directories. Each exports a `meta` object
-with `name` and `description`. The viewer auto-discovers all examples — no
-registry to maintain.
-
-```
-examples/
-  _banner.tsx           # Shared banner component (not an example)
-  viewer.tsx            # Interactive example browser
-  layout/               # Layout and responsive design
-  interactive/          # Keyboard-driven interactive apps
-  kitty/                # Kitty protocol features (graphics, keyboard)
-  runtime/              # Runtime layer demos (Layer 1-3)
-  inline/               # Inline mode and scrollback
-  playground/           # Web playground (not an example)
-  screenshots/          # Screenshot generation tool
-  web/                  # Web render targets (canvas, DOM)
-```
-
-## Layout
-
-| Example     | File                     | Description                                   |
-| ----------- | ------------------------ | --------------------------------------------- |
-| Dashboard   | `layout/dashboard.tsx`   | Multi-pane dashboard with keyboard navigation |
-| Live Resize | `layout/live-resize.tsx` | Responsive columns via `useContentRect()`     |
-| Overflow    | `layout/overflow.tsx`    | `overflow="hidden"` content clipping          |
-
-## Interactive
-
-| Example         | File                            | Description                                    |
-| --------------- | ------------------------------- | ---------------------------------------------- |
-| AI Coding Agent | `interactive/aichat/`           | Coding agent with streaming, tool calls        |
-| Todo App        | `interactive/app-todo.tsx`      | Layer 3: `createApp()` with Zustand store      |
-| Async Data      | `interactive/async-data.tsx`    | Suspense boundaries with `use()` hook          |
-| Kanban          | `interactive/kanban.tsx`        | Multi-column kanban with card movement         |
-| Layout Ref      | `interactive/layout-ref.tsx`    | `forwardRef` + `onLayout` callbacks            |
-| Scroll          | `interactive/scroll.tsx`        | Basic scrollable list                          |
-| Search Filter   | `interactive/search-filter.tsx` | React concurrent features (`useDeferredValue`) |
-| Task List       | `interactive/task-list.tsx`     | VirtualList with variable-height items         |
-| TextArea        | `interactive/textarea.tsx`      | Multi-line text input component                |
-| Virtual 10K     | `interactive/virtual-10k.tsx`   | VirtualList with 10,000 items                  |
-| Clipboard       | `interactive/clipboard.tsx`     | OSC 52 clipboard copy/paste across sessions    |
-| Paste Demo      | `interactive/paste-demo.tsx`    | Bracketed paste mode — paste as single event   |
-| Outline         | `interactive/outline.tsx`       | Outline vs border side-by-side comparison      |
-| Transform       | `interactive/transform.tsx`     | Text post-processing with Transform component  |
-
-## Kitty Protocol
-
-| Example         | File                        | Description                                      |
-| --------------- | --------------------------- | ------------------------------------------------ |
-| Image Viewer    | `kitty/images.tsx`          | Raw Kitty graphics protocol image display        |
-| Image Component | `kitty/image-component.tsx` | Declarative `<Image>` with protocol auto-detect  |
-| Key Events      | `kitty/keys.tsx`            | Interactive key chord tester with Kitty protocol |
-| Input           | `kitty/input.tsx`           | Kitty keyboard input demonstration               |
-| Canvas          | `kitty/canvas.tsx`          | Canvas rendering via Kitty graphics              |
-| Paint           | `kitty/paint.tsx`           | Terminal paint app using Kitty graphics          |
-
-## Runtime
-
-| Example         | File                          | Description                                      |
-| --------------- | ----------------------------- | ------------------------------------------------ |
-| Elm Counter     | `runtime/elm-counter.tsx`     | Layer 1: `createRuntime()` with Elm architecture |
-| Hello Runtime   | `runtime/hello-runtime.tsx`   | Layer 1: minimal static render                   |
-| Run Counter     | `runtime/run-counter.tsx`     | Layer 2: `run()` with React hooks                |
-| Runtime Counter | `runtime/runtime-counter.tsx` | Layer 1: `createRuntime()` with event loop       |
-
-## Inline
-
-| Example         | File                         | Description                                         |
-| --------------- | ---------------------------- | --------------------------------------------------- |
-| Inline Simple   | `inline/inline-simple.tsx`   | Basic inline rendering                              |
-| Inline Progress | `inline/inline-progress.tsx` | Inline progress bar                                 |
-| Inline Non-TTY  | `inline/inline-nontty.tsx`   | Inline output for piped/non-TTY                     |
-| Scrollback      | `inline/scrollback.tsx`      | REPL with `useScrollback` + VirtualList virtualized |
-
-## Creating New Examples
-
-1. Add a `.tsx` file in the appropriate category directory
-2. Export a `meta` object: `export const meta: ExampleMeta = { name: "...", description: "..." }`
-3. Export your main component as a named function
-4. Wrap with `ExampleBanner` in the `import.meta.main` block for standalone mode
-5. The viewer discovers it automatically — no registry to update

package/examples/inline/inline-nontty.tsx

@@ -1,98 +0,0 @@
-#!/usr/bin/env tsx
-/**
- * Example: Non-TTY Mode Support (km-silvery-nontty)
- *
- * Demonstrates silvery's non-TTY mode support for rendering in environments
- * without a terminal (pipes, CI, TERM=dumb).
- *
- * Run this example:
- *   # Normal TTY mode
- *   bun examples/inline-nontty.tsx
- *
- *   # Piped output (auto-detects non-TTY)
- *   bun examples/inline-nontty.tsx | cat
- *
- *   # Force plain text mode
- *   SILVERY_NONTTY=plain bun examples/inline-nontty.tsx
- *
- *   # Force line-by-line mode
- *   SILVERY_NONTTY=line-by-line bun examples/inline-nontty.tsx
- */
-
-import React, { useEffect, useState } from "react"
-import { Box, render, Text, useApp, createTerm, type NonTTYMode } from "../../src/index.js"
-import type { ExampleMeta } from "../_banner.js"
-
-export const meta: ExampleMeta = {
-  name: "Non-TTY Mode",
-  description: "Graceful degradation for pipes, CI, and TERM=dumb",
-  features: ["renderString()", "non-TTY output", "pipe-safe"],
-}
-
-function ProgressExample() {
-  const { exit } = useApp()
-  const [progress, setProgress] = useState(0)
-  const [done, setDone] = useState(false)
-
-  useEffect(() => {
-    const timer = setInterval(() => {
-      setProgress((prev) => {
-        const next = prev + 20
-        if (next >= 100) {
-          setDone(true)
-          clearInterval(timer)
-          return 100
-        }
-        return next
-      })
-    }, 300)
-
-    return () => clearInterval(timer)
-  }, [])
-
-  // Exit cleanly after showing "Complete!" for a moment
-  useEffect(() => {
-    if (!done) return
-    const timeout = setTimeout(() => exit(), 300)
-    return () => clearTimeout(timeout)
-  }, [done, exit])
-
-  const barWidth = 30
-  const filled = Math.floor((progress / 100) * barWidth)
-  const bar = "#".repeat(filled) + "-".repeat(barWidth - filled)
-
-  return (
-    <Box flexDirection="column">
-      <Text>Processing files...</Text>
-      <Text>
-        [{bar}] {progress}%
-      </Text>
-      {done && <Text color="green">Complete!</Text>}
-    </Box>
-  )
-}
-
-async function main() {
-  // Determine non-TTY mode from environment
-  const envMode = process.env.SILVERY_NONTTY as NonTTYMode | undefined
-  const nonTTYMode = envMode || "auto"
-
-  console.log(`Non-TTY mode: ${nonTTYMode}`)
-  console.log(`stdout.isTTY: ${process.stdout.isTTY}`)
-  console.log("---\n")
-
-  using term = createTerm()
-  const { waitUntilExit } = await render(<ProgressExample />, term, {
-    mode: "inline",
-    nonTTYMode,
-  })
-
-  await waitUntilExit()
-
-  console.log("\n---")
-  console.log("Done!")
-}
-
-if (import.meta.main) {
-  main().catch(console.error)
-}

package/examples/inline/inline-progress.tsx

@@ -1,79 +0,0 @@
-#!/usr/bin/env tsx
-/**
- * Example: Inline Progress Indicator
- *
- * Demonstrates the new inline mode for progress bars and status indicators.
- * Unlike fullscreen mode, inline mode renders from the current cursor position
- * and updates in place using relative cursor positioning.
- */
-
-import React, { useState, useEffect } from "react"
-import { render, Box, Text, useApp, createTerm } from "../../src/index.js"
-import type { ExampleMeta } from "../_banner.js"
-
-export const meta: ExampleMeta = {
-  name: "Inline Progress",
-  description: "Inline progress bar updating in place",
-  features: ["render() inline mode", "setInterval updates"],
-}
-
-function InlineProgress() {
-  const { exit } = useApp()
-  const [progress, setProgress] = useState(0)
-  const [status, setStatus] = useState("Starting...")
-
-  useEffect(() => {
-    const timer = setInterval(() => {
-      setProgress((prev) => {
-        const next = prev + 10
-        if (next >= 100) {
-          setStatus("Complete!")
-          clearInterval(timer)
-          return 100
-        }
-        setStatus(`Processing... ${next}%`)
-        return next
-      })
-    }, 500)
-
-    return () => clearInterval(timer)
-  }, [])
-
-  // Exit cleanly after showing "Complete!" for a moment
-  useEffect(() => {
-    if (progress < 100) return
-    const timeout = setTimeout(() => exit(), 300)
-    return () => clearTimeout(timeout)
-  }, [progress, exit])
-
-  const barWidth = 40
-  const filled = Math.floor((progress / 100) * barWidth)
-  const bar = "█".repeat(filled) + "░".repeat(barWidth - filled)
-
-  return (
-    <Box flexDirection="column">
-      <Text>{status}</Text>
-      <Text>
-        [{bar}] {progress}%
-      </Text>
-    </Box>
-  )
-}
-
-async function main() {
-  console.log("This is regular console output before the progress bar.\n")
-
-  using term = createTerm()
-  const { waitUntilExit } = await render(<InlineProgress />, term, {
-    mode: "inline",
-    exitOnCtrlC: true,
-  })
-
-  await waitUntilExit()
-
-  console.log("\nProgress complete! This is output after the progress bar.")
-}
-
-if (import.meta.main) {
-  main().catch(console.error)
-}

package/examples/inline/inline-simple.tsx

@@ -1,63 +0,0 @@
-#!/usr/bin/env bun
-/**
- * Simple inline mode test
- */
-
-import React, { useState, useEffect } from "react"
-import { render, Box, Text, useApp, createTerm } from "../../src/index.js"
-import type { ExampleMeta } from "../_banner.js"
-
-export const meta: ExampleMeta = {
-  name: "Inline Simple",
-  description: "Inline rendering from current cursor position",
-  features: ["render() inline mode", "one-shot output"],
-}
-
-function Counter() {
-  const { exit } = useApp()
-  const [count, setCount] = useState(0)
-
-  useEffect(() => {
-    const timer = setInterval(() => {
-      setCount((c) => {
-        if (c >= 5) {
-          clearInterval(timer)
-          return c
-        }
-        return c + 1
-      })
-    }, 500)
-
-    return () => clearInterval(timer)
-  }, [])
-
-  // Exit cleanly after count reaches 5
-  useEffect(() => {
-    if (count < 5) return
-    const timeout = setTimeout(() => exit(), 300)
-    return () => clearTimeout(timeout)
-  }, [count, exit])
-
-  return (
-    <Box>
-      <Text>Count: {count}</Text>
-    </Box>
-  )
-}
-
-async function main() {
-  console.log("Before\n")
-
-  using term = createTerm()
-  const { waitUntilExit } = await render(<Counter />, term, {
-    mode: "inline",
-  })
-
-  await waitUntilExit()
-
-  console.log("\nAfter")
-}
-
-if (import.meta.main) {
-  main().catch(console.error)
-}