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

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/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)  |

package/docs/api/camera-permission.mdx

@@ -0,0 +1,142 @@
+---
+title: "Camera Permission & Privacy"
+description: "Distinguish unknown, requesting, granted, denied, blocked and unavailable camera states; request, retry and recover without remounting; release the camera cleanly; keep every frame on the device until the viewer allows access."
+sidebarTitle: "Camera Permission"
+icon: "camera"
+---
+
+Camera access is the first thing that can go wrong in an AR experience, and
+the browser's `NotAllowedError` hides four different situations. The SDK
+splits them into states a creator can act on, offers the request flow as a
+hook and a gate component, and guarantees no camera frame is processed
+before explicit, usable access.
+
+## States
+
+| State         | Meaning                                                                              | Next step                                                 |
+| ------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------- |
+| `unknown`     | Never asked (the next request prompts), or the browser cannot say.                   | Show a primer and a request button.                       |
+| `requesting`  | A prompt is open.                                                                    | Wait.                                                     |
+| `granted`     | Usable.                                                                              | Mount the session.                                        |
+| `denied`      | This prompt was declined or dismissed; the next request prompts again.               | Offer "try again".                                        |
+| `blocked`     | Persistently denied in the site settings; a request fails without a prompt.          | Explain how to change the setting.                        |
+| `unavailable` | No camera, insecure context, unsupported browser, or held by another app (`reason`). | Fall back; `reason.recoverable` says if a retry can help. |
+
+`denied` and `blocked` are told apart by reading the Permissions API _after_
+the failed request: `denied` there means blocked. `reason` is an
+`XRFallbackReason` (`camera-permission-denied`, `camera-in-use`,
+`no-camera`, `camera-insecure-context`, `camera-unsupported`, `camera-lost`).
+
+## Before the session: the gate
+
+```tsx
+import { CameraPermissionGate, useCameraPermission } from "@vincentt-xr/sdk";
+
+// Component form: children render only while access is granted.
+<CameraPermissionGate
+  fallback={({ state, reason, canPrompt, request }) => (
+    <Primer state={state} reason={reason} onAllow={canPrompt ? () => request() : undefined} />
+  )}
+>
+  <XRProvider>
+    <Experience />
+  </XRProvider>
+</CameraPermissionGate>;
+
+// Hook form, for your own layout.
+const { state, reason, canPrompt, usable, request, refresh } = useCameraPermission();
+```
+
+Neither needs an `<XRProvider>`. On mount they only _query_ the permission
+(no prompt); `request()` prompts, and must run from a user gesture (a
+button) as browsers require. The probe stream is stopped at once, so the
+camera indicator goes off again and nothing is captured: the call only
+moves the permission. Pass `auto` to prompt on mount. Both follow the
+site-setting changes through the Permissions API, so a viewer who allows
+the camera in the address bar flips the gate without a reload.
+
+The built-in fallback of `<CameraPermissionGate>` announces state changes
+with `aria-live="polite"`, keeps the request behind a real `<button>`,
+disables it when a prompt cannot help, and labels the region "Camera access".
+Keep those in a custom fallback: a visible button, `aria-live` on the
+status text, `aria-disabled` when blocked, and the explanation for
+`blocked` next to the button rather than in a toast.
+
+## Inside the session
+
+The session reports its own live state through `useXRSessionCameraPermission()`
+(`@vincentt-xr/sdk/low-level`): `requesting` while its webcam
+`getUserMedia` is pending, `granted` once bound, the classified failure
+otherwise, and `blocked` / `unavailable` after a mid-session revoke or a
+lost camera. Stream and canvas sources leave it `unknown`.
+
+```tsx
+const { state, reason } = useXRSessionCameraPermission();
+```
+
+### Request, retry, recover without remounting
+
+```tsx
+const { session } = useXRContext();
+const retry = async () => {
+  await session.setMediaSource({ source: XRMediaSource.WEBCAM }); // prompts again if allowed
+  await session.start();
+};
+```
+
+A failed bind leaves the session where it was (`idle` stays idle, a running
+session keeps its old source), so the same provider, models and scene are
+reused. A revoke mid-session stops the session with a `camera-lost` /
+`permission-denied` error; the same two calls recover it.
+
+### Privacy: releasing the camera
+
+- `session.stop()` stops every media track: the browser's camera indicator
+  goes off and no frame is read. Models stay initialized, so a later
+  `setMediaSource` + `start` is fast. Use this for an in-app "privacy mode".
+- A revoke (`permission-denied`) or a lost device (`camera-lost`) releases
+  the tracks once and suspends every model automatically.
+- No model runs before `session.start()`, and `start()` needs a bound
+  source, so no camera data is processed before explicit access. The gate
+  adds the second guarantee: the session is not even mounted until
+  `granted`.
+- Frames never leave the device: inference runs in the page, and the only
+  network traffic is the one-time model and engine download.
+
+## Choosing the camera
+
+`setMediaSource({ source: XRMediaSource.WEBCAM, facingMode: "environment" })`
+opens the rear camera; `"user"` (default) the front one; `deviceId` picks a
+specific camera from `enumerateDevices()`. Binding again with a different
+facing swaps the camera mid-session. The front camera is mirrored
+(`sourceKind` `"webcam"`), the rear camera is drawn straight (`sourceKind`
+`"rear-camera"`), and `mirrored: true | false` overrides that for a camera
+whose facing is unknown. Trackers and the coordinate toolkit follow the
+source kind, so content stays aligned either way. `useXRCameraFacing()`
+(low-level) reports the bound facing. The full cross-camera and orientation
+contract lands with the next sprint item.
+
+## Low-level helpers
+
+`queryCameraPermission()`, `requestCameraAccess({ keepStream, constraints })`,
+`subscribeCameraPermission(listener)` and `canPromptForCamera(state)` are
+plain functions (core door) for non-React code; `CAMERA_PERMISSION_MESSAGES`
+holds the default copy per state. `classifyCameraFailure(reason,
+permissionState)` and `mapDomExceptionToReason(err)` live in `/low-level`
+next to `XRErrorReason`, for callers that classify their own
+`getUserMedia` failure.
+
+## Manual validation
+
+Run `/camera-permission`:
+
+| Case         | Steps                                     | Expect                                                            |
+| ------------ | ----------------------------------------- | ----------------------------------------------------------------- |
+| First visit  | load                                      | gate `unknown`, no prompt until "Allow camera"                    |
+| Allow        | click Allow, accept                       | `requesting` → `granted`; the experience mounts and binds         |
+| Dismiss      | click Allow, close the prompt             | `denied`, "Try again" enabled                                     |
+| Block        | deny with "never" / site setting          | `blocked`, button disabled, settings hint shown                   |
+| Unblock      | allow in the address bar                  | gate flips to `granted` without reload                            |
+| Revoke       | "simulate revoke" (or revoke in settings) | session `blocked` / `unavailable`, lifecycle `stopped`            |
+| Recover      | "retry camera"                            | prompt if needed, lifecycle `running`                             |
+| Privacy mode | "privacy mode (stop camera)"              | camera indicator off, lifecycle `stopped`; "retry camera" resumes |

