@vincentt-xr/sdk 2.0.0-alpha.0 → 2.0.0-alpha.10

package/dist/assets/cache.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Refcounted, deduplicating asset cache with a byte budget.
+ *
+ * One entry per `key`. The first `acquire` starts the load; concurrent
+ * acquires share the in-flight promise; owners are tracked by id so a
+ * re-render or a StrictMode double mount never double-counts. When the last
+ * owner releases, the value stays cached (unreferenced) until the budget
+ * needs room, `disposeUnreferenced()`, or `disposeAll()`. Only unreferenced
+ * entries are ever evicted, least recently used first, and each value is
+ * disposed exactly once.
+ */
+export type XRAssetDefinition<T> = {
+    /** Cache identity (usually the URL plus any option that changes the bytes). */
+    key: string;
+    /** Produce the value. Honour `signal` to stop a load nobody wants any more. */
+    load: (signal: AbortSignal) => Promise<T>;
+    /** Release GPU / media resources. Called exactly once per loaded value. */
+    dispose?: (value: T) => void;
+    /** Estimated resident bytes (GPU + CPU) for the budget; default 0. */
+    bytes?: (value: T) => number;
+};
+export type XRAssetStatus = "idle" | "loading" | "ready" | "error";
+export type XRAssetEntryInfo = {
+    key: string;
+    status: XRAssetStatus;
+    bytes: number;
+    owners: number;
+    /** `performance.now()` of the last acquire / release. */
+    lastUsed: number;
+    error: Error | null;
+};
+export type XRAssetStats = {
+    assets: number;
+    referencedAssets: number;
+    loadingAssets: number;
+    erroredAssets: number;
+    /** Bytes of every loaded value, referenced or not. */
+    usageBytes: number;
+    /** Bytes held by unreferenced values (what eviction can reclaim). */
+    reclaimableBytes: number;
+    budgetBytes: number;
+    overBudget: boolean;
+    /** Values disposed by `evict()` — budget pressure or an explicit call — since creation. `disposeUnreferenced` / `disposeAll` do not count. */
+    evictions: number;
+    /** Loads served from an existing entry (hit) vs started (miss). */
+    hits: number;
+    misses: number;
+};
+export type XRAssetCacheOptions = {
+    /** Byte budget; eviction of unreferenced values starts above it. Default 256 MiB. `Infinity` disables. */
+    budgetBytes?: number;
+    /** Clock for `lastUsed` (tests). */
+    now?: () => number;
+};
+export declare const DEFAULT_ASSET_BUDGET_BYTES: number;
+export declare class XRAssetCache {
+    private entries;
+    private listeners;
+    private budget;
+    private readonly now;
+    private evictions;
+    private hits;
+    private misses;
+    /** Memoised `getStats()` result; cleared on every change so `useSyncExternalStore` sees a stable snapshot. */
+    private statsSnapshot;
+    constructor(options?: XRAssetCacheOptions);
+    /** Acquire `asset` on behalf of `ownerId`; shares an in-flight or loaded value. */
+    acquire<T>(asset: XRAssetDefinition<T>, ownerId: string): Promise<T>;
+    /** Start loading without holding a reference (warm the cache). */
+    preload<T>(asset: XRAssetDefinition<T>): Promise<T>;
+    /** Drop `ownerId`'s reference. The value stays cached until evicted or disposed. */
+    release(key: string, ownerId: string): void;
+    /** Synchronous read of a loaded value (or `undefined`). Does not take a reference. */
+    get<T>(key: string): T | undefined;
+    has(key: string): boolean;
+    entry(key: string): XRAssetEntryInfo | undefined;
+    list(): XRAssetEntryInfo[];
+    setBudget(bytes: number): void;
+    /**
+     * Dispose unreferenced values, least recently used first, until usage is
+     * within the budget (or `bytesToFree` is reclaimed). Referenced values are
+     * never touched. Returns the bytes reclaimed.
+     */
+    evict(bytesToFree?: number): number;
+    /** Dispose every unreferenced value (route change, scene teardown). Returns the bytes freed. */
+    disposeUnreferenced(): number;
+    /** Dispose everything, referenced or not (app / session shutdown). Owners are forgotten. */
+    disposeAll(): void;
+    /** Current statistics. The object is reused until the cache changes, so it is safe as a store snapshot. */
+    getStats(): XRAssetStats;
+    subscribe(listener: () => void): () => void;
+    private usage;
+    private enforceBudget;
+    private disposeEntry;
+    private notify;
+}
+export declare const createAssetCache: (options?: XRAssetCacheOptions) => XRAssetCache;
+/** The app-wide cache `useXRAsset` uses when no `<XRAssetCacheProvider>` is mounted. */
+export declare const getDefaultAssetCache: () => XRAssetCache;

package/dist/assets/estimate.d.ts

@@ -0,0 +1,11 @@
+import * as THREE from "three";
+/** Resident bytes of a texture (RGBA, mip chain included when generated); 0 for an unloaded image. */
+export declare const estimateTextureBytes: (texture: THREE.Texture | null | undefined) => number;
+/** Bytes of every attribute buffer (and the index) of a geometry. */
+export declare const estimateGeometryBytes: (geometry: THREE.BufferGeometry | null | undefined) => number;
+/** Textures a material references (de-duplicated by the caller). */
+export declare const materialTextures: (material: THREE.Material) => THREE.Texture[];
+/** Sum of the geometries and textures reachable from an object, each counted once. */
+export declare const estimateObjectBytes: (object: THREE.Object3D | null | undefined) => number;
+/** Dispose every geometry, material and texture reachable from an object, each once. */
+export declare const disposeObject3D: (object: THREE.Object3D | null | undefined) => void;

package/dist/assets/gltfLoader.d.ts

@@ -0,0 +1,16 @@
+import { GLTFLoader, GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
+/**
+ * The one GLTFLoader setup for every SDK-owned model path. The meshopt decoder
+ * ships inside three (wasm inlined) and fetches nothing. Draco and KTX2 are
+ * deliberately left unconfigured: their decoders would be fetched from a
+ * third-party CDN at view time, so such a model rejects instead.
+ */
+export declare const createGltfLoader: () => GLTFLoader;
+/** Parses GLB / glTF bytes with {@link createGltfLoader}; an unsupported compression rejects with an actionable error. */
+export declare const parseGltf: (buffer: ArrayBuffer, path?: string, label?: string) => Promise<GLTF>;
+/**
+ * A cached `url -> GLTF` loader over {@link fetchAndVerify}: SDK CDN models are
+ * hash-checked, a custom URL passes through. A failed load is evicted so the
+ * next call refetches.
+ */
+export declare const createVerifiedGltfLoader: () => (url: string) => Promise<GLTF>;

package/dist/assets/index.d.ts

@@ -0,0 +1,7 @@
+export { DEFAULT_ASSET_BUDGET_BYTES, XRAssetCache, createAssetCache, getDefaultAssetCache, } from './cache';
+export type { XRAssetCacheOptions, XRAssetDefinition, XRAssetEntryInfo, XRAssetStats, XRAssetStatus, } from './cache';
+export { disposeObject3D, estimateGeometryBytes, estimateObjectBytes, estimateTextureBytes, materialTextures, } from './estimate';
+export { defineGltfAsset, defineTextureAsset, defineVideoAsset } from './loaders';
+export type { TextureAssetOptions, VideoAsset, VideoAssetOptions } from './loaders';
+export { XRAssetCacheProvider, useXRAsset, useXRAssetCache, useXRAssetStats } from './react';
+export type { UseXRAssetResult, XRAssetCacheProviderProps } from './react';

package/dist/assets/loaders.d.ts

@@ -0,0 +1,43 @@
+import { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { XRAssetDefinition } from './cache';
+import * as THREE from "three";
+/**
+ * An asset's bytes could not be fetched: a network or CORS failure, an HTTP
+ * error status, or a failed integrity check. Decoding failures are not
+ * this (they keep their own error). Internal: lets loaders' callers tell a
+ * download failure from a decode failure.
+ */
+export declare class AssetFetchError extends Error {
+    /** The underlying error, when there was one. */
+    readonly cause: unknown;
+    constructor(message: string, cause?: unknown);
+}
+export type TextureAssetOptions = {
+    colorSpace?: THREE.ColorSpace;
+    generateMipmaps?: boolean;
+    flipY?: boolean;
+    /** Extra key suffix when the same URL is loaded with different options. */
+    variant?: string;
+};
+/**
+ * An image texture. Loaded with the SDK's verifying fetch (CDN assets are
+ * hash-checked), decoded off the main thread, disposed on eviction.
+ */
+export declare const defineTextureAsset: (url: string, options?: TextureAssetOptions) => XRAssetDefinition<THREE.Texture>;
+/**
+ * A glTF / GLB scene via three's GLTFLoader over the verifying fetch. Loads
+ * meshopt geometry and WebP textures; a Draco or KTX2 model rejects. Disposes
+ * geometries, materials and textures.
+ */
+export declare const defineGltfAsset: (url: string) => XRAssetDefinition<GLTF>;
+export type VideoAssetOptions = {
+    loop?: boolean;
+    muted?: boolean;
+    crossOrigin?: string;
+};
+export type VideoAsset = {
+    video: HTMLVideoElement;
+    texture: THREE.VideoTexture;
+};
+/** A looping, muted video element with its `VideoTexture`. Playback is the consumer's call. */
+export declare const defineVideoAsset: (url: string, options?: VideoAssetOptions) => XRAssetDefinition<VideoAsset>;

package/dist/assets/react.d.ts

@@ -0,0 +1,33 @@
+import { PropsWithChildren } from 'react';
+import { XRAssetCache, XRAssetDefinition, XRAssetStats, XRAssetStatus } from './cache';
+export type XRAssetCacheProviderProps = PropsWithChildren<{
+    /** The cache to use below; default the app-wide cache. */
+    cache?: XRAssetCache;
+    /**
+     * On unmount (a route change away from the AR screen) dispose every value
+     * nobody references any more. Default `true`. Referenced values are never
+     * touched; their owners release them as they unmount.
+     */
+    disposeUnreferencedOnUnmount?: boolean;
+}>;
+/** Scope a cache to a subtree and release unreferenced assets when it unmounts. */
+export declare const XRAssetCacheProvider: ({ cache, disposeUnreferencedOnUnmount, children, }: XRAssetCacheProviderProps) => import("react/jsx-runtime").JSX.Element;
+/** The cache in scope (provider or the app-wide default). */
+export declare const useXRAssetCache: () => XRAssetCache;
+export type UseXRAssetResult<T> = {
+    value: T | null;
+    status: XRAssetStatus;
+    error: Error | null;
+};
+/**
+ * Hold a reference to an asset while mounted. Two components asking for the
+ * same key share one load and one value; the reference is released on
+ * unmount (and when `enabled` turns false), after which the budget decides
+ * when the value is disposed. `asset.key` is the identity: build definitions
+ * with `defineTextureAsset` / `defineGltfAsset` / `defineVideoAsset` or your own.
+ */
+export declare const useXRAsset: <T>(asset: XRAssetDefinition<T> | null | undefined, options?: {
+    enabled?: boolean;
+}) => UseXRAssetResult<T>;
+/** Live cache statistics (re-renders on every cache change). */
+export declare const useXRAssetStats: (cache?: XRAssetCache) => XRAssetStats;

package/dist/assets/sdkModels.d.ts

@@ -0,0 +1,22 @@
+import { GLTF } from 'three/examples/jsm/loaders/GLTFLoader.js';
+import { XRAssetDefinition } from './cache';
+/**
+ * The SDK-hosted rig models, by name, as CDN paths (hash-checked: each path
+ * has an entry in `INTEGRITY_MANIFEST`):
+ * - `hand`: a right hand on the `HandRig` contract (21 joints named as
+ *   `HAND_JOINT_NAMES`, a `forearm` bone, 11 gesture poses), centimetres.
+ * - `glove`: a knit glove on the same rig (`knit` and `rib` materials).
+ * - `body`: the Y Bot, a Mixamo-rig humanoid for `BodyRig` / `BodyOccluder`
+ *   (16 poses, `idle` among them), centimetres, meshopt-compressed.
+ * Credits are in each GLB's `asset.copyright` and in `assets-src/`.
+ */
+export declare const SDK_MODEL_PATHS: {
+    readonly hand: "/assets/xr/3d-models/hand-v1.glb";
+    readonly glove: "/assets/xr/3d-models/glove-v1.glb";
+    readonly body: "/assets/xr/3d-models/ybot-v1.glb";
+};
+export type SdkModel = keyof typeof SDK_MODEL_PATHS;
+/** The model's URL on the SDK CDN. */
+export declare const sdkModelUrl: (model: SdkModel) => string;
+/** The model as an asset for `useXRAsset` (verified fetch, shared, disposed by the cache). */
+export declare const sdkModelAsset: (model: SdkModel) => XRAssetDefinition<GLTF>;

package/dist/audio/AudioEngine.d.ts

@@ -4,7 +4,7 @@
  *
  * 1. Gesture-started audio is BLOCKED. Audio kicked off from a camera-detected
  *    gesture (a peace sign to start) is not a user-input event, so iOS autoplay
- *    policy blocks it. The fix is IG/Snap-style: run muted by default (muted
+ *    policy blocks it. The fix is app-style: run muted by default (muted
  *    autoplay is allowed un-gestured) and let the tap that unmutes be the real
  *    gesture that unlocks the pipeline (prime each element with a muted
  *    play->pause on that tap).
@@ -52,6 +52,8 @@ export declare class AudioEngine {
     private muted;
     private readonly listeners;
     private music;
+    private musicUrl;
+    private musicReady;
     private musicWanted;
     private readonly pools;
     /** Last play time per SFX URL, for the coalesce window. */

package/dist/audio/AudioPlayer.d.ts

@@ -0,0 +1,29 @@
+export type AudioPlayMode = "once" | "loop" | "infinite";
+export interface AudioPlayerHandle {
+    play: () => Promise<void>;
+    pause: () => void;
+    stop: () => void;
+    readonly current: HTMLAudioElement | null;
+}
+export interface AudioPlayerProps {
+    src: string;
+    playMode?: AudioPlayMode;
+    /** Total number of plays in `loop` mode. Values below 1 become 1. */
+    loopCount?: number;
+    autoplay?: boolean;
+    muted?: boolean;
+    /** Volume from 0 through 100. Values are clamped. */
+    volume?: number;
+    preload?: "none" | "metadata" | "auto";
+    onReady?: () => void;
+    onPlay?: () => void;
+    onPause?: () => void;
+    onEnded?: () => void;
+    onError?: (error: Error) => void;
+}
+/**
+ * Headless, declarative audio player with timeline-friendly playback
+ * properties. It renders only a hidden HTML audio element; build any visible
+ * controls with the imperative ref or application state.
+ */
+export declare const AudioPlayer: import('react').ForwardRefExoticComponent<AudioPlayerProps & import('react').RefAttributes<AudioPlayerHandle>>;

package/dist/audio/AudioPlayerLogic.d.ts

@@ -0,0 +1,4 @@
+import { AudioPlayMode } from './AudioPlayer';
+export type AudioEndedAction = "replay" | "ended";
+export declare const resolveAudioEndedAction: (playMode: AudioPlayMode, completedPlays: number, loopCount: number) => AudioEndedAction;
+export declare const shouldAutoplaySource: (autoplay: boolean, autoplayedSrc: string | null, src: string) => boolean;

package/dist/audio/index.d.ts

@@ -1,6 +1,8 @@
 import { AudioEngine } from './AudioEngine';
 export { AudioEngine } from './AudioEngine';
 export type { AudioEngineOptions } from './AudioEngine';
+export { AudioPlayer } from './AudioPlayer';
+export type { AudioPlayerHandle, AudioPlayerProps, AudioPlayMode } from './AudioPlayer';
 /** The process-wide default engine the free functions target. */
 export declare const audio: AudioEngine;
 /** Create + buffer the looping music element. Await in the loading gate so the

package/dist/body/__fixtures__/syntheticRig.d.ts

@@ -0,0 +1,21 @@
+import { BodyPose } from '../bodyPose';
+import * as THREE from "three";
+/**
+ * A synthetic humanoid rig shaped like the example Y Bot (T-pose, cm, facing
+ * +Z, its left at +X) with face and heel points, for the body rig tests.
+ */
+/** Rest joints in root space (cm), the example Y Bot's T-pose: facing +Z, its left at +X. */
+export declare const REST: Array<[name: string, parent: string | null, x: number, y: number, z: number]>;
+/** Builds the rig; with a `seed`, every node gets its own rest roll (positions unchanged). */
+export declare const makeRig: (seed?: number) => {
+    root: THREE.Group<THREE.Object3DEventMap>;
+    nodes: Map<string, THREE.Object3D<THREE.Object3DEventMap>>;
+};
+export declare const worldQuaternion: (node: THREE.Object3D) => THREE.Quaternion;
+export declare const worldPosition: (node: THREE.Object3D) => THREE.Vector3;
+/** Rotates `name`'s subtree by `degrees` about a root-space `axis` through its joint. */
+export declare const turn: (rig: ReturnType<typeof makeRig>, name: string, axis: [number, number, number], degrees: number) => void;
+/** The tracked pose a camera would see of `rig` (world joints relative to the hips; all visible). */
+export declare const poseOf: (rig: ReturnType<typeof makeRig>, visibility?: number) => BodyPose;
+export type SyntheticRig = ReturnType<typeof makeRig>;
+export declare const direction: (rig: ReturnType<typeof makeRig>, from: string, to: string) => THREE.Vector3;

package/dist/body/bodyFlipGuard.d.ts

@@ -0,0 +1,39 @@
+import * as THREE from "three";
+/**
+ * Holds a tracked body through a facing it misreads for a moment.
+ *
+ * The pose tracker sometimes turns the whole torso 60–140° for 50–250 ms and
+ * back (a side view, a fast move), and its own temporal filter spreads that
+ * over several detections, each a small step. So the guard compares each
+ * detection's hips rotation with the one it accepted `windowMs` earlier, not
+ * with the previous detection: a turn of more than `jump` within that window
+ * is held (the last accepted pose stays) until it has lasted `confirmMs` over
+ * `confirmSamples` detections — a real turn stays — and then taken. Turns
+ * faster than `jump / windowMs` (a dance spin) wait `confirmMs` too.
+ */
+export type BodyFlipGuardSettings = {
+    /** Degrees within `windowMs` that count as a possible flip. Default 35. */
+    jump: number;
+    /** How far back the comparison looks, ms. Default 120. */
+    windowMs: number;
+    /** A held turn is taken once it has lasted this long, ms. Default 200. */
+    confirmMs: number;
+    /** …and shown up in this many detections. Default 4. */
+    confirmSamples: number;
+};
+export declare const BODY_FLIP_GUARD_DEFAULTS: Readonly<BodyFlipGuardSettings>;
+export declare class BodyFlipGuard {
+    settings: BodyFlipGuardSettings;
+    /** Accepted detections, oldest first, kept for `windowMs`. */
+    private accepted;
+    private pending;
+    constructor(settings?: Partial<BodyFlipGuardSettings>);
+    /**
+     * Checks one detection's hips rotation at `nowMs` (its timestamp); `true` =
+     * hold it (keep the last accepted pose), `false` = take it.
+     */
+    hold(hips: THREE.Quaternion, nowMs: number): boolean;
+    /** Forget the body (it was lost): the next detection is taken as it is. */
+    reset(): void;
+    private take;
+}

package/dist/body/bodyIdentity.d.ts

@@ -0,0 +1,72 @@
+import { BodyPose } from './bodyPose';
+/**
+ * A tracked body with a stable identity: `id` stays with the person from
+ * detection to detection, whatever position MediaPipe gives them in its
+ * result array, and through dropouts shorter than `holdMs`.
+ */
+export type TrackedBody = {
+    /** 1, 2, 3 … in order of first appearance; never reused within a session. */
+    id: number;
+    /** The latest pose; while `held`, the last one seen. */
+    pose: BodyPose;
+    /** `true` while the body is missing but still within the hold. */
+    held: boolean;
+};
+export type BodyIdentitySettings = {
+    /** How long a missing body keeps its id (and its last pose is reported), ms. Default 250. */
+    holdMs: number;
+    /**
+     * The farthest a body may be from where it was predicted to be and still
+     * be the same person, in torso lengths. Default 1.
+     */
+    maxJump: number;
+    /**
+     * Two detections closer than this (torso lengths, within 10 % in size) are
+     * one person seen twice: the less visible one is dropped. Two people side by
+     * side stand farther apart than this. Default 0.1.
+     */
+    duplicate: number;
+    /**
+     * Detections in a row a newcomer needs before it gets an id (the tracker
+     * reports a part of a person as another body for a frame or two, e.g. the
+     * legs of someone crouching). The first person into an empty scene gets one
+     * at once. Default 3.
+     */
+    confirm: number;
+    /**
+     * …spanning at least this long, ms: inference can run faster than the
+     * camera and detect one frame twice. Default 100 (three camera frames).
+     */
+    confirmMs: number;
+};
+export declare const BODY_IDENTITY_DEFAULTS: Readonly<BodyIdentitySettings>;
+/**
+ * Gives each tracked body a stable id across detections. MediaPipe returns
+ * bodies in no particular order, so each detection is matched to the bodies
+ * already tracked by where their torso is (predicted from its motion, so two
+ * people crossing keep their ids) and how big it is (a person nearer the
+ * camera looks bigger). Identity is spatial only: nothing about the person
+ * is recognised, and someone who leaves for longer than `holdMs` comes back
+ * with a new id.
+ */
+export declare class BodyIdentity {
+    settings: BodyIdentitySettings;
+    private tracks;
+    private nextId;
+    constructor(settings?: Partial<BodyIdentitySettings>);
+    /**
+     * One detection's bodies (any order) at `nowMs`; `aspect` is the analysed
+     * frame's width / height. Returns every tracked body, by id.
+     */
+    update(poses: readonly BodyPose[], nowMs: number, aspect?: number): TrackedBody[];
+    private confirm;
+    /** Forget every body; ids keep counting up. */
+    reset(): void;
+    /** One person detected twice (overlapping tracking regions): keep the more visible. */
+    private dedupe;
+}
+/**
+ * How many bodies the shared model looks for: the most any live consumer
+ * asks for, at least 1 and at most `max`.
+ */
+export declare const resolveNumBodies: (requests: Iterable<number>, max: number) => number;

package/dist/body/bodyMask.d.ts

@@ -0,0 +1,79 @@
+import { TrackedBody } from './bodyIdentity';
+import { BodyPose } from './bodyPose';
+/**
+ * The joint pairs a person's mask is split by: the torso (its outline and
+ * both diagonals, so its middle counts as near), the head, arms and legs.
+ */
+export declare const BODY_MASK_BONES: ReadonlyArray<readonly [number, number]>;
+/** A bone counts when both its joints are at least this visible. */
+export declare const BODY_MASK_MIN_VISIBILITY = 0.3;
+/**
+ * One person's skeleton for the split, in feed units with the frame's aspect
+ * applied (x right from 0 to `aspect`, y down from 0 to 1), so distances are
+ * proportional to pixels.
+ */
+export type BodyMaskPerson = {
+    /** `ax, ay, bx, by` per bone. */
+    bones: Float32Array;
+    /** Bones in `bones`. */
+    count: number;
+    /** The torso's length (shoulders' to hips' midpoint), feed units: distances are measured in it. */
+    scale: number;
+};
+/**
+ * A pose's visible bones for the split (`aspect` = the feed's width / height),
+ * or `null` without a measurable torso.
+ */
+export declare const bodyMaskPerson: (pose: BodyPose, aspect: number, minVisibility?: number) => BodyMaskPerson | null;
+export type BodyMaskSplitOptions = {
+    /**
+     * Beyond this distance from every skeleton, in that person's torso
+     * lengths, a mask pixel belongs to nobody (someone the pose tracker
+     * misses). Default 1.
+     */
+    nobody: number;
+    /** Width of the soft band where two people meet, and of the edge at `nobody`, in torso lengths. Default 0.1. */
+    feather: number;
+};
+export declare const BODY_MASK_SPLIT_DEFAULTS: Readonly<BodyMaskSplitOptions>;
+/** Distance from (x, y) to the nearest of a person's bones, in their torso lengths. */
+export declare const bodyMaskDistance: (x: number, y: number, person: BodyMaskPerson) => number;
+/**
+ * How much of a mask pixel at (x, y) (feed units with aspect) belongs to each
+ * person: the nearest skeleton (in each person's own torso lengths, so someone
+ * nearer the camera keeps their wider body) takes it, blended across a
+ * `feather`-wide band where two people meet, and fading out at `nobody`.
+ * Weights are 0..1 and sum to at most 1. The GPU split computes the same.
+ */
+export declare const bodyMaskWeights: (x: number, y: number, people: readonly BodyMaskPerson[], options?: Partial<BodyMaskSplitOptions>, out?: number[]) => number[];
+/**
+ * CPU reference of the split: each person's share of a person mask
+ * (`mask[i]`, 0..1 or 0..255 with `max`), `width × height` in feed space.
+ * For tests and offline use; the live split runs on the GPU.
+ */
+export declare const splitBodyMask: (mask: ArrayLike<number>, width: number, height: number, people: readonly BodyMaskPerson[], options?: Partial<BodyMaskSplitOptions> & {
+    max?: number;
+}) => Float32Array[];
+/** People the GPU split takes (the body model's maximum). */
+export declare const BODY_MASK_MAX_PEOPLE: number;
+/** The split's people packed for the shader: `BODY_MASK_MAX_PEOPLE` slots of `BODY_MASK_BONES.length` bones. */
+export type BodyMaskUniforms = {
+    /** `ax, ay, bx, by` per bone, person after person. */
+    bones: Float32Array;
+    counts: number[];
+    scales: number[];
+    people: number;
+};
+/** Packs up to `BODY_MASK_MAX_PEOPLE` people for the GPU split (extra people are left out). */
+export declare const packBodyMaskUniforms: (people: readonly BodyMaskPerson[], out?: BodyMaskUniforms) => BodyMaskUniforms;
+/** One detection's bodies, at the detection's time. */
+export type BodyMaskSnapshot = {
+    ms: number;
+    bodies: readonly TrackedBody[];
+};
+/**
+ * The snapshot nearest in time to `ms` (a person mask lags the frame it shows,
+ * by a different amount than the pose): split a mask by where the people were
+ * when it was made. The latest without a time (`ms` 0) or snapshots.
+ */
+export declare const closestBodies: (history: readonly BodyMaskSnapshot[], ms: number) => BodyMaskSnapshot | null;

package/dist/body/bodyMaskMaterial.d.ts

@@ -0,0 +1,15 @@
+import { BodyMaskSplitOptions, BodyMaskUniforms } from './bodyMask';
+import * as THREE from "three";
+/**
+ * The GPU split: draws one person's share of a person mask (`uMask`, feed
+ * space, white on people) on a full-screen quad, white on that person and
+ * black elsewhere — the same convention as the mask, so the result drops in
+ * wherever the person mask does. Set the people with
+ * `setBodyMaskSplitUniforms`.
+ */
+export declare const createBodyMaskSplitMaterial: () => THREE.ShaderMaterial;
+/**
+ * Sets the split's inputs: the mask, its aspect (width / height), the packed
+ * people, which of them to draw (`target`, `-1` = nobody) and the options.
+ */
+export declare const setBodyMaskSplitUniforms: (material: THREE.ShaderMaterial, mask: THREE.Texture | null, aspect: number, people: BodyMaskUniforms, target: number, options?: Partial<BodyMaskSplitOptions>) => void;

package/dist/body/bodyPose.d.ts

@@ -0,0 +1,58 @@
+import { TrackerPoint } from '../types/common';
+/**
+ * The 33 MediaPipe pose landmarks, in landmark order (index = MediaPipe
+ * index). Sided names are the PERSON's own side in a `BodyPose`; MediaPipe's
+ * raw arrays name them as the image shows them (see `anatomicalBodyPose`).
+ * `…Pinky`, `…Index` and `…Thumb` are MediaPipe's rough hand points: the
+ * pinky and index knuckles and the thumb's second knuckle.
+ */
+export declare const BODY_JOINT_NAMES: readonly ["nose", "leftEyeInner", "leftEye", "leftEyeOuter", "rightEyeInner", "rightEye", "rightEyeOuter", "leftEar", "rightEar", "mouthLeft", "mouthRight", "leftShoulder", "rightShoulder", "leftElbow", "rightElbow", "leftWrist", "rightWrist", "leftPinky", "rightPinky", "leftIndex", "rightIndex", "leftThumb", "rightThumb", "leftHip", "rightHip", "leftKnee", "rightKnee", "leftAnkle", "rightAnkle", "leftHeel", "rightHeel", "leftFootIndex", "rightFootIndex"];
+export type BodyJointName = (typeof BODY_JOINT_NAMES)[number];
+export declare const BODY_JOINT_INDEX: Readonly<Record<BodyJointName, number>>;
+/** For each landmark, the index of the same joint on the other side (`nose` is its own). */
+export declare const BODY_JOINT_OTHER_SIDE: readonly number[];
+/**
+ * One tracked body, both spaces, sided as the person's own left and right on
+ * every source (mirrored webcam or not).
+ *
+ * - `world`: 33 joints in the body's own metric frame — CENTIMETRES, origin
+ *   between the hips, three.js axes for the feed as displayed: +X screen
+ *   right, +Y up, +Z toward the viewer. The true 3D shape (limb bend, which
+ *   way the body faces), independent of distance. On a mirrored feed it is
+ *   the mirrored shape, as displayed.
+ * - `image`: the same joints in tracker space (centre origin, ±1, Y up; `z`
+ *   is MediaPipe's relative depth). Unproject with `trackerToWorld` to place
+ *   things on screen.
+ * - `visibility`: MediaPipe's 0..1 estimate that each joint is in frame and
+ *   not hidden.
+ */
+export type BodyPose = {
+    world: TrackerPoint[];
+    image: TrackerPoint[];
+    visibility: number[];
+    /** `performance.now()` of the detection this pose came from. */
+    timestampMs: number;
+};
+/** One body as MediaPipe returns it, sided as the image shows it, in SDK units. */
+export type BodyDetection = {
+    world: TrackerPoint[];
+    image: TrackerPoint[];
+    visibility: number[];
+};
+/**
+ * A MediaPipe pose world landmark (metres, origin between the hips, image
+ * axes: +y down, +z away from the camera) → a `BodyPose.world` joint.
+ */
+export declare const bodyWorldLandmarkToJoint: (landmark: {
+    x: number;
+    y: number;
+    z: number;
+}, target?: TrackerPoint) => TrackerPoint;
+/**
+ * Names a detection's joints by the person's own side. MediaPipe labels each
+ * side as an unmirrored image shows it (a person facing the camera has their
+ * left on the image's right), so on the mirrored webcam feed its "left
+ * shoulder" is the person's right: there every sided joint swaps with its
+ * other-side twin. Positions are untouched.
+ */
+export declare const anatomicalBodyPose: (detection: BodyDetection, feedMirrored: boolean, timestampMs: number) => BodyPose;