@xincli/opentui-core 0.4.6

package/src/tests/audio.test.ts

@@ -0,0 +1,303 @@
+import { afterEach, expect, test } from "bun:test"
+import { Audio } from "../audio.js"
+import { resolveRenderLib } from "../zig.js"
+
+const SAMPLE_RATE = 48_000
+
+function buildPcm16Wav(samples: number[], channels: number): Uint8Array {
+  if (channels <= 0 || samples.length % channels !== 0) {
+    throw new Error(`Invalid PCM payload for channel count ${channels}`)
+  }
+
+  const bitsPerSample = 16
+  const bytesPerSample = bitsPerSample / 8
+  const frameCount = samples.length / channels
+  const dataSize = frameCount * channels * bytesPerSample
+  const byteRate = SAMPLE_RATE * channels * bytesPerSample
+  const blockAlign = channels * bytesPerSample
+  const totalSize = 44 + dataSize
+  const out = new Uint8Array(totalSize)
+  const view = new DataView(out.buffer)
+
+  out.set([0x52, 0x49, 0x46, 0x46], 0) // RIFF
+  view.setUint32(4, totalSize - 8, true)
+  out.set([0x57, 0x41, 0x56, 0x45], 8) // WAVE
+  out.set([0x66, 0x6d, 0x74, 0x20], 12) // fmt
+  view.setUint32(16, 16, true)
+  view.setUint16(20, 1, true) // PCM
+  view.setUint16(22, channels, true)
+  view.setUint32(24, SAMPLE_RATE, true)
+  view.setUint32(28, byteRate, true)
+  view.setUint16(32, blockAlign, true)
+  view.setUint16(34, bitsPerSample, true)
+  out.set([0x64, 0x61, 0x74, 0x61], 36) // data
+  view.setUint32(40, dataSize, true)
+
+  for (let i = 0; i < samples.length; i += 1) {
+    const clamped = Math.max(-1, Math.min(1, samples[i]))
+    view.setInt16(44 + i * 2, Math.round(clamped * 32767), true)
+  }
+
+  return out
+}
+
+function buildMonoPcm16Wav(samples: number[]): Uint8Array {
+  return buildPcm16Wav(samples, 1)
+}
+
+const instances: Audio[] = []
+
+afterEach(() => {
+  for (const instance of instances.splice(0)) {
+    instance.dispose()
+  }
+})
+
+test("Audio loads wav and mixes frames", () => {
+  const audio = Audio.create({ autoStart: false })
+  instances.push(audio)
+
+  const wav = buildMonoPcm16Wav([0, 0.25, -0.25, 0.5, -0.5, 0])
+  const sound = audio.loadSound(wav)
+  const sfx = audio.group("sfx")
+
+  expect(sound).not.toBeNull()
+  expect(sfx).not.toBeNull()
+  if (sound == null || sfx == null) return
+
+  expect(audio.startMixer()).toBe(true)
+  const voice = audio.play(sound, { groupId: sfx, volume: 1, pan: 0, loop: false })
+  expect(voice).not.toBeNull()
+  const mixed = audio.mixFrames(6, 2)
+
+  expect(mixed).not.toBeNull()
+  if (!mixed) return
+  expect(mixed.length).toBe(12)
+  expect(mixed.some((sample) => Math.abs(sample) > 0.001)).toBe(true)
+  expect(audio.getStats()?.soundsLoaded).toBe(1)
+})
+
+test("Audio does not auto-start by default", () => {
+  const audio = Audio.create()
+  instances.push(audio)
+
+  expect(audio.isStarted()).toBe(false)
+  expect(audio.isMixerStarted()).toBe(false)
+})
+
+test("Audio start reports playback availability only", () => {
+  const audio = Audio.create({ autoStart: false })
+  audio.on("error", () => {})
+  instances.push(audio)
+
+  expect(audio.isStarted()).toBe(false)
+  expect(audio.isMixerStarted()).toBe(false)
+
+  const started = audio.start()
+  expect(audio.isStarted()).toBe(started)
+  expect(audio.isMixerStarted()).toBe(started)
+})
+
+test("Audio startMixer enables headless mixing without playback", () => {
+  const audio = Audio.create({ autoStart: false })
+  instances.push(audio)
+
+  const wav = buildMonoPcm16Wav([0, 0.25, -0.25, 0.5, -0.5, 0])
+  const sound = audio.loadSound(wav)
+  expect(sound).not.toBeNull()
+  if (sound == null) return
+
+  expect(audio.startMixer()).toBe(true)
+  expect(audio.isStarted()).toBe(false)
+  expect(audio.isMixerStarted()).toBe(true)
+
+  const voice = audio.play(sound, { volume: 1, loop: true })
+  expect(voice).not.toBeNull()
+
+  const mixed = audio.mixFrames(6, 2)
+  expect(mixed).not.toBeNull()
+  expect(mixed?.some((sample) => Math.abs(sample) > 0.001)).toBe(true)
+
+  expect(audio.stop()).toBe(true)
+  expect(audio.isStarted()).toBe(false)
+  expect(audio.isMixerStarted()).toBe(false)
+})
+
+test("Audio unloads sounds and invalidates old handles", () => {
+  const audio = Audio.create({ autoStart: false })
+  audio.on("error", () => {})
+  instances.push(audio)
+
+  const first = audio.loadSound(buildMonoPcm16Wav([0, 0.25, -0.25, 0.5, -0.5, 0]))
+  expect(first).not.toBeNull()
+  if (first == null) return
+
+  expect(audio.startMixer()).toBe(true)
+  const firstVoice = audio.play(first, { volume: 1, pan: 0, loop: true })
+  expect(firstVoice).not.toBeNull()
+  expect(audio.getStats()?.voicesActive).toBeGreaterThan(0)
+
+  expect(audio.unloadSound(first)).toBe(true)
+  expect(audio.getStats()?.soundsLoaded).toBe(0)
+  expect(audio.getStats()?.voicesActive).toBe(0)
+  expect(audio.play(first, { volume: 1 })).toBeNull()
+  expect(audio.unloadSound(first)).toBe(false)
+
+  const second = audio.loadSound(buildMonoPcm16Wav([0.6, -0.2, 0.4, -0.4, 0.3, -0.1]))
+  expect(second).not.toBeNull()
+  if (second == null) return
+  expect(second).not.toBe(first)
+
+  const secondVoice = audio.play(second, { volume: 1, pan: 0, loop: false })
+  expect(secondVoice).not.toBeNull()
+})
+
+test("Audio mixes into mono and multichannel output buffers", () => {
+  const audio = Audio.create({ autoStart: false })
+  instances.push(audio)
+
+  const wav = buildMonoPcm16Wav([0.6, -0.2, 0.4, -0.4, 0.3, -0.1])
+  const sound = audio.loadSound(wav)
+  expect(sound).not.toBeNull()
+  if (sound == null) return
+
+  expect(audio.startMixer()).toBe(true)
+  const voice = audio.play(sound, { volume: 1, pan: 0, loop: true })
+  expect(voice).not.toBeNull()
+
+  const mono = audio.mixFrames(6, 1)
+  expect(mono).not.toBeNull()
+  if (!mono) return
+  expect(mono.length).toBe(6)
+  expect(mono.some((sample) => Math.abs(sample) > 0.001)).toBe(true)
+
+  const quad = audio.mixFrames(6, 4)
+  expect(quad).not.toBeNull()
+  if (!quad) return
+  expect(quad.length).toBe(24)
+  expect(quad.some((sample, index) => index % 4 < 2 && Math.abs(sample) > 0.001)).toBe(true)
+  for (let frame = 0; frame < 6; frame += 1) {
+    expect(quad[frame * 4 + 2]).toBe(0)
+    expect(quad[frame * 4 + 3]).toBe(0)
+  }
+})
+
+test("Audio updates mix stats", () => {
+  const audio = Audio.create({ autoStart: false })
+  instances.push(audio)
+
+  const wave = Array.from({ length: 2048 }, (_, index) => Math.sin((Math.PI * 2 * index) / 32) * 0.8)
+  const wav = buildMonoPcm16Wav(wave)
+  const sound = audio.loadSound(wav)
+  expect(sound).not.toBeNull()
+  if (sound == null) return
+
+  expect(audio.startMixer()).toBe(true)
+  const voice = audio.play(sound, { volume: 1, pan: 0, loop: true })
+  expect(voice).not.toBeNull()
+
+  const initialStats = audio.getStats()
+  expect(initialStats).not.toBeNull()
+  const initialFrames = initialStats?.framesMixed ?? 0n
+
+  const mixed = audio.mixFrames(512, 2)
+  expect(mixed).not.toBeNull()
+
+  const finalStats = audio.getStats()
+  expect(finalStats).not.toBeNull()
+  expect(finalStats?.framesMixed ?? 0n).toBeGreaterThan(initialFrames)
+  expect(finalStats?.voicesActive ?? 0).toBeGreaterThan(0)
+})
+
+test("Audio tap mirrors mixed frames without consuming stream", () => {
+  const audio = Audio.create({ autoStart: false })
+  instances.push(audio)
+
+  const wav = buildMonoPcm16Wav([0, 0.5, -0.5, 0.25, -0.25, 0])
+  const sound = audio.loadSound(wav)
+  expect(sound).not.toBeNull()
+  if (sound == null) return
+
+  expect(audio.startMixer()).toBe(true)
+  expect(audio.enableTap(2048)).toBe(true)
+  const voice = audio.play(sound, { volume: 1, pan: 0, loop: true })
+  expect(voice).not.toBeNull()
+
+  const mixed = audio.mixFrames(256, 2)
+  expect(mixed).not.toBeNull()
+
+  const tap = audio.readTapFrames(128, 2)
+  expect(tap).not.toBeNull()
+  if (!tap) return
+
+  expect(tap.framesRead).toBeGreaterThan(0)
+  expect(tap.frames.length).toBe(256)
+  expect(tap.frames.some((sample) => Math.abs(sample) > 0.001)).toBe(true)
+
+  expect(audio.disableTap()).toBe(true)
+})
+
+test("Audio supports immutable custom sample rate", () => {
+  const audio = Audio.create({ autoStart: false, sampleRate: 44_100, playbackChannels: 1 })
+  instances.push(audio)
+
+  const wav = buildMonoPcm16Wav([0.3, -0.3, 0.2, -0.2, 0.1, -0.1])
+  const sound = audio.loadSound(wav)
+  expect(sound).not.toBeNull()
+  if (sound == null) return
+
+  expect(audio.startMixer()).toBe(true)
+  const voice = audio.play(sound, { volume: 1, pan: 0, loop: true })
+  expect(voice).not.toBeNull()
+
+  const mixed = audio.mixFrames(128, 2)
+  expect(mixed).not.toBeNull()
+  if (!mixed) return
+  expect(mixed.some((sample) => Math.abs(sample) > 0.001)).toBe(true)
+})
+
+test("audioLoad rejects oversized payload lengths before truncating to u32", () => {
+  const lib = resolveRenderLib()
+  const engine = lib.createAudioEngine()
+  expect(engine).not.toBeNull()
+  if (engine == null) return
+
+  const oversized = {
+    buffer: new ArrayBuffer(1),
+    byteOffset: 0,
+    byteLength: 0x1_0000_0000,
+    length: 0x1_0000_0000,
+  } as unknown as Uint8Array
+
+  try {
+    expect(() => lib.audioLoad(engine, oversized)).toThrow("Audio data length exceeds native u32 length limit")
+  } finally {
+    lib.destroyAudioEngine(engine)
+  }
+})
+
+test("audioCreateGroup rejects oversized encoded name lengths before truncating to u32", () => {
+  const lib = resolveRenderLib()
+  const engine = lib.createAudioEngine()
+  expect(engine).not.toBeNull()
+  if (engine == null) return
+
+  const originalEncode = lib.encoder.encode
+  const oversized = {
+    buffer: new ArrayBuffer(1),
+    byteOffset: 0,
+    byteLength: 0x1_0000_0000,
+    length: 0x1_0000_0000,
+  } as unknown as Uint8Array
+
+  ;(lib.encoder as { encode: (input: string) => Uint8Array }).encode = () => oversized
+
+  try {
+    expect(() => lib.audioCreateGroup(engine, "oversized")).toThrow(
+      "Audio group name length exceeds native u32 length limit",
+    )
+  } finally {
+    ;(lib.encoder as { encode: (input: string) => Uint8Array }).encode = originalEncode
+    lib.destroyAudioEngine(engine)
+  }
+})

