@simulatte/webgpu-doe 0.1.0 → 0.1.1

package/README.md

@@ -1,69 +1,119 @@
 # @simulatte/webgpu-doe
 
-Native WebGPU runtime for Node.js via the Doe drop-in library.
+Headless WebGPU for Node.js, powered by the
+[Doe](https://github.com/clocksmith/fawn) runtime.
 
-Doe (`libdoe_webgpu`) is a Zig-built WebGPU routing layer that provides the
-standard `wgpu*` C ABI. This package wraps it as a Node.js N-API addon, giving
-JavaScript code a WebGPU compute surface without depending on browser runtimes.
+## What this is
 
-## Status
+A native Metal WebGPU implementation for Node.js — no Dawn, no IPC, no
+11 MB sidecar. Doe compiles WGSL to MSL at runtime via an AST-based
+shader compiler and dispatches directly to Metal via a Zig + ObjC bridge.
 
-**v0.1.0 — bring your own libs.** This release ships the N-API binding source
-and JS wrapper. You must build `libdoe_webgpu` yourself and point the package
-to it. Prebuilt binaries are planned for a future release.
+This package ships:
 
-## Requirements
+- **`libdoe_webgpu`** — Doe native runtime (~2 MB, Zig + Metal)
+- **`doe_napi.node`** — N-API addon bridging `libdoe_webgpu` to JavaScript
+- **`src/index.js`** — JS wrapper providing WebGPU-shaped classes and constants
 
-- Node.js >= 18
-- A C compiler (node-gyp builds the N-API addon on `npm install`)
-- `libdoe_webgpu` shared library (`.dylib` / `.so` / `.dll`)
-- Dawn sidecar library (`libwebgpu_dawn`) — loaded by `libdoe_webgpu` at runtime
+## Architecture
 
-## Building libdoe_webgpu
+```
+JavaScript (DoeGPUDevice, DoeGPUBuffer, ...)
+    |
+  N-API addon (doe_napi.c)
+    |
+  libdoe_webgpu.dylib  ← Doe native Metal backend, ~2 MB
+    |
+  Metal.framework       ← GPU execution (Apple Silicon)
+```
 
-From the [fawn](https://github.com/clocksmith/fawn) repository:
+No Dawn dependency. All GPU calls go directly from Zig to Metal.
 
-```sh
-cd fawn/zig
-zig build dropin
-# produces zig-out/lib/libdoe_webgpu.{dylib,so}
-```
+## Performance claims (Metal, Apple Silicon)
 
-The Dawn sidecar must also be built or obtained separately. See
-`fawn/bench/vendor/dawn/` for build instructions.
+Apples-to-apples vs Dawn (Chromium's WebGPU), matched workloads and timing:
 
-## Install
+- **Compute e2e** — 1.5x faster (0.23ms vs 0.35ms, 4096 threads)
+- **Buffer upload** — faster across 1 KB to 4 GB (8 sizes claimable)
+- **Atomics** — workgroup atomic and non-atomic both claimable
+- **Matrix-vector multiply** — 3 variants claimable (naive, swizzle, workgroup-shared)
+- **Concurrent execution** — claimable
+- **Zero-init workgroup memory** — claimable
+- **Draw throughput** — 200k draws claimable
+- **Binary size** — ~2 MB vs Dawn's ~11 MB
 
-```sh
-npm install @simulatte/webgpu-doe
-```
+19 of 30 workloads are claimable. The remaining 11 are bottlenecked by
+per-command Metal command buffer creation overhead (~350us vs Dawn's ~30us).
+See `fawn/bench/` for methodology and raw data.
 
-node-gyp compiles the N-API addon automatically. If the build fails, ensure you
-have a working C toolchain (`xcode-select --install` on macOS, `build-essential`
-on Debian/Ubuntu).
+## API surface
 
-## Configuration
+Compute:
 
-The package searches for `libdoe_webgpu` in these locations (first match wins):
+- `create()` / `setupGlobals()` / `requestAdapter()` / `requestDevice()`
+- `device.createBuffer()` / `device.createShaderModule()` (WGSL)
+- `device.createComputePipeline()` / `device.createBindGroupLayout()`
+- `device.createBindGroup()` / `device.createPipelineLayout()`
+- `device.createCommandEncoder()` / `encoder.beginComputePass()`
+- `pass.setPipeline()` / `pass.setBindGroup()` / `pass.dispatchWorkgroups()`
+- `pass.dispatchWorkgroupsIndirect()`
+- `pipeline.getBindGroupLayout()`
+- `device.createComputePipelineAsync()`
+- `encoder.copyBufferToBuffer()` / `queue.submit()` / `queue.writeBuffer()`
+- `buffer.mapAsync()` / `buffer.getMappedRange()` / `buffer.unmap()`
+- `queue.onSubmittedWorkDone()`
 
-1. `DOE_WEBGPU_LIB` environment variable (full path to the shared library)
-2. `<package>/prebuilds/<platform>-<arch>/libdoe_webgpu.{ext}` (future prebuilds)
-3. `<workspace>/zig/zig-out/lib/libdoe_webgpu.{ext}` (monorepo dev layout)
-4. `<cwd>/zig/zig-out/lib/libdoe_webgpu.{ext}`
+Render:
+
+- `device.createTexture()` / `texture.createView()` / `device.createSampler()`
+- `device.createRenderPipeline()` / `encoder.beginRenderPass()`
+- `renderPass.setPipeline()` / `renderPass.draw()` / `renderPass.end()`
+
+Device capabilities:
+
+- `device.limits` / `adapter.limits` — full Metal device limits
+- `device.features` / `adapter.features` — reports `shader-f16`
+
+Not yet supported: canvas/surface presentation, vertex/index buffer binding
+in render passes, full render pipeline descriptor parsing.
+
+## Backend readiness
+
+| Backend | Compute | Render | WGSL compiler | Status |
+|---------|---------|--------|---------------|--------|
+| **Metal** (macOS) | Production | Basic (no vertex/index) | WGSL -> MSL (AST-based) | Ready |
+| **Vulkan** (Linux) | WIP | Not started | WGSL -> SPIR-V needed | Experimental |
+| **D3D12** (Windows) | WIP | Not started | WGSL -> HLSL/DXIL needed | Experimental |
+
+**Metal** is the primary backend. All Doppler compute workloads run on Metal today:
+bind groups 0-3, buffer map/unmap, indirect dispatch, shader-f16, subgroups,
+override constants, workgroup shared memory, multiple entry points.
+
+**Vulkan** and **D3D12** have real native runtime paths (not stubs) with instance
+creation, compute dispatch, and buffer upload — but lack shader translation,
+bind group management, buffer map/unmap, textures, and render pipelines.
+
+See [`fawn/status.md`](../../status.md) for the full backend implementation matrix.
 
-Dawn's sidecar library must be discoverable at runtime. On macOS/Linux, set
-`DYLD_LIBRARY_PATH` or `LD_LIBRARY_PATH` to include the directory containing
-`libwebgpu_dawn.dylib` / `libwebgpu_dawn.so`.
+## Platform support
+
+| Platform | Architecture | Status |
+|----------|-------------|--------|
+| macOS | arm64 | Prebuilt, tested |
+| macOS | x64 | Not yet built |
+| Linux | x64 | Not yet built (Vulkan backend experimental) |
+| Windows | x64 | Not yet built (D3D12 backend experimental) |
+
+## Install
 
 ```sh
-export DOE_WEBGPU_LIB=/path/to/libdoe_webgpu.dylib
-export DYLD_LIBRARY_PATH=/path/to/dawn/out/Release
-node your-app.js
+npm install @simulatte/webgpu-doe
 ```
 
-## Usage
+The N-API addon compiles from C source on install via node-gyp. This requires
+a C compiler (`xcode-select --install` on macOS).
 
-### Direct API
+## Usage
 
 ```js
 import { create, globals } from '@simulatte/webgpu-doe';
@@ -72,10 +122,26 @@ const gpu = create();
 const adapter = await gpu.requestAdapter();
 const device = await adapter.requestDevice();
 
+console.log(device.limits.maxComputeWorkgroupSizeX); // 1024
+console.log(device.features.has('shader-f16'));       // true
+
+// Standard WebGPU compute workflow
 const buffer = device.createBuffer({
   size: 64,
   usage: globals.GPUBufferUsage.STORAGE | globals.GPUBufferUsage.COPY_SRC,
 });
+
+const shader = device.createShaderModule({
+  code: `
+    @group(0) @binding(0) var<storage, read_write> data: array<f32>;
+    @compute @workgroup_size(64)
+    fn main(@builtin(global_invocation_id) id: vec3u) {
+      data[id.x] = data[id.x] * 2.0;
+    }
+  `,
+});
+
+// ... create pipeline, bind group, encode, dispatch, readback
 ```
 
 ### Setup globals (navigator.gpu)
@@ -84,33 +150,36 @@ const buffer = device.createBuffer({
 import { setupGlobals } from '@simulatte/webgpu-doe';
 
 setupGlobals(globalThis);
-
 const adapter = await navigator.gpu.requestAdapter();
-const device = await adapter.requestDevice();
 ```
 
-### Convenience helpers
+### Provider info
 
 ```js
-import { requestAdapter, requestDevice } from '@simulatte/webgpu-doe';
-
-const adapter = await requestAdapter();
-const device = await requestDevice();
+import { providerInfo } from '@simulatte/webgpu-doe';
+console.log(providerInfo());
+// { module: '@simulatte/webgpu-doe', loaded: true, doeNative: true, ... }
 ```
 
-## Supported surface
+## Configuration
+
+The library search order:
+
+1. `DOE_WEBGPU_LIB` environment variable (full path)
+2. `<package>/prebuilds/<platform>-<arch>/libdoe_webgpu.{ext}`
+3. `<workspace>/zig/zig-out/lib/libdoe_webgpu.{ext}` (monorepo layout)
+4. `<cwd>/zig/zig-out/lib/libdoe_webgpu.{ext}`
 
-v0.1.0 covers the headless compute surface:
+## Building from source
 
-- Instance creation, adapter/device request
-- Buffer create, map, unmap, destroy
-- Shader module creation (WGSL)
-- Compute pipeline, bind group layout, bind group, pipeline layout
-- Command encoder, compute pass (setPipeline, setBindGroup, dispatch, end)
-- Buffer-to-buffer copy
-- Queue submit, queue writeBuffer
+Requires [Zig](https://ziglang.org/download/) (0.15+).
 
-Render passes, textures, and canvas presentation are not yet supported.
+```sh
+git clone https://github.com/clocksmith/fawn
+cd fawn/zig
+zig build dropin
+# Output: zig-out/lib/libdoe_webgpu.{dylib,so}
+```
 
 ## License