@liveroom-tech/react-immersive 5.1.0 → 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,18 +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`
-- glTF material variants (`KHR_materials_variants`) with a built-in picker through `showMaterialVariants`, selected by `sceneConfig.model.materialVariant`
+- 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`, using browser-supported WebM/MP4 encoding
+- 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
+- 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
@@ -97,8 +103,8 @@ It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectBindi
 
 `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.)
@@ -112,8 +118,8 @@ It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectBindi
 
 `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
@@ -763,8 +769,9 @@ 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
@@ -778,7 +785,8 @@ 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
-- pick which of the model's glTF material variants the scene starts with, exported as `sceneConfig.model.materialVariant`
+- 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`
@@ -794,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`
@@ -813,7 +821,7 @@ A locked feature renders in place (not hidden) with a message naming the require
 
 ## `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:
 
@@ -900,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
@@ -1000,6 +1062,90 @@ 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:
@@ -1031,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`), `fullscreen` (`showFullscreenButton`), `loadingOverlay` (`showLoadingOverlay`), `viewGizmo` (`showViewGizmo`), `mouseController` (`showMouseController`; `{ position, opacity }` also sets `mouseControllerPosition` and `mouseControllerOpacity`), `annotationNavigation` (`showAnnotationNavigation`), `annotationOnHover` (`showAnnotationOnHover`), `highlightOnHover`, `materialVariants` (`showMaterialVariants`) |
+| `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` |
-| `perf` | `renderMode`, `maxDpr`, `profile` (`performanceProfile`), `preserveDrawingBuffer` |
+| `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` |
@@ -1057,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;
@@ -1127,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;
@@ -1163,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:
 
@@ -1174,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
 
@@ -1463,6 +1641,7 @@ 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
 };
 ```
 
@@ -1546,8 +1725,8 @@ 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"` or `"panel"`). Selecting/focusing a different part; reselecting the current part is ignored. |
-| `variant-chosen` | `variant` and `previousVariant` (names or `null` for the default). Choosing a different built-in material variant. |
+| `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. |
@@ -1585,6 +1764,7 @@ type ViewerReadyState = {
   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
@@ -1651,7 +1831,7 @@ const abort = new AbortController();
 // 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
+  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,
@@ -1661,7 +1841,7 @@ const clip = await viewer.connection.captureVideo({
 ```
 
 The download menu offers **Record turntable video** and, when cinematic is
-enabled, **Record cinematic video**, plus Auto/WebM/MP4 format selection. A
+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
@@ -1671,11 +1851,32 @@ 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,
-GIF encoding, or format transcoding is included. The browser must support
-`canvas.captureStream` and `MediaRecorder`; exports reject before framing,
+`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.
@@ -2466,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`
 
@@ -2495,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
@@ -2560,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.
@@ -2584,9 +2933,11 @@ If the WebGL context is lost, rendering pauses and the viewer displays a
 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, cancels video recording,
-and resets transient viewer state (camera, selection, measurements, and playback).
-Keep configuration edits in controlled props to retain them across a rebuild.
+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.
 
@@ -2713,43 +3064,79 @@ false;
 
 ### `showMaterialVariants`
 
-Shows a row of buttons, centered at the bottom of the viewer, for switching
+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. It
-appears only for a glTF/GLB with more than one variant. Default `true`.
+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:
 
-Picking a variant sets `sceneConfig.model.materialVariant`, which is also how
-you choose one yourself:
+- 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="/shoe.glb" licenseKey="your-license-key" {...viewer.props} />;
+<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" }, ...] },
+// ]
 
-// The model's variant names, once it has loaded
-viewer.model.materialVariants; // ["midnight", "beach", "street"]
+viewer.scene.updateSceneConfig({ model: { activeVariants: ["Paint: Red", "Wheels: Sport"] } });
+viewer.scene.updateSceneConfig({ model: { activeVariants: [] } }); // the defaults
 
-viewer.scene.updateSceneConfig({ model: { materialVariant: "beach" } });
-viewer.scene.updateSceneConfig({ model: { materialVariant: null } }); // 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 the variant doesn't map keep their default material, bound or not.
+- 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 pick itself until
-  `sceneConfig.model.materialVariant` or `modelUrl` changes.
-- A name the model doesn't have shows the defaults and logs a console warning
-  listing the model's variants.
+  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: { materialVariant: "beach" } } }`.
-- `onModelLoaded` reports the names as `materialVariants`, and BindingBuilder's
-  Scene tab (**General → Material variant**) picks the one the exported scene
-  config starts with. OBJ, FBX, USDZ, and streamed 3D Tiles models have no
-  variants.
+  `{ 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
 
@@ -2899,7 +3286,8 @@ showIsolateControls?: boolean; // tools.isolate
 
 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`.
+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
@@ -2951,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 = {
@@ -3099,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;
@@ -3111,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;
@@ -3129,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.
@@ -3237,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:
 
@@ -3424,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.
 
@@ -3465,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.