@gjsify/rolldown-native 0.22.0 → 0.24.1

package/README.md

@@ -1,6 +1,6 @@
 # @gjsify/rolldown-native
 
-A native Rust cdylib + Vala/GObject bridge that wraps the Rust `rolldown` bundler and exposes it to GJS via `gi://`. This is the default bundler engine used by `gjsify build` under GJS — npm's `rolldown` is an N-API addon that cannot load in GJS, so this bridge is how gjsify bundles without a Node runtime. Includes a complete plugin bridge (`bundleWithPlugins`) for load, transform, resolveId, and render-chunk hooks. Ships prebuilt `.so` + `.typelib` for Linux.
+A native Rust cdylib + Vala/GObject bridge that wraps the Rust `rolldown` bundler and exposes it to GJS via `gi://`. This is the default bundler engine used by `gjsify build` under GJS — npm's `rolldown` is an N-API addon that cannot load in GJS, so this bridge is how gjsify bundles without a Node runtime. Includes a complete plugin bridge (`bundleWithPlugins`) for load, transform, resolveId, and render-chunk hooks. Ships prebuilt `.so` + `.typelib` for **Linux**; the source is now platform-neutral and cross-compiles for macOS, but no macOS prebuild is published yet — see [Platform coverage](#platform-coverage).
 
 Part of the [gjsify](https://github.com/gjsify/gjsify) project — Node.js and Web APIs for GJS (GNOME JavaScript).
 
@@ -30,6 +30,60 @@ if (hasNativeRolldown()) {
 
 Under normal usage `@gjsify/rolldown-native` is consumed automatically by the gjsify CLI (`gjsify build`) — direct use is only needed when embedding the bundler in custom build tooling.
 
+## Platform coverage
+
+| Platform | Prebuild | Built by |
+|---|---|---|
+| `linux-x64` | ✅ `.so` + `.gir` + `.typelib` | native runner |
+| `linux-arm64` | ✅ | native runner |
+| `linux-ppc64`, `linux-s390x`, `linux-riscv64` | ❌ | not built — the rolldown crate graph is too slow under QEMU |
+| macOS (`darwin-arm64`) | ⏳ source-ready, no prebuild yet | pending a green `prebuilds.yml` macOS leg |
+| macOS (`darwin-x64`) | ❌ | — |
+| Windows | ❌ | — no Vala/GI bridge in this repo targets Windows |
+
+All prebuilds are produced by [`.github/workflows/prebuilds.yml`](../../../.github/workflows/prebuilds.yml)
+and committed back to the repository.
+
+### macOS status
+
+The **Rust-level blocker is gone.** The core used to wake the GLib main loop through three
+`libc::eventfd(2)` descriptors — a Linux syscall the `libc` crate does not even expose on
+Apple targets, so `cargo build` could not compile at all there. The wakeup channel is now a
+plain anonymous pipe (`src/rust/src/wakeup.rs`), one portable implementation used on every
+platform, so the crate cross-compiles: `cargo check --target aarch64-apple-darwin` is green.
+`meson.build` was already macOS-ready (`.dylib` naming, `@loader_path` rpath).
+
+What is still missing is a **native macOS build**: the `.dylib` + `.gir` + `.typelib` have to
+be produced and load-tested by the `prebuilds.yml` darwin leg (Homebrew `vala`, `gobject-
+introspection`, `json-glib`, `gjs`) before `darwin-arm64` is added to `package.json`'s
+`gjsify.platforms` and a prebuild is committed. Until that leg is green, treat macOS as
+unproven — a cross-`check` does not exercise linking, the GIR/typelib step, or `gi://` load.
+
+Because `@gjsify/rolldown-native` is the only bundler engine available to `gjsify build`
+under GJS, it is the last package gating a Node-free gjsify toolchain on macOS —
+`@gjsify/lightningcss-native` and `@gjsify/oxfmt-native` already ship `darwin-arm64`
+prebuilds.
+
+### Wakeup channel (implementation note)
+
+Three pipes carry "a plugin hook fired" / "the build finished" / "a `this.resolve()` result
+is ready" from the tokio worker threads to the GLib main loop, which watches their read ends
+with `GLib.IOChannel.unix_new()` + `add_watch()`. Two properties are load-bearing and easy to
+break:
+
+- **Both ends are `O_NONBLOCK` and a full buffer is not an error.** A pipe (unlike an eventfd
+  counter) can fill up. The writer never blocks a tokio worker; an `EAGAIN` write is dropped
+  on purpose, because a full buffer means the reader still owes a drain cycle — and the
+  reader drains the pipe *before* it re-drains the request queue, so nothing is lost.
+- **The reader consumes everything available**, not one fixed-size chunk. GLib's watch is
+  level-triggered, so leftover bytes re-dispatch the callback — re-draining the queue for
+  nothing — once per chunk until the pipe empties. Draining to `EAGAIN` collapses a burst of
+  N hook wakeups back into a single main-loop iteration, which is the coalescing the eventfd
+  counter used to provide for free.
+
+Both ends are also `FD_CLOEXEC`, so a subprocess spawned from a plugin hook cannot inherit a
+wakeup fd.
+
 ## License
 
 MIT

package/meson.build

@@ -21,6 +21,52 @@ vala_deps = [
     dependency('json-glib-1.0'),
 ]
 
+# ----------------------------------------------------------------------------
+# Host-dependent naming + runtime-lookup conventions
+#
+# Three things differ per host and MUST agree, or the prebuild loads on one
+# platform and silently fails on the other (mirrors @gjsify/napi's meson
+# branch):
+#
+#   1. cargo's cdylib leaf     — libgjsify_rolldown.{so,dylib}
+#   2. meson's library() leaf  — libgjsifyrolldown.{so,dylib}; the typelib
+#      records this name and gjs' g_module_open() resolves exactly it at load.
+#   3. how the Vala library finds its sibling Rust cdylib at runtime. Both
+#      files ship side by side in prebuilds/<platform>-<arch>/, so the lookup
+#      must be relative to the loading binary: $ORIGIN on ELF, @loader_path on
+#      Mach-O. On macOS this is load-bearing — unlike Linux (where the CLI
+#      exports LD_LIBRARY_PATH for the prebuild dir) nothing sets
+#      DYLD_LIBRARY_PATH, so the rpath is the ONLY way the cdylib is found.
+#
+# The Rust core is platform-neutral: it wakes the GLib main loop through three
+# anonymous pipes (src/rust/src/wakeup.rs), not the Linux-only `eventfd(2)` it
+# used to, so `cargo build` compiles for Apple targets too. Verified with
+# `cargo check --target aarch64-apple-darwin`; the first NATIVE macOS build is
+# what `prebuilds.yml`'s darwin leg has to prove before `package.json`'s
+# `gjsify.platforms` gains `darwin-arm64`.
+# The branch below is kept in lockstep with its lightningcss/oxfmt siblings.
+# ----------------------------------------------------------------------------
+host_system = host_machine.system()
+
+if host_system == 'darwin'
+    rust_cdylib_name = 'libgjsify_rolldown.dylib'
+    shared_lib_name = 'libgjsifyrolldown.dylib'
+    lib_rpath = '@loader_path'
+    # Normalise the cdylib's LC_ID_DYLIB to @rpath/<leaf> BEFORE the Vala
+    # library links against it: ld64 copies the dependency's install name
+    # verbatim into the dependent's LC_LOAD_DYLIB. rustc's own install name has
+    # varied across releases (absolute build path in older rustc, @rpath/<leaf>
+    # in current ones); pinning it here makes the recorded dependency
+    # rustc-version-independent, and @rpath/ is never longer than an absolute
+    # path so install_name_tool can always rewrite in place.
+    rust_cdylib_post = ' && install_name_tool -id "@rpath/' + rust_cdylib_name + '" "$3"'
+else
+    rust_cdylib_name = 'libgjsify_rolldown.so'
+    shared_lib_name = 'libgjsifyrolldown.so'
+    lib_rpath = '$ORIGIN'
+    rust_cdylib_post = ''
+endif
+
 # ----------------------------------------------------------------------------
 # Rust cdylib (cargo)
 # ----------------------------------------------------------------------------
@@ -31,15 +77,17 @@ rust_sources = files(
     'src/rust/src/lib.rs',
     'src/rust/src/plugin_proxy.rs',
     'src/rust/src/session.rs',
+    'src/rust/src/wakeup.rs',
 )
 
 rust_target_dir = meson.current_build_dir() / 'cargo-target'
 
 rust_cdylib = custom_target('gjsify-rolldown-rust',
     input:  rust_sources,
-    output: 'libgjsify_rolldown.so',
+    output: rust_cdylib_name,
     command: ['sh', '-c',
-              'cargo build --release --manifest-path "$1" --target-dir "$2" && cp "$2/release/libgjsify_rolldown.so" "$3"',
+              'cargo build --release --manifest-path "$1" --target-dir "$2" && cp "$2/release/'
+                  + rust_cdylib_name + '" "$3"' + rust_cdylib_post,
               'sh',
               meson.current_source_dir() / 'src/rust/Cargo.toml',
               rust_target_dir,
@@ -69,7 +117,11 @@ libGjsifyRolldown = library('gjsifyrolldown', sources,
     link_depends: rust_cdylib,
     install: true,
     install_dir: [true, true, true, true],
-    install_rpath: '$ORIGIN',
+    # `build_rpath` (not just `install_rpath`) is what matters for the prebuild:
+    # the artifact shipped in prebuilds/ is copied straight out of the build
+    # dir, never through `meson install`, so only the build-tree rpath survives.
+    build_rpath: lib_rpath,
+    install_rpath: lib_rpath,
 )
 
 g_ir_compiler = find_program('g-ir-compiler')
@@ -77,7 +129,7 @@ g_ir_compiler = find_program('g-ir-compiler')
 custom_target(meson.project_name() + '-1.0.typelib',
     command: [
         g_ir_compiler,
-        '--shared-library', 'libgjsifyrolldown.so',
+        '--shared-library', shared_lib_name,
         '--output', '@OUTPUT@',
         meson.current_build_dir() / meson.project_name() + '-1.0.gir',
     ],

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/rolldown-native",
-    "version": "0.22.0",
+    "version": "0.24.1",
     "description": "Phase D-2 POC: Vala/GObject + Rust cdylib bridge to rolldown for GJS. Wraps `rolldown::Bundler::generate()` (async, tokio) in a per-call current-thread runtime so JS sees a sync `bundle()` call. JSON-encoded BundlerOptions in, JSON-encoded BundleOutput out — the boundary stays small even though rolldown's option surface is enormous. POC scope: no JS plugins (Phase B), no watch/HMR, no incremental builds. Companion to `@gjsify/lightningcss-native`; together they remove the last two Rust-crate runtime blockers from the gjsify build pipeline (Phase D-3 unblock).",
     "type": "module",
     "main": "lib/esm/index.js",
@@ -20,7 +20,17 @@
         "src/vala"
     ],
     "gjsify": {
+        "platforms": [
+            "linux-x64",
+            "linux-arm64"
+        ],
         "prebuilds": "prebuilds",
+        "refsLockstep": {
+            "refs/rolldown": {
+                "npm": "rolldown",
+                "tag": "v{version}"
+            }
+        },
         "tier": 1
     },
     "scripts": {
@@ -30,9 +40,9 @@
         "init:meson:wipe": "gjsify run init:meson --wipe",
         "build": "gjsify run build:gjsify && gjsify run build:types",
         "build:gjsify": "gjsify build --library 'src/ts/**/*.{ts,js}'",
-        "build:meson": "gjsify run init:meson && meson compile -C build",
+        "build:meson": "node ../../../scripts/check-refs-pin.mjs . && gjsify run init:meson && meson compile -C build",
         "build:types": "gjsify tsc",
-        "build:prebuilds": "gjsify run build:meson && mkdir -p prebuilds/linux-x86_64 && cp build/libgjsifyrolldown.so build/libgjsify_rolldown.so build/GjsifyRolldown-1.0.gir build/GjsifyRolldown-1.0.typelib prebuilds/linux-x86_64/"
+        "build:prebuilds": "gjsify run build:meson && node ../../../scripts/stage-prebuild.mjs ."
     },
     "keywords": [
         "gjs",
@@ -48,7 +58,7 @@
         "@girs/gobject-2.0": "^4.1.0"
     },
     "devDependencies": {
-        "@gjsify/cli": "^0.22.0",
+        "@gjsify/cli": "^0.24.1",
         "@types/node": "^25.9.2",
         "typescript": "^6.0.3"
     },

package/src/rust/Cargo.toml

@@ -2,6 +2,11 @@
 name = "gjsify_rolldown"
 version = "0.1.0"
 edition = "2024"
+# `std::io::pipe()` (the portable main-loop wakeup channel in src/wakeup.rs)
+# is stable since 1.87. The rolldown graph already needs >= 1.85 for
+# edition2024, so this only makes the stricter bound fail loudly instead of
+# surfacing as a confusing "no function `pipe` in module `std::io`".
+rust-version = "1.87"
 publish = false
 
 [lib]

package/src/rust/src/lib.rs

@@ -36,11 +36,13 @@ use serde::Serialize;
 use tokio::runtime::Builder;
 
 // Plugin-callback machinery (Phase B.1). The session module owns the
-// stateful Bundler instance + tokio runtime + Vala-side eventfd
+// stateful Bundler instance + tokio runtime + the Vala-side wakeup
 // pumps; plugin_proxy holds the JsPluginProxy that bridges
-// rolldown's Pluginable trait to the channel.
+// rolldown's Pluginable trait to the channel; wakeup holds the
+// portable pipe that wakes the GLib main loop.
 pub mod plugin_proxy;
 pub mod session;
+pub mod wakeup;
 
 /// Serializable mirror of the parts of `rolldown_common::Output` we expose to JS.
 ///

package/src/rust/src/plugin_proxy.rs

@@ -14,7 +14,7 @@
 //!   - tokio-task running `Bundler::generate()` on the worker pool
 //!   - calls into JsPluginProxy from various worker threads
 //!   - JsPluginProxy serializes a `HookRequest`, pushes to channel
-//!   - eventfd-write wakes the GLib main loop
+//!   - a byte on the wakeup pipe wakes the GLib main loop
 //!   - Vala source pulls requests, emits GObject signal on main thread
 //!   - JS handler runs, calls `session.respond(req_id, json)`
 //!   - Vala forwards to `gjsify_rolldown_session_respond` extern
@@ -35,8 +35,9 @@ use rolldown_plugin::{
     HookGenerateBundleArgs, HookInjectionOutputReturn, HookLoadArgs, HookLoadOutput,
     HookLoadReturn, HookNoopReturn, HookRenderChunkArgs, HookRenderChunkOutput,
     HookRenderChunkReturn, HookResolveIdArgs, HookResolveIdOutput, HookResolveIdReturn,
-    HookTransformArgs, HookTransformOutput, HookTransformReturn, HookUsage, HookWriteBundleArgs,
-    Plugin, PluginContext, SharedLoadPluginContext, SharedTransformPluginContext,
+    HookTransformArgs, HookTransformOutput, HookTransformOutputMap, HookTransformReturn, HookUsage,
+    HookWriteBundleArgs, Plugin, PluginContext, SharedLoadPluginContext,
+    SharedTransformPluginContext,
 };
 use serde::{Deserialize, Serialize};
 use tokio::sync::oneshot;
@@ -111,7 +112,7 @@ pub enum HookRequestPayload {
 }
 
 /// Wire-format envelope for one hook invocation. Sent over
-/// crossbeam channel; eventfd written after each push.
+/// crossbeam channel; the wakeup pipe is woken after each push.
 pub struct HookRequest {
     pub req_id: u64,
     pub plugin_index: usize,
@@ -277,7 +278,13 @@ impl HookResponse {
                 };
                 Ok(Some(HookTransformOutput {
                     code,
-                    map: None,
+                    // The bridge has no source-map channel at all (JS
+                    // never gets to return one), so this is the explicit
+                    // "no sourcemap intended" case rather than rolldown's
+                    // `Omitted` (= plugin forgot one → SOURCEMAP_BROKEN).
+                    // Matches how upstream migrated its own `map: None`
+                    // call sites when the enum replaced the Option.
+                    map: HookTransformOutputMap::Null,
                     side_effects: None,
                     module_type,
                 }))
@@ -295,7 +302,8 @@ impl HookResponse {
                 let module_type = parse_module_type(v.module_type.as_deref())?;
                 Ok(Some(HookTransformOutput {
                     code: v.code,
-                    map: None,
+                    // See `into_transform_return_with_bytes`.
+                    map: HookTransformOutputMap::Null,
                     side_effects: None,
                     module_type,
                 }))
@@ -312,7 +320,8 @@ impl HookResponse {
                     .map_err(|e| anyhow!("rolldown: malformed renderChunk response: {e}"))?;
                 Ok(Some(HookRenderChunkOutput {
                     code: v.code,
-                    map: None,
+                    // See `into_transform_return_with_bytes`.
+                    map: HookTransformOutputMap::Null,
                 }))
             }
             HookResponse::Error { message, stack } => Err(combine(message, stack)),
@@ -367,11 +376,11 @@ pub struct JsPluginProxy {
     /// Atomic monotonic ID dispenser; shared across all proxies in
     /// the same session via Arc clone in the session constructor.
     pub next_request_id: std::sync::Arc<AtomicU64>,
-    /// Wakeup pipe written after each request.send() so the Vala
+    /// Wakeup pipe woken after each request.send() so the Vala
     /// source on the main loop can react. Owned handle (see
-    /// `SessionShared`): keeps the fd number reserved even when this
+    /// `SessionShared`): keeps both fd numbers reserved even when this
     /// proxy outlives the session's runtime shutdown.
-    pub request_eventfd: std::sync::Arc<std::os::fd::OwnedFd>,
+    pub request_wakeup: std::sync::Arc<crate::wakeup::Wakeup>,
     /// Maximum time we wait for a JS response before failing the
     /// build with a timeout error. Defaults to 60s.
     pub response_timeout: Duration,
@@ -406,7 +415,7 @@ impl JsPluginProxy {
     }
 
     /// Push a hook request onto the channel + wake the main loop via
-    /// eventfd-write, then await the JS-side response.
+    /// the wakeup pipe, then await the JS-side response.
     async fn dispatch(&self, payload: HookRequestPayload) -> anyhow::Result<HookResponse> {
         let (resp, _bytes) = self.dispatch_inner(payload, None, None).await?;
         Ok(resp)
@@ -469,7 +478,10 @@ impl JsPluginProxy {
             return Err(anyhow!("rolldown: plugin channel closed (session aborted)"));
         }
 
-        crate::session::wake_eventfd(&self.request_eventfd);
+        // Wake AFTER the queue push — the reader drains the wakeup pipe
+        // before it drains the queue, so this ordering is what makes a
+        // coalesced (buffer-full) wake safe. See `crate::wakeup`.
+        self.request_wakeup.wake();
 
         let result = tokio::time::timeout(self.response_timeout, reply_rx).await;
         // Clear the context registration regardless of outcome; the
@@ -621,7 +633,10 @@ impl Plugin for JsPluginProxy {
         args: &HookRenderChunkArgs<'_>,
     ) -> impl std::future::Future<Output = HookRenderChunkReturn> + Send {
         let proxies = self.proxies("renderChunk");
-        let code = args.code.clone();
+        // `args.code` is an `Arc<String>` (rolldown keeps the chunk code
+        // recoverable after the hook chain); the wire payload owns its
+        // own String.
+        let code = args.code.as_ref().clone();
         let file_name = args.chunk.filename.to_string();
         let name = args.chunk.name.to_string();
         let is_entry = args.chunk.is_entry;

package/src/rust/src/session.rs

@@ -1,6 +1,6 @@
 //! BundleSession — owns the tokio runtime, the plugin-channel pump,
-//! the eventfd wakeup pair, and the BundleHandle the JS layer uses
-//! to drive the build.
+//! the wakeup pipes, and the BundleHandle the JS layer uses to drive
+//! the build.
 //!
 //! Lifecycle:
 //!   1. `start()` — caller passes options + plugin metadata. We
@@ -8,16 +8,18 @@
 //!      Bundler::with_plugins, spawn a tokio task that drives
 //!      `Bundler::generate()` to completion, return the session.
 //!   2. While the build runs, the worker pool calls into the proxies,
-//!      pushing HookRequests to the channel + writing the request
-//!      eventfd. JS drains via `next_request()` and replies via
+//!      pushing HookRequests to the channel + waking the request
+//!      pipe. JS drains via `next_request()` and replies via
 //!      `respond()`.
 //!   3. When the bundle task completes, the result is stored on the
 //!      session. The Vala side polls `try_take_result()` after
-//!      seeing the request_eventfd close (or its own completion
-//!      eventfd, see Phase B.2 — for B.1 we expose `wait()` only).
+//!      waking on the completion pipe.
+//!
+//! The wakeup channels are plain anonymous pipes on every platform —
+//! see `crate::wakeup` for why (portability) and for the
+//! counter-vs-byte-stream semantics that entails.
 
 use std::ffi::CString;
-use std::os::fd::{AsRawFd, FromRawFd, OwnedFd};
 use std::os::raw::{c_char, c_int};
 use std::ptr;
 use std::sync::Arc;
@@ -35,6 +37,7 @@ use tokio::runtime::{Builder, Runtime};
 use tokio::sync::oneshot;
 
 use crate::plugin_proxy::{HookRequest, HookResponse, JsPluginProxy, PluginMeta};
+use crate::wakeup::Wakeup;
 use crate::{BundleOutputJson, OutputJson, convert_output};
 
 #[derive(Debug, Deserialize)]
@@ -44,7 +47,7 @@ pub struct StartArgs {
 }
 
 /// One context-resolve sub-result flowing Rust → JS. Surfaces through
-/// the `context_response_eventfd` queue.
+/// the `context_response_wakeup` queue.
 #[derive(Debug, Serialize)]
 #[serde(rename_all = "camelCase")]
 pub struct ContextResolveResponse {
@@ -64,16 +67,16 @@ pub struct ContextResolveResponse {
 /// `Arc` and cloned into each proxy. Holds everything the proxies
 /// need to (a) register/unregister parent `PluginContext` snapshots
 /// for nested-protocol callbacks, (b) deliver context-resolve results
-/// to JS via the dedicated eventfd, and (c) accumulate `this.warn()`
+/// to JS via the dedicated wakeup pipe, and (c) accumulate `this.warn()`
 /// strings into the final BundleOutput.
 pub struct SessionShared {
     pub contexts: Mutex<std::collections::HashMap<u64, PluginContext>>,
     pub next_child_id: AtomicU64,
     pub context_response_tx: Sender<ContextResolveResponse>,
-    /// Owned handle — the fd stays reserved for as long as any clone
-    /// (incl. leaked post-shutdown tasks) is alive, so a stale write
+    /// Owned pipe — both fds stay reserved for as long as any clone
+    /// (incl. leaked post-shutdown tasks) is alive, so a stale wake
     /// can never land in a recycled fd number of a later session.
-    pub context_response_eventfd: Arc<OwnedFd>,
+    pub context_response_wakeup: Arc<Wakeup>,
     pub context_warnings: Mutex<Vec<String>>,
     /// Phase B.4 — parallel bytes-payload slots keyed by req_id.
     /// `request_payloads` holds Rust → JS payloads (e.g. transform
@@ -96,12 +99,12 @@ pub struct BundleSession {
     pub request_rx: Receiver<HookRequest>,
     /// Pending requests waiting on JS reply. Keyed by req_id.
     pub pending: Mutex<std::collections::HashMap<u64, oneshot::Sender<HookResponse>>>,
-    /// eventfd for "request available" wakeup → GLib main loop watches.
-    pub request_eventfd: Arc<OwnedFd>,
+    /// "Request available" wakeup → GLib main loop watches its read fd.
+    pub request_wakeup: Arc<Wakeup>,
     /// Result of the bundle task once complete. None while still running.
     pub result: Mutex<Option<Result<String, String>>>,
-    /// Completion eventfd: written exactly once when `result` is set.
-    pub complete_eventfd: Arc<OwnedFd>,
+    /// Completion wakeup: woken exactly once when `result` is set.
+    pub complete_wakeup: Arc<Wakeup>,
     /// Cancel flag — set by the C side via `cancel()`. tokio task
     /// observes via shared atomic and aborts.
     pub cancelled: Arc<std::sync::atomic::AtomicBool>,
@@ -110,7 +113,7 @@ pub struct BundleSession {
     pub shared: Arc<SessionShared>,
     /// Receiver side of the context-response channel. Drained by
     /// `gjsify_rolldown_session_next_context_response` from the GLib
-    /// main loop after waking on `context_response_eventfd`.
+    /// main loop after waking on `context_response_wakeup`.
     pub context_response_rx: Receiver<ContextResolveResponse>,
 }
 
@@ -168,37 +171,39 @@ pub extern "C" fn gjsify_rolldown_session_start(
         }
     };
 
-    // Create the eventfd pair. EFD_NONBLOCK so writes never block;
-    // EFD_SEMAPHORE off (we use counter-mode so JS can read once
-    // per drain cycle and process all pending requests in a loop).
-    // Each fd is wrapped in Arc<OwnedFd> immediately: every holder
+    // Create the three wakeup pipes (see `crate::wakeup`): non-blocking
+    // + close-on-exec on both ends, one portable implementation on every
+    // platform. Each is wrapped in Arc<Wakeup> immediately: every holder
     // (proxies, the bundle task, SessionShared, the session itself)
-    // keeps a clone, so the fd number stays reserved until the LAST
+    // keeps a clone, so both fd numbers stay reserved until the LAST
     // user — including tasks leaked past the runtime shutdown
     // timeout — has dropped it. Closing eagerly in session_free while
-    // such tasks still hold the raw number let their deferred
-    // `libc::write` land in whatever fd the kernel recycled the
-    // number into (issue #501's stale-fd hazard).
-    let request_eventfd = unsafe { libc::eventfd(0, libc::EFD_NONBLOCK | libc::EFD_CLOEXEC) };
-    if request_eventfd < 0 {
-        unsafe { *err_out = err_to_cstr("rolldown: eventfd(request) failed".to_string()) };
-        return ptr::null_mut();
-    }
-    let request_eventfd = Arc::new(unsafe { OwnedFd::from_raw_fd(request_eventfd) });
-    let complete_eventfd = unsafe { libc::eventfd(0, libc::EFD_NONBLOCK | libc::EFD_CLOEXEC) };
-    if complete_eventfd < 0 {
-        unsafe { *err_out = err_to_cstr("rolldown: eventfd(complete) failed".to_string()) };
-        return ptr::null_mut();
-    }
-    let complete_eventfd = Arc::new(unsafe { OwnedFd::from_raw_fd(complete_eventfd) });
-
-    let context_response_eventfd =
-        unsafe { libc::eventfd(0, libc::EFD_NONBLOCK | libc::EFD_CLOEXEC) };
-    if context_response_eventfd < 0 {
-        unsafe { *err_out = err_to_cstr("rolldown: eventfd(context_response) failed".to_string()) };
-        return ptr::null_mut();
-    }
-    let context_response_eventfd = Arc::new(unsafe { OwnedFd::from_raw_fd(context_response_eventfd) });
+    // such tasks still hold the raw number let their deferred wake land
+    // in whatever fd the kernel recycled the number into (issue #501's
+    // stale-fd hazard).
+    let request_wakeup = match Wakeup::new() {
+        Ok(w) => Arc::new(w),
+        Err(e) => {
+            unsafe { *err_out = err_to_cstr(format!("rolldown: wakeup pipe (request): {e}")) };
+            return ptr::null_mut();
+        }
+    };
+    let complete_wakeup = match Wakeup::new() {
+        Ok(w) => Arc::new(w),
+        Err(e) => {
+            unsafe { *err_out = err_to_cstr(format!("rolldown: wakeup pipe (complete): {e}")) };
+            return ptr::null_mut();
+        }
+    };
+    let context_response_wakeup = match Wakeup::new() {
+        Ok(w) => Arc::new(w),
+        Err(e) => {
+            unsafe {
+                *err_out = err_to_cstr(format!("rolldown: wakeup pipe (context_response): {e}"))
+            };
+            return ptr::null_mut();
+        }
+    };
 
     let cancelled = Arc::new(std::sync::atomic::AtomicBool::new(false));
     let (request_tx, request_rx) = unbounded::<HookRequest>();
@@ -209,7 +214,7 @@ pub extern "C" fn gjsify_rolldown_session_start(
         contexts: Mutex::new(std::collections::HashMap::new()),
         next_child_id: AtomicU64::new(1),
         context_response_tx,
-        context_response_eventfd: context_response_eventfd.clone(),
+        context_response_wakeup: context_response_wakeup.clone(),
         context_warnings: Mutex::new(Vec::new()),
         request_payloads: Mutex::new(std::collections::HashMap::new()),
         response_payloads: Mutex::new(std::collections::HashMap::new()),
@@ -234,7 +239,7 @@ pub extern "C" fn gjsify_rolldown_session_start(
                 hooks: meta.hooks.clone(),
                 request_tx: request_tx.clone(),
                 next_request_id: next_request_id.clone(),
-                request_eventfd: request_eventfd.clone(),
+                request_wakeup: request_wakeup.clone(),
                 response_timeout: Duration::from_secs(60),
                 load_id_filter,
                 transform_id_filter,
@@ -270,7 +275,7 @@ pub extern "C" fn gjsify_rolldown_session_start(
 
     let result_slot: Arc<Mutex<Option<Result<String, String>>>> = Arc::new(Mutex::new(None));
     let result_slot_clone = result_slot.clone();
-    let complete_eventfd_for_task = complete_eventfd.clone();
+    let complete_wakeup_for_task = complete_wakeup.clone();
     let cancelled_for_task = cancelled.clone();
     let shared_for_task = shared.clone();
 
@@ -282,16 +287,16 @@ pub extern "C" fn gjsify_rolldown_session_start(
         };
         *result_slot_clone.lock().unwrap() = Some(final_json);
         // Signal completion to the GLib main loop.
-        wake_eventfd(&complete_eventfd_for_task);
+        complete_wakeup_for_task.wake();
     });
 
     let session = Box::new(BundleSession {
         runtime,
         request_rx,
         pending: Mutex::new(std::collections::HashMap::new()),
-        request_eventfd,
+        request_wakeup,
         result: Mutex::new(None),
-        complete_eventfd,
+        complete_wakeup,
         cancelled,
         shared,
         context_response_rx,
@@ -389,7 +394,7 @@ pub extern "C" fn gjsify_rolldown_session_request_fd(session: *mut BundleSession
     if session.is_null() {
         return -1;
     }
-    unsafe { (*session).request_eventfd.as_raw_fd() }
+    unsafe { (*session).request_wakeup.read_fd() }
 }
 
 #[unsafe(no_mangle)]
@@ -397,7 +402,7 @@ pub extern "C" fn gjsify_rolldown_session_complete_fd(session: *mut BundleSessio
     if session.is_null() {
         return -1;
     }
-    unsafe { (*session).complete_eventfd.as_raw_fd() }
+    unsafe { (*session).complete_wakeup.read_fd() }
 }
 
 /// Drain one pending request. Returns NULL when the channel is
@@ -541,11 +546,11 @@ pub extern "C" fn gjsify_rolldown_session_free(session: *mut BundleSession) {
     unregister_result_slot(session);
     let boxed = unsafe { Box::from_raw(session) };
     // Shut the runtime down FIRST (up to 500ms drain; workers that
-    // don't finish in time are leaked), THEN let the eventfds drop.
-    // The fds are Arc<OwnedFd>, so even a task leaked past the
-    // shutdown timeout keeps its clone alive — the fd number stays
-    // reserved and a deferred stale write can never corrupt whatever
-    // fd the kernel would otherwise have recycled the number into.
+    // don't finish in time are leaked), THEN let the wakeup pipes drop.
+    // They are Arc<Wakeup>, so even a task leaked past the shutdown
+    // timeout keeps its clone alive — the fd numbers stay reserved and
+    // a deferred stale wake can never corrupt whatever fd the kernel
+    // would otherwise have recycled the number into.
     boxed.runtime.shutdown_timeout(Duration::from_millis(500));
 }
 
@@ -609,7 +614,7 @@ pub extern "C" fn gjsify_rolldown_session_context_resolve(
                 error: Some(format!("rolldown: malformed context_resolve args JSON: {e}")),
             };
             let _ = session.shared.context_response_tx.send(resp);
-            wake_eventfd(&session.shared.context_response_eventfd);
+            session.shared.context_response_wakeup.wake();
             return child_id;
         }
     };
@@ -654,7 +659,7 @@ pub extern "C" fn gjsify_rolldown_session_context_resolve(
             },
         };
         let _ = shared.context_response_tx.send(resp);
-        wake_eventfd(&shared.context_response_eventfd);
+        shared.context_response_wakeup.wake();
     });
 
     child_id
@@ -680,8 +685,8 @@ pub extern "C" fn gjsify_rolldown_session_context_warn(
     session.shared.context_warnings.lock().unwrap().push(msg);
 }
 
-/// FFI: get the eventfd that signals "a context-resolve sub-result is
-/// available". GLib main loop watches this with `G_IO_IN`.
+/// FFI: get the wakeup-pipe read fd that signals "a context-resolve
+/// sub-result is available". GLib main loop watches this with `G_IO_IN`.
 #[unsafe(no_mangle)]
 pub extern "C" fn gjsify_rolldown_session_context_response_fd(
     session: *mut BundleSession,
@@ -690,7 +695,7 @@ pub extern "C" fn gjsify_rolldown_session_context_response_fd(
         return -1;
     }
     let session = unsafe { &*session };
-    session.shared.context_response_eventfd.as_raw_fd()
+    session.shared.context_response_wakeup.read_fd()
 }
 
 /// FFI: drain one pending context-resolve response. Returns NULL when
@@ -720,13 +725,6 @@ pub extern "C" fn gjsify_rolldown_session_next_context_response(
     CString::new(json).ok().map(|c| c.into_raw()).unwrap_or(ptr::null_mut())
 }
 
-pub(crate) fn wake_eventfd(fd: &OwnedFd) {
-    let one: u64 = 1;
-    unsafe {
-        libc::write(fd.as_raw_fd(), &one as *const u64 as *const libc::c_void, 8);
-    }
-}
-
 // ---------------------------------------------------------------------
 // Phase B.4 — bytes-payload side-channel for the transform hook.
 // ---------------------------------------------------------------------

package/src/rust/src/wakeup.rs

@@ -0,0 +1,180 @@
+//! Wakeup — the portable "something is queued for you" channel between
+//! the tokio worker threads and the GLib main loop.
+//!
+//! ONE implementation for every platform: an anonymous pipe. The
+//! previous implementation used `eventfd(2)`, which is Linux-only (the
+//! `libc` crate does not even expose it on Apple targets), so the crate
+//! could not be compiled for macOS at all. A pipe is POSIX, is what the
+//! Vala side already treats the descriptor as (`GLib.IOChannel.unix_new`
+//! + `add_watch`, which only ever needs *a pollable fd*), and therefore
+//! removes the platform split instead of doubling it — a second,
+//! platform-gated wakeup path would only ever be exercised on the
+//! platform nobody develops on.
+//!
+//! ## eventfd counter vs pipe byte stream
+//!
+//! An eventfd is a 64-bit counter: N writes coalesce into one readable
+//! event and a single 8-byte read resets it. A pipe is a byte stream
+//! with a finite buffer (64 KiB on Linux, 16 KiB on macOS). Swapping one
+//! for the other naively introduces two bugs; both are handled
+//! explicitly here and in `rolldown.vala`:
+//!
+//! 1. **Lost wakeup / blocked writer when the buffer is full.** Both
+//!    ends are `O_NONBLOCK`, so a full buffer surfaces as `EAGAIN`
+//!    (`ErrorKind::WouldBlock`) instead of parking a tokio worker
+//!    thread forever. `EAGAIN` is *safe to drop*: a full buffer means
+//!    the reader has not consumed the bytes already in it, so a wakeup
+//!    is already pending. The reader always drains the pipe *before* it
+//!    drains the request queue, and the queue push happens before the
+//!    write attempt, so the item is guaranteed to be observed by the
+//!    drain cycle that consumes those pending bytes. In other words the
+//!    pipe recovers eventfd's coalescing property from its buffer
+//!    instead of from a counter.
+//!
+//! 2. **A partial read leaves the fd readable.** The reader must
+//!    consume *everything* available, not one fixed-size chunk. GLib's
+//!    watch is level-triggered, so leftover bytes re-dispatch the
+//!    callback — which re-drains the queue for nothing — once per chunk
+//!    until the pipe empties: a burst of N wakes costs N/chunk no-op
+//!    main-loop iterations instead of one. `rolldown.vala` reads to
+//!    `G_IO_STATUS_AGAIN` so a burst collapses back into a single
+//!    wake-up cycle, recovering the coalescing the counter gave for
+//!    free.
+//!
+//! ## Ownership
+//!
+//! Both ends live in the same struct, which the session hands out as
+//! `Arc<Wakeup>` to every holder (the proxies, the bundle task,
+//! `SessionShared`, the session itself). Consequences:
+//!
+//! * The fd numbers stay reserved until the LAST holder — including a
+//!   task leaked past the runtime shutdown timeout — drops its clone,
+//!   so a deferred stale wake can never land in an fd number the kernel
+//!   recycled into something else (issue #501's hazard, previously
+//!   documented on the `Arc<OwnedFd>` eventfds).
+//! * The read end cannot outlive the write end or vice versa, so
+//!   `wake()` can never hit `EPIPE`/`SIGPIPE` — that would require the
+//!   read end to be closed while a writer still holds a reference,
+//!   which the shared ownership makes unrepresentable. (The Vala watch
+//!   borrows the read fd with `set_close_on_unref(false)`, so it never
+//!   closes it either.)
+//!
+//! Both ends are close-on-exec: `std::io::pipe()` sets `FD_CLOEXEC`
+//! atomically where the platform supports it (`pipe2`), matching the
+//! `EFD_CLOEXEC` the eventfds were created with. A wakeup fd leaking
+//! into a subprocess spawned by a plugin hook would be a real fd leak.
+
+use std::io::{ErrorKind, PipeReader, PipeWriter, Write};
+use std::os::fd::{AsRawFd, RawFd};
+
+/// A one-way "wake the main loop" channel.
+#[derive(Debug)]
+pub struct Wakeup {
+    reader: PipeReader,
+    writer: PipeWriter,
+}
+
+impl Wakeup {
+    /// Create a non-blocking, close-on-exec wakeup pipe.
+    pub fn new() -> std::io::Result<Self> {
+        let (reader, writer) = std::io::pipe()?;
+        // Non-blocking on BOTH ends: the writer must never park a tokio
+        // worker on a full buffer, and the reader must be able to drain
+        // to EAGAIN from the GLib main loop without blocking it.
+        set_nonblocking(reader.as_raw_fd())?;
+        set_nonblocking(writer.as_raw_fd())?;
+        Ok(Self { reader, writer })
+    }
+
+    /// Raw read fd for the GLib watch. Borrowed — the `Wakeup` keeps
+    /// ownership, so the watch must not close it.
+    pub fn read_fd(&self) -> RawFd {
+        self.reader.as_raw_fd()
+    }
+
+    /// Signal the main loop. Call AFTER pushing onto the queue the
+    /// reader will drain.
+    ///
+    /// Never blocks and never fails the build: a full buffer
+    /// (`WouldBlock`) means a wakeup is already pending and unread, so
+    /// dropping this one loses nothing (see the module docs).
+    ///
+    /// Safe to call concurrently from every tokio worker: a write of
+    /// `≤ PIPE_BUF` bytes is atomic per POSIX, so 1-byte wakes from
+    /// different threads never interleave or tear.
+    pub fn wake(&self) {
+        loop {
+            match (&self.writer).write(&[1u8]) {
+                // A ≤PIPE_BUF write is atomic: either the byte is in or
+                // we got EAGAIN, never a short write.
+                Ok(_) => return,
+                Err(e) if e.kind() == ErrorKind::Interrupted => continue,
+                // Buffer full — the reader still owes us a drain cycle,
+                // and that cycle re-checks the queue. Coalesced.
+                Err(e) if e.kind() == ErrorKind::WouldBlock => return,
+                // Nothing actionable during teardown; the build result
+                // is delivered through the queue + result slot, not here.
+                Err(_) => return,
+            }
+        }
+    }
+}
+
+fn set_nonblocking(fd: RawFd) -> std::io::Result<()> {
+    // SAFETY: `fd` is owned by the `PipeReader`/`PipeWriter` the caller
+    // holds for the duration of the call, so it is a valid open fd.
+    let flags = unsafe { libc::fcntl(fd, libc::F_GETFL) };
+    if flags < 0 {
+        return Err(std::io::Error::last_os_error());
+    }
+    if unsafe { libc::fcntl(fd, libc::F_SETFL, flags | libc::O_NONBLOCK) } < 0 {
+        return Err(std::io::Error::last_os_error());
+    }
+    Ok(())
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::io::Read;
+
+    #[test]
+    fn cloexec_and_nonblocking_on_both_ends() {
+        let w = Wakeup::new().expect("wakeup");
+        for fd in [w.reader.as_raw_fd(), w.writer.as_raw_fd()] {
+            let fdflags = unsafe { libc::fcntl(fd, libc::F_GETFD) };
+            assert!(fdflags >= 0);
+            assert_ne!(fdflags & libc::FD_CLOEXEC, 0, "fd must be close-on-exec");
+            let flflags = unsafe { libc::fcntl(fd, libc::F_GETFL) };
+            assert!(flflags >= 0);
+            assert_ne!(flflags & libc::O_NONBLOCK, 0, "fd must be non-blocking");
+        }
+    }
+
+    #[test]
+    fn wake_never_blocks_when_the_buffer_is_full() {
+        let w = Wakeup::new().expect("wakeup");
+        // Far more wakes than any pipe buffer can hold. If `wake()`
+        // blocked or panicked on EAGAIN this would hang / fail.
+        for _ in 0..200_000 {
+            w.wake();
+        }
+        // A full drain (what the Vala watch does) makes the pipe
+        // writable again — i.e. the wakeup channel is self-healing.
+        let mut buf = [0u8; 4096];
+        loop {
+            match (&w.reader).read(&mut buf) {
+                Ok(0) => break,
+                Ok(_) => continue,
+                Err(e) if e.kind() == ErrorKind::WouldBlock => break,
+                Err(e) => panic!("unexpected drain error: {e}"),
+            }
+        }
+        let mut probe = [0u8; 1];
+        assert!(
+            (&w.writer).write(&probe[..]).is_ok(),
+            "a drained wakeup pipe must accept writes again"
+        );
+        assert_eq!((&w.reader).read(&mut probe).expect("read back"), 1);
+    }
+}

package/src/vala/rolldown.vala

@@ -149,6 +149,14 @@ namespace GjsifyRolldown {
         private uint _complete_source_id = 0;
         private uint _ctx_response_source_id = 0;
 
+        /**
+         * Scratch buffer for draining the wakeup pipes. Their content is
+         * meaningless — only the readability edge matters — so one buffer
+         * is shared by all three watch callbacks; they all dispatch on the
+         * same main-loop thread and never run concurrently.
+         */
+        private char[] _drain_buf = new char[4096];
+
         /**
          * Emitted whenever rolldown invokes a plugin hook.
          *
@@ -210,9 +218,10 @@ namespace GjsifyRolldown {
             int req_fd = _session_request_fd (_handle);
             int comp_fd = _session_complete_fd (_handle);
 
-            // Watch the eventfds on the GLib main loop. add_full hands
-            // the source priority + condition; we own the fd lifetime
-            // via Rust, so don't pass close_fd:true.
+            // Watch the wakeup-pipe read ends on the GLib main loop.
+            // add_full hands the source priority + condition; we own the
+            // fd lifetime via Rust (both pipe ends live in the session's
+            // Arc<Wakeup>), so don't pass close_fd:true.
             //
             // IMPORTANT: each watch source holds a strong GObject ref on
             // the session (the explicit `this.ref ()` below, released 1:1
@@ -223,8 +232,8 @@ namespace GjsifyRolldown {
             // its own signal-handler closures — a self cycle) gets
             // collected by the SpiderMonkey GC: dispose() removes the
             // watch sources while the Rust build is still running, every
-            // later eventfd wake lands on an unwatched fd, and the build
-            // stalls forever (issue #501). The extra refs also flip GJS's
+            // later wake lands on an unwatched fd, and the build stalls
+            // forever (issue #501). The extra refs also flip GJS's
             // toggle-ref into "keep the JS wrapper rooted" mode, so the
             // signal closures survive until the sources are dropped.
             var req_chan = new GLib.IOChannel.unix_new (req_fd);
@@ -253,9 +262,9 @@ namespace GjsifyRolldown {
         /**
          * close — release the session's resources.
          *
-         * Removes the three GLib eventfd watch sources and drops the owned
+         * Removes the three GLib wakeup-pipe watch sources and drops the owned
          * Rust handle (whose `free_function`, gjsify_rolldown_session_free,
-         * tears down the bundler + tokio runtime + eventfds). Without this,
+         * tears down the bundler + tokio runtime + wakeup pipes). Without this,
          * every bundle leaked its session for the process lifetime — the
          * watch sources hold a ref on the session, so neither the GObject
          * nor the Rust side could ever be collected. Idempotent; safe to
@@ -268,14 +277,44 @@ namespace GjsifyRolldown {
             _handle = null;
         }
 
-        private bool on_ctx_response_ready (GLib.IOChannel source, GLib.IOCondition cond) {
-            char[] sink = new char[8];
+        /**
+         * Consume EVERY byte currently queued on a wakeup pipe.
+         *
+         * The wakeup fds are pipes on every platform (see
+         * src/rust/src/wakeup.rs) — a byte stream, not an eventfd counter
+         * that one 8-byte read resets. Reading a single fixed-size chunk
+         * would leave the rest queued, and GLib's watch is
+         * level-triggered: the callback is re-dispatched (re-draining the
+         * queue for nothing) once per chunk until the pipe finally
+         * empties, so a burst of N hook wakeups costs N/chunk no-op main
+         * loop iterations instead of one. Draining to `AGAIN` collapses a
+         * burst back into a single wake-up cycle — the coalescing the
+         * eventfd counter used to give us for free.
+         *
+         * The order also matters: drain the pipe FIRST, then the queue.
+         * The Rust writer drops a wake when the buffer is full, which is
+         * only safe because every drain here is followed by a full queue
+         * drain (see src/rust/src/wakeup.rs). Every caller below keeps
+         * that order.
+         *
+         * Both ends are O_NONBLOCK, so the final read returns
+         * `IOStatus.AGAIN` instead of blocking the main loop.
+         */
+        private void drain_wakeup (GLib.IOChannel source) {
             try {
-                size_t got;
-                source.read_chars (sink, out got);
+                size_t got = 0;
+                while (source.read_chars (_drain_buf, out got) == GLib.IOStatus.NORMAL && got > 0) {
+                    // Keep reading until AGAIN/EOF; the bytes themselves
+                    // carry no information.
+                }
             } catch (Error e) {
-                // ignore — eventfd had nothing left
+                // Transient/EAGAIN-equivalent — the queue drain below is
+                // what actually matters.
             }
+        }
+
+        private bool on_ctx_response_ready (GLib.IOChannel source, GLib.IOCondition cond) {
+            drain_wakeup (source);
 
             while (_handle != null) {
                 var resp_bytes = _glue_session_next_context_response (_handle);
@@ -300,18 +339,9 @@ namespace GjsifyRolldown {
         }
 
         private bool on_request_ready (GLib.IOChannel source, GLib.IOCondition cond) {
-            // Drain the eventfd counter (best-effort; ignore errors).
-            // Drain via posix read() — IOChannel.read_chars wants
-            // `char[]` and Vala can't auto-convert from `uint8[]`.
-            // The eventfd content is an opaque 8-byte counter; we
-            // discard it (just need the wake-up).
-            char[] sink = new char[8];
-            try {
-                size_t got;
-                source.read_chars (sink, out got);
-            } catch (Error e) {
-                // EAGAIN-equivalent — eventfd had nothing left, fine.
-            }
+            // Drain the wakeup pipe FIRST, then the queue — see
+            // drain_wakeup() for why that order is load-bearing.
+            drain_wakeup (source);
 
             // Pull all queued requests in this wake-up cycle.
             while (_handle != null) {
@@ -373,13 +403,7 @@ namespace GjsifyRolldown {
         }
 
         private bool on_complete_ready (GLib.IOChannel source, GLib.IOCondition cond) {
-            char[] sink = new char[8];
-            try {
-                size_t got;
-                source.read_chars (sink, out got);
-            } catch (Error e) {
-                // ignore
-            }
+            drain_wakeup (source);
 
             if (_handle == null) return false;
             try {