@simulatte/webgpu 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -7,26 +7,53 @@ retrofitted from package version history and package-surface commits so the npm
 package has a conventional release history alongside the broader Fawn status
 and process documents.
 
+## [0.3.2] - 2026-03-15
+
+### Changed
+
+- Switched the package Doe helper namespace to depend on the standalone
+  `@simulatte/webgpu-doe` package instead of the previous bundled-only import
+  path.
+- Updated the package README to point package users at the new helper-only
+  package when they want the Doe API as an independent npm boundary.
+
+## [0.3.1] - 2026-03-11
+
+### Changed
+
+- Tightened the published package README wording, section names, and layering
+  narrative after the `0.3.0` release.
+- Clarified the terminology split between the `Doe runtime` underneath the
+  package and the `Doe API` JS convenience surface exposed by the package,
+  including the more opinionated `gpu.compute(...)` helper within it.
+- Fixed the layered README SVG asset so it renders correctly on package
+  surfaces.
+
 ## [0.3.0] - 2026-03-11
 
 ### Changed
 
 - Breaking: redesigned the shared `doe` surface around `await
-  doe.requestDevice()`, grouped `gpu.buffers.*`, and grouped
-  `gpu.compute.*` instead of the earlier flat bound-helper methods.
-- Added `gpu.buffers.like(...)` for buffer-allocation boilerplate reduction and
-  `gpu.compute.once(...)` for the first `Doe routines` workflow.
+  doe.requestDevice()`, grouped `gpu.buffer.*`, grouped `gpu.kernel.*`, and
+  `gpu.compute(...)` instead of the earlier flat bound-helper methods.
+- Added `gpu.compute(...)` as the first more opinionated one-shot helper inside
+  the Doe API.
+- `gpu.buffer.create(...)` now accepts an optional `data` field for combined
+  allocation and upload (replaces `fromData`). `like(...)` removed; use
+  `create({ size: src.size, ... })`. `read(...)` now takes an options bag.
 - Doe helper token values now use camelCase (`storageRead`,
   `storageReadWrite`) and Doe workgroups now accept `[x, y]` in addition to
   `number` and `[x, y, z]`.
-- `gpu.compute.once(...)` now rejects raw numeric WebGPU usage flags; use Doe
-  usage tokens there or drop to `gpu.buffers.*` for explicit raw-flag control.
+- `gpu.compute(...)` now rejects raw numeric WebGPU usage flags; use Doe
+  usage tokens there or drop to `gpu.buffer.*` / `gpu.kernel.*` for explicit
+  raw control.
 - Kept the same `doe` shape on `@simulatte/webgpu` and
   `@simulatte/webgpu/compute`; the package split remains the underlying raw
   device surface (`full` vs compute-only facade), not separate helper dialects.
 - Updated the package README, API contract, and JSDoc guide to standardize the
-  `Direct WebGPU`, `Doe API`, and `Doe routines` model and the boundary between the headless package lane and
-  `nursery/fawn-browser`.
+  `Direct WebGPU` and `Doe API` model, including the more opinionated
+  `gpu.compute(...)` helper within the Doe API, and the boundary between
+  the headless package lane and `nursery/fawn-browser`.
 
 ## [0.2.4] - 2026-03-11
 
@@ -54,8 +81,8 @@ and process documents.
 - Added explicit package export surfaces for `@simulatte/webgpu` (default
   full) and `@simulatte/webgpu/compute`, plus the first `doe` ergonomic
   namespace for buffer/readback/compute helpers.
-- Added `doe.bind(device)` so the ergonomic helper surface supports device-bound
-  workflows in addition to static helper calls.
+- Added `doe.bind(device)` so the ergonomic helper surface can wrap an existing
+  device into the same bound helper object returned by `doe.requestDevice()`.
 
 ### Changed
 

package/LICENSE

@@ -0,0 +1,191 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Fawn Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -6,27 +6,35 @@
       <strong>Run real WebGPU workloads in Node.js and Bun with Doe, the WebGPU runtime from Fawn.</strong>
     </td>
     <td valign="middle">
-      <img src="assets/fawn-icon-main-256.png" alt="Fawn logo" width="88" />
+      <img src="assets/fawn-icon-main.svg" alt="Fawn logo" width="88" />
     </td>
   </tr>
 </table>
 
 `@simulatte/webgpu` is Fawn's headless WebGPU package for Node.js and Bun: use
 the raw WebGPU API through `requestDevice()` and `device.*`, or move up to the
-Doe API + routines when you want the same runtime with less setup. Browser
-DOM/canvas ownership lives in the separate `nursery/fawn-browser` lane.
+Doe API when you want the same runtime with less setup. Browser DOM/canvas
+ownership lives in the separate `nursery/fawn-browser` lane.
 
 Terminology in this README is deliberate:
 
 - `Doe runtime` means the Zig/native WebGPU runtime underneath the package
-- `Doe API` means the explicit JS convenience surface under `doe`, `gpu.buffers.*`,
-  `gpu.compute.run(...)`, and `gpu.compute.compile(...)`
-- `Doe routines` means the narrower, more opinionated JS flows such as
-  `gpu.compute.once(...)`
+- `Doe API` means the explicit JS convenience surface under `doe`, `gpu.buffer.*`,
+  `gpu.kernel.run(...)`, `gpu.kernel.create(...)`, and `gpu.compute(...)`
+
+The current implemented helper contract is documented in
+[api-contract.md](./api-contract.md). The proposed naming cleanup for the Doe
+helper surface is documented in [doe-api-design.md](./doe-api-design.md).
+The generated interactive Doe API reference lives at
+[docs/doe-api-reference.html](./docs/doe-api-reference.html).
+
+The same helper layer is now also published separately as
+`@simulatte/webgpu-doe` when you want the Doe API as an independent package
+boundary.
 
 ## Start here
 
-### Same workload, two layers
+### From direct WebGPU to Doe API
 
 The same simple compute pass, shown first at the raw WebGPU layer and then at
 the explicit Doe API layer.
@@ -110,12 +118,10 @@ to manage the resources yourself.
 import { doe } from "@simulatte/webgpu/compute";
 
 const gpu = await doe.requestDevice();
-const src = gpu.buffers.fromData(Float32Array.of(1, 2, 3, 4));
-const dst = gpu.buffers.like(src, {
-  usage: "storageReadWrite",
-});
+const src = gpu.buffer.create({ data: Float32Array.of(1, 2, 3, 4) });
+const dst = gpu.buffer.create({ size: src.size, usage: "storageReadWrite" });
 
-await gpu.compute.run({
+await gpu.kernel.run({
   code: `
     @group(0) @binding(0) var<storage, read> src: array<f32>;
     @group(0) @binding(1) var<storage, read_write> dst: array<f32>;
@@ -131,18 +137,18 @@ await gpu.compute.run({
   workgroups: 1,
 });
 
-console.log(await gpu.buffers.read(dst, Float32Array)); // Float32Array(4) [ 2, 4, 6, 8 ]
+console.log(await gpu.buffer.read({ buffer: dst, type: Float32Array })); // Float32Array(4) [ 2, 4, 6, 8 ]
 ```
 
-The package identity is simple:
+What this package gives you:
 
 - `requestDevice()` gives you real headless WebGPU
 - `doe` gives you the same runtime with less boilerplate and explicit resource control
-- `compute.once(...)` is the more opinionated routines layer when you do not want to manage buffers and readback yourself
+- `gpu.compute(...)` is the more opinionated Doe API helper when you do not want to manage buffers and readback yourself
 
-#### 3. Doe routines: one-shot tensor matmul
+#### 3. Doe API: one-shot tensor matmul
 
-This is where the routines layer starts to separate itself: you pass typed
+This is the more opinionated one-shot end of the Doe API: you pass typed
 arrays and an output spec, and the package handles upload, output allocation,
 dispatch, and readback while the shader and tensor shapes stay explicit.
 
@@ -156,7 +162,7 @@ const lhs = Float32Array.from({ length: M * K }, (_, i) => (i % 17) / 17);
 const rhs = Float32Array.from({ length: K * N }, (_, i) => (i % 13) / 13);
 const dims = new Uint32Array([M, K, N, 0]);
 
-const result = await gpu.compute.once({
+const result = await gpu.compute({
   code: `
     struct Dims {
       m: u32,
@@ -185,11 +191,7 @@ const result = await gpu.compute.once({
       out[row * dims.n + col] = acc;
     }
   `,
-  inputs: [
-    { data: dims, usage: "uniform", access: "uniform" },
-    lhs,
-    rhs,
-  ],
+  inputs: [{ data: dims, usage: "uniform", access: "uniform" }, lhs, rhs],
   output: {
     type: Float32Array,
     size: M * N * Float32Array.BYTES_PER_ELEMENT,
@@ -200,11 +202,11 @@ const result = await gpu.compute.once({
 console.log(result.subarray(0, 8)); // Float32Array(8) [ ... ]
 ```
 
-### Benchmarked package surface
+### Benchmark snapshot
 
-The package is not just a wrapper API. It is the headless package surface of
-the Doe runtime, Fawn's Zig-first WebGPU implementation, and it is exercised as
-a measured package surface with explicit package lanes.
+This package is the headless package surface of the Doe runtime, Fawn's
+Zig-first WebGPU implementation, and it is benchmarked through separate
+Node and Bun package lanes.
 
 <p align="center">
   <img src="assets/package-surface-cube-snapshot.svg" alt="Static package-surface benchmark cube snapshot" width="920" />
@@ -221,6 +223,12 @@ separate `nursery/fawn-browser` Chromium/browser integration lane.
 npm install @simulatte/webgpu
 ```
 
+If you want the helper-only extraction explicitly:
+
+```bash
+npm install @simulatte/webgpu @simulatte/webgpu-doe
+```
+
 The install ships platform-specific prebuilds for macOS arm64 (Metal) and
 Linux x64 (Vulkan). If no prebuild matches your platform, the installer falls
 back to building the native addon with `node-gyp` only; it does not build or
@@ -229,18 +237,18 @@ platforms, use a local Fawn workspace build for those runtime libraries.
 
 ## Choose a surface
 
-| Import                      | Surface               | Includes                                                  |
-| --------------------------- | --------------------- | --------------------------------------------------------- |
-| `@simulatte/webgpu`         | Default full surface  | Buffers, compute, textures, samplers, render, Doe API + routines |
-| `@simulatte/webgpu/compute` | Compute-first surface | Buffers, compute, copy/upload/readback, Doe API + routines |
-| `@simulatte/webgpu/full`    | Explicit full surface | Same contract as the default package surface              |
+| Import                      | Surface               | Includes                                                         |
+| --------------------------- | --------------------- | ---------------------------------------------------------------- |
+| `@simulatte/webgpu`         | Default full surface  | Buffers, compute, textures, samplers, render, Doe API            |
+| `@simulatte/webgpu/compute` | Compute-first surface | Buffers, compute, copy/upload/readback, Doe API                  |
+| `@simulatte/webgpu/full`    | Explicit full surface | Same contract as the default package surface                     |
 
 Use `@simulatte/webgpu/compute` when you want the constrained package contract
 for AI workloads and other buffer/dispatch-heavy headless execution. The
 compute surface intentionally omits render and sampler methods from the JS
 facade.
 
-## Package basics
+## Basic entry points
 
 ### Inspect the provider
 
@@ -269,38 +277,44 @@ console.log(typeof device.createComputePipeline); // "function"
 console.log(typeof device.createRenderPipeline); // "undefined"
 ```
 
-## Doe layers
+## API layers
 
-The package exposes three layers over the same runtime:
+The package gives you two API styles over the same Doe runtime:
 
 <p align="center">
-  <img src="assets/package-layers.svg" alt="Layered package graph showing direct WebGPU, Doe API, and Doe routines over the same package surfaces." width="920" />
+  <img src="assets/package-layers.svg" alt="Layered package graph showing direct WebGPU and Doe API over the same package surfaces." width="920" />
 </p>
 
 - `Direct WebGPU`
   raw `requestDevice()` plus direct `device.*`
 - `Doe API`
-  explicit Doe surface for lower-boilerplate buffer and compute flows
-- `Doe routines`
-  more opinionated Doe flows where the JS surface carries more of the operation
+  explicit Doe surface for lower-boilerplate buffer, kernel, and one-shot compute flows
 
 Examples for each style ship in:
 
 - `examples/direct-webgpu/`
 - `examples/doe-api/`
-- `examples/doe-routines/`
+
+The Doe example directory is organized by API shape:
+
+- `buffers-readback.js` for `gpu.buffer.*`
+- `kernel-run.js` for `gpu.kernel.run(...)`
+- `kernel-create-and-dispatch.js` for `gpu.kernel.create(...)` plus `kernel.dispatch(...)`
+- `compute-one-shot*.js` for the `gpu.compute(...)` helper family
 
 `doe` is the package's shared JS convenience surface over the Doe runtime. It is available
 from both `@simulatte/webgpu` and `@simulatte/webgpu/compute`.
 
 - `await doe.requestDevice()` gets a bound helper object in one step; use
   `doe.bind(device)` when you already have a device.
-- `gpu.buffers.*`, `gpu.compute.run(...)`, and `gpu.compute.compile(...)` are
+- `gpu.buffer.*`, `gpu.kernel.run(...)`, and `gpu.kernel.create(...)` are
   the main `Doe API` surface.
-- `gpu.compute.once(...)` is currently the first `Doe routines` path.
+- `gpu.compute(...)` is the single more opinionated one-shot helper inside the same Doe API surface.
+- `doe` itself is just the binding entrypoint; the actual helper methods live
+  on the returned `gpu` object.
 
-The Doe API and Doe routines surface is the same on both package surfaces.
-The difference is the raw device beneath it:
+The Doe API surface is the same on both package surfaces. The difference is the
+raw device beneath it:
 
 - `@simulatte/webgpu/compute` returns a compute-only facade
 - `@simulatte/webgpu` keeps the full headless device surface
@@ -349,9 +363,9 @@ covers the Node package contract and a packed-tarball export/import check.
 
 ## Further reading
 
+- [Architecture](./architecture.md) — full layer stack from Zig native to package exports
 - [API contract](./api-contract.md)
+- [Doe API design](./doe-api-design.md)
 - [Support contracts](./support-contracts.md)
-- [Compatibility scope](./compat-scope.md)
-- [Layering plan](./layering-plan.md)
+- [Scope and non-goals](./api-contract.md#scope-and-non-goals)
 - [Headless WebGPU comparison](./headless-webgpu-comparison.md)
-- [Zig source inventory](./zig-source-inventory.md)

package/api-contract.md

@@ -3,68 +3,57 @@
 Contract version: `v1`
 
 Scope: current headless WebGPU package contract for Node.js and Bun, with a
-default `full` surface, an explicit `compute` subpath, and the Doe API / Doe
-routines surface used by benchmarking, CI, and artifact-backed comparison
-workflows.
+default `full` surface, an explicit `compute` subpath, and the Doe API surface
+used by benchmarking, CI, and artifact-backed comparison workflows.
 
 Terminology in this contract is explicit:
 
 - `Doe runtime`
   the Zig/native WebGPU runtime underneath the package
 - `Doe API`
-  the explicit JS convenience surface under `doe.bind(...)`, `gpu.buffers.*`,
-  `gpu.compute.run(...)`, and `gpu.compute.compile(...)`
-- `Doe routines`
-  the narrower, more opinionated JS flows layered on that same runtime;
-  currently `gpu.compute.once(...)`
+  the explicit JS convenience surface under `doe.bind(...)`, `gpu.buffer.*`,
+  `gpu.kernel.run(...)`, `gpu.kernel.create(...)`, and `gpu.compute(...)`
 
 For the current `compute` vs `full` support split, see
-[`./support-contracts.md`](./support-contracts.md).
+[`./support-contracts.md`](./support-contracts.md). For scope and non-goals, see
+the bottom of this document.
 
 Exact type and method shapes live in:
 
 - [`./src/full.d.ts`](./src/full.d.ts)
 - [`./src/compute.d.ts`](./src/compute.d.ts)
-- [`./src/doe.d.ts`](./src/doe.d.ts)
+- `@simulatte/webgpu-doe` in `src/index.d.ts`
+
+Planned naming cleanup for the Doe helper surface is documented separately in:
+
+- [`./doe-api-design.md`](./doe-api-design.md)
 
 This contract covers package-surface GPU access, provider metadata, and helper
 entrypoints. It does not promise DOM/canvas ownership or browser-process
 parity.
 
+This is the contract for the current implemented API. It intentionally may
+differ from the future helper naming proposed in `doe-api-design.md`.
+
 ## API styles
 
-The current package surface is organized around three API styles:
+The package surface has two API styles: `Direct WebGPU` (raw
+`requestAdapter`, `requestDevice`, `device.*`) and `Doe API` (convenience
+surface under `doe.bind(...)`, `gpu.buffer.*`, `gpu.kernel.*`, and the
+one-shot `gpu.compute(...)` helper).
 
-- `Direct WebGPU`
-  raw `requestAdapter(...)`, `requestDevice(...)`, and direct `device.*` usage
-- `Doe API`
-  the package's explicit JS convenience surface under `doe.bind(...)`,
-  `gpu.buffers.*`, `gpu.compute.run(...)`, and `gpu.compute.compile(...)`
-- `Doe routines`
-  the package's more opinionated precomposed flows; currently
-  `gpu.compute.once(...)`
+For the full layer stack from Zig native to package exports, see
+[`./architecture.md`](./architecture.md).
 
 ## Export surfaces
 
-### `@simulatte/webgpu`
-
-Default package surface.
-
-Contract:
-
-- headless `full` surface
-- includes compute plus render/sampler/surface APIs already exposed by the Doe runtime package surface
-- also exports the shared `doe` namespace for the Doe API and Doe routines surface
-
-### `@simulatte/webgpu/compute`
-
-Compute-first package surface.
+| Import | Surface |
+|--------|---------|
+| `@simulatte/webgpu` | Default full headless surface + `doe` namespace |
+| `@simulatte/webgpu/compute` | Compute-first facade + `doe` namespace |
 
-Contract:
-
-- sized for AI workloads and other buffer/dispatch-heavy headless execution
-- excludes render/sampler/surface methods from the public JS facade
-- also exports the same `doe` namespace for the Doe API and Doe routines surface
+Export paths and transport details are documented in
+[`./architecture.md`](./architecture.md).
 
 ## Shared runtime API
 
@@ -85,6 +74,10 @@ level:
 - `setupGlobals(...)` installs globals and `navigator.gpu` when missing.
 - `requestAdapter(...)` and `requestDevice(...)` are the `Direct WebGPU` entry
   points.
+- `preflightShaderSource(code)` validates WGSL source before pipeline creation
+  and returns structured compilation diagnostics.
+- `setNativeTimeoutMs(ms)` sets the native-side timeout for synchronous GPU
+  operations (map, flush).
 
 On `@simulatte/webgpu/compute`, the returned device is intentionally
 compute-only:
@@ -105,22 +98,23 @@ Behavior:
 
 Behavior:
 
-- provides the `Doe API` and `Doe routines` surface for common headless
-  compute tasks
+- provides the `Doe API` surface for common headless compute tasks
 - the exported `doe` namespace is the JS convenience surface, distinct from
   the underlying Doe runtime
 - `requestDevice(options?)` resolves the package-local `requestDevice(...)` and returns
   the bound helper object directly
-- supports both static helper calls and `doe.bind(device)` for device-bound workflows
-- helper methods are grouped under `buffers.*` and `compute.*`
-- `buffers.*`, `compute.run(...)`, and `compute.compile(...)` are the main
+- `doe.bind(device)` wraps an existing raw device into the same bound helper object
+- helper methods are grouped under the bound helper object's `buffer.*`,
+  `kernel.*`, and `compute(...)`
+- `buffer.*`, `kernel.run(...)`, and `kernel.create(...)` are the main
   `Doe API` surface
-- `compute.once(...)` is the first `Doe routines` path and stays intentionally
+- `gpu.compute(...)` is the more opinionated one-shot helper inside the same
+  `Doe API` surface and stays intentionally
   narrow: typed-array/headless one-call execution, not a replacement for
   explicit reusable resource ownership
-- infers `compute.run(...).bindings` access from Doe helper-created buffer usage when that
+- infers `kernel.run(...).bindings` access from Doe helper-created buffer usage when that
   usage maps to one bindable access mode (`uniform`, `storageRead`, `storageReadWrite`)
-- `compute.once(...)` accepts Doe usage tokens only; raw numeric WebGPU usage flags stay on
+- `compute(...)` accepts Doe usage tokens only; raw numeric WebGPU usage flags stay on
   the more explicit `Doe API` surface
 - fails fast for bare bindings that do not carry Doe helper usage metadata or whose
   usage is non-bindable/ambiguous; callers must pass `{ buffer, access }` explicitly
@@ -156,8 +150,32 @@ Purpose:
 
 - one-command Dawn-vs-Doe compare wrapper from Node tooling.
 
-## Non-goals in v1
+## Scope and non-goals
+
+This package exists for headless GPU work in Node/Bun: compute, offscreen
+execution, benchmarking, and CI. Compatibility work serves those surfaces first.
+
+### Required now
+
+1. Stable headless Node/Bun provider behavior for real Doe-native execution.
+2. Stable command/trace orchestration for benchmark and CI pipelines.
+3. Reliable wrappers for Doe native bench runs and Dawn-vs-Doe compare runs.
+4. Deterministic artifact paths and non-zero exit-code propagation.
+5. Minimal convenience entrypoints for Node consumers (`create`, `globals`,
+   `requestAdapter`/`requestDevice`, `setupGlobals`).
+
+### Optional later (only when demanded by integrations)
+
+1. Minimal constants compatibility (only constants required by real integrations).
+2. Provider-module swap support for non-default backends beyond `webgpu`.
+
+### Not planned
+
+1. Full `navigator.gpu` browser-parity behavior in Node.
+2. Full object lifetime/event parity (`device lost`, full error scopes, full mapping semantics).
+3. Broad drop-in support for arbitrary npm packages expecting complete `webgpu` behavior.
+4. Browser presentation parity.
 
-1. Full browser-parity WebGPU JS object model emulation.
-2. Browser presentation parity.
-3. npm `webgpu` drop-in compatibility guarantee.
+Decision rule: add parity features only after a concrete headless integration is
+blocked by a missing capability and cannot be addressed by the existing package,
+bridge, or CLI contract.