wgpu-kit 1.1.0 → 1.1.1

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.js

@@ -7,9 +7,9 @@ const USIZE = 32;
 export async function createNeighborGrid(config) {
     const { count, worldHalf, cellSize, workgroupSize = WG } = config;
     if (!Number.isInteger(count) || count <= 0)
-        throw new Error(`count 必须是正整数,收到 ${String(count)}`);
+        throw new Error(`count must be a positive integer, got ${String(count)}`);
     if (!(cellSize > 0))
-        throw new Error(`cellSize 必须为正,收到 ${String(cellSize)}`);
+        throw new Error(`cellSize must be positive, got ${String(cellSize)}`);
     const gridSize = Math.max(1, Math.ceil((2 * worldHalf) / cellSize));
     const cells = gridSize * gridSize;
     const ctx = await GpuContext.get();

package/dist/packs/image/index.js

@@ -4,7 +4,7 @@ const OPS = ['grayscale', 'invert', 'edge', 'blur', 'sharpen', 'brightness', 'co
 const OP_IDS = { grayscale: 0, invert: 1, edge: 2, blur: 3, sharpen: 4, brightness: 5, contrast: 6 };
 export async function applyImage(source, target, ops) {
     if (ops.length === 0)
-        throw new Error('applyImage 需要至少一个算子');
+        throw new Error('applyImage requires at least one operator');
     const width = 'naturalWidth' in source ? source.naturalWidth : source.width;
     const height = 'naturalHeight' in source ? source.naturalHeight : source.height;
     const ctx = await GpuContext.get();

package/dist/packs/particles/config.js

@@ -1,17 +1,17 @@
 import { resolveMatrix, hashSeed } from "./presets.js";
-import { UsageError } from "../../core/errors.js";
+import { ERR, UsageError } from "../../core/errors.js";
 const MODES = ['n2', 'tiled', 'grid'];
 export function resolveConfig(config = {}) {
     const { count = 8192, forces = 'cells', mode = 'grid', // 基准数据驱动:v0.4 起 grid 全面优于 tiled(0.54ms vs 3.62ms @16k),见 benchmarks.md
     color = 'species', bounds = 'wrap', seed = 'wgpu-kit', rMax = 0.12, beta = 0.3, forceFactor = 10, frictionHalfLife = 0.04, dt = 0.02, pointSize = 0.004, maxNeighbors = 8100, } = config;
     if (!Number.isInteger(count) || count <= 0 || count > 1_000_000) {
-        throw new UsageError(`count 必须是 1..1_000_000 的整数,收到: ${String(count)}`);
+        throw new UsageError(ERR.USAGE, `count must be an integer in 1..1_000_000, got: ${String(count)}`);
     }
     if (!MODES.includes(mode)) {
-        throw new UsageError(`mode 必须是 ${MODES.join(' | ')},收到: "${String(mode)}"`);
+        throw new UsageError(ERR.USAGE, `mode must be one of ${MODES.join(" | ")}, got: "${String(mode)}"`);
     }
     if (mode === 'n2' && count > 32_000) {
-        throw new UsageError(`mode='n2' 建议 count ≤ 20000(当前 ${count});大规模请用 mode='tiled' 或 'grid'`);
+        throw new UsageError(ERR.USAGE, `mode='n2' is recommended for count <= 20000 (got ${count}); use 'tiled' or 'grid' for larger counts`);
     }
     const seedStr = String(seed);
     return {

package/dist/packs/particles/grid.js

@@ -40,12 +40,13 @@ fn main(@builtin(global_invocation_id) gid: vec3u) {
 `;
 }
 export function gridScanWgsl() {
-    // 两级扫描,三 pass 结构(pass 边界保证跨 workgroup 可见性):
-    //   A main_scan_blocks : 每 workgroup 对自己的 256-cell 块做排他扫描 → cellFill(临时),
-    //                        块总和写入 blockSums[wid]
-    //   B main_scan_bases  : 单 workgroup 对 blockSums 做排他扫描 → 各块基址
-    //   C main_scan_apply  : start = cellFill + base;fill = start + count;counts 归零
-    // 支持至 65536 cell(gridSize ≤ 256);更大的世界需要多 pass 分块升级(路线图)。
+    // 单 workgroup 分块扫描:256-cell 块循环推进,块内 Hillis-Steele,块间用
+    // workgroup 级 carry 串接。此前版本按多 workgroup 分两级写,但 dispatch(1)
+    // 只有 block 0 在跑 —— 256 格之外 cellStart 永远是 0、cellCount 永不清零,
+    // 对应粒子受力恒零被摩擦冻住(屏幕上出现水平"冻结带")。改成单 workgroup
+    // 循环后 barrier 是合法同步,正确性不依赖任何跨 workgroup 时序;
+    // cell 上限 65536 = 256 块,每块一轮微秒级,性能无虞。顺带把 cellCount
+    // 归零给下一帧。
     return /* wgsl */ `
 struct Params {
   count: u32, _pad0: u32,
@@ -56,70 +57,50 @@ struct Params {
 @group(0) @binding(0) var<uniform> params: Params;
 @group(0) @binding(1) var<storage, read_write> cellCount: array<atomic<u32>>;
 @group(0) @binding(2) var<storage, read_write> cellStart: array<u32>;
-@group(0) @binding(3) var<storage, read_write> cellFill: array<atomic<u32>>;
-@group(0) @binding(4) var<storage, read_write> blockSums: array<atomic<u32>>;
+@group(0) @binding(3) var<storage, read_write> cellFill: array<u32>;
 
 var<workgroup> partial: array<u32, ${SCAN_WORKGROUP}>;
+var<workgroup> carry: u32;
 
-// Pass A:块内排他扫描。cellFill[c] = 块内排他前缀(临时);blockSums[wid] = 块总和
 @compute @workgroup_size(${SCAN_WORKGROUP})
-fn main_scan_blocks(@builtin(local_invocation_id) lid: vec3u, @builtin(workgroup_id) wid: vec3u) {
+fn main(@builtin(local_invocation_id) lid: vec3u) {
   let tid = lid.x;
   let wg = ${SCAN_WORKGROUP}u;
-  let base = wid.x * wg;
   let cells = params.cells;
-  let v0 = select(0u, atomicLoad(&cellCount[base + tid]), base + tid < cells);
-  partial[tid] = v0;
+  let numChunks = (cells + wg - 1u) / wg;
+  if (tid == 0u) { carry = 0u; }
   workgroupBarrier();
-  var offset = 1u;
-  loop {
-    if (offset >= wg) { break; }
-    var v = 0u;
-    if (tid >= offset) { v = partial[tid - offset]; }
-    workgroupBarrier();
-    if (tid >= offset) { partial[tid] = partial[tid] + v; }
+  for (var ch = 0u; ch < numChunks; ch++) {
+    let idx = ch * wg + tid;
+    let inRange = idx < cells;
+    let v0 = select(0u, atomicLoad(&cellCount[idx]), inRange);
+    partial[tid] = v0;
     workgroupBarrier();
-    offset = offset << 1u;
-  }
-  // 含前缀 → 排他:excl = incl - own
-  if (base + tid < cells) {
-    atomicStore(&cellFill[base + tid], partial[tid] - v0);
-  }
-  if (tid == 0u) { atomicStore(&blockSums[wid.x], partial[wg - 1u]); }
-}
-
-// Pass B:单 workgroup 对 blockSums 做排他扫描 → 各块基址
-@compute @workgroup_size(${SCAN_WORKGROUP})
-fn main_scan_bases(@builtin(local_invocation_id) lid: vec3u) {
-  let tid = lid.x;
-  let nBlocks = ceil(f32(params.cells) / ${SCAN_WORKGROUP}.0);
-  let v0 = select(atomicLoad(&blockSums[tid]), 0u, f32(tid) >= nBlocks);
-  partial[tid] = v0;
-  workgroupBarrier();
-  var offset = 1u;
-  loop {
-    if (offset >= ${SCAN_WORKGROUP}u) { break; }
-    var v = 0u;
-    if (tid >= offset) { v = partial[tid - offset]; }
+    // 块内含前缀(Hillis-Steele)
+    var offset = 1u;
+    loop {
+      if (offset >= wg) { break; }
+      var v = 0u;
+      if (tid >= offset) { v = partial[tid - offset]; }
+      workgroupBarrier();
+      if (tid >= offset) { partial[tid] = partial[tid] + v; }
+      workgroupBarrier();
+      offset = offset << 1u;
+    }
+    // 排他:start = carry + 块内前缀(不含自身);fill 是 scatter 的原子填充
+    // 游标,初始化为段起点(与通用包 NeighborGrid 同语义)——scatter 填完一格
+    // 后 fill 恰好 = start + count,力核读 [start, fill) 才不会多扫下一格的粒子。
+    if (inRange) {
+      let excl = partial[tid] - v0;
+      cellStart[idx] = carry + excl;
+      cellFill[idx] = carry + excl;
+      atomicStore(&cellCount[idx], 0u);
+    }
+    // 所有线程读完 partial/写完 carry 后才能进入下一块
     workgroupBarrier();
-    if (tid >= offset) { partial[tid] = partial[tid] + v; }
+    if (tid == wg - 1u) { carry = carry + partial[wg - 1u]; }
     workgroupBarrier();
-    offset = offset << 1u;
   }
-  atomicStore(&blockSums[tid], partial[tid] - v0);
-}
-
-// Pass C:加块基址 → 最终 start/fill;counts 归零供下一帧
-@compute @workgroup_size(${SCAN_WORKGROUP})
-fn main_scan_apply(@builtin(global_invocation_id) gid: vec3u) {
-  let i = gid.x;
-  if (i >= params.cells) { return; }
-  let block = i / ${SCAN_WORKGROUP}u;
-  let base = atomicLoad(&blockSums[block]);
-  let excl = atomicLoad(&cellFill[i]);
-  cellStart[i] = excl + base;
-  atomicExchange(&cellFill[i], excl + base);
-  atomicStore(&cellCount[i], 0u);
 }
 `;
 }

package/dist/packs/particles/index.js

@@ -37,8 +37,9 @@ export async function particles(config = {}) {
     }
     const phys = { rMax: cfg.rMax, beta: cfg.beta, forceFactor: cfg.forceFactor, frictionHalfLife: cfg.frictionHalfLife, dt: cfg.dt };
     const uniform = device.createBuffer({ size: USIZE, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST, label: 'particles-params' });
-    // grid 尺寸由 rMax 决定(格宽 ≈ rMax → 邻域恰好 3×3 格)
-    const gridSizeOf = (rMax, half = worldHalf) => Math.max(4, Math.ceil((2 * half) / Math.max(rMax, 1e-3)));
+    // grid 尺寸由 rMax 决定(floor 确保格宽 ≥ rMax → 3×3 邻域完整覆盖交互半径;
+    // ceil 会导致格宽 < rMax,3×3 不够覆盖,边界粒子漏配邻居)
+    const gridSizeOf = (rMax, half = worldHalf) => Math.max(4, Math.floor((2 * half) / Math.max(rMax, 1e-3)));
     let gridSize = gridSizeOf(phys.rMax, worldHalf);
     const writeUniform = (dt) => {
         const buf = new ArrayBuffer(USIZE);
@@ -83,7 +84,6 @@ export async function particles(config = {}) {
         g.partial.destroy();
         g.sortedPos.destroy();
         g.sortedSp.destroy();
-        g.blockSums.destroy();
     };
     const buildGrid = async (size) => {
         const cells = size * size;
@@ -97,14 +97,11 @@ export async function particles(config = {}) {
         const mScatter = await compile(gridScatterWgsl(), 'grid-scatter');
         const mForce = await compile(gridForceWgsl(4), 'grid-force');
         const pCounts = await makePipeline(mCounts, 'main', 'grid-counts');
-        const pScanBlocks = await makePipeline(mScan, 'main_scan_blocks', 'grid-scan-blocks');
-        const pScanBases = await makePipeline(mScan, 'main_scan_bases', 'grid-scan-bases');
-        const pScanApply = await makePipeline(mScan, 'main_scan_apply', 'grid-scan-apply');
+        const pScan = await makePipeline(mScan, 'main', 'grid-scan');
         const pScatter = await makePipeline(mScatter, 'main', 'grid-scatter');
         const pForceCell = await makePipeline(mForce, 'main_force_cell', 'grid-force-cell');
         const pForceInt = await makePipeline(mForce, 'main_force_integrate', 'grid-force-integrate');
         const partial = await Buffer.create('vec2f', cfg.count * 9); // (粒子 × 3×3 格) 部分力
-        const blockSums = await Buffer.create('u32', Math.ceil(cells / 256)); // 二级扫描块和
         const sortedPos = await Buffer.create('vec2f', cfg.count); // 按格子序重排的副本(合并访问)
         const sortedSp = await Buffer.create('u32', cfg.count);
         const bgCounts = (readPos) => device.createBindGroup({
@@ -115,34 +112,13 @@ export async function particles(config = {}) {
                 { binding: 2, resource: { buffer: count.gpuBuffer } },
             ],
         });
-        const bgScanBlocks = device.createBindGroup({
-            layout: pScanBlocks.getBindGroupLayout(0),
+        const bgScan = device.createBindGroup({
+            layout: pScan.getBindGroupLayout(0),
             entries: [
                 { binding: 0, resource: { buffer: uniform } },
                 { binding: 1, resource: { buffer: count.gpuBuffer } },
                 { binding: 2, resource: { buffer: start.gpuBuffer } },
                 { binding: 3, resource: { buffer: fill.gpuBuffer } },
-                { binding: 4, resource: { buffer: blockSums.gpuBuffer } },
-            ],
-        });
-        const bgScanBases = device.createBindGroup({
-            layout: pScanBases.getBindGroupLayout(0),
-            entries: [
-                { binding: 0, resource: { buffer: uniform } },
-                { binding: 1, resource: { buffer: count.gpuBuffer } },
-                { binding: 2, resource: { buffer: start.gpuBuffer } },
-                { binding: 3, resource: { buffer: fill.gpuBuffer } },
-                { binding: 4, resource: { buffer: blockSums.gpuBuffer } },
-            ],
-        });
-        const bgScanApply = device.createBindGroup({
-            layout: pScanApply.getBindGroupLayout(0),
-            entries: [
-                { binding: 0, resource: { buffer: uniform } },
-                { binding: 1, resource: { buffer: count.gpuBuffer } },
-                { binding: 2, resource: { buffer: start.gpuBuffer } },
-                { binding: 3, resource: { buffer: fill.gpuBuffer } },
-                { binding: 4, resource: { buffer: blockSums.gpuBuffer } },
             ],
         });
         const bgScatter = (readPos) => device.createBindGroup({
@@ -192,11 +168,10 @@ export async function particles(config = {}) {
         };
         const state = {
             size,
-            cells,
-            count, start, fill, order, partial, sortedPos, sortedSp, blockSums,
-            pCounts, pScanBlocks, pScanBases, pScanApply, pScatter, pForceCell, pForceInt,
+            count, start, fill, order, partial, sortedPos, sortedSp,
+            pCounts, pScan, pScatter, pForceCell, pForceInt,
             bgCountsA: bgCounts(sideA.pos), bgCountsB: bgCounts(sideB.pos),
-            bgScanBlocks, bgScanBases, bgScanApply,
+            bgScan,
             bgScatterA: bgScatter(sideA.pos), bgScatterB: bgScatter(sideB.pos),
             bgForceCellAB: bgForceCell(sideA.pos), bgForceCellBA: bgForceCell(sideB.pos),
             bgIntegrateAB: bgIntegrate(sideA, sideB), bgIntegrateBA: bgIntegrate(sideB, sideA),
@@ -259,28 +234,39 @@ export async function particles(config = {}) {
                 grid.bgForceCellRebuild(sideA.pos);
                 gridBindGroupsDirty = false;
             }
+            const enc = device.createCommandEncoder();
             if (grid) {
-                // 五段各自独立 encoder+submit:WebGPU 同队列按提交序执行,
-                // pass 边界保证跨 workgroup 可见性(单 pass 内多 dispatch 曾实测读到旧数据)
-                const runPass = (pipeline, bg, wgs) => {
-                    const e = device.createCommandEncoder();
-                    const p = e.beginComputePass();
-                    p.setPipeline(pipeline);
-                    p.setBindGroup(0, bg);
-                    p.dispatchWorkgroups(wgs);
-                    p.end();
-                    device.queue.submit([e.finish()]);
-                };
-                const nCellWg = Math.ceil(grid.cells / 256);
-                runPass(grid.pCounts, useAB ? grid.bgCountsA : grid.bgCountsB, Math.ceil(cfg.count / WORKGROUP));
-                runPass(grid.pScanBlocks, grid.bgScanBlocks, nCellWg);
-                runPass(grid.pScanBases, grid.bgScanBases, 1);
-                runPass(grid.pScatter, useAB ? grid.bgScatterA : grid.bgScatterB, Math.ceil(cfg.count / WORKGROUP));
-                runPass(grid.pForceCell, useAB ? grid.bgForceCellAB : grid.bgForceCellBA, Math.ceil((cfg.count * 9) / WORKGROUP));
-                runPass(grid.pForceInt, useAB ? grid.bgIntegrateAB : grid.bgIntegrateBA, Math.ceil(cfg.count / WORKGROUP));
+                // 每个 build 阶段独立 pass:同 pass 内跨 dispatch 的存储可见性规范不保证
+                // (Dawn/Windows 实测出现过旧数据),counts→scan→scatter 是严格串行依赖。
+                // 单 encoder 内 pass 按序执行且天然可见,不增加 submit 次数。
+                const passCounts = enc.beginComputePass();
+                passCounts.setPipeline(grid.pCounts);
+                passCounts.setBindGroup(0, useAB ? grid.bgCountsA : grid.bgCountsB);
+                passCounts.dispatchWorkgroups(Math.ceil(cfg.count / WORKGROUP));
+                passCounts.end();
+                const passScan = enc.beginComputePass();
+                passScan.setPipeline(grid.pScan);
+                passScan.setBindGroup(0, grid.bgScan);
+                passScan.dispatchWorkgroups(1);
+                passScan.end();
+                const passScatter = enc.beginComputePass();
+                passScatter.setPipeline(grid.pScatter);
+                passScatter.setBindGroup(0, useAB ? grid.bgScatterA : grid.bgScatterB);
+                passScatter.dispatchWorkgroups(Math.ceil(cfg.count / WORKGROUP));
+                passScatter.end();
+                const passB = enc.beginComputePass();
+                passB.setPipeline(grid.pForceCell);
+                passB.setBindGroup(0, useAB ? grid.bgForceCellAB : grid.bgForceCellBA);
+                passB.dispatchWorkgroups(Math.ceil((cfg.count * 9) / WORKGROUP));
+                passB.end();
+                const passC = enc.beginComputePass();
+                passC.setPipeline(grid.pForceInt);
+                passC.setBindGroup(0, useAB ? grid.bgIntegrateAB : grid.bgIntegrateBA);
+                passC.dispatchWorkgroups(Math.ceil(cfg.count / WORKGROUP));
+                passC.end();
+                device.queue.submit([enc.finish()]);
             }
             else {
-                const enc = device.createCommandEncoder();
                 const pass = enc.beginComputePass();
                 pass.setPipeline(simPipeline);
                 pass.setBindGroup(0, useAB ? bgAB : bgBA);

package/dist/packs/particles/presets.js

@@ -67,7 +67,7 @@ export function resolveMatrix(forces, seed) {
     if (typeof forces === 'string') {
         const preset = FORCE_PRESETS[forces];
         if (!preset) {
-            throw new Error(`未知力矩阵预设 "${forces}",可用: ${Object.keys(FORCE_PRESETS).join(', ')}, random`);
+            throw new Error(`Unknown force preset "${forces}". Available: ${Object.keys(FORCE_PRESETS).join(", ")}, random`);
         }
         return preset;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wgpu-kit",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Creative-coding GPU toolkit for the browser. 200k-particle physics at 120fps in 5 lines of code. WebGPU compute without the boilerplate.",
   "type": "module",
   "license": "MIT",
@@ -103,5 +103,10 @@
   "bugs": {
     "url": "https://github.com/nanfengw0w/wgpu-kit/issues"
   },
-  "homepage": "https://github.com/nanfengw0w/wgpu-kit#readme"
+  "homepage": "https://github.com/nanfengw0w/wgpu-kit#readme",
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
 }