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

package/dist/{index-ByoNj0QP.js → uv-DJU_XfmN.js}

@@ -1,61 +1,13 @@
-import { jsx as _, jsxs as w } from "react/jsx-runtime";
-import { useThree as k, useFrame as U } from "@react-three/fiber";
-import z, { useId as B, useState as W, useRef as A, useEffect as F, useSyncExternalStore as q, useMemo as v, useContext as G, createContext as J, useCallback as Q } from "react";
-import { u as $, a as e0, X as P, b as t0 } from "./index-9dlAQAhy.js";
-import { R as n0 } from "./renderLayers-zrK2pv5O.js";
-import * as T from "three";
-function r0(e) {
-  return JSON.stringify(e ?? {});
-}
-function j(e, t, r = !0) {
-  const { session: n } = $(), s = B(), [i, f] = W(null), u = r0(t), o = A(t);
-  o.current = t, F(() => {
-    let c = !1;
-    return f(null), n.registry.acquire(e, s, o.current).catch((l) => {
-      c || f(l instanceof Error ? l : new Error(String(l)));
-    }), () => {
-      c = !0, n.registry.release(e, s);
-    };
-  }, [n, e, s, u]), F(() => {
-    n.registry.setActive(e, s, r);
-  }, [n, e, s, r]);
-  const d = n.store, h = q(
-    (c) => d.subscribe(c),
-    () => d.getSnapshot().pipeline.get(e) ?? null,
-    () => null
-  ), p = v(() => h ? h.getModelNode() : null, [h]);
-  return {
-    ready: h !== null && i === null,
-    node: p,
-    error: i
-  };
-}
-const s0 = ({ materialProps: e, settings: t }) => t.type === "basic" ? /* @__PURE__ */ _("meshBasicMaterial", { ...e }) : /* @__PURE__ */ _(
-  "meshStandardMaterial",
-  {
-    ...e,
-    roughness: t.roughness,
-    metalness: t.metalness
-  }
-), g = 1e-6, o0 = (e) => {
-  const { x: t, y: r, z: n } = e.scale;
-  return Math.abs(t - r) <= g && Math.abs(t - n) <= g ? t : 1;
-}, R0 = (e, t, r, n) => {
-  if (!r.enabled) return e;
-  const s = o0(r);
-  return n.x = t.x + (e.x - t.x) * s + r.position.x, n.y = t.y + (e.y - t.y) * s - r.position.y, n.z = t.z + (e.z - t.z) * s + r.position.z, n;
-}, c0 = (e, t, r) => e0(e, t, r), b0 = (e, t, r) => {
-  const n = (e.x - 0.5) * 2, s = (0.5 - e.y) * 2, i = T.MathUtils.clamp(e.z * 2, -1, 1);
-  return r.set(n, s, i).unproject(t);
-}, i0 = (e, t, r, n, s, i) => {
-  const f = Math.min(t, e.length);
-  for (let u = 0; u < f; u++) {
-    s(e[u], n, i);
-    const o = u * 3;
-    r[o] = i.x, r[o + 1] = i.y, r[o + 2] = i.z;
-  }
-  return f;
-}, a0 = [
+const E = {
+  /** Camera background and segmentation mask. `depthTest` disabled. */
+  BACKGROUND: -1e3,
+  /** Free world-space content. `depthTest` enabled. */
+  WORLD: 0,
+  /** Descendants of `FaceTracker` / `HandTracker` / `BodyTracker`. `depthTest` enabled. */
+  TRACKED: 100,
+  /** Descendants of `ScreenSpaceUI`. `depthTest` disabled. */
+  SCREEN_UI: 1e3
+}, R = [
   [127, 34, 139],
   [11, 0, 37],
   [232, 231, 120],
@@ -909,7 +861,7 @@ const s0 = ({ materialProps: e, settings: t }) => t.type === "basic" ? /* @__PUR
   [390, 339, 249],
   [339, 448, 255],
   [255, 339, 448]
-].flat(), u0 = [
+].flat(), s = [
   0.5104879319667817,
   0.33515610277652746,
   0.5174233198165894,
@@ -1866,193 +1818,9 @@ const s0 = ({ materialProps: e, settings: t }) => t.type === "basic" ? /* @__PUR
   0.618020570576191,
   0.33353258967399596,
   0.5936576622724534
-], H = 468, l0 = H * 3, f0 = {
-  type: "standard",
-  color: "#ffffff",
-  opacity: 1,
-  wireframe: !1,
-  roughness: 1,
-  metalness: 0
-}, K = ({
-  material: e,
-  faceIndex: t = 0,
-  numFaces: r,
-  visible: n = !0,
-  children: s
-}) => {
-  const { ready: i, node: f } = j(
-    P.FACE_TRACKER,
-    r === void 0 ? void 0 : { numFaces: r }
-  ), { camera: u } = k(), o = A(null), d = A(null), h = A(null), p = A(null), c = A(null), l = A(new T.Vector3()), E = v(() => {
-    const m = new Uint16Array(a0), x = new T.BufferAttribute(m, 1), y = new T.Float32BufferAttribute(u0, 2), R = new Float32Array(l0), a = new T.Float32BufferAttribute(R, 3);
-    return a.setUsage(T.DynamicDrawUsage), { indexAttr: x, uvAttr: y, positionAttr: a, positions: R };
-  }, []);
-  F(() => {
-    p.current = E.indexAttr, c.current = E.uvAttr, h.current = E.positionAttr, d.current = E.positions;
-    const m = o.current;
-    if (m) {
-      const x = m.geometry;
-      x.setAttribute("position", E.positionAttr), x.setAttribute("uv", E.uvAttr), x.setIndex(E.indexAttr);
-    }
-    return () => {
-      p.current = null, c.current = null, h.current = null, d.current = null;
-    };
-  }, [E]), U(() => {
-    var M;
-    if (!i || !f || !o.current) return;
-    const { detectionResults: m } = f, x = (M = m == null ? void 0 : m.faceLandmarks) == null ? void 0 : M[t], y = o.current.geometry, R = d.current, a = h.current;
-    if (!x || x.length === 0 || !R || !a) {
-      y.drawRange.count !== 0 && y.setDrawRange(0, 0);
-      return;
-    }
-    y.getAttribute("position") !== a && (y.setAttribute("position", a), y.setAttribute("uv", c.current), y.setIndex(p.current)), y.drawRange.count === 0 && y.setDrawRange(0, 1 / 0), i0(
-      x,
-      H,
-      R,
-      u,
-      c0,
-      l.current
-    ), a.needsUpdate = !0, y.computeVertexNormals();
-  });
-  const S = s != null && s !== !1;
-  return /* @__PURE__ */ w("mesh", { material: e, ref: o, visible: n, children: [
-    /* @__PURE__ */ _("bufferGeometry", {}),
-    !e && !S && /* @__PURE__ */ _(
-      s0,
-      {
-        settings: f0,
-        materialProps: {
-          attach: "material",
-          transparent: !0,
-          depthWrite: !1,
-          side: T.DoubleSide,
-          needsUpdate: !0
-        }
-      }
-    ),
-    !e && S ? s : null
-  ] });
-};
-K.displayName = "FaceMesh";
-const L = {
-  "face.forehead": 10,
-  "face.noseTip": 1,
-  "face.chin": 152,
-  "face.leftEyeOuter": 263,
-  "face.rightEyeOuter": 33,
-  "face.leftCheek": 425,
-  "face.rightCheek": 205,
-  "face.mouthCenter": 13,
-  "face.leftEarlobe": 454,
-  "face.rightEarlobe": 234
-}, y0 = {
-  "face.center": [10, 152, 234, 454],
-  "face.leftEye": [263, 362, 387, 373],
-  "face.rightEye": [33, 133, 158, 145]
-}, V = (e, t = 0) => Number.isFinite(e) ? e : t, D = (e) => Math.max(-1, Math.min(1, V(e))), d0 = { x: 0, y: 0, z: 0 }, h0 = (e, t, r = d0, n = { x: 0, y: 0, z: 0, visibility: 0 }) => {
-  const s = L[e];
-  if (s !== void 0) {
-    const c = t[s];
-    return c ? Object.assign(n, c) : null;
-  }
-  const i = y0[e];
-  if (i) {
-    n.x = 0, n.y = 0, n.z = 0;
-    for (const c of i) {
-      const l = t[c];
-      if (!l) return null;
-      n.x += l.x, n.y += l.y, n.z += l.z;
-    }
-    return n.x /= i.length, n.y /= i.length, n.z /= i.length, n.visibility = 1, n;
-  }
-  if (e !== "face.custom" || t.length === 0) return null;
-  let f = 1 / 0, u = 1 / 0, o = -1 / 0, d = -1 / 0, h = 0;
-  for (const c of t)
-    f = Math.min(f, c.x), u = Math.min(u, c.y), o = Math.max(o, c.x), d = Math.max(d, c.y), h += c.z;
-  const p = o - f;
-  return n.x = (f + o) * 0.5 - D(r.x) * p * 0.5, n.y = (u + d) * 0.5 - D(r.y) * (d - u) * 0.5, n.z = h / t.length - V(r.z) * p, n.visibility = 1, n;
-}, T0 = {
-  left: L["face.leftEyeOuter"],
-  right: L["face.rightEyeOuter"]
-}, X = J(null), _0 = () => G(X), p0 = ({
-  faceIndex: e = 0,
-  numFaces: t,
-  scaleWithFace: r = !1,
-  followFaceRoll: n = !0,
-  targetFps: s,
-  active: i = !0,
-  children: f
-}) => {
-  const u = A(!1), o = A(null), d = v(() => {
-    if (!(t === void 0 && s === void 0))
-      return {
-        ...t === void 0 ? {} : { numFaces: t },
-        ...s === void 0 ? {} : { targetFps: s }
-      };
-  }, [t, s]), { ready: h, node: p } = j(
-    P.FACE_TRACKER,
-    d,
-    i
-  ), { camera: c } = k(), l = A(c);
-  l.current !== c && (l.current = c, u.current = !1);
-  const E = A(null), S = A({ x: 0, y: 0, z: 0, visibility: 0 });
-  U(() => {
-    if (!h || !p || !o.current) return;
-    E.current = p, !u.current && l.current && (p.setCamera(l.current, e), u.current = !0);
-    const a = p.getFace(e);
-    if (!a) {
-      o.current.visible = !1;
-      return;
-    }
-    o.current.visible = !0;
-    const { position: M, rotation: C, scale: b } = a.transform;
-    o.current.position.set(M.x, M.y, M.z), o.current.rotation.set(C.x, C.y, n ? C.z : 0), r ? o.current.scale.set(b.x, b.y, b.z) : o.current.scale.set(1, 1, 1);
-  });
-  const m = Q(
-    (a, M) => {
-      var O, I;
-      const C = E.current, b = (I = (O = C == null ? void 0 : C.detectionResults) == null ? void 0 : O.faceLandmarks) == null ? void 0 : I[e];
-      if (!b || b.length === 0) return null;
-      const N = h0(
-        a,
-        b,
-        M,
-        S.current
-      );
-      return N ? { position: t0(N, l.current) } : null;
-    },
-    [e]
-  ), x = v(
-    () => ({ type: "face", resolveLandmark: m }),
-    [m]
-  );
-  let y;
-  const R = [];
-  return z.Children.forEach(f, (a) => {
-    var M, C;
-    z.isValidElement(a) && // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    (((M = a.type) == null ? void 0 : M.displayName) === "FaceTracker.Mesh" || // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    ((C = a.type) == null ? void 0 : C.displayName) === "FaceMesh") ? y = z.cloneElement(a, { faceIndex: e, numFaces: t }) : R.push(a);
-  }), /* @__PURE__ */ w(X.Provider, { value: x, children: [
-    /* @__PURE__ */ _("group", { ref: o, renderOrder: n0.TRACKED, children: R }),
-    y
-  ] });
-}, Z = (e) => /* @__PURE__ */ _(K, { ...e });
-Z.displayName = "FaceTracker.Mesh";
-const Y = p0;
-Y.Mesh = Z;
-const S0 = Y;
+];
 export {
-  T0 as F,
-  S0 as H,
-  s0 as M,
-  X as T,
-  _0 as a,
-  Y as b,
-  K as c,
-  L as d,
-  b0 as p,
-  h0 as r,
-  R0 as t,
-  j as u
+  R as F,
+  E as R,
+  s as a
 };

package/docs/SDK_DOCUMENTATION.md

@@ -31,10 +31,9 @@ The XR SDK (`@vincentt-xr/sdk`) is a WebAR SDK that provides AI-powered tracking
 Source of truth: `example/src/navigation/routes.tsx`. This list is a readable summary only.
 
 - `/unified-architecture`: debug-ui scene editor composition for face tracking
-- `/testing-hook`: multi-face face-mesh sanity example
+- `/face-mesh?faces=two`: multi-face face-mesh sanity example
 - `/body`: visible body-tracking anchors
 - `/debugger`: debugger overlay and metrics example
-- `/viewport-editor`: reusable 3D scene editor fixture
 - `/face-retouch-legacy`: legacy face-retouch shader settings example
 
 ## Installation

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 `/session-health`, quality section (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)  |