package/src/tests/destroy-during-render.test.ts

@@ -0,0 +1,200 @@
+import { test, expect, beforeEach, afterEach, describe } from "bun:test"
+import { Renderable, type RenderableOptions } from "../Renderable.js"
+import { createTestRenderer, type TestRenderer } from "../testing/test-renderer.js"
+import type { RenderContext } from "../types.js"
+import type { OptimizedBuffer } from "../buffer.js"
+
+class TestRenderable extends Renderable {
+  public renderSelfCalled = false
+  public customOnUpdate?: () => void
+
+  constructor(ctx: RenderContext, options: RenderableOptions) {
+    super(ctx, options)
+  }
+
+  public onUpdate(deltaTime: number): void {
+    if (this.customOnUpdate) {
+      this.customOnUpdate()
+    }
+  }
+
+  protected renderSelf(buffer: OptimizedBuffer, deltaTime: number): void {
+    this.renderSelfCalled = true
+  }
+}
+
+let testRenderer: TestRenderer
+let renderOnce: () => Promise<void>
+
+beforeEach(async () => {
+  ;({ renderer: testRenderer, renderOnce } = await createTestRenderer({}))
+})
+
+afterEach(() => {
+  testRenderer.destroy()
+})
+
+describe("Destroy During Render - Actual Bugs", () => {
+  test("BUG: destroying self in onUpdate still calls renderSelf", async () => {
+    const renderable = new TestRenderable(testRenderer, {
+      id: "test",
+      width: 100,
+      height: 100,
+    })
+
+    renderable.customOnUpdate = () => {
+      renderable.destroy()
+    }
+
+    testRenderer.root.add(renderable)
+    await renderOnce()
+
+    expect(renderable.isDestroyed).toBe(true)
+    // BUG: renderSelf should NOT be called after destroy in onUpdate
+    expect(renderable.renderSelfCalled).toBe(false)
+  })
+
+  test("BUG: destroying child in parent's onUpdate, child still renders", async () => {
+    const parent = new TestRenderable(testRenderer, {
+      id: "parent",
+      width: 100,
+      height: 100,
+    })
+    const child = new TestRenderable(testRenderer, {
+      id: "child",
+      width: 50,
+      height: 50,
+    })
+
+    parent.add(child)
+    testRenderer.root.add(parent)
+
+    parent.customOnUpdate = () => {
+      child.destroy()
+    }
+
+    await renderOnce()
+
+    expect(child.isDestroyed).toBe(true)
+    // BUG: Child should not render if destroyed in parent's onUpdate
+    expect(child.renderSelfCalled).toBe(false)
+  })
+
+  test("BUG: destroying sibling in onUpdate, sibling still renders", async () => {
+    const parent = new TestRenderable(testRenderer, { id: "parent" })
+    const child1 = new TestRenderable(testRenderer, {
+      id: "child1",
+      width: 50,
+      height: 50,
+    })
+    const child2 = new TestRenderable(testRenderer, {
+      id: "child2",
+      width: 50,
+      height: 50,
+    })
+
+    parent.add(child1)
+    parent.add(child2)
+    testRenderer.root.add(parent)
+
+    child1.customOnUpdate = () => {
+      child2.destroy()
+    }
+
+    await renderOnce()
+
+    expect(child2.isDestroyed).toBe(true)
+    // BUG: child2 should not render if destroyed by sibling's onUpdate
+    expect(child2.renderSelfCalled).toBe(false)
+  })
+
+  test("BUG: destroying sibling in renderBefore, sibling (later in render list) still renders", async () => {
+    const parent = new TestRenderable(testRenderer, { id: "parent" })
+    const child2 = new TestRenderable(testRenderer, {
+      id: "child2",
+      width: 50,
+      height: 50,
+      zIndex: 2,
+    })
+
+    const child1 = new TestRenderable(testRenderer, {
+      id: "child1",
+      width: 50,
+      height: 50,
+      zIndex: 1,
+      renderBefore: function () {
+        child2.destroy()
+      },
+    })
+
+    parent.add(child1)
+    parent.add(child2)
+    testRenderer.root.add(parent)
+
+    await renderOnce()
+
+    expect(child2.isDestroyed).toBe(true)
+    // BUG: child2 should not render since it was destroyed before its turn
+    expect(child2.renderSelfCalled).toBe(false)
+  })
+
+  test("BUG: onLifecyclePass not called (registration issue)", async () => {
+    let lifecyclePassCalled = false
+
+    const renderable = new TestRenderable(testRenderer, { id: "test" })
+    renderable.onLifecyclePass = () => {
+      lifecyclePassCalled = true
+    }
+
+    testRenderer.root.add(renderable)
+    await renderOnce()
+
+    // BUG: Lifecycle pass should be called but isn't
+    expect(lifecyclePassCalled).toBe(true)
+  })
+})
+
+describe("Destroy During Render - Working Cases (for documentation)", () => {
+  test("WORKS: destroying self in renderAfter", async () => {
+    const renderable = new TestRenderable(testRenderer, {
+      id: "test",
+      width: 100,
+      height: 100,
+      renderAfter: function () {
+        this.destroy()
+      },
+    })
+
+    testRenderer.root.add(renderable)
+    await renderOnce()
+
+    expect(renderable.isDestroyed).toBe(true)
+    // renderSelf was already called by this point, which is fine
+    expect(renderable.renderSelfCalled).toBe(true)
+  })
+
+  test("WORKS: destroying child in renderAfter", async () => {
+    const child = new TestRenderable(testRenderer, {
+      id: "child",
+      width: 50,
+      height: 50,
+    })
+
+    const parent = new TestRenderable(testRenderer, {
+      id: "parent",
+      width: 100,
+      height: 100,
+      renderAfter: function () {
+        child.destroy()
+      },
+    })
+
+    parent.add(child)
+    testRenderer.root.add(parent)
+
+    await renderOnce()
+
+    expect(child.isDestroyed).toBe(true)
+    // Child already rendered before parent's renderAfter, which is expected
+  })
+})

