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

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

@@ -1,11 +1,60 @@
 import { RunModelParams } from '../../types';
 import { PerformanceData } from '../../types/common';
+/**
+ * Per-model health read by `useXRDiagnostics`. Every field is a current value
+ * (not an event); `null` means "not measured yet" or "not applicable".
+ */
+export type XRModelDiagnostics = {
+    /** Duration of the last inference in milliseconds. */
+    inferenceMs: number | null;
+    /** Inferences per second over the last ~1 s window. */
+    inferenceFps: number;
+    /** Total inferences since `run()`. */
+    inferences: number;
+    /**
+     * RAF ticks the model saw but did not analyse (throttled by `targetFps`, or
+     * skipped while busy). A high value next to a low `inferenceFps` means the
+     * cap is doing its job; a high value with no cap means the device is slow.
+     */
+    skippedFrames: number;
+    /** Subjects detected in the last inference (faces, hands, bodies; `null` when not applicable). */
+    detections: number | null;
+    /** Detector confidence of the primary subject, 0..1 (`null` when the model reports none). */
+    confidence: number | null;
+    /** `error` when the last inference threw; models without inline status report `"ready"`. */
+    status: "ready" | "error";
+    error: Error | null;
+    paused: boolean;
+    disposed: boolean;
+};
 export declare class BaseXRModel {
     protected disposed: boolean;
     protected paused: boolean;
     protected rafId: number | null;
+    private statInferenceMs;
+    private statInferences;
+    private statWindowStart;
+    private statWindowCount;
+    private statFps;
+    private statSkipped;
+    private statDetections;
+    private statConfidence;
+    private statStatus;
+    private statError;
+    /** Record one completed inference that started at `startMs` (`performance.now()`). */
+    protected recordInference(startMs: number, endMs?: number): number;
+    /** Record what the last inference found (subjects and the primary confidence). */
+    protected recordDetections(count: number | null, confidence?: number | null): void;
+    /** Record an inference failure (or clear it with `null`). */
+    protected recordInferenceError(error: Error | null): void;
+    /** Current health snapshot. Allocates a small object; sample it at UI rate, not per frame. */
+    getDiagnostics(): XRModelDiagnostics;
     protected targetFrameIntervalMs: number;
     protected lastInferenceMs: number;
+    /** Analysis-resolution multiplier (0.25..1) from the quality tier; subclasses read it where they downscale. */
+    protected analysisScale: number;
+    /** Clamp and store the analysis scale; subclasses with a downscaler forward it. */
+    protected setAnalysisScale(scale: number | undefined): void;
     /** Set the per-frame inference cap. fps <= 0 (or undefined) → uncapped. */
     protected setTargetFps(fps: number | undefined): void;
     /**

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,8 +16,9 @@ export declare class BodyTrackingModel extends BaseXRModel {
     resume(): void;
     dispose(): void;
     private getLandmarks2D;
+    private getVisibility;
     initialize(options?: BodyModelOptions): Promise<void>;
-    run({ sourceCanvas, targetFps }: RunModelParams): Promise<void>;
+    run({ sourceCanvas, targetFps, analysisScale }: RunModelParams): Promise<void>;
     getModelNode(): XRModelNodeBodyTracking;
     getPerformanceData(): Promise<PerformanceData>;
 }

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>;
-    run({ sourceCanvas, getSource, targetFps }: RunModelParams): 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/GestureTracking.d.ts

@@ -15,7 +15,7 @@ export declare class GestureTrackingModel extends BaseXRModel {
     resume(): void;
     dispose(): void;
     initialize(): Promise<void>;
-    run({ sourceCanvas, targetFps }: RunModelParams): Promise<void>;
+    run({ sourceCanvas, targetFps, analysisScale }: RunModelParams): Promise<void>;
     getModelNode(): XRModelNodeGestureTracking;
     getPerformanceData(): Promise<PerformanceData>;
 }

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 }: RunModelParams): Promise<void>;
+    run({ sourceCanvas, getSource, targetFps, analysisScale, }: RunModelParams): Promise<void>;
     getModelNode(): XRModelNodeHandTracking;
     getPerformanceData(): Promise<PerformanceData>;
 }

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

@@ -0,0 +1,49 @@
+import { RunModelParams } from '../../types';
+import { PerformanceData } from '../../types/common';
+import { HolisticModelOptions } from '../../types/holistic';
+import { XRModelNodeHolisticTracking } from '../../types/nodes';
+import { BaseXRModel } from '../Base';
+export declare class HolisticTrackingModel extends BaseXRModel {
+    private landmarker;
+    private status;
+    private error;
+    private processingTime;
+    private sourceCanvas;
+    private getSource;
+    private downscaler;
+    private raw;
+    private delegatePolicy;
+    private delegate;
+    /** Kept so the graph can be rebuilt on another delegate without refetching. */
+    private vision;
+    private modelBuffer;
+    private graphOptions;
+    private rebuilding;
+    private fallbackAttempted;
+    private readonly result;
+    private readonly builder;
+    private readonly node;
+    constructor();
+    private setRuntimeOptions;
+    initialize(options?: HolisticModelOptions): Promise<void>;
+    private createLandmarker;
+    /**
+     * The GPU graph can fail on its first run (the face-blendshape stage has no
+     * WebGL kernel for one of its ops). Rebuild on the CPU once, keep the RAF
+     * loop alive meanwhile, and run one detection right away so static sources
+     * (which pulse models once) still get a result.
+     */
+    private fallbackToCpu;
+    /** One detect + publish outside the loop (used after a delegate rebuild). */
+    private detectOnce;
+    private detect;
+    /** The session mirrors only the webcam feed (an unknown kind is treated as webcam). */
+    private isMirrored;
+    run({ sourceCanvas, getSource, targetFps, analysisScale, }: RunModelParams): Promise<void>;
+    private process;
+    resume(): void;
+    dispose(): void;
+    getModelNode(): XRModelNodeHolisticTracking;
+    getPerformanceData(): Promise<PerformanceData>;
+}
+export { DEFAULT_HOLISTIC_ANALYSIS_MAX_DIMENSION, DEFAULT_HOLISTIC_HOLD_MS, DEFAULT_HOLISTIC_MODEL_URL, DEFAULT_HOLISTIC_PREDICT_MS, HolisticResultBuilder, createHolisticResult, resolveHolisticRuntimeOptions, } from './result';

package/dist/models/Holistic/result.d.ts

@@ -0,0 +1,68 @@
+import { HolisticLandmarkerResult } from '@mediapipe/tasks-vision';
+import { TrackerPoint } from '../../types/common';
+import { HolisticResult, HolisticRuntimeOptions } from '../../types/holistic';
+/** MediaPipe's published holistic landmarker; the SDK CDN copy is not published yet. */
+export declare const DEFAULT_HOLISTIC_MODEL_URL = "https://storage.googleapis.com/mediapipe-models/holistic_landmarker/holistic_landmarker/float16/latest/holistic_landmarker.task";
+export declare const DEFAULT_HOLISTIC_HOLD_MS = 250;
+export declare const DEFAULT_HOLISTIC_PREDICT_MS = 0;
+/**
+ * Pose needs a full-body subject at distance resolved well enough to detect,
+ * so the cap matches `BodyTrackingModel` (768) rather than Hand/Face (512).
+ */
+export declare const DEFAULT_HOLISTIC_ANALYSIS_MAX_DIMENSION = 768;
+export declare const resolveHolisticRuntimeOptions: (options?: HolisticRuntimeOptions) => Required<HolisticRuntimeOptions>;
+export declare const createHolisticResult: () => HolisticResult;
+type Point3 = {
+    x: number;
+    y: number;
+    z: number;
+};
+/**
+ * MediaPipe Pose index with left and right swapped: 0 (nose) stays, then the
+ * 16 left/right pairs (eyes 1–3/4–6, ears 7/8, mouth 9/10, shoulders 11/12,
+ * elbows 13/14, wrists 15/16, pinkies 17/18, indexes 19/20, thumbs 21/22,
+ * hips 23/24, knees 25/26, ankles 27/28, heels 29/30, foot indexes 31/32).
+ */
+export declare const MIRRORED_POSE_INDEX: readonly number[];
+/**
+ * Converts raw MediaPipe holistic results into the SDK's unified
+ * `HolisticResult`, bridging dropouts per stream with `FaceTrackMemory` (the
+ * SDK's single hold/predict mechanism). Output arrays and objects are reused
+ * frame-over-frame; the published result is mutated in place.
+ */
+export declare class HolisticResultBuilder {
+    private options;
+    private readonly faceMemory;
+    private readonly leftHandMemory;
+    private readonly rightHandMemory;
+    private readonly poseMemory;
+    private readonly face;
+    private readonly leftHand;
+    private readonly rightHand;
+    private readonly poseScratch;
+    private readonly poseWorldScratch;
+    private readonly pose;
+    constructor(options?: HolisticRuntimeOptions);
+    getOptions(): Required<HolisticRuntimeOptions>;
+    setOptions(options?: HolisticRuntimeOptions): void;
+    reset(): void;
+    private memories;
+    /**
+     * Publish `raw` (or a miss when `undefined`) into `result` at `nowMs`.
+     *
+     * `mirrored` says the analysed frame is a mirror of the person (the
+     * session's webcam feed). Pose left/right follow the image, and holistic
+     * assigns hands from the pose, so on a mirrored frame MediaPipe's "left"
+     * is the person's right. Swap both the hands and the pose's left/right
+     * landmarks so the whole result is anatomical and self-consistent
+     * (`leftHand` and pose wrist 15 are the same physical hand), matching the
+     * convention `HandTracker` reports on that feed.
+     */
+    update(raw: HolisticLandmarkerResult | undefined, nowMs: number, result: HolisticResult, mirrored?: boolean): HolisticResult;
+    private updateFace;
+    private updateHand;
+    private updatePose;
+}
+/** Convenience for tests and custom consumers: a single-stream TrackerPoint copy. */
+export declare const toTrackerPoints: (landmarks: ReadonlyArray<Point3>) => TrackerPoint[];
+export {};

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/SemanticSegmentation/index.d.ts

