@fairyhunter13/opentui-core 0.1.89 → 0.1.91

package/README.md

@@ -13,7 +13,7 @@ OpenTUI is a native terminal UI core written in Zig with TypeScript bindings. Th
 ## Install
 
 ```bash
-bun install @opentui/core
+bun install @fairyhunter13/opentui-core
 ```
 
 ## Build
@@ -52,7 +52,7 @@ NativeSpanFeed TypeScript benchmarks:
 Renderables are hierarchical objects that can be positioned, nested, styled and rendered to the terminal:
 
 ```typescript
-import { createCliRenderer, TextRenderable } from "@opentui/core"
+import { createCliRenderer, TextRenderable } from "@fairyhunter13/opentui-core"
 
 const renderer = await createCliRenderer()
 

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.id)
+      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/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)
+})

package/docs/development.md

@@ -0,0 +1,141 @@
+# Development Guide
+
+## Prerequisites
+
+- [Bun](https://bun.sh) - JavaScript runtime and package manager
+- [Zig](https://ziglang.org/learn/getting-started/) - Required for building native modules
+
+## Setup
+
+```bash
+git clone https://github.com/anomalyco/opentui.git
+cd opentui
+bun install
+```
+
+## Building
+
+```bash
+bun run build
+```
+
+**Note:** Only needed when changing native Zig code. TypeScript changes don't require rebuilding.
+
+## Running Examples
+
+```bash
+cd packages/core
+bun run src/examples/index.ts
+```
+
+## Testing
+
+```bash
+# TypeScript tests
+cd packages/core
+bun test
+
+# Native tests
+bun run test:native
+
+# Filter native tests
+bun run test:native -Dtest-filter="test name"
+
+# Benchmarks
+bun run bench:native
+```
+
+## Local Development Linking
+
+Link your local OpenTUI to another project:
+
+```bash
+./scripts/link-opentui-dev.sh /path/to/your/project
+```
+
+**Options:**
+
+- `--react` - Also link `@fairyhunter13/opentui-react` and React dependencies
+- `--solid` - Also link `@fairyhunter13/opentui-solid` and SolidJS dependencies
+- `--dist` - Link built `dist` directories instead of source
+- `--copy` - Copy instead of symlink (requires `--dist`)
+- `--subdeps` - Find and link packages that depend on opentui (e.g., `opentui-spinner`)
+
+**Examples:**
+
+```bash
+# Link core only
+./scripts/link-opentui-dev.sh /path/to/your/project
+
+# Link core and solid with subdependency discovery
+./scripts/link-opentui-dev.sh /path/to/your/project --solid --subdeps
+
+# Link built artifacts
+./scripts/link-opentui-dev.sh /path/to/your/project --react --dist
+
+# Copy for Docker/Windows
+./scripts/link-opentui-dev.sh /path/to/your/project --dist --copy
+```
+
+The script automatically links:
+
+- Main packages: `@fairyhunter13/opentui-core`, `@fairyhunter13/opentui-solid`, `@fairyhunter13/opentui-react`
+- Peer dependencies: `yoga-layout`, `solid-js`, `react`, `react-dom`, `react-reconciler`
+- Subdependencies (with `--subdeps`): Packages like `opentui-spinner` that depend on opentui
+
+**Requirements:** Target project must have `node_modules` (run `bun install` first).
+
+## Debugging
+
+OpenTUI captures `console.log` output. Toggle the built-in console with backtick or use [Environment Variables](./env-vars.md) for debugging.
+
+## Terminal Compatibility
+
+### OSC 66 Artifacts on Older Terminals
+
+**Problem:** If you see weird artifacts containing "66" in your terminal when running OpenTUI applications, your terminal emulator doesn't support OSC 66 escape sequences (used for explicit character width detection).
+
+**Affected Terminals:**
+
+- GNOME Terminal
+- Konsole (older versions)
+- xterm (older versions)
+- Many VT100/VT220 emulators
+
+**Solution:** Disable OSC 66 queries by setting an environment variable:
+
+```bash
+export OPENTUI_FORCE_EXPLICIT_WIDTH=false
+```
+
+Or run your application with:
+
+```bash
+OPENTUI_FORCE_EXPLICIT_WIDTH=false your-app
+```
+
+**For Application Developers:**
+
+Set it in your code before creating the renderer:
+
+```typescript
+process.env.OPENTUI_FORCE_EXPLICIT_WIDTH = "false"
+
+const renderer = new CliRenderer()
+// ... rest of your app
+```
+
+Or add to your `.env` file:
+
+```bash
+OPENTUI_FORCE_EXPLICIT_WIDTH=false
+```
+
+**What This Does:**
+
+- Prevents OSC 66 detection queries from being sent
+- Disables the explicit width feature
+- Falls back to standard width calculation
+- No visual artifacts on unsupported terminals
+
+**Modern Terminals:** If your terminal supports OSC 66 (Kitty, Ghostty, WezTerm, Alacritty, iTerm2), you don't need this setting - they work correctly by default.

package/docs/env-vars.md

@@ -0,0 +1,140 @@
+# Environment Variables
+
+# Environment Variables
+
+## OTUI_TS_STYLE_WARN
+
+Enable warnings for missing syntax styles
+
+**Type:** `string`  
+**Default:** `false`
+
+## OTUI_TREE_SITTER_WORKER_PATH
+
+Path to the TreeSitter worker
+
+**Type:** `string`  
+**Default:** `""`
+
+## XDG_CONFIG_HOME
+
+Base directory for user-specific configuration files
+
+**Type:** `string`  
+**Default:** `""`
+
+## XDG_DATA_HOME
+
+Base directory for user-specific data files
+
+**Type:** `string`  
+**Default:** `""`
+
+## OTUI_DEBUG_FFI
+
+Enable debug logging for the FFI bindings.
+
+**Type:** `boolean`  
+**Default:** `false`
+
+## OTUI_SHOW_STATS
+
+Show the debug overlay at startup.
+
+**Type:** `boolean`  
+**Default:** `false`
+
+## OTUI_TRACE_FFI
+
+Enable tracing for the FFI bindings.
+
+**Type:** `boolean`  
+**Default:** `false`
+
+## OPENTUI_FORCE_WCWIDTH
+
+Use wcwidth for character width calculations
+
+**Type:** `boolean`  
+**Default:** `false`
+
+## OPENTUI_FORCE_UNICODE
+
+Force Mode 2026 Unicode support in terminal capabilities
+
+**Type:** `boolean`  
+**Default:** `false`
+
+## OPENTUI_GRAPHICS
+
+Enable Kitty graphics protocol detection
+
+**Type:** `boolean`  
+**Default:** `true`
+
+## OPENTUI_FORCE_NOZWJ
+
+Use no_zwj width method (Unicode without ZWJ joining)
+
+**Type:** `boolean`  
+**Default:** `false`
+
+## OPENTUI_FORCE_EXPLICIT_WIDTH
+
+Force explicit width capability in terminal to true or false. Set to "true" or "1" to enable, "false" or "0" to disable. When set to "false" or "0", also skips sending OSC 66 detection queries to prevent artifacts on older terminals (e.g., GNOME Terminal).
+
+**Type:** `string`
+**Values:** `"true"`, `"1"`, `"false"`, `"0"`
+
+## OTUI_USE_CONSOLE
+
+Whether to use the console. Will not capture console output if set to false.
+
+**Type:** `boolean`  
+**Default:** `true`
+
+## SHOW_CONSOLE
+
+Show the console at startup if set to true.
+
+**Type:** `boolean`  
+**Default:** `false`
+
+## OTUI_DUMP_CAPTURES
+
+Dump captured output when the renderer exits.
+
+**Type:** `boolean`  
+**Default:** `false`
+
+## OTUI_NO_NATIVE_RENDER
+
+Disable native rendering. This will not actually output ansi and is useful for debugging.
+
+**Type:** `boolean`  
+**Default:** `false`
+
+## OTUI_USE_ALTERNATE_SCREEN
+
+Whether to use the console. Will not capture console output if set to false.
+
+**Type:** `boolean`  
+**Default:** `true`
+
+## OTUI_OVERRIDE_STDOUT
+
+Override the stdout stream. This is useful for debugging.
+
+**Type:** `boolean`  
+**Default:** `true`
+
+## OTUI_DEBUG
+
+Enable debug mode to capture all raw input for debugging purposes.
+
+**Type:** `boolean`  
+**Default:** `false`
+
+---
+
+_generated via packages/core/dev/print-env-vars.ts_