@xincli/opentui-core 0.4.6

package/scripts/test-node.ts

@@ -0,0 +1,241 @@
+import { spawnSync } from "node:child_process"
+import { cpSync, existsSync, mkdirSync, rmSync } from "node:fs"
+import { tmpdir } from "node:os"
+import { dirname, resolve } from "node:path"
+import { fileURLToPath } from "node:url"
+
+import { requireNode26 } from "../../../scripts/node26.mjs"
+
+const scriptDir = dirname(fileURLToPath(import.meta.url))
+const packageRoot = resolve(scriptDir, "..")
+const workspaceRoot = resolve(packageRoot, "..", "..")
+const outDir = resolve(packageRoot, ".node-test")
+const treeSitterStyledTextDataPath = resolve(tmpdir(), "tree-sitter-styled-text-test")
+const treeSitterCacheTestDataPath = resolve(tmpdir(), "tree-sitter-cache-test")
+const treeSitterDefaultDataPath = resolve(tmpdir(), "tree-sitter-default-node-test")
+const treeSitterMarkdownRenderableTestDataPath = resolve(tmpdir(), "tree-sitter-markdown-renderable-test-data")
+const textBufferTestDataPath = resolve(tmpdir(), "text-buffer-node-test")
+const treeSitterClientTestDataPaths = [
+  "tree-sitter-shared-test-data",
+  "tree-sitter-injections-test-data",
+  "tree-sitter-conceal-test-data",
+  "tree-sitter-edge-case-test-data",
+  "tree-sitter-reactive-data-path-test",
+].map((name) => resolve(tmpdir(), name))
+const treeSitterTestDataPaths = [
+  treeSitterStyledTextDataPath,
+  treeSitterCacheTestDataPath,
+  treeSitterDefaultDataPath,
+  treeSitterMarkdownRenderableTestDataPath,
+  textBufferTestDataPath,
+  ...treeSitterClientTestDataPaths,
+]
+const treeSitterCacheTestAddress = "127.0.0.1:55231"
+const treeSitterAssetsDir = "src/lib/tree-sitter/assets"
+const nodeTestTimeoutMs = 30_000
+const nodeProcessTimeoutMs = 10 * 60_000
+const nodePath = requireNode26()
+const emittedAllowlist = [
+  ".node-test/src/platform/ffi.test.js",
+  ".node-test/src/platform/runtime.test.js",
+  ".node-test/src/platform/worker.node-test.js",
+  ".node-test/src/lib/bunfs.test.js",
+  ".node-test/src/lib/border.test.js",
+  ".node-test/src/lib/clipboard.test.js",
+  ".node-test/src/lib/extmarks.test.js",
+  ".node-test/src/lib/detect-links.test.js",
+  ".node-test/src/lib/extmarks-multiwidth.test.js",
+  ".node-test/src/lib/KeyHandler.test.js",
+  ".node-test/src/lib/keybinding.internal.test.js",
+  ".node-test/src/lib/KeyHandler.integration.test.js",
+  ".node-test/src/lib/parse.keypress-kitty.protocol.test.js",
+  ".node-test/src/lib/parse.keypress-kitty.test.js",
+  ".node-test/src/lib/parse.mouse.test.js",
+  ".node-test/src/lib/RGBA.test.js",
+  ".node-test/src/lib/tree-sitter/resolve-ft.test.js",
+  ".node-test/src/tests/renderer.kitty-flags.test.js",
+  ".node-test/src/buffer.test.js",
+  ".node-test/src/tests/renderer.idle.test.js",
+  ".node-test/src/tests/renderer.notifications.test.js",
+  ".node-test/src/tests/renderer.selection.test.js",
+  ".node-test/src/console.test.js",
+  ".node-test/src/native-handle.test.js",
+  ".node-test/src/renderables/Box.test.js",
+  ".node-test/src/renderables/Code.test.js",
+  ".node-test/src/renderables/Diff.regression.test.js",
+  ".node-test/src/renderables/Diff.test.js",
+  ".node-test/src/renderables/EditBufferRenderable.test.js",
+  ".node-test/src/renderables/Input.test.js",
+  ".node-test/src/renderables/Select.test.js",
+  ".node-test/src/renderables/Slider.test.js",
+  ".node-test/src/renderables/TabSelect.test.js",
+  ".node-test/src/renderables/__tests__/Code.test.js",
+  ".node-test/src/renderables/__tests__/LineNumberRenderable.scrollbox-simple.test.js",
+  ".node-test/src/renderables/__tests__/LineNumberRenderable.scrollbox.test.js",
+  ".node-test/src/renderables/__tests__/LineNumberRenderable.test.js",
+  ".node-test/src/renderables/__tests__/LineNumberRenderable.wrapping.test.js",
+  ".node-test/src/renderables/__tests__/Markdown.code-colors.test.js",
+  ".node-test/src/renderables/__tests__/Markdown.test.js",
+  ".node-test/src/renderables/__tests__/MultiRenderable.selection.test.js",
+  ".node-test/src/renderables/__tests__/Textarea.buffer.test.js",
+  ".node-test/src/renderables/__tests__/Textarea.destroyed-events.test.js",
+  ".node-test/src/renderables/__tests__/Textarea.editing.test.js",
+  ".node-test/src/renderables/__tests__/Textarea.error-handling.test.js",
+  ".node-test/src/renderables/__tests__/Textarea.events.test.js",
+  ".node-test/src/renderables/__tests__/Textarea.highlights.test.js",
+  ".node-test/src/renderables/__tests__/Textarea.keybinding.test.js",
+  ".node-test/src/renderables/__tests__/Textarea.paste.test.js",
+  ".node-test/src/renderables/__tests__/Textarea.rendering.test.js",
+  ".node-test/src/renderables/__tests__/Textarea.scroll.test.js",
+  ".node-test/src/renderables/__tests__/Textarea.selection.test.js",
+  ".node-test/src/renderables/__tests__/Textarea.stress.test.js",
+  ".node-test/src/renderables/__tests__/Textarea.undo-redo.test.js",
+  ".node-test/src/renderables/__tests__/Textarea.visual-lines.test.js",
+  ".node-test/src/renderables/Text.test.js",
+  ".node-test/src/renderables/Text.selection-buffer.test.js",
+  ".node-test/src/renderables/TextTable.test.js",
+  ".node-test/src/animation/Timeline.test.js",
+  ".node-test/src/edit-buffer.test.js",
+  ".node-test/src/editor-view.test.js",
+  ".node-test/src/lib/data-paths.test.js",
+  ".node-test/src/lib/env.test.js",
+  ".node-test/src/lib/KeyHandler.stopPropagation.test.js",
+  ".node-test/src/lib/objects-in-viewport.test.js",
+  ".node-test/src/lib/parse.keypress.test.js",
+  ".node-test/src/lib/renderable.validations.test.js",
+  ".node-test/src/lib/stdin-parser.test.js",
+  ".node-test/src/lib/terminal-capability-detection.test.js",
+  ".node-test/src/lib/terminal-palette.test.js",
+  ".node-test/src/lib/tree-sitter/cache.test.js",
+  ".node-test/src/lib/tree-sitter/client.test.js",
+  ".node-test/src/lib/tree-sitter-styled-text.test.js",
+  ".node-test/src/lib/yoga.options.test.js",
+  ".node-test/src/renderables/__tests__/markdown-parser.test.js",
+  ".node-test/src/renderables/TextNode.test.js",
+  ".node-test/src/syntax-style.test.js",
+  ".node-test/src/testing/capture-spans.test.js",
+  ".node-test/src/testing/test-recorder.test.js",
+  ".node-test/src/testing/integration.test.js",
+  ".node-test/src/testing/mock-keys.test.js",
+  ".node-test/src/testing/mock-mouse.test.js",
+  ".node-test/src/tests/absolute-positioning.snapshot.test.js",
+  ".node-test/src/tests/renderable.snapshot.test.js",
+  ".node-test/src/tests/allocator-stats.test.js",
+  ".node-test/src/tests/audio.test.js",
+  ".node-test/src/tests/destroy-on-exit.test.js",
+  ".node-test/src/tests/destroy-during-render.test.js",
+  ".node-test/src/tests/ffi-borrowed-pointer-callsites.test.js",
+  ".node-test/src/tests/hover-cursor.test.js",
+  ".node-test/src/tests/native-backed-measurement-lifecycle.test.js",
+  ".node-test/src/tests/native-backed-measurement-parity.test.js",
+  ".node-test/src/tests/native-span-feed-async.test.js",
+  ".node-test/src/tests/native-span-feed-close.test.js",
+  ".node-test/src/tests/native-span-feed-coverage.test.js",
+  ".node-test/src/tests/native-span-feed-edge-cases.test.js",
+  ".node-test/src/tests/opacity.test.js",
+  ".node-test/src/tests/native-span-feed-use-after-free.test.js",
+  ".node-test/src/tests/renderable.test.js",
+  ".node-test/src/tests/renderer.clock.test.js",
+  ".node-test/src/tests/renderer.console-startup.test.js",
+  ".node-test/src/tests/renderer.control.test.js",
+  ".node-test/src/tests/renderer.core-slot-binding.test.js",
+  ".node-test/src/tests/renderer.cursor.test.js",
+  ".node-test/src/tests/renderer.destroy-during-render.test.js",
+  ".node-test/src/tests/renderer.focus.test.js",
+  ".node-test/src/tests/renderer.focus-restore.test.js",
+  ".node-test/src/tests/renderer.input.test.js",
+  ".node-test/src/tests/renderer.mouse.test.js",
+  ".node-test/src/tests/renderer.palette.test.js",
+  ".node-test/src/tests/renderer.scrollback-surface.test.js",
+  ".node-test/src/tests/renderer.slot-registry.test.js",
+  ".node-test/src/tests/renderer.useMouse.test.js",
+  ".node-test/src/tests/scrollbox.test.js",
+  ".node-test/src/tests/scrollbox-culling-bug.test.js",
+  ".node-test/src/tests/scrollbox-hitgrid-resize.test.js",
+  ".node-test/src/tests/scrollbox-hitgrid.test.js",
+  ".node-test/src/tests/yoga-callback-stress.test.js",
+  ".node-test/src/tests/yoga-setters.test.js",
+  ".node-test/src/tests/wrap-resize-perf.test.js",
+  ".node-test/src/text-buffer.test.js",
+  ".node-test/src/text-buffer-view.test.js",
+]
+
+let exitCode = 0
+
+try {
+  rmSync(outDir, { recursive: true, force: true })
+
+  exitCode = run(process.execPath, ["x", "tsc", "-p", "tsconfig.node-test.json"])
+
+  // node --test silently ignores nonexistent file arguments, so a missing
+  // emitted test (e.g. not listed in tsconfig.node-test.json) would skip
+  // coverage without failing. Fail loudly instead.
+  if (exitCode === 0) {
+    const missing = emittedAllowlist.filter((path) => !existsSync(resolve(packageRoot, path)))
+    if (missing.length > 0) {
+      console.error(`Missing emitted node tests (add them to tsconfig.node-test.json?):\n${missing.join("\n")}`)
+      exitCode = 1
+    }
+  }
+
+  if (exitCode === 0) {
+    cpSync(resolve(packageRoot, treeSitterAssetsDir), resolve(outDir, treeSitterAssetsDir), { recursive: true })
+    for (const dataPath of treeSitterTestDataPaths) {
+      mkdirSync(dataPath, { recursive: true })
+    }
+
+    exitCode = run(
+      nodePath,
+      [
+        "--disable-warning=SecurityWarning",
+        "--disable-warning=ExperimentalWarning",
+        "--permission",
+        `--allow-fs-read=${workspaceRoot}`,
+        ...treeSitterTestDataPaths.map((path) => `--allow-fs-read=${path}`),
+        ...treeSitterTestDataPaths.map((path) => `--allow-fs-write=${path}`),
+        `--allow-net=${treeSitterCacheTestAddress}`,
+        "--allow-child-process",
+        "--allow-worker",
+        "--allow-ffi",
+        "--experimental-ffi",
+        "--import",
+        "./scripts/test-node-hook.mjs",
+        "--test-concurrency=1",
+        `--test-timeout=${nodeTestTimeoutMs}`,
+        "--test",
+        ...emittedAllowlist,
+      ],
+      {
+        env: {
+          ...process.env,
+          OTUI_TEXT_BUFFER_TEST_TMPDIR: textBufferTestDataPath,
+          XDG_DATA_HOME: treeSitterDefaultDataPath,
+        },
+        timeout: nodeProcessTimeoutMs,
+      },
+    )
+  }
+} finally {
+  rmSync(outDir, { recursive: true, force: true })
+}
+
+process.exit(exitCode)
+
+function run(command: string, args: string[], options: { env?: NodeJS.ProcessEnv; timeout?: number } = {}): number {
+  const result = spawnSync(command, args, {
+    cwd: packageRoot,
+    env: options.env ?? process.env,
+    stdio: "inherit",
+    timeout: options.timeout,
+  })
+
+  if (result.error) {
+    if (result.error.name === "TimeoutError") {
+      console.error(`Command timed out after ${options.timeout}ms: ${command} ${args.join(" ")}`)
+    }
+
+    throw result.error
+  }
+
+  return result.status ?? 1
+}

