@xincli/opentui-core 0.4.6

package/src/text-buffer.ts

@@ -0,0 +1,250 @@
+import type { StyledText } from "./lib/styled-text.js"
+import { RGBA } from "./lib/RGBA.js"
+import { resolveRenderLib, type LineInfo, type RenderLib, type TextBufferHandle } from "./zig.js"
+import { type WidthMethod, type Highlight } from "./types.js"
+import type { SyntaxStyle } from "./syntax-style.js"
+
+export interface TextChunk {
+  __isChunk: true
+  text: string
+  fg?: RGBA
+  bg?: RGBA
+  attributes?: number
+  link?: { url: string }
+}
+
+export class TextBuffer {
+  private lib: RenderLib
+  private bufferPtr: TextBufferHandle
+  private _length: number = 0
+  private _byteSize: number = 0
+  private _lineInfo?: LineInfo
+  private _destroyed: boolean = false
+  private _syntaxStyle?: SyntaxStyle
+  private _textBytes?: Uint8Array
+  private _memId?: number
+  private _appendedChunks: Uint8Array[] = []
+
+  constructor(lib: RenderLib, ptr: TextBufferHandle) {
+    this.lib = lib
+    this.bufferPtr = ptr
+  }
+
+  static create(widthMethod: WidthMethod): TextBuffer {
+    const lib = resolveRenderLib()
+    return lib.createTextBuffer(widthMethod)
+  }
+
+  // Fail loud and clear
+  // Instead of trying to return values that could work or not,
+  // this at least will show a stack trace to know where the call to a destroyed TextBuffer was made
+  private guard(): void {
+    if (this._destroyed) throw new Error("TextBuffer is destroyed")
+  }
+
+  public setText(text: string): void {
+    this.guard()
+    this._textBytes = this.lib.encoder.encode(text)
+
+    if (this._memId === undefined) {
+      this._memId = this.lib.textBufferRegisterMemBuffer(this.bufferPtr, this._textBytes, false)
+    } else if (!this.lib.textBufferReplaceMemBuffer(this.bufferPtr, this._memId, this._textBytes, false)) {
+      this._memId = this.lib.textBufferRegisterMemBuffer(this.bufferPtr, this._textBytes, false)
+    }
+
+    this.lib.textBufferSetTextFromMem(this.bufferPtr, this._memId)
+    this._length = this.lib.textBufferGetLength(this.bufferPtr)
+    this._byteSize = this.lib.textBufferGetByteSize(this.bufferPtr)
+    this._lineInfo = undefined
+    this._appendedChunks = [] // Clear any previously appended chunks
+  }
+
+  public append(text: string): void {
+    this.guard()
+    const textBytes = this.lib.encoder.encode(text)
+    // Keep the bytes alive to prevent garbage collection
+    this._appendedChunks.push(textBytes)
+    this.lib.textBufferAppend(this.bufferPtr, textBytes)
+    this._length = this.lib.textBufferGetLength(this.bufferPtr)
+    this._byteSize = this.lib.textBufferGetByteSize(this.bufferPtr)
+    this._lineInfo = undefined
+  }
+
+  public loadFile(path: string): void {
+    this.guard()
+    const success = this.lib.textBufferLoadFile(this.bufferPtr, path)
+    if (!success) {
+      throw new Error(`Failed to load file: ${path}`)
+    }
+    this._length = this.lib.textBufferGetLength(this.bufferPtr)
+    this._byteSize = this.lib.textBufferGetByteSize(this.bufferPtr)
+    this._lineInfo = undefined
+    this._textBytes = undefined
+  }
+
+  public setStyledText(text: StyledText): void {
+    this.guard()
+
+    this.lib.textBufferSetStyledText(this.bufferPtr, text.chunks)
+
+    this._length = this.lib.textBufferGetLength(this.bufferPtr)
+    this._byteSize = this.lib.textBufferGetByteSize(this.bufferPtr)
+    this._lineInfo = undefined
+  }
+
+  public setDefaultFg(fg: RGBA | null): void {
+    this.guard()
+    this.lib.textBufferSetDefaultFg(this.bufferPtr, fg)
+  }
+
+  public setDefaultBg(bg: RGBA | null): void {
+    this.guard()
+    this.lib.textBufferSetDefaultBg(this.bufferPtr, bg)
+  }
+
+  public setDefaultAttributes(attributes: number | null): void {
+    this.guard()
+    this.lib.textBufferSetDefaultAttributes(this.bufferPtr, attributes)
+  }
+
+  public resetDefaults(): void {
+    this.guard()
+    this.lib.textBufferResetDefaults(this.bufferPtr)
+  }
+
+  public getLineCount(): number {
+    this.guard()
+    return this.lib.textBufferGetLineCount(this.bufferPtr)
+  }
+
+  public get length(): number {
+    this.guard()
+    return this._length
+  }
+
+  public get byteSize(): number {
+    this.guard()
+    return this._byteSize
+  }
+
+  public get ptr(): TextBufferHandle {
+    this.guard()
+    return this.bufferPtr
+  }
+
+  public getPlainText(): string {
+    this.guard()
+    if (this._byteSize === 0) return ""
+    // Use byteSize for accurate buffer allocation (includes newlines in byte count)
+    const plainBytes = this.lib.getPlainTextBytes(this.bufferPtr, this._byteSize)
+
+    if (!plainBytes) return ""
+
+    return this.lib.decoder.decode(plainBytes)
+  }
+
+  public getTextRange(startOffset: number, endOffset: number): string {
+    this.guard()
+    if (startOffset >= endOffset) return ""
+    if (this._byteSize === 0) return ""
+
+    const rangeBytes = this.lib.textBufferGetTextRange(this.bufferPtr, startOffset, endOffset, this._byteSize)
+
+    if (!rangeBytes) return ""
+
+    return this.lib.decoder.decode(rangeBytes)
+  }
+
+  /**
+   * Add a highlight using character offsets into the full text.
+   * start/end in highlight represent absolute character positions.
+   */
+  public addHighlightByCharRange(highlight: Highlight): void {
+    this.guard()
+    this.lib.textBufferAddHighlightByCharRange(this.bufferPtr, highlight)
+  }
+
+  /**
+   * Add a highlight to a specific line by column positions.
+   * start/end in highlight represent column offsets.
+   */
+  public addHighlight(lineIdx: number, highlight: Highlight): void {
+    this.guard()
+    this.lib.textBufferAddHighlight(this.bufferPtr, lineIdx, highlight)
+  }
+
+  public removeHighlightsByRef(hlRef: number): void {
+    this.guard()
+    this.lib.textBufferRemoveHighlightsByRef(this.bufferPtr, hlRef)
+  }
+
+  public clearLineHighlights(lineIdx: number): void {
+    this.guard()
+    this.lib.textBufferClearLineHighlights(this.bufferPtr, lineIdx)
+  }
+
+  public clearAllHighlights(): void {
+    this.guard()
+    this.lib.textBufferClearAllHighlights(this.bufferPtr)
+  }
+
+  public getLineHighlights(lineIdx: number): Array<Highlight> {
+    this.guard()
+    return this.lib.textBufferGetLineHighlights(this.bufferPtr, lineIdx)
+  }
+
+  public getHighlightCount(): number {
+    this.guard()
+    return this.lib.textBufferGetHighlightCount(this.bufferPtr)
+  }
+
+  public setSyntaxStyle(style: SyntaxStyle | null): void {
+    this.guard()
+    if (this.lib.textBufferSetSyntaxStyle(this.bufferPtr, style?.ptr ?? null)) {
+      this._syntaxStyle = style ?? undefined
+    }
+  }
+
+  public getSyntaxStyle(): SyntaxStyle | null {
+    this.guard()
+    return this._syntaxStyle ?? null
+  }
+
+  public setTabWidth(width: number): void {
+    this.guard()
+    this.lib.textBufferSetTabWidth(this.bufferPtr, width)
+  }
+
+  public getTabWidth(): number {
+    this.guard()
+    return this.lib.textBufferGetTabWidth(this.bufferPtr)
+  }
+
+  public clear(): void {
+    this.guard()
+    this.lib.textBufferClear(this.bufferPtr)
+    this._length = 0
+    this._byteSize = 0
+    this._lineInfo = undefined
+    this._textBytes = undefined
+    this._appendedChunks = []
+    // Note: _memId is NOT cleared - it can be reused for next setText
+  }
+
+  public reset(): void {
+    this.guard()
+    this.lib.textBufferReset(this.bufferPtr)
+    this._length = 0
+    this._byteSize = 0
+    this._lineInfo = undefined
+    this._textBytes = undefined
+    this._memId = undefined // Reset clears the registry, so clear our ID
+    this._appendedChunks = []
+  }
+
+  public destroy(): void {
+    if (this._destroyed) return
+    this._destroyed = true
+    this.lib.destroyTextBuffer(this.bufferPtr)
+  }
+}

