@fairyhunter13/opentui-core 0.1.112 → 0.1.114

package/src/testing/test-recorder.test.ts

@@ -0,0 +1,415 @@
+import { describe, test, expect, beforeEach, afterEach } from "bun:test"
+import { createTestRenderer, type TestRenderer } from "./test-renderer.js"
+import { TestRecorder } from "./test-recorder.js"
+import { TextRenderable } from "../renderables/Text.js"
+
+describe("TestRecorder", () => {
+  let renderer: TestRenderer
+  let recorder: TestRecorder
+  let renderOnce: () => Promise<void>
+
+  beforeEach(async () => {
+    const setup = await createTestRenderer({ width: 80, height: 24 })
+    renderer = setup.renderer
+    renderOnce = setup.renderOnce
+    recorder = new TestRecorder(renderer)
+  })
+
+  afterEach(() => {
+    recorder.stop()
+    renderer.destroy()
+  })
+
+  test("should initialize with empty frames", () => {
+    expect(recorder.recordedFrames).toEqual([])
+    expect(recorder.isRecording).toBe(false)
+  })
+
+  test("should start recording", () => {
+    recorder.rec()
+    expect(recorder.isRecording).toBe(true)
+  })
+
+  test("should stop recording", () => {
+    recorder.rec()
+    expect(recorder.isRecording).toBe(true)
+    recorder.stop()
+    expect(recorder.isRecording).toBe(false)
+  })
+
+  test("should record frames during rendering", async () => {
+    recorder.rec()
+
+    const text = new TextRenderable(renderer, { content: "Hello World" })
+    renderer.root.add(text)
+    await Bun.sleep(1)
+
+    expect(recorder.recordedFrames.length).toBe(1)
+
+    await renderOnce()
+    expect(recorder.recordedFrames.length).toBe(2)
+
+    recorder.stop()
+  })
+
+  test("should capture frame content correctly", async () => {
+    recorder.rec()
+
+    const text = new TextRenderable(renderer, { content: "Test Content" })
+    renderer.root.add(text)
+    await Bun.sleep(1)
+
+    const frames = recorder.recordedFrames
+    expect(frames.length).toBe(1)
+    expect(frames[0].frame).toContain("Test Content")
+
+    recorder.stop()
+  })
+
+  test("should include frame metadata", async () => {
+    recorder.rec()
+
+    const text = new TextRenderable(renderer, { content: "Frame Metadata" })
+    renderer.root.add(text)
+    await Bun.sleep(1)
+
+    const frames = recorder.recordedFrames
+    expect(frames.length).toBe(1)
+    expect(frames[0].timestamp).toBeGreaterThanOrEqual(0)
+    expect(frames[0].frameNumber).toBe(0)
+
+    recorder.stop()
+  })
+
+  test("should increment frame numbers", async () => {
+    recorder.rec()
+
+    const text = new TextRenderable(renderer, { content: "Multiple Frames" })
+    renderer.root.add(text)
+    await Bun.sleep(1)
+
+    await renderOnce()
+    await renderOnce()
+
+    const frames = recorder.recordedFrames
+    expect(frames.length).toBe(3)
+    expect(frames[0].frameNumber).toBe(0)
+    expect(frames[1].frameNumber).toBe(1)
+    expect(frames[2].frameNumber).toBe(2)
+
+    recorder.stop()
+  })
+
+  test("should capture changing content across frames", async () => {
+    recorder.rec()
+
+    const text = new TextRenderable(renderer, { content: "Initial" })
+    renderer.root.add(text)
+    await Bun.sleep(10)
+
+    text.content = "Changed"
+    await Bun.sleep(10)
+    recorder.stop()
+
+    // NOTE: Should this fail, make sure the Bun.sleeps are in sync with maxFps of the renderer
+    const frame1 = recorder.recordedFrames[0].frame
+    const frame2 = recorder.recordedFrames[1].frame
+
+    expect(frame1).toContain("Initial")
+    expect(frame2).toContain("Changed")
+    expect(frame1).not.toEqual(frame2)
+  })
+
+  test("should not record when not started", async () => {
+    const text = new TextRenderable(renderer, { content: "Not Recording" })
+    renderer.root.add(text)
+    await Bun.sleep(1)
+
+    expect(recorder.recordedFrames.length).toBe(0)
+  })
+
+  test("should not record after stopped", async () => {
+    recorder.rec()
+
+    const text = new TextRenderable(renderer, { content: "Stopped" })
+    renderer.root.add(text)
+    await Bun.sleep(1)
+
+    expect(recorder.recordedFrames.length).toBe(1)
+
+    recorder.stop()
+    await renderOnce()
+    expect(recorder.recordedFrames.length).toBe(1)
+  })
+
+  test("should clear recorded frames", async () => {
+    recorder.rec()
+
+    const text = new TextRenderable(renderer, { content: "Clear Test" })
+    renderer.root.add(text)
+    await Bun.sleep(1)
+
+    await renderOnce()
+
+    expect(recorder.recordedFrames.length).toBe(2)
+    recorder.clear()
+    expect(recorder.recordedFrames.length).toBe(0)
+
+    recorder.stop()
+  })
+
+  test("should handle multiple rec/stop cycles", async () => {
+    const text = new TextRenderable(renderer, { content: "Cycle Test" })
+
+    recorder.rec()
+    renderer.root.add(text)
+    await Bun.sleep(1)
+    recorder.stop()
+    expect(recorder.recordedFrames.length).toBe(1)
+
+    recorder.clear()
+    recorder.rec()
+    await renderOnce()
+    await renderOnce()
+    recorder.stop()
+    expect(recorder.recordedFrames.length).toBe(2)
+  })
+
+  test("should not duplicate frames when rec is called multiple times", async () => {
+    recorder.rec()
+    recorder.rec()
+
+    const text = new TextRenderable(renderer, { content: "Duplicate Test" })
+    renderer.root.add(text)
+    await Bun.sleep(1)
+
+    recorder.stop()
+
+    expect(recorder.recordedFrames.length).toBe(1)
+  })
+
+  test("should restore original renderNative after stop", async () => {
+    const text = new TextRenderable(renderer, { content: "Restore Test" })
+
+    recorder.rec()
+    renderer.root.add(text)
+    await Bun.sleep(1)
+    recorder.stop()
+
+    recorder.clear()
+    await renderOnce()
+    expect(recorder.recordedFrames.length).toBe(0)
+
+    recorder.rec()
+    await renderOnce()
+    recorder.stop()
+    expect(recorder.recordedFrames.length).toBe(1)
+  })
+
+  test("should capture timestamps in increasing order", async () => {
+    let time = 0
+    recorder = new TestRecorder(renderer, { now: () => time })
+    recorder.rec()
+
+    await renderOnce()
+    time += 10
+    await renderOnce()
+
+    const frames = recorder.recordedFrames
+    expect(frames.length).toBe(2)
+    expect(frames[1].timestamp).toBeGreaterThan(frames[0].timestamp)
+    expect(frames[1].timestamp - frames[0].timestamp).toBe(10)
+
+    recorder.stop()
+  })
+
+  test("should return a copy of recorded frames", async () => {
+    recorder.rec()
+
+    const text = new TextRenderable(renderer, { content: "Copy Test" })
+    renderer.root.add(text)
+    await Bun.sleep(1)
+
+    const frames1 = recorder.recordedFrames
+    const frames2 = recorder.recordedFrames
+
+    expect(frames1).toEqual(frames2)
+    expect(frames1).not.toBe(frames2)
+
+    recorder.stop()
+  })
+
+  test("should handle empty renders", async () => {
+    recorder.rec()
+    await renderOnce()
+
+    expect(recorder.recordedFrames.length).toBe(1)
+    expect(recorder.recordedFrames[0].frame).toBeDefined()
+
+    recorder.stop()
+  })
+
+  test("should capture complex content", async () => {
+    recorder.rec()
+
+    const text1 = new TextRenderable(renderer, { content: "Line 1" })
+    const text2 = new TextRenderable(renderer, { content: "Line 2" })
+    renderer.root.add(text1)
+    renderer.root.add(text2)
+    await Bun.sleep(1)
+
+    const frame = recorder.recordedFrames[0].frame
+    expect(frame).toContain("Line 1")
+    expect(frame).toContain("Line 2")
+
+    recorder.stop()
+  })
+
+  test("should handle rapid render calls", async () => {
+    recorder.rec()
+
+    const text = new TextRenderable(renderer, { content: "Rapid Test" })
+    renderer.root.add(text)
+    await Bun.sleep(1)
+
+    for (let i = 0; i < 4; i++) {
+      await renderOnce()
+    }
+
+    expect(recorder.recordedFrames.length).toBe(5)
+
+    recorder.stop()
+  })
+
+  test("should optionally record fg buffer", async () => {
+    const recorderWithFg = new TestRecorder(renderer, { recordBuffers: { fg: true } })
+    recorderWithFg.rec()
+
+    const text = new TextRenderable(renderer, { content: "Buffer Test" })
+    renderer.root.add(text)
+    await Bun.sleep(1)
+
+    const frames = recorderWithFg.recordedFrames
+    expect(frames.length).toBe(1)
+    expect(frames[0].buffers).toBeDefined()
+    expect(frames[0].buffers?.fg).toBeInstanceOf(Float32Array)
+    expect(frames[0].buffers?.bg).toBeUndefined()
+    expect(frames[0].buffers?.attributes).toBeUndefined()
+
+    recorderWithFg.stop()
+  })
+
+  test("should optionally record bg buffer", async () => {
+    const recorderWithBg = new TestRecorder(renderer, { recordBuffers: { bg: true } })
+    recorderWithBg.rec()
+
+    const text = new TextRenderable(renderer, { content: "Buffer Test" })
+    renderer.root.add(text)
+    await Bun.sleep(1)
+
+    const frames = recorderWithBg.recordedFrames
+    expect(frames.length).toBe(1)
+    expect(frames[0].buffers).toBeDefined()
+    expect(frames[0].buffers?.bg).toBeInstanceOf(Float32Array)
+    expect(frames[0].buffers?.fg).toBeUndefined()
+    expect(frames[0].buffers?.attributes).toBeUndefined()
+
+    recorderWithBg.stop()
+  })
+
+  test("should optionally record attributes buffer", async () => {
+    const recorderWithAttrs = new TestRecorder(renderer, { recordBuffers: { attributes: true } })
+    recorderWithAttrs.rec()
+
+    const text = new TextRenderable(renderer, { content: "Buffer Test" })
+    renderer.root.add(text)
+    await Bun.sleep(1)
+
+    const frames = recorderWithAttrs.recordedFrames
+    expect(frames.length).toBe(1)
+    expect(frames[0].buffers).toBeDefined()
+    expect(frames[0].buffers?.attributes).toBeInstanceOf(Uint8Array)
+    expect(frames[0].buffers?.fg).toBeUndefined()
+    expect(frames[0].buffers?.bg).toBeUndefined()
+
+    recorderWithAttrs.stop()
+  })
+
+  test("should record multiple buffers when requested", async () => {
+    const recorderWithAll = new TestRecorder(renderer, {
+      recordBuffers: { fg: true, bg: true, attributes: true },
+    })
+    recorderWithAll.rec()
+
+    const text = new TextRenderable(renderer, { content: "Buffer Test" })
+    renderer.root.add(text)
+    await Bun.sleep(1)
+
+    const frames = recorderWithAll.recordedFrames
+    expect(frames.length).toBe(1)
+    expect(frames[0].buffers).toBeDefined()
+    expect(frames[0].buffers?.fg).toBeInstanceOf(Float32Array)
+    expect(frames[0].buffers?.bg).toBeInstanceOf(Float32Array)
+    expect(frames[0].buffers?.attributes).toBeInstanceOf(Uint8Array)
+
+    recorderWithAll.stop()
+  })
+
+  test("should not record buffers when not requested", async () => {
+    recorder.rec()
+
+    const text = new TextRenderable(renderer, { content: "No Buffer Test" })
+    renderer.root.add(text)
+    await Bun.sleep(1)
+
+    const frames = recorder.recordedFrames
+    expect(frames.length).toBe(1)
+    expect(frames[0].buffers).toBeUndefined()
+
+    recorder.stop()
+  })
+
+  test("should record independent buffer copies", async () => {
+    const recorderWithBuffers = new TestRecorder(renderer, { recordBuffers: { fg: true } })
+    recorderWithBuffers.rec()
+
+    const text = new TextRenderable(renderer, { content: "Copy Test" })
+    renderer.root.add(text)
+    await Bun.sleep(1)
+
+    await renderOnce()
+
+    const frames = recorderWithBuffers.recordedFrames
+    expect(frames.length).toBe(2)
+
+    const frame1Fg = frames[0].buffers?.fg
+    const frame2Fg = frames[1].buffers?.fg
+
+    expect(frame1Fg).toBeDefined()
+    expect(frame2Fg).toBeDefined()
+    expect(frame1Fg).not.toBe(frame2Fg)
+
+    recorderWithBuffers.stop()
+  })
+
+  test("should have correct buffer sizes", async () => {
+    const recorderWithAll = new TestRecorder(renderer, {
+      recordBuffers: { fg: true, bg: true, attributes: true },
+    })
+    recorderWithAll.rec()
+
+    const text = new TextRenderable(renderer, { content: "Size Test" })
+    renderer.root.add(text)
+    await Bun.sleep(1)
+
+    const frames = recorderWithAll.recordedFrames
+    expect(frames.length).toBe(1)
+
+    const expectedSize = renderer.width * renderer.height
+    expect(frames[0].buffers?.fg?.length).toBe(expectedSize * 4)
+    expect(frames[0].buffers?.bg?.length).toBe(expectedSize * 4)
+    expect(frames[0].buffers?.attributes?.length).toBe(expectedSize)
+
+    recorderWithAll.stop()
+  })
+})

package/src/testing/test-recorder.ts

@@ -0,0 +1,145 @@
+import type { TestRenderer } from "./test-renderer.js"
+
+export interface RecordBuffersOptions {
+  fg?: boolean
+  bg?: boolean
+  attributes?: boolean
+}
+
+export interface RecordedBuffers {
+  fg?: Float32Array
+  bg?: Float32Array
+  attributes?: Uint8Array
+}
+
+export interface RecordedFrame {
+  frame: string
+  timestamp: number
+  frameNumber: number
+  buffers?: RecordedBuffers
+}
+
+export interface TestRecorderOptions {
+  recordBuffers?: RecordBuffersOptions
+  now?: () => number
+}
+
+/**
+ * TestRecorder records frames from a TestRenderer by hooking into the render pipeline.
+ * It captures the character frame after each native render pass.
+ */
+export class TestRecorder {
+  private renderer: TestRenderer
+  private frames: RecordedFrame[] = []
+  private recording: boolean = false
+  private frameNumber: number = 0
+  private startTime: number = 0
+  private originalRenderNative?: () => void
+  private decoder = new TextDecoder()
+  private recordBuffers: RecordBuffersOptions
+  private now: () => number
+
+  constructor(renderer: TestRenderer, options?: TestRecorderOptions) {
+    this.renderer = renderer
+    this.recordBuffers = options?.recordBuffers || {}
+    this.now = options?.now ?? (() => performance.now())
+  }
+
+  /**
+   * Start recording frames. This hooks into the renderer's renderNative method.
+   */
+  public rec(): void {
+    if (this.recording) {
+      return
+    }
+
+    this.recording = true
+    this.frames = []
+    this.frameNumber = 0
+    this.startTime = this.now()
+
+    // Store the original renderNative method
+    this.originalRenderNative = this.renderer["renderNative"].bind(this.renderer)
+
+    // Override renderNative to capture frames after each render
+    this.renderer["renderNative"] = () => {
+      // Call the original renderNative
+      this.originalRenderNative!()
+
+      // Capture the frame after rendering
+      this.captureFrame()
+    }
+  }
+
+  /**
+   * Stop recording frames and restore the original renderNative method.
+   */
+  public stop(): void {
+    if (!this.recording) {
+      return
+    }
+
+    this.recording = false
+
+    // Restore the original renderNative method
+    if (this.originalRenderNative) {
+      this.renderer["renderNative"] = this.originalRenderNative
+      this.originalRenderNative = undefined
+    }
+  }
+
+  /**
+   * Get the recorded frames.
+   */
+  public get recordedFrames(): RecordedFrame[] {
+    return [...this.frames]
+  }
+
+  /**
+   * Clear all recorded frames.
+   */
+  public clear(): void {
+    this.frames = []
+    this.frameNumber = 0
+  }
+
+  /**
+   * Check if currently recording.
+   */
+  public get isRecording(): boolean {
+    return this.recording
+  }
+
+  /**
+   * Capture the current frame from the renderer's buffer.
+   */
+  private captureFrame(): void {
+    const currentBuffer = this.renderer.currentRenderBuffer
+    const frameBytes = currentBuffer.getRealCharBytes(true)
+    const frame = this.decoder.decode(frameBytes)
+
+    const recordedFrame: RecordedFrame = {
+      frame,
+      timestamp: this.now() - this.startTime,
+      frameNumber: this.frameNumber++,
+    }
+
+    // Optionally record buffer data from currentRenderBuffer
+    if (this.recordBuffers.fg || this.recordBuffers.bg || this.recordBuffers.attributes) {
+      const buffers = currentBuffer.buffers
+      recordedFrame.buffers = {}
+
+      if (this.recordBuffers.fg) {
+        recordedFrame.buffers.fg = new Float32Array(buffers.fg)
+      }
+      if (this.recordBuffers.bg) {
+        recordedFrame.buffers.bg = new Float32Array(buffers.bg)
+      }
+      if (this.recordBuffers.attributes) {
+        recordedFrame.buffers.attributes = new Uint8Array(buffers.attributes)
+      }
+    }
+
+    this.frames.push(recordedFrame)
+  }
+}

package/src/testing/test-renderer.ts

@@ -0,0 +1,132 @@
+import { Readable, Writable } from "stream"
+import { CliRenderer, type CliRendererConfig } from "../renderer.js"
+import { resolveRenderLib } from "../zig.js"
+import { createMockKeys } from "./mock-keys.js"
+import { createMockMouse } from "./mock-mouse.js"
+import type { CapturedFrame } from "../types.js"
+
+export interface TestRendererOptions extends CliRendererConfig {
+  width?: number
+  height?: number
+  kittyKeyboard?: boolean
+  otherModifiersMode?: boolean
+}
+export interface TestRenderer extends CliRenderer {}
+export type MockInput = ReturnType<typeof createMockKeys>
+export type MockMouse = ReturnType<typeof createMockMouse>
+
+const decoder = new TextDecoder()
+
+class TestWriteStream extends Writable {
+  public readonly isTTY = true
+  public readonly columns: number
+  public readonly rows: number
+
+  constructor(columns: number, rows: number) {
+    super()
+    this.columns = columns
+    this.rows = rows
+  }
+
+  _write(_chunk: any, _encoding: BufferEncoding, callback: (error?: Error | null) => void): void {
+    callback()
+  }
+
+  getColorDepth(): number {
+    return 24
+  }
+}
+
+export async function createTestRenderer(options: TestRendererOptions): Promise<{
+  renderer: TestRenderer
+  mockInput: MockInput
+  mockMouse: MockMouse
+  renderOnce: () => Promise<void>
+  captureCharFrame: () => string
+  captureSpans: () => CapturedFrame
+  resize: (width: number, height: number) => void
+}> {
+  // Convert legacy kittyKeyboard boolean to new format
+  const useKittyKeyboard = options.kittyKeyboard ? { events: true } : options.useKittyKeyboard
+
+  const renderer = await setupTestRenderer({
+    ...options,
+    useKittyKeyboard,
+    screenMode: options.screenMode ?? "main-screen",
+    footerHeight: options.footerHeight ?? 12,
+    consoleMode: options.consoleMode ?? "disabled",
+    externalOutputMode: options.externalOutputMode ?? "passthrough",
+  })
+
+  const mockInput = createMockKeys(renderer, {
+    kittyKeyboard: options.kittyKeyboard,
+    otherModifiersMode: options.otherModifiersMode,
+  })
+  const mockMouse = createMockMouse(renderer)
+
+  const renderOnce = async () => {
+    //@ts-expect-error - this is a test renderer
+    await renderer.loop()
+  }
+
+  return {
+    renderer,
+    mockInput,
+    mockMouse,
+    renderOnce,
+    captureCharFrame: () => {
+      const currentBuffer = renderer.currentRenderBuffer
+      const frameBytes = currentBuffer.getRealCharBytes(true)
+      return decoder.decode(frameBytes)
+    },
+    captureSpans: () => {
+      const currentBuffer = renderer.currentRenderBuffer
+      const lines = currentBuffer.getSpanLines()
+      const cursorState = renderer.getCursorState()
+      return {
+        cols: currentBuffer.width,
+        rows: currentBuffer.height,
+        cursor: [cursorState.x, cursorState.y] as [number, number],
+        lines,
+      }
+    },
+    resize: (width: number, height: number) => {
+      //@ts-expect-error - this is a test renderer
+      renderer.processResize(width, height)
+    },
+  }
+}
+
+async function setupTestRenderer(config: TestRendererOptions) {
+  const stdin = config.stdin || (new Readable({ read() {} }) as NodeJS.ReadStream)
+  const width = config.width || config.stdout?.columns || process.stdout.columns || 80
+  const height = config.height || config.stdout?.rows || process.stdout.rows || 24
+  const stdout = config.stdout || (new TestWriteStream(width, height) as unknown as NodeJS.WriteStream)
+  const renderHeight = config.screenMode === "split-footer" ? (config.footerHeight ?? 12) : height
+
+  const ziglib = resolveRenderLib()
+  const rendererPtr = ziglib.createRenderer(width, renderHeight, {
+    testing: true,
+    remote: config.remote ?? false,
+  })
+  if (!rendererPtr) {
+    throw new Error("Failed to create test renderer")
+  }
+  if (config.useThread === undefined) {
+    config.useThread = true
+  }
+
+  if (process.platform === "linux") {
+    config.useThread = false
+  }
+  ziglib.setUseThread(rendererPtr, config.useThread)
+
+  const renderer = new CliRenderer(ziglib, rendererPtr, stdin, stdout, width, height, config)
+
+  process.off("SIGWINCH", renderer["sigwinchHandler"])
+
+  // Do not setup the terminal for testing as we will not actually output anything to the terminal
+  // await renderer.setupTerminal()
+
+  return renderer
+}

package/src/testing.ts

@@ -0,0 +1,7 @@
+// Testing utilities module exports
+export * from "./testing/test-renderer.js"
+export * from "./testing/mock-keys.js"
+export * from "./testing/mock-mouse.js"
+export * from "./testing/mock-tree-sitter-client.js"
+export * from "./testing/spy.js"
+export { TestRecorder, type RecordedFrame } from "./testing/test-recorder.js"