insomni 0.2.0-alpha.0

package/dist/particles.d.mts

@@ -0,0 +1,816 @@
+import { d as CustomDrawableContext, ln as LayerSpace, r as Renderer2D, u as CustomDrawable } from "./renderer-DzZqd1bY.mjs";
+import { g as GPUOwner } from "./text-font-D7GGDtTK.mjs";
+import { TgpuRoot } from "typegpu";
+
+//#region src/particles/codegen/pipeline-cache.d.ts
+type PipelineFactory = () => GPUComputePipeline;
+declare class PipelineCache {
+  private readonly cache;
+  /**
+   * Return the pipeline for `key`, calling `factory()` to build it on miss.
+   * Factories are only invoked on cold lookups.
+   */
+  getOrCreate(key: string, factory: PipelineFactory): GPUComputePipeline;
+  /** Current cache size — useful for tests and introspection. */
+  get size(): number;
+  /**
+   * Drop every cached pipeline. WebGPU pipelines are reference-counted and
+   * released when the JS handle becomes unreferenced; nothing extra needed.
+   */
+  clear(): void;
+}
+//#endregion
+//#region src/particles/types.d.ts
+/** WGSL-mappable scalar / vector types a user attribute may take. */
+type AttributeType = "f32" | "u32" | "i32" | "vec2f" | "vec3f" | "vec4f" | "vec2u" | "vec4u";
+/** Declared at system construction — name → WGSL type. */
+type AttributeCatalog = Record<string, AttributeType>;
+type BoundsMode = {
+  kind: "none";
+} | {
+  kind: "clamp";
+  rect: [minX: number, minY: number, maxX: number, maxY: number];
+} | {
+  kind: "wrap";
+  rect: [minX: number, minY: number, maxX: number, maxY: number];
+} | {
+  kind: "bounce";
+  rect: [minX: number, minY: number, maxX: number, maxY: number];
+  restitution?: number;
+};
+interface ParticleSystemOptions {
+  /**
+   * Hard cap on simultaneously live particles. Bounded above by the
+   * compaction module's single-pass-B scan limit (262144 in v1). Buffers
+   * are sized to this; there is no auto-grow.
+   */
+  capacity: number;
+  /** User-declared extra attributes beyond the always-present built-ins. */
+  attributes?: AttributeCatalog;
+  /** Fixed simulation timestep. Default 1 / 60. */
+  dt?: number;
+  bounds?: BoundsMode;
+}
+//#endregion
+//#region src/particles/emitter.d.ts
+/** Local tuple form used by emitter samplers and specs. The math module's
+ * `Vec2` is object-shaped (`{x, y}`); this subsystem prefers tuples so
+ * samplers can produce/consume array literals without allocation churn. */
+type Vec2 = readonly [x: number, y: number];
+/** Scalar that can be sampled as a point in 2D space. */
+type PositionShape = {
+  kind: "point";
+  at: Vec2 | (() => Vec2);
+} | {
+  kind: "disc";
+  center: Vec2;
+  radius: number;
+} | {
+  kind: "ring";
+  center: Vec2;
+  radius: number;
+  thickness?: number;
+} | {
+  kind: "rect";
+  min: Vec2;
+  max: Vec2;
+} | {
+  kind: "line";
+  a: Vec2;
+  b: Vec2;
+} | {
+  kind: "grid";
+  origin: Vec2;
+  cols: number;
+  rows: number;
+  spacing: number | Vec2;
+} | {
+  kind: "fn";
+  fn: (i: number, count: number) => Vec2;
+};
+type VelocityShape = {
+  kind: "zero";
+} | {
+  kind: "uniform";
+  value: Vec2;
+} | {
+  kind: "random";
+  speed: [min: number, max: number];
+} | {
+  kind: "cone";
+  dir: Vec2 | (() => Vec2);
+  spread: number;
+  speed: [number, number];
+} | {
+  kind: "tangential";
+  center: Vec2;
+  speed: [number, number];
+  ccw?: boolean;
+} | {
+  kind: "fn";
+  fn: (i: number, count: number) => Vec2;
+};
+/** Either a fixed value or a `[min, max]` range to sample uniformly. */
+type ScalarRange = number | readonly [number, number];
+/**
+ * Per-attribute value at emit time. Scalar types accept a fixed number, a
+ * `[min, max]` range, or a sampler `(i, count) => number`. Vector types
+ * accept a fixed array, or a sampler `(i, count) => readonly number[]`.
+ *
+ * For integer attribute types (`u32`, `i32`, `vec2u`, `vec4u`) floats are
+ * truncated via `Math.floor` when packing. Omitted attributes default to
+ * zero.
+ */
+type AttributeSampler = number | readonly [number, number] | readonly number[] | ((i: number, count: number) => number | readonly number[]);
+interface EmitSpec {
+  count: number;
+  position: PositionShape;
+  velocity?: VelocityShape;
+  /** Per-particle lifetime in seconds. Default `Infinity` (immortal). */
+  lifetime?: ScalarRange;
+  /** Per-particle user-attribute values. Unmentioned attrs default to zero. */
+  attributes?: Readonly<Record<string, AttributeSampler>>;
+}
+/**
+ * RNG interface. Defaults to `Math.random`. Tests inject a deterministic
+ * source for reproducible assertions.
+ */
+type Rng = () => number;
+//#endregion
+//#region src/particles/state.d.ts
+interface BuiltinBuffers {
+  readonly positions: GPUBuffer;
+  readonly velocities: GPUBuffer;
+  readonly accelPrev: GPUBuffer;
+  readonly accel: GPUBuffer;
+  readonly ages: GPUBuffer;
+  readonly lifetimes: GPUBuffer;
+  readonly alive: GPUBuffer;
+  readonly aliveCount: GPUBuffer;
+}
+interface IndirectBuffers {
+  /** dispatchWorkgroupsIndirect args: [workgroupCountX, 1, 1] */
+  readonly dispatchArgs: GPUBuffer;
+  /** drawIndexedIndirect args: [indexCount, instanceCount, firstIndex, baseVertex, firstInstance] */
+  readonly drawArgs: GPUBuffer;
+}
+interface UserAttributeBuffer {
+  readonly name: string;
+  readonly type: AttributeType;
+  readonly strideBytes: number;
+  readonly buffer: GPUBuffer;
+  /**
+   * Declaration-order index. Matches `@group(1) @binding(<index>)` in the
+   * prelude — so caller code that needs to resolve an attribute's binding
+   * reads this field.
+   */
+  readonly bindingIndex: number;
+}
+/** One attribute's main + scratch buffers + codegen metadata. */
+interface ScatteredAttribute {
+  readonly name: string;
+  /** WGSL element type (e.g. `vec2f`, `f32`, `u32`). Used to pick a scatter pipeline. */
+  readonly wgslType: string;
+  /** Bytes per element on the GPU (std430-aligned). Used for copyBufferToBuffer. */
+  readonly strideBytes: number;
+  /** The main (live) attribute buffer. Forces / integrator / render read & write it. */
+  readonly main: GPUBuffer;
+  /** Compaction scratch — scatter writes here, then copyBufferToBuffer lifts it back. */
+  readonly scratch: GPUBuffer;
+}
+interface CompactionBuffers {
+  /**
+   * Per-slot exclusive prefix sum within its 1024-element block. Written by
+   * scan-local, read by scatter. Sized to `capacity` u32.
+   */
+  readonly scanLocal: GPUBuffer;
+  /**
+   * Per-block total alive count. Written by scan-local (one entry per block),
+   * read by scan-blocks. Sized to `blockCount` u32.
+   */
+  readonly blockTotals: GPUBuffer;
+  /**
+   * Per-block exclusive prefix of blockTotals. Written by scan-blocks, read
+   * by scatter. Sized to `blockCount` u32.
+   */
+  readonly blockOffsets: GPUBuffer;
+  /**
+   * Two u32s: `[base, actualCount]`. Written by emit-reserve (single thread),
+   * read by the emit kernel. Exposing this lets the reserve + emit kernels
+   * share a GPU-resident hand-off with no CPU round trip.
+   */
+  readonly emitReserve: GPUBuffer;
+  /**
+   * Number of scan blocks = `ceil(capacity / ELEMENTS_PER_BLOCK)`. Bounded by
+   * `COMPACT_BLOCK_SIZE` (= 256) by the capacity cap so pass B stays single-
+   * workgroup.
+   */
+  readonly blockCount: number;
+}
+interface ParticleState {
+  readonly capacity: number;
+  readonly catalog: AttributeCatalog;
+  readonly builtins: BuiltinBuffers;
+  readonly indirect: IndirectBuffers;
+  readonly compaction: CompactionBuffers;
+  /** Declaration-ordered — `userAttrs[i].bindingIndex === i`. */
+  readonly userAttrs: readonly UserAttributeBuffer[];
+  /**
+   * Every attribute that must survive compaction — built-ins (sans `accel`
+   * and `alive`) followed by user attributes in declaration order. The
+   * compaction pipeline iterates this list once per step.
+   */
+  readonly scatteredAttributes: readonly ScatteredAttribute[];
+  readonly stateBindGroupLayout: GPUBindGroupLayout;
+  readonly userAttrBindGroupLayout: GPUBindGroupLayout;
+  readonly stateBindGroup: GPUBindGroup;
+  readonly userAttrBindGroup: GPUBindGroup;
+  destroy(): void;
+}
+//#endregion
+//#region src/particles/spatial-hash.d.ts
+interface ParticleSpatialHashOptions {
+  readonly root: TgpuRoot;
+  readonly state: ParticleState;
+  /** World-space maximum pair distance. Drives cell size (= 2 × reach). */
+  readonly reach: number;
+  readonly label?: string;
+}
+declare class ParticleSpatialHash {
+  readonly reach: number;
+  readonly cellSize: number;
+  readonly bucketCount: number;
+  /** Buffers consumers bind in their accumulate kernels (heads/next/cells/params). */
+  readonly consumeBindGroupLayout: GPUBindGroupLayout;
+  readonly consumeBindGroup: GPUBindGroup;
+  private readonly device;
+  private readonly heads;
+  private readonly next;
+  private readonly cells;
+  private readonly paramsBuffer;
+  private readonly clearBindGroup;
+  private readonly clearPipeline;
+  private readonly clearWorkgroups;
+  private readonly buildBindGroup;
+  private readonly buildPipeline;
+  constructor(opts: ParticleSpatialHashOptions);
+  /**
+   * Record clear + indirect build onto the open compute pass. Caller supplies
+   * the same `dispatchArgs` buffer `prepareIndirect` wrote this frame.
+   */
+  record(pass: GPUComputePassEncoder, dispatchArgs: GPUBuffer): void;
+  destroy(): void;
+}
+//#endregion
+//#region src/particles/forces/types.d.ts
+interface ForceAttachContext {
+  readonly root: TgpuRoot;
+  readonly state: ParticleState;
+  /**
+   * Label prefix for GPU-object debug names. Forces should concatenate their
+   * own kind: e.g. `${ctx.label}.drag.pipeline`.
+   */
+  readonly label: string;
+  /**
+   * Request (or get the existing) spatial hash for this reach. Reaches within
+   * a small epsilon share an instance. Only pairwise forces use this; per-
+   * particle forces ignore it.
+   */
+  readonly requestSpatialHash: (reach: number) => ParticleSpatialHash;
+}
+interface ForceHandle {
+  /**
+   * Record this force's dispatch onto an open compute pass. Forces may record
+   * one or more dispatches (e.g. pairwise = build + accumulate); no structural
+   * requirement beyond not ending the pass.
+   */
+  record(pass: GPUComputePassEncoder, ctx: ForceStepContext): void;
+  destroy(): void;
+}
+interface ForceStepContext {
+  /** Buffer populated by `prepareIndirect` — 3×u32 `[wgCount, 1, 1]`. */
+  readonly dispatchArgs: GPUBuffer;
+  /** Fixed step size this frame, in seconds. */
+  readonly dt: number;
+}
+interface Force {
+  readonly kind: string;
+  attach(ctx: ForceAttachContext): ForceHandle;
+  /**
+   * Optional per-step CPU hook for forces that need to sample some JS-side
+   * state and write it into a uniform (e.g. pointer position). Called before
+   * `record()` each step.
+   */
+  prepare?(ctx: ForceStepContext): void;
+}
+/** Opaque ID the system returns from `addForce` to identify a force later. */
+type ForceId = number;
+//#endregion
+//#region src/particles/render/shader.wgsl.d.ts
+type ShapeKind = "circle" | "square" | "triangle" | "rounded-square";
+type ShapeOption = ShapeKind | {
+  readonly sdf: string;
+};
+type ColorOption = "uniform" | {
+  readonly wgsl: string;
+};
+type FadeOption = "none" | "linear" | "lut";
+//#endregion
+//#region src/particles/render/drawable-v3.d.ts
+interface Color4 {
+  r: number;
+  g: number;
+  b: number;
+  a: number;
+}
+type FadeByAgeOption = boolean | {
+  readonly curve: (t: number) => number;
+};
+interface DrawableV3Options {
+  /** Shape SDF. Default 'circle'. */
+  shape?: ShapeOption;
+  /** World-unit half-size (particles are quads of 2·size). Default 4. */
+  size?: number;
+  /**
+   * Uniform RGBA for every live particle. Default opaque white. Ignored
+   * when `colorWgsl` is supplied.
+   */
+  color?: Color4;
+  /**
+   * Custom fragment color WGSL. Must be a snippet that `return`s a `vec4f`.
+   * Receives a local `p: Particle` with fields `position, velocity, age,
+   * lifetime, index`. Mutually exclusive with `color`.
+   */
+  colorWgsl?: string;
+  /**
+   * Seconds of velocity-direction travel added to the quad's length. `0`
+   * (default) keeps the particle round.
+   */
+  velocityStretch?: number;
+  /**
+   * Fade each particle's alpha by its normalized age. `true` applies a linear
+   * 1→0 ramp. `{ curve }` samples the callback at 64 points in [0, 1] and
+   * LUTs it onto the GPU. Immortal particles (lifetime = Infinity) are
+   * unaffected.
+   */
+  fadeByAge?: FadeByAgeOption;
+  /**
+   * Coordinate space the drawable occupies. Particles are world-space by
+   * default; the renderer binds the matching per-space camera bind group.
+   */
+  space?: LayerSpace;
+}
+declare class ParticleDrawableV3 implements CustomDrawable {
+  readonly __customDrawable: true;
+  readonly space: LayerSpace;
+  readonly clipRect: undefined;
+  readonly opaque = false;
+  private readonly device;
+  private readonly bundle;
+  private readonly drawArgsBuffer;
+  private readonly scratch;
+  private lutTexture;
+  private lutSampler;
+  private lutBindGroup;
+  private size;
+  private color;
+  private velocityStretch;
+  private fadeByAge;
+  private destroyed;
+  constructor(renderer: Renderer2D, state: ParticleState, options?: DrawableV3Options);
+  /**
+   * 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: DrawableV3Options): void;
+  record(pass: GPURenderPassEncoder, ctx: CustomDrawableContext): void;
+  destroy(): void;
+  private buildLut;
+  private uploadParams;
+}
+//#endregion
+//#region src/particles/system.d.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.
+ */
+declare class ParticleSystem {
+  private readonly options;
+  readonly capacity: number;
+  /** Attribute names in declaration order. Binding indices match this order. */
+  readonly attributeNames: readonly string[];
+  /** @internal — exposed for kernel attach in later phases. */
+  readonly state: ParticleState;
+  /** @internal — shared across every pipeline this system compiles. */
+  readonly pipelineCache: PipelineCache;
+  private readonly root;
+  private readonly dt;
+  private readonly drawables;
+  private readonly emitQueue;
+  private readonly forces;
+  /** Spatial hashes keyed by quantized reach. Shared across pairwise forces. */
+  private readonly hashes;
+  private nextForceId;
+  private emitStagingCursor;
+  private emitPipeline;
+  private prepareIndirectPipeline;
+  private zeroAccelPipeline;
+  private integratorPipeline;
+  private boundsPipeline;
+  private compactionPipeline;
+  private aliveCountCache;
+  private aliveCountReadback;
+  private aliveCountReadbackInFlight;
+  private destroyed;
+  constructor(owner: GPUOwner, options: ParticleSystemOptions);
+  getAttributeNames(): readonly string[];
+  /**
+   * 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: string, data: ArrayBufferView, offsetElements?: number): void;
+  /**
+   * 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(): number;
+  private scheduleAliveCountReadback;
+  /**
+   * 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: Renderer2D, options?: DrawableV3Options): ParticleDrawableV3;
+  /**
+   * 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: EmitSpec): void;
+  /**
+   * 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: Force): ForceId;
+  private getOrCreateHash;
+  removeForce(id: ForceId): void;
+  hasForce(id: ForceId): boolean;
+  /**
+   * 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?: number): void;
+  destroy(): void;
+  private flushEmissions;
+  private ensureEmitPipeline;
+  private ensurePrepareIndirect;
+  private ensureZeroAccel;
+  private ensureIntegrator;
+  private ensureBounds;
+  private ensureCompaction;
+  private pendingEmitCount;
+  private assertAlive;
+}
+//#endregion
+//#region src/particles/forces/attractor.d.ts
+type AttractorFalloff = "inverseSquare" | "linear" | "spring";
+interface AttractorOptions {
+  /** World-space anchor the attractor pulls toward (negative strength pushes). */
+  point: readonly [number, number];
+  /** Signed strength. Positive = pull, negative = push. */
+  strength: number;
+  /**
+   * Distance beyond which the force is zero. Omit / set to 0 for an
+   * unbounded field. Linear falloff interprets `reach` as the distance where
+   * the force has decayed to zero.
+   */
+  reach?: number;
+  /** Default: `'inverseSquare'`. */
+  falloff?: AttractorFalloff;
+}
+/**
+ * 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.
+ */
+declare function attractor(options: AttractorOptions): Force;
+interface PointerOptions {
+  /** Callable returning the current world-space target each frame. */
+  target: () => readonly [number, number];
+  /**
+   * Attraction strength. A number is static; a callback is resampled every
+   * step — flip sign to toggle attract/repel, set to 0 to disable without
+   * pipeline churn.
+   */
+  strength: number | (() => number);
+  reach?: number;
+  falloff?: AttractorFalloff;
+}
+/**
+ * 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.
+ */
+declare function pointer(options: PointerOptions): Force;
+//#endregion
+//#region src/particles/forces/boids.d.ts
+interface BoidsOptions {
+  /** Neighbourhood radius. Also the cell size driver for the shared hash. */
+  reach: number;
+  /** Alignment weight — match neighbours' heading. Typical 0.5–1.5. */
+  alignment?: number;
+  /** Cohesion weight — steer toward local centroid. Typical 0.3–1.0. */
+  cohesion?: number;
+  /** Separation weight — push away from close neighbours. Typical 1.0–2.0. */
+  separation?: number;
+  /**
+   * Distance at which separation kicks in. Should be smaller than `reach`;
+   * default = reach × 0.4.
+   */
+  separationRadius?: number;
+  /**
+   * Target cruising speed used to build desired-velocity vectors. The kernel
+   * itself doesn't clamp speed — pair with a `drag` force or clamp in your
+   * integrator.
+   */
+  maxSpeed?: number;
+}
+/**
+ * Reynolds boids — alignment, cohesion, separation over a spatial-hash
+ * neighbourhood. Shares the system's hash at the given `reach`.
+ */
+declare function boids(options: BoidsOptions): Force;
+//#endregion
+//#region src/particles/forces/drag.d.ts
+interface DragOptions {
+  /**
+   * Per-second velocity-decay coefficient. Larger → more damping. Applied as
+   * an acceleration, so the integrator step is `v' = v + (a_other - c*v)·dt`.
+   */
+  coefficient: number;
+}
+/** Linear velocity damping. `a += -coefficient * v`. */
+declare function drag(options: DragOptions): Force;
+//#endregion
+//#region src/particles/forces/field.d.ts
+interface FieldWorldBounds {
+  /** World-space x of the texture's left edge. */
+  readonly x: number;
+  /** World-space y of the texture's bottom edge. */
+  readonly y: number;
+  /** World-space width the texture spans. */
+  readonly width: number;
+  /** World-space height the texture spans. */
+  readonly height: number;
+}
+/** Row-major 2×3 affine as six numbers: [m00, m01, m02, m10, m11, m12]. */
+type FieldAffine2x3 = readonly [number, number, number, number, number, number];
+type FieldWrap = "clamp" | "repeat";
+interface FieldOptions {
+  /** 2D GPU texture encoding a vec2 field in its R and G channels. */
+  readonly texture: GPUTexture;
+  /** Acceleration scalar. Multiplies the sampled vector. */
+  readonly strength: number;
+  /**
+   * Rectangle in world space that the texture covers, mapping to uv [0..1]².
+   * Mutually exclusive with `worldToUv`. If neither is given, the texture is
+   * treated as covering `[0, width] × [0, height]` world units 1:1.
+   */
+  readonly worldBounds?: FieldWorldBounds;
+  /**
+   * Explicit world→uv affine matrix. Row-major 2×3:
+   *   `uv = [[m00 m01 m02], [m10 m11 m12]] · [x, y, 1]ᵀ`.
+   */
+  readonly worldToUv?: FieldAffine2x3;
+  /** Sampler address mode outside the unit UV square. Default 'clamp'. */
+  readonly wrap?: FieldWrap;
+  /** Sampler filter. Default 'linear' (falls back to 'nearest' for non-filterable formats). */
+  readonly filter?: "linear" | "nearest";
+}
+/**
+ * Texture-sampled flow-field force. Particles receive
+ * `sampleRG(worldToUv·pos) * strength` as an acceleration each step.
+ */
+declare function field(options: FieldOptions): Force;
+declare class FieldHandle implements ForceHandle {
+  private readonly device;
+  private readonly paramsBuffer;
+  private readonly paramsScratch;
+  private readonly bindGroup;
+  private readonly pipeline;
+  private strength;
+  private matrix;
+  constructor(ctx: ForceAttachContext, opts: FieldOptions);
+  /** Swap strength at runtime without rebuilding the pipeline. */
+  setStrength(strength: number): void;
+  record(pass: GPUComputePassEncoder, ctx: ForceStepContext): void;
+  destroy(): void;
+}
+//#endregion
+//#region src/particles/forces/gravity.d.ts
+interface GravityOptions {
+  /** Direction of the gravity vector. Does not need to be normalized. */
+  direction: [number, number];
+  /** Magnitude in world-units / second². Applied along the normalized direction. */
+  strength: number;
+}
+/** Uniform acceleration in a fixed direction. Classic "falling" force. */
+declare function gravity(options: GravityOptions): Force;
+//#endregion
+//#region src/particles/forces/noise.d.ts
+type NoiseKind = "simplex" | "curl";
+interface NoiseOptions {
+  /** Noise frequency (cycles per world unit). Typical: 0.002–0.05. */
+  scale: number;
+  /** Force magnitude scalar. Rough guideline: match your drag coefficient. */
+  strength: number;
+  /** Default `'curl'` — the divergence-free flow-field look. */
+  kind?: NoiseKind;
+  /**
+   * How fast the field evolves over time. 0 freezes it. Default 1 — each
+   * second of simulation advances the noise seed by 1 unit.
+   */
+  timeScale?: number;
+}
+/**
+ * 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.
+ */
+declare function noise(options: NoiseOptions): Force;
+//#endregion
+//#region src/particles/forces/pairwise.d.ts
+interface PairwiseExtraBinding {
+  /**
+   * WGSL declaration line — e.g. `@group(3) @binding(1) var<storage, read> pairMatrix: array<f32>;`.
+   * Binding indices must be ≥ 1 (binding 0 is reserved for the params uniform).
+   * Note: `matrix` is a reserved WGSL identifier — use `pairMatrix` or similar.
+   */
+  readonly wgsl: string;
+  readonly layoutEntry: GPUBindGroupLayoutEntry;
+  readonly bindGroupEntry: GPUBindGroupEntry;
+}
+interface PairwiseParamsSpec {
+  /** Full WGSL `struct PairwiseParams { ... };` declaration. */
+  readonly structWgsl: string;
+  /** Byte size of the packed struct (std140 uniform rules). */
+  readonly bytes: number;
+  /**
+   * Optional initial pack — receives a DataView into a fresh ArrayBuffer of
+   * `bytes` length in little-endian. Callers can also upload later via
+   * `PairwiseHandle.writeParams`.
+   */
+  readonly write?: (view: DataView) => void;
+}
+interface PairwiseOptions {
+  /** Max pair distance in world units. Hash cell size = 2 × reach. */
+  readonly reach: number;
+  /** User attributes to expose on the `me` / `other` Particle structs. */
+  readonly reads?: readonly string[];
+  /**
+   * WGSL body run inside the neighbourhood loop. Has access to `me`, `other`,
+   * `addAccel(index, delta)`, `params.*`, `hashParams.*` and standard WGSL.
+   * Must not end the loop — a trailing `cursor = next[cursor];` is appended
+   * by the wrapper.
+   */
+  readonly wgsl: string;
+  readonly params?: PairwiseParamsSpec;
+  readonly extraBindings?: readonly PairwiseExtraBinding[];
+  /** Debug label suffix appended to `ctx.label`. Default `pairwise`. */
+  readonly label?: string;
+}
+/**
+ * Generic pairwise force. Typically invoked by presets (`particleLife`,
+ * `boids`) but also exposed directly for ad-hoc user kernels.
+ */
+declare function pairwise(options: PairwiseOptions): Force;
+declare class PairwiseHandle implements ForceHandle {
+  private readonly device;
+  private readonly hash;
+  private readonly pipeline;
+  private readonly stateBindGroup;
+  private readonly userAttrBindGroup;
+  private readonly hashBindGroup;
+  private readonly paramsGroup;
+  private readonly paramsBuffer;
+  private readonly paramsSize;
+  constructor(ctx: ForceAttachContext, opts: PairwiseOptions);
+  record(pass: GPUComputePassEncoder, ctx: ForceStepContext): void;
+  /**
+   * Overwrite the params uniform. Caller packs into a view matching the
+   * struct declared at construction. Bytes beyond `paramsSize` are ignored.
+   */
+  writeParams(data: ArrayBufferView): void;
+  destroy(): void;
+}
+//#endregion
+//#region src/particles/forces/speed-limit.d.ts
+interface SpeedLimitOptions {
+  /** Maximum allowed speed in world-units per second. */
+  maxSpeed: number;
+}
+/**
+ * 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.
+ */
+declare function speedLimit(options: SpeedLimitOptions): Force;
+//#endregion
+//#region src/particles/forces/particle-life.d.ts
+interface PairRule {
+  /** Signed long-range attraction coefficient. Negative = repel. */
+  attract: number;
+  /** Per-pair max reach (0 → fall back to global reach). */
+  reach?: number;
+  /** Per-pair short-range repel distance (0 → fall back to global minDist). */
+  minDist?: number;
+}
+declare class PairMatrix {
+  readonly speciesCount: number;
+  /** Flat f32 data, length = speciesCount² × 4. Row-major. */
+  readonly data: Float32Array;
+  constructor(speciesCount: number);
+  set(a: number, b: number, rule: PairRule): void;
+  get(a: number, b: number): PairRule;
+}
+interface RandomPairMatrixOptions {
+  /** `[min, max]` attract range, uniform. Default `[-1, 1]`. */
+  attract?: [number, number];
+  /** Optional per-pair reach range; omit to inherit the force's global reach. */
+  reach?: [number, number];
+  /** Optional per-pair minDist range; omit to inherit the force's global minDist. */
+  minDist?: [number, number];
+  /** PRNG — default `Math.random`. */
+  rand?: () => number;
+}
+declare function randomPairMatrix(speciesCount: number, opts?: RandomPairMatrixOptions): PairMatrix;
+interface ParticleLifeOptions {
+  /** Global max pair distance. Per-pair `matrix[a,b].reach` may override per pair. */
+  reach: number;
+  /** Universal short-range repel distance. Per-pair override via matrix. */
+  minDist: number;
+  /** Repel strength when `d < minDist`. Default 20. */
+  repelStrength?: number;
+  /** Initial matrix. Size fixes `speciesCount`; swap via `updateMatrix`. */
+  matrix: PairMatrix;
+  /** Name of the declared `u32` species attribute. Default `species`. */
+  speciesAttribute?: string;
+}
+/**
+ * Create a particleLife force. The returned Force's handle exposes
+ * `updateMatrix(newMatrix)` so callers can regenerate the matrix without
+ * rebuilding the pipeline.
+ */
+declare function particleLife(options: ParticleLifeOptions): ParticleLifeForce;
+declare class ParticleLifeForce implements Force {
+  readonly kind = "particleLife";
+  private readonly opts;
+  private handle;
+  constructor(opts: ParticleLifeOptions);
+  attach(ctx: ForceAttachContext): ForceHandle;
+  /**
+   * 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: PairMatrix): void;
+}
+//#endregion
+export { type AttractorFalloff, type AttractorOptions, type AttributeCatalog, type AttributeSampler, type AttributeType, type BoidsOptions, type BoundsMode, type Color4, type ColorOption, type DragOptions, type DrawableV3Options, type EmitSpec, type FadeByAgeOption, type FadeOption, type FieldAffine2x3, FieldHandle, type FieldOptions, type FieldWorldBounds, type FieldWrap, type Force, type ForceAttachContext, type ForceHandle, type ForceId, type ForceStepContext, type GPUOwner, type GravityOptions, type NoiseKind, type NoiseOptions, PairMatrix, type PairRule, type PairwiseExtraBinding, PairwiseHandle, type PairwiseOptions, type PairwiseParamsSpec, ParticleDrawableV3, ParticleLifeForce, type ParticleLifeOptions, ParticleSpatialHash, ParticleSystem, type ParticleSystemOptions, type PointerOptions, type PositionShape, type RandomPairMatrixOptions, type Rng, type ScalarRange, type ShapeKind, type ShapeOption, type SpeedLimitOptions, type VelocityShape, attractor, boids, drag, field, gravity, noise, pairwise, particleLife, pointer, randomPairMatrix, speedLimit };