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

package/dist/useFaceInfo-Blf7FCu3.js

@@ -0,0 +1,303 @@
+import { useMemo as I, useEffect as N, useCallback as k, useRef as U } from "react";
+import { Vector2 as X, Raycaster as S, Ray as Y, Vector3 as L } from "three";
+import { D as d, a as y } from "./screenTransform-BenfCtZt.js";
+import { n as j, t as A, X as p } from "./index-CnGox6Xr.js";
+import { useThree as D } from "@react-three/fiber";
+import { g as B, u as J } from "./getFaceInfo-BkZfaQs-.js";
+import { u as V } from "./index-CsUdQ-pn.js";
+const a = (e, n) => {
+  if (!Number.isFinite(e) || e <= 0) throw new RangeError(`${n} must be positive`);
+  return e;
+}, q = (e, n) => {
+  const t = a(n.width, "root.width"), s = a(n.height, "root.height");
+  return !Number.isFinite(e.width) || !Number.isFinite(e.height) || e.width <= 0 || e.height <= 0 ? 0 : Math.min(e.width / t, e.height / s);
+}, b = (e, n, t, s) => n.width <= 0 || n.height <= 0 ? Object.assign(s, { x: 0, y: 0 }) : (a(t.width, "root.width"), a(t.height, "root.height"), s.x = (e.x / n.width - 0.5) * t.width, s.y = (0.5 - e.y / n.height) * t.height, s), P = (e, n, t, s) => n.width <= 0 || n.height <= 0 ? Object.assign(s, { x: 0, y: 0 }) : (a(t.width, "root.width"), a(t.height, "root.height"), s.x = (e.x / t.width + 0.5) * n.width, s.y = (0.5 - e.y / t.height) * n.height, s), O = ({
+  parentSize: e,
+  referencePixelsPerUnit: n = y,
+  root: t = d
+}) => q(e, t) * (y / a(n, "referencePixelsPerUnit")), re = (e, n) => e * O(n), ce = (e, n) => {
+  const t = O(n);
+  return t === 0 ? 0 : e / t;
+}, oe = ({
+  point: e,
+  parentSize: n,
+  referencePixelsPerUnit: t = y,
+  root: s = d,
+  target: i = { x: 0, y: 0 }
+}) => {
+  if (n.width <= 0 || n.height <= 0) return Object.assign(i, { x: 0, y: 0 });
+  const r = y / a(t, "referencePixelsPerUnit");
+  return i.x = e.x * (n.width / a(s.width, "root.width")) * r, i.y = e.y * (n.height / a(s.height, "root.height")) * r, i;
+}, he = ({
+  point: e,
+  parentSize: n,
+  referencePixelsPerUnit: t = y,
+  root: s = d,
+  target: i = { x: 0, y: 0 }
+}) => {
+  if (n.width <= 0 || n.height <= 0) return Object.assign(i, { x: 0, y: 0 });
+  const r = y / a(t, "referencePixelsPerUnit");
+  return i.x = e.x / (n.width / a(s.width, "root.width") * r), i.y = e.y / (n.height / a(s.height, "root.height") * r), i;
+}, xe = ({
+  point: e,
+  rect: n,
+  root: t = d,
+  target: s = { x: 0, y: 0 }
+}) => b({ x: e.x - n.left, y: e.y - n.top }, n, t, s), ae = ({
+  point: e,
+  rect: n,
+  root: t = d,
+  target: s = { x: 0, y: 0 }
+}) => (P(e, n, t, s), s.x += n.left, s.y += n.top, s), _ = ({
+  point: e,
+  root: n = d,
+  target: t = { x: 0, y: 0 },
+  viewportSize: s
+}) => b(
+  { x: e.x * s.width, y: e.y * s.height },
+  s,
+  n,
+  t
+), K = ({
+  point: e,
+  root: n = d,
+  target: t = { x: 0, y: 0 },
+  viewportSize: s
+}) => s.width <= 0 || s.height <= 0 ? Object.assign(t, { x: 0, y: 0 }) : (P(e, s, n, t), t.x /= s.width, t.y /= s.height, t), de = ({
+  point: e,
+  root: n = d,
+  target: t = { x: 0, y: 0 },
+  viewportSize: s
+}) => _({
+  point: { x: (e.x + 1) / 2, y: (1 - e.y) / 2 },
+  viewportSize: s,
+  root: n,
+  target: t
+}), le = ({
+  layout: e,
+  mirrored: n = !1,
+  point: t,
+  root: s = d,
+  target: i = { x: 0, y: 0 }
+}) => {
+  if (e.scale <= 0) return Object.assign(i, { x: 0, y: 0 });
+  const r = e.offsetX + t.x * e.scale;
+  return b(
+    {
+      x: n ? e.destination.width - r : r,
+      y: e.offsetY + t.y * e.scale
+    },
+    e.destination,
+    s,
+    i
+  );
+}, ue = ({
+  layout: e,
+  mirrored: n = !1,
+  point: t,
+  root: s = d,
+  target: i = { x: 0, y: 0 }
+}) => {
+  if (e.scale <= 0) return Object.assign(i, { x: 0, y: 0 });
+  P(t, e.destination, s, i);
+  const r = n ? e.destination.width - i.x : i.x;
+  return i.x = (r - e.offsetX) / e.scale, i.y = (i.y - e.offsetY) / e.scale, i;
+}, w = new L(), g = new X(), R = new S(), fe = ({
+  camera: e,
+  point: n,
+  root: t = d,
+  target: s = { x: 0, y: 0, depth: 0 },
+  viewportSize: i
+}) => (a(t.width, "root.width"), a(t.height, "root.height"), w.set(n.x, n.y, n.z).project(e), s.x = w.x * t.width / 2, s.y = w.y * t.height / 2, s.depth = w.z, s), ye = ({
+  camera: e,
+  point: n,
+  root: t = d,
+  target: s = new Y(),
+  viewportSize: i
+}) => (a(t.width, "root.width"), a(t.height, "root.height"), g.set(n.x * 2 / t.width, n.y * 2 / t.height), R.setFromCamera(g, e), s.copy(R.ray)), me = (e, n) => j({ x: e.x, y: e.y, z: e.z ?? 0 }, n), H = (e, n = { x: 0, y: 0 }) => {
+  const t = A(e);
+  return n.x = t.x, n.y = t.y, n.z = t.z, n;
+}, we = (e, n, t = { x: 0, y: 0 }) => (t.x = e.x * n.width, t.y = e.y * n.height, t), Te = (e, n, t = { x: 0, y: 0 }) => n.width <= 0 || n.height <= 0 ? Object.assign(t, { x: 0, y: 0 }) : (t.x = e.x / n.width, t.y = e.y / n.height, t), be = (e, n, t = {}) => _({
+  point: e,
+  viewportSize: n,
+  root: t.root,
+  target: t.target
+}), Pe = (e, n, t = {}) => {
+  const s = t.target ?? { x: 0, y: 0 };
+  return K({ point: e, viewportSize: n, root: t.root, target: s }), s;
+}, W = { selection: "index", index: 0 }, $ = Object.freeze({
+  face: { max: 10, default: 1, option: "numFaces" },
+  hand: { max: 2, default: 2, option: null },
+  gesture: { max: 1, default: 1, option: null },
+  body: { max: 1, default: 1, option: null },
+  holistic: { max: 1, default: 1, option: null }
+}), C = { center: null }, f = (e, n) => Math.hypot(e.x - n.x, e.y - n.y), M = (e, n, t) => {
+  if (!e.length) return null;
+  switch (n) {
+    case "largest":
+      return e.reduce((s, i) => i.size > s.size ? i : s);
+    case "nearest-center":
+      return e.reduce(
+        (s, i) => f(i.center, { x: 0.5, y: 0.5 }) < f(s.center, { x: 0.5, y: 0.5 }) ? i : s
+      );
+    case "leftmost":
+      return e.reduce((s, i) => i.center.x < s.center.x ? i : s);
+    case "rightmost":
+      return e.reduce((s, i) => i.center.x > s.center.x ? i : s);
+    default:
+      return e.find((s) => s.index === t) ?? null;
+  }
+}, G = (e, n = W, t = C) => {
+  const s = n.index ?? 0;
+  if (n.selection !== "sticky") {
+    const c = M(e, n.selection, s);
+    return {
+      index: (c == null ? void 0 : c.index) ?? null,
+      reason: c ? n.selection : "none",
+      memory: c ? { center: { ...c.center }, label: c.label } : t
+    };
+  }
+  const i = n.stickyRadius ?? 0.2;
+  if (t.center) {
+    const c = t.center, x = e.filter((l) => f(l.center, c) <= i).sort((l, m) => f(l.center, c) - f(m.center, c)), h = (t.label ? x.find((l) => l.label === t.label) : void 0) ?? x[0];
+    if (h)
+      return {
+        index: h.index,
+        reason: "sticky",
+        memory: { center: { ...h.center }, label: h.label }
+      };
+  }
+  const r = M(e, n.fallback ?? "largest", s);
+  return {
+    index: (r == null ? void 0 : r.index) ?? null,
+    reason: r ? "sticky-fallback" : "none",
+    // Keep the old memory on a miss so a brief dropout does not forget the subject.
+    memory: r ? { center: { ...r.center }, label: r.label } : t
+  };
+}, Fe = (e) => e.map((n, t) => {
+  let s = 1 / 0, i = -1 / 0, r = 1 / 0, c = -1 / 0;
+  for (const o of n)
+    o.x < s && (s = o.x), o.x > i && (i = o.x), o.y < r && (r = o.y), o.y > c && (c = o.y);
+  const x = n.length > 0 && Number.isFinite(s);
+  return {
+    index: t,
+    center: x ? { x: (s + i) / 2, y: (r + c) / 2 } : { x: 0.5, y: 0.5 },
+    size: x ? i - s : 0
+  };
+}), Ee = (e) => e.map((n, t) => {
+  const s = (n.coordinates ?? []).map((h) => H(h));
+  let i = 1 / 0, r = -1 / 0, c = 1 / 0, x = -1 / 0;
+  for (const h of s)
+    h.x < i && (i = h.x), h.x > r && (r = h.x), h.y < c && (c = h.y), h.y > x && (x = h.y);
+  const o = s.length > 0;
+  return {
+    index: t,
+    center: o ? { x: (i + r) / 2, y: (c + x) / 2 } : { x: 0.5, y: 0.5 },
+    size: o ? Math.max(r - i, x - c) : 0,
+    ...n.label ? { label: n.label } : {}
+  };
+}), ge = (e, n, t = 0.35) => {
+  const s = [];
+  for (const c of e)
+    for (const x of n) {
+      const o = f(c.center, x.center);
+      o <= t && s.push({ primaryIndex: c.index, secondaryIndex: x.index, distance: o });
+    }
+  s.sort((c, x) => c.distance - x.distance);
+  const i = /* @__PURE__ */ new Set(), r = /* @__PURE__ */ new Set();
+  return s.filter((c) => i.has(c.primaryIndex) || r.has(c.secondaryIndex) ? !1 : (i.add(c.primaryIndex), r.add(c.secondaryIndex), !0));
+}, Q = ({
+  active: e = !0,
+  holdMs: n = 250,
+  numFaces: t = 1,
+  targetFps: s,
+  throttleMs: i = 16
+} = {}) => {
+  const { camera: r } = D(), c = Number.isFinite(t) ? Math.min($.face.max, Math.max(1, Math.round(t))) : 1, x = s !== void 0 && Number.isFinite(s) && s > 0 ? s : void 0, o = I(
+    () => ({
+      numFaces: c,
+      ...x ? { targetFps: x } : {}
+    }),
+    [c, x]
+  ), { node: h, ready: l } = V(
+    p.FACE_TRACKER,
+    o,
+    e
+  );
+  N(() => {
+    if (h)
+      for (let u = 0; u < o.numFaces; u += 1)
+        h.setCamera(r, u);
+  }, [o.numFaces, r, h]);
+  const m = k(
+    (u) => {
+      if (!h) return [];
+      const F = [];
+      for (let T = 0; T < u.faceLandmarks.length; T += 1) {
+        const E = B(h, u, T);
+        E && F.push(E);
+      }
+      return F;
+    },
+    [h]
+  );
+  return J({
+    enabled: e && l,
+    holdMs: Number.isFinite(n) ? Math.max(0, n) : 250,
+    node: h,
+    prepare: m,
+    throttleMs: Number.isFinite(i) ? Math.max(0, i) : 16
+  });
+}, Z = 4, Re = ({
+  faceIndex: e = 0,
+  numFaces: n,
+  subject: t,
+  ...s
+} = {}) => {
+  const i = Number.isFinite(e) ? Math.max(0, Math.round(e)) : 0, r = Q({
+    ...s,
+    numFaces: Math.max(n ?? (t ? Z : i + 1), i + 1)
+  }), c = U(C), x = JSON.stringify(t ?? null), o = I(() => {
+    if (!t) return null;
+    const h = r.map((l, m) => ({
+      index: m,
+      center: { x: l.bounds.centerX, y: l.bounds.centerY },
+      size: l.bounds.width
+    }));
+    return G(h, t, c.current);
+  }, [r, x]);
+  return N(() => {
+    o && (c.current = o.memory);
+  }, [o]), t ? o && o.index !== null ? r[o.index] ?? null : null : r[i] ?? null;
+};
+export {
+  W as D,
+  C as E,
+  $ as X,
+  ge as a,
+  Z as b,
+  Re as c,
+  xe as d,
+  re as e,
+  Fe as f,
+  ae as g,
+  ue as h,
+  K as i,
+  Ee as j,
+  oe as k,
+  ye as l,
+  le as m,
+  _ as n,
+  he as o,
+  ce as p,
+  be as q,
+  me as r,
+  G as s,
+  de as t,
+  Q as u,
+  we as v,
+  fe as w,
+  Pe as x,
+  H as y,
+  Te as z
+};

