insomni 0.2.0-alpha.0

package/dist/particles.mjs

@@ -0,0 +1,4804 @@
+import { n as resolveRoot } from "./root-CHradZKM.mjs";
+import { A as DEPTH_FORMAT, _ as TAU, t as ALPHA_BLEND } from "./pipeline-BWCAZTKx.mjs";
+import { i as SPATIAL_HASH_PARAMS_WGSL } from "./spatial-hash-C1crBjTo.mjs";
+const PREPARE_INDIRECT_WGSL = `
+@group(0) @binding(0) var<storage, read>       aliveCount   : u32;
+@group(0) @binding(1) var<storage, read_write> dispatchArgs : array<u32, 3>;
+@group(0) @binding(2) var<storage, read_write> drawArgs     : array<u32, 4>;
+
+@compute @workgroup_size(1)
+fn main() {
+  let n = aliveCount;
+  dispatchArgs[0] = (n + 64u - 1u) / 64u;
+  dispatchArgs[1] = 1u;
+  dispatchArgs[2] = 1u;
+
+  // drawIndirect: [vertexCount, instanceCount, firstVertex, firstInstance]
+  drawArgs[0] = 6u;
+  drawArgs[1] = n;
+  drawArgs[2] = 0u;
+  drawArgs[3] = 0u;
+}
+`;
+const BOUNDS_WGSL = `
+struct BoundsParams {
+  min:         vec2f,
+  max:         vec2f,
+  mode:        u32,
+  restitution: f32,
+  _pad0:       u32,
+  _pad1:       u32,
+};
+
+@group(0) @binding(0) var<storage, read_write> positions:  array<vec2f>;
+@group(0) @binding(1) var<storage, read_write> velocities: array<vec2f>;
+@group(0) @binding(2) var<storage, read>       alive:      array<u32>;
+@group(0) @binding(3) var<storage, read>       aliveCount: u32;
+@group(0) @binding(4) var<uniform>             params:     BoundsParams;
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  if (i >= aliveCount) { return; }
+  if (alive[i] == 0u) { return; }
+  if (params.mode == 0u) { return; }
+
+  var p = positions[i];
+  var v = velocities[i];
+  let lo = params.min;
+  let hi = params.max;
+  let size = hi - lo;
+
+  if (params.mode == 1u) {
+    if (p.x < lo.x) { p.x = lo.x; v.x = 0.0; }
+    else if (p.x > hi.x) { p.x = hi.x; v.x = 0.0; }
+    if (p.y < lo.y) { p.y = lo.y; v.y = 0.0; }
+    else if (p.y > hi.y) { p.y = hi.y; v.y = 0.0; }
+  } else if (params.mode == 2u) {
+    // Fully vectorised modulo — handles arbitrary excursions (e.g. huge dt).
+    let rel = (p - lo) - size * floor((p - lo) / size);
+    p = lo + rel;
+  } else if (params.mode == 3u) {
+    let r = params.restitution;
+    if (p.x < lo.x) { p.x = lo.x; v.x = -v.x * r; }
+    else if (p.x > hi.x) { p.x = hi.x; v.x = -v.x * r; }
+    if (p.y < lo.y) { p.y = lo.y; v.y = -v.y * r; }
+    else if (p.y > hi.y) { p.y = hi.y; v.y = -v.y * r; }
+  }
+
+  positions[i] = p;
+  velocities[i] = v;
+}
+`;
+//#endregion
+//#region src/particles/bounds.ts
+var BoundsPipeline = class {
+	device;
+	mode;
+	paramsBuffer;
+	bindGroup;
+	pipeline;
+	constructor(root, state, mode, label = "particles.bounds") {
+		this.device = root.device;
+		this.mode = mode;
+		if (mode.kind === "none") {
+			this.paramsBuffer = null;
+			this.bindGroup = null;
+			this.pipeline = null;
+			return;
+		}
+		this.paramsBuffer = this.device.createBuffer({
+			label: `${label}.params`,
+			size: 32,
+			usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+		});
+		const scratch = /* @__PURE__ */ new ArrayBuffer(32);
+		const f = new Float32Array(scratch);
+		const u = new Uint32Array(scratch);
+		f[0] = mode.rect[0];
+		f[1] = mode.rect[1];
+		f[2] = mode.rect[2];
+		f[3] = mode.rect[3];
+		u[4] = encodeMode(mode);
+		f[5] = mode.kind === "bounce" ? mode.restitution ?? .8 : 0;
+		this.device.queue.writeBuffer(this.paramsBuffer, 0, scratch);
+		const layout = this.device.createBindGroupLayout({
+			label: `${label}.layout`,
+			entries: [
+				{
+					binding: 0,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "storage" }
+				},
+				{
+					binding: 1,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "storage" }
+				},
+				{
+					binding: 2,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 3,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 4,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "uniform" }
+				}
+			]
+		});
+		this.bindGroup = this.device.createBindGroup({
+			label: `${label}.group`,
+			layout,
+			entries: [
+				{
+					binding: 0,
+					resource: { buffer: state.builtins.positions }
+				},
+				{
+					binding: 1,
+					resource: { buffer: state.builtins.velocities }
+				},
+				{
+					binding: 2,
+					resource: { buffer: state.builtins.alive }
+				},
+				{
+					binding: 3,
+					resource: { buffer: state.builtins.aliveCount }
+				},
+				{
+					binding: 4,
+					resource: { buffer: this.paramsBuffer }
+				}
+			]
+		});
+		this.pipeline = this.device.createComputePipeline({
+			label: `${label}.pipeline`,
+			layout: this.device.createPipelineLayout({
+				label: `${label}.pipelineLayout`,
+				bindGroupLayouts: [layout]
+			}),
+			compute: {
+				module: this.device.createShaderModule({
+					label: `${label}.shader`,
+					code: BOUNDS_WGSL
+				}),
+				entryPoint: "main"
+			}
+		});
+	}
+	/** Record one bounds dispatch. No-op when mode is `none`. */
+	record(pass, dispatchArgs) {
+		if (!this.pipeline || !this.bindGroup) return;
+		pass.setPipeline(this.pipeline);
+		pass.setBindGroup(0, this.bindGroup);
+		pass.dispatchWorkgroupsIndirect(dispatchArgs, 0);
+	}
+	destroy() {
+		this.paramsBuffer?.destroy();
+	}
+	get isNoop() {
+		return this.mode.kind === "none";
+	}
+};
+function encodeMode(mode) {
+	switch (mode.kind) {
+		case "none": return 0;
+		case "clamp": return 1;
+		case "wrap": return 2;
+		case "bounce": return 3;
+	}
+}
+//#endregion
+//#region src/particles/codegen/pipeline-cache.ts
+var PipelineCache = class {
+	cache = /* @__PURE__ */ new Map();
+	/**
+	* Return the pipeline for `key`, calling `factory()` to build it on miss.
+	* Factories are only invoked on cold lookups.
+	*/
+	getOrCreate(key, factory) {
+		const existing = this.cache.get(key);
+		if (existing !== void 0) return existing;
+		const fresh = factory();
+		this.cache.set(key, fresh);
+		return fresh;
+	}
+	/** Current cache size — useful for tests and introspection. */
+	get size() {
+		return this.cache.size;
+	}
+	/**
+	* Drop every cached pipeline. WebGPU pipelines are reference-counted and
+	* released when the JS handle becomes unreferenced; nothing extra needed.
+	*/
+	clear() {
+		this.cache.clear();
+	}
+};
+const COMPACT_ELEMENTS_PER_BLOCK = 256 * 4;
+/**
+* Maximum capacity supported by the single-workgroup Pass B below. A larger
+* capacity would require a hierarchical third pass; rejected at system
+* construction to keep the compaction module simple.
+*/
+const COMPACT_MAX_CAPACITY = 256 * COMPACT_ELEMENTS_PER_BLOCK;
+const COMPACT_SCAN_LOCAL_WGSL = `
+struct ScanParams {
+  capacity: u32,
+  _pad0:    u32,
+  _pad1:    u32,
+  _pad2:    u32,
+};
+
+@group(0) @binding(0) var<storage, read>       alive:       array<u32>;
+@group(0) @binding(1) var<storage, read_write> scanLocal:   array<u32>;
+@group(0) @binding(2) var<storage, read_write> blockTotals: array<u32>;
+@group(0) @binding(3) var<uniform>             params:      ScanParams;
+
+const BLOCK_SIZE: u32 = 256u;
+const ELEMENTS_PER_THREAD: u32 = 4u;
+const ELEMENTS_PER_BLOCK: u32 = ${COMPACT_ELEMENTS_PER_BLOCK}u;
+
+var<workgroup> threadSums: array<u32, 256>;
+
+@compute @workgroup_size(256)
+fn main(
+  @builtin(local_invocation_id) lid: vec3u,
+  @builtin(workgroup_id)        wid: vec3u,
+) {
+  let tid = lid.x;
+  let base = wid.x * ELEMENTS_PER_BLOCK + tid * ELEMENTS_PER_THREAD;
+
+  // Phase 1 — read my 4 flags, serially accumulate an exclusive prefix of
+  // just this thread's values. \`local[k]\` = sum of my flags strictly before k.
+  var local: array<u32, 4>;
+  var threadSum: u32 = 0u;
+  for (var k: u32 = 0u; k < ELEMENTS_PER_THREAD; k = k + 1u) {
+    let gi = base + k;
+    var v: u32 = 0u;
+    if (gi < params.capacity) {
+      if (alive[gi] != 0u) { v = 1u; }
+    }
+    local[k] = threadSum;
+    threadSum = threadSum + v;
+  }
+
+  // Phase 2 — Hillis-Steele inclusive scan across threadSums. Two barriers
+  // per iteration (read-before-write then write-before-read) — WGSL does not
+  // permit racing loads with stores.
+  threadSums[tid] = threadSum;
+  workgroupBarrier();
+  for (var offset: u32 = 1u; offset < BLOCK_SIZE; offset = offset << 1u) {
+    var t: u32 = 0u;
+    if (tid >= offset) {
+      t = threadSums[tid - offset];
+    }
+    workgroupBarrier();
+    threadSums[tid] = threadSums[tid] + t;
+    workgroupBarrier();
+  }
+
+  let threadInclusive = threadSums[tid];
+  let threadExclusive = threadInclusive - threadSum;
+
+  // Phase 3 — emit per-element block-local exclusive prefix.
+  for (var k: u32 = 0u; k < ELEMENTS_PER_THREAD; k = k + 1u) {
+    let gi = base + k;
+    if (gi < params.capacity) {
+      scanLocal[gi] = threadExclusive + local[k];
+    }
+  }
+
+  // Thread 255 holds the block's inclusive total (= sum of all flags in the
+  // 1024-element block). Write it once.
+  if (tid == BLOCK_SIZE - 1u) {
+    blockTotals[wid.x] = threadInclusive;
+  }
+}
+`;
+const COMPACT_SCAN_BLOCKS_WGSL = `
+struct BlocksParams {
+  blockCount: u32,
+  _pad0:      u32,
+  _pad1:      u32,
+  _pad2:      u32,
+};
+
+@group(0) @binding(0) var<storage, read>       blockTotals:  array<u32>;
+@group(0) @binding(1) var<storage, read_write> blockOffsets: array<u32>;
+@group(0) @binding(2) var<storage, read_write> aliveCount:   atomic<u32>;
+@group(0) @binding(3) var<uniform>             params:       BlocksParams;
+
+const BLOCK_SIZE_B: u32 = 256u;
+
+var<workgroup> sdata: array<u32, 256>;
+
+@compute @workgroup_size(256)
+fn main(@builtin(local_invocation_id) lid: vec3u) {
+  let tid = lid.x;
+  let n = params.blockCount;
+
+  var v: u32 = 0u;
+  if (tid < n) {
+    v = blockTotals[tid];
+  }
+  sdata[tid] = v;
+  workgroupBarrier();
+
+  for (var offset: u32 = 1u; offset < BLOCK_SIZE_B; offset = offset << 1u) {
+    var t: u32 = 0u;
+    if (tid >= offset) {
+      t = sdata[tid - offset];
+    }
+    workgroupBarrier();
+    sdata[tid] = sdata[tid] + t;
+    workgroupBarrier();
+  }
+
+  let inclusive = sdata[tid];
+  let exclusive = inclusive - v;
+
+  if (tid < n) {
+    blockOffsets[tid] = exclusive;
+  }
+
+  // Last *valid* thread writes the grand total. For n==0 nothing writes,
+  // but construction guarantees capacity > 0 → n >= 1.
+  if (n > 0u && tid == n - 1u) {
+    atomicStore(&aliveCount, inclusive);
+  }
+}
+`;
+//#endregion
+//#region src/particles/kernels/compact-alive-rewrite.ts
+const COMPACT_ALIVE_REWRITE_WGSL = `
+struct Params {
+  capacity: u32,
+  _pad0:    u32,
+  _pad1:    u32,
+  _pad2:    u32,
+};
+
+@group(0) @binding(0) var<storage, read_write> alive:      array<u32>;
+@group(0) @binding(1) var<storage, read>       aliveCount: u32;
+@group(0) @binding(2) var<uniform>             params:     Params;
+
+@compute @workgroup_size(256)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  if (i >= params.capacity) { return; }
+  alive[i] = select(0u, 1u, i < aliveCount);
+}
+`;
+//#endregion
+//#region src/particles/kernels/compact-scatter.ts
+/**
+* Build a scatter kernel for `wgslType`. Kernels are cached by type in the
+* `CompactionPipeline` harness — two `f32` attributes (say, `age` and
+* `charge`) share the same pipeline object, they just bind different buffers.
+*/
+function buildCompactScatterWGSL(wgslType) {
+	return `
+struct ScatterParams {
+  capacity: u32,
+  _pad0:    u32,
+  _pad1:    u32,
+  _pad2:    u32,
+};
+
+@group(0) @binding(0) var<storage, read>       src:          array<${wgslType}>;
+@group(0) @binding(1) var<storage, read_write> dst:          array<${wgslType}>;
+@group(0) @binding(2) var<storage, read>       alive:        array<u32>;
+@group(0) @binding(3) var<storage, read>       scanLocal:    array<u32>;
+@group(0) @binding(4) var<storage, read>       blockOffsets: array<u32>;
+@group(0) @binding(5) var<uniform>             params:       ScatterParams;
+
+const ELEMENTS_PER_BLOCK: u32 = ${COMPACT_ELEMENTS_PER_BLOCK}u;
+
+@compute @workgroup_size(256)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let srcIdx = gid.x;
+  if (srcIdx >= params.capacity) { return; }
+  if (alive[srcIdx] == 0u) { return; }
+
+  let dstIdx = scanLocal[srcIdx] + blockOffsets[srcIdx / ELEMENTS_PER_BLOCK];
+  dst[dstIdx] = src[srcIdx];
+}
+`;
+}
+//#endregion
+//#region src/particles/compaction.ts
+var CompactionPipeline = class {
+	device;
+	state;
+	dispatchWorkgroups;
+	scanLocalParams;
+	scanLocalBindGroup;
+	scanLocalPipeline;
+	scanBlocksParams;
+	scanBlocksBindGroup;
+	scanBlocksPipeline;
+	scatterParams;
+	scatterLayout;
+	scatterPipelineByType = /* @__PURE__ */ new Map();
+	scatterEntries;
+	aliveRewriteParams;
+	aliveRewriteBindGroup;
+	aliveRewritePipeline;
+	constructor(root, state, label = "particles.compaction") {
+		this.device = root.device;
+		this.state = state;
+		this.dispatchWorkgroups = Math.ceil(state.capacity / 256);
+		this.scanLocalParams = this.createParamsBuffer(`${label}.scanLocal.params`, 16);
+		writeU32Params(this.device, this.scanLocalParams, [
+			state.capacity,
+			0,
+			0,
+			0
+		]);
+		{
+			const layout = this.device.createBindGroupLayout({
+				label: `${label}.scanLocal.layout`,
+				entries: [
+					{
+						binding: 0,
+						visibility: GPUShaderStage.COMPUTE,
+						buffer: { type: "read-only-storage" }
+					},
+					{
+						binding: 1,
+						visibility: GPUShaderStage.COMPUTE,
+						buffer: { type: "storage" }
+					},
+					{
+						binding: 2,
+						visibility: GPUShaderStage.COMPUTE,
+						buffer: { type: "storage" }
+					},
+					{
+						binding: 3,
+						visibility: GPUShaderStage.COMPUTE,
+						buffer: { type: "uniform" }
+					}
+				]
+			});
+			this.scanLocalBindGroup = this.device.createBindGroup({
+				label: `${label}.scanLocal.group`,
+				layout,
+				entries: [
+					{
+						binding: 0,
+						resource: { buffer: state.builtins.alive }
+					},
+					{
+						binding: 1,
+						resource: { buffer: state.compaction.scanLocal }
+					},
+					{
+						binding: 2,
+						resource: { buffer: state.compaction.blockTotals }
+					},
+					{
+						binding: 3,
+						resource: { buffer: this.scanLocalParams }
+					}
+				]
+			});
+			this.scanLocalPipeline = this.device.createComputePipeline({
+				label: `${label}.scanLocal.pipeline`,
+				layout: this.device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+				compute: {
+					module: this.device.createShaderModule({
+						label: `${label}.scanLocal.shader`,
+						code: COMPACT_SCAN_LOCAL_WGSL
+					}),
+					entryPoint: "main"
+				}
+			});
+		}
+		this.scanBlocksParams = this.createParamsBuffer(`${label}.scanBlocks.params`, 16);
+		writeU32Params(this.device, this.scanBlocksParams, [
+			state.compaction.blockCount,
+			0,
+			0,
+			0
+		]);
+		{
+			const layout = this.device.createBindGroupLayout({
+				label: `${label}.scanBlocks.layout`,
+				entries: [
+					{
+						binding: 0,
+						visibility: GPUShaderStage.COMPUTE,
+						buffer: { type: "read-only-storage" }
+					},
+					{
+						binding: 1,
+						visibility: GPUShaderStage.COMPUTE,
+						buffer: { type: "storage" }
+					},
+					{
+						binding: 2,
+						visibility: GPUShaderStage.COMPUTE,
+						buffer: { type: "storage" }
+					},
+					{
+						binding: 3,
+						visibility: GPUShaderStage.COMPUTE,
+						buffer: { type: "uniform" }
+					}
+				]
+			});
+			this.scanBlocksBindGroup = this.device.createBindGroup({
+				label: `${label}.scanBlocks.group`,
+				layout,
+				entries: [
+					{
+						binding: 0,
+						resource: { buffer: state.compaction.blockTotals }
+					},
+					{
+						binding: 1,
+						resource: { buffer: state.compaction.blockOffsets }
+					},
+					{
+						binding: 2,
+						resource: { buffer: state.builtins.aliveCount }
+					},
+					{
+						binding: 3,
+						resource: { buffer: this.scanBlocksParams }
+					}
+				]
+			});
+			this.scanBlocksPipeline = this.device.createComputePipeline({
+				label: `${label}.scanBlocks.pipeline`,
+				layout: this.device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+				compute: {
+					module: this.device.createShaderModule({
+						label: `${label}.scanBlocks.shader`,
+						code: COMPACT_SCAN_BLOCKS_WGSL
+					}),
+					entryPoint: "main"
+				}
+			});
+		}
+		this.scatterParams = this.createParamsBuffer(`${label}.scatter.params`, 16);
+		writeU32Params(this.device, this.scatterParams, [
+			state.capacity,
+			0,
+			0,
+			0
+		]);
+		this.scatterLayout = this.device.createBindGroupLayout({
+			label: `${label}.scatter.layout`,
+			entries: [
+				{
+					binding: 0,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 1,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "storage" }
+				},
+				{
+					binding: 2,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 3,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 4,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 5,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "uniform" }
+				}
+			]
+		});
+		this.scatterEntries = state.scatteredAttributes.map((attr) => {
+			const pipeline = this.getOrBuildScatterPipeline(attr.wgslType, label);
+			return {
+				attr,
+				bindGroup: this.device.createBindGroup({
+					label: `${label}.scatter.${attr.name}.group`,
+					layout: this.scatterLayout,
+					entries: [
+						{
+							binding: 0,
+							resource: { buffer: attr.main }
+						},
+						{
+							binding: 1,
+							resource: { buffer: attr.scratch }
+						},
+						{
+							binding: 2,
+							resource: { buffer: state.builtins.alive }
+						},
+						{
+							binding: 3,
+							resource: { buffer: state.compaction.scanLocal }
+						},
+						{
+							binding: 4,
+							resource: { buffer: state.compaction.blockOffsets }
+						},
+						{
+							binding: 5,
+							resource: { buffer: this.scatterParams }
+						}
+					]
+				}),
+				pipeline
+			};
+		});
+		this.aliveRewriteParams = this.createParamsBuffer(`${label}.aliveRewrite.params`, 16);
+		writeU32Params(this.device, this.aliveRewriteParams, [
+			state.capacity,
+			0,
+			0,
+			0
+		]);
+		{
+			const layout = this.device.createBindGroupLayout({
+				label: `${label}.aliveRewrite.layout`,
+				entries: [
+					{
+						binding: 0,
+						visibility: GPUShaderStage.COMPUTE,
+						buffer: { type: "storage" }
+					},
+					{
+						binding: 1,
+						visibility: GPUShaderStage.COMPUTE,
+						buffer: { type: "read-only-storage" }
+					},
+					{
+						binding: 2,
+						visibility: GPUShaderStage.COMPUTE,
+						buffer: { type: "uniform" }
+					}
+				]
+			});
+			this.aliveRewriteBindGroup = this.device.createBindGroup({
+				label: `${label}.aliveRewrite.group`,
+				layout,
+				entries: [
+					{
+						binding: 0,
+						resource: { buffer: state.builtins.alive }
+					},
+					{
+						binding: 1,
+						resource: { buffer: state.builtins.aliveCount }
+					},
+					{
+						binding: 2,
+						resource: { buffer: this.aliveRewriteParams }
+					}
+				]
+			});
+			this.aliveRewritePipeline = this.device.createComputePipeline({
+				label: `${label}.aliveRewrite.pipeline`,
+				layout: this.device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+				compute: {
+					module: this.device.createShaderModule({
+						label: `${label}.aliveRewrite.shader`,
+						code: COMPACT_ALIVE_REWRITE_WGSL
+					}),
+					entryPoint: "main"
+				}
+			});
+		}
+	}
+	/**
+	* Record every compute-pass dispatch for one compaction. Does NOT record
+	* the copyback — caller ends the pass then calls `recordCopyback` on the
+	* same encoder.
+	*/
+	record(pass) {
+		pass.setPipeline(this.scanLocalPipeline);
+		pass.setBindGroup(0, this.scanLocalBindGroup);
+		pass.dispatchWorkgroups(this.state.compaction.blockCount);
+		pass.setPipeline(this.scanBlocksPipeline);
+		pass.setBindGroup(0, this.scanBlocksBindGroup);
+		pass.dispatchWorkgroups(1);
+		for (const entry of this.scatterEntries) {
+			pass.setPipeline(entry.pipeline);
+			pass.setBindGroup(0, entry.bindGroup);
+			pass.dispatchWorkgroups(this.dispatchWorkgroups);
+		}
+		pass.setPipeline(this.aliveRewritePipeline);
+		pass.setBindGroup(0, this.aliveRewriteBindGroup);
+		pass.dispatchWorkgroups(this.dispatchWorkgroups);
+	}
+	/**
+	* Copy every scratch buffer back into its main attribute buffer. Must be
+	* called on the same encoder after `record()`, after the compute pass has
+	* ended. Cost scales with total attribute bytes × capacity — 1-2 MB per
+	* step at our target scales, which is well under a millisecond on any
+	* GPU that supports WebGPU.
+	*/
+	recordCopyback(encoder) {
+		for (const entry of this.scatterEntries) encoder.copyBufferToBuffer(entry.attr.scratch, 0, entry.attr.main, 0, this.state.capacity * entry.attr.strideBytes);
+	}
+	destroy() {
+		this.scanLocalParams.destroy();
+		this.scanBlocksParams.destroy();
+		this.scatterParams.destroy();
+		this.aliveRewriteParams.destroy();
+	}
+	createParamsBuffer(label, size) {
+		return this.device.createBuffer({
+			label,
+			size,
+			usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+		});
+	}
+	getOrBuildScatterPipeline(wgslType, label) {
+		const existing = this.scatterPipelineByType.get(wgslType);
+		if (existing) return existing;
+		const pipeline = this.device.createComputePipeline({
+			label: `${label}.scatter.${wgslType}.pipeline`,
+			layout: this.device.createPipelineLayout({ bindGroupLayouts: [this.scatterLayout] }),
+			compute: {
+				module: this.device.createShaderModule({
+					label: `${label}.scatter.${wgslType}.shader`,
+					code: buildCompactScatterWGSL(wgslType)
+				}),
+				entryPoint: "main"
+			}
+		});
+		this.scatterPipelineByType.set(wgslType, pipeline);
+		return pipeline;
+	}
+};
+/**
+* Small helper to initialise a static uniform buffer with a 4×u32 payload.
+* Every compaction params buffer is fixed at construction (capacity / block
+* count never change during a system's lifetime), so we write once and forget.
+*/
+function writeU32Params(device, buffer, values) {
+	const scratch = new Uint32Array(buffer.size / 4);
+	for (let i = 0; i < values.length; i++) scratch[i] = values[i] ?? 0;
+	device.queue.writeBuffer(buffer, 0, scratch);
+}
+//#endregion
+//#region src/particles/kernels/integrate.ts
+const INTEGRATE_WGSL = `
+struct IntegrateParams {
+  dt:        f32,
+  _pad0:     f32,
+  _pad1:     f32,
+  _pad2:     f32,
+};
+
+@group(0) @binding(0) var<storage, read_write> positions:  array<vec2f>;
+@group(0) @binding(1) var<storage, read_write> velocities: array<vec2f>;
+@group(0) @binding(2) var<storage, read_write> accelPrev:  array<vec2f>;
+@group(0) @binding(3) var<storage, read>       accel:      array<vec2f>;
+@group(0) @binding(4) var<storage, read_write> ages:       array<f32>;
+@group(0) @binding(5) var<storage, read>       lifetimes:  array<f32>;
+@group(0) @binding(6) var<storage, read_write> alive:      array<u32>;
+@group(0) @binding(7) var<storage, read>       aliveCount: u32;
+@group(0) @binding(8) var<uniform>             params:     IntegrateParams;
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  if (i >= aliveCount) { return; }
+  if (alive[i] == 0u) { return; }
+
+  let dt = params.dt;
+  let aPrev = accelPrev[i];
+  let a = accel[i];
+  let v = velocities[i];
+
+  positions[i]  = positions[i] + v * dt + 0.5 * aPrev * dt * dt;
+  velocities[i] = v + 0.5 * (aPrev + a) * dt;
+  accelPrev[i]  = a;
+
+  let newAge = ages[i] + dt;
+  ages[i] = newAge;
+  if (newAge >= lifetimes[i]) {
+    alive[i] = 0u;
+  }
+}
+`;
+//#endregion
+//#region src/particles/integrator.ts
+var IntegratorPipeline = class {
+	device;
+	paramsBuffer;
+	bindGroup;
+	pipeline;
+	scratch = new Float32Array(16 / 4);
+	constructor(root, state, label = "particles.integrate") {
+		this.device = root.device;
+		this.paramsBuffer = this.device.createBuffer({
+			label: `${label}.params`,
+			size: 16,
+			usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+		});
+		const layout = this.device.createBindGroupLayout({
+			label: `${label}.layout`,
+			entries: [
+				{
+					binding: 0,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "storage" }
+				},
+				{
+					binding: 1,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "storage" }
+				},
+				{
+					binding: 2,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "storage" }
+				},
+				{
+					binding: 3,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 4,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "storage" }
+				},
+				{
+					binding: 5,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 6,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "storage" }
+				},
+				{
+					binding: 7,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 8,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "uniform" }
+				}
+			]
+		});
+		this.bindGroup = this.device.createBindGroup({
+			label: `${label}.group`,
+			layout,
+			entries: [
+				{
+					binding: 0,
+					resource: { buffer: state.builtins.positions }
+				},
+				{
+					binding: 1,
+					resource: { buffer: state.builtins.velocities }
+				},
+				{
+					binding: 2,
+					resource: { buffer: state.builtins.accelPrev }
+				},
+				{
+					binding: 3,
+					resource: { buffer: state.builtins.accel }
+				},
+				{
+					binding: 4,
+					resource: { buffer: state.builtins.ages }
+				},
+				{
+					binding: 5,
+					resource: { buffer: state.builtins.lifetimes }
+				},
+				{
+					binding: 6,
+					resource: { buffer: state.builtins.alive }
+				},
+				{
+					binding: 7,
+					resource: { buffer: state.builtins.aliveCount }
+				},
+				{
+					binding: 8,
+					resource: { buffer: this.paramsBuffer }
+				}
+			]
+		});
+		this.pipeline = this.device.createComputePipeline({
+			label: `${label}.pipeline`,
+			layout: this.device.createPipelineLayout({
+				label: `${label}.pipelineLayout`,
+				bindGroupLayouts: [layout]
+			}),
+			compute: {
+				module: this.device.createShaderModule({
+					label: `${label}.shader`,
+					code: INTEGRATE_WGSL
+				}),
+				entryPoint: "main"
+			}
+		});
+	}
+	/**
+	* Record one integration dispatch. Caller supplies the shared dispatch-args
+	* buffer populated by `prepareIndirect` earlier in the frame.
+	*/
+	record(pass, dispatchArgs, dt) {
+		this.scratch[0] = dt;
+		this.scratch[1] = 0;
+		this.scratch[2] = 0;
+		this.scratch[3] = 0;
+		this.device.queue.writeBuffer(this.paramsBuffer, 0, this.scratch);
+		pass.setPipeline(this.pipeline);
+		pass.setBindGroup(0, this.bindGroup);
+		pass.dispatchWorkgroupsIndirect(dispatchArgs, 0);
+	}
+	destroy() {
+		this.paramsBuffer.destroy();
+	}
+};
+//#endregion
+//#region src/particles/attributes.ts
+const ATTRIBUTE_TYPE_INFO = {
+	f32: {
+		wgsl: "f32",
+		strideBytes: 4,
+		integer: false,
+		scalarCount: 1
+	},
+	u32: {
+		wgsl: "u32",
+		strideBytes: 4,
+		integer: true,
+		scalarCount: 1
+	},
+	i32: {
+		wgsl: "i32",
+		strideBytes: 4,
+		integer: true,
+		scalarCount: 1
+	},
+	vec2f: {
+		wgsl: "vec2f",
+		strideBytes: 8,
+		integer: false,
+		scalarCount: 2
+	},
+	vec3f: {
+		wgsl: "vec3f",
+		strideBytes: 16,
+		integer: false,
+		scalarCount: 3
+	},
+	vec4f: {
+		wgsl: "vec4f",
+		strideBytes: 16,
+		integer: false,
+		scalarCount: 4
+	},
+	vec2u: {
+		wgsl: "vec2u",
+		strideBytes: 8,
+		integer: true,
+		scalarCount: 2
+	},
+	vec4u: {
+		wgsl: "vec4u",
+		strideBytes: 16,
+		integer: true,
+		scalarCount: 4
+	}
+};
+/** Names owned by the system; user attributes cannot shadow these. */
+const RESERVED_ATTRIBUTE_NAMES = new Set([
+	"position",
+	"velocity",
+	"accel",
+	"accelPrev",
+	"age",
+	"lifetime",
+	"alive",
+	"aliveCount",
+	"index"
+]);
+/**
+* Validate a user-supplied catalog. Throws on:
+*   • unknown / unsupported type literals
+*   • names that collide with built-ins (§ `RESERVED_ATTRIBUTE_NAMES`)
+*   • names that are empty or would be invalid WGSL identifiers
+*
+* Returns the catalog unchanged on success so callers can chain.
+*/
+function validateAttributeCatalog(catalog) {
+	for (const [name, type] of Object.entries(catalog)) {
+		if (!name) throw new Error("ParticleSystem: attribute name must be non-empty");
+		if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) throw new Error(`ParticleSystem: attribute name '${name}' must be a valid identifier`);
+		if (RESERVED_ATTRIBUTE_NAMES.has(name)) throw new Error(`ParticleSystem: attribute '${name}' collides with a built-in. Reserved: ${[...RESERVED_ATTRIBUTE_NAMES].join(", ")}.`);
+		if (!(type in ATTRIBUTE_TYPE_INFO)) throw new Error(`ParticleSystem: attribute '${name}' has unsupported type '${type}'. Supported: ${Object.keys(ATTRIBUTE_TYPE_INFO).join(", ")}.`);
+	}
+	return catalog;
+}
+/** WGSL type literal (e.g. `vec2f`). */
+function attributeWgslType(type) {
+	return ATTRIBUTE_TYPE_INFO[type].wgsl;
+}
+//#endregion
+//#region src/particles/kernels/atomic-accel.ts
+const ATOMIC_ACCEL_WGSL = `
+fn atomicAddF32(slot: u32, v: f32) {
+  loop {
+    let old_u = atomicLoad(&accel[slot]);
+    let new_u = bitcast<u32>(bitcast<f32>(old_u) + v);
+    let r = atomicCompareExchangeWeak(&accel[slot], old_u, new_u);
+    if (r.exchanged) { break; }
+  }
+}
+
+fn addAccel(particleIndex: u32, delta: vec2f) {
+  atomicAddF32(particleIndex * 2u + 0u, delta.x);
+  atomicAddF32(particleIndex * 2u + 1u, delta.y);
+}
+`;
+//#endregion
+//#region src/particles/codegen/attributes.ts
+/**
+* Stable, sorted list of (name, type) for the catalog. Used both to emit
+* bindings deterministically and to hash pipeline-cache keys.
+*/
+function catalogEntries(catalog) {
+	return Object.entries(catalog).map(([k, v]) => [k, v]);
+}
+/**
+* Shadow-safe identifier for a bound attribute. Appending `_` avoids WGSL
+* keyword collisions for names like `alignment`, `sample`, etc., and keeps
+* the struct field name (`species`) distinct from the array binding
+* (`species_`).
+*/
+function bindingName(attrName) {
+	return `${attrName}_`;
+}
+//#endregion
+//#region src/particles/emitter.ts
+function samplePosition(shape, i, count, rand = Math.random) {
+	switch (shape.kind) {
+		case "point": {
+			const at = typeof shape.at === "function" ? shape.at() : shape.at;
+			return [at[0], at[1]];
+		}
+		case "disc": {
+			const theta = rand() * TAU;
+			const r = Math.sqrt(rand()) * shape.radius;
+			return [shape.center[0] + Math.cos(theta) * r, shape.center[1] + Math.sin(theta) * r];
+		}
+		case "ring": {
+			const theta = rand() * TAU;
+			const thickness = shape.thickness ?? 0;
+			const r = shape.radius + (rand() - .5) * thickness;
+			return [shape.center[0] + Math.cos(theta) * r, shape.center[1] + Math.sin(theta) * r];
+		}
+		case "rect": return [shape.min[0] + rand() * (shape.max[0] - shape.min[0]), shape.min[1] + rand() * (shape.max[1] - shape.min[1])];
+		case "line": {
+			const t = rand();
+			return [shape.a[0] + t * (shape.b[0] - shape.a[0]), shape.a[1] + t * (shape.b[1] - shape.a[1])];
+		}
+		case "grid": {
+			const cols = Math.max(1, shape.cols);
+			const rows = Math.max(1, shape.rows);
+			const idx = i % (cols * rows);
+			const col = idx % cols;
+			const row = Math.floor(idx / cols);
+			const sp = shape.spacing;
+			const sx = typeof sp === "number" ? sp : sp[0];
+			const sy = typeof sp === "number" ? sp : sp[1];
+			return [shape.origin[0] + (col - (cols - 1) * .5) * sx, shape.origin[1] + (row - (rows - 1) * .5) * sy];
+		}
+		case "fn": return shape.fn(i, count);
+	}
+}
+function sampleVelocity(shape, i, count, origin, rand = Math.random) {
+	if (!shape) return [0, 0];
+	switch (shape.kind) {
+		case "zero": return [0, 0];
+		case "uniform": return [shape.value[0], shape.value[1]];
+		case "random": {
+			const [sMin, sMax] = shape.speed;
+			const speed = sMin + rand() * (sMax - sMin);
+			const theta = rand() * TAU;
+			return [Math.cos(theta) * speed, Math.sin(theta) * speed];
+		}
+		case "cone": {
+			const [sMin, sMax] = shape.speed;
+			const speed = sMin + rand() * (sMax - sMin);
+			const dir = typeof shape.dir === "function" ? shape.dir() : shape.dir;
+			const theta = Math.atan2(dir[1], dir[0]) + (rand() - .5) * shape.spread;
+			return [Math.cos(theta) * speed, Math.sin(theta) * speed];
+		}
+		case "tangential": {
+			const [sMin, sMax] = shape.speed;
+			const speed = sMin + rand() * (sMax - sMin);
+			const dx = origin[0] - shape.center[0];
+			const dy = origin[1] - shape.center[1];
+			const len = Math.hypot(dx, dy);
+			if (len < 1e-6) return [0, 0];
+			const sign = shape.ccw === false ? -1 : 1;
+			return [-dy / len * speed * sign, dx / len * speed * sign];
+		}
+		case "fn": return shape.fn(i, count);
+	}
+}
+function sampleScalarRange(range, rand = Math.random) {
+	if (range === void 0) return Infinity;
+	if (typeof range === "number") return range;
+	return range[0] + rand() * (range[1] - range[0]);
+}
+/**
+* Resolve an attribute sampler to the concrete scalar values written to
+* staging. Always returns exactly `scalarCount` numbers. Integer attribute
+* types are truncated to 32-bit integers at pack time, not here.
+*/
+function sampleAttribute(sampler, type, i, count, rand = Math.random) {
+	const n = ATTRIBUTE_TYPE_INFO[type].scalarCount;
+	const out = Array.from({ length: n }, () => 0);
+	if (sampler === void 0) return out;
+	if (typeof sampler === "function") {
+		const v = sampler(i, count);
+		if (typeof v === "number") out[0] = v;
+		else for (let k = 0; k < n && k < v.length; k++) out[k] = v[k] ?? 0;
+		return out;
+	}
+	if (typeof sampler === "number") {
+		out[0] = sampler;
+		return out;
+	}
+	if (Array.isArray(sampler)) {
+		if (n === 1 && sampler.length === 2) {
+			const a = sampler[0] ?? 0;
+			const b = sampler[1] ?? 0;
+			out[0] = a + rand() * (b - a);
+			return out;
+		}
+		for (let k = 0; k < n && k < sampler.length; k++) out[k] = sampler[k] ?? 0;
+		return out;
+	}
+	return out;
+}
+/**
+* F32-slot stride for the emit staging buffer given a catalog. Built-ins
+* occupy the first 5 slots; each user attribute adds `scalarCount` slots
+* (vec3f packs tight as 3 slots in staging — the GPU buffer pads to 4 when
+* the kernel writes `vec3f(...)`).
+*/
+function emitStagingStride(catalog) {
+	let stride = 5;
+	for (const [, type] of catalogEntries(catalog)) stride += ATTRIBUTE_TYPE_INFO[type].scalarCount;
+	return stride;
+}
+/**
+* Per-attribute staging offset (in f32 slots, relative to the particle base).
+* Returns a map `{ attrName -> offsetF32 }` in catalog declaration order.
+*/
+function emitStagingOffsets(catalog) {
+	const offsets = {};
+	let cursor = 5;
+	for (const [name, type] of catalogEntries(catalog)) {
+		offsets[name] = cursor;
+		cursor += ATTRIBUTE_TYPE_INFO[type].scalarCount;
+	}
+	return offsets;
+}
+/**
+* Write one spec's worth of staging data into `out` starting at `offsetF32`.
+*
+* `out` is the Float32Array view over the shared staging backing buffer;
+* integer attributes are written through `outU32` (a Uint32Array view over
+* the same buffer) so their bit pattern survives unchanged — the WGSL emit
+* kernel bitcasts them back to `u32`/`i32`.
+*/
+function packEmitBatch(out, outU32, offsetF32, spec, catalog = {}, rand = Math.random) {
+	const stride = emitStagingStride(catalog);
+	const offsets = emitStagingOffsets(catalog);
+	const count = Math.min(spec.count, (out.length - offsetF32) / stride) | 0;
+	const entries = catalogEntries(catalog);
+	for (let i = 0; i < count; i++) {
+		const pos = samplePosition(spec.position, i, count, rand);
+		const vel = sampleVelocity(spec.velocity, i, count, pos, rand);
+		const life = sampleScalarRange(spec.lifetime, rand);
+		const base = offsetF32 + i * stride;
+		out[base + 0] = pos[0];
+		out[base + 1] = pos[1];
+		out[base + 2] = vel[0];
+		out[base + 3] = vel[1];
+		out[base + 4] = life;
+		for (const [name, type] of entries) {
+			const info = ATTRIBUTE_TYPE_INFO[type];
+			const values = sampleAttribute(spec.attributes?.[name], type, i, count, rand);
+			const slot = base + (offsets[name] ?? 0);
+			if (info.integer) for (let k = 0; k < info.scalarCount; k++) outU32[slot + k] = Math.trunc(values[k] ?? 0) | 0;
+			else for (let k = 0; k < info.scalarCount; k++) out[slot + k] = values[k] ?? 0;
+		}
+	}
+}
+/**
+* Generate the emit kernel WGSL for a given catalog. For an empty catalog
+* this matches the pre-codegen kernel — built-ins only.
+*/
+function generateEmitWgsl(catalog) {
+	const entries = catalogEntries(catalog);
+	const offsets = emitStagingOffsets(catalog);
+	const stride = emitStagingStride(catalog);
+	const userBindings = [];
+	const userWrites = [];
+	for (let i = 0; i < entries.length; i++) {
+		const entry = entries[i];
+		if (entry === void 0) continue;
+		const [name, type] = entry;
+		const info = ATTRIBUTE_TYPE_INFO[type];
+		const binding = 9 + i;
+		const bindName = `${name}_`;
+		userBindings.push(`@group(0) @binding(${binding}) var<storage, read_write> ${bindName} : array<${info.wgsl}>;`);
+		const off = offsets[name] ?? 0;
+		userWrites.push(`  ${bindName}[dst] = ${readAttrExpr(type, off)};`);
+	}
+	return `
+struct EmitParams {
+  capacity: u32,
+  _pad0:    u32,
+  _pad1:    u32,
+  _pad2:    u32,
+};
+
+@group(0) @binding(0) var<storage, read_write> positions:  array<vec2f>;
+@group(0) @binding(1) var<storage, read_write> velocities: array<vec2f>;
+@group(0) @binding(2) var<storage, read_write> accelPrev:  array<vec2f>;
+@group(0) @binding(3) var<storage, read_write> ages:       array<f32>;
+@group(0) @binding(4) var<storage, read_write> lifetimes:  array<f32>;
+@group(0) @binding(5) var<storage, read_write> alive:      array<u32>;
+@group(0) @binding(6) var<storage, read>       staging:    array<f32>;
+@group(0) @binding(7) var<storage, read>       reserve:    array<u32, 2>;
+@group(0) @binding(8) var<uniform>             params:     EmitParams;
+${userBindings.length > 0 ? "\n" + userBindings.join("\n") : ""}
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  let count = reserve[1];
+  if (i >= count) {
+    return;
+  }
+  let dst = reserve[0] + i;
+  if (dst >= params.capacity) {
+    return;
+  }
+
+  let base = i * ${stride}u;
+  positions[dst]  = vec2f(staging[base + 0u], staging[base + 1u]);
+  velocities[dst] = vec2f(staging[base + 2u], staging[base + 3u]);
+  lifetimes[dst]  = staging[base + 4u];
+  ages[dst]       = 0.0;
+  accelPrev[dst]  = vec2f(0.0);
+  alive[dst]      = 1u;
+${userWrites.length > 0 ? "\n" + userWrites.join("\n") : ""}
+}
+`;
+}
+/**
+* WGSL expression that reads one attribute value from `staging` starting at
+* `offsetF32` slots past `base`. Integer attributes are stored bit-identically
+* in the staging f32 slots by `packEmitBatch`, so we `bitcast` back.
+*/
+function readAttrExpr(type, offsetF32) {
+	const o = (k) => `staging[base + ${offsetF32 + k}u]`;
+	switch (type) {
+		case "f32": return o(0);
+		case "u32": return `bitcast<u32>(${o(0)})`;
+		case "i32": return `bitcast<i32>(${o(0)})`;
+		case "vec2f": return `vec2f(${o(0)}, ${o(1)})`;
+		case "vec3f": return `vec3f(${o(0)}, ${o(1)}, ${o(2)})`;
+		case "vec4f": return `vec4f(${o(0)}, ${o(1)}, ${o(2)}, ${o(3)})`;
+		case "vec2u": return `vec2u(bitcast<u32>(${o(0)}), bitcast<u32>(${o(1)}))`;
+		case "vec4u": return `vec4u(bitcast<u32>(${o(0)}), bitcast<u32>(${o(1)}), bitcast<u32>(${o(2)}), bitcast<u32>(${o(3)}))`;
+	}
+}
+//#endregion
+//#region src/particles/kernels/emit-reserve.ts
+const EMIT_RESERVE_WGSL = `
+struct ReserveParams {
+  requestedCount: u32,
+  capacity:       u32,
+  _pad0:          u32,
+  _pad1:          u32,
+};
+
+@group(0) @binding(0) var<storage, read_write> aliveCount: atomic<u32>;
+@group(0) @binding(1) var<storage, read_write> reserve:    array<u32, 2>;
+@group(0) @binding(2) var<uniform>             params:     ReserveParams;
+
+@compute @workgroup_size(1)
+fn main() {
+  let before = atomicLoad(&aliveCount);
+  // Saturating clamp: if aliveCount is already at or past capacity, reserve 0.
+  let available = select(0u, params.capacity - before, before < params.capacity);
+  let actual = min(params.requestedCount, available);
+  reserve[0] = before;
+  reserve[1] = actual;
+  atomicStore(&aliveCount, before + actual);
+}
+`;
+//#endregion
+//#region src/particles/kernels/emit-pipeline.ts
+var EmitPipeline = class {
+	device;
+	state;
+	/** F32-slot stride per particle in the staging buffer. Depends on catalog. */
+	stagingStrideF32;
+	stagingBuffer;
+	stagingBackingBuffer;
+	stagingF32;
+	stagingU32;
+	reserveParams;
+	reserveBindGroup;
+	reservePipeline;
+	reserveScratch = new Uint32Array(16 / 4);
+	emitParams;
+	emitBindGroup;
+	emitPipeline;
+	constructor(root, state, label = "particles.emit") {
+		this.device = root.device;
+		this.state = state;
+		this.stagingStrideF32 = emitStagingStride(state.catalog);
+		const stagingSlots = state.capacity * this.stagingStrideF32;
+		const stagingBytes = Math.max(stagingSlots * 4, 16);
+		this.stagingBuffer = this.device.createBuffer({
+			label: `${label}.staging`,
+			size: stagingBytes,
+			usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
+		});
+		this.stagingBackingBuffer = /* @__PURE__ */ new ArrayBuffer(stagingSlots * 4);
+		this.stagingF32 = new Float32Array(this.stagingBackingBuffer);
+		this.stagingU32 = new Uint32Array(this.stagingBackingBuffer);
+		this.reserveParams = this.device.createBuffer({
+			label: `${label}.reserve.params`,
+			size: 16,
+			usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+		});
+		{
+			const layout = this.device.createBindGroupLayout({
+				label: `${label}.reserve.layout`,
+				entries: [
+					{
+						binding: 0,
+						visibility: GPUShaderStage.COMPUTE,
+						buffer: { type: "storage" }
+					},
+					{
+						binding: 1,
+						visibility: GPUShaderStage.COMPUTE,
+						buffer: { type: "storage" }
+					},
+					{
+						binding: 2,
+						visibility: GPUShaderStage.COMPUTE,
+						buffer: { type: "uniform" }
+					}
+				]
+			});
+			this.reserveBindGroup = this.device.createBindGroup({
+				label: `${label}.reserve.group`,
+				layout,
+				entries: [
+					{
+						binding: 0,
+						resource: { buffer: state.builtins.aliveCount }
+					},
+					{
+						binding: 1,
+						resource: { buffer: state.compaction.emitReserve }
+					},
+					{
+						binding: 2,
+						resource: { buffer: this.reserveParams }
+					}
+				]
+			});
+			this.reservePipeline = this.device.createComputePipeline({
+				label: `${label}.reserve.pipeline`,
+				layout: this.device.createPipelineLayout({ bindGroupLayouts: [layout] }),
+				compute: {
+					module: this.device.createShaderModule({
+						label: `${label}.reserve.shader`,
+						code: EMIT_RESERVE_WGSL
+					}),
+					entryPoint: "main"
+				}
+			});
+		}
+		this.emitParams = this.device.createBuffer({
+			label: `${label}.params`,
+			size: 16,
+			usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+		});
+		{
+			const scratch = new Uint32Array(16 / 4);
+			scratch[0] = state.capacity;
+			this.device.queue.writeBuffer(this.emitParams, 0, scratch);
+		}
+		{
+			const layoutEntries = [
+				...[
+					0,
+					1,
+					2,
+					3,
+					4,
+					5
+				].map((binding) => ({
+					binding,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "storage" }
+				})),
+				{
+					binding: 6,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 7,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 8,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "uniform" }
+				}
+			];
+			const bindEntries = [
+				{
+					binding: 0,
+					resource: { buffer: state.builtins.positions }
+				},
+				{
+					binding: 1,
+					resource: { buffer: state.builtins.velocities }
+				},
+				{
+					binding: 2,
+					resource: { buffer: state.builtins.accelPrev }
+				},
+				{
+					binding: 3,
+					resource: { buffer: state.builtins.ages }
+				},
+				{
+					binding: 4,
+					resource: { buffer: state.builtins.lifetimes }
+				},
+				{
+					binding: 5,
+					resource: { buffer: state.builtins.alive }
+				},
+				{
+					binding: 6,
+					resource: { buffer: this.stagingBuffer }
+				},
+				{
+					binding: 7,
+					resource: { buffer: state.compaction.emitReserve }
+				},
+				{
+					binding: 8,
+					resource: { buffer: this.emitParams }
+				}
+			];
+			for (const attr of state.userAttrs) {
+				const binding = 9 + attr.bindingIndex;
+				layoutEntries.push({
+					binding,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "storage" }
+				});
+				bindEntries.push({
+					binding,
+					resource: { buffer: attr.buffer }
+				});
+			}
+			const layout = this.device.createBindGroupLayout({
+				label: `${label}.layout`,
+				entries: layoutEntries
+			});
+			this.emitBindGroup = this.device.createBindGroup({
+				label: `${label}.group`,
+				layout,
+				entries: bindEntries
+			});
+			this.emitPipeline = this.device.createComputePipeline({
+				label: `${label}.pipeline`,
+				layout: this.device.createPipelineLayout({
+					label: `${label}.pipelineLayout`,
+					bindGroupLayouts: [layout]
+				}),
+				compute: {
+					module: this.device.createShaderModule({
+						label: `${label}.shader`,
+						code: generateEmitWgsl(state.catalog)
+					}),
+					entryPoint: "main"
+				}
+			});
+		}
+	}
+	/**
+	* Pack a batch of `spec` into the staging scratch starting at
+	* `stagingOffsetF32`. `count` is clamped only by staging-buffer room — the
+	* GPU-side capacity clamp now happens in the reserve kernel, so the CPU
+	* does not need to know the live aliveCount. Callers use the returned
+	* `count` to advance the staging cursor.
+	*/
+	packBatch(spec, stagingOffsetF32) {
+		const stagingRoom = Math.max(0, (this.stagingF32.length - stagingOffsetF32) / this.stagingStrideF32);
+		const count = Math.max(0, Math.min(spec.count, stagingRoom)) | 0;
+		if (count > 0) packEmitBatch(this.stagingF32, this.stagingU32, stagingOffsetF32, {
+			...spec,
+			count
+		}, this.state.catalog);
+		return {
+			spec,
+			count
+		};
+	}
+	/**
+	* Upload the packed staging buffer and dispatch reserve + emit for a
+	* contiguous run of `totalCount` particles. The GPU may clamp this to
+	* fewer particles if capacity is exhausted — the kernel's internal
+	* `i >= count` check covers that.
+	*/
+	flush(encoder, totalCount) {
+		if (totalCount <= 0) return;
+		const usedBytes = totalCount * this.stagingStrideF32 * 4;
+		this.device.queue.writeBuffer(this.stagingBuffer, 0, this.stagingBackingBuffer, 0, usedBytes);
+		this.reserveScratch[0] = totalCount;
+		this.reserveScratch[1] = this.state.capacity;
+		this.reserveScratch[2] = 0;
+		this.reserveScratch[3] = 0;
+		this.device.queue.writeBuffer(this.reserveParams, 0, this.reserveScratch);
+		const pass = encoder.beginComputePass({ label: "particles.emit.pass" });
+		pass.setPipeline(this.reservePipeline);
+		pass.setBindGroup(0, this.reserveBindGroup);
+		pass.dispatchWorkgroups(1);
+		pass.setPipeline(this.emitPipeline);
+		pass.setBindGroup(0, this.emitBindGroup);
+		const workgroups = Math.ceil(totalCount / 64);
+		pass.dispatchWorkgroups(workgroups);
+		pass.end();
+	}
+	destroy() {
+		this.stagingBuffer.destroy();
+		this.reserveParams.destroy();
+		this.emitParams.destroy();
+	}
+};
+//#endregion
+//#region src/particles/kernels/prepare-indirect-pipeline.ts
+var PrepareIndirectPipeline = class {
+	bindGroup;
+	pipeline;
+	constructor(root, state, label = "particles.prepareIndirect") {
+		const device = root.device;
+		const layout = device.createBindGroupLayout({
+			label: `${label}.layout`,
+			entries: [
+				{
+					binding: 0,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 1,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "storage" }
+				},
+				{
+					binding: 2,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "storage" }
+				}
+			]
+		});
+		this.bindGroup = device.createBindGroup({
+			label: `${label}.group`,
+			layout,
+			entries: [
+				{
+					binding: 0,
+					resource: { buffer: state.builtins.aliveCount }
+				},
+				{
+					binding: 1,
+					resource: { buffer: state.indirect.dispatchArgs }
+				},
+				{
+					binding: 2,
+					resource: { buffer: state.indirect.drawArgs }
+				}
+			]
+		});
+		this.pipeline = device.createComputePipeline({
+			label: `${label}.pipeline`,
+			layout: device.createPipelineLayout({
+				label: `${label}.pipelineLayout`,
+				bindGroupLayouts: [layout]
+			}),
+			compute: {
+				module: device.createShaderModule({
+					label: `${label}.shader`,
+					code: PREPARE_INDIRECT_WGSL
+				}),
+				entryPoint: "main"
+			}
+		});
+	}
+	record(pass) {
+		pass.setPipeline(this.pipeline);
+		pass.setBindGroup(0, this.bindGroup);
+		pass.dispatchWorkgroups(1);
+	}
+};
+//#endregion
+//#region src/particles/kernels/zero-accel.ts
+const ZERO_ACCEL_WGSL = `
+@group(0) @binding(0) var<storage, read_write> accel: array<atomic<u32>>;
+
+struct Params { count: u32, _pad0: u32, _pad1: u32, _pad2: u32 };
+@group(0) @binding(1) var<uniform> params: Params;
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  if (i >= params.count) {
+    return;
+  }
+  atomicStore(&accel[i], 0u);
+}
+`;
+//#endregion
+//#region src/particles/kernels/zero-accel-pipeline.ts
+const ZERO_ACCEL_PARAMS_BYTES = 16;
+var ZeroAccelPipeline = class {
+	bindGroup;
+	pipeline;
+	workgroupCount;
+	paramsBuffer;
+	device;
+	constructor(root, state, label = "particles.zeroAccel") {
+		this.device = root.device;
+		const slotCount = state.capacity * 2;
+		this.workgroupCount = Math.ceil(slotCount / 64);
+		this.paramsBuffer = this.device.createBuffer({
+			label: `${label}.params`,
+			size: ZERO_ACCEL_PARAMS_BYTES,
+			usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+		});
+		const scratch = new Uint32Array(ZERO_ACCEL_PARAMS_BYTES / 4);
+		scratch[0] = slotCount;
+		this.device.queue.writeBuffer(this.paramsBuffer, 0, scratch);
+		const layout = this.device.createBindGroupLayout({
+			label: `${label}.layout`,
+			entries: [{
+				binding: 0,
+				visibility: GPUShaderStage.COMPUTE,
+				buffer: { type: "storage" }
+			}, {
+				binding: 1,
+				visibility: GPUShaderStage.COMPUTE,
+				buffer: { type: "uniform" }
+			}]
+		});
+		this.bindGroup = this.device.createBindGroup({
+			label: `${label}.group`,
+			layout,
+			entries: [{
+				binding: 0,
+				resource: { buffer: state.builtins.accel }
+			}, {
+				binding: 1,
+				resource: { buffer: this.paramsBuffer }
+			}]
+		});
+		this.pipeline = this.device.createComputePipeline({
+			label: `${label}.pipeline`,
+			layout: this.device.createPipelineLayout({
+				label: `${label}.pipelineLayout`,
+				bindGroupLayouts: [layout]
+			}),
+			compute: {
+				module: this.device.createShaderModule({
+					label: `${label}.shader`,
+					code: ZERO_ACCEL_WGSL
+				}),
+				entryPoint: "main"
+			}
+		});
+	}
+	record(pass) {
+		pass.setPipeline(this.pipeline);
+		pass.setBindGroup(0, this.bindGroup);
+		pass.dispatchWorkgroups(this.workgroupCount);
+	}
+	destroy() {
+		this.paramsBuffer.destroy();
+	}
+};
+//#endregion
+//#region src/particles/render/shader.wgsl.ts
+/** Signed distance fn bodies in UV space (p ∈ [-1, 1]²; shape covers uv ≤ 0). */
+const BUILTIN_SHAPE_WGSL = {
+	circle: `return length(p) - 1.0;`,
+	square: `return max(abs(p.x), abs(p.y)) - 1.0;`,
+	triangle: `
+    let k = sqrt(3.0);
+    var q = vec2f(abs(p.x) - 0.8660254, p.y + 0.5);
+    if (q.x + k * q.y > 0.0) {
+      q = vec2f(q.x - k * q.y, -k * q.x - q.y) * 0.5;
+    }
+    q.x -= clamp(q.x, -1.7320508, 0.0);
+    return -length(q) * sign(q.y);`,
+	"rounded-square": `
+    let b = vec2f(0.75, 0.75);
+    let r = 0.25;
+    let q = abs(p) - b + vec2f(r);
+    return length(max(q, vec2f(0.0))) + min(max(q.x, q.y), 0.0) - r;`
+};
+function resolveShapeBody(shape) {
+	if (typeof shape === "string") return BUILTIN_SHAPE_WGSL[shape];
+	return shape.sdf;
+}
+function buildParticleRenderWgsl(opts) {
+	const shapeBody = resolveShapeBody(opts.shape);
+	const fadeMode = opts.fade;
+	const lutBindings = fadeMode === "lut" ? `
+@group(3) @binding(0) var lutTexture: texture_2d<f32>;
+@group(3) @binding(1) var lutSampler: sampler;
+` : "";
+	const fadeExpr = fadeMode === "none" ? `1.0` : fadeMode === "linear" ? `clamp(1.0 - t, 0.0, 1.0)` : `textureSampleLevel(lutTexture, lutSampler, vec2f(clamp(t, 0.0, 1.0), 0.5), 0.0).r`;
+	return `
+struct Camera {
+  vpCol0: vec2f,
+  vpCol1: vec2f,
+  vpCol2: vec2f,
+};
+
+struct RenderParams {
+  color:           vec4f,
+  size:            f32,
+  velocityStretch: f32,
+  fadeByAge:       f32,
+  _pad0:           f32,
+};
+
+struct Particle {
+  position: vec2f,
+  velocity: vec2f,
+  age:      f32,
+  lifetime: f32,
+  index:    u32,
+};
+
+@group(0) @binding(0) var<uniform> camera: Camera;
+
+@group(1) @binding(0) var<storage, read> positions:  array<vec2f>;
+@group(1) @binding(1) var<storage, read> alive:      array<u32>;
+@group(1) @binding(2) var<storage, read> velocities: array<vec2f>;
+@group(1) @binding(3) var<storage, read> ages:       array<f32>;
+@group(1) @binding(4) var<storage, read> lifetimes:  array<f32>;
+
+@group(2) @binding(0) var<uniform> render: RenderParams;
+${lutBindings}
+
+fn loadParticle(i: u32) -> Particle {
+  return Particle(positions[i], velocities[i], ages[i], lifetimes[i], i);
+}
+
+fn shapeSdf(p: vec2f) -> f32 {
+  ${shapeBody}
+}
+${opts.color === "uniform" ? `
+fn fragColor(p: Particle) -> vec4f {
+  return render.color;
+}` : `
+fn fragColor(p: Particle) -> vec4f {
+  ${opts.color.wgsl}
+}`}
+
+struct VOut {
+  @builtin(position) clip: vec4f,
+  @location(0) uv:    vec2f,
+  @location(1) aliveF: f32,
+  @location(2) alphaScale: f32,
+  @location(3) @interpolate(flat) iid: u32,
+};
+
+const QUAD: array<vec2f, 6> = array<vec2f, 6>(
+  vec2f(-1.0, -1.0),
+  vec2f( 1.0, -1.0),
+  vec2f(-1.0,  1.0),
+  vec2f( 1.0, -1.0),
+  vec2f( 1.0,  1.0),
+  vec2f(-1.0,  1.0),
+);
+
+@vertex
+fn vmain(
+  @builtin(vertex_index) vid: u32,
+  @builtin(instance_index) iid: u32,
+) -> VOut {
+  let corner = QUAD[vid];
+  let center = positions[iid];
+
+  var dir = vec2f(1.0, 0.0);
+  var perp = vec2f(0.0, 1.0);
+  var lengthScale = render.size;
+  let widthScale = render.size;
+  if (render.velocityStretch > 0.0) {
+    let v = velocities[iid];
+    let speed = length(v);
+    if (speed > 1e-4) {
+      dir = v / speed;
+      perp = vec2f(-dir.y, dir.x);
+      lengthScale = render.size + render.velocityStretch * speed;
+    }
+  }
+
+  let local = dir * (corner.x * lengthScale) + perp * (corner.y * widthScale);
+  let world = center + local;
+  let ndc = camera.vpCol0 * world.x + camera.vpCol1 * world.y + camera.vpCol2;
+
+  var out: VOut;
+  out.clip = vec4f(ndc, 0.5, 1.0);
+  out.uv = corner;
+  out.aliveF = select(0.0, 1.0, alive[iid] == 1u);
+
+  var alphaScale = 1.0;
+  if (render.fadeByAge > 0.5) {
+    let life = lifetimes[iid];
+    let t = ages[iid] / max(life, 1e-6);
+    alphaScale = ${fadeExpr};
+  }
+  out.alphaScale = alphaScale;
+  out.iid = iid;
+  return out;
+}
+
+@fragment
+fn fmain(in: VOut) -> @location(0) vec4f {
+  if (in.aliveF < 0.5) { discard; }
+
+  let d = shapeSdf(in.uv);
+  let aa = fwidth(d);
+  let coverage = 1.0 - smoothstep(-aa, aa, d);
+  if (coverage < 0.003) { discard; }
+
+  let p = loadParticle(in.iid);
+  let base = fragColor(p);
+  let a = base.a * coverage * in.alphaScale;
+  let rgb = base.rgb * a;
+  return vec4f(rgb, a);
+}
+`;
+}
+/**
+* Compile the render pipeline and allocate its render-side bind groups. The
+* compute-side bind groups in `state` use COMPUTE visibility; the render
+* pipeline needs VERTEX|FRAGMENT, so we build a parallel pair here.
+*/
+function createParticleRenderPipeline(opts) {
+	const { device, state, colorFormat, cameraBindGroupLayout, shader } = opts;
+	const label = opts.label ?? "particles.render";
+	const particleVisibility = GPUShaderStage.VERTEX | GPUShaderStage.FRAGMENT;
+	const particleBindGroupLayout = device.createBindGroupLayout({
+		label: `${label}.particleLayout`,
+		entries: [
+			0,
+			1,
+			2,
+			3,
+			4
+		].map((binding) => ({
+			binding,
+			visibility: particleVisibility,
+			buffer: { type: "read-only-storage" }
+		}))
+	});
+	const paramsBindGroupLayout = device.createBindGroupLayout({
+		label: `${label}.paramsLayout`,
+		entries: [{
+			binding: 0,
+			visibility: particleVisibility,
+			buffer: { type: "uniform" }
+		}]
+	});
+	const lutBindGroupLayout = shader.fade === "lut" ? device.createBindGroupLayout({
+		label: `${label}.lutLayout`,
+		entries: [{
+			binding: 0,
+			visibility: GPUShaderStage.VERTEX,
+			texture: {
+				sampleType: "float",
+				viewDimension: "2d"
+			}
+		}, {
+			binding: 1,
+			visibility: GPUShaderStage.VERTEX,
+			sampler: { type: "filtering" }
+		}]
+	}) : null;
+	const particleBindGroup = device.createBindGroup({
+		label: `${label}.particleGroup`,
+		layout: particleBindGroupLayout,
+		entries: [
+			{
+				binding: 0,
+				resource: { buffer: state.builtins.positions }
+			},
+			{
+				binding: 1,
+				resource: { buffer: state.builtins.alive }
+			},
+			{
+				binding: 2,
+				resource: { buffer: state.builtins.velocities }
+			},
+			{
+				binding: 3,
+				resource: { buffer: state.builtins.ages }
+			},
+			{
+				binding: 4,
+				resource: { buffer: state.builtins.lifetimes }
+			}
+		]
+	});
+	const paramsBuffer = device.createBuffer({
+		label: `${label}.params`,
+		size: 32,
+		usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+	});
+	const paramsBindGroup = device.createBindGroup({
+		label: `${label}.paramsGroup`,
+		layout: paramsBindGroupLayout,
+		entries: [{
+			binding: 0,
+			resource: { buffer: paramsBuffer }
+		}]
+	});
+	const module = device.createShaderModule({
+		label: `${label}.shader`,
+		code: buildParticleRenderWgsl(shader)
+	});
+	const bindGroupLayouts = [
+		cameraBindGroupLayout,
+		particleBindGroupLayout,
+		paramsBindGroupLayout
+	];
+	if (lutBindGroupLayout) bindGroupLayouts.push(lutBindGroupLayout);
+	const pipelineLayout = device.createPipelineLayout({
+		label: `${label}.pipelineLayout`,
+		bindGroupLayouts
+	});
+	return {
+		pipeline: device.createRenderPipeline({
+			label: `${label}.pipeline`,
+			layout: pipelineLayout,
+			vertex: {
+				module,
+				entryPoint: "vmain"
+			},
+			fragment: {
+				module,
+				entryPoint: "fmain",
+				targets: [{
+					format: colorFormat,
+					blend: ALPHA_BLEND
+				}]
+			},
+			primitive: {
+				topology: "triangle-list",
+				cullMode: "none"
+			},
+			depthStencil: {
+				format: DEPTH_FORMAT,
+				depthWriteEnabled: false,
+				depthCompare: "always"
+			},
+			multisample: { count: opts.sampleCount ?? 1 }
+		}),
+		particleBindGroupLayout,
+		paramsBindGroupLayout,
+		lutBindGroupLayout,
+		particleBindGroup,
+		paramsBindGroup,
+		paramsBuffer,
+		fade: shader.fade
+	};
+}
+/**
+* Pack a `RenderParams` struct into a writable view. Matches the WGSL layout:
+*   color:            vec4f  (offset 0,  16 bytes)
+*   size:             f32    (offset 16,  4 bytes)
+*   velocityStretch:  f32    (offset 20,  4 bytes)
+*   fadeByAge:        f32    (offset 24,  4 bytes) — 0 or 1
+*   _pad0             f32    (offset 28,  4 bytes)
+*/
+function writeRenderParams(buffer, opts) {
+	buffer[0] = opts.color[0];
+	buffer[1] = opts.color[1];
+	buffer[2] = opts.color[2];
+	buffer[3] = opts.color[3];
+	buffer[4] = opts.size;
+	buffer[5] = opts.velocityStretch ?? 0;
+	buffer[6] = opts.fadeEnabled ? 1 : 0;
+	buffer[7] = 0;
+}
+//#endregion
+//#region src/particles/render/drawable-v3.ts
+const DEFAULT_COLOR = {
+	r: 1,
+	g: 1,
+	b: 1,
+	a: 1
+};
+const DEFAULT_SIZE = 4;
+const LUT_SIZE = 64;
+function resolveShape(opt) {
+	return opt ?? "circle";
+}
+function resolveColor(opt) {
+	return opt.colorWgsl !== void 0 ? { wgsl: opt.colorWgsl } : "uniform";
+}
+function resolveFadeMode(opt) {
+	if (!opt) return "none";
+	if (opt === true) return "linear";
+	return "lut";
+}
+var ParticleDrawableV3 = class {
+	__customDrawable = true;
+	space;
+	clipRect = void 0;
+	opaque = false;
+	device;
+	bundle;
+	drawArgsBuffer;
+	scratch = new Float32Array(32 / 4);
+	lutTexture = null;
+	lutSampler = null;
+	lutBindGroup = null;
+	size;
+	color;
+	velocityStretch;
+	fadeByAge;
+	destroyed = false;
+	constructor(renderer, state, options = {}) {
+		this.device = renderer.device;
+		this.space = options.space ?? "world";
+		this.size = options.size ?? DEFAULT_SIZE;
+		this.color = options.color ?? DEFAULT_COLOR;
+		this.velocityStretch = options.velocityStretch ?? 0;
+		this.fadeByAge = options.fadeByAge ?? false;
+		this.drawArgsBuffer = state.indirect.drawArgs;
+		const fadeMode = resolveFadeMode(this.fadeByAge);
+		this.bundle = createParticleRenderPipeline({
+			device: this.device,
+			state,
+			colorFormat: renderer.colorFormat,
+			cameraBindGroupLayout: renderer.getCameraBindGroupLayout(),
+			shader: {
+				shape: resolveShape(options.shape),
+				color: resolveColor(options),
+				fade: fadeMode
+			},
+			sampleCount: 1
+		});
+		if (fadeMode === "lut" && this.bundle.lutBindGroupLayout) this.buildLut(typeof this.fadeByAge === "object" ? this.fadeByAge.curve : (t) => 1 - t);
+		this.uploadParams();
+	}
+	/**
+	* Replace color / size / stretch / fade flag. Takes effect on the next
+	* frame. Does NOT rebuild the pipeline — shape and colorWgsl are baked in
+	* at construction. Swapping a curve function re-uploads the LUT texture.
+	*/
+	setOptions(options) {
+		if (options.size !== void 0) this.size = options.size;
+		if (options.color !== void 0) this.color = options.color;
+		if (options.velocityStretch !== void 0) this.velocityStretch = options.velocityStretch;
+		if (options.fadeByAge !== void 0) {
+			const nextMode = resolveFadeMode(options.fadeByAge);
+			if (nextMode !== resolveFadeMode(this.fadeByAge)) throw new Error("ParticleDrawableV3.setOptions: fadeByAge mode (off/linear/curve) is baked into the pipeline at construction. Create a new drawable to switch.");
+			this.fadeByAge = options.fadeByAge;
+			if (nextMode === "lut" && typeof this.fadeByAge === "object") this.buildLut(this.fadeByAge.curve);
+		}
+		this.uploadParams();
+	}
+	record(pass, ctx) {
+		if (this.destroyed) return;
+		pass.setPipeline(this.bundle.pipeline);
+		pass.setBindGroup(0, ctx.cameraBindGroup);
+		pass.setBindGroup(1, this.bundle.particleBindGroup);
+		pass.setBindGroup(2, this.bundle.paramsBindGroup);
+		if (this.lutBindGroup) pass.setBindGroup(3, this.lutBindGroup);
+		pass.drawIndirect(this.drawArgsBuffer, 0);
+	}
+	destroy() {
+		if (this.destroyed) return;
+		this.bundle.paramsBuffer.destroy();
+		this.lutTexture?.destroy();
+		this.destroyed = true;
+	}
+	buildLut(curve) {
+		if (!this.lutTexture) {
+			this.lutTexture = this.device.createTexture({
+				label: "particles.render.ageLut",
+				size: {
+					width: LUT_SIZE,
+					height: 1
+				},
+				format: "r8unorm",
+				usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST
+			});
+			this.lutSampler = this.device.createSampler({
+				label: "particles.render.ageLutSampler",
+				magFilter: "linear",
+				minFilter: "linear",
+				addressModeU: "clamp-to-edge"
+			});
+			if (this.bundle.lutBindGroupLayout) this.lutBindGroup = this.device.createBindGroup({
+				label: "particles.render.ageLutGroup",
+				layout: this.bundle.lutBindGroupLayout,
+				entries: [{
+					binding: 0,
+					resource: this.lutTexture.createView()
+				}, {
+					binding: 1,
+					resource: this.lutSampler
+				}]
+			});
+		}
+		const bytes = new Uint8Array(LUT_SIZE);
+		for (let i = 0; i < LUT_SIZE; i++) {
+			const v = curve(i / (LUT_SIZE - 1));
+			bytes[i] = Math.max(0, Math.min(255, Math.round(v * 255)));
+		}
+		this.device.queue.writeTexture({ texture: this.lutTexture }, bytes, {
+			bytesPerRow: LUT_SIZE,
+			rowsPerImage: 1
+		}, {
+			width: LUT_SIZE,
+			height: 1
+		});
+	}
+	uploadParams() {
+		writeRenderParams(this.scratch, {
+			color: [
+				this.color.r,
+				this.color.g,
+				this.color.b,
+				this.color.a
+			],
+			size: this.size,
+			velocityStretch: this.velocityStretch,
+			fadeEnabled: !!this.fadeByAge
+		});
+		this.device.queue.writeBuffer(this.bundle.paramsBuffer, 0, this.scratch);
+	}
+};
+//#endregion
+//#region src/particles/spatial-hash.ts
+/**
+* Return an identifier usable as a map key for a `reach` request. Two forces
+* with reach values within 0.001 world-units share a hash.
+*/
+function quantizeReach(reach) {
+	return Math.round(reach * 1e3) / 1e3;
+}
+/**
+* Smallest power of two ≥ `n`, with a hard floor of 16 so the mask-based
+* bucket lookup never degenerates to 0.
+*/
+function nextPow2(n) {
+	let p = 16;
+	while (p < n) p <<= 1;
+	return p;
+}
+const CLEAR_WGSL = `${SPATIAL_HASH_PARAMS_WGSL}
+@group(0) @binding(0) var<storage, read_write> heads: array<atomic<u32>>;
+@group(0) @binding(1) var<uniform> params: SpatialHashParams;
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  if (i >= params.bucketCount) { return; }
+  atomicStore(&heads[i], EMPTY_SLOT);
+}
+`;
+const BUILD_WGSL = `${SPATIAL_HASH_PARAMS_WGSL}
+@group(0) @binding(0) var<storage, read_write> heads: array<atomic<u32>>;
+@group(0) @binding(1) var<storage, read_write> next: array<u32>;
+@group(0) @binding(2) var<storage, read_write> cells: array<vec2i>;
+@group(0) @binding(3) var<storage, read> positions: array<vec2f>;
+@group(0) @binding(4) var<storage, read> alive: array<u32>;
+@group(0) @binding(5) var<storage, read> aliveCount: u32;
+@group(0) @binding(6) var<uniform> params: SpatialHashParams;
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  if (i >= aliveCount) { return; }
+  next[i] = EMPTY_SLOT;
+  if (alive[i] == 0u) {
+    // Dead slot: park at a cell that can never match a live particle's 3×3
+    // neighbourhood (INT_MAX). Keeps the accumulate loop's cell-equality
+    // guard honest without an extra alive check per neighbour.
+    cells[i] = vec2i(2147483647, 2147483647);
+    return;
+  }
+  let cell = worldCell(positions[i], params.invCellSize);
+  cells[i] = cell;
+  let bucket = hashCell(cell, params.bucketMask);
+  let prev = atomicExchange(&heads[bucket], i);
+  next[i] = prev;
+}
+`;
+var ParticleSpatialHash = class {
+	reach;
+	cellSize;
+	bucketCount;
+	/** Buffers consumers bind in their accumulate kernels (heads/next/cells/params). */
+	consumeBindGroupLayout;
+	consumeBindGroup;
+	device;
+	heads;
+	next;
+	cells;
+	paramsBuffer;
+	clearBindGroup;
+	clearPipeline;
+	clearWorkgroups;
+	buildBindGroup;
+	buildPipeline;
+	constructor(opts) {
+		const { root, state, reach } = opts;
+		this.device = root.device;
+		this.reach = reach;
+		const cellSize = 2 * Math.max(reach, .001);
+		this.cellSize = cellSize;
+		this.bucketCount = nextPow2(Math.max(state.capacity * 4, 16));
+		this.clearWorkgroups = Math.ceil(this.bucketCount / 64);
+		const label = opts.label ?? `particles.hash.r${reach}`;
+		this.heads = this.device.createBuffer({
+			label: `${label}.heads`,
+			size: this.bucketCount * 4,
+			usage: GPUBufferUsage.STORAGE
+		});
+		this.next = this.device.createBuffer({
+			label: `${label}.next`,
+			size: Math.max(state.capacity, 4) * 4,
+			usage: GPUBufferUsage.STORAGE
+		});
+		this.cells = this.device.createBuffer({
+			label: `${label}.cells`,
+			size: Math.max(state.capacity, 2) * 8,
+			usage: GPUBufferUsage.STORAGE
+		});
+		this.paramsBuffer = this.device.createBuffer({
+			label: `${label}.params`,
+			size: 32,
+			usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+		});
+		{
+			const ab = /* @__PURE__ */ new ArrayBuffer(32);
+			const u = new Uint32Array(ab);
+			const f = new Float32Array(ab);
+			u[0] = 0;
+			u[1] = 0;
+			u[2] = this.bucketCount - 1;
+			u[3] = this.bucketCount;
+			f[4] = 1 / cellSize;
+			f[5] = 1;
+			f[6] = 0;
+			f[7] = 0;
+			this.device.queue.writeBuffer(this.paramsBuffer, 0, ab);
+		}
+		const clearLayout = this.device.createBindGroupLayout({
+			label: `${label}.clear.layout`,
+			entries: [{
+				binding: 0,
+				visibility: GPUShaderStage.COMPUTE,
+				buffer: { type: "storage" }
+			}, {
+				binding: 1,
+				visibility: GPUShaderStage.COMPUTE,
+				buffer: { type: "uniform" }
+			}]
+		});
+		this.clearBindGroup = this.device.createBindGroup({
+			label: `${label}.clear.group`,
+			layout: clearLayout,
+			entries: [{
+				binding: 0,
+				resource: { buffer: this.heads }
+			}, {
+				binding: 1,
+				resource: { buffer: this.paramsBuffer }
+			}]
+		});
+		this.clearPipeline = this.device.createComputePipeline({
+			label: `${label}.clear.pipeline`,
+			layout: this.device.createPipelineLayout({ bindGroupLayouts: [clearLayout] }),
+			compute: {
+				module: this.device.createShaderModule({
+					label: `${label}.clear.shader`,
+					code: CLEAR_WGSL
+				}),
+				entryPoint: "main"
+			}
+		});
+		const buildLayout = this.device.createBindGroupLayout({
+			label: `${label}.build.layout`,
+			entries: [
+				{
+					binding: 0,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "storage" }
+				},
+				{
+					binding: 1,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "storage" }
+				},
+				{
+					binding: 2,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "storage" }
+				},
+				{
+					binding: 3,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 4,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 5,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 6,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "uniform" }
+				}
+			]
+		});
+		this.buildBindGroup = this.device.createBindGroup({
+			label: `${label}.build.group`,
+			layout: buildLayout,
+			entries: [
+				{
+					binding: 0,
+					resource: { buffer: this.heads }
+				},
+				{
+					binding: 1,
+					resource: { buffer: this.next }
+				},
+				{
+					binding: 2,
+					resource: { buffer: this.cells }
+				},
+				{
+					binding: 3,
+					resource: { buffer: state.builtins.positions }
+				},
+				{
+					binding: 4,
+					resource: { buffer: state.builtins.alive }
+				},
+				{
+					binding: 5,
+					resource: { buffer: state.builtins.aliveCount }
+				},
+				{
+					binding: 6,
+					resource: { buffer: this.paramsBuffer }
+				}
+			]
+		});
+		this.buildPipeline = this.device.createComputePipeline({
+			label: `${label}.build.pipeline`,
+			layout: this.device.createPipelineLayout({ bindGroupLayouts: [buildLayout] }),
+			compute: {
+				module: this.device.createShaderModule({
+					label: `${label}.build.shader`,
+					code: BUILD_WGSL
+				}),
+				entryPoint: "main"
+			}
+		});
+		this.consumeBindGroupLayout = this.device.createBindGroupLayout({
+			label: `${label}.consume.layout`,
+			entries: [
+				{
+					binding: 0,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 1,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 2,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 3,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "uniform" }
+				}
+			]
+		});
+		this.consumeBindGroup = this.device.createBindGroup({
+			label: `${label}.consume.group`,
+			layout: this.consumeBindGroupLayout,
+			entries: [
+				{
+					binding: 0,
+					resource: { buffer: this.heads }
+				},
+				{
+					binding: 1,
+					resource: { buffer: this.next }
+				},
+				{
+					binding: 2,
+					resource: { buffer: this.cells }
+				},
+				{
+					binding: 3,
+					resource: { buffer: this.paramsBuffer }
+				}
+			]
+		});
+	}
+	/**
+	* Record clear + indirect build onto the open compute pass. Caller supplies
+	* the same `dispatchArgs` buffer `prepareIndirect` wrote this frame.
+	*/
+	record(pass, dispatchArgs) {
+		pass.setPipeline(this.clearPipeline);
+		pass.setBindGroup(0, this.clearBindGroup);
+		pass.dispatchWorkgroups(this.clearWorkgroups);
+		pass.setPipeline(this.buildPipeline);
+		pass.setBindGroup(0, this.buildBindGroup);
+		pass.dispatchWorkgroupsIndirect(dispatchArgs, 0);
+	}
+	destroy() {
+		this.heads.destroy();
+		this.next.destroy();
+		this.cells.destroy();
+		this.paramsBuffer.destroy();
+	}
+};
+/**
+* WGSL snippet declaring the consumer spatial-hash bindings at a given bind
+* group. Pairwise kernels embed this after the particle prelude.
+*/
+function spatialHashConsumerWgsl(group) {
+	return `${SPATIAL_HASH_PARAMS_WGSL}
+@group(${group}) @binding(0) var<storage, read> heads: array<u32>;
+@group(${group}) @binding(1) var<storage, read> next: array<u32>;
+@group(${group}) @binding(2) var<storage, read> cells: array<vec2i>;
+@group(${group}) @binding(3) var<uniform> hashParams: SpatialHashParams;
+`;
+}
+//#endregion
+//#region src/particles/state.ts
+const BUILTIN_STRIDES = {
+	positions: 8,
+	velocities: 8,
+	accelPrev: 8,
+	accel: 8,
+	ages: 4,
+	lifetimes: 4,
+	alive: 4
+};
+/**
+* Built-in attributes that must survive compaction. `accel` is excluded
+* because it is zeroed at the start of every step; `alive` is excluded
+* because the alive-rewrite pass regenerates it from the new count.
+*/
+const SCATTERED_BUILTINS = [
+	{
+		name: "positions",
+		wgslType: "vec2f",
+		strideBytes: 8
+	},
+	{
+		name: "velocities",
+		wgslType: "vec2f",
+		strideBytes: 8
+	},
+	{
+		name: "accelPrev",
+		wgslType: "vec2f",
+		strideBytes: 8
+	},
+	{
+		name: "ages",
+		wgslType: "f32",
+		strideBytes: 4
+	},
+	{
+		name: "lifetimes",
+		wgslType: "f32",
+		strideBytes: 4
+	}
+];
+function createParticleState(opts) {
+	const { root, capacity } = opts;
+	if (!Number.isInteger(capacity) || capacity <= 0) throw new Error(`ParticleSystem: capacity must be a positive integer (got ${capacity})`);
+	if (capacity > 262144) throw new Error(`ParticleSystem: capacity ${capacity} exceeds the single-pass-B scan limit (${COMPACT_MAX_CAPACITY}). Hierarchical scan is v2; lower the capacity or split into multiple systems.`);
+	const catalog = validateAttributeCatalog(opts.attributes ?? {});
+	const device = root.device;
+	const label = opts.label ?? "particles";
+	const builtins = {
+		positions: createStorage(device, `${label}.positions`, capacity * BUILTIN_STRIDES.positions),
+		velocities: createStorage(device, `${label}.velocities`, capacity * BUILTIN_STRIDES.velocities),
+		accelPrev: createStorage(device, `${label}.accelPrev`, capacity * BUILTIN_STRIDES.accelPrev),
+		accel: createStorage(device, `${label}.accel`, capacity * BUILTIN_STRIDES.accel),
+		ages: createStorage(device, `${label}.ages`, capacity * BUILTIN_STRIDES.ages),
+		lifetimes: createStorage(device, `${label}.lifetimes`, capacity * BUILTIN_STRIDES.lifetimes),
+		alive: createStorage(device, `${label}.alive`, capacity * BUILTIN_STRIDES.alive),
+		aliveCount: device.createBuffer({
+			label: `${label}.aliveCount`,
+			size: 4,
+			usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST
+		})
+	};
+	const indirect = {
+		dispatchArgs: device.createBuffer({
+			label: `${label}.dispatchArgs`,
+			size: 12,
+			usage: GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_DST
+		}),
+		drawArgs: device.createBuffer({
+			label: `${label}.drawArgs`,
+			size: 16,
+			usage: GPUBufferUsage.STORAGE | GPUBufferUsage.INDIRECT | GPUBufferUsage.COPY_DST
+		})
+	};
+	const userAttrs = catalogEntries(catalog).map(([name, type], i) => {
+		const info = ATTRIBUTE_TYPE_INFO[type];
+		return {
+			name,
+			type,
+			strideBytes: info.strideBytes,
+			bindingIndex: i,
+			buffer: createStorage(device, `${label}.attr.${name}`, capacity * info.strideBytes)
+		};
+	});
+	const stateBindGroupLayout = device.createBindGroupLayout({
+		label: `${label}.state.layout`,
+		entries: [
+			{
+				binding: 0,
+				visibility: GPUShaderStage.COMPUTE,
+				buffer: { type: "read-only-storage" }
+			},
+			{
+				binding: 1,
+				visibility: GPUShaderStage.COMPUTE,
+				buffer: { type: "read-only-storage" }
+			},
+			{
+				binding: 2,
+				visibility: GPUShaderStage.COMPUTE,
+				buffer: { type: "read-only-storage" }
+			},
+			{
+				binding: 3,
+				visibility: GPUShaderStage.COMPUTE,
+				buffer: { type: "storage" }
+			},
+			{
+				binding: 4,
+				visibility: GPUShaderStage.COMPUTE,
+				buffer: { type: "read-only-storage" }
+			},
+			{
+				binding: 5,
+				visibility: GPUShaderStage.COMPUTE,
+				buffer: { type: "read-only-storage" }
+			},
+			{
+				binding: 6,
+				visibility: GPUShaderStage.COMPUTE,
+				buffer: { type: "read-only-storage" }
+			},
+			{
+				binding: 7,
+				visibility: GPUShaderStage.COMPUTE,
+				buffer: { type: "storage" }
+			}
+		]
+	});
+	const userAttrBindGroupLayout = device.createBindGroupLayout({
+		label: `${label}.userAttrs.layout`,
+		entries: userAttrs.map((attr) => ({
+			binding: attr.bindingIndex,
+			visibility: GPUShaderStage.COMPUTE,
+			buffer: { type: "read-only-storage" }
+		}))
+	});
+	const stateBindGroup = device.createBindGroup({
+		label: `${label}.state.group`,
+		layout: stateBindGroupLayout,
+		entries: [
+			{
+				binding: 0,
+				resource: { buffer: builtins.positions }
+			},
+			{
+				binding: 1,
+				resource: { buffer: builtins.velocities }
+			},
+			{
+				binding: 2,
+				resource: { buffer: builtins.accelPrev }
+			},
+			{
+				binding: 3,
+				resource: { buffer: builtins.accel }
+			},
+			{
+				binding: 4,
+				resource: { buffer: builtins.ages }
+			},
+			{
+				binding: 5,
+				resource: { buffer: builtins.lifetimes }
+			},
+			{
+				binding: 6,
+				resource: { buffer: builtins.alive }
+			},
+			{
+				binding: 7,
+				resource: { buffer: builtins.aliveCount }
+			}
+		]
+	});
+	const userAttrBindGroup = device.createBindGroup({
+		label: `${label}.userAttrs.group`,
+		layout: userAttrBindGroupLayout,
+		entries: userAttrs.map((attr) => ({
+			binding: attr.bindingIndex,
+			resource: { buffer: attr.buffer }
+		}))
+	});
+	const builtinScatter = SCATTERED_BUILTINS.map((info) => ({
+		name: info.name,
+		wgslType: info.wgslType,
+		strideBytes: info.strideBytes,
+		main: builtins[info.name],
+		scratch: createStorage(device, `${label}.scratch.${info.name}`, capacity * info.strideBytes)
+	}));
+	const userScatter = userAttrs.map((attr) => ({
+		name: attr.name,
+		wgslType: ATTRIBUTE_TYPE_INFO[attr.type].wgsl,
+		strideBytes: attr.strideBytes,
+		main: attr.buffer,
+		scratch: createStorage(device, `${label}.scratch.attr.${attr.name}`, capacity * attr.strideBytes)
+	}));
+	const scatteredAttributes = [...builtinScatter, ...userScatter];
+	const blockCount = Math.ceil(capacity / COMPACT_ELEMENTS_PER_BLOCK);
+	const compaction = {
+		scanLocal: createStorage(device, `${label}.compaction.scanLocal`, capacity * 4),
+		blockTotals: createStorage(device, `${label}.compaction.blockTotals`, blockCount * 4),
+		blockOffsets: createStorage(device, `${label}.compaction.blockOffsets`, blockCount * 4),
+		emitReserve: createStorage(device, `${label}.compaction.emitReserve`, 8),
+		blockCount
+	};
+	return {
+		capacity,
+		catalog,
+		builtins,
+		indirect,
+		compaction,
+		userAttrs,
+		scatteredAttributes,
+		stateBindGroupLayout,
+		userAttrBindGroupLayout,
+		stateBindGroup,
+		userAttrBindGroup,
+		destroy() {
+			for (const b of Object.values(builtins)) b.destroy();
+			indirect.dispatchArgs.destroy();
+			indirect.drawArgs.destroy();
+			for (const attr of userAttrs) attr.buffer.destroy();
+			for (const attr of scatteredAttributes) attr.scratch.destroy();
+			compaction.scanLocal.destroy();
+			compaction.blockTotals.destroy();
+			compaction.blockOffsets.destroy();
+			compaction.emitReserve.destroy();
+		}
+	};
+}
+function createStorage(device, label, size) {
+	const paddedSize = Math.max(size, 16);
+	return device.createBuffer({
+		label,
+		size: paddedSize,
+		usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_SRC | GPUBufferUsage.COPY_DST
+	});
+}
+//#endregion
+//#region src/particles/system.ts
+/**
+* GPU particle system. Manages a fixed-capacity pool of particles with SoA
+* attribute storage, a pluggable force chain, CPU-driven emission, and
+* dedicated draw-indirect rendering.
+*
+* Typical usage:
+*
+* ```ts
+* const system = new ParticleSystem(renderer.getRoot(), {
+*   capacity: 20_000,
+*   bounds: { kind: "wrap", rect: [-400, -300, 400, 300] },
+* });
+* system.addForce(drag({ coefficient: 0.2 }));
+* system.addForce(gravity({ direction: [0, 1], strength: 300 }));
+* const drawable = system.createDrawable(renderer, { fadeByAge: true });
+*
+* // per frame:
+* system.emit({ count: 20, position: {...}, velocity: {...} });
+* system.step(dt);
+* renderer.render([drawable]);
+* ```
+*
+* Capacity is bounded at construction (no auto-grow). The compaction
+* module runs every step to keep the alive list dense; `getAliveCount()`
+* returns the GPU-authoritative count via a non-blocking readback.
+*/
+var ParticleSystem = class {
+	capacity;
+	/** Attribute names in declaration order. Binding indices match this order. */
+	attributeNames;
+	/** @internal — exposed for kernel attach in later phases. */
+	state;
+	/** @internal — shared across every pipeline this system compiles. */
+	pipelineCache = new PipelineCache();
+	root;
+	dt;
+	drawables = [];
+	emitQueue = [];
+	forces = [];
+	/** Spatial hashes keyed by quantized reach. Shared across pairwise forces. */
+	hashes = /* @__PURE__ */ new Map();
+	nextForceId = 1;
+	emitStagingCursor = 0;
+	emitPipeline = null;
+	prepareIndirectPipeline = null;
+	zeroAccelPipeline = null;
+	integratorPipeline = null;
+	boundsPipeline = null;
+	compactionPipeline = null;
+	aliveCountCache = 0;
+	aliveCountReadback = null;
+	aliveCountReadbackInFlight = false;
+	destroyed = false;
+	constructor(owner, options) {
+		this.options = options;
+		this.root = resolveRoot(owner);
+		this.state = createParticleState({
+			root: this.root,
+			capacity: options.capacity,
+			attributes: options.attributes
+		});
+		this.capacity = this.state.capacity;
+		this.attributeNames = this.state.userAttrs.map((a) => a.name);
+		this.dt = options.dt ?? 1 / 60;
+	}
+	getAttributeNames() {
+		return this.attributeNames;
+	}
+	/**
+	* Write raw data into a user-declared attribute buffer at the given element
+	* offset. Intended for one-shot initialisation (e.g. seeding `species` after
+	* emitting a fixed population) and interactive tooling — not a hot-path API;
+	* the emit kernel does not yet write user attributes, so callers that need
+	* per-emission attribute values fill them here directly.
+	*/
+	writeAttribute(name, data, offsetElements = 0) {
+		this.assertAlive();
+		const attr = this.state.userAttrs.find((a) => a.name === name);
+		if (!attr) throw new Error(`ParticleSystem.writeAttribute: '${name}' is not a declared attribute. Declared: ${this.attributeNames.join(", ") || "<none>"}.`);
+		this.root.device.queue.writeBuffer(attr.buffer, offsetElements * attr.strideBytes, data.buffer, data.byteOffset, data.byteLength);
+	}
+	/**
+	* Most recent live-particle count read from the GPU. aliveCount is
+	* GPU-authoritative — the CPU does not mirror it exactly — so this returns
+	* a cached value from the last completed readback. Calling this schedules
+	* a fresh readback in the background (non-blocking); repeated callers
+	* (e.g. a per-frame HUD) converge within one frame of latency. Returns 0
+	* until the first readback completes, which normally takes 1-2 frames.
+	*/
+	getAliveCount() {
+		if (this.destroyed) return this.aliveCountCache;
+		this.scheduleAliveCountReadback();
+		return this.aliveCountCache;
+	}
+	scheduleAliveCountReadback() {
+		if (this.aliveCountReadbackInFlight) return;
+		const device = this.root.device;
+		if (!this.aliveCountReadback) this.aliveCountReadback = device.createBuffer({
+			label: "particles.aliveCount.readback",
+			size: 4,
+			usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.COPY_DST
+		});
+		const encoder = device.createCommandEncoder({ label: "particles.aliveCount.encoder" });
+		encoder.copyBufferToBuffer(this.state.builtins.aliveCount, 0, this.aliveCountReadback, 0, 4);
+		device.queue.submit([encoder.finish()]);
+		this.aliveCountReadbackInFlight = true;
+		const buffer = this.aliveCountReadback;
+		buffer.mapAsync(GPUMapMode.READ).then(() => {
+			if (this.destroyed) return;
+			this.aliveCountCache = new Uint32Array(buffer.getMappedRange())[0] ?? 0;
+			buffer.unmap();
+		}).catch(() => {}).finally(() => {
+			this.aliveCountReadbackInFlight = false;
+		});
+	}
+	/**
+	* Build a `CustomDrawable` that renders this system's live particles.
+	* Pass to the v3 renderer's `render([...])`. Multiple drawables may share
+	* a system.
+	*/
+	createV3Drawable(renderer, options = {}) {
+		this.assertAlive();
+		const drawable = new ParticleDrawableV3(renderer, this.state, options);
+		this.drawables.push(drawable);
+		return drawable;
+	}
+	/**
+	* Queue an emission. CPU-packs now; the staging upload + reserve + emit
+	* dispatch run at the start of the next `step()`. Overflow past capacity
+	* is dropped silently on the GPU (the reserve kernel clamps to the
+	* remaining room). Multiple emits in one frame coalesce into one upload.
+	*/
+	emit(spec) {
+		if (this.destroyed) return;
+		if (spec.count <= 0) return;
+		const pipeline = this.ensureEmitPipeline();
+		const batch = pipeline.packBatch(spec, this.emitStagingCursor);
+		if (batch.count === 0) return;
+		this.emitQueue.push(batch);
+		this.emitStagingCursor += batch.count * pipeline.stagingStrideF32;
+	}
+	/**
+	* Attach a force. Returns a numeric id that can later be passed to
+	* `removeForce`. Forces run in registration order during each `step()`,
+	* accumulating into the per-particle acceleration buffer before the
+	* integrator sweep.
+	*/
+	addForce(force) {
+		this.assertAlive();
+		const id = this.nextForceId++;
+		const handle = force.attach({
+			root: this.root,
+			state: this.state,
+			label: `particles.force${id}`,
+			requestSpatialHash: (reach) => this.getOrCreateHash(reach)
+		});
+		this.forces.push({
+			id,
+			force,
+			handle
+		});
+		return id;
+	}
+	getOrCreateHash(reach) {
+		const key = quantizeReach(reach);
+		const existing = this.hashes.get(key);
+		if (existing) return existing;
+		const hash = new ParticleSpatialHash({
+			root: this.root,
+			state: this.state,
+			reach: key,
+			label: `particles.hash.r${key}`
+		});
+		this.hashes.set(key, hash);
+		return hash;
+	}
+	removeForce(id) {
+		const idx = this.forces.findIndex((f) => f.id === id);
+		if (idx < 0) return;
+		this.forces[idx].handle.destroy();
+		this.forces.splice(idx, 1);
+	}
+	hasForce(id) {
+		return this.forces.some((f) => f.id === id);
+	}
+	/**
+	* Advance the simulation by one tick. Records the full pipeline
+	* (emission → prepareIndirect → zeroAccel → forces → integrate → bounds
+	* → compaction + copyback) into a single command encoder and submits.
+	*
+	* `dt` overrides the system's configured timestep for this call only.
+	* Useful for variable-rate rendering (e.g. reduce dt when catching up on
+	* multiple frames).
+	*/
+	step(dt = this.dt) {
+		if (this.destroyed) return;
+		const encoder = this.root.device.createCommandEncoder({ label: "particles.step" });
+		if (this.pendingEmitCount() > 0) this.flushEmissions(encoder);
+		const dispatchArgs = this.state.indirect.dispatchArgs;
+		const pass = encoder.beginComputePass({ label: "particles.step.pass" });
+		this.ensurePrepareIndirect().record(pass);
+		this.ensureZeroAccel().record(pass);
+		for (const hash of this.hashes.values()) hash.record(pass, dispatchArgs);
+		const forceCtx = {
+			dispatchArgs,
+			dt
+		};
+		for (const { force, handle } of this.forces) {
+			force.prepare?.(forceCtx);
+			handle.record(pass, forceCtx);
+		}
+		this.ensureIntegrator().record(pass, dispatchArgs, dt);
+		this.ensureBounds().record(pass, dispatchArgs);
+		const compaction = this.ensureCompaction();
+		compaction.record(pass);
+		pass.end();
+		compaction.recordCopyback(encoder);
+		this.root.device.queue.submit([encoder.finish()]);
+	}
+	destroy() {
+		if (this.destroyed) return;
+		for (const d of this.drawables) d.destroy();
+		this.drawables.length = 0;
+		for (const { handle } of this.forces) handle.destroy();
+		this.forces.length = 0;
+		for (const hash of this.hashes.values()) hash.destroy();
+		this.hashes.clear();
+		this.emitPipeline?.destroy();
+		this.zeroAccelPipeline?.destroy();
+		this.integratorPipeline?.destroy();
+		this.boundsPipeline?.destroy();
+		this.compactionPipeline?.destroy();
+		this.aliveCountReadback?.destroy();
+		this.emitPipeline = null;
+		this.prepareIndirectPipeline = null;
+		this.zeroAccelPipeline = null;
+		this.integratorPipeline = null;
+		this.boundsPipeline = null;
+		this.compactionPipeline = null;
+		this.aliveCountReadback = null;
+		this.state.destroy();
+		this.pipelineCache.clear();
+		this.destroyed = true;
+	}
+	flushEmissions(encoder) {
+		const total = this.pendingEmitCount();
+		if (total === 0) return;
+		const pipeline = this.emitPipeline;
+		if (!pipeline) return;
+		pipeline.flush(encoder, total);
+		this.emitQueue.length = 0;
+		this.emitStagingCursor = 0;
+	}
+	ensureEmitPipeline() {
+		if (!this.emitPipeline) this.emitPipeline = new EmitPipeline(this.root, this.state);
+		return this.emitPipeline;
+	}
+	ensurePrepareIndirect() {
+		if (!this.prepareIndirectPipeline) this.prepareIndirectPipeline = new PrepareIndirectPipeline(this.root, this.state);
+		return this.prepareIndirectPipeline;
+	}
+	ensureZeroAccel() {
+		if (!this.zeroAccelPipeline) this.zeroAccelPipeline = new ZeroAccelPipeline(this.root, this.state);
+		return this.zeroAccelPipeline;
+	}
+	ensureIntegrator() {
+		if (!this.integratorPipeline) this.integratorPipeline = new IntegratorPipeline(this.root, this.state);
+		return this.integratorPipeline;
+	}
+	ensureBounds() {
+		if (!this.boundsPipeline) this.boundsPipeline = new BoundsPipeline(this.root, this.state, this.options.bounds ?? { kind: "none" });
+		return this.boundsPipeline;
+	}
+	ensureCompaction() {
+		if (!this.compactionPipeline) this.compactionPipeline = new CompactionPipeline(this.root, this.state);
+		return this.compactionPipeline;
+	}
+	pendingEmitCount() {
+		let n = 0;
+		for (const b of this.emitQueue) n += b.count;
+		return n;
+	}
+	assertAlive() {
+		if (this.destroyed) throw new Error("ParticleSystem: called on a destroyed system");
+	}
+};
+//#endregion
+//#region src/particles/forces/attractor.ts
+const ATTRACTOR_PARAMS_BYTES = 32;
+/** Falloff → integer code packed into the params uniform. */
+const FALLOFF_CODE = {
+	inverseSquare: 0,
+	linear: 1,
+	spring: 2
+};
+const ATTRACTOR_WGSL = `
+struct AttractorParams {
+  point:       vec2f,
+  strength:    f32,
+  reach:       f32,
+  falloffCode: u32,
+  _pad0:       u32,
+  _pad1:       u32,
+  _pad2:       u32,
+};
+
+@group(0) @binding(0) var<storage, read>       positions:  array<vec2f>;
+@group(0) @binding(1) var<storage, read_write> accel:      array<atomic<u32>>;
+@group(0) @binding(2) var<storage, read>       alive:      array<u32>;
+@group(0) @binding(3) var<storage, read>       aliveCount: u32;
+@group(0) @binding(4) var<uniform>             params:     AttractorParams;
+${ATOMIC_ACCEL_WGSL}
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  if (i >= aliveCount) { return; }
+  if (alive[i] == 0u) { return; }
+
+  let delta = params.point - positions[i];
+  let d2 = dot(delta, delta);
+  let reach2 = params.reach * params.reach;
+  if (params.reach > 0.0 && d2 > reach2) { return; }
+
+  var force = vec2f(0.0);
+  if (params.falloffCode == 2u) {
+    // Spring: F = k·delta. No singularity at the origin.
+    force = delta * params.strength;
+  } else {
+    let d = max(sqrt(d2), 1e-4);
+    let dir = delta / d;
+    if (params.falloffCode == 0u) {
+      // Inverse-square. Clamp d to avoid divergence at the point.
+      force = dir * (params.strength / max(d2, 1e-4));
+    } else {
+      // Linear: fade to 0 at reach (or at 1 world unit if no reach set).
+      let scale = select(1.0, 1.0 - d / params.reach, params.reach > 0.0);
+      force = dir * (params.strength * max(scale, 0.0));
+    }
+  }
+
+  atomicAddF32(i * 2u + 0u, force.x);
+  atomicAddF32(i * 2u + 1u, force.y);
+}
+`;
+/**
+* Radial attraction / repulsion around a fixed world point. Use negative
+* `strength` for repulsion. Falloff kinds control how force decays with
+* distance; `reach` optionally hard-clips beyond that radius.
+*/
+function attractor(options) {
+	return {
+		kind: "attractor",
+		attach(ctx) {
+			return new AttractorHandle(ctx, options);
+		}
+	};
+}
+var AttractorHandle = class {
+	device;
+	paramsBuffer;
+	paramsScratch = new ArrayBuffer(ATTRACTOR_PARAMS_BYTES);
+	paramsF32 = new Float32Array(this.paramsScratch);
+	paramsU32 = new Uint32Array(this.paramsScratch);
+	bindGroup;
+	pipeline;
+	constructor(ctx, opts) {
+		const { state } = ctx;
+		const label = `${ctx.label}.attractor`;
+		this.device = ctx.root.device;
+		this.paramsBuffer = this.device.createBuffer({
+			label: `${label}.params`,
+			size: ATTRACTOR_PARAMS_BYTES,
+			usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+		});
+		this.writeParams(opts);
+		const layout = this.device.createBindGroupLayout({
+			label: `${label}.layout`,
+			entries: [
+				{
+					binding: 0,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 1,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "storage" }
+				},
+				{
+					binding: 2,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 3,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 4,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "uniform" }
+				}
+			]
+		});
+		this.bindGroup = this.device.createBindGroup({
+			label: `${label}.group`,
+			layout,
+			entries: [
+				{
+					binding: 0,
+					resource: { buffer: state.builtins.positions }
+				},
+				{
+					binding: 1,
+					resource: { buffer: state.builtins.accel }
+				},
+				{
+					binding: 2,
+					resource: { buffer: state.builtins.alive }
+				},
+				{
+					binding: 3,
+					resource: { buffer: state.builtins.aliveCount }
+				},
+				{
+					binding: 4,
+					resource: { buffer: this.paramsBuffer }
+				}
+			]
+		});
+		this.pipeline = this.device.createComputePipeline({
+			label: `${label}.pipeline`,
+			layout: this.device.createPipelineLayout({
+				label: `${label}.pipelineLayout`,
+				bindGroupLayouts: [layout]
+			}),
+			compute: {
+				module: this.device.createShaderModule({
+					label: `${label}.shader`,
+					code: ATTRACTOR_WGSL
+				}),
+				entryPoint: "main"
+			}
+		});
+	}
+	writeParams(opts) {
+		this.paramsF32[0] = opts.point[0];
+		this.paramsF32[1] = opts.point[1];
+		this.paramsF32[2] = opts.strength;
+		this.paramsF32[3] = opts.reach ?? 0;
+		this.paramsU32[4] = FALLOFF_CODE[opts.falloff ?? "inverseSquare"];
+		this.device.queue.writeBuffer(this.paramsBuffer, 0, this.paramsScratch);
+	}
+	record(pass, ctx) {
+		pass.setPipeline(this.pipeline);
+		pass.setBindGroup(0, this.bindGroup);
+		pass.dispatchWorkgroupsIndirect(ctx.dispatchArgs, 0);
+	}
+	destroy() {
+		this.paramsBuffer.destroy();
+	}
+};
+/**
+* Like `attractor`, but the anchor point is resampled from `target()` on
+* every step. Built on the same kernel — pointer dragging the canvas is the
+* canonical use.
+*/
+function pointer(options) {
+	const falloff = options.falloff ?? "inverseSquare";
+	return {
+		kind: "pointer",
+		attach(ctx) {
+			return new PointerHandle(ctx, options, falloff);
+		}
+	};
+}
+var PointerHandle = class extends AttractorHandle {
+	target;
+	strengthFn;
+	reach;
+	falloff;
+	constructor(ctx, opts, falloff) {
+		const strengthFn = typeof opts.strength === "function" ? opts.strength : () => opts.strength;
+		super(ctx, {
+			point: opts.target(),
+			strength: strengthFn(),
+			reach: opts.reach,
+			falloff
+		});
+		this.target = opts.target;
+		this.strengthFn = strengthFn;
+		this.reach = opts.reach ?? 0;
+		this.falloff = falloff;
+	}
+	record(pass, ctx) {
+		const pt = this.target();
+		this.writeParams({
+			point: [pt[0], pt[1]],
+			strength: this.strengthFn(),
+			reach: this.reach,
+			falloff: this.falloff
+		});
+		super.record(pass, ctx);
+	}
+};
+//#endregion
+//#region src/particles/forces/boids.ts
+const BOIDS_PARAMS_BYTES = 32;
+const BOIDS_WGSL = `
+struct BoidsParams {
+  reach:            f32,
+  separationRadius: f32,
+  alignment:        f32,
+  cohesion:         f32,
+  separation:       f32,
+  maxSpeed:         f32,
+  _pad0:            f32,
+  _pad1:            f32,
+};
+
+@group(0) @binding(0) var<storage, read>       positions:  array<vec2f>;
+@group(0) @binding(1) var<storage, read>       velocities: array<vec2f>;
+@group(0) @binding(2) var<storage, read_write> accel:      array<atomic<u32>>;
+@group(0) @binding(3) var<storage, read>       alive:      array<u32>;
+@group(0) @binding(4) var<storage, read>       aliveCount: u32;
+
+${spatialHashConsumerWgsl(1)}
+
+@group(2) @binding(0) var<uniform> params: BoidsParams;
+${ATOMIC_ACCEL_WGSL}
+fn safeNormalize(v: vec2f) -> vec2f {
+  let len = length(v);
+  if (len < 1e-6) { return vec2f(0.0); }
+  return v / len;
+}
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  if (i >= aliveCount) { return; }
+  if (alive[i] == 0u) { return; }
+
+  let myPos = positions[i];
+  let myVel = velocities[i];
+  let myCell = worldCell(myPos, hashParams.invCellSize);
+
+  let reach2 = params.reach * params.reach;
+  let sepR2  = params.separationRadius * params.separationRadius;
+
+  var sumVel = vec2f(0.0);
+  var sumPos = vec2f(0.0);
+  var sumSep = vec2f(0.0);
+  var countNeighbours = 0u;
+  var countSep = 0u;
+
+  for (var oy = -1; oy <= 1; oy = oy + 1) {
+    for (var ox = -1; ox <= 1; ox = ox + 1) {
+      let targetCell = myCell + vec2i(ox, oy);
+      var cursor = heads[hashCell(targetCell, hashParams.bucketMask)];
+      loop {
+        if (cursor == EMPTY_SLOT) { break; }
+        if (cursor != i && all(cells[cursor] == targetCell) && alive[cursor] != 0u) {
+          let delta = positions[cursor] - myPos;
+          let d2 = dot(delta, delta);
+          if (d2 <= reach2) {
+            sumVel = sumVel + velocities[cursor];
+            sumPos = sumPos + positions[cursor];
+            countNeighbours = countNeighbours + 1u;
+            if (d2 < sepR2 && d2 > 1e-8) {
+              // Push proportional to 1/d — closer neighbours push harder.
+              sumSep = sumSep - delta / sqrt(d2);
+              countSep = countSep + 1u;
+            }
+          }
+        }
+        cursor = next[cursor];
+      }
+    }
+  }
+
+  if (countNeighbours == 0u && countSep == 0u) { return; }
+
+  var force = vec2f(0.0);
+  if (countNeighbours > 0u) {
+    let inv = 1.0 / f32(countNeighbours);
+    // Alignment: steer toward the average neighbour heading.
+    let avgVel = sumVel * inv;
+    let desiredAlign = safeNormalize(avgVel) * params.maxSpeed;
+    force = force + (desiredAlign - myVel) * params.alignment;
+
+    // Cohesion: steer toward the local centroid.
+    let centroid = sumPos * inv;
+    let desiredCoh = safeNormalize(centroid - myPos) * params.maxSpeed;
+    force = force + (desiredCoh - myVel) * params.cohesion;
+  }
+  if (countSep > 0u) {
+    let sepDir = safeNormalize(sumSep);
+    let desiredSep = sepDir * params.maxSpeed;
+    force = force + (desiredSep - myVel) * params.separation;
+  }
+
+  atomicAddF32(i * 2u + 0u, force.x);
+  atomicAddF32(i * 2u + 1u, force.y);
+}
+`;
+/**
+* Reynolds boids — alignment, cohesion, separation over a spatial-hash
+* neighbourhood. Shares the system's hash at the given `reach`.
+*/
+function boids(options) {
+	return {
+		kind: "boids",
+		attach(ctx) {
+			return new BoidsHandle(ctx, options);
+		}
+	};
+}
+var BoidsHandle = class {
+	device;
+	pipeline;
+	stateBindGroup;
+	hashBindGroup;
+	paramsGroup;
+	paramsBuffer;
+	constructor(ctx, opts) {
+		const { root, state } = ctx;
+		this.device = root.device;
+		const label = `${ctx.label}.boids`;
+		const hash = ctx.requestSpatialHash(opts.reach);
+		this.hashBindGroup = hash.consumeBindGroup;
+		const stateLayout = this.device.createBindGroupLayout({
+			label: `${label}.state.layout`,
+			entries: [
+				{
+					binding: 0,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 1,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 2,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "storage" }
+				},
+				{
+					binding: 3,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 4,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				}
+			]
+		});
+		this.stateBindGroup = this.device.createBindGroup({
+			label: `${label}.state.group`,
+			layout: stateLayout,
+			entries: [
+				{
+					binding: 0,
+					resource: { buffer: state.builtins.positions }
+				},
+				{
+					binding: 1,
+					resource: { buffer: state.builtins.velocities }
+				},
+				{
+					binding: 2,
+					resource: { buffer: state.builtins.accel }
+				},
+				{
+					binding: 3,
+					resource: { buffer: state.builtins.alive }
+				},
+				{
+					binding: 4,
+					resource: { buffer: state.builtins.aliveCount }
+				}
+			]
+		});
+		this.paramsBuffer = this.device.createBuffer({
+			label: `${label}.params`,
+			size: BOIDS_PARAMS_BYTES,
+			usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+		});
+		const scratch = new Float32Array(BOIDS_PARAMS_BYTES / 4);
+		scratch[0] = opts.reach;
+		scratch[1] = opts.separationRadius ?? opts.reach * .4;
+		scratch[2] = opts.alignment ?? 1;
+		scratch[3] = opts.cohesion ?? .5;
+		scratch[4] = opts.separation ?? 1.5;
+		scratch[5] = opts.maxSpeed ?? 100;
+		this.device.queue.writeBuffer(this.paramsBuffer, 0, scratch);
+		const paramsLayout = this.device.createBindGroupLayout({
+			label: `${label}.params.layout`,
+			entries: [{
+				binding: 0,
+				visibility: GPUShaderStage.COMPUTE,
+				buffer: { type: "uniform" }
+			}]
+		});
+		this.paramsGroup = this.device.createBindGroup({
+			label: `${label}.params.group`,
+			layout: paramsLayout,
+			entries: [{
+				binding: 0,
+				resource: { buffer: this.paramsBuffer }
+			}]
+		});
+		this.pipeline = this.device.createComputePipeline({
+			label: `${label}.pipeline`,
+			layout: this.device.createPipelineLayout({
+				label: `${label}.pipelineLayout`,
+				bindGroupLayouts: [
+					stateLayout,
+					hash.consumeBindGroupLayout,
+					paramsLayout
+				]
+			}),
+			compute: {
+				module: this.device.createShaderModule({
+					label: `${label}.shader`,
+					code: BOIDS_WGSL
+				}),
+				entryPoint: "main"
+			}
+		});
+	}
+	record(pass, ctx) {
+		pass.setPipeline(this.pipeline);
+		pass.setBindGroup(0, this.stateBindGroup);
+		pass.setBindGroup(1, this.hashBindGroup);
+		pass.setBindGroup(2, this.paramsGroup);
+		pass.dispatchWorkgroupsIndirect(ctx.dispatchArgs, 0);
+	}
+	destroy() {
+		this.paramsBuffer.destroy();
+	}
+};
+//#endregion
+//#region src/particles/forces/drag.ts
+const DRAG_PARAMS_BYTES = 16;
+const DRAG_WGSL = `
+struct DragParams {
+  coefficient: f32,
+  _pad0: f32,
+  _pad1: f32,
+  _pad2: f32,
+};
+
+@group(0) @binding(0) var<storage, read>       velocities: array<vec2f>;
+@group(0) @binding(1) var<storage, read_write> accel:      array<atomic<u32>>;
+@group(0) @binding(2) var<storage, read>       alive:      array<u32>;
+@group(0) @binding(3) var<storage, read>       aliveCount: u32;
+@group(0) @binding(4) var<uniform>             params:     DragParams;
+${ATOMIC_ACCEL_WGSL}
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  if (i >= aliveCount) { return; }
+  if (alive[i] == 0u) { return; }
+
+  let v = velocities[i];
+  let a = -params.coefficient * v;
+  atomicAddF32(i * 2u + 0u, a.x);
+  atomicAddF32(i * 2u + 1u, a.y);
+}
+`;
+/** Linear velocity damping. `a += -coefficient * v`. */
+function drag(options) {
+	return {
+		kind: "drag",
+		attach(ctx) {
+			return new DragHandle(ctx, options);
+		}
+	};
+}
+var DragHandle = class {
+	device;
+	paramsBuffer;
+	bindGroup;
+	pipeline;
+	constructor(ctx, opts) {
+		const { state } = ctx;
+		const label = `${ctx.label}.drag`;
+		this.device = ctx.root.device;
+		this.paramsBuffer = this.device.createBuffer({
+			label: `${label}.params`,
+			size: DRAG_PARAMS_BYTES,
+			usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+		});
+		const scratch = new Float32Array(DRAG_PARAMS_BYTES / 4);
+		scratch[0] = opts.coefficient;
+		this.device.queue.writeBuffer(this.paramsBuffer, 0, scratch);
+		const layout = this.device.createBindGroupLayout({
+			label: `${label}.layout`,
+			entries: [
+				{
+					binding: 0,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 1,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "storage" }
+				},
+				{
+					binding: 2,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 3,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 4,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "uniform" }
+				}
+			]
+		});
+		this.bindGroup = this.device.createBindGroup({
+			label: `${label}.group`,
+			layout,
+			entries: [
+				{
+					binding: 0,
+					resource: { buffer: state.builtins.velocities }
+				},
+				{
+					binding: 1,
+					resource: { buffer: state.builtins.accel }
+				},
+				{
+					binding: 2,
+					resource: { buffer: state.builtins.alive }
+				},
+				{
+					binding: 3,
+					resource: { buffer: state.builtins.aliveCount }
+				},
+				{
+					binding: 4,
+					resource: { buffer: this.paramsBuffer }
+				}
+			]
+		});
+		this.pipeline = this.device.createComputePipeline({
+			label: `${label}.pipeline`,
+			layout: this.device.createPipelineLayout({
+				label: `${label}.pipelineLayout`,
+				bindGroupLayouts: [layout]
+			}),
+			compute: {
+				module: this.device.createShaderModule({
+					label: `${label}.shader`,
+					code: DRAG_WGSL
+				}),
+				entryPoint: "main"
+			}
+		});
+	}
+	record(pass, ctx) {
+		pass.setPipeline(this.pipeline);
+		pass.setBindGroup(0, this.bindGroup);
+		pass.dispatchWorkgroupsIndirect(ctx.dispatchArgs, 0);
+	}
+	destroy() {
+		this.paramsBuffer.destroy();
+	}
+};
+//#endregion
+//#region src/particles/forces/field.ts
+const FIELD_PARAMS_BYTES = 32;
+const FIELD_WGSL = `
+struct FieldParams {
+  col0:     vec2f,  // (m00, m10) — applied to world.x
+  col1:     vec2f,  // (m01, m11) — applied to world.y
+  col2:     vec2f,  // (m02, m12) — translation
+  strength: f32,
+  _pad:     f32,
+};
+
+@group(0) @binding(0) var<storage, read>       positions:  array<vec2f>;
+@group(0) @binding(1) var<storage, read_write> accel:      array<atomic<u32>>;
+@group(0) @binding(2) var<storage, read>       alive:      array<u32>;
+@group(0) @binding(3) var<storage, read>       aliveCount: u32;
+@group(0) @binding(4) var<uniform>             params:     FieldParams;
+@group(0) @binding(5) var                      fieldTex:   texture_2d<f32>;
+@group(0) @binding(6) var                      fieldSamp:  sampler;
+${ATOMIC_ACCEL_WGSL}
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  if (i >= aliveCount) { return; }
+  if (alive[i] == 0u) { return; }
+
+  let pos = positions[i];
+  let uv = params.col0 * pos.x + params.col1 * pos.y + params.col2;
+  let s = textureSampleLevel(fieldTex, fieldSamp, uv, 0.0);
+  let f = s.xy * params.strength;
+
+  atomicAddF32(i * 2u + 0u, f.x);
+  atomicAddF32(i * 2u + 1u, f.y);
+}
+`;
+/**
+* Texture-sampled flow-field force. Particles receive
+* `sampleRG(worldToUv·pos) * strength` as an acceleration each step.
+*/
+function field(options) {
+	return {
+		kind: "field",
+		attach(ctx) {
+			return new FieldHandle(ctx, options);
+		}
+	};
+}
+var FieldHandle = class {
+	device;
+	paramsBuffer;
+	paramsScratch = new Float32Array(FIELD_PARAMS_BYTES / 4);
+	bindGroup;
+	pipeline;
+	strength;
+	matrix;
+	constructor(ctx, opts) {
+		const { state } = ctx;
+		const label = `${ctx.label}.field`;
+		this.device = ctx.root.device;
+		this.strength = opts.strength;
+		this.matrix = resolveMatrix(opts);
+		this.paramsBuffer = this.device.createBuffer({
+			label: `${label}.params`,
+			size: FIELD_PARAMS_BYTES,
+			usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+		});
+		const addressMode = opts.wrap === "repeat" ? "repeat" : "clamp-to-edge";
+		const filter = opts.filter ?? "linear";
+		const sampler = this.device.createSampler({
+			label: `${label}.sampler`,
+			addressModeU: addressMode,
+			addressModeV: addressMode,
+			magFilter: filter,
+			minFilter: filter
+		});
+		const layout = this.device.createBindGroupLayout({
+			label: `${label}.layout`,
+			entries: [
+				{
+					binding: 0,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 1,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "storage" }
+				},
+				{
+					binding: 2,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 3,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 4,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "uniform" }
+				},
+				{
+					binding: 5,
+					visibility: GPUShaderStage.COMPUTE,
+					texture: { sampleType: filter === "linear" ? "float" : "unfilterable-float" }
+				},
+				{
+					binding: 6,
+					visibility: GPUShaderStage.COMPUTE,
+					sampler: { type: filter === "linear" ? "filtering" : "non-filtering" }
+				}
+			]
+		});
+		this.bindGroup = this.device.createBindGroup({
+			label: `${label}.group`,
+			layout,
+			entries: [
+				{
+					binding: 0,
+					resource: { buffer: state.builtins.positions }
+				},
+				{
+					binding: 1,
+					resource: { buffer: state.builtins.accel }
+				},
+				{
+					binding: 2,
+					resource: { buffer: state.builtins.alive }
+				},
+				{
+					binding: 3,
+					resource: { buffer: state.builtins.aliveCount }
+				},
+				{
+					binding: 4,
+					resource: { buffer: this.paramsBuffer }
+				},
+				{
+					binding: 5,
+					resource: opts.texture.createView()
+				},
+				{
+					binding: 6,
+					resource: sampler
+				}
+			]
+		});
+		this.pipeline = this.device.createComputePipeline({
+			label: `${label}.pipeline`,
+			layout: this.device.createPipelineLayout({
+				label: `${label}.pipelineLayout`,
+				bindGroupLayouts: [layout]
+			}),
+			compute: {
+				module: this.device.createShaderModule({
+					label: `${label}.shader`,
+					code: FIELD_WGSL
+				}),
+				entryPoint: "main"
+			}
+		});
+	}
+	/** Swap strength at runtime without rebuilding the pipeline. */
+	setStrength(strength) {
+		this.strength = strength;
+	}
+	record(pass, ctx) {
+		this.paramsScratch[0] = this.matrix[0];
+		this.paramsScratch[1] = this.matrix[3];
+		this.paramsScratch[2] = this.matrix[1];
+		this.paramsScratch[3] = this.matrix[4];
+		this.paramsScratch[4] = this.matrix[2];
+		this.paramsScratch[5] = this.matrix[5];
+		this.paramsScratch[6] = this.strength;
+		this.paramsScratch[7] = 0;
+		this.device.queue.writeBuffer(this.paramsBuffer, 0, this.paramsScratch);
+		pass.setPipeline(this.pipeline);
+		pass.setBindGroup(0, this.bindGroup);
+		pass.dispatchWorkgroupsIndirect(ctx.dispatchArgs, 0);
+	}
+	destroy() {
+		this.paramsBuffer.destroy();
+	}
+};
+function resolveMatrix(opts) {
+	if (opts.worldToUv && opts.worldBounds) throw new Error("field force: pass either `worldBounds` or `worldToUv`, not both.");
+	if (opts.worldToUv) return opts.worldToUv;
+	if (opts.worldBounds) {
+		const { x, y, width, height } = opts.worldBounds;
+		if (width <= 0 || height <= 0) throw new Error("field force: worldBounds.width and .height must be positive.");
+		return [
+			1 / width,
+			0,
+			-x / width,
+			0,
+			1 / height,
+			-y / height
+		];
+	}
+	const w = opts.texture.width;
+	const h = opts.texture.height;
+	return [
+		1 / w,
+		0,
+		0,
+		0,
+		1 / h,
+		0
+	];
+}
+//#endregion
+//#region src/particles/forces/gravity.ts
+const GRAVITY_PARAMS_BYTES = 16;
+const GRAVITY_WGSL = `
+struct GravityParams {
+  accel: vec2f,
+  _pad0: f32,
+  _pad1: f32,
+};
+
+@group(0) @binding(0) var<storage, read_write> accel:      array<atomic<u32>>;
+@group(0) @binding(1) var<storage, read>       alive:      array<u32>;
+@group(0) @binding(2) var<storage, read>       aliveCount: u32;
+@group(0) @binding(3) var<uniform>             params:     GravityParams;
+${ATOMIC_ACCEL_WGSL}
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  if (i >= aliveCount) { return; }
+  if (alive[i] == 0u) { return; }
+  atomicAddF32(i * 2u + 0u, params.accel.x);
+  atomicAddF32(i * 2u + 1u, params.accel.y);
+}
+`;
+/** Uniform acceleration in a fixed direction. Classic "falling" force. */
+function gravity(options) {
+	return {
+		kind: "gravity",
+		attach(ctx) {
+			return new GravityHandle(ctx, options);
+		}
+	};
+}
+var GravityHandle = class {
+	device;
+	paramsBuffer;
+	bindGroup;
+	pipeline;
+	constructor(ctx, opts) {
+		const { state } = ctx;
+		const label = `${ctx.label}.gravity`;
+		this.device = ctx.root.device;
+		const len = Math.hypot(opts.direction[0], opts.direction[1]);
+		const nx = len > 1e-9 ? opts.direction[0] / len : 0;
+		const ny = len > 1e-9 ? opts.direction[1] / len : 0;
+		this.paramsBuffer = this.device.createBuffer({
+			label: `${label}.params`,
+			size: GRAVITY_PARAMS_BYTES,
+			usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+		});
+		const scratch = new Float32Array(GRAVITY_PARAMS_BYTES / 4);
+		scratch[0] = nx * opts.strength;
+		scratch[1] = ny * opts.strength;
+		this.device.queue.writeBuffer(this.paramsBuffer, 0, scratch);
+		const layout = this.device.createBindGroupLayout({
+			label: `${label}.layout`,
+			entries: [
+				{
+					binding: 0,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "storage" }
+				},
+				{
+					binding: 1,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 2,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 3,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "uniform" }
+				}
+			]
+		});
+		this.bindGroup = this.device.createBindGroup({
+			label: `${label}.group`,
+			layout,
+			entries: [
+				{
+					binding: 0,
+					resource: { buffer: state.builtins.accel }
+				},
+				{
+					binding: 1,
+					resource: { buffer: state.builtins.alive }
+				},
+				{
+					binding: 2,
+					resource: { buffer: state.builtins.aliveCount }
+				},
+				{
+					binding: 3,
+					resource: { buffer: this.paramsBuffer }
+				}
+			]
+		});
+		this.pipeline = this.device.createComputePipeline({
+			label: `${label}.pipeline`,
+			layout: this.device.createPipelineLayout({
+				label: `${label}.pipelineLayout`,
+				bindGroupLayouts: [layout]
+			}),
+			compute: {
+				module: this.device.createShaderModule({
+					label: `${label}.shader`,
+					code: GRAVITY_WGSL
+				}),
+				entryPoint: "main"
+			}
+		});
+	}
+	record(pass, ctx) {
+		pass.setPipeline(this.pipeline);
+		pass.setBindGroup(0, this.bindGroup);
+		pass.dispatchWorkgroupsIndirect(ctx.dispatchArgs, 0);
+	}
+	destroy() {
+		this.paramsBuffer.destroy();
+	}
+};
+//#endregion
+//#region src/particles/forces/noise.ts
+const NOISE_PARAMS_BYTES = 32;
+const KIND_CODE = {
+	simplex: 0,
+	curl: 1
+};
+const NOISE_WGSL = `
+struct NoiseParams {
+  scale:      f32,
+  strength:   f32,
+  timeOffset: f32,
+  kindCode:   u32,
+  _pad0:      u32,
+  _pad1:      u32,
+  _pad2:      u32,
+  _pad3:      u32,
+};
+
+@group(0) @binding(0) var<storage, read>       positions:  array<vec2f>;
+@group(0) @binding(1) var<storage, read_write> accel:      array<atomic<u32>>;
+@group(0) @binding(2) var<storage, read>       alive:      array<u32>;
+@group(0) @binding(3) var<storage, read>       aliveCount: u32;
+@group(0) @binding(4) var<uniform>             params:     NoiseParams;
+${ATOMIC_ACCEL_WGSL}
+// ---- Simplex 2D ---------------------------------------------------------
+// Adapted from Ashima Arts' GLSL snoise2 (MIT). Returns a value roughly in
+// [-1, 1].
+
+fn mod289v2(x: vec2f) -> vec2f { return x - floor(x * (1.0 / 289.0)) * 289.0; }
+fn mod289v3(x: vec3f) -> vec3f { return x - floor(x * (1.0 / 289.0)) * 289.0; }
+fn permute(x: vec3f) -> vec3f { return mod289v3(((x * 34.0) + 1.0) * x); }
+
+fn snoise2(v: vec2f) -> f32 {
+  let C = vec4f(0.211324865405187,  // (3-sqrt(3))/6
+                0.366025403784439,  // 0.5*(sqrt(3)-1)
+               -0.577350269189626,  // -1 + 2*C.x
+                0.024390243902439); // 1/41
+  var i  = floor(v + dot(v, C.yy));
+  let x0 = v - i + dot(i, C.xx);
+  var i1 = vec2f(0.0, 0.0);
+  if (x0.x > x0.y) { i1 = vec2f(1.0, 0.0); } else { i1 = vec2f(0.0, 1.0); }
+  let x1 = x0.xy + C.xx - i1;
+  let x2 = x0.xy + C.zz;
+  i = mod289v2(i);
+  let p = permute(permute(vec3f(i.y, i.y + i1.y, i.y + 1.0))
+                  + vec3f(i.x, i.x + i1.x, i.x + 1.0));
+  let m0 = max(vec3f(0.5) - vec3f(dot(x0, x0), dot(x1, x1), dot(x2, x2)), vec3f(0.0));
+  let m = m0 * m0 * m0 * m0;
+  let x = 2.0 * fract(p * C.www) - 1.0;
+  let h = abs(x) - 0.5;
+  let ox = floor(x + 0.5);
+  let a0 = x - ox;
+  let norm = 1.79284291400159 - 0.85373472095314 * (a0 * a0 + h * h);
+  let g = vec3f(a0.x * x0.x + h.x * x0.y,
+                a0.y * x1.x + h.y * x1.y,
+                a0.z * x2.x + h.z * x2.y);
+  return 130.0 * dot(m * norm, g);
+}
+
+// Sample the "scalar field" the particle sits in at world-space pos.
+fn field(p: vec2f) -> f32 {
+  return snoise2(p * params.scale + vec2f(params.timeOffset, 0.0));
+}
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  if (i >= aliveCount) { return; }
+  if (alive[i] == 0u) { return; }
+
+  let pos = positions[i];
+  // Finite-difference step in world units. Small relative to scale so
+  // gradient accuracy is decent; large enough to avoid catastrophic
+  // cancellation in f32.
+  let eps = max(0.25 / max(params.scale, 1e-6), 1e-3);
+  let n_px = field(pos + vec2f(eps, 0.0));
+  let n_mx = field(pos - vec2f(eps, 0.0));
+  let n_py = field(pos + vec2f(0.0, eps));
+  let n_my = field(pos - vec2f(0.0, eps));
+  let grad = vec2f((n_px - n_mx), (n_py - n_my)) / (2.0 * eps);
+
+  var f: vec2f;
+  if (params.kindCode == 1u) {
+    // 2D curl of scalar field: (dN/dy, -dN/dx)
+    f = vec2f(grad.y, -grad.x) * params.strength;
+  } else {
+    f = grad * params.strength;
+  }
+
+  atomicAddF32(i * 2u + 0u, f.x);
+  atomicAddF32(i * 2u + 1u, f.y);
+}
+`;
+/**
+* Simplex-noise flow force. `curl` (default) gives a divergence-free field
+* for wispy, flow-like motion; `simplex` applies the scalar gradient
+* directly and looks more turbulent.
+*/
+function noise(options) {
+	return {
+		kind: "noise",
+		attach(ctx) {
+			return new NoiseHandle(ctx, options);
+		}
+	};
+}
+var NoiseHandle = class {
+	device;
+	paramsBuffer;
+	paramsScratch = new ArrayBuffer(NOISE_PARAMS_BYTES);
+	paramsF32 = new Float32Array(this.paramsScratch);
+	paramsU32 = new Uint32Array(this.paramsScratch);
+	bindGroup;
+	pipeline;
+	scale;
+	strength;
+	kindCode;
+	timeScale;
+	timeOffset = 0;
+	constructor(ctx, opts) {
+		const { state } = ctx;
+		const label = `${ctx.label}.noise`;
+		this.device = ctx.root.device;
+		this.scale = opts.scale;
+		this.strength = opts.strength;
+		this.kindCode = KIND_CODE[opts.kind ?? "curl"];
+		this.timeScale = opts.timeScale ?? 1;
+		this.paramsBuffer = this.device.createBuffer({
+			label: `${label}.params`,
+			size: NOISE_PARAMS_BYTES,
+			usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+		});
+		const layout = this.device.createBindGroupLayout({
+			label: `${label}.layout`,
+			entries: [
+				{
+					binding: 0,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 1,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "storage" }
+				},
+				{
+					binding: 2,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 3,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 4,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "uniform" }
+				}
+			]
+		});
+		this.bindGroup = this.device.createBindGroup({
+			label: `${label}.group`,
+			layout,
+			entries: [
+				{
+					binding: 0,
+					resource: { buffer: state.builtins.positions }
+				},
+				{
+					binding: 1,
+					resource: { buffer: state.builtins.accel }
+				},
+				{
+					binding: 2,
+					resource: { buffer: state.builtins.alive }
+				},
+				{
+					binding: 3,
+					resource: { buffer: state.builtins.aliveCount }
+				},
+				{
+					binding: 4,
+					resource: { buffer: this.paramsBuffer }
+				}
+			]
+		});
+		this.pipeline = this.device.createComputePipeline({
+			label: `${label}.pipeline`,
+			layout: this.device.createPipelineLayout({
+				label: `${label}.pipelineLayout`,
+				bindGroupLayouts: [layout]
+			}),
+			compute: {
+				module: this.device.createShaderModule({
+					label: `${label}.shader`,
+					code: NOISE_WGSL
+				}),
+				entryPoint: "main"
+			}
+		});
+	}
+	record(pass, ctx) {
+		this.timeOffset += ctx.dt * this.timeScale;
+		this.paramsF32[0] = this.scale;
+		this.paramsF32[1] = this.strength;
+		this.paramsF32[2] = this.timeOffset;
+		this.paramsU32[3] = this.kindCode;
+		this.device.queue.writeBuffer(this.paramsBuffer, 0, this.paramsScratch);
+		pass.setPipeline(this.pipeline);
+		pass.setBindGroup(0, this.bindGroup);
+		pass.dispatchWorkgroupsIndirect(ctx.dispatchArgs, 0);
+	}
+	destroy() {
+		this.paramsBuffer.destroy();
+	}
+};
+//#endregion
+//#region src/particles/forces/pairwise.ts
+/**
+* Generic pairwise force. Typically invoked by presets (`particleLife`,
+* `boids`) but also exposed directly for ad-hoc user kernels.
+*/
+function pairwise(options) {
+	return {
+		kind: "pairwise",
+		attach(ctx) {
+			return new PairwiseHandle(ctx, options);
+		}
+	};
+}
+function generatePairwisePrelude(state, reads) {
+	for (const name of reads) if (!(name in state.catalog)) throw new Error(`pairwise: attribute '${name}' is not declared on the system. Declared: ${Object.keys(state.catalog).join(", ") || "<none>"}.`);
+	const readsSet = new Set(reads);
+	const entries = catalogEntries(state.catalog);
+	const lines = [];
+	lines.push("// === generated pairwise prelude ===");
+	lines.push("@group(0) @binding(0) var<storage, read>       positions  : array<vec2f>;");
+	lines.push("@group(0) @binding(1) var<storage, read_write> accel      : array<atomic<u32>>;");
+	lines.push("@group(0) @binding(2) var<storage, read>       alive      : array<u32>;");
+	lines.push("@group(0) @binding(3) var<storage, read_write> aliveCount : atomic<u32>;");
+	const userAttrLayoutEntries = [];
+	const userAttrBindings = [];
+	let nextBinding = 0;
+	for (const [name, type] of entries) {
+		if (!readsSet.has(name)) continue;
+		const attr = state.userAttrs.find((a) => a.name === name);
+		if (!attr) continue;
+		const wgsl = attributeWgslType(type);
+		const binding = nextBinding++;
+		lines.push(`@group(1) @binding(${binding}) var<storage, read> ${bindingName(name)} : array<${wgsl}>;`);
+		userAttrLayoutEntries.push({
+			binding,
+			visibility: GPUShaderStage.COMPUTE,
+			buffer: { type: "read-only-storage" }
+		});
+		userAttrBindings.push({
+			binding,
+			resource: { buffer: attr.buffer }
+		});
+	}
+	lines.push("");
+	lines.push("struct Particle {");
+	lines.push("  index:    u32,");
+	lines.push("  position: vec2f,");
+	for (const [name, type] of entries) {
+		if (!readsSet.has(name)) continue;
+		lines.push(`  ${name}: ${attributeWgslType(type)},`);
+	}
+	lines.push("};");
+	lines.push("");
+	lines.push("fn loadParticle(i: u32) -> Particle {");
+	lines.push("  return Particle(");
+	lines.push("    i,");
+	lines.push("    positions[i],");
+	for (const [name] of entries) {
+		if (!readsSet.has(name)) continue;
+		lines.push(`    ${bindingName(name)}[i],`);
+	}
+	lines.push("  );");
+	lines.push("}");
+	lines.push(ATOMIC_ACCEL_WGSL);
+	lines.push("// === end pairwise prelude ===");
+	lines.push("");
+	return {
+		wgsl: lines.join("\n"),
+		userAttrLayoutEntries,
+		userAttrBindings
+	};
+}
+var PairwiseHandle = class {
+	device;
+	hash;
+	pipeline;
+	stateBindGroup;
+	userAttrBindGroup;
+	hashBindGroup;
+	paramsGroup;
+	paramsBuffer;
+	paramsSize;
+	constructor(ctx, opts) {
+		const { root, state } = ctx;
+		this.device = root.device;
+		const label = `${ctx.label}.${opts.label ?? "pairwise"}`;
+		this.hash = ctx.requestSpatialHash(opts.reach);
+		const stateLayout = this.device.createBindGroupLayout({
+			label: `${label}.state.layout`,
+			entries: [
+				{
+					binding: 0,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 1,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "storage" }
+				},
+				{
+					binding: 2,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 3,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "storage" }
+				}
+			]
+		});
+		this.stateBindGroup = this.device.createBindGroup({
+			label: `${label}.state.group`,
+			layout: stateLayout,
+			entries: [
+				{
+					binding: 0,
+					resource: { buffer: state.builtins.positions }
+				},
+				{
+					binding: 1,
+					resource: { buffer: state.builtins.accel }
+				},
+				{
+					binding: 2,
+					resource: { buffer: state.builtins.alive }
+				},
+				{
+					binding: 3,
+					resource: { buffer: state.builtins.aliveCount }
+				}
+			]
+		});
+		const { wgsl: preludeWgsl, userAttrLayoutEntries, userAttrBindings } = generatePairwisePrelude(state, opts.reads ?? []);
+		const userAttrLayout = this.device.createBindGroupLayout({
+			label: `${label}.userAttrs.layout`,
+			entries: userAttrLayoutEntries
+		});
+		this.userAttrBindGroup = this.device.createBindGroup({
+			label: `${label}.userAttrs.group`,
+			layout: userAttrLayout,
+			entries: userAttrBindings
+		});
+		let paramsBuffer = null;
+		const groupLayoutEntries = [];
+		const groupEntries = [];
+		let paramsStructWgsl = "";
+		let paramsBindingWgsl = "";
+		this.paramsSize = opts.params?.bytes ?? 0;
+		if (opts.params) {
+			paramsBuffer = this.device.createBuffer({
+				label: `${label}.params`,
+				size: opts.params.bytes,
+				usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+			});
+			if (opts.params.write) {
+				const ab = new ArrayBuffer(opts.params.bytes);
+				opts.params.write(new DataView(ab));
+				this.device.queue.writeBuffer(paramsBuffer, 0, ab);
+			}
+			paramsStructWgsl = opts.params.structWgsl;
+			paramsBindingWgsl = `@group(3) @binding(0) var<uniform> params: PairwiseParams;`;
+			groupLayoutEntries.push({
+				binding: 0,
+				visibility: GPUShaderStage.COMPUTE,
+				buffer: { type: "uniform" }
+			});
+			groupEntries.push({
+				binding: 0,
+				resource: { buffer: paramsBuffer }
+			});
+		}
+		let extraWgsl = "";
+		if (opts.extraBindings) for (const extra of opts.extraBindings) {
+			groupLayoutEntries.push(extra.layoutEntry);
+			groupEntries.push(extra.bindGroupEntry);
+			extraWgsl += `\n${extra.wgsl}`;
+		}
+		this.paramsBuffer = paramsBuffer;
+		const group3Layout = groupLayoutEntries.length ? this.device.createBindGroupLayout({
+			label: `${label}.group3.layout`,
+			entries: groupLayoutEntries
+		}) : null;
+		this.paramsGroup = group3Layout ? this.device.createBindGroup({
+			label: `${label}.group3.group`,
+			layout: group3Layout,
+			entries: groupEntries
+		}) : null;
+		const kernelWgsl = `${preludeWgsl}
+${spatialHashConsumerWgsl(2)}
+${paramsStructWgsl}
+${paramsBindingWgsl}
+${extraWgsl}
+
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  let n = atomicLoad(&aliveCount);
+  if (i >= n) { return; }
+  if (alive[i] == 0u) { return; }
+
+  let me = loadParticle(i);
+  let myCell = worldCell(me.position, hashParams.invCellSize);
+
+  for (var oy = -1; oy <= 1; oy = oy + 1) {
+    for (var ox = -1; ox <= 1; ox = ox + 1) {
+      let targetCell = myCell + vec2i(ox, oy);
+      var cursor = heads[hashCell(targetCell, hashParams.bucketMask)];
+      loop {
+        if (cursor == EMPTY_SLOT) { break; }
+        if (cursor != i && all(cells[cursor] == targetCell) && alive[cursor] != 0u) {
+          let other = loadParticle(cursor);
+          ${opts.wgsl}
+        }
+        cursor = next[cursor];
+      }
+    }
+  }
+}
+`;
+		this.hashBindGroup = this.hash.consumeBindGroup;
+		const bindGroupLayouts = [
+			stateLayout,
+			userAttrLayout,
+			this.hash.consumeBindGroupLayout
+		];
+		if (group3Layout) bindGroupLayouts.push(group3Layout);
+		this.pipeline = this.device.createComputePipeline({
+			label: `${label}.pipeline`,
+			layout: this.device.createPipelineLayout({
+				label: `${label}.pipelineLayout`,
+				bindGroupLayouts
+			}),
+			compute: {
+				module: this.device.createShaderModule({
+					label: `${label}.shader`,
+					code: kernelWgsl
+				}),
+				entryPoint: "main"
+			}
+		});
+	}
+	record(pass, ctx) {
+		pass.setPipeline(this.pipeline);
+		pass.setBindGroup(0, this.stateBindGroup);
+		pass.setBindGroup(1, this.userAttrBindGroup);
+		pass.setBindGroup(2, this.hashBindGroup);
+		if (this.paramsGroup) pass.setBindGroup(3, this.paramsGroup);
+		pass.dispatchWorkgroupsIndirect(ctx.dispatchArgs, 0);
+	}
+	/**
+	* Overwrite the params uniform. Caller packs into a view matching the
+	* struct declared at construction. Bytes beyond `paramsSize` are ignored.
+	*/
+	writeParams(data) {
+		if (!this.paramsBuffer) return;
+		this.device.queue.writeBuffer(this.paramsBuffer, 0, data.buffer, data.byteOffset, Math.min(data.byteLength, this.paramsSize));
+	}
+	destroy() {
+		this.paramsBuffer?.destroy();
+	}
+};
+//#endregion
+//#region src/particles/forces/speed-limit.ts
+const LIMIT_PARAMS_BYTES = 16;
+const SPEED_LIMIT_WGSL = `
+struct LimitParams {
+  maxSpeed: f32,
+  invDt:    f32,
+  _pad0:    f32,
+  _pad1:    f32,
+};
+
+@group(0) @binding(0) var<storage, read>       velocities: array<vec2f>;
+@group(0) @binding(1) var<storage, read_write> accel:      array<atomic<u32>>;
+@group(0) @binding(2) var<storage, read>       alive:      array<u32>;
+@group(0) @binding(3) var<storage, read>       aliveCount: u32;
+@group(0) @binding(4) var<uniform>             params:     LimitParams;
+${ATOMIC_ACCEL_WGSL}
+@compute @workgroup_size(64)
+fn main(@builtin(global_invocation_id) gid: vec3u) {
+  let i = gid.x;
+  if (i >= aliveCount) { return; }
+  if (alive[i] == 0u) { return; }
+
+  let v = velocities[i];
+  let sp = length(v);
+  if (sp <= params.maxSpeed || sp < 1e-6) { return; }
+
+  // Desired v' = (v / sp) * maxSpeed. Needed Δv = v' − v = v · (maxSpeed/sp − 1).
+  // With Δv = a · dt we need a = Δv · (1/dt).
+  let scale = (params.maxSpeed / sp - 1.0) * params.invDt;
+  let correction = v * scale;
+
+  atomicAddF32(i * 2u + 0u, correction.x);
+  atomicAddF32(i * 2u + 1u, correction.y);
+}
+`;
+/**
+* Hard cap on particle speed. Applies a corrective acceleration so that
+* after the next integrator step, speed ≤ maxSpeed. Register AFTER other
+* forces to see the full accumulated excess.
+*/
+function speedLimit(options) {
+	return {
+		kind: "speedLimit",
+		attach(ctx) {
+			return new SpeedLimitHandle(ctx, options);
+		}
+	};
+}
+var SpeedLimitHandle = class {
+	device;
+	paramsBuffer;
+	paramsScratch = new Float32Array(LIMIT_PARAMS_BYTES / 4);
+	bindGroup;
+	pipeline;
+	maxSpeed;
+	constructor(ctx, opts) {
+		const { state } = ctx;
+		const label = `${ctx.label}.speedLimit`;
+		this.device = ctx.root.device;
+		this.maxSpeed = opts.maxSpeed;
+		this.paramsBuffer = this.device.createBuffer({
+			label: `${label}.params`,
+			size: LIMIT_PARAMS_BYTES,
+			usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST
+		});
+		const layout = this.device.createBindGroupLayout({
+			label: `${label}.layout`,
+			entries: [
+				{
+					binding: 0,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 1,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "storage" }
+				},
+				{
+					binding: 2,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 3,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				{
+					binding: 4,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "uniform" }
+				}
+			]
+		});
+		this.bindGroup = this.device.createBindGroup({
+			label: `${label}.group`,
+			layout,
+			entries: [
+				{
+					binding: 0,
+					resource: { buffer: state.builtins.velocities }
+				},
+				{
+					binding: 1,
+					resource: { buffer: state.builtins.accel }
+				},
+				{
+					binding: 2,
+					resource: { buffer: state.builtins.alive }
+				},
+				{
+					binding: 3,
+					resource: { buffer: state.builtins.aliveCount }
+				},
+				{
+					binding: 4,
+					resource: { buffer: this.paramsBuffer }
+				}
+			]
+		});
+		this.pipeline = this.device.createComputePipeline({
+			label: `${label}.pipeline`,
+			layout: this.device.createPipelineLayout({
+				label: `${label}.pipelineLayout`,
+				bindGroupLayouts: [layout]
+			}),
+			compute: {
+				module: this.device.createShaderModule({
+					label: `${label}.shader`,
+					code: SPEED_LIMIT_WGSL
+				}),
+				entryPoint: "main"
+			}
+		});
+	}
+	record(pass, ctx) {
+		this.paramsScratch[0] = this.maxSpeed;
+		this.paramsScratch[1] = 1 / Math.max(ctx.dt, 1e-6);
+		this.device.queue.writeBuffer(this.paramsBuffer, 0, this.paramsScratch);
+		pass.setPipeline(this.pipeline);
+		pass.setBindGroup(0, this.bindGroup);
+		pass.dispatchWorkgroupsIndirect(ctx.dispatchArgs, 0);
+	}
+	destroy() {
+		this.paramsBuffer.destroy();
+	}
+};
+//#endregion
+//#region src/particles/forces/particle-life.ts
+const MAX_SPECIES = 64;
+const PARAMS_BYTES = 32;
+var PairMatrix = class {
+	speciesCount;
+	/** Flat f32 data, length = speciesCount² × 4. Row-major. */
+	data;
+	constructor(speciesCount) {
+		if (!Number.isInteger(speciesCount) || speciesCount <= 0 || speciesCount > MAX_SPECIES) throw new Error(`PairMatrix: speciesCount must be 1..${MAX_SPECIES} (got ${speciesCount})`);
+		this.speciesCount = speciesCount;
+		this.data = new Float32Array(speciesCount * speciesCount * 4);
+	}
+	set(a, b, rule) {
+		const base = (a * this.speciesCount + b) * 4;
+		this.data[base + 0] = rule.attract;
+		this.data[base + 1] = rule.reach ?? 0;
+		this.data[base + 2] = rule.minDist ?? 0;
+		this.data[base + 3] = 0;
+	}
+	get(a, b) {
+		const base = (a * this.speciesCount + b) * 4;
+		return {
+			attract: this.data[base + 0] ?? 0,
+			reach: this.data[base + 1] ?? 0,
+			minDist: this.data[base + 2] ?? 0
+		};
+	}
+};
+function randomPairMatrix(speciesCount, opts = {}) {
+	const rand = opts.rand ?? Math.random;
+	const [aMin, aMax] = opts.attract ?? [-1, 1];
+	const m = new PairMatrix(speciesCount);
+	for (let a = 0; a < speciesCount; a++) for (let b = 0; b < speciesCount; b++) {
+		const attract = aMin + rand() * (aMax - aMin);
+		const reach = opts.reach ? opts.reach[0] + rand() * (opts.reach[1] - opts.reach[0]) : 0;
+		const minDist = opts.minDist ? opts.minDist[0] + rand() * (opts.minDist[1] - opts.minDist[0]) : 0;
+		m.set(a, b, {
+			attract,
+			reach,
+			minDist
+		});
+	}
+	return m;
+}
+/**
+* Create a particleLife force. The returned Force's handle exposes
+* `updateMatrix(newMatrix)` so callers can regenerate the matrix without
+* rebuilding the pipeline.
+*/
+function particleLife(options) {
+	return new ParticleLifeForce(options);
+}
+var ParticleLifeForce = class {
+	kind = "particleLife";
+	opts;
+	handle = null;
+	constructor(opts) {
+		this.opts = opts;
+	}
+	attach(ctx) {
+		const speciesName = this.opts.speciesAttribute ?? "species";
+		const speciesType = ctx.state.catalog[speciesName];
+		if (speciesType !== "u32") throw new Error(`particleLife: requires attribute '${speciesName}' declared as 'u32' (got ${speciesType ?? "undeclared"}). Declare it on the system.`);
+		const handle = new ParticleLifeHandle(ctx, this.opts);
+		this.handle = handle;
+		return handle;
+	}
+	/**
+	* Replace the matrix contents on the GPU. Attach first; no-op if called
+	* before. The matrix size must match the speciesCount fixed at attach time.
+	*/
+	updateMatrix(matrix) {
+		this.handle?.updateMatrix(matrix);
+	}
+};
+var ParticleLifeHandle = class {
+	device;
+	matrixBuffer;
+	speciesCount;
+	inner;
+	constructor(ctx, opts) {
+		this.device = ctx.root.device;
+		this.speciesCount = opts.matrix.speciesCount;
+		const speciesName = opts.speciesAttribute ?? "species";
+		const matrixBytes = this.speciesCount * this.speciesCount * 4 * 4;
+		this.matrixBuffer = this.device.createBuffer({
+			label: `${ctx.label}.particleLife.matrix`,
+			size: matrixBytes,
+			usage: GPUBufferUsage.STORAGE | GPUBufferUsage.COPY_DST
+		});
+		this.device.queue.writeBuffer(this.matrixBuffer, 0, opts.matrix.data);
+		const paramsStructWgsl = `
+struct PairwiseParams {
+  globalReach:   f32,
+  minDist:       f32,
+  repelStrength: f32,
+  speciesCount:  u32,
+  _pad0:         f32,
+  _pad1:         f32,
+  _pad2:         f32,
+  _pad3:         f32,
+};
+
+struct PairRule {
+  attract: f32,
+  reach:   f32,
+  minDist: f32,
+  _pad:    f32,
+};
+`;
+		const body = `
+      let rule = pairMatrix[me.${speciesName} * params.speciesCount + other.${speciesName}];
+      let delta = other.position - me.position;
+      let d2 = dot(delta, delta);
+      let effectiveReach = select(params.globalReach, rule.reach, rule.reach > 0.0);
+      if (d2 <= effectiveReach * effectiveReach) {
+        let d = max(sqrt(d2), 1e-4);
+        let dir = delta / d;
+        let effMinDist = select(params.minDist, rule.minDist, rule.minDist > 0.0);
+        if (d < effMinDist) {
+          // Short-range universal repulsion — prevents collapse regardless of sign.
+          let pen = effMinDist - d;
+          addAccel(me.index, dir * -params.repelStrength * pen);
+        } else {
+          // Asymmetric long-range attract/repel, linear falloff 1 → 0 across
+          // [effMinDist, effectiveReach]. Newton's third law is deliberately
+          // not enforced; the body writes only to me.
+          let range = max(effectiveReach - effMinDist, 1e-3);
+          let falloff = 1.0 - (d - effMinDist) / range;
+          addAccel(me.index, dir * rule.attract * falloff);
+        }
+      }
+`;
+		this.inner = new PairwiseHandle({
+			...ctx,
+			label: `${ctx.label}.particleLife`
+		}, {
+			reach: opts.reach,
+			reads: [speciesName],
+			wgsl: body,
+			label: "pairwise",
+			params: {
+				structWgsl: paramsStructWgsl,
+				bytes: PARAMS_BYTES,
+				write: (dv) => {
+					dv.setFloat32(0, opts.reach, true);
+					dv.setFloat32(4, opts.minDist, true);
+					dv.setFloat32(8, opts.repelStrength ?? 20, true);
+					dv.setUint32(12, this.speciesCount, true);
+				}
+			},
+			extraBindings: [{
+				wgsl: `@group(3) @binding(1) var<storage, read> pairMatrix: array<PairRule>;`,
+				layoutEntry: {
+					binding: 1,
+					visibility: GPUShaderStage.COMPUTE,
+					buffer: { type: "read-only-storage" }
+				},
+				bindGroupEntry: {
+					binding: 1,
+					resource: { buffer: this.matrixBuffer }
+				}
+			}]
+		});
+	}
+	record(pass, ctx) {
+		this.inner.record(pass, ctx);
+	}
+	updateMatrix(matrix) {
+		if (matrix.speciesCount !== this.speciesCount) throw new Error(`particleLife.updateMatrix: speciesCount mismatch (force=${this.speciesCount}, new=${matrix.speciesCount}). Remove + re-add the force to change species count.`);
+		this.device.queue.writeBuffer(this.matrixBuffer, 0, matrix.data);
+	}
+	destroy() {
+		this.matrixBuffer.destroy();
+		this.inner.destroy();
+	}
+};
+//#endregion
+export { FieldHandle, PairMatrix, PairwiseHandle, ParticleDrawableV3, ParticleLifeForce, ParticleSpatialHash, ParticleSystem, attractor, boids, drag, field, gravity, noise, pairwise, particleLife, pointer, randomPairMatrix, speedLimit };