package/src/types.ts

@@ -0,0 +1,199 @@
+import type { RGBA } from "./lib/RGBA.js"
+import type { EventEmitter } from "events"
+import type { Selection } from "./lib/selection.js"
+import type { Renderable } from "./Renderable.js"
+import type { InternalKeyHandler, KeyHandler } from "./lib/KeyHandler.js"
+import type { EditBufferRenderable } from "./renderables/EditBufferRenderable.js"
+
+export const TextAttributes = {
+  NONE: 0,
+  BOLD: 1 << 0, // 1
+  DIM: 1 << 1, // 2
+  ITALIC: 1 << 2, // 4
+  UNDERLINE: 1 << 3, // 8
+  BLINK: 1 << 4, // 16
+  INVERSE: 1 << 5, // 32
+  HIDDEN: 1 << 6, // 64
+  STRIKETHROUGH: 1 << 7, // 128
+}
+
+// Constants for attribute bit packing
+export const ATTRIBUTE_BASE_BITS = 8
+export const ATTRIBUTE_BASE_MASK = 0xff
+
+/**
+ * Extract the base 8 bits of attributes from a u32 attribute value.
+ * Currently we only use the first 8 bits for standard text attributes.
+ */
+export function getBaseAttributes(attr: number): number {
+  return attr & ATTRIBUTE_BASE_MASK
+}
+
+export type ThemeMode = "dark" | "light"
+
+export type CursorStyle = "block" | "line" | "underline" | "default"
+
+export type MousePointerStyle = "default" | "pointer" | "text" | "crosshair" | "move" | "not-allowed"
+
+export interface CursorStyleOptions {
+  style?: CursorStyle
+  blinking?: boolean
+  color?: RGBA
+  cursor?: MousePointerStyle
+}
+
+export enum DebugOverlayCorner {
+  topLeft = 0,
+  topRight = 1,
+  bottomLeft = 2,
+  bottomRight = 3,
+}
+
+export enum TargetChannel {
+  FG = 1,
+  BG = 2,
+  Both = 3,
+}
+
+export type WidthMethod = "wcwidth" | "unicode"
+export type TerminalMultiplexer = "none" | "tmux" | "zellij" | "screen" | "unknown"
+export type TerminalCapabilityState = "unknown" | "supported" | "unsupported"
+
+export interface TerminalInfo {
+  name: string
+  version: string
+  from_xtversion: boolean
+}
+
+export interface TerminalCapabilities {
+  kitty_keyboard: boolean
+  kitty_graphics: boolean
+  rgb: boolean
+  ansi256: boolean
+  unicode: WidthMethod
+  sgr_pixels: boolean
+  color_scheme_updates: boolean
+  explicit_width: boolean
+  scaled_text: boolean
+  sixel: boolean
+  focus_tracking: boolean
+  sync: boolean
+  bracketed_paste: boolean
+  hyperlinks: boolean
+  osc52: boolean
+  osc52_support: TerminalCapabilityState
+  notifications: boolean
+  explicit_cursor_positioning: boolean
+  remote: boolean
+  multiplexer: TerminalMultiplexer
+  terminal: TerminalInfo
+}
+
+export interface RendererEvents {
+  resize: (width: number, height: number) => void
+  key: (data: Buffer) => void
+  "memory:snapshot": (snapshot: { heapUsed: number; heapTotal: number; arrayBuffers: number }) => void
+  capabilities: (capabilities: TerminalCapabilities) => void
+  selection: (selection: Selection) => void
+  focused_renderable: (current: Renderable | null, previous: Renderable | null) => void
+  focused_editor: (current: EditBufferRenderable | null, previous: EditBufferRenderable | null) => void
+  "debugOverlay:toggle": (enabled: boolean) => void
+  theme_mode: (mode: ThemeMode) => void
+}
+
+export interface RenderContext extends EventEmitter {
+  addToHitGrid: (x: number, y: number, width: number, height: number, id: number) => void
+  pushHitGridScissorRect: (x: number, y: number, width: number, height: number) => void
+  popHitGridScissorRect: () => void
+  clearHitGridScissorRects: () => void
+  width: number
+  height: number
+  /** Monotonic, bumped once per `loop()` iteration. Lets renderables dedupe per-frame work. */
+  frameId: number
+  requestRender: () => void
+  setCursorPosition: (x: number, y: number, visible: boolean) => void
+  setCursorStyle: (options: CursorStyleOptions) => void
+  setCursorColor: (color: RGBA) => void
+  setMousePointer: (shape: MousePointerStyle) => void
+  widthMethod: WidthMethod
+  capabilities: TerminalCapabilities | null
+  requestLive: () => void
+  dropLive: () => void
+  hasSelection: boolean
+  getSelection: () => Selection | null
+  requestSelectionUpdate: () => void
+  currentFocusedRenderable: Renderable | null
+  currentFocusedEditor: EditBufferRenderable | null
+  focusRenderable: (renderable: Renderable) => void
+  blurRenderable: (renderable: Renderable) => void
+  claimFirstLineOffset?: (renderable?: Renderable) => number
+  registerLifecyclePass: (renderable: Renderable) => void
+  unregisterLifecyclePass: (renderable: Renderable) => void
+  getLifecyclePasses: () => Set<Renderable>
+  keyInput: KeyHandler
+  _internalKeyInput: InternalKeyHandler
+  clearSelection: () => void
+  startSelection: (renderable: Renderable, x: number, y: number) => void
+  updateSelection: (
+    currentRenderable: Renderable | undefined,
+    x: number,
+    y: number,
+    options?: { finishDragging?: boolean },
+  ) => void
+}
+
+export type Timeout = ReturnType<typeof setTimeout> | undefined
+
+export interface ViewportBounds {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+export interface Highlight {
+  start: number
+  end: number
+  styleId: number
+  priority?: number | null
+  hlRef?: number | null
+}
+
+export interface LineInfo {
+  /** Display-column offset for each visual line start. */
+  lineStartCols: number[]
+  /** Display-column width for each visual line. */
+  lineWidthCols: number[]
+  /** Maximum display-column width across the reported lines. */
+  lineWidthColsMax: number
+  /** Source logical line index for each visual line. */
+  lineSources: number[]
+  /** Wrap index within each source logical line. */
+  lineWraps: number[]
+}
+
+export interface LineInfoProvider {
+  get lineInfo(): LineInfo
+  get lineCount(): number
+  get virtualLineCount(): number
+  get scrollY(): number
+}
+
+export interface CapturedSpan {
+  text: string
+  fg: RGBA
+  bg: RGBA
+  attributes: number
+  width: number
+}
+
+export interface CapturedLine {
+  spans: CapturedSpan[]
+}
+
+export interface CapturedFrame {
+  cols: number
+  rows: number
+  cursor: [number, number]
+  lines: CapturedLine[]
+}

package/src/utils.ts

@@ -0,0 +1,88 @@
+import { TextAttributes } from "./types.js"
+import { Renderable } from "./Renderable.js"
+
+export function createTextAttributes({
+  bold = false,
+  italic = false,
+  underline = false,
+  dim = false,
+  blink = false,
+  inverse = false,
+  hidden = false,
+  strikethrough = false,
+}: {
+  bold?: boolean
+  italic?: boolean
+  underline?: boolean
+  dim?: boolean
+  blink?: boolean
+  inverse?: boolean
+  hidden?: boolean
+  strikethrough?: boolean
+} = {}): number {
+  let attributes = TextAttributes.NONE
+
+  if (bold) attributes |= TextAttributes.BOLD
+  if (italic) attributes |= TextAttributes.ITALIC
+  if (underline) attributes |= TextAttributes.UNDERLINE
+  if (dim) attributes |= TextAttributes.DIM
+  if (blink) attributes |= TextAttributes.BLINK
+  if (inverse) attributes |= TextAttributes.INVERSE
+  if (hidden) attributes |= TextAttributes.HIDDEN
+  if (strikethrough) attributes |= TextAttributes.STRIKETHROUGH
+
+  return attributes
+}
+
+// Link attribute helpers (bits 8-31 encode link_id)
+const ATTRIBUTE_BASE_MASK = 0xff
+const LINK_ID_SHIFT = 8
+const LINK_ID_PAYLOAD_MASK = 0xffffff
+
+export function attributesWithLink(baseAttributes: number, linkId: number): number {
+  const base = baseAttributes & ATTRIBUTE_BASE_MASK
+  const linkBits = (linkId & LINK_ID_PAYLOAD_MASK) << LINK_ID_SHIFT
+  return base | linkBits
+}
+
+export function getLinkId(attributes: number): number {
+  return (attributes >>> LINK_ID_SHIFT) & LINK_ID_PAYLOAD_MASK
+}
+
+// For debugging purposes
+export function visualizeRenderableTree(renderable: Renderable, maxDepth: number = 10): void {
+  function buildTreeLines(
+    node: Renderable,
+    prefix: string = "",
+    parentPrefix: string = "",
+    isLastChild: boolean = true,
+    depth: number = 0,
+  ): string[] {
+    if (depth >= maxDepth) {
+      return [`${prefix}${node.id} ... (max depth reached)`]
+    }
+
+    const lines: string[] = []
+    const children = node.getChildren()
+
+    // Add current node
+    lines.push(`${prefix}${node.id}`)
+
+    if (children.length > 0) {
+      const lastChildIndex = children.length - 1
+
+      children.forEach((child, index) => {
+        const childIsLast = index === lastChildIndex
+        const connector = childIsLast ? "└── " : "├── "
+        const childPrefix = parentPrefix + (isLastChild ? "    " : "│   ")
+        const childLines = buildTreeLines(child, childPrefix + connector, childPrefix, childIsLast, depth + 1)
+        lines.push(...childLines)
+      })
+    }
+
+    return lines
+  }
+
+  const treeLines = buildTreeLines(renderable)
+  console.log("Renderable Tree:\n" + treeLines.join("\n"))
+}