package/src/tests/destroy-on-exit.fixture.ts

@@ -0,0 +1,36 @@
+import { Readable } from "node:stream"
+import { createTestRenderer } from "../testing.js"
+
+const code = parseInt(process.argv[2] ?? "0", 10)
+const mode = process.argv[3] ?? "idle"
+
+const stdin = new Readable({ read() {} }) as NodeJS.ReadStream & {
+  setRawMode: (enabled: boolean) => NodeJS.ReadStream
+}
+stdin.setRawMode = (enabled) => {
+  if (!enabled) {
+    console.log("raw mode disabled")
+  }
+  return stdin
+}
+
+const { renderer } = await createTestRenderer({ width: 20, height: 10, stdin })
+const lib = (renderer as any).lib
+const originalSuspendRenderer = lib.suspendRenderer.bind(lib)
+lib.suspendRenderer = (rendererPtr: unknown) => {
+  console.log("renderer suspended")
+  originalSuspendRenderer(rendererPtr)
+}
+
+process.on("exit", () => {
+  renderer.destroy()
+})
+
+if (mode === "during-render") {
+  renderer.setFrameCallback(async () => {
+    process.exit(code)
+  })
+  renderer.start()
+} else {
+  process.exit(code)
+}

package/src/tests/destroy-on-exit.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "bun:test"
+import { spawnSync } from "node:child_process"
+import { dirname, extname, join, resolve, sep } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const testFilePath = fileURLToPath(import.meta.url)
+const testDir = dirname(testFilePath)
+const fixturePath = join(testDir, `destroy-on-exit.fixture${extname(testFilePath)}`)
+const packageRoot = testFilePath.includes(`${sep}.node-test${sep}`)
+  ? resolve(testDir, "..", "..", "..")
+  : resolve(testDir, "..", "..")
+const workspaceRoot = resolve(packageRoot, "..", "..")
+
+const runFixture = (code: number, mode: "idle" | "during-render" = "idle") => {
+  const result = spawnSync(process.execPath, [...getFixtureRuntimeArgs(), fixturePath, code.toString(), mode], {
+    cwd: packageRoot,
+    env: process.env,
+  })
+
+  const stdout = result.stdout?.toString() ?? ""
+
+  return { result, stdout }
+}
+
+function getFixtureRuntimeArgs(): string[] {
+  if (process.versions.bun) {
+    return []
+  }
+
+  return [
+    "--permission",
+    `--allow-fs-read=${workspaceRoot}`,
+    "--allow-child-process",
+    "--allow-worker",
+    "--allow-ffi",
+    "--experimental-ffi",
+  ]
+}
+
+describe("destroy on process exit", () => {
+  it("it should let applications restore terminal state in an exit handler", () => {
+    const { result, stdout } = runFixture(0)
+
+    expect(result.status).toBe(0)
+    expect(stdout).toContain("raw mode disabled")
+  })
+
+  it("it should restore terminal state for non-zero exit codes", () => {
+    const { result, stdout } = runFixture(1)
+
+    expect(result.status).toBe(1)
+    expect(stdout).toContain("raw mode disabled")
+  })
+
+  it("it should suspend the renderer when destroy happens during an active frame in an exit handler", () => {
+    const { result, stdout } = runFixture(0, "during-render")
+
+    expect(result.status).toBe(0)
+    expect(stdout).toContain("raw mode disabled")
+    expect(stdout).toContain("renderer suspended")
+  })
+})