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

package/docs/api/person-cutout.mdx

@@ -0,0 +1,136 @@
+---
+title: "Person Cutout"
+description: "Background replacement as a two-layer ScreenImage composition: any background media below, the person-masked live camera above."
+sidebarTitle: "Person Cutout"
+icon: "user"
+---
+
+`PersonCutout` is the live camera, masked to the person by portrait
+segmentation, rendered as a full-screen `ScreenImage`. Put any background
+surface behind it with a lower `renderOrder` and you have background
+replacement without assembling masks, materials or coordinates yourself.
+
+```tsx
+import { FULL_SCREEN_ANCHORS, PersonCutout, ScreenImage, ScreenSpaceUI } from "@vincentt-xr/sdk";
+
+<ScreenSpaceUI>
+  {/* 1. Background: image, video texture or GIF — anything ScreenImage shows. */}
+  <ScreenImage
+    src="/backgrounds/beach.jpg"
+    fit="cover"
+    anchors={FULL_SCREEN_ANCHORS}
+    renderOrder={0}
+  />
+  {/* 2. Foreground: the camera, person only. */}
+  <PersonCutout renderOrder={100} />
+</ScreenSpaceUI>;
+```
+
+## The composition contract
+
+- **Background** is any full-screen surface drawn first: a `ScreenImage`
+  (`{ kind: "image" }`, `{ kind: "gif" }`, or `{ kind: "texture" }` with a
+  `THREE.VideoTexture`), or a custom shader plane inside
+  `<ScreenTransform anchors={FULL_SCREEN_ANCHORS}>`. Give it a `renderOrder`
+  below the cut-out's (default 100).
+- **Foreground** is `PersonCutout`: a `ScreenImage` whose `source` is the
+  session camera texture and whose `maskTexture` is the portrait segmentation
+  mask. It accepts the usual `ScreenImage` props (`opacity`, `fit`, `anchors`,
+  `blendMode`, `flipX`, `renderOrder`, `visible`) except `source` and the mask
+  props, which it owns.
+- **Ordering** is `renderOrder`; both layers are overlay-style screen planes
+  with depth testing off, so only the order matters.
+
+## Alignment: aspect ratio, mirroring, resolution
+
+- The camera texture is already cover-cropped to the viewport and mirrored
+  for webcams by the session, and the segmentation mask is produced in that
+  same feed space. `PersonCutout` samples the mask through the image's own
+  fit transform (`fit="cover"` by default), so mask and camera stay aligned
+  under any aspect ratio and any further crop or flip you apply.
+- Background media is not mirrored. If a background has to match a mirrored
+  webcam (a sign you are sitting in front of), set `flipX` on that
+  `ScreenImage`.
+- The mask is a render-size canvas texture with a half-pixel blur, so edges
+  are soft at the display resolution. The segmentation `quality` option on
+  the model trades edge detail for cost.
+
+## Mask, opacity, invert
+
+The SDK mask carries its signal in RGB: white (255) on the person, black on
+the background, with alpha 255 everywhere (three's `alphaMap` reads the green
+channel, which is how `VideoBackground` consumes the same texture). The
+cut-out reads `maskChannel="green"`, keeping the person and dropping the
+background. `invert` flips that to show only the background with the person
+cut out.
+`opacity` fades the whole person layer. `usePersonMaskTexture()` returns the
+raw mask texture with its `status` for custom compositions, and `ScreenImage`
+itself now accepts `maskTexture`, `maskChannel` (`alpha` | `red` | `green` |
+`luminance`), `maskInvert`, `maskFeather` and `maskErode` for any image.
+
+## Edge quality: feather and erode
+
+The segmenter's mask is hard-edged and sits a texel or two outside the person,
+so the raw cut-out carries a fringe of the source background (green-screen
+spill, a light halo on dark backgrounds). Two props clean it up:
+
+- `maskFeather` — radius in mask texels of a 3×3 blur over the mask. `0` keeps
+  the hard edge. Texel units keep the softness the same on screen whatever
+  resolution the mask arrives at.
+- `maskErode` — `0..1` of the feather width to shrink the kept region by. The
+  blurred edge is re-thresholded, so the silhouette moves inward and the fringe
+  falls outside it. It does nothing without feather.
+
+`PersonCutout` defaults to `maskFeather={4}` and `maskErode={0.7}`, chosen on
+the SDK's green-screen clips with the 720-px portrait mask. Raise erode when
+spill remains, lower it when fingers or hair tips disappear. Neither prop fixes
+the mask trailing a fast-moving arm; that is the segmenter's temporal lag.
+
+## Loading and fallback
+
+The segmentation model downloads on first use. `PersonCutout` reports
+`loading` → `ready` | `error` through `onStatusChange`. While not ready it
+follows `fallback`: `"camera"` (default) draws the unmasked camera so the
+experience degrades to a plain feed, `"hidden"` draws nothing so only the
+background shows. On error the same fallback applies and `error` carries
+the reason.
+
+## When to use this instead of 3D
+
+- **Use this 2D path** for background replacement, virtual backgrounds,
+  person-in-a-scene stickers, and any effect that only needs "the person
+  versus the rest of the frame". It is one quad, one mask, no geometry.
+- **Use the face mesh** when something must stick to the face surface with
+  correct perspective and shading (lipstick, face paint, UV-mapped textures).
+- **Use the head occluder** when 3D objects must disappear behind the head
+  (glasses arms, hats seen from the side). A 2D mask cannot occlude in depth.
+- The 2D mask also covers the body, hair and clothes, which neither the face
+  mesh nor the head occluder does.
+
+## Performance
+
+One extra full-screen quad with a masked shader; the segmentation model
+runs at its own `targetFps` (24 by default). Share the model: `VideoBackground`
+with `segmentation="portrait"`, `usePersonMask` overlays and `PersonCutout`
+all consume the same instance.
+
+## Manual visual test plan
+
+Run `/segmentation?mode=cutout` in the playground:
+
+| Case                     | Source / background                     | Expect                                                                          |
+| ------------------------ | --------------------------------------- | ------------------------------------------------------------------------------- |
+| Image background         | video source, Image                     | Person on the photo; no camera background visible around the edges              |
+| Video background         | video source, Video                     | Background plays behind the person; both layers keep playing                    |
+| GIF background           | video source, GIF                       | GIF animates behind the person                                                  |
+| Shader background        | video source, Shader                    | Animated plane behind the person; person edges unaffected                       |
+| Opacity                  | any, opacity 0.5                        | Person fades over the background; background unchanged                          |
+| Show background only     | any, invert                             | Person region shows the background through the camera layer                     |
+| Edge feather / erode     | video source, feather 0 vs 4, erode 0.7 | Feather 0 shows a green fringe on sleeves; the defaults remove it               |
+| Aspect / orientation     | resize the pane, rotate device          | Person stays aligned with the camera; background re-covers the screen           |
+| Mirrored webcam          | webcam                                  | Person mirrored like the feed; text on a background not mirrored unless `flipX` |
+| Movement                 | "Person Shaking Head", "Person ThumbUp" | Mask follows head and hands; thin fingers may soften                            |
+| Lighting                 | webcam, bright vs dim                   | Mask holds under both; dark clothes on dark background is the hard case         |
+| Loading, fallback camera | reload                                  | Plain camera until `ready`, then the background appears                         |
+| Loading, fallback hidden | reload                                  | Only the background until `ready`                                               |
+| Multi-person             | "Two People Smiling"                    | Both people kept; the segmenter is person-class                                 |

