@simulatte/webgpu 0.3.1 → 0.3.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (50) hide show
  1. package/CHANGELOG.md +27 -12
  2. package/LICENSE +191 -0
  3. package/README.md +55 -41
  4. package/api-contract.md +67 -49
  5. package/architecture.md +317 -0
  6. package/assets/package-layers.svg +3 -3
  7. package/docs/doe-api-reference.html +1842 -0
  8. package/doe-api-design.md +237 -0
  9. package/examples/doe-api/README.md +19 -0
  10. package/examples/doe-api/buffers-readback.js +3 -2
  11. package/examples/{doe-routines/compute-once-like-input.js → doe-api/compute-one-shot-like-input.js} +1 -1
  12. package/examples/{doe-routines/compute-once-matmul.js → doe-api/compute-one-shot-matmul.js} +2 -2
  13. package/examples/{doe-routines/compute-once-multiple-inputs.js → doe-api/compute-one-shot-multiple-inputs.js} +1 -1
  14. package/examples/{doe-routines/compute-once.js → doe-api/compute-one-shot.js} +1 -1
  15. package/examples/doe-api/{compile-and-dispatch.js → kernel-create-and-dispatch.js} +4 -6
  16. package/examples/doe-api/{compute-dispatch.js → kernel-run.js} +4 -6
  17. package/headless-webgpu-comparison.md +3 -3
  18. package/jsdoc-style-guide.md +435 -0
  19. package/native/doe_napi.c +1481 -84
  20. package/package.json +18 -6
  21. package/prebuilds/darwin-arm64/doe_napi.node +0 -0
  22. package/prebuilds/darwin-arm64/libwebgpu_doe.dylib +0 -0
  23. package/prebuilds/darwin-arm64/metadata.json +5 -5
  24. package/prebuilds/linux-x64/metadata.json +1 -1
  25. package/scripts/generate-doe-api-docs.js +1607 -0
  26. package/scripts/generate-readme-assets.js +3 -3
  27. package/src/build_metadata.js +7 -4
  28. package/src/bun-ffi.js +1229 -474
  29. package/src/bun.js +5 -1
  30. package/src/compute.d.ts +16 -7
  31. package/src/compute.js +84 -53
  32. package/src/full.d.ts +16 -7
  33. package/src/full.js +12 -10
  34. package/src/index.js +679 -1324
  35. package/src/runtime_cli.js +17 -17
  36. package/src/shared/capabilities.js +144 -0
  37. package/src/shared/compiler-errors.js +78 -0
  38. package/src/shared/encoder-surface.js +295 -0
  39. package/src/shared/full-surface.js +514 -0
  40. package/src/shared/public-surface.js +82 -0
  41. package/src/shared/resource-lifecycle.js +120 -0
  42. package/src/shared/validation.js +495 -0
  43. package/src/webgpu_constants.js +30 -0
  44. package/support-contracts.md +2 -2
  45. package/compat-scope.md +0 -46
  46. package/layering-plan.md +0 -259
  47. package/src/auto_bind_group_layout.js +0 -32
  48. package/src/doe.d.ts +0 -184
  49. package/src/doe.js +0 -641
  50. package/zig-source-inventory.md +0 -468
@@ -260,7 +260,7 @@ ${renderSurfaceCard(SURFACE_SPECS[1], bunCells, 640)}
260
260
  function renderLayersSvg() {
261
261
  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">
262
262
  <title id="layers-title">@simulatte/webgpu layered package graph</title>
263
- <desc id="layers-desc">Layered package graph showing direct WebGPU, Doe API, and Doe routines over the same package surfaces.</desc>
263
+ <desc id="layers-desc">Layered package graph showing direct WebGPU and Doe API over the same package surfaces.</desc>
264
264
  <defs>
265
265
  <linearGradient id="layers-bg" x1="0%" y1="0%" x2="100%" y2="100%">
266
266
  <stop offset="0%" stop-color="#050816"/>
@@ -305,7 +305,7 @@ function renderLayersSvg() {
305
305
  <rect width="1200" height="470" fill="url(#layers-bg)"/>
306
306
  <rect width="1200" height="470" fill="url(#layers-glow-top)"/>
307
307
  <rect width="1200" height="470" fill="url(#layers-glow-bottom)"/>
308
- <text x="64" y="62" class="title">Same package, four layers</text>
308
+ <text x="64" y="62" class="title">Same package, three layers</text>
309
309
  <text x="64" y="94" class="subtitle">The package surface stays the same while the API gets progressively higher-level.</text>
310
310
 
311
311
  <rect x="170" y="122" width="860" height="64" rx="20" fill="url(#layers-root)" stroke="#c4b5fd" class="box"/>
@@ -318,7 +318,7 @@ function renderLayersSvg() {
318
318
  <text x="600" y="343" text-anchor="middle" class="nodeTitle">Doe API</text>
319
319
 
320
320
  <rect x="360" y="398" width="480" height="52" rx="18" fill="url(#layers-routines)" stroke="#fde68a" class="box"/>
321
- <text x="600" y="431" text-anchor="middle" class="nodeTitle">Doe routines</text>
321
+ <text x="600" y="431" text-anchor="middle" class="nodeTitle">Doe API (`gpu.compute(...))</text>
322
322
  </svg>
323
323
  `;
324
324
  }
@@ -1,6 +1,9 @@
1
1
  import { existsSync, readFileSync } from 'node:fs';
2
2
  import { dirname, resolve } from 'node:path';
3
3
 
4
+ const EXPECTED_SCHEMA_VERSION = 1;
5
+ const EXPECTED_ARTIFACT_TYPE = 'libwebgpu_doe';
6
+
4
7
  export const UNKNOWN_DOE_BUILD_METADATA = Object.freeze({
5
8
  source: 'none',
6
9
  path: '',
@@ -18,8 +21,8 @@ function normalizeProofArtifactSha256(value) {
18
21
 
19
22
  function parseDoeBuildSidecar(json, metadataPath, source) {
20
23
  if (!isObject(json)) return null;
21
- if (json.schemaVersion !== 1) return null;
22
- if (json.artifact !== 'libwebgpu_doe') return null;
24
+ if (json.schemaVersion !== EXPECTED_SCHEMA_VERSION) return null;
25
+ if (json.artifact !== EXPECTED_ARTIFACT_TYPE) return null;
23
26
  if (typeof json.leanVerifiedBuild !== 'boolean') return null;
24
27
  const proofArtifactSha256 = normalizeProofArtifactSha256(json.proofArtifactSha256);
25
28
  if (proofArtifactSha256 === undefined) return null;
@@ -33,10 +36,10 @@ function parseDoeBuildSidecar(json, metadataPath, source) {
33
36
 
34
37
  function parsePrebuildMetadata(json, metadataPath, source) {
35
38
  if (!isObject(json)) return null;
36
- if (json.schemaVersion !== 1) return null;
39
+ if (json.schemaVersion !== EXPECTED_SCHEMA_VERSION) return null;
37
40
  const doeBuild = json.doeBuild;
38
41
  if (!isObject(doeBuild)) return null;
39
- if (doeBuild.artifact !== 'libwebgpu_doe') return null;
42
+ if (doeBuild.artifact !== EXPECTED_ARTIFACT_TYPE) return null;
40
43
  if (typeof doeBuild.leanVerifiedBuild !== 'boolean') return null;
41
44
  const proofArtifactSha256 = normalizeProofArtifactSha256(doeBuild.proofArtifactSha256);
42
45
  if (proofArtifactSha256 === undefined) return null;