wgpu-kit 1.0.3 → 1.1.1

package/README.cn.md

@@ -1,6 +1,6 @@
 # wgpu-kit
 
-> 浏览器创意编程 GPU 工具包:20 万粒子物理 120fps,只需 5 行代码。
+> 浏览器创意编程 GPU 工具包:20 万粒子物理 120fps,只需 5 行代码。(所有 fps 均为**可见帧**)
 > WebGPU 计算的全套样板——设备、缓冲、管线、dispatch、双缓冲、读回、错误行号映射——打包成两层简单 API。
 
 [![CI](https://github.com/nanfengw0w/wgpu-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/nanfengw0w/wgpu-kit/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/wgpu-kit)](https://www.npmjs.com/package/wgpu-kit) [![license MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
@@ -70,8 +70,8 @@ await integrate.run({ pos, vel }, { dt: 0.02 });
 
 | 指标 | 数值 | 环境 |
 | --- | --- | --- |
-| 粒子端到端 | 200,000 @ 122fps / 66,000 @ 144fps | RTX 4060 Laptop,playground 实测 |
-| 粒子计算(grid) | 16k→262k 平坦,3.0→3.3ms/帧 | headless 基准 |
+| 粒子端到端 | 200,000 @ 122fps · 66,000 @ 144fps(**可见帧**)| RTX 4060 Laptop,playground 实测 |
+| 粒子计算(grid) | 16k→262k 平坦,3.0→4.4ms/帧 | headless 基准,GPU 42°C |
 | 邻域算法 | grid 近似 O(N),66k 时比暴力快 8.5× | 同会话 A/B |
 | 库体积 | core gzip ~10kB(共享上下文构建) | gzip |
 

package/README.md

@@ -1,11 +1,12 @@
 # wgpu-kit
 
-**Browser GPGPU middle layer. 200,000 particles at 142fps — in 5 lines of code.**
-All the WebGPU boilerplate — device, buffers, pipelines, dispatch, readbacks — wrapped into two simple API layers.
-
 [![CI](https://github.com/nanfengw0w/wgpu-kit/actions/workflows/ci.yml/badge.svg)](https://github.com/nanfengw0w/wgpu-kit/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/wgpu-kit)](https://www.npmjs.com/package/wgpu-kit) [![license MIT](https://img.shields.io/badge/license-MIT-green)](LICENSE)
 
-[**API Reference**](docs/API.md) · [中文文档](README.cn.md) · **[LIVE DEMO](https://nanfengw0w.github.io/wgpu-kit/)** · Changelog: [releases](https://github.com/nanfengw0w/wgpu-kit/releases)
+**Creative-coding GPU toolkit for the browser. 200,000-particle physics at 120fps — in 5 lines of code.**
+All the WebGPU boilerplate — device, buffers, pipelines, dispatch, double
+buffering, readbacks, error line-mapping — wrapped into two simple API layers.
+
+[**API Reference**](docs/API.md) · [中文文档](README.cn.md) · **[LIVE DEMO](https://nanfengw0w.github.io/wgpu-kit/)**
 
 ![wgpu-kit particle life](hero.gif)
 
@@ -18,7 +19,7 @@ npm i wgpu-kit
 **100,000 particles in 5 lines:**
 
 ```ts
-import { particles } from 'wgpu-kit';  // 或 'wgpu-kit/particles'
+import { particles } from 'wgpu-kit';
 
 const sim = await particles({ count: 100_000, forces: 'cells' });
 await sim.attach(canvas);
@@ -50,6 +51,42 @@ await integrate.run({ pos, vel }, { dt: 0.02 });
 Device management, buffer sizing, pipeline creation, double buffering,
 dispatch, readbacks, error line-mapping — all handled by the library.
 
+### The same thing, with raw WebGPU
+
+For honesty: here is the **heavily condensed** native equivalent (full
+version is ~150 lines; this excerpt omits error handling, resize, double
+buffering, staging readbacks and the render pipeline):
+
+```ts
+const adapter = await navigator.gpu.requestAdapter();
+const device = await adapter.requestDevice();
+
+// buffers — sizes and usages hand-computed
+const pos = device.createBuffer({ size: 100_000 * 8, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC });
+const vel = device.createBuffer({ size: 100_000 * 8, usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST | GPUBufferUsage.COPY_SRC });
+
+// hand-written WGSL, uniform struct aligned to 16 bytes by hand
+const module = device.createShaderModule({ code: `...struct Params {...}...` });
+
+const pipeline = device.createComputePipeline({ layout: 'auto', compute: { module, entryPoint: 'main' } });
+const bindGroup = device.createBindGroup({ layout: pipeline.getBindGroupLayout(0), entries: [/* every binding, exact order */] });
+
+function tick(dt) {
+  const enc = device.createCommandEncoder();
+  const pass = enc.beginComputePass();
+  pass.setPipeline(pipeline);
+  pass.setBindGroup(0, bindGroup);
+  pass.dispatchWorkgroups(Math.ceil(100_000 / 64));
+  pass.end();
+  device.queue.submit([enc.finish()]);
+}
+// …plus: staging readbacks, device-lost handling, WGSL compile diagnostics,
+// canvas resize — and a render pipeline before anything is visible.
+```
+
+With `wgpu-kit`, the kernel is the only code you write — and when WGSL fails
+to compile, the error points at **your line**.
+
 ## Entry points
 
 | import | purpose |
@@ -62,6 +99,7 @@ dispatch, readbacks, error line-mapping — all handled by the library.
 | `wgpu-kit/react` | `<ParticleCanvas />` |
 | `wgpu-kit/three` | three.js snapshot interop |
 | `wgpu-kit/media` | canvas recording (webm/mp4) |
+| `wgpu-kit/observe` | GPU timing / device diagnostics / canvas helpers |
 | `wgpu-kit/vite` | WGSL kernel hot reload |
 
 ![life quartet](life-quartet.png)
@@ -70,19 +108,14 @@ dispatch, readbacks, error line-mapping — all handled by the library.
 
 ## Numbers (reproducible)
 
+All fps numbers are **visible frames** — every `tick()` renders fresh state.
+
 | metric | value | environment |
 | --- | --- | --- |
-| particles end-to-end | 200,000 @ 142fps | RTX 4060 Laptop, playground |
-| particle compute (grid) | 131k @ 0.89ms/frame | headless bench |
-| neighborhood algorithms | grid ~O(N); 8.5× faster than brute force at 66k | same-session A/B |
-| bundle size | core gzip 5.5kB; +particles 10.3kB | gzip |
-
-## Verification
-
-41+ automated probes run on a real GPU via a headless Chromium harness
-(included under `tests/` + `scripts/verify.mjs`) — including a physics
-equivalence regression that fails if the neighborhood algorithms ever
-produce divergent structures.
+| particles end-to-end | 200,000 @ 122fps · 66,000 @ 144fps | RTX 4060 Laptop, playground |
+| particle compute (grid) | 16k→262k flat, 3.0→4.4ms/frame | reproducible via `npm run bench` → docs/BENCHMARK.md |
+| neighborhood algorithms | grid ~O(N), 8.5× faster than brute force at 66k | same-session A/B |
+| bundle size | core gzip ~10kB (all entries share one context) | measured by `npm run build` |
 
 ## Three design rules
 
@@ -92,6 +125,13 @@ produce divergent structures.
 3. **Benchmarks are documentation** — every published number is reproducible;
    gzip budgets are enforced by `npm run build`.
 
+## Verification
+
+41+ automated probes run on a real GPU via a headless Chromium harness
+(included: `tests/` + `scripts/verify.mjs`) — including a **physics
+equivalence regression** that fails the build if the neighborhood algorithms
+(n2 / tiled / grid) ever produce divergent structures.
+
 ## Support matrix
 
 | browser | status |

package/dist/core/buffer.js

@@ -1,6 +1,6 @@
 import { TYPES } from "./layout.js";
 import { GpuContext } from "./context.js";
-import { UsageError } from "./errors.js";
+import { ERR, UsageError } from "./errors.js";
 const TYPED_CTORS = {
     Float32Array, Int32Array, Uint32Array,
 };
@@ -16,6 +16,7 @@ export class Buffer {
     #ctx;
     #byteLength;
     #stride;
+    #reading = null;
     #staging = null;
     constructor(ctx, kind, length, gpuBuffer) {
         this.#ctx = ctx;
@@ -27,11 +28,11 @@ export class Buffer {
     }
     static async create(kind, length) {
         if (!Number.isInteger(length) || length <= 0) {
-            throw new UsageError(`Buffer 长度必须是正整数,收到: ${String(length)}`);
+            throw new UsageError(ERR.BUFFER_CREATE, `Buffer length must be a positive integer, got: ${String(length)}`);
         }
         const def = TYPES[kind];
         if (!def)
-            throw new UsageError(`未知类型 "${String(kind)}",可用: ${Object.keys(TYPES).join(', ')}`);
+            throw new UsageError(ERR.BUFFER_CREATE, `Unknown Buffer kind "${String(kind)}". Available: ${Object.keys(TYPES).join(", ")}`);
         const ctx = await GpuContext.get();
         const gpuBuffer = ctx.device.createBuffer({
             size: length * def.stride,
@@ -45,11 +46,11 @@ export class Buffer {
         const def = TYPES[this.kind];
         const ctor = TYPED_CTORS[def.typed];
         if (!(data instanceof ctor)) {
-            throw new UsageError(`Buffer<${this.kind}>.write 需要 ${def.typed},收到 ${data.constructor?.name ?? typeof data}`);
+            throw new UsageError(ERR.BUFFER_WRITE, `Buffer<${this.kind}>.write expects ${def.typed}, got ${data.constructor?.name ?? typeof data}`);
         }
         const expected = this.length * def.comps;
         if (data.length !== expected) {
-            throw new UsageError(`Buffer<${this.kind}>[${this.length}].write 需要 ${expected} 个分量,收到 ${data.length}`);
+            throw new UsageError(ERR.BUFFER_WRITE, `Buffer<${this.kind}>[${this.length}].write expects ${expected} components, got ${data.length}`);
         }
         if (def.stride === def.size || def.comps === 1) {
             this.#ctx.device.queue.writeBuffer(this.gpuBuffer, 0, data);
@@ -67,6 +68,17 @@ export class Buffer {
     }
     /** GPU → CPU:内部 staging buffer + mapAsync,mapAsync 的异步陷阱由库承担 */
     async read() {
+        if (this.#reading)
+            return this.#reading;
+        this.#reading = this.#doRead();
+        try {
+            return await this.#reading;
+        }
+        finally {
+            this.#reading = null;
+        }
+    }
+    async #doRead() {
         const def = TYPES[this.kind];
         if (!this.#staging) {
             this.#staging = this.#ctx.device.createBuffer({

package/dist/core/codes.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Error codes for programmatic identification of wgpu-kit errors.
+ * These are stable string constants — safe to switch on in user code.
+ */
+export declare const ERR: {
+    /** WebGPU is unavailable or the adapter could not be acquired */
+    readonly WGPU_UNAVAILABLE: "ERR_WGPU_UNAVAILABLE";
+    /** WGSL compilation failed */
+    readonly COMPILE: "ERR_COMPILE";
+    /** Invalid argument passed by the caller */
+    readonly USAGE: "ERR_USAGE";
+    /** A required uniform field is missing or has an invalid value */
+    readonly UNIFORM_FIELD: "ERR_UNIFORM_FIELD";
+    /** Uniform scalar types are not yet supported */
+    readonly UNIFORM_UNSUPPORTED: "ERR_UNIFORM_UNSUPPORTED";
+    /** workgroupSize is outside the valid range */
+    readonly WORKGROUP_SIZE: "ERR_WORKGROUP_SIZE";
+    /** A resource (Buffer) is missing from the resources map */
+    readonly RESOURCE_MISSING: "ERR_RESOURCE_MISSING";
+    /** A resource type does not match the kernel declaration */
+    readonly RESOURCE_TYPE: "ERR_RESOURCE_TYPE";
+    /** Resource lengths are inconsistent across state/inputs */
+    readonly RESOURCE_LENGTH: "ERR_RESOURCE_LENGTH";
+    /** Buffer.create received an invalid kind or length */
+    readonly BUFFER_CREATE: "ERR_BUFFER_CREATE";
+    /** Buffer.write type or component count mismatch */
+    readonly BUFFER_WRITE: "ERR_BUFFER_WRITE";
+    /** MediaRecorder is unavailable or the recording failed */
+    readonly MEDIA: "ERR_MEDIA";
+    /** timestamp-query is not supported on this device */
+    readonly TIMESTAMP_UNSUPPORTED: "ERR_TIMESTAMP_UNSUPPORTED";
+    /** A generic library error that doesn't fit any specific code */
+    readonly GENERIC: "ERR_GENERIC";
+};
+export type ErrorCode = (typeof ERR)[keyof typeof ERR];

package/dist/core/codes.js

@@ -0,0 +1,34 @@
+/**
+ * Error codes for programmatic identification of wgpu-kit errors.
+ * These are stable string constants — safe to switch on in user code.
+ */
+export const ERR = {
+    /** WebGPU is unavailable or the adapter could not be acquired */
+    WGPU_UNAVAILABLE: 'ERR_WGPU_UNAVAILABLE',
+    /** WGSL compilation failed */
+    COMPILE: 'ERR_COMPILE',
+    /** Invalid argument passed by the caller */
+    USAGE: 'ERR_USAGE',
+    /** A required uniform field is missing or has an invalid value */
+    UNIFORM_FIELD: 'ERR_UNIFORM_FIELD',
+    /** Uniform scalar types are not yet supported */
+    UNIFORM_UNSUPPORTED: 'ERR_UNIFORM_UNSUPPORTED',
+    /** workgroupSize is outside the valid range */
+    WORKGROUP_SIZE: 'ERR_WORKGROUP_SIZE',
+    /** A resource (Buffer) is missing from the resources map */
+    RESOURCE_MISSING: 'ERR_RESOURCE_MISSING',
+    /** A resource type does not match the kernel declaration */
+    RESOURCE_TYPE: 'ERR_RESOURCE_TYPE',
+    /** Resource lengths are inconsistent across state/inputs */
+    RESOURCE_LENGTH: 'ERR_RESOURCE_LENGTH',
+    /** Buffer.create received an invalid kind or length */
+    BUFFER_CREATE: 'ERR_BUFFER_CREATE',
+    /** Buffer.write type or component count mismatch */
+    BUFFER_WRITE: 'ERR_BUFFER_WRITE',
+    /** MediaRecorder is unavailable or the recording failed */
+    MEDIA: 'ERR_MEDIA',
+    /** timestamp-query is not supported on this device */
+    TIMESTAMP_UNSUPPORTED: 'ERR_TIMESTAMP_UNSUPPORTED',
+    /** A generic library error that doesn't fit any specific code */
+    GENERIC: 'ERR_GENERIC',
+};

package/dist/core/context.js

@@ -26,7 +26,7 @@ export class GpuContext {
     }
     static async #create() {
         if (typeof navigator === 'undefined' || !('gpu' in navigator) || !navigator.gpu) {
-            throw new WebGPUUnavailableError('navigator.gpu 不存在');
+            throw new WebGPUUnavailableError('navigator.gpu is not available');
         }
         const adapter = await navigator.gpu.requestAdapter({ powerPreference: 'high-performance' });
         if (!adapter)

package/dist/core/errors.d.ts

@@ -1,20 +1,32 @@
-/** 错误体系:所有错误说人话,给出定位与修复建议(章程原则 3)。 */
+import { type ErrorCode } from './codes.ts';
+/**
+ * Error hierarchy for wgpu-kit. All errors extend WgpuKitError and carry a
+ * stable machine-readable `code` for programmatic handling.
+ */
 export declare class WgpuKitError extends Error {
-    constructor(message: string);
+    /** Stable error code, e.g. 'ERR_WGPU_UNAVAILABLE' — safe to switch on. */
+    readonly code: ErrorCode;
+    constructor(code: ErrorCode, message: string);
 }
-/** 环境无 WebGPU / 拿不到 adapter。 */
+/** WebGPU is unavailable or the adapter could not be acquired. */
 export declare class WebGPUUnavailableError extends WgpuKitError {
     constructor(reason: string);
 }
-/** WGSL 编译错误,行号已映射回用户代码。 */
+/** WGSL compilation failed. Line numbers are mapped back to user code. */
 export declare class CompileError extends WgpuKitError {
     constructor(kernelName: string, messages: readonly {
         line: number;
         msg: string;
     }[], userCodeOffset: number);
 }
-/** 调用方使用不当(缺资源/类型不匹配/长度不一致等)。 */
+/** Caller passed an invalid argument (missing resource, type mismatch, bad length, etc.). */
 export declare class UsageError extends WgpuKitError {
+    constructor(code: ErrorCode, message: string);
 }
-/** 创建 compute 管线并用 pushErrorScope 捕获异步校验错误(超限等),把"黑屏刷屏"变成显式报错 */
+/** Compute pipeline creation failed validation (e.g. too many storage buffers). */
+export declare class PipelineError extends WgpuKitError {
+    constructor(label: string, detail: string);
+}
+export { ERR, type ErrorCode } from './codes.ts';
+/** Create a compute pipeline with pushErrorScope to surface async validation errors. */
 export declare function createComputePipelineChecked(device: GPUDevice, module: GPUShaderModule, label: string, entryPoint?: string): Promise<GPUComputePipeline>;

package/dist/core/errors.js

@@ -1,42 +1,57 @@
-/** 错误体系:所有错误说人话,给出定位与修复建议(章程原则 3)。 */
+import { ERR } from "./codes.js";
+/**
+ * Error hierarchy for wgpu-kit. All errors extend WgpuKitError and carry a
+ * stable machine-readable `code` for programmatic handling.
+ */
 export class WgpuKitError extends Error {
-    constructor(message) {
+    /** Stable error code, e.g. 'ERR_WGPU_UNAVAILABLE' — safe to switch on. */
+    code;
+    constructor(code, message) {
         super(message);
         this.name = new.target.name;
+        this.code = code;
     }
 }
-/** 环境无 WebGPU / 拿不到 adapter。 */
+/** WebGPU is unavailable or the adapter could not be acquired. */
 export class WebGPUUnavailableError extends WgpuKitError {
     constructor(reason) {
-        super(`当前环境不可用 WebGPU: ${reason}\n` +
-            '  排查:① 浏览器需 Chrome/Edge 113+ 或 Safari 18+;② 无头环境需开启 WebGPU;③ 检查 GPU 驱动与硬件加速设置。\n' +
-            '  可用 navigator.gpu 是否存在快速判断。');
+        super(ERR.WGPU_UNAVAILABLE, `WebGPU is unavailable: ${reason}\n` +
+            '  Check: 1) Use Chrome/Edge 113+ or Safari 18+. 2) Enable WebGPU in headless mode. 3) Verify GPU drivers and hardware acceleration.');
     }
 }
-/** WGSL 编译错误,行号已映射回用户代码。 */
+/** WGSL compilation failed. Line numbers are mapped back to user code. */
 export class CompileError extends WgpuKitError {
     constructor(kernelName, messages, userCodeOffset) {
         const mapped = messages
             .map((m) => {
             const userLine = m.line - userCodeOffset;
-            const where = userLine > 0 ? `用户代码第 ${userLine} 行` : `生成代码第 ${m.line} 行(库的问题,欢迎报 issue)`;
+            const where = userLine > 0 ? `your code, line ${userLine}` : `generated code, line ${m.line} (library issue — please file an issue)`;
             return `  ${where}: ${m.msg}`;
         })
             .join('\n');
-        super(`kernel "${kernelName}" WGSL 编译失败:\n${mapped}`);
+        super(ERR.COMPILE, `kernel "${kernelName}" WGSL compilation failed:\n${mapped}`);
     }
 }
-/** 调用方使用不当(缺资源/类型不匹配/长度不一致等)。 */
+/** Caller passed an invalid argument (missing resource, type mismatch, bad length, etc.). */
 export class UsageError extends WgpuKitError {
+    constructor(code, message) {
+        super(code, message);
+    }
+}
+/** Compute pipeline creation failed validation (e.g. too many storage buffers). */
+export class PipelineError extends WgpuKitError {
+    constructor(label, detail) {
+        super(ERR.GENERIC, `compute pipeline "${label}" creation failed: ${detail}`);
+    }
 }
-/** 创建 compute 管线并用 pushErrorScope 捕获异步校验错误(超限等),把"黑屏刷屏"变成显式报错 */
+export { ERR } from "./codes.js";
+/** Create a compute pipeline with pushErrorScope to surface async validation errors. */
 export async function createComputePipelineChecked(device, module, label, entryPoint = 'main') {
     device.pushErrorScope('validation');
     const pipeline = device.createComputePipeline({ layout: 'auto', compute: { module, entryPoint } });
     const err = await device.popErrorScope();
     if (err) {
-        throw new WgpuKitError(`compute 管线 "${label}" 创建失败: ${err.message}
-  常见原因:storage buffer 数超过每阶段上限(可向本库提 issue 申请 limits 支持)`);
+        throw new PipelineError(label, err.message);
     }
     return pipeline;
 }

package/dist/core/kernel.js

@@ -1,7 +1,7 @@
 import { planUniform, packUniformInto, TYPES } from "./layout.js";
 import { GpuContext } from "./context.js";
 import { Buffer } from "./buffer.js";
-import { CompileError, UsageError } from "./errors.js";
+import { CompileError, ERR, UsageError } from "./errors.js";
 const RESERVED = new Set(['count']);
 /** GPUBuffer 的稳定数字身份(WeakMap 分配,用于 bind group 缓存键) */
 let nextBufferId = 0;
@@ -19,24 +19,24 @@ export function generateElementKernel(spec) {
     const name = spec.name ?? 'kernel';
     const workgroupSize = spec.workgroupSize ?? 64;
     if (!Number.isInteger(workgroupSize) || workgroupSize < 1 || workgroupSize > 512) {
-        throw new UsageError(`workgroupSize 必须在 1..512,收到: ${String(workgroupSize)}`);
+        throw new UsageError(ERR.WORKGROUP_SIZE, `workgroupSize must be in 1..512, got: ${String(workgroupSize)}`);
     }
     const state = Object.entries(spec.state ?? {});
     const inputs = Object.entries(spec.inputs ?? {});
     const uniforms = Object.entries(spec.uniforms ?? {});
     if (state.length + inputs.length === 0) {
-        throw new UsageError(`elementKernel "${name}" 至少需要一个 state 或 inputs 字段`);
+        throw new UsageError(ERR.RESOURCE_MISSING, `elementKernel "${name}" requires at least one state or inputs field`);
     }
     for (const [uName] of uniforms) {
         if (RESERVED.has(uName))
-            throw new UsageError(`uniform 名 "${uName}" 是保留名(count 由库自动注入)`);
+            throw new UsageError(ERR.USAGE, `uniform name "${uName}" is reserved (count is auto-injected by the library)`);
     }
     const seen = new Set([...state, ...inputs, ...uniforms].map(([n]) => n));
     if (seen.size !== state.length + inputs.length + uniforms.length) {
-        throw new UsageError(`elementKernel "${name}" 的 state/inputs/uniforms 存在重名字段`);
+        throw new UsageError(ERR.USAGE, `elementKernel "${name}" has duplicate field names across state/inputs/uniforms`);
     }
     if (typeof spec.code !== 'string' || spec.code.trim().length === 0) {
-        throw new UsageError(`elementKernel "${name}" 缺少 code(用户 WGSL 函数)`);
+        throw new UsageError(ERR.USAGE, `elementKernel "${name}" is missing code (user WGSL function)`);
     }
     const uniformEntries = [...uniforms, ['count', 'u32']];
     const uniformLayout = planUniform(uniformEntries);
@@ -143,17 +143,17 @@ export function elementKernel(spec) {
                 const f = orderedFields[i];
                 const buf = resources[f.key];
                 if (!buf)
-                    throw new UsageError(`kernel "${normalized.name}".run 缺少资源 "${f.key}"`);
+                    throw new UsageError(ERR.RESOURCE_MISSING, `kernel "${normalized.name}".run is missing resource "${f.key}"`);
                 const want = expectedKinds.get(f.key);
                 if (buf.kind !== want) {
-                    throw new UsageError(`资源 "${f.key}" 类型不匹配: 需要 ${want},收到 ${buf.kind}`);
+                    throw new UsageError(ERR.RESOURCE_TYPE, `Resource "${f.key}" type mismatch: expected ${want}, got ${buf.kind}`);
                 }
                 if (count === -1) {
                     count = buf.length;
                     firstKey = f.key;
                 }
                 else if (buf.length !== count) {
-                    throw new UsageError(`资源 "${f.key}" 长度 ${buf.length} 与 "${firstKey}" 的 ${count} 不一致`);
+                    throw new UsageError(ERR.RESOURCE_LENGTH, `Resource "${f.key}" length ${buf.length} does not match "${firstKey}" length ${count}`);
                 }
                 ordered.push(buf);
             }
@@ -171,12 +171,15 @@ export function elementKernel(spec) {
             let cacheKey = 0;
             for (let i = 0; i < ordered.length; i++)
                 cacheKey = (cacheKey * 31 + bufId(ordered[i].gpuBuffer)) | 0;
-            let bg = bindGroupCache.get(cacheKey);
+            const ids = ordered.map((b) => bufId(b.gpuBuffer));
+            const cached = bindGroupCache.get(cacheKey);
+            const identityMatch = cached && cached.ids.length === ids.length && cached.ids.every((id, idx) => id === ids[idx]);
+            let bg = identityMatch ? cached.bg : undefined;
             if (!bg) {
                 const entries = [{ binding: 0, resource: { buffer: uniformBuffer } }];
                 ordered.forEach((buffer, i) => entries.push({ binding: i + 1, resource: { buffer: buffer.gpuBuffer } }));
                 bg = device.createBindGroup({ layout: pipeline.getBindGroupLayout(0), entries });
-                bindGroupCache.set(cacheKey, bg);
+                bindGroupCache.set(cacheKey, { bg, ids });
             }
             // —— 编码提交 ——
             const enc = device.createCommandEncoder();

package/dist/core/layout.js

@@ -1,3 +1,4 @@
+import { ERR, UsageError } from "./errors.js";
 export const TYPES = {
     f32: { size: 4, stride: 4, align: 4, comps: 1, typed: 'Float32Array', wgsl: 'f32' },
     i32: { size: 4, stride: 4, align: 4, comps: 1, typed: 'Int32Array', wgsl: 'i32' },
@@ -38,13 +39,13 @@ export function packUniform(layout, values) {
     for (const f of layout.fields) {
         const pack = PACKERS[f.kind];
         if (!pack) {
-            throw new Error(`uniform 字段 ${f.name} 的类型 ${f.kind} 暂不支持(当前仅支持标量)`);
+            throw new UsageError(ERR.UNIFORM_UNSUPPORTED, `Uniform field "${f.name}" has unsupported type "${f.kind}". Only scalars are currently supported.`);
         }
         const v = values[f.name];
         if (v === undefined)
-            throw new Error(`缺少 uniform 值: ${f.name}`);
+            throw new UsageError(ERR.UNIFORM_FIELD, `Missing uniform value for "${f.name}"`);
         if (typeof v !== 'number' || !Number.isFinite(v)) {
-            throw new Error(`uniform 值 ${f.name} 必须是有限数字,收到: ${String(v)}`);
+            throw new UsageError(ERR.UNIFORM_FIELD, `Uniform value for "${f.name}" must be a finite number, got: ${String(v)}`);
         }
         pack(view, f.offset, v);
     }
@@ -56,13 +57,13 @@ export function packUniformInto(target, layout, values) {
     for (const f of layout.fields) {
         const pack = PACKERS[f.kind];
         if (!pack) {
-            throw new Error(`uniform 字段 ${f.name} 的类型 ${f.kind} 暂不支持(当前仅支持标量)`);
+            throw new UsageError(ERR.UNIFORM_UNSUPPORTED, `Uniform field "${f.name}" has unsupported type "${f.kind}". Only scalars are currently supported.`);
         }
         const v = values[f.name];
         if (v === undefined)
-            throw new Error(`缺少 uniform 值: ${f.name}`);
+            throw new UsageError(ERR.UNIFORM_FIELD, `Missing uniform value for "${f.name}"`);
         if (typeof v !== 'number' || !Number.isFinite(v)) {
-            throw new Error(`uniform 值 ${f.name} 必须是有限数字,收到: ${String(v)}`);
+            throw new UsageError(ERR.UNIFORM_FIELD, `Uniform value for "${f.name}" must be a finite number, got: ${String(v)}`);
         }
         pack(view, f.offset, v);
     }

package/dist/core/pingpong.js

@@ -20,7 +20,7 @@ export class PingPong {
     static async create(kinds, length) {
         const names = Object.keys(kinds);
         if (names.length === 0)
-            throw new Error('PingPong 至少需要一个字段');
+            throw new Error('PingPong requires at least one field');
         const make = async () => {
             const side = {};
             for (const name of names)

package/dist/core/raw.js

@@ -1,13 +1,13 @@
 import { GpuContext } from "./context.js";
-import { CompileError, UsageError } from "./errors.js";
+import { CompileError, ERR, UsageError } from "./errors.js";
 export function rawKernel(code, entryPoint = 'main', label = 'rawKernel') {
     if (typeof code !== 'string' || code.trim().length === 0)
-        throw new UsageError('rawKernel 需要 WGSL 代码');
+        throw new UsageError(ERR.USAGE, 'rawKernel requires WGSL code');
     let pipelinePromise = null;
     return {
         async run(entries, workgroups) {
             if (!Number.isInteger(workgroups) || workgroups < 1) {
-                throw new UsageError(`rawKernel.run 的 workgroups 必须是正整数,收到 ${String(workgroups)}`);
+                throw new UsageError(ERR.USAGE, `rawKernel.run workgroups must be a positive integer, got ${String(workgroups)}`);
             }
             const ctx = await GpuContext.get();
             if (!pipelinePromise) {

package/dist/media.js

@@ -24,14 +24,14 @@ export class CanvasRecorder {
     constructor() {
         const mime = pickMime();
         if (!mime)
-            throw new Error('当前环境不支持 MediaRecorder 录制(无可用编码)');
+            throw new Error('MediaRecorder is not supported in this environment');
         this.#mime = mime;
     }
     get mimeType() { return this.#mime; }
     get recording() { return this.#recorder?.state === 'recording'; }
     start(canvas, videoBitsPerSecond = 12_000_000) {
         if (this.#recorder)
-            throw new Error('已在录制中');
+            throw new Error('Recording already in progress');
         const stream = canvas.captureStream(60);
         this.#chunks = [];
         this.#recorder = new MediaRecorder(stream, { mimeType: this.#mime, videoBitsPerSecond });
@@ -51,7 +51,7 @@ export class CanvasRecorder {
                 const blob = new Blob(this.#chunks, { type: this.#mime });
                 this.#recorder = null;
                 if (blob.size === 0) {
-                    err(new Error(`录制产物为空(${this.#mime});编码器可能不可用,换浏览器或网络前重试`));
+                    err(new Error(`Recording produced 0 bytes (${this.#mime}); encoder may be unavailable`));
                     return;
                 }
                 ok({ blob, mimeType: this.#mime, seconds: (performance.now() - this.#startedAt) / 1000, bytes: blob.size });

package/dist/observe.js

@@ -3,7 +3,7 @@
  * —— 评审指出的"最大产品级缺口":GPGPU 库却看不到"这帧 GPU 花了多少"。
  */
 import { GpuContext } from "./core/context.js";
-import { UsageError } from "./core/errors.js";
+import { ERR, UsageError } from "./core/errors.js";
 /** 时间戳查询封装:测量一段 GPU 工作的真实耗时(毫秒)。
  *  Chrome/Edge 支持 timestamp-query;不支持的浏览器 reject。 */
 export async function timeGpu(fn) {
@@ -11,7 +11,7 @@ export async function timeGpu(fn) {
     const device = ctx.device;
     const featureOk = device.features.has('timestamp-query');
     if (!featureOk)
-        throw new UsageError('timestamp-query 在当前设备不可用(需 Chrome/Edge + 支持时间戳的 GPU)');
+        throw new UsageError(ERR.TIMESTAMP_UNSUPPORTED, 'timestamp-query is not supported on this device (requires Chrome/Edge + a GPU with timestamp support)');
     const QUERY_POOL = 2;
     const querySet = device.createQuerySet({ type: 'timestamp', count: QUERY_POOL });
     const resolveBuf = device.createBuffer({

package/dist/packs/grid/index.d.ts

@@ -0,0 +1,39 @@
+import { Buffer } from '../../core/buffer.ts';
+/**
+ * NeighborGrid —— 通用空间邻域加速(计数排序 spatial hash)。
+ *
+ * 从粒子包的 grid 实现中提取的通用能力:任意"每帧需要查邻居"的模拟
+ * (流体 SPH / boids / 碰撞 / 聚类)都能用,实测 8.5× 于暴力解、近似 O(N)。
+ *
+ * 用法:
+ *   const grid = await NeighborGrid.create({ count, worldHalf, cellSize });
+ *   // 每帧:先 update(按位置建格),再让你的力 kernel 读 cellStart/cellFill/order
+ *   grid.update(posBuffer);
+ *   // 你的 kernel 通过 order[k] 解引用邻居(或直接用 grid.sortedPos 若启用了 payload)
+ *
+ * 设计说明:三个 build pass 在同一个 encoder 内提交(实测 pass 边界保证可见性);
+ * 粒子包保留其含 payload 排序的专用高性能变体,本包是无 payload 的通用版。
+ */
+export interface NeighborGridConfig {
+    /** 粒子/实体数量 */
+    count: number;
+    /** 世界半宽(世界 = [-worldHalf, worldHalf]) */
+    worldHalf: number;
+    /** 格子边长(通常 = 交互半径,使邻域恰为 3×3 格) */
+    cellSize: number;
+    workgroupSize?: number;
+}
+export interface NeighborGrid {
+    readonly gridSize: number;
+    readonly cells: number;
+    /** 格内首个有序槽位 */
+    cellStart: Buffer;
+    /** 格内结束槽位(原子填充) */
+    cellFill: Buffer;
+    /** 按格子序排列的实体下标(order[slot] = 实体 i) */
+    order: Buffer;
+    /** 建格:counts → scan → scatter(三 pass,一 encoder,内部提交) */
+    update(pos: Buffer): void;
+    destroy(): void;
+}
+export declare function createNeighborGrid(config: NeighborGridConfig): Promise<NeighborGrid>;