package/docs/api/pin-to-face-mesh.mdx

@@ -0,0 +1,274 @@
+---
+title: "Pin to Face Mesh"
+description: "Pin content to a point on the live face surface: it follows the head and the skin under it through expressions, turning with the skin. Named piercing presets for the nose, septum, lip and brow."
+sidebarTitle: "Pin to Face Mesh"
+icon: "thumbtack"
+---
+
+`PinToFaceMesh` pins content to a point on the face. It follows the head and the skin under it
+through expressions:
+
+- a sticker on the cheek rides a smile;
+- a stud by the mouth follows the corner as it moves;
+- the content turns with the skin.
+
+It is part of the face-character pipeline ([#194](https://github.com/vincentt-xr/sdk/issues/194),
+#198) and runs on a [`FaceRig`](/api/external-face-mesh#facerig).
+
+The generic [`PinToMesh`](/api/behavior-components) resolves its point once against a static mesh.
+That is still the tool for a static mesh; this one follows a surface that moves every frame.
+
+Import from `@vincentt-xr/sdk/face-effects`.
+
+## Quick start
+
+```tsx
+import { PinToFaceMesh } from "@vincentt-xr/sdk/face-effects";
+import { FaceTracker } from "@vincentt-xr/sdk/tracking";
+
+<FaceTracker>
+  <PinToFaceMesh anchor="face.leftCheek" offset={{ position: [0, 0, 0.1] }}>
+    <mesh>
+      <circleGeometry args={[1.2, 32]} />
+      <meshBasicMaterial color="hotpink" />
+    </mesh>
+  </PinToFaceMesh>
+</FaceTracker>;
+```
+
+Author the content in **centimetres** around its origin. The pin's frame is:
+
+- **X** along the face, toward the screen's right on a face looking at the camera;
+- **Y** up;
+- **Z** out of the skin.
+
+## Anchors
+
+| `anchor`                | Where                                                                                                                                                         |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `"face.leftCheek"` …    | A face target (`FACE_PIN_TARGETS`): left and right are the person's own on every feed. Composites project onto the skin.                                      |
+| `{ landmark: 278 }`     | A MediaPipe face landmark, 0–467 (MediaPipe's side; never swapped).                                                                                           |
+| `{ point: [x, y, z] }`  | A point in the canonical head frame (cm, `+X` = MediaPipe's left; never swapped), e.g. measured in the head-occluder `.blend`. It binds to the skin under it. |
+| `{ triangle, weights }` | An exact surface point: a canonical face triangle and barycentric weights.                                                                                    |
+
+Every anchor is bound once to the canonical face surface. A `point` that lies off the skin keeps its
+offset in the pin frame. An unknown name or an out-of-range index throws, listing the valid forms.
+
+A named left / right anchor follows the person's real side (GROUNDING "Left and right"): the
+canonical face's sides are MediaPipe's, which the mirrored webcam swaps, so `PinToFaceMesh` binds
+`facePinAnchorForFeed(anchor, mirrored)` with the session's mirror state. Pass `mirrored` to
+override. `"face.leftCheek"` is on the screen's left in the mirrored selfie view and on its right in
+a video.
+
+## Props
+
+| Prop        | Default     | What it does                                                                                                                                    |
+| ----------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `anchor`    | —           | Where on the face (see above).                                                                                                                  |
+| `surface`   | `"face"`    | `"face"`: the person's real face (shape + expression). `"model"`: the canonical face + expression, as an `ExternalFaceMesh` character wears it. |
+| `orient`    | `"surface"` | `"surface"`: turns with the skin (normal averaged over the triangles within 1.2 cm). `"head"`: keeps the head's orientation.                    |
+| `offset`    | —           | `{ position (cm), rotation (degrees), scale }` in the pin frame.                                                                                |
+| `smoothing` | `1`         | A per-frame EMA on the pin's position and turn (`1` = none; the rig already smooths the expression).                                            |
+| `onto`      | —           | A face model to sit on (a ref to the group around an `ExternalFaceMesh`). See below.                                                            |
+| rig props   | —           | `faceIndex`, `expressionSmoothing`, `holdMs`, `neutral`, `neutralMs`, `neutralKey`, `leadMs`, `onTrackingChange` (when it runs its own rig).    |
+
+**Pins on a character.** A character's skin is never exactly the canonical surface: its cheek may sit
+a few millimetres in front of it. Pass the character as `onto`. Once the model can be hit, the pin
+moves along its rest normal onto that skin, then rides the expression from there.
+
+Anchor at the exact spot (a `point`, a landmark or a triangle) rather than at a nearby landmark plus a
+sideways offset. The projection happens at the anchor; a sideways offset can land inside a curved
+cheek.
+
+```tsx
+const character = useRef<THREE.Group>(null);
+<FaceRig>
+  <group ref={character}>
+    <ExternalFaceMesh model={head.scene} />
+  </group>
+  <PinToFaceMesh anchor="face.rightCheek" surface="model" onto={character}>
+    <Star />
+  </PinToFaceMesh>
+</FaceRig>;
+```
+
+**Tracking.** The pin is hidden while the face is lost, holds through short dropouts (the rig's
+`holdMs`), and snaps into place on reacquire.
+
+## Pure pieces
+
+- **`bindFacePin(anchor, { patchRadius })`** → `FacePinBinding`, with `triangle`, `weights`,
+  `offset` and the normal `patch`.
+- **`stepFacePin(binding, rig, { surface, orient }, out)`** gives the pin's position and quaternion in
+  the head frame for this frame.
+- **`projectFacePinOnto(binding, model, headFrame)`** gives how far (cm) the pin must move along its
+  normal to sit on a model's skin.
+
+## Piercings
+
+`FacePiercing` puts jewellery on a named piercing spot. It is a preset over `PinToFaceMesh`: it
+knows where the hole is on the face mesh and how a stud or a ring sits there, so you never look up a
+landmark.
+
+```tsx
+import { FacePiercing, FaceRig } from "@vincentt-xr/sdk/face-effects";
+import { FaceTracker } from "@vincentt-xr/sdk/tracking";
+
+<FaceTracker>
+  <FaceRig>
+    <FacePiercing preset="nose.left" />
+    <FacePiercing preset="septum" />
+    <FacePiercing preset="brow.right" kind="stud">
+      <primitive object={myStud} />
+    </FacePiercing>
+  </FaceRig>
+</FaceTracker>;
+```
+
+Without children it draws a plain silver stud or ring sized for the spot. Wrap several piercings in
+one `FaceRig`; on its own each one runs its own rig.
+
+### Spots
+
+| `preset`       | Where                                                       | Classic `kind` | Typical size  |
+| -------------- | ----------------------------------------------------------- | -------------- | ------------- |
+| `"nose.left"`  | The alar crease of the left nostril.                        | `"stud"`       | 2.5 mm / 8 mm |
+| `"nose.right"` | The same on the right nostril.                              | `"stud"`       | 2.5 mm / 8 mm |
+| `"septum"`     | Through the septum, above the base of the nose.             | `"ring"`       | 3 mm / 10 mm  |
+| `"lip.centre"` | Below the centre of the lower lip (labret).                 | `"stud"`       | 3 mm / 9 mm   |
+| `"lip.left"`   | Below the outer third of the lower lip, left.               | `"ring"`       | 3 mm / 9 mm   |
+| `"lip.right"`  | The same on the right.                                      | `"ring"`       | 3 mm / 9 mm   |
+| `"brow.left"`  | The outer third of the left brow; a ring enters at its top. | `"ring"`       | 3 mm / 10 mm  |
+| `"brow.right"` | The same on the right brow.                                 | `"ring"`       | 3 mm / 10 mm  |
+
+Sizes are a stud's face diameter and a ring's inner diameter (`FACE_PIERCINGS[preset].size`, in
+cm).
+
+How each kind sits:
+
+- **Stud:** on the skin at the hole, its face out of the skin (the septum bead faces forward, just
+  under the nose).
+- **Nostril ring:** through the nostril wing, hanging over the rim.
+- **Septum ring:** through the septum from side to side, hanging below the nose and tipped slightly
+  forward.
+- **Lip ring:** in below the lip, wrapping up over its edge.
+- **Brow ring:** in at the top of the brow and out under it, mostly outside the skin, leaning toward
+  the temple.
+
+Every spot is bound to the face surface, so it rides expressions: the lip spots follow the jaw when
+the mouth opens, the brow spots rise with the brows.
+
+**Left and right are the person's real sides on every feed.** The face mesh's own sides are those of
+the face as the tracker sees it, which a mirrored feed (the front webcam) swaps. `FacePiercing` reads
+the session's mirroring (`useXRMirrored`) and takes the other side's placement there, so
+`"nose.left"` is always the person's left nostril: on the screen's left in the mirrored selfie view,
+on its right in a video. Pass `mirrored` to override.
+
+### The piercing frame
+
+Author jewellery in centimetres in the piercing frame; it then needs no offset:
+
+- the origin is the hole, on the skin;
+- **+Z** is the piercing axis, out of the skin: a stud's face looks along +Z, its back on the origin;
+- **+Y** is up;
+- a ring lies in the **YZ plane**, its wire passing through the origin, and hangs toward −Y (its
+  centre at `(0, −r, 0)` for a centre-line radius `r`).
+
+In Blender (glTF `+Y Up` export) that is: a stud facing −Y, a ring around the X axis hanging below
+the origin. The example sets in `assets-src/accessories/piercings-v1.blend` follow it.
+
+### Props
+
+| Prop        | Default       | What it does                                                                                       |
+| ----------- | ------------- | -------------------------------------------------------------------------------------------------- |
+| `preset`    | —             | The spot (`FACE_PIERCING_NAMES`).                                                                  |
+| `kind`      | the spot's    | `"stud"` or `"ring"`.                                                                              |
+| `mirrored`  | the session's | Whether the feed is mirrored; decides which mesh side is the person's left.                        |
+| `occlude`   | `true`        | Hides what passes behind the skin (a ring's inner half) with a depth-only patch of the live face.  |
+| `offset`    | —             | `{ position (cm), rotation (degrees), scale }` in the piercing frame, mirrored on the other side.  |
+| `surface`   | `"face"`      | As on `PinToFaceMesh`.                                                                             |
+| `smoothing` | `1`           | As on `PinToFaceMesh`.                                                                             |
+| `onto`      | —             | A worn character to sit on, as on `PinToFaceMesh` (no skin patch; the character hides the inside). |
+| rig props   | —             | Used when it runs its own rig, as on `PinToFaceMesh`.                                              |
+
+**Metals.** Gold and silver need something to reflect: give the scene an environment map (for
+example three's `RoomEnvironment` through a `PMREMGenerator`, as `/pin-to-face-mesh` does).
+
+### The skin occluder
+
+`FaceSurfaceOccluder` is the depth-only mesh of the live face that `FacePiercing` mounts around each
+hole. Use it with your own `PinToFaceMesh` content that passes through the skin:
+
+```tsx
+<FaceRig>
+  <FaceSurfaceOccluder around={{ landmark: 334 }} radius={2} />
+  <PinToFaceMesh anchor={{ landmark: 334 }}>
+    <MyRing />
+  </PinToFaceMesh>
+</FaceRig>
+```
+
+It follows the same surface as the pins (face shape, expression, and a `FaceWarp3D` / `FaceMorph`
+surface when inside one). Props: `surface`, `around` (an anchor; the whole face when omitted;
+resolved for the feed like a pin's, so a named `"face.leftCheek"` covers the same cheek as the pin),
+`mirrored` (default the session's), `radius` (cm, default 2.5), `renderOrder` (default `-1`, the
+head occluder's tier), `debug` (a visible wireframe).
+
+### Pure pieces
+
+- **`FACE_PIERCINGS`**: the presets, each with `label`, `region`, `side`, `kind`, `size` and a
+  `stud` and a `ring` placement (`at`, the hole in canonical cm as on an unmirrored source; `orient`;
+  `offset`, the piercing frame in the pin frame).
+- **`resolveFacePiercing(preset, { kind, mirrored })`** gives the exact surface `anchor`, `orient`,
+  `offset`, `size` and `flip` (the placement is the mirror image of the left-side authoring) for a
+  feed.
+- **`mirrorFacePiercingOffset(offset)`** and **`mirrorFacePiercingPlacement(placement)`** mirror an
+  offset or a placement across the face.
+
+## Example
+
+`/pin-to-face-mesh` has:
+
+- **Accessories:** a forehead gem, a brow ring, a nose stud, a star sticker on the cheek, and a beauty
+  mark just outside the mouth corner.
+- **A custom pin with debug controls:** anchor by face target, landmark index or triangle; surface;
+  orient; offsets; roll; smoothing. An axes gizmo shows X red, Y green, Z blue.
+- **A live point cloud** of the 468-landmark surface the pins follow.
+- **The facecap character** (local, see [External Face Mesh](/api/external-face-mesh#example)), with
+  the accessories projected onto its skin.
+- **Piercings** (off by default): a style chip (realistic gold and silver, or playful stars, hearts,
+  gems and candy hoops), a jewellery chip (classic, studs or rings) and a toggle per spot. URL:
+  `?p.nose.left=1&p.septum=1&pstyle=playful&pkind=ring`; `?pocclude=0` turns the skin patch off.
+
+## Manual visual test plan
+
+Open `/pin-to-face-mesh` on the webcam.
+
+1. **Placement**: the gem sits mid-forehead; the ring through a brow, the stud on a nostril and the
+   mark just above a mouth corner, all on the screen's right (landmark / point anchors keep
+   MediaPipe's side: your right on the mirrored webcam); the star on your real left cheek, on the
+   screen's left (a named anchor, the person's own side). Each sits on the skin, not floating.
+   Switch to a video: the star moves to the person's left cheek, now on the screen's right; the
+   other pieces stay on the screen's right.
+2. **Head motion**: turn and tilt. Every piece stays on its spot. The star turns with the cheek and
+   shows its edge at a steep angle.
+3. **Expressions**: smile, and the star rises with the cheek. Open your mouth, and the mark follows
+   the corner. Raise your brows, and the ring rises.
+4. **Custom pin**: switch the anchor between face targets, landmark indices and triangles. The gizmo
+   jumps there, Z out of the skin. With orient "head", the gizmo keeps the head's axes. Offsets move
+   it in the pin frame.
+5. **Surface**: tick "show the live face surface". The dots sit on your face and move with it. With
+   surface "model", the pin drifts onto the canonical face.
+6. **Character**: tick "on the facecap character". Every accessory sits on the character's own skin,
+   nothing buried, and follows its expression.
+7. **Dropouts**: cover the camera briefly and the pins hold. Cover it longer and they hide, then snap
+   back.
+8. **Piercings**: turn off the accessories and press "all" under piercings. Each piece sits on its
+   spot: studs on the skin, the nostril ring over the rim, the septum ring below the nose, the lip
+   rings over the lower lip, the brow rings through the outer brows. No ring shows its inner half.
+9. **Piercing sides**: on the webcam, the left nostril piece is on the screen's left (your left).
+   Switch to a video and it is on the person's left, the screen's right.
+10. **Piercings through expressions**: open your mouth wide; the lip pieces follow the jaw. Raise your
+    brows; the brow rings rise. Turn your head; nothing slides off.
+11. **Styles**: switch realistic / playful and classic / studs / rings. With realistic, the metals
+    reflect. With "skin hides the inside" off, the inner half of each ring appears.

package/docs/api/product-ar.mdx

@@ -0,0 +1,114 @@
+---
+title: "Product Placement AR"
+description: "View-in-your-space AR for product pages on top of Google's model-viewer: capability detection, the ProductViewer wrapper, the useProductAr hook, and the camera handoff with the tracking session."
+sidebarTitle: "Product AR"
+icon: "cube"
+---
+
+Placement AR puts a product on the floor or a wall through the device's
+native path: WebXR (Android Chrome), Scene Viewer (Android) or Quick Look
+(iOS, from a USDZ). It is a different mode from the SDK's camera session,
+which has no world tracking. The SDK wraps Google's `<model-viewer>` for it
+rather than rebuilding it; the rule for every page: **placement AR is
+model-viewer, face/body AR is the session, never both at once.**
+
+```tsx
+import { ProductViewer, useProductAr } from "@vincentt-xr/sdk/product";
+
+const Product = () => {
+  const ar = useProductAr();
+  return (
+    <>
+      <ProductViewer
+        src="/hat.glb"
+        iosSrc="/hat.usdz"
+        poster="/hat.webp"
+        alt="Hat"
+        onReady={ar.bind}
+      />
+      {ar.supportedModes.length > 0 && (
+        <button onClick={() => ar.activate()} disabled={!ar.canActivate}>
+          View in your space
+        </button>
+      )}
+    </>
+  );
+};
+```
+
+## Install
+
+`@google/model-viewer` is an optional peer dependency: add it to the app
+that renders products. `<ProductViewer>` imports it lazily on first render,
+so other pages never pay for it. It bundles its own three.js (it cannot share
+the SDK's), roughly 1 MB; keep it on product routes only.
+
+## Capability
+
+`detectXRCapabilities` / `useXRCapabilities` report `placement`:
+
+| Field         | How it is detected                                                                  |
+| ------------- | ----------------------------------------------------------------------------------- |
+| `webxr`       | `navigator.xr.isSessionSupported("immersive-ar")`                                   |
+| `sceneViewer` | Android Chrome / Samsung Internet user agent                                        |
+| `quickLook`   | `<a rel="ar">` support (iOS Safari and WebKit browsers)                             |
+| `any`         | one of the above; otherwise `reason.code` `placement-unsupported` (not recoverable) |
+
+Offer "View in AR" only when `any` is true; desktop shows the viewer alone.
+
+## `<ProductViewer>`
+
+| Prop                                                                                         | model-viewer attribute                           |
+| -------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| `src`, `iosSrc`, `poster`, `alt`                                                             | `src`, `ios-src`, `poster`, `alt`                |
+| `ar` (default true), `arModes`                                                               | `ar`, `ar-modes` (preference order)              |
+| `placement: "floor" \| "wall"`                                                               | `ar-placement`                                   |
+| `scale: "auto" \| "fixed"`                                                                   | `ar-scale` (`fixed` = true-to-size, no pinch)    |
+| `cameraControls`, `autoRotate`, `loading`, `environmentImage`, `shadowIntensity`, `exposure` | same names, kebab-cased                          |
+| `attributes`                                                                                 | anything else, passed straight through           |
+| `onLoad`, `onError`, `onArStatus`, `onReady(element)`                                        | `load`, `error`, `ar-status` events; the element |
+
+Children are slotted into model-viewer (`slot="ar-button"`, `slot="poster"`,
+hotspots).
+
+## `useProductAr()`
+
+Returns `{ status, supportedModes, canActivate, reason, loading, error, bind, activate, handleStatus }`.
+`status` is model-viewer's `ar-status` (`not-presenting`, `session-started`,
+`object-placed`, `failed`) or `unavailable` when no mode is supported.
+`activate()` must run from a user gesture.
+
+### Camera handoff
+
+Only WebXR runs in the page and needs the camera the tracking session
+holds; Scene Viewer and Quick Look open a native activity and never touch
+it. When the hook runs under an `<XRProvider>` whose session is `running` or
+`paused` on the webcam and the mode about to be used is `webxr`,
+`activate()` stops the session first and restores the same facing and
+lifecycle (a paused session comes back paused) when `ar-status` returns to
+`not-presenting` (or `failed`). `handoffCamera: false` opts out. Stream /
+canvas sources are left alone. The pure form is
+`releaseSessionForAr(session, mode)`. Keep `arModes` on the viewer and
+`modes` on the hook identical; both default to `DEFAULT_PRODUCT_AR_MODES`.
+
+## Assets
+
+- GLB for every platform; keep it under a few MB. Compress with meshopt
+  (geometry) + WebP (textures); never Draco or KTX2. model-viewer would fetch
+  Draco / KTX2 decoders from Google's CDN at view time, and the same GLB fails
+  to load in the SDK's own model paths (`defineGltfAsset`, `MeshRenderer`).
+- USDZ for iOS Quick Look via `iosSrc`; without it model-viewer exports one
+  on the fly (slower, lower fidelity). The GLB → USDZ step is a publishing
+  step (see the asset pipeline issue), never runtime code.
+- Host both on the CDN with long cache headers.
+
+## Manual validation
+
+Run `/product-details?model=astronaut`:
+
+| Device                          | Expect                                                                                                                                                             |
+| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Desktop                         | viewer with orbit; `supported modes: none`, button disabled                                                                                                        |
+| Android Chrome                  | `scene-viewer` (and `webxr` on ARCore devices); tap → Scene Viewer / WebXR places the astronaut; status log `session-started` → `object-placed` → `not-presenting` |
+| iPhone                          | `quick-look`; tap → Quick Look opens the USDZ                                                                                                                      |
+| With a tracking session running | the session reads `stopped` during AR and `running` after                                                                                                          |

package/docs/api/product-details.mdx

@@ -0,0 +1,78 @@
+---
+title: "Product Variants, Hotspots & Dimensions"
+description: "Material variants (colour / size), surface-anchored hotspots with serializable authoring data, and true-size dimension labels on a ProductViewer."
+sidebarTitle: "Product Details"
+icon: "tags"
+---
+
+Builds on `<ProductViewer>` (Product Placement AR). Three details a product
+page needs on the same model: switching looks, pointing at parts, and
+telling the real size.
+
+```tsx
+import {
+  ProductViewer,
+  ProductHotspot,
+  ProductDimensions,
+  useProductVariants,
+  useProductHotspots,
+  useProductDimensions,
+  type ProductViewerElement,
+} from "@vincentt-xr/sdk/product";
+
+const [el, setEl] = useState<ProductViewerElement | null>(null);
+const variants = useProductVariants(el); // { variants, variant, setVariant }
+const dimensions = useProductDimensions(el); // { size: [w, h, d], center } in metres, null until loaded
+const hotspots = useProductHotspots(el, { initial: fromCms, onChange: save });
+
+<ProductViewer src="/shoe.glb" scale="fixed" onReady={(e) => setEl(e)}>
+  {hotspots.hotspots.map((h) => (
+    <ProductHotspot key={h.id} hotspot={h} onClick={open} />
+  ))}
+  <ProductDimensions dimensions={dimensions} unit="metric" />
+</ProductViewer>;
+```
+
+## Variants
+
+`useProductVariants(element)` reads the model's `KHR_materials_variants`
+after load and sets `variantName` on the element. Variants change materials
+only, so they carry into AR wherever the platform renders the glTF (WebXR,
+Scene Viewer). Quick Look renders the USDZ as exported: ship one USDZ per
+variant and switch `iosSrc` with the variant, or accept the default look.
+
+## Hotspots
+
+`ProductHotspotData = { id, position: [x, y, z], normal: [x, y, z], label?, description? }`
+in model metres; serializable and validated (`parseHotspots`,
+`serializeHotspots`). `<ProductHotspot>` renders a slotted callout model-viewer
+keeps over the surface as the camera orbits, fading it when the surface
+faces away.
+
+`useProductHotspots(element, { initial, onChange })` is the authoring and
+runtime state: `placeFromPointer(clientX, clientY, label)` raycasts the
+click onto the model (`positionAndNormalFromPoint`), `add` / `update` /
+`remove` / `clear`, `json` / `importJson`. The debug-ui
+`<ProductHotspotPanel>` wraps it with click-to-place, label editing and a
+JSON copy, so authored data goes back into the app as `initial`.
+
+## Dimensions
+
+`useProductDimensions(element)` returns the bounding box (`getDimensions`,
+`getBoundingBoxCenter`) after load. `<ProductDimensions>` labels width,
+height and depth on three box edges, anchored as hotspots (`dimensionLines`
+computes the edges); `unit` is `metric` (cm under 1 m) or `imperial`.
+Pair with `scale="fixed"` on the viewer so AR places the model at that
+size with no pinch-to-resize.
+
+## Manual validation
+
+Run `/product-details` (model-viewer's variants shoe):
+
+| Case       | Steps                               | Expect                                                         |
+| ---------- | ----------------------------------- | -------------------------------------------------------------- |
+| Variants   | tap the colourway buttons           | the shoe changes material; the panel select follows            |
+| Hotspots   | "place hotspot", click the shoe     | a labelled dot stays on that point while orbiting              |
+| Authoring  | edit the label, "copy JSON", reload | label persists; JSON matches the panel                         |
+| Dimensions | toggle, switch unit                 | W / H / D labels on the box edges, cm ↔ in                    |
+| AR (phone) | "View in your space"                | true-size placement; variant carried into Scene Viewer / WebXR |

package/docs/api/screen-space-coordinates.mdx

@@ -7,7 +7,10 @@ icon: "ruler"
 
 Import screen-coordinate helpers from `@vincentt-xr/sdk`. SDK screen pixels use
 a `720x1280` design canvas by default, center origin, and positive Y upward.
-They are not Three.js world units.
+They are not Three.js world units. For the feed (landmark) space, the
+source-media crop, mirroring and world projection, see
+[Coordinate Spaces](/api/coordinate-spaces); this page covers the design-pixel
+helpers.
 
 ## Coordinate contract