@@ -0,0 +1,31 @@
+import { PerformanceData, RunModelParams } from '../../types';
+import { XRModelNodeSemanticSegmentation } from '../../types/nodes';
+import { SemanticSegmentationModelOptions } from '../../types/segmentation';
+import { BaseXRModel } from '../Base';
+/**
+ * Generic MediaPipe category segmenter publishing a `SemanticMask` in feed
+ * space. The first acquirer picks the preset (hair or multiclass) and the
+ * model asset; the mask object is stable and mutated in place, with `version`
+ * bumped on every inference.
+ */
+export declare class SemanticSegmentationModel extends BaseXRModel {
+    private segmenter;
+    private preset;
+    private quality;
+    private status;
+    private error;
+    private processingTime;
+    private sourceCanvas;
+    private processCanvas;
+    private isProcessing;
+    private readonly mask;
+    private readonly node;
+    constructor();
+    initialize(options?: SemanticSegmentationModelOptions): Promise<void>;
+    run({ sourceCanvas, targetFps }: RunModelParams): Promise<void>;
+    private process;
+    resume(): void;
+    getModelNode(): XRModelNodeSemanticSegmentation;
+    getPerformanceData(): Promise<PerformanceData>;
+    dispose(): void;
+}

package/dist/models/SemanticSegmentation/presets.d.ts

@@ -0,0 +1,28 @@
+import { SemanticSegmentationPreset } from '../../types/segmentation';
+export type SemanticSegmentationPresetSpec = {
+    /** Class labels in model index order; index 0 is `bg`. */
+    labels: readonly string[];
+    /**
+     * Model asset path on the SDK CDN. Its hash is already pinned in the
+     * integrity manifest; once the file is uploaded there, point `defaultUrl`
+     * at it.
+     */
+    assetPath: string;
+    /**
+     * Where the model loads from by default: MediaPipe's published file, whose
+     * bytes are pinned in the integrity manifest, so the default is verified
+     * (a republished file fails loudly with an SRI mismatch rather than
+     * silently changing behaviour).
+     */
+    defaultUrl: string;
+    /**
+     * How a category-mask byte maps to a class index. The hair and multiclass
+     * segmenters emit the class index itself (measured: hair reads 0 / 1). The
+     * SDK's portrait selfie segmenter is the odd one out and emits 255 for
+     * background / 0 for person; `usePersonMask` handles that separately.
+     */
+    decode: (value: number) => number;
+};
+export declare const SEMANTIC_SEGMENTATION_PRESET_SPECS: Record<SemanticSegmentationPreset, SemanticSegmentationPresetSpec>;
+/** Decode a MediaPipe category mask into class indices, resizing `out` when needed. */
+export declare const decodeCategoryMask: (raw: Uint8Array, decode: (value: number) => number, out: Uint8Array) => Uint8Array;

package/dist/models/index.d.ts

@@ -1,5 +1,7 @@
 export { BodyTrackingModel } from './Body';
 export { FaceTrackingModel } from './Face';
 export { GestureTrackingModel } from './Hand/GestureTracking';
+export { HolisticTrackingModel } from './Holistic';
 export { HandTrackingModel } from './Hand/HandTracking';
 export { BackgroundSegmentationModel } from './Segmentation';
+export { SemanticSegmentationModel } from './SemanticSegmentation';

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;
+}