@xincli/opentui-core 0.4.6

package/README.md

@@ -0,0 +1,63 @@
+# OpenTUI Core
+
+OpenTUI is a native terminal UI core written in Zig with TypeScript bindings. The native core exposes a C ABI and can be used from any language. OpenTUI powers OpenCode in production today and will also power terminal.shop. It is an extensible core with a focus on correctness, stability, and high performance. It provides a component-based architecture with flexible layout capabilities, allowing you to create complex terminal applications.
+
+## Documentation
+
+- [Getting Started](docs/getting-started.md) - API and usage guide
+- [Development Guide](docs/development.md) - Building, testing, and contributing
+- [Tree-Sitter](docs/tree-sitter.md) - Syntax highlighting integration
+- [Renderables vs Constructs](docs/renderables-vs-constructs.md) - Understanding the component model
+- [Environment Variables](docs/env-vars.md) - Configuration options
+
+## Install
+
+```bash
+bun install @opentui/core
+```
+
+## Build
+
+```bash
+bun run build
+```
+
+This creates platform-specific libraries that are automatically loaded by the TypeScript layer.
+
+## Examples
+
+```bash
+bun install
+cd ../examples
+bun run dev
+```
+
+## Benchmarks
+
+Run native performance benchmarks:
+
+```bash
+bun run bench:native
+```
+
+See [src/zig/bench.zig](src/zig/bench.zig) for available options like `--filter` and `--mem`.
+
+NativeSpanFeed TypeScript benchmarks:
+
+- [src/benchmark/native-span-feed-benchmark.md](src/benchmark/native-span-feed-benchmark.md)
+
+## CLI Renderer
+
+### Renderables
+
+Renderables are hierarchical objects that can be positioned, nested, styled and rendered to the terminal:
+
+```typescript
+import { createCliRenderer, TextRenderable } from "@opentui/core"
+
+const renderer = await createCliRenderer()
+
+const obj = new TextRenderable(renderer, { id: "my-obj", content: "Hello, world!" })
+
+renderer.root.add(obj)
+```

package/dev/keypress-debug-renderer.ts

