@silvery/examples 0.5.2 → 0.5.4

package/apps/terminal-caps-demo.tsx

@@ -0,0 +1,334 @@
+/**
+ * Terminal Capabilities Demo
+ *
+ * A "terminal health check" dashboard that probes all supported terminal
+ * protocols and displays their status in real time.
+ *
+ * Probed protocols:
+ * - Synchronized Output (Mode 2026)
+ * - SGR Mouse (Mode 1006)
+ * - Bracketed Paste (Mode 2004)
+ * - Focus Reporting (Mode 1004)
+ * - Kitty Keyboard (CSI u)
+ * - Mode 2031 Color Scheme Detection
+ * - DEC 1020-1023 Width Detection (UTF-8, CJK, Emoji, Private-Use)
+ * - OSC 66 Text Sizing
+ * - OSC 52 Clipboard
+ * - OSC 5522 Advanced Clipboard
+ * - OSC 8 Hyperlinks
+ * - Image Support (Kitty Graphics / Sixel)
+ * - DA1/DA2/DA3 Device Attributes
+ *
+ * Run: bun vendor/silvery/examples/apps/terminal-caps-demo.tsx
+ */
+
+import React, { useState } from "react"
+import { Box, Text, H3, Muted, Kbd, render, useInput, useApp, type Key } from "silvery"
+import {
+  detectTerminalCaps,
+  type TerminalCaps,
+  createWidthDetector,
+  type TerminalWidthConfig,
+  DEFAULT_WIDTH_CONFIG,
+  detectKittyFromStdio,
+} from "@silvery/ag-term"
+import { createColorSchemeDetector, type ColorScheme } from "@silvery/ag-term/ansi"
+import { ExampleBanner, type ExampleMeta } from "../_banner.js"
+
+export const meta: ExampleMeta = {
+  name: "Terminal Capabilities",
+  description: "Probe and display all supported terminal protocols",
+  demo: true,
+  features: ["detectTerminalCaps()", "Mode 2031", "DEC 1020-1023", "OSC 66", "OSC 52", "OSC 5522", "DA1/DA2/DA3"],
+}
+
+// ============================================================================
+// Types
+// ============================================================================
+
+type CapStatus = "supported" | "not-supported" | "probing" | "detected"
+
+interface CapEntry {
+  name: string
+  status: CapStatus
+  detail?: string
+}
+
+// ============================================================================
+// Status indicator component
+// ============================================================================
+
+function StatusIcon({ status }: { status: CapStatus }) {
+  switch (status) {
+    case "supported":
+      return <Text color="$success">{"✓"}</Text>
+    case "not-supported":
+      return <Text color="$error">{"✗"}</Text>
+    case "probing":
+      return <Text color="$warning">{"?"}</Text>
+    case "detected":
+      return <Text color="$warning">{"?"}</Text>
+  }
+}
+
+function CapRow({ entry, width }: { entry: CapEntry; width: number }) {
+  const label = entry.detail ? `${entry.name}: ${entry.detail}` : entry.name
+  const padded = label.length < width ? label + " ".repeat(width - label.length) : label
+  return (
+    <Box>
+      <StatusIcon status={entry.status} />
+      <Text> </Text>
+      <Text color={entry.status === "not-supported" ? "$muted" : undefined}>{padded}</Text>
+    </Box>
+  )
+}
+
+// ============================================================================
+// Build capability entries from detected caps
+// ============================================================================
+
+function buildStaticEntries(caps: TerminalCaps): CapEntry[] {
+  const bool = (supported: boolean): CapStatus => (supported ? "supported" : "not-supported")
+
+  return [
+    { name: "Synchronized Output (Mode 2026)", status: bool(caps.syncOutput) },
+    { name: "SGR Mouse (Mode 1006)", status: bool(caps.mouse) },
+    { name: "Bracketed Paste (Mode 2004)", status: bool(caps.bracketedPaste) },
+    { name: "Focus Reporting (Mode 1004)", status: bool(caps.bracketedPaste) }, // focus follows paste support heuristic
+    { name: "Kitty Keyboard (CSI u)", status: bool(caps.kittyKeyboard) },
+    { name: "OSC 52 Clipboard", status: bool(caps.osc52) },
+    { name: "OSC 8 Hyperlinks", status: bool(caps.hyperlinks) },
+    {
+      name: "Image Support",
+      status: caps.kittyGraphics || caps.sixel ? "supported" : "not-supported",
+      detail: caps.kittyGraphics ? "Kitty" : caps.sixel ? "Sixel" : "none",
+    },
+    { name: "Notifications (OSC 9/99)", status: bool(caps.notifications) },
+    { name: "Underline Styles (SGR 4:x)", status: bool(caps.underlineStyles) },
+    { name: "Underline Color (SGR 58)", status: bool(caps.underlineColor) },
+    { name: "Unicode", status: bool(caps.unicode) },
+    { name: "Nerd Font", status: bool(caps.nerdfont) },
+  ]
+}
+
+// ============================================================================
+// Main app component
+// ============================================================================
+
+function TerminalCapsApp({
+  initialProbes,
+}: {
+  initialProbes?: { colorScheme: ColorScheme; widthConfig: TerminalWidthConfig | null; kittyDetected: boolean | null }
+}) {
+  const { exit } = useApp()
+  const [caps] = useState<TerminalCaps>(() => detectTerminalCaps())
+  const [colorScheme] = useState<ColorScheme>(initialProbes?.colorScheme ?? "unknown")
+  const [widthConfig] = useState<TerminalWidthConfig | null>(initialProbes?.widthConfig ?? null)
+  const [kittyDetected] = useState<boolean | null>(initialProbes?.kittyDetected ?? null)
+
+  // Quit on q or Esc
+  useInput((input: string, key: Key) => {
+    if (input === "q" || key.escape) {
+      exit()
+    }
+  })
+
+  // Probing is done before render() in main() — no useEffect needed.
+  // This avoids stdin conflicts between protocol responses and useInput.
+
+  // Build the display entries
+  const staticEntries = buildStaticEntries(caps)
+
+  // Override Kitty detection if we have live results
+  if (kittyDetected !== null) {
+    const kittyEntry = staticEntries.find((e) => e.name.startsWith("Kitty Keyboard"))
+    if (kittyEntry) {
+      kittyEntry.status = kittyDetected ? "supported" : "not-supported"
+    }
+  }
+
+  // Dynamic probe entries
+  const probeEntries: CapEntry[] = [
+    {
+      name: "Mode 2031 Color Scheme",
+      status: colorScheme === "unknown" ? "probing" : "detected",
+      detail: colorScheme === "unknown" ? "probing..." : colorScheme,
+    },
+    {
+      name: "DEC 1020 UTF-8",
+      status: widthConfig === null ? "probing" : "detected",
+      detail: widthConfig === null ? "probing..." : widthConfig.utf8 ? "enabled" : "disabled",
+    },
+    {
+      name: "DEC 1021 CJK Width",
+      status: widthConfig === null ? "probing" : "detected",
+      detail: widthConfig === null ? "probing..." : String(widthConfig.cjkWidth),
+    },
+    {
+      name: "DEC 1022 Emoji Width",
+      status: widthConfig === null ? "probing" : "detected",
+      detail: widthConfig === null ? "probing..." : String(widthConfig.emojiWidth),
+    },
+    {
+      name: "DEC 1023 Private Width",
+      status: widthConfig === null ? "probing" : "detected",
+      detail: widthConfig === null ? "probing..." : String(widthConfig.privateUseWidth),
+    },
+    {
+      name: "OSC 66 Text Sizing",
+      status: caps.textSizingSupported ? "supported" : "not-supported",
+      detail: caps.textSizingSupported ? "supported" : "not supported",
+    },
+    {
+      name: "OSC 5522 Advanced Clipboard",
+      // Kitty 0.28+ supports this; approximate via kitty detection
+      status: caps.term === "xterm-kitty" ? "supported" : "not-supported",
+      detail: caps.term === "xterm-kitty" ? "Kitty" : "not supported",
+    },
+    {
+      name: "DA1/DA2/DA3",
+      // All modern terminals respond to DA queries
+      status: caps.program !== "" ? "supported" : "not-supported",
+    },
+  ]
+
+  // Terminal info header
+  const termProgram = caps.program || "(unknown)"
+  const termType = caps.term || "(unknown)"
+  const colorLevel = caps.colorLevel
+
+  // Column width for alignment
+  const colWidth = 38
+
+  return (
+    <Box flexDirection="column" paddingX={1} paddingY={1}>
+      <H3>Terminal Capabilities Probe</H3>
+
+      {/* Terminal identity */}
+      <Box paddingBottom={1}>
+        <Muted>
+          Terminal: {termProgram} ({termType}) | Colors: {colorLevel} | Background:{" "}
+          {caps.darkBackground ? "dark" : "light"}
+        </Muted>
+      </Box>
+
+      {/* Two-column layout */}
+      <Box>
+        {/* Left column: static capabilities */}
+        <Box flexDirection="column" width={colWidth + 4}>
+          <Text bold color="$primary">
+            Static Detection
+          </Text>
+          <Box height={1} />
+          {staticEntries.map((entry) => (
+            <CapRow key={entry.name} entry={entry} width={colWidth} />
+          ))}
+        </Box>
+
+        {/* Right column: runtime probes */}
+        <Box flexDirection="column" width={colWidth + 4}>
+          <Text bold color="$primary">
+            Runtime Probes
+          </Text>
+          <Box height={1} />
+          {probeEntries.map((entry) => (
+            <CapRow key={entry.name} entry={entry} width={colWidth} />
+          ))}
+        </Box>
+      </Box>
+
+      {/* Footer */}
+      <Box paddingTop={1}>
+        <Muted>
+          <Kbd>q</Kbd> or <Kbd>Esc</Kbd> to quit
+        </Muted>
+      </Box>
+    </Box>
+  )
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main() {
+  // Probe BEFORE render() starts — avoids stdin conflict with useInput.
+  // Once render() owns stdin, protocol responses leak as visible text.
+  let probeResults: {
+    colorScheme: ColorScheme
+    widthConfig: TerminalWidthConfig | null
+    kittyDetected: boolean | null
+  } = { colorScheme: "unknown", widthConfig: null, kittyDetected: null }
+
+  if (process.stdin.isTTY) {
+    process.stdin.setRawMode(true)
+    process.stdin.resume()
+
+    const write = (data: string) => process.stdout.write(data)
+    const onData = (handler: (data: string) => void): (() => void) => {
+      const h = (chunk: Buffer | string) => handler(typeof chunk === "string" ? chunk : chunk.toString())
+      process.stdin.on("data", h)
+      return () => process.stdin.removeListener("data", h)
+    }
+
+    // Run all probes in parallel with 500ms timeout
+    const [colorResult, widthResult, kittyResult] = await Promise.allSettled([
+      new Promise<ColorScheme>((resolve) => {
+        const det = createColorSchemeDetector({ write, onData, timeoutMs: 500 })
+        det.subscribe((s) => {
+          resolve(s)
+          det.stop()
+        })
+        det.start()
+        setTimeout(() => {
+          resolve(det.scheme)
+          det.stop()
+        }, 600)
+      }),
+      createWidthDetector({ write, onData, timeoutMs: 500 })
+        .detect()
+        .catch(() => null),
+      detectKittyFromStdio(process.stdout, process.stdin, 500)
+        .then((r) => r.supported)
+        .catch(() => false),
+    ])
+
+    probeResults = {
+      colorScheme: colorResult.status === "fulfilled" ? colorResult.value : "unknown",
+      widthConfig: widthResult.status === "fulfilled" ? widthResult.value : null,
+      kittyDetected: kittyResult.status === "fulfilled" ? kittyResult.value : false,
+    }
+
+    process.stdin.setRawMode(false)
+    process.stdin.pause()
+  }
+
+  const { waitUntilExit } = await render(
+    <ExampleBanner meta={meta} controls="q/Esc quit">
+      <TerminalCapsApp initialProbes={probeResults} />
+    </ExampleBanner>,
+  )
+
+  await waitUntilExit()
+}
+
+export { main }
+
+if (import.meta.main) {
+  main().catch((err) => {
+    // Ensure terminal is restored on error
+    const stdout = process.stdout
+    stdout.write("\x1b[?25h") // show cursor
+    stdout.write("\x1b[?1049l") // leave alt screen
+    stdout.write("\x1b[0m") // reset styles
+    if (process.stdin.isTTY && process.stdin.isRaw) {
+      try {
+        process.stdin.setRawMode(false)
+      } catch {
+        /* noop */
+      }
+    }
+    console.error(err)
+    process.exit(1)
+  })
+}

package/apps/text-selection-demo.tsx

@@ -0,0 +1,189 @@
+/**
+ * Text Selection Demo
+ *
+ * Demonstrates silvery's real text selection system using the useSelection hook.
+ * Shows userSelect modes (text, none, contain) and live selection state readout.
+ *
+ * Run: bun vendor/silvery/examples/apps/text-selection-demo.tsx
+ */
+
+import React from "react"
+import { Box, Text, H1, H2, Small, Muted, Strong, Kbd, HR } from "silvery"
+import { createApp } from "@silvery/create/create-app"
+import { pipe, withReact, withTerminal, withDomEvents } from "@silvery/create/plugins"
+import { ExampleBanner, type ExampleMeta } from "../_banner.js"
+import { useSelection } from "../../packages/ag-react/src/hooks/useSelection"
+
+export const meta: ExampleMeta = {
+  name: "Text Selection",
+  description: "Real selection via useSelection hook, userSelect modes, live state readout",
+  demo: true,
+  features: ["useSelection()", "userSelect prop", "CapabilityRegistry", "mouse drag selection"],
+}
+
+// ============================================================================
+// Selectable text panel (default — userSelect="text")
+// ============================================================================
+
+function SelectableTextPanel(): React.ReactElement {
+  return (
+    <Box flexDirection="column" borderStyle="round" borderColor="$border" paddingX={1} flexGrow={1}>
+      <H2>Selectable Text</H2>
+      <Small>userSelect="text" (default)</Small>
+      <Box height={1} />
+      <Text>Drag your mouse over this text to select it.</Text>
+      <Text>Multi-line selections work across paragraphs.</Text>
+      <Box height={1} />
+      <Text color="$muted">The quick brown fox jumps over the lazy dog. Pack my box with five dozen liquor jugs.</Text>
+    </Box>
+  )
+}
+
+// ============================================================================
+// Non-selectable panel (userSelect="none")
+// ============================================================================
+
+function NonSelectablePanel(): React.ReactElement {
+  return (
+    <Box flexDirection="column" borderStyle="round" borderColor="$border" paddingX={1} flexGrow={1} userSelect="none">
+      <H2>Non-Selectable</H2>
+      <Small>userSelect="none"</Small>
+      <Box height={1} />
+      <Text>This area cannot be selected by mouse drag.</Text>
+      <Text>Click events still work normally here.</Text>
+      <Box height={1} />
+      <Muted>Hold Alt and drag to override and select anyway.</Muted>
+    </Box>
+  )
+}
+
+// ============================================================================
+// Contained panel (userSelect="contain")
+// ============================================================================
+
+function ContainedPanel(): React.ReactElement {
+  return (
+    <Box flexDirection="column" borderStyle="round" borderColor="$warning" paddingX={1} flexGrow={1}>
+      <H2 color="$warning">Contained Selection</H2>
+      <Small>userSelect="contain"</Small>
+      <Box height={1} />
+      <Box flexDirection="column" borderStyle="round" borderColor="$primary" paddingX={1} userSelect="contain">
+        <Text bold color="$primary">
+          Selection Boundary
+        </Text>
+        <Box height={1} />
+        <Text>Selection cannot escape this container.</Text>
+        <Text>Try dragging past the border — it clips.</Text>
+        <Box height={1} />
+        <Text color="$success">Useful for modals, side panes, overlays.</Text>
+      </Box>
+    </Box>
+  )
+}
+
+// ============================================================================
+// Live selection state readout via useSelection()
+// ============================================================================
+
+function SelectionStatePanel(): React.ReactElement {
+  const selection = useSelection()
+
+  return (
+    <Box flexDirection="column" borderStyle="round" borderColor="$info" paddingX={1} flexGrow={1}>
+      <H2 color="$info">Selection State</H2>
+      <Small>Live readout from useSelection()</Small>
+      <Box height={1} />
+      {!selection ? (
+        <Text color="$muted">useSelection() returned undefined — feature not installed</Text>
+      ) : selection.range ? (
+        <>
+          <Box gap={1}>
+            <Strong>Status:</Strong>
+            <Text color="$success">{selection.selecting ? "Selecting..." : "Selected"}</Text>
+          </Box>
+          <Box gap={1}>
+            <Strong>Source:</Strong>
+            <Text>{selection.source ?? "unknown"}</Text>
+          </Box>
+          <Box gap={1}>
+            <Strong>Anchor:</Strong>
+            <Text>
+              ({selection.range.anchor.col}, {selection.range.anchor.row})
+            </Text>
+          </Box>
+          <Box gap={1}>
+            <Strong>Head:</Strong>
+            <Text>
+              ({selection.range.head.col}, {selection.range.head.row})
+            </Text>
+          </Box>
+        </>
+      ) : (
+        <Text color="$muted">No active selection — drag to select text</Text>
+      )}
+    </Box>
+  )
+}
+
+// ============================================================================
+// Status bar
+// ============================================================================
+
+function StatusBar(): React.ReactElement {
+  return (
+    <Box flexDirection="row" gap={2} paddingX={1} flexShrink={0} userSelect="none">
+      <Muted>
+        <Kbd>Drag</Kbd> select <Kbd>Alt+Drag</Kbd> force select <Kbd>Ctrl+C</Kbd> quit
+      </Muted>
+    </Box>
+  )
+}
+
+// ============================================================================
+// Main app
+// ============================================================================
+
+function TextSelectionDemo(): React.ReactElement {
+  return (
+    <Box flexDirection="column" padding={1} gap={1} height="100%">
+      <Box>
+        <H1 color="$primary">Text Selection Demo</H1>
+        <Muted> — real selection via useSelection()</Muted>
+      </Box>
+
+      {/* Top row: selectable + non-selectable */}
+      <Box flexDirection="row" gap={1} flexGrow={1}>
+        <SelectableTextPanel />
+        <NonSelectablePanel />
+      </Box>
+
+      {/* Bottom row: contained + live state readout */}
+      <Box flexDirection="row" gap={1} flexGrow={1}>
+        <ContainedPanel />
+        <SelectionStatePanel />
+      </Box>
+
+      <HR />
+      <StatusBar />
+    </Box>
+  )
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+if (import.meta.main) {
+  const app = pipe(
+    createApp(() => () => ({})) as any,
+    withReact(
+      <ExampleBanner meta={meta} controls="Drag select  Alt+Drag force select  Ctrl+C quit">
+        <TextSelectionDemo />
+      </ExampleBanner>,
+    ),
+    withTerminal(process as any, { mouse: true }),
+    withDomEvents(),
+  )
+  using handle = await app.run()
+  await handle.waitUntilExit()
+}

package/apps/textarea.tsx

@@ -0,0 +1,155 @@
+/**
+ * TextArea Example — Split-Pane Note Editor
+ *
+ * A note-taking app demonstrating:
+ * - Multi-line text input with word wrapping and pre-filled content
+ * - Split-pane layout: editor (2/3) + saved notes sidebar (1/3)
+ * - Tab focus cycling between panes
+ * - Cursor movement (arrow keys, Home/End, Ctrl+A/E)
+ * - Kill operations (Ctrl+K, Ctrl+U)
+ * - Word/character stats in the header
+ * - Submit with Ctrl+Enter to collect notes
+ */
+
+import React, { useState } from "react"
+import { render, Box, Text, H1, Strong, Muted, TextArea, useInput, useApp, createTerm, type Key } from "silvery"
+import { ExampleBanner, type ExampleMeta } from "../_banner.js"
+
+export const meta: ExampleMeta = {
+  name: "TextArea",
+  description: "Split-pane note editor with word wrap, kill ring, and note collection",
+  features: ["TextArea", "Split pane layout", "Ctrl+Enter submit", "Tab focus cycling"],
+}
+
+const INITIAL_CONTENT = `# Release Notes — Silvery v0.1
+
+## New Features
+
+- **Flexbox layout engine** — CSS-compatible sizing,
+  wrapping, and gap support via Flexily
+- **38 built-in color palettes** — from Dracula
+  to Solarized, Nord to Catppuccin
+- **Incremental rendering** — only changed cells
+  are repainted, no full-screen flicker
+
+## Breaking Changes
+
+- Dropped Node.js 18 support (now requires >=20)
+- Renamed \`useTerminal()\` to \`useTerm()\`
+
+## Performance
+
+Benchmark results on an M4 MacBook Pro:
+  Initial render:  2.1ms (80x24)
+  Incremental:     0.3ms (typical diff)
+  Layout:          0.8ms (1000 nodes)
+
+Thanks to all contributors!`
+
+export function NoteEditor() {
+  const { exit } = useApp()
+  const [notes, setNotes] = useState<string[]>([])
+  const [value, setValue] = useState(INITIAL_CONTENT)
+  const [focusIndex, setFocusIndex] = useState(0)
+
+  useInput((input: string, key: Key) => {
+    if (key.escape) {
+      exit()
+    }
+    if (key.tab && !key.shift) {
+      setFocusIndex((prev) => (prev + 1) % 2)
+    }
+    if (key.tab && key.shift) {
+      setFocusIndex((prev) => (prev - 1 + 2) % 2)
+    }
+  })
+
+  function handleSubmit(text: string) {
+    if (text.trim()) {
+      setNotes((prev) => [...prev, text.trim()])
+      setValue("")
+    }
+  }
+
+  const lines = value.split("\n").length
+  const chars = value.length
+  const words = value.split(/\s+/).filter(Boolean).length
+
+  return (
+    <Box flexDirection="column" flexGrow={1} padding={1}>
+      <Box flexDirection="row" gap={1} flexGrow={1}>
+        {/* Main editor */}
+        <Box
+          borderStyle="round"
+          borderColor={focusIndex === 0 ? "$primary" : "$border"}
+          flexDirection="column"
+          flexGrow={3}
+          flexBasis={0}
+        >
+          <Box paddingX={1} justifyContent="space-between">
+            <H1>Editor</H1>
+            <Muted>
+              {lines} lines, {words} words, {chars} chars
+            </Muted>
+          </Box>
+          <Text> </Text>
+          <Box paddingX={1} flexGrow={1}>
+            <TextArea
+              value={value}
+              onChange={setValue}
+              onSubmit={handleSubmit}
+              height={16}
+              isActive={focusIndex === 0}
+            />
+          </Box>
+        </Box>
+
+        {/* Saved notes sidebar */}
+        <Box
+          borderStyle="round"
+          borderColor={focusIndex === 1 ? "$primary" : "$border"}
+          flexDirection="column"
+          flexGrow={2}
+          flexBasis={0}
+        >
+          <Box paddingX={1}>
+            <H1>Notes</H1>
+            <Muted> ({notes.length})</Muted>
+          </Box>
+          <Text> </Text>
+          <Box flexDirection="column" paddingX={1} overflow="scroll" flexGrow={1}>
+            {notes.length === 0 ? (
+              <Muted>No notes yet.</Muted>
+            ) : (
+              notes.map((note, i) => (
+                <Box key={i} flexDirection="column" marginBottom={1}>
+                  <Text wrap="truncate">
+                    <Strong color="$success">#{i + 1}</Strong> {note.split("\n")[0]}
+                  </Text>
+                  <Muted>
+                    {note.split("\n").length} lines, {note.length} chars
+                  </Muted>
+                </Box>
+              ))
+            )}
+          </Box>
+        </Box>
+      </Box>
+    </Box>
+  )
+}
+
+async function main() {
+  using term = createTerm()
+  const { waitUntilExit } = await render(
+    <ExampleBanner meta={meta} controls="Tab switch pane  Ctrl+Enter submit  Esc quit">
+      <NoteEditor />
+    </ExampleBanner>,
+    term,
+  )
+  await waitUntilExit()
+}
+
+if (import.meta.main) {
+  main().catch(console.error)
+}

package/{examples/apps → apps}/theme.tsx

@@ -45,7 +45,7 @@ import {
   ansi16LightTheme,
   type ColorPalette,
   type ThemeAdjustment,
-} from "silvery/theme"
+} from "@silvery/theme"
 import { ExampleBanner, type ExampleMeta } from "../_banner.js"
 
 export const meta: ExampleMeta = {