@xincli/opentui-core 0.4.6

package/src/lib/terminal-palette.ts

@@ -0,0 +1,441 @@
+import { RGBA, DEFAULT_BACKGROUND_RGB, DEFAULT_FOREGROUND_RGB, ansi256IndexToRgb } from "./RGBA.js"
+import { SystemClock, type Clock, type TimerHandle } from "./clock.js"
+import { env, registerEnvVar } from "./env.js"
+
+type Hex = string | null
+
+const SYSTEM_CLOCK = new SystemClock()
+
+registerEnvVar({
+  name: "OTUI_PALETTE_IDLE_TIMEOUT_MS",
+  description: "Milliseconds of silence after palette queries before using fallback colors.",
+  type: "number",
+  default: 300,
+})
+
+const OSC4_RESPONSE =
+  /\x1b]4;(\d+);(?:(?:rgb:)([0-9a-fA-F]+)\/([0-9a-fA-F]+)\/([0-9a-fA-F]+)|#([0-9a-fA-F]{6}))(?:\x07|\x1b\\)/g
+
+const OSC_SPECIAL_RESPONSE =
+  /\x1b](\d+);(?:(?:rgb:)([0-9a-fA-F]+)\/([0-9a-fA-F]+)\/([0-9a-fA-F]+)|#([0-9a-fA-F]{6}))(?:\x07|\x1b\\)/g
+
+export type WriteFunction = (data: string | Buffer) => boolean
+
+export interface TerminalColors {
+  palette: Hex[]
+  defaultForeground: Hex
+  defaultBackground: Hex
+  cursorColor: Hex
+  mouseForeground: Hex
+  mouseBackground: Hex
+  tekForeground: Hex
+  tekBackground: Hex
+  highlightBackground: Hex
+  highlightForeground: Hex
+}
+
+export interface GetPaletteOptions {
+  timeout?: number
+  size?: number
+}
+
+export interface TerminalPaletteDetector {
+  detect(options?: GetPaletteOptions): Promise<TerminalColors>
+  detectOSCSupport(timeoutMs?: number): Promise<boolean>
+  cleanup(): void
+}
+
+export interface NormalizedTerminalPalette {
+  palette: RGBA[]
+  defaultForeground: RGBA
+  defaultBackground: RGBA
+}
+
+export type OscSubscriptionSource = {
+  subscribeOsc(handler: (sequence: string) => void): () => void
+}
+
+export interface TerminalPaletteOptions {
+  stdin: NodeJS.ReadStream
+  stdout: NodeJS.WriteStream
+  writeFn?: WriteFunction
+  isLegacyTmux?: boolean
+  isTmux?: boolean
+  oscSource?: OscSubscriptionSource
+  clock?: Clock
+}
+
+function scaleComponent(comp: string): string {
+  const val = parseInt(comp, 16)
+  const maxIn = (1 << (4 * comp.length)) - 1
+  return Math.round((val / maxIn) * 255)
+    .toString(16)
+    .padStart(2, "0")
+}
+
+function toHex(r?: string, g?: string, b?: string, hex6?: string): string {
+  if (hex6) return `#${hex6.toLowerCase()}`
+  if (r && g && b) return `#${scaleComponent(r)}${scaleComponent(g)}${scaleComponent(b)}`
+  return "#000000"
+}
+
+/**
+ * Wrap OSC sequence for tmux passthrough
+ * tmux requires DCS sequences to pass OSC to the underlying terminal
+ * Format: ESC P tmux; ESC <OSC_SEQUENCE> ESC \
+ */
+function wrapForTmux(osc: string): string {
+  // Replace ESC with ESC ESC for tmux (escape the escape)
+  const escaped = osc.replace(/\x1b/g, "\x1b\x1b")
+  return `\x1bPtmux;${escaped}\x1b\\`
+}
+
+export class TerminalPalette implements TerminalPaletteDetector {
+  private stdin: NodeJS.ReadStream
+  private stdout: NodeJS.WriteStream
+  private writeFn: WriteFunction
+  private activeQuerySessions: Array<() => void> = []
+  private inLegacyTmux: boolean
+  private inTmux: boolean
+  private oscSource?: OscSubscriptionSource
+  private readonly clock: Clock
+
+  constructor(options: TerminalPaletteOptions) {
+    const { stdin, stdout, writeFn, isLegacyTmux, isTmux, oscSource, clock } = options
+
+    this.stdin = stdin
+    this.stdout = stdout
+    this.writeFn = writeFn || ((data: string | Buffer) => stdout.write(data))
+    this.inLegacyTmux = isLegacyTmux ?? false
+    this.inTmux = isTmux ?? this.inLegacyTmux
+    this.oscSource = oscSource
+    this.clock = clock ?? SYSTEM_CLOCK
+  }
+
+  private writeOsc(osc: string, wrapForLegacyTmux = false): boolean {
+    const data = wrapForLegacyTmux && this.inLegacyTmux ? wrapForTmux(osc) : osc
+    return this.writeFn(data)
+  }
+
+  cleanup(): void {
+    for (const cleanupSession of [...this.activeQuerySessions]) {
+      cleanupSession()
+    }
+    this.activeQuerySessions = []
+  }
+
+  private subscribeInput(handler: (chunk: string | Buffer) => void): () => void {
+    if (this.oscSource) {
+      return this.oscSource.subscribeOsc((sequence) => {
+        handler(sequence)
+      })
+    }
+
+    this.stdin.on("data", handler)
+    return () => {
+      this.stdin.removeListener("data", handler)
+    }
+  }
+
+  private createQuerySession() {
+    const timers = new Set<TimerHandle>()
+    const subscriptions = new Set<() => void>()
+    let closed = false
+
+    const cleanup = () => {
+      if (closed) return
+      closed = true
+
+      for (const timer of timers) {
+        this.clock.clearTimeout(timer)
+      }
+      timers.clear()
+
+      for (const unsubscribe of subscriptions) {
+        unsubscribe()
+      }
+      subscriptions.clear()
+
+      const idx = this.activeQuerySessions.indexOf(cleanup)
+      if (idx !== -1) this.activeQuerySessions.splice(idx, 1)
+    }
+
+    this.activeQuerySessions.push(cleanup)
+
+    return {
+      setTimer: (fn: () => void, ms: number): TimerHandle => {
+        const timer = this.clock.setTimeout(fn, ms)
+        timers.add(timer)
+        return timer
+      },
+      resetTimer: (existing: TimerHandle | null, fn: () => void, ms: number): TimerHandle => {
+        if (existing) {
+          this.clock.clearTimeout(existing)
+          timers.delete(existing)
+        }
+
+        const timer = this.clock.setTimeout(fn, ms)
+        timers.add(timer)
+        return timer
+      },
+      subscribeInput: (handler: (chunk: string | Buffer) => void): (() => void) => {
+        const unsubscribe = this.subscribeInput(handler)
+        subscriptions.add(unsubscribe)
+        return () => {
+          if (!subscriptions.has(unsubscribe)) return
+          subscriptions.delete(unsubscribe)
+          unsubscribe()
+        }
+      },
+      cleanup,
+    }
+  }
+
+  async detectOSCSupport(timeoutMs = 300): Promise<boolean> {
+    const out = this.stdout
+
+    if (!out.isTTY || !this.stdin.isTTY) return false
+
+    return new Promise<boolean>((resolve) => {
+      const session = this.createQuerySession()
+      let buffer = ""
+      let settled = false
+
+      const finish = (supported: boolean) => {
+        if (settled) return
+        settled = true
+        session.cleanup()
+        resolve(supported)
+      }
+
+      const onData = (chunk: string | Buffer) => {
+        buffer += chunk.toString()
+        // Reset regex lastIndex before testing due to global flag
+        OSC4_RESPONSE.lastIndex = 0
+        if (OSC4_RESPONSE.test(buffer)) {
+          finish(true)
+        }
+      }
+
+      session.setTimer(() => {
+        finish(false)
+      }, timeoutMs)
+      session.subscribeInput(onData)
+      // Only OSC 4 needs legacy tmux passthrough; tmux routes OSC 4 replies back to the pane.
+      this.writeOsc("\x1b]4;0;?\x07", true)
+    })
+  }
+
+  private async queryPalette(
+    indices: number[],
+    timeoutMs = 1200,
+    idleTimeoutMs = env.OTUI_PALETTE_IDLE_TIMEOUT_MS,
+  ): Promise<Map<number, Hex>> {
+    const out = this.stdout
+    const results = new Map<number, Hex>()
+    indices.forEach((i) => results.set(i, null))
+
+    if (!out.isTTY || !this.stdin.isTTY) {
+      return results
+    }
+
+    return new Promise<Map<number, Hex>>((resolve) => {
+      const session = this.createQuerySession()
+      let buffer = ""
+      let idleTimer: TimerHandle | null = null
+      let settled = false
+
+      const finish = () => {
+        if (settled) return
+        settled = true
+        session.cleanup()
+        resolve(results)
+      }
+
+      const onData = (chunk: string | Buffer) => {
+        buffer += chunk.toString()
+
+        let m: RegExpExecArray | null
+        OSC4_RESPONSE.lastIndex = 0
+        while ((m = OSC4_RESPONSE.exec(buffer))) {
+          const idx = parseInt(m[1], 10)
+          if (results.has(idx)) results.set(idx, toHex(m[2], m[3], m[4], m[5]))
+        }
+
+        if (buffer.length > 8192) buffer = buffer.slice(-4096)
+
+        const done = [...results.values()].filter((v) => v !== null).length
+        if (done === results.size) {
+          finish()
+          return
+        }
+
+        idleTimer = session.resetTimer(idleTimer, finish, idleTimeoutMs)
+      }
+
+      session.setTimer(finish, timeoutMs)
+      session.subscribeInput(onData)
+      // Only OSC 4 needs legacy tmux passthrough; tmux routes OSC 4 replies back to the pane.
+      this.writeOsc(indices.map((i) => `\x1b]4;${i};?\x07`).join(""), true)
+      idleTimer = session.resetTimer(idleTimer, finish, idleTimeoutMs)
+    })
+  }
+
+  private async querySpecialColors(
+    timeoutMs = 1200,
+    idleTimeoutMs = env.OTUI_PALETTE_IDLE_TIMEOUT_MS,
+  ): Promise<Record<number, Hex>> {
+    const out = this.stdout
+    const results: Record<number, Hex> = {
+      10: null,
+      11: null,
+      12: null,
+      13: null,
+      14: null,
+      15: null,
+      16: null,
+      17: null,
+      19: null,
+    }
+    // tmux handles plain OSC 10/11/12 only; it has no OSC 13-17/19 handlers or reply routing.
+    const queries = this.inTmux ? [10, 11, 12] : [10, 11, 12, 13, 14, 15, 16, 17, 19]
+
+    if (!out.isTTY || !this.stdin.isTTY) {
+      return results
+    }
+
+    return new Promise<Record<number, Hex>>((resolve) => {
+      const session = this.createQuerySession()
+      let buffer = ""
+      let idleTimer: TimerHandle | null = null
+      let settled = false
+
+      const finish = () => {
+        if (settled) return
+        settled = true
+        session.cleanup()
+        resolve(results)
+      }
+
+      const onData = (chunk: string | Buffer) => {
+        buffer += chunk.toString()
+        let updated = false
+
+        let m: RegExpExecArray | null
+        OSC_SPECIAL_RESPONSE.lastIndex = 0
+        while ((m = OSC_SPECIAL_RESPONSE.exec(buffer))) {
+          const idx = parseInt(m[1], 10)
+          if (idx in results) {
+            results[idx] = toHex(m[2], m[3], m[4], m[5])
+            updated = true
+          }
+        }
+
+        if (buffer.length > 8192) buffer = buffer.slice(-4096)
+
+        if (queries.every((idx) => results[idx] !== null)) {
+          finish()
+          return
+        }
+
+        if (!updated) return
+
+        idleTimer = session.resetTimer(idleTimer, finish, idleTimeoutMs)
+      }
+
+      session.setTimer(finish, timeoutMs)
+      session.subscribeInput(onData)
+      // OSC 10/11/12 are plain tmux handlers. DCS passthrough does not help other special colors.
+      this.writeOsc(queries.map((idx) => `\x1b]${idx};?\x07`).join(""))
+      idleTimer = session.resetTimer(idleTimer, finish, idleTimeoutMs)
+    })
+  }
+
+  async detect(options?: GetPaletteOptions): Promise<TerminalColors> {
+    const { timeout = 5000, size = 16 } = options || {}
+    const supported = await this.detectOSCSupport()
+
+    if (!supported) {
+      return {
+        palette: Array(size).fill(null),
+        defaultForeground: null,
+        defaultBackground: null,
+        cursorColor: null,
+        mouseForeground: null,
+        mouseBackground: null,
+        tekForeground: null,
+        tekBackground: null,
+        highlightBackground: null,
+        highlightForeground: null,
+      }
+    }
+
+    const indicesToQuery = [...Array(size).keys()]
+    const idleTimeout = env.OTUI_PALETTE_IDLE_TIMEOUT_MS
+    const [paletteResults, specialColors] = await Promise.all([
+      this.queryPalette(indicesToQuery, timeout, idleTimeout),
+      this.querySpecialColors(timeout, idleTimeout),
+    ])
+
+    return {
+      palette: [...Array(size).keys()].map((i) => paletteResults.get(i) ?? null),
+      defaultForeground: specialColors[10],
+      defaultBackground: specialColors[11],
+      cursorColor: specialColors[12],
+      mouseForeground: specialColors[13],
+      mouseBackground: specialColors[14],
+      tekForeground: specialColors[15],
+      tekBackground: specialColors[16],
+      highlightBackground: specialColors[17],
+      highlightForeground: specialColors[19],
+    }
+  }
+}
+
+export function createTerminalPalette(options: TerminalPaletteOptions): TerminalPaletteDetector {
+  return new TerminalPalette(options)
+}
+
+const DEFAULT_FOREGROUND_FALLBACK = RGBA.fromInts(...DEFAULT_FOREGROUND_RGB)
+const DEFAULT_BACKGROUND_FALLBACK = RGBA.fromInts(...DEFAULT_BACKGROUND_RGB)
+
+let fallbackAnsi256Palette: RGBA[] | null = null
+
+function getFallbackAnsi256Palette(): readonly RGBA[] {
+  if (!fallbackAnsi256Palette) {
+    fallbackAnsi256Palette = Array.from({ length: 256 }, (_, index) => {
+      const [r, g, b] = ansi256IndexToRgb(index)
+      return RGBA.fromInts(r, g, b)
+    })
+  }
+
+  return fallbackAnsi256Palette
+}
+
+export function normalizeTerminalPalette(colors?: TerminalColors | null): NormalizedTerminalPalette {
+  const fallbackPalette = getFallbackAnsi256Palette()
+
+  return {
+    palette: Array.from({ length: 256 }, (_, index) => {
+      const detected = colors?.palette[index]
+      return detected ? RGBA.fromHex(detected) : RGBA.clone(fallbackPalette[index])
+    }),
+    defaultForeground: colors?.defaultForeground
+      ? RGBA.fromHex(colors.defaultForeground)
+      : RGBA.clone(DEFAULT_FOREGROUND_FALLBACK),
+    defaultBackground: colors?.defaultBackground
+      ? RGBA.fromHex(colors.defaultBackground)
+      : RGBA.clone(DEFAULT_BACKGROUND_FALLBACK),
+  }
+}
+
+export function buildTerminalPaletteSignature(colors?: TerminalColors | null): string {
+  const normalized = normalizeTerminalPalette(colors)
+  const paletteSignature = normalized.palette.map((color) => color.toInts().join(",")).join(";")
+
+  return [
+    paletteSignature,
+    normalized.defaultForeground.toInts().join(","),
+    normalized.defaultBackground.toInts().join(","),
+  ].join("|")
+}

package/src/lib/tree-sitter/assets/README.md

@@ -0,0 +1,119 @@
+# Tree-sitter Assets
+
+This directory contains downloaded tree-sitter language parsers and highlight queries for the default parsers used by OpenTUI.
+They are included in the repository to avoid downloading them every time the project is built or tests are run.
+
+## Asset Management
+
+Parser definitions are configured in `../parsers-config.ts` for OpenTUI's built-in parser set.
+
+### Update Script
+
+The `update.ts` script downloads parsers and queries from the configured URLs and generates the `../default-parsers.ts` file.
+
+#### Usage
+
+**For OpenTUI Core Development (using default paths):**
+
+```bash
+# Run from this directory
+bun update.ts
+
+# Or from the project root
+bun packages/core/src/lib/tree-sitter/assets/update.ts
+```
+
+**For Application Developers (using custom paths):**
+
+```bash
+# CLI usage with custom paths
+bun update.ts \
+  --config ./my-parsers-config.json \
+  --assets ./src/tree-sitter/assets \
+  --output ./src/tree-sitter/parsers.ts
+
+# Show help
+bun update.ts --help
+```
+
+**Programmatic Usage:**
+
+```typescript
+import { updateAssets } from "@opentui/core/tree-sitter/update-assets"
+
+await updateAssets({
+  configPath: "./my-parsers-config.json",
+  assetsDir: "./src/tree-sitter/assets",
+  outputPath: "./src/tree-sitter/parsers.ts",
+})
+```
+
+#### What it does
+
+1. **Downloads Language Parsers**: Downloads `.wasm` files from GitHub releases
+2. **Downloads Query Files**: Downloads `.scm` highlight query files from repositories
+3. **Combines Queries**: For languages like TypeScript, combines multiple query files (JS base + TS extensions)
+4. **Generates Imports**: Creates a TypeScript file with proper file imports using Bun's `with { type: "file" }` syntax
+
+## Adding New Parsers
+
+### For Application Developers
+
+If you're using OpenTUI in your application and want to add support for additional languages:
+
+#### 1. Create a parsers configuration file
+
+Create a `parsers-config.json` file in your project with the structure:
+
+```json
+{
+  "parsers": [
+    {
+      "filetype": "python",
+      "wasm": "https://github.com/tree-sitter/tree-sitter-python/releases/download/v0.20.4/tree-sitter-python.wasm",
+      "queries": {
+        "highlights": [
+          "https://raw.githubusercontent.com/tree-sitter/tree-sitter-python/refs/heads/master/queries/highlights.scm"
+        ]
+      }
+    }
+  ]
+}
+```
+
+#### 2. Add to your build pipeline
+
+Add the update script to your `package.json`:
+
+```json
+{
+  "scripts": {
+    "prebuild": "bun node_modules/@opentui/core/lib/tree-sitter/update-assets.js --config ./parsers-config.json --assets ./src/parsers --output ./src/parsers.ts",
+    "build": "bun build ./src/index.ts"
+  }
+}
+```
+
+#### 3. Use the generated parsers
+
+```typescript
+import { getTreeSitterClient } from "@opentui/core"
+import { getParsers } from "./parsers"
+
+const client = getTreeSitterClient()
+
+// Register your custom parsers
+for (const parser of getParsers()) {
+  client.addFiletypeParser(parser)
+}
+```
+
+For more information about using Tree-Sitter in your application, see the [Tree-Sitter guide](../../../docs/tree-sitter.md).
+
+### For OpenTUI Core Developers
+
+To add a new default parser to OpenTUI Core:
+
+1. **Update Configuration**: Add the new parser to `../parsers-config.ts`
+2. **Run Update Script**: Execute `bun update.ts` to download assets and regenerate imports
+3. **Commit Generated Assets**: Include the downloaded parser/query files and regenerated `../default-parsers.ts`