package/docs/api/coordinate-spaces.mdx

@@ -0,0 +1,165 @@
+---
+title: "Coordinate Spaces"
+description: "One toolkit for source, feed, tracker, viewport, screen and world coordinates: cover crop, zoom, mirroring, orientation, and documented conversions."
+sidebarTitle: "Coordinate Spaces"
+icon: "arrows-to-dot"
+---
+
+Every tracking consumer meets the same six spaces. Import the conversions from
+`@vincentt-xr/sdk`; each one performs its origin, axis, crop and mirror change
+exactly once, so never chain a manual flip or crop after it.
+
+## The spaces
+
+```
+ source (media px)         feed (0..1)                 viewport (CSS px)
+ ┌──────────────────┐      ┌────────┐                  ┌────────┐
+ │ raw video/image  │ cover│        │  identity        │        │
+ │ 1280 × 720       │ crop │ 720 ×  │  per axis        │ 390 ×  │
+ │ never mirrored   │──────▶ 1280   │◀────────────────▶│ 844    │
+ └──────────────────┘ zoom │ webcam │                  │        │
+                     mirror│ mirror │                  └────────┘
+                           └───┬────┘                       │
+                               │ x·2−1, 1−y·2                │ design canvas
+                               ▼                             ▼
+                           tracker (−1..1, Y up)        screen (720×1280 design px, Y up)
+                               │
+                               │ camera ray → z = 0 plane
+                               ▼
+                           world (three.js)
+```
+
+| Space        | Origin / axes                                  | Who produces it                                                |
+| ------------ | ---------------------------------------------- | -------------------------------------------------------------- |
+| **source**   | top-left, Y down, media pixels, never mirrored | the `<video>` / `<img>` the session was given                  |
+| **feed**     | top-left, Y down, 0..1                         | the camera texture; every landmark and SDK mask                |
+| **tracker**  | center, X right, Y up, Z toward the viewer     | hand, body, holistic nodes (`TrackerPoint`)                    |
+| **viewport** | top-left, Y down, CSS pixels                   | the rendered canvas, pointer events via `clientToScreenPixels` |
+| **screen**   | center, Y up, 720×1280 design pixels           | `ScreenSpaceUI`, `ScreenImage`, labels                         |
+| **world**    | three.js world; tracked content on z = 0       | `TrackingAnchor`, face mesh, iris quads                        |
+
+The feed is the source **cover-cropped to the render size**, enlarged by
+`perf.cameraZoom` (default 1.2) about the centre, and **mirrored for the
+webcam only**. Image and video sources are drawn straight. Because the feed
+fills the viewport, feed and viewport agree per axis; a landmark at feed
+(0.5, 0.5) is the middle of the canvas on every aspect ratio.
+
+## The feed crop, once
+
+`FeedCrop` is the single description of source → feed. The session's blit
+loop draws with it, `computeMaskUvTransform` fits source-space masks with it,
+and the point conversions use it, so what the trackers saw and what you
+compute agree.
+
+```ts
+import { computeFeedCrop, feedToSource, sourceToFeed } from "@vincentt-xr/sdk";
+import { useXRFeedCrop } from "@vincentt-xr/sdk/low-level";
+
+// Inside the provider: the live crop (null until media is bound).
+const crop = useXRFeedCrop();
+
+// Or build one yourself for an offline pipeline.
+const offline = computeFeedCrop({
+  source: { width: 1280, height: 720 },
+  feed: { width: 720, height: 1280 },
+  zoom: 1.2,
+  mirrored: true, // webcam
+});
+
+// A landmark back onto the raw frame (for a crop, a server call, an overlay on the <video>).
+const px = feedToSource({ x: 0.62, y: 0.4 }, crop); // { x, y } in source pixels
+// A detection made on the raw frame into landmark space.
+const fp = sourceToFeed({ x: 800, y: 300 }, crop); // { x, y } in 0..1
+```
+
+`feedToSource` can return points outside the source when the feed shows
+less than the frame (zoom > 1 never does; a contain-shaped source does);
+`isFeedPointInSource` tells you.
+
+## Mirroring
+
+- Positions never need a flip: landmarks already live in the (possibly
+  mirrored) feed, and the feed is what you see.
+- **Direction signs** do. Holistic hand labels and the iris `offset.x` are
+  corrected with `isMirroredSourceKind(sourceKind)` so "the person's left"
+  means the same thing on every source. Use the same helper, never
+  `sourceKind === "webcam"` inline.
+- `mirrorFeedX` flips a feed point's x (for a direction vector, or to compare
+  a selfie feed with a straight recording).
+
+## Camera orientation
+
+A frame delivered sideways (a native capture, a rotated file) must be
+rotated before it becomes the source. `orientSourcePoint(point, size,
+orientation)` and `orientedSize(size, orientation)` move a point and a frame
+size through a clockwise 0 / 90 / 180 / 270 rotation; apply them before
+`sourceToFeed`. The browser already orients webcam frames, so the session
+does not rotate.
+
+## Conversions
+
+| From → to              | Helper                                                              |
+| ---------------------- | ------------------------------------------------------------------- |
+| source ↔ feed         | `sourceToFeed`, `feedToSource` (with a `FeedCrop`)                  |
+| feed ↔ tracker        | `feedToTracker`, `trackerToFeed`                                    |
+| feed ↔ viewport       | `feedToViewport`, `viewportToFeed` (viewport size)                  |
+| feed ↔ screen         | `feedToScreenPixels`, `screenPixelsToFeed`                          |
+| feed / tracker → world | `feedToWorld`, `trackerToWorld` (camera, optional `planeZ`)         |
+| world → feed / tracker | `worldToFeed`, `worldToTracker` (`z` is NDC depth)                  |
+| media layout           | `computeFitLayout(source, destination, "cover" \| "contain", zoom)` |
+
+The screen-space helpers (`normalizedToScreenPixels`, `worldToScreenPixels`,
+`screenPointToRay`, `mediaToScreenPixels` …) are unchanged and documented in
+[Screen-Space Coordinates](/api/screen-space-coordinates); a feed point is a
+"normalized viewport point" there.
+
+### Worked examples
+
+**A hand joint to a DOM overlay**
+
+```ts
+const joint = handNode.hands?.[0].coordinates?.[8]; // tracker space
+const feed = trackerToFeed(joint); // 0..1
+const css = feedToViewport(feed, { width: el.clientWidth, height: el.clientHeight });
+badge.style.transform = `translate(${css.x}px, ${css.y}px)`;
+```
+
+**A face landmark into the 3D scene** (what `TrackingAnchor` does)
+
+```ts
+useFrame(() => {
+  const tip = face.landmarks[1]; // feed space, from useFaceInfo
+  feedToWorld(tip, camera, mesh.position); // onto the z = 0 tracking plane
+});
+```
+
+**A tap to the raw frame** (send the touched pixel to a server)
+
+```ts
+const screen = clientToScreenPixels({ point: { x: e.clientX, y: e.clientY }, rect });
+const feed = screenPixelsToFeed(screen, viewportSize);
+const sourcePx = feedToSource(feed, useXRFeedCrop()!);
+```
+
+**A mask made on the raw video**
+
+```ts
+computeMaskUvTransform({
+  space: "source",
+  maskWidth: 1280,
+  maskHeight: 720,
+  feedWidth,
+  feedHeight,
+  zoom: 1.2, // the session's perf.cameraZoom
+  mirrored: true, // webcam
+});
+```
+
+## Regression coverage
+
+`lib/coordinates/coordinates.test.ts` pins: the cover crop with zoom against
+the blit loop's rectangle for landscape→portrait, portrait→landscape and 4:3
+pairs; webcam mirroring (source left edge → feed right edge, round trip);
+feed/tracker/viewport/screen round trips and agreement with
+`trackerPointToScreenPixels`; feed→world depth independence and plane
+selection; and the mask fit matching the feed crop, zoom included.