wgpu-kit 1.1.0 → 1.1.2

package/dist/packs/fields/index.js

@@ -2,6 +2,8 @@ import { GpuContext } from "../../core/context.js";
 import { Buffer } from "../../core/buffer.js";
 import { PingPong } from "../../core/pingpong.js";
 import { CompileError } from "../../core/errors.js";
+import { createShaderModuleChecked } from "../../core/shader.js";
+import { definePack } from "../../core/pack.js";
 import { MapRenderer } from "../life/map.js";
 import { mulberry32 } from "../particles/presets.js";
 const FIELD_FNS = {
@@ -79,9 +81,8 @@ export async function flow(config = {}) {
     device.queue.writeBuffer(diffuseUniform, 0, new Uint32Array([mapSize, mapSize]));
     device.queue.writeBuffer(diffuseUniform, 8, new Float32Array([1 - decay, 0]));
     const compile = async (code, label) => {
-        const m = device.createShaderModule({ code, label });
-        const info = await m.getCompilationInfo();
-        const errors = info.messages.filter((x) => x.type === 'error');
+        const { module: m, messages } = await createShaderModuleChecked(device, code, label);
+        const errors = messages.filter((x) => x.type === 'error');
         if (errors.length > 0)
             throw new CompileError(label, errors.map((x) => ({ line: x.lineNum, msg: x.message })), 0);
         return m;
@@ -151,6 +152,23 @@ export async function flow(config = {}) {
         },
         stats() { return { fps: lastFps }; },
         async sampleTrail() { return (await trail.current.t.read()); },
+        async probe() {
+            const t = (await trail.current.t.read());
+            let finite = true;
+            let maxv = 0;
+            let sum = 0;
+            for (let i = 0; i < t.length; i++) {
+                const v = t[i];
+                if (!Number.isFinite(v)) {
+                    finite = false;
+                    break;
+                }
+                if (v > maxv)
+                    maxv = v;
+                sum += v;
+            }
+            return { finite, trailMax: maxv, trailMean: sum / Math.max(t.length, 1), frames: frame };
+        },
         destroy() {
             posBuf.destroy();
             trail.destroy();
@@ -159,6 +177,12 @@ export async function flow(config = {}) {
         },
     };
 }
+/** fields 包的平台注册形态:第三方包与它长得一模一样(见 docs "Writing a pack") */
+export const fieldsPack = definePack({
+    name: 'fields',
+    description: 'Vector-field advection trails (vortex / curl / twin)',
+    create: (config) => flow(config ?? {}),
+});
 function advectWgsl(fieldFn, mapSize) {
     return /* wgsl */ `
 struct Params {

package/dist/packs/grid/index.js

@@ -1,15 +1,16 @@
 import { GpuContext } from "../../core/context.js";
 import { Buffer } from "../../core/buffer.js";
 import { CompileError } from "../../core/errors.js";
+import { createShaderModuleChecked } from "../../core/shader.js";
 const WG = 64;
 const SCAN = 256;
 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();
@@ -34,9 +35,8 @@ export async function createNeighborGrid(config) {
     const cellFill = await Buffer.create('u32', cells);
     const order = await Buffer.create('u32', count);
     cellCount.write(new Uint32Array(cells));
-    const module = device.createShaderModule({ code: gridWgsl(), label: 'ngrid' });
-    const info = await module.getCompilationInfo();
-    const errors = info.messages.filter((m) => m.type === 'error');
+    const { module, messages } = await createShaderModuleChecked(device, gridWgsl(), 'ngrid');
+    const errors = messages.filter((m) => m.type === 'error');
     if (errors.length > 0)
         throw new CompileError('ngrid', errors.map((m) => ({ line: m.lineNum, msg: m.message })), 0);
     const pCounts = device.createComputePipeline({ layout: 'auto', compute: { module, entryPoint: 'main_counts' } });

package/dist/packs/image/index.js

@@ -1,10 +1,11 @@
 import { GpuContext } from "../../core/context.js";
 import { CompileError } from "../../core/errors.js";
+import { createShaderModuleChecked } from "../../core/shader.js";
 const OPS = ['grayscale', 'invert', 'edge', 'blur', 'sharpen', 'brightness', 'contrast'];
 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();
@@ -34,9 +35,8 @@ export async function applyImage(source, target, ops) {
         });
         return t;
     };
-    const module = device.createShaderModule({ code: shader(), label: 'image-filters' });
-    const info = await module.getCompilationInfo();
-    const errors = info.messages.filter((m) => m.type === 'error');
+    const { module, messages } = await createShaderModuleChecked(device, shader(), 'image-filters');
+    const errors = messages.filter((m) => m.type === 'error');
     if (errors.length > 0)
         throw new CompileError('image-filters', errors.map((m) => ({ line: m.lineNum, msg: m.message })), 0);
     const pipeline = device.createRenderPipeline({

package/dist/packs/life/boids.js

@@ -2,6 +2,7 @@ import { GpuContext } from "../../core/context.js";
 import { Buffer } from "../../core/buffer.js";
 import { PingPong } from "../../core/pingpong.js";
 import { CompileError } from "../../core/errors.js";
+import { createShaderModuleChecked } from "../../core/shader.js";
 import { createNeighborGrid } from "../grid/index.js";
 import { mulberry32 } from "../particles/presets.js";
 const WG = 64;
@@ -47,9 +48,8 @@ export async function boids(config = {}) {
         device.queue.writeBuffer(uniform, 0, b);
     };
     writeUniform();
-    const module = device.createShaderModule({ code: boidsWgsl(size), label: 'boids' });
-    const info = await module.getCompilationInfo();
-    const errors = info.messages.filter((m) => m.type === 'error');
+    const { module, messages } = await createShaderModuleChecked(device, boidsWgsl(size), 'boids');
+    const errors = messages.filter((m) => m.type === 'error');
     if (errors.length > 0)
         throw new CompileError('boids', errors.map((m) => ({ line: m.lineNum, msg: m.message })), 0);
     const neighborGrid = await createNeighborGrid({ count: N, worldHalf: 1.0, cellSize: perception });

package/dist/packs/life/physarum.js

@@ -2,6 +2,7 @@ import { GpuContext } from "../../core/context.js";
 import { Buffer } from "../../core/buffer.js";
 import { PingPong } from "../../core/pingpong.js";
 import { CompileError } from "../../core/errors.js";
+import { createShaderModuleChecked } from "../../core/shader.js";
 import { MapRenderer } from "./map.js";
 import { mulberry32 } from "../particles/presets.js";
 const AWG = 32; // count(u32) pad(u32) + sensorAngle, sensorDist, turnAngle, step, deposit, worldHalf (f32×6) = 32
@@ -51,9 +52,8 @@ export async function physarum(config = {}) {
     // decay 写进 diffuse kernel 的第二个 uniform?并成 16B:w,h,decayFrac,pad
     device.queue.writeBuffer(diffuseUniform, 8, new Float32Array([1 - decay, 0]));
     const compile = async (code, label) => {
-        const m = device.createShaderModule({ code, label });
-        const info = await m.getCompilationInfo();
-        const errors = info.messages.filter((x) => x.type === 'error');
+        const { module: m, messages } = await createShaderModuleChecked(device, code, label);
+        const errors = messages.filter((x) => x.type === 'error');
         if (errors.length > 0)
             throw new CompileError(label, errors.map((x) => ({ line: x.lineNum, msg: x.message })), 0);
         return m;

package/dist/packs/life/turing.js

@@ -2,6 +2,7 @@ import { GpuContext } from "../../core/context.js";
 import { Buffer } from "../../core/buffer.js";
 import { PingPong } from "../../core/pingpong.js";
 import { CompileError } from "../../core/errors.js";
+import { createShaderModuleChecked } from "../../core/shader.js";
 import { MapRenderer } from "./map.js";
 import { mulberry32 } from "../particles/presets.js";
 const PRESETS = {
@@ -58,9 +59,8 @@ export async function turing(config = {}) {
         device.queue.writeBuffer(uniform, 0, buf);
     };
     writeUniform();
-    const module = device.createShaderModule({ code: updateWgsl(), label: 'turing-update' });
-    const info = await module.getCompilationInfo();
-    const errors = info.messages.filter((m) => m.type === 'error');
+    const { module, messages } = await createShaderModuleChecked(device, updateWgsl(), 'turing-update');
+    const errors = messages.filter((m) => m.type === 'error');
     if (errors.length > 0)
         throw new CompileError('turing-update', errors.map((m) => ({ line: m.lineNum, msg: m.message })), 0);
     const pipeline = device.createComputePipeline({ layout: 'auto', compute: { module, entryPoint: 'main' } });

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

@@ -2,6 +2,7 @@ import { GpuContext } from "../../core/context.js";
 import { Buffer } from "../../core/buffer.js";
 import { PingPong } from "../../core/pingpong.js";
 import { CompileError, createComputePipelineChecked } from "../../core/errors.js";
+import { createShaderModuleChecked } from "../../core/shader.js";
 import { resolveConfig } from "./config.js";
 import { mulberry32, resolveMatrix, hashSeed } from "./presets.js";
 import { simWgsl, WORKGROUP } from "./wgsl.js";
@@ -37,8 +38,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);
@@ -60,9 +62,8 @@ export async function particles(config = {}) {
     writeUniform(cfg.dt);
     // —— 着色器模块(编译错误 → 行号映射) ——
     const compile = async (code, label) => {
-        const module = device.createShaderModule({ code, label });
-        const info = await module.getCompilationInfo();
-        const errors = info.messages.filter((m) => m.type === 'error');
+        const { module, messages } = await createShaderModuleChecked(device, code, label);
+        const errors = messages.filter((m) => m.type === 'error');
         if (errors.length > 0)
             throw new CompileError(label, errors.map((m) => ({ line: m.lineNum, msg: m.message })), 0);
         return module;
@@ -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.2",
   "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
+    }
+  }
 }