wgpu-kit 1.0.3 → 1.1.0

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/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>;

package/dist/packs/grid/index.js

@@ -0,0 +1,187 @@
+import { GpuContext } from "../../core/context.js";
+import { Buffer } from "../../core/buffer.js";
+import { CompileError } from "../../core/errors.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)}`);
+    if (!(cellSize > 0))
+        throw new Error(`cellSize 必须为正,收到 ${String(cellSize)}`);
+    const gridSize = Math.max(1, Math.ceil((2 * worldHalf) / cellSize));
+    const cells = gridSize * gridSize;
+    const ctx = await GpuContext.get();
+    const device = ctx.device;
+    const uniform = device.createBuffer({ size: USIZE, usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST, label: 'ngrid-params' });
+    const writeUniform = () => {
+        const b = new ArrayBuffer(USIZE);
+        const v = new DataView(b);
+        v.setUint32(0, count, true);
+        v.setUint32(4, 0, true);
+        v.setFloat32(8, worldHalf, true);
+        v.setUint32(12, gridSize, true);
+        v.setUint32(16, cells, true);
+        v.setUint32(20, 0, true);
+        v.setUint32(24, 0, true);
+        v.setUint32(28, 0, true);
+        device.queue.writeBuffer(uniform, 0, b);
+    };
+    writeUniform();
+    const cellCount = await Buffer.create('u32', cells);
+    const cellStart = await Buffer.create('u32', cells);
+    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');
+    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' } });
+    const pScan = device.createComputePipeline({ layout: 'auto', compute: { module, entryPoint: 'main_scan' } });
+    const pScatter = device.createComputePipeline({ layout: 'auto', compute: { module, entryPoint: 'main_scatter' } });
+    const bgCounts = (pos) => device.createBindGroup({
+        layout: pCounts.getBindGroupLayout(0),
+        entries: [
+            { binding: 0, resource: { buffer: uniform } },
+            { binding: 1, resource: { buffer: pos.gpuBuffer } },
+            { binding: 2, resource: { buffer: cellCount.gpuBuffer } },
+        ],
+    });
+    const bgScan = device.createBindGroup({
+        layout: pScan.getBindGroupLayout(0),
+        entries: [
+            { binding: 0, resource: { buffer: uniform } },
+            { binding: 1, resource: { buffer: cellCount.gpuBuffer } },
+            { binding: 2, resource: { buffer: cellStart.gpuBuffer } },
+            { binding: 3, resource: { buffer: cellFill.gpuBuffer } },
+        ],
+    });
+    const bgScatter = (pos) => device.createBindGroup({
+        layout: pScatter.getBindGroupLayout(0),
+        entries: [
+            { binding: 0, resource: { buffer: uniform } },
+            { binding: 1, resource: { buffer: pos.gpuBuffer } },
+            { binding: 2, resource: { buffer: cellFill.gpuBuffer } },
+            { binding: 3, resource: { buffer: order.gpuBuffer } },
+        ],
+    });
+    return {
+        gridSize,
+        cells,
+        cellStart,
+        cellFill,
+        order,
+        update(pos) {
+            writeUniform();
+            const enc = device.createCommandEncoder();
+            const pass = enc.beginComputePass();
+            // 独立 pass:实测同 pass 连续 dispatch 存在旧数据可见性问题(Dawn/Windows)
+            pass.setPipeline(pCounts);
+            pass.setBindGroup(0, bgCounts(pos));
+            pass.dispatchWorkgroups(Math.ceil(count / WG));
+            pass.end();
+            const pass2 = enc.beginComputePass();
+            pass2.setPipeline(pScan);
+            pass2.setBindGroup(0, bgScan);
+            pass2.dispatchWorkgroups(1);
+            pass2.end();
+            const pass3 = enc.beginComputePass();
+            pass3.setPipeline(pScatter);
+            pass3.setBindGroup(0, bgScatter(pos));
+            pass3.dispatchWorkgroups(Math.ceil(count / WG));
+            pass3.end();
+            device.queue.submit([enc.finish()]);
+        },
+        destroy() {
+            cellCount.destroy();
+            cellStart.destroy();
+            cellFill.destroy();
+            order.destroy();
+            uniform.destroy();
+        },
+    };
+}
+function gridWgsl() {
+    return /* wgsl */ `
+struct Params {
+  count: u32, _pad0: u32,
+  worldHalf: f32, gridSize: u32, cells: u32,
+  _p0: u32, _p1: u32, _p2: u32,
+};
+@group(0) @binding(0) var<uniform> params: Params;
+@group(0) @binding(1) var<storage, read> posIn: array<vec2f>;
+@group(0) @binding(2) var<storage, read_write> cellCount: array<atomic<u32>>;
+@group(0) @binding(3) var<storage, read_write> cellStart: array<u32>;
+@group(0) @binding(4) var<storage, read_write> cellFill: array<atomic<u32>>;
+@group(0) @binding(5) var<storage, read_write> order: array<u32>;
+
+fn cellOf(p: vec2f) -> u32 {
+  let g = i32(params.gridSize);
+  let span = params.worldHalf * 2.0;
+  let cx = clamp(i32(floor((p.x + params.worldHalf) / span * f32(g))), 0, g - 1);
+  let cy = clamp(i32(floor((p.y + params.worldHalf) / span * f32(g))), 0, g - 1);
+  return u32(cy) * u32(g) + u32(cx);
+}
+
+@compute @workgroup_size(${WG})
+fn main_counts(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  if (i >= params.count) { return; }
+  atomicAdd(&cellCount[cellOf(posIn[i])], 1u);
+}
+
+var<workgroup> partial: array<u32, ${SCAN}>;
+@compute @workgroup_size(${SCAN})
+fn main_scan(@builtin(local_invocation_id) lid: vec3u, @builtin(workgroup_id) wid: vec3u) {
+  let tid = lid.x;
+  let cells = params.cells;
+  let wg = ${SCAN}u;
+  let chunks = (cells + wg - 1u) / wg;
+
+  // ① 本 workgroup 负责的 chunk 局部和
+  var local = 0u;
+  for (var c = 0u; c < chunks; c++) {
+    let idx = c * wg + tid;
+    if (idx < cells) { local = local + atomicLoad(&cellCount[idx]); }
+  }
+  partial[tid] = local;
+  workgroupBarrier();
+
+  // ② 局部和的含前缀扫描(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;
+  }
+
+  // ③ chunk 基址 → start/fill,顺带把 count 归零给下一帧
+  var run = 0u;
+  if (tid > 0u) { run = partial[tid - 1u]; }
+  for (var c = 0u; c < chunks; c++) {
+    let idx = c * wg + tid;
+    if (idx < cells) {
+      cellStart[idx] = run;
+      atomicStore(&cellFill[idx], run);
+      run = run + atomicLoad(&cellCount[idx]);
+      atomicStore(&cellCount[idx], 0u);
+    }
+  }
+}
+
+@compute @workgroup_size(${WG})
+fn main_scatter(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  if (i >= params.count) { return; }
+  let slot = atomicAdd(&cellFill[cellOf(posIn[i])], 1u);
+  order[slot] = i;
+}
+`;
+}

