@xincli/opentui-core 0.4.6

package/src/lib/parse.mouse.ts

@@ -0,0 +1,232 @@
+export type MouseEventType = "down" | "up" | "move" | "drag" | "drag-end" | "drop" | "over" | "out" | "scroll"
+
+export interface ScrollInfo {
+  direction: "up" | "down" | "left" | "right"
+  delta: number
+}
+
+export type RawMouseEvent = {
+  type: MouseEventType
+  button: number
+  x: number
+  y: number
+  modifiers: { shift: boolean; alt: boolean; ctrl: boolean }
+  scroll?: ScrollInfo
+}
+
+type ParsedMouseSequence = {
+  event: RawMouseEvent
+  consumed: number
+}
+
+export class MouseParser {
+  private mouseButtonsPressed = new Set<number>()
+
+  private static readonly SCROLL_DIRECTIONS: Record<number, "up" | "down" | "left" | "right"> = {
+    0: "up",
+    1: "down",
+    2: "left",
+    3: "right",
+  }
+
+  public reset(): void {
+    this.mouseButtonsPressed.clear()
+  }
+
+  // Preserve raw byte values so X10 payload bytes >= 0x80 remain intact.
+  // SGR sequences are ASCII digits + separators and are unaffected either way.
+  private decodeInput(data: Buffer | Uint8Array): string {
+    const buf = Buffer.isBuffer(data) ? data : Buffer.from(data.buffer, data.byteOffset, data.byteLength)
+    return buf.toString("latin1")
+  }
+
+  public parseMouseEvent(data: Buffer | Uint8Array): RawMouseEvent | null {
+    const str = this.decodeInput(data)
+    const parsed = this.parseMouseSequenceAt(str, 0)
+    return parsed?.event ?? null
+  }
+
+  public parseAllMouseEvents(data: Buffer | Uint8Array): RawMouseEvent[] {
+    const str = this.decodeInput(data)
+    const events: RawMouseEvent[] = []
+    let offset = 0
+
+    while (offset < str.length) {
+      const parsed = this.parseMouseSequenceAt(str, offset)
+      if (!parsed) {
+        // Stop at the first non-mouse sequence. Callers can decide whether to
+        // route any remaining data through keyboard/terminal input handling.
+        break
+      }
+
+      events.push(parsed.event)
+      offset += parsed.consumed
+    }
+
+    return events
+  }
+
+  private parseMouseSequenceAt(str: string, offset: number): ParsedMouseSequence | null {
+    if (!str.startsWith("\x1b[", offset)) return null
+    const introducer = str[offset + 2]
+
+    if (introducer === "<") {
+      return this.parseSgrSequence(str, offset)
+    }
+
+    if (introducer === "M") {
+      return this.parseBasicSequence(str, offset)
+    }
+
+    return null
+  }
+
+  private parseSgrSequence(str: string, offset: number): ParsedMouseSequence | null {
+    let index = offset + 3
+    const values = [0, 0, 0]
+    let part = 0
+    let hasDigit = false
+
+    while (index < str.length) {
+      const char = str[index]
+      const charCode = str.charCodeAt(index)
+
+      if (charCode >= 48 && charCode <= 57) {
+        hasDigit = true
+        values[part] = values[part]! * 10 + (charCode - 48)
+        index++
+        continue
+      }
+
+      switch (char) {
+        case ";": {
+          if (!hasDigit || part >= 2) return null
+          part++
+          hasDigit = false
+          index++
+          break
+        }
+        case "M":
+        case "m": {
+          if (!hasDigit || part !== 2) return null
+
+          return {
+            event: this.decodeSgrEvent(values[0]!, values[1]!, values[2]!, char),
+            consumed: index - offset + 1,
+          }
+        }
+        default:
+          return null
+      }
+    }
+
+    return null
+  }
+
+  private parseBasicSequence(str: string, offset: number): ParsedMouseSequence | null {
+    // ESC [ M + 3 bytes
+    if (offset + 6 > str.length) return null
+
+    const buttonByte = str.charCodeAt(offset + 3) - 32
+    // Convert from 1-based to 0-based
+    const x = str.charCodeAt(offset + 4) - 33
+    const y = str.charCodeAt(offset + 5) - 33
+
+    return {
+      event: this.decodeBasicEvent(buttonByte, x, y),
+      consumed: 6,
+    }
+  }
+
+  private decodeSgrEvent(rawButtonCode: number, wireX: number, wireY: number, pressRelease: "M" | "m"): RawMouseEvent {
+    const button = rawButtonCode & 3
+    const isScroll = (rawButtonCode & 64) !== 0
+    const scrollDirection = !isScroll ? undefined : MouseParser.SCROLL_DIRECTIONS[button]
+
+    const isMotion = (rawButtonCode & 32) !== 0
+    const modifiers = {
+      shift: (rawButtonCode & 4) !== 0,
+      alt: (rawButtonCode & 8) !== 0,
+      ctrl: (rawButtonCode & 16) !== 0,
+    }
+
+    let type: MouseEventType
+    let scrollInfo: ScrollInfo | undefined
+
+    if (isMotion) {
+      const isDragging = this.mouseButtonsPressed.size > 0
+
+      if (button === 3) {
+        type = "move"
+      } else if (isDragging) {
+        type = "drag"
+      } else {
+        type = "move"
+      }
+    } else if (isScroll && pressRelease === "M") {
+      type = "scroll"
+      scrollInfo = {
+        direction: scrollDirection!,
+        delta: 1,
+      }
+    } else {
+      type = pressRelease === "M" ? "down" : "up"
+
+      if (type === "down" && button !== 3) {
+        this.mouseButtonsPressed.add(button)
+      } else if (type === "up") {
+        this.mouseButtonsPressed.clear()
+      }
+    }
+
+    return {
+      type,
+      button: button === 3 ? 0 : button,
+      x: wireX - 1,
+      y: wireY - 1,
+      modifiers,
+      scroll: scrollInfo,
+    }
+  }
+
+  private decodeBasicEvent(buttonByte: number, x: number, y: number): RawMouseEvent {
+    const button = buttonByte & 3
+    const isScroll = (buttonByte & 64) !== 0
+    const isMotion = (buttonByte & 32) !== 0
+    const scrollDirection = !isScroll ? undefined : MouseParser.SCROLL_DIRECTIONS[button]
+
+    const modifiers = {
+      shift: (buttonByte & 4) !== 0,
+      alt: (buttonByte & 8) !== 0,
+      ctrl: (buttonByte & 16) !== 0,
+    }
+
+    let type: MouseEventType
+    let actualButton: number
+    let scrollInfo: ScrollInfo | undefined
+
+    if (isMotion) {
+      type = "move"
+      actualButton = button === 3 ? -1 : button
+    } else if (isScroll) {
+      type = "scroll"
+      actualButton = 0
+      scrollInfo = {
+        direction: scrollDirection!,
+        delta: 1,
+      }
+    } else {
+      type = button === 3 ? "up" : "down"
+      actualButton = button === 3 ? 0 : button
+    }
+
+    return {
+      type,
+      button: actualButton,
+      x,
+      y,
+      modifiers,
+      scroll: scrollInfo,
+    }
+  }
+}

package/src/lib/paste.ts

@@ -0,0 +1,18 @@
+import { stripANSI } from "../platform/runtime.js"
+
+export type PasteKind = "text" | "binary" | "unknown"
+
+export interface PasteMetadata {
+  mimeType?: string
+  kind?: PasteKind
+}
+
+const PASTE_TEXT_DECODER = new TextDecoder()
+
+export function decodePasteBytes(bytes: Uint8Array): string {
+  return PASTE_TEXT_DECODER.decode(bytes)
+}
+
+export function stripAnsiSequences(text: string): string {
+  return stripANSI(text)
+}

package/src/lib/queue.ts

@@ -0,0 +1,65 @@
+/**
+ * Generic processing queue that handles asynchronous job processing
+ */
+export class ProcessQueue<T> {
+  private queue: T[] = []
+  private processing: boolean = false
+  private autoProcess: boolean = true
+
+  constructor(
+    private processor: (item: T) => Promise<void> | void,
+    autoProcess: boolean = true,
+  ) {
+    this.autoProcess = autoProcess
+  }
+
+  enqueue(item: T): void {
+    this.queue.push(item)
+
+    if (!this.processing && this.autoProcess) {
+      this.processQueue()
+    }
+  }
+
+  private processQueue(): void {
+    if (this.queue.length === 0) {
+      return
+    }
+
+    this.processing = true
+
+    queueMicrotask(async () => {
+      if (this.queue.length === 0) {
+        this.processing = false
+        return
+      }
+
+      // Get the next item to process (FIFO)
+      const item = this.queue.shift()!
+
+      try {
+        await this.processor(item)
+      } catch (error) {
+        console.error("Error processing queue item:", error)
+      }
+
+      if (this.queue.length > 0) {
+        this.processQueue()
+      } else {
+        this.processing = false
+      }
+    })
+  }
+
+  clear(): void {
+    this.queue = []
+  }
+
+  isProcessing(): boolean {
+    return this.processing
+  }
+
+  size(): number {
+    return this.queue.length
+  }
+}

package/src/lib/render-geometry.ts

@@ -0,0 +1,36 @@
+export type RenderGeometryScreenMode = "alternate-screen" | "main-screen" | "split-footer"
+
+export interface RenderGeometry {
+  effectiveFooterHeight: number
+  renderOffset: number
+  renderWidth: number
+  renderHeight: number
+}
+
+export function calculateRenderGeometry(
+  screenMode: RenderGeometryScreenMode,
+  terminalWidth: number,
+  terminalHeight: number,
+  footerHeight: number,
+): RenderGeometry {
+  const safeTerminalWidth = Math.max(terminalWidth, 0)
+  const safeTerminalHeight = Math.max(terminalHeight, 0)
+
+  if (screenMode !== "split-footer") {
+    return {
+      effectiveFooterHeight: 0,
+      renderOffset: 0,
+      renderWidth: safeTerminalWidth,
+      renderHeight: safeTerminalHeight,
+    }
+  }
+
+  const effectiveFooterHeight = Math.min(footerHeight, safeTerminalHeight)
+
+  return {
+    effectiveFooterHeight,
+    renderOffset: safeTerminalHeight - effectiveFooterHeight,
+    renderWidth: safeTerminalWidth,
+    renderHeight: effectiveFooterHeight,
+  }
+}

package/src/lib/renderable.validations.test.ts

