feat: add Linux cooperative run-loop drain via g_main_context_iteration

Author: ipfizz

src/main/platform/linux/glib-ffi.ts

@@ -0,0 +1,41 @@
+import { dlopen, FFIType } from 'bun:ffi';
+import { UnsupportedPlatformError } from '../../../common/errors';
+import { currentPlatform } from '../../../common/platform';
+
+/**
+ * Loads GLib's main-context iteration symbols.
+ *
+ * GLib (not GTK directly) owns the main-loop primitives Sambar uses to pump the
+ * Linux UI cooperatively, mirroring the macOS CoreFoundation pump (D020).
+ * `libglib-2.0` is a hard dependency of GTK 4, so it is always present wherever
+ * `libgtk-4` is.
+ *
+ * `g_main_context_iteration(context, may_block)` dispatches at most one set of
+ * ready sources; a `NULL` context means the default one. `g_main_context_pending`
+ * reports whether any sources are ready, letting us drain to quiescence without
+ * ever blocking Bun's thread.
+ *
+ * Only callable on Linux — throws {@link UnsupportedPlatformError} otherwise so
+ * the module stays safely importable on macOS for unit testing.
+ */
+
+const LIBGLIB_PATH = 'libglib-2.0.so.0';
+
+export const loadGlibFFI = () => {
+  const platform = currentPlatform();
+  if (platform !== 'linux') {
+    throw new UnsupportedPlatformError(
+      `loadGlibFFI() is only supported on Linux; current platform is ${platform}`,
+    );
+  }
+  return dlopen(LIBGLIB_PATH, {
+    g_main_context_iteration: {
+      args: [FFIType.pointer, FFIType.i32],
+      returns: FFIType.i32,
+    },
+    g_main_context_pending: {
+      args: [FFIType.pointer],
+      returns: FFIType.i32,
+    },
+  });
+};

src/main/platform/linux/gtk-run-loop.ts

@@ -0,0 +1,33 @@
+import { loadGlibFFI } from './glib-ffi';
+
+/**
+ * Linux native run-loop drain.
+ *
+ * The Linux analogue of the macOS CF drain (D020): the {@link CooperativePump}
+ * calls this each tick to service GTK/GLib events without blocking Bun's thread.
+ * We iterate the default main context while it reports pending sources, never
+ * blocking (`may_block = FALSE`), bounded by a per-tick budget so a busy loop
+ * cannot starve Bun's own event loop.
+ */
+
+const NULL_CONTEXT = null;
+const MAY_BLOCK_FALSE = 0;
+
+/** Upper bound on inner iterations per tick. */
+const DRAIN_BUDGET = 256;
+
+/**
+ * Create the Linux drain function. Throws {@link UnsupportedPlatformError} off
+ * Linux (via the loader). Cheap to call repeatedly; never blocks.
+ */
+export const createLinuxDrain = (): (() => void) => {
+  const glib = loadGlibFFI();
+  return () => {
+    for (let i = 0; i < DRAIN_BUDGET; i += 1) {
+      if (glib.symbols.g_main_context_pending(NULL_CONTEXT) === 0) {
+        break;
+      }
+      glib.symbols.g_main_context_iteration(NULL_CONTEXT, MAY_BLOCK_FALSE);
+    }
+  };
+};

tests/integration/linux/gtk-run-loop.test.ts

@@ -0,0 +1,15 @@
+import { describe, expect, test } from 'bun:test';
+import { currentPlatform } from '../../../src/common/platform';
+import { createLinuxDrain } from '../../../src/main/platform/linux/gtk-run-loop';
+
+if (currentPlatform() === 'linux') {
+  describe('createLinuxDrain', () => {
+    test('returns a drain that runs many times without crashing', () => {
+      const drain = createLinuxDrain();
+      for (let i = 0; i < 50; i += 1) {
+        drain();
+      }
+      expect(typeof drain).toBe('function');
+    });
+  });
+}

tests/unit/main/platform/linux/gtk-run-loop.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, test } from 'bun:test';
+import { UnsupportedPlatformError } from '../../../../../src/common/errors';
+import { currentPlatform } from '../../../../../src/common/platform';
+import { createLinuxDrain } from '../../../../../src/main/platform/linux/gtk-run-loop';
+
+describe('createLinuxDrain export', () => {
+  test('is a function', () => {
+    expect(typeof createLinuxDrain).toBe('function');
+  });
+});
+
+if (currentPlatform() !== 'linux') {
+  describe('createLinuxDrain on non-Linux hosts', () => {
+    test('throws UnsupportedPlatformError', () => {
+      expect(() => createLinuxDrain()).toThrow(UnsupportedPlatformError);
+    });
+  });
+}