package/dist/useFaceInfo-C5mO8NQY.cjs

@@ -0,0 +1 @@
+"use strict";const T=require("react"),R=require("three"),l=require("./screenTransform-BiXdpVf0.cjs"),F=require("./index-CeVkgsag.cjs"),j=require("@react-three/fiber"),w=require("./getFaceInfo-ahPxQFGu.cjs"),q=require("./index-OCPjOaeP.cjs"),h=(e,n)=>{if(!Number.isFinite(e)||e<=0)throw new RangeError(`${n} must be positive`);return e},B=(e,n)=>{const t=h(n.width,"root.width"),i=h(n.height,"root.height");return!Number.isFinite(e.width)||!Number.isFinite(e.height)||e.width<=0||e.height<=0?0:Math.min(e.width/t,e.height/i)},m=(e,n,t,i)=>n.width<=0||n.height<=0?Object.assign(i,{x:0,y:0}):(h(t.width,"root.width"),h(t.height,"root.height"),i.x=(e.x/n.width-.5)*t.width,i.y=(.5-e.y/n.height)*t.height,i),P=(e,n,t,i)=>n.width<=0||n.height<=0?Object.assign(i,{x:0,y:0}):(h(t.width,"root.width"),h(t.height,"root.height"),i.x=(e.x/t.width+.5)*n.width,i.y=(.5-e.y/t.height)*n.height,i),I=({parentSize:e,referencePixelsPerUnit:n=l.DEFAULT_REFERENCE_PIXELS_PER_UNIT,root:t=l.DEFAULT_SCREEN_TRANSFORM_ROOT})=>B(e,t)*(l.DEFAULT_REFERENCE_PIXELS_PER_UNIT/h(n,"referencePixelsPerUnit")),J=(e,n)=>e*I(n),V=(e,n)=>{const t=I(n);return t===0?0:e/t},p=({point:e,parentSize:n,referencePixelsPerUnit:t=l.DEFAULT_REFERENCE_PIXELS_PER_UNIT,root:i=l.DEFAULT_SCREEN_TRANSFORM_ROOT,target:s={x:0,y:0}})=>{if(n.width<=0||n.height<=0)return Object.assign(s,{x:0,y:0});const r=l.DEFAULT_REFERENCE_PIXELS_PER_UNIT/h(t,"referencePixelsPerUnit");return s.x=e.x*(n.width/h(i.width,"root.width"))*r,s.y=e.y*(n.height/h(i.height,"root.height"))*r,s},H=({point:e,parentSize:n,referencePixelsPerUnit:t=l.DEFAULT_REFERENCE_PIXELS_PER_UNIT,root:i=l.DEFAULT_SCREEN_TRANSFORM_ROOT,target:s={x:0,y:0}})=>{if(n.width<=0||n.height<=0)return Object.assign(s,{x:0,y:0});const r=l.DEFAULT_REFERENCE_PIXELS_PER_UNIT/h(t,"referencePixelsPerUnit");return s.x=e.x/(n.width/h(i.width,"root.width")*r),s.y=e.y/(n.height/h(i.height,"root.height")*r),s},K=({point:e,rect:n,root:t=l.DEFAULT_SCREEN_TRANSFORM_ROOT,target:i={x:0,y:0}})=>m({x:e.x-n.left,y:e.y-n.top},n,t,i),$=({point:e,rect:n,root:t=l.DEFAULT_SCREEN_TRANSFORM_ROOT,target:i={x:0,y:0}})=>(P(e,n,t,i),i.x+=n.left,i.y+=n.top,i),S=({point:e,root:n=l.DEFAULT_SCREEN_TRANSFORM_ROOT,target:t={x:0,y:0},viewportSize:i})=>m({x:e.x*i.width,y:e.y*i.height},i,n,t),L=({point:e,root:n=l.DEFAULT_SCREEN_TRANSFORM_ROOT,target:t={x:0,y:0},viewportSize:i})=>i.width<=0||i.height<=0?Object.assign(t,{x:0,y:0}):(P(e,i,n,t),t.x/=i.width,t.y/=i.height,t),W=({point:e,root:n=l.DEFAULT_SCREEN_TRANSFORM_ROOT,target:t={x:0,y:0},viewportSize:i})=>S({point:{x:(e.x+1)/2,y:(1-e.y)/2},viewportSize:i,root:n,target:t}),z=({layout:e,mirrored:n=!1,point:t,root:i=l.DEFAULT_SCREEN_TRANSFORM_ROOT,target:s={x:0,y:0}})=>{if(e.scale<=0)return Object.assign(s,{x:0,y:0});const r=e.offsetX+t.x*e.scale;return m({x:n?e.destination.width-r:r,y:e.offsetY+t.y*e.scale},e.destination,i,s)},G=({layout:e,mirrored:n=!1,point:t,root:i=l.DEFAULT_SCREEN_TRANSFORM_ROOT,target:s={x:0,y:0}})=>{if(e.scale<=0)return Object.assign(s,{x:0,y:0});P(t,e.destination,i,s);const r=n?e.destination.width-s.x:s.x;return s.x=(r-e.offsetX)/e.scale,s.y=(s.y-e.offsetY)/e.scale,s},y=new R.Vector3,C=new R.Vector2,A=new R.Raycaster,Q=({camera:e,point:n,root:t=l.DEFAULT_SCREEN_TRANSFORM_ROOT,target:i={x:0,y:0,depth:0},viewportSize:s})=>(h(t.width,"root.width"),h(t.height,"root.height"),y.set(n.x,n.y,n.z).project(e),i.x=y.x*t.width/2,i.y=y.y*t.height/2,i.depth=y.z,i),Z=({camera:e,point:n,root:t=l.DEFAULT_SCREEN_TRANSFORM_ROOT,target:i=new R.Ray,viewportSize:s})=>(h(t.width,"root.width"),h(t.height,"root.height"),C.set(n.x*2/t.width,n.y*2/t.height),A.setFromCamera(C,e),i.copy(A.ray)),v=(e,n)=>F.normalizedTrackerPointToTrackerPoint({x:e.x,y:e.y,z:e.z??0},n),b=(e,n={x:0,y:0})=>{const t=F.trackerPointToNormalizedTrackerPoint(e);return n.x=t.x,n.y=t.y,n.z=t.z,n},ee=(e,n,t={x:0,y:0})=>(t.x=e.x*n.width,t.y=e.y*n.height,t),ne=(e,n,t={x:0,y:0})=>n.width<=0||n.height<=0?Object.assign(t,{x:0,y:0}):(t.x=e.x/n.width,t.y=e.y/n.height,t),te=(e,n,t={})=>S({point:e,viewportSize:n,root:t.root,target:t.target}),ie=(e,n,t={})=>{const i=t.target??{x:0,y:0};return L({point:e,viewportSize:n,root:t.root,target:i}),i},D={selection:"index",index:0},g=Object.freeze({face:{max:10,default:1,option:"numFaces"},hand:{max:2,default:2,option:null},gesture:{max:1,default:1,option:null},body:{max:1,default:1,option:null},holistic:{max:1,default:1,option:null}}),O={center:null},f=(e,n)=>Math.hypot(e.x-n.x,e.y-n.y),M=(e,n,t)=>{if(!e.length)return null;switch(n){case"largest":return e.reduce((i,s)=>s.size>i.size?s:i);case"nearest-center":return e.reduce((i,s)=>f(s.center,{x:.5,y:.5})<f(i.center,{x:.5,y:.5})?s:i);case"leftmost":return e.reduce((i,s)=>s.center.x<i.center.x?s:i);case"rightmost":return e.reduce((i,s)=>s.center.x>i.center.x?s:i);default:return e.find(i=>i.index===t)??null}},X=(e,n=D,t=O)=>{const i=n.index??0;if(n.selection!=="sticky"){const c=M(e,n.selection,i);return{index:(c==null?void 0:c.index)??null,reason:c?n.selection:"none",memory:c?{center:{...c.center},label:c.label}:t}}const s=n.stickyRadius??.2;if(t.center){const c=t.center,d=e.filter(a=>f(a.center,c)<=s).sort((a,E)=>f(a.center,c)-f(E.center,c)),x=(t.label?d.find(a=>a.label===t.label):void 0)??d[0];if(x)return{index:x.index,reason:"sticky",memory:{center:{...x.center},label:x.label}}}const r=M(e,n.fallback??"largest",i);return{index:(r==null?void 0:r.index)??null,reason:r?"sticky-fallback":"none",memory:r?{center:{...r.center},label:r.label}:t}},se=e=>e.map((n,t)=>{let i=1/0,s=-1/0,r=1/0,c=-1/0;for(const o of n)o.x<i&&(i=o.x),o.x>s&&(s=o.x),o.y<r&&(r=o.y),o.y>c&&(c=o.y);const d=n.length>0&&Number.isFinite(i);return{index:t,center:d?{x:(i+s)/2,y:(r+c)/2}:{x:.5,y:.5},size:d?s-i:0}}),re=e=>e.map((n,t)=>{const i=(n.coordinates??[]).map(x=>b(x));let s=1/0,r=-1/0,c=1/0,d=-1/0;for(const x of i)x.x<s&&(s=x.x),x.x>r&&(r=x.x),x.y<c&&(c=x.y),x.y>d&&(d=x.y);const o=i.length>0;return{index:t,center:o?{x:(s+r)/2,y:(c+d)/2}:{x:.5,y:.5},size:o?Math.max(r-s,d-c):0,...n.label?{label:n.label}:{}}}),ce=(e,n,t=.35)=>{const i=[];for(const c of e)for(const d of n){const o=f(c.center,d.center);o<=t&&i.push({primaryIndex:c.index,secondaryIndex:d.index,distance:o})}i.sort((c,d)=>c.distance-d.distance);const s=new Set,r=new Set;return i.filter(c=>s.has(c.primaryIndex)||r.has(c.secondaryIndex)?!1:(s.add(c.primaryIndex),r.add(c.secondaryIndex),!0))},k=({active:e=!0,holdMs:n=250,numFaces:t=1,targetFps:i,throttleMs:s=16}={})=>{const{camera:r}=j.useThree(),c=Number.isFinite(t)?Math.min(g.face.max,Math.max(1,Math.round(t))):1,d=i!==void 0&&Number.isFinite(i)&&i>0?i:void 0,o=T.useMemo(()=>({numFaces:c,...d?{targetFps:d}:{}}),[c,d]),{node:x,ready:a}=q.useXRModel(F.XRModel.FACE_TRACKER,o,e);T.useEffect(()=>{if(x)for(let u=0;u<o.numFaces;u+=1)x.setCamera(r,u)},[o.numFaces,r,x]);const E=T.useCallback(u=>{if(!x)return[];const N=[];for(let _=0;_<u.faceLandmarks.length;_+=1){const U=w.getFaceInfoFromResults(x,u,_);U&&N.push(U)}return N},[x]);return w.useFaceResultReader({enabled:e&&a,holdMs:Number.isFinite(n)?Math.max(0,n):250,node:x,prepare:E,throttleMs:Number.isFinite(s)?Math.max(0,s):16})},Y=4,oe=({faceIndex:e=0,numFaces:n,subject:t,...i}={})=>{const s=Number.isFinite(e)?Math.max(0,Math.round(e)):0,r=k({...i,numFaces:Math.max(n??(t?Y:s+1),s+1)}),c=T.useRef(O),d=JSON.stringify(t??null),o=T.useMemo(()=>{if(!t)return null;const x=r.map((a,E)=>({index:E,center:{x:a.bounds.centerX,y:a.bounds.centerY},size:a.bounds.width}));return X(x,t,c.current)},[r,d]);return T.useEffect(()=>{o&&(c.current=o.memory)},[o]),t?o&&o.index!==null?r[o.index]??null:null:r[s]??null};exports.DEFAULT_POLICY_NUM_FACES=Y;exports.DEFAULT_SUBJECT_POLICY=D;exports.EMPTY_SUBJECT_MEMORY=O;exports.XR_MAX_SUBJECTS=g;exports.associateSubjects=ce;exports.clientToScreenPixels=K;exports.faceCandidates=se;exports.feedToScreenPixels=te;exports.feedToTracker=v;exports.feedToViewport=ee;exports.jointCandidates=re;exports.mediaToScreenPixels=z;exports.normalizedToScreenPixels=S;exports.screenPixelsToClient=$;exports.screenPixelsToFeed=ie;exports.screenPixelsToMedia=G;exports.screenPixelsToNormalized=L;exports.screenPixelsToScreenSpace=p;exports.screenPixelsToUnits=J;exports.screenPointToRay=Z;exports.screenSpaceToScreenPixels=H;exports.screenUnitsToPixels=V;exports.selectSubject=X;exports.trackerPointToScreenPixels=W;exports.trackerToFeed=b;exports.useFaceInfo=oe;exports.useFaceInfos=k;exports.viewportToFeed=ne;exports.worldToScreenPixels=Q;