@@ -0,0 +1,87 @@
+import { describe, test, expect } from "bun:test"
+import {
+  validateOptions,
+  isPositionType,
+  isDimensionType,
+  isFlexBasisType,
+  isSizeType,
+  isMarginType,
+  isPaddingType,
+  isPositionTypeType,
+  isOverflowType,
+  isValidPercentage,
+} from "./renderable.validations.js"
+
+describe("Utility Functions", () => {
+  test("validateOptions", () => {
+    expect(validateOptions("test", { width: 100, height: 100 })).toBe(undefined)
+    expect(() => validateOptions("test", { width: -100, height: 100 })).toThrow(TypeError)
+    expect(() => validateOptions("test", { width: 100, height: -100 })).toThrow(TypeError)
+  })
+
+  test("isValidPercentage", () => {
+    expect(isValidPercentage("50%")).toBe(true)
+    expect(isValidPercentage("0%")).toBe(true)
+    expect(isValidPercentage("100.5%")).toBe(true)
+    expect(isValidPercentage("abc")).toBe(false)
+    expect(isValidPercentage("50")).toBe(false)
+    expect(isValidPercentage(50)).toBe(false)
+  })
+
+  test("isMarginType", () => {
+    expect(isMarginType(10)).toBe(true)
+    expect(isMarginType("auto")).toBe(true)
+    expect(isMarginType("50%")).toBe(true)
+    expect(isMarginType(NaN)).toBe(false)
+    expect(isMarginType("invalid")).toBe(false)
+  })
+
+  test("isPaddingType", () => {
+    expect(isPaddingType(10)).toBe(true)
+    expect(isPaddingType("50%")).toBe(true)
+    expect(isPaddingType("auto")).toBe(false)
+    expect(isPaddingType(NaN)).toBe(false)
+  })
+
+  test("isPositionType", () => {
+    expect(isPositionType(10)).toBe(true)
+    expect(isPositionType("auto")).toBe(true)
+    expect(isPositionType("50%")).toBe(true)
+    expect(isPositionType(NaN)).toBe(false)
+  })
+
+  test("isDimensionType", () => {
+    expect(isDimensionType(100)).toBe(true)
+    expect(isDimensionType("auto")).toBe(true)
+    expect(isDimensionType("50%")).toBe(true)
+    expect(isDimensionType(NaN)).toBe(false)
+  })
+
+  test("isFlexBasisType", () => {
+    expect(isFlexBasisType(100)).toBe(true)
+    expect(isFlexBasisType("auto")).toBe(true)
+    expect(isFlexBasisType(undefined)).toBe(true)
+    expect(isFlexBasisType(NaN)).toBe(false)
+  })
+
+  test("isSizeType", () => {
+    expect(isSizeType(100)).toBe(true)
+    expect(isSizeType("50%")).toBe(true)
+    expect(isSizeType(undefined)).toBe(true)
+    expect(isSizeType(NaN)).toBe(false)
+  })
+
+  test("isPositionTypeType", () => {
+    expect(isPositionTypeType("relative")).toBe(true)
+    expect(isPositionTypeType("absolute")).toBe(true)
+    expect(isPositionTypeType("static")).toBe(false)
+    expect(isPositionTypeType("fixed")).toBe(false)
+  })
+
+  test("isOverflowType", () => {
+    expect(isOverflowType("visible")).toBe(true)
+    expect(isOverflowType("hidden")).toBe(true)
+    expect(isOverflowType("scroll")).toBe(true)
+    expect(isOverflowType("auto")).toBe(false)
+  })
+})

package/src/lib/renderable.validations.ts

@@ -0,0 +1,83 @@
+import type { RenderableOptions, Renderable } from "../Renderable.js"
+import type { PositionTypeString, OverflowString } from "./yoga.options.js"
+
+export function validateOptions(id: string, options: RenderableOptions<Renderable>): void {
+  if (typeof options.width === "number") {
+    if (options.width < 0) {
+      throw new TypeError(`Invalid width for Renderable ${id}: ${options.width}`)
+    }
+  }
+  if (typeof options.height === "number") {
+    if (options.height < 0) {
+      throw new TypeError(`Invalid height for Renderable ${id}: ${options.height}`)
+    }
+  }
+}
+
+export function isValidPercentage(value: any): value is `${number}%` {
+  if (typeof value === "string" && value.endsWith("%")) {
+    const numPart = value.slice(0, -1)
+    const num = parseFloat(numPart)
+    return !Number.isNaN(num)
+  }
+  return false
+}
+
+export function isMarginType(value: any): value is number | "auto" | `${number}%` {
+  if (typeof value === "number" && !Number.isNaN(value)) {
+    return true
+  }
+  if (value === "auto") {
+    return true
+  }
+  return isValidPercentage(value)
+}
+
+export function isPaddingType(value: any): value is number | `${number}%` {
+  if (typeof value === "number" && !Number.isNaN(value)) {
+    return true
+  }
+  return isValidPercentage(value)
+}
+
+export function isPositionType(value: any): value is number | "auto" | `${number}%` {
+  if (typeof value === "number" && !Number.isNaN(value)) {
+    return true
+  }
+  if (value === "auto") {
+    return true
+  }
+  return isValidPercentage(value)
+}
+
+export function isPositionTypeType(value: any): value is PositionTypeString {
+  return value === "relative" || value === "absolute"
+}
+
+export function isOverflowType(value: any): value is OverflowString {
+  return value === "visible" || value === "hidden" || value === "scroll"
+}
+
+export function isDimensionType(value: any): value is number | "auto" | `${number}%` {
+  return isPositionType(value)
+}
+
+export function isFlexBasisType(value: any): value is number | "auto" | undefined {
+  if (value === undefined || value === "auto") {
+    return true
+  }
+  if (typeof value === "number" && !Number.isNaN(value)) {
+    return true
+  }
+  return false
+}
+
+export function isSizeType(value: any): value is number | `${number}%` | undefined {
+  if (value === undefined) {
+    return true
+  }
+  if (typeof value === "number" && !Number.isNaN(value)) {
+    return true
+  }
+  return isValidPercentage(value)
+}