package/scripts/vendor-deps.sh

@@ -0,0 +1,73 @@
+#!/data/data/com.termux/files/usr/bin/bash
+# ═════════════════════════════════════════════════════════════════
+# vendor-deps.sh — Pre-fetch Zig deps so builds work offline
+#
+# Run this ONCE on a machine with good network (your laptop, or your
+# phone on WiFi). It downloads yoga + uucode into .zig-deps/ so
+# build-native-termux.sh doesn't need network during the build.
+#
+# Run from the repo root:
+#   bash packages/core/scripts/vendor-deps.sh
+# ═════════════════════════════════════════════════════════════════
+
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/../../.." && pwd)"
+DEPS_DIR="$REPO_ROOT/.zig-deps"
+
+mkdir -p "$DEPS_DIR"
+
+# ── uucode ──────────────────────────────────────────────────────
+UUCODE_URL="https://github.com/jacobsandlund/uucode/archive/84ceda8561a17ba4a9b96ac5c583f779660bbd4e.tar.gz"
+UUCODE_DIR="$DEPS_DIR/uucode"
+
+if [ -d "$UUCODE_DIR" ]; then
+  echo "✓ uucode already vendored at $UUCODE_DIR"
+else
+  echo "📦 Downloading uucode..."
+  # Retry up to 3 times — mobile DNS can be flaky
+  for attempt in 1 2 3; do
+    if curl -fsSL --retry 3 --retry-delay 2 "$UUCODE_URL" | tar xz -C "$DEPS_DIR"; then
+      mv "$DEPS_DIR/uucode-84ceda8561a17ba4a9b96ac5c583f779660bbd4e" "$UUCODE_DIR" 2>/dev/null || true
+      echo "✓ uucode downloaded"
+      break
+    else
+      echo "⚠️  Attempt $attempt failed, retrying in 5s..."
+      sleep 5
+    fi
+  done
+  if [ ! -d "$UUCODE_DIR" ]; then
+    echo "❌ Failed to download uucode after 3 attempts."
+    echo "   Check your network connection and try again."
+    exit 1
+  fi
+fi
+
+# ── yoga ────────────────────────────────────────────────────────
+YOGA_DIR="$DEPS_DIR/yoga"
+
+if [ -d "$YOGA_DIR" ]; then
+  echo "✓ yoga already vendored at $YOGA_DIR"
+else
+  echo "📦 Downloading yoga v3.2.1..."
+  YOGA_URL="https://github.com/facebook/yoga/archive/refs/tags/v3.2.1.tar.gz"
+  for attempt in 1 2 3; do
+    if curl -fsSL --retry 3 --retry-delay 2 "$YOGA_URL" | tar xz -C "$DEPS_DIR"; then
+      mv "$DEPS_DIR/yoga-3.2.1" "$YOGA_DIR" 2>/dev/null || true
+      echo "✓ yoga downloaded"
+      break
+    else
+      echo "⚠️  Attempt $attempt failed, retrying in 5s..."
+      sleep 5
+    fi
+  done
+  if [ ! -d "$YOGA_DIR" ]; then
+    echo "❌ Failed to download yoga after 3 attempts."
+    exit 1
+  fi
+fi
+
+echo ""
+echo "✅ All deps vendored to $DEPS_DIR"
+echo "   Now run: bash packages/core/scripts/build-native-termux.sh"

