@xincli/opentui-core 0.4.6

package/src/platform/ffi.ts

@@ -0,0 +1,653 @@
+import { createRequire } from "node:module"
+import { fileURLToPath } from "node:url"
+
+declare const pointerBrand: unique symbol
+
+// This module owns OpenTUI's native FFI surface. Portable code imports this
+// file instead of bun:ffi, so backends can keep the same call sites.
+
+// External FFI producers may expose their own branded pointer types. Public APIs
+// that consume foreign pointers should accept the raw pointer shape and normalize
+// it before crossing OpenTUI's native boundary.
+export type PointerInput = number | bigint
+
+// Runtime pointers are numbers in Bun and bigints in Node's experimental FFI.
+// Keep both in our own type, and narrow only inside a backend that requires it.
+export type Pointer = PointerInput & { readonly [pointerBrand]: "Pointer" }
+
+type PointerSource = ArrayBufferLike | ArrayBufferView
+
+// Bun accepts numeric pointers only. Keep this type private so Bun's pointer
+// model does not leak into the exported surface.
+type BunPointer = number
+
+// These names match the Bun FFI type strings OpenTUI uses today. Other
+// backends map them at library load time instead of wrapping every native call.
+export const FFIType = {
+  char: "char",
+  int8_t: "int8_t",
+  i8: "i8",
+  uint8_t: "uint8_t",
+  u8: "u8",
+  int16_t: "int16_t",
+  i16: "i16",
+  uint16_t: "uint16_t",
+  u16: "u16",
+  int32_t: "int32_t",
+  i32: "i32",
+  int: "int",
+  uint32_t: "uint32_t",
+  u32: "u32",
+  int64_t: "int64_t",
+  i64: "i64",
+  uint64_t: "uint64_t",
+  u64: "u64",
+  double: "double",
+  f64: "f64",
+  float: "float",
+  f32: "f32",
+  bool: "bool",
+  ptr: "ptr",
+  pointer: "pointer",
+  void: "void",
+  cstring: "cstring",
+  function: "function",
+  usize: "usize",
+  callback: "callback",
+  napi_env: "napi_env",
+  napi_value: "napi_value",
+  buffer: "buffer",
+} as const
+
+export type FFIType = (typeof FFIType)[keyof typeof FFIType]
+// Kept as a source-shape compatibility alias for Bun-style call sites.
+export type FFITypeOrString = FFIType
+
+// A function definition describes one native symbol. `ptr` overrides the symbol
+// address and follows the same pointer safety rules as normal pointer values.
+export interface FFIFunction {
+  readonly args?: readonly FFITypeOrString[]
+  readonly returns?: FFITypeOrString
+  readonly ptr?: Pointer
+  readonly threadsafe?: boolean
+}
+
+// A callback instance owns a native trampoline. `close()` invalidates `ptr`;
+// callers must not pass that pointer to native code after close.
+export interface FFICallbackInstance {
+  readonly ptr: Pointer | null
+  readonly threadsafe: boolean
+  close(): void
+}
+
+// A loaded library owns callbacks created through `createCallback()`.
+//
+// Typical use:
+// const callback = library.createCallback(handler, { args: ["ptr"], returns: "void" })
+// library.symbols.setLogCallback(callback.ptr)
+//
+// `close()` first closes the native library, then closes any callbacks that
+// remain open.
+export interface Library<Fns extends Record<string, FFIFunction>> {
+  symbols: { [K in keyof Fns]: (...args: any[]) => any }
+  createCallback(callback: (...args: any[]) => any, definition: FFIFunction): FFICallbackInstance
+  close(): void
+}
+
+// A backend normalizes runtime differences once. Do not wrap hot symbol calls
+// here unless a backend must adapt them.
+interface FfiBackend {
+  dlopen<Fns extends Record<string, FFIFunction>>(path: string | URL, symbols: Fns): Library<Fns>
+  ptr(value: PointerSource): Pointer
+  suffix: string
+  toArrayBuffer(pointer: Pointer, offset: number | undefined, length: number): ArrayBuffer
+}
+
+interface BunFFIFunction {
+  readonly args?: readonly FFITypeOrString[]
+  readonly returns?: FFITypeOrString
+  readonly ptr?: BunPointer
+  readonly threadsafe?: boolean
+}
+
+interface BunFfiLibrary<Fns extends Record<string, BunFFIFunction>> {
+  symbols: { [K in keyof Fns]: (...args: any[]) => any }
+  close(): void
+}
+
+interface BunFfiBackend {
+  JSCallback: new (callback: (...args: any[]) => any, definition: BunFFIFunction) => FFICallbackInstance
+  dlopen<Fns extends Record<string, BunFFIFunction>>(path: string | URL, symbols: Fns): BunFfiLibrary<Fns>
+  ptr(value: PointerSource): Pointer
+  suffix: string
+  toArrayBuffer(pointer: BunPointer, offset: number | undefined, length: number): ArrayBuffer
+}
+
+interface NodeFFIFunction {
+  readonly arguments: readonly string[]
+  readonly return: string
+}
+
+interface NodeDynamicLibrary {
+  close(): void
+  registerCallback(signature: NodeFFIFunction, callback: (...args: any[]) => any): bigint
+  unregisterCallback(pointer: bigint): void
+}
+
+interface NodeFfiLibrary {
+  readonly lib: NodeDynamicLibrary
+  readonly functions: Record<string, (...args: any[]) => any>
+}
+
+interface NodeFfiBackend {
+  dlopen(path: string | null, symbols: Record<string, NodeFFIFunction>): NodeFfiLibrary
+  getRawPointer(source: ArrayBuffer): bigint
+  suffix: string
+  toArrayBuffer(pointer: bigint, length: number, copy?: boolean): ArrayBuffer
+}
+
+export const FFI_UNAVAILABLE = "OpenTUI native FFI is not available for this runtime yet"
+export const BUN_DLOPEN_NULL = "Bun FFI backend does not support dlopen(null)"
+export const LIBRARY_CLOSED = "Cannot create FFI callback after library.close() has been called"
+export const NODE_CALLBACK_THREADSAFE =
+  "Node FFI callbacks are same-thread only and do not support threadsafe callbacks"
+export const NODE_NAPI_UNSUPPORTED = "Node FFI backend does not support Bun N-API FFI types"
+export const NODE_POINTER_OVERRIDE = "Node FFI backend does not support FFIFunction.ptr overrides"
+export const NODE_POINTER_ARGUMENT = "Node FFI pointer arguments must be a Pointer, ArrayBuffer, or ArrayBufferView"
+export const NODE_PTR_VALUE =
+  "node:ffi ptr() only supports ArrayBuffer and ArrayBufferView values backed by ArrayBuffer"
+export const NODE_STRING_RETURN = "Node FFI backend does not normalize string return values (yet)"
+export const NODE_USIZE_UNSUPPORTED = "Node FFI backend does not support usize yet"
+export const POINTER_NEGATIVE = "Pointer must be non-negative"
+export const POINTER_OFFSET_NEGATIVE = "Pointer offset must be non-negative"
+export const POINTER_OFFSET_UNSAFE = "Pointer offset must be a safe integer"
+export const POINTER_UNSAFE = "Pointer exceeds safe integer range"
+
+function unavailable(cause?: unknown): never {
+  throw new Error(FFI_UNAVAILABLE, { cause })
+}
+
+// The placeholder backend lets non-Bun runtimes load without errors.
+function createUnsupportedBackend(cause?: unknown): FfiBackend {
+  return {
+    dlopen() {
+      return unavailable(cause)
+    },
+    ptr() {
+      return unavailable(cause)
+    },
+    suffix: "",
+    toArrayBuffer() {
+      return unavailable(cause)
+    },
+  }
+}
+
+const isBun =
+  typeof process !== "undefined" &&
+  typeof process.versions === "object" &&
+  process.versions !== null &&
+  typeof process.versions.bun === "string"
+
+const requireModule = createRequire(import.meta.url)
+const backend = loadBackend()
+
+function loadBackend(): FfiBackend {
+  // Keep the Bun module import behind the runtime check so Node does not
+  // resolve bun:ffi during import.
+  if (isBun) {
+    return createBunBackend(requireModule("bun:ffi") as BunFfiBackend)
+  }
+
+  try {
+    const nodeFfi = requireModule("node:ffi") as NodeFfiBackend & { default?: NodeFfiBackend }
+    return createNodeBackend(nodeFfi.default ?? nodeFfi)
+  } catch (error) {
+    return createUnsupportedBackend(error)
+  }
+}
+
+// Normalize foreign pointer-like values into the current runtime's pointer
+// representation before passing them to native code.
+export function toPointer(value: PointerInput): Pointer {
+  if (isBun && typeof value === "bigint") {
+    return toSafeNumberPointer(value) as Pointer
+  }
+
+  if (!isBun && typeof value === "number") {
+    return toSafeBigIntPointer(value) as Pointer
+  }
+
+  return value as Pointer
+}
+
+export function ffiBool(value: boolean): 0 | 1 {
+  return value ? 1 : 0
+}
+
+// Convert a bigint pointer to a number only when JavaScript can represent it
+// exactly. A rounded pointer would target the wrong address.
+function toSafeNumberPointer(pointer: bigint): number {
+  if (pointer < 0n) {
+    throw new Error(POINTER_NEGATIVE)
+  }
+
+  if (pointer > BigInt(Number.MAX_SAFE_INTEGER)) {
+    throw new Error(POINTER_UNSAFE)
+  }
+
+  return Number(pointer)
+}
+
+function toSafeBigIntPointer(pointer: number): bigint {
+  if (pointer < 0) {
+    throw new Error(POINTER_NEGATIVE)
+  }
+
+  if (!Number.isSafeInteger(pointer)) {
+    throw new Error(POINTER_UNSAFE)
+  }
+
+  return BigInt(pointer)
+}
+
+// Wrap a backend callback so the loaded library can close it later. The wrapper
+// keeps `ptr` live until close, then clears it so callers cannot reuse a stale
+// trampoline pointer.
+function createManagedCallback(raw: FFICallbackInstance, callbacks: Set<FFICallbackInstance>): FFICallbackInstance {
+  let ptr = raw.ptr
+  let closed = false
+
+  const instance: FFICallbackInstance = {
+    get ptr() {
+      return ptr
+    },
+    get threadsafe() {
+      return raw.threadsafe
+    },
+    close() {
+      if (closed) {
+        return
+      }
+
+      closed = true
+      callbacks.delete(instance)
+      try {
+        raw.close()
+      } finally {
+        // Clear the pointer even if the backend close throws. The trampoline is
+        // no longer safe to use.
+        ptr = null
+      }
+    },
+  }
+
+  callbacks.add(instance)
+
+  return instance
+}
+
+function normalizeBunDefinitions<Fns extends Record<string, FFIFunction>>(
+  definitions: Fns,
+): { [K in keyof Fns]: BunFFIFunction } {
+  // Normalize all Bun definitions before `dlopen()`. Bun rejects bigint pointer
+  // overrides, so convert them once before loading the native library.
+  return Object.fromEntries(
+    Object.entries(definitions).map(([name, definition]) => [name, normalizeBunDefinition(definition)]),
+  ) as { [K in keyof Fns]: BunFFIFunction }
+}
+
+function normalizeBunDefinition(definition: FFIFunction): BunFFIFunction {
+  return {
+    args: definition.args,
+    returns: definition.returns,
+    ptr: definition.ptr == null ? undefined : toBunPointer(definition.ptr),
+    threadsafe: definition.threadsafe,
+  }
+}
+
+// Convert Pointer pointers to Bun pointers at the Bun boundary only.
+function toBunPointer(pointer: Pointer): BunPointer {
+  return typeof pointer === "bigint" ? toSafeNumberPointer(pointer) : pointer
+}
+
+// Create a Bun backend from bun:ffi.
+export function createBunBackend(bun: BunFfiBackend): FfiBackend {
+  return {
+    dlopen(path, symbols) {
+      if (path === null) {
+        throw new Error(BUN_DLOPEN_NULL)
+      }
+
+      const library = bun.dlopen(path, normalizeBunDefinitions(symbols))
+      const callbacks = new Set<FFICallbackInstance>()
+      let closed = false
+
+      return {
+        symbols: library.symbols,
+        createCallback(callback, definition) {
+          if (closed) {
+            // A closed library no longer owns native state. New callbacks would
+            // have no cleanup path.
+            throw new Error(LIBRARY_CLOSED)
+          }
+
+          // Bun callbacks are standalone objects. OpenTUI treats them as
+          // library-owned to match the future Node FFI shape and to avoid
+          // leaked trampolines.
+          const raw = new bun.JSCallback(callback, normalizeBunDefinition(definition))
+
+          return createManagedCallback(raw, callbacks)
+        },
+        close() {
+          if (closed) {
+            return
+          }
+
+          closed = true
+
+          try {
+            // Close native state while callbacks still point to live
+            // trampolines. Native teardown may call back during final cleanup.
+            library.close()
+          } finally {
+            // After native teardown, close any JS trampolines the caller did
+            // not close explicitly.
+            for (const callback of [...callbacks]) {
+              callback.close()
+            }
+          }
+        },
+      }
+    },
+    ptr: bun.ptr,
+    suffix: bun.suffix,
+    toArrayBuffer(pointer, offset, length) {
+      // Bun only accepts numeric pointers here. Keep the coercion at this
+      // backend boundary.
+      return bun.toArrayBuffer(toBunPointer(pointer), offset, length)
+    },
+  }
+}
+
+// Create a Node backend from node:ffi.
+export function createNodeBackend(nodeFfi: NodeFfiBackend): FfiBackend {
+  return {
+    dlopen(path, symbols) {
+      const { lib, functions } = nodeFfi.dlopen(toNodeLibraryPath(path), normalizeNodeDefinitions(symbols))
+      const callbacks = new Set<FFICallbackInstance>()
+      let closed = false
+      let libraryClosed = false
+
+      return {
+        symbols: wrapNodeSymbols(functions, symbols),
+        createCallback(callback, definition) {
+          if (closed) {
+            throw new Error(LIBRARY_CLOSED)
+          }
+
+          if (definition.threadsafe) {
+            throw new Error(NODE_CALLBACK_THREADSAFE)
+          }
+
+          const callbackPointer = lib.registerCallback(normalizeNodeDefinition(definition), callback)
+          const raw: FFICallbackInstance = {
+            ptr: callbackPointer as Pointer,
+            threadsafe: false,
+            close() {
+              if (!libraryClosed) {
+                lib.unregisterCallback(callbackPointer)
+              }
+            },
+          }
+
+          return createManagedCallback(raw, callbacks)
+        },
+        close() {
+          if (closed) {
+            return
+          }
+
+          closed = true
+
+          try {
+            libraryClosed = true
+            lib.close()
+          } finally {
+            for (const callback of [...callbacks]) {
+              callback.close()
+            }
+          }
+        },
+      }
+    },
+    ptr(value) {
+      return toNodeSourcePointer(nodeFfi, value) as Pointer
+    },
+    suffix: nodeFfi.suffix,
+    toArrayBuffer(pointer, offset, length) {
+      return nodeFfi.toArrayBuffer(toBigIntPointer(pointer) + toNodePointerOffset(offset), length, false)
+    },
+  }
+}
+
+function toNodeLibraryPath(path: string | URL | null): string | null {
+  return path instanceof URL ? fileURLToPath(path) : path
+}
+
+function normalizeNodeDefinitions<Fns extends Record<string, FFIFunction>>(
+  definitions: Fns,
+): Record<string, NodeFFIFunction> {
+  return Object.fromEntries(
+    Object.entries(definitions).map(([name, definition]) => [name, normalizeNodeDefinition(definition)]),
+  )
+}
+
+function wrapNodeSymbols<Fns extends Record<string, FFIFunction>>(
+  functions: Record<string, (...args: any[]) => any>,
+  definitions: Fns,
+): { [K in keyof Fns]: (...args: any[]) => any } {
+  return Object.fromEntries(
+    Object.entries(functions).map(([name, fn]) => [name, wrapNodeSymbol(fn, definitions[name])]),
+  ) as { [K in keyof Fns]: (...args: any[]) => any }
+}
+
+function wrapNodeSymbol(fn: (...args: any[]) => any, definition: FFIFunction): (...args: any[]) => any {
+  const pointerArgIndexes = (definition.args ?? []).flatMap((type, index) =>
+    isNodePointerArgumentType(type) ? [index] : [],
+  )
+
+  if (pointerArgIndexes.length === 0) {
+    return fn
+  }
+
+  return (...args: any[]) => {
+    const normalizedArgs = args.slice()
+
+    for (const index of pointerArgIndexes) {
+      normalizedArgs[index] = toNodePointerArgument(normalizedArgs[index])
+    }
+
+    return fn(...normalizedArgs)
+  }
+}
+
+function isNodePointerArgumentType(type: FFITypeOrString): boolean {
+  return type === FFIType.ptr || type === FFIType.pointer || type === FFIType.function || type === FFIType.callback
+}
+
+function toNodePointerArgument(value: unknown): bigint | ArrayBuffer | ArrayBufferView {
+  if (value == null) {
+    return 0n
+  }
+
+  if (typeof value === "number" || typeof value === "bigint") {
+    return toBigIntPointer(value as Pointer)
+  }
+
+  if (ArrayBuffer.isView(value)) {
+    if (!(value.buffer instanceof ArrayBuffer)) {
+      throw new TypeError(NODE_PTR_VALUE)
+    }
+
+    if (value.byteLength === 0) {
+      return 0n
+    }
+
+    return value
+  }
+
+  if (value instanceof ArrayBuffer) {
+    if (value.byteLength === 0) {
+      return 0n
+    }
+
+    return value
+  }
+
+  throw new TypeError(NODE_POINTER_ARGUMENT)
+}
+
+function toNodeSourcePointer(nodeFfi: NodeFfiBackend, value: PointerSource): bigint {
+  if (ArrayBuffer.isView(value)) {
+    if (!(value.buffer instanceof ArrayBuffer)) {
+      throw new TypeError(NODE_PTR_VALUE)
+    }
+
+    return nodeFfi.getRawPointer(value.buffer) + BigInt(value.byteOffset)
+  }
+
+  if (value instanceof ArrayBuffer) {
+    return nodeFfi.getRawPointer(value)
+  }
+
+  throw new TypeError(NODE_PTR_VALUE)
+}
+
+function toNodePointerOffset(offset: number | undefined): bigint {
+  if (offset == null) {
+    return 0n
+  }
+
+  if (offset < 0) {
+    throw new Error(POINTER_OFFSET_NEGATIVE)
+  }
+
+  if (!Number.isSafeInteger(offset)) {
+    throw new Error(POINTER_OFFSET_UNSAFE)
+  }
+
+  return BigInt(offset)
+}
+
+function normalizeNodeDefinition(definition: FFIFunction): NodeFFIFunction {
+  if (definition.ptr != null) {
+    throw new Error(NODE_POINTER_OVERRIDE)
+  }
+
+  return {
+    arguments: (definition.args ?? []).map((type) => toNodeFFIType(type, "parameter")),
+    return: toNodeFFIType(definition.returns ?? FFIType.void, "result"),
+  }
+}
+
+function toNodeFFIType(type: FFITypeOrString, position: "parameter" | "result"): string {
+  switch (type) {
+    case FFIType.char:
+      return "char"
+    case FFIType.int8_t:
+    case FFIType.i8:
+      return "i8"
+    case FFIType.uint8_t:
+    case FFIType.u8:
+      return "u8"
+    case FFIType.int16_t:
+    case FFIType.i16:
+      return "i16"
+    case FFIType.uint16_t:
+    case FFIType.u16:
+      return "u16"
+    case FFIType.int32_t:
+    case FFIType.int:
+    case FFIType.i32:
+      return "i32"
+    case FFIType.uint32_t:
+    case FFIType.u32:
+      return "u32"
+    case FFIType.int64_t:
+    case FFIType.i64:
+      return "i64"
+    case FFIType.uint64_t:
+    case FFIType.u64:
+      return "u64"
+    case FFIType.double:
+    case FFIType.f64:
+      return "f64"
+    case FFIType.float:
+    case FFIType.f32:
+      return "f32"
+    case FFIType.bool:
+      return "bool"
+    case FFIType.ptr:
+    case FFIType.pointer:
+      return "pointer"
+    case FFIType.void:
+      return "void"
+    case FFIType.cstring:
+      // TODO(audit): cstring vs string semantics differ between backends.
+      //
+      // The type-name mapping here is intentional, but the runtime marshalling
+      // is not equivalent:
+      //   - Bun's `cstring` parameter rejects raw JavaScript strings; callers
+      //     must pass a TypedArray, a Pointer, or a CString.
+      //   - Node's `string` parameter copies a JavaScript string to a
+      //     temporary NUL-terminated UTF-8 buffer for the duration of the
+      //     call.
+      //
+      // Callsites should encode strings into byte buffers and pass pointers
+      // instead of relying on either backend's string handling.
+      if (position === "result") {
+        throw new Error(NODE_STRING_RETURN)
+      }
+
+      return "string"
+    case FFIType.function:
+    case FFIType.callback:
+      // Pointer-like types (pointer, string, buffer, arraybuffer, and function)
+      // are all passed as pointers in node:ffi.
+      return "pointer"
+    case FFIType.usize:
+      // `usize` needs an ABI audit before Node support; use u64 would require
+      // BigInt call sites and u32 can truncate pointers.
+      throw new Error(NODE_USIZE_UNSUPPORTED)
+    case FFIType.napi_env:
+    case FFIType.napi_value:
+      // Bun's N-API bridge types are not equivalent to raw Node FFI pointers.
+      throw new Error(NODE_NAPI_UNSUPPORTED)
+    case FFIType.buffer:
+      return "buffer"
+    default:
+      return unsupportedNodeFFIType(type)
+  }
+}
+
+function unsupportedNodeFFIType(type: never): never {
+  throw new Error(`Unsupported FFIType for node:ffi: ${String(type)}`)
+}
+
+function toBigIntPointer(pointer: Pointer): bigint {
+  if (typeof pointer === "bigint") {
+    if (pointer < 0n) {
+      throw new Error(POINTER_NEGATIVE)
+    }
+
+    return pointer
+  }
+
+  return toSafeBigIntPointer(pointer)
+}
+
+export const dlopen = backend.dlopen
+export const ptr = backend.ptr
+export const suffix = backend.suffix
+export const toArrayBuffer = backend.toArrayBuffer

