@simulatte/webgpu 0.2.0

package/assets/package-surface-cube-snapshot.svg

@@ -0,0 +1,81 @@
+<!-- Generated by scripts/generate-readme-assets.js. Do not edit by hand. -->
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="640" viewBox="0 0 1200 640" role="img" aria-labelledby="title desc">
+  <title id="title">Package surface benchmark cube snapshot</title>
+  <desc id="desc">Two-card package surface snapshot for Node and Bun generated from bench/out/cube/latest/cube.summary.json.</desc>
+  <defs>
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#050816"/>
+      <stop offset="100%" stop-color="#0f172a"/>
+    </linearGradient>
+    <linearGradient id="panel-left" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#ef444420"/>
+      <stop offset="60%" stop-color="#ef444426"/>
+      <stop offset="100%" stop-color="#7c3aed22"/>
+    </linearGradient>
+    <linearGradient id="panel-right" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#7c3aed20"/>
+      <stop offset="60%" stop-color="#7c3aed24"/>
+      <stop offset="100%" stop-color="#2563eb22"/>
+    </linearGradient>
+    <style>
+      .title { font: 700 34px "Segoe UI", "Helvetica Neue", Arial, sans-serif; fill: #ffffff; paint-order: stroke fill; stroke: #000000; stroke-width: 2px; stroke-linejoin: round; }
+      .subtitle { font: 500 18px "Segoe UI", "Helvetica Neue", Arial, sans-serif; fill: #cbd5e1; paint-order: stroke fill; stroke: #000000; stroke-width: 2px; stroke-linejoin: round; }
+      .cardTitle { font: 700 26px "Segoe UI", "Helvetica Neue", Arial, sans-serif; fill: #ffffff; paint-order: stroke fill; stroke: #000000; stroke-width: 2px; stroke-linejoin: round; }
+      .cardMeta { font: 500 16px "Segoe UI", "Helvetica Neue", Arial, sans-serif; fill: #cbd5e1; paint-order: stroke fill; stroke: #000000; stroke-width: 2px; stroke-linejoin: round; }
+      .metricTitle { font: 700 18px "Segoe UI", "Helvetica Neue", Arial, sans-serif; fill: #ffffff; paint-order: stroke fill; stroke: #000000; stroke-width: 2px; stroke-linejoin: round; }
+      .metricBody { font: 500 15px SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace; fill: #e2e8f0; paint-order: stroke fill; stroke: #000000; stroke-width: 2px; stroke-linejoin: round; }
+      .pillText { font: 700 13px "Segoe UI", "Helvetica Neue", Arial, sans-serif; fill: #f8fafc; letter-spacing: 0.5px; paint-order: stroke fill; stroke: #000000; stroke-width: 2px; stroke-linejoin: round; }
+      .foot { font: 500 14px "Segoe UI", "Helvetica Neue", Arial, sans-serif; fill: #cbd5e1; paint-order: stroke fill; stroke: #000000; stroke-width: 2px; stroke-linejoin: round; }
+      .panel { stroke-width: 4; }
+      .toneLeft { fill: url(#panel-left); stroke: #ef4444; }
+      .toneRight { fill: url(#panel-right); stroke: #2563eb; }
+      .metric { fill: #020617a8; stroke-width: 1.8; }
+      .metric.toneLeft { stroke: #ef4444; }
+      .metric.toneRight { stroke: #2563eb; }
+    </style>
+  </defs>
+  <rect width="1200" height="640" fill="url(#bg)"/>
+  <text x="72" y="72" class="title">@simulatte/webgpu package snapshot</text>
+  <text x="72" y="102" class="subtitle">Derived from bench/out/cube/latest/cube.summary.json | latest populated cell 2026-03-06T21:55:26.482Z</text>
+  <text x="72" y="128" class="subtitle">Package-surface evidence only. Backend-native strict claim lanes remain separate.</text>
+
+  <rect x="72" y="176" width="488" height="318" rx="24" class="panel toneLeft"/>
+  <text x="100" y="216" class="cardTitle">Node package lane</text>
+  <text x="100" y="244" class="cardMeta">Primary support | mac_apple_silicon</text>
+  <text x="100" y="266" class="cardMeta">latest populated cell 2026-03-06T21:40:32.181Z</text>
+
+  <rect x="90" y="300" width="452" height="82" rx="16" class="metric toneLeft"/>
+  <text x="114" y="331" class="metricTitle">Uploads</text>
+  <rect x="386" y="315" width="132" height="28" rx="14" fill="#16a34a" stroke="#86efac" stroke-width="1.5"/>
+  <text x="452" y="334" text-anchor="middle" class="pillText">CLAIMABLE</text>
+  <text x="114" y="357" class="metricBody">5 rows | claimable</text>
+  <text x="114" y="377" class="metricBody">median p50 delta +53.9%</text>
+
+  <rect x="90" y="396" width="452" height="82" rx="16" class="metric toneLeft"/>
+  <text x="114" y="427" class="metricTitle">Compute E2E</text>
+  <rect x="386" y="411" width="132" height="28" rx="14" fill="#d97706" stroke="#fbbf24" stroke-width="1.5"/>
+  <text x="452" y="430" text-anchor="middle" class="pillText">COMPARABLE</text>
+  <text x="114" y="453" class="metricBody">3 rows | comparable</text>
+  <text x="114" y="473" class="metricBody">median p50 delta +21.2%</text>
+
+  <rect x="640" y="176" width="488" height="318" rx="24" class="panel toneRight"/>
+  <text x="668" y="216" class="cardTitle">Bun package lane</text>
+  <text x="668" y="244" class="cardMeta">Prototype support | linux_x64</text>
+  <text x="668" y="266" class="cardMeta">latest populated cell 2026-03-06T21:55:26.482Z</text>
+
+  <rect x="658" y="300" width="452" height="82" rx="16" class="metric toneRight"/>
+  <text x="682" y="331" class="metricTitle">Compute E2E</text>
+  <rect x="954" y="315" width="132" height="28" rx="14" fill="#16a34a" stroke="#86efac" stroke-width="1.5"/>
+  <text x="1020" y="334" text-anchor="middle" class="pillText">CLAIMABLE</text>
+  <text x="682" y="357" class="metricBody">3 rows | claimable</text>
+  <text x="682" y="377" class="metricBody">median p50 delta +77.2%</text>
+
+  <rect x="658" y="396" width="452" height="82" rx="16" class="metric toneRight"/>
+  <text x="682" y="427" class="metricTitle">Uploads</text>
+  <rect x="954" y="411" width="132" height="28" rx="14" fill="#d97706" stroke="#fbbf24" stroke-width="1.5"/>
+  <text x="1020" y="430" text-anchor="middle" class="pillText">COMPARABLE</text>
+  <text x="682" y="453" class="metricBody">5 rows | comparable</text>
+  <text x="682" y="473" class="metricBody">median p50 delta +8.6%</text>
+  <text x="72" y="590" class="foot">Generated by nursery/webgpu/scripts/generate-readme-assets.js.</text>
+  <text x="72" y="612" class="foot">Static claim and comparability card from the package-surface cube. It is not a substitute for strict backend reports.</text>
+</svg>

package/bin/fawn-webgpu-bench.js

@@ -0,0 +1,182 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { createDoeRuntime } from "../src/node-runtime.js";
+
+function usage() {
+    console.log(`Usage:
+  fawn-webgpu-bench --commands PATH [options]
+
+Options:
+  --commands PATH            Command JSON input (required)
+  --quirks PATH              Quirk JSON input
+  --vendor NAME              Profile vendor
+  --api NAME                 Profile API
+  --family NAME              Device family
+  --driver VERSION           Driver string
+  --trace-jsonl PATH         Trace NDJSON output path
+  --trace-meta PATH          Trace meta JSON output path
+  --queue-wait-mode MODE     process-events|wait-any
+  --queue-sync-mode MODE     per-command|deferred
+  --upload-buffer-usage MODE copy-dst|copy-dst-copy-src
+  --upload-submit-every N    Upload submission cadence
+  --doe-bin PATH             doe-zig-runtime path override
+  --doe-lib PATH             libwebgpu_doe path override
+  --extra-arg ARG            Pass through additional arg to runtime (repeatable)
+  --json                     Emit full JSON result
+  --help                     Show this help
+`);
+}
+
+function parseArgs(argv) {
+    const opts = { extraArgs: [] };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        const next = argv[i + 1];
+        switch (arg) {
+            case "--help":
+                opts.help = true;
+                break;
+            case "--json":
+                opts.json = true;
+                break;
+            case "--commands":
+                opts.commandsPath = next;
+                i += 1;
+                break;
+            case "--quirks":
+                opts.quirksPath = next;
+                i += 1;
+                break;
+            case "--vendor":
+                opts.vendor = next;
+                i += 1;
+                break;
+            case "--api":
+                opts.api = next;
+                i += 1;
+                break;
+            case "--family":
+                opts.family = next;
+                i += 1;
+                break;
+            case "--driver":
+                opts.driver = next;
+                i += 1;
+                break;
+            case "--trace-jsonl":
+                opts.traceJsonlPath = next;
+                i += 1;
+                break;
+            case "--trace-meta":
+                opts.traceMetaPath = next;
+                i += 1;
+                break;
+            case "--queue-wait-mode":
+                opts.queueWaitMode = next;
+                i += 1;
+                break;
+            case "--queue-sync-mode":
+                opts.queueSyncMode = next;
+                i += 1;
+                break;
+            case "--upload-buffer-usage":
+                opts.uploadBufferUsage = next;
+                i += 1;
+                break;
+            case "--upload-submit-every":
+                opts.uploadSubmitEvery = Number.parseInt(next ?? "", 10);
+                i += 1;
+                break;
+            case "--doe-bin":
+                opts.binPath = next;
+                i += 1;
+                break;
+            case "--doe-lib":
+                opts.libPath = next;
+                i += 1;
+                break;
+            case "--extra-arg":
+                opts.extraArgs.push(next ?? "");
+                i += 1;
+                break;
+            default:
+                throw new Error(`Unknown option: ${arg}`);
+        }
+    }
+    return opts;
+}
+
+function toAbsolutePath(path) {
+    if (!path) return path;
+    return resolve(path);
+}
+
+function summarize(result) {
+    const lines = [
+        `ok: ${result.ok}`,
+        `exitCode: ${result.exitCode}`,
+    ];
+    if (result.traceMetaPath) {
+        lines.push(`traceMetaPath: ${result.traceMetaPath}`);
+    }
+    if (result.traceJsonlPath) {
+        lines.push(`traceJsonlPath: ${result.traceJsonlPath}`);
+    }
+    if (result.traceMeta?.executionTotalNs != null) {
+        lines.push(`executionTotalNs: ${result.traceMeta.executionTotalNs}`);
+    }
+    if (result.traceMeta?.executionEncodeTotalNs != null) {
+        lines.push(`executionEncodeTotalNs: ${result.traceMeta.executionEncodeTotalNs}`);
+    }
+    if (result.traceMeta?.executionSubmitWaitTotalNs != null) {
+        lines.push(`executionSubmitWaitTotalNs: ${result.traceMeta.executionSubmitWaitTotalNs}`);
+    }
+    return lines.join("\n");
+}
+
+function main() {
+    const opts = parseArgs(process.argv.slice(2));
+    if (opts.help) {
+        usage();
+        return;
+    }
+    if (!opts.commandsPath) {
+        usage();
+        throw new Error("--commands is required");
+    }
+
+    const runtime = createDoeRuntime({
+        binPath: toAbsolutePath(opts.binPath),
+        libPath: toAbsolutePath(opts.libPath),
+    });
+
+    const result = runtime.runBench({
+        commandsPath: toAbsolutePath(opts.commandsPath),
+        quirksPath: toAbsolutePath(opts.quirksPath),
+        vendor: opts.vendor,
+        api: opts.api,
+        family: opts.family,
+        driver: opts.driver,
+        traceJsonlPath: toAbsolutePath(opts.traceJsonlPath),
+        traceMetaPath: toAbsolutePath(opts.traceMetaPath),
+        queueWaitMode: opts.queueWaitMode,
+        queueSyncMode: opts.queueSyncMode,
+        uploadBufferUsage: opts.uploadBufferUsage,
+        uploadSubmitEvery: opts.uploadSubmitEvery,
+        extraArgs: opts.extraArgs,
+    });
+
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+    } else {
+        console.log(summarize(result));
+    }
+    process.exitCode = result.exitCode;
+}
+
+try {
+    main();
+} catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}

package/bin/fawn-webgpu-compare.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+import { resolve } from "node:path";
+import { runDawnVsDoeCompare } from "../src/node-runtime.js";
+
+function usage() {
+    console.log(`Usage:
+  fawn-webgpu-compare --config PATH [options] [-- <extra compare args>]
+
+Options:
+  --config PATH                compare_dawn_vs_doe config JSON path (required unless passed in --extra-arg)
+  --out PATH                   output report path
+  --repo-root PATH             Fawn repo root override
+  --compare-script PATH        compare_dawn_vs_doe.py path override
+  --python BIN                 Python executable (default: python3)
+  --extra-arg ARG              pass-through arg (repeatable)
+  --help                       show this help
+`);
+}
+
+function parseArgs(argv) {
+    const opts = { extraArgs: [] };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        const next = argv[i + 1];
+        switch (arg) {
+            case "--help":
+                opts.help = true;
+                break;
+            case "--config":
+                opts.configPath = next;
+                i += 1;
+                break;
+            case "--out":
+                opts.outPath = next;
+                i += 1;
+                break;
+            case "--repo-root":
+                opts.repoRoot = next;
+                i += 1;
+                break;
+            case "--compare-script":
+                opts.compareScriptPath = next;
+                i += 1;
+                break;
+            case "--python":
+                opts.pythonBin = next;
+                i += 1;
+                break;
+            case "--extra-arg":
+                opts.extraArgs.push(next ?? "");
+                i += 1;
+                break;
+            case "--":
+                opts.extraArgs.push(...argv.slice(i + 1));
+                i = argv.length;
+                break;
+            default:
+                throw new Error(`Unknown option: ${arg}`);
+        }
+    }
+    return opts;
+}
+
+function toAbsolute(path) {
+    if (!path) return path;
+    return resolve(path);
+}
+
+function main() {
+    const opts = parseArgs(process.argv.slice(2));
+    if (opts.help) {
+        usage();
+        return;
+    }
+
+    const result = runDawnVsDoeCompare({
+        repoRoot: toAbsolute(opts.repoRoot),
+        compareScriptPath: toAbsolute(opts.compareScriptPath),
+        pythonBin: opts.pythonBin,
+        configPath: toAbsolute(opts.configPath),
+        outPath: toAbsolute(opts.outPath),
+        extraArgs: opts.extraArgs,
+    });
+
+    if (result.stdout) process.stdout.write(result.stdout);
+    if (result.stderr) process.stderr.write(result.stderr);
+    process.exitCode = result.exitCode;
+}
+
+try {
+    main();
+} catch (error) {
+    usage();
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+}

package/binding.gyp

@@ -0,0 +1,21 @@
+{
+  "targets": [
+    {
+      "target_name": "doe_napi",
+      "sources": ["native/doe_napi.c"],
+      "include_dirs": [],
+      "defines": ["NAPI_VERSION=8"],
+      "conditions": [
+        ["OS=='mac'", {
+          "xcode_settings": {
+            "OTHER_CFLAGS": ["-std=c11"],
+            "MACOSX_DEPLOYMENT_TARGET": "13.0"
+          }
+        }],
+        ["OS=='linux'", {
+          "cflags": ["-std=c11"]
+        }]
+      ]
+    }
+  ]
+}

package/doe-build-metadata.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "Doe Zig Build Metadata",
+  "type": "object",
+  "required": [
+    "schemaVersion",
+    "artifact",
+    "leanVerifiedBuild",
+    "proofArtifactSha256"
+  ],
+  "properties": {
+    "schemaVersion": { "type": "integer", "const": 1 },
+    "artifact": { "type": "string", "const": "libwebgpu_doe" },
+    "leanVerifiedBuild": { "type": "boolean" },
+    "proofArtifactSha256": {
+      "anyOf": [
+        { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        { "type": "null" }
+      ]
+    }
+  },
+  "additionalProperties": false
+}

package/headless-webgpu-comparison.md

@@ -0,0 +1,43 @@
+# WebGPU Headless Runtime Comparison Matrix
+
+This document outlines qualitative differences and target use-cases for headless WebGPU workloads in JavaScript environments. It is intentionally scoped as a comparison draft, not a claim report.
+
+| Feature / Trait | **Fawn Doe** (`@simulatte/webgpu`) | **Node WebGPU** (`webgpu`) | **Bun WebGPU** (`bun-webgpu`) |
+| :--- | :--- | :--- | :--- |
+| **Underlying Engine** | `libwebgpu_doe` (Zig + Lean pipeline) | Google Dawn (C++) | Google Dawn (C++) |
+| **Primary Focus** | Deterministic Compute, ML/AI, Verifiability | Browser Parity, Graphics | Browser Parity, Graphics |
+| **Binary Footprint** | Smaller targeted runtime expected | Varies by build/distribution | Varies by build/distribution |
+| **JS Binding Layer** | Node-API (N-API) / Bun FFI | Node-API (N-API) | Bun FFI (Fast Foreign Function) |
+| **Security Model** | Explicit schema/gate discipline in Fawn pipeline | Runtime heuristics + Dawn validation | Runtime heuristics + Dawn validation |
+| **Resource Allocation** | Arena-backed, predictable memory | General WebGPU async allocations | General WebGPU async allocations |
+| **WebGPU Spec Compliance**| Compute-prioritized subset target | Broad Chromium-aligned coverage | Broad Chromium-aligned coverage |
+| **WGSL Shader Support** | Runtime-specific compiler/tooling path | Tint | Tint |
+| **Target Use Case** | LLM Inference Testing, Benchmarks, Contracts | E2E Graphics Testing, Headless bots | High-perf TS Server Compute |
+
+## Architectural Takeaways for Fawn
+
+1. Determinism and fail-fast contracts are the intended Doe value proposition for benchmarking workflows.
+2. Bun FFI can reduce wrapper overhead versus heavier bridge layers, but end-to-end results must be measured per workload.
+3. Distribution size and startup claims must be backed by measured artifacts before release claims.
+
+## Ecosystem reference: official/community competitors and stats
+
+Sorted by GitHub stars (snapshot taken: 2026-03-02).
+This list is limited to real WebGPU runtime implementations (not types/tooling).
+
+| Runtime surface | GitHub project | Maintainer signal | Stars |
+| :--- | :--- | :--- | ---: |
+| `webgpu` (npm) | `dawn-gpu/node-webgpu` | `dawn-gpu` (official Dawn upstream) | 73 |
+| `bun-webgpu` (npm) | `kommander/bun-webgpu` | Community maintained | 29 |
+
+Notes:
+
+1. `@simulatte/webgpu` is still pre-publication, so no direct npm star baseline exists in this snapshot yet.
+2. This section is for runtime head-to-head comparability only; stars are a popularity signal, not a quality or correctness signal.
+3. For this repo’s “official” definition, maintainer/org governance is the gate.
+
+## Scaffolding the Fawn NPM Package
+
+- Doe is exposed through a native C ABI and can be bridged from JS via Bun FFI now.
+- Node N-API support now exists in the canonical `@simulatte/webgpu` package.
+- Browser API parity is not claimed by this draft package; the current focus is headless benchmarking workflows.