package/src/lib/scroll-acceleration.ts

@@ -0,0 +1,98 @@
+export interface ScrollAcceleration {
+  tick(now?: number): number
+  reset(): void
+}
+
+export class LinearScrollAccel implements ScrollAcceleration {
+  tick(_now?: number): number {
+    return 1
+  }
+
+  reset(): void {}
+}
+
+/**
+ * macOS-inspired scroll acceleration.
+ *
+ * The class measures the time between consecutive scroll events and keeps a short
+ * moving window of the latest intervals. The average interval determines which
+ * multiplier to apply so that quick bursts accelerate and slower gestures stay precise.
+ *
+ * For intuition, treat the streak as a continuous timeline and compare it with the
+ * exponential distance curve from the pointer-acceleration research post:
+ *   d(t) = v₀ * ( t + A * (exp(t/τ) - 1 - t/τ) ).
+ * Small t stays near the base multiplier, medium streaks settle on multiplier1, and
+ * sustained bursts reach multiplier2, mirroring how the exponential curve bends up.
+ *
+ * Options:
+ * - threshold1: upper bound (ms) of the "medium" band. Raise to delay the ramp.
+ * - threshold2: upper bound (ms) of the "fast" band. Lower to demand tighter bursts.
+ * - multiplier1: scale for medium speed streaks.
+ * - multiplier2: scale for sustained fast streaks.
+ * - baseMultiplier: scale for relaxed scrolling; set to 1 for linear behaviour.
+ */
+export class MacOSScrollAccel implements ScrollAcceleration {
+  private lastTickTime = 0
+  private velocityHistory: number[] = []
+  private readonly historySize = 3
+  private readonly streakTimeout = 150
+  // Some terminals send 2 or more ticks for each mouse wheel tick, for example Ghostty, with a small delay between each tick, about 4ms on average.
+  // We ignore these ticks otherwise they would cause faster acceleration to kick in
+  // https://github.com/ghostty-org/ghostty/discussions/7577
+  private readonly minTickInterval = 6
+
+  constructor(
+    private opts: {
+      A?: number
+      tau?: number
+      maxMultiplier?: number
+    } = {},
+  ) {}
+
+  tick(now = Date.now()): number {
+    const A = this.opts.A ?? 0.8
+    const tau = this.opts.tau ?? 3
+    const maxMultiplier = this.opts.maxMultiplier ?? 6
+
+    const dt = this.lastTickTime ? now - this.lastTickTime : Infinity
+
+    // Reset streak if too much time has passed or first tick
+    if (dt === Infinity || dt > this.streakTimeout) {
+      this.lastTickTime = now
+      this.velocityHistory = []
+      return 1
+    }
+
+    // Ignore ticks closer than minTickInterval (they're part of the same logical tick)
+    if (dt < this.minTickInterval) {
+      return 1
+    }
+
+    this.lastTickTime = now
+
+    this.velocityHistory.push(dt)
+    if (this.velocityHistory.length > this.historySize) {
+      this.velocityHistory.shift()
+    }
+
+    // Calculate average interval (lower = faster scrolling)
+    const avgInterval = this.velocityHistory.reduce((a, b) => a + b, 0) / this.velocityHistory.length
+
+    // Convert interval to velocity: faster ticks = higher velocity
+    // Normalize to a reference interval (e.g., 100ms = velocity of 1)
+    const referenceInterval = 100
+    const velocity = referenceInterval / avgInterval
+
+    // Apply exponential curve based on velocity
+    // Higher velocity (tighter ticks) = more acceleration
+    const x = velocity / tau
+    const multiplier = 1 + A * (Math.exp(x) - 1)
+
+    return Math.min(multiplier, maxMultiplier)
+  }
+
+  reset(): void {
+    this.lastTickTime = 0
+    this.velocityHistory = []
+  }
+}