package/src/platform/runtime.test.ts

@@ -0,0 +1,52 @@
+import { describe, expect, test } from "bun:test"
+import { fileURLToPath } from "node:url"
+
+import { resolveBundledFilePath } from "./runtime.js"
+
+describe("platform/runtime", () => {
+  test("resolves bundled file paths through the active runtime path", async () => {
+    const bundledUrl = new URL("./bundled-tree-sitter.wasm", import.meta.url).href
+    const fallbackUrl = new URL("./fallback-tree-sitter.wasm", import.meta.url)
+    let fallbackCalled = false
+
+    const resolved = await resolveBundledFilePath(
+      async () => ({ default: bundledUrl }),
+      () => {
+        fallbackCalled = true
+        return fallbackUrl
+      },
+      import.meta.url,
+    )
+
+    const isBun = typeof process.versions?.bun === "string"
+
+    expect(resolved).toBe(fileURLToPath(isBun ? bundledUrl : fallbackUrl))
+    expect(fallbackCalled).toBe(!isBun)
+  })
+
+  test("resolves Bun-emitted asset modules when a non-Bun bundle has no source fallback", async () => {
+    const bundledUrl = new URL("./bundled-tree-sitter.wasm", import.meta.url).href
+    const bundledModuleSpecifier = `data:text/javascript,${encodeURIComponent(
+      `export default ${JSON.stringify(bundledUrl)}`,
+    )}`
+    const loadBundledFile = async (): Promise<{ default: string }> => {
+      if (typeof process.versions?.bun === "string") {
+        return { default: bundledUrl }
+      }
+
+      throw new TypeError("Import attribute type=file is not supported")
+    }
+
+    Object.defineProperty(loadBundledFile, "toString", {
+      value: () => `() => import(${JSON.stringify(bundledModuleSpecifier)}, { with: { type: "file" } })`,
+    })
+
+    const resolved = await resolveBundledFilePath(
+      loadBundledFile,
+      "./missing-bundled-tree-sitter.wasm",
+      import.meta.url,
+    )
+
+    expect(resolved).toBe(fileURLToPath(bundledUrl))
+  })
+})