@@ -0,0 +1,148 @@
+#!/usr/bin/env bun
+import { BoxRenderable, type CliRenderer, createCliRenderer, CodeRenderable, addDefaultParsers } from "../src/index.js"
+import { ScrollBoxRenderable } from "../src/renderables/ScrollBox.js"
+import { SyntaxStyle } from "../src/syntax-style.js"
+import { parseColor } from "../src/lib/RGBA.js"
+
+const parsers = [
+  {
+    filetype: "json",
+    wasm: "https://github.com/tree-sitter/tree-sitter-json/releases/download/v0.24.8/tree-sitter-json.wasm",
+    queries: {
+      highlights: [
+        "https://raw.githubusercontent.com/nvim-treesitter/nvim-treesitter/refs/heads/master/queries/json/highlights.scm",
+      ],
+    },
+  },
+]
+addDefaultParsers(parsers)
+let scrollBox: ScrollBoxRenderable | null = null
+let renderer: CliRenderer | null = null
+let syntaxStyle: SyntaxStyle | null = null
+let eventCount = 0
+
+function addEvent(eventType: string, event: object) {
+  if (!renderer || !scrollBox || !syntaxStyle) return
+
+  eventCount++
+
+  const eventData = {
+    type: eventType,
+    timestamp: new Date().toISOString(),
+    ...event,
+  }
+
+  const eventBox = new BoxRenderable(renderer, {
+    id: `event-${eventCount}`,
+    width: "auto",
+    marginBottom: 1,
+    padding: 1,
+    backgroundColor: "#1f2937",
+  })
+
+  const codeDisplay = new CodeRenderable(renderer, {
+    id: `event-code-${eventCount}`,
+    content: JSON.stringify(eventData, null, 2),
+    filetype: "json",
+    conceal: false,
+    syntaxStyle,
+    bg: "#1f2937",
+  })
+
+  eventBox.add(codeDisplay)
+  scrollBox.add(eventBox)
+
+  const children = scrollBox.getChildren()
+  if (children.length > 50) {
+    const oldest = children[0]
+    if (oldest) {
+      scrollBox.remove(oldest)
+      oldest.destroyRecursively()
+    }
+  }
+}
+
+async function main() {
+  const usePrepend = process.argv.includes("--prepend")
+  const prependInputHandlers = usePrepend
+    ? [
+        (sequence: string) => {
+          addEvent("raw-input-before", { sequence })
+          return false
+        },
+      ]
+    : []
+  renderer = await createCliRenderer({
+    exitOnCtrlC: true,
+    targetFps: 60,
+    useKittyKeyboard: { events: true },
+    prependInputHandlers,
+  })
+
+  renderer.setBackgroundColor("#0D1117")
+
+  const mainContainer = new BoxRenderable(renderer, {
+    id: "main-container",
+    flexGrow: 1,
+    flexDirection: "column",
+  })
+
+  renderer.root.add(mainContainer)
+
+  scrollBox = new ScrollBoxRenderable(renderer, {
+    id: "event-scroll-box",
+    stickyScroll: true,
+    stickyStart: "bottom",
+    border: true,
+    borderColor: "#6BCF7F",
+    title: `Keypress Debug${usePrepend ? " (prepend mode)" : ""} (Ctrl+C to exit)`,
+    titleAlignment: "center",
+    contentOptions: {
+      paddingLeft: 1,
+      paddingRight: 1,
+      paddingTop: 1,
+    },
+  })
+
+  mainContainer.add(scrollBox)
+
+  syntaxStyle = SyntaxStyle.fromStyles({
+    string: { fg: parseColor("#A5D6FF") },
+    number: { fg: parseColor("#79C0FF") },
+    boolean: { fg: parseColor("#79C0FF") },
+    keyword: { fg: parseColor("#FF7B72") },
+    default: { fg: parseColor("#E6EDF3") },
+  })
+
+  addEvent("capabilities", renderer.capabilities)
+
+  renderer.addInputHandler((sequence) => {
+    addEvent("raw-input-after", { sequence })
+    return true
+  })
+
+  renderer.keyInput.on("keypress", (event) => {
+    addEvent("keypress", event)
+
+    if (event.name === "c" && event.shift) {
+      if (renderer) {
+        addEvent("capabilities", renderer.capabilities)
+      }
+    }
+  })
+
+  renderer.keyInput.on("keyrelease", (event) => {
+    addEvent("keyrelease", event)
+  })
+
+  renderer.keyInput.on("paste", (event) => {
+    addEvent("paste", event)
+  })
+
+  renderer.requestRender()
+}
+
+main().catch((err) => {
+  console.error("Error:", err)
+  process.exit(1)
+})

package/dev/keypress-debug.ts

@@ -0,0 +1,43 @@
+#!/usr/bin/env bun
+import { parseKeypress } from "../src/lib/parse.keypress.ts"
+
+console.log("Keypress Debug Tool")
+console.log("Press keys to see their parsed output. Press Ctrl+C to exit.\n")
+
+// Set stdin to raw mode to capture individual keypresses
+process.stdin.setRawMode(true)
+process.stdin.resume()
+
+// Listen for keypress data
+process.stdin.on("data", (data: Buffer) => {
+  // Check for Ctrl+C to exit
+  if (data.toString() === "\x03") {
+    console.log("\nExiting keypress debug tool...")
+    process.stdin.setRawMode(false)
+    process.exit(0)
+  }
+
+  const parsed = parseKeypress(data)
+
+  console.log("Input data:", JSON.stringify(data.toString()))
+  console.log("Raw:", JSON.stringify(parsed?.raw))
+  console.log("Parsed:", {
+    name: parsed?.name,
+    ctrl: parsed?.ctrl,
+    meta: parsed?.meta,
+    shift: parsed?.shift,
+    option: parsed?.option,
+    number: parsed?.number,
+    sequence: parsed?.sequence,
+    code: parsed?.code,
+    buffer: data,
+  })
+  console.log("---")
+})
+
+// Handle Ctrl+C gracefully
+process.on("SIGINT", () => {
+  console.log("\nExiting keypress debug tool...")
+  process.stdin.setRawMode(false)
+  process.exit(0)
+})