package/dist/useXRCapabilities-B1R2ghy-.cjs

@@ -0,0 +1 @@
+"use strict";const e=require("react"),C=require("./index-CeVkgsag.cjs"),S=(s={})=>{const{enabled:c=!0,timeoutMs:i,queryPermission:l}=s,f=(s.models??[]).join("|"),a=e.useRef(s.models);a.current=s.models;const[m,b]=e.useState(null),[R,n]=e.useState("idle"),[y,o]=e.useState(null),t=e.useRef(0),u=e.useCallback(async()=>{t.current+=1;const d=t.current;n("checking");try{const r=await C.detectXRCapabilities({models:a.current,timeoutMs:i,queryPermission:l});return d!==t.current?null:(b(r),o(null),n("ready"),r)}catch(r){return d!==t.current||(o(r instanceof Error?r:new Error(String(r))),n("error")),null}},[i,l]);return e.useEffect(()=>{if(c)return u(),()=>{t.current+=1}},[c,u,f]),{capabilities:m,status:R,error:y,refresh:u}};exports.useXRCapabilities=S;

package/dist/useXRCapabilities-C68v__wB.js

@@ -0,0 +1,30 @@
+import { useRef as m, useState as u, useCallback as E, useEffect as R } from "react";
+import { d as g } from "./index-CnGox6Xr.js";
+const k = (t = {}) => {
+  const { enabled: c = !0, timeoutMs: o, queryPermission: l } = t, f = (t.models ?? []).join("|"), i = m(t.models);
+  i.current = t.models;
+  const [b, p] = u(null), [y, n] = u("idle"), [C, a] = u(null), e = m(0), s = E(async () => {
+    e.current += 1;
+    const d = e.current;
+    n("checking");
+    try {
+      const r = await g({
+        models: i.current,
+        timeoutMs: o,
+        queryPermission: l
+      });
+      return d !== e.current ? null : (p(r), a(null), n("ready"), r);
+    } catch (r) {
+      return d !== e.current || (a(r instanceof Error ? r : new Error(String(r))), n("error")), null;
+    }
+  }, [o, l]);
+  return R(() => {
+    if (c)
+      return s(), () => {
+        e.current += 1;
+      };
+  }, [c, s, f]), { capabilities: b, status: y, error: C, refresh: s };
+};
+export {
+  k as u
+};