package/dist/packs/life/boids.js

@@ -2,10 +2,11 @@ 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 { createNeighborGrid } from "../grid/index.js";
 import { mulberry32 } from "../particles/presets.js";
 const WG = 64;
 export async function boids(config = {}) {
-    const { count: N = 3000, perception = 0.05, maxSpeed = 0.012, wSep = 1.6, wAli = 1.0, wCoh = 0.8, size = 0.009, seed = 'boids', } = config;
+    const { count: N = 1200, perception = 0.05, maxSpeed = 0.012, wSep = 1.6, wAli = 1.0, wCoh = 0.8, size = 0.009, seed = 'boids', } = config;
     const seedHash = typeof seed === 'string' ? hashStr(seed) : (seed ?? 3);
     const gridSize = Math.max(4, Math.ceil(2 / perception));
     const ctx = await GpuContext.get();
@@ -46,20 +47,12 @@ export async function boids(config = {}) {
         device.queue.writeBuffer(uniform, 0, b);
     };
     writeUniform();
-    const cells = gridSize * gridSize;
-    const cellCount = await Buffer.create('u32', cells);
-    const cellStart = await Buffer.create('u32', cells);
-    const cellFill = await Buffer.create('u32', cells);
-    const order = await Buffer.create('u32', N);
-    cellCount.write(new Uint32Array(cells));
     const module = device.createShaderModule({ code: boidsWgsl(size), label: 'boids' });
     const info = await module.getCompilationInfo();
     const errors = info.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 pCounts = device.createComputePipeline({ layout: 'auto', compute: { module, entryPoint: 'main_counts' } });
-    const pScan = device.createComputePipeline({ layout: 'auto', compute: { module, entryPoint: 'main_scan' } });
-    const pScatter = device.createComputePipeline({ layout: 'auto', compute: { module, entryPoint: 'main_scatter' } });
+    const neighborGrid = await createNeighborGrid({ count: N, worldHalf: 1.0, cellSize: perception });
     const pForce = device.createComputePipeline({ layout: 'auto', compute: { module, entryPoint: 'main_force' } });
     const pRender = device.createRenderPipeline({
         layout: 'auto',
@@ -67,32 +60,6 @@ export async function boids(config = {}) {
         fragment: { module, entryPoint: 'fs', targets: [{ format: navigator.gpu.getPreferredCanvasFormat() }] },
         primitive: { topology: 'triangle-list' },
     });
-    const bgCounts = (read) => device.createBindGroup({
-        layout: pCounts.getBindGroupLayout(0),
-        entries: [
-            { binding: 0, resource: { buffer: uniform } },
-            { binding: 1, resource: { buffer: read.pos.gpuBuffer } },
-            { binding: 2, resource: { buffer: cellCount.gpuBuffer } },
-        ],
-    });
-    const bgScan = device.createBindGroup({
-        layout: pScan.getBindGroupLayout(0),
-        entries: [
-            { binding: 0, resource: { buffer: uniform } },
-            { binding: 2, resource: { buffer: cellCount.gpuBuffer } },
-            { binding: 3, resource: { buffer: cellStart.gpuBuffer } },
-            { binding: 4, resource: { buffer: cellFill.gpuBuffer } },
-        ],
-    });
-    const bgScatter = (read) => device.createBindGroup({
-        layout: pScatter.getBindGroupLayout(0),
-        entries: [
-            { binding: 0, resource: { buffer: uniform } },
-            { binding: 1, resource: { buffer: read.pos.gpuBuffer } },
-            { binding: 4, resource: { buffer: cellFill.gpuBuffer } },
-            { binding: 5, resource: { buffer: order.gpuBuffer } },
-        ],
-    });
     const bgForce = (read, write) => device.createBindGroup({
         layout: pForce.getBindGroupLayout(0),
         entries: [
@@ -101,9 +68,9 @@ export async function boids(config = {}) {
             { binding: 6, resource: { buffer: read.vel.gpuBuffer } },
             { binding: 7, resource: { buffer: write.pos.gpuBuffer } },
             { binding: 8, resource: { buffer: write.vel.gpuBuffer } },
-            { binding: 3, resource: { buffer: cellStart.gpuBuffer } },
-            { binding: 4, resource: { buffer: cellFill.gpuBuffer } },
-            { binding: 5, resource: { buffer: order.gpuBuffer } },
+            { binding: 3, resource: { buffer: neighborGrid.cellStart.gpuBuffer } },
+            { binding: 4, resource: { buffer: neighborGrid.cellFill.gpuBuffer } },
+            { binding: 5, resource: { buffer: neighborGrid.order.gpuBuffer } },
         ],
     });
     const bgRender = (read) => device.createBindGroup({
@@ -137,15 +104,6 @@ export async function boids(config = {}) {
             const write = useAB ? sideB : sideA;
             const enc = device.createCommandEncoder();
             const pass = enc.beginComputePass();
-            pass.setPipeline(pCounts);
-            pass.setBindGroup(0, bgCounts(read));
-            pass.dispatchWorkgroups(Math.ceil(N / WG));
-            pass.setPipeline(pScan);
-            pass.setBindGroup(0, bgScan);
-            pass.dispatchWorkgroups(1);
-            pass.setPipeline(pScatter);
-            pass.setBindGroup(0, bgScatter(read));
-            pass.dispatchWorkgroups(Math.ceil(N / WG));
             pass.setPipeline(pForce);
             pass.setBindGroup(0, bgForce(read, write));
             pass.dispatchWorkgroups(Math.ceil(N / WG));
@@ -172,10 +130,7 @@ export async function boids(config = {}) {
         buffers() { return { pos: pp.current.pos, vel: pp.current.vel }; },
         destroy() {
             pp.destroy();
-            cellCount.destroy();
-            cellStart.destroy();
-            cellFill.destroy();
-            order.destroy();
+            neighborGrid.destroy();
             uniform.destroy();
         },
     };
@@ -223,57 +178,6 @@ fn cellOf(p: vec2f) -> u32 {
   return u32(cy) * u32(g) + u32(cx);
 }
 
-@compute @workgroup_size(${WG})
-fn main_counts(@builtin(global_invocation_id) gid: vec3u) {
-  let i = gid.x;
-  if (i >= params.count) { return; }
-  atomicAdd(&cellCount[cellOf(posIn[i])], 1u);
-}
-
-var<workgroup> partial: array<u32, 256>;
-@compute @workgroup_size(256)
-fn main_scan(@builtin(local_invocation_id) lid: vec3u) {
-  let tid = lid.x;
-  let cells = params.gridSize * params.gridSize;
-  let chunks = (cells + 255u) / 256u;
-  var local = 0u;
-  for (var c = 0u; c < chunks; c++) {
-    let idx = c * 256u + tid;
-    if (idx < cells) { local = local + atomicLoad(&cellCount[idx]); }
-  }
-  partial[tid] = local;
-  workgroupBarrier();
-  var offset = 1u;
-  loop {
-    if (offset >= 256u) { break; }
-    var v = 0u;
-    if (tid >= offset) { v = partial[tid - offset]; }
-    workgroupBarrier();
-    if (tid >= offset) { partial[tid] = partial[tid] + v; }
-    workgroupBarrier();
-    offset = offset << 1u;
-  }
-  var run = 0u;
-  if (tid > 0u) { run = partial[tid - 1u]; }
-  for (var c = 0u; c < chunks; c++) {
-    let idx = c * 256u + tid;
-    if (idx < cells) {
-      cellStart[idx] = run;
-      atomicStore(&cellFill[idx], run);
-      run = run + atomicLoad(&cellCount[idx]);
-      atomicStore(&cellCount[idx], 0u);
-    }
-  }
-}
-
-@compute @workgroup_size(${WG})
-fn main_scatter(@builtin(global_invocation_id) gid: vec3u) {
-  let i = gid.x;
-  if (i >= params.count) { return; }
-  let slot = atomicAdd(&cellFill[cellOf(posIn[i])], 1u);
-  order[slot] = i;
-}
-
 @compute @workgroup_size(${WG})
 fn main_force(@builtin(global_invocation_id) gid: vec3u) {
   let i = gid.x;

package/dist/packs/particles/config.d.ts

@@ -22,7 +22,8 @@ export interface ParticlesConfig {
     dt?: number;
     /** 点大小(canvas 像素单位的比例,默认 0.004;大规模下自动缩小) */
     pointSize?: number;
-    /** 每粒子邻域候选上限(grid 模式;仅作极端抱团的保险丝,默认 32768 在支持密度内不触发——按格子顺序截断会引入方向偏差伪影) */
+    /** 每粒子邻域候选总上限(grid 模式,均摊到 3×3=9 格)。默认 8100:正常密度永不触发,
+     *  极端抱团时以轻微方向偏差换取帧率稳定(实测 30ms → 7.5ms @ 200k 抱团态)。设 Infinity 可禁用。 */
     maxNeighbors?: number;
 }
 export interface ResolvedConfig {

package/dist/packs/particles/config.js

@@ -3,7 +3,7 @@ import { 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 = 32768, } = config;
+    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)}`);
     }

package/dist/packs/particles/grid.js

@@ -40,9 +40,12 @@ fn main(@builtin(global_invocation_id) gid: vec3u) {
 `;
 }
 export function gridScanWgsl() {
-    // 两级扫描:① 各 workgroup 扫自己的 256-cell 块,块总和写入 blockSums;
-    // ② 单 workgroup 扫 blockSums(最多 SCAN_WORKGROUP 个块 = 65536 cell);
-    // ③ 各 workgroup 加上本块基址。256×256=65536 cell 内 O(1) 轮次,不再随规模线性退化。
+    // 两级扫描,三 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 分块升级(路线图)。
     return /* wgsl */ `
 struct Params {
   count: u32, _pad0: u32,
@@ -53,19 +56,18 @@ 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<u32>;
-@group(0) @binding(4) var<storage, read_write> blockSums: 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>>;
 
 var<workgroup> partial: array<u32, ${SCAN_WORKGROUP}>;
 
+// Pass A:块内排他扫描。cellFill[c] = 块内排他前缀(临时);blockSums[wid] = 块总和
 @compute @workgroup_size(${SCAN_WORKGROUP})
-fn main(@builtin(local_invocation_id) lid: vec3u, @builtin(workgroup_id) wid: vec3u) {
+fn main_scan_blocks(@builtin(local_invocation_id) lid: vec3u, @builtin(workgroup_id) wid: vec3u) {
   let tid = lid.x;
   let wg = ${SCAN_WORKGROUP}u;
   let base = wid.x * wg;
   let cells = params.cells;
-
-  // ① 块内 Hillis-Steele(块不足时以 0 填充)
   let v0 = select(0u, atomicLoad(&cellCount[base + tid]), base + tid < cells);
   partial[tid] = v0;
   workgroupBarrier();
@@ -79,39 +81,45 @@ fn main(@builtin(local_invocation_id) lid: vec3u, @builtin(workgroup_id) wid: ve
     workgroupBarrier();
     offset = offset << 1u;
   }
-  // 含前缀 → 排他:start = 块内前缀(不含自身),fill = start + count
-  let myCount = v0;
-  let myPrefix = select(partial[tid - 1u], 0u, tid == 0u);
+  // 含前缀 → 排他:excl = incl - own
   if (base + tid < cells) {
-    cellStart[base + tid] = myPrefix;
-    cellFill[base + tid] = myPrefix + myCount;
+    atomicStore(&cellFill[base + tid], partial[tid] - v0);
   }
-  // 块总和 → blockSums(含)
-  if (tid == 0u) { blockSums[wid.x] = partial[wg - 1u]; }
-  workgroupBarrier();
+  if (tid == 0u) { atomicStore(&blockSums[wid.x], partial[wg - 1u]); }
+}
 
-  // ② 块间扫描(单 workgroup;块数 = ceil(cells/wg) ≤ SCAN_WORKGROUP)
-  if (wid.x == 0u) {
-    var off = 1u;
-    loop {
-      if (off >= wg) { break; }
-      var v = 0u;
-      if (tid >= off) { v = blockSums[tid - off]; }
-      workgroupBarrier();
-      if (tid >= off) { blockSums[tid] = blockSums[tid] + v; }
-      workgroupBarrier();
-      off = off << 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();
-
-  // ③ 加块基址;cellCount 归零供下一帧
-  let blockBase = select(0u, blockSums[wid.x - 1u], wid.x > 0u);
-  if (base + tid < cells) {
-    cellStart[base + tid] = cellStart[base + tid] + blockBase;
-    cellFill[base + tid] = cellFill[base + tid] + blockBase;
-    atomicStore(&cellCount[base + tid], 0u);
+  var offset = 1u;
+  loop {
+    if (offset >= ${SCAN_WORKGROUP}u) { break; }
+    var v = 0u;
+    if (tid >= offset) { v = partial[tid - offset]; }
+    workgroupBarrier();
+    if (tid >= offset) { partial[tid] = partial[tid] + v; }
+    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

@@ -97,7 +97,9 @@ 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 pScan = await makePipeline(mScan, 'main', 'grid-scan');
+        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 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');
@@ -113,8 +115,28 @@ export async function particles(config = {}) {
                 { binding: 2, resource: { buffer: count.gpuBuffer } },
             ],
         });
-        const bgScan = device.createBindGroup({
-            layout: pScan.getBindGroupLayout(0),
+        const bgScanBlocks = device.createBindGroup({
+            layout: pScanBlocks.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 } },
@@ -170,10 +192,11 @@ export async function particles(config = {}) {
         };
         const state = {
             size,
+            cells,
             count, start, fill, order, partial, sortedPos, sortedSp, blockSums,
-            pCounts, pScan, pScatter, pForceCell, pForceInt,
+            pCounts, pScanBlocks, pScanBases, pScanApply, pScatter, pForceCell, pForceInt,
             bgCountsA: bgCounts(sideA.pos), bgCountsB: bgCounts(sideB.pos),
-            bgScan,
+            bgScanBlocks, bgScanBases, bgScanApply,
             bgScatterA: bgScatter(sideA.pos), bgScatterB: bgScatter(sideB.pos),
             bgForceCellAB: bgForceCell(sideA.pos), bgForceCellBA: bgForceCell(sideB.pos),
             bgIntegrateAB: bgIntegrate(sideA, sideB), bgIntegrateBA: bgIntegrate(sideB, sideA),
@@ -236,37 +259,29 @@ export async function particles(config = {}) {
                 grid.bgForceCellRebuild(sideA.pos);
                 gridBindGroupsDirty = false;
             }
-            const enc = device.createCommandEncoder();
-            const pass = enc.beginComputePass();
             if (grid) {
-                // 实测:同一 compute pass 内连续 dispatch 之间,后续 kernel 读到的可能
-                // 是前一 kernel 的旧数据(Dawn/Windows,partial 竞态)——各段独立 pass
-                // 提交以保证可见性。
-                // 单 encoder、五个独立 pass:同一 encoder 内 pass 天然按序执行且可见,
-                // 免掉每帧 2 次额外 enc.finish()/submit(评审:提交间隔调度空隙)
-                pass.setPipeline(grid.pCounts);
-                pass.setBindGroup(0, useAB ? grid.bgCountsA : grid.bgCountsB);
-                pass.dispatchWorkgroups(Math.ceil(cfg.count / WORKGROUP));
-                pass.setPipeline(grid.pScan);
-                pass.setBindGroup(0, grid.bgScan);
-                pass.dispatchWorkgroups(1);
-                pass.setPipeline(grid.pScatter);
-                pass.setBindGroup(0, useAB ? grid.bgScatterA : grid.bgScatterB);
-                pass.dispatchWorkgroups(Math.ceil(cfg.count / WORKGROUP));
-                pass.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()]);
+                // 五段各自独立 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));
             }
             else {
+                const enc = device.createCommandEncoder();
+                const pass = enc.beginComputePass();
                 pass.setPipeline(simPipeline);
                 pass.setBindGroup(0, useAB ? bgAB : bgBA);
                 pass.dispatchWorkgroups(Math.ceil(cfg.count / WORKGROUP));

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "wgpu-kit",
-  "version": "1.0.3",
-  "description": "Browser GPGPU middle layer: 100k particles in 5 lines. WebGPU compute without the boilerplate.",
+  "version": "1.1.0",
+  "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",
   "keywords": [
@@ -25,31 +25,43 @@
     },
     "./particles": {
       "types": "./dist/packs/particles/index.d.ts",
-      "import": "./dist/particles.js"
+      "import": "./dist/packs/particles/index.js"
     },
     "./three": {
       "types": "./dist/interop/three.d.ts",
-      "import": "./dist/three.js"
+      "import": "./dist/interop/three.js"
     },
     "./life": {
       "types": "./dist/packs/life/index.d.ts",
-      "import": "./dist/life.js"
+      "import": "./dist/packs/life/index.js"
     },
     "./react": {
       "types": "./dist/react/index.d.ts",
-      "import": "./dist/react.js"
+      "import": "./dist/react/index.js"
     },
     "./fields": {
       "types": "./dist/packs/fields/index.d.ts",
-      "import": "./dist/fields.js"
+      "import": "./dist/packs/fields/index.js"
     },
     "./image": {
       "types": "./dist/packs/image/index.d.ts",
-      "import": "./dist/image.js"
+      "import": "./dist/packs/image/index.js"
+    },
+    "./media": {
+      "types": "./dist/media.d.ts",
+      "import": "./dist/media.js"
+    },
+    "./observe": {
+      "types": "./dist/observe.d.ts",
+      "import": "./dist/observe.js"
     },
     "./vite": {
       "types": "./dist/vite.d.ts",
       "import": "./dist/vite.js"
+    },
+    "./grid": {
+      "types": "./dist/packs/grid/index.d.ts",
+      "import": "./dist/packs/grid/index.js"
     }
   },
   "peerDependencies": {
@@ -64,8 +76,10 @@
     "build:playground": "vite build playground",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "bundle:tests": "esbuild tests/gpu/smoke.ts --bundle --format=esm --outfile=tests/gpu/smoke.bundle.js --log-level=warning && esbuild tests/gpu/bench.ts --bundle --format=esm --outfile=tests/gpu/bench.bundle.js --log-level=warning && esbuild tests/gpu/packages.ts --bundle --format=esm --outfile=tests/gpu/packages.bundle.js --log-level=warning",
-    "verify": "node scripts/verify.mjs"
+    "bundle:tests": "esbuild tests/gpu/smoke.ts --bundle --format=esm --outfile=tests/gpu/smoke.bundle.js --log-level=warning && esbuild tests/gpu/bench.ts --bundle --format=esm --outfile=tests/gpu/bench.bundle.js --log-level=warning && esbuild tests/gpu/packages.ts --bundle --format=esm --outfile=tests/gpu/packages.bundle.js --log-level=warning && esbuild tests/gpu/grid-debug.ts --bundle --format=esm --outfile=tests/gpu/grid-debug.bundle.js --log-level=warning",
+    "verify": "node scripts/verify.mjs",
+    "prepublishOnly": "npm run build && node scripts/audit-exports.mjs",
+    "bench": "node scripts/bench.mjs"
   },
   "devDependencies": {
     "@types/node": "^24.0.0",