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

package/dist/components/ScreenImage/index.d.ts

@@ -1,8 +1,10 @@
 export { ScreenImage, defaultScreenImageUrl } from './ScreenImage';
 export { screenImageBlendModeOptions } from './utils/ScreenImageConstants';
 export { resolveBlendProps } from './materials/ScreenImageBlendMaterial';
+export { SCREEN_IMAGE_MASK_CHANNELS, resolveMaskChannelIndex, } from './materials/ScreenImageMaskMaterial';
+export type { ScreenImageMaskChannel } from './materials/ScreenImageMaskMaterial';
 export type { ScreenImageBlendMode, ScreenImageMaterialType, ScreenImageProps } from './types';
 export type { ScreenImageSource } from './source';
-export { getScreenImageTextureAspect, getScreenImageTextureSize, resolveScreenImageSource, } from './source';
+export { getScreenImageTextureAspect, getScreenImageTextureSize, isDynamicScreenImageTexture, resolveScreenImageSource, } from './source';
 export { computeScreenImageFitResolution, computeScreenImageFittedRect, resolveScreenImageStretchMode, } from './fit';
 export type { ScreenImageFit, ScreenImageFittedRect, ScreenImageFittedRectInput, ScreenImageStretchMode, } from './fit';

package/dist/components/ScreenImage/materials/ScreenImageBlendMaterial.d.ts

@@ -6,4 +6,4 @@ export declare const advancedBlendModeIndices: Record<AdvancedBlendMode, number>
 export type BlendMaterialProps = Partial<Pick<THREE.Material, "blending" | "blendSrc" | "blendDst" | "blendEquation">>;
 export declare const resolveBlendProps: (mode: ScreenImageBlendMode) => BlendMaterialProps;
 export declare const advancedBlendVertexShader = "\nvarying vec2 vUv;\nvoid main(){vUv=uv;gl_Position=projectionMatrix*modelViewMatrix*vec4(position,1.0);}";
-export declare const advancedBlendFragmentShader = "\nuniform sampler2D imageMap;uniform sampler2D backdropMap;uniform vec2 resolution;\nuniform vec3 tint;uniform float opacity;uniform float alphaTest;uniform int blendMode;varying vec2 vUv;\nfloat overlayChannel(float b,float s){return b<.5?2.*b*s:1.-2.*(1.-b)*(1.-s);}\nfloat hardLightChannel(float b,float s){return s<.5?2.*b*s:1.-2.*(1.-b)*(1.-s);}\nfloat softLightChannel(float b,float s){return s<.5?b-(1.-2.*s)*b*(1.-b):b+(2.*s-1.)*(sqrt(max(b,0.))-b);}\nvec3 applyAdvancedBlend(vec3 b,vec3 s){\nif(blendMode==0)return vec3(overlayChannel(b.r,s.r),overlayChannel(b.g,s.g),overlayChannel(b.b,s.b));\nif(blendMode==1)return vec3(softLightChannel(b.r,s.r),softLightChannel(b.g,s.g),softLightChannel(b.b,s.b));\nif(blendMode==2)return vec3(hardLightChannel(b.r,s.r),hardLightChannel(b.g,s.g),hardLightChannel(b.b,s.b));\nif(blendMode==3)return abs(b-s);return b+s-2.*b*s;}\nvoid main(){vec4 image=texture2D(imageMap,vUv)*vec4(tint,opacity);if(image.a<=alphaTest)discard;\nvec2 uv=gl_FragCoord.xy/max(resolution,vec2(1.));vec3 base=texture2D(backdropMap,uv).rgb;\nvec3 mixed=applyAdvancedBlend(base,image.rgb);gl_FragColor=vec4(mix(base,mixed,image.a),1.);}";
+export declare const advancedBlendFragmentShader = "\nuniform sampler2D imageMap;uniform sampler2D backdropMap;uniform vec2 resolution;\nuniform vec3 tint;uniform float opacity;uniform float alphaTest;uniform int blendMode;varying vec2 vUv;\nfloat overlayChannel(float b,float s){return b<.5?2.*b*s:1.-2.*(1.-b)*(1.-s);}\nfloat hardLightChannel(float b,float s){return s<.5?2.*b*s:1.-2.*(1.-b)*(1.-s);}\nfloat softLightChannel(float b,float s){return s<.5?b-(1.-2.*s)*b*(1.-b):b+(2.*s-1.)*(sqrt(max(b,0.))-b);}\nvec3 applyAdvancedBlend(vec3 b,vec3 s){\nif(blendMode==0)return vec3(overlayChannel(b.r,s.r),overlayChannel(b.g,s.g),overlayChannel(b.b,s.b));\nif(blendMode==1)return vec3(softLightChannel(b.r,s.r),softLightChannel(b.g,s.g),softLightChannel(b.b,s.b));\nif(blendMode==2)return vec3(hardLightChannel(b.r,s.r),hardLightChannel(b.g,s.g),hardLightChannel(b.b,s.b));\nif(blendMode==3)return abs(b-s);return b+s-2.*b*s;}\nvoid main(){vec4 image=texture2D(imageMap,vUv)*vec4(tint,opacity);if(image.a<=alphaTest)discard;\nvec2 uv=gl_FragCoord.xy/max(resolution,vec2(1.));vec3 base=texture2D(backdropMap,uv).rgb;\nvec3 mixed=applyAdvancedBlend(base,image.rgb);gl_FragColor=vec4(mix(base,mixed,image.a),1.);\n#include <colorspace_fragment>\n}";

package/dist/components/ScreenImage/materials/ScreenImageMaskMaterial.d.ts

@@ -0,0 +1,11 @@
+/** Which channel of a `maskTexture` carries coverage. */
+export declare const SCREEN_IMAGE_MASK_CHANNELS: readonly ["alpha", "red", "green", "luminance"];
+export type ScreenImageMaskChannel = (typeof SCREEN_IMAGE_MASK_CHANNELS)[number];
+export declare const resolveMaskChannelIndex: (channel: ScreenImageMaskChannel | undefined) => number;
+export declare const maskedVertexShader = "\nvarying vec2 vUv;\nvoid main(){vUv=uv;gl_Position=projectionMatrix*modelViewMatrix*vec4(position,1.0);}";
+/**
+ * Image × mask. Both are sampled through the image's fit transform (repeat /
+ * offset / flips), so a mask authored in the image's own space — a camera
+ * frame and its segmentation mask — stays aligned under cover-cropping.
+ */
+export declare const maskedFragmentShader = "\nuniform sampler2D imageMap;uniform sampler2D maskMap;uniform mat3 mapTransform;\nuniform vec3 tint;uniform float opacity;uniform float alphaTest;uniform int maskChannel;uniform float maskInvert;\nuniform float maskFeather;uniform float maskErode;uniform vec2 maskTexel;\nvarying vec2 vUv;\nfloat coverageAt(vec2 uv){\nvec4 m=texture2D(maskMap,uv);\nfloat c=maskChannel==0?m.a:maskChannel==1?m.r:maskChannel==2?m.g:dot(m.rgb,vec3(0.299,0.587,0.114));\nreturn mix(c,1.0-c,maskInvert);}\nvoid main(){\nvec2 uv=(mapTransform*vec3(vUv,1.0)).xy;\nvec4 image=texture2D(imageMap,uv);\nfloat coverage;\nif(maskFeather>0.0){\nvec2 step=maskTexel*maskFeather;\ncoverage=0.0;\nfor(int y=-1;y<=1;y++){for(int x=-1;x<=1;x++){coverage+=coverageAt(uv+vec2(float(x),float(y))*step);}}\ncoverage/=9.0;\n// Erode: raise the threshold on the blurred edge so the silhouette shrinks\n// by up to the feather radius (maskErode is a fraction of that width).\ncoverage=smoothstep(clamp(maskErode,0.0,0.95),1.0,coverage);\n}else{coverage=coverageAt(uv);}\nfloat alpha=image.a*opacity*coverage;\nif(alpha<=alphaTest)discard;\ngl_FragColor=vec4(image.rgb*tint,alpha);\n#include <colorspace_fragment>\n}";

package/dist/components/ScreenImage/source.d.ts

@@ -16,4 +16,10 @@ export declare const getScreenImageTextureSize: (texture: THREE.Texture) => {
     width: number;
     height: number;
 };
+/**
+ * Textures whose pixels change after upload: videos and any canvas-backed
+ * texture, including `OffscreenCanvas` sources such as the session camera
+ * feed. These need `needsUpdate` every frame to stay live.
+ */
+export declare const isDynamicScreenImageTexture: (texture: THREE.Texture) => boolean;
 export declare const getScreenImageTextureAspect: (texture: THREE.Texture) => number;

package/dist/components/ScreenImage/types.d.ts

@@ -1,6 +1,7 @@
 import { ScreenAnchorEdges, ScreenOffsetEdges, ScreenTransformGuideLayer } from '../ScreenSpaceUI';
 import { ScreenCanvasSize, ScreenCoordinateSpace, ScreenTransform2DSettings } from '../../screen2d';
 import { ScreenImageFit, ScreenImageStretchMode } from './fit';
+import { ScreenImageMaskChannel } from './materials/ScreenImageMaskMaterial';
 import { ScreenImageSource } from './source';
 import type * as THREE from "three";
 export type ScreenImageMaterialType = "unlit" | "standardPBR" | "matcap";
@@ -27,6 +28,23 @@ export type ScreenImageProps = {
     backdropTexture?: THREE.Texture | null;
     opacity?: number;
     color?: THREE.ColorRepresentation;
+    /**
+     * Alpha mask in the image's own texture space: it is sampled through the
+     * same fit / crop / flip transform as the image, so a camera frame and its
+     * segmentation mask stay aligned. Takes precedence over advanced blend modes.
+     */
+    maskTexture?: THREE.Texture | null;
+    /** Channel of `maskTexture` that carries coverage. Default `"alpha"`. */
+    maskChannel?: ScreenImageMaskChannel;
+    /** Keep where the mask is 0 instead of 1. */
+    maskInvert?: boolean;
+    /** Soften mask edges: 3×3 blur radius in mask texels. 0 = hard. */
+    maskFeather?: number;
+    /**
+     * Shrink the kept region into the feathered edge, 0..1 of the feather
+     * width; removes fringe from the source. Needs `maskFeather` > 0.
+     */
+    maskErode?: number;
     flipX?: boolean;
     flipY?: boolean;
     renderOrder?: number;

package/dist/components/SegmentationOverlay/SegmentationOverlay.d.ts

@@ -0,0 +1,37 @@
+import { ReactNode } from 'react';
+import { SemanticMask } from '../../segmentation2d/types';
+import { SegmentationOverlaySettings } from './settings';
+import * as THREE from "three";
+export type SegmentationOverlayMaterialContext = {
+    cameraTexture: THREE.Texture | null;
+    /**
+     * Class-index texture (red channel, 0..255 → index); nearest-filtered.
+     * Re-allocated when the mask changes size; the factory is re-run with the
+     * new texture, so read it from the context rather than caching it.
+     */
+    maskTexture: THREE.Texture;
+    /** Feed UV → mask UV, including the row flip, mirror and source cover-fit. */
+    maskTransform: THREE.Matrix3;
+    /** Class indices the overlay selects, resolved from `label` against the mask; empty until the mask has data. */
+    labelIndices: number[];
+    mask: SemanticMask | null;
+    settings: SegmentationOverlaySettings;
+};
+export type SegmentationOverlayMaterialSpec = ReactNode | THREE.Material | ((context: SegmentationOverlayMaterialContext) => ReactNode | THREE.Material);
+export type SegmentationOverlayProps = Partial<SegmentationOverlaySettings> & {
+    /** The mask to draw from: a provider hook's result or your own `SemanticMask`. */
+    mask: SemanticMask | null;
+    /** Optional image multiplied into the paint, sampled in screen UV (cover of the viewport). */
+    texture?: THREE.Texture | string;
+    /** Custom material (node, instance, or factory). Replaces the built-in look. */
+    material?: SegmentationOverlayMaterialSpec;
+    /** Default: just above the video background. */
+    renderOrder?: number;
+    visible?: boolean;
+};
+/**
+ * Draw one or more semantic regions of a mask as a screen-aligned 2D layer,
+ * tinted and composited over the camera feed. Covers the viewport exactly
+ * like `VideoBackground`, so feed-space masks need no coordinate work.
+ */
+export declare const SegmentationOverlay: ({ mask, texture, material, renderOrder, visible, ...settingsInput }: SegmentationOverlayProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/SegmentationOverlay/SegmentationOverlayMaterial.d.ts

@@ -0,0 +1,31 @@
+import { SemanticMask } from '../../segmentation2d/types';
+import { SegmentationOverlaySettings } from './settings';
+import * as THREE from "three";
+/** Up to this many labels can be selected by one overlay. */
+export declare const MAX_OVERLAY_LABELS = 4;
+export type SegmentationOverlayMaterialInputs = {
+    cameraTexture: THREE.Texture | null;
+    maskTexture: THREE.Texture;
+    mask: SemanticMask | null;
+    settings: SegmentationOverlaySettings;
+    /** Optional image sampled in screen UV and multiplied into the paint. */
+    designTexture?: THREE.Texture | null;
+    /** Feed (camera texture) size, for cover-fitting source-space masks. */
+    feedWidth?: number;
+    feedHeight?: number;
+};
+export declare const SEGMENTATION_OVERLAY_VERTEX_SHADER = "\nvarying vec2 vUv;\nvoid main() {\n  vUv = uv;\n  gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);\n}";
+export declare const SEGMENTATION_OVERLAY_FRAGMENT_SHADER = "\nuniform sampler2D cameraTexture;\nuniform sampler2D maskTexture;\nuniform sampler2D designTexture;\nuniform float useDesign;\nuniform vec4 labels;\nuniform float labelCount;\nuniform float invert;\nuniform vec3 tint;\nuniform float opacity;\nuniform float blendMode;\nuniform float feather;\nuniform vec2 maskTexel;\nuniform mat3 maskTransform;\nvarying vec2 vUv;\n\nfloat member(vec2 uv) {\n  if (uv.x < 0.0 || uv.x > 1.0 || uv.y < 0.0 || uv.y > 1.0) return 0.0;\n  float index = floor(texture2D(maskTexture, uv).r * 255.0 + 0.5);\n  float m = 0.0;\n  if (labelCount > 0.5 && abs(index - labels.x) < 0.5) m = 1.0;\n  if (labelCount > 1.5 && abs(index - labels.y) < 0.5) m = 1.0;\n  if (labelCount > 2.5 && abs(index - labels.z) < 0.5) m = 1.0;\n  if (labelCount > 3.5 && abs(index - labels.w) < 0.5) m = 1.0;\n  return invert > 0.5 ? 1.0 - m : m;\n}\n\nvoid main() {\n  vec2 maskUv = (maskTransform * vec3(vUv, 1.0)).xy;\n  float coverage;\n  if (feather > 0.0) {\n    vec2 step = maskTexel * feather;\n    coverage = 0.0;\n    for (int y = -1; y <= 1; y++) {\n      for (int x = -1; x <= 1; x++) {\n        coverage += member(maskUv + vec2(float(x), float(y)) * step);\n      }\n    }\n    coverage /= 9.0;\n  } else {\n    coverage = member(maskUv);\n  }\n\n  vec3 base = texture2D(cameraTexture, vUv).rgb;\n  vec4 design = useDesign > 0.5 ? texture2D(designTexture, vUv) : vec4(1.0);\n  vec3 paint = tint * design.rgb;\n  vec3 blended = blendMode < 0.5\n    ? paint\n    : blendMode < 1.5\n      ? base * paint\n      : blendMode < 2.5\n        ? 1.0 - (1.0 - base) * (1.0 - paint)\n        : mix(2.0 * base * paint, 1.0 - 2.0 * (1.0 - base) * (1.0 - paint), step(0.5, base));\n\n  gl_FragColor = vec4(blended, coverage * opacity * design.a);\n  #include <colorspace_fragment>\n}";
+/** The built-in overlay material as a plain three.js object (shareable across meshes). */
+export declare const createSegmentationOverlayMaterial: () => THREE.ShaderMaterial;
+/** Resolve the selected labels to class indices for a mask (unknown labels are skipped). */
+export declare const resolveOverlayLabelIndices: (mask: Pick<SemanticMask, "labels"> | null, label: string | readonly string[]) => number[];
+/**
+ * The class indices an overlay should draw right now: the resolved labels,
+ * or none while the mask is still at `version` 0 (no data yet). Shared by
+ * the built-in material and the custom-material context so both agree.
+ */
+export declare const resolveActiveOverlayLabelIndices: (mask: SemanticMask | null, label: string | readonly string[]) => number[];
+export declare const updateSegmentationOverlayMaterial: (material: THREE.ShaderMaterial, { cameraTexture, maskTexture, mask, settings, designTexture, feedWidth, feedHeight, }: SegmentationOverlayMaterialInputs) => THREE.ShaderMaterial;
+/** Own one overlay material and keep it in sync with the inputs on every render. */
+export declare const useSegmentationOverlayMaterial: (inputs: SegmentationOverlayMaterialInputs) => THREE.ShaderMaterial;

package/dist/components/SegmentationOverlay/index.d.ts

@@ -0,0 +1,9 @@
+export { SegmentationOverlay } from './SegmentationOverlay';
+export type { SegmentationOverlayMaterialContext, SegmentationOverlayMaterialSpec, SegmentationOverlayProps, } from './SegmentationOverlay';
+export { MAX_OVERLAY_LABELS, SEGMENTATION_OVERLAY_FRAGMENT_SHADER, SEGMENTATION_OVERLAY_VERTEX_SHADER, createSegmentationOverlayMaterial, resolveActiveOverlayLabelIndices, resolveOverlayLabelIndices, updateSegmentationOverlayMaterial, useSegmentationOverlayMaterial, } from './SegmentationOverlayMaterial';
+export type { SegmentationOverlayMaterialInputs } from './SegmentationOverlayMaterial';
+export { createSemanticMaskTexture, uploadSemanticMask, useSemanticMaskTexture, } from './maskTexture';
+export { PERSON_MASK_LABELS, resolveMaskSize, useFaceRegionMask, useHairMask, usePersonMask, useSemanticSegmentationMask, } from './providers';
+export type { SemanticSegmentationMaskResult, UseFaceRegionMaskOptions, UsePersonMaskOptions, UseSemanticSegmentationMaskOptions, } from './providers';
+export { DEFAULT_SEGMENTATION_OVERLAY_SETTINGS, SEGMENTATION_OVERLAY_BLEND_MODES, SEGMENTATION_OVERLAY_SETTINGS_FIELDS, parseOverlayLabels, patchSegmentationOverlaySettings, resolveSegmentationOverlaySettings, } from './settings';
+export type { SegmentationOverlayBlendMode, SegmentationOverlaySettings } from './settings';

package/dist/components/SegmentationOverlay/maskTexture.d.ts

@@ -0,0 +1,23 @@
+import { SemanticMask } from '../../segmentation2d/types';
+import * as THREE from "three";
+/** One red byte per pixel holding the class index; nearest filtering keeps classes crisp. */
+export declare const createSemanticMaskTexture: (width?: number, height?: number) => THREE.DataTexture;
+/**
+ * Copy a mask into the texture, re-allocating when its size changed. Returns
+ * the texture to use (a new one when re-allocated; dispose the old one).
+ */
+export declare const uploadSemanticMask: (texture: THREE.DataTexture, mask: SemanticMask) => THREE.DataTexture;
+type Uploaded = {
+    texture: THREE.DataTexture;
+    version: number;
+    mask: SemanticMask | null;
+};
+/**
+ * Keep a GPU copy of a mask in sync with its `version`. The returned holder
+ * is stable; call `sync()` once per frame (or render) before drawing.
+ */
+export declare const useSemanticMaskTexture: (mask: SemanticMask | null) => {
+    holder: Uploaded;
+    sync: () => THREE.DataTexture;
+};
+export {};

package/dist/components/SegmentationOverlay/providers.d.ts

@@ -0,0 +1,72 @@
+import { FaceRegionLabel } from '../../segmentation2d/faceRegions';
+import { SemanticMask } from '../../segmentation2d/types';
+import { SemanticSegmentationModelOptions, SemanticSegmentationStatus } from '../../types/segmentation';
+/** Mask size for a long edge, keeping the feed's aspect ratio. */
+export declare const resolveMaskSize: (feed: {
+    width: number;
+    height: number;
+}, longEdge: number) => {
+    width: number;
+    height: number;
+};
+export type UseFaceRegionMaskOptions = {
+    /** Which face, or `"all"` to stack every tracked face into one mask. Default `"all"`. */
+    faceIndex?: number | "all";
+    /** Only rasterize these regions. Default: all of `FACE_REGION_LABELS`. */
+    regions?: readonly FaceRegionLabel[];
+    /** Mask long edge in pixels. Default 256. */
+    resolution?: number;
+    /** Cap how often the mask is re-rasterized. Omit for every frame. */
+    maxUpdateFps?: number;
+    /**
+     * Keep a face's last mask for this long (ms) when the tracker drops it,
+     * bridging the brief dropouts small or fast faces cause. Default 250,
+     * matching `useFaceInfos`. 0 clears the mask on the first missing frame.
+     */
+    holdMs?: number;
+    /**
+     * While a face is held, move it along its last velocity for up to this
+     * long (ms) so the mask keeps up with a moving subject. Default 0.
+     */
+    predictMs?: number;
+};
+/**
+ * A semantic mask of `face_skin`, `brows`, `eyes`, `lips` and `mouth`
+ * rasterized from the face tracker's landmarks every frame. The returned
+ * object is stable and mutated in place; its `version` changes on updates.
+ * Requires a face tracker in the session.
+ */
+export declare const useFaceRegionMask: ({ faceIndex, regions, resolution, maxUpdateFps, holdMs, predictMs, }?: UseFaceRegionMaskOptions) => SemanticMask;
+export declare const PERSON_MASK_LABELS: readonly ["bg", "person"];
+export type UsePersonMaskOptions = {
+    /** Cap how often the mask is read back from the GPU. Default 15. */
+    maxUpdateFps?: number;
+    /** Keep the segmentation model running. Default true. */
+    active?: boolean;
+};
+/**
+ * The SDK's portrait segmentation as a semantic mask (`bg` / `person`) in
+ * feed space. Acquires the segmentation model itself. Each update is a
+ * GPU→CPU readback, so it is rate-limited by default.
+ */
+export declare const usePersonMask: ({ maxUpdateFps, active, }?: UsePersonMaskOptions) => SemanticMask;
+export type UseSemanticSegmentationMaskOptions = SemanticSegmentationModelOptions & {
+    /** Keep the model running. Default true. */
+    active?: boolean;
+};
+export type SemanticSegmentationMaskResult = {
+    /** Stable mask in feed space; `version` stays 0 until the first inference. */
+    mask: SemanticMask;
+    status: SemanticSegmentationStatus;
+    error: Error | null;
+    labels: readonly string[];
+};
+/**
+ * A category-segmentation mask from `XRModel.SEMANTIC_SEGMENTATION` (hair or
+ * multiclass). Acquires the model itself; the first acquirer in a session
+ * picks the preset and model URL. The mask is produced on the model's own
+ * loop at its `targetFps` (15 by default), so no extra throttle is needed.
+ */
+export declare const useSemanticSegmentationMask: ({ active, ...modelOptions }?: UseSemanticSegmentationMaskOptions) => SemanticSegmentationMaskResult;
+/** MediaPipe Hair Segmenter as a `bg` / `hair` mask in feed space. */
+export declare const useHairMask: (options?: Omit<UseSemanticSegmentationMaskOptions, "preset">) => SemanticSegmentationMaskResult;

package/dist/components/SegmentationOverlay/settings.d.ts

@@ -0,0 +1,65 @@
+export declare const SEGMENTATION_OVERLAY_BLEND_MODES: readonly ["normal", "multiply", "screen", "overlay"];
+export type SegmentationOverlayBlendMode = (typeof SEGMENTATION_OVERLAY_BLEND_MODES)[number];
+/** Serializable look of a `SegmentationOverlay`. */
+export type SegmentationOverlaySettings = {
+    /** Region label to show (comma-separate several, e.g. `"lips,mouth"`). */
+    label: string;
+    /** Show everything except the selected labels. */
+    invert: boolean;
+    color: string;
+    opacity: number;
+    /** How the paint combines with the camera pixels underneath. */
+    blendMode: SegmentationOverlayBlendMode;
+    /** Edge feather radius in mask texels (0 = hard class edges). */
+    feather: number;
+    /** Flip the mask horizontally (source-space masks on a mirrored feed). */
+    mirrored: boolean;
+};
+export declare const DEFAULT_SEGMENTATION_OVERLAY_SETTINGS: SegmentationOverlaySettings;
+export declare const resolveSegmentationOverlaySettings: (input?: Partial<SegmentationOverlaySettings>) => SegmentationOverlaySettings;
+export declare const patchSegmentationOverlaySettings: (current: SegmentationOverlaySettings, patch: Partial<SegmentationOverlaySettings>) => SegmentationOverlaySettings;
+/** Split a `label` setting into the individual labels it names. */
+export declare const parseOverlayLabels: (label: string | readonly string[]) => string[];
+export declare const SEGMENTATION_OVERLAY_SETTINGS_FIELDS: [{
+    readonly key: "label";
+    readonly label: "Region";
+    readonly type: "select";
+    readonly options: {
+        label: "bg" | "brows" | "eyes" | "face_skin" | "hair" | "lips" | "mouth" | "person";
+        value: "bg" | "brows" | "eyes" | "face_skin" | "hair" | "lips" | "mouth" | "person";
+    }[];
+}, {
+    readonly key: "invert";
+    readonly label: "Invert selection";
+    readonly type: "boolean";
+}, {
+    readonly key: "color";
+    readonly label: "Color";
+    readonly type: "color";
+}, {
+    readonly key: "opacity";
+    readonly label: "Opacity";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 1;
+    readonly step: 0.01;
+}, {
+    readonly key: "blendMode";
+    readonly label: "Blend";
+    readonly type: "select";
+    readonly options: {
+        label: "multiply" | "overlay" | "screen" | "normal";
+        value: "multiply" | "overlay" | "screen" | "normal";
+    }[];
+}, {
+    readonly key: "feather";
+    readonly label: "Feather (texels)";
+    readonly type: "number";
+    readonly min: 0;
+    readonly max: 8;
+    readonly step: 0.5;
+}, {
+    readonly key: "mirrored";
+    readonly label: "Mirror mask";
+    readonly type: "boolean";
+}];

package/dist/components/ShoulderOccluder/index.d.ts

@@ -0,0 +1,43 @@
+import { PropsWithChildren } from 'react';
+import { CanonicalOffset } from '../HeadOccluder/useLandmarkPoseFit';
+import { CanonicalTorsoFitOptions } from './useCanonicalTorsoFit';
+export { CANONICAL_TORSO_FIT_DEFAULT_SMOOTHING, useCanonicalTorsoFit, } from './useCanonicalTorsoFit';
+export type { CanonicalTorsoFitOptions } from './useCanonicalTorsoFit';
+/** The canonical-frame shoulder / upper-torso mesh. */
+export declare const SHOULDER_OCCLUDER_V1_PATH = "/assets/xr/3d-models/shoulder-occluder-v1.glb";
+export declare const SHOULDER_OCCLUDER_DEFAULT_OPACITY = 1;
+export declare const shoulderOccluderUrl: () => string;
+export type ShoulderOccluderProps = {
+    /** Which tracked body feeds the fit. Matches the parent `BodyTracker`'s `bodyIndex`. */
+    bodyIndex?: number;
+    /** Adjustments on top of the fit, in torso centimetres. */
+    offset?: CanonicalOffset;
+    /** Override the mesh. The fit expects a torso-frame mesh. */
+    url?: string;
+    /** Draw the mesh visibly (calibration). Production keeps it depth-only. */
+    showDebugMaterial?: boolean;
+    opacity?: number;
+    /** Per-frame EMA factor for the fitted pose, `1` = no smoothing. */
+    smoothing?: number;
+    onFit?: CanonicalTorsoFitOptions["onFit"];
+};
+/**
+ * Depth-only shoulder and upper-torso mesh under a `BodyTracker`, so
+ * accessories around the neck and shoulders (necklaces, scarves, straps,
+ * wings, capes) pass behind the body. Same contract as `HeadOccluder`:
+ * `colorWrite: false`, `depthWrite: true`, `renderOrder: -1`,
+ * `frustumCulled: false`, fitted every frame from the two shoulder
+ * landmarks only (selfie mode; nothing below them is read). Mount it beside a `HeadBinding` / `HeadOccluder` for a full
+ * head-and-shoulders occluder; the two necks overlap on purpose.
+ */
+export declare const ShoulderOccluder: ({ bodyIndex, offset, url, showDebugMaterial, opacity, smoothing, onFit, }: ShoulderOccluderProps) => import("react/jsx-runtime").JSX.Element | null;
+export type CanonicalTorsoFrameProps = PropsWithChildren<CanonicalTorsoFitOptions>;
+/**
+ * A group, inside a `BodyTracker`, whose children are authored in torso
+ * centimetres: origin between the shoulder joints, +X screen right (the
+ * person's right in the mirrored selfie view), +Y up, +Z toward the camera;
+ * shoulders at `x = ±18`. Fitted with
+ * the same solver as `ShoulderOccluder`, so a necklace placed here sits where
+ * the occluder expects it.
+ */
+export declare const CanonicalTorsoFrame: ({ children, ...options }: CanonicalTorsoFrameProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/ShoulderOccluder/useCanonicalTorsoFit.d.ts

@@ -0,0 +1,24 @@
+import { MutableRefObject } from 'react';
+import { CanonicalOffset, LandmarkPoseFit } from '../HeadOccluder/useLandmarkPoseFit';
+import * as THREE from "three";
+export type CanonicalTorsoFitOptions = {
+    /** Which tracked body feeds the fit. Matches the parent `BodyTracker`'s `bodyIndex`. */
+    bodyIndex?: number;
+    offset?: CanonicalOffset;
+    /** Per-frame EMA factor for the fitted pose, `1` = no smoothing. */
+    smoothing?: number;
+    enabled?: boolean;
+    onFit?: (fit: LandmarkPoseFit) => void;
+    /** Fires once on body found (`true`) and once on body lost (`false`). */
+    onTrackingChange?: (tracked: boolean) => void;
+};
+export declare const CANONICAL_TORSO_FIT_DEFAULT_SMOOTHING = 0.5;
+/**
+ * Drives `target` (a child of a `BodyTracker` group) with the canonical torso
+ * pose from the two shoulder joints: scale from their distance, roll from the
+ * line between them, yaw from their depth difference, no pitch. Nothing below
+ * the shoulders is read (selfie mode: the hips are out of frame and their
+ * predicted positions inflated the torso at close range). Written as a local
+ * transform re-expressed in the parent's frame, like the head fit.
+ */
+export declare const useCanonicalTorsoFit: (target: MutableRefObject<THREE.Object3D | null>, { bodyIndex, offset, smoothing, enabled, onFit, onTrackingChange, }?: CanonicalTorsoFitOptions) => void;

package/dist/components/SpringSwing/SpringSwing.d.ts

@@ -0,0 +1,22 @@
+import { Euler, Vector3 } from '@react-three/fiber';
+import { ReactNode } from 'react';
+import { SpringSwingOptions } from '../../spring/swing';
+export type SpringSwingProps = SpringSwingOptions & {
+    /** False: the children hang still at rest. Default true. */
+    enabled?: boolean;
+    /** The pivot in the parent (the children swing about it). */
+    position?: Vector3;
+    /** Turns the rest direction (the children hang along this group's −Y). */
+    rotation?: Euler;
+    children?: ReactNode;
+};
+/**
+ * Its children swing about its origin, hanging along its own −Y, as
+ * whatever it sits in moves and turns, then settle: drop earrings,
+ * pendants, charms. `frequency`, `damping`, `maxAngle` and `length` set the
+ * feel (gentle jewellery by default). The rest direction is the parent's own
+ * down, so a tilt of the head tilts them too; only motion swings them. It
+ * swings from the pose it is drawn at (the scene's before-render hook) and
+ * rests while hidden.
+ */
+export declare const SpringSwing: ({ enabled, position, rotation, children, ...options }: SpringSwingProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/SpringSwing/index.d.ts

@@ -0,0 +1 @@
+export { SpringSwing, type SpringSwingProps } from './SpringSwing';

package/dist/components/XRProvider/index.d.ts

@@ -1,13 +1,27 @@
 import { PropsWithChildren } from 'react';
 import { SessionFacade } from '../../hooks/useXRSession';
-import { XRPerfConfig } from '../../types';
+import { XRLifecycleConfig, XRPerfConfig } from '../../types';
+import { XRQualityConfigInput } from '../../quality/types';
 export type XRContextType = {
     session: SessionFacade;
 };
 export declare const useXRContext: () => XRContextType;
+/** The session facade when inside an `<XRProvider>`, else `null` (for components that work with or without a session). */
+export declare const useOptionalXRContext: () => XRContextType | null;
 export type XRProviderProps = PropsWithChildren<{
     /** Performance config: cap ML inference fps and camera resolution to reduce
      *  GPU/CPU load and heat. See {@link XRPerfConfig}. */
     perf?: XRPerfConfig;
+    /** Lifecycle behaviour (pause while hidden). See {@link XRLifecycleConfig}. */
+    lifecycle?: XRLifecycleConfig;
+    /**
+     * Adaptive quality. ON by default with `DEFAULT_QUALITY_TIERS` and
+     * `DEFAULT_PERFORMANCE_BUDGET`: tracker fps, analysis resolution and the
+     * render pixel ratio step down under load and back up when it clears.
+     * Pass a partial config ({@link XRQualityConfigInput}) to customise (tiers, budget,
+     * bounds, `adaptive: false` to pin), or `false` to mount no controller
+     * (mount `<XRQualityController>` yourself, or manage `perf` by hand).
+     */
+    quality?: XRQualityConfigInput | false;
 }>;
-export declare const XRProvider: ({ children, perf }: XRProviderProps) => import("react/jsx-runtime").JSX.Element;
+export declare const XRProvider: ({ children, perf, lifecycle, quality }: XRProviderProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/XRScene/renderOutputTarget.d.ts

@@ -0,0 +1,12 @@
+import * as THREE from "three";
+/**
+ * The render target `XRScene` captures the scene into for `renderOutputs`
+ * (scene colour and/or depth). It has a stencil buffer, as the canvas does:
+ * the captured frame must match the screen, and face effects use stencil
+ * bits (the mouth cut-out 0x01, the face surface's self-occlusion 0x80).
+ * With `sceneDepth` a depth texture replaces the depth renderbuffer, so it
+ * carries the stencil too (DEPTH24_STENCIL8); sampling it still reads depth.
+ */
+export declare const createXRSceneRenderOutputTarget: (width: number, height: number, { sceneDepth }?: {
+    sceneDepth?: boolean;
+}) => THREE.WebGLRenderTarget;

package/dist/components/XRViewport/hooks/useViewportExternalFaces.d.ts

@@ -9,5 +9,5 @@ export declare const useViewportExternalFaces: ({ enabled, selectedSource, }: {
     selectedSource: CalibrationMediaSourceKind;
 }) => {
     faces: import('../../../types').FaceTrackingResult[];
-    trackerStatus: "idle" | "ready";
+    trackerStatus: "ready" | "idle";
 };

package/dist/components/XRViewport/hooks/useViewportMediaSource.d.ts

@@ -11,6 +11,6 @@ export declare const useViewportMediaSource: ({ enabled, imageAsset, selectedSou
     imageRef: import('react').RefObject<HTMLImageElement>;
     stream: MediaStream | null;
     mediaSize: XRViewportSize;
-    status: "idle" | "ready" | "error" | "requesting";
+    status: "ready" | "error" | "requesting" | "idle";
     error: string | null;
 };

package/dist/components/XRViewport/hooks/useViewportPipeline.d.ts

@@ -24,7 +24,7 @@ export declare const useViewportPipeline: ({ fitMode, imageOptions, initialImage
         imageRef: import('react').RefObject<HTMLImageElement>;
         stream: MediaStream | null;
         mediaSize: import('..').XRViewportSize;
-        status: "idle" | "ready" | "error" | "requesting";
+        status: "ready" | "error" | "requesting" | "idle";
         error: string | null;
     };
     renderOutputState: import('..').XRViewportRenderOutputs;

package/dist/components/index.d.ts

@@ -5,9 +5,15 @@ export * from './FaceTracker';
 export * from './FaceMesh';
 export * from './FaceRetouch';
 export * from './FaceWarp3D';
+export * from './FaceInset';
+export * from './FaceLiquify';
+export * from './Faceless';
 export * from './GestureTracker';
+export * from './GestureListener';
 export * from './GestureTrigger';
 export * from './HandTracker';
+export * from './IrisEffect';
+export * from './HolisticTracker';
 export * from './HandTracking3D';
 export * from './HandTracking2DController';
 export * from './HandTracking2D';
@@ -15,11 +21,16 @@ export * from './HandJoints2D';
 export * from './HeadBinding';
 export * from './HeadBindingOccluder';
 export * from './HeadOccluder';
+export * from './ShoulderOccluder';
+export * from './SpringSwing';
+export * from './Necklace';
+export * from './HairLock';
 export * from './MeshRenderer';
 export * from './LightObject';
 export * from './LookAt';
 export * from './Panel';
 export * from './PinToMesh';
+export * from './ParticleEmitter';
 export * from './PerspectiveCamera';
 export * from './RenderGroupLayer';
 export * from './ScreenImage';

package/dist/config/index.d.ts

@@ -1,5 +1,4 @@
 export declare const libConfig: {
-    apiBaseUrl: string;
     assetStorageEndpoint: string;
     sdkAssetsBaseUrl: string;
     loggerPrefix: string;

package/dist/constants/index.d.ts

@@ -8,7 +8,10 @@ export declare enum XRModel {
     GESTURE_TRACKER = "vincentt.xr.gesture-tracker",
     FACE_TRACKER = "vincentt.xr.face-tracker",
     BODY_TRACKER = "vincentt.xr.body-tracker",
-    BACKGROUND_SEGMENTATION = "vincentt.xr.background-segmentation"
+    /** One MediaPipe Holistic inference for face + both hands + pose (single person). */
+    HOLISTIC_TRACKER = "vincentt.xr.holistic-tracker",
+    BACKGROUND_SEGMENTATION = "vincentt.xr.background-segmentation",
+    SEMANTIC_SEGMENTATION = "vincentt.xr.semantic-segmentation"
 }
 export declare enum XRComponentEnum {
     CAMERA = "vincentt.component.camera",

package/dist/context-DTxSQvp4.js

@@ -0,0 +1,13 @@
+import { createContext as t, useContext as c } from "react";
+const n = t(null), o = () => {
+  const e = c(n);
+  if (!e)
+    throw new Error("useScreenSpace must be used within ScreenSpaceUI");
+  return e;
+}, s = t(null), a = () => c(s) ?? 1;
+export {
+  s as S,
+  a,
+  n as b,
+  o as u
+};

package/dist/context-hA0Rb2Xa.cjs

@@ -0,0 +1 @@
+"use strict";const e=require("react"),c=e.createContext(null),s=()=>{const t=e.useContext(c);if(!t)throw new Error("useScreenSpace must be used within ScreenSpaceUI");return t},n=e.createContext(null),r=()=>e.useContext(n)??1;exports.ScreenRectAspectContext=n;exports.ScreenSpaceContext=c;exports.useScreenRectAspect=r;exports.useScreenSpace=s;

package/dist/contexts-BH7PdKFS.cjs

@@ -0,0 +1 @@
+"use strict";var Ee=Object.defineProperty;var Te=(e,t,n)=>t in e?Ee(e,t,{enumerable:!0,configurable:!0,writable:!0,value:n}):e[t]=n;var O=(e,t,n)=>Te(e,typeof t!="symbol"?t+"":t,n);const B=require("react/jsx-runtime"),ae=require("@react-three/fiber"),C=require("react"),Ae=require("three"),fe=require("./uv-BMFt19bg.cjs"),K=require("./selectors-C4X71aoD.cjs"),ue=require("./index-CfSF8LXa.cjs"),se=require("./context-hA0Rb2Xa.cjs");function Me(e){const t=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(e){for(const n in e)if(n!=="default"){const a=Object.getOwnPropertyDescriptor(e,n);Object.defineProperty(t,n,a.get?a:{enumerable:!0,get:()=>e[n]})}}return t.default=e,Object.freeze(t)}const j=Me(Ae),xe={display:"flex",alignItems:"center",justifyContent:"center",height:"100%",background:"#363636",color:"white",fontFamily:"monospace"},Ce=()=>B.jsx("div",{style:xe,children:"Loading..."}),Fe=e=>B.jsx("div",{style:xe,children:e.error}),ke=(e,t,{sceneDepth:n=!1}={})=>{const a=new j.WebGLRenderTarget(e,t,{colorSpace:j.SRGBColorSpace,depthBuffer:!0,stencilBuffer:!0});return n&&(a.depthTexture=new j.DepthTexture(e,t),a.depthTexture.format=j.DepthStencilFormat,a.depthTexture.type=j.UnsignedInt248Type),a},Ie=e=>typeof e=="number"?e:Array.isArray(e)?e[1]:3,le={position:"absolute",top:0,left:0,width:"100%",height:"100%",zIndex:10},ce={sceneColorTexture:null,sceneDepthTexture:null},Le=e=>{const t=K.useXRQualityState(),a=K.useXRQualityConfig()?(t==null?void 0:t.decision.tier.renderScale)??1:1,r=typeof window<"u"&&window.devicePixelRatio||1;return Math.max(.5,Math.min(r,e)*a)},Xe=({onRenderOutputs:e,renderOutputs:t,size:n})=>{const{gl:a,scene:r,size:i}=ae.useThree(),{session:c}=ue.useXRContext(),o=Math.max(1,Math.round((n==null?void 0:n.width)??i.width)),h=Math.max(1,Math.round((n==null?void 0:n.height)??i.height)),f=!!(t.sceneColor||t.sceneDepth),s=C.useMemo(()=>f?ke(o,h,{sceneDepth:!!t.sceneDepth}):null,[f,h,t.sceneDepth,o]);return C.useEffect(()=>{if(!s){e==null||e(ce);return}return e==null||e({sceneColorTexture:t.sceneColor?s.texture:null,sceneDepthTexture:t.sceneDepth&&s.depthTexture?s.depthTexture:null}),()=>{var l;s.dispose(),(l=s.depthTexture)==null||l.dispose(),e==null||e(ce)}},[e,t.sceneColor,t.sceneDepth,s]),ae.useFrame(()=>{if(!s)return;const l=[];t.excludeScreenUI!==!1&&r.traverse(u=>{u.visible&&u.renderOrder>=fe.RENDER_LAYERS.SCREEN_UI&&(l.push(u),u.visible=!1)});const p=a.getRenderTarget(),m=a.xr.enabled;a.xr.enabled=!1,a.setRenderTarget(s),a.clear(),c._renderFrame(),a.setRenderTarget(p),a.xr.enabled=m,l.forEach(u=>{u.visible=!0})},-100),null},Be=({style:e,canvasProps:t,children:n,loadingComponent:a,loadingTransitionDuration:r,errorComponent:i,renderTargetSize:c,renderOutputs:o={},onRenderOutputs:h})=>{const f=C.useRef(null),s=C.useRef(null),l=C.useRef(null),p=C.useRef(!1),m=Le(Ie(t==null?void 0:t.dpr)),{session:u}=ue.useXRContext(),x=K.useXRReady(),d=K.useXRError(),[g,R]=C.useState(!0);return C.useEffect(()=>{if(c){u._setRenderSize(Math.round(c.width),Math.round(c.height));return}const v=(E,F)=>{E<=0||F<=0||u._setRenderSize(Math.round(E),Math.round(F))},A=()=>{!s.current||p.current||(p.current=!0,u._setRenderTarget(s.current))},S=(E,F)=>{l.current!==null&&cancelAnimationFrame(l.current),l.current=requestAnimationFrame(()=>{l.current=null,v(E,F)})},y=new ResizeObserver(E=>{const F=E[0];if(!F)return;const{width:L,height:G}=F.contentRect;A(),S(L,G)});return f.current&&y.observe(f.current),A(),()=>{y.disconnect(),l.current!==null&&(cancelAnimationFrame(l.current),l.current=null),p.current=!1}},[c,u]),C.useEffect(()=>{x&&(r?setTimeout(()=>{R(!1)},r):R(!1))},[x,r]),B.jsxs("div",{id:"vincentt-xr-container",ref:f,style:{width:"100%",height:"100%",...e,position:"relative"},children:[g&&B.jsx("div",{style:le,children:a||B.jsx(Ce,{})}),d&&B.jsx("div",{style:le,children:i||B.jsx(Fe,{error:d.message})}),B.jsxs(ae.Canvas,{id:"vincentt-xr-canvas",ref:s,gl:{alpha:!0,preserveDrawingBuffer:!1,antialias:!0,stencil:!0,premultipliedAlpha:!1,toneMapping:j.NoToneMapping},...t,dpr:m,onCreated:v=>{c?u._setRenderSize(Math.round(c.width),Math.round(c.height)):u._setRenderTarget(s.current),u._setR3FState({renderer:v.gl,scene:v.scene,camera:v.camera}),v.gl.outputColorSpace=j.SRGBColorSpace,t!=null&&t.onCreated&&t.onCreated(v)},children:[B.jsx(Xe,{onRenderOutputs:h,renderOutputs:o,size:c}),n]})]})},ve=(e,t,n,a,r)=>{const i=e/2,c=t/2,o=n.left*i+a.left,h=n.right*i-a.right,f=n.bottom*c+a.bottom,s=n.top*c-a.top,l=h-o,p=s-f,m=(o+h)/2,u=(f+s)/2,x=r[0]*l/2,d=r[1]*p/2;return{centerX:m,centerY:u,width:l,height:p,pivotX:x,pivotY:d}},Ge={left:0,right:0,top:0,bottom:0},De={left:0,right:0,top:0,bottom:0},Ue=[0,0],je=({anchors:e,offsets:t,pivot:n=Ue,children:a})=>{const{width:r,height:i}=se.useScreenSpace(),c=C.useMemo(()=>({anchors:{...Ge,...e??{}},offsets:{...De,...t??{}}}),[e,t]),o=C.useMemo(()=>ve(r,i,c.anchors,c.offsets,n),[r,i,c,n]);C.useEffect(()=>{const l=c.anchors;l.left>l.right&&console.warn(`[ScreenTransform] inverted X axis: anchors.left (${l.left}) > anchors.right (${l.right})`),l.bottom>l.top&&console.warn(`[ScreenTransform] inverted Y axis: anchors.bottom (${l.bottom}) > anchors.top (${l.top})`),o.width<=0&&console.warn(`[ScreenTransform] zero or negative width (${o.width.toFixed(3)}) — anchors + offsets collapse the X extent`),o.height<=0&&console.warn(`[ScreenTransform] zero or negative height (${o.height.toFixed(3)}) — anchors + offsets collapse the Y extent`)},[c,o.width,o.height]);const h=n[0]!==0||n[1]!==0,f=h?[1,1,1]:[o.width,o.height,1],s=!h&&o.width>0&&o.height>0?o.width/o.height:null;return B.jsx("group",{position:[o.centerX-o.pivotX,o.centerY-o.pivotY,0],scale:f,renderOrder:fe.RENDER_LAYERS.SCREEN_UI,children:B.jsx(se.ScreenRectAspectContext.Provider,{value:s,children:a})})};class pe{constructor(t,n){O(this,"capabilities");O(this,"snapshot");O(this,"listeners",new Set);O(this,"eventListeners",new Map);this.capabilities=t,this.snapshot={state:"idle",frame:0,time:0,playMode:"forward",loop:!0,loopCount:0,...n}}play(){const t=this.snapshot.state==="paused";this.update({state:"playing"}),this.emit(t?"Resume":"PlayBegin")}pause(){this.update({state:"paused"}),this.emit("Pause")}restart(){this.update({state:"playing",frame:0,time:0}),this.emit("PlayBegin")}setPlayMode(t){!this.capabilities.canReverse&&(t==="reverse"||t==="ping-pong"||t==="random")||this.update({playMode:t})}setLoop(t,n=0){this.update({loop:t,loopCount:n})}seek(t){this.capabilities.canSeek&&this.update({frame:Math.max(0,Math.floor(t)),time:Math.max(0,t)})}subscribe(t){return this.listeners.add(t),()=>this.listeners.delete(t)}on(t,n){const a=this.eventListeners.get(t)??new Set;return a.add(n),this.eventListeners.set(t,a),()=>this.off(t,n)}off(t,n){var a;(a=this.eventListeners.get(t))==null||a.delete(n)}getSnapshot(){return this.snapshot}dispose(){this.listeners.clear(),this.eventListeners.clear(),this.snapshot={...this.snapshot,state:"idle"}}updateSnapshot(t){this.update(t)}emit(t){var n;(n=this.eventListeners.get(t))==null||n.forEach(a=>a({type:t,snapshot:this.snapshot}))}update(t){this.snapshot={...this.snapshot,...t},this.listeners.forEach(n=>n(this.snapshot))}}const ge=(e,t,n,a,r)=>{const i=Math.max(1,Math.floor(t)),c=Math.max(0,Math.floor(e)),o=n==="ping-pong"&&i>1?i*2-2:i,h=Math.floor(c/o),f=r>0?h>=r:!a&&c>=o,s=f?o-1:c%o;return{frame:n==="reverse"?i-1-s%i:n==="random"?s*7919%i:n==="ping-pong"&&s>=i?o-s:s,ended:f,loop:h}},$e=(e,t,n)=>{const a=Math.max(1,Math.floor(n));return Math.floor(Math.max(0,e)*Math.max(0,t))%a};var de={},me,qe;function We(e,t,n,i){var r=0,i=i===void 0?{}:i,c=i.loop===void 0?null:i.loop,o=i.palette===void 0?null:i.palette;if(t<=0||n<=0||t>65535||n>65535)throw new Error("Width/Height invalid.");function h(d){var g=d.length;if(g<2||g>256||g&g-1)throw new Error("Invalid code/color length, must be power of 2 and 2 .. 256.");return g}e[r++]=71,e[r++]=73,e[r++]=70,e[r++]=56,e[r++]=57,e[r++]=97;var f=0,s=0;if(o!==null){for(var l=h(o);l>>=1;)++f;if(l=1<<f,--f,i.background!==void 0){if(s=i.background,s>=l)throw new Error("Background index out of range.");if(s===0)throw new Error("Background index explicitly passed as 0.")}}if(e[r++]=t&255,e[r++]=t>>8&255,e[r++]=n&255,e[r++]=n>>8&255,e[r++]=(o!==null?128:0)|f,e[r++]=s,e[r++]=0,o!==null)for(var p=0,m=o.length;p<m;++p){var u=o[p];e[r++]=u>>16&255,e[r++]=u>>8&255,e[r++]=u&255}if(c!==null){if(c<0||c>65535)throw new Error("Loop count invalid.");e[r++]=33,e[r++]=255,e[r++]=11,e[r++]=78,e[r++]=69,e[r++]=84,e[r++]=83,e[r++]=67,e[r++]=65,e[r++]=80,e[r++]=69,e[r++]=50,e[r++]=46,e[r++]=48,e[r++]=3,e[r++]=1,e[r++]=c&255,e[r++]=c>>8&255,e[r++]=0}var x=!1;this.addFrame=function(d,g,R,v,A,S){if(x===!0&&(--r,x=!1),S=S===void 0?{}:S,d<0||g<0||d>65535||g>65535)throw new Error("x/y invalid.");if(R<=0||v<=0||R>65535||v>65535)throw new Error("Width/Height invalid.");if(A.length<R*v)throw new Error("Not enough pixels for the frame size.");var y=!0,E=S.palette;if(E==null&&(y=!1,E=o),E==null)throw new Error("Must supply either a local or global palette.");for(var F=h(E),L=0;F>>=1;)++L;F=1<<L;var G=S.delay===void 0?0:S.delay,_=S.disposal===void 0?0:S.disposal;if(_<0||_>3)throw new Error("Disposal out of range.");var T=!1,I=0;if(S.transparent!==void 0&&S.transparent!==null&&(T=!0,I=S.transparent,I<0||I>=F))throw new Error("Transparent color index.");if((_!==0||T||G!==0)&&(e[r++]=33,e[r++]=249,e[r++]=4,e[r++]=_<<2|(T===!0?1:0),e[r++]=G&255,e[r++]=G>>8&255,e[r++]=I,e[r++]=0),e[r++]=44,e[r++]=d&255,e[r++]=d>>8&255,e[r++]=g&255,e[r++]=g>>8&255,e[r++]=R&255,e[r++]=R>>8&255,e[r++]=v&255,e[r++]=v>>8&255,e[r++]=y===!0?128|L-1:0,y===!0)for(var $=0,X=E.length;$<X;++$){var k=E[$];e[r++]=k>>16&255,e[r++]=k>>8&255,e[r++]=k&255}return r=Pe(e,r,L<2?2:L,A),r},this.end=function(){return x===!1&&(e[r++]=59,x=!0),r},this.getOutputBuffer=function(){return e},this.setOutputBuffer=function(d){e=d},this.getOutputBufferPosition=function(){return r},this.setOutputBufferPosition=function(d){r=d}}function Pe(e,t,n,a){e[t++]=n;var r=t++,i=1<<n,c=i-1,o=i+1,h=o+1,f=n+1,s=0,l=0;function p(S){for(;s>=S;)e[t++]=l&255,l>>=8,s-=8,t===r+256&&(e[r]=255,r=t++)}function m(S){l|=S<<s,s+=f,p(8)}var u=a[0]&c,x={};m(i);for(var d=1,g=a.length;d<g;++d){var R=a[d]&c,v=u<<8|R,A=x[v];if(A===void 0){for(l|=u<<s,s+=f;s>=8;)e[t++]=l&255,l>>=8,s-=8,t===r+256&&(e[r]=255,r=t++);h===4096?(m(i),h=o+1,f=n+1,x={}):(h>=1<<f&&++f,x[v]=h++),u=R}else u=A}return m(u),m(o),p(1),r+1===t?e[r]=0:(e[r]=t-r-1,e[t++]=0),t}function Ne(e){var t=0;if(e[t++]!==71||e[t++]!==73||e[t++]!==70||e[t++]!==56||(e[t++]+1&253)!==56||e[t++]!==97)throw new Error("Invalid GIF 87a/89a header.");var n=e[t++]|e[t++]<<8,a=e[t++]|e[t++]<<8,r=e[t++],i=r>>7,c=r&7,o=1<<c+1;e[t++],e[t++];var h=null,f=null;i&&(h=t,f=o,t+=o*3);var s=!0,l=[],p=0,m=null,u=0,x=null;for(this.width=n,this.height=a;s&&t<e.length;)switch(e[t++]){case 33:switch(e[t++]){case 255:if(e[t]!==11||e[t+1]==78&&e[t+2]==69&&e[t+3]==84&&e[t+4]==83&&e[t+5]==67&&e[t+6]==65&&e[t+7]==80&&e[t+8]==69&&e[t+9]==50&&e[t+10]==46&&e[t+11]==48&&e[t+12]==3&&e[t+13]==1&&e[t+16]==0)t+=14,x=e[t++]|e[t++]<<8,t++;else for(t+=12;;){var d=e[t++];if(!(d>=0))throw Error("Invalid block size");if(d===0)break;t+=d}break;case 249:if(e[t++]!==4||e[t+4]!==0)throw new Error("Invalid graphics extension block.");var g=e[t++];p=e[t++]|e[t++]<<8,m=e[t++],g&1||(m=null),u=g>>2&7,t++;break;case 254:for(;;){var d=e[t++];if(!(d>=0))throw Error("Invalid block size");if(d===0)break;t+=d}break;default:throw new Error("Unknown graphic control label: 0x"+e[t-1].toString(16))}break;case 44:var R=e[t++]|e[t++]<<8,v=e[t++]|e[t++]<<8,A=e[t++]|e[t++]<<8,S=e[t++]|e[t++]<<8,y=e[t++],E=y>>7,F=y>>6&1,L=y&7,G=1<<L+1,_=h,T=f,I=!1;if(E){var I=!0;_=t,T=G,t+=G*3}var $=t;for(t++;;){var d=e[t++];if(!(d>=0))throw Error("Invalid block size");if(d===0)break;t+=d}l.push({x:R,y:v,width:A,height:S,has_local_palette:I,palette_offset:_,palette_size:T,data_offset:$,data_length:t-$,transparent_index:m,interlaced:!!F,delay:p,disposal:u});break;case 59:s=!1;break;default:throw new Error("Unknown gif block: 0x"+e[t-1].toString(16))}this.numFrames=function(){return l.length},this.loopCount=function(){return x},this.frameInfo=function(X){if(X<0||X>=l.length)throw new Error("Frame index out of range.");return l[X]},this.decodeAndBlitFrameBGRA=function(X,k){var w=this.frameInfo(X),Q=w.width*w.height,q=new Uint8Array(Q);he(e,w.data_offset,q,Q);var W=w.palette_offset,P=w.transparent_index;P===null&&(P=256);var D=w.width,N=n-D,Y=D,Z=(w.y*n+w.x)*4,b=((w.y+w.height)*n+w.x)*4,M=Z,V=N*4;w.interlaced===!0&&(V+=n*4*7);for(var H=8,z=0,ee=q.length;z<ee;++z){var U=q[z];if(Y===0&&(M+=V,Y=D,M>=b&&(V=N*4+n*4*(H-1),M=Z+(D+N)*(H<<1),H>>=1)),U===P)M+=4;else{var te=e[W+U*3],re=e[W+U*3+1],ne=e[W+U*3+2];k[M++]=ne,k[M++]=re,k[M++]=te,k[M++]=255}--Y}},this.decodeAndBlitFrameRGBA=function(X,k){var w=this.frameInfo(X),Q=w.width*w.height,q=new Uint8Array(Q);he(e,w.data_offset,q,Q);var W=w.palette_offset,P=w.transparent_index;P===null&&(P=256);var D=w.width,N=n-D,Y=D,Z=(w.y*n+w.x)*4,b=((w.y+w.height)*n+w.x)*4,M=Z,V=N*4;w.interlaced===!0&&(V+=n*4*7);for(var H=8,z=0,ee=q.length;z<ee;++z){var U=q[z];if(Y===0&&(M+=V,Y=D,M>=b&&(V=N*4+n*4*(H-1),M=Z+(D+N)*(H<<1),H>>=1)),U===P)M+=4;else{var te=e[W+U*3],re=e[W+U*3+1],ne=e[W+U*3+2];k[M++]=te,k[M++]=re,k[M++]=ne,k[M++]=255}--Y}}}function he(e,t,n,a){for(var r=e[t++],i=1<<r,c=i+1,o=c+1,h=r+1,f=(1<<h)-1,s=0,l=0,p=0,m=e[t++],u=new Int32Array(4096),x=null;;){for(;s<16&&m!==0;)l|=e[t++]<<s,s+=8,m===1?m=e[t++]:--m;if(s<h)break;var d=l&f;if(l>>=h,s-=h,d===i){o=c+1,h=r+1,f=(1<<h)-1,x=null;continue}else if(d===c)break;for(var g=d<o?d:x,R=0,v=g;v>i;)v=u[v]>>8,++R;var A=v,S=p+R+(g!==d?1:0);if(S>a){console.log("Warning, gif stream longer than expected.");return}n[p++]=A,p+=R;var y=p;for(g!==d&&(n[p++]=A),v=g;R--;)v=u[v],n[--y]=v&255,v>>=8;x!==null&&o<4096&&(u[o++]=x<<8|A,o>=f+1&&h<12&&(++h,f=f<<1|1)),x=d}return p!==a&&console.log("Warning, gif stream shorter than expected."),n}try{qe=de.GifWriter=We,me=de.GifReader=Ne}catch{}const Ye=me;function Ve(e){return async(t,n)=>{const a=e.find(r=>r.canResolve(t));if(!a)throw new we("No texture provider matched source",t);return Se(a.resolve.bind(a),t,n)}}class we extends Error{constructor(n,a){super(n);O(this,"source");this.name="TextureSourceLoadError",this.source=a}}function J(e){if(e.aborted)throw new DOMException("Texture source load aborted","AbortError")}async function Se(e,t,n){J(n);const a=await e(t,n);return n.aborted&&(a.dispose(),J(n)),a}function He(e){e==null||e.dispose()}const ye=5*1024*1024,oe=1e6,ie=180,ze=(e,t,n)=>{for(let a=n.y;a<n.y+n.height;a+=1)e.fill(0,(a*t+n.x)*4,(a*t+n.x+n.width)*4)},Oe=(e,t,n,a,r)=>t.byteLength>ye?`file is ${(t.byteLength/1024/1024).toFixed(1)} MB; max is 5 MB`:n*a>oe?`canvas is ${n}x${a}; max area is ${oe}`:r>ie?`frame count is ${r}; max is ${ie}`:r===0?"frame count is 0":e?null:"source URL is empty",Qe=e=>typeof e=="string"?e:e.src,Ze={canResolve:e=>typeof e=="string"?/\.gif(?:[?#].*)?$/i.test(e):e.kind==="gif",async resolve(e,t){const n=Qe(e),a=await fetch(n,{signal:t});if(!a.ok)throw new Error(`GIF request failed with ${a.status}`);const r=new Uint8Array(await a.arrayBuffer());J(t);const i=new Ye(r),c=i.numFrames(),o=Oe(n,r,i.width,i.height,c);if(o)throw console.warn(`[xr-sdk] GIF ScreenImage source rejected: ${o}`,n),new Error(`GIF source rejected: ${o}`);const h=document.createElement("canvas");h.width=i.width,h.height=i.height;const f=h.getContext("2d");if(!f)throw new Error("Could not create GIF canvas context");const s=new j.CanvasTexture(h);s.colorSpace=j.SRGBColorSpace;const l=new Uint8Array(i.width*i.height*4),p=new ImageData(new Uint8ClampedArray(l.buffer),i.width,i.height),m=Array.from({length:c},(_,T)=>i.frameInfo(T)),u=m.reduce((_,T)=>_+Math.max(20,T.delay*10),0)/1e3,x=new pe({canSeek:!1,canReverse:!1,supportsLoopCount:!0},{state:"ready",duration:u,frameCount:c});let d=0,g=0,R=!1,v=!1,A=0,S=0,y=null;const E=(_,T=!1)=>{T&&(l.fill(0),y=null),(y==null?void 0:y.info.disposal)===2?ze(l,i.width,y.info):y!=null&&y.restorePixels&&l.set(y.restorePixels);const I=m[_],$=I.disposal===3?new Uint8Array(l):null;return i.decodeAndBlitFrameRGBA(_,l),f.putImageData(p,0,0),s.needsUpdate=!0,y={info:I,restorePixels:$},v=!0,x.updateSnapshot({frame:_,time:m.slice(0,_).reduce((X,k)=>X+Math.max(20,k.delay*10),0)/1e3}),v=!1,x.emit("KeyFrameInSecond"),Math.max(20,I.delay*10)},F=_=>{g=window.setTimeout(()=>{d=requestAnimationFrame(L)},_)},L=()=>{if(R||x.getSnapshot().state!=="playing")return;const _=x.getSnapshot(),T=ge(A,c,_.playMode,_.loop,_.loopCount);if(T.ended){x.updateSnapshot({state:"ended",frame:T.frame,time:u}),x.emit("PlayEnd");return}const I=T.loop!==S;S=T.loop,A+=1,F(E(T.frame,I))},G=x.subscribe(_=>{v||(clearTimeout(g),cancelAnimationFrame(d),_.state==="playing"&&(d=requestAnimationFrame(L)))});return E(0),x.play(),{texture:s,controller:x,metadata:{width:i.width,height:i.height,duration:u,frameCount:c},dispose(){R=!0,G(),clearTimeout(g),cancelAnimationFrame(d),x.dispose(),s.dispose()}}}},_e=C.createContext(null),Re=C.createContext(null),Ke=()=>C.useContext(_e),Je=()=>C.useContext(Re);exports.BasicAnimatedTextureController=pe;exports.MAX_GIF_BYTES=ye;exports.MAX_GIF_FRAMES=ie;exports.MAX_GIF_PIXELS=oe;exports.ScreenTransform=je;exports.TextureSourceLoadError=we;exports.XRScene=Be;exports.XRViewportRenderOutputsContext=Re;exports.XRViewportStateContext=_e;exports.computeScreenTransform=ve;exports.createTextureSourceResolver=Ve;exports.disposeResolvedTextureSource=He;exports.getPlaybackFrame=ge;exports.getSequenceFrame=$e;exports.gifTextureSourceProvider=Ze;exports.resolveTextureSource=Se;exports.throwIfAborted=J;exports.useXRViewportRenderOutputs=Je;exports.useXRViewportState=Ke;