@liveroom-tech/react-immersive 5.0.2 → 5.2.0

package/README.md

@@ -1,6 +1,6 @@
 # React Immersive — 3D model viewer for React
 
-`@liveroom-tech/react-immersive` is a React-based 3D model viewer for interactive GLB, GLTF, OBJ, FBX, and USDZ assets. It renders a model with React Three Fiber, lets users click named meshes, shows a built-in side panel for the selected object, and supports per-object actions such as color changes, texture uploads, and visibility toggles.
+`@liveroom-tech/react-immersive` is a React-based 3D model viewer for interactive GLB, GLTF, OBJ, FBX, USDZ, STL, and PLY assets. It renders a model with React Three Fiber, lets users click named meshes, shows a built-in side panel for the selected object, and supports per-object actions such as color changes, texture uploads, and visibility toggles.
 
 [Website](https://react-immersive.liveroom.dev) · [Documentation](https://react-immersive.liveroom.dev/docs) · [Live editor](https://react-immersive.liveroom.dev/editor) · [npm](https://www.npmjs.com/package/@liveroom-tech/react-immersive) · [GitHub](https://github.com/Liveroom-Technologies/react-immersive-docs)
 
@@ -18,6 +18,7 @@ import {
   useObjectBindingIds,
   useObjectBindings,
   useSceneConfig,
+  useShareableViewerState,
   useViewer,
   useViewerActions,
   useViewerAnimations,
@@ -25,6 +26,7 @@ import {
   useViewerConnection,
   useViewerEffects,
   useViewerHover,
+  useViewerIsolation,
   useViewerModel,
   useViewerSelection,
   MATERIAL_BLENDING_MODES,
@@ -41,7 +43,7 @@ It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectBindi
 
 `ModelViewer` provides:
 
-- GLB/GLTF, OBJ/MTL, FBX, and USDZ model rendering through `@react-three/fiber`
+- GLB/GLTF, OBJ/MTL, FBX, USDZ, STL, and PLY model rendering through `@react-three/fiber`
 - camera-driven 3D Tiles streaming through `tilesetUrl`, with configurable screen-space error and bounded tile cache
 - orbit/pan/zoom camera controls via `CameraControls`
 - auto-fits the model on load, and re-fits when the canvas is resized (window resize, device rotation, or a panel opening/closing), toggleable through `refitOnResize` to instead preserve the user's orbit/zoom
@@ -51,6 +53,7 @@ It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectBindi
 - optional shadow rendering toggle through a `shadows` prop (on by default)
 - optional on-screen movement controller through `showMouseController` and its tuning props
 - optional canvas-focused keyboard camera navigation through `enableKeyboardNavigation`
+- keyboard object navigation, screen-reader selection announcements, and reduced motion for visitors who ask for it (see [Accessibility](#accessibility))
 - optional top-right camera orientation control through `showViewGizmo`
 - optional per-object move and rotate gizmo through `moveModeEnabled`, with World/Local axis alignment through `objectTransformSpace`
 - optional custom left object data panel through `customObjectBindingDataPanel`
@@ -59,13 +62,21 @@ It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectBindi
 - optional hiding of either built-in panel through `showObjectBindingDataPanel` and `showSceneObjectsPanel`
 - optional model export button through `showDownloadButton` and `downloadFilename`, opt-in PNG capture through `preserveDrawingBuffer`, plus an independent `showResetButton` toggle for the rest of that action bar
 - an optional UV Checker toolbar button through `showUvCheckerButton`, for inspecting UV scale, stretching, seams, orientation, and missing UV0 coordinates directly in `ModelViewer`
-- click-to-measure distance tool and a bounding-box dimensions overlay through `showMeasureTools` and `measurementUnit`
+- glTF material variants (`KHR_materials_variants`) as swatch rows, one per option group, through `showMaterialVariants`, selected by `sceneConfig.model.activeVariants`
+- distance, angle, polygon area, and point-to-plane measurements with vertex/edge snapping and bounding dimensions through `showMeasureTools` and `measurementUnit`
 - an exploded-view slider that slides each bound part outward from the model center to reveal interior/assembly structure through `showExplodeControls`
+- isolation that ghosts or hides everything but the objects you focus on, through `isolation` / `onIsolationChange` and `showIsolateControls`
+- a section cut that opens the model along an axis, with a draggable plane, through `showSectionTools` and `sceneConfig.section`
 - a cinematic auto-camera that glides the camera along authored waypoints (or a zero-config showcase orbit), like a film, through `cinematic`, with a play/pause control that yields the moment you touch the camera
+- video export of a cinematic pass or turntable revolution, through the download menu or `captureVideo`, as browser-supported WebM/MP4 or an animated GIF
+- `CompareViewer`, which shows two configurations (or two models) with one camera, as a before/after slider or side by side
+- opt-in WebGPU rendering through `perf={{ webgpu: true }}`, falling back to WebGL where the browser lacks it
+- lazy loading: a viewer starts its 3D view when it's near the screen, and a page of viewers stays within the browser's limit on 3D views, with a `poster` image and an optional "View in 3D" button (`reveal`) until the view is there (see [Lazy loading and posters](#lazy-loading-and-posters))
 - a guided-tour control cluster (Previous/Stop/Next) for stepping through annotations, toggleable via `showAnnotationNavigation`
 - optional annotation detail popups on marker hover via `showAnnotationOnHover`
 - PBR, Matcap, and UV Checker renderer modes, with the checker exposing UV stretching, seams, rotation, and missing UV0 data directly on the model
 - a `sceneConfig` prop accepting the same scene-wide config (lighting, environment, background, post-processing, animations, annotations) authored by `BindingBuilder`'s Scene tab
+- WebGL context-loss recovery with a reload button and automatic rebuild when the context returns, keeping the camera and the visitor's changes
 - render-loop and perf tuning through `renderMode`, `maxDpr`, `performanceProfile`, and compressed-asset decoder options (`dracoDecoderPath`, `ktx2TranscoderPath`, `meshopt`)
 - WebXR "View in your space" (AR) and "Enter VR" through `enableXR`, with tap-to-place, pinch-to-resize, and twist-to-rotate AR placement gestures
 - mesh selection by object name
@@ -75,6 +86,8 @@ It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectBindi
 - built-in texture upload that commits a URL into `objectBindings.style.material.texture.path` (blob URL by default, or a durable URL when `onTextureUpload` is provided)
 - per-object `MeshPhysicalMaterial` overrides for metalness, roughness, emissive, normal/bump, AO, displacement, clearcoat, sheen, anisotropy, specular, transmission, thickness, reflectivity, sidedness, and limited blending modes
 - per-object visibility toggling through `objectBindings.visible`
+- decals: images and text printed on an object's surface through `objectBindings.decals`, placed from the surface point pointer events report
+- data-driven looks through `sceneConfig.styleRules`: colour scales from metrics, material overrides by status or metadata, and pulsing alarms
 - hover and selected-state highlighting
 - external selection state control through `selectedObject` and `onObjectSelect`
 - hover callbacks through `onObjectHover`
@@ -84,13 +97,14 @@ It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectBindi
 - camera change callbacks through `onCameraChange`
 - viewer-ready callbacks through `onViewerReady`
 - action event callbacks through `onAction`
+- opt-in engagement analytics through `onEngagement`, with `debugEngagement` console logging
 - animation playback for GLB/GLTF, FBX, and USDZ models with supported embedded animations through `onAnimationsReady`
 - annotation marker callbacks through `onAnnotationsChange` and controlled/uncontrolled `activeAnnotation` / `onActiveAnnotationChange`
 
 `BindingBuilder` provides:
 
-- a design-time UI for generating starter bindings from GLB, GLTF, OBJ, FBX, and USDZ assets, gated by `licenseKey` (see "`BindingBuilder` licensing & plan tiers" below)
-- demo model loading or custom `.glb`, `.gltf`, `.obj`, `.fbx`, `.usdz`, or model ZIP bundle upload
+- a design-time UI for generating starter bindings from GLB, GLTF, OBJ, FBX, USDZ, STL, and PLY assets, gated by `licenseKey` (see "`BindingBuilder` licensing & plan tiers" below)
+- demo model loading or custom `.glb`, `.gltf`, `.obj`, `.fbx`, `.usdz`, `.stl`, `.ply`, or model ZIP bundle upload
 - editable binding fields for identity, basics, style, actions, metrics, metadata, and saved camera state
 - per-object move and rotate authoring with a geometry-centered pivot, World/Local axes, numeric fields, and restore-to-authored-transform support
 - a one-click material preset gallery (wood, metal, chrome, glass, plastic, fabric, ceramic, concrete, etc.)
@@ -100,12 +114,12 @@ It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectBindi
 - import a previously exported `objectBindings.json` or `sceneConfig.json` and merge it back onto the current model/config
 - live preview using `ModelViewer`
 - export as JSON or TypeScript, bundled into a `.zip` with a `materials/` folder automatically when any texture field was filled by file upload, otherwise a plain file
-- license-tier gating for some editor features (texture maps, environment lighting/backgrounds, wireframe preview, animation configuration, annotations, post-processing)
+- license-tier gating for some editor features (texture maps, environment lighting/backgrounds, wireframe preview, animation configuration, annotations, style rules, post-processing)
 
 `SimpleModelViewer` provides:
 
-- a lightweight GLB/GLTF/OBJ/FBX/USDZ viewer with no bindings or actions that does not require a `licenseKey`
-- optional local `.glb`, standalone/data-URI `.gltf`, `.obj`, `.fbx`, `.usdz`, or model ZIP bundle upload mode for ad-hoc inspection without relying on the `modelUrl` asset
+- a lightweight GLB/GLTF/OBJ/FBX/USDZ/STL/PLY viewer with no bindings or actions that does not require a `licenseKey`
+- optional local `.glb`, standalone/data-URI `.gltf`, `.obj`, `.fbx`, `.usdz`, `.stl`, `.ply`, or model ZIP bundle upload mode for ad-hoc inspection without relying on the `modelUrl` asset
 - built-in scene objects panel with search and visibility toggles
 - a built-in environment/scene settings panel (background color, environment preset, auto-rotate, exposure, ambient + directional light) toggleable via `showSceneSettingsPanel`, with each control's initial value seedable via props
 - click-to-select and fit-to-object focus behavior
@@ -267,7 +281,7 @@ export default function Configurator() {
 
 `viewer.bindings`, `viewer.selection`, `viewer.hover`, `viewer.camera`,
 `viewer.model`, `viewer.animations`, `viewer.actions`, `viewer.scene`,
-`viewer.effects`, and `viewer.connection` are the results of the hooks they're
+`viewer.isolation`, `viewer.effects`, and `viewer.connection` are the results of the hooks they're
 named after (`useObjectBindings`, `useViewerSelection`, and so on), so
 everything below applies to them. Without a `bindings` option, `useViewer`
 generates bindings from the model like `objectBindings="auto"`; pass
@@ -462,6 +476,9 @@ const {
   setTransform,
   resetTransform,
   updateMetadata,
+  addDecal,
+  updateDecal,
+  removeDecal,
   hiddenObjects,
   hiddenObjectIds,
   hideObject,
@@ -524,6 +541,7 @@ The hook returns:
 - `setMaterial`, `setBaseColor`, `setTexture`, `clearTexture`, `copyMaterial`, `resetMaterial`, and `getMaterial`
 - `setTransform` and `resetTransform` for persistent local-space model transforms
 - `updateMetadata` for recursively merged application data
+- `addDecal`, `updateDecal`, and `removeDecal` for images and text printed on objects (see [Decals](#decals))
 - `hiddenObjects`: a derived map of hidden binding keys
 - `hiddenObjectIds`: the currently hidden binding IDs
 - `hideObject`, `showObject`, `toggleObjectVisibility`
@@ -661,6 +679,7 @@ const {
   error,
   bounds,
   objectCount,
+  materialVariants,
   objects,
   handleModelLoaded,
   handleObjectCatalog,
@@ -684,6 +703,8 @@ const {
 - `error`: the most recent load/render error, or `null`
 - `bounds`: the loaded scene bounds as `min`, `max`, `center`, and `size`
 - `objectCount`: the number of mesh objects in the loaded scene
+- `materialVariants`: the names of the model's glTF material variants, or an
+  empty array (see [`showMaterialVariants`](#showmaterialvariants))
 - `objects`: every bindable object in the model as a `ViewerObjectInfo`, once
   `handleObjectCatalog` is passed to `onObjectCatalog`
 - `handleModelLoaded`: a callback you can pass directly to `onModelLoaded`
@@ -748,9 +769,11 @@ type BindingBuilderProps = {
 
 Current behavior, Object tab:
 
-- upload a `.glb`, standalone/data-URI `.gltf`, `.obj`, `.fbx`, or `.usdz` file, or a `.zip` bundle (a `.gltf` with its `.bin` and textures, an `.obj` with its MTL and textures, or an `.fbx` with external textures)
+- upload a `.glb`, standalone/data-URI `.gltf`, `.obj`, `.fbx`, `.usdz`, `.stl`, or `.ply` file, or a `.zip` bundle (a `.gltf` with its `.bin` and textures, an `.obj` with its MTL and textures, or an `.fbx` with external textures)
 - traverse renderable mesh nodes and generate starter bindings automatically
+- for an object without texture coordinates (STL, most PLY), the **Material** image map fields are turned off with a note, and the starter actions leave out **Change Material** (see [STL and PLY](#stl-and-ply))
 - edit binding identity, label, type, status, booleans, style, actions, metrics, metadata, and saved camera state
+- add decals to the selected object from the **Decals** panel: upload an image or add text to place it automatically at the centre of the camera-facing surface, then set its size, rotation, and opacity; **Move** lets you drag the decal across the object's surface. Release to save, or press Escape to cancel. Uploaded images are exported under `materials/` with the bindings
 - move and rotate the selected object from the **Move & Rotate** panel using a geometry-centered pivot, World/Local axis alignment, or numeric position and degree fields; restore its authored transform with one click
 - apply a one-click material preset (wood, metal, chrome, glass, plastic, fabric, ceramic, concrete, etc.) onto the selected object's material
 - undo/redo the current bindings (toolbar buttons or `Cmd/Ctrl+Z` / `Cmd/Ctrl+Shift+Z`); rapid edits coalesce into a single undo step
@@ -761,6 +784,12 @@ Current behavior, Scene tab:
 
 - configure the same `SceneConfig` shape `ModelViewer`'s `sceneConfig` prop accepts (lighting, environment, background, ground shadows, wireframe, post-processing, animations, annotations)
 - configure auto-rotation and its speed, exported as `sceneConfig.model.autoRotate` and `sceneConfig.model.autoRotateSpeed`
+- preview animation clips, several at once and forwards or backwards, and set each clip's loop mode (loop, play once, or ping-pong), speed, and display name
+- check changes with **Compare** above the preview: a before/after divider across the preview, with the project as it was opened on the left and as it is now on the right; orbiting either side moves both, and **Pin** on the "Before" label makes the current state the "before" for the next round of changes
+- pick which of the model's glTF material variants the scene starts with, one per option group, exported as `sceneConfig.model.activeVariants`
+- isolate a node from the Scene Nodes list to see it on its own in the preview while you edit it (not exported)
+- set up a section cut (**General → Section Cut**: axis, position, and side to keep), exported as `sceneConfig.section`; the preview has the section toolbar and draggable plane too
+- build style rules (**Rules** sub-tab) that restyle objects from their metrics, status, and metadata, with suggestions from the model's bindings, a live match count, and a live preview; exported as `sceneConfig.styleRules`
 - position and rotate directional, point, and spot lights with transform gizmos; spot lights also expose angle and penumbra controls
 - undo/redo the scene config independently of the Object tab's bindings history
 - import a previously exported `sceneConfig.json`, merged by top-level section
@@ -773,7 +802,7 @@ Preview:
 Autosave:
 
 - the session (the model, its object bindings, and the scene settings, with an uploaded model file included) is saved to this browser's IndexedDB, in a database named `react-immersive:binding-builder`, shortly after each edit and when the tab is hidden or closed
-- **Restore last session** in the preview toolbar reopens it; one session is kept per browser
+- **Restore last session** in the preview's "⋯" menu reopens it; one session is kept per browser
 - while there are edits on screen, leaving or reloading the page asks for confirmation
 - if the browser refuses to store a session, usually for lack of space, the editor says so; export your work to keep it
 - enable **Transform gizmo**, select a mesh, then use the arrows and plane handles to move it or the rings to rotate it; all changes are saved to `binding.transform`
@@ -785,14 +814,14 @@ Some editor features are gated by the license's plan tier (the server-returned `
 | Tier      | Unlocks                                                                                                                                                                                                                       |
 | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `free`    | All 3 components are available. `SimpleModelViewer` is fully available, while `ModelViewer` and `BindingBuilder` are limited to local development with base color, metalness/roughness sliders, and basic scene settings only |
-| `starter` | + Texture maps, the specular workflow, reflectivity, environment lighting, environment backgrounds, wireframe preview, animation configuration, annotations                                                                   |
+| `starter` | + Texture maps, the specular workflow, reflectivity, environment lighting, environment backgrounds, wireframe preview, animation configuration, annotations, style rules, decals                                              |
 | `growth`  | + Post-processing effects                                                                                                                                                                                                     |
 
 A locked feature renders in place (not hidden) with a message naming the required plan, so it stays discoverable while editing.
 
 ## `SimpleModelViewer`
 
-`SimpleModelViewer` is an exported lightweight viewer for cases where you want to load a GLB, GLTF, OBJ, FBX, or USDZ asset, inspect meshes, and toggle visibility without building `objectBindings`. It can either load a fixed `modelUrl` or, when `enableModelUpload` is turned on, let the user drag-and-drop or choose a local model at runtime.
+`SimpleModelViewer` is an exported lightweight viewer for cases where you want to load a GLB, GLTF, OBJ, FBX, USDZ, STL, or PLY asset, inspect meshes, and toggle visibility without building `objectBindings`. It can either load a fixed `modelUrl` or, when `enableModelUpload` is turned on, let the user drag-and-drop or choose a local model at runtime.
 
 Basic usage:
 
@@ -879,6 +908,60 @@ const {
 
 Pass `initialPosition`, `initialTarget`, and optional named `presets` to `useViewerCamera` to configure the first view without writing an `onViewerReady` wrapper.
 
+If you want a link that opens the viewer the way it looks now, the library also exports `useShareableViewerState`. It keeps the camera, the hidden objects, and the selection in the page URL's hash (`#view=…`), and puts them back when the link is opened:
+
+```tsx
+const viewer = useViewer();
+const share = useShareableViewerState({
+  cameraState: viewer.camera.cameraState,
+  setCameraState: viewer.camera.setCameraState,
+  objectBindings: viewer.bindings.objectBindings,
+  onObjectBindingsChange: viewer.bindings.setObjectBindings,
+  selectedObjectBinding: viewer.selection.selectedObjectBinding,
+  setSelectedObjectBinding: viewer.selection.setSelectedObjectBinding,
+});
+
+<ModelViewer
+  modelUrl="/model.glb"
+  licenseKey="your-license-key"
+  {...viewer.props}
+  onViewerReady={(ready) => {
+    viewer.props.onViewerReady(ready);
+    void share.restoreFromUrl();
+  }}
+  refitOnResize={false}
+/>;
+
+<button onClick={() => navigator.clipboard.writeText(share.getShareUrl())}>
+  Copy link
+</button>;
+```
+
+`useShareableViewerState` takes:
+
+- `cameraState` and `setCameraState`: from `useViewerCamera` (`viewer.camera`)
+- `objectBindings` and `onObjectBindingsChange`: the bindings and their setter; hidden objects are restored by setting their `visible` to `false`
+- `selectedObjectBinding` and `setSelectedObjectBinding`: from `useViewerSelection` (`viewer.selection`). `ModelViewer` also needs `selectedObject` (`viewer.props` passes it), or a restored selection won't show
+- `paramKey`: the hash key the view is stored under. Default `"view"`
+- `debounceMs`: how long after a change the hash is updated, in milliseconds. Default `400`
+- `autoSync`: keep the hash up to date as the view changes. Default `true`. With `false`, write it with `syncUrl` or build links with `getShareUrl`
+
+`useShareableViewerState` returns:
+
+- `getShareUrl`: the current page URL with the current view in its hash, without changing the address bar
+- `syncUrl`: writes the current view into the hash now, with `history.replaceState`, so no history entry is added
+- `restoreFromUrl`: applies the view in the hash, if there is one, and resolves `true` once it has applied all of it. Called again, it does nothing until the hash holds a different view, so it's safe to call from `onViewerReady`, which runs often
+
+Things to know:
+
+- The link holds the view, not the model. Keep whatever identifies the model, such as a route or query parameter, in the URL too. Objects are stored by `binding.id`, so links keep working while the ids stay the same.
+- The hash is only updated after `restoreFromUrl` has been called once, so an incoming link isn't overwritten before it's read. Call it even if you don't restore links; with nothing in the hash it does nothing.
+- When the bindings come from the model, as with `useViewer` or `objectBindings="auto"`, they exist only once it has loaded, after the first `onViewerReady`. A link that hides or selects objects then restores its camera at once and waits for them: `onViewerReady` runs again when the bindings arrive, and that call hides and selects them. The hash isn't updated while it waits.
+- The camera jumps to the shared view without a transition. `refitOnResize={false}` keeps a later resize from re-framing the model away from it.
+- The hook listens for `hashchange`, so pasting a newer link into an open tab applies it.
+
+See the [Shareable View example](https://react-immersive.liveroom.dev/examples/shareable-view) and the [`useShareableViewerState` docs](https://react-immersive.liveroom.dev/docs/hooks/use-shareable-viewer-state).
+
 If your GLB/GLTF model contains animations, the library also exports:
 
 ```tsx
@@ -906,16 +989,17 @@ const {
 
 - `clips`: an array of animation clip names found in the GLB/GLTF file
 - `clipDetails`: clip metadata including `sourceName` and `duration` in seconds
-- `currentClip`: the name of the currently playing clip, or `null`
-- `isPlaying`: `true` while an animation is playing (not paused or stopped)
-- `speed`: the current playback speed (default `1`)
-- `time`: the live playback position of the current clip, in seconds (updates while playing)
-- `duration`: the length of the current clip, in seconds
-- `play`: starts a clip by name; if the same clip is paused, resumes it instead of restarting
-- `pause`: pauses the currently playing clip at its current time
-- `stop`: stops the current clip and resets it
-- `setSpeed`: changes the playback speed (e.g. `0.5` for half speed, `2` for double)
-- `seek`: scrubs the current clip to an absolute time in seconds (works while playing or paused), clamped to the clip length
+- `currentClip`: the clip played most recently, while it's active, or `null`
+- `isPlaying`: `true` while any clip is playing (not paused, finished, or stopped)
+- `speed`: the playback speed of `currentClip` (default `1`)
+- `time`: the live playback position of `currentClip`, in seconds (updates while playing)
+- `duration`: the length of `currentClip`, in seconds
+- `active`: every active clip (playing, paused, or finished) with its `status`, `time`, `duration`, `speed`, and `reverse`, most recently played last
+- `play(clip, options?)`: starts a clip by name, replacing the clips already playing unless `options.alongside` is set; `options.fade` blends over that many seconds, and `options.reverse` plays it backwards. A paused clip resumes instead of restarting
+- `pause(clip?)`: pauses one clip, or every active clip, at its current time
+- `stop(clip?)`: stops one clip, or every active clip, and resets the pose
+- `setSpeed(speed, clip?)`: changes the playback speed (e.g. `0.5` for half speed, `2` for double) of one clip, or of every active clip and those played later without their own speed
+- `seek(time, clip?)`: scrubs one clip, or every active clip, to an absolute time in seconds (works while playing or paused), clamped to the clip length
 - `handleAnimationsReady`: a callback you can pass directly to `onAnimationsReady`
 
 Example with playback controls:
@@ -930,7 +1014,7 @@ const { clips, currentClip, isPlaying, play, pause, stop, setSpeed } =
 </button>
 
 // Stop
-<button onClick={stop}>Stop</button>
+<button onClick={() => stop()}>Stop</button>
 
 // Speed slider
 <input
@@ -950,16 +1034,128 @@ const { clips, currentClip, isPlaying, play, pause, stop, setSpeed } =
 ))}
 ```
 
+Several clips can play at once. `play` replaces the clips already playing
+unless you pass `alongside: true`, and the other controls act on one clip when
+you name it, or on every active clip when you don't:
+
+```tsx
+const animations = useViewerAnimations();
+
+// Open both doors together, then close the left one.
+animations.play("DoorLeftOpen", { alongside: true });
+animations.play("DoorRightOpen", { alongside: true });
+animations.play("DoorLeftOpen", { alongside: true, reverse: true });
+
+// Blend from walking to running over half a second.
+animations.play("Run", { fade: 0.5 });
+
+animations.pause("Wheels"); // one clip
+animations.stop(); // every clip
+
+// What's active, and how far along each clip is
+animations.active.map(({ clip, status, time }) => `${clip}: ${status} at ${time}s`);
+```
+
+A clip whose `loopMode` is `"once"` holds its last pose when it finishes
+(`status: "finished"`) until it's stopped or played again, so an opened door
+stays open. `"ping-pong"` plays forwards then backwards, repeatedly. Playing a
+clip that's already playing in the same direction leaves it running; playing
+it the other way turns it around where it is.
+
+## `CompareViewer`
+
+Shows two configurations next to each other with one camera: a before and
+after of a renovation, two paint options, the current part against its
+replacement. Each side is a full [`ModelViewer`](#public-api),
+so a side can differ in anything a viewer takes: `objectBindings`,
+`sceneConfig`, material variants, even a different `modelUrl`.
+
+```tsx
+import "@liveroom-tech/react-immersive/styles.css";
+import { CompareViewer } from "@liveroom-tech/react-immersive";
+
+<div style={{ height: 600 }}>
+  <CompareViewer
+    modelUrl="/kitchen.glb"
+    licenseKey="your-license-key"
+    before={{ label: "Current", objectBindings: currentBindings }}
+    after={{ label: "Proposed", objectBindings: proposedBindings }}
+  />
+</div>;
+```
+
+### Layouts
+
+- **`layout="slider"`** (default) lays the two views over each other. A divider
+  splits them: the left of it shows `before`, the right shows `after`. Drag the
+  divider, or focus it and use the arrow keys, Page Up/Down, Home, and End. It
+  is a slider to screen readers, with each side's label and share.
+- **`layout="side-by-side"`** shows the two views next to each other, each half
+  the width.
+
+```tsx
+<CompareViewer
+  modelUrl="/car.glb"
+  licenseKey="your-license-key"
+  layout="side-by-side"
+  before={{ sceneConfig: { ...config, model: { ...config.model, activeVariants: ["Paint: Red"] } } }}
+  after={{ sceneConfig: { ...config, model: { ...config.model, activeVariants: ["Paint: Blue"] } } }}
+/>
+```
+
+### One camera
+
+Orbiting, panning, or zooming either side moves both. The side you last
+grabbed leads and the other copies it every frame, so a fly-in, a zoom to a
+selected object, or a refit on one side shows on both. With two different
+models, the views line up on the same point in space, so the models should
+share a coordinate system.
+
+### Props
+
+```ts
+type CompareViewerProps = Partial<ModelViewerProps> & {
+  licenseKey: string;
+  before: CompareViewerSide; // the left side
+  after: CompareViewerSide; // the right side
+  layout?: "slider" | "side-by-side"; // default "slider"
+  split?: number; // the divider, 0 (left edge) to 1; default 0.5
+  onSplitChange?: (split: number) => void;
+};
+
+type CompareViewerSide = Partial<ModelViewerProps> & {
+  label?: string; // shown over the side; default "Before" / "After"
+};
+```
+
+Every other prop is shared by both sides, and a side's own props win.
+Callbacks run per side: give `before.onObjectSelect` and
+`after.onObjectSelect` to tell the sides apart. Both sides start from the
+`minimal` [preset](#presets-and-grouped-props),
+with no panels or buttons, so their interfaces don't overlap; pass `preset`
+or `ui` to change that. Pass `split` to control the divider yourself;
+without it, `CompareViewer` keeps the position.
+
+> Each side has its own WebGL (or [WebGPU](#webgpu)) canvas. The two share one download and parse of the model file, but the GPU holds two copies of its geometry and textures.
+
+`poster`, `loading` and `reveal` work as on
+[`ModelViewer`](#lazy-loading-and-posters). With `reveal="interaction"`, one
+**View in 3D** button starts both sides.
+
+The divider and the default side labels use the
+[`labels`](https://react-immersive.liveroom.dev/docs/reference/labels) keys `compareBefore`, `compareAfter`,
+`compareDivider`, and `compareDividerValue`.
+
 ## Presets and grouped props
 
 `preset` sets `ModelViewer` up for a common kind of page:
 
 | Preset | For | What it sets |
 | --- | --- | --- |
-| `minimal` | Just the model | Hides both panels, the download and reset buttons, and tour controls |
+| `minimal` | Just the model | Hides both panels, the download and reset buttons, tour controls, and the material variant buttons |
 | `showcase` | A product on display | Everything `minimal` does, plus auto-rotation |
-| `configurator` | Customers changing parts | Shows the selected object's panel and the reset button; hides the scene objects panel and download |
-| `inspector` | Checking a model | Every panel, the view gizmo, the measure, UV checker, and exploded-view tools, and keyboard navigation |
+| `configurator` | Customers changing parts | Shows the selected object's panel, the reset button, and the material variant buttons; hides the scene objects panel and download |
+| `inspector` | Checking a model | Every panel, the view gizmo, the measure, UV checker, exploded-view, section-cut, and isolate tools, and keyboard navigation |
 
 `MODEL_VIEWER_PRESETS` lists exactly which props each preset sets.
 
@@ -981,10 +1177,10 @@ readable:
 
 | Group | Fields, and the flat prop each one sets |
 | --- | --- |
-| `ui` | `objectPanel` (`showObjectBindingDataPanel`), `sceneObjects` (`showSceneObjectsPanel`), `download` (`showDownloadButton`; a string also sets `downloadFilename`), `reset` (`showResetButton`), `loadingOverlay` (`showLoadingOverlay`), `viewGizmo` (`showViewGizmo`), `mouseController` (`showMouseController`; `{ position, opacity }` also sets `mouseControllerPosition` and `mouseControllerOpacity`), `annotationNavigation` (`showAnnotationNavigation`), `annotationOnHover` (`showAnnotationOnHover`), `highlightOnHover` |
-| `tools` | `measure` (`showMeasureTools`; `{ unit }` also sets `measurementUnit`), `uvChecker` (`showUvCheckerButton`), `explode` (`showExplodeControls`), `texturePositioning` (`texturePositioning`) |
-| `controls` | `enabled` (`enableCameraControls`), `keyboard` (`enableKeyboardNavigation`), `zoom` (the opposite of `disableZoom`), `zoomOnSelect` (`zoomOnSelected`), `autoRotate` (a number also sets `autoRotateSpeed`), `refitOnResize`, `limits` (`cameraLimits`), `moveSensitivity`, `zoomSensitivity` |
-| `perf` | `renderMode`, `maxDpr`, `profile` (`performanceProfile`), `preserveDrawingBuffer` |
+| `ui` | `objectPanel` (`showObjectBindingDataPanel`), `sceneObjects` (`showSceneObjectsPanel`), `download` (`showDownloadButton`; a string also sets `downloadFilename`), `reset` (`showResetButton`), `fullscreen` (`showFullscreenButton`), `loadingOverlay` (`showLoadingOverlay`), `viewGizmo` (`showViewGizmo`), `mouseController` (`showMouseController`; `{ position, opacity }` also sets `mouseControllerPosition` and `mouseControllerOpacity`), `annotationNavigation` (`showAnnotationNavigation`), `annotationOnHover` (`showAnnotationOnHover`), `highlightOnHover`, `materialVariants` (`showMaterialVariants`), `objectNavigator` (`showObjectNavigator`) |
+| `tools` | `measure` (`showMeasureTools`; `{ unit }` also sets `measurementUnit`), `uvChecker` (`showUvCheckerButton`), `explode` (`showExplodeControls`), `section` (`showSectionTools`), `isolate` (`showIsolateControls`), `texturePositioning` (`texturePositioning`) |
+| `controls` | `enabled` (`enableCameraControls`), `keyboard` (`enableKeyboardNavigation`), `zoom` (the opposite of `disableZoom`), `zoomOnSelect` (`zoomOnSelected`), `autoRotate` (a number also sets `autoRotateSpeed`), `refitOnResize`, `limits` (`cameraLimits`), `moveSensitivity`, `zoomSensitivity`, `reducedMotion` |
+| `perf` | `renderMode`, `maxDpr`, `profile` (`performanceProfile`), `preserveDrawingBuffer`, `webgpu` |
 | `tiles` | `url` (`tilesetUrl`), `errorTarget` (`tilesErrorTarget`), `cacheSize` (`tilesCacheSize`) |
 | `xr` | `enabled` (`enableXR`), `usdzUrl`, `scaleMode` (`arScaleMode`), `mobileHandoffUrl` |
 | `decoders` | `draco` (`dracoDecoderPath`), `ktx2` (`ktx2TranscoderPath`), `meshopt` |
@@ -1007,11 +1203,14 @@ type Props = {
   xr?: ModelViewerXrOptions;
   decoders?: ModelViewerDecoderOptions;
   modelUrl: string;
+  poster?: string;
+  loading?: "lazy" | "eager"; // default "lazy"
+  reveal?: "auto" | "interaction"; // default "auto"
   tilesetUrl?: string | null;
   tilesErrorTarget?: number;
   tilesCacheSize?: number;
   onObjectCatalog?: (objects: ViewerObjectInfo[]) => void;
-  modelFormat?: "glb" | "gltf" | "obj" | "fbx" | "usdz";
+  modelFormat?: "glb" | "gltf" | "obj" | "fbx" | "usdz" | "stl" | "ply";
   licenseKey: string;
   objectBindings?: Record<string, ObjectBinding> | "auto"; // default "auto"
   selectedObject?: ObjectBinding | null;
@@ -1029,6 +1228,8 @@ type Props = {
     controller: "orbit" | "pointerLock",
   ) => void;
   onAction?: (event: ObjectActionEvent) => void;
+  onEngagement?: (event: ViewerEngagementEvent) => void | Promise<void>;
+  debugEngagement?: boolean;
   onHiddenObjectsChange?: (next: Record<string, boolean>) => void;
   onCameraChange?: (state: ViewerCameraState) => void;
   onViewerReady?: (viewer: ViewerReadyState) => void;
@@ -1053,6 +1254,7 @@ type Props = {
   showDownloadButton?: boolean;
   downloadFilename?: string;
   showResetButton?: boolean;
+  showFullscreenButton?: boolean;
   showLoadingOverlay?: boolean;
   showMouseController?: boolean;
   mouseControllerPosition?:
@@ -1074,11 +1276,14 @@ type Props = {
   moveModeEnabled?: boolean;
   objectTransformSpace?: "local" | "world";
   enableKeyboardNavigation?: boolean;
+  showObjectNavigator?: boolean;
+  reducedMotion?: "user" | "always" | "never";
   onAutoFit?: () => Promise<boolean>;
   refitOnResize?: boolean;
   renderMode?: "always" | "demand";
   maxDpr?: number;
   preserveDrawingBuffer?: boolean;
+  webgpu?: boolean;
   performanceProfile?: "auto" | "high" | "low";
   dracoDecoderPath?: string | false;
   ktx2TranscoderPath?: string | false;
@@ -1086,6 +1291,11 @@ type Props = {
   showMeasureTools?: boolean;
   showUvCheckerButton?: boolean;
   showExplodeControls?: boolean;
+  showSectionTools?: boolean;
+  isolation?: ViewerIsolation | null;
+  onIsolationChange?: (isolation: ViewerIsolation | null) => void;
+  showIsolateControls?: boolean;
+  showMaterialVariants?: boolean;
   cinematic?: boolean | CinematicConfig;
   measurementUnit?: string;
   enableXR?: boolean;
@@ -1105,7 +1315,7 @@ type Props = {
 
 ### `modelUrl`
 
-URL or public path to a `.glb`, `.gltf`, `.obj`, `.fbx`, or `.usdz` model. Hosted GLTF, OBJ, and FBX assets must serve external buffers, MTL files, and textures at their declared relative paths. USDZ dependencies are contained in the USDZ package. Use `modelFormat` when a signed or extensionless URL cannot be auto-detected.
+URL or public path to a `.glb`, `.gltf`, `.obj`, `.fbx`, `.usdz`, `.stl`, or `.ply` model. Hosted GLTF, OBJ, and FBX assets must serve external buffers, MTL files, and textures at their declared relative paths. USDZ dependencies are contained in the USDZ package. Use `modelFormat` when a signed or extensionless URL cannot be auto-detected.
 
 Example:
 
@@ -1116,7 +1326,33 @@ modelUrl = "/model.glb";
 ### `modelFormat`
 
 Optional explicit format for signed or extensionless model URLs. Normal URLs
-ending in `.glb`, `.gltf`, `.obj`, `.fbx`, or `.usdz` are detected automatically.
+ending in `.glb`, `.gltf`, `.obj`, `.fbx`, `.usdz`, `.stl`, or `.ply` are detected automatically.
+
+### STL and PLY
+
+STL and PLY files hold geometry only: no object names, materials or
+animations.
+
+- **One object per file**, named after the file: `bracket.stl` loads as one
+  object keyed `bracket`, which its bindings use. A text STL with several named
+  solids loads one object per solid. A `.zip` holding one STL or PLY file also
+  works.
+- **Colour:** objects start a matte grey. A PLY file's vertex colours show as
+  they are, and picking a colour (or texture) replaces them.
+- **No texture coordinates:** STL files have none and PLY files rarely do, so an
+  image can't be mapped onto them. The viewer's **Change Material** says so
+  instead of offering an upload, BindingBuilder turns off its image map fields
+  for that object, and new bindings leave Change Material out. [Decals](#decals)
+  work without texture coordinates. This applies to any object without them, in
+  any format.
+- **Units and orientation:** STL files are usually in millimetres with Z up, so a
+  part can load lying on its back. Turn it upright with
+  [`sceneConfig.model.rotation`](#sceneconfig) (BindingBuilder: **Scene** →
+  model rotation, −90° on X), and set [`measurementUnit`](#measurementunit) to
+  `"mm"`. In AR, the default `"normalized"` [`arScaleMode`](#arscalemode) fits the
+  model to a metre; `"real-world"` would read millimetres as metres.
+- **PLY point clouds** (points with no faces) can't be shown; the viewer
+  explains why instead of loading them.
 
 ### 3D Tiles streaming
 
@@ -1312,6 +1548,7 @@ type ObjectPointerEvent = {
   clientX: number; // viewport coordinates
   clientY: number;
   pointerType: string; // "mouse" | "pen" | "touch"
+  surface?: { position: Vec3; normal: Vec3 }; // where on the object, in its own space
 };
 ```
 
@@ -1403,6 +1640,8 @@ count:
 type ViewerModelInfo = {
   bounds: { min: Vec3; max: Vec3; center: Vec3; size: Vec3 }; // world space
   objectCount: number; // meshes in the loaded scene
+  materialVariants: string[]; // glTF material variant names, if any
+  materialVariantGroups: MaterialVariantGroup[]; // the same, as option groups
 };
 ```
 
@@ -1450,6 +1689,60 @@ type ObjectActionEvent = {
 };
 ```
 
+### `onEngagement` / `debugEngagement`
+
+Optional interaction analytics. Set `onEngagement` to receive typed
+`ViewerEngagementEvent` objects, or set `debugEngagement` to log them in the
+browser's developer console with the `[react-immersive engagement]` prefix.
+Both are disabled by default. The viewer does not send telemetry or persist
+analytics identifiers; your callback decides where events go.
+
+```tsx
+import { ModelViewer, type ViewerEngagementEvent } from "@liveroom-tech/react-immersive";
+
+function handleEngagement(event: ViewerEngagementEvent) {
+  if (event.type === "part-viewed") {
+    console.info("Part viewed:", event.objectKey, event.source);
+  }
+  if (event.type === "ar-ended") {
+    console.info("Time in AR:", event.durationMs);
+  }
+  // Connect this callback to your application's analytics integration.
+}
+
+<ModelViewer
+  modelUrl="/car.glb"
+  licenseKey={licenseKey}
+  onEngagement={handleEngagement}
+  debugEngagement
+/>
+```
+
+Every event includes `sessionId` (an ephemeral ID for this viewer/model),
+`timestamp` (ISO format), `elapsedMs`, `modelUrl`, and `tilesetUrl` (or `null`).
+Durations use a monotonic clock and are expressed in milliseconds. Session
+elapsed time includes loading and background time; it is not an attention metric.
+
+| Event `type` | Details and trigger |
+| --- | --- |
+| `part-viewed` | `objectId`, `objectKey`, optional `label`, and `source` (`"canvas"`, `"panel"`, or `"keyboard"`). Selecting/focusing a different part; reselecting the current part is ignored. |
+| `variant-chosen` | `variant`, `previousVariant` (names, or `null` for the default), and `group` (the option group's name, or `null`). Choosing or clearing a built-in material variant; `previousVariant` is the earlier choice in the same group. |
+| `ar-started` | A confirmed immersive WebXR AR session begins. |
+| `ar-ended` | `durationMs` and `reason` (`"session-ended"` or `"interrupted"`). A confirmed AR session ends, or tracking stops on model change, unmount, or context loss. |
+| `ar-launch-requested` | `channel` (`"quick-look"` or `"mobile-handoff"`). Opening external AR or its QR handoff; this does not claim an AR session started. |
+| `tour-started` | `annotationCount`. Starting the guided tour. |
+| `tour-completed` | `annotationCount` and `durationMs`. Advancing past its final annotation; emitted once per completed tour. |
+| `tour-stopped` | `annotationCount`, `durationMs`, and `reason` (`"stopped"`, `"restarted"`, `"annotations-changed"`, or `"interrupted"`). Leaving a tour before completion. |
+
+Hover, camera motion, renders, and externally supplied selection/variant updates
+do not create engagement events. WebXR duration measures the session interval;
+Quick Look runs outside the page and has no reliable duration callback. Turning
+tracking on during an existing AR session measures from attachment. Callback
+changes do not restart timing, and synchronous or asynchronous callback failures are logged without
+interrupting the viewer. A new model or re-enabling tracking creates a new
+analytics session; WebGL recovery keeps the session ID; context loss ends active intervals
+as interrupted.
+
 ### `onViewerReady`
 
 Optional callback fired once camera controls are available and again when the
@@ -1469,7 +1762,9 @@ type ViewerReadyState = {
   objectBindings: Record<string, ObjectBinding>;
   homeCameraState: { position: Vec3; target: Vec3 } | null;
   captureImage: (options?: CaptureImageOptions) => Promise<string>;
+  captureVideo: (options?: CaptureVideoOptions) => Promise<Blob>;
   invalidate: () => void;
+  rendererBackend: "webgl" | "webgpu"; // which renderer draws; see `webgpu`
   raw: {
     controls: CameraControls; // camera-controls
     scene: Object3D | null; // three.js
@@ -1521,6 +1816,67 @@ const connection = useViewerConnection(camera, effects);
 const dataUrl = await connection.captureImage({ width: 1920, height: 1080 });
 ```
 
+`captureVideo` records one complete cinematic pass or turntable revolution and
+resolves with a video `Blob`. It is also available on `useViewerConnection` and
+`useViewer().connection`. Call it from a button handler after the model has
+finished loading and framing; ready-state callbacks run repeatedly as the camera
+moves and should not start recordings automatically.
+
+```tsx
+const viewer = useViewer();
+const abort = new AbortController();
+
+<ModelViewer {...viewer.props} cinematic showDownloadButton />;
+
+// Run in an event handler. Upload the Blob or preview it with an object URL.
+const clip = await viewer.connection.captureVideo({
+  mode: "turntable", // or "cinematic" to use the enabled camera path
+  format: "auto",    // prefers WebM; falls back to MP4. "gif" for an animated GIF
+  duration: 12,      // seconds; defaults to path timing or a 24-second orbit
+  fps: 30,          // 1–60; actual throughput depends on rendering/encoding
+  videoBitsPerSecond: 8_000_000,
+  signal: abort.signal,
+});
+// abort.abort() cancels an in-progress export and discards its data.
+```
+
+The download menu offers **Record turntable video** and, when cinematic is
+enabled, **Record cinematic video**, plus Auto/WebM/MP4/GIF format selection. A
+recording shows progress and a Cancel control. The filename and Blob MIME type
+match the encoded format; an explicitly requested unsupported format rejects
+instead of silently changing formats. With `loop: true`, a cinematic export
+includes the return segment and stops after one cycle.
+
+Recording runs in real time at the canvas's current pixel resolution, includes
+post-processing, and hides editor gizmos. It pauses cinematic playback, blocks
+viewer gestures, then restores the previous camera pose and controls on success,
+cancellation, or failure. Keep the tab visible until recording completes.
+`preserveDrawingBuffer` is unnecessary for video. No audio, HTML overlays, or
+format transcoding is included. The browser must support
+`canvas.captureStream`, and `MediaRecorder` for WebM/MP4; exports reject before framing,
+during XR, during another recording, or for durations outside (0, 300] seconds.
+
+**Animated GIF.** Pass `format: "gif"` (or pick **GIF** in the menu's format
+select) for a GIF that loops forever, for places that don't play video, such as
+email, chat, and some marketplaces:
+
+```ts
+const gif = await connection.captureVideo({
+  mode: "turntable",
+  format: "gif",
+  gifWidth: 480, // pixels; the height follows the canvas. Default 480
+  // fps defaults to 15, and a turntable to an 8-second turn
+});
+```
+
+A GIF holds 256 colours per frame and stores every frame whole, so it is much
+larger than a video of the same length and shows some banding on smooth
+gradients. Frames are taken from the same stream as a video and encoded as
+they're captured, so a long recording doesn't build up memory. Each frame lasts
+as long as it really showed, so a busy device drops frames rather than playing
+the GIF fast. `videoBitsPerSecond` doesn't apply to GIFs. The encoder
+([gifenc](https://github.com/mattdesl/gifenc)) loads only when a GIF is made.
+
 ### `onTextureUpload`
 
 Optional async callback for handling texture file uploads. When provided, the viewer calls it instead of creating a blob URL, letting consumers upload to their own storage (S3, Cloudinary, a CDN, etc.) and return a durable URL that survives page reloads.
@@ -1605,22 +1961,39 @@ Current callback shape:
 Where `AnimationControls` is:
 
 ```ts
-type AnimationPlaybackState = {
-  currentClip: string | null;
-  isPlaying: boolean;
+type AnimationPlayOptions = {
+  alongside?: boolean; // keep the clips already playing (default false: replace them)
+  fade?: number; // seconds to fade in, and to fade out the clips it replaces
+  reverse?: boolean; // play backwards, from where the clip is or from its end
+};
+
+type AnimationClipState = {
+  clip: string;
+  status: "playing" | "paused" | "finished"; // finished: a play-once clip holding its last pose
+  time: number; // seconds
+  duration: number; // seconds
   speed: number;
-  time: number; // live position of the current clip, in seconds
-  duration: number; // length of the current clip, in seconds
+  reverse: boolean;
 };
 
+type AnimationPlaybackState = {
+  currentClip: string | null; // the clip played most recently, while it's active
+  isPlaying: boolean; // whether any clip is playing
+  speed: number; // speed, position and length of currentClip
+  time: number;
+  duration: number;
+  active: AnimationClipState[]; // every active clip, most recently played last
+};
+
+// Leave out clipName to act on every active clip.
 type AnimationControls = {
   clips: string[];
   clipDetails?: { sourceName: string; duration: number }[];
-  play: (clipName: string) => void;
-  pause: () => void;
-  stop: () => void;
-  setSpeed: (speed: number) => void;
-  seek?: (time: number) => void; // scrub the current clip to an absolute time (seconds)
+  play: (clipName: string, options?: AnimationPlayOptions) => void;
+  pause: (clipName?: string) => void;
+  stop: (clipName?: string) => void; // stops and resets the pose
+  setSpeed: (speed: number, clipName?: string) => void;
+  seek?: (time: number, clipName?: string) => void; // absolute time, in seconds
   getState?: () => AnimationPlaybackState;
   subscribe?: (listener: (state: AnimationPlaybackState) => void) => () => void;
 };
@@ -1628,8 +2001,8 @@ type AnimationControls = {
 
 Wire this to `useViewerAnimations().handleAnimationsReady` for the simplest integration.
 When `sceneConfig.animations.autoplayClip` is set, `ModelViewer` will auto-play
-that clip on load and respect per-clip `loopMode`, `speed`, `displayName`, and
-soft-delete (`hidden`) settings.
+that clip on load and respect per-clip `loopMode` (`"repeat"`, `"once"`, or
+`"ping-pong"`), `speed`, `displayName`, and soft-delete (`hidden`) settings.
 
 ### Lighting
 
@@ -1679,6 +2052,81 @@ An attached light follows the object, offset from the object's origin in its
 local space (the origin is often at its base, not its center). Lighting set up
 in `BindingBuilder`'s Scene tab exports as the same `sceneConfig`.
 
+### Style rules
+
+`sceneConfig.styleRules` restyles objects from their own data while the app
+runs: a colour for a temperature, grey for a disabled part, a pulsing glow for
+an alarm. Each rule picks objects (`target`), checks their data (`when`), and
+sets a look (`material`, `colorScale`, `pulse`):
+
+```tsx
+const viewer = useViewer({
+  bindings,
+  sceneConfig: {
+    ...DEFAULT_SCENE_CONFIG,
+    styleRules: [
+      {
+        id: "temperature",
+        target: { group: "pumps" },
+        colorScale: {
+          metric: "temperature",
+          stops: [[18, "#3b82f6"], [24, "#22c55e"], [32, "#ef4444"]],
+        },
+      },
+      {
+        id: "offline",
+        when: { status: "disabled" },
+        material: { baseColor: "#9ca3af", opacity: 0.4 },
+      },
+      {
+        id: "alarm",
+        when: [{ metric: "temperature", above: 32 }, { metadata: "alarm.acknowledged", equals: false }],
+        pulse: { color: "#ff3b30", speed: 1.5 },
+      },
+    ],
+  },
+});
+
+<ModelViewer modelUrl="/plant.glb" licenseKey="your-license-key" {...viewer.props} />;
+
+// Live data: update the bindings and the looks follow.
+viewer.bindings.updateObjectBindings("pump-3", { metrics: { temperature: 34 } });
+viewer.bindings.updateObjectBindings("valve-1", { status: "disabled" });
+```
+
+- `target` takes the same targets as the binding helpers: an id, a list of
+  ids, `{ group }`, `{ tag }`, or `{ type }`. Left out, the rule considers every
+  bound object.
+- `when` is a condition, or a list that must all match; left out, the rule
+  always applies. Conditions: `{ metric, above?, below? }` (the value must be
+  greater than `above` and less than `below`; an object without the metric
+  doesn't match), `{ status }` with one status or a list (a binding without
+  one counts as `"normal"`), and `{ metadata, equals }`, where dots in the key
+  reach into nested metadata.
+- `material` accepts any `style.material` field. `colorScale` sets
+  `baseColor` (or `emissive`, with `channel: "emissive"`) from a metric,
+  blending between hex colour stops and taking the nearest stop outside them.
+  `pulse` makes the glow fade in and out (`true`, or `{ color, speed }` in
+  pulses per second).
+- Rules apply in order over each object's own `style.material`, so a later
+  rule wins where two set the same field. Hover and selection highlighting
+  still show on top.
+- Rules only change how objects look. `objectBindings`, `onObjectBindingsChange`,
+  and every callback keep the object's own values, so nothing a rule sets is
+  saved with the bindings.
+- The pulse isn't drawn on streamed 3D Tiles models (`tilesetUrl`); the other
+  looks are.
+
+BindingBuilder's Scene tab has a **Rules** sub-tab for building these rules
+visually. It suggests your groups, tags, types, metric names, and metadata
+keys, shows how many objects each rule matches right now, and previews the
+result live. Rules export and import with the rest of `sceneConfig`.
+
+`applyStyleRules(bindings, rules)` (from the main entry or `/utils`) returns
+the styled bindings, for example to colour your own list the way the viewer
+does, and `colorScaleValue(stops, value)` the colour a scale gives a value, for
+a legend.
+
 ### `camera`
 
 Optional starting camera: where it is and its lens.
@@ -1942,7 +2390,7 @@ SVG texture template per material. Meshes without a `uv` attribute are omitted;
 when the model has no UV coordinates, the viewer reports that no layout is
 available.
 
-The bottom-right action bar renders when at least one of `showResetButton`, `showDownloadButton`, or (`showAnnotationNavigation` with annotations present) is `true`.
+The bottom-right action bar renders when at least one of `showResetButton`, `showDownloadButton`, `showFullscreenButton` (when supported), or (`showAnnotationNavigation` with annotations present) is `true`.
 
 ### `downloadFilename`
 
@@ -1964,6 +2412,26 @@ Default:
 true;
 ```
 
+### `showFullscreenButton`
+
+Optional boolean that adds an enter/exit fullscreen toggle to the bottom-right
+action bar. Its grouped form is `ui.fullscreen`. Default: `false`.
+
+```tsx
+<ModelViewer
+  modelUrl="/model.glb"
+  licenseKey={licenseKey}
+  ui={{ fullscreen: true }}
+/>
+```
+
+Fullscreen expands the whole viewer, including its panels and overlays. The
+button reflects browser exits such as Escape, and is hidden when fullscreen is
+unavailable. It is temporarily disabled during video recording. Embedded viewers
+need an iframe with `allow="fullscreen"` (or `allowFullScreen` in React). A rejected
+request displays an error beside the button; see the
+[Fullscreen API permissions](https://developer.mozilla.org/en-US/docs/Web/API/Element/requestFullscreen#security).
+
 ### `showLoadingOverlay`
 
 Optional boolean controlling whether the built-in loading overlay is shown while the model is loading and the initial camera fit is settling, and the load-error message if the model fails to load (see [`onLoadError`](#onloaderror)).
@@ -2199,13 +2667,76 @@ Enables automatic orbiting and controls its speed. Defaults are `false` and
 <ModelViewer {...props} autoRotate autoRotateSpeed={0.75} />
 ```
 
+Auto-rotate doesn't start for visitors who ask their device to reduce motion.
+See [`reducedMotion`](#reducedmotion).
+
 ### `enableKeyboardNavigation`
 
 Optional boolean enabling camera shortcuts after the viewer canvas is clicked
 or focused. Default: `false`. Use `W`/`S` to move forward/back, `A`/`D` to
 truck left/right, Space/`C` to move up/down, and the arrow keys to orbit.
 `Shift` + Up/Down moves forward/back. Keyboard navigation is inactive while
-object editing or camera controls are disabled.
+object editing or camera controls are disabled. While the canvas has focus, a
+screen reader reads out what its keys do (the `cameraKeyboardHelp` label).
+
+### Accessibility
+
+The viewer can be used without a mouse, and reads out what is happening:
+
+- **Moving through objects with the keyboard.** Tabbing into the viewer reaches
+  a small object list at the top of the canvas, shown only while it has focus.
+  The arrow keys (or `Home` and `End`) move through the objects and highlight
+  each one in the scene. Typing a letter jumps to an object whose name starts
+  with it. `Enter` or Space selects the object, exactly as clicking it would,
+  and `Escape` clears the selection. Screen readers hear each object's name and
+  its position ("Wheel, 3 of 12"). The list follows the scene objects panel's
+  order. It skips hidden objects, and objects an isolation has set aside.
+- **Announcing the selection.** Every change of selection is announced, whether
+  it came from a click, the keyboard, the objects panel, or your app ("Wheel
+  selected", "Selection cleared").
+- **The scene objects panel.** Each row is a button, so the panel can be used
+  from the keyboard too. Focusing a row highlights its object, and the
+  visibility buttons name the object they hide or show.
+- **Reduced motion.** See [`reducedMotion`](#reducedmotion) below.
+
+All of this text can be translated with `labels`.
+
+### `showObjectNavigator`
+
+Optional boolean for the keyboard object list described above. Default: `true`.
+It takes no space until a keyboard user reaches it, so it's on by default. Set it
+to `false` when your app provides its own way to choose objects from the
+keyboard. It is hidden while measuring, since clicks then place points instead
+of selecting. Keyboard selections reach `onEngagement` as `part-viewed` events
+with `source: "keyboard"`.
+
+```tsx
+<ModelViewer {...props} ui={{ objectNavigator: false }} />
+```
+
+### `reducedMotion`
+
+Cuts motion the viewer starts on its own, for visitors who find it hard to
+watch. Default: `"user"`, which follows the visitor's device setting
+(`prefers-reduced-motion`). `"always"` and `"never"` override it. Also
+`controls.reducedMotion`; the type is exported as `ReducedMotionSetting`.
+
+When motion is reduced:
+
+- Auto-rotate doesn't start.
+- A `cinematic` path with `autoPlay` waits for its play button.
+- Camera moves jump straight to where they're going instead of gliding: the
+  first framing, focusing a selected object, resetting the view, saved views,
+  guided-tour stops, and moves made through `useViewerCamera`.
+- Panels, menus and popups appear in place instead of sliding or fading in.
+  Loading spinners keep turning, since they show that something is still
+  happening.
+
+Motion the visitor asks for still plays: the cinematic play button, video
+export, and dragging the camera. The viewer doesn't change animations your app
+starts, such as model clips, effects, or style rule pulses. To respect the
+setting there too, check `matchMedia("(prefers-reduced-motion: reduce)")` in
+your app. `SimpleModelViewer` takes the same prop.
 
 ### `showViewGizmo`
 
@@ -2228,6 +2759,8 @@ Current callback shape:
 
 Optional boolean controlling whether the camera re-frames the model to fit whenever the canvas is resized, a browser window resize, a device rotation, or a side panel opening/closing (which changes how much width the canvas has). Set to `false` to preserve the user's current orbit/zoom across resizes; the camera aspect stays correct either way, so the model never distorts, it just isn't re-centered. This only affects re-fits _after_ the initial mount-time auto-fit.
 
+While a selected object is framed (see `zoomOnSelected`), a resize frames that object again rather than the whole model, so the object panel opening doesn't undo the zoom. An object with an authored `cameraState` keeps that view. Once the selection is cleared, or something else moves the camera away from the object, resizes frame the whole model again.
+
 Default:
 
 ```ts
@@ -2293,6 +2826,89 @@ Default:
 false;
 ```
 
+### `webgpu`
+
+Optional boolean. Draws with three.js's WebGPU renderer when the browser has
+WebGPU, and with WebGL otherwise. Default: `false`. Also `perf.webgpu`.
+
+```tsx
+<ModelViewer {...props} perf={{ webgpu: true }} />
+```
+
+The viewer asks the browser for a WebGPU adapter once per page before
+creating its canvas. Without one, it uses WebGL and says so once in the
+console. `onViewerReady` reports which renderer is drawing as
+`rendererBackend` (`"webgl"` or `"webgpu"`). The WebGPU renderer is loaded only
+by viewers that use it.
+
+With WebGPU, the model, materials, bindings, hover highlight, picking,
+animations, decals, annotations, measurement, video and GIF export, and tone
+mapping and exposure work as they do with WebGL. Some features are built on
+WebGL and are left out:
+
+- The post-processing effects (outline, bloom, depth of field, and the rest)
+  don't draw. Tone mapping and exposure from `sceneConfig.postProcessing` still
+  apply, through the renderer.
+- Contact shadows (`sceneConfig.groundShadows` in shadow-catcher mode) don't
+  draw.
+- The section cut and the move gizmo (`moveModeEnabled`) aren't available, and
+  the console says so if they're asked for.
+- AR and VR sessions in the browser (WebXR) aren't offered. Quick Look on iOS
+  and the phone hand-off still work.
+- Measurement lines are one pixel wide.
+
+`captureImage` and the Download PNG action work with WebGPU without
+`preserveDrawingBuffer`. A lost WebGPU device shows the same **Reload viewer**
+message as a lost WebGL context.
+
+### Lazy loading and posters
+
+`loading`, `poster` and `reveal` decide when a viewer creates its 3D view, and
+what shows in its place until then. They matter most on pages with many
+viewers, such as a product grid: browsers allow a page about 16 WebGL contexts
+and take the oldest away past that.
+
+```tsx
+<ModelViewer {...props} poster="/chair.webp" />
+<ModelViewer {...props} poster="/chair.webp" reveal="interaction" />
+```
+
+`loading` is `"lazy"` by default. A lazy viewer:
+
+- starts its 3D view when it comes within about 200px of the screen. One that's
+  on the screen when the page loads starts at once.
+- shares the page's live 3D views with the other lazy viewers: at most 12, or 6
+  on phones and tablets. Viewers on the screen come first. One scrolled away
+  from keeps its view while there's room, so coming back is instant. When the
+  room is needed, it's put away, leaving a picture of its last frame, and is
+  built again when it comes back near the screen.
+- comes back as it was: the camera, picked variants, light and section-cut
+  changes, isolation, the exploded view, the camera controller, the UV checker,
+  the annotation filter, and, when the viewer keeps `objectBindings` itself,
+  the changes made to them. The selection and open panels don't come back. `onModelLoaded` and
+  `onViewerReady` run again, with a new viewer.
+- stops drawing while it's off the screen, and starts again when it's back.
+  Browsers already stop drawing in hidden tabs.
+
+`loading="eager"` starts the 3D view at once and keeps it. Eager viewers don't
+count towards the 12. `BindingBuilder`'s preview is eager.
+
+`poster` is an image shown in the viewer's place until its 3D view is drawn,
+then fades out; the loading message shows over it. It's fitted inside the
+viewer. To fill the viewer instead, set the CSS variable
+`--ri-poster-fit: cover` on a parent. A render of the model framed as the
+viewer frames it works best: [`captureImage`](#onviewerready) can make one.
+
+`reveal="interaction"` keeps the poster, with a **View in 3D** button, until the
+visitor presses it, so only the products someone picks use a 3D view. The
+button's text is the [`labels`](https://react-immersive.liveroom.dev/docs/reference/labels)
+key `viewIn3D`. `reveal` is `"auto"` by default: the view starts on its own.
+
+The same three props work on [`SimpleModelViewer`](#simplemodelviewer-public-api)
+and [`CompareViewer`](#compareviewer).
+
+---
+
 ### `performanceProfile`
 
 Optional control over how aggressively the viewer trades visual fidelity for a stable WebGL context on constrained GPUs.
@@ -2311,6 +2927,20 @@ Default:
 "auto";
 ```
 
+If the WebGL context is lost, rendering pauses and the viewer displays a
+**Reload viewer** button. This message appears even with
+`ui={{ loadingOverlay: false }}`. When the browser fires `webglcontextrestored`,
+the viewer automatically rebuilds its canvas and scene; the reload button starts
+the same rebuild without waiting for browser restoration.
+
+Recovery uses the current props and cached model assets, and cancels video
+recording. The rebuilt viewer keeps its camera and the visitor's changes, as a
+lazy viewer does when it comes back (see
+[Lazy loading and posters](#lazy-loading-and-posters)); the selection,
+measurements and playback start over.
+`onSceneLoaded`, `onModelLoaded`, `onAnimationsReady`, and `onViewerReady` run again
+for the rebuilt scene, so integrations receive fresh controls and object refs.
+
 ### `dracoDecoderPath` / `ktx2TranscoderPath` / `meshopt`
 
 Optional controls for the compressed-asset decoders used when loading the GLB/GLTF asset.
@@ -2375,7 +3005,33 @@ false;
 
 ### `showMeasureTools`
 
-Optional boolean that shows a click-to-measure toolbar over the canvas: click two points on the model for a distance readout, plus a toggleable bounding-box dimensions overlay.
+Optional boolean that shows measurement tools and a toggleable bounding-box
+dimensions overlay. Start measuring, then choose a tool:
+
+- **Distance:** pick points for distances between consecutive picks.
+- **Angle:** pick an arm, the angle's vertex, and the other arm. The readout is
+  in degrees, with an arc around the middle pick.
+- **Area:** pick polygon corners in boundary order, then **Finish area**. The
+  closed polygon is shaded and labeled in square units. Concave polygons are
+  supported; nonplanar, crossing, touching, duplicate, or collinear boundaries
+  show an error. Use Undo to correct a pick.
+- **Point to plane:** pick a reference face, then a point. The tool highlights
+  the picked triangle and shows the shortest distance to its infinite plane,
+  with a perpendicular segment to the projected point.
+
+**No snapping** keeps picks on the surface. **Snap: vertex**, **Snap: edge**,
+and **Snap: auto** snap within 12 CSS pixels to vertices or triangle edges on
+the picked face. Auto prioritizes nearby vertices. Hover markers identify the
+snap target; snapped picks are yellow. Snapping respects world transforms,
+instances, and the current pose of skinned/morph geometry. Mesh triangulation
+edges can also be snap targets.
+
+Undo removes the last pick; Clear removes the current measurement. Switching
+tools clears picks. A new pick after a completed angle, area, or point-to-plane
+measurement starts another measurement. Picks are snapshots in world space;
+model changes, display rotation, and binding transforms clear them. Pause
+animated models before measuring a pose. Hidden objects, decals, and editor
+helpers are excluded from picking.
 
 Default:
 
@@ -2385,7 +3041,10 @@ false;
 
 ### `measurementUnit`
 
-Optional unit suffix appended to measurement readouts. glTF models are authored in meters by spec, so values are not converted, this only changes the displayed label.
+Optional unit suffix appended to distance and dimension readouts; area uses its
+squared form (for example `m²`). Angles always use degrees. glTF models are
+authored in meters by spec, so values are not converted; this only changes the
+displayed label.
 
 Default:
 
@@ -2403,6 +3062,272 @@ Default:
 false;
 ```
 
+### `showMaterialVariants`
+
+Shows swatch buttons, centered at the bottom of the viewer, for switching
+between the model's glTF material variants (the `KHR_materials_variants`
+extension): the colorways, finishes, or trims a product file ships with. Each
+button shows the variant's colour when its material is a plain colour. It
+appears for a glTF/GLB with any variants. Default `true`.
+
+Variants come in **option groups**, one row each. Choosing a variant replaces
+the other choice in its row and keeps the other rows, so a paint colour and a
+wheel style combine. Clicking the chosen variant again returns that row to the
+file's default materials. The viewer works out the groups from the file:
+
+- A name like `"Paint: Red"` or `"Paint / Red"` puts the variant in a row
+  labelled **Paint**, with a button labelled **Red**.
+- Otherwise, variants that restyle the same parts share a row, and variants
+  that restyle different parts get separate rows. A shoe's `"midnight"`,
+  `"beach"` and `"street"` colorways, which all restyle the same parts, are one
+  row.
+
+The variants shown are `sceneConfig.model.activeVariants`, at most one from
+each group, which is also how you choose them yourself:
+
+```tsx
+import { chooseMaterialVariant, useViewer } from "@liveroom-tech/react-immersive";
+
+const viewer = useViewer();
+
+<ModelViewer modelUrl="/car.glb" licenseKey="your-license-key" {...viewer.props} />;
+
+// Once the model has loaded
+viewer.model.materialVariants; // ["Paint: Red", "Paint: Blue", "Wheels: Sport", "Wheels: Classic"]
+viewer.model.materialVariantGroups;
+// [
+//   { name: "Paint", variants: [{ name: "Paint: Red", label: "Red", swatch: "#ff0000" }, ...] },
+//   { name: "Wheels", variants: [{ name: "Wheels: Sport", label: "Sport" }, ...] },
+// ]
+
+viewer.scene.updateSceneConfig({ model: { activeVariants: ["Paint: Red", "Wheels: Sport"] } });
+viewer.scene.updateSceneConfig({ model: { activeVariants: [] } }); // the defaults
+
+// Your own swatches: swap a choice within its group, keeping the others.
+const active = viewer.scene.sceneConfig.model.activeVariants ?? [];
+viewer.scene.updateSceneConfig({
+  model: {
+    activeVariants: chooseMaterialVariant(active, "Paint: Blue", viewer.model.materialVariantGroups),
+  },
+});
+```
+
+- A variant sets each object's starting material. `objectBindings` material
+  overrides (`style.material`) still apply on top of it, and clearing an
+  override returns to the variant's material rather than the file's default.
+- Objects no active variant maps keep their default material, bound or not.
+  If two active variants map the same object, the later one in the list wins.
+- A variant's materials and textures load the first time it's chosen; the
+  current look stays until they're ready.
+- With `onSceneConfigChange`, a pick goes to your scene config (`useViewer`
+  wires this up). Without it, `ModelViewer` keeps the picks itself until
+  `sceneConfig.model.activeVariants` or `modelUrl` changes.
+- A name the model doesn't have is skipped with a console warning listing the
+  model's variants.
+- An action can switch variants with a scene-config effect:
+  `{ sceneConfig: { model: { activeVariants: ["Paint: Red"] } } }`.
+- Swatches use the colour of the material a variant puts on the most vertices.
+  A textured material gets no swatch, just its label, so showing the buttons
+  never loads textures.
+- Each pick reaches [`onEngagement`](#onengagement--debugengagement) as a
+  `variant-chosen` event with its `group`.
+- `onModelLoaded` reports `materialVariants` and `materialVariantGroups`, and
+  BindingBuilder's Scene tab (**General**, one select per group) picks the
+  variants the exported scene config starts with. OBJ, FBX, USDZ, STL, PLY, and
+  streamed 3D Tiles models have no variants.
+- Scene configs saved before option groups, with a single
+  `model.materialVariant`, still show that variant.
+
+### Decals
+
+`binding.decals` prints images and text onto an object's surface: a logo on a
+shirt, a name on a mug, a label on a machine. Each decal is projected onto the
+object and follows it as it moves, and it's saved with the binding like any
+other edit.
+
+```tsx
+const viewer = useViewer();
+
+<ModelViewer
+  modelUrl="/mug.glb"
+  licenseKey="your-license-key"
+  {...viewer.props}
+  // Put the customer's text where they double-click.
+  onObjectDoubleClick={({ binding, surface }) => {
+    if (!surface) return;
+    viewer.bindings.addDecal(binding.id, {
+      text: customerName,
+      color: "#1e293b",
+      ...surface, // position and normal, in the object's own space
+      size: 0.06, // width in model units
+    });
+    return true; // skip the viewer's own double-click behavior
+  }}
+/>;
+
+const id = viewer.bindings.addDecal("mug", { image: "/logos/acme.png", position, normal, size: 0.05 });
+viewer.bindings.updateDecal("mug", id, { size: 0.08, rotation: Math.PI / 12 });
+viewer.bindings.removeDecal("mug", id);
+```
+
+```ts
+type ObjectBindingDecal = {
+  id: string;
+  image?: string; // a URL or public path
+  text?: string; // shown when there's no image
+  color?: string; // text colour, default "#ffffff"
+  fontFamily?: string; // CSS font family, default "sans-serif"
+  fontWeight?: "normal" | "bold"; // default "bold"
+  position: [number, number, number]; // on the object, in its own space
+  normal: [number, number, number]; // the way the surface faces there
+  size: number; // width in model units; the height follows the image or text
+  rotation?: number; // radians around the normal, default 0
+  opacity?: number; // 0–1, default 1
+};
+```
+
+- `onObjectDoubleClick` and `onObjectContextMenu` report `surface`: the point
+  under the pointer and the way the surface faces, in the object's own space,
+  which is exactly what a decal's `position` and `normal` take.
+- `addDecal` returns the decal's id (pass your own `id` to choose it), and
+  takes the same targets as the other binding helpers, so
+  `addDecal({ group: "panels" }, …)` prints on each. Decals are plain binding
+  data: you can also set `decals` directly.
+- A decal wraps onto the surface around its position, reaching about half
+  its size in depth, so it follows gentle curves without printing on the far
+  side of a thin part.
+- A decal fades with its object when that object is ghosted by isolation or
+  made see-through by a style rule, and is cut by a section cut.
+- To let the people using your viewer add their own, give a binding the
+  built-in `add-text` and `add-image` actions:
+
+  ```ts
+  actions: [
+    { id: "add-text", label: "Add Text", type: "command" },
+    { id: "add-image", label: "Add Image", type: "command" },
+  ]
+  ```
+
+  Each opens a control under its button in the object panel. **Add Text**
+  takes the text and a colour; **Add Image** takes an image file (sent through
+  `onTextureUpload` when you pass it, so the saved URL lasts; otherwise a
+  blob URL for this session). The decal appears automatically at the centre
+  of the camera-facing surface, ready to drag, resize, turn, or remove. **Move** enables dragging across
+  the object's surface; release to save, or press Escape to cancel. The
+  **Position** arrows move a decal in small steps relative to the current
+  view, without needing to grab it. Click for a fine adjustment or hold an
+  arrow for continuous movement. Each step stays on the nearby visible surface.
+  Every change is saved to the
+  binding's `decals` and reported through `onObjectBindingsChange`. While a
+  decal is in Move mode, a hint shows over the viewer and Escape cancels
+  the current drag without removing the centred decal.
+- On a rigged (skinned) mesh a decal bends with the animation: it takes on
+  the bone weights of the surface under it and is driven by the same skeleton.
+  A click on a posed mesh is stored at the matching point of its rest shape, so
+  a decal lands where you clicked whatever pose the model is in. Over a joint
+  that bends sharply across few polygons, the decal's outer edge can sit a
+  hair off the surface. Decals don't follow morph targets (blend shapes).
+- Decals need the binding's object to be a mesh, and aren't drawn on streamed
+  3D Tiles models.
+
+### Isolating objects
+
+`isolation` focuses the view on some objects: everything else is ghosted
+(drawn faintly) or hidden, and clicks and hovers pass through to what's
+isolated. Nothing about the bindings changes, and clearing the isolation puts
+everything back. It's view state, like the selection, so it isn't part of
+`sceneConfig`.
+
+```tsx
+const viewer = useViewer();
+
+<ModelViewer
+  modelUrl="/engine.glb"
+  licenseKey="your-license-key"
+  {...viewer.props}
+  tools={{ isolate: true }}
+/>;
+
+viewer.isolation.isolate({ group: "gearbox" }); // ghost everything else
+viewer.isolation.isolate(["piston-1", "piston-2"], { mode: "hide" });
+viewer.isolation.clearIsolation();
+```
+
+```ts
+type ViewerIsolation = {
+  target: ObjectBindingTarget; // an id, a list of ids, { group }, { tag }, or { type }
+  mode?: "ghost" | "hide"; // default "ghost"
+  ghostOpacity?: number; // 0–1, default 0.12
+};
+
+isolation?: ViewerIsolation | null;
+onIsolationChange?: (isolation: ViewerIsolation | null) => void;
+showIsolateControls?: boolean; // tools.isolate
+```
+
+- Pass `isolation` (including `null`) to control it, and update it from
+  `onIsolationChange`; `useViewer` wires both, as `viewer.isolation`. Leave
+  `isolation` out and `ModelViewer` keeps it itself, clearing it when
+  `modelUrl` changes. `useViewerIsolation` is the same state on its own.
+- `showIsolateControls` (`tools.isolate`, default `false`) adds an isolate
+  button to each row of the scene objects panel (click again to show all) and
+  a "Show all" pill at the bottom of the viewer while anything is isolated.
+- An action can isolate with an `isolation` effect:
+  `{ isolation: { target: { group: "engine" } } }`, or `{ isolation: null }`
+  to show everything again. Pass `isolation` to `useViewerActions` for it
+  (`useViewer` does).
+- A target that matches no object isolates nothing, rather than fading out
+  the whole model. Ghosting never raises an object's own lower opacity, and
+  style rules still apply underneath.
+- `applyIsolation` (main entry and `/utils`) applies an isolation to bindings
+  the same way, for rendering your own lists.
+
+### `showSectionTools`
+
+Shows a section-cut button over the canvas (`tools.section`). It cuts the model
+open along an axis, hiding everything on one side of a plane, to look inside
+assemblies, equipment, and buildings. Default `false`. Not available with
+[`webgpu`](#webgpu).
+
+With the cut on, the toolbar picks the axis (X, Y, or Z), the position along
+it, and which side stays, and a plane appears across the model that you can
+drag. The cut is stored in `sceneConfig.section`, so you can also set it
+yourself, author it in BindingBuilder, or switch it from an action:
+
+```tsx
+viewer.scene.updateSceneConfig({
+  section: { enabled: true, axis: "y", position: 0.4, flip: false }, // a floor-plan cut
+});
+```
+
+```ts
+type SceneSectionConfig = {
+  enabled: boolean;
+  axis: "x" | "y" | "z"; // world axis the cut runs across
+  position: number; // 0 at the model's minimum along the axis, 1 at its maximum
+  flip: boolean; // keep the higher side instead of the lower one
+};
+```
+
+- The cut applies to the model only; lights, helpers, and gizmos stay whole.
+  It also shows without the toolbar whenever `sceneConfig.section.enabled` is
+  set; the draggable plane appears only with `showSectionTools`.
+- While the cut is on, the model's materials render both sides of each
+  surface, so a cut part shows its inside surfaces instead of disappearing.
+  There are no solid caps over the cut.
+- Clicking and hovering ignore whatever is cut away, so the parts you can see
+  behind the cut are the ones you select.
+- Toolbar changes go to `onSceneConfigChange` when you pass it (`useViewer`
+  does); otherwise `ModelViewer` keeps them until `sceneConfig.section` or
+  `modelUrl` changes.
+- The measuring tool can still pick points on the hidden side of a cut.
+
+Default:
+
+```ts
+false;
+```
+
 ### `cinematic`
 
 Optional cinematic auto-camera. The camera glides along a path on its own, like a film, ideal for showing off a gallery, apartment, or product with no user interaction. Renders a play/pause button over the canvas; grabbing the camera (or selecting a part) pauses it.
@@ -2414,7 +3339,7 @@ type CinematicConfig = {
   waypoints?: CinematicWaypoint[]; // camera keyframes to glide through
   duration?: number; // seconds for one full pass (auto-scales when omitted)
   loop?: boolean; // default true
-  autoPlay?: boolean; // start once the model has loaded and framed (default false)
+  autoPlay?: boolean; // start once the model has loaded and framed (default false); waits for the play button under reduced motion
 };
 
 type CinematicWaypoint = {
@@ -2562,7 +3487,10 @@ See the full variable list in the [`ModelViewer` docs](https://react-immersive.l
 ```ts
 type SimpleModelViewerProps = {
   modelUrl: string;
-  modelFormat?: "glb" | "gltf" | "obj" | "fbx" | "usdz";
+  poster?: string; // see ModelViewer's poster
+  loading?: "lazy" | "eager"; // default "lazy"
+  reveal?: "auto" | "interaction"; // default "auto"
+  modelFormat?: "glb" | "gltf" | "obj" | "fbx" | "usdz" | "stl" | "ply";
   dracoDecoderPath?: string | false;
   ktx2TranscoderPath?: string | false;
   meshopt?: boolean;
@@ -2574,6 +3502,7 @@ type SimpleModelViewerProps = {
   highlightOnHover?: boolean;
   showLoadingOverlay?: boolean;
   refitOnResize?: boolean;
+  reducedMotion?: "user" | "always" | "never"; // see ModelViewer's reducedMotion
   // Initial values for the scene settings (environment) panel
   backgroundEnabled?: boolean;
   autoRotate?: boolean;
@@ -2592,13 +3521,21 @@ type SimpleModelViewerProps = {
 
 ### `modelUrl`
 
-URL or public path to the `.glb`, `.gltf`, `.obj`, `.fbx`, or `.usdz` model to inspect. Hosted assets must serve external dependencies at their declared relative paths; USDZ dependencies are packaged internally. Use `modelFormat` when a signed or extensionless URL cannot be auto-detected.
+URL or public path to the `.glb`, `.gltf`, `.obj`, `.fbx`, `.usdz`, `.stl`, or `.ply` model to inspect. Hosted assets must serve external dependencies at their declared relative paths; USDZ dependencies are packaged internally. Use `modelFormat` when a signed or extensionless URL cannot be auto-detected.
 
 ### `modelFormat`
 
 Optional explicit format for signed or extensionless model URLs. Normal URLs
 ending in a supported extension are detected automatically.
 
+### `poster` / `loading` / `reveal`
+
+Work as on [`ModelViewer`](#lazy-loading-and-posters), sharing the same
+page-wide count of live 3D views. When a `SimpleModelViewer` is put away, only
+its canvas goes: the panels and their settings stay, and the canvas comes back
+with its camera, hidden objects and selection.
+`onModelLoaded` runs again when it does.
+
 ### `backgroundColor`
 
 Optional canvas background color.
@@ -2700,7 +3637,7 @@ true;
 
 ### `enableModelUpload`
 
-Optional boolean that swaps the fixed `modelUrl` workflow for a built-in upload UI. It accepts `.glb`, standalone/data-URI `.gltf`, `.obj`, `.fbx`, `.usdz`, or a `.zip` bundle. ZIP bundles may contain a GLTF with its buffers/textures, an OBJ with its optional MTL/textures, or an FBX with external textures. A USDZ file is already a self-contained package and is uploaded directly.
+Optional boolean that swaps the fixed `modelUrl` workflow for a built-in upload UI. It accepts `.glb`, standalone/data-URI `.gltf`, `.obj`, `.fbx`, `.usdz`, `.stl`, `.ply`, or a `.zip` bundle. ZIP bundles may contain a GLTF with its buffers/textures, an OBJ with its optional MTL/textures, or an FBX with external textures. A USDZ file is already a self-contained package and is uploaded directly.
 
 Default:
 
@@ -2762,6 +3699,7 @@ type ObjectBinding = {
   hoverable?: boolean;
   transform?: ObjectBindingTransform;
   style?: ObjectBindingStyle;
+  decals?: ObjectBindingDecal[];
   actions?: ObjectBindingAction[];
   metrics?: Record<string, number>;
   metadata?: Record<string, unknown>;
@@ -2789,9 +3727,9 @@ Notes:
 
 ## Supported Built-In Actions
 
-`ModelViewer` handles six action ids itself: `change-color`,
-`change-material`, `toggle-visibility`, `toggle-light`, `change-light-color`,
-and `set-brightness`. Any other id does something only when you handle it in
+`ModelViewer` handles eight action ids itself: `change-color`,
+`change-material`, `add-text`, `add-image`, `toggle-visibility`,
+`toggle-light`, `change-light-color`, and `set-brightness`. Any other id does something only when you handle it in
 `onAction` (pass `useViewerActions().handleAction` there to run an action's
 declared `effects`). If a binding has such an action and `ModelViewer` has no
 `onAction`, its button does nothing, and the viewer logs a console warning
@@ -2809,6 +3747,10 @@ findCatalogAction("toggle-light")?.handling; // "viewer"
 
 ### Implemented behaviors
 
+- `add-text`
+  Opens a text box and colour inline beneath the action; the text appears at the centre of the camera-facing surface, ready to drag, resize, turn, or remove. Saved to `binding.decals` (see [Decals](#decals))
+- `add-image`
+  Opens an image chooser inline beneath the action; the image is placed and edited the same way. Uses `onTextureUpload` for a durable URL when provided, otherwise a session-scoped blob URL
 - `toggle-visibility`
   Hides or shows the selected mesh by setting `binding.visible` and calling `onObjectBindingsChange`
 - `change-color`
@@ -2882,8 +3824,8 @@ To use this library successfully, your model asset should follow these expectati
 - the mesh node names must match the keys in `objectBindings` (or be referenced via `modelObjectId`)
 - target nodes should have geometry and a supported Three.js mesh material; imported materials are normalized into the editable PBR pipeline
 - the file should be accessible from the browser at `modelUrl`; hosted GLTF, OBJ, and FBX assets must also serve external dependencies at their declared relative paths
-- OBJ does not contain animations; supported FBX and USDZ animation clips are exposed through the same animation controls as glTF
-- OBJ has no standard unit metadata, so set an appropriate measurement label/scene scale when real-world dimensions matter
+- OBJ, STL, and PLY do not contain animations; supported FBX and USDZ animation clips are exposed through the same animation controls as glTF
+- OBJ, STL, and PLY have no standard unit metadata, so set an appropriate measurement label/scene scale when real-world dimensions matter
 
 If a node name or material name does not match, that object will not render through the interactive binding flow.
 
@@ -2923,3 +3865,32 @@ Two related picking notes that apply to models of every size:
 ## License
 
 Proprietary, see [LICENSE](./LICENSE). Installing the package does not itself grant a right to use it in production; a valid `licenseKey` from the [Developer Portal](https://react-immersive.liveroom.dev) is required, and usage is bound to the terms of your license tier.
+
+### Rich annotations
+
+`sceneConfig.annotations` supports optional `cameraView` (position, target,
+orbit angles, fov and zoom), `images: [{ src, alt }]`, `links: [{ href, label }]`,
+`category`, and `minDistance` / `maxDistance` in scene units. BindingBuilder's
+Annotations tab authors these fields; new markers use automatic close-up tour
+framing. Explicitly capture a camera view for custom framing. Marker selection
+and guided tours restore saved views when provided. The viewer's category chips
+filter markers and tour steps.
+Use `annotationCategories` (`null` = all, `[]` = none) and
+`onAnnotationCategoriesChange` for controlled filtering, and
+`ui.annotationFilters: false` to hide the built-in chips. Distance limits affect
+markers only, so their content remains available through tours. Images stay at
+their HTTP(S) or relative URLs and are not bundled into exports automatically.
+
+## Translatable viewer text
+
+Both viewers accept a partial `labels` dictionary. Omitted keys use English; changing labels updates text without reloading the model. Named placeholders such as `{count}` can be reordered in translations.
+
+```tsx
+<ModelViewer
+  licenseKey="your-license-key"
+  modelUrl="/car.glb"
+  labels={{ guidedTour: "Visite guidée", tapToPlace: "Touchez pour placer", visibleEntries: "{count} éléments visibles" }}
+/>
+```
+
+`ModelViewerLabels`, `ModelViewerLabelKey`, and `DEFAULT_MODEL_VIEWER_LABELS` are exported from the main package, `/simple-model-viewer`, and `/utils`. See the [full catalog](https://react-immersive.liveroom.dev/docs/reference/labels). Annotation content, metadata, and custom panels use your application's translations.