wgpu-kit 0.9.11 → 1.0.0

package/dist/packs/particles/config.js

@@ -0,0 +1,36 @@
+import { resolveMatrix, hashSeed } from "./presets.js";
+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;
+    if (!Number.isInteger(count) || count <= 0 || count > 1_000_000) {
+        throw new UsageError(`count 必须是 1..1_000_000 的整数,收到: ${String(count)}`);
+    }
+    if (!MODES.includes(mode)) {
+        throw new UsageError(`mode 必须是 ${MODES.join(' | ')},收到: "${String(mode)}"`);
+    }
+    if (mode === 'n2' && count > 32_000) {
+        throw new UsageError(`mode='n2' 建议 count ≤ 20000(当前 ${count});大规模请用 mode='tiled' 或 'grid'`);
+    }
+    const seedStr = String(seed);
+    return {
+        count,
+        forces: resolveMatrix(forces, hashSeed(seedStr)),
+        forcesName: typeof forces === 'string' ? forces : 'custom',
+        mode,
+        color,
+        bounds,
+        seed: seedStr,
+        seedHash: hashSeed(seedStr),
+        rMax,
+        beta,
+        forceFactor,
+        friction: Math.exp(-dt / frictionHalfLife),
+        frictionHalfLife,
+        dt,
+        pointSize,
+        maxNeighbors,
+    };
+}
+export { FORCE_PRESETS, mulberry32, hashSeed, randomMatrix, resolveMatrix } from "./presets.js";

package/dist/packs/particles/grid.js

