@xincli/opentui-core 0.4.6

package/src/lib/styled-text.ts

@@ -0,0 +1,178 @@
+import type { TextRenderable } from "../renderables/Text.js"
+import type { TextBuffer, TextChunk } from "../text-buffer.js"
+import { createTextAttributes } from "../utils.js"
+import { parseColor, type ColorInput } from "./RGBA.js"
+
+const BrandedStyledText: unique symbol = Symbol.for("@opentui/core/StyledText")
+
+export type Color = ColorInput
+
+export interface StyleAttrs {
+  fg?: Color
+  bg?: Color
+  bold?: boolean
+  italic?: boolean
+  underline?: boolean
+  strikethrough?: boolean
+  dim?: boolean
+  reverse?: boolean
+  blink?: boolean
+}
+
+export function isStyledText(obj: any): obj is StyledText {
+  return obj && obj[BrandedStyledText]
+}
+
+export class StyledText {
+  [BrandedStyledText] = true
+
+  public chunks: TextChunk[]
+
+  constructor(chunks: TextChunk[]) {
+    this.chunks = chunks
+  }
+}
+
+export function stringToStyledText(content: string): StyledText {
+  const chunk = {
+    __isChunk: true as const,
+    text: content,
+  }
+  return new StyledText([chunk])
+}
+
+export type StylableInput = string | number | boolean | TextChunk
+
+function applyStyle(input: StylableInput, style: StyleAttrs): TextChunk {
+  if (typeof input === "object" && "__isChunk" in input) {
+    const existingChunk = input as TextChunk
+
+    const fg = style.fg ? parseColor(style.fg) : existingChunk.fg
+    const bg = style.bg ? parseColor(style.bg) : existingChunk.bg
+
+    const newAttrs = createTextAttributes(style)
+    const mergedAttrs = existingChunk.attributes ? existingChunk.attributes | newAttrs : newAttrs
+
+    return {
+      __isChunk: true,
+      text: existingChunk.text,
+      fg,
+      bg,
+      attributes: mergedAttrs,
+      link: existingChunk.link,
+    }
+  } else {
+    const plainTextStr = String(input)
+    const fg = style.fg ? parseColor(style.fg) : undefined
+    const bg = style.bg ? parseColor(style.bg) : undefined
+    const attributes = createTextAttributes(style)
+
+    return {
+      __isChunk: true,
+      text: plainTextStr,
+      fg,
+      bg,
+      attributes,
+    }
+  }
+}
+
+// Color functions
+export const black = (input: StylableInput): TextChunk => applyStyle(input, { fg: "black" })
+export const red = (input: StylableInput): TextChunk => applyStyle(input, { fg: "red" })
+export const green = (input: StylableInput): TextChunk => applyStyle(input, { fg: "green" })
+export const yellow = (input: StylableInput): TextChunk => applyStyle(input, { fg: "yellow" })
+export const blue = (input: StylableInput): TextChunk => applyStyle(input, { fg: "blue" })
+export const magenta = (input: StylableInput): TextChunk => applyStyle(input, { fg: "magenta" })
+export const cyan = (input: StylableInput): TextChunk => applyStyle(input, { fg: "cyan" })
+export const white = (input: StylableInput): TextChunk => applyStyle(input, { fg: "white" })
+
+// Bright color functions
+export const brightBlack = (input: StylableInput): TextChunk => applyStyle(input, { fg: "brightBlack" })
+export const brightRed = (input: StylableInput): TextChunk => applyStyle(input, { fg: "brightRed" })
+export const brightGreen = (input: StylableInput): TextChunk => applyStyle(input, { fg: "brightGreen" })
+export const brightYellow = (input: StylableInput): TextChunk => applyStyle(input, { fg: "brightYellow" })
+export const brightBlue = (input: StylableInput): TextChunk => applyStyle(input, { fg: "brightBlue" })
+export const brightMagenta = (input: StylableInput): TextChunk => applyStyle(input, { fg: "brightMagenta" })
+export const brightCyan = (input: StylableInput): TextChunk => applyStyle(input, { fg: "brightCyan" })
+export const brightWhite = (input: StylableInput): TextChunk => applyStyle(input, { fg: "brightWhite" })
+
+// Background color functions
+export const bgBlack = (input: StylableInput): TextChunk => applyStyle(input, { bg: "black" })
+export const bgRed = (input: StylableInput): TextChunk => applyStyle(input, { bg: "red" })
+export const bgGreen = (input: StylableInput): TextChunk => applyStyle(input, { bg: "green" })
+export const bgYellow = (input: StylableInput): TextChunk => applyStyle(input, { bg: "yellow" })
+export const bgBlue = (input: StylableInput): TextChunk => applyStyle(input, { bg: "blue" })
+export const bgMagenta = (input: StylableInput): TextChunk => applyStyle(input, { bg: "magenta" })
+export const bgCyan = (input: StylableInput): TextChunk => applyStyle(input, { bg: "cyan" })
+export const bgWhite = (input: StylableInput): TextChunk => applyStyle(input, { bg: "white" })
+
+// Style functions
+export const bold = (input: StylableInput): TextChunk => applyStyle(input, { bold: true })
+export const italic = (input: StylableInput): TextChunk => applyStyle(input, { italic: true })
+export const underline = (input: StylableInput): TextChunk => applyStyle(input, { underline: true })
+export const strikethrough = (input: StylableInput): TextChunk => applyStyle(input, { strikethrough: true })
+export const dim = (input: StylableInput): TextChunk => applyStyle(input, { dim: true })
+export const reverse = (input: StylableInput): TextChunk => applyStyle(input, { reverse: true })
+export const blink = (input: StylableInput): TextChunk => applyStyle(input, { blink: true })
+
+// Custom color functions
+export const fg =
+  (color: Color) =>
+  (input: StylableInput): TextChunk =>
+    applyStyle(input, { fg: color })
+export const bg =
+  (color: Color) =>
+  (input: StylableInput): TextChunk =>
+    applyStyle(input, { bg: color })
+
+export const link =
+  (url: string) =>
+  (input: StylableInput): TextChunk => {
+    const chunk =
+      typeof input === "object" && "__isChunk" in input
+        ? (input as TextChunk)
+        : {
+            __isChunk: true as const,
+            text: String(input),
+          }
+
+    return {
+      ...chunk,
+      link: { url },
+    }
+  }
+
+/**
+ * Template literal handler for styled text (non-cached version).
+ * Returns a StyledText object containing chunks of text with optional styles.
+ */
+export function t(strings: TemplateStringsArray, ...values: StylableInput[]): StyledText {
+  const chunks: TextChunk[] = []
+
+  for (let i = 0; i < strings.length; i++) {
+    const raw = strings[i]
+
+    if (raw) {
+      chunks.push({
+        __isChunk: true,
+        text: raw,
+        attributes: 0,
+      })
+    }
+
+    const val = values[i]
+    if (typeof val === "object" && "__isChunk" in val) {
+      chunks.push(val as TextChunk)
+    } else if (val !== undefined) {
+      const plainTextStr = String(val)
+      chunks.push({
+        __isChunk: true,
+        text: plainTextStr,
+        attributes: 0,
+      })
+    }
+  }
+
+  return new StyledText(chunks)
+}

