@liveroom-tech/react-immersive 5.0.2 → 5.1.0

package/README.md

@@ -59,13 +59,18 @@ 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`) with a built-in picker through `showMaterialVariants`, selected by `sceneConfig.model.materialVariant`
+- 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
 - 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
 - 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 +80,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,6 +91,7 @@ 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`
 
@@ -100,7 +108,7 @@ 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:
 
@@ -267,7 +275,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 +470,9 @@ const {
   setTransform,
   resetTransform,
   updateMetadata,
+  addDecal,
+  updateDecal,
+  removeDecal,
   hiddenObjects,
   hiddenObjectIds,
   hideObject,
@@ -524,6 +535,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 +673,7 @@ const {
   error,
   bounds,
   objectCount,
+  materialVariants,
   objects,
   handleModelLoaded,
   handleObjectCatalog,
@@ -684,6 +697,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`
@@ -751,6 +766,7 @@ 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)
 - traverse renderable mesh nodes and generate starter bindings automatically
 - 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 +777,11 @@ 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`
+- 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
@@ -785,7 +806,7 @@ 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.
@@ -906,16 +927,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 +952,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 +972,44 @@ 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.
+
 ## 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,8 +1031,8 @@ 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`) |
+| `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`) |
+| `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` |
 | `tiles` | `url` (`tilesetUrl`), `errorTarget` (`tilesErrorTarget`), `cacheSize` (`tilesCacheSize`) |
@@ -1029,6 +1079,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 +1105,7 @@ type Props = {
   showDownloadButton?: boolean;
   downloadFilename?: string;
   showResetButton?: boolean;
+  showFullscreenButton?: boolean;
   showLoadingOverlay?: boolean;
   showMouseController?: boolean;
   mouseControllerPosition?:
@@ -1086,6 +1139,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;
@@ -1312,6 +1370,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 +1462,7 @@ 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
 };
 ```
 
@@ -1450,6 +1510,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"` 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. |
+| `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,6 +1583,7 @@ type ViewerReadyState = {
   objectBindings: Record<string, ObjectBinding>;
   homeCameraState: { position: Vec3; target: Vec3 } | null;
   captureImage: (options?: CaptureImageOptions) => Promise<string>;
+  captureVideo: (options?: CaptureVideoOptions) => Promise<Blob>;
   invalidate: () => void;
   raw: {
     controls: CameraControls; // camera-controls
@@ -1521,6 +1636,46 @@ 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
+  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 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,
+GIF encoding, or format transcoding is included. The browser must support
+`canvas.captureStream` and `MediaRecorder`; exports reject before framing,
+during XR, during another recording, or for durations outside (0, 300] seconds.
+
 ### `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 +1760,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 +1800,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 +1851,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 +2189,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 +2211,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)).
@@ -2311,6 +2578,18 @@ 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, 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.
+`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 +2654,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 +2690,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 +2711,235 @@ Default:
 false;
 ```
 
+### `showMaterialVariants`
+
+Shows a row of 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`.
+
+Picking a variant sets `sceneConfig.model.materialVariant`, which is also how
+you choose one yourself:
+
+```tsx
+const viewer = useViewer();
+
+<ModelViewer modelUrl="/shoe.glb" licenseKey="your-license-key" {...viewer.props} />;
+
+// The model's variant names, once it has loaded
+viewer.model.materialVariants; // ["midnight", "beach", "street"]
+
+viewer.scene.updateSceneConfig({ model: { materialVariant: "beach" } });
+viewer.scene.updateSceneConfig({ model: { materialVariant: null } }); // the defaults
+```
+
+- 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.
+- 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.
+- 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.
+
+### 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`.
+
+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.
@@ -2762,6 +3299,7 @@ type ObjectBinding = {
   hoverable?: boolean;
   transform?: ObjectBindingTransform;
   style?: ObjectBindingStyle;
+  decals?: ObjectBindingDecal[];
   actions?: ObjectBindingAction[];
   metrics?: Record<string, number>;
   metadata?: Record<string, unknown>;
@@ -2789,9 +3327,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 +3347,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`