@@ -0,0 +1,248 @@
+/**
+ * grid 模式(spatial hash / counting sort)的四个 kernel。
+ * 每帧在同一个 command encoder 里跑四遍:
+ *   ① counts  原子计数每格粒子数
+ *   ② scan    单 workgroup 分块前缀和(cellStart/cellFill),顺带把 cellCount 归零给下一帧
+ *   ③ scatter 按格散射出有序索引表 order
+ *   ④ force   与 tiled 相同的力计算,但邻域遍历改为 3×3 个 cell 的有序区间
+ * 相比 O(N²),复杂度 ≈ O(N · 邻域密度)——10 万粒子的大门。
+ */
+export const GRID_WORKGROUP = 64;
+export const SCAN_WORKGROUP = 256;
+/** cellOf:世界坐标 → 格子索引(世界固定 [-worldHalf, worldHalf],格宽 = 2*worldHalf/gridSize) */
+export const CELL_OF = /* wgsl */ `
+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) * params.gridSize + u32(cx);
+}
+`;
+export function gridCountsWgsl() {
+    return /* wgsl */ `
+struct Params {
+  count: u32, _pad0: u32,
+  dt: f32, rMax: f32, beta: f32, forceFactor: f32, friction: f32,
+  worldHalf: f32, wrapEdge: f32,
+  gridSize: u32, cells: u32, maxCand: 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>>;
+${CELL_OF}
+@compute @workgroup_size(${GRID_WORKGROUP})
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  if (i >= params.count) { return; }
+  atomicAdd(&cellCount[cellOf(posIn[i])], 1u);
+}
+`;
+}
+export function gridScanWgsl() {
+    // 两级扫描:① 各 workgroup 扫自己的 256-cell 块,块总和写入 blockSums;
+    // ② 单 workgroup 扫 blockSums(最多 SCAN_WORKGROUP 个块 = 65536 cell);
+    // ③ 各 workgroup 加上本块基址。256×256=65536 cell 内 O(1) 轮次,不再随规模线性退化。
+    return /* wgsl */ `
+struct Params {
+  count: u32, _pad0: u32,
+  dt: f32, rMax: f32, beta: f32, forceFactor: f32, friction: f32,
+  worldHalf: f32, wrapEdge: f32,
+  gridSize: u32, cells: u32, maxCand: u32,
+};
+@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>;
+
+var<workgroup> partial: array<u32, ${SCAN_WORKGROUP}>;
+
+@compute @workgroup_size(${SCAN_WORKGROUP})
+fn main(@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();
+  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 = 块内前缀(不含自身),fill = start + count
+  let myCount = v0;
+  let myPrefix = select(partial[tid - 1u], 0u, tid == 0u);
+  if (base + tid < cells) {
+    cellStart[base + tid] = myPrefix;
+    cellFill[base + tid] = myPrefix + myCount;
+  }
+  // 块总和 → blockSums(含)
+  if (tid == 0u) { blockSums[wid.x] = partial[wg - 1u]; }
+  workgroupBarrier();
+
+  // ② 块间扫描(单 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;
+    }
+  }
+  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);
+  }
+}
+`;
+}
+export function gridScatterWgsl() {
+    return /* wgsl */ `
+struct Params {
+  count: u32, _pad0: u32,
+  dt: f32, rMax: f32, beta: f32, forceFactor: f32, friction: f32,
+  worldHalf: f32, wrapEdge: f32,
+  gridSize: u32, cells: u32, maxCand: 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> species: array<u32>;
+@group(0) @binding(3) var<storage, read_write> cellFill: array<atomic<u32>>;
+@group(0) @binding(4) var<storage, read_write> order: array<u32>;
+@group(0) @binding(5) var<storage, read_write> sortedPos: array<vec2f>;
+@group(0) @binding(6) var<storage, read_write> sortedSp: array<u32>;
+${CELL_OF}
+@compute @workgroup_size(${GRID_WORKGROUP})
+fn main(@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;
+  sortedPos[slot] = posIn[i];
+  sortedSp[slot] = species[i];
+}
+`;
+}
+/**
+ * grid 力核:拆成两趟以消除负载不均(v0.9.7 黑屏级卡顿的根治)。
+ * 抱团时单格可能挤几千粒子,"一个线程扫 9 格"会让重格子线程拖死整批;
+ * 拆成 (粒子 × 格子) 一线程后工作量均分,物理结果与单趟完全一致(仅求和顺序不同)。
+ *   ① main_force_cell:线程 = (粒子 i × 邻域格 c),把该格贡献写入 partial[i*9+c]
+ *   ② main_force_integrate:线程 = 粒子,汇总 9 份贡献并积分
+ * 同格候选数上限 maxCand(由 JS 侧传 maxNeighbors/9)仍是极端抱团的保险丝。
+ */
+export function gridForceWgsl(speciesCount) {
+    return /* wgsl */ `
+struct Params {
+  count: u32, _pad0: u32,
+  dt: f32, rMax: f32, beta: f32, forceFactor: f32, friction: f32,
+  worldHalf: f32, wrapEdge: f32,
+  gridSize: u32, cells: u32, maxCand: u32,
+};
+@group(0) @binding(0) var<uniform> params: Params;
+@group(0) @binding(1) var<storage, read> matrix: array<f32>;
+@group(0) @binding(2) var<storage, read> species: array<u32>;
+@group(0) @binding(3) var<storage, read> posIn: array<vec2f>;
+@group(0) @binding(4) var<storage, read> sortedPos: array<vec2f>;
+@group(0) @binding(5) var<storage, read> sortedSp: array<u32>;
+@group(0) @binding(6) var<storage, read> cellStart: array<u32>;
+@group(0) @binding(7) var<storage, read> cellFill: array<u32>;
+@group(0) @binding(8) var<storage, read> order: array<u32>;
+@group(0) @binding(9) var<storage, read_write> partial: array<vec2f>;
+
+fn force(r: f32, a: f32) -> f32 {
+  if (r < params.beta) { return a / params.beta - 1.0; }
+  if (r < 1.0) { return a * (1.0 - abs(2.0 * r - 1.0 - params.beta) / (1.0 - params.beta)); }
+  return 0.0;
+}
+
+@compute @workgroup_size(64)
+fn main_force_cell(@builtin(global_invocation_id) gid: vec3u) {
+  let tid = gid.x;
+  let i = tid / 9u;
+  if (i >= params.count) { return; }
+  let c = tid % 9u;
+  let g = i32(params.gridSize);
+  // 与 CELL_OF 完全相同的浮点序列(除以 span 再乘 g)——路径不一致会让贴格粒子查询错位一格
+  let span = params.worldHalf * 2.0;
+  var cx = clamp(i32(floor((posIn[i].x + params.worldHalf) / span * f32(g))), 0, g - 1);
+  var cy = clamp(i32(floor((posIn[i].y + params.worldHalf) / span * f32(g))), 0, g - 1);
+  let dx = i32(c % 3u) - 1;
+  let dy = i32(c / 3u) - 1;
+  let nx = cx + dx;
+  let ny = cy + dy;
+  let out = i * 9u + c;
+  if (nx < 0 || ny < 0 || nx >= g || ny >= g) { partial[out] = vec2f(0.0); return; }
+  let cc = u32(ny) * u32(g) + u32(nx);
+  let s = cellStart[cc];
+  let e = cellFill[cc];
+  let myPos = posIn[i];
+  let mySp = species[i];
+  let rMax2 = params.rMax * params.rMax;
+  var accel = vec2f(0.0, 0.0);
+  var checked = 0u;
+  for (var k = s; k < e; k++) {
+    checked = checked + 1u;
+    if (checked > params.maxCand) { break; }
+    if (order[k] == i) { continue; }
+    let rel = sortedPos[k] - myPos;
+    let d2 = dot(rel, rel);
+    if (d2 > rMax2) { continue; }
+    let d = sqrt(d2);
+    let r = d / params.rMax;
+    if (r > 0.0 && r < 1.0) {
+      let f = force(r, matrix[mySp * ${speciesCount}u + sortedSp[k]]);
+      accel = accel + rel / d * f;
+    }
+  }
+  partial[out] = accel;
+}
+
+@group(0) @binding(0) var<uniform> params2: Params;
+@group(0) @binding(1) var<storage, read> velIn: array<vec2f>;
+@group(0) @binding(2) var<storage, read> posIn2: array<vec2f>;
+@group(0) @binding(3) var<storage, read> partialR: array<vec2f>;
+@group(0) @binding(4) var<storage, read_write> posOut: array<vec2f>;
+@group(0) @binding(5) var<storage, read_write> velOut: array<vec2f>;
+
+@compute @workgroup_size(64)
+fn main_force_integrate(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  if (i >= params2.count) { return; }
+  var accel = vec2f(0.0, 0.0);
+  for (var c = 0u; c < 9u; c++) {
+    accel = accel + partialR[i * 9u + c];
+  }
+  accel = accel * params2.forceFactor * params2.rMax;
+  var vel = (velIn[i] + accel * params2.dt) * params2.friction;
+  var pos = posIn2[i] + vel * params2.dt;
+  let span = params2.worldHalf * 2.0;
+  if (params2.wrapEdge > 0.5) {
+    pos = ((pos + params2.worldHalf) % span + span) % span - params2.worldHalf;
+  } else {
+    pos = clamp(pos, vec2f(-params2.worldHalf), vec2f(params2.worldHalf));
+  }
+  posOut[i] = pos;
+  velOut[i] = vel;
+}
+`;
+}