package/src/NativeSpanFeed.ts

@@ -0,0 +1,375 @@
+import { toArrayBuffer, type Pointer } from "./platform/ffi.js"
+import { resolveRenderLib } from "./zig.js"
+import { SpanInfoStruct } from "./zig-structs.js"
+import type { NativeSpanFeedOptions } from "./zig-structs.js"
+
+export type { GrowthPolicy, NativeSpanFeedOptions, NativeSpanFeedStats } from "./zig-structs.js"
+
+const enum EventId {
+  ChunkAdded = 2,
+  Closed = 5,
+  Error = 6,
+  DataAvailable = 7,
+  StateBuffer = 8,
+}
+
+function toNumber(value: number | bigint): number {
+  return typeof value === "bigint" ? Number(value) : value
+}
+
+type StreamEventHandler = (eventId: number, arg0: Pointer, arg1: number | bigint) => void
+
+export type DataHandler = (data: Uint8Array) => void | Promise<void>
+
+const canThrowAcrossNativeCallback =
+  typeof process !== "undefined" &&
+  typeof process.versions === "object" &&
+  process.versions !== null &&
+  typeof process.versions.bun === "string"
+
+/**
+ * Zero-copy wrapper over Zig memory; not a full stream interface.
+ * Chunk and state typed-array views are borrowed and invalid after destroy.
+ */
+export class NativeSpanFeed {
+  static create(options?: NativeSpanFeedOptions): NativeSpanFeed {
+    const lib = resolveRenderLib()
+    const streamPtr = lib.createNativeSpanFeed(options)
+    const stream = new NativeSpanFeed(streamPtr)
+
+    lib.registerNativeSpanFeedStream(streamPtr, stream.eventHandler)
+
+    const status = lib.attachNativeSpanFeed(streamPtr)
+    if (status !== 0) {
+      lib.unregisterNativeSpanFeedStream(streamPtr)
+      lib.destroyNativeSpanFeed(streamPtr)
+      throw new Error(`Failed to attach stream: ${status}`)
+    }
+
+    return stream
+  }
+
+  static attach(streamPtr: Pointer, _options?: NativeSpanFeedOptions): NativeSpanFeed {
+    const lib = resolveRenderLib()
+    const stream = new NativeSpanFeed(streamPtr)
+
+    lib.registerNativeSpanFeedStream(streamPtr, stream.eventHandler)
+
+    const status = lib.attachNativeSpanFeed(streamPtr)
+    if (status !== 0) {
+      lib.unregisterNativeSpanFeedStream(streamPtr)
+      throw new Error(`Failed to attach stream: ${status}`)
+    }
+
+    return stream
+  }
+
+  readonly streamPtr: Pointer
+  private readonly lib = resolveRenderLib()
+  private readonly eventHandler: StreamEventHandler
+  private chunkMap = new Map<Pointer, ArrayBuffer>()
+  private chunkSizes = new Map<Pointer, number>()
+  private dataHandlers = new Set<DataHandler>()
+  private errorHandlers = new Set<(code: number) => void>()
+  private drainBuffer: Uint8Array | null = null
+  private stateBuffer: Uint8Array | null = null
+  private closed = false
+  private destroyed = false
+  private draining = false
+  private pendingDataAvailable = false
+  private pendingClose = false
+  private closing = false
+  private pendingAsyncHandlers = 0
+  private inCallback = false
+  private closeQueued = false
+  private idleResolvers: Array<() => void> = []
+  private pendingHandlerError: unknown = null
+  private pendingHandlerErrorQueued = false
+
+  private constructor(streamPtr: Pointer) {
+    this.streamPtr = streamPtr
+    this.eventHandler = (eventId, arg0, arg1) => {
+      this.handleEvent(eventId, arg0, arg1)
+    }
+    this.ensureDrainBuffer()
+  }
+
+  private ensureDrainBuffer(): void {
+    if (this.drainBuffer) return
+    const capacity = 256
+    this.drainBuffer = new Uint8Array(capacity * SpanInfoStruct.size)
+  }
+
+  onData(handler: DataHandler): () => void {
+    this.dataHandlers.add(handler)
+    if (this.pendingDataAvailable) {
+      this.pendingDataAvailable = false
+      this.drainAll()
+    }
+    return () => this.dataHandlers.delete(handler)
+  }
+
+  onError(handler: (code: number) => void): () => void {
+    this.errorHandlers.add(handler)
+    return () => this.errorHandlers.delete(handler)
+  }
+
+  private hasPinnedChunks(): boolean {
+    if (!this.stateBuffer) return false
+    for (const refcount of this.stateBuffer) {
+      if (refcount > 0) return true
+    }
+    return false
+  }
+
+  isBackpressured(): boolean {
+    return this.pendingAsyncHandlers > 0 || this.pendingDataAvailable || this.hasPinnedChunks()
+  }
+
+  close(): void {
+    if (this.destroyed) return
+    if (this.inCallback || this.draining || this.pendingAsyncHandlers > 0) {
+      this.pendingClose = true
+      if (!this.closeQueued) {
+        this.closeQueued = true
+        queueMicrotask(() => {
+          this.closeQueued = false
+          this.processPendingClose()
+        })
+      }
+      return
+    }
+    this.performClose()
+  }
+
+  private processPendingClose(): void {
+    if (!this.pendingClose || this.destroyed) return
+    if (this.inCallback || this.draining || this.pendingAsyncHandlers > 0) return
+    this.pendingClose = false
+    this.performClose()
+    this.resolveIdleIfNeeded()
+  }
+
+  private performClose(): void {
+    if (this.closing) return
+    this.closing = true
+    if (!this.closed) {
+      const status = this.lib.streamClose(this.streamPtr)
+      if (status !== 0) {
+        this.closing = false
+        return
+      }
+      this.closed = true
+    }
+    this.finalizeDestroy()
+  }
+
+  private finalizeDestroy(): void {
+    if (this.destroyed) return
+    this.lib.unregisterNativeSpanFeedStream(this.streamPtr)
+    this.lib.destroyNativeSpanFeed(this.streamPtr)
+    this.destroyed = true
+    this.chunkMap.clear()
+    this.chunkSizes.clear()
+    this.stateBuffer = null
+    this.drainBuffer = null
+    this.dataHandlers.clear()
+    this.errorHandlers.clear()
+    this.pendingDataAvailable = false
+    this.resolveIdleIfNeeded()
+  }
+
+  private isIdle(): boolean {
+    return (
+      !this.inCallback &&
+      !this.draining &&
+      this.pendingAsyncHandlers === 0 &&
+      !this.pendingDataAvailable &&
+      !this.hasPinnedChunks()
+    )
+  }
+
+  private resolveIdleIfNeeded(): void {
+    if (!this.isIdle()) return
+    const resolvers = this.idleResolvers.splice(0)
+    for (const resolve of resolvers) {
+      resolve()
+    }
+  }
+
+  idle(): Promise<void> {
+    if (this.isIdle()) return Promise.resolve()
+    return new Promise<void>((resolve) => {
+      this.idleResolvers.push(resolve)
+    })
+  }
+
+  private handleEvent(eventId: number, arg0: Pointer, arg1: number | bigint): void {
+    this.inCallback = true
+    try {
+      switch (eventId) {
+        case EventId.StateBuffer: {
+          const len = toNumber(arg1)
+          if (len > 0 && arg0) {
+            // toArrayBuffer must alias Zig memory so refcount writes are visible.
+            const buffer = toArrayBuffer(arg0, 0, len)
+            this.stateBuffer = new Uint8Array(buffer)
+          }
+          break
+        }
+        case EventId.DataAvailable: {
+          if (this.closing) break
+          if (this.dataHandlers.size === 0) {
+            this.pendingDataAvailable = true
+            break
+          }
+          this.drainAll()
+          break
+        }
+        case EventId.ChunkAdded: {
+          const chunkLen = toNumber(arg1)
+          if (chunkLen > 0 && arg0) {
+            if (!this.chunkMap.has(arg0)) {
+              const buffer = toArrayBuffer(arg0, 0, chunkLen)
+              this.chunkMap.set(arg0, buffer)
+            }
+            this.chunkSizes.set(arg0, chunkLen)
+          }
+          break
+        }
+        case EventId.Error: {
+          const code = toNumber(arg0)
+          for (const handler of this.errorHandlers) handler(code)
+          break
+        }
+        case EventId.Closed: {
+          this.closed = true
+          break
+        }
+        default:
+          break
+      }
+    } finally {
+      this.inCallback = false
+      this.resolveIdleIfNeeded()
+    }
+  }
+
+  private decrementRefcount(chunkIndex: number): void {
+    if (this.stateBuffer && chunkIndex < this.stateBuffer.length) {
+      const prev = this.stateBuffer[chunkIndex]
+      this.stateBuffer[chunkIndex] = prev > 0 ? prev - 1 : 0
+    }
+  }
+
+  private queuePendingHandlerError(error: unknown): void {
+    this.pendingHandlerError ??= error
+    if (this.pendingHandlerErrorQueued) return
+
+    this.pendingHandlerErrorQueued = true
+    queueMicrotask(() => {
+      this.pendingHandlerErrorQueued = false
+      if (this.pendingHandlerError === null) return
+
+      const pendingError = this.pendingHandlerError
+      this.pendingHandlerError = null
+      throw pendingError
+    })
+  }
+
+  private throwPendingHandlerError(): void {
+    if (this.pendingHandlerError === null) return
+
+    const pendingError = this.pendingHandlerError
+    this.pendingHandlerError = null
+    throw pendingError
+  }
+
+  private drainOnce(): number {
+    if (!this.drainBuffer || this.draining || this.pendingClose) return 0
+    const capacity = Math.floor(this.drainBuffer.byteLength / SpanInfoStruct.size)
+    if (capacity === 0) return 0
+
+    const count = this.lib.streamDrainSpans(this.streamPtr, this.drainBuffer, capacity)
+    if (count === 0) return 0
+
+    this.draining = true
+    const spans = SpanInfoStruct.unpackList(this.drainBuffer.buffer, count)
+    let firstError: unknown = null
+
+    try {
+      for (const span of spans) {
+        if (span.len === 0) continue
+
+        let buffer = this.chunkMap.get(span.chunkPtr)
+        if (!buffer) {
+          const size = this.chunkSizes.get(span.chunkPtr)
+          if (!size) continue
+          buffer = toArrayBuffer(span.chunkPtr, 0, size)
+          this.chunkMap.set(span.chunkPtr, buffer)
+        }
+
+        if (span.offset + span.len > buffer.byteLength) continue
+
+        const slice = new Uint8Array(buffer, span.offset, span.len)
+        let asyncResults: Promise<void>[] | null = null
+
+        for (const handler of this.dataHandlers) {
+          try {
+            const result = handler(slice)
+            // Async handlers keep the chunk pinned until they settle.
+            if (result && typeof result.then === "function") {
+              asyncResults ??= []
+              asyncResults.push(result)
+            }
+          } catch (e) {
+            firstError ??= e
+          }
+        }
+
+        const shouldStopAfterThisSpan = this.pendingClose
+
+        if (asyncResults) {
+          // Use allSettled so rejections still release refcounts.
+          const chunkIndex = span.chunkIndex
+          this.pendingAsyncHandlers += 1
+          Promise.allSettled(asyncResults).then(() => {
+            this.decrementRefcount(chunkIndex)
+            this.pendingAsyncHandlers -= 1
+            this.processPendingClose()
+            this.resolveIdleIfNeeded()
+          })
+        } else {
+          this.decrementRefcount(span.chunkIndex)
+        }
+
+        if (shouldStopAfterThisSpan) break
+      }
+    } finally {
+      this.draining = false
+      this.resolveIdleIfNeeded()
+    }
+
+    if (firstError) {
+      if (!this.inCallback || canThrowAcrossNativeCallback) {
+        throw firstError
+      }
+
+      // Node FFI terminates when JS exceptions cross a native callback boundary.
+      // Surface the error after the callback returns instead of swallowing it.
+      this.queuePendingHandlerError(firstError)
+    }
+
+    return count
+  }
+
+  drainAll(): void {
+    let count = this.drainOnce()
+    while (count > 0) {
+      count = this.drainOnce()
+    }
+    if (!this.inCallback) {
+      this.throwPendingHandlerError()
+    }
+  }
+}