package/dev/print-env-vars.ts

@@ -0,0 +1,32 @@
+#!/usr/bin/env bun
+
+/**
+ * Development script to print all registered environment variables
+ *
+ * Usage:
+ *   bun dev/print-env-vars.ts          # Colored output (default)
+ *   bun dev/print-env-vars.ts --markdown  # Markdown output
+ *   bun dev/print-env-vars.ts --update   # Update docs/env-vars.md
+ */
+
+import { generateEnvColored, generateEnvMarkdown } from "../src/index.js"
+import { join } from "path"
+
+const args = process.argv.slice(2)
+const useMarkdown = args.includes("--markdown")
+const updateDocs = args.includes("--update")
+
+const generateMarkdownContent = () => {
+  return `# Environment Variables\n\n${generateEnvMarkdown()}---\n\n_generated via packages/core/dev/print-env-vars.ts_\n`
+}
+
+if (updateDocs) {
+  const docsPath = join(import.meta.dir, "../docs/env-vars.md")
+  const content = generateMarkdownContent()
+  await Bun.write(docsPath, content)
+  console.log(`✓ Updated ${docsPath}`)
+} else if (useMarkdown) {
+  console.log(`${generateEnvMarkdown()}\n---\n_generated via packages/core/dev/print-env-vars.ts_`)
+} else {
+  console.log(generateEnvColored())
+}

package/dev/test-tmux-graphics-334.sh

@@ -0,0 +1,68 @@
+#!/bin/bash
+# Test script for issue #334: Kitty Graphics Protocol query leaks into tmux pane title
+#
+# This script verifies that the kitty graphics query doesn't corrupt tmux pane titles.
+# Run this inside tmux to test.
+#
+# Usage: ./test-tmux-graphics-334.sh
+#
+# Expected results:
+#   - Test 1 (Direct query): FAIL - demonstrates the bug
+#   - Test 2 (DCS passthrough): PASS - demonstrates the fix
+#   - Test 3 (No query): PASS - control test
+
+set -e
+
+SESSION_NAME="opentui-test-334-$$"
+EXPECTED_TITLE="test-title"
+
+cleanup() {
+    tmux kill-session -t "$SESSION_NAME" 2>/dev/null || true
+}
+trap cleanup EXIT
+
+run_test() {
+    local test_name="$1"
+    local query_cmd="$2"
+    
+    cleanup
+    tmux new-session -d -s "$SESSION_NAME" -x 80 -y 24
+    tmux select-pane -t "$SESSION_NAME" -T "$EXPECTED_TITLE"
+    
+    if [ -n "$query_cmd" ]; then
+        tmux send-keys -t "$SESSION_NAME" "$query_cmd" Enter
+        sleep 0.5
+    fi
+    
+    local after_title
+    after_title=$(tmux display-message -t "$SESSION_NAME" -p '#{pane_title}')
+    
+    if [[ "$after_title" == *"Gi=31337"* ]] || [[ "$after_title" == *"i=31337"* ]]; then
+        echo "FAIL: $test_name - pane title corrupted: '$after_title'"
+        return 1
+    elif [[ "$after_title" != "$EXPECTED_TITLE" ]]; then
+        echo "WARN: $test_name - pane title changed: '$after_title'"
+        return 1
+    else
+        echo "PASS: $test_name"
+        return 0
+    fi
+}
+
+echo "=== Issue #334 Test: Kitty Graphics Query in tmux ==="
+echo "tmux version: $(tmux -V)"
+echo ""
+
+echo "Test 1: Direct query (demonstrates bug)"
+run_test "Direct kitty graphics query" \
+    "printf '\\x1b_Gi=31337,s=1,v=1,a=q,t=d,f=24;AAAA\\x1b\\\\\\x1b[c'" || true
+
+echo "Test 2: DCS passthrough wrapped query (demonstrates fix)"
+run_test "DCS passthrough wrapped" \
+    "printf '\\x1bPtmux;\\x1b\\x1b_Gi=31337,s=1,v=1,a=q,t=d,f=24;AAAA\\x1b\\x1b\\\\\\x1b\\x1b[c\\x1b\\\\'"
+
+echo "Test 3: No query (control)"
+run_test "No query" ""
+
+echo ""
+echo "If Test 1 fails and Test 2 passes, the fix is working correctly."

