@xincli/opentui-core 0.4.6

package/src/lib/objects-in-viewport.ts

@@ -0,0 +1,153 @@
+import type { ViewportBounds } from "../types.js"
+
+interface ViewportObject {
+  screenX: number
+  screenY: number
+  width: number
+  height: number
+  zIndex: number
+}
+
+/**
+ * Returns objects that overlap with the viewport bounds.
+ *
+ * @param viewport - The viewport bounds to check against
+ * @param objects - Array of objects MUST be sorted by screen position (screenY for column, screenX for row direction)
+ * @param direction - Primary scroll direction: "column" (vertical) or "row" (horizontal)
+ * @param padding - Extra padding around viewport to include nearby objects
+ * @param minTriggerSize - Minimum array size to use binary search optimization
+ * @returns Array of visible objects sorted by zIndex
+ *
+ * @remarks
+ * Objects must be pre-sorted by their start screen position (screenY for column direction, screenX for row direction).
+ * Unsorted input will produce incorrect results.
+ */
+export function getObjectsInViewport<T extends ViewportObject>(
+  viewport: ViewportBounds,
+  objects: T[],
+  direction: "row" | "column" = "column",
+  padding: number = 10,
+  minTriggerSize: number = 16,
+): T[] {
+  if (viewport.width <= 0 || viewport.height <= 0) {
+    return []
+  }
+
+  if (objects.length === 0) {
+    return []
+  }
+
+  if (objects.length < minTriggerSize) {
+    return objects
+  }
+
+  const viewportTop = viewport.y - padding
+  const viewportBottom = viewport.y + viewport.height + padding
+  const viewportLeft = viewport.x - padding
+  const viewportRight = viewport.x + viewport.width + padding
+
+  const isRow = direction === "row"
+
+  const children = objects
+  const totalChildren = children.length
+  if (totalChildren === 0) return []
+
+  const vpStart = isRow ? viewportLeft : viewportTop
+  const vpEnd = isRow ? viewportRight : viewportBottom
+
+  // Binary search to find any child that overlaps along the primary axis
+  let lo = 0
+  let hi = totalChildren - 1
+  let candidate = -1
+  while (lo <= hi) {
+    const mid = (lo + hi) >> 1
+    const c = children[mid]
+    const start = isRow ? c.screenX : c.screenY
+    const end = isRow ? c.screenX + c.width : c.screenY + c.height
+
+    if (end < vpStart) {
+      lo = mid + 1
+    } else if (start > vpEnd) {
+      hi = mid - 1
+    } else {
+      candidate = mid
+      break
+    }
+  }
+
+  const visibleChildren: T[] = []
+
+  // If binary search found no candidate, the viewport might be in a gap between objects
+  // Start from the position where the search ended
+  if (candidate === -1) {
+    // Binary search failed to find overlap - viewport is in a gap
+    // We need to check objects before lo for any that extend into the viewport
+    candidate = lo > 0 ? lo - 1 : 0
+  }
+
+  // Expand left to find all objects that overlap the viewport
+  // To handle large objects that start early but extend far, we continue
+  // checking even after finding objects that don't overlap, up to a limit
+  // This handles cases where many small objects sit between a large object and the viewport
+  // Real-world examples: background panels, large images, or spanning containers
+  const maxLookBehind = 50
+  let left = candidate
+  let gapCount = 0
+
+  while (left - 1 >= 0) {
+    const prev = children[left - 1]
+    const prevEnd = isRow ? prev.screenX + prev.width : prev.screenY + prev.height
+
+    if (prevEnd <= vpStart) {
+      gapCount++
+      if (gapCount >= maxLookBehind) {
+        break
+      }
+    } else {
+      gapCount = 0
+    }
+
+    left--
+  }
+
+  // Expand right to find the rightmost overlapping object
+  let right = candidate + 1
+  while (right < totalChildren) {
+    const next = children[right]
+    if ((isRow ? next.screenX : next.screenY) >= vpEnd) break
+    right++
+  }
+
+  // Collect candidates that also overlap on the cross axis
+  for (let i = left; i < right; i++) {
+    const child = children[i]
+    const start = isRow ? child.screenX : child.screenY
+    const end = isRow ? child.screenX + child.width : child.screenY + child.height
+
+    // Check primary axis overlap (optimization: skip objects that don't overlap)
+    if (end <= vpStart) continue
+    if (start >= vpEnd) break
+
+    // Check cross-axis overlap
+    if (isRow) {
+      const childBottom = child.screenY + child.height
+      if (childBottom < viewportTop) continue
+      const childTop = child.screenY
+      if (childTop > viewportBottom) continue
+    } else {
+      const childRight = child.screenX + child.width
+      if (childRight < viewportLeft) continue
+      const childLeft = child.screenX
+      if (childLeft > viewportRight) continue
+    }
+
+    visibleChildren.push(child)
+  }
+
+  // Sort by zIndex
+  if (visibleChildren.length > 1) {
+    visibleChildren.sort((a, b) => (a.zIndex > b.zIndex ? 1 : a.zIndex < b.zIndex ? -1 : 0))
+  }
+
+  return visibleChildren
+}

package/src/lib/output.capture.ts

@@ -0,0 +1,58 @@
+import { Writable } from "stream"
+import { EventEmitter } from "events"
+
+export type CapturedOutput = {
+  stream: "stdout" | "stderr"
+  output: string
+}
+
+export class Capture extends EventEmitter {
+  // TODO: Cache could rather be a buffer to avoid join()?
+  private output: CapturedOutput[] = []
+
+  constructor() {
+    super()
+  }
+
+  get size(): number {
+    return this.output.length
+  }
+
+  write(stream: "stdout" | "stderr", data: string): void {
+    this.output.push({ stream, output: data })
+    this.emit("write", stream, data)
+  }
+
+  claimOutput() {
+    const output = this.output.map((o) => o.output).join("")
+    this.clear()
+    return output
+  }
+
+  private clear(): void {
+    this.output = []
+  }
+}
+
+export class CapturedWritableStream extends Writable {
+  public isTTY: boolean = true
+  public columns: number = process.stdout.columns || 80
+  public rows: number = process.stdout.rows || 24
+
+  constructor(
+    private stream: "stdout" | "stderr",
+    private capture: Capture,
+  ) {
+    super()
+  }
+
+  _write(chunk: any, encoding: BufferEncoding, callback: (error?: Error | null) => void): void {
+    const data = chunk.toString()
+    this.capture.write(this.stream, data)
+    callback()
+  }
+
+  getColorDepth(): number {
+    return process.stdout.getColorDepth?.() || 8
+  }
+}

package/src/lib/parse.keypress-kitty.protocol.test.ts

@@ -0,0 +1,347 @@
+import { describe, expect, test } from "bun:test"
+import { parseKeypress, type ParseKeypressOptions, type ParsedKey } from "./parse.keypress.js"
+
+// This mirrors the upstream protocol tables and expands them into one test
+// per case so missing mappings fail with a name.
+//
+// https://raw.githubusercontent.com/kovidgoyal/kitty/refs/heads/master/docs/keyboard-protocol.rst
+
+const options: ParseKeypressOptions = { useKittyKeyboard: true }
+
+type ExpectedKey = Partial<ParsedKey> & Pick<ParsedKey, "name">
+
+interface KeyCase {
+  title: string
+  sequence: string
+  expected: ExpectedKey
+}
+
+function parse(sequence: string): ParsedKey {
+  const result = parseKeypress(sequence, options)
+  expect(result).not.toBeNull()
+  return result!
+}
+
+function expectKey(sequence: string, expected: ExpectedKey): void {
+  expect(parse(sequence)).toMatchObject(expected)
+}
+
+function defineKeyCases(cases: readonly KeyCase[]): void {
+  for (const { title, sequence, expected } of cases) {
+    test(title, () => {
+      expectKey(sequence, expected)
+    })
+  }
+}
+
+function rangeCases(start: number, names: readonly string[]): Array<[number, string]> {
+  return names.map((name, index) => [start + index, name] as [number, string])
+}
+
+function functionalCase(code: number, name: string): KeyCase {
+  return {
+    title: `CSI ${code}u -> ${name}`,
+    sequence: `\x1b[${code}u`,
+    expected: {
+      name,
+      code: `[${code}u`,
+      eventType: "press",
+      source: "kitty",
+    },
+  }
+}
+
+function legacyAliasCase(sequence: string, name: string): KeyCase {
+  return {
+    title: `legacy ${JSON.stringify(sequence)} -> ${name}`,
+    sequence,
+    expected: {
+      name,
+      eventType: "press",
+    },
+  }
+}
+
+function enhancedAliasCase(sequence: string, name: string): KeyCase {
+  return {
+    title: `enhanced ${JSON.stringify(sequence)} -> ${name}`,
+    sequence,
+    expected: {
+      name,
+      eventType: "press",
+      source: "kitty",
+    },
+  }
+}
+
+function canonicalAliasCase(sequence: string, expected: ExpectedKey): KeyCase {
+  return {
+    title: `canonical ${JSON.stringify(sequence)} -> ${expected.name}`,
+    sequence,
+    expected: {
+      eventType: "press",
+      ...expected,
+    },
+  }
+}
+
+function modifierCase(modifier: number, expected: ExpectedKey): KeyCase {
+  return {
+    title: `modifier ${modifier} -> ${expected.name}`,
+    sequence: `\x1b[97;${modifier}u`,
+    expected: {
+      source: "kitty",
+      ...expected,
+    },
+  }
+}
+
+const numberedFunctionalEntries: Array<[number, string]> = [
+  [27, "escape"],
+  [13, "return"],
+  [9, "tab"],
+  [127, "backspace"],
+  ...rangeCases(57348, [
+    "insert",
+    "delete",
+    "left",
+    "right",
+    "up",
+    "down",
+    "pageup",
+    "pagedown",
+    "home",
+    "end",
+    "capslock",
+    "scrolllock",
+    "numlock",
+    "printscreen",
+    "pause",
+    "menu",
+  ]),
+  ...Array.from({ length: 35 }, (_, index) => [57364 + index, `f${index + 1}`] as [number, string]),
+  ...rangeCases(57399, [
+    "kp0",
+    "kp1",
+    "kp2",
+    "kp3",
+    "kp4",
+    "kp5",
+    "kp6",
+    "kp7",
+    "kp8",
+    "kp9",
+    "kpdecimal",
+    "kpdivide",
+    "kpmultiply",
+    "kpminus",
+    "kpplus",
+    "kpenter",
+    "kpequal",
+    "kpseparator",
+    "kpleft",
+    "kpright",
+    "kpup",
+    "kpdown",
+    "kppageup",
+    "kppagedown",
+    "kphome",
+    "kpend",
+    "kpinsert",
+    "kpdelete",
+    "clear",
+  ]),
+  ...rangeCases(57428, [
+    "mediaplay",
+    "mediapause",
+    "mediaplaypause",
+    "mediareverse",
+    "mediastop",
+    "mediafastforward",
+    "mediarewind",
+    "medianext",
+    "mediaprev",
+    "mediarecord",
+  ]),
+  ...rangeCases(57438, ["volumedown", "volumeup", "mute"]),
+  ...rangeCases(57441, [
+    "leftshift",
+    "leftctrl",
+    "leftalt",
+    "leftsuper",
+    "lefthyper",
+    "leftmeta",
+    "rightshift",
+    "rightctrl",
+    "rightalt",
+    "rightsuper",
+    "righthyper",
+    "rightmeta",
+  ]),
+  ...rangeCases(57453, ["iso_level3_shift", "iso_level5_shift"]),
+]
+
+const numberedFunctionalCases: KeyCase[] = numberedFunctionalEntries.map(([code, name]) => functionalCase(code, name))
+
+const legacyAliasCases = [
+  ["\x1b[A", "up"],
+  ["\x1b[B", "down"],
+  ["\x1b[C", "right"],
+  ["\x1b[D", "left"],
+  ["\x1b[E", "clear"],
+  ["\x1b[F", "end"],
+  ["\x1b[H", "home"],
+  ["\x1bOP", "f1"],
+  ["\x1bOQ", "f2"],
+  ["\x1bOR", "f3"],
+  ["\x1bOS", "f4"],
+  ["\x1b[2~", "insert"],
+  ["\x1b[3~", "delete"],
+  ["\x1b[5~", "pageup"],
+  ["\x1b[6~", "pagedown"],
+  ["\x1b[7~", "home"],
+  ["\x1b[8~", "end"],
+  ["\x1b[11~", "f1"],
+  ["\x1b[12~", "f2"],
+  ["\x1b[13~", "f3"],
+  ["\x1b[14~", "f4"],
+  ["\x1b[15~", "f5"],
+  ["\x1b[17~", "f6"],
+  ["\x1b[18~", "f7"],
+  ["\x1b[19~", "f8"],
+  ["\x1b[20~", "f9"],
+  ["\x1b[21~", "f10"],
+  ["\x1b[23~", "f11"],
+  ["\x1b[24~", "f12"],
+  ["\x1b[29~", "menu"],
+  ["\x1b[57427~", "clear"],
+] as const satisfies ReadonlyArray<readonly [string, string]>
+
+const enhancedLetterAliasCases = [
+  ["\x1b[1;1:1A", "up"],
+  ["\x1b[1;1:1B", "down"],
+  ["\x1b[1;1:1C", "right"],
+  ["\x1b[1;1:1D", "left"],
+  ["\x1b[1;1:1E", "clear"],
+  ["\x1b[1;1:1F", "end"],
+  ["\x1b[1;1:1H", "home"],
+  ["\x1b[1;1:1P", "f1"],
+  ["\x1b[1;1:1Q", "f2"],
+  ["\x1b[1;1:1S", "f4"],
+] as const satisfies ReadonlyArray<readonly [string, string]>
+
+const canonicalLetterAliasCases: KeyCase[] = [
+  canonicalAliasCase("\x1b[P", { name: "f1" }),
+  canonicalAliasCase("\x1b[Q", { name: "f2" }),
+  canonicalAliasCase("\x1b[S", { name: "f4" }),
+  canonicalAliasCase("\x1b[1;2P", { name: "f1", shift: true }),
+  canonicalAliasCase("\x1b[1;5Q", { name: "f2", ctrl: true }),
+  canonicalAliasCase("\x1b[1;3S", { name: "f4", meta: true, option: true }),
+]
+
+const enhancedTildeAliasCases = [
+  ["\x1b[2;1:1~", "insert"],
+  ["\x1b[3;1:1~", "delete"],
+  ["\x1b[5;1:1~", "pageup"],
+  ["\x1b[6;1:1~", "pagedown"],
+  ["\x1b[7;1:1~", "home"],
+  ["\x1b[8;1:1~", "end"],
+  ["\x1b[11;1:1~", "f1"],
+  ["\x1b[12;1:1~", "f2"],
+  ["\x1b[13;1:1~", "f3"],
+  ["\x1b[14;1:1~", "f4"],
+  ["\x1b[15;1:1~", "f5"],
+  ["\x1b[17;1:1~", "f6"],
+  ["\x1b[18;1:1~", "f7"],
+  ["\x1b[19;1:1~", "f8"],
+  ["\x1b[20;1:1~", "f9"],
+  ["\x1b[21;1:1~", "f10"],
+  ["\x1b[23;1:1~", "f11"],
+  ["\x1b[24;1:1~", "f12"],
+  ["\x1b[29;1:1~", "menu"],
+  ["\x1b[57427;1:1~", "clear"],
+] as const satisfies ReadonlyArray<readonly [string, string]>
+
+const modifierCases: KeyCase[] = [
+  modifierCase(2, { name: "a", shift: true }),
+  modifierCase(3, { name: "a", meta: true, option: true }),
+  modifierCase(5, { name: "a", ctrl: true }),
+  modifierCase(9, { name: "a", super: true }),
+  modifierCase(17, { name: "a", hyper: true }),
+  modifierCase(33, { name: "a", meta: true, option: false }),
+  modifierCase(65, { name: "a", capsLock: true }),
+  modifierCase(129, { name: "a", numLock: true }),
+  modifierCase(256, {
+    name: "a",
+    shift: true,
+    ctrl: true,
+    meta: true,
+    option: true,
+    super: true,
+    hyper: true,
+    capsLock: true,
+    numLock: true,
+  }),
+]
+
+const eventAndPayloadCases = [
+  ["\x1b[32u", { name: "space", sequence: " " }],
+  ["\x1b[32;2u", { name: "space", sequence: " ", shift: true }],
+  ["\x1b[32;5u", { name: "space", sequence: " ", ctrl: true }],
+  ["\x1b[32:32:32;5u", { name: "space", sequence: " ", ctrl: true, baseCode: 32 }],
+  ["\x1b[97;1:1u", { name: "a", eventType: "press" }],
+  ["\x1b[97;1:2u", { name: "a", eventType: "press", repeated: true }],
+  ["\x1b[97;1:3u", { name: "a", eventType: "release" }],
+  ["\x1b[97:65u", { name: "a", sequence: "a" }],
+  ["\x1b[97:65;2u", { name: "a", sequence: "A", shift: true }],
+  ["\x1b[97::113u", { name: "a", sequence: "a", baseCode: 113 }],
+  ["\x1b[97;1;65u", { name: "a", sequence: "A" }],
+  ["\x1b[57400u", { name: "kp1", sequence: "1" }],
+  ["\x1b[57413u", { name: "kpplus", sequence: "+" }],
+  ["\x1b[57400;1;120u", { name: "kp1", sequence: "x" }],
+  ["\x1b[0;;229u", { name: "å", sequence: "å" }],
+  ["\x1b[0;;104:105u", { name: "hi", sequence: "hi" }],
+] as const satisfies ReadonlyArray<readonly [string, ExpectedKey]>
+
+describe("Kitty protocol: functional key definitions", () => {
+  defineKeyCases(numberedFunctionalCases)
+})
+
+describe("Kitty protocol: legacy aliases", () => {
+  defineKeyCases(legacyAliasCases.map(([sequence, name]) => legacyAliasCase(sequence, name)))
+})
+
+describe("Kitty protocol: enhanced letter aliases", () => {
+  defineKeyCases(enhancedLetterAliasCases.map(([sequence, name]) => enhancedAliasCase(sequence, name)))
+
+  test("CSI 1;1:1R is not an enhanced F3 alias in the current spec", () => {
+    expect(parseKeypress("\x1b[1;1:1R", options)?.name).not.toBe("f3")
+  })
+})
+
+describe("Kitty protocol: canonical CSI letter forms", () => {
+  defineKeyCases(canonicalLetterAliasCases)
+
+  test("CSI R is not a canonical F3 alias in the current spec", () => {
+    expect(parseKeypress("\x1b[R", options)?.name).not.toBe("f3")
+    expect(parseKeypress("\x1b[1;2R", options)?.name).not.toBe("f3")
+  })
+})
+
+describe("Kitty protocol: enhanced tilde aliases", () => {
+  defineKeyCases(enhancedTildeAliasCases.map(([sequence, name]) => enhancedAliasCase(sequence, name)))
+})
+
+describe("Kitty protocol: modifier bitfield", () => {
+  defineKeyCases(modifierCases)
+})
+
+describe("Kitty protocol: event, alternate-key, and text fields", () => {
+  defineKeyCases(
+    eventAndPayloadCases.map(([sequence, expected]) => ({
+      title: `payload ${JSON.stringify(sequence)}`,
+      sequence,
+      expected: { source: "kitty", ...expected },
+    })),
+  )
+})