@silvery/term 0.3.0

package/src/terminal-colors.ts

@@ -0,0 +1,216 @@
+/**
+ * OSC 10/11/12 Terminal Color Queries
+ *
+ * Provides functions to query and set the terminal's foreground, background,
+ * and cursor colors. Also provides theme detection via background luminance.
+ *
+ * Protocol: OSC N
+ * - Query:    ESC ] N ; ? BEL
+ * - Set:      ESC ] N ; <color> BEL
+ * - Reset:    ESC ] N BEL  (some terminals) or ESC ] 1N BEL (110/111/112)
+ * - Response: ESC ] N ; rgb:RRRR/GGGG/BBBB ST
+ *
+ * Where N is:
+ *   10 = foreground (text) color
+ *   11 = background color
+ *   12 = cursor color
+ *
+ * Response format uses the same rgb: notation as OSC 4 palette colors.
+ * Terminators: BEL (\x07) or ST (ESC \) — both are accepted.
+ *
+ * Supported by: xterm, Ghostty, Kitty, WezTerm, iTerm2, foot, Alacritty
+ */
+
+const ESC = "\x1b"
+const BEL = "\x07"
+
+// ============================================================================
+// Response Parsing (shared)
+// ============================================================================
+
+/**
+ * Regex for an OSC color response body: rgb:R/G/B (1-4 hex digits per channel)
+ */
+const RGB_BODY_RE = /rgb:([0-9a-fA-F]{1,4})\/([0-9a-fA-F]{1,4})\/([0-9a-fA-F]{1,4})/
+
+/**
+ * Normalize a hex color channel to 2-digit hex.
+ * - 1-digit: repeat (e.g., "f" -> "ff")
+ * - 2-digit: as-is
+ * - 3-digit: take first 2
+ * - 4-digit: take first 2
+ */
+function normalizeHexChannel(hex: string): string {
+  switch (hex.length) {
+    case 1:
+      return hex + hex
+    case 2:
+      return hex
+    default:
+      return hex.slice(0, 2)
+  }
+}
+
+/**
+ * Parse an OSC color response (10/11/12) into a #RRGGBB hex string.
+ *
+ * @param input Raw terminal input
+ * @param oscCode The OSC code to look for (10, 11, or 12)
+ * @returns Normalized #RRGGBB hex string, or null if not a valid response
+ */
+function parseOscColorResponse(input: string, oscCode: number): string | null {
+  const prefix = `${ESC}]${oscCode};`
+  const prefixIdx = input.indexOf(prefix)
+  if (prefixIdx === -1) return null
+
+  const bodyStart = prefixIdx + prefix.length
+
+  // Find terminator: BEL (\x07) or ST (ESC \)
+  let bodyEnd = input.indexOf(BEL, bodyStart)
+  if (bodyEnd === -1) {
+    bodyEnd = input.indexOf(`${ESC}\\`, bodyStart)
+  }
+  if (bodyEnd === -1) return null
+
+  const body = input.slice(bodyStart, bodyEnd)
+  const match = RGB_BODY_RE.exec(body)
+  if (!match) return null
+
+  const r = normalizeHexChannel(match[1]!)
+  const g = normalizeHexChannel(match[2]!)
+  const b = normalizeHexChannel(match[3]!)
+
+  return `#${r}${g}${b}`
+}
+
+// ============================================================================
+// Query Functions
+// ============================================================================
+
+/**
+ * Query a terminal color via OSC code.
+ *
+ * @param write Function to write to stdout
+ * @param read Function to read a chunk from stdin
+ * @param oscCode The OSC code (10, 11, or 12)
+ * @param timeoutMs How long to wait for response
+ */
+async function queryOscColor(
+  write: (data: string) => void,
+  read: (timeoutMs: number) => Promise<string | null>,
+  oscCode: number,
+  timeoutMs: number,
+): Promise<string | null> {
+  write(`${ESC}]${oscCode};?${BEL}`)
+
+  const data = await read(timeoutMs)
+  if (data == null) return null
+
+  return parseOscColorResponse(data, oscCode)
+}
+
+/**
+ * Query the terminal foreground (text) color.
+ * @returns "#RRGGBB" hex string, or null on timeout/unsupported
+ */
+export async function queryForegroundColor(
+  write: (data: string) => void,
+  read: (timeoutMs: number) => Promise<string | null>,
+  timeoutMs = 200,
+): Promise<string | null> {
+  return queryOscColor(write, read, 10, timeoutMs)
+}
+
+/**
+ * Query the terminal background color.
+ * @returns "#RRGGBB" hex string, or null on timeout/unsupported
+ */
+export async function queryBackgroundColor(
+  write: (data: string) => void,
+  read: (timeoutMs: number) => Promise<string | null>,
+  timeoutMs = 200,
+): Promise<string | null> {
+  return queryOscColor(write, read, 11, timeoutMs)
+}
+
+/**
+ * Query the terminal cursor color.
+ * @returns "#RRGGBB" hex string, or null on timeout/unsupported
+ */
+export async function queryCursorColor(
+  write: (data: string) => void,
+  read: (timeoutMs: number) => Promise<string | null>,
+  timeoutMs = 200,
+): Promise<string | null> {
+  return queryOscColor(write, read, 12, timeoutMs)
+}
+
+// ============================================================================
+// Set Functions
+// ============================================================================
+
+/** Set the terminal foreground (text) color. */
+export function setForegroundColor(write: (data: string) => void, color: string): void {
+  write(`${ESC}]10;${color}${BEL}`)
+}
+
+/** Set the terminal background color. */
+export function setBackgroundColor(write: (data: string) => void, color: string): void {
+  write(`${ESC}]11;${color}${BEL}`)
+}
+
+/** Set the terminal cursor color. */
+export function setCursorColor(write: (data: string) => void, color: string): void {
+  write(`${ESC}]12;${color}${BEL}`)
+}
+
+// ============================================================================
+// Reset Functions
+// ============================================================================
+
+/** Reset the terminal foreground color to default. */
+export function resetForegroundColor(write: (data: string) => void): void {
+  write(`${ESC}]110${BEL}`)
+}
+
+/** Reset the terminal background color to default. */
+export function resetBackgroundColor(write: (data: string) => void): void {
+  write(`${ESC}]111${BEL}`)
+}
+
+/** Reset the terminal cursor color to default. */
+export function resetCursorColor(write: (data: string) => void): void {
+  write(`${ESC}]112${BEL}`)
+}
+
+// ============================================================================
+// Theme Detection
+// ============================================================================
+
+/**
+ * Detect the terminal color scheme (light or dark) by querying the
+ * background color and computing its relative luminance.
+ *
+ * Uses the standard sRGB luminance formula:
+ *   L = 0.2126*R + 0.7152*G + 0.0722*B
+ *
+ * L > 0.5 → light theme, L <= 0.5 → dark theme
+ *
+ * @returns "light" or "dark", or null if the background color could not be queried
+ */
+export async function detectColorScheme(
+  write: (data: string) => void,
+  read: (timeoutMs: number) => Promise<string | null>,
+  timeoutMs = 200,
+): Promise<"light" | "dark" | null> {
+  const bg = await queryBackgroundColor(write, read, timeoutMs)
+  if (bg == null) return null
+
+  // Parse #RRGGBB
+  const r = parseInt(bg.slice(1, 3), 16) / 255
+  const g = parseInt(bg.slice(3, 5), 16) / 255
+  const b = parseInt(bg.slice(5, 7), 16) / 255
+
+  const luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b
+  return luminance > 0.5 ? "light" : "dark"
+}

package/src/termtest.ts

@@ -0,0 +1,224 @@
+/**
+ * Terminal Capability Test
+ *
+ * Renders labeled test patterns for each terminal feature.
+ * Run in any terminal to visually verify what it supports.
+ *
+ * Usage:
+ *   import { runTermtest } from "@silvery/react"
+ *   runTermtest()                    // all sections
+ *   runTermtest({ sections: ["emoji", "colors"] })  // specific sections
+ *
+ * Compare output across terminals to build/verify profiles.
+ */
+
+import { detectTerminalCaps } from "./terminal-caps"
+
+const ESC = "\x1b"
+const CSI = `${ESC}[`
+const RESET = `${CSI}0m`
+
+function sgr(...codes: (string | number)[]): string {
+  return `${CSI}${codes.join(";")}m`
+}
+
+function sectionHeader(title: string): string {
+  return `\n${sgr(1)}═══ ${title} ═══${RESET}\n`
+}
+
+function row(label: string, content: string): string {
+  return `  ${label.padEnd(24)} ${content}${RESET}`
+}
+
+/** Available test sections */
+export const TERMTEST_SECTIONS = [
+  "sgr",
+  "underline",
+  "colors",
+  "256",
+  "truecolor",
+  "unicode",
+  "emoji",
+  "borders",
+  "inverse",
+  "profile",
+] as const
+
+export type TermtestSection = (typeof TERMTEST_SECTIONS)[number]
+
+export interface TermtestOptions {
+  /** Writable stream (defaults to process.stdout) */
+  output?: { write(s: string): boolean }
+  /** Show only these sections. Omit or empty = all sections. */
+  sections?: TermtestSection[]
+}
+
+/**
+ * Run the terminal capability test.
+ * Pass section names to filter: `runTermtest({ sections: ["emoji"] })`
+ */
+export function runTermtest(options?: TermtestOptions): void {
+  const w = options?.output ?? process.stdout
+  const filter = options?.sections
+  const show = (s: TermtestSection) => !filter || filter.length === 0 || filter.includes(s)
+
+  const caps = detectTerminalCaps()
+
+  w.write(`\n${sgr(1)}Terminal Capability Test${RESET}\n`)
+  w.write(`  Program: ${caps.program || "(unknown)"}\n`)
+  w.write(`  TERM: ${caps.term || "(unknown)"}\n`)
+  w.write(`  COLORTERM: ${process.env.COLORTERM || "(unset)"}\n`)
+  w.write(`  Detected: color=${caps.colorLevel} dark=${caps.darkBackground} nerdfont=${caps.nerdfont}\n`)
+  w.write(`  Underline: styles=${caps.underlineStyles} color=${caps.underlineColor}\n`)
+  w.write(`  Emoji wide: ${caps.textEmojiWide}\n`)
+
+  if (show("sgr")) {
+    w.write(sectionHeader("SGR Text Attributes"))
+    w.write(row("Bold", `${sgr(1)}The quick brown fox${RESET}`) + "\n")
+    w.write(row("Dim", `${sgr(2)}The quick brown fox${RESET}`) + "\n")
+    w.write(row("Italic", `${sgr(3)}The quick brown fox${RESET}`) + "\n")
+    w.write(row("Underline", `${sgr(4)}The quick brown fox${RESET}`) + "\n")
+    w.write(row("Strikethrough", `${sgr(9)}The quick brown fox${RESET}`) + "\n")
+    w.write(row("Inverse", `${sgr(7)}The quick brown fox${RESET}`) + "\n")
+    w.write(row("Blink", `${sgr(5)}The quick brown fox${RESET}`) + "\n")
+    w.write(row("Bold+Italic", `${sgr(1, 3)}The quick brown fox${RESET}`) + "\n")
+  }
+
+  if (show("underline")) {
+    w.write(sectionHeader("SGR 4:x Underline Styles (Terminal.app BREAKS here)"))
+    w.write(row("4:1 Single", `${CSI}4:1mThe quick brown fox${RESET}`) + "\n")
+    w.write(row("4:2 Double", `${CSI}4:2mThe quick brown fox${RESET}`) + "\n")
+    w.write(row("4:3 Curly", `${CSI}4:3mThe quick brown fox${RESET}`) + "\n")
+    w.write(row("4:4 Dotted", `${CSI}4:4mThe quick brown fox${RESET}`) + "\n")
+    w.write(row("4:5 Dashed", `${CSI}4:5mThe quick brown fox${RESET}`) + "\n")
+    w.write(
+      row("After 4:x (clean?)", `${CSI}4:3m${RESET}This text should be normal — if garbled, 4:x corrupted SGR state`) +
+        "\n",
+    )
+
+    w.write(sectionHeader("SGR 58 Underline Color (Terminal.app BREAKS here)"))
+    w.write(row("58;5;1 Red UL", `${sgr(4)}${CSI}58;5;1mThe quick brown fox${RESET}`) + "\n")
+    w.write(row("58;5;2 Green UL", `${sgr(4)}${CSI}58;5;2mThe quick brown fox${RESET}`) + "\n")
+    w.write(row("58;5;4 Blue UL", `${sgr(4)}${CSI}58;5;4mThe quick brown fox${RESET}`) + "\n")
+    w.write(row("58;2;R;G;B TC UL", `${sgr(4)}${CSI}58;2;255;128;0mThe quick brown fox${RESET}`) + "\n")
+    w.write(
+      row(
+        "After SGR 58 (clean?)",
+        `${sgr(4)}${CSI}58;5;1m${RESET}This text should be normal — if garbled, 58 corrupted SGR state`,
+      ) + "\n",
+    )
+  }
+
+  if (show("colors")) {
+    w.write(sectionHeader("ANSI 16 Colors"))
+    const colorNames = ["Black", "Red", "Green", "Yellow", "Blue", "Magenta", "Cyan", "White"]
+    let fgLine = "  FG:  "
+    for (let i = 0; i < 8; i++) fgLine += `${sgr(30 + i)} ${colorNames[i]}${RESET}`
+    w.write(fgLine + "\n")
+    let fgBrLine = "  Br:  "
+    for (let i = 0; i < 8; i++) fgBrLine += `${sgr(90 + i)} ${colorNames[i]}${RESET}`
+    w.write(fgBrLine + "\n")
+    let bgLine = "  BG:  "
+    for (let i = 0; i < 8; i++) bgLine += `${sgr(40 + i)} ${colorNames[i]} ${RESET}`
+    w.write(bgLine + "\n")
+    let bgBrLine = "  BrBG:"
+    for (let i = 0; i < 8; i++) bgBrLine += `${sgr(100 + i)} ${colorNames[i]} ${RESET}`
+    w.write(bgBrLine + "\n")
+  }
+
+  if (show("256")) {
+    w.write(sectionHeader("256 Colors (indices 0-15, 16-231, 232-255)"))
+    let stdLine = "  0-15:  "
+    for (let i = 0; i < 16; i++) stdLine += `${CSI}48;5;${i}m  ${RESET}`
+    w.write(stdLine + "\n")
+    let cubeLine = "  Cube:  "
+    for (let i = 16; i < 52; i++) cubeLine += `${CSI}48;5;${i}m ${RESET}`
+    w.write(cubeLine + "\n")
+    let grayLine = "  Gray:  "
+    for (let i = 232; i < 256; i++) grayLine += `${CSI}48;5;${i}m ${RESET}`
+    w.write(grayLine + "\n")
+  }
+
+  if (show("truecolor")) {
+    w.write(sectionHeader("Truecolor (38;2;R;G;B / 48;2;R;G;B)"))
+    let tcLine = "  Gradient: "
+    for (let i = 0; i < 40; i++) {
+      const r = Math.round((i / 39) * 255)
+      const g = Math.round(((39 - i) / 39) * 128)
+      tcLine += `${CSI}48;2;${r};${g};80m ${RESET}`
+    }
+    w.write(tcLine + "\n")
+    w.write(row("If solid blocks →", "Truecolor NOT supported (256-color fallback)") + "\n")
+  }
+
+  if (show("unicode")) {
+    w.write(sectionHeader("Unicode, Emoji, PUA (Nerd Fonts)"))
+    w.write(row("ASCII", "Hello World! 0123456789") + "\n")
+    w.write(row("Latin Extended", "àéîõü ñ ß ø å") + "\n")
+    w.write(row("CJK", "你好世界 日本語 한국어") + "\n")
+    w.write(row("Box Drawing", "┌─┬─┐ ╔═╦═╗ ╭─╮") + "\n")
+    w.write(row("Block Elements", "▀▄█▌▐░▒▓") + "\n")
+    w.write(row("Symbols", "● ○ ◉ ▶ ◀ ⚠ ✓ ✗ ⋮ §") + "\n")
+    w.write(row("Emoji", "🎉 🚀 📁 📄 ⭐ 🔥 👍") + "\n")
+    w.write(row("Nerd Font PUA", "\uF114 folder  \uF0F6 file  \uE0B0 arrow  \uF013 gear") + "\n")
+    w.write(row("If PUA = boxes →", "Nerd Fonts not installed") + "\n")
+  }
+
+  if (show("emoji")) {
+    // Each test line places a character then fills to exactly 10 visible columns.
+    // If the _'s don't align with the ruler, the terminal's character width
+    // disagrees with the expected width (shown in parentheses).
+    w.write(sectionHeader("Emoji Width Alignment (_'s should align with ruler)"))
+    w.write("  Ruler:     |1234567890|\n")
+    w.write("  ASCII 'A': |A_________| (w=1)\n")
+    w.write("  CJK '你':  |你________| (w=2)\n")
+    w.write("  Flag 🇨🇦:  |🇨🇦________| (w=2)\n")
+    w.write("  Flag 🇺🇸:  |🇺🇸________| (w=2)\n")
+    w.write("  Emoji 📁:  |📁________| (w=2)\n")
+    w.write("  Emoji 📄:  |📄________| (w=2)\n")
+    w.write("  Emoji 📋:  |📋________| (w=2)\n")
+    w.write("  Emoji ⚠️:  |⚠️________| (w=2)\n")
+    w.write("  Text  ⚠:   |⚠_________| (w=1 text, 2 emoji)\n")
+    w.write("  Text  ⭐:   |⭐________| (w=1 text, 2 emoji)\n")
+    w.write("  Text  ☑:   |☑_________| (w=1 text, 2 emoji)\n")
+    w.write("  Emoji 🏠:  |🏠________| (w=2)\n")
+    w.write("  Emoji 👓:  |👓________| (w=2)\n")
+    w.write("  ZWJ 👨🏻‍💻: |👨🏻‍💻________| (w=2)\n")
+    w.write("  Arrow →:   |→_________| (w=1)\n")
+    w.write("  Arrow ▸:   |▸_________| (w=1)\n")
+    w.write("  Circle ○:  |○_________| (w=1)\n")
+    w.write("  Square □:  |□_________| (w=1)\n")
+    w.write("  Check ✓:   |✓_________| (w=1)\n")
+  }
+
+  if (show("borders")) {
+    w.write(sectionHeader("Box Drawing Borders"))
+    w.write("  ┌──────────┐  ╔══════════╗  ╭──────────╮\n")
+    w.write("  │  single  │  ║  double  ║  │  round   │\n")
+    w.write("  └──────────┘  ╚══════════╝  ╰──────────╯\n")
+  }
+
+  if (show("inverse")) {
+    w.write(sectionHeader("Inverse + Background (potential artifact source)"))
+    w.write(row("Red FG + Inverse", `${sgr(31, 7)}This should have red background${RESET}`) + "\n")
+    w.write(row("Cyan BG + White FG", `${sgr(46, 37)}Cyan background, white text${RESET}`) + "\n")
+    w.write(row("Black BG + White FG", `${sgr(40, 97)}Black bg, bright white text${RESET}`) + "\n")
+    w.write(row("White BG + Black FG", `${sgr(107, 30)}White bg, black text${RESET}`) + "\n")
+
+    w.write(sectionHeader("Reset Sanity Check"))
+    w.write("  This line should be completely normal with no formatting artifacts.\n")
+    w.write("  If you see colors, underlines, or other styling above, the terminal\n")
+    w.write("  failed to process an SGR reset (\\x1b[0m) correctly.\n")
+  }
+
+  if (show("profile")) {
+    w.write(sectionHeader("Detected Terminal Profile"))
+    const entries = Object.entries(caps) as [string, unknown][]
+    for (const [key, value] of entries) {
+      const indicator = value === true ? "✓" : value === false ? "✗" : String(value)
+      w.write(`  ${key.padEnd(20)} ${indicator}\n`)
+    }
+  }
+
+  w.write("\n")
+}

package/src/text-sizing.ts

@@ -0,0 +1,109 @@
+/**
+ * Text Sizing Protocol (OSC 66) -- Kitty v0.40+
+ *
+ * Lets the app specify how many cells a character should occupy.
+ * This solves the measurement/rendering mismatch for Private Use Area (PUA)
+ * characters (nerdfont icons, powerline symbols) that `string-width` reports
+ * as 1-cell but terminals render as 2-cell.
+ *
+ * When OSC 66 is used with w=2, both the app's layout engine and the terminal
+ * agree on the character width, eliminating truncation and misalignment.
+ *
+ * Protocol format:
+ *   ESC ] 66 ; w=<width> ; <text> BEL
+ *
+ * @see https://sw.kovidgoyal.net/kitty/text-sizing-protocol/
+ */
+
+const OSC = "\x1b]"
+const ST = "\x07" // BEL terminator (more compatible than ESC \)
+
+/**
+ * Wrap text in an OSC 66 sequence that tells the terminal to render it
+ * in exactly `width` cells.
+ */
+export function textSized(text: string, width: number): string {
+  return `${OSC}66;w=${width};${text}${ST}`
+}
+
+/**
+ * Check if a code point is in the Private Use Area (PUA).
+ * Covers BMP PUA (U+E000-U+F8FF) and Supplementary PUA-A/B.
+ */
+export function isPrivateUseArea(cp: number): boolean {
+  return (
+    (cp >= 0xe000 && cp <= 0xf8ff) || // BMP PUA
+    (cp >= 0xf0000 && cp <= 0xffffd) || // Supplementary PUA-A
+    (cp >= 0x100000 && cp <= 0x10fffd) // Supplementary PUA-B
+  )
+}
+
+/**
+ * Check if text sizing is likely supported based on environment variables.
+ * This is a fast synchronous check -- use detectTextSizingSupport() for
+ * definitive detection via cursor position reports.
+ */
+export function isTextSizingLikelySupported(): boolean {
+  const termProgram = process.env.TERM_PROGRAM?.toLowerCase() ?? ""
+  const termVersion = process.env.TERM_PROGRAM_VERSION ?? ""
+
+  // Kitty v0.40+ supports OSC 66
+  if (termProgram === "kitty") {
+    const parts = termVersion.split(".")
+    const major = Number(parts[0]) || 0
+    const minor = Number(parts[1]) || 0
+    if (major > 0 || (major === 0 && minor >= 40)) return true
+  }
+
+  // Ghostty parses OSC 66 but does NOT render it (as of v1.3.0, March 2026).
+  // Wrapping text in OSC 66 causes Ghostty to swallow the content silently.
+  // Re-enable when Ghostty ships actual text sizing GUI support.
+  // if (termProgram === "ghostty") return true
+
+  return false
+}
+
+/**
+ * Detect terminal support for the text sizing protocol.
+ * Uses cursor position reports (CPR) to check if OSC 66 advances the cursor
+ * by the specified width.
+ *
+ * @returns Object with `supported` and `widthOnly` flags:
+ * - supported=true, widthOnly=false: full support (scale + width)
+ * - supported=true, widthOnly=true: width mode only
+ * - supported=false: no support
+ */
+export async function detectTextSizingSupport(
+  write: (data: string) => void,
+  read: () => Promise<string>,
+  timeout = 1000,
+): Promise<{ supported: boolean; widthOnly: boolean }> {
+  // Detection sequence:
+  // 1. CR to column 0
+  // 2. OSC 66 w=2 with a space character
+  // 3. Request CPR (cursor position report)
+  // If cursor is at column 3 (1-indexed), w=2 worked
+  const testSequence = "\r" + textSized(" ", 2) + "\x1b[6n" + "\r\x1b[K"
+  write(testSequence)
+
+  try {
+    const response = await Promise.race([
+      read(),
+      new Promise<string>((_resolve, reject) => setTimeout(() => reject(new Error("timeout")), timeout)),
+    ])
+
+    // Parse CPR response: ESC [ row ; col R
+    const match = response.match(/\x1b\[(\d+);(\d+)R/)
+    if (match) {
+      const col = Number(match[2])
+      // Column 3 means the space occupied 2 cells (col is 1-indexed, started at 1)
+      if (col === 3) {
+        return { supported: true, widthOnly: false }
+      }
+    }
+
+    return { supported: false, widthOnly: false }
+  } catch {
+    return { supported: false, widthOnly: false }
+  }
+}

package/src/toolbelt/index.ts

@@ -0,0 +1,72 @@
+/**
+ * silvery/toolbelt - Diagnostic and helper tools for debugging TUI rendering
+ *
+ * Central import for all diagnostic utilities. Use this when you need to:
+ * - Debug incremental rendering issues
+ * - Verify ANSI replay correctness
+ * - Check buffer content stability
+ *
+ * @example
+ * ```typescript
+ * import {
+ *   withDiagnostics,
+ *   VirtualTerminal,
+ *   IncrementalRenderMismatchError,
+ *   compareBuffers,
+ *   formatMismatch,
+ * } from '@silvery/term/toolbelt';
+ *
+ * // All checks enabled by default when plugin is used
+ * const driver = withDiagnostics(createBoardDriver(repo, rootId));
+ *
+ * // Or disable specific checks
+ * const driver = withDiagnostics(createBoardDriver(repo, rootId), {
+ *   checkReplay: false  // skip ANSI replay check
+ * });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// =============================================================================
+// Diagnostic Plugin
+// =============================================================================
+
+export {
+  withDiagnostics,
+  checkLayoutInvariants,
+  VirtualTerminal,
+  type DiagnosticOptions,
+} from "@silvery/tea/with-diagnostics"
+
+// =============================================================================
+// Error Types
+// =============================================================================
+
+export { IncrementalRenderMismatchError } from "../scheduler"
+
+// =============================================================================
+// Buffer Comparison
+// =============================================================================
+
+export { compareBuffers, formatMismatch, type BufferMismatch } from "@silvery/test/compare-buffers"
+
+// =============================================================================
+// Pipeline Internals (for manual ANSI replay verification)
+// =============================================================================
+
+export { outputPhase } from "../pipeline"
+
+// =============================================================================
+// Mismatch Debug Utilities
+// =============================================================================
+
+export {
+  findNodeAtPosition,
+  findAllContainingNodes,
+  getNodeDebugInfo,
+  buildMismatchContext,
+  formatMismatchContext,
+  type NodeDebugInfo,
+  type MismatchDebugContext,
+} from "@silvery/test/debug-mismatch"