feat(opentui): implement threadsafe callbacks and performance APIs

Threadsafe callbacks (no more TODOs/no-ops):
- setLogCallback: TSFN bridge for log messages from native render thread
- setEventCallback: TSFN bridge for native events (input, resize, etc.)
- streamSetCallback: TSFN bridge for NativeSpanFeed stream notifications
All three properly create/release napi_threadsafe_function, handle
undefined/null to clear callbacks, and use nonblocking queue mode.

Performance APIs for zero-copy buffer access:
- bufferGetCharArrayBuffer/FgArrayBuffer/BgArrayBuffer/AttributesArrayBuffer:
  Return external ArrayBuffers backed by native memory (no copy)
- bufferDrawTextEncoded: Accept pre-encoded Uint8Array to skip
  per-call UTF-8 conversion overhead
- editBufferGetCursorInto/editorViewGetCursorInto/getCursorStateInto:
  Write cursor state into reusable typed arrays (no object allocation)

JS wrapper additions:
- BufferView class: Lazy typed array views over native buffer memory
  with direct cell writes (bypass FFI for bulk updates)
- CursorState class: Reusable cursor reader (zero allocation per read)
- encodeText(): Cached TextEncoder for pre-encoding text

napi.zig additions:
- createThreadsafeFunction/callThreadsafeFunction/releaseThreadsafeFunction
- acquireThreadsafeFunction for multi-thread access
- getTypedArrayInfo for reading typed array data pointers

Author: jdalton

packages/opentui-builder/lib/index.d.ts

@@ -60,3 +60,31 @@ export declare const TargetChannel: {
   readonly BG: 2
   readonly BOTH: 3
 }
+
+export declare function encodeText(text: string): Uint8Array
+
+export type NativePointer = import('./native.js').NativePointer
+
+export declare class BufferView {
+  constructor(bufferPtr: NativePointer)
+  readonly width: number
+  readonly height: number
+  readonly chars: Uint32Array
+  readonly fg: Float32Array
+  readonly bg: Float32Array
+  readonly attributes: Uint32Array
+  setCell(x: number, y: number, char: number, fgR: number, fgG: number, fgB: number, fgA: number, bgR: number, bgG: number, bgB: number, bgA: number, attrs: number): void
+  invalidate(): void
+}
+
+export declare class CursorState {
+  constructor()
+  readEditBuffer(editBufferPtr: NativePointer): this
+  readEditorView(editorViewPtr: NativePointer): this
+  readRenderer(rendererPtr: NativePointer): this
+  readonly row: number
+  readonly col: number
+  readonly x: number
+  readonly y: number
+  readonly visible: boolean
+}

packages/opentui-builder/lib/index.mjs

@@ -218,3 +218,104 @@ export const TargetChannel = {
   BG: 2,
   BOTH: 3,
 }
+
+// ── Performance helpers ──
+
+const textEncoder = new TextEncoder()
+
+export function encodeText(text) {
+  return textEncoder.encode(text)
+}
+
+export class BufferView {
+  constructor(bufferPtr) {
+    this._ptr = bufferPtr
+    this._chars = undefined
+    this._fg = undefined
+    this._bg = undefined
+    this._attrs = undefined
+    this._width = native.getBufferWidth(bufferPtr)
+    this._height = native.getBufferHeight(bufferPtr)
+  }
+
+  get width() { return this._width }
+  get height() { return this._height }
+
+  get chars() {
+    if (!this._chars) {
+      this._chars = new Uint32Array(native.bufferGetCharArrayBuffer(this._ptr))
+    }
+    return this._chars
+  }
+
+  get fg() {
+    if (!this._fg) {
+      this._fg = new Float32Array(native.bufferGetFgArrayBuffer(this._ptr))
+    }
+    return this._fg
+  }
+
+  get bg() {
+    if (!this._bg) {
+      this._bg = new Float32Array(native.bufferGetBgArrayBuffer(this._ptr))
+    }
+    return this._bg
+  }
+
+  get attributes() {
+    if (!this._attrs) {
+      this._attrs = new Uint32Array(native.bufferGetAttributesArrayBuffer(this._ptr))
+    }
+    return this._attrs
+  }
+
+  setCell(x, y, char, fgR, fgG, fgB, fgA, bgR, bgG, bgB, bgA, attrs) {
+    const idx = y * this._width + x
+    this.chars[idx] = char
+    const ci = idx * 4
+    this.fg[ci] = fgR
+    this.fg[ci + 1] = fgG
+    this.fg[ci + 2] = fgB
+    this.fg[ci + 3] = fgA
+    this.bg[ci] = bgR
+    this.bg[ci + 1] = bgG
+    this.bg[ci + 2] = bgB
+    this.bg[ci + 3] = bgA
+    this.attributes[idx] = attrs
+  }
+
+  invalidate() {
+    this._chars = undefined
+    this._fg = undefined
+    this._bg = undefined
+    this._attrs = undefined
+  }
+}
+
+export class CursorState {
+  constructor() {
+    this._buf = new Uint32Array(2)
+    this._i32buf = new Int32Array(3)
+  }
+
+  readEditBuffer(editBufferPtr) {
+    native.editBufferGetCursorInto(editBufferPtr, this._buf)
+    return this
+  }
+
+  readEditorView(editorViewPtr) {
+    native.editorViewGetCursorInto(editorViewPtr, this._buf)
+    return this
+  }
+
+  readRenderer(rendererPtr) {
+    native.getCursorStateInto(rendererPtr, this._i32buf)
+    return this
+  }
+
+  get row() { return this._buf[0] }
+  get col() { return this._buf[1] }
+  get x() { return this._i32buf[0] }
+  get y() { return this._i32buf[1] }
+  get visible() { return this._i32buf[2] !== 0 }
+}

packages/opentui-builder/lib/native.d.ts

@@ -287,6 +287,17 @@ interface OpenTUIBindings {
   streamGetStats(stream: NativePointer): { totalBytesWritten: number; totalSpansEmitted: number; totalCommits: number; chunksAllocated: number; chunksInUse: number; currentChunkUsed: number; pendingSpanBytes: number; attached: boolean }
   streamDrainSpans(stream: NativePointer, outPtr: ArrayBuffer, maxSpans: number): number
   streamSetCallback(stream: NativePointer, callback: (() => void) | undefined): void
+
+  // ── Performance: batch/direct buffer access ──
+
+  bufferDrawTextEncoded(buffer: NativePointer, data: Uint8Array, x: number, y: number, fgR: number, fgG: number, fgB: number, fgA: number, bgR: number, bgG: number, bgB: number, bgA: number, attributes: number): void
+  bufferGetCharArrayBuffer(buffer: NativePointer): ArrayBuffer
+  bufferGetFgArrayBuffer(buffer: NativePointer): ArrayBuffer
+  bufferGetBgArrayBuffer(buffer: NativePointer): ArrayBuffer
+  bufferGetAttributesArrayBuffer(buffer: NativePointer): ArrayBuffer
+  editBufferGetCursorInto(editBuffer: NativePointer, out: Uint32Array): void
+  editorViewGetCursorInto(view: NativePointer, out: Uint32Array): void
+  getCursorStateInto(renderer: NativePointer, out: Int32Array): void
 }
 
 export type { NativePointer }