@vincentt-xr/sdk 2.0.0-alpha.8 → 2.0.0-alpha.9

package/dist/models/Body/index.d.ts

@@ -7,6 +7,7 @@ export declare class BodyTrackingModel extends BaseXRModel {
     private landmarker;
     private processingTime;
     private coordinates;
+    private visibility;
     private sourceCanvas;
     private readonly downscaler;
     constructor();
@@ -15,6 +16,7 @@ export declare class BodyTrackingModel extends BaseXRModel {
     resume(): void;
     dispose(): void;
     private getLandmarks2D;
+    private getVisibility;
     initialize(options?: BodyModelOptions): Promise<void>;
     run({ sourceCanvas, targetFps, analysisScale }: RunModelParams): Promise<void>;
     getModelNode(): XRModelNodeBodyTracking;

package/dist/models/Face/constants.d.ts

@@ -1,2 +1,10 @@
 export declare const FACE_OCCLUDER_SCALE_FACTOR = 0.11;
 export declare const FACE_OCCLUDER_Y_ROTATION_OFFSET_SCALE_FACTOR = 0.004;
+/**
+ * The face landmarker model on the SDK CDN (`libConfig.assetStorageEndpoint`).
+ * Its SRI hash is in `INTEGRITY_MANIFEST`. The live tracker (VIDEO mode) and
+ * the still-image detector (IMAGE mode) both load it.
+ */
+export declare const FACE_TRACKING_MODEL_PATH = "/assets/xr/models/face_tracking.task";
+/** The MediaPipe vision WASM folder on the SDK CDN. */
+export declare const VISION_WASM_PATH = "/assets/xr/wasm";

package/dist/models/Face/index.d.ts

@@ -1,4 +1,3 @@
-import { NormalizedLandmark } from '@mediapipe/tasks-vision';
 import { XRModelNodeFaceTracking } from '../../types/nodes';
 import { RunModelParams } from '../../types';
 import { PerformanceData } from '../../types/common';
@@ -6,6 +5,8 @@ import { FaceModelOptions } from '../../types/face';
 import { BaseXRModel } from '../Base';
 export declare class FaceTrackingModel extends BaseXRModel {
     private landmarker;
+    /** The face model bytes, held while this model is alive (shared with the still-image detector). */
+    private modelBytes;
     private processingTime;
     private sourceCanvas;
     private analysisCanvas;
@@ -16,12 +17,10 @@ export declare class FaceTrackingModel extends BaseXRModel {
     private faces;
     private leftCheekScratch;
     private rightCheekScratch;
-    private landmarkScratch;
     private rotMatrixScratch;
     private rotQuatScratch;
     private rotEulerScratch;
     constructor();
-    private landmarkForSource;
     private extractAndUpdateFaceData;
     private processFaceTracking;
     resume(): void;
@@ -30,17 +29,10 @@ export declare class FaceTrackingModel extends BaseXRModel {
     private getDetectionResults;
     private getRawFaceTrackingData;
     initialize(options?: FaceModelOptions): Promise<void>;
+    private releaseModelBytes;
     run({ sourceCanvas, getSource, targetFps, analysisScale, }: RunModelParams): Promise<void>;
     getModelNode(): XRModelNodeFaceTracking;
     getPerformanceData(): Promise<PerformanceData>;
 }
 export declare const resolveFaceYawRotation: (yawDegrees: number) => number;
 export declare const resolveFaceAnalysisDimension: (numFaces: number) => 1024 | 512;
-/**
- * Reference (allocating) source-aware landmark normalization. Non-webcam
- * sources (image/video) read mirrored from MediaPipe, so x is flipped to
- * display space. The per-frame extraction path uses an in-place scratch
- * variant (`landmarkForSource`) to avoid allocating; this pure form exists
- * for callers/tests that need a plain array transform.
- */
-export declare const normalizeFaceLandmarksForSource: (landmarks: NormalizedLandmark[], sourceKind?: "webcam" | "image" | "video") => NormalizedLandmark[];

package/dist/models/Face/rotation.d.ts

@@ -1,3 +1,18 @@
-import { Euler, Vector3 } from 'three';
-/** Writes the SDK convention: up/left positive, down/right negative. */
-export declare const writeFaceRotation: (euler: Euler, target: Vector3) => Vector3;
+import { Euler, Matrix4, Quaternion, Vector3 } from 'three';
+/**
+ * Writes the SDK convention: up and the person's own left positive. `euler`
+ * is the x-mirrored, inverted pose, whose `-y` / `z` read toward the SCREEN's
+ * left; that is the person's left on the mirrored webcam (`feedMirrored`,
+ * the default), and their right on an unmirrored feed, where yaw and roll are
+ * negated. Negating yaw and roll of an XYZ Euler is exactly the x-mirror of
+ * the rotation (pitch commutes with it), so the reading is the head as seen in
+ * a mirror on every feed (#298).
+ */
+export declare const writeFaceRotation: (euler: Euler, target: Vector3, feedMirrored?: boolean) => Vector3;
+/**
+ * Writes the head's orientation from MediaPipe's facial transformation matrix:
+ * the rotation part, as-is. The matrix maps the canonical face into the camera
+ * space of the analyzed frame — the feed as displayed — whose axes are the
+ * three.js world axes, so no mirror or sign flip applies (#169).
+ */
+export declare const writeFaceQuaternion: (matrix: Matrix4, target: Quaternion) => Quaternion;

package/dist/models/Hand/HandTracking.d.ts

@@ -2,6 +2,20 @@ import { XRModelNodeHandTracking } from '../../types/nodes';
 import { RunModelParams } from '../../types';
 import { PerformanceData } from '../../types/common';
 import { BaseXRModel } from '../Base';
+/**
+ * The hand landmarker's thresholds. In video mode MediaPipe keeps following a
+ * hand's last box while the landmark model's presence score stays over
+ * `minHandPresenceConfidence`; at the 0.5 default a face under a hand's last
+ * position kept scoring as a "ghost" hand (a `HandCutout` then cut a hole in
+ * the face's makeup or liquify there). 0.65 is the strictest that still keeps
+ * a real hand half hidden behind the other (both hands over the mouth, which
+ * score between 0.65 and 0.7); detection and tracking keep MediaPipe's 0.5.
+ */
+export declare const HAND_TRACKING_CONFIDENCE: Readonly<{
+    minHandDetectionConfidence: 0.5;
+    minHandPresenceConfidence: 0.65;
+    minTrackingConfidence: 0.5;
+}>;
 export declare class HandTrackingModel extends BaseXRModel {
     private landmarker;
     private processingTime;
@@ -9,7 +23,9 @@ export declare class HandTrackingModel extends BaseXRModel {
     private coordinates;
     private gesture;
     private handedness;
+    private poses;
     private sourceCanvas;
+    private getSource;
     private readonly downscaler;
     constructor();
     private getHandData;
@@ -17,7 +33,7 @@ export declare class HandTrackingModel extends BaseXRModel {
     resume(): void;
     dispose(): void;
     initialize(): Promise<void>;
-    run({ sourceCanvas, targetFps, analysisScale }: RunModelParams): Promise<void>;
+    run({ sourceCanvas, getSource, targetFps, analysisScale, }: RunModelParams): Promise<void>;
     getModelNode(): XRModelNodeHandTracking;
     getPerformanceData(): Promise<PerformanceData>;
 }

package/dist/models/Segmentation/index.d.ts

@@ -19,6 +19,8 @@ export declare class BackgroundSegmentationModel extends BaseXRModel {
     private isProcessing;
     private latestMask;
     private rawCache;
+    /** When the frame behind `latestMask` was segmented (`performance.now()`). */
+    private latestMaskTimeMs;
     private quality;
     constructor();
     private getQualityScaleFactor;

package/dist/models/nodeSource.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The model behind a model node. `getModelNode()` builds a new node object on
+ * each call (each `useXRModelNode` consumer holds its own), so per-model
+ * bookkeeping (a warning shown once) keys on this instead of the node. Not
+ * enumerable; absent on custom nodes.
+ */
+export declare const MODEL_NODE_SOURCE: unique symbol;
+/** The model that made `node` (`MODEL_NODE_SOURCE`), else the node itself. */
+export declare const modelNodeSource: (node: object) => object;

package/dist/particles/emission.d.ts

@@ -0,0 +1,24 @@
+/**
+ * When particles are born (pure): a continuous rate, with the fraction of a
+ * particle left at the end of a frame carried to the next, and each birth
+ * placed at its own moment inside the frame, so a moving emitter leaves
+ * evenly spaced particles at any frame rate.
+ */
+/**
+ * The longest stretch emitted in one frame (s): after a stall (a hidden tab,
+ * a slow load) emission resumes at its rate instead of firing a burst.
+ */
+export declare const PARTICLE_MAX_STEP = 0.25;
+export type ParticleEmission = {
+    /** The fraction of the next particle already due (0..1). */
+    carry: number;
+};
+export declare const createParticleEmission: () => ParticleEmission;
+/**
+ * The particles due over a frame of `dt` seconds at `rate` per second. Each
+ * birth goes into `out` as its moment in the frame (0 = the frame's start,
+ * 1 = now), oldest first; `out.length` is the count. Only the last
+ * `PARTICLE_MAX_STEP` seconds of a long frame emit, and at most `max`
+ * particles (the newest) per frame.
+ */
+export declare const stepParticleEmission: (emission: ParticleEmission, rate: number, dt: number, out?: number[], max?: number) => number[];

package/dist/particles/eyes.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Where an eye emitter sits (pure): in the canonical head frame
+ * (`CanonicalHeadFrame`: centimetres, +Y up, +Z out of the face, +X
+ * MediaPipe's left), at the centre of the eye opening, a little in front of
+ * it, facing +Z (straight out of the face).
+ */
+/** What `<ParticleEmitter target>` emits from: one eye (the person's own side) or both. */
+export declare const PARTICLE_EMITTER_TARGETS: readonly ["leftEye", "rightEye", "eyes"];
+export type ParticleEmitterTarget = (typeof PARTICLE_EMITTER_TARGETS)[number];
+/** How far in front of the eye opening the emitter sits (cm), clear of the eye's own surface. */
+export declare const PARTICLE_EYE_FORWARD = 0.4;
+/**
+ * The eye's centre (cm, canonical head frame) on MediaPipe's left (+X); the
+ * other eye is its mirror. The two contours averaged, so both eyes match.
+ */
+export declare const PARTICLE_EYE_CENTRE: readonly [number, number, number];
+/**
+ * The person's own `side` eye in the canonical head frame on this feed:
+ * their left eye is MediaPipe's left (+X) on an unmirrored feed and
+ * MediaPipe's right (−X) on the mirrored webcam.
+ */
+export declare const particleEyePosition: (side: "left" | "right", mirrored: boolean) => [number, number, number];
+/** The eyes a target emits from (the person's own sides). */
+export declare const particleTargetSides: (target: ParticleEmitterTarget) => ("left" | "right")[];

package/dist/particles/glsl.d.ts

@@ -0,0 +1,14 @@
+/** Uniforms and functions shared by the vertex shader and the self-test (GLSL ES 3.00 and 1.00). */
+export declare const PARTICLE_STATE_GLSL: string;
+/**
+ * One quad per particle (corners ±1 in `position`), in view space: the
+ * model matrix is ignored (particles are in world space). A streak runs from
+ * where the particle was `uStretch` seconds ago (at most its age) to where it
+ * is. A dead particle collapses outside the clip volume.
+ */
+export declare const PARTICLE_VERTEX_SHADER: string;
+/**
+ * Straight alpha: the glow's soft disc, or the streak's soft line
+ * brightening toward its head (a soft cross-section, both ends fading).
+ */
+export declare const PARTICLE_FRAGMENT_SHADER = "\nvarying vec2 vCorner;\nvarying vec4 vColor;\nvarying float vStreak;\nvoid main() {\n  float shape;\n  if (vStreak > 0.5) {\n    float across = exp(-5.0 * vCorner.x * vCorner.x);\n    float along = clamp(vCorner.y * 0.5 + 0.5, 0.0, 1.0);\n    shape = across * along * along * (1.0 - smoothstep(0.9, 1.0, along));\n  } else {\n    float r2 = dot(vCorner, vCorner);\n    shape = r2 < 1.0 ? (1.0 - r2) * (1.0 - r2) : 0.0;\n  }\n  float alpha = shape * vColor.a;\n  if (alpha < 0.002) discard;\n  gl_FragColor = vec4(vColor.rgb, alpha);\n  #include <colorspace_fragment>\n}\n";

package/dist/particles/index.d.ts

@@ -0,0 +1,10 @@
+export { DEFAULT_PARTICLE_SETTINGS, PARTICLE_BLENDINGS, PARTICLE_MAX_COLORS, PARTICLE_MAX_PARTICLES, PARTICLE_SETTINGS_RANGES, PARTICLE_SHAPES, PARTICLE_SPRITES, parseParticleColor, particleCapacity, resolveParticleSettings, type ParticleBlending, type ParticleColor, type ParticleOverLife, type ParticleSettings, type ParticleShape, type ParticleSprite, type ResolvedParticleSettings, } from './settings';
+export { createParticleRandom, createParticleStart, sampleParticleCone, sampleParticleStart, type ParticleRandom, type ParticleStart, } from './shapes';
+export { PARTICLE_RECORD, PARTICLE_RECORD_FLOATS, ParticleRing, createParticleRecord, type ParticleRecord, type ParticleSlotRange, } from './ring';
+export { PARTICLE_DRAG_SERIES_LIMIT, createParticleSample, particleAcceleration, particleColorAt, particleDragAcceleration, particleDragDistance, particleOverLife, sampleParticle, type ParticleSample, } from './motion';
+export { PARTICLE_MAX_STEP, createParticleEmission, stepParticleEmission, type ParticleEmission, } from './emission';
+export { PARTICLE_PRESETS, PARTICLE_PRESET_KEYS, isParticlePreset, particlePresetBase, type ParticlePreset, } from './presets';
+export { PARTICLE_EMITTER_TARGETS, PARTICLE_EYE_CENTRE, PARTICLE_EYE_FORWARD, particleEyePosition, particleTargetSides, type ParticleEmitterTarget, } from './eyes';
+export { PARTICLE_FRAGMENT_SHADER, PARTICLE_STATE_GLSL, PARTICLE_VERTEX_SHADER } from './glsl';
+export { ParticleSystem, applyParticleUniforms, createParticleUniforms, type ParticleUniforms, } from './system';
+export { ParticleSpawner, particleUnitOf, spawnParticles, type ParticleSpawnFrame, } from './spawner';

package/dist/particles/motion.d.ts

@@ -0,0 +1,42 @@
+import { ResolvedParticleSettings } from './settings';
+/**
+ * Particle motion and looks over life (pure): the closed forms the vertex
+ * shader evaluates, so a particle's state at any time follows from its spawn
+ * record alone. This is the CPU reference the shader is tested against.
+ *
+ * With drag k and a constant acceleration a (gravity and wind):
+ *   v(t) = v0·e^(−kt) + a·D(t),        D(t) = (1 − e^(−kt)) / k
+ *   x(t) = x0 + v0·D(t) + a·A(t),      A(t) = (t − D(t)) / k
+ * and with no drag D = t, A = t²/2 (a short series near kt = 0 keeps both
+ * accurate in float32).
+ */
+/** Below this k·t the series replaces the exponential forms. */
+export declare const PARTICLE_DRAG_SERIES_LIMIT = 0.01;
+/** How far a unit start velocity carries in `t` seconds under drag `k`: D(t). */
+export declare const particleDragDistance: (k: number, t: number) => number;
+/** How far a unit constant acceleration carries in `t` seconds under drag `k`: A(t). */
+export declare const particleDragAcceleration: (k: number, t: number) => number;
+/** The world acceleration (gravity along −Y plus wind), in emitter units / s². */
+export declare const particleAcceleration: (settings: Pick<ResolvedParticleSettings, "gravity" | "wind">, out?: [number, number, number]) => [number, number, number];
+/** Linear between birth (0) and death (1). */
+export declare const particleOverLife: (range: readonly [number, number], life: number) => number;
+/** The colour at `life` (0..1): the colours spread evenly from birth to death, mixed between neighbours. */
+export declare const particleColorAt: (settings: Pick<ResolvedParticleSettings, "colors" | "colorCount">, life: number, out?: [number, number, number]) => [number, number, number];
+/** One particle at one time. */
+export type ParticleSample = {
+    /** Born and not yet past its lifetime. */
+    alive: boolean;
+    /** Seconds since birth. */
+    age: number;
+    /** 0 at birth … 1 at death. */
+    life: number;
+    position: [number, number, number];
+    velocity: [number, number, number];
+    /** World units. */
+    size: number;
+    opacity: number;
+    color: [number, number, number];
+};
+export declare const createParticleSample: () => ParticleSample;
+/** Slot `slot` of a ring's records at `time` (s), as the shader computes it. */
+export declare const sampleParticle: (data: Float32Array, slot: number, time: number, settings: ResolvedParticleSettings, out?: ParticleSample) => ParticleSample;

package/dist/particles/presets.d.ts

@@ -0,0 +1,12 @@
+import { ParticleSettings } from './settings';
+/**
+ * Built-in looks (pure). A preset is a base the emitter's own settings go on
+ * top of: `<ParticleEmitter preset="laser" speed={400} />` is the laser with
+ * faster beams. Values are in centimetres, as inside a head frame.
+ */
+export declare const PARTICLE_PRESET_KEYS: readonly ["laser"];
+export type ParticlePreset = (typeof PARTICLE_PRESET_KEYS)[number];
+export declare const PARTICLE_PRESETS: Readonly<Record<ParticlePreset, Partial<ParticleSettings>>>;
+export declare const isParticlePreset: (value: unknown) => value is ParticlePreset;
+/** The settings an emitter starts from: the preset over the defaults (the defaults alone for none or an unknown name). */
+export declare const particlePresetBase: (preset?: string | null) => ParticleSettings;

package/dist/particles/ring.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The particles' spawn records (pure): a fixed ring of slots, each written
+ * once when a particle is emitted and never touched again. The shader works
+ * out everything else from the record and the time, so only the slots
+ * written since the last upload go to the GPU.
+ */
+/** Floats per particle (three vec4s). */
+export declare const PARTICLE_RECORD_FLOATS = 12;
+/**
+ * Each record's layout (float offsets): start position (world) and birth
+ * time (s); start velocity (world units / s) and lifetime (s); size scale
+ * (world units per emitter unit, times the size jitter), unit (world units
+ * per emitter unit, for gravity and wind) and a random seed (0..1).
+ */
+export declare const PARTICLE_RECORD: Readonly<{
+    position: 0;
+    birth: 3;
+    velocity: 4;
+    lifetime: 7;
+    sizeScale: 8;
+    unit: 9;
+    seed: 10;
+}>;
+/** One particle as emitted (reuse one object: `push` copies it). */
+export type ParticleRecord = {
+    position: [number, number, number];
+    velocity: [number, number, number];
+    birth: number;
+    lifetime: number;
+    sizeScale: number;
+    unit: number;
+    seed: number;
+};
+export declare const createParticleRecord: () => ParticleRecord;
+/** A range of slots: `[first, count]`. */
+export type ParticleSlotRange = [number, number];
+export declare class ParticleRing {
+    readonly capacity: number;
+    /** `capacity × PARTICLE_RECORD_FLOATS` floats; a lifetime of 0 is an empty slot. */
+    readonly data: Float32Array;
+    private head;
+    private dirtyFirst;
+    private dirtyCount;
+    constructor(capacity: number);
+    /** The slot the next particle goes in (the oldest). */
+    get next(): number;
+    /** Writes a particle over the oldest slot; returns the slot. */
+    push(record: ParticleRecord): number;
+    /**
+     * The slots written since the last call, as at most two ranges (one when
+     * they do not wrap, the whole ring after a full lap), then forgets them.
+     */
+    takeDirty(out?: ParticleSlotRange[]): ParticleSlotRange[];
+    /** Empties every slot (and marks them all for upload). */
+    clear(): void;
+    /** Particles alive at `time` (s): born and not yet past their lifetime. */
+    aliveAt(time: number): number;
+}

package/dist/particles/selfTest.d.ts

@@ -0,0 +1,53 @@
+import * as THREE from "three";
+/**
+ * A GPU self-test of the particles on this device's WebGL2:
+ *
+ * 1. **compile**: the particle and parity shaders link, with no shader or GL error.
+ * 2. **parity**: `PARTICLE_STATE_GLSL` matches `sampleParticle` (the CPU
+ *    reference) for particles from a moving, turning, scaled emitter, at
+ *    several times, under no forces, under drag, gravity and wind, and with
+ *    colour ramps (float targets; skipped where the GPU cannot render them).
+ * 3. **same frame**: particles emitted in the scene's before-render hook
+ *    draw in that very render, along the emitter's path, and nowhere else.
+ * 4. **streak**: a streak lies along its motion and never reaches behind
+ *    its emitter (its tail is at most its age).
+ * 5. **dead**: past their lifetime, particles draw nothing.
+ *
+ * The headless smoke run drives it (`example/smoke/particles.spec.ts`); open
+ * `/smoke/particles.html` on the dev server to run it on a device.
+ */
+export type ParticleSelfTestCheck = {
+    name: string;
+    ok: boolean;
+    detail: string;
+};
+export type ParticleSelfTestResult = {
+    ok: boolean;
+    error: string | null;
+    checks: ParticleSelfTestCheck[];
+};
+export declare const PARTICLE_SELF_TEST: Readonly<{
+    parityParticles: 256;
+    parityTimes: readonly number[];
+    /** Position and velocity: |GPU − CPU| ≤ abs + rel × |CPU|. */
+    motionTolerance: {
+        abs: number;
+        rel: number;
+    };
+    /** Size, opacity, colour and life. */
+    looksTolerance: 0.0002;
+    /** Birth and death within this of the time are not compared (float32 rounding). */
+    boundaryMargin: 0.001;
+    /** The draw checks' target (px, square) and view (world units across). */
+    drawSize: 128;
+    drawView: 32;
+    /** A pixel is lit above this (8-bit sum of RGB). */
+    litLevel: 24;
+}>;
+/**
+ * Runs every check on `options.renderer` (default: an offscreen renderer it
+ * disposes). Never rejects: failures and thrown errors are in the result.
+ */
+export declare const runParticleSelfTest: (options?: {
+    renderer?: THREE.WebGLRenderer;
+}) => Promise<ParticleSelfTestResult>;

package/dist/particles/settings.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Particle emitter settings (pure): the fields, their defaults and ranges,
+ * and `resolveParticleSettings`, which turns any partial (from an app or an
+ * agent) into a complete, clamped set the emitter and the shader read.
+ *
+ * Lengths, speeds and forces are in the emitter's own units: its world
+ * scale when a particle is emitted converts them (inside a head frame they
+ * are centimetres). Gravity pulls along the world's −Y, wind pushes along
+ * the world's axes; the shape and the direction particles leave in are in
+ * the emitter's axes (+Z forward).
+ */
+/** Where particles start: one point, a sphere, a box, or the base of a cone. */
+export declare const PARTICLE_SHAPES: readonly ["point", "sphere", "box", "cone"];
+export type ParticleShape = (typeof PARTICLE_SHAPES)[number];
+/** The built-in particle shapes: a soft round glow, or a streak along the motion. */
+export declare const PARTICLE_SPRITES: readonly ["glow", "streak"];
+export type ParticleSprite = (typeof PARTICLE_SPRITES)[number];
+/** `additive` brightens what is behind (light, lasers); `normal` covers it. */
+export declare const PARTICLE_BLENDINGS: readonly ["additive", "normal"];
+export type ParticleBlending = (typeof PARTICLE_BLENDINGS)[number];
+/** A CSS colour (`"#ff3b30"`, `"red"`, `"rgb(255 0 0)"`) or a hex number (`0xff3b30`). */
+export type ParticleColor = string | number;
+/** One value for the whole life, or `[start, end]` (linear over life). */
+export type ParticleOverLife = number | readonly [number, number];
+/** The most colours over life. */
+export declare const PARTICLE_MAX_COLORS = 4;
+/** The most particles one emitter keeps alive. */
+export declare const PARTICLE_MAX_PARTICLES = 65536;
+export type ParticleSettings = {
+    /** Particles per second. */
+    rate: number;
+    /** Seconds each particle lives. */
+    lifetime: number;
+    /** 0..1: each particle lives `lifetime × (1 − lifetimeJitter × random)`. */
+    lifetimeJitter: number;
+    /** Where particles start (the emitter's axes and units). */
+    shape: ParticleShape;
+    /** `sphere`: its radius. `cone`: its base radius (0 = from one point). */
+    radius: number;
+    /** `box`: its full size along x, y, z. */
+    boxSize: readonly [number, number, number];
+    /**
+     * Degrees around the emitter's +Z: `point` and `box` send particles within
+     * this angle, `cone` is a cone of this half angle (180 = every direction).
+     * `sphere` sends them outward.
+     */
+    angle: number;
+    /** `sphere` and `box`: start on the surface only. */
+    surface: boolean;
+    /** Start speed, units per second. */
+    speed: number;
+    /** 0..1: each particle starts at `speed × (1 − speedJitter × random)`. */
+    speedJitter: number;
+    /** Pull along the world's −Y, units per second² (negative floats up). */
+    gravity: number;
+    /** Constant push along the world's x, y, z, units per second². */
+    wind: readonly [number, number, number];
+    /** How fast speed decays, per second (0: none). With gravity or wind it sets the top speed. */
+    drag: number;
+    /** Size over life, units (the glow's width, the streak's thickness). */
+    size: ParticleOverLife;
+    /** 0..1: each particle is `size × (1 − sizeJitter × random)`. */
+    sizeJitter: number;
+    /** Colour over life: one colour, or up to 4 spread evenly from birth to death. */
+    color: ParticleColor | readonly ParticleColor[];
+    /** Opacity over life, 0..1. */
+    opacity: ParticleOverLife;
+    /** The built-in shape drawn. */
+    sprite: ParticleSprite;
+    /** `streak`: its length, as the seconds of motion it covers. */
+    stretch: number;
+    blending: ParticleBlending;
+    /** The most particles alive at once; 0 (default) sizes it from `rate × lifetime`. */
+    maxParticles: number;
+    /** The random sequence's seed: the same seed and inputs give the same particles. */
+    seed: number;
+};
+/** A generic emitter: a soft white spray along +Z, sized for centimetres. */
+export declare const DEFAULT_PARTICLE_SETTINGS: ParticleSettings;
+/** Valid ranges of the numeric fields (each component of `boxSize`, `wind`, `size`, `opacity`). */
+export declare const PARTICLE_SETTINGS_RANGES: {
+    readonly rate: readonly [0, 10000];
+    readonly lifetime: readonly [0.02, 30];
+    readonly lifetimeJitter: readonly [0, 1];
+    readonly radius: readonly [0, 10000];
+    readonly boxSize: readonly [0, 10000];
+    readonly angle: readonly [0, 180];
+    readonly speed: readonly [0, 100000];
+    readonly speedJitter: readonly [0, 1];
+    readonly gravity: readonly [-100000, 100000];
+    readonly wind: readonly [-100000, 100000];
+    readonly drag: readonly [0, 100];
+    readonly size: readonly [0, 10000];
+    readonly sizeJitter: readonly [0, 1];
+    readonly opacity: readonly [0, 1];
+    readonly stretch: readonly [0, 1];
+    readonly maxParticles: readonly [0, 65536];
+    readonly seed: readonly [-1000000000, 1000000000];
+};
+/** Everything the emitter and the shader read, complete and clamped. */
+export type ResolvedParticleSettings = Omit<ParticleSettings, "boxSize" | "wind" | "size" | "color" | "opacity"> & {
+    boxSize: [number, number, number];
+    wind: [number, number, number];
+    /** Size at birth and at death. */
+    size: [number, number];
+    /** Opacity at birth and at death. */
+    opacity: [number, number];
+    /** The colours over life, linear RGB, `colorCount` of them (1..4), 3 floats each. */
+    colors: Float32Array;
+    colorCount: number;
+    /** Particles kept (the ring's size): `maxParticles`, or enough for `rate × lifetime`. */
+    capacity: number;
+};
+/** A colour as linear RGB, or null when it cannot be read. */
+export declare const parseParticleColor: (value: unknown) => [number, number, number] | null;
+/**
+ * Particles to keep for `rate × lifetime` alive at once, with room for a
+ * slow frame's spawns: 10% more plus a tenth of a second's worth.
+ */
+export declare const particleCapacity: (rate: number, lifetime: number, maxParticles?: number) => number;
+/**
+ * Any partial settings → complete, clamped settings. Missing, non-finite or
+ * unknown values fall back to `base` (default `DEFAULT_PARTICLE_SETTINGS`);
+ * numbers clamp to `PARTICLE_SETTINGS_RANGES`; colours that cannot be read
+ * fall back as a whole; more than 4 colours keep the first 4.
+ */
+export declare const resolveParticleSettings: (input?: Partial<ParticleSettings>, base?: ParticleSettings) => ResolvedParticleSettings;

package/dist/particles/shapes.d.ts

@@ -0,0 +1,29 @@
+import { ResolvedParticleSettings } from './settings';
+/**
+ * Where a particle starts and which way it leaves (pure), in the emitter's
+ * own axes and units: +Z is forward. The emitter's world transform is
+ * applied when the particle is emitted (`spawnParticles`).
+ */
+/** A seeded random sequence in [0, 1) (mulberry32): the same seed gives the same numbers. */
+export type ParticleRandom = () => number;
+export declare const createParticleRandom: (seed: number) => ParticleRandom;
+/** A start point and a unit direction, written in place. */
+export type ParticleStart = {
+    position: [number, number, number];
+    direction: [number, number, number];
+};
+export declare const createParticleStart: () => ParticleStart;
+/** A direction within `angle` degrees of +Z, uniform over that cap of the sphere. */
+export declare const sampleParticleCone: (angle: number, random: ParticleRandom, out: [number, number, number]) => [number, number, number];
+/**
+ * One particle's start (the emitter's axes and units):
+ * - `point`: at the origin, leaving within `angle` of +Z;
+ * - `sphere`: inside the sphere of `radius` (on it with `surface`), leaving
+ *   outward from the centre;
+ * - `box`: inside the box of `boxSize` centred on the origin (on its faces
+ *   with `surface`), leaving within `angle` of +Z;
+ * - `cone`: on the disc of `radius` at the origin, facing +Z, leaving along
+ *   the cone of half angle `angle` (tilted outward by `angle × distance /
+ *   radius`; with radius 0, anywhere within `angle`).
+ */
+export declare const sampleParticleStart: (settings: Pick<ResolvedParticleSettings, "shape" | "radius" | "boxSize" | "angle" | "surface">, random: ParticleRandom, out?: ParticleStart) => ParticleStart;

package/dist/particles/spawner.d.ts

@@ -0,0 +1,60 @@
+import { ParticleRing } from './ring';
+import { ResolvedParticleSettings } from './settings';
+import { ParticleRandom } from './shapes';
+import * as THREE from "three";
+/**
+ * Emitting particles into the ring (pure, no GPU): each frame, the
+ * particles due are placed along the emitter's path from its last world
+ * transform to this one, at their own moments in the frame, and written as
+ * spawn records in world space. They keep their own path from then on.
+ */
+/** The emitter's mean world scale (world units per emitter unit). */
+export declare const particleUnitOf: (matrix: THREE.Matrix4) => number;
+/** One frame of the emitter's motion: its world transform and the clock (s) at the last frame and now. */
+export type ParticleSpawnFrame = {
+    from: THREE.Matrix4;
+    to: THREE.Matrix4;
+    timeFrom: number;
+    timeTo: number;
+};
+/**
+ * Writes one particle per birth moment (`births`, 0..1 through the frame)
+ * into `ring`. Settings are in the emitter's units: its world scale at the
+ * birth converts speed and size and is kept for gravity and wind. The random
+ * sequence advances by the same count per particle whatever the settings.
+ */
+export declare const spawnParticles: (ring: ParticleRing, settings: ResolvedParticleSettings, frame: ParticleSpawnFrame, births: readonly number[], random: ParticleRandom) => void;
+/**
+ * One emitter's particles on the CPU side: its settings, its ring of spawn
+ * records, its rate and random sequence, and its last pose. `update` once a
+ * frame with the emitter's world matrix and the clock; upload the ring's
+ * dirty slots after it.
+ */
+export declare class ParticleSpawner {
+    private ringValue;
+    private settingsValue;
+    private random;
+    private readonly emission;
+    private readonly births;
+    private readonly last;
+    private lastTime;
+    private readonly frame;
+    constructor(settings: ResolvedParticleSettings);
+    get ring(): ParticleRing;
+    get settings(): ResolvedParticleSettings;
+    /**
+     * New settings. A new capacity starts a new (empty) ring and a new seed a
+     * new random sequence; anything else applies to the particles already out
+     * (the shader reads it every frame) and to the next ones.
+     */
+    setSettings(settings: ResolvedParticleSettings): void;
+    /**
+     * One frame at `time` (s) with the emitter at `matrix` (world): emits the
+     * particles due since the last update along the emitter's path, unless
+     * `emitting` is false. The first update only records the pose. Returns how
+     * many were emitted.
+     */
+    update(matrix: THREE.Matrix4, time: number, emitting?: boolean): number;
+    /** Removes every particle and forgets the last pose (the next update starts again). */
+    reset(): void;
+}