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

package/dist/{session-DLFN_VII.js → session-Cy0m7l7-.js}

@@ -1,15 +1,15 @@
-import { l as j, u as z, c as v, X as L } from "./index-9dlAQAhy.js";
-import { jsx as n, jsxs as u } from "react/jsx-runtime";
-import { createPortal as W } from "react-dom";
-import { useState as y, useRef as $, useMemo as F, useEffect as f } from "react";
-import { c as d, X } from "./x-Co8jPhP0.js";
-const M = (t, e) => new URL(`/assets/sdk/debug-ui/v1/${t}/${e}`, j.assetStorageEndpoint).href, C = (t) => t.replace(/\.[^.]+$/, "").replace(/[_-]+/g, " ").replace(/\s+/g, " ").trim().replace(/\b\w/g, (e) => e.toUpperCase()), P = [
+import { l as z, u as L, g as v, X as W } from "./index-CnGox6Xr.js";
+import { jsx as n, jsxs as h } from "react/jsx-runtime";
+import { createPortal as $ } from "react-dom";
+import { useState as y, useRef as M, useMemo as F, useEffect as f } from "react";
+import { c as l, X } from "./x-Co8jPhP0.js";
+const R = (t, e) => new URL(`/assets/sdk/debug-ui/v1/${t}/${e}`, z.assetStorageEndpoint).href, C = (t) => t.replace(/\.[^.]+$/, "").replace(/[_-]+/g, " ").replace(/\s+/g, " ").trim().replace(/\b\w/g, (e) => e.toUpperCase()), N = [
   "person_fullbody.mp4",
   "person_looking.mp4",
   "person_shaking_head.mp4",
   "person_thumbUp.mp4",
   "two_people_smiling.mp4"
-], U = [
+], P = [
   "person_fist_sign.jpg",
   "person_fullbody.jpg",
   "person_peace_sign.jpg",
@@ -17,20 +17,20 @@ const M = (t, e) => new URL(`/assets/sdk/debug-ui/v1/${t}/${e}`, j.assetStorageE
   "person_side_portrait.jpg",
   "three_people_smiling.jpg",
   "two_people_smiling.jpg"
-], V = (t, e) => ({
+], U = (t, e) => ({
   id: `sdk-video-${e + 1}`,
   kind: "video",
   label: C(t),
-  url: M("videos", t)
-}), D = (t, e) => ({
+  url: R("videos", t)
+}), V = (t, e) => ({
   id: `sdk-image-${e + 1}`,
   kind: "image",
   label: C(t),
-  url: M("images", t)
-}), N = P.map(V), T = U.map(D), ke = [
+  url: R("images", t)
+}), D = N.map(U), K = P.map(V), ke = [
+  ...D,
   { id: "webcam", kind: "webcam", label: "Webcam" },
-  ...N,
-  ...T
+  ...K
 ];
 /**
  * @license lucide-react v1.17.0 - ISC
@@ -38,7 +38,7 @@ const M = (t, e) => new URL(`/assets/sdk/debug-ui/v1/${t}/${e}`, j.assetStorageE
  * This source code is licensed under the ISC license.
  * See the LICENSE file in the root directory of this source tree.
  */
-const A = [
+const T = [
   [
     "path",
     {
@@ -47,14 +47,14 @@ const A = [
     }
   ],
   ["circle", { cx: "12", cy: "13", r: "3", key: "1vg3eu" }]
-], K = d("camera", A);
+], A = l("camera", T);
 /**
  * @license lucide-react v1.17.0 - ISC
  *
  * This source code is licensed under the ISC license.
  * See the LICENSE file in the root directory of this source tree.
  */
-const B = [["path", { d: "m6 9 6 6 6-6", key: "qrunsl" }]], O = d("chevron-down", B);
+const O = [["path", { d: "m6 9 6 6 6-6", key: "qrunsl" }]], B = l("chevron-down", O);
 /**
  * @license lucide-react v1.17.0 - ISC
  *
@@ -68,7 +68,7 @@ const H = [
   ["circle", { cx: "15", cy: "12", r: "1", key: "1tmaij" }],
   ["circle", { cx: "15", cy: "5", r: "1", key: "19l28e" }],
   ["circle", { cx: "15", cy: "19", r: "1", key: "f4zoj3" }]
-], G = d("grip-vertical", H);
+], G = l("grip-vertical", H);
 /**
  * @license lucide-react v1.17.0 - ISC
  *
@@ -79,7 +79,7 @@ const Y = [
   ["rect", { width: "18", height: "18", x: "3", y: "3", rx: "2", ry: "2", key: "1m3agn" }],
   ["circle", { cx: "9", cy: "9", r: "2", key: "af1f0g" }],
   ["path", { d: "m21 15-3.086-3.086a2 2 0 0 0-2.828 0L6 21", key: "1xmnt7" }]
-], q = d("image", Y);
+], q = l("image", Y);
 /**
  * @license lucide-react v1.17.0 - ISC
  *
@@ -90,7 +90,7 @@ const J = [
   ["path", { d: "M4 5h16", key: "1tepv9" }],
   ["path", { d: "M4 12h16", key: "1lakjw" }],
   ["path", { d: "M4 19h16", key: "1djgab" }]
-], Q = d("menu", J);
+], Q = l("menu", J);
 /**
  * @license lucide-react v1.17.0 - ISC
  *
@@ -106,7 +106,7 @@ const Z = [
     }
   ],
   ["rect", { x: "2", y: "6", width: "14", height: "12", rx: "2", key: "158x01" }]
-], ee = d("video", Z), te = (t) => t === "webcam" ? "📷 " : t === "image" ? "🖼 " : "▶ ", re = {
+], ee = l("video", Z), te = (t) => t === "webcam" ? "📷 " : t === "image" ? "🖼 " : "▶ ", re = {
   position: "fixed",
   zIndex: 2e4,
   pointerEvents: "none"
@@ -170,7 +170,7 @@ const Z = [
   position: "relative",
   display: "flex",
   alignItems: "center"
-}, de = {
+}, le = {
   width: "100%",
   minWidth: 140,
   height: 24,
@@ -184,7 +184,7 @@ const Z = [
   paddingRight: 20,
   appearance: "none",
   cursor: "pointer"
-}, le = {
+}, de = {
   pointerEvents: "none",
   position: "absolute",
   right: 5,
@@ -207,72 +207,72 @@ const Z = [
   value: t,
   onChange: e,
   sources: i,
-  style: s
+  style: c
 }) => {
-  const [c, m] = y(!1), [a, h] = y({ x: 16, y: 16 }), [l, b] = y(t.kind), p = $(null), w = F(
+  const [g, d] = y(!1), [s, b] = y({ x: 16, y: 16 }), [o, u] = y(t.kind), p = M(null), w = F(
     () => ({
       webcam: i.filter((r) => r.kind === "webcam"),
       image: i.filter((r) => r.kind === "image"),
       video: i.filter((r) => r.kind === "video")
     }),
     [i]
-  ), k = w[l];
+  ), k = w[o];
   f(() => {
-    b(t.kind);
+    u(t.kind);
   }, [t.kind]);
-  const R = (r) => {
-    b(r);
-    const o = w[r][0];
-    o && e(o);
+  const I = (r) => {
+    u(r);
+    const a = w[r][0];
+    a && e(a);
   };
   f(() => {
-    const r = (g) => {
-      p.current && h({
-        x: Math.max(8, g.clientX - p.current.x),
-        y: Math.max(8, g.clientY - p.current.y)
+    const r = (m) => {
+      p.current && b({
+        x: Math.max(8, m.clientX - p.current.x),
+        y: Math.max(8, m.clientY - p.current.y)
       });
-    }, o = () => {
+    }, a = () => {
       p.current = null, document.body.classList.remove("select-none");
     };
-    return window.addEventListener("pointermove", r), window.addEventListener("pointerup", o), () => {
-      window.removeEventListener("pointermove", r), window.removeEventListener("pointerup", o);
+    return window.addEventListener("pointermove", r), window.addEventListener("pointerup", a), () => {
+      window.removeEventListener("pointermove", r), window.removeEventListener("pointerup", a);
     };
   }, []);
   const x = (r) => {
-    const o = r.currentTarget.getBoundingClientRect();
+    const a = r.currentTarget.getBoundingClientRect();
     p.current = {
-      x: r.clientX - o.left,
-      y: r.clientY - o.top
+      x: r.clientX - a.left,
+      y: r.clientY - a.top
     }, document.body.classList.add("select-none"), r.currentTarget.setPointerCapture(r.pointerId);
-  }, I = () => k.length === 0 ? /* @__PURE__ */ n("div", { style: pe, children: l === "webcam" ? "No camera source" : l === "image" ? "No image preview" : "No video preview" }) : /* @__PURE__ */ u("div", { style: ce, children: [
+  }, j = () => k.length === 0 ? /* @__PURE__ */ n("div", { style: pe, children: o === "webcam" ? "No camera source" : o === "image" ? "No image preview" : "No video preview" }) : /* @__PURE__ */ h("div", { style: ce, children: [
     /* @__PURE__ */ n(
       "select",
       {
         value: t.id,
         onChange: (r) => {
-          const o = i.find((g) => g.id === r.target.value);
-          o && e(o);
+          const a = i.find((m) => m.id === r.target.value);
+          a && e(a);
         },
-        style: de,
-        children: k.map((r) => /* @__PURE__ */ u("option", { value: r.id, children: [
-          te(l),
+        style: le,
+        children: k.map((r) => /* @__PURE__ */ h("option", { value: r.id, children: [
+          te(o),
           r.label
         ] }, r.id))
       }
     ),
-    /* @__PURE__ */ n("div", { style: le, children: /* @__PURE__ */ n("span", { style: { width: 10, height: 10 }, children: /* @__PURE__ */ n(O, { size: 10, strokeWidth: 1.8 }) }) })
+    /* @__PURE__ */ n("div", { style: de, children: /* @__PURE__ */ n("span", { style: { width: 10, height: 10 }, children: /* @__PURE__ */ n(B, { size: 10, strokeWidth: 1.8 }) }) })
   ] });
-  return typeof document > "u" ? null : W(
-    /* @__PURE__ */ n("div", { style: { ...re, left: a.x, top: a.y, ...s }, children: c ? (
+  return typeof document > "u" ? null : $(
+    /* @__PURE__ */ n("div", { style: { ...re, left: s.x, top: s.y, ...c }, children: g ? (
       // --- Expanded State ---
-      /* @__PURE__ */ u("div", { style: ie, children: [
-        /* @__PURE__ */ u("div", { style: oe, children: [
+      /* @__PURE__ */ h("div", { style: ie, children: [
+        /* @__PURE__ */ h("div", { style: oe, children: [
           /* @__PURE__ */ n("div", { onPointerDown: x, style: se, title: "Drag to move", children: /* @__PURE__ */ n(G, { size: 11, strokeWidth: 2 }) }),
           /* @__PURE__ */ n(
             "button",
             {
               type: "button",
-              onClick: () => m(!1),
+              onClick: () => d(!1),
               style: S(!1),
               title: "Close Menu",
               children: /* @__PURE__ */ n("span", { style: _, children: /* @__PURE__ */ n(X, { size: 14, strokeWidth: 1.8 }) })
@@ -283,15 +283,15 @@ const Z = [
             "button",
             {
               type: "button",
-              onClick: () => R(r),
-              style: S(l === r),
+              onClick: () => I(r),
+              style: S(o === r),
               title: r.charAt(0).toUpperCase() + r.slice(1),
-              children: /* @__PURE__ */ n("span", { style: _, children: r === "webcam" ? /* @__PURE__ */ n(K, { size: 14, strokeWidth: 1.8 }) : r === "image" ? /* @__PURE__ */ n(q, { size: 14, strokeWidth: 1.8 }) : /* @__PURE__ */ n(ee, { size: 14, strokeWidth: 1.8 }) })
+              children: /* @__PURE__ */ n("span", { style: _, children: r === "webcam" ? /* @__PURE__ */ n(A, { size: 14, strokeWidth: 1.8 }) : r === "image" ? /* @__PURE__ */ n(q, { size: 14, strokeWidth: 1.8 }) : /* @__PURE__ */ n(ee, { size: 14, strokeWidth: 1.8 }) })
             },
             r
           ))
         ] }),
-        I()
+        j()
       ] })
     ) : (
       // --- Collapsed State (Minimal FAB) ---
@@ -299,7 +299,7 @@ const Z = [
         "div",
         {
           style: ne,
-          onClick: () => m(!0),
+          onClick: () => d(!0),
           onPointerDown: x,
           title: "Open Media Menu",
           children: /* @__PURE__ */ n("span", { style: { width: 16, height: 16 }, children: /* @__PURE__ */ n(Q, { size: 14, strokeWidth: 1.8 }) })
@@ -313,51 +313,51 @@ const Z = [
   e.crossOrigin = "anonymous", e.src = t, await e.decode();
   const i = document.createElement("canvas");
   i.width = e.naturalWidth, i.height = e.naturalHeight;
-  const s = i.getContext("2d");
-  if (!s) throw new Error("Unable to create image media canvas");
-  return s.drawImage(e, 0, 0, i.width, i.height), i.captureStream(30);
+  const c = i.getContext("2d");
+  if (!c) throw new Error("Unable to create image media canvas");
+  return c.drawImage(e, 0, 0, i.width, i.height), i.captureStream(30);
 }, ue = async (t) => {
   const e = document.createElement("video");
   return e.src = t, e.loop = !0, e.muted = !0, e.playsInline = !0, e.crossOrigin = "anonymous", await e.play(), e.captureStream();
 }, me = (t, e) => {
-  const { session: i } = z();
-  f(() => {
-    let s = !1, c = null;
+  const { session: i } = L(), c = JSON.stringify((e == null ? void 0 : e.pipeline) ?? null), g = M(e == null ? void 0 : e.pipeline);
+  g.current = e == null ? void 0 : e.pipeline, f(() => {
+    let d = !1, s = null;
     return (async () => {
       try {
         if (t.kind === "webcam")
           await i.setMediaSource({ source: v.WEBCAM });
         else {
           if (!t.url) throw new Error(`Missing media URL for ${t.id}`);
-          const a = t.kind === "image" ? await ge(t.url) : await ue(t.url);
-          if (c = a, s) {
-            a.getTracks().forEach((h) => h.stop());
+          const o = t.kind === "image" ? await ge(t.url) : await ue(t.url);
+          if (s = o, d) {
+            o.getTracks().forEach((u) => u.stop());
             return;
           }
           await i.setMediaSource({
             source: v.STREAM,
-            stream: a,
+            stream: o,
             sourceKind: t.kind
           });
         }
         await i.registerXRPipeline(
-          (e == null ? void 0 : e.pipeline) ?? [
-            { model: L.FACE_TRACKER, options: { numFaces: (e == null ? void 0 : e.numFaces) ?? 1 } }
+          g.current ?? [
+            { model: W.FACE_TRACKER, options: { numFaces: (e == null ? void 0 : e.numFaces) ?? 1 } }
           ]
         ), await i.start();
-      } catch (a) {
-        console.error("[MediaSourceSession] Error initializing XR session:", a);
+      } catch (o) {
+        console.error("[MediaSourceSession] Error initializing XR session:", o);
       }
     })(), () => {
-      s = !0, c == null || c.getTracks().forEach((a) => a.stop());
+      d = !0, s == null || s.getTracks().forEach((o) => o.stop());
     };
-  }, [t, e == null ? void 0 : e.numFaces, e == null ? void 0 : e.pipeline, i]);
+  }, [t, e == null ? void 0 : e.numFaces, c, i]);
 }, ve = me;
 export {
   xe as M,
-  N as a,
+  D as a,
   me as b,
   ke as d,
-  T as s,
+  K as s,
   ve as u
 };

package/dist/settings-DRR7-snV.cjs

@@ -0,0 +1 @@
+"use strict";const o=require("./detector-ijypGtse.cjs"),s=["both","left","right","none"],n={hands:"both",targetFps:24,analysisMaxDimension:768,holdMs:250,predictMs:0,outputFaceBlendshapes:!0},l=[{key:"hands",label:"Hands",type:"select",options:s.map(e=>({label:e,value:e}))},{key:"targetFps",label:"Target FPS (0 = uncapped)",type:"number",min:0,max:60,step:1},{key:"analysisMaxDimension",label:"Analysis max px",type:"number",min:256,max:1280,step:64},{key:"holdMs",label:"Hold (ms)",type:"number",min:0,max:1e3,step:10},{key:"predictMs",label:"Predict (ms)",type:"number",min:0,max:300,step:10},{key:"outputFaceBlendshapes",label:"Face blendshapes (re-inits)",type:"boolean"}],r=e=>({...n,...e}),i=(e,t)=>({...e,...t}),p=e=>({hands:e.hands,targetFps:e.targetFps>0?e.targetFps:void 0,analysisMaxDimension:e.analysisMaxDimension,holdMs:e.holdMs,predictMs:e.predictMs,outputFaceBlendshapes:e.outputFaceBlendshapes}),a={...o.DEFAULT_GESTURE_DETECTOR_OPTIONS},T=[{key:"enterThreshold",label:"Enter threshold",type:"number",min:0,max:1,step:.01},{key:"exitThreshold",label:"Exit threshold",type:"number",min:0,max:1,step:.01},{key:"holdMs",label:"Hold before begin (ms)",type:"number",min:0,max:1e3,step:10},{key:"cooldownMs",label:"Cooldown after end (ms)",type:"number",min:0,max:3e3,step:50},{key:"minConfidence",label:"Min confidence",type:"number",min:0,max:1,step:.05},{key:"lostGraceMs",label:"Loss grace (ms)",type:"number",min:0,max:1e3,step:10}],c=(e,t=a)=>({...t,...e}),S=(e,t)=>({...e,...t});exports.DEFAULT_GESTURE_SETTINGS=a;exports.DEFAULT_HOLISTIC_TRACKER_SETTINGS=n;exports.GESTURE_SETTINGS_FIELDS=T;exports.HOLISTIC_HANDS_OPTIONS=s;exports.HOLISTIC_TRACKER_SETTINGS_FIELDS=l;exports.patchGestureSettings=S;exports.patchHolisticTrackerSettings=i;exports.resolveGestureSettings=c;exports.resolveHolisticTrackerSettings=r;exports.toHolisticTrackerProps=p;

package/dist/settings-aQk845NJ.js

@@ -0,0 +1,73 @@
+import { D as a } from "./detector-K8aej4MB.js";
+const t = [
+  "both",
+  "left",
+  "right",
+  "none"
+], n = {
+  hands: "both",
+  targetFps: 24,
+  analysisMaxDimension: 768,
+  holdMs: 250,
+  predictMs: 0,
+  outputFaceBlendshapes: !0
+}, p = [
+  {
+    key: "hands",
+    label: "Hands",
+    type: "select",
+    options: t.map((e) => ({ label: e, value: e }))
+  },
+  {
+    key: "targetFps",
+    label: "Target FPS (0 = uncapped)",
+    type: "number",
+    min: 0,
+    max: 60,
+    step: 1
+  },
+  {
+    key: "analysisMaxDimension",
+    label: "Analysis max px",
+    type: "number",
+    min: 256,
+    max: 1280,
+    step: 64
+  },
+  { key: "holdMs", label: "Hold (ms)", type: "number", min: 0, max: 1e3, step: 10 },
+  { key: "predictMs", label: "Predict (ms)", type: "number", min: 0, max: 300, step: 10 },
+  { key: "outputFaceBlendshapes", label: "Face blendshapes (re-inits)", type: "boolean" }
+], r = (e) => ({ ...n, ...e }), i = (e, s) => ({ ...e, ...s }), m = (e) => ({
+  hands: e.hands,
+  targetFps: e.targetFps > 0 ? e.targetFps : void 0,
+  analysisMaxDimension: e.analysisMaxDimension,
+  holdMs: e.holdMs,
+  predictMs: e.predictMs,
+  outputFaceBlendshapes: e.outputFaceBlendshapes
+}), o = { ...a }, c = [
+  { key: "enterThreshold", label: "Enter threshold", type: "number", min: 0, max: 1, step: 0.01 },
+  { key: "exitThreshold", label: "Exit threshold", type: "number", min: 0, max: 1, step: 0.01 },
+  { key: "holdMs", label: "Hold before begin (ms)", type: "number", min: 0, max: 1e3, step: 10 },
+  {
+    key: "cooldownMs",
+    label: "Cooldown after end (ms)",
+    type: "number",
+    min: 0,
+    max: 3e3,
+    step: 50
+  },
+  { key: "minConfidence", label: "Min confidence", type: "number", min: 0, max: 1, step: 0.05 },
+  { key: "lostGraceMs", label: "Loss grace (ms)", type: "number", min: 0, max: 1e3, step: 10 }
+], d = (e, s = o) => ({ ...s, ...e }), b = (e, s) => ({ ...e, ...s });
+export {
+  n as D,
+  c as G,
+  t as H,
+  p as a,
+  o as b,
+  b as c,
+  d,
+  i as p,
+  r,
+  m as t
+};

package/dist/subjects/index.d.ts

@@ -0,0 +1,2 @@
+export type { XRSubjectAssociation, XRSubjectCandidate, XRSubjectMemory, XRSubjectPolicy, XRSubjectSelection, XRSubjectSelectionResult, } from './types';
+export { DEFAULT_SUBJECT_POLICY, EMPTY_SUBJECT_MEMORY, XR_MAX_SUBJECTS, associateSubjects, faceCandidates, jointCandidates, selectSubject, } from './select';

package/dist/subjects/select.d.ts

@@ -0,0 +1,62 @@
+import { TrackerPoint } from '../types/common';
+import { XRSubjectAssociation, XRSubjectCandidate, XRSubjectMemory, XRSubjectPolicy, XRSubjectSelectionResult } from './types';
+export declare const DEFAULT_SUBJECT_POLICY: XRSubjectPolicy;
+/**
+ * Maximum subjects each tracker can report, and whether the count is a
+ * request option. Face: `numFaces` (1 default, raise per consumer; the first
+ * acquirer wins). Hand: 2 (fixed). Gesture: 1. Body: 1. Holistic: 1 (single
+ * person by design). Segmentation has no subjects.
+ */
+export declare const XR_MAX_SUBJECTS: Readonly<{
+    face: {
+        max: number;
+        default: number;
+        option: "numFaces";
+    };
+    hand: {
+        max: number;
+        default: number;
+        option: null;
+    };
+    gesture: {
+        max: number;
+        default: number;
+        option: null;
+    };
+    body: {
+        max: number;
+        default: number;
+        option: null;
+    };
+    holistic: {
+        max: number;
+        default: number;
+        option: null;
+    };
+}>;
+export declare const EMPTY_SUBJECT_MEMORY: XRSubjectMemory;
+/**
+ * Pick one subject. Pure: feed `result.memory` back on the next frame for
+ * `sticky`. `null` index means nothing to select (the consumer should treat
+ * it as a dropout and apply its own hold).
+ */
+export declare const selectSubject: (candidates: XRSubjectCandidate[], policy?: XRSubjectPolicy, memory?: XRSubjectMemory) => XRSubjectSelectionResult;
+type Landmark = {
+    x: number;
+    y: number;
+};
+/** Candidates from face-mesh landmark arrays (feed space): centre and width of the bounds. */
+export declare const faceCandidates: (faces: ReadonlyArray<ReadonlyArray<Landmark>>) => XRSubjectCandidate[];
+/** Candidates from tracker-space joint lists (hands, bodies): centre and span, converted to feed space. */
+export declare const jointCandidates: (subjects: ReadonlyArray<{
+    coordinates?: ReadonlyArray<TrackerPoint>;
+    label?: string;
+}>) => XRSubjectCandidate[];
+/**
+ * Greedy nearest-centre matching between two trackers' subjects (face ↔
+ * body, hand ↔ body). Each subject is used once; pairs farther than
+ * `maxDistance` (feed units) are not associated. This is the SDK's whole
+ * association contract: spatial proximity in the same frame, no identity.
+ */
+export declare const associateSubjects: (primary: XRSubjectCandidate[], secondary: XRSubjectCandidate[], maxDistance?: number) => XRSubjectAssociation[];
+export {};

package/dist/subjects/types.d.ts

@@ -0,0 +1,55 @@
+import { FeedPoint } from '../coordinates/spaces';
+/**
+ * How one subject is picked from a tracker's result array.
+ *
+ * - `index`: the result-array position (`policy.index`, default 0). The
+ *   SDK's historical behaviour; the position is NOT a persistent identity.
+ * - `largest`: the biggest subject (closest to the camera).
+ * - `nearest-center`: the subject closest to the feed centre.
+ * - `leftmost` / `rightmost`: by feed x (viewer's left / right as shown in the preview).
+ * - `sticky`: the subject nearest to the previously selected one (within
+ *   `stickyRadius`), falling back to `fallback` when none is close enough.
+ *   This is the SDK's only re-identification: spatial continuity, nothing
+ *   learned about the person.
+ */
+export type XRSubjectSelection = "index" | "largest" | "nearest-center" | "leftmost" | "rightmost" | "sticky";
+export type XRSubjectPolicy = {
+    selection: XRSubjectSelection;
+    /** Result-array position for `index`. Default 0. */
+    index?: number;
+    /** Max feed distance (0..1 units) a `sticky` subject may move between frames. Default 0.2. */
+    stickyRadius?: number;
+    /** What `sticky` picks when nothing is within the radius (default `largest`). */
+    fallback?: Exclude<XRSubjectSelection, "sticky">;
+};
+/** A subject reduced to what selection needs: its feed-space centre and size. */
+export type XRSubjectCandidate = {
+    /** Result-array position. */
+    index: number;
+    /** Feed space (0..1, top-left origin). */
+    center: FeedPoint;
+    /** Width in feed units (bounds width for faces, span for hands / bodies). */
+    size: number;
+    /** Extra identity hint the selection may use (e.g. handedness). */
+    label?: string;
+};
+export type XRSubjectSelectionResult = {
+    /** Selected result-array position, or `null` when there is no candidate. */
+    index: number | null;
+    /** Which rule decided. */
+    reason: XRSubjectSelection | "none" | "sticky-fallback";
+    /** Carry to the next call for `sticky`. */
+    memory: XRSubjectMemory;
+};
+/** Where the selected subject was last seen (for `sticky`). */
+export type XRSubjectMemory = {
+    center: FeedPoint | null;
+    label?: string;
+};
+/** A pair of subjects matched across two trackers (face ↔ body, hand ↔ body…). */
+export type XRSubjectAssociation = {
+    primaryIndex: number;
+    secondaryIndex: number;
+    /** Feed-space distance between the matched centres. */
+    distance: number;
+};

package/dist/tracking-config/apply.d.ts

@@ -0,0 +1,57 @@
+import { XRProviderProps } from '../components/XRProvider';
+import { XRModel } from '../constants';
+import { XRCameraRequest } from '../types/compositor';
+import { XRTrackerKind, XRTrackingConfig } from './types';
+/** `perf`, `lifecycle` and `quality` for `<XRProvider>`. */
+export declare const toProviderProps: (config: XRTrackingConfig) => Pick<XRProviderProps, "perf" | "lifecycle" | "quality">;
+/** The webcam request for `setMediaSource` / `switchCamera`. */
+export declare const toCameraRequest: (config: XRTrackingConfig) => XRCameraRequest;
+type TrackerProps = {
+    face: {
+        numFaces: number;
+        targetFps?: number;
+        holdMs: number;
+        predictMs: number;
+        active: boolean;
+    };
+    hand: {
+        targetFps?: number;
+        active: boolean;
+    };
+    gesture: {
+        targetFps?: number;
+        active: boolean;
+    };
+    /** `<BodyTracker>` has no fps prop; its cap comes from `toModelOptions` / `perf.targetFps`. */
+    body: {
+        active: boolean;
+    };
+    holistic: {
+        targetFps?: number;
+        hands: XRTrackingConfig["trackers"]["holistic"]["hands"];
+        holdMs: number;
+        predictMs: number;
+        analysisMaxDimension: number;
+        outputFaceBlendshapes: boolean;
+        delegate: XRTrackingConfig["trackers"]["holistic"]["delegate"];
+        modelUrl?: string;
+        active: boolean;
+    };
+    segmentation: {
+        quality: XRTrackingConfig["trackers"]["segmentation"]["quality"];
+        active: boolean;
+    };
+    semanticSegmentation: {
+        preset: XRTrackingConfig["trackers"]["semanticSegmentation"]["preset"];
+        quality: XRTrackingConfig["trackers"]["semanticSegmentation"]["quality"];
+        modelUrl?: string;
+        active: boolean;
+    };
+};
+/** Props for one tracker component / hook from the config (`active` mirrors `enabled`). */
+export declare const toTrackerProps: <K extends XRTrackerKind>(config: XRTrackingConfig, kind: K) => TrackerProps[K];
+/** Acquire options for `useXRModel` / `registry.acquire` per model. */
+export declare const toModelOptions: (config: XRTrackingConfig, model: XRModel) => Record<string, unknown>;
+/** The models the config enables, for capability probes and preloading. */
+export declare const enabledModels: (config: XRTrackingConfig) => XRModel[];
+export {};

package/dist/tracking-config/index.d.ts

@@ -0,0 +1,7 @@
+export type { XRTrackerKind, XRTrackingConfig, XRTrackingConfigInput, XRTrackingConfigParseResult, } from './types';
+export { DEFAULT_TRACKING_CONFIG, TRACKER_KINDS, TRACKING_CONFIG_VERSION, mergeTrackingConfig, parseTrackingConfig, resolveTrackingConfig, serializeTrackingConfig, } from './resolve';
+export { enabledModels, toCameraRequest, toModelOptions, toProviderProps, toTrackerProps, } from './apply';
+export { TRACKING_CONFIG_STORAGE_KEY, clearTrackingConfig, loadTrackingConfig, saveTrackingConfig, } from './storage';
+export type { TrackingConfigStorage } from './storage';
+export { useXRTrackingConfig } from './useXRTrackingConfig';
+export type { UseXRTrackingConfigOptions, UseXRTrackingConfigResult } from './useXRTrackingConfig';

package/dist/tracking-config/resolve.d.ts

@@ -0,0 +1,25 @@
+import { XRTrackerKind, XRTrackingConfig, XRTrackingConfigInput, XRTrackingConfigParseResult } from './types';
+export declare const TRACKING_CONFIG_VERSION: 1;
+export declare const DEFAULT_TRACKING_CONFIG: XRTrackingConfig;
+/**
+ * Validate a partial config over `base` (the defaults unless given). Every
+ * leaf is type-checked and clamped; invalid values keep the base value and
+ * add a warning. Returns a new object; never throws.
+ */
+export declare const resolveTrackingConfig: (input?: XRTrackingConfigInput, base?: XRTrackingConfig, warnings?: string[]) => XRTrackingConfig;
+/** Apply a patch over a resolved config (stamps `updatedAt`). */
+export declare const mergeTrackingConfig: (current: XRTrackingConfig, patch: XRTrackingConfigInput, now?: number) => XRTrackingConfig;
+/**
+ * Serialize for storage or transport. The config holds no runtime values by
+ * construction; this strips anything a caller may have attached and emits
+ * stable key order.
+ */
+export declare const serializeTrackingConfig: (config: XRTrackingConfig) => string;
+/**
+ * Parse a stored document of any version. Unknown or older versions are
+ * migrated field-by-field onto the current defaults (fields that still
+ * exist keep their values; the rest default) with `migrated: true`;
+ * corrupt input yields the defaults with a warning. Never throws.
+ */
+export declare const parseTrackingConfig: (raw: string | unknown) => XRTrackingConfigParseResult;
+export declare const TRACKER_KINDS: XRTrackerKind[];

package/dist/tracking-config/storage.d.ts

@@ -0,0 +1,8 @@
+import { XRTrackingConfig, XRTrackingConfigParseResult } from './types';
+export declare const TRACKING_CONFIG_STORAGE_KEY = "vincentt.xr.tracking-config";
+export type TrackingConfigStorage = Pick<Storage, "getItem" | "setItem" | "removeItem">;
+/** Read and migrate a stored config; `null` when nothing is stored or storage is unavailable. */
+export declare const loadTrackingConfig: (key?: string, storage?: TrackingConfigStorage | null) => XRTrackingConfigParseResult | null;
+/** Persist (serialized, runtime-free). Returns `false` when storage is unavailable or full. */
+export declare const saveTrackingConfig: (config: XRTrackingConfig, key?: string, storage?: TrackingConfigStorage | null) => boolean;
+export declare const clearTrackingConfig: (key?: string, storage?: TrackingConfigStorage | null) => void;