update docs

Author: 0xF6

README.md

@@ -6,9 +6,10 @@
 [![bun](https://img.shields.io/badge/bun-%E2%89%A5%201.4-f9f1e1?logo=bun)](https://bun.sh)
 
 **The `webgpu` npm package segfaults Bun. This is a WebGPU that runs there.** A `bun:ffi` binding to
-[wgpu-native](https://github.com/gfx-rs/wgpu-native), API-compatible with
-[`webgpu`](https://www.npmjs.com/package/webgpu) — headless compute and offscreen rendering on
-Windows, macOS and Linux, x64 and arm64.
+[wgpu-native](https://github.com/gfx-rs/wgpu-native) — the C API over
+[`wgpu`](https://github.com/gfx-rs/wgpu), which is the core of WebGPU in **Firefox, Servo and
+Deno** — API-compatible with [`webgpu`](https://www.npmjs.com/package/webgpu). Headless compute and
+offscreen rendering on Windows, macOS and Linux, x64 and arm64.
 
 ```sh
 bun add wgpu-bun
@@ -79,7 +80,7 @@ It is a **subpath** on purpose: the root export stays exactly the three names `w
 
 | | **wgpu-bun** | [`bun-webgpu`](https://github.com/kommander/bun-webgpu) | [`webgpu`](https://www.npmjs.com/package/webgpu) |
 |---|---|---|---|
-| Backend | **wgpu-native** (the Rust `wgpu` everyone else ships) | Dawn | Dawn |
+| Backend | **wgpu-native** — the Rust `wgpu` behind Firefox, Servo and Deno | Dawn — Chromium's | Dawn — Chromium's |
 | Runs under Bun | **yes** | yes | **no** — the N-API addon segfaults the runtime |
 | `popErrorScope()` | **reports, with negative tests proving it can go red** | crashes its allocator, even on an empty scope | works |
 | `getCompilationInfo()` | **real diagnostics**, synthesised from the validation error | unimplemented | works |

docs/COMPATIBILITY.md

@@ -94,8 +94,15 @@ And by design:
 - **Browser API fidelity beyond WebGPU.** No `requestAnimationFrame`, no `ImageBitmap`, no
   `OffscreenCanvas`. Note that `queue.copyExternalImageToTexture` therefore has no equivalent — decode
   to a `Uint8Array` and use `writeTexture`.
-- **Dawn.** Not a fallback, not a build flag. If you want Dawn under Bun, `bun-webgpu` already does it.
-- **Node.** Bun-only, deliberately — `bun:ffi` *is* the implementation strategy.
+- **Dawn.** Not a fallback and not a build flag *in this package*. If you want Dawn under Bun,
+  `bun-webgpu` already does it.
+- **Node.** Bun-only, deliberately — `bun:ffi` *is* the implementation strategy here.
+
+  Both of those are properties of **this package**, not of the repository. `wgpu-bun` is the Bun
+  binding; a Node counterpart, or a Dawn-backed one, would be its own package built on its own
+  mechanism, and neither would change what the sentences above say about this one. That is also why
+  the repository is `argon-chat/wgpu` and not `argon-chat/wgpu-bun` — see
+  [RELEASE.md](./RELEASE.md#repository-name-deliberately-not-the-package-name).
 - **WebGPU CTS conformance.** A worthy goal; not a claim that will be made before it is measured.
 
 Nothing on this list returns a plausible-looking nothing. A call either does the thing or throws

docs/ERROR-PATH.md

@@ -79,10 +79,22 @@ choice**, so those are first-class deliverables, not a later milestone.
 
 Dawn and wgpu-native are both conformant-ish WebGPU implementations that disagree in observable ways:
 validation strictness, WGSL acceptance, reported limits, resource lifetimes, error message text.
-Neither is "correct"; they are different. wgpu-native is the C API over
-[wgpu](https://github.com/gfx-rs/wgpu), the same implementation every Rust/wgpu consumer ships. If
-that is your deployment target, a Dawn-backed binding tests an implementation you do not run — and
-passes.
+Neither is "correct"; they are different.
+
+They are also not obscure alternatives — they are **the two browser implementations**, and which one
+you validate against is the choice this package exists to hand you:
+
+| | implementation | ships in |
+|---|---|---|
+| **wgpu-native** — what this binds | the C API over [`wgpu`](https://github.com/gfx-rs/wgpu) | "the core of the WebGPU integration in **Firefox, Servo, and Deno**" — wgpu's own README |
+| **Dawn** — what `webgpu` and `bun-webgpu` bind | Google's implementation | "the underlying implementation of WebGPU in **Chromium**" — Dawn's own README |
+
+Deno is the one to notice if you are choosing a JavaScript runtime's binding: its WebGPU is wgpu, so
+this is the binding that makes Bun agree with Deno rather than with Chrome. And if you ship a Rust
+or wgpu-based renderer, it is the same implementation your other half already runs.
+
+The general form of the argument: a Dawn-backed binding tests an implementation you may not deploy —
+and passes.
 
 Bindings are the right layer to make that choice at. Being able to pick the implementation your JS
 code is validated against, rather than inheriting whichever one your binding's author preferred, is

docs/RELEASE.md

@@ -95,19 +95,18 @@ Worth knowing before submitting: the existing entries do not consistently follow
 actually reads. The maintainers ask for edits on the existing PR rather than a new one, so expect a
 round of review rather than a merge or a close.
 
-## Repository name and discoverability
+## Repository name: deliberately NOT the package name
 
-The npm package is `wgpu-bun`; the repository is `argon-chat/wgpu`. A search for "bun webgpu" on
-GitHub does not find the latter, which is the whole audience.
+The npm package is `wgpu-bun`; the repository is `argon-chat/wgpu`, and it stays that way.
 
-Renaming to `wgpu-bun` costs a redirect GitHub maintains for you, and requires updating in the same
-change:
+The obvious argument for renaming is discoverability — a GitHub search for "bun webgpu" does not
+find `argon-chat/wgpu`. Topics answer that (below), and the owner's roadmap answers the rest:
+**Dawn and a Node port are both on the table.** A repository named `wgpu-bun` would then be hosting
+a binding that is neither only-wgpu nor only-bun, and renaming a second time costs the same as the
+first. The package name is one artefact this repository produces, not its identity.
 
-- `repository.url`, `homepage` and `bugs.url` in `package.json` — an npm trusted-publisher
-  configuration matches on the repository, so it must be updated on npmjs.com too, for all five
-  packages;
-- the three badge URLs at the top of `README.md`;
-- the `SHIM_ASSETS` release URLs in `shim.manifest.ts`.
+So if a future reader wonders why the two names differ: they differ on purpose, and the general one
+is the repository.
 
 Topics, which cost nothing and are how GitHub search actually finds things: