@simulatte/webgpu-doe 0.1.0 → 0.1.2

package/README.md

@@ -1,116 +1,172 @@
 # @simulatte/webgpu-doe
 
-Native WebGPU runtime for Node.js via the Doe drop-in library.
+Headless WebGPU for Node.js on the Doe 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.
+**[Fawn](https://github.com/clocksmith/fawn/tree/main/nursery/webgpu-doe)** · **[npm](https://www.npmjs.com/package/@simulatte/webgpu-doe)** · **[simulatte.world](https://simulatte.world)**
 
-## Status
+## Install
 
-**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.
+```sh
+npm install @simulatte/webgpu-doe
+```
 
-## Requirements
+The published package currently targets `darwin-arm64`. The N-API addon builds
+from C source during install via `node-gyp`, so a local C toolchain is
+required (`xcode-select --install` on macOS).
 
-- 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
+## Quick start
 
-## Building libdoe_webgpu
+```js
+import { create, globals } from '@simulatte/webgpu-doe';
 
-From the [fawn](https://github.com/clocksmith/fawn) repository:
+const gpu = create();
+const adapter = await gpu.requestAdapter();
+const device = await adapter.requestDevice();
 
-```sh
-cd fawn/zig
-zig build dropin
-# produces zig-out/lib/libdoe_webgpu.{dylib,so}
-```
+console.log(device.limits.maxComputeWorkgroupSizeX); // 1024
+console.log(device.features.has('shader-f16'));       // true
 
-The Dawn sidecar must also be built or obtained separately. See
-`fawn/bench/vendor/dawn/` for build instructions.
+// Standard WebGPU compute workflow
+const buffer = device.createBuffer({
+  size: 64,
+  usage: globals.GPUBufferUsage.STORAGE | globals.GPUBufferUsage.COPY_SRC,
+});
 
-## Install
+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;
+    }
+  `,
+});
 
-```sh
-npm install @simulatte/webgpu-doe
+// ... create pipeline, bind group, encode, dispatch, readback
 ```
 
-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).
+The package loads `libdoe_webgpu` and exposes a WebGPU-shaped API for
+headless compute and basic render work. See [more examples](#more-examples)
+below for `navigator.gpu` setup and provider inspection.
 
-## Configuration
+## Why Doe
 
-The package searches for `libdoe_webgpu` in these locations (first match wins):
+- Native path: JavaScript calls into an N-API addon, which loads
+  `libdoe_webgpu` and submits work through Doe's Metal backend.
+- Runtime ownership: WGSL is compiled to MSL inside Doe's AST-based compiler
+  instead of going through Dawn.
+- Small package payload: the shared library is about 2 MB on `darwin-arm64`.
+- WebGPU-shaped surface: `requestAdapter`, `requestDevice`, buffer mapping,
+  bind groups, compute pipelines, command encoders, and basic render passes are
+  exposed directly from the package.
 
-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}`
+## Status
 
-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`.
+Current package target:
+- macOS arm64: prebuilt library and tested package path
 
-```sh
-export DOE_WEBGPU_LIB=/path/to/libdoe_webgpu.dylib
-export DYLD_LIBRARY_PATH=/path/to/dawn/out/Release
-node your-app.js
-```
+Backend readiness:
 
-## Usage
+| Backend | Compute | Render | WGSL compiler | Status |
+|---------|---------|--------|---------------|--------|
+| **Metal** (macOS) | Production | Basic (no vertex/index) | WGSL -> MSL (AST-based) | Ready for package use |
+| **Vulkan** (Linux) | WIP | Not started | WGSL -> SPIR-V needed | Experimental |
+| **D3D12** (Windows) | WIP | Not started | WGSL -> HLSL/DXIL needed | Experimental |
 
-### Direct API
+Metal currently covers the package's intended use: bind groups 0-3, buffer
+map/unmap, indirect dispatch, `shader-f16`, subgroups, override constants,
+workgroup shared memory, multiple entry points, textures, samplers, and basic
+render-pass execution.
 
-```js
-import { create, globals } from '@simulatte/webgpu-doe';
+Vulkan and D3D12 already have native runtime paths for instance creation,
+compute dispatch, and buffer upload, but they still need shader translation,
+bind group management, buffer map/unmap, textures, and render pipelines.
 
-const gpu = create();
-const adapter = await gpu.requestAdapter();
-const device = await adapter.requestDevice();
+Performance snapshot from the Fawn Dawn-vs-Doe harness on Apple Silicon with
+strict comparability checks:
 
-const buffer = device.createBuffer({
-  size: 64,
-  usage: globals.GPUBufferUsage.STORAGE | globals.GPUBufferUsage.COPY_SRC,
-});
-```
+- 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
+- Concurrent execution: claimable
+- Zero-init workgroup memory: claimable
+- Draw throughput: 200k draws claimable
+- Binary size: about 2 MB vs Dawn's about 11 MB
+
+19 of 30 workloads are currently claimable. The remaining 11 are limited by
+per-command Metal command buffer creation overhead (~350us vs Dawn's ~30us).
+See `fawn/bench/` and [`status.md`](../../status.md) for methodology and the
+broader backend matrix.
+
+## API surface
+
+Compute:
+
+- `create()` / `setupGlobals()` / `requestAdapter()` / `requestDevice()`
+- `device.createBuffer()` / `device.createShaderModule()` (WGSL)
+- `device.createComputePipeline()` / `device.createComputePipelineAsync()`
+- `device.createBindGroupLayout()` / `device.createBindGroup()`
+- `device.createPipelineLayout()` / `pipeline.getBindGroupLayout()`
+- `device.createCommandEncoder()` / `encoder.beginComputePass()`
+- `pass.setPipeline()` / `pass.setBindGroup()` / `pass.dispatchWorkgroups()`
+- `pass.dispatchWorkgroupsIndirect()`
+- `encoder.copyBufferToBuffer()` / `queue.submit()` / `queue.writeBuffer()`
+- `buffer.mapAsync()` / `buffer.getMappedRange()` / `buffer.unmap()`
+- `queue.onSubmittedWorkDone()`
+
+Render:
+
+- `device.createTexture()` / `texture.createView()` / `device.createSampler()`
+- `device.createRenderPipeline()` / `encoder.beginRenderPass()`
+- `renderPass.setPipeline()` / `renderPass.draw()` / `renderPass.end()`
 
-### Setup globals (navigator.gpu)
+Device capabilities:
+
+- `device.limits` / `adapter.limits`
+- `device.features` / `adapter.features` with `shader-f16`
+
+Current gaps:
+- Canvas and surface presentation
+- Vertex and index buffer binding in render passes
+- Full render pipeline descriptor parsing
+
+## More examples
 
 ```js
 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