package/dist/packs/particles/index.js

@@ -0,0 +1,361 @@
+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 { resolveConfig } from "./config.js";
+import { mulberry32, resolveMatrix, hashSeed } from "./presets.js";
+import { simWgsl, WORKGROUP } from "./wgsl.js";
+import { gridCountsWgsl, gridScanWgsl, gridScatterWgsl, gridForceWgsl } from "./grid.js";
+import { ParticlesRenderer } from "./render.js";
+const USIZE = 48;
+export async function particles(config = {}) {
+    const cfg = resolveConfig(config);
+    const ctx = await GpuContext.get();
+    const device = ctx.device;
+    // 世界自适应:面积随粒子数等比扩大(默认 16k 密度),密度/邻居数/力与 16k 版逐位一致,
+    // 只是"宇宙更大、相机更远"——大规模下不改变任何物理行为(用户可关)
+    const worldHalf = 1 * Math.sqrt(cfg.count / 16_000);
+    // —— 数据 ——
+    const pp = await PingPong.create({ pos: 'vec2f', vel: 'vec2f' }, cfg.count);
+    const sideA = { pos: pp.current.pos, vel: pp.current.vel }; // 固定引用;pp.current 随 swap 翻转
+    const sideB = { pos: pp.other.pos, vel: pp.other.vel };
+    const species = await Buffer.create('u32', cfg.count);
+    const matrix = await Buffer.create('f32', 16);
+    {
+        const rand = mulberry32(cfg.seedHash);
+        const pos0 = new Float32Array(cfg.count * 2);
+        for (let i = 0; i < pos0.length; i++)
+            pos0[i] = (rand() * 1.6 - 0.8) * worldHalf;
+        const vel0 = new Float32Array(cfg.count * 2);
+        const sp0 = new Uint32Array(cfg.count);
+        for (let i = 0; i < cfg.count; i++)
+            sp0[i] = Math.floor(rand() * 4);
+        sideA.pos.write(pos0);
+        sideA.vel.write(vel0);
+        species.write(sp0);
+        matrix.write(new Float32Array(cfg.forces));
+    }
+    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)));
+    let gridSize = gridSizeOf(phys.rMax, worldHalf);
+    const writeUniform = (dt) => {
+        const buf = new ArrayBuffer(USIZE);
+        const v = new DataView(buf);
+        v.setUint32(0, cfg.count, true);
+        v.setUint32(4, 0, true);
+        v.setFloat32(8, dt, true);
+        v.setFloat32(12, phys.rMax, true);
+        v.setFloat32(16, phys.beta, true);
+        v.setFloat32(20, phys.forceFactor, true);
+        v.setFloat32(24, Math.exp(-dt / phys.frictionHalfLife), true);
+        v.setFloat32(28, worldHalf, true);
+        v.setFloat32(32, cfg.bounds === 'wrap' ? 1 : 0, true);
+        v.setUint32(36, gridSize, true);
+        v.setUint32(40, gridSize * gridSize, true);
+        v.setUint32(44, Math.ceil(cfg.maxNeighbors / 9), true); // 每格候选上限
+        device.queue.writeBuffer(uniform, 0, buf);
+    };
+    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');
+        if (errors.length > 0)
+            throw new CompileError(label, errors.map((m) => ({ line: m.lineNum, msg: m.message })), 0);
+        return module;
+    };
+    const makePipeline = async (module, entryPoint, label) => createComputePipelineChecked(device, module, `${label}(${entryPoint})`, entryPoint);
+    // —— n2 / tiled:单 kernel + 双缓冲 ——
+    let simPipeline = null;
+    let bgAB = null;
+    let bgBA = null;
+    let grid = null;
+    let gridBuildVersion = 0;
+    let gridBindGroupsDirty = false;
+    const gridDestroy = (g) => {
+        g.count.destroy();
+        g.start.destroy();
+        g.fill.destroy();
+        g.order.destroy();
+        g.partial.destroy();
+        g.sortedPos.destroy();
+        g.sortedSp.destroy();
+        g.blockSums.destroy();
+    };
+    const buildGrid = async (size) => {
+        const cells = size * size;
+        const count = await Buffer.create('u32', cells);
+        const start = await Buffer.create('u32', cells);
+        const fill = await Buffer.create('u32', cells);
+        const order = await Buffer.create('u32', cfg.count);
+        count.write(new Uint32Array(cells)); // 归零
+        const mCounts = await compile(gridCountsWgsl(), 'grid-counts');
+        const mScan = await compile(gridScanWgsl(), 'grid-scan');
+        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 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({
+            layout: pCounts.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: { buffer: uniform } },
+                { binding: 1, resource: { buffer: readPos.gpuBuffer } },
+                { binding: 2, resource: { buffer: count.gpuBuffer } },
+            ],
+        });
+        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 bgScatter = (readPos) => device.createBindGroup({
+            layout: pScatter.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: { buffer: uniform } },
+                { binding: 1, resource: { buffer: readPos.gpuBuffer } },
+                { binding: 2, resource: { buffer: species.gpuBuffer } },
+                { binding: 3, resource: { buffer: fill.gpuBuffer } },
+                { binding: 4, resource: { buffer: order.gpuBuffer } },
+                { binding: 5, resource: { buffer: sortedPos.gpuBuffer } },
+                { binding: 6, resource: { buffer: sortedSp.gpuBuffer } },
+            ],
+        });
+        // 力核第一趟:(粒子 × 格子) 部分力 —— 负载均衡的关键;读按格子序重排的副本(合并访问)
+        const bgForceCell = (readPos) => device.createBindGroup({
+            layout: pForceCell.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: { buffer: uniform } },
+                { binding: 1, resource: { buffer: matrix.gpuBuffer } },
+                { binding: 2, resource: { buffer: species.gpuBuffer } },
+                { binding: 3, resource: { buffer: readPos.gpuBuffer } },
+                { binding: 4, resource: { buffer: sortedPos.gpuBuffer } },
+                { binding: 5, resource: { buffer: sortedSp.gpuBuffer } },
+                { binding: 6, resource: { buffer: start.gpuBuffer } },
+                { binding: 7, resource: { buffer: fill.gpuBuffer } },
+                { binding: 8, resource: { buffer: order.gpuBuffer } },
+                { binding: 9, resource: { buffer: partial.gpuBuffer } },
+            ],
+        });
+        // 力核第二趟:汇总 9 份贡献并积分
+        const bgIntegrate = (read, write) => device.createBindGroup({
+            layout: pForceInt.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: { buffer: uniform } },
+                { binding: 1, resource: { buffer: read.vel.gpuBuffer } },
+                { binding: 2, resource: { buffer: read.pos.gpuBuffer } },
+                { binding: 3, resource: { buffer: partial.gpuBuffer } },
+                { binding: 4, resource: { buffer: write.pos.gpuBuffer } },
+                { binding: 5, resource: { buffer: write.vel.gpuBuffer } },
+            ],
+        });
+        const rebuildForceCellBG = (readPos) => {
+            const otherPos = readPos === sideA.pos ? sideB.pos : sideA.pos;
+            state.bgForceCellAB = bgForceCell(readPos);
+            state.bgForceCellBA = bgForceCell(otherPos);
+        };
+        const state = {
+            size,
+            count, start, fill, order, partial, sortedPos, sortedSp, blockSums,
+            pCounts, pScan, pScatter, pForceCell, pForceInt,
+            bgCountsA: bgCounts(sideA.pos), bgCountsB: bgCounts(sideB.pos),
+            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),
+            bgForceCellRebuild: rebuildForceCellBG,
+        };
+        return state;
+    };
+    if (cfg.mode === 'grid')
+        grid = await buildGrid(gridSize);
+    else {
+        const module = await compile(simWgsl(cfg.mode, 4), `particles-sim(${cfg.mode})`);
+        simPipeline = await makePipeline(module, 'main', `particles-sim(${cfg.mode})`);
+        const bg = (read, write) => device.createBindGroup({
+            layout: simPipeline.getBindGroupLayout(0),
+            entries: [
+                { binding: 0, resource: { buffer: uniform } },
+                { binding: 1, resource: { buffer: matrix.gpuBuffer } },
+                { binding: 2, resource: { buffer: species.gpuBuffer } },
+                { binding: 3, resource: { buffer: read.pos.gpuBuffer } },
+                { binding: 4, resource: { buffer: read.vel.gpuBuffer } },
+                { binding: 5, resource: { buffer: write.pos.gpuBuffer } },
+                { binding: 6, resource: { buffer: write.vel.gpuBuffer } },
+            ],
+        });
+        bgAB = bg(sideA, sideB);
+        bgBA = bg(sideB, sideA);
+    }
+    let renderer = null;
+    let frame = 0;
+    let lastFps = 0;
+    let fpsFrames = 0;
+    let fpsAcc = 0;
+    let fpsLast = performance.now();
+    let gpuErrorCount = 0;
+    device.addEventListener?.('uncapturederror', (e) => {
+        gpuErrorCount++;
+        const msg = e.error?.message ?? String(e);
+        const g = globalThis;
+        g.__firstGpuError ??= msg.slice(0, 400);
+        g.__lastGpuError = msg.slice(0, 300);
+        console.error('[wgpu-kit particles] GPU 错误:', msg);
+    });
+    return {
+        config: cfg,
+        async attach(canvas) {
+            const dpr = Math.min(window.devicePixelRatio || 1, 2);
+            canvas.width = Math.max(1, Math.floor(canvas.clientWidth * dpr));
+            canvas.height = Math.max(1, Math.floor(canvas.clientHeight * dpr));
+            renderer = await ParticlesRenderer.create(canvas, {
+                count: cfg.count, species, vel: sideA.vel,
+                color: cfg.color, pointSize: cfg.pointSize * worldHalf, worldHalf,
+            });
+        },
+        tick(dtMultiplier = 1) {
+            const dt = cfg.dt * dtMultiplier;
+            writeUniform(dt);
+            const useAB = frame % 2 === 0;
+            const read = useAB ? sideA : sideB;
+            if (gridBindGroupsDirty && grid) {
+                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()]);
+            }
+            else {
+                pass.setPipeline(simPipeline);
+                pass.setBindGroup(0, useAB ? bgAB : bgBA);
+                pass.dispatchWorkgroups(Math.ceil(cfg.count / WORKGROUP));
+                pass.end();
+                device.queue.submit([enc.finish()]);
+            }
+            // 渲染刚写入的一侧(队列顺序保证 compute 先行),再翻转
+            // 渲染刚写入的一侧(useAB 时写入 other;!useAB 时写入 current)——
+            // 旧代码相位错位,隔帧才显示新状态(v0.9.7 引入的回归,评审 #4)
+            const writtenSide = useAB ? pp.other : pp.current;
+            renderer?.render(writtenSide.pos, writtenSide.vel);
+            pp.swap();
+            frame++;
+            // 内置轻量 fps 统计(playground/harness 都直接读)
+            fpsFrames++;
+            const now = performance.now();
+            fpsAcc += now - fpsLast;
+            fpsLast = now;
+            if (fpsAcc >= 500) {
+                lastFps = fpsFrames / (fpsAcc / 1000);
+                fpsFrames = 0;
+                fpsAcc = 0;
+            }
+        },
+        setForces(forces) {
+            const m = resolveMatrix(forces, hashSeed(cfg.seed));
+            matrix.write(new Float32Array(m));
+            cfg.forces = m;
+            cfg.forcesName = typeof forces === 'string' ? forces : 'custom';
+        },
+        setParams(p) {
+            Object.assign(phys, p);
+            if (grid && p.rMax !== undefined) {
+                const g = gridSizeOf(phys.rMax);
+                if (g !== gridSize) {
+                    gridSize = g;
+                    // 版本号 + 原子切换:重建期间旧 grid 继续服务(不再有"新 gridSize × 旧缓冲"窗口);
+                    // 连续调用只有最后一次生效,被超越/被替换的 grid 统一销毁,不泄漏
+                    const version = ++gridBuildVersion;
+                    void (async () => {
+                        const fresh = await buildGrid(gridSize);
+                        if (version !== gridBuildVersion) {
+                            gridDestroy(fresh);
+                            return; // 已有更新版本的重建完成,丢弃本份
+                        }
+                        const old = grid;
+                        grid = fresh;
+                        fresh.bgForceCellRebuild(sideA.pos); // 用当前侧重建 forceCell 绑定组(AB/BA 双向齐备)
+                        if (old)
+                            gridDestroy(old);
+                    })();
+                }
+            }
+        },
+        snapshot() {
+            return JSON.stringify({
+                count: cfg.count, forces: cfg.forcesName, mode: cfg.mode, color: cfg.color,
+                bounds: cfg.bounds, seed: cfg.seed, rMax: phys.rMax, beta: phys.beta,
+                forceFactor: phys.forceFactor, frictionHalfLife: phys.frictionHalfLife, dt: phys.dt,
+                pointSize: cfg.pointSize,
+            });
+        },
+        stats() {
+            return { fps: lastFps, gpuErrors: gpuErrorCount };
+        },
+        debugGrid: grid
+            ? () => {
+                const g = grid;
+                return { partial: g.partial, start: g.start, fill: g.fill, sortedPos: g.sortedPos, sortedSp: g.sortedSp, order: g.order };
+            }
+            : undefined,
+        buffers() {
+            return { pos: pp.current.pos, vel: pp.current.vel, species };
+        },
+        destroy() {
+            renderer?.destroy();
+            pp.destroy();
+            species.destroy();
+            matrix.destroy();
+            uniform.destroy();
+            if (grid) {
+                grid.count.destroy();
+                grid.start.destroy();
+                grid.fill.destroy();
+                grid.order.destroy();
+                grid.partial.destroy();
+                grid.sortedPos.destroy();
+                grid.sortedSp.destroy();
+            }
+        },
+    };
+}