silvery 0.3.0 → 0.4.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)
-}

package/examples/inline/scrollback.tsx

@@ -1,185 +0,0 @@
-/**
- * Scrollback Mode — REPL
- *
- * Interactive expression evaluator demonstrating useScrollback + VirtualList virtualized.
- * Completed results freeze into terminal scrollback; the active prompt stays at bottom.
- *
- * Controls:
- *   Type expression + Enter  - Evaluate
- *   q (when input empty)     - Quit
- */
-
-import React, { useState, useCallback } from "react"
-import { Box, Text, Divider, VirtualList, useInput, type Key } from "../../src/index.js"
-import { run, useExit } from "@silvery/term/runtime"
-import { useScrollback } from "../../src/hooks/useScrollback.js"
-import { ExampleBanner, type ExampleMeta } from "../_banner.js"
-
-export const meta: ExampleMeta = {
-  name: "Scrollback",
-  description: "REPL with useScrollback + VirtualList virtualized for terminal scrollback",
-  features: ["useScrollback()", "VirtualList virtualized", "inline mode"],
-}
-
-// =============================================================================
-// Data
-// =============================================================================
-
-interface Result {
-  id: number
-  expr: string
-  value: string
-  frozen: boolean
-}
-
-let nextId = 0
-
-function evaluate(expr: string): string {
-  try {
-    // eslint-disable-next-line no-eval
-    return String(eval(expr))
-  } catch (e: unknown) {
-    return `Error: ${e instanceof Error ? e.message : String(e)}`
-  }
-}
-
-// =============================================================================
-// Component
-// =============================================================================
-
-export function Repl() {
-  const exit = useExit()
-  const [results, setResults] = useState<Result[]>([])
-  const [input, setInput] = useState("")
-  const [cursor, setCursor] = useState(0)
-
-  // Push frozen results to terminal scrollback
-  const frozenCount = useScrollback(results, {
-    frozen: (r) => r.frozen,
-    render: (r) => `$ ${r.expr}\n→ ${r.value}`,
-  })
-
-  const submit = useCallback(() => {
-    const expr = input.trim()
-    if (!expr) return
-
-    const value = evaluate(expr)
-    const id = nextId++
-
-    // Mark all existing results as frozen, add new one unfrozen
-    setResults((prev) => [...prev.map((r) => ({ ...r, frozen: true })), { id, expr, value, frozen: false }])
-    setInput("")
-    setCursor(0)
-  }, [input])
-
-  useInput((ch: string, key: Key) => {
-    if (key.return) {
-      submit()
-      return
-    }
-    if (key.escape || (ch === "q" && input === "")) {
-      exit()
-      return
-    }
-    if (key.backspace) {
-      if (cursor > 0) {
-        setInput((v) => v.slice(0, cursor - 1) + v.slice(cursor))
-        setCursor((c) => c - 1)
-      }
-      return
-    }
-    if (key.leftArrow) {
-      setCursor((c) => Math.max(0, c - 1))
-      return
-    }
-    if (key.rightArrow) {
-      setCursor((c) => Math.min(input.length, c + 1))
-      return
-    }
-    // Ctrl+A: beginning of line
-    if (key.ctrl && ch === "a") {
-      setCursor(0)
-      return
-    }
-    // Ctrl+E: end of line
-    if (key.ctrl && ch === "e") {
-      setCursor(input.length)
-      return
-    }
-    // Ctrl+U: clear line
-    if (key.ctrl && ch === "u") {
-      setInput("")
-      setCursor(0)
-      return
-    }
-    if (ch >= " ") {
-      setInput((v) => v.slice(0, cursor) + ch + v.slice(cursor))
-      setCursor((c) => c + 1)
-    }
-  })
-
-  const activeCount = results.length - frozenCount
-  const beforeCursor = input.slice(0, cursor)
-  const atCursor = input[cursor] ?? " "
-  const afterCursor = input.slice(cursor + 1)
-
-  return (
-    <Box flexDirection="column">
-      {/* Active (non-virtualized) results via VirtualList */}
-      {activeCount > 0 && (
-        <VirtualList
-          items={results}
-          virtualized={(r) => r.frozen}
-          height={activeCount * 2}
-          itemHeight={2}
-          scrollTo={0}
-          renderItem={(r) => (
-            <Box key={r.id} flexDirection="column">
-              <Text>
-                <Text color="gray">{"$ "}</Text>
-                <Text>{r.expr}</Text>
-              </Text>
-              <Text>
-                <Text color="cyan">{"→ "}</Text>
-                <Text>{r.value}</Text>
-              </Text>
-            </Box>
-          )}
-        />
-      )}
-
-      {/* Separator */}
-      <Divider />
-
-      {/* Input prompt */}
-      <Text>
-        <Text color="yellow">{"› "}</Text>
-        <Text>{beforeCursor}</Text>
-        <Text inverse>{atCursor}</Text>
-        <Text>{afterCursor}</Text>
-      </Text>
-
-      {/* Status */}
-      <Text dim>
-        {results.length} result{results.length !== 1 ? "s" : ""} | Esc/q to quit
-      </Text>
-    </Box>
-  )
-}
-
-// =============================================================================
-// Main
-// =============================================================================
-
-async function main() {
-  await run(
-    <ExampleBanner meta={meta} controls="Type expr + Enter  Esc/q quit">
-      <Repl />
-    </ExampleBanner>,
-    { mode: "inline" },
-  )
-}
-
-if (import.meta.main) {
-  main().catch(console.error)
-}

