fix(webgpu): support native uploads, readbacks, and render bundles

Open

thejustinwalshwants to merge intofrom

The native WebGPU adapter rejects or misinterprets standard inputs used by a TypeGPU consumer: GPU flag globals are absent, omitted entry points become "main", and buffer source ranges are ignored. This fills those gaps and adds native texture readback and reusable render-bundle recording/execution.

System

The changes stay at the JavaScript WebGPU adapter boundary. Helpers normalize buffer ranges, texture extents, and callback ABI selection; Dawn records and executes bundles through the existing native FFI exports. The diagram's adapter-to-Dawn boundary also carries bundle commands. Electrobun gains no TypeGPU or Glyph dependency.

Change

Element	Change	Why
Upload and pipeline inputs	Install GPU flag globals; honor `writeBuffer` ranges and tuple extents; preserve omitted entry points for Dawn inference.	Accept standard consumer inputs without app-side patches.
Mapping and completion	Expose `mapState`, use const read mappings, correct callback userdata positions, and add `copyTextureToBuffer`.	Retrieve native GPU results and settle the intended callback.
Render bundles	Add `createRenderBundleEncoder`, binding commands, direct/indexed/indirect draws, debug markers, `finish`, and nonempty `executeBundles`.	Record once and replay compatible draw commands across render passes.
Native handle ownership	Finalize abandoned encoders/bundles; unregister on explicit release or finish; release encoders even when finish fails.	Standard consumers get automatic cleanup, with optional deterministic `release()`.
FFI declarations	Correct the four bundle string-call signatures and their generator for indirect Windows x64 versus two-word ARM64/SysV arguments.	Pass labels and debug strings by the native `WGPUStringView` ABI.

Blast radius

Measured against origin/main: 12 files, with three direct import dependents outside the diff: entries/webgpu.ts, the main SDK entry, and Warren's built-in renderer. Existing upload arguments remain valid. Omitted entry points now reach Dawn's inference path; shaders with multiple eligible entry points must name one.

Verify

From package: node node_modules/typescript/bin/tsc --noEmit: passed.
Pinned Hutch Bun runner, eight focused test files: 24 passed, 0 failed. The isolated bundle fixture checks descriptor layout, dynamic-offset packing/slicing, ordered replay, all four draw commands, and explicit/finalizer cleanup. Exact command below.
macOS ARM64, actual Cottontail 0.7.2 and packaged Electrobun 2.0.4 Dawn: TypeGPU 0.12.8 records direct, indexed, indirect, and indexed-indirect bundles. Each is reused across two submissions; all eight readbacks contain the expected 16 red pixels. Includes nonzero index-buffer offset, empty execution followed by real bundles, and debug groups/markers.
Real C→Cottontail callback fixture on macOS ARM64; cross-target clang output distinguishes Windows ARM64 aggregate registers from Windows x64 indirection. The ABI helper covers six platform/architecture combinations.
Repeat native consumer validation on Windows and Linux, including map/queue completion callbacks.

Risks

Bundle replay resets pipeline/bind-group/vertex/index bindings, even for an empty iterable. Subsequent direct draws must rebind state; the docs call this out.
Garbage collection has nondeterministic timing. Applications that recreate recordings frequently can use release() for prompt native cleanup.
Windows x64 string arguments are indirect; ARM64/SysV use two words. Native Windows/Linux execution remains unchecked.
The adapter retains its pre-existing @ts-nocheck; the range, extent, and ABI helpers are independently typechecked.

Evidence

The native bundle probe at bc0554061140a3e0b8347a45c9b36c15fdc8e1dd verified eight submissions and 128 exact RGBA pixels across the four draw paths. The independent adversarial re-review found no remaining P1/P2 blockers after the ownership and ABI changes.

The earlier combined prototype also exercised Glyph text updates/clipping/removal and queue completion. That historical evidence is separate from the current branch's bundle/readback check above.

Unknowns

Windows/Linux native execution, MSAA/depth bundle rendering, and full WebGPU conformance remain unverified. The standalone TypeGPU native probe is local; the committed isolated fixture uses mocked FFI calls.
TypeGPU's experimental immediate variables still require feature/limit negotiation that this adapter does not expose. The docs state that existing limitation; this PR adds ordinary render-bundle commands.
Existing reports #542, #543, and #544 describe the global flags, map state, and entry-point gaps. They are referenced without auto-closing them.

