@simulatte/webgpu 0.2.4 → 0.3.1

package/examples/doe-routines/compute-once-multiple-inputs.js

@@ -0,0 +1,27 @@
+import { doe } from "@simulatte/webgpu/compute";
+
+const gpu = await doe.requestDevice();
+
+const result = await gpu.compute.once({
+  code: `
+    @group(0) @binding(0) var<storage, read> lhs: array<f32>;
+    @group(0) @binding(1) var<storage, read> rhs: array<f32>;
+    @group(0) @binding(2) var<storage, read_write> dst: array<f32>;
+
+    @compute @workgroup_size(4)
+    fn main(@builtin(global_invocation_id) gid: vec3u) {
+      let i = gid.x;
+      dst[i] = lhs[i] + rhs[i];
+    }
+  `,
+  inputs: [
+    new Float32Array([1, 2, 3, 4]),
+    new Float32Array([10, 20, 30, 40]),
+  ],
+  output: {
+    type: Float32Array,
+  },
+  workgroups: 1,
+});
+
+console.log(JSON.stringify(Array.from(result)));

package/examples/doe-routines/compute-once.js

@@ -0,0 +1,23 @@
+import { doe } from "@simulatte/webgpu/compute";
+
+const gpu = await doe.requestDevice();
+
+const result = await gpu.compute.once({
+  code: `
+    @group(0) @binding(0) var<storage, read> src: array<f32>;
+    @group(0) @binding(1) var<storage, read_write> dst: array<f32>;
+
+    @compute @workgroup_size(4)
+    fn main(@builtin(global_invocation_id) gid: vec3u) {
+      let i = gid.x;
+      dst[i] = src[i] * 3.0;
+    }
+  `,
+  inputs: [new Float32Array([1, 2, 3, 4])],
+  output: {
+    type: Float32Array,
+  },
+  workgroups: 1,
+});
+
+console.log(JSON.stringify(Array.from(result)));

package/headless-webgpu-comparison.md

@@ -7,7 +7,7 @@ This document outlines qualitative differences and target use-cases for headless
 | **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); experimental Bun FFI implementation also exists | Node-API (N-API) | Bun FFI (Fast Foreign Function) |
+| **JS Binding Layer** | Node addon-backed path; Bun uses FFI on Linux and full/addon-backed path on macOS today | 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 |
@@ -17,7 +17,7 @@ This document outlines qualitative differences and target use-cases for headless
 ## Architectural Takeaways for Fawn
 
 1. Determinism and fail-fast contracts are the intended Doe value proposition for benchmarking workflows.
-2. The package currently defaults Bun to the addon-backed runtime for correctness parity. The separate Bun FFI path may reduce wrapper overhead later, but end-to-end results must be measured per workload.
+2. The package currently uses a platform-split Bun path: Linux uses the direct FFI route, while macOS uses the addon-backed full path for correctness parity. FFI may reduce wrapper overhead, 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

package/layering-plan.md

@@ -37,7 +37,7 @@ Current reality:
 4. Canonical texture command handling now lives in `zig/src/core/resource/wgpu_texture_commands.zig`; canonical sampler and surface command handling now lives in `zig/src/full/render/wgpu_sampler_commands.zig` and `zig/src/full/surface/wgpu_surface_commands.zig`.
 5. `zig/src/wgpu_commands.zig`, `zig/src/wgpu_resources.zig`, and `zig/src/wgpu_extended_commands.zig` are now compatibility façades over the canonical subtrees, while `zig/src/webgpu_ffi.zig` remains the public façade and owner of `WebGPUBackend`.
 6. Dedicated Zig test lanes now exist as `zig build test-core` and `zig build test-full`, but split coverage remains thin and capability tracking is still represented by one shared coverage ledger.
-7. The JS package now exposes a default `full` surface plus an explicit `compute` subpath, while the underlying JS implementation is still shared.
+7. The JS package now exposes a default `full` surface plus an explicit `compute` subpath, while the underlying JS implementation is still shared and presented through `Direct WebGPU`, `Doe API`, and `Doe routines` styles.
 
 That means this plan is now materially physicalized in the tree, and the remaining semantic split is concentrated in the public façade files and backend roots.
 

package/native/doe_napi.c

@@ -60,6 +60,8 @@ typedef uint32_t WGPUBool;
 #define WGPU_WHOLE_SIZE UINT64_MAX
 #define WGPU_STYPE_SHADER_SOURCE_WGSL 0x00000002
 #define WGPU_WAIT_STATUS_SUCCESS 1
+#define WGPU_WAIT_STATUS_TIMED_OUT 2
+#define WGPU_WAIT_STATUS_ERROR 3
 #define WGPU_MAP_ASYNC_STATUS_SUCCESS 1
 #define WGPU_REQUEST_STATUS_SUCCESS 1
 #define WGPU_CALLBACK_MODE_ALLOW_PROCESS_EVENTS 2
@@ -824,6 +826,11 @@ typedef struct {
     uint32_t done;
 } BufferMapResult;
 
+typedef struct {
+    uint32_t status;
+    uint32_t done;
+} QueueWorkDoneResult;
+
 static void buffer_map_callback(uint32_t status, WGPUStringView message,
     void* userdata1, void* userdata2) {
     (void)message; (void)userdata2;
@@ -832,6 +839,14 @@ static void buffer_map_callback(uint32_t status, WGPUStringView message,
     r->done = 1;
 }
 
+static void queue_work_done_callback(uint32_t status, WGPUStringView message,
+    void* userdata1, void* userdata2) {
+    (void)message; (void)userdata2;
+    QueueWorkDoneResult* r = (QueueWorkDoneResult*)userdata1;
+    r->status = status;
+    r->done = 1;
+}
+
 /* bufferMapSync(instance, buffer, mode, offset, size) */
 static napi_value doe_buffer_map_sync(napi_env env, napi_callback_info info) {
     NAPI_ASSERT_ARGC(env, info, 5);
@@ -1387,16 +1402,58 @@ static napi_value doe_queue_write_buffer(napi_env env, napi_callback_info info)
     return NULL;
 }
 
-/* queueFlush(queue) — wait for all pending GPU work to complete.
- * Calls doeNativeQueueFlush directly (semaphore wait on pending command buffer)
- * instead of routing through wgpuQueueOnSubmittedWorkDone (immediate no-op in Doe). */
+/* queueFlush(instance, queue) — wait for all pending GPU work to complete.
+ * Use the Doe-native queue flush when available; otherwise fall back to the
+ * portable queue work-done callback path and process events until completion. */
 static napi_value doe_queue_flush(napi_env env, napi_callback_info info) {
-    NAPI_ASSERT_ARGC(env, info, 1);
+    NAPI_ASSERT_ARGC(env, info, 2);
     CHECK_LIB_LOADED(env);
-    WGPUQueue queue = unwrap_ptr(env, _args[0]);
+    WGPUInstance inst = unwrap_ptr(env, _args[0]);
+    WGPUQueue queue = unwrap_ptr(env, _args[1]);
     if (!queue) NAPI_THROW(env, "queueFlush requires queue");
-    if (!pfn_doeNativeQueueFlush) NAPI_THROW(env, "queueFlush: doeNativeQueueFlush not available");
-    pfn_doeNativeQueueFlush(queue);
+    if (pfn_doeNativeQueueFlush) {
+        pfn_doeNativeQueueFlush(queue);
+        return NULL;
+    }
+    if (!inst) NAPI_THROW(env, "queueFlush requires instance when doeNativeQueueFlush is unavailable");
+
+    QueueWorkDoneResult result = {0, 0};
+    WGPUQueueWorkDoneCallbackInfo cb_info = {
+        .nextInChain = NULL,
+        .mode = WGPU_CALLBACK_MODE_WAIT_ANY_ONLY,
+        .callback = queue_work_done_callback,
+        .userdata1 = &result,
+        .userdata2 = NULL,
+    };
+
+    WGPUFuture future = pfn_wgpuQueueOnSubmittedWorkDone(queue, cb_info);
+    if (future.id == 0) NAPI_THROW(env, "queueFlush: queue work-done future unavailable");
+    uint64_t start_ns = monotonic_now_ns();
+    while (!result.done) {
+        WGPUFutureWaitInfo wait_info = {
+            .future = future,
+            .completed = 0,
+        };
+        uint32_t wait_status = pfn_wgpuInstanceWaitAny(inst, 1, &wait_info, 0);
+        if (wait_status == WGPU_WAIT_STATUS_SUCCESS) {
+            if (!result.done) {
+                pfn_wgpuInstanceProcessEvents(inst);
+            }
+        } else if (wait_status == WGPU_WAIT_STATUS_TIMED_OUT) {
+            pfn_wgpuInstanceProcessEvents(inst);
+            if (monotonic_now_ns() - start_ns >= DOE_DEFAULT_TIMEOUT_NS) {
+                NAPI_THROW(env, "queueFlush: queue wait timed out");
+            }
+            wait_slice();
+        } else if (wait_status == WGPU_WAIT_STATUS_ERROR) {
+            NAPI_THROW(env, "queueFlush: wgpuInstanceWaitAny failed");
+        } else {
+            NAPI_THROW(env, "queueFlush: unsupported wait status");
+        }
+    }
+    if (result.status != WGPU_QUEUE_WORK_DONE_STATUS_SUCCESS) {
+        NAPI_THROW(env, "queueFlush: queue work did not complete");
+    }
     return NULL;
 }
 
@@ -1547,7 +1604,6 @@ static napi_value doe_submit_compute_dispatch_copy(napi_env env, napi_callback_i
     uint64_t copy_dst_off = (uint64_t)copy_dst_off_i;
     uint64_t copy_size = (uint64_t)copy_size_i;
     if (!device || !queue || !pipeline) NAPI_THROW(env, "submitComputeDispatchCopy requires device, queue, and pipeline");
-    if (!pfn_doeNativeComputeDispatchFlush) NAPI_THROW(env, "submitComputeDispatchCopy: doeNativeComputeDispatchFlush not available");
 
     uint32_t bg_count = 0;
     napi_get_array_length(env, bgs, &bg_count);
@@ -1559,10 +1615,44 @@ static napi_value doe_submit_compute_dispatch_copy(napi_env env, napi_callback_i
         bg_ptrs[j] = unwrap_ptr(env, bg_val);
     }
 
-    pfn_doeNativeComputeDispatchFlush(
-        queue, pipeline, (void**)bg_ptrs, bg_count,
-        dx, dy, dz,
-        copy_src, copy_src_off, copy_dst, copy_dst_off, copy_size);
+    if (pfn_doeNativeComputeDispatchFlush) {
+        pfn_doeNativeComputeDispatchFlush(
+            queue, pipeline, (void**)bg_ptrs, bg_count,
+            dx, dy, dz,
+            copy_src, copy_src_off, copy_dst, copy_dst_off, copy_size);
+        return NULL;
+    }
+
+    WGPUCommandEncoder encoder = pfn_wgpuDeviceCreateCommandEncoder(device, NULL);
+    if (!encoder) NAPI_THROW(env, "submitComputeDispatchCopy: createCommandEncoder failed");
+    WGPUComputePassEncoder pass = pfn_wgpuCommandEncoderBeginComputePass(encoder, NULL);
+    if (!pass) {
+        pfn_wgpuCommandEncoderRelease(encoder);
+        NAPI_THROW(env, "submitComputeDispatchCopy: beginComputePass failed");
+    }
+    pfn_wgpuComputePassEncoderSetPipeline(pass, pipeline);
+    for (uint32_t j = 0; j < bg_count; j++) {
+        if (bg_ptrs[j]) pfn_wgpuComputePassEncoderSetBindGroup(pass, j, bg_ptrs[j], 0, NULL);
+    }
+    pfn_wgpuComputePassEncoderDispatchWorkgroups(pass, dx, dy, dz);
+    pfn_wgpuComputePassEncoderEnd(pass);
+    pfn_wgpuComputePassEncoderRelease(pass);
+    pfn_wgpuCommandEncoderCopyBufferToBuffer(
+        encoder,
+        copy_src,
+        copy_src_off,
+        copy_dst,
+        copy_dst_off,
+        copy_size
+    );
+    WGPUCommandBuffer cmd_buf = pfn_wgpuCommandEncoderFinish(encoder, NULL);
+    if (!cmd_buf) {
+        pfn_wgpuCommandEncoderRelease(encoder);
+        NAPI_THROW(env, "submitComputeDispatchCopy: finish failed");
+    }
+    pfn_wgpuQueueSubmit(queue, 1, &cmd_buf);
+    pfn_wgpuCommandBufferRelease(cmd_buf);
+    pfn_wgpuCommandEncoderRelease(encoder);
     return NULL;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simulatte/webgpu",
-  "version": "0.2.4",
+  "version": "0.3.1",
   "description": "Headless WebGPU runtime for Node.js and Bun, powered by Doe",
   "type": "module",
   "main": "./src/node-runtime.js",
@@ -35,6 +35,7 @@
   "files": [
     "assets/",
     "bin/",
+    "examples/",
     "src/",
     "scripts/",
     "native/",

package/prebuilds/darwin-arm64/metadata.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
   "package": "@simulatte/webgpu",
-  "packageVersion": "0.2.3",
+  "packageVersion": "0.3.1",
   "platform": "darwin",
   "arch": "arm64",
   "nodeNapiVersion": 8,
-  "doeVersion": "68a193c88",
+  "doeVersion": "dae96664a",
   "doeBuild": {
     "artifact": "libwebgpu_doe",
     "leanVerifiedBuild": false,
@@ -13,14 +13,14 @@
   },
   "files": {
     "doe_napi.node": {
-      "sha256": "472c753c5c5bd82b60444bfcc1d3837bdbd40d1fce1b8281e6c706043bb64a84"
+      "sha256": "4baee8a48487e8725b7b6bbccd269da4b4868d28c4d4a26e8ee075f3a8d1e75a"
     },
     "libwebgpu_doe.dylib": {
-      "sha256": "d9a66fa8fad7a8e50736778329ea5c011457c814238f96ecf230eb8eb97bcc64"
+      "sha256": "1598ea11e54c7087ebe9020c07b5bbc0f7d376927b20edac3ed9ca08a0fe6789"
     },
     "libwebgpu_dawn.dylib": {
-      "sha256": "22751faeb459e7a2ec778c0410ca122e23c23366eb3da145c651d1d43e26707d"
+      "sha256": "828fb9ef95b08b4192cb9e84392e432e0d0a4ebca90df678e076e2e3c731b82e"
     }
   },
-  "builtAt": "2026-03-10T17:19:18.720Z"
+  "builtAt": "2026-03-11T18:42:09.399Z"
 }

package/prebuilds/linux-x64/metadata.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
   "package": "@simulatte/webgpu",
-  "packageVersion": "0.2.3",
+  "packageVersion": "0.3.1",
   "platform": "linux",
   "arch": "x64",
   "nodeNapiVersion": 8,
-  "doeVersion": "b09d34586",
+  "doeVersion": "1010cdc41",
   "doeBuild": {
     "artifact": "libwebgpu_doe",
     "leanVerifiedBuild": false,
@@ -13,14 +13,14 @@
   },
   "files": {
     "doe_napi.node": {
-      "sha256": "21475bcd04b499e1a0ed6e75d8af2a7bead08d365ddfb09708d509d0de62bf28"
+      "sha256": "08e6019b07dee38ac7140c27d4c1e10237fec5778e68506fcf85ea85dee797ec"
     },
     "libwebgpu_doe.so": {
-      "sha256": "28c5da84da65a5d6f4a3a74b9757279cddee738aaa93fe8ece6e358d4d94cdb1"
+      "sha256": "ee4f0fcd43751574bc5570492b27a911408e31c90b2c91bd4ee4af09a8f7f5cb"
     },
     "libwebgpu_dawn.so": {
       "sha256": "9d329301f59fbe85a190cee4faacde97f9c991b07264a18a6750b890899cc417"
     }
   },
-  "builtAt": "2026-03-10T21:30:16.241Z"
+  "builtAt": "2026-03-11T18:05:22.324Z"
 }

package/scripts/generate-readme-assets.js

@@ -8,7 +8,8 @@ const __dirname = dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = resolve(__dirname, '..');
 const WORKSPACE_ROOT = resolve(PACKAGE_ROOT, '..', '..');
 const CUBE_SUMMARY_PATH = resolve(WORKSPACE_ROOT, 'bench', 'out', 'cube', 'latest', 'cube.summary.json');
-const OUTPUT_PATH = resolve(PACKAGE_ROOT, 'assets', 'package-surface-cube-snapshot.svg');
+const CUBE_OUTPUT_PATH = resolve(PACKAGE_ROOT, 'assets', 'package-surface-cube-snapshot.svg');
+const LAYERS_OUTPUT_PATH = resolve(PACKAGE_ROOT, 'assets', 'package-layers.svg');
 
 const UI_FONT = '"Segoe UI", "Helvetica Neue", Arial, sans-serif';
 const MONO_FONT = 'SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace';
@@ -256,15 +257,87 @@ ${renderSurfaceCard(SURFACE_SPECS[1], bunCells, 640)}
 `;
 }
 
+function renderLayersSvg() {
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="470" viewBox="0 0 1200 470" role="img" aria-labelledby="layers-title layers-desc">
+  <title id="layers-title">@simulatte/webgpu layered package graph</title>
+  <desc id="layers-desc">Layered package graph showing direct WebGPU, Doe API, and Doe routines over the same package surfaces.</desc>
+  <defs>
+    <linearGradient id="layers-bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#050816"/>
+      <stop offset="100%" stop-color="#140c1f"/>
+    </linearGradient>
+    <radialGradient id="layers-glow-top" cx="25%" cy="18%" r="55%">
+      <stop offset="0%" stop-color="#ef444430"/>
+      <stop offset="55%" stop-color="#7c3aed18"/>
+      <stop offset="100%" stop-color="#00000000"/>
+    </radialGradient>
+    <radialGradient id="layers-glow-bottom" cx="78%" cy="84%" r="52%">
+      <stop offset="0%" stop-color="#f59e0b26"/>
+      <stop offset="60%" stop-color="#f9731618"/>
+      <stop offset="100%" stop-color="#00000000"/>
+    </radialGradient>
+    <linearGradient id="layers-root" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#7c3aed"/>
+      <stop offset="100%" stop-color="#ef4444"/>
+    </linearGradient>
+    <linearGradient id="layers-direct" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#ef4444"/>
+      <stop offset="100%" stop-color="#f97316"/>
+    </linearGradient>
+    <linearGradient id="layers-api" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#f97316"/>
+      <stop offset="100%" stop-color="#f59e0b"/>
+    </linearGradient>
+    <linearGradient id="layers-routines" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" stop-color="#f59e0b"/>
+      <stop offset="100%" stop-color="#eab308"/>
+    </linearGradient>
+    <filter id="shadow" x="-20%" y="-20%" width="140%" height="140%">
+      <feDropShadow dx="0" dy="10" stdDeviation="14" flood-color="#000000" flood-opacity="0.32"/>
+    </filter>
+    <style>
+      .title { font: 700 34px ${UI_FONT}; fill: #ffffff; ${TEXT_STROKE} }
+      .subtitle { font: 500 18px ${UI_FONT}; fill: #cbd5e1; ${TEXT_STROKE} }
+      .nodeTitle { font: 700 22px ${UI_FONT}; fill: #ffffff; ${TEXT_STROKE} }
+      .box { stroke-width: 2.5; filter: url(#shadow); }
+    </style>
+  </defs>
+  <rect width="1200" height="470" fill="url(#layers-bg)"/>
+  <rect width="1200" height="470" fill="url(#layers-glow-top)"/>
+  <rect width="1200" height="470" fill="url(#layers-glow-bottom)"/>
+  <text x="64" y="62" class="title">Same package, four layers</text>
+  <text x="64" y="94" class="subtitle">The package surface stays the same while the API gets progressively higher-level.</text>
+
+  <rect x="170" y="122" width="860" height="64" rx="20" fill="url(#layers-root)" stroke="#c4b5fd" class="box"/>
+  <text x="600" y="162" text-anchor="middle" class="nodeTitle">@simulatte/webgpu / @simulatte/webgpu/compute</text>
+
+  <rect x="220" y="222" width="760" height="52" rx="18" fill="url(#layers-direct)" stroke="#fca5a5" class="box"/>
+  <text x="600" y="255" text-anchor="middle" class="nodeTitle">Direct WebGPU</text>
+
+  <rect x="280" y="310" width="640" height="52" rx="18" fill="url(#layers-api)" stroke="#fdba74" class="box"/>
+  <text x="600" y="343" text-anchor="middle" class="nodeTitle">Doe API</text>
+
+  <rect x="360" y="398" width="480" height="52" rx="18" fill="url(#layers-routines)" stroke="#fde68a" class="box"/>
+  <text x="600" y="431" text-anchor="middle" class="nodeTitle">Doe routines</text>
+</svg>
+`;
+}
+
 function main() {
   const summary = readCubeSummary(CUBE_SUMMARY_PATH);
-  const svg = renderSvg(summary);
-  mkdirSync(dirname(OUTPUT_PATH), { recursive: true });
+  const cubeSvg = renderSvg(summary);
+  const layersSvg = renderLayersSvg();
+  mkdirSync(dirname(CUBE_OUTPUT_PATH), { recursive: true });
+  writeFileSync(
+    CUBE_OUTPUT_PATH,
+    `<!-- Generated by scripts/generate-readme-assets.js. Do not edit by hand. -->\n${cubeSvg}`,
+  );
+  console.log(`Wrote ${CUBE_OUTPUT_PATH}`);
   writeFileSync(
-    OUTPUT_PATH,
-    `<!-- Generated by scripts/generate-readme-assets.js. Do not edit by hand. -->\n${svg}`,
+    LAYERS_OUTPUT_PATH,
+    `<!-- Generated by scripts/generate-readme-assets.js. Do not edit by hand. -->\n${layersSvg}`,
   );
-  console.log(`Wrote ${OUTPUT_PATH}`);
+  console.log(`Wrote ${LAYERS_OUTPUT_PATH}`);
 }
 
 main();

package/scripts/prebuild.js

@@ -60,7 +60,7 @@ function copyArtifact(src, destName) {
   const dest = resolve(prebuildDir, destName);
   copyFileSync(src, dest);
   console.log(`  ${destName} <- ${src}`);
-  return { name: destName, sha256: sha256(dest) };
+  return { name: destName, path: dest };
 }
 
 // 1. Build addon if needed.
@@ -122,13 +122,31 @@ console.log(`\nAssembling prebuilds/${platform}-${arch}/`);
 
 const files = {};
 const addonEntry = copyArtifact(addonSrc, 'doe_napi.node');
-if (addonEntry) files[addonEntry.name] = { sha256: addonEntry.sha256 };
+if (addonEntry) files[addonEntry.name] = { path: addonEntry.path };
 
 const doeEntry = copyArtifact(doeLib, `libwebgpu_doe.${ext}`);
-if (doeEntry) files[doeEntry.name] = { sha256: doeEntry.sha256 };
+if (doeEntry) files[doeEntry.name] = { path: doeEntry.path };
 
 const sidecarEntry = copyArtifact(sidecarSrc, sidecarName);
-if (sidecarEntry) files[sidecarEntry.name] = { sha256: sidecarEntry.sha256 };
+if (sidecarEntry) files[sidecarEntry.name] = { path: sidecarEntry.path };
+
+// macOS: ad-hoc sign dylibs for distribution.
+if (platform === 'darwin') {
+  console.log('\nSigning dylibs (ad-hoc)...');
+  for (const name of Object.keys(files)) {
+    if (name.endsWith('.dylib')) {
+      try {
+        execFileSync('codesign', ['-s', '-', resolve(prebuildDir, name)], { stdio: 'inherit' });
+      } catch {
+        console.warn(`  Warning: codesign failed for ${name} (may already be signed)`);
+      }
+    }
+  }
+}
+
+const metadataFiles = Object.fromEntries(
+  Object.entries(files).map(([name, entry]) => [name, { sha256: sha256(entry.path) }]),
+);
 
 // 5. Write metadata manifest.
 const pkg = JSON.parse(readFileSync(resolve(PACKAGE_ROOT, 'package.json'), 'utf8'));
