doe-gpu

doe-gpu is the JavaScript entry point for Doe's native WebGPU runtime. It loads a native Doe library when one is available and fails explicitly when it is not.

Install

npm install doe-gpu

Package map

+-------------------+
| app code          |
| Node | Bun | Deno |
+---------+---------+
         |
         v
+--------------------------------+
| doe-gpu npm package            |
| JS API + native runtime loader |
+------+------------+------------+
       |            |
       v            v
+-------------+  +--------------------------------+
| entrypoints |  | native library resolution      |
| compute     |  | optional pkg | workspace build |
| native      |  | DOE_WEBGPU_LIB / DOE_LIB       |
| node-webgpu |  +---------------+----------------+
| plan        |                  |
| capture     |                  v
| browser     |          +----------------+
+------+------+          | libwebgpu_doe  |
      |                +-------+--------+
      |                        |
      |                        v
      |          +-------------------------------+
      |          | native backend path           |
      |          | Metal | Vulkan | D3D12/DXIL  |
      |          +---------------+---------------+
      |                          |
      +--------------------------+
                                 v
                      +---------------------+
                      | receipts or explicit|
                      | missing-runtime fail|
                      +---------------------+

+------------------+     +--------------------------+
| doe-gpu/browser  | --> | incumbent browser WebGPU |
+------------------+     +--------------------------+

+-------------------------------+
| Fawn/Chromium                 |
| separate browser release lane |
+-------------------------------+

Usage

Run the package examples:

node node_modules/doe-gpu/examples/node-first-kernel.mjs
bun node_modules/doe-gpu/examples/bun-first-kernel.mjs

Or call the default compute surface:

import { gpu } from "doe-gpu";

const device = await gpu.requestDevice();
const result = await device.compute({
  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;
         }`,
  inputs: [new Float32Array([1, 2, 3, 4])],
  output: { type: Float32Array, size: 16 },
  workgroups: 1,
});

Use createNativeDirect() when you want the native WebGPU provider directly:

import { createNativeDirect } from "doe-gpu";

const gpu = createNativeDirect();
const adapter = await gpu.requestAdapter();
const device = await adapter.requestDevice();

Entry Points

• doe-gpu: default runtime surface
• doe-gpu/compute: compute-focused helper surface
• doe-gpu/native: explicit Zig-backed native WebGPU provider
• doe-gpu/node-webgpu: Node WebGPU provider bootstrap
• doe-gpu/api: provider-neutral helpers and types
• doe-gpu/plan: JSON command-stream and execution-plan contracts
• doe-gpu/capture: record-only WebGPU capture provider
• doe-gpu/browser: browser API wrapper
• doe-gpu/hybrid: compatibility helper for older integrations

Runtime requirements

• Node.js 18+ for the default package entry point
• Bun and Deno are supported through the package entrypoints in exports
• a matching optional platform package, local workspace build, or explicit native library path

Native loading checks these paths:

• npm-installed optional platform packages such as doe-gpu-darwin-arm64 and doe-gpu-linux-x64
• a local workspace build under runtime/zig/zig-out/
• explicit DOE_WEBGPU_LIB / DOE_LIB overrides
• local debug prebuilds under packages/doe-gpu/prebuilds/<platform-arch>/

If the native addon or shared library is missing, the package fails explicitly instead of silently falling back to another runtime.

Evidence

The npm package is the JavaScript wrapper. It does not bundle the full Vulkan, Metal, Dawn-vs-Doe, browser, or hardware evidence trees.

Current public package and runtime evidence is indexed in reports/claim-index.json. The shared chart separates claim-indexed Apple Metal package/native rows, AMD Vulkan package/native/drop-in rows, and diagnostic ORT/browser rows. Read each row by its claim state:

• claim-indexed: public claim row with a report path and claim sidecar.
• diagnostic: measured engineering evidence, not public speed wording.
• status-only: support or capability status without a performance claim.

Do not promote old package charts or local run artifacts unless the current claim index and gates still mark the lane as claimable.

Release boundary

A doe-gpu npm release is a package/native-runtime release. It is not, by itself, a Fawn/Chromium browser release and it does not prove that Doe replaces Dawn in every browser path.

Platform packages and prebuilds are platform-specific. macOS arm64, Linux x64, and future Windows artifacts need matching native libraries, package metadata, and evidence rows. Keep macOS evidence and downloads separate from Linux Vulkan browser diagnostics.

Browser runtime releases need their own public archive, SHA-256, proof surface, launch receipt, and Dawn-vs-Doe comparison receipts outside the npm package.

Browser boundary

doe-gpu/browser wraps the browser's incumbent WebGPU implementation. It is for API compatibility in browser code; it is not Doe replacing the browser runtime.

A future Fawn/Doe browser artifact for macOS arm64 should be documented as a separate browser release lane, not as doe-gpu/browser.

More detail

• repo overview: README.md
• runtime internals: runtime/zig/README.md
• benchmarks and evidence: bench/README.md
• current status: docs/status.md

Legacy package names

These legacy package names are deprecated in favor of doe-gpu:

• @simulatte/webgpu
• @simulatte/webgpu-doe

License

Apache-2.0. See docs/licensing.md.