Agent context

You are reviewing blackboardsh/electrobun PR #585: https://github.com/blackboardsh/electrobun/pull/585.
Problem and plan: complete the native adapter inputs, readback paths, and ordinary render-bundle recording/replay used by an external TypeGPU consumer.
Task: review the change against these measured facts and the platform limitations above.
Facts were collected at the commits below; check each against source before relying on it.
{
  "base": "c54c0c14876455d43a25af0f9cd41a4b14e21854",
  "head": "bc0554061140a3e0b8347a45c9b36c15fdc8e1dd",
  "summary": {
    "filesChanged": 12,
    "insertions": 707,
    "deletions": 28,
    "byKind": {
      "docs": 1,
      "source": 7,
      "test": 4
    },
    "elementsChanged": 2,
    "directDependents": 3,
    "exportedSignatureChanges": 3
  },
  "caveats": [
    "dependents are files whose imports resolve to a changed file; calls through dependency injection, reflection, string paths or generated code are not seen",
    "edge status (added/removed) compares only the imports of files in this diff against base, resolved against the head file list",
    "transitive dependents are followed 3 import hops; a file that imports a re-exporting module counts even when it uses other names from it",
    "no CODEOWNERS file; owners are empty"
  ]
}

Architecture: package and docs are directory fallbacks, not a saved system architecture map. The existing diagram still describes the unchanged adapter-to-native relationship; it predates the additional bundle commands.

Commands run
From package: node node_modules/typescript/bin/tsc --noEmit
HUTCH_HOME=/absolute/agent-deck/.tools/hutch HUTCH_BINARY=/absolute/agent-deck/.tools/hutch/bin/hutch node scripts/run-bun-test.js src/sdks/main/webgpuRenderBundle.test.ts src/sdks/main/webgpuBufferSource.test.ts src/sdks/main/webgpuExtent.test.ts src/sdks/main/webgpuCallback.test.ts src/sdks/main/webgpuRenderPass.test.ts src/sdks/main/webgpuContextKey.test.ts src/sdks/main/webgpuContextRegistry.test.ts src/sdks/main/webgpuPresentationState.test.ts
24 pass; 0 fail. The child fixture contains additional node:assert contract checks.
Native TypeGPU 0.12.8/unplugin-typegpu 0.12.6/esbuild 0.28.2 probe; Cottontail 0.7.2, Electrobun 2.0.4 native runtime; adapter head named above.
Four bundle recordings, each replayed twice: all eight 4x4 GPU readbacks equal red RGBA pixels.
Window/core imports were substituted with an offscreen shim forwarding device/readback operations to the packaged native WGPUBridge functions. No window presentation check or runtime rebuild claimed.
Earlier native callback fixture and cross-target ABI check remain applicable; no callback code changed in this commit.

Full impact facts, lossless gzip+base64
Decoded SHA-256: fe99d2724e68de373efc326afa96a351f6f2298bc833861a7d497250656dacf5
Decode base64 then gunzip to obtain JSON.
BEGIN_GZIP_BASE64_FACTS
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
END_GZIP_BASE64_FACTS

Refs #542 Refs #543 Refs #544

Activity

fix(webgpu): support native TypeGPU uploads and readbacks

42a9739Oct 19

fix(webgpu): respect Windows ARM64 callback ABI and bound bundle support

71a6d11Oct 19

thejustinwalsh11d ago

Addressed adversarial review: callback ABI selection now distinguishes Windows x64 from Windows ARM64, with six architecture cases and a real macOS ARM64 C→Cottontail callback check. Empty executeBundles calls are supported for TypeGPU pass detection; all nonempty inputs now throw NotSupportedError because bundle encoding is not implemented. 25 focused tests and package typecheck pass; native Windows/Linux checks remain pending.

feat(webgpu): record and execute native render bundles

bc05540Oct 19

thejustinwalsh11d ago

Implemented native render-bundle creation, recording, finish, and nonempty execution. Direct, indexed, indirect, and indexed-indirect TypeGPU recordings each passed two native macOS ARM64 submissions/readbacks. Added automatic native-handle finalization plus optional deterministic release, corrected bundle string-call FFI declarations and their generator, and documented binding resets and the existing immediate-variable limitation. Package typecheck and 24 focused tests pass; adversarial re-review found no remaining P1/P2 blockers. Windows/Linux native validation remains pending.