package/examples/interactive/_input-debug.tsx

@@ -1,110 +0,0 @@
-/**
- * Input Debug Tool
- *
- * Minimal diagnostic to find where keypresses are lost.
- * Shows every event received by useInput + TextArea side by side.
- *
- * Run: bun vendor/silvery/examples/interactive/_input-debug.tsx
- */
-
-import React, { useState, useRef } from "react"
-import { render, Box, Text, TextArea, useInput, useApp, createTerm, type Key } from "../../src/index.js"
-
-function InputDebug(): JSX.Element {
-  const { exit } = useApp()
-
-  // Track raw useInput events
-  const [rawEvents, setRawEvents] = useState<string[]>([])
-  const rawCountRef = useRef(0)
-
-  // Track TextArea value
-  const [textValue, setTextValue] = useState("")
-  const textChangeCountRef = useRef(0)
-
-  // Raw useInput handler — logs EVERY event
-  useInput((input: string, key: Key) => {
-    if (key.escape) {
-      exit()
-      return
-    }
-    rawCountRef.current++
-    const desc = describeKey(input, key)
-    setRawEvents((prev) => [...prev.slice(-15), `#${rawCountRef.current} ${desc}`])
-  })
-
-  // TextArea onChange handler
-  function handleChange(value: string) {
-    textChangeCountRef.current++
-    setTextValue(value)
-  }
-
-  return (
-    <Box flexDirection="column" padding={1}>
-      <Text bold color="cyan">
-        Input Pipeline Diagnostic
-      </Text>
-      <Text dim>Type slowly (1 char/2sec). Compare left (raw events) vs right (TextArea value).</Text>
-      <Text dim>Press Esc to quit.</Text>
-      <Box height={1} />
-
-      <Box gap={4}>
-        {/* Left: Raw useInput events */}
-        <Box flexDirection="column" width={40}>
-          <Text bold color="yellow">
-            useInput events: {rawCountRef.current}
-          </Text>
-          {rawEvents.map((e, i) => (
-            <Text key={i} dimColor={i < rawEvents.length - 1}>
-              {e}
-            </Text>
-          ))}
-        </Box>
-
-        {/* Right: TextArea */}
-        <Box flexDirection="column" width={40}>
-          <Text bold color="green">
-            TextArea value ({textValue.length} chars, {textChangeCountRef.current} changes):
-          </Text>
-          <Box borderStyle="single" borderColor="green">
-            <Box paddingX={1}>
-              <TextArea value={textValue} onChange={handleChange} height={4} placeholder="Type here..." />
-            </Box>
-          </Box>
-          <Box marginTop={1}>
-            <Text>Value: {JSON.stringify(textValue)}</Text>
-          </Box>
-        </Box>
-      </Box>
-    </Box>
-  )
-}
-
-function describeKey(input: string, key: Key): string {
-  const parts: string[] = []
-  if (key.ctrl) parts.push("Ctrl")
-  if (key.meta) parts.push("Meta")
-  if (key.shift) parts.push("Shift")
-
-  if (key.return) parts.push("Enter")
-  else if (key.escape) parts.push("Esc")
-  else if (key.backspace) parts.push("BS")
-  else if (key.delete) parts.push("Del")
-  else if (key.upArrow) parts.push("Up")
-  else if (key.downArrow) parts.push("Down")
-  else if (key.leftArrow) parts.push("Left")
-  else if (key.rightArrow) parts.push("Right")
-  else if (key.tab) parts.push("Tab")
-  else if (input.length === 1 && input >= " ") parts.push(`'${input}'`)
-  else if (input) parts.push(`raw:${JSON.stringify(input)}`)
-  else parts.push("(empty)")
-
-  return parts.join("+")
-}
-
-async function main() {
-  using term = createTerm()
-  const { waitUntilExit } = await render(<InputDebug />, term)
-  await waitUntilExit()
-}
-
-main().catch(console.error)