package/dist/utils/fns.d.ts

@@ -14,11 +14,11 @@ export declare const drawImageDataCover: (canvas: HTMLCanvasElement, input: Imag
  * trackers call this once per landmark per frame (~468× for face), so the
  * allocating variant below shows up as a real GC pressure source.
  */
-export declare const unprojectToZZeroInto: ({ x, y, z }: NormalizedLandmark, camera: THREE.Camera, out: THREE.Vector3) => THREE.Vector3;
+export declare const unprojectToZZeroInto: (landmark: NormalizedLandmark, camera: THREE.Camera, out: THREE.Vector3) => THREE.Vector3;
 /**
  * Allocating wrapper kept for backwards compatibility with any
- * consumer-facing API surface. New call sites in the trackers use
- * unprojectToZZeroInto with a pre-allocated out vector.
+ * consumer-facing API surface. New call sites use `feedToWorld` from
+ * `lib/coordinates` (or `unprojectToZZeroInto` with a pre-allocated out).
  */
 export declare const unprojectToZZero: (landmark: NormalizedLandmark, camera: THREE.Camera) => THREE.Vector3;
 export declare const smoothScale: (originalScale: number, newScale: number, alpha?: number) => number;
@@ -37,7 +37,10 @@ export declare const smoothScale: (originalScale: number, newScale: number, alph
 export declare class AnalysisDownscaler {
     private readonly maxDimension;
     private canvas;
+    private scale;
     constructor(maxDimension: number);
+    /** Multiply the cap (0.25..1); the adaptive-quality tier sets it. */
+    setScale(scale: number): void;
     /**
      * Returns a downscaled copy of `source` capped to `maxDimension` on its
      * longest side (or `source` unchanged if it's already within the cap, or if a

package/dist/utils/integrity.d.ts

@@ -14,7 +14,10 @@ export declare const INTEGRITY_MANIFEST: Record<string, IntegrityHash>;
  * Consumer-owned URLs with no manifest entry pass through with a warning.
  * SDK-owned CDN URLs with no entry fail closed.
  */
-export declare function fetchAndVerify(url: string): Promise<ArrayBuffer>;
+export declare function fetchAndVerify(url: string, init?: {
+    signal?: AbortSignal;
+}): Promise<ArrayBuffer>;
+export declare function isSdkOwnedUrl(url: string): boolean;
 /**
  * fetchAndVerify variant that returns a Uint8Array view — what MediaPipe's
  * `modelAssetBuffer` expects.

package/dist/utils/updateThrottle.d.ts

@@ -0,0 +1,2 @@
+/** True when a per-frame update should be skipped to honour a `maxFps` cap. */
+export declare const shouldSkipUpdate: (elapsed: number, lastUpdate: number, maxFps: number | undefined) => boolean;

package/dist/utils/useStableUniforms.d.ts

@@ -0,0 +1,18 @@
+export type StableUniforms<T extends Record<string, unknown>> = {
+    [K in keyof T]: {
+        value: T[K];
+    };
+};
+/**
+ * Build a `ShaderMaterial` uniforms object whose entries never change identity.
+ *
+ * three.js captures `material.uniforms` once, when the program is compiled,
+ * and keeps reading that object on every draw. A uniforms object re-created
+ * on a React render (a plain literal, or a `useMemo` with dependencies) is
+ * therefore silently ignored after the first frame unless the material is
+ * re-mounted. This hook allocates each `{ value }` entry once and copies the
+ * latest values into them on every render, so prop changes reach the shader.
+ *
+ * The set of keys must be the same on every render.
+ */
+export declare const useStableUniforms: <T extends Record<string, unknown>>(values: T) => StableUniforms<T>;

package/docs/SDK_DOCUMENTATION.md

@@ -341,6 +341,7 @@ import { XRScene } from "@vincentt-xr/sdk";
 - media source selection
 - cover/contain fitting
 - mirror state
+- a shared media composition canvas for display, tracker input, and DOM capture
 - DOM overlay composition
 - optional scene adapter mounting
 
@@ -360,6 +361,8 @@ Modes:
 Media strategies:
 
 - `internal` — viewport owns webcam/image/video and tracking preview lifecycle
+- `internal` media reuses its composed canvas for session tracker input and
+  `session.captureFrame()` / `session.captureStream()` when no XRScene is mounted
 - `external` — legacy session/media owner stays in control while viewport provides responsive scene/overlay composition
 
 Core props:

package/docs/api/adaptive-quality.mdx

@@ -0,0 +1,104 @@
+---
+title: "Adaptive Quality & Performance Budget"
+description: "An opt-out performance budget that measures frame time, inference time, memory and device signals, then steps tracker fps, analysis resolution, render pixel ratio and camera resolution between declared tiers; bounded, observable, reversible."
+sidebarTitle: "Adaptive Quality"
+icon: "gauge"
+---
+
+Phones differ by an order of magnitude and heat up over a session. Instead
+of hand-tuning `perf.targetFps`, declare quality tiers and a budget; the
+controller moves between the tiers and tells you why.
+
+```tsx
+import { XRProvider, useXRQuality } from "@vincentt-xr/sdk";
+
+// On by default. Customise, pin, or turn it off:
+<XRProvider quality={{ budget: { maxFrameMs: 33 }, minTier: "medium" }}>…</XRProvider>;
+<XRProvider quality={{ adaptive: false, initialTier: "medium" }}>…</XRProvider>;
+<XRProvider quality={false}>…</XRProvider>;
+
+const { tier, decision, signals, setTier, lock, unlock, reset } = useXRQuality();
+```
+
+## Tiers and budget (serializable)
+
+```ts
+const DEFAULT_QUALITY_TIERS = [
+  { name: "high", targetFps: 30, renderScale: 1, analysisScale: 1, camRes: 960 },
+  { name: "medium", targetFps: 24, renderScale: 0.8, analysisScale: 0.85, camRes: 720 },
+  { name: "low", targetFps: 15, renderScale: 0.6, analysisScale: 0.7, camRes: 640 },
+];
+const DEFAULT_PERFORMANCE_BUDGET = {
+  maxFrameMs: 1000 / 24,
+  maxInferenceMs: 24,
+  maxMemoryMb: null,
+  sampleMs: 1000,
+  downgradeAfter: 2,
+  upgradeAfter: 6,
+  upgradeHeadroom: 0.75,
+  cooldownMs: 4000,
+};
+```
+
+Tiers are ordered best → worst; every knob is optional. `resolveQualityConfig`
+validates a partial config (clamps scales to 0.25..1, drops invalid knobs,
+resolves `initialTier` / `minTier` / `maxTier` by index or name), and the
+result is plain JSON you can persist.
+
+## Knobs and ownership
+
+| Knob            | Owner                                                               | Applied how                                                    |
+| --------------- | ------------------------------------------------------------------- | -------------------------------------------------------------- |
+| `targetFps`     | session perf config → every tracker without its own `targetFps`     | `_setPerf` re-runs the models; immediate                       |
+| `analysisScale` | session perf config → every model's analysis downscaler             | immediate (next inference)                                     |
+| `renderScale`   | `<XRScene>` pixel ratio: `min(devicePixelRatio, cap) × renderScale` | immediate; `cap` is the `dpr` ceiling (3 or `canvasProps.dpr`) |
+| `camRes`        | session perf config, **only with `rebindCamera: true`**             | re-opens the webcam once when the tier changes                 |
+
+A per-tracker `targetFps` prop still beats the tier. The app's own `perf`
+is the base the tiers are merged over, and it is restored when the
+controller unmounts.
+
+## Behaviour
+
+- **Sample** every `sampleMs`: mean main-thread frame time (window RAF),
+  fps, total tracker inference (`inferenceMsTotal` from diagnostics), feed
+  fps, JS heap (`performance.memory` where it exists), `deviceMemory`,
+  `hardwareConcurrency`, thermal. Hidden tabs are never judged.
+- **Judge** most severe first: thermal `critical` → memory over
+  `maxMemoryMb` → inference over `maxInferenceMs` → frame time over
+  `maxFrameMs`.
+- **Step down** after `downgradeAfter` consecutive bad samples, at most once
+  per `cooldownMs`, never below `minTier`. At the floor and still over
+  budget on frame time, `signals.thermal` becomes `"suspected"` so the app
+  can shed content; nothing else changes.
+- **Step up** after `upgradeAfter` consecutive good samples (frame time and
+  inference under `budget × upgradeHeadroom`), never above `maxTier`.
+- **Initial tier**: `initialTier` if set, else one step down from the top on
+  devices with ≤ 4 GB or ≤ 4 cores.
+- **Manual**: `setTier()` (controller may move again after the cooldown),
+  `lock()` / `unlock()`, `reset()`. Every change is a decision with a
+  `reason` (`init`, `frame-time`, `inference`, `memory`, `thermal`,
+  `recovered`, `manual`, `locked`, `reset`) kept in `history`.
+- **Unsupported signals degrade gracefully**: no `performance.memory` →
+  `memoryMb: null` and memory is ignored; no thermal API in browsers →
+  `thermal: "unknown"` unless the host passes one to
+  `<XRQualityController thermal=…>`.
+
+The state is published to the session store (`useXRQualityState()` in
+low-level) and shows in `useXRDiagnostics().quality` and the
+`XRDiagnosticsPanel`. The pure stepping functions (`stepQualityController`,
+`judgeSample`, …) are exported from `/low-level` for tests and custom
+controllers.
+
+## Manual validation
+
+Run `/adaptive-quality` (budget tightened: 2 bad samples, 3 s cooldown):
+
+| Case        | Steps                       | Expect                                                            |
+| ----------- | --------------------------- | ----------------------------------------------------------------- |
+| Baseline    | load with a video source    | tier `high` (or `medium` on a weak device), `init`                |
+| Load        | simulated load 60 ms        | within ~3 s `medium` (`frame-time`), then `low`                   |
+| Recover     | load 0                      | after ~4 good samples back to `medium`, then `high` (`recovered`) |
+| Lock        | lock, load 60               | stays put                                                         |
+| Manual      | pick `low`                  | tier `low` (`manual`), diagnostics panel shows it                 |
+| Pixel ratio | pick `low` on a DPR-3 phone | scene renders softer (0.6×)                                       |

package/docs/api/asset-lifecycle.mdx

@@ -0,0 +1,78 @@
+---
+title: "Asset Lifecycle & GPU Memory"
+description: "Preload, cache, reference-count, de-duplicate, dispose and budget textures, GLB models and video with the SDK's own three.js loaders; observe usage and eviction."
+sidebarTitle: "Asset Lifecycle"
+icon: "memory"
+---
+
+GPU memory grows when the same texture is loaded twice, when a route change
+leaves a model behind, or when nobody owns disposal. The asset cache gives
+every asset one identity, one load, one owner list and one disposal.
+
+```tsx
+import {
+  XRAssetCacheProvider,
+  defineGltfAsset,
+  defineTextureAsset,
+  useXRAsset,
+  useXRAssetStats,
+} from "@vincentt-xr/sdk";
+
+const HAT = defineGltfAsset("https://cdn.example.com/hat.glb");
+const LOGO = defineTextureAsset("https://cdn.example.com/logo.png");
+
+const Hat = () => {
+  const { value, status } = useXRAsset(HAT); // shared with every other <Hat>
+  return value ? <primitive object={value.scene} /> : null;
+};
+
+<XRAssetCacheProvider>
+  {" "}
+  {/* optional: scopes a cache; releases unreferenced assets on unmount */}
+  <Hat />
+  <Hat /> {/* second mount: cache hit, same scene object */}
+</XRAssetCacheProvider>;
+```
+
+## Model
+
+- **Definition** `XRAssetDefinition<T> = { key, load(signal), dispose?(value), bytes?(value) }`. `key` is the identity; `defineTextureAsset`, `defineGltfAsset` and `defineVideoAsset` build one over three's loaders (no drei); SDK-CDN URLs go through the verifying fetch (fail closed without a pinned hash), consumer URLs are fetched plainly. Loads honour the abort signal, and a decode or parse that finishes after a release is disposed, not leaked. Write your own for anything else (audio buffers, JSON, fonts).
+- **Acquire / release** `cache.acquire(asset, ownerId)` returns the shared value (in-flight loads are shared too); `cache.release(key, ownerId)` drops that owner. Owners are ids, so a re-render or a StrictMode double mount never double-counts. `useXRAsset` does both for a component.
+- **Unreferenced values stay cached** until the budget needs room, `disposeUnreferenced()` or `disposeAll()`. A value nobody wanted by the time its load finished is disposed at once; releasing during a load aborts it.
+- **Budget** `createAssetCache({ budgetBytes })` (default 256 MiB, `Infinity` disables). Above it, unreferenced values are disposed least-recently-used first; referenced values are never evicted, so `overBudget` can stay true while everything is in use. `setBudget` applies immediately; `evict(bytes)` forces room.
+- **Bytes** come from `bytes(value)`: `estimateTextureBytes` (RGBA × mip chain), `estimateGeometryBytes`, `estimateObjectBytes` (geometries and textures reachable from a scene, each once). They are estimates of resident GPU memory; the browser exposes no exact figure.
+- **Disposal is exactly once**: `dispose(value)` runs once per loaded value, on eviction, `disposeUnreferenced`, `disposeAll` or a too-late load. `disposeObject3D` releases every geometry, material and texture under an object.
+- **Errors** are recorded on the entry (`status: "error"`); the next acquire retries.
+
+## Observability
+
+`useXRAssetStats()` (or `cache.getStats()`) reports `assets`,
+`referencedAssets`, `loadingAssets`, `erroredAssets`, `usageBytes`,
+`reclaimableBytes`, `budgetBytes`, `overBudget`, `evictions`, `hits` and
+`misses`; `cache.list()` gives every entry with its status, bytes and owner
+count; `cache.subscribe(listener)` fires on every change.
+
+## Route changes and session shutdown
+
+Owners release on unmount, so navigating away drops every reference held by
+the page. `<XRAssetCacheProvider>` then calls `disposeUnreferenced()` as it
+unmounts (`disposeUnreferencedOnUnmount`, default `true`), so a page-scoped
+cache leaves nothing behind; the app-wide default cache (no provider) keeps
+unreferenced values for the next page until the budget says otherwise. For
+a hard shutdown call `cache.disposeAll()`. Tracker-owned resources (the
+MediaPipe models, the camera texture, segmentation masks) are managed by the
+session registry, released once when the provider unmounts; the asset cache
+covers everything the app loads on top.
+
+## Manual validation
+
+Run `/asset-lifecycle` (a 24 MB page-scoped cache):
+
+| Case         | Steps                               | Expect                                                             |
+| ------------ | ----------------------------------- | ------------------------------------------------------------------ |
+| Dedupe       | mount texture 1 twice (remount)     | `hits` rises, one entry                                            |
+| Release      | unmount a texture                   | entry stays with 0 owners, `reclaimable` grows                     |
+| Budget       | lower the budget slider             | unreferenced entries disappear oldest first, `evictions` counts up |
+| Referenced   | budget below usage with all mounted | `OVER` shown, nothing evicted                                      |
+| Preload      | "preload texture 4"                 | entry `ready` with 0 owners; mounting it is a hit                  |
+| Route change | navigate away and back              | entries empty on return (provider disposed the unreferenced ones)  |