ventiws 1.0.0-alpha → 1.0.0-alpha.10

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Farben
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 Farben
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,138 +1,160 @@
-<p align="center">
-  <img src="misc/ventiws_banner.png" alt="ventiws banner" />
-</p>
-
-# ventiws
-
-A WebSocket implementation for Node.js with the API of
-[`ws`](https://github.com/websockets/ws), delivered as a native addon whose framing
-engine is written in Zig. It targets `ws` 8.21.3 and reproduces that release's
-observable behaviour rather than its source. ventiws is not affiliated with the
-`ws` project and vendors none of its code; the upstream API reference is vendored
-as the pinned contract, credited in
-[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
-
-**ventiws is at `1.0.0-alpha`.** Nothing is published to npm yet, so an
-install builds the addon for one platform, and the surface may change between
-alpha releases. What "alpha" means here is bounded: the `ws` compatibility
-contract is tracked row by row in
-[COMPATIBILITY.md](COMPATIBILITY.md), and the four places ventiws knowingly
-differs from `ws` are listed in [CHANGELOG.md](CHANGELOG.md) under "Known
-divergences from `ws`".
-
-## Install
-
-Working in the tree:
-
-```sh
-git clone git@github.com:farbenbuilds/ventiws.git
-cd ventiws
-nix develop
-pnpm install
-pnpm build
-```
-
-Published usage, once a release lands:
-
-```sh
-pnpm add ventiws
-```
-
-`nix develop` pins Node.js, pnpm, and Zig 0.16.0. The first `pnpm build` compiles
-the vendored C dependencies, which takes minutes and about a gigabyte; later
-builds are incremental.
-
-## Usage
-
-```ts
-import { WebSocket, WebSocketServer } from "ventiws";
-
-const server = new WebSocketServer({ port: 8080 });
-
-server.on("listening", () => {
-  console.log("listening on", server.address()?.port);
-});
-
-server.on("connection", (socket) => {
-  socket.on("message", (data, isBinary) => {
-    socket.send(isBinary ? data : `echo: ${data.toString()}`);
-  });
-  socket.on("close", (code, reason) => {
-    console.log("closed", code, reason.toString());
-  });
-});
-
-const client = new WebSocket("ws://127.0.0.1:8080/");
-client.on("open", () => client.send("hello"));
-client.on("message", (data) => console.log("client saw", data.toString()));
-client.on("error", (error) => console.error(error));
-```
-
-Both halves run against a real `ws` peer in this repository's suites, and the
-constructors are plain functions returning state records: no `class`, no `this`,
-no prototype.
-
-## Status
-
-Option defaults match `ws`: `maxPayload` 100 MiB, `maxFragments` 16384, and
-`closeTimeout` 30000 ms. The itemised matrix, with the owner module and the
-evidence test behind every row, is [COMPATIBILITY.md](COMPATIBILITY.md).
-
-| Area                                                                                | State                                                                                                                             |
-| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
-| `WebSocketServer`: options, events, `handleUpgrade`, `shouldHandle`, `verifyClient` | Works, compared property for property against `ws`                                                                                |
-| Server-side `WebSocket`: properties, `on*` and DOM handlers, ready states           | Works, with exactly-once `close`                                                                                                  |
-| `WebSocket` client: `net` and `tls`, redirects, `ws+unix:`, `unexpected-response`   | Works against a real `ws` server                                                                                                  |
-| `send`, fragmentation, `binaryType`, `ping`/`pong`, close codes                     | Works both directions; `maxPayload` and `maxFragments` are enforced per connection                                                |
-| `permessage-deflate`                                                                | Works; context takeover is declined in both directions ([why](COMPATIBILITY.md#shared-with-the-engine))                           |
-| `createWebSocketStream`, `clientTracking`, `server.options`                         | Works, including the `WebSocket` class option                                                                                     |
-| Engine route message cap, 64 KiB                                                    | A property of the build. [Two limits](#two-limits-worth-knowing)                                                                  |
-| Engine route inbound ring, 64 messages                                              | Excess is dropped and counted. Same section                                                                                       |
-| RFC 6455 Autobahn suite                                                             | Regression gate; 424 of 517 cases in the full run, 268 in the framing selection ([matrix](COMPATIBILITY.md#rfc-6455-conformance)) |
-| Client `wss:` to `ws:` downgrade, redirect hop limit, `origin`, `handshakeTimeout`  | Implemented with no behavioural test ([outstanding](COMPATIBILITY.md#what-is-still-outstanding))                                  |
-
-## Two limits worth knowing
-
-**The 64 KiB message cap.** `message_capacity` in
-`src/engine/server/capacities.zig` is a `comptime` constant, so it is baked into
-the addon: `maxPayload` sizes each connection's own ceiling and does not lift this
-one. 64 KiB is the largest payload the conformance suite puts on the wire, and a
-frame above it is closed with 1009. Raising it costs about 22 MB per live server,
-because the message slab, the write queue, and both staging rings scale with it.
-
-**The 64-slot inbound ring.** The engine has no hook for stopping a read when its
-consumer falls behind, so the ring in `src/engine/server/instance.zig` is the
-only place a burst can be absorbed. It holds 64 messages, and a peer delivering
-more before the Node main thread drains has the excess dropped and counted by
-`serverDroppedMessages`. `ws` applies backpressure instead, so it has no cliff.
-
-Both bind the engine route, which is µWebZockets' own listener. The codec route
-the public `ws` surface uses is bound by neither: its buffers grow into each
-connection's own `maxPayload` and `maxFragments`. `engineLimits()` is exported
-from the package entry, so the compiled numbers are readable at runtime.
-
-## Commands
-
-```sh
-pnpm build
-pnpm test
-pnpm test:compat
-pnpm test:autobahn
-pnpm bench
-pnpm typecheck
-pnpm lint
-pnpm format:check
-```
-
-## Docs and licence
-
-- [COMPATIBILITY.md](COMPATIBILITY.md): every `ws` surface item, its owner module, its status, and its evidence test.
-- [CODEBASE.md](CODEBASE.md): repository layout, the two routes, the boundary, and the compiled capacities.
-- [CODING_CONVENTION.md](CODING_CONVENTION.md): TypeScript and Zig style, the anti-OOP rules, and the module budget.
-- [docs/migrating.md](docs/migrating.md): moving an existing `ws` application over.
-- [CONTRIBUTE.md](CONTRIBUTE.md): environment setup, the script contract, and how to release.
-
-MIT. See [LICENSE](LICENSE). `ws` is copyright Einar Otto Stangvik, Arnout
-Kazemier, and contributors, MIT-licensed. µWebZockets is the first-party
-MIT-licensed protocol engine written for this project. Provenance for everything
-vendored or CI-only is in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+<p align="center">
+  <img src="misc/ventiws_banner.png" alt="ventiws banner" />
+</p>
+
+# ventiws
+
+A WebSocket implementation for Node.js with the API of
+[`ws`](https://github.com/websockets/ws), delivered as a native addon whose framing
+engine is written in Zig. It targets `ws` 8.21.3 and reproduces that release's
+observable behaviour rather than its source. ventiws is not affiliated with the
+`ws` project and vendors none of its code; the upstream API reference is vendored
+as the pinned contract, credited in
+[THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).
+
+**ventiws is at `1.0.0-alpha.10`.** The surface may change between alpha
+releases. What "alpha" means here is bounded: the `ws` compatibility
+contract is tracked row by row in
+[COMPATIBILITY.md](COMPATIBILITY.md), and the four places ventiws knowingly
+differs from `ws` are listed in [CHANGELOG.md](CHANGELOG.md) under "Known
+divergences from `ws`".
+
+## Install
+
+```sh
+pnpm add ventiws
+```
+
+The addon arrives as a per-platform package that npm installs only on a host
+it matches, so the install needs no compiler:
+
+| Platform                    | Package                            |
+| --------------------------- | ---------------------------------- |
+| Linux x64, glibc            | `@ventiws/binding-linux-x64-gnu`   |
+| Linux x64, musl (Alpine)    | `@ventiws/binding-linux-x64-musl`  |
+| Linux arm64, glibc          | `@ventiws/binding-linux-arm64-gnu` |
+| macOS x64                   | `@ventiws/binding-darwin-x64`      |
+| macOS arm64 (Apple silicon) | `@ventiws/binding-darwin-arm64`    |
+
+Any other host installs ventiws with no addon behind it, and the first
+`WebSocketServer` says so by name and lists the platforms above.
+
+**Windows is not supported yet, at either layer.** There is no published addon,
+because the pinned `napi-zig` asks the build for an ABI-less
+`x86_64-windows-none` that has no `ws2_32` to link. More fundamentally, the
+engine cannot serve a socket there: its listener binds and the kernel accepts,
+then the event loop fails `accept` and `read` with `error.Unexpected`, and the
+peer is reset. Building in a checkout does not change that, so a Windows
+checkout is a place to edit the code, not to run a server. The frame codec
+itself is platform-independent and its suites do pass there.
+
+Working in the tree:
+
+```sh
+git clone git@github.com:farbenbuilds/ventiws.git
+cd ventiws
+direnv allow
+pnpm install
+pnpm build
+```
+
+`direnv allow` runs `.envrc`, which enters the pinned Nix shell with Node.js,
+pnpm, and Zig 0.16.0, and re-enters it on every later `cd`. Without
+[direnv](https://direnv.net) installed, run `nix develop` once per shell
+instead. The first `pnpm build` compiles the vendored C dependencies, which
+takes minutes and about a gigabyte; later builds are incremental.
+
+## Usage
+
+```ts
+import { WebSocket, WebSocketServer } from "ventiws";
+
+const server = new WebSocketServer({ port: 8080 });
+
+server.on("listening", () => {
+  console.log("listening on", server.address()?.port);
+});
+
+server.on("connection", (socket) => {
+  socket.on("message", (data, isBinary) => {
+    socket.send(isBinary ? data : `echo: ${data.toString()}`);
+  });
+  socket.on("close", (code, reason) => {
+    console.log("closed", code, reason.toString());
+  });
+});
+
+const client = new WebSocket("ws://127.0.0.1:8080/");
+client.on("open", () => client.send("hello"));
+client.on("message", (data) => console.log("client saw", data.toString()));
+client.on("error", (error) => console.error(error));
+```
+
+Both halves run against a real `ws` peer in this repository's suites, and the
+constructors are plain functions returning state records: no `class`, no `this`,
+no prototype.
+
+## Status
+
+Option defaults match `ws`: `maxPayload` 100 MiB, `maxFragments` 16384, and
+`closeTimeout` 30000 ms. The itemised matrix, with the owner module and the
+evidence test behind every row, is [COMPATIBILITY.md](COMPATIBILITY.md).
+
+| Area                                                                                | State                                                                                                                             |
+| ----------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `WebSocketServer`: options, events, `handleUpgrade`, `shouldHandle`, `verifyClient` | Works, compared property for property against `ws`                                                                                |
+| Server-side `WebSocket`: properties, `on*` and DOM handlers, ready states           | Works, with exactly-once `close`                                                                                                  |
+| `WebSocket` client: `net` and `tls`, redirects, `ws+unix:`, `unexpected-response`   | Works against a real `ws` server                                                                                                  |
+| `send`, fragmentation, `binaryType`, `ping`/`pong`, close codes                     | Works both directions; `maxPayload` and `maxFragments` are enforced per connection                                                |
+| `permessage-deflate`                                                                | Works; context takeover is declined in both directions ([why](COMPATIBILITY.md#shared-with-the-engine))                           |
+| `createWebSocketStream`, `clientTracking`, `server.options`                         | Works, including the `WebSocket` class option                                                                                     |
+| Engine route message cap, 64 KiB                                                    | A property of the build. [Two limits](#two-limits-worth-knowing)                                                                  |
+| Engine route inbound ring, 64 messages                                              | Excess is dropped and counted. Same section                                                                                       |
+| RFC 6455 Autobahn suite                                                             | Regression gate; 424 of 517 cases in the full run, 268 in the framing selection ([matrix](COMPATIBILITY.md#rfc-6455-conformance)) |
+| Client `wss:` to `ws:` downgrade, redirect hop limit, `origin`, `handshakeTimeout`  | Implemented with no behavioural test ([outstanding](COMPATIBILITY.md#what-is-still-outstanding))                                  |
+
+## Two limits worth knowing
+
+**The 64 KiB message cap.** `message_capacity` in
+`src/engine/server/capacities.zig` is a `comptime` constant, so it is baked into
+the addon: `maxPayload` sizes each connection's own ceiling and does not lift this
+one. 64 KiB is the largest payload the conformance suite puts on the wire, and a
+frame above it is closed with 1009. Raising it costs about 22 MB per live server,
+because the message slab, the write queue, and both staging rings scale with it.
+
+**The 64-slot inbound ring.** The engine has no hook for stopping a read when its
+consumer falls behind, so the ring in `src/engine/server/instance.zig` is the
+only place a burst can be absorbed. It holds 64 messages, and a peer delivering
+more before the Node main thread drains has the excess dropped and counted by
+`serverDroppedMessages`. `ws` applies backpressure instead, so it has no cliff.
+
+Both bind the engine route, which is µWebZockets' own listener. The codec route
+the public `ws` surface uses is bound by neither: its buffers grow into each
+connection's own `maxPayload` and `maxFragments`. `engineLimits()` is exported
+from the package entry, so the compiled numbers are readable at runtime.
+
+## Commands
+
+```sh
+pnpm build
+pnpm test
+pnpm test:compat
+pnpm test:autobahn
+pnpm bench
+pnpm typecheck
+pnpm lint
+pnpm format:check
+```
+
+## Docs and licence
+
+- [COMPATIBILITY.md](COMPATIBILITY.md): every `ws` surface item, its owner module, its status, and its evidence test.
+- [CODEBASE.md](CODEBASE.md): repository layout, the two routes, the boundary, and the compiled capacities.
+- [CODING_CONVENTION.md](CODING_CONVENTION.md): TypeScript and Zig style, the anti-OOP rules, and the module budget.
+- [docs/migrating.md](docs/migrating.md): moving an existing `ws` application over.
+- [CONTRIBUTE.md](CONTRIBUTE.md): environment setup, the script contract, and how to release.
+
+MIT. See [LICENSE](LICENSE). `ws` is copyright Einar Otto Stangvik, Arnout
+Kazemier, and contributors, MIT-licensed. µWebZockets is the first-party
+MIT-licensed protocol engine written for this project. Provenance for everything
+vendored or CI-only is in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/dist/index.cjs

@@ -8,6 +8,7 @@ let node_module = require("node:module");
 let node_process = require("node:process");
 let node_path = require("node:path");
 let node_url = require("node:url");
+let node_child_process = require("node:child_process");
 let node_util = require("node:util");
 let node_crypto = require("node:crypto");
 let node_https = require("node:https");
@@ -16,19 +17,95 @@ let node_stream = require("node:stream");
 function unloadableAddonMessage(path, platform, arch) {
 	return `ventiws: the native addon at ${path} was found but could not be loaded, so it was built for a different ${platform}-${arch} or against a different libc. In a checkout the fix is "pnpm build:binding"; in an install, a package built for this platform. The loader's own error is the cause.`;
 }
-function missingAddonMessage(root, platform, arch) {
-	const target = `${platform}-${arch}`;
-	if (root === void 0) return `ventiws: the package layout is broken -- there is no package.json above the native addon, so the artifact for ${target} cannot be located. Reinstalling ventiws should restore it.`;
-	return `ventiws: no native addon for ${target} was found under ${root}. An install ships the addon for one platform, so a ${target} machine needs ventiws built for ${target}, which needs the Zig toolchain (zig 0.16.0). If you are working in a checkout, the command is "pnpm build:binding".`;
+function missingAddonMessage(root, platform, arch, target, published) {
+	const host = `${platform}-${arch}`;
+	if (root === void 0) return `ventiws: the package layout is broken -- there is no package.json above the native addon, so the artifact for ${host} cannot be located. Reinstalling ventiws should restore it.`;
+	if (target === void 0) return `ventiws: no published native addon for ${host}, so nothing was installed to load. A published ventiws ships a binary for ${published.join(", ")}. In a checkout, the fix is "pnpm build:binding", which builds the addon for this machine.`;
+	return `ventiws: the native addon for ${target} is not installed under ${root}. It is an optional dependency, so npm skipped it for ${host}; an install that resolves no binary for this host needs a reinstall, and a checkout needs "pnpm build:binding".`;
+}
+//#endregion
+//#region src/binding/target.ts
+const ADDON_SCOPE = "@ventiws";
+const PUBLISHED_TARGETS = [
+	"linux-x64-gnu",
+	"linux-arm64-gnu",
+	"linux-x64-musl",
+	"darwin-x64",
+	"darwin-arm64"
+];
+function bindingPackageName(target) {
+	return `${ADDON_SCOPE}/binding-${target}`;
+}
+function addonTarget(nodePlatform, nodeArch) {
+	if (nodePlatform === "darwin") return darwinTarget(nodeArch);
+	if (nodePlatform !== "linux") return void 0;
+	const libc = isMuslLibc() ? "musl" : "gnu";
+	if (nodeArch === "x64") return `linux-x64-${libc}`;
+	if (nodeArch === "arm64" && libc === "gnu") return "linux-arm64-gnu";
+}
+function darwinTarget(nodeArch) {
+	if (nodeArch === "x64") return "darwin-x64";
+	if (nodeArch === "arm64") return "darwin-arm64";
+}
+function isMuslLibc() {
+	const facts = reportFacts();
+	if (facts?.glibcVersionRuntime !== void 0) return false;
+	if (isMuslSharedObject(facts?.sharedObjects)) return true;
+	return probeMuslBinary();
+}
+function reportFacts() {
+	if (typeof process.report?.getReport !== "function") return void 0;
+	const report = asRecord(asRecord(process.report.getReport()));
+	if (report === void 0) return void 0;
+	const facts = {};
+	const glibc = asRecord(report.header)?.glibcVersionRuntime;
+	if (typeof glibc === "string") facts.glibcVersionRuntime = glibc;
+	const objects = report.sharedObjects;
+	if (Array.isArray(objects)) facts.sharedObjects = objects.filter((entry) => typeof entry === "string");
+	return facts;
+}
+function asRecord(value) {
+	if (typeof value === "string") return parsedJson(value);
+	if (typeof value !== "object" || value === null) return void 0;
+	return value;
+}
+function parsedJson(source) {
+	try {
+		return asRecord(JSON.parse(source));
+	} catch {
+		return;
+	}
+}
+function isMuslSharedObject(sharedObjects) {
+	if (sharedObjects === void 0) return false;
+	return sharedObjects.some((entry) => entry.includes("libc.musl-") || entry.includes("ld-musl-"));
+}
+function probeMuslBinary() {
+	try {
+		return (0, node_fs.readFileSync)("/usr/bin/ldd", "utf8").includes("musl");
+	} catch {
+		return probeLddVersion();
+	}
+}
+function probeLddVersion() {
+	try {
+		return (0, node_child_process.execFileSync)("ldd", ["--version"], { encoding: "utf8" }).includes("musl");
+	} catch {
+		return false;
+	}
+}
+function hostAddonTarget() {
+	return addonTarget(node_process.platform, node_process.arch);
 }
 //#endregion
 //#region src/binding/load.ts
 const require$1 = (0, node_module.createRequire)(require("url").pathToFileURL(__filename).href);
-const candidatePaths = [[
+const checkoutPath = [
 	"zig-out",
 	"lib",
 	"ventiws.node"
-], ["dist", "ventiws.node"]];
+];
+const legacyPath = ["dist", "ventiws.node"];
 function findPackageRoot(start) {
 	let current = start;
 	while (current !== void 0) {
@@ -37,25 +114,51 @@ function findPackageRoot(start) {
 		current = parent === current ? void 0 : parent;
 	}
 }
-function resolveAddonPath() {
-	const root = findPackageRoot((0, node_path.dirname)((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href)));
-	for (const parts of candidatePaths) {
-		if (root === void 0) continue;
-		const candidate = (0, node_path.join)(root, ...parts);
-		if ((0, node_fs.existsSync)(candidate)) return candidate;
+function packageRoot() {
+	return findPackageRoot((0, node_path.dirname)((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href)));
+}
+function checkoutArtifact(root) {
+	if (root === void 0) return void 0;
+	const candidate = (0, node_path.join)(root, ...checkoutPath);
+	return (0, node_fs.existsSync)(candidate) ? candidate : void 0;
+}
+function legacyArtifact(root) {
+	if (root === void 0) return void 0;
+	const candidate = (0, node_path.join)(root, ...legacyPath);
+	return (0, node_fs.existsSync)(candidate) ? candidate : void 0;
+}
+function installedBinding(target) {
+	try {
+		return require$1.resolve(bindingPackageName(target));
+	} catch {
+		return;
 	}
-	throw new Error(missingAddonMessage(root, node_process.platform, node_process.arch));
 }
 let addon;
 function loadAddon() {
 	if (addon !== void 0) return addon;
-	const path = resolveAddonPath();
+	addon = resolveAddon();
+	return addon;
+}
+function resolveAddon() {
+	const root = packageRoot();
+	const target = hostAddonTarget();
+	const checkout = checkoutArtifact(root);
+	if (checkout !== void 0) return requireAddon$1(checkout);
+	if (target !== void 0) {
+		const installed = installedBinding(target);
+		if (installed !== void 0) return requireAddon$1(installed);
+	}
+	const legacy = legacyArtifact(root);
+	if (legacy !== void 0) return requireAddon$1(legacy);
+	throw new Error(missingAddonMessage(root, node_process.platform, node_process.arch, target, PUBLISHED_TARGETS));
+}
+function requireAddon$1(path) {
 	try {
-		addon = require$1(path);
+		return require$1(path);
 	} catch (cause) {
 		throw Object.assign(new Error(unloadableAddonMessage(path, node_process.platform, node_process.arch)), { cause });
 	}
-	return addon;
 }
 //#endregion
 //#region src/compat/events/registry.ts

package/dist/index.d.cts

@@ -71,15 +71,15 @@ declare class WebSocket$1 extends EventEmitter {
     fin?: boolean | undefined;
   }, cb?: (err?: Error) => void): void;
   terminate(): void;
-  /**
-   * Pause the websocket causing it to stop emitting events. Some events can still be
-   * emitted after this is called, until all buffered data is consumed. This method
-   * is a noop if the ready state is `CONNECTING` or `CLOSED`.
+  /**
+   * Pause the websocket causing it to stop emitting events. Some events can still be
+   * emitted after this is called, until all buffered data is consumed. This method
+   * is a noop if the ready state is `CONNECTING` or `CLOSED`.
    */
   pause(): void;
-  /**
-   * Make a paused socket resume emitting events. This method is a noop if the ready
-   * state is `CONNECTING` or `CLOSED`.
+  /**
+   * Make a paused socket resume emitting events. This method is a noop if the ready
+   * state is `CONNECTING` or `CLOSED`.
    */
   resume(): void;
   // HTML5 WebSocket events
@@ -143,42 +143,42 @@ declare class WebSocket$1 extends EventEmitter {
 declare const WebSocketAlias: typeof WebSocket$1;
 interface WebSocketAlias extends WebSocket$1 {} // eslint-disable-line @typescript-eslint/no-empty-interface
 declare namespace WebSocket$1 {
-  /**
-   * Data represents the raw message payload received over the WebSocket.
+  /**
+   * Data represents the raw message payload received over the WebSocket.
    */
   type RawData = Buffer | ArrayBuffer | Buffer[];
-  /**
-   * Data represents the message payload received over the WebSocket.
+  /**
+   * Data represents the message payload received over the WebSocket.
    */
   type Data = string | Buffer | ArrayBuffer | Buffer[];
-  /**
-   * CertMeta represents the accepted types for certificate & key data.
+  /**
+   * CertMeta represents the accepted types for certificate & key data.
    */
   type CertMeta = string | string[] | Buffer | Buffer[];
-  /**
-   * VerifyClientCallbackSync is a synchronous callback used to inspect the
-   * incoming message. The return value (boolean) of the function determines
-   * whether or not to accept the handshake.
+  /**
+   * VerifyClientCallbackSync is a synchronous callback used to inspect the
+   * incoming message. The return value (boolean) of the function determines
+   * whether or not to accept the handshake.
    */
   type VerifyClientCallbackSync<Request extends IncomingMessage = IncomingMessage> = (info: {
     origin: string;
     secure: boolean;
     req: Request;
   }) => boolean;
-  /**
-   * VerifyClientCallbackAsync is an asynchronous callback used to inspect the
-   * incoming message. The return value (boolean) of the function determines
-   * whether or not to accept the handshake.
+  /**
+   * VerifyClientCallbackAsync is an asynchronous callback used to inspect the
+   * incoming message. The return value (boolean) of the function determines
+   * whether or not to accept the handshake.
    */
   type VerifyClientCallbackAsync<Request extends IncomingMessage = IncomingMessage> = (info: {
     origin: string;
     secure: boolean;
     req: Request;
   }, callback: (res: boolean, code?: number, message?: string, headers?: OutgoingHttpHeaders) => void) => void;
-  /**
-   * FinishRequestCallback is a callback for last minute customization of the
-   * headers. If finishRequest is set, then it has the responsibility to call
-   * request.end() once it is done setting request headers.
+  /**
+   * FinishRequestCallback is a callback for last minute customization of the
+   * headers. If finishRequest is set, then it has the responsibility to call
+   * request.end() once it is done setting request headers.
    */
   type FinishRequestCallback = (request: ClientRequest, websocket: WebSocket$1) => void;
   interface ClientOptions extends SecureContextOptions {

package/dist/index.d.mts

@@ -72,15 +72,15 @@ declare class WebSocket$1 extends EventEmitter {
     fin?: boolean | undefined;
   }, cb?: (err?: Error) => void): void;
   terminate(): void;
-  /**
-   * Pause the websocket causing it to stop emitting events. Some events can still be
-   * emitted after this is called, until all buffered data is consumed. This method
-   * is a noop if the ready state is `CONNECTING` or `CLOSED`.
+  /**
+   * Pause the websocket causing it to stop emitting events. Some events can still be
+   * emitted after this is called, until all buffered data is consumed. This method
+   * is a noop if the ready state is `CONNECTING` or `CLOSED`.
    */
   pause(): void;
-  /**
-   * Make a paused socket resume emitting events. This method is a noop if the ready
-   * state is `CONNECTING` or `CLOSED`.
+  /**
+   * Make a paused socket resume emitting events. This method is a noop if the ready
+   * state is `CONNECTING` or `CLOSED`.
    */
   resume(): void;
   // HTML5 WebSocket events
@@ -144,42 +144,42 @@ declare class WebSocket$1 extends EventEmitter {
 declare const WebSocketAlias: typeof WebSocket$1;
 interface WebSocketAlias extends WebSocket$1 {} // eslint-disable-line @typescript-eslint/no-empty-interface
 declare namespace WebSocket$1 {
-  /**
-   * Data represents the raw message payload received over the WebSocket.
+  /**
+   * Data represents the raw message payload received over the WebSocket.
    */
   type RawData = Buffer | ArrayBuffer | Buffer[];
-  /**
-   * Data represents the message payload received over the WebSocket.
+  /**
+   * Data represents the message payload received over the WebSocket.
    */
   type Data = string | Buffer | ArrayBuffer | Buffer[];
-  /**
-   * CertMeta represents the accepted types for certificate & key data.
+  /**
+   * CertMeta represents the accepted types for certificate & key data.
    */
   type CertMeta = string | string[] | Buffer | Buffer[];
-  /**
-   * VerifyClientCallbackSync is a synchronous callback used to inspect the
-   * incoming message. The return value (boolean) of the function determines
-   * whether or not to accept the handshake.
+  /**
+   * VerifyClientCallbackSync is a synchronous callback used to inspect the
+   * incoming message. The return value (boolean) of the function determines
+   * whether or not to accept the handshake.
    */
   type VerifyClientCallbackSync<Request extends IncomingMessage = IncomingMessage> = (info: {
     origin: string;
     secure: boolean;
     req: Request;
   }) => boolean;
-  /**
-   * VerifyClientCallbackAsync is an asynchronous callback used to inspect the
-   * incoming message. The return value (boolean) of the function determines
-   * whether or not to accept the handshake.
+  /**
+   * VerifyClientCallbackAsync is an asynchronous callback used to inspect the
+   * incoming message. The return value (boolean) of the function determines
+   * whether or not to accept the handshake.
    */
   type VerifyClientCallbackAsync<Request extends IncomingMessage = IncomingMessage> = (info: {
     origin: string;
     secure: boolean;
     req: Request;
   }, callback: (res: boolean, code?: number, message?: string, headers?: OutgoingHttpHeaders) => void) => void;
-  /**
-   * FinishRequestCallback is a callback for last minute customization of the
-   * headers. If finishRequest is set, then it has the responsibility to call
-   * request.end() once it is done setting request headers.
+  /**
+   * FinishRequestCallback is a callback for last minute customization of the
+   * headers. If finishRequest is set, then it has the responsibility to call
+   * request.end() once it is done setting request headers.
    */
   type FinishRequestCallback = (request: ClientRequest, websocket: WebSocket$1) => void;
   interface ClientOptions extends SecureContextOptions {

package/dist/index.mjs

@@ -1,9 +1,10 @@
 import { createRequire } from "node:module";
 import { STATUS_CODES, createServer, request } from "node:http";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { arch, platform } from "node:process";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
+import { execFileSync } from "node:child_process";
 import { inspect } from "node:util";
 import { createHash, randomBytes } from "node:crypto";
 import { request as request$1 } from "node:https";
@@ -12,19 +13,95 @@ import { Duplex } from "node:stream";
 function unloadableAddonMessage(path, platform, arch) {
 	return `ventiws: the native addon at ${path} was found but could not be loaded, so it was built for a different ${platform}-${arch} or against a different libc. In a checkout the fix is "pnpm build:binding"; in an install, a package built for this platform. The loader's own error is the cause.`;
 }
-function missingAddonMessage(root, platform, arch) {
-	const target = `${platform}-${arch}`;
-	if (root === void 0) return `ventiws: the package layout is broken -- there is no package.json above the native addon, so the artifact for ${target} cannot be located. Reinstalling ventiws should restore it.`;
-	return `ventiws: no native addon for ${target} was found under ${root}. An install ships the addon for one platform, so a ${target} machine needs ventiws built for ${target}, which needs the Zig toolchain (zig 0.16.0). If you are working in a checkout, the command is "pnpm build:binding".`;
+function missingAddonMessage(root, platform, arch, target, published) {
+	const host = `${platform}-${arch}`;
+	if (root === void 0) return `ventiws: the package layout is broken -- there is no package.json above the native addon, so the artifact for ${host} cannot be located. Reinstalling ventiws should restore it.`;
+	if (target === void 0) return `ventiws: no published native addon for ${host}, so nothing was installed to load. A published ventiws ships a binary for ${published.join(", ")}. In a checkout, the fix is "pnpm build:binding", which builds the addon for this machine.`;
+	return `ventiws: the native addon for ${target} is not installed under ${root}. It is an optional dependency, so npm skipped it for ${host}; an install that resolves no binary for this host needs a reinstall, and a checkout needs "pnpm build:binding".`;
+}
+//#endregion
+//#region src/binding/target.ts
+const ADDON_SCOPE = "@ventiws";
+const PUBLISHED_TARGETS = [
+	"linux-x64-gnu",
+	"linux-arm64-gnu",
+	"linux-x64-musl",
+	"darwin-x64",
+	"darwin-arm64"
+];
+function bindingPackageName(target) {
+	return `${ADDON_SCOPE}/binding-${target}`;
+}
+function addonTarget(nodePlatform, nodeArch) {
+	if (nodePlatform === "darwin") return darwinTarget(nodeArch);
+	if (nodePlatform !== "linux") return void 0;
+	const libc = isMuslLibc() ? "musl" : "gnu";
+	if (nodeArch === "x64") return `linux-x64-${libc}`;
+	if (nodeArch === "arm64" && libc === "gnu") return "linux-arm64-gnu";
+}
+function darwinTarget(nodeArch) {
+	if (nodeArch === "x64") return "darwin-x64";
+	if (nodeArch === "arm64") return "darwin-arm64";
+}
+function isMuslLibc() {
+	const facts = reportFacts();
+	if (facts?.glibcVersionRuntime !== void 0) return false;
+	if (isMuslSharedObject(facts?.sharedObjects)) return true;
+	return probeMuslBinary();
+}
+function reportFacts() {
+	if (typeof process.report?.getReport !== "function") return void 0;
+	const report = asRecord(asRecord(process.report.getReport()));
+	if (report === void 0) return void 0;
+	const facts = {};
+	const glibc = asRecord(report.header)?.glibcVersionRuntime;
+	if (typeof glibc === "string") facts.glibcVersionRuntime = glibc;
+	const objects = report.sharedObjects;
+	if (Array.isArray(objects)) facts.sharedObjects = objects.filter((entry) => typeof entry === "string");
+	return facts;
+}
+function asRecord(value) {
+	if (typeof value === "string") return parsedJson(value);
+	if (typeof value !== "object" || value === null) return void 0;
+	return value;
+}
+function parsedJson(source) {
+	try {
+		return asRecord(JSON.parse(source));
+	} catch {
+		return;
+	}
+}
+function isMuslSharedObject(sharedObjects) {
+	if (sharedObjects === void 0) return false;
+	return sharedObjects.some((entry) => entry.includes("libc.musl-") || entry.includes("ld-musl-"));
+}
+function probeMuslBinary() {
+	try {
+		return readFileSync("/usr/bin/ldd", "utf8").includes("musl");
+	} catch {
+		return probeLddVersion();
+	}
+}
+function probeLddVersion() {
+	try {
+		return execFileSync("ldd", ["--version"], { encoding: "utf8" }).includes("musl");
+	} catch {
+		return false;
+	}
+}
+function hostAddonTarget() {
+	return addonTarget(platform, arch);
 }
 //#endregion
 //#region src/binding/load.ts
 const require = createRequire(import.meta.url);
-const candidatePaths = [[
+const checkoutPath = [
 	"zig-out",
 	"lib",
 	"ventiws.node"
-], ["dist", "ventiws.node"]];
+];
+const legacyPath = ["dist", "ventiws.node"];
 function findPackageRoot(start) {
 	let current = start;
 	while (current !== void 0) {
@@ -33,25 +110,51 @@ function findPackageRoot(start) {
 		current = parent === current ? void 0 : parent;
 	}
 }
-function resolveAddonPath() {
-	const root = findPackageRoot(dirname(fileURLToPath(import.meta.url)));
-	for (const parts of candidatePaths) {
-		if (root === void 0) continue;
-		const candidate = join(root, ...parts);
-		if (existsSync(candidate)) return candidate;
+function packageRoot() {
+	return findPackageRoot(dirname(fileURLToPath(import.meta.url)));
+}
+function checkoutArtifact(root) {
+	if (root === void 0) return void 0;
+	const candidate = join(root, ...checkoutPath);
+	return existsSync(candidate) ? candidate : void 0;
+}
+function legacyArtifact(root) {
+	if (root === void 0) return void 0;
+	const candidate = join(root, ...legacyPath);
+	return existsSync(candidate) ? candidate : void 0;
+}
+function installedBinding(target) {
+	try {
+		return require.resolve(bindingPackageName(target));
+	} catch {
+		return;
 	}
-	throw new Error(missingAddonMessage(root, platform, arch));
 }
 let addon;
 function loadAddon() {
 	if (addon !== void 0) return addon;
-	const path = resolveAddonPath();
+	addon = resolveAddon();
+	return addon;
+}
+function resolveAddon() {
+	const root = packageRoot();
+	const target = hostAddonTarget();
+	const checkout = checkoutArtifact(root);
+	if (checkout !== void 0) return requireAddon$1(checkout);
+	if (target !== void 0) {
+		const installed = installedBinding(target);
+		if (installed !== void 0) return requireAddon$1(installed);
+	}
+	const legacy = legacyArtifact(root);
+	if (legacy !== void 0) return requireAddon$1(legacy);
+	throw new Error(missingAddonMessage(root, platform, arch, target, PUBLISHED_TARGETS));
+}
+function requireAddon$1(path) {
 	try {
-		addon = require(path);
+		return require(path);
 	} catch (cause) {
 		throw Object.assign(new Error(unloadableAddonMessage(path, platform, arch)), { cause });
 	}
-	return addon;
 }
 //#endregion
 //#region src/compat/events/registry.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ventiws",
-  "version": "1.0.0-alpha",
+  "version": "1.0.0-alpha.10",
   "description": "A drop-in replacement for ws for Node.js, built on the first-party µWebZockets Zig engine via napi-zig.",
   "homepage": "https://github.com/farbenbuilds/ventiws#readme",
   "bugs": {
@@ -18,51 +18,22 @@
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",
-  "types": "./dist/index.d.mts",
+  "types": "./dist/index.d.cts",
   "exports": {
     ".": {
-      "types": {
-        "import": "./dist/index.d.mts",
-        "require": "./dist/index.d.cts"
-      },
       "import": "./dist/index.mjs",
       "require": "./dist/index.cjs"
     },
     "./package.json": "./package.json"
   },
-  "devDependencies": {
-    "@types/node": "^26.6.3",
-    "@types/ws": "8.18.1",
-    "bumpp": "^12.3.0",
-    "lefthook": "^2.1.14",
-    "napi-zig": "^0.2.8",
-    "oxfmt": "^0.70.0",
-    "oxlint": "^1.85.0",
-    "tsdown": "^0.23.0",
-    "typescript": "^7.0.2",
-    "vite": "^8.3.0",
-    "vitest": "^5.0.2",
-    "ws": "8.21.3"
-  },
   "engines": {
     "node": ">=22.12.0"
   },
-  "scripts": {
-    "build": "pnpm run build:binding && tsdown && node scripts/finalize-exports.mjs && pnpm run typecheck:dist",
-    "build:binding": "napi-zig build --optimize safe",
-    "dev": "tsdown --watch",
-    "format": "oxfmt",
-    "format:check": "oxfmt --check",
-    "lint": "oxlint && node scripts/check-conventions.mjs",
-    "finalize:exports": "node scripts/finalize-exports.mjs",
-    "lint:fix": "oxlint --fix",
-    "test": "pnpm run build:binding && vitest run --no-file-parallelism",
-    "test:watch": "pnpm run build:binding && vitest",
-    "test:compat": "vitest run tests/conformance",
-    "test:autobahn": "node tests/autobahn/run.ts",
-    "bench": "node bench/index.ts",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.test.json",
-    "typecheck:dist": "tsc -p tsconfig.dist-types.json",
-    "release": "bumpp"
+  "optionalDependencies": {
+    "@ventiws/binding-darwin-arm64": "1.0.0-alpha.10",
+    "@ventiws/binding-darwin-x64": "1.0.0-alpha.10",
+    "@ventiws/binding-linux-arm64-gnu": "1.0.0-alpha.10",
+    "@ventiws/binding-linux-x64-gnu": "1.0.0-alpha.10",
+    "@ventiws/binding-linux-x64-musl": "1.0.0-alpha.10"
   }
 }