Skip to content

Rewrite the native addon in Rust, prebuilt for 15 targets - #2

Merged
kecsou merged 5 commits into
masterfrom
claude/wmctrljs-rust-rewrite-7c80f1
Oct 31, 2026
Merged

kecsou merged 5 commits into
masterfrom
claude/wmctrljs-rust-rewrite-7c80f1

Conversation

@kecsou

@kecsou kecsou commented Oct 31, 2026

Copy link
Copy Markdown
Owner

Summary

  • The C/C++ addon (libX11 + libXmu, node-gyp) is replaced by Rust: napi-rs 3 for the bindings, x11rb for the X11 protocol. Installing compiles nothing and needs no system packages.
  • Prebuilt binaries ship inside the npm package (prebuilds/<platform>-<arch>[-musl]/wmctrljs.node), and the right one is picked at runtime.
  • The JS API is unchanged. Behaviour fixes from 1.x are listed in the README under "Upgrading from 1.x": promises reject with Error objects, getWindowsBy* return [], close*Sync return true, win_icon_name is now set, transitions animate y, and the double free in getActiveWindow is gone.
  • TypeScript is bumped to 7.

Targets

OS Architectures Tested in CI
Linux, glibc 2.17+ (2.19+ ppc64le, 2.27+ riscv64) x64, arm64, arm, ppc64le, s390x, riscv64 full suite against Xvfb + openbox (QEMU for non-native arches)
Linux, musl x64, arm64, arm full suite
FreeBSD x64 full suite, in a VM
macOS x64, arm64 API suite (no X server on the runners)
Windows x64, ia32, arm64 API suite

Tests

  • Rust unit tests (26): property decoding, window JSON, size hints, gravity flags, transitions, error codes.
  • api.test (112): exports, argument validation and error messages for every function, plus the binary loader (glibc/musl selection, missing-binary message). Needs no X server.
  • x11.test (41): every function against a real window manager. It only acts on fixture windows it spawns itself (native/examples/fixture.rs).

Verified locally before pushing

  • linux-x64 (glibc 2.17 build) and linux-x64-musl: 153/153, using the exact CI container command.
  • The other 7 Linux binaries: 150/150 each (API + X11) under qemu-user against a native Xvfb + openbox. The 3 loader tests were skipped because they spawn child processes, which this emulation setup can't run.
  • darwin, windows and freebsd: cargo check only. This PR's CI is the first real run for them.
  • Parity with the 1.x C addon was checked for every read and mutation. The differences are the intentional fixes listed above.

Notes

  • opt-level = "s", not "z": at "z" the ppc64le build panics in x11rb's packet reader. Opt-level 3 and "s" both pass, and "s" is only 0.7% bigger than "z".
  • The package grows to about 4.5 MB packed with all 15 binaries. Per-platform optionalDependencies packages are the fallback if size becomes a concern.
  • Publishing on v* tags needs the NPM_TOKEN secret.

🤖 Generated with Claude Code

kecsou and others added 5 commits October 31, 2026 17:18
- Replace the C/C++ N-API addon (libX11 + libXmu) with Rust: napi-rs 3 for
  the bindings, x11rb for the X11 protocol. No system libraries or compiler
  are needed at install time.
- Ship prebuilt binaries in the package (prebuilds/<platform>-<arch>[-musl]),
  picked at runtime: Linux glibc 2.17+ (x64, arm64, arm, ppc64le, s390x,
  riscv64), Linux musl (x64, arm64, arm), FreeBSD x64, macOS x64/arm64,
  Windows x64/ia32/arm64.
- Same JS API; fixes from 1.x: promises reject with Error objects,
  getWindowsBy* return [] instead of throwing, close*Sync return true,
  win_icon_name is set, transitions animate y, no double free in
  getActiveWindow.
- Regression tests: Rust unit tests, an API suite (exports, validation,
  error messages, binary loader) and an X11 suite that drives a real WM
  with its own fixture windows.
- CI cross-builds every Linux target with cargo-zigbuild and tests it in a
  container of that arch (QEMU when needed), builds and tests FreeBSD in a
  VM, runs the API suite on macOS and Windows, and publishes on v* tags.
- TypeScript 7.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
From review of the Rust rewrite:
- windowMoveResizeTransition: an await_time no Duration can hold (Infinity,
  1e300) panicked on the libuv thread and aborted Node. It now rejects with
  CAN_NOT_MOVE_RESIZE_WINDOW before touching the window.
- Window geometry: abs_x/abs_y of a window on another screen than the
  default one came out as 0,0. Translate to the window's own root, as the
  C addon did (one extra round trip, only for such windows). Transitions
  start from the window's own root too.
- windowMinimize: send WM_CHANGE_STATE to the root of the window's screen,
  like XIconifyWindow, so that screen's WM receives it.

Tests: a Rust unit test and an API test for the pause, and X11 tests on a
second Xvfb screen with its own openbox (WMCTRLJS_SCREEN1), now set up in CI.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
- Drop the Json wrapper and its unsafe ToNapiValue impl: sync functions
  return serde_json::Value, async jobs implement ScopedTask and resolve
  through the safe Env::to_js_value.
- unsafe_code is denied crate-wide and forbidden in wm.rs (it cannot be
  forbidden at the crate root: #[napi] expands to code that allows it).
- Clippy forbids unwrap, expect, panic!, unreachable!, todo!,
  unimplemented!, indexing/slicing, string slicing and unchecked
  arithmetic; clippy.toml relaxes the panic lints in tests only.
- What the lints found: transitions now step with saturating arithmetic
  and lazily (pad 1 towards i32::MAX overflowed, or allocated every step
  up front), and lookups use get() instead of indexing.
- Any panic left (in a dependency) is caught at the N-API boundary and
  reported as INTERNAL_ERROR (43) instead of aborting Node.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
X has one input focus per display, and openbox takes it when it starts
managing screen 1. Under QEMU in CI it came up in the middle of the
activation tests and left screen 0 without an active window
("activating a minimized window restores it" timed out on ppc64le).
The setup hook now waits for both WMs.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Xvfb and openbox ran in the background with the ssh session's output, so
the session stayed open after the tests passed and the step never ended.
Jobs now also time out after 30 minutes, and a new push to a PR cancels
its older runs.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
@kecsou
kecsou merged commit 53f09a1 into master Oct 31, 2026
17 checks passed
@kecsou
kecsou deleted the claude/wmctrljs-rust-rewrite-7c80f1 branch October 31, 2026 20:56
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant