@simulatte/webgpu 0.2.3 → 0.3.0

package/{LAYERING_PLAN.md → layering-plan.md}

@@ -20,10 +20,10 @@ It answers four questions:
 
 Use this together with:
 
-- `SUPPORT_CONTRACTS.md` for product/support scope
-- `API_CONTRACT.md` for the current single-surface package contract
-- `COMPAT_SCOPE.md` for current package non-goals
-- `ZIG_SOURCE_INVENTORY.md` for the current `zig/src` file map
+- `support-contracts.md` for product/support scope
+- `api-contract.md` for the current package contract (`full` default, `compute` subpath)
+- `compat-scope.md` for current package non-goals
+- `zig-source-inventory.md` for the current `zig/src` file map
 
 ## Current state
 
@@ -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 still exposes a single surface today.
+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.
 
@@ -195,12 +195,14 @@ lean/Fawn/Core/
 lean/Fawn/Full/
 ```
 
-Matching package layout can be one of:
+Matching package layout is currently:
 
 1. one package with scoped exports
-2. separate packages with separate contracts
+   - `@simulatte/webgpu` => `full`
+   - `@simulatte/webgpu/compute` => compute-first subset
 
-Packaging choice is secondary. The source boundary must come first.
+Separate packages remain optional later, but they are not the current shape.
+The source boundary still comes first.
 
 ## Refactor order
 

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,16 +1,32 @@
 {
   "name": "@simulatte/webgpu",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "Headless WebGPU runtime for Node.js and Bun, powered by Doe",
   "type": "module",
   "main": "./src/node-runtime.js",
+  "types": "./src/full.d.ts",
   "exports": {
     ".": {
+      "types": "./src/full.d.ts",
       "bun": "./src/bun.js",
       "default": "./src/node-runtime.js"
     },
-    "./bun": "./src/bun.js",
-    "./node": "./src/node-runtime.js"
+    "./bun": {
+      "types": "./src/full.d.ts",
+      "default": "./src/bun.js"
+    },
+    "./node": {
+      "types": "./src/full.d.ts",
+      "default": "./src/node-runtime.js"
+    },
+    "./compute": {
+      "types": "./src/compute.d.ts",
+      "default": "./src/compute.js"
+    },
+    "./full": {
+      "types": "./src/full.d.ts",
+      "default": "./src/full.js"
+    }
   },
   "bin": {
     "fawn-webgpu-bench": "./bin/fawn-webgpu-bench.js",
@@ -19,6 +35,7 @@
   "files": [
     "assets/",
     "bin/",
+    "examples/",
     "src/",
     "scripts/",
     "native/",
@@ -26,11 +43,11 @@
     "binding.gyp",
     "README.md",
     "CHANGELOG.md",
-    "API_CONTRACT.md",
-    "COMPAT_SCOPE.md",
-    "SUPPORT_CONTRACTS.md",
-    "LAYERING_PLAN.md",
-    "ZIG_SOURCE_INVENTORY.md",
+    "api-contract.md",
+    "compat-scope.md",
+    "support-contracts.md",
+    "layering-plan.md",
+    "zig-source-inventory.md",
     "headless-webgpu-comparison.md",
     "doe-build-metadata.schema.json",
     "prebuild-metadata.schema.json"
@@ -40,7 +57,7 @@
     "build:addon": "node-gyp rebuild",
     "build:readme-assets": "node scripts/generate-readme-assets.js",
     "prebuild": "node scripts/prebuild.js",
-    "test": "node ./test-node.js",
+    "test": "node ./test-node.js && node ./test-package-exports.js",
     "test:bun": "bun ./test-bun.js",
     "smoke": "node scripts/smoke-test.js"
   },

package/prebuilds/darwin-arm64/metadata.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
   "package": "@simulatte/webgpu",
-  "packageVersion": "0.2.3",
+  "packageVersion": "0.3.0",
   "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.0",
   "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';
@@ -26,8 +27,8 @@ const SURFACE_SPECS = [
   {
     surface: 'bun_package',
     title: 'Bun package lane',
-    supportLabel: 'Prototype support',
-    preferredHostProfile: 'linux_x64',
+    supportLabel: 'Validated support',
+    preferredHostProfile: 'mac_apple_silicon',
     focusSets: ['compute_e2e', 'uploads'],
     tone: 'right',
   },
@@ -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;
+}