@xincli/opentui-core 0.4.6

package/dev/theme-mode.ts

@@ -0,0 +1,290 @@
+#!/usr/bin/env bun
+import { BoxRenderable, type CliRenderer, createCliRenderer, type KeyEvent, TextRenderable } from "../src/index.js"
+import { parseColor } from "../src/lib/RGBA.js"
+
+let renderer: CliRenderer | null = null
+let titleText: TextRenderable | null = null
+let themeText: TextRenderable | null = null
+let statusText: TextRenderable | null = null
+let eventCountText: TextRenderable | null = null
+let firstDrawText: TextRenderable | null = null
+let waitForThemeModeText: TextRenderable | null = null
+let historyText: TextRenderable | null = null
+let helpText: TextRenderable | null = null
+let themeModeEventCount = 0
+let firstDrawStartedAt = 0
+let timeToFirstDrawMs: number | null = null
+let waitForThemeModeStartedAt = 0
+let waitForThemeModeResolvedMs: number | null = null
+let waitForThemeModeResolvedValue: string | null = null
+const updateThemeHistory: string[] = []
+
+function stringifySequence(sequence: string): string {
+  return JSON.stringify(sequence)
+}
+
+function classifyDebugSequence(sequence: string): string | null {
+  if (sequence === "\x1b[?997;1n" || sequence === "\x1b[?997;2n") {
+    return "csi-theme-notify"
+  }
+
+  if (sequence.startsWith("\x1bP")) {
+    if (sequence.includes("\x1b]10;") || sequence.includes("\x1b]11;")) {
+      return "dcs-theme-reply"
+    }
+    if (sequence.includes(">|tmux")) {
+      return "dcs-xtversion"
+    }
+    return "dcs"
+  }
+
+  if (sequence.startsWith("\x1b]")) {
+    if (sequence.includes("\x1b]10;") || sequence.includes("\x1b]11;")) {
+      return "osc-theme-reply"
+    }
+    return "osc"
+  }
+
+  if (/^\x1b\[[0-9;]+R$/.test(sequence)) {
+    return "cpr"
+  }
+
+  if (sequence.includes("$y")) {
+    return "decrqm"
+  }
+
+  if (sequence.startsWith("\x1b[") && sequence.endsWith("c")) {
+    return "device-attributes"
+  }
+
+  return null
+}
+
+function updateThemeDisplay() {
+  if (!renderer || renderer.isDestroyed) return
+  if (
+    !titleText ||
+    !themeText ||
+    !statusText ||
+    !eventCountText ||
+    !firstDrawText ||
+    !waitForThemeModeText ||
+    !historyText ||
+    !helpText
+  )
+    return
+
+  const currentTheme = renderer.themeMode
+  updateThemeHistory.push(`updateThemeDisplay ${updateThemeHistory.length + 1}: themeMode=${currentTheme ?? "null"}`)
+  console.log("[theme-mode-debug] updateThemeDisplay", {
+    themeMode: currentTheme,
+    themeModeEventCount,
+    timeToFirstDrawMs,
+    waitForThemeModeResolvedMs,
+    waitForThemeModeResolvedValue,
+  })
+
+  eventCountText.content = `theme_mode events: ${themeModeEventCount}`
+  firstDrawText.content =
+    timeToFirstDrawMs === null ? "time to first draw: pending" : `time to first draw: ${timeToFirstDrawMs.toFixed(1)}ms`
+  waitForThemeModeText.content =
+    waitForThemeModeResolvedMs === null
+      ? "waitForThemeMode: pending"
+      : `waitForThemeMode: ${waitForThemeModeResolvedMs.toFixed(1)}ms (resolved ${waitForThemeModeResolvedValue ?? "null"})`
+  historyText.content = `updateThemeDisplay history:
+${updateThemeHistory.join("\n")}`
+
+  if (currentTheme === "dark") {
+    titleText.fg = parseColor("#6BCF7F")
+    themeText.content = "🌙 Dark Mode"
+    themeText.fg = parseColor("#A5D6FF")
+    statusText.content = "Terminal is in dark mode"
+    statusText.fg = parseColor("#D7DBE0")
+    eventCountText.fg = parseColor("#B8C0CC")
+    firstDrawText.fg = parseColor("#B8C0CC")
+    waitForThemeModeText.fg = parseColor("#B8C0CC")
+    historyText.fg = parseColor("#B8C0CC")
+    helpText.fg = parseColor("#8F9BA8")
+    renderer.setBackgroundColor("#1a1a2e")
+  } else if (currentTheme === "light") {
+    titleText.fg = parseColor("#166534")
+    themeText.content = "☀️ Light Mode"
+    themeText.fg = parseColor("#C2410C")
+    statusText.content = "Terminal is in light mode"
+    statusText.fg = parseColor("#1F2937")
+    eventCountText.fg = parseColor("#374151")
+    firstDrawText.fg = parseColor("#374151")
+    waitForThemeModeText.fg = parseColor("#374151")
+    historyText.fg = parseColor("#374151")
+    helpText.fg = parseColor("#4B5563")
+    renderer.setBackgroundColor("#f5f5f0")
+  } else {
+    titleText.fg = parseColor("#6BCF7F")
+    themeText.content = "❓ Unknown"
+    themeText.fg = parseColor("#FFA500")
+    statusText.content = "Theme mode not detected. Try switching your terminal theme."
+    statusText.fg = parseColor("#D7DBE0")
+    eventCountText.fg = parseColor("#B8C0CC")
+    firstDrawText.fg = parseColor("#B8C0CC")
+    waitForThemeModeText.fg = parseColor("#B8C0CC")
+    historyText.fg = parseColor("#B8C0CC")
+    helpText.fg = parseColor("#8F9BA8")
+    renderer.setBackgroundColor("#2d2d2d")
+  }
+}
+
+async function main() {
+  firstDrawStartedAt = performance.now()
+  console.log("[theme-mode-debug] starting", {
+    tmux: process.env.TMUX ?? null,
+    term: process.env.TERM ?? null,
+    termProgram: process.env.TERM_PROGRAM ?? null,
+    termProgramVersion: process.env.TERM_PROGRAM_VERSION ?? null,
+  })
+
+  renderer = await createCliRenderer({
+    exitOnCtrlC: true,
+    targetFps: 30,
+    prependInputHandlers: [
+      (sequence) => {
+        const debugKind = classifyDebugSequence(sequence)
+        if (debugKind) {
+          console.log("[theme-mode-debug] input", {
+            kind: debugKind,
+            sequence: stringifySequence(sequence),
+          })
+        }
+        return false
+      },
+    ],
+  })
+
+  console.log("[theme-mode-debug] renderer created", {
+    initialThemeMode: renderer.themeMode,
+    consoleMode: renderer.consoleMode,
+  })
+
+  const mainContainer = new BoxRenderable(renderer, {
+    id: "main-container",
+    flexGrow: 1,
+    flexDirection: "column",
+    padding: 2,
+  })
+
+  renderer.root.add(mainContainer)
+
+  titleText = new TextRenderable(renderer, {
+    id: "title",
+    content: "Theme Mode Monitor",
+    bold: true,
+    fg: parseColor("#6BCF7F"),
+    marginBottom: 2,
+  })
+
+  themeText = new TextRenderable(renderer, {
+    id: "theme-display",
+    content: "Detecting...",
+    bold: true,
+    marginBottom: 1,
+  })
+
+  statusText = new TextRenderable(renderer, {
+    id: "status",
+    content: "Waiting for theme detection...",
+    marginBottom: 2,
+  })
+
+  eventCountText = new TextRenderable(renderer, {
+    id: "event-count",
+    content: "theme_mode events: 0",
+    marginBottom: 2,
+  })
+
+  firstDrawText = new TextRenderable(renderer, {
+    id: "first-draw",
+    content: "time to first draw: pending",
+    marginBottom: 2,
+  })
+
+  waitForThemeModeText = new TextRenderable(renderer, {
+    id: "wait-for-theme-mode",
+    content: "waitForThemeMode: pending",
+    marginBottom: 2,
+  })
+
+  historyText = new TextRenderable(renderer, {
+    id: "history",
+    content: "updateThemeDisplay history:\n(none)",
+    marginBottom: 2,
+  })
+
+  helpText = new TextRenderable(renderer, {
+    id: "help",
+    content:
+      "Press ` to toggle the renderer console. Press Ctrl+C to exit. Try switching your terminal's light/dark theme to see updates.",
+    fg: parseColor("#888888"),
+  })
+
+  mainContainer.add(titleText)
+  mainContainer.add(themeText)
+  mainContainer.add(statusText)
+  mainContainer.add(eventCountText)
+  mainContainer.add(firstDrawText)
+  mainContainer.add(waitForThemeModeText)
+  mainContainer.add(historyText)
+  mainContainer.add(helpText)
+
+  renderer.keyInput.on("keypress", (key: KeyEvent) => {
+    if (key.name === "`" || key.name === '"') {
+      console.log("[theme-mode-debug] toggling console", {
+        key: key.name,
+        ctrl: key.ctrl,
+        meta: key.meta,
+        shift: key.shift,
+      })
+      renderer?.console.toggle()
+    }
+  })
+
+  // Listen for theme mode changes from the terminal
+  renderer.on("theme_mode", () => {
+    themeModeEventCount++
+    console.log("[theme-mode-debug] theme_mode event", {
+      count: themeModeEventCount,
+      themeMode: renderer?.themeMode ?? null,
+    })
+    updateThemeDisplay()
+  })
+
+  waitForThemeModeStartedAt = performance.now()
+  console.log("[theme-mode-debug] waiting for theme mode")
+  const resolvedThemeMode = await renderer.waitForThemeMode()
+  waitForThemeModeResolvedMs = performance.now() - waitForThemeModeStartedAt
+  waitForThemeModeResolvedValue = resolvedThemeMode
+  console.log("[theme-mode-debug] waitForThemeMode resolved", {
+    resolvedThemeMode,
+    waitForThemeModeResolvedMs,
+  })
+
+  updateThemeDisplay()
+
+  const handleFirstDraw = async () => {
+    if (!renderer || !firstDrawText || timeToFirstDrawMs !== null) {
+      return
+    }
+
+    timeToFirstDrawMs = performance.now() - firstDrawStartedAt
+    console.log("[theme-mode-debug] first draw", { timeToFirstDrawMs })
+    renderer.removeFrameCallback(handleFirstDraw)
+    updateThemeDisplay()
+  }
+
+  renderer.setFrameCallback(handleFirstDraw)
+
+  renderer.requestRender()
+}
+
+main().catch((err) => {
+  console.error("Error:", err)
+  process.exit(1)
+})

package/docs/development.md

@@ -0,0 +1,144 @@
+# 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/examples
+bun run dev
+```
+
+## Testing
+
+```bash
+# Build native dependencies first
+bun run build
+
+# 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 `@opentui/react` and React dependencies
+- `--solid` - Also link `@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: `@opentui/core`, `@opentui/solid`, `@opentui/react`
+- Peer dependencies: `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/package.json

@@ -0,0 +1,102 @@
+{
+  "name": "@xincli/opentui-core",
+  "description": "XINCLI fork of OpenTUI core — with Android/Termux support via @xincli/opentui-core-android-*",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bd-loser/opentui",
+    "directory": "packages/core"
+  },
+  "types": "src/index.ts",
+  "module": "src/index.ts",
+  "main": "src/index.ts",
+  "version": "0.4.6",
+  "type": "module",
+  "scripts": {
+    "build": "bun run build:native && bun run build:lib",
+    "build:dev": "bun run build:native:dev && bun run build:lib",
+    "build:lib": "bun scripts/build.ts --lib",
+    "build:native": "bun scripts/build.ts --native",
+    "build:native:dev": "bun scripts/build.ts --native --dev",
+    "test:native": "cd src/zig && zig build test --summary all",
+    "bench:native": "cd src/zig && zig build bench -Dbench-optimize=ReleaseFast --",
+    "bench:layout": "bun src/benchmark/layout-benchmark.ts",
+    "bench:box-draw": "bun src/benchmark/box-draw-benchmark.ts",
+    "bench:render-traversal": "bun src/benchmark/render-traversal-benchmark.ts",
+    "bench:text-table": "bun src/benchmark/text-table-benchmark.ts",
+    "bench:ts": "bun src/benchmark/native-span-feed-benchmark.ts --suite=quick --json=src/benchmark/latest-quick-bench-run.json && bun src/benchmark/native-span-feed-benchmark.ts --suite=default --json=src/benchmark/latest-default-bench-run.json && bun src/benchmark/native-span-feed-benchmark.ts --suite=large --json=src/benchmark/latest-large-bench-run.json && bun src/benchmark/native-span-feed-benchmark.ts --suite=all --json=src/benchmark/latest-all-bench-run.json && bun src/benchmark/native-span-feed-async-benchmark.ts --json=src/benchmark/latest-async-bench-run.json",
+    "publish": "bun scripts/publish.ts",
+    "test:dist": "bun scripts/dist-test.ts",
+    "test:js": "bun test",
+    "test:js:node": "bun scripts/test-node.ts",
+    "test": "bun run test:native && bun run test:js"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@opentui/keymap": "workspace:*",
+    "@types/bun": "latest",
+    "@types/node": "^24.0.0",
+    "commander": "^13.1.0",
+    "typescript": "^5",
+    "web-tree-sitter": "0.25.10"
+  },
+  "dependencies": {
+    "bun-ffi-structs": "0.2.4",
+    "diff": "9.0.0",
+    "marked": "17.0.1",
+    "string-width": "7.2.0",
+    "strip-ansi": "7.1.2"
+  },
+  "peerDependencies": {
+    "web-tree-sitter": "0.25.10"
+  },
+  "optionalDependencies": {
+    "@opentui/core-darwin-x64": "0.4.3",
+    "@opentui/core-darwin-arm64": "0.4.3",
+    "@opentui/core-linux-x64": "0.4.3",
+    "@opentui/core-linux-arm64": "0.4.3",
+    "@opentui/core-win32-x64": "0.4.3",
+    "@opentui/core-win32-arm64": "0.4.3",
+    "@opentui/core-linux-x64-musl": "0.4.3",
+    "@opentui/core-linux-arm64-musl": "0.4.3",
+    "@xincli/opentui-core-android-arm64": "0.4.5",
+    "@xincli/opentui-core-android-arm": "0.4.5",
+    "@xincli/opentui-core-android-x64": "0.4.5"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
+    },
+    "./testing": {
+      "types": "./src/testing.ts",
+      "import": "./src/testing.ts"
+    },
+    "./runtime-plugin": {
+      "types": "./src/runtime-plugin.ts",
+      "import": "./src/runtime-plugin.ts"
+    },
+    "./runtime-plugin-support": {
+      "types": "./src/runtime-plugin-support.ts",
+      "import": "./src/runtime-plugin-support.ts"
+    },
+    "./runtime-plugin-support/configure": {
+      "types": "./src/runtime-plugin-support-configure.ts",
+      "import": "./src/runtime-plugin-support-configure.ts"
+    },
+    "./yoga": {
+      "types": "./src/yoga.ts",
+      "import": "./src/yoga.ts"
+    },
+    "./tree-sitter/update-assets": {
+      "types": "./src/lib/tree-sitter/update-assets.ts",
+      "import": "./src/lib/tree-sitter/update-assets.ts"
+    },
+    "./parser.worker": {
+      "types": "./src/lib/tree-sitter/parser.worker.ts",
+      "import": "./src/lib/tree-sitter/parser.worker.ts"
+    }
+  },
+  "engines": {
+    "bun": ">=1.3.0"
+  }
+}