@silvery/examples 0.4.2

package/examples/apps/inline-bench.tsx

@@ -0,0 +1,136 @@
+/**
+ * Inline incremental rendering benchmark
+ *
+ * Measures output phase bytes and timing for inline mode:
+ * - Full render (bare outputPhase — always full render, no instance state)
+ * - Incremental render (createOutputPhase — instance-scoped cursor tracking)
+ *
+ * Usage:
+ *   bun examples/apps/inline-bench.tsx
+ */
+
+import { TerminalBuffer } from "@silvery/ag-term/buffer"
+import { createOutputPhase, outputPhase } from "@silvery/ag-term/pipeline/output-phase"
+
+const RUNS = 500
+
+function fillBuffer(buf: TerminalBuffer, rows: number, prefix = ""): void {
+  for (let y = 0; y < rows; y++) {
+    const text = `${prefix}Item ${y}: Content line with some styling and longer text here`
+    for (let x = 0; x < Math.min(text.length, buf.width); x++) {
+      buf.setCell(x, y, { char: text[x]! })
+    }
+  }
+}
+
+interface BenchResult {
+  name: string
+  timings: number[]
+  bytes: number[]
+}
+
+function benchmarkOutputPhase(
+  name: string,
+  width: number,
+  height: number,
+  contentRows: number,
+  changedCells: number,
+  forceFullRender: boolean,
+): BenchResult {
+  const timings: number[] = []
+  const bytes: number[] = []
+
+  for (let i = 0; i < RUNS; i++) {
+    // Create fresh buffers each iteration
+    const prev = new TerminalBuffer(width, height)
+    fillBuffer(prev, contentRows)
+
+    const next = new TerminalBuffer(width, height)
+    fillBuffer(next, contentRows)
+
+    // Apply changes
+    for (let c = 0; c < changedCells; c++) {
+      const row = Math.floor((c / Math.max(changedCells, 1)) * contentRows)
+      const col = c % Math.min(10, width)
+      next.setCell(col, row, { char: "X" })
+    }
+
+    if (forceFullRender) {
+      // Bare outputPhase always uses fresh state → full render
+      outputPhase(null, prev, "inline", 0, height)
+      const t0 = performance.now()
+      const output = outputPhase(prev, next, "inline", 0, height)
+      const t1 = performance.now()
+      timings.push(t1 - t0)
+      bytes.push(output.length)
+    } else {
+      // createOutputPhase captures instance state → incremental after first render
+      const render = createOutputPhase({})
+      render(null, prev, "inline", 0, height) // first render (inits tracking)
+      const t0 = performance.now()
+      const output = render(prev, next, "inline", 0, height) // incremental
+      const t1 = performance.now()
+      timings.push(t1 - t0)
+      bytes.push(output.length)
+    }
+  }
+
+  timings.sort((a, b) => a - b)
+  bytes.sort((a, b) => a - b)
+
+  return { name, timings, bytes }
+}
+
+function printResult(r: BenchResult): void {
+  const p50t = r.timings[Math.floor(r.timings.length * 0.5)]!
+  const p95t = r.timings[Math.floor(r.timings.length * 0.95)]!
+  const p50b = r.bytes[Math.floor(r.bytes.length * 0.5)]!
+  const avgB = r.bytes.reduce((a, b) => a + b, 0) / r.bytes.length
+
+  console.log(
+    `  ${r.name.padEnd(40)} ` +
+      `p50=${p50t.toFixed(3).padStart(7)}ms  ` +
+      `p95=${p95t.toFixed(3).padStart(7)}ms  ` +
+      `bytes=${Math.round(p50b).toString().padStart(6)} (avg ${Math.round(avgB)})`,
+  )
+}
+
+function printComparison(full: BenchResult, incr: BenchResult): void {
+  const fullP50b = full.bytes[Math.floor(full.bytes.length * 0.5)]!
+  const incrP50b = incr.bytes[Math.floor(incr.bytes.length * 0.5)]!
+  const fullP50t = full.timings[Math.floor(full.timings.length * 0.5)]!
+  const incrP50t = incr.timings[Math.floor(incr.timings.length * 0.5)]!
+
+  const byteRatio = fullP50b / Math.max(incrP50b, 1)
+  const timeRatio = fullP50t / Math.max(incrP50t, 0.001)
+
+  console.log(
+    `  ${"→ savings".padEnd(40)} ` +
+      `time=${timeRatio.toFixed(1)}x faster  ` +
+      `bytes=${byteRatio.toFixed(0)}x fewer (${fullP50b} → ${incrP50b})`,
+  )
+}
+
+async function main() {
+  console.log(`\n═══ Inline Output Phase: Full vs Incremental (${RUNS} runs) ═══\n`)
+
+  const configs = [
+    { label: "10 rows, 1 change", w: 80, h: 20, rows: 10, changes: 1 },
+    { label: "30 rows, 1 change", w: 120, h: 40, rows: 30, changes: 1 },
+    { label: "50 rows, 1 change", w: 120, h: 60, rows: 50, changes: 1 },
+    { label: "50 rows, 3 changes", w: 120, h: 60, rows: 50, changes: 3 },
+    { label: "50 rows, 10 changes", w: 120, h: 60, rows: 50, changes: 10 },
+  ]
+
+  for (const cfg of configs) {
+    console.log(`--- ${cfg.label} ---`)
+    const full = benchmarkOutputPhase(`full render`, cfg.w, cfg.h, cfg.rows, cfg.changes, true)
+    const incr = benchmarkOutputPhase(`incremental`, cfg.w, cfg.h, cfg.rows, cfg.changes, false)
+    printResult(full)
+    printResult(incr)
+    printComparison(full, incr)
+    console.log()
+  }
+}
+
+main().catch(console.error)