@@ -153,7 +171,7 @@ const metadata = {
     leanVerifiedBuild: doeBuild.leanVerifiedBuild,
     proofArtifactSha256: doeBuild.proofArtifactSha256,
   },
-  files,
+  files: metadataFiles,
   builtAt: new Date().toISOString(),
 };
 
@@ -161,19 +179,5 @@ const metadataPath = resolve(prebuildDir, 'metadata.json');
 writeFileSync(metadataPath, JSON.stringify(metadata, null, 2) + '\n');
 console.log(`  metadata.json`);
 
-// macOS: ad-hoc sign dylibs for distribution.
-if (platform === 'darwin') {
-  console.log('\nSigning dylibs (ad-hoc)...');
-  for (const name of Object.keys(files)) {
-    if (name.endsWith('.dylib')) {
-      try {
-        execFileSync('codesign', ['-s', '-', resolve(prebuildDir, name)], { stdio: 'inherit' });
-      } catch {
-        console.warn(`  Warning: codesign failed for ${name} (may already be signed)`);
-      }
-    }
-  }
-}
-
 console.log(`\nDone. Prebuild artifacts in prebuilds/${platform}-${arch}/`);
 console.log(`Total files: ${Object.keys(files).length}`);

package/src/auto_bind_group_layout.js

