Doe

Doe is a Zig-first WebGPU runtime built as an explicit, performance-oriented alternative to Dawn.

If you want to use the published package:

• doe-gpu: WebGPU for Node.js, Bun, and Deno, with the Doe runtime and Doe helper API

import { gpu } from 'doe-gpu';           // full (default)
import { gpu } from 'doe-gpu/compute';   // compute-only
import { gpu } from 'doe-gpu/browser';   // browser shim

If you are working on the runtime itself, this repo carries the runtime, package surfaces, browser bring-up, proof artifacts, tracing, and benchmarking.

What this repo contains

• runtime/zig: the Doe runtime, WGSL pipeline, and native backend execution paths
• packages/doe-gpu: the npm package for headless WebGPU
• browser/fawn-browser: browser-owned and Chromium-oriented integration work
• pipeline/agent: quirk mining and normalization
• pipeline/lean: proof artifacts that can remove runtime checks ahead of time
• pipeline/trace: reproducible trace and replay tooling
• bench: Dawn-vs-Doe comparison harnesses and artifacts

Why Doe

Doe is built around a simple split: checks that can be resolved ahead of time should move out of the hot path, and the checks that must stay live should stay explicit in the runtime.

That shows up in a few project-wide choices:

• explicit native backend paths instead of opaque bridge layers
• config-first policy and schema-backed behavior
• optional Lean-backed proof elimination at build time, not a runtime proof interpreter
• benchmark claims grounded in replayable artifacts instead of prose summaries

Current status

Doe currently targets Vulkan, Metal, and D3D12. It is intentionally focused on modern GPU APIs and modern workloads rather than broad legacy-backend coverage.

Benchmarking and claim discipline are important here, but the repo README is not the right place for artifact-by-artifact inventory. The current ground truth lives in:

• docs/status.md
• docs/process.md
• docs/performance-strategy.md
• bench/out/

One distinction matters up front: package-surface results are not treated as a substitute for backend-native Dawn-vs-Doe evidence. Those lanes are tracked separately.

Working in the repo

Pick the README that matches the surface you are touching.

For package consumers:

• use packages/doe-gpu/README.md

For runtime contributors:

• start with runtime/zig/README.md
• then read bench/README.md if your change affects performance or comparability

Quick start

Published package:

npm install doe-gpu

Local runtime work:

cd runtime/zig
zig build test
zig build dropin

Doe currently requires Zig 0.15.2. See config/toolchains.json.

If you are working on Dawn-vs-Doe comparisons, use the benchmark tooling in bench/README.md rather than treating this README as the operational guide.

Deprecated packages

The following packages are deprecated and replaced by doe-gpu:

• @simulatte/webgpu — use doe-gpu instead
• @simulatte/webgpu-doe — merged into doe-gpu

Documentation

• docs/architecture.md: system overview
• docs/process.md: stage order, gates, and release policy
• docs/status.md: current status and tracked follow-ups
• docs/thesis.md: project thesis and framing
• runtime/zig/README.md: runtime development guide
• bench/README.md: benchmark workflows and evidence lanes
• packages/doe-gpu/README.md: npm package

License

See docs/licensing.md.