package/src/lib/terminal-capability-detection.test.ts

@@ -0,0 +1,226 @@
+import { test, expect, describe } from "bun:test"
+import {
+  isCapabilityResponse,
+  isPixelResolutionResponse,
+  parsePixelResolution,
+} from "./terminal-capability-detection.js"
+
+describe("isCapabilityResponse", () => {
+  test("detects DECRPM responses", () => {
+    expect(isCapabilityResponse("\x1b[?1016;2$y")).toBe(true)
+    expect(isCapabilityResponse("\x1b[?2027;0$y")).toBe(true)
+    expect(isCapabilityResponse("\x1b[?2031;2$y")).toBe(true)
+    expect(isCapabilityResponse("\x1b[?1004;1$y")).toBe(true)
+    expect(isCapabilityResponse("\x1b[?2026;2$y")).toBe(true)
+    expect(isCapabilityResponse("\x1b[?2004;2$y")).toBe(true)
+  })
+
+  test("detects CPR responses for width detection", () => {
+    expect(isCapabilityResponse("\x1b[1;2R")).toBe(true) // explicit width
+    expect(isCapabilityResponse("\x1b[1;3R")).toBe(true) // scaled text
+  })
+
+  test("does not detect regular CPR responses as capabilities", () => {
+    // Regular cursor position reports are NOT capabilities
+    expect(isCapabilityResponse("\x1b[10;5R")).toBe(false)
+    expect(isCapabilityResponse("\x1b[20;30R")).toBe(false)
+  })
+
+  test("detects XTVersion responses", () => {
+    expect(isCapabilityResponse("\x1bP>|kitty(0.40.1)\x1b\\")).toBe(true)
+    expect(isCapabilityResponse("\x1bP>|ghostty 1.1.3\x1b\\")).toBe(true)
+    expect(isCapabilityResponse("\x1bP>|tmux 3.5a\x1b\\")).toBe(true)
+  })
+
+  test("detects XTGETTCAP Ms responses", () => {
+    expect(isCapabilityResponse("\x1bP1+r4d73=2570312573\x1b\\")).toBe(true)
+    expect(isCapabilityResponse("\x1bP1+r4d73\x1b\\")).toBe(true)
+    expect(isCapabilityResponse("\x1bP1+r4d73=\x1b\\")).toBe(true)
+    expect(isCapabilityResponse("\x1bP0+r\x1b\\")).toBe(true)
+    expect(isCapabilityResponse("\x1bP0+r4D73\x1b\\")).toBe(true)
+    expect(isCapabilityResponse("\x1bP1+r544e=787465726d\x1b\\")).toBe(false)
+    expect(isCapabilityResponse("\x1bP1+r4d73=abc\x1b\\")).toBe(true)
+    expect(isCapabilityResponse("\x1bP1+r4d73=zz\x1b\\")).toBe(true)
+  })
+
+  test("detects Kitty graphics responses", () => {
+    expect(isCapabilityResponse("\x1b_Gi=1;OK\x1b\\")).toBe(true)
+    expect(isCapabilityResponse("\x1b_Gi=1;EINVAL:Zero width/height not allowed\x1b\\")).toBe(true)
+  })
+
+  test("detects DA1 (Device Attributes) responses", () => {
+    expect(isCapabilityResponse("\x1b[?62;c")).toBe(true)
+    expect(isCapabilityResponse("\x1b[?62;22c")).toBe(true)
+    expect(isCapabilityResponse("\x1b[?1;2;4c")).toBe(true)
+    expect(isCapabilityResponse("\x1b[?6c")).toBe(true)
+  })
+
+  test("detects Kitty keyboard query responses", () => {
+    expect(isCapabilityResponse("\x1b[?0u")).toBe(true)
+    expect(isCapabilityResponse("\x1b[?1u")).toBe(true)
+    expect(isCapabilityResponse("\x1b[?31u")).toBe(true)
+  })
+
+  test("detects notification capability responses", () => {
+    expect(isCapabilityResponse("\x1b]99;i=opentui-notifications:p=?;p=title,body\x1b\\")).toBe(true)
+    expect(isCapabilityResponse("\x1b]99;i=opentui-notifications:p=?;p=title,body\x07")).toBe(true)
+    expect(isCapabilityResponse("\x1b]1337;Capabilities=T2NoH\x1b\\")).toBe(true)
+  })
+
+  test("does not detect regular keypresses", () => {
+    expect(isCapabilityResponse("a")).toBe(false)
+    expect(isCapabilityResponse("A")).toBe(false)
+    expect(isCapabilityResponse("\x1b")).toBe(false)
+    expect(isCapabilityResponse("\x1ba")).toBe(false)
+  })
+
+  test("does not detect arrow keys", () => {
+    expect(isCapabilityResponse("\x1b[A")).toBe(false)
+    expect(isCapabilityResponse("\x1b[B")).toBe(false)
+    expect(isCapabilityResponse("\x1b[C")).toBe(false)
+    expect(isCapabilityResponse("\x1b[D")).toBe(false)
+  })
+
+  test("does not detect function keys", () => {
+    expect(isCapabilityResponse("\x1bOP")).toBe(false)
+    expect(isCapabilityResponse("\x1b[11~")).toBe(false)
+    expect(isCapabilityResponse("\x1b[24~")).toBe(false)
+  })
+
+  test("does not detect modified arrow keys", () => {
+    expect(isCapabilityResponse("\x1b[1;2A")).toBe(false)
+    expect(isCapabilityResponse("\x1b[1;5C")).toBe(false)
+  })
+
+  test("does not detect mouse sequences", () => {
+    expect(isCapabilityResponse("\x1b[<35;20;5m")).toBe(false)
+    expect(isCapabilityResponse("\x1b[<0;10;10M")).toBe(false)
+  })
+
+  test("does not detect arbitrary OSC sequences as capabilities", () => {
+    expect(isCapabilityResponse("\x1b]9;hello\x1b\\")).toBe(false)
+    expect(isCapabilityResponse("\x1b]777;notify;title;body\x1b\\")).toBe(false)
+    expect(isCapabilityResponse("\x1b]99;i=other:p=?;p=title\x1b\\")).toBe(false)
+  })
+})
+
+describe("isPixelResolutionResponse", () => {
+  test("detects pixel resolution responses", () => {
+    expect(isPixelResolutionResponse("\x1b[4;720;1280t")).toBe(true)
+    expect(isPixelResolutionResponse("\x1b[4;1080;1920t")).toBe(true)
+    expect(isPixelResolutionResponse("\x1b[4;0;0t")).toBe(true)
+  })
+
+  test("does not detect other sequences", () => {
+    expect(isPixelResolutionResponse("a")).toBe(false)
+    expect(isPixelResolutionResponse("\x1b[A")).toBe(false)
+    expect(isPixelResolutionResponse("\x1b[?1016;2$y")).toBe(false)
+  })
+})
+
+describe("parsePixelResolution", () => {
+  test("parses valid pixel resolution responses", () => {
+    expect(parsePixelResolution("\x1b[4;720;1280t")).toEqual({ width: 1280, height: 720 })
+    expect(parsePixelResolution("\x1b[4;1080;1920t")).toEqual({ width: 1920, height: 1080 })
+    expect(parsePixelResolution("\x1b[4;0;0t")).toEqual({ width: 0, height: 0 })
+  })
+
+  test("returns null for invalid sequences", () => {
+    expect(parsePixelResolution("a")).toBeNull()
+    expect(parsePixelResolution("\x1b[A")).toBeNull()
+    expect(parsePixelResolution("\x1b[?1016;2$y")).toBeNull()
+  })
+})
+
+describe("real-world terminal capability sequences", () => {
+  test("kitty terminal full response - individual sequences", () => {
+    // Should detect multiple capability sequences
+    expect(isCapabilityResponse("\x1b[?1016;2$y")).toBe(true)
+    expect(isCapabilityResponse("\x1b[?2027;0$y")).toBe(true)
+    expect(isCapabilityResponse("\x1b[1;2R")).toBe(true)
+    expect(isCapabilityResponse("\x1b[1;3R")).toBe(true)
+    expect(isCapabilityResponse("\x1bP>|kitty(0.40.1)\x1b\\")).toBe(true)
+    expect(isCapabilityResponse("\x1b_Gi=1;EINVAL:Zero width/height not allowed\x1b\\")).toBe(true)
+    expect(isCapabilityResponse("\x1b[?62;c")).toBe(true)
+  })
+
+  test("ghostty terminal response - individual sequences", () => {
+    expect(isCapabilityResponse("\x1bP>|ghostty 1.1.3\x1b\\")).toBe(true)
+    expect(isCapabilityResponse("\x1b_Gi=1;OK\x1b\\")).toBe(true)
+    expect(isCapabilityResponse("\x1b[?62;22c")).toBe(true)
+  })
+
+  test("alacritty terminal response - individual sequences", () => {
+    expect(isCapabilityResponse("\x1b[?1016;0$y")).toBe(true)
+    expect(isCapabilityResponse("\x1b[?6c")).toBe(true)
+  })
+
+  test("vscode terminal minimal response", () => {
+    expect(isCapabilityResponse("\x1b[?1016;2$y")).toBe(true)
+  })
+})
+
+describe("renderer capabilities event", () => {
+  /**
+   * The renderer emits "capabilities" event each time a capability response is processed.
+   * This happens multiple times at startup because the terminal responds to multiple queries:
+   * - DECRPM queries (sgr_pixels, unicode, color_scheme, focus, bracketed_paste, sync)
+   * - CPR queries for width detection (explicit_width, scaled_text)
+   * - XTVersion (terminal name/version, kitty detection)
+   * - Kitty keyboard query response
+   *
+   * Each response arrives async and triggers the event, so consumers should expect
+   * multiple emissions and handle them reactively.
+   */
+  test("kitty terminal emits capabilities event for each response", async () => {
+    const { createTestRenderer } = await import("../testing/test-renderer.js")
+    const { renderer } = await createTestRenderer({})
+
+    const events: any[] = []
+    renderer.on("capabilities", (caps) => events.push({ ...caps }))
+
+    // Simulate all 10 Kitty capability responses (as they arrive separately)
+    const kittyResponses = [
+      "\x1b[?1016;2$y", // 1. sgr_pixels
+      "\x1b[?2027;0$y", // 2. unicode query
+      "\x1b[?2031;2$y", // 3. color_scheme_updates
+      "\x1b[?1004;2$y", // 4. focus_tracking
+      "\x1b[?2004;2$y", // 5. bracketed_paste
+      "\x1b[?2026;2$y", // 6. sync
+      "\x1b[1;2R", // 7. explicit_width (CPR)
+      "\x1b[1;3R", // 8. scaled_text (CPR)
+      "\x1bP>|kitty(0.42.2)\x1b\\", // 9. xtversion (triggers kitty detection)
+      "\x1b[?0u", // 10. kitty keyboard query
+    ]
+
+    for (const response of kittyResponses) {
+      renderer.stdin.emit("data", Buffer.from(response))
+      await new Promise((resolve) => setTimeout(resolve, 10))
+    }
+
+    // Should have received 10 capability events
+    expect(events.length).toBe(10)
+
+    // First event: sgr_pixels detected
+    expect(events[0].sgr_pixels).toBe(true)
+
+    // After xtversion (event 9): kitty_keyboard should be true
+    expect(events[8].kitty_keyboard).toBe(true)
+    expect(events[8].kitty_graphics).toBe(true)
+    expect(events[8].notifications).toBe(true)
+    expect(events[8].terminal.name).toBe("kitty")
+    expect(events[8].terminal.version).toBe("0.42.2")
+
+    // Final state should have all kitty capabilities
+    const finalCaps = events[9]
+    expect(finalCaps.kitty_keyboard).toBe(true)
+    expect(finalCaps.sgr_pixels).toBe(true)
+    expect(finalCaps.color_scheme_updates).toBe(true)
+    expect(finalCaps.focus_tracking).toBe(true)
+    expect(finalCaps.sync).toBe(true)
+    expect(finalCaps.explicit_width).toBe(true)
+    expect(finalCaps.scaled_text).toBe(true)
+
+    renderer.destroy()
+  })
+})

package/src/lib/terminal-capability-detection.ts

@@ -0,0 +1,98 @@
+/**
+ * Terminal capability response detection utilities.
+ *
+ * Detects various terminal capability response sequences:
+ * - DECRPM (DEC Request Mode): ESC[?...;N$y where N is 0,1,2,3,4
+ * - CPR (Cursor Position Report): ESC[row;colR (used for width detection)
+ * - XTVersion: ESC P >| ... ESC \
+ * - Kitty Graphics: ESC _ G ... ESC \
+ * - Kitty Keyboard Query: ESC[?Nu where N is 0,1,2,etc
+ * - DA1 (Device Attributes): ESC[?...c
+ * - Pixel Resolution: ESC[4;height;widtht
+ * - OSC 99 notification capability query response
+ * - iTerm2 OSC 1337 feature-reporting response
+ */
+
+/**
+ * Check if a sequence is a terminal capability response.
+ * Returns true if the sequence matches any known capability response pattern.
+ */
+export function isCapabilityResponse(sequence: string): boolean {
+  // DECRPM: ESC[?digits;digits$y
+  if (/\x1b\[\?\d+(?:;\d+)*\$y/.test(sequence)) {
+    return true
+  }
+
+  // CPR for explicit width/scaled text detection: ESC[1;NR where N >= 2
+  // The column number tells us how many characters were rendered with width annotations
+  // ESC[1;1R means no width support (cursor didn't move)
+  // ESC[1;2R or higher means width support (cursor moved after rendering)
+  // We accept any column >= 2 to handle cases where cursor wasn't at exact home position
+  if (/\x1b\[1;(?!1R)\d+R/.test(sequence)) {
+    return true
+  }
+
+  // XTVersion: ESC P >| ... ESC \
+  if (/\x1bP>\|[\s\S]*?\x1b\\/.test(sequence)) {
+    return true
+  }
+
+  // XTGETTCAP Ms: consume replies to our query here; native parsing separately
+  // validates whether a positive value is sufficient evidence of support.
+  if (/\x1bP(?:1\+r4d73(?:=[^\x1b]*)?|0\+r(?:4d73)?)\x1b\\/i.test(sequence)) {
+    return true
+  }
+
+  // Kitty graphics response: ESC _ G ... ESC \
+  // Matches any graphics response including OK, errors, etc.
+  // This is for filtering capability responses from user input
+  if (/\x1b_G[\s\S]*?\x1b\\/.test(sequence)) {
+    return true
+  }
+
+  // Kitty keyboard query response: ESC[?Nu or ESC[?N;Mu (progressive enhancement)
+  if (/\x1b\[\?\d+(?:;\d+)?u/.test(sequence)) {
+    return true
+  }
+
+  // DA1 (Device Attributes): ESC[?...c
+  if (/\x1b\[\?[0-9;]*c/.test(sequence)) {
+    return true
+  }
+
+  // Kitty desktop notification capability query response.
+  if (/\x1b\]99;[^\x07\x1b]*i=opentui-notifications[^\x07\x1b]*p=\?[\s\S]*?(?:\x07|\x1b\\)/.test(sequence)) {
+    return true
+  }
+
+  // iTerm2 feature reporting response. The native parser decides whether the
+  // feature string contains the Notifications feature code.
+  if (/\x1b\]1337;Capabilities=[\s\S]*?(?:\x07|\x1b\\)/.test(sequence)) {
+    return true
+  }
+
+  return false
+}
+
+/**
+ * Check if a sequence is a pixel resolution response.
+ * Format: ESC[4;height;widtht
+ */
+export function isPixelResolutionResponse(sequence: string): boolean {
+  return /\x1b\[4;\d+;\d+t/.test(sequence)
+}
+
+/**
+ * Parse pixel resolution from response sequence.
+ * Returns { width, height } or null if not a valid resolution response.
+ */
+export function parsePixelResolution(sequence: string): { width: number; height: number } | null {
+  const match = sequence.match(/\x1b\[4;(\d+);(\d+)t/)
+  if (match) {
+    return {
+      width: parseInt(match[2]),
+      height: parseInt(match[1]),
+    }
+  }
+  return null
+}