package/examples/apps/kanban.tsx

@@ -0,0 +1,267 @@
+/**
+ * Kanban Board Example
+ *
+ * A 3-column kanban board demonstrating:
+ * - Todo, In Progress, Done columns
+ * - Move items between columns with arrow keys
+ * - Each column uses native overflow="scroll" for scrolling
+ * - Flexbox layout for proportional sizing
+ */
+
+import React, { useState } from "react"
+import { render, Box, Text, Kbd, Muted, useInput, useApp, createTerm, type Key } from "../../src/index.js"
+import { ExampleBanner, type ExampleMeta } from "../_banner.js"
+
+export const meta: ExampleMeta = {
+  name: "Kanban Board",
+  description: "3-column kanban with card movement and independent scroll",
+  demo: true,
+  features: ["Box flexDirection", "useInput", "backgroundColor", "multi-column layout"],
+}
+
+// ============================================================================
+// Types
+// ============================================================================
+
+type ColumnId = "todo" | "inProgress" | "done"
+
+interface Card {
+  id: number
+  title: string
+  tags: string[]
+}
+
+interface Column {
+  id: ColumnId
+  title: string
+  cards: Card[]
+}
+
+// ============================================================================
+// Initial Data
+// ============================================================================
+
+const initialColumns: Column[] = [
+  {
+    id: "todo",
+    title: "To Do",
+    cards: [
+      { id: 1, title: "Design new landing page", tags: ["design"] },
+      { id: 2, title: "Write API documentation", tags: ["docs"] },
+      { id: 3, title: "Set up monitoring", tags: ["devops"] },
+      { id: 4, title: "Create onboarding flow", tags: ["ux"] },
+      { id: 5, title: "Database optimization", tags: ["backend"] },
+      { id: 6, title: "Mobile responsive fixes", tags: ["frontend"] },
+      { id: 7, title: "Add dark mode", tags: ["frontend", "ux"] },
+      { id: 8, title: "Implement caching", tags: ["backend"] },
+    ],
+  },
+  {
+    id: "inProgress",
+    title: "In Progress",
+    cards: [
+      { id: 9, title: "User authentication", tags: ["backend", "security"] },
+      { id: 10, title: "Dashboard redesign", tags: ["frontend", "design"] },
+      { id: 11, title: "API rate limiting", tags: ["backend"] },
+    ],
+  },
+  {
+    id: "done",
+    title: "Done",
+    cards: [
+      { id: 12, title: "Project setup", tags: ["devops"] },
+      { id: 13, title: "CI/CD pipeline", tags: ["devops"] },
+      { id: 14, title: "Initial wireframes", tags: ["design"] },
+      { id: 15, title: "Database schema", tags: ["backend"] },
+    ],
+  },
+]
+
+// ============================================================================
+// Components
+// ============================================================================
+
+const tagColors: Record<string, string> = {
+  frontend: "$info",
+  backend: "$accent",
+  design: "$warning",
+  devops: "$success",
+  docs: "$primary",
+  ux: "$muted",
+  security: "$error",
+}
+
+function Tag({ name }: { name: string }) {
+  const color = tagColors[name] ?? "$muted"
+  return (
+    <Text color={color} dim>
+      #{name}
+    </Text>
+  )
+}
+
+function CardComponent({ card, isSelected }: { card: Card; isSelected: boolean }) {
+  return (
+    <Box flexDirection="column" borderStyle="round" borderColor={isSelected ? "$primary" : "$border"} paddingX={1}>
+      {isSelected ? (
+        <Text backgroundColor="$primary" color="black" bold>
+          {card.title}
+        </Text>
+      ) : (
+        <Text>{card.title}</Text>
+      )}
+      <Box gap={1}>
+        {card.tags.map((tag) => (
+          <Tag key={tag} name={tag} />
+        ))}
+      </Box>
+    </Box>
+  )
+}
+
+function ColumnComponent({
+  column,
+  isSelected,
+  selectedCardIndex,
+}: {
+  column: Column
+  isSelected: boolean
+  selectedCardIndex: number
+}) {
+  return (
+    <Box flexDirection="column" flexGrow={1} borderStyle="single" borderColor={isSelected ? "$primary" : "$border"}>
+      <Box backgroundColor={isSelected ? "$primary" : undefined} paddingX={1}>
+        <Text bold color={isSelected ? "black" : "$text"}>
+          {column.title}
+        </Text>
+        <Text color={isSelected ? "black" : "$muted"}> ({column.cards.length})</Text>
+      </Box>
+
+      <Box
+        flexDirection="column"
+        paddingX={1}
+        overflow="scroll"
+        scrollTo={isSelected ? selectedCardIndex : undefined}
+        flexGrow={1}
+        gap={1}
+      >
+        {column.cards.map((card, cardIndex) => (
+          <CardComponent key={card.id} card={card} isSelected={isSelected && cardIndex === selectedCardIndex} />
+        ))}
+
+        {column.cards.length === 0 && (
+          <Text dim italic>
+            No cards
+          </Text>
+        )}
+      </Box>
+    </Box>
+  )
+}
+
+function HelpBar() {
+  return (
+    <Muted>
+      {" "}
+      <Kbd>h/l</Kbd> column <Kbd>j/k</Kbd> card <Kbd>{"</"}</Kbd> move <Kbd>Esc/q</Kbd> quit
+    </Muted>
+  )
+}
+
+export function KanbanBoard() {
+  const { exit } = useApp()
+  const [columns, setColumns] = useState<Column[]>(initialColumns)
+  const [selectedColumn, setSelectedColumn] = useState(0)
+  const [selectedCard, setSelectedCard] = useState(0)
+
+  const currentColumn = columns[selectedColumn]
+  const currentColumnCards = currentColumn?.cards ?? []
+  const boundedSelectedCard = Math.min(selectedCard, Math.max(0, currentColumnCards.length - 1))
+
+  useInput((input: string, key: Key) => {
+    if (input === "q" || key.escape) {
+      exit()
+    }
+
+    // Column navigation
+    if (key.leftArrow || input === "h") {
+      setSelectedColumn((prev) => Math.max(0, prev - 1))
+      setSelectedCard(0)
+    }
+    if (key.rightArrow || input === "l") {
+      setSelectedColumn((prev) => Math.min(columns.length - 1, prev + 1))
+      setSelectedCard(0)
+    }
+
+    // Card navigation
+    if (key.upArrow || input === "k") {
+      setSelectedCard((prev) => Math.max(0, prev - 1))
+    }
+    if (key.downArrow || input === "j") {
+      setSelectedCard((prev) => Math.min(currentColumnCards.length - 1, prev + 1))
+    }
+
+    // Move card between columns
+    if (input === "<" || input === ",") {
+      moveCard(-1)
+    }
+    if (input === ">" || input === ".") {
+      moveCard(1)
+    }
+  })
+
+  function moveCard(direction: number): void {
+    const targetColumnIndex = selectedColumn + direction
+    if (targetColumnIndex < 0 || targetColumnIndex >= columns.length) return
+    if (currentColumnCards.length === 0) return
+
+    const cardToMove = currentColumnCards[boundedSelectedCard]
+    if (!cardToMove) return
+
+    setColumns((prev) => {
+      const next = prev.map((col) => ({ ...col, cards: [...col.cards] }))
+      next[selectedColumn]!.cards.splice(boundedSelectedCard, 1)
+      next[targetColumnIndex]!.cards.push(cardToMove)
+      return next
+    })
+
+    setSelectedColumn(targetColumnIndex)
+    setSelectedCard(columns[targetColumnIndex]!.cards.length)
+  }
+
+  return (
+    <Box flexDirection="column" padding={1} height="100%">
+      <Box flexGrow={1} flexDirection="row" gap={1} overflow="hidden">
+        {columns.map((column, colIndex) => (
+          <ColumnComponent
+            key={column.id}
+            column={column}
+            isSelected={colIndex === selectedColumn}
+            selectedCardIndex={colIndex === selectedColumn ? boundedSelectedCard : -1}
+          />
+        ))}
+      </Box>
+
+      <HelpBar />
+    </Box>
+  )
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main() {
+  using term = createTerm()
+  const { waitUntilExit } = await render(
+    <ExampleBanner meta={meta} controls="h/l column  j/k card  </> move  Esc/q quit">
+      <KanbanBoard />
+    </ExampleBanner>,
+    term,
+  )
+  await waitUntilExit()
+}
+
+if (import.meta.main) {
+  main().catch(console.error)
+}

package/examples/apps/layout-ref.tsx

@@ -0,0 +1,185 @@
+/**
+ * Layout Ref Example
+ *
+ * Demonstrates imperative access to layout information:
+ * - forwardRef on Box and Text components
+ * - BoxHandle for accessing layout info imperatively
+ * - onLayout callback for responding to size changes
+ */
+
+import React, { useRef, useState, useEffect } from "react"
+import {
+  render,
+  Box,
+  Text,
+  H1,
+  Kbd,
+  Muted,
+  useInput,
+  useApp,
+  createTerm,
+  type BoxHandle,
+  type Key,
+} from "../../src/index.js"
+import { ExampleBanner, type ExampleMeta } from "../_banner.js"
+
+export const meta: ExampleMeta = {
+  name: "Layout Ref",
+  description: "useContentRect + useScreenRect for imperative layout measurement",
+  features: ["forwardRef", "BoxHandle", "onLayout", "getContentRect()"],
+}
+
+// ============================================================================
+// Components
+// ============================================================================
+
+interface LayoutInfo {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+function ResizablePane({
+  title,
+  color,
+  onLayoutChange,
+}: {
+  title: string
+  color: string
+  onLayoutChange: (info: LayoutInfo) => void
+}) {
+  const boxRef = useRef<BoxHandle>(null)
+
+  // onLayout callback fires when this Box's dimensions change
+  return (
+    <Box
+      ref={boxRef}
+      flexGrow={1}
+      borderStyle="round"
+      borderColor={color}
+      padding={1}
+      onLayout={(layout) => onLayoutChange(layout)}
+    >
+      <H1 color={color}>{title}</H1>
+    </Box>
+  )
+}
+
+function ImperativeAccessDemo() {
+  const boxRef = useRef<BoxHandle>(null)
+  const [info, setInfo] = useState<string>("Click 'i' to inspect")
+
+  const inspect = () => {
+    if (!boxRef.current) {
+      setInfo("No ref attached")
+      return
+    }
+
+    const content = boxRef.current.getContentRect()
+    const screen = boxRef.current.getScreenRect()
+    const node = boxRef.current.getNode()
+
+    setInfo(
+      `Content: ${content?.width}x${content?.height} at (${content?.x},${content?.y})\n` +
+        `Screen: ${screen?.width}x${screen?.height} at (${screen?.x},${screen?.y})\n` +
+        `Node: ${node ? "available" : "null"}`,
+    )
+  }
+
+  return (
+    <Box ref={boxRef} flexDirection="column" borderStyle="double" borderColor="magenta" padding={1}>
+      <H1 color="magenta">Imperative Access (BoxHandle)</H1>
+      <Muted>Press 'i' to inspect this box</Muted>
+      <Box marginTop={1}>
+        <Text>{info}</Text>
+      </Box>
+      {/* Expose inspect function via closure */}
+      <InspectTrigger onInspect={inspect} />
+    </Box>
+  )
+}
+
+// Hidden component to trigger inspect on keypress
+function InspectTrigger({ onInspect }: { onInspect: () => void }) {
+  useInput((input: string) => {
+    if (input === "i") {
+      onInspect()
+    }
+  })
+  return null
+}
+
+export function LayoutRefApp() {
+  const { exit } = useApp()
+  const [layouts, setLayouts] = useState<Record<string, LayoutInfo>>({})
+
+  useInput((input: string, key: Key) => {
+    if (input === "q" || key.escape) {
+      exit()
+    }
+  })
+
+  const handleLayoutChange = (pane: string) => (info: LayoutInfo) => {
+    setLayouts((prev) => ({ ...prev, [pane]: info }))
+  }
+
+  return (
+    <Box flexDirection="column" padding={1}>
+      {/* Row of resizable panes with onLayout callbacks */}
+      <Box flexDirection="row" gap={1} height={8}>
+        <ResizablePane title="Pane A" color="green" onLayoutChange={handleLayoutChange("a")} />
+        <ResizablePane title="Pane B" color="blue" onLayoutChange={handleLayoutChange("b")} />
+        <ResizablePane title="Pane C" color="cyan" onLayoutChange={handleLayoutChange("c")} />
+      </Box>
+
+      {/* Show layout info from onLayout callbacks */}
+      <Box marginTop={1} borderStyle="single" borderColor="gray" padding={1}>
+        <Box flexDirection="column">
+          <Text bold dim>
+            onLayout Results:
+          </Text>
+          {Object.entries(layouts).map(([pane, info]) => (
+            <Text key={pane} dim>
+              Pane {pane.toUpperCase()}: {info.width}x{info.height} at ({info.x},{info.y})
+            </Text>
+          ))}
+          {Object.keys(layouts).length === 0 && (
+            <Text dim italic>
+              Waiting for layout...
+            </Text>
+          )}
+        </Box>
+      </Box>
+
+      {/* Imperative access demo */}
+      <Box flexGrow={1} marginTop={1}>
+        <ImperativeAccessDemo />
+      </Box>
+
+      <Muted>
+        {" "}
+        <Kbd>i</Kbd> inspect <Kbd>Esc/q</Kbd> quit
+      </Muted>
+    </Box>
+  )
+}
+
+// ============================================================================
+// Main
+// ============================================================================
+
+async function main() {
+  using term = createTerm()
+  const { waitUntilExit } = await render(
+    <ExampleBanner meta={meta} controls="i inspect  Esc/q quit">
+      <LayoutRefApp />
+    </ExampleBanner>,
+    term,
+  )
+  await waitUntilExit()
+}
+
+if (import.meta.main) {
+  main().catch(console.error)
+}