@@ -0,0 +1,32 @@
+export function inferAutoBindGroupLayouts(code, visibility) {
+  const groups = new Map();
+  const bindingPattern = /@group\((\d+)\)\s*@binding\((\d+)\)\s*var(?:<([^>]+)>)?\s+\w+\s*:\s*([^;]+);/g;
+
+  for (const match of code.matchAll(bindingPattern)) {
+    const group = Number(match[1]);
+    const binding = Number(match[2]);
+    const addressSpace = (match[3] ?? '').trim();
+    const typeExpr = (match[4] ?? '').trim();
+    let entry = null;
+
+    if (addressSpace.startsWith('uniform')) {
+      entry = { binding, visibility, buffer: { type: 'uniform' } };
+    } else if (addressSpace.startsWith('storage')) {
+      const readOnly = !addressSpace.includes('read_write');
+      entry = { binding, visibility, buffer: { type: readOnly ? 'read-only-storage' : 'storage' } };
+    } else if (typeExpr.startsWith('sampler')) {
+      entry = { binding, visibility, sampler: {} };
+    }
+
+    if (!entry) continue;
+    const entries = groups.get(group) ?? [];
+    entries.push(entry);
+    groups.set(group, entries);
+  }
+
+  for (const entries of groups.values()) {
+    entries.sort((left, right) => left.binding - right.binding);
+  }
+
+  return groups;
+}