package/dev/test-tmux-theme-queries.sh

@@ -0,0 +1,151 @@
+#!/bin/bash
+# Probe theme-related terminal queries inside and outside tmux.
+#
+# Run this in the pane you want to test. It writes queries directly to /dev/tty,
+# captures any replies, and prints both an escaped representation and raw hex.
+#
+# Usage:
+#   ./packages/core/dev/test-tmux-theme-queries.sh
+
+set -u
+set -o pipefail
+
+LC_ALL=C
+
+ESC=$'\033'
+BEL=$'\a'
+ST="${ESC}\\"
+LOG_FILE="${LOG_FILE:-./_tmux_theme_query_$(date +%s).log}"
+
+exec 3<> /dev/tty
+
+ORIGINAL_STTY="$(stty -g <&3)"
+
+cleanup() {
+  stty "$ORIGINAL_STTY" <&3 2>/dev/null || true
+  exec 3>&- 3<&-
+}
+
+interrupt() {
+  cleanup
+  exit 130
+}
+
+trap cleanup EXIT
+trap interrupt INT TERM
+
+READ_GAP_TENTHS="${READ_GAP_TENTHS:-4}"
+
+stty -echo -icanon min 0 time "$READ_GAP_TENTHS" <&3
+
+tmux_wrap() {
+  local payload="$1"
+  payload=${payload//$ESC/$ESC$ESC}
+  printf '%s' "${ESC}Ptmux;${payload}${ST}"
+}
+
+escape_for_display() {
+  local value="$1"
+  value=${value//$ESC/\\e}
+  value=${value//$BEL/\\a}
+  value=${value//$'\r'/\\r}
+  value=${value//$'\n'/\\n$'\n'}
+  value=${value//$'\t'/\\t}
+  printf '%s' "$value"
+}
+
+hex_dump() {
+  if [ -z "$1" ]; then
+    printf '(none)\n'
+    return
+  fi
+
+  printf '%s' "$1" | od -An -tx1 -v | tr -s ' ' | sed 's/^ //'
+}
+
+read_until_gap() {
+  local response=""
+  local chunk=""
+
+  while true; do
+    chunk="$(dd bs=1 count=1 2>/dev/null <&3)"
+    if [ -z "$chunk" ]; then
+      break
+    fi
+    response+="$chunk"
+  done
+
+  printf '%s' "$response"
+}
+
+drain_input() {
+  local drained=""
+  drained="$(read_until_gap)"
+  if [ -n "$drained" ]; then
+    printf 'Drained pending input before next test.\n' | tee -a "$LOG_FILE"
+    printf '  escaped: %s\n' "$(escape_for_display "$drained")" | tee -a "$LOG_FILE"
+    printf '  hex: %s\n' "$(hex_dump "$drained")" | tee -a "$LOG_FILE"
+  fi
+}
+
+run_case() {
+  local name="$1"
+  local payload="$2"
+  local response=""
+
+  drain_input
+
+  {
+    printf '\n=== %s ===\n' "$name"
+    printf 'query escaped: %s\n' "$(escape_for_display "$payload")"
+    printf 'query hex: %s\n' "$(hex_dump "$payload")"
+  } | tee -a "$LOG_FILE"
+
+  printf '%s' "$payload" >&3
+  response="$(read_until_gap)"
+
+  if [ -z "$response" ]; then
+    printf 'response: (none)\n' | tee -a "$LOG_FILE"
+    return
+  fi
+
+  {
+    printf 'response escaped: %s\n' "$(escape_for_display "$response")"
+    printf 'response hex: %s\n' "$(hex_dump "$response")"
+  } | tee -a "$LOG_FILE"
+}
+
+OSC10_BEL="${ESC}]10;?${BEL}"
+OSC11_BEL="${ESC}]11;?${BEL}"
+OSC10_ST="${ESC}]10;?${ST}"
+OSC11_ST="${ESC}]11;?${ST}"
+OSC10_11_BEL="${OSC10_BEL}${OSC11_BEL}"
+OSC10_11_ST="${OSC10_ST}${OSC11_ST}"
+CPR_QUERY="${ESC}[6n"
+XTVERSION_QUERY="${ESC}[>0q"
+COLOR_SCHEME_REQUEST="${ESC}[?996n"
+
+{
+  printf 'tmux theme query probe\n'
+  printf 'log file: %s\n' "$LOG_FILE"
+  printf 'tmux env: %s\n' "${TMUX:-<not set>}"
+  printf 'TERM: %s\n' "${TERM:-<not set>}"
+  printf 'TERM_PROGRAM: %s\n' "${TERM_PROGRAM:-<not set>}"
+  printf 'read gap tenths: %s\n' "$READ_GAP_TENTHS"
+  printf '\n'
+  printf 'Recommended: run this inside tmux in the same pane where theme-mode.ts fails.\n'
+} | tee "$LOG_FILE"
+
+run_case 'Control: plain CPR (CSI 6n)' "$CPR_QUERY"
+run_case 'Control: plain xtversion (CSI > 0q)' "$XTVERSION_QUERY"
+run_case 'Plain OSC 10/11 combined with BEL terminators' "$OSC10_11_BEL"
+run_case 'Plain OSC 10/11 combined with ST terminators' "$OSC10_11_ST"
+run_case 'tmux wrapped OSC 10/11 combined in one DCS wrapper (BEL)' "$(tmux_wrap "$OSC10_11_BEL")"
+run_case 'tmux wrapped OSC 10/11 combined in one DCS wrapper (ST)' "$(tmux_wrap "$OSC10_11_ST")"
+run_case 'tmux wrapped OSC 10 only (BEL)' "$(tmux_wrap "$OSC10_BEL")"
+run_case 'tmux wrapped OSC 11 only (BEL)' "$(tmux_wrap "$OSC11_BEL")"
+run_case 'tmux wrapped OSC 10 then OSC 11 as separate DCS wrappers (BEL)' "$(tmux_wrap "$OSC10_BEL")$(tmux_wrap "$OSC11_BEL")"
+run_case 'Plain color scheme request (CSI ?996n)' "$COLOR_SCHEME_REQUEST"
+run_case 'tmux wrapped color scheme request (CSI ?996n)' "$(tmux_wrap "$COLOR_SCHEME_REQUEST")"
+
+printf '\nDone. If you want, paste the generated log file and I will compare which query forms tmux answers.\n' | tee -a "$LOG_FILE"

package/dev/thai-debug-test.ts

@@ -0,0 +1,68 @@
+#!/usr/bin/env bun
+import { TextRenderable, createCliRenderer } from "../src/index.js"
+import { ScrollBoxRenderable } from "../src/renderables/ScrollBox.js"
+async function main() {
+  const renderer = await createCliRenderer({ exitOnCtrlC: true })
+  console.log("capabilities:", renderer.capabilities)
+  const scrollBox = new ScrollBoxRenderable(renderer, {
+    id: "scroll-box",
+    border: true,
+    height: 20,
+    title: "Thai Render Debug (Up/Down to scroll, Ctrl+C to exit)",
+    titleAlignment: "center",
+  })
+  const thaiLorem = `ภาษาไทยเป็นภาษาที่มีความสวยงามและซับซ้อนมาก มีพยัญชนะ 44 ตัว สระ 32 รูป และวรรณยุกต์ 4 รูป
+มอญเป็นชนชาติที่มีอิทธิพลต่อภาษาไทยมาก คำว่า "มอ" เป็นพยัญชนะที่ใช้บ่อยในภาษาไทย
+ตัวอย่างคำที่มี มอ: มา มี มือ มอง มัว มอบ มวย มอม มอด มอก
+การเขียนภาษาไทยต้องใส่ใจเรื่องวรรณยุกต์ เช่น ม่า ม้า หม่า หม้า
+สระลอยและสระเปลี่ยนรูปทำให้ภาษาไทยมีความพิเศษ เช่น เมือง แมว ไม้ ใหม่
+คำผสมที่น่าสนใจ: มอมแมม มอดมอด มอมเมา มืดมอม มอมดำ
+ภาษาไทยมีระบบการเขียนที่ไม่เว้นวรรคระหว่างคำ ทำให้การอ่านต้องอาศัยความเข้าใจ
+ตัวอักษรไทยมีสามระดับ: บน กลาง ล่าง เช่น ก็ ปี่ ฎุ ฏู ญ ฐ ฑ
+วรรณยุกต์ไทยมี 5 เสียง: สามัญ เอก โท ตรี จัตวา
+ตัวอย่างเสียงวรรณยุกต์: มา ม่า ม้า หมา หม่า หม้า
+การสะกดคำในภาษาไทยมีกฎเกณฑ์ที่ซับซ้อน มีทั้งตัวสะกดมาตราแม่ ก กา และตัวสะกดไม่ตรงมาตรา
+คำยืมจากภาษาบาลีสันสกฤต: กรรม ธรรม สงฆ์ ศาสนา พระ มหา
+คำยืมจากภาษาเขมร: ถนน เสวย ขนม ตำรวจ ทหาร
+คำยืมจากภาษาจีน: ก๋วยเตี๋ยว เต้าหู้ บะหมี่ เกี๊ยว ซาลาเปา
+ภาษาไทยถิ่นมีหลายภาษา: ภาษาเหนือ ภาษาอีสาน ภาษาใต้ ภาษากลาง
+มอญกับไทยมีความสัมพันธ์ทางวัฒนธรรมมายาวนาน
+ตัวเลขไทย: ๐ ๑ ๒ ๓ ๔ ๕ ๖ ๗ ๘ ๙
+เครื่องหมายวรรคตอน: ฯ ๆ ฯลฯ « » ๏
+อักษรไทยมีต้นกำเนิดจากอักษรเขมร ซึ่งมาจากอักษรปัลลวะของอินเดียใต้
+พ่อขุนรามคำแหงมหาราชทรงประดิษฐ์อักษรไทยเมื่อ พ.ศ. 1826
+ภาษาไทยเป็นภาษาที่มีวรรณยุกต์ การออกเสียงผิดวรรณยุกต์ทำให้ความหมายเปลี่ยน
+ตัวอย่าง: ขาว (สีขาว) ข่าว (news) ข้าว (rice) เข้า (enter)
+มอเตอร์ไซค์ มอนิเตอร์ มอลต์ มอร์ฟีน เป็นคำทับศัพท์ที่มี มอ
+สำนวนไทยที่มี มอ: มอมเมา หมอมหมาม มืดมอม มอดไหม้
+คำกริยาที่มี มอ: มอง มอบ มอม มอด มอก
+คำนามที่มี มอ: มอญ มอด หมอ มอเตอร์
+การผันวรรณยุกต์ของ มอ: มอ ม่อ ม้อ หมอ หม่อ หม้อ
+ภาษาไทยมีคำควบกล้ำ: กร กล กว ขร ขล ขว คร คล คว
+ตัวอย่างคำควบกล้ำ: กราบ กลาง กวาง ครู คลอง ความ
+อักษรสูง กลาง ต่ำ มีผลต่อการผันวรรณยุกต์
+อักษรสูง: ข ฃ ฉ ฐ ถ ผ ฝ ศ ษ ส ห
+อักษรกลาง: ก จ ฎ ฏ ด ต บ ป อ
+อักษรต่ำ: ค ฅ ฆ ง ช ซ ฌ ญ ฑ ฒ ณ ท ธ น พ ฟ ภ ม ย ร ล ว ฬ ฮ`
+  const text = new TextRenderable(renderer, {
+    id: "thai-text",
+    content: thaiLorem,
+  })
+  scrollBox.add(text)
+  renderer.root.add(scrollBox)
+  renderer.keyInput.on("keypress", (event) => {
+    if (event.name === "down") scrollBox.scrollDown()
+    if (event.name === "up") scrollBox.scrollUp()
+  })
+  renderer.requestRender()
+
+  renderer.keyInput.on("keypress", (event) => {
+    if (event.name === "`") {
+      renderer.console.toggle()
+    }
+  })
+}
+main().catch((err) => {
+  console.error("Error:", err)
+  process.exit(1)
+})