@xincli/opentui-core 0.4.6 → 0.4.7

package/src/testing/test-renderer.ts

@@ -1,375 +0,0 @@
-import {
-  CliRenderer,
-  CliRenderEvents,
-  type CliRendererConfig,
-  type CliRendererExternalOutputEvent,
-  type CliRendererFrameEvent,
-} from "../renderer.js"
-import type { NativeSpanFeed } from "../NativeSpanFeed.js"
-import type { NativeRenderStats } from "../zig.js"
-import { createMockKeys } from "./mock-keys.js"
-import { createMockMouse } from "./mock-mouse.js"
-import { createTestStdin, createTestStdout } from "./test-streams.js"
-import type { CapturedFrame } from "../types.js"
-
-export interface TestRendererOptions extends CliRendererConfig {
-  width?: number
-  height?: number
-  kittyKeyboard?: boolean
-  otherModifiersMode?: boolean
-}
-export type TestRenderer = CliRenderer
-export type MockInput = ReturnType<typeof createMockKeys>
-export type MockMouse = ReturnType<typeof createMockMouse>
-
-type RendererFeedAccess = {
-  _feed?: NativeSpanFeed | null
-}
-
-export interface TestFlushOptions {
-  maxPasses?: number
-}
-
-export interface TestVisualIdleOptions {
-  quietFrames?: number
-  maxFrames?: number
-}
-
-export interface TestWaitForOptions {
-  maxPasses?: number
-}
-
-export interface TestExternalOutputCommit {
-  text: string
-  rows: string[]
-  width: number
-  height: number
-  rowColumns: number
-  startOnNewLine: boolean
-  trailingNewline: boolean
-}
-
-export interface TestExternalOutput {
-  take(): TestExternalOutputCommit[]
-  takeText(): string
-  clear(): void
-}
-
-export interface TestRendererSetup {
-  renderer: TestRenderer
-  mockInput: MockInput
-  mockMouse: MockMouse
-  renderOnce: () => Promise<void>
-  flush: (options?: TestFlushOptions) => Promise<void>
-  waitFor: (predicate: () => boolean | Promise<boolean>, options?: TestWaitForOptions) => Promise<void>
-  waitForFrame: (
-    predicate: (frame: string) => boolean | Promise<boolean>,
-    options?: TestWaitForOptions,
-  ) => Promise<string>
-  waitForVisualIdle: (options?: TestVisualIdleOptions) => Promise<void>
-  externalOutput: TestExternalOutput
-  getNativeStats: () => NativeRenderStats
-  captureCharFrame: () => string
-  captureSpans: () => CapturedFrame
-  resize: (width: number, height: number) => void
-}
-
-const decoder = new TextDecoder()
-const DEFAULT_MAX_PASSES = 20
-const DEFAULT_MAX_VISUAL_IDLE_FRAMES = 20
-const DEFAULT_QUIET_FRAMES = 1
-
-async function drainImmediateWork(): Promise<void> {
-  await Promise.resolve()
-  await new Promise<void>((resolve) => process.nextTick(resolve))
-  await Promise.resolve()
-}
-
-function normalizePositiveInteger(value: number | undefined, fallback: number): number {
-  if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
-    return fallback
-  }
-
-  return Math.floor(value)
-}
-
-function createWaitError(renderer: TestRenderer, message: string, frame?: string): Error {
-  const stats = renderer.getStats()
-  const scheduler = renderer.getSchedulerState()
-  const details = [
-    message,
-    `frameId: ${renderer.frameId}`,
-    `nativeFrameCount: ${stats.nativeFrameCount}`,
-    `cellsUpdated: ${stats.cellsUpdated}`,
-    `isRunning: ${scheduler.isRunning}`,
-    `isRendering: ${scheduler.isRendering}`,
-    `hasScheduledRender: ${scheduler.hasScheduledRender}`,
-  ]
-
-  if (frame !== undefined) {
-    details.push(`lastFrame:\n${frame}`)
-  }
-
-  return new Error(details.join("\n"))
-}
-
-class TestExternalOutputRecorder implements TestExternalOutput {
-  private commits: TestExternalOutputCommit[] = []
-
-  constructor(renderer: TestRenderer) {
-    renderer.on(CliRenderEvents.EXTERNAL_OUTPUT, this.record)
-    renderer.once(CliRenderEvents.DESTROY, () => {
-      renderer.off(CliRenderEvents.EXTERNAL_OUTPUT, this.record)
-    })
-  }
-
-  private record = (event: CliRendererExternalOutputEvent): void => {
-    const raw = decoder.decode(event.snapshot.getRealCharBytes(false))
-    const rows = Array.from({ length: event.snapshot.height }, (_, index) =>
-      raw.slice(index * event.snapshot.width, (index + 1) * event.snapshot.width).trimEnd(),
-    )
-
-    this.commits.push({
-      text: rows.join("\n"),
-      rows,
-      width: event.snapshot.width,
-      height: event.snapshot.height,
-      rowColumns: event.rowColumns,
-      startOnNewLine: event.startOnNewLine,
-      trailingNewline: event.trailingNewline,
-    })
-  }
-
-  public take(): TestExternalOutputCommit[] {
-    const commits = this.commits
-    this.commits = []
-    return commits
-  }
-
-  public takeText(): string {
-    return this.take()
-      .flatMap((commit) => commit.rows)
-      .join("\n")
-  }
-
-  public clear(): void {
-    this.commits = []
-  }
-}
-
-function waitForNextFrameOrIdle(renderer: TestRenderer): Promise<CliRendererFrameEvent | null> {
-  const scheduler = renderer.getSchedulerState()
-  if (!scheduler.isRunning && !scheduler.isRendering && !scheduler.hasScheduledRender) {
-    return Promise.resolve(null)
-  }
-
-  return new Promise((resolve) => {
-    let settled = false
-
-    const cleanup = () => {
-      renderer.off(CliRenderEvents.FRAME, onFrame)
-      renderer.off(CliRenderEvents.DESTROY, onDestroy)
-    }
-
-    const finish = (event: CliRendererFrameEvent | null) => {
-      if (settled) return
-      settled = true
-      cleanup()
-      resolve(event)
-    }
-
-    const onFrame = (event: CliRendererFrameEvent) => {
-      finish(event)
-    }
-
-    const onDestroy = () => {
-      finish(null)
-    }
-
-    renderer.on(CliRenderEvents.FRAME, onFrame)
-    renderer.once(CliRenderEvents.DESTROY, onDestroy)
-
-    if (!scheduler.isRunning) {
-      renderer.idle().then(() => finish(null))
-    }
-  })
-}
-
-export async function createTestRenderer(options: TestRendererOptions): Promise<TestRendererSetup> {
-  // 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 externalOutput = new TestExternalOutputRecorder(renderer)
-
-  const mockInput = createMockKeys(renderer, {
-    kittyKeyboard: options.kittyKeyboard,
-    otherModifiersMode: options.otherModifiersMode,
-  })
-  const mockMouse = createMockMouse(renderer)
-
-  const renderOnce = async () => {
-    const feed = (renderer as unknown as RendererFeedAccess)._feed
-    if (feed?.isBackpressured()) {
-      await feed.idle()
-    }
-    //@ts-expect-error - this is a test renderer
-    await renderer.loop()
-  }
-
-  const captureCharFrame = () => {
-    const currentBuffer = renderer.currentRenderBuffer
-    const frameBytes = currentBuffer.getRealCharBytes(true)
-    return decoder.decode(frameBytes)
-  }
-
-  const waitForVisualIdle = async (waitOptions: TestVisualIdleOptions = {}): Promise<void> => {
-    const maxFrames = normalizePositiveInteger(waitOptions.maxFrames, DEFAULT_MAX_VISUAL_IDLE_FRAMES)
-    const quietFrames = normalizePositiveInteger(waitOptions.quietFrames, DEFAULT_QUIET_FRAMES)
-    let consecutiveQuietFrames = 0
-
-    for (let frame = 0; frame < maxFrames; frame++) {
-      await drainImmediateWork()
-
-      const scheduler = renderer.getSchedulerState()
-      if (!scheduler.isRunning && !scheduler.isRendering && !scheduler.hasScheduledRender) {
-        return
-      }
-
-      const event = await waitForNextFrameOrIdle(renderer)
-      if (!event) {
-        return
-      }
-
-      if (renderer.getNativeStats().cellsUpdated === 0) {
-        consecutiveQuietFrames++
-        if (consecutiveQuietFrames >= quietFrames) {
-          return
-        }
-      } else {
-        consecutiveQuietFrames = 0
-      }
-    }
-
-    await drainImmediateWork()
-    const scheduler = renderer.getSchedulerState()
-    if (!scheduler.isRunning && !scheduler.isRendering && !scheduler.hasScheduledRender) {
-      return
-    }
-
-    throw createWaitError(renderer, `Timed out waiting for visual idle after ${maxFrames} frames`)
-  }
-
-  const flush = async (flushOptions: TestFlushOptions = {}): Promise<void> => {
-    await waitForVisualIdle({ maxFrames: normalizePositiveInteger(flushOptions.maxPasses, DEFAULT_MAX_PASSES) })
-  }
-
-  const waitFor = async (
-    predicate: () => boolean | Promise<boolean>,
-    waitOptions: TestWaitForOptions = {},
-  ): Promise<void> => {
-    const maxPasses = normalizePositiveInteger(waitOptions.maxPasses, DEFAULT_MAX_PASSES)
-
-    for (let pass = 0; pass <= maxPasses; pass++) {
-      await drainImmediateWork()
-      if (await predicate()) {
-        return
-      }
-
-      if (pass === maxPasses) {
-        break
-      }
-
-      const scheduler = renderer.getSchedulerState()
-      if (!scheduler.isRunning && !scheduler.isRendering && !scheduler.hasScheduledRender) {
-        break
-      }
-
-      await waitForNextFrameOrIdle(renderer)
-    }
-
-    throw createWaitError(renderer, `Timed out waiting for predicate after ${maxPasses} passes`)
-  }
-
-  const waitForFrame = async (
-    predicate: (frame: string) => boolean | Promise<boolean>,
-    waitOptions: TestWaitForOptions = {},
-  ): Promise<string> => {
-    const maxPasses = normalizePositiveInteger(waitOptions.maxPasses, DEFAULT_MAX_PASSES)
-    let frame = captureCharFrame()
-
-    for (let pass = 0; pass <= maxPasses; pass++) {
-      await drainImmediateWork()
-      frame = captureCharFrame()
-      if (await predicate(frame)) {
-        return frame
-      }
-
-      if (pass === maxPasses) {
-        break
-      }
-
-      const scheduler = renderer.getSchedulerState()
-      if (!scheduler.isRunning && !scheduler.isRendering && !scheduler.hasScheduledRender) {
-        break
-      }
-
-      await waitForNextFrameOrIdle(renderer)
-    }
-
-    frame = captureCharFrame()
-    throw createWaitError(renderer, `Timed out waiting for frame predicate after ${maxPasses} passes`, frame)
-  }
-
-  return {
-    renderer,
-    mockInput,
-    mockMouse,
-    renderOnce,
-    flush,
-    waitFor,
-    waitForFrame,
-    waitForVisualIdle,
-    externalOutput,
-    getNativeStats: () => renderer.getNativeStats(),
-    captureCharFrame,
-    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 || createTestStdin()
-  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 || createTestStdout(width, height)
-
-  // Direct construction skips setupTerminal(); native bytes are routed to an
-  // explicit memory destination so tests do not depend on process stdout or feed
-  // backpressure behavior. CliRenderer still owns native renderer creation and
-  // applies the same useThread defaults as production construction.
-  return new CliRenderer(stdin, stdout, width, height, {
-    ...config,
-    bufferedOutput: config.bufferedOutput ?? "memory",
-  })
-}

package/src/testing/test-renderer.wait.test.ts

@@ -1,278 +0,0 @@
-import { afterEach, expect, spyOn, test } from "bun:test"
-import { CliRenderEvents } from "../renderer.js"
-import { TextRenderable } from "../renderables/Text.js"
-import { ManualClock } from "./manual-clock.js"
-import { createTestRenderer, type TestRendererSetup } from "./test-renderer.js"
-
-let setup: TestRendererSetup | null = null
-
-async function drainImmediateWork(): Promise<void> {
-  await Promise.resolve()
-  await new Promise<void>((resolve) => process.nextTick(resolve))
-  await Promise.resolve()
-}
-
-afterEach(() => {
-  setup?.renderer.destroy()
-  setup = null
-})
-
-test("flush waits for scheduled render work without forcing an extra frame", async () => {
-  setup = await createTestRenderer({ width: 10, height: 4, useThread: false, maxFps: Number.POSITIVE_INFINITY })
-
-  const text = new TextRenderable(setup.renderer, {
-    content: "abc",
-    width: 3,
-    height: 1,
-  })
-  setup.renderer.root.add(text)
-
-  await setup.flush({ maxPasses: 1 })
-
-  const renderedStats = setup.getNativeStats()
-  expect(renderedStats.nativeFrameCount).toBe(1)
-  expect(renderedStats.cellsUpdated).toBeGreaterThanOrEqual(3)
-
-  await setup.flush()
-
-  expect(setup.getNativeStats().nativeFrameCount).toBe(1)
-})
-
-test("waitForFrame observes text from a scheduled render", async () => {
-  setup = await createTestRenderer({ width: 10, height: 4, useThread: false, maxFps: Number.POSITIVE_INFINITY })
-
-  const text = new TextRenderable(setup.renderer, {
-    content: "hello",
-    width: 5,
-    height: 1,
-  })
-  setup.renderer.root.add(text)
-
-  const frame = await setup.waitForFrame((value) => value.includes("hello"), { maxPasses: 1 })
-
-  expect(frame).toContain("hello")
-  expect(setup.getNativeStats().nativeFrameCount).toBe(1)
-})
-
-test("waitFor observes predicate changes after scheduled work", async () => {
-  setup = await createTestRenderer({ width: 10, height: 4, useThread: false, maxFps: Number.POSITIVE_INFINITY })
-
-  const text = new TextRenderable(setup.renderer, {
-    content: "ready",
-    width: 5,
-    height: 1,
-  })
-  setup.renderer.root.add(text)
-
-  await setup.waitFor(() => setup!.getNativeStats().nativeFrameCount > 0, { maxPasses: 1 })
-
-  expect(setup.getNativeStats().nativeFrameCount).toBe(1)
-})
-
-test("renderer does not build frame event stats when no frame listener is registered", async () => {
-  setup = await createTestRenderer({ width: 10, height: 4, useThread: false })
-
-  const getStats = spyOn(setup.renderer, "getStats")
-
-  const text = new TextRenderable(setup.renderer, {
-    content: "quiet",
-    width: 5,
-    height: 1,
-  })
-  setup.renderer.root.add(text)
-
-  await setup.renderOnce()
-
-  expect(getStats).not.toHaveBeenCalled()
-  getStats.mockRestore()
-})
-
-test("renderer emits frame event without building stats when a frame listener is registered", async () => {
-  setup = await createTestRenderer({ width: 10, height: 4, useThread: false })
-
-  const getStats = spyOn(setup.renderer, "getStats")
-  let frameEventCount = 0
-  let frameEvent: unknown
-  setup.renderer.on(CliRenderEvents.FRAME, (event) => {
-    frameEventCount++
-    frameEvent = event
-  })
-
-  const text = new TextRenderable(setup.renderer, {
-    content: "event",
-    width: 5,
-    height: 1,
-  })
-  setup.renderer.root.add(text)
-
-  await setup.renderOnce()
-
-  expect(frameEventCount).toBe(1)
-  expect(frameEvent).toEqual({ frameId: setup.renderer.frameId })
-  expect(getStats).not.toHaveBeenCalled()
-  getStats.mockRestore()
-})
-
-test("waitForFrame fails instead of rendering when no work is pending", async () => {
-  setup = await createTestRenderer({ width: 10, height: 4, useThread: false, maxFps: Number.POSITIVE_INFINITY })
-
-  await expect(setup.waitForFrame((frame) => frame.includes("missing"), { maxPasses: 2 })).rejects.toThrow(
-    "hasScheduledRender: false",
-  )
-
-  expect(setup.getNativeStats().nativeFrameCount).toBe(0)
-})
-
-test("waitForVisualIdle observes a naturally emitted zero-cell live frame", async () => {
-  const clock = new ManualClock()
-  setup = await createTestRenderer({
-    width: 10,
-    height: 4,
-    useThread: false,
-    clock,
-    maxFps: Number.POSITIVE_INFINITY,
-    targetFps: Number.POSITIVE_INFINITY,
-  })
-
-  const text = new TextRenderable(setup.renderer, {
-    content: "live",
-    width: 4,
-    height: 1,
-  })
-  setup.renderer.root.add(text)
-  setup.renderer.start()
-
-  await drainImmediateWork()
-  expect(setup.getNativeStats().nativeFrameCount).toBe(1)
-
-  const idle = setup.waitForVisualIdle({ maxFrames: 2 })
-  await drainImmediateWork()
-  clock.advance(1)
-  await idle
-
-  const stats = setup.getNativeStats()
-  expect(stats.nativeFrameCount).toBe(2)
-  expect(stats.cellsUpdated).toBe(0)
-
-  setup.renderer.stop()
-})
-
-test("externalOutput records writeToScrollback commits without consuming native queue", async () => {
-  setup = await createTestRenderer({
-    width: 10,
-    height: 6,
-    screenMode: "split-footer",
-    footerHeight: 3,
-    externalOutputMode: "capture-stdout",
-    consoleMode: "disabled",
-    useThread: false,
-    maxFps: Number.POSITIVE_INFINITY,
-  })
-
-  setup.renderer.writeToScrollback((ctx) => {
-    const root = new TextRenderable(ctx.renderContext, {
-      content: "hello\nworld",
-      width: 5,
-      height: 2,
-    })
-
-    return {
-      root,
-      width: 5,
-      height: 2,
-      trailingNewline: false,
-    }
-  })
-
-  const commits = setup.externalOutput.take()
-
-  expect(commits).toHaveLength(1)
-  expect(commits[0]).toMatchObject({
-    text: "hello\nworld",
-    rows: ["hello", "world"],
-    width: 5,
-    height: 2,
-    rowColumns: 5,
-    startOnNewLine: true,
-    trailingNewline: false,
-  })
-  expect((setup.renderer as any).externalOutputQueue.size).toBe(1)
-
-  await setup.renderOnce()
-
-  expect((setup.renderer as any).externalOutputQueue.size).toBe(0)
-  expect(setup.externalOutput.take()).toEqual([])
-})
-
-test("externalOutput records scrollback surface commits", async () => {
-  setup = await createTestRenderer({
-    width: 10,
-    height: 6,
-    screenMode: "split-footer",
-    footerHeight: 3,
-    externalOutputMode: "capture-stdout",
-    consoleMode: "disabled",
-    useThread: false,
-  })
-
-  const surface = setup.renderer.createScrollbackSurface()
-  const text = new TextRenderable(surface.renderContext, {
-    content: "surface",
-    width: 7,
-    height: 1,
-  })
-
-  surface.root.add(text)
-  surface.render()
-  surface.commitRows(0, 1, { trailingNewline: false })
-
-  const commits = setup.externalOutput.take()
-
-  expect(commits).toHaveLength(1)
-  expect(commits[0]).toMatchObject({
-    text: "surface",
-    rows: ["surface"],
-    width: 10,
-    height: 1,
-    rowColumns: 10,
-    startOnNewLine: true,
-    trailingNewline: false,
-  })
-})
-
-test("externalOutput records captured stdout in FIFO order", async () => {
-  setup = await createTestRenderer({
-    width: 10,
-    height: 6,
-    screenMode: "split-footer",
-    footerHeight: 3,
-    externalOutputMode: "capture-stdout",
-    consoleMode: "disabled",
-    useThread: false,
-  })
-
-  setup.renderer.writeToScrollback((ctx) => {
-    const root = new TextRenderable(ctx.renderContext, {
-      content: "api",
-      width: 3,
-      height: 1,
-    })
-
-    return {
-      root,
-      width: 3,
-      height: 1,
-    }
-  })
-  ;(setup.renderer as any).stdout.write("out-1\n\nout-2")
-
-  const commits = setup.externalOutput.take()
-
-  expect(commits.map((commit) => commit.text)).toEqual(["api", "out-1", "", "out-2"])
-  expect(commits.map((commit) => commit.startOnNewLine)).toEqual([true, false, false, false])
-  expect(commits.map((commit) => commit.trailingNewline)).toEqual([true, true, true, false])
-
-  ;(setup.renderer as any).stdout.write("again")
-  expect(setup.externalOutput.takeText()).toBe("again")
-  expect(setup.externalOutput.take()).toEqual([])
-})

package/src/testing/test-streams.ts

@@ -1,31 +0,0 @@
-import { Readable, Writable } from "stream"
-
-export class TestWriteStream extends Writable {
-  public readonly isTTY = true
-  public readonly columns: number
-  public readonly rows: number
-
-  constructor(columns = 80, rows = 24) {
-    super()
-    this.columns = columns
-    this.rows = rows
-  }
-
-  override _write(_chunk: any, _encoding: BufferEncoding, callback: (error?: Error | null) => void): void {
-    callback()
-  }
-
-  getColorDepth(): number {
-    return 24
-  }
-}
-
-export type TestStdout = TestWriteStream & NodeJS.WriteStream
-
-export function createTestStdin(): NodeJS.ReadStream {
-  return new Readable({ read() {} }) as NodeJS.ReadStream
-}
-
-export function createTestStdout(columns = 80, rows = 24): NodeJS.WriteStream {
-  return new TestWriteStream(columns, rows) as TestStdout
-}

package/src/testing.ts

@@ -1,9 +0,0 @@
-// 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/terminal-capabilities.js"
-export * from "./testing/spy.js"
-export { ManualClock } from "./testing/manual-clock.js"
-export { TestRecorder, type RecordedFrame } from "./testing/test-recorder.js"