@liveroom-tech/react-immersive 4.3.0 → 5.0.0

package/README.md

@@ -10,16 +10,15 @@ The library currently exports:
 
 ```ts
 import {
-  BindingBuilder,
   material,
   ModelViewer,
   patchBindings,
   patchSceneConfig,
-  SimpleModelViewer,
   useObjectBinding,
   useObjectBindingIds,
   useObjectBindings,
   useSceneConfig,
+  useViewer,
   useViewerActions,
   useViewerAnimations,
   useViewerCamera,
@@ -31,8 +30,13 @@ import {
   MATERIAL_BLENDING_MODES,
   MATERIAL_SIDES,
 } from "@liveroom-tech/react-immersive";
+import { SimpleModelViewer } from "@liveroom-tech/react-immersive/simple-model-viewer";
+import { BindingBuilder } from "@liveroom-tech/react-immersive/binding-builder";
 ```
 
+Each component has its own entry point, so an app downloads only the ones it
+imports.
+
 It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectBindingsController`, `ObjectActionEvent`, `ObjectTransformSpace`, `SceneConfig`, `SceneConfigPatch`, `SceneConfigController`, `AnimationControls`, `CinematicConfig` / `CinematicWaypoint`, and related shapes used throughout this document.
 
 `ModelViewer` provides:
@@ -41,7 +45,7 @@ It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectBindi
 - 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
-- optional custom scene lighting through a `lights` prop
+- scene lighting through `sceneConfig.lighting`, with the `sceneLight` helper and a runtime lights controller
 - optional custom camera configuration through a `camera` prop
 - optional custom background color through a `backgroundColor` prop
 - optional shadow rendering toggle through a `shadows` prop (on by default)
@@ -51,6 +55,7 @@ It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectBindi
 - optional per-object move and rotate gizmo through `moveModeEnabled`, with World/Local axis alignment through `objectTransformSpace`
 - optional custom left object data panel through `customObjectBindingDataPanel`
 - optional custom right scene objects panel through `customSceneObjectsPanel`
+- your own UI over the 3D view through `overlay`, and react-three-fiber content inside the scene through `unsafe_sceneChildren`
 - 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`
@@ -73,6 +78,7 @@ It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectBindi
 - hover and selected-state highlighting
 - external selection state control through `selectedObject` and `onObjectSelect`
 - hover callbacks through `onObjectHover`
+- double-click, right-click, and touch long-press callbacks through `onObjectDoubleClick` and `onObjectContextMenu`
 - model-ready callbacks through `onModelLoaded`
 - model-load error callbacks through `onLoadError`
 - camera change callbacks through `onCameraChange`
@@ -98,7 +104,7 @@ It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectBindi
 
 `SimpleModelViewer` provides:
 
-- a lightweight GLB/GLTF/OBJ/FBX/USDZ viewer that does not require `objectBindings` and does not require a `licenseKey`
+- 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
 - 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
@@ -165,24 +171,33 @@ has its own meaning, state, or behavior," object bindings are a strong fit.
 ## Installation
 
 ```bash
-npm install @liveroom-tech/react-immersive
+npm install @liveroom-tech/react-immersive three @react-three/fiber
 ```
 
-Import the library stylesheet once from your application root (for example,
-Next.js `app/layout.tsx`):
+Import the stylesheet for each component you use, once, from your
+application root (for example, Next.js `app/layout.tsx`):
 
 ```tsx
-import "@liveroom-tech/react-immersive/styles.css";
+import "@liveroom-tech/react-immersive/styles.css"; // ModelViewer
+import "@liveroom-tech/react-immersive/simple-model-viewer.css"; // SimpleModelViewer
+import "@liveroom-tech/react-immersive/binding-builder.css"; // BindingBuilder
 ```
 
 The styles ship as a static CSS file rather than a runtime-injected `<style>`
 tag, so a strict CSP does not need `style-src 'unsafe-inline'`. Tailwind is not
 required in the consuming app.
 
-Peer dependencies:
+If a component's stylesheet is missing, it renders unstyled, and in
+development it logs a console warning naming the import to add.
+
+Peer dependencies, which your app provides so there's exactly one copy of each:
+
+- `react` and `react-dom` 19
+- `three` 0.184
+- `@react-three/fiber` 9
 
-- `react >= 17`
-- `react-dom >= 17`
+Everything else, including drei, post-processing, and WebXR support, installs
+with the package.
 
 `ModelViewer` and `BindingBuilder` require a `licenseKey` at runtime (see [`licenseKey`](#licensekey)). Get one from the Developer Portal, see [Resources](#resources) below.
 
@@ -199,6 +214,74 @@ Peer dependencies:
 
 ## Quick Start
 
+The shortest working viewer lets `ModelViewer` generate the bindings itself:
+
+```tsx
+import { ModelViewer } from "@liveroom-tech/react-immersive";
+
+export default function Example() {
+  return (
+    <div style={{ height: "100vh", overflow: "hidden" }}>
+      <ModelViewer
+        modelUrl="/model.glb"
+        licenseKey="your-license-key"
+      />
+    </div>
+  );
+}
+```
+
+Every mesh in the model can then be hovered and selected, and opens the side
+panel with Change Color, Change Material, and Toggle Visibility (or, for meshes
+whose names contain "light", Toggle Light, Change Light Color, and Set
+Brightness). See
+[Generating bindings automatically](#generating-bindings-automatically) for how
+to keep and refine the generated bindings.
+
+To control the viewer from your own UI, use `useViewer`. It connects every
+viewer hook to `ModelViewer` at once:
+
+```tsx
+import { ModelViewer, useViewer } from "@liveroom-tech/react-immersive";
+
+export default function Configurator() {
+  const viewer = useViewer();
+
+  return (
+    <div style={{ height: "100vh", overflow: "hidden" }}>
+      <ModelViewer
+        modelUrl="/model.glb"
+        licenseKey="your-license-key"
+        {...viewer.props}
+      />
+      <button
+        onClick={() => viewer.bindings.setBaseColor({ group: "paint" }, "#b91c1c")}
+      >
+        Paint it red
+      </button>
+      <button onClick={() => viewer.camera.resetView()}>Reset view</button>
+    </div>
+  );
+}
+```
+
+`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
+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
+`useViewer({ bindings })` to start from your own. It also accepts
+`sceneConfig`, `camera` (the `useViewerCamera` options), and `onAction`,
+`onObjectSelect`, `onObjectHover`, and `onLoadError` callbacks. `sceneConfig`
+is passed to `ModelViewer` only once you've supplied one or changed the scene
+through `viewer.scene`, so the default scene behaves as if none were passed.
+Props set on `ModelViewer` after the spread take precedence.
+
+The full example below authors bindings by hand and wires up every hook
+individually, which is what `useViewer` does for you. Wire them yourself when
+state lives elsewhere, such as bindings owned by a store:
+
 ```tsx
 import {
   ModelViewer,
@@ -488,8 +571,7 @@ pure `patchSceneConfig(sceneConfig, patch)` utility when a store or parent owns
 the scene state. The namespaced `lights` controller also provides `add`,
 `update`, `remove`, `show`, `hide`, `toggle`, `setIntensity`, `setColor`,
 `attach`, and `detach`. Attached lights follow a bound model object without an
-R3F light component. The custom `lights` prop replaces scene-config lights, so
-leave it unset when using this controller.
+R3F light component.
 
 For high-frequency visual effects, use `useViewerEffects`. It mutates the live
 viewer efficiently, requests demand-rendered frames automatically, and restores
@@ -579,7 +661,9 @@ const {
   error,
   bounds,
   objectCount,
+  objects,
   handleModelLoaded,
+  handleObjectCatalog,
   handleLoadError,
 } = useViewerModel();
 
@@ -588,6 +672,7 @@ const {
   licenseKey="your-license-key"
   objectBindings={objectBindings}
   onModelLoaded={handleModelLoaded}
+  onObjectCatalog={handleObjectCatalog}
   onLoadError={handleLoadError}
 />;
 ```
@@ -599,7 +684,10 @@ 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
+- `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`
+- `handleObjectCatalog`: a callback you can pass directly to `onObjectCatalog`
 - `handleLoadError`: a callback you can pass directly to `onLoadError`
 
 If you want to inspect or trigger binding actions programmatically, the library also exports:
@@ -636,7 +724,8 @@ Actions can declare ordered `effects` for object-binding patches, scene patches,
 Basic usage:
 
 ```tsx
-import { BindingBuilder } from "@liveroom-tech/react-immersive";
+import "@liveroom-tech/react-immersive/binding-builder.css";
+import { BindingBuilder } from "@liveroom-tech/react-immersive/binding-builder";
 
 export default function App() {
   return <BindingBuilder licenseKey="your-license-key" />;
@@ -655,31 +744,11 @@ type BindingBuilderProps = {
 };
 ```
 
-Pass `tilesetUrl` to `ModelViewer` for a processed 3D Tiles asset. The original
-`modelUrl` remains the durable source/fallback URL, but is not downloaded by the
-viewer while a tileset is present:
-
-```tsx
-<ModelViewer
-  modelUrl="https://assets.example.com/source/building.glb"
-  tilesetUrl="https://assets.example.com/tiles/building/tileset.json"
-  tilesErrorTarget={8}
-  tilesCacheSize={800}
-  licenseKey="your-license-key"
-  objectBindings={{}}
-/>
-```
-
-Tiles are a dynamic level-of-detail scene, so automatic mesh binding generation
-is intentionally disabled in streamed `BindingBuilder` projects. Scene settings
-remain editable. Per-part editing requires the conversion pipeline to provide a
-stable CAD/object catalog that can be mapped to tile feature metadata.
-
 `licenseKey` is validated the same way as `ModelViewer`'s (see [`licenseKey`](#licensekey) below). While the key is being checked, `BindingBuilder` renders a "Verifying license…" placeholder; if it's invalid, it renders an error message instead of the editor.
 
 Current behavior, Object tab:
 
-- upload a `.glb`, standalone/data-URI `.gltf`, or `.zip` containing a `.gltf` plus its referenced `.bin` and texture files
+- 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
 - 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
@@ -691,6 +760,8 @@ Current behavior, Object tab:
 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`
+- 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
 - export the current scene config as JSON or TypeScript
@@ -698,6 +769,13 @@ Current behavior, Scene tab:
 Preview:
 
 - the selected node previews live in an embedded `ModelViewer`
+
+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
+- 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`
 
 ### `BindingBuilder` licensing & plan tiers
@@ -719,7 +797,8 @@ A locked feature renders in place (not hidden) with a message naming the require
 Basic usage:
 
 ```tsx
-import { SimpleModelViewer } from "@liveroom-tech/react-immersive";
+import "@liveroom-tech/react-immersive/simple-model-viewer.css";
+import { SimpleModelViewer } from "@liveroom-tech/react-immersive/simple-model-viewer";
 
 export default function App() {
   return (
@@ -791,7 +870,7 @@ const {
 - `setCameraTarget`: sets the camera target to a given `[x, y, z]`
 - `setCameraState`: restores a full camera state (`position`/`target`/`fov`/`zoom`) previously read from `cameraState`
 - `lookAt`: moves the position and target together
-- `orbitTo`: moves to azimuth and polar angles in radians
+- `orbitTo`: orbits to azimuth and polar angles in degrees (azimuth 0 is the front, 90 the right; polar 0 is straight down, 90 level)
 - `dollyTo`: moves to a distance from the current target
 - `savePreset`: captures the current camera under a name
 - `goToPreset`: moves to a named camera preset
@@ -871,35 +950,96 @@ const { clips, currentClip, isPlaying, play, pause, stop, setSpeed } =
 ))}
 ```
 
+## 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 |
+| `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 |
+
+`MODEL_VIEWER_PRESETS` lists exactly which props each preset sets.
+
+Related props are also available as groups, which keeps a configured viewer
+readable:
+
+```tsx
+<ModelViewer
+  modelUrl="/car.glb"
+  licenseKey="your-license-key"
+  preset="configurator"
+  ui={{ download: "car.glb" }}
+  tools={{ measure: { unit: "cm" } }}
+  controls={{ autoRotate: 0.5, zoom: false, limits: { maxDistance: 20 } }}
+  perf={{ profile: "low" }}
+  xr={{ enabled: true, usdzUrl: "/car.usdz" }}
+/>
+```
+
+| Group | Fields, and the flat prop each one sets |
+| --- | --- |
+| `ui` | `objectPanel` (`showObjectBindingDataPanel`), `sceneObjects` (`showSceneObjectsPanel`), `download` (`showDownloadButton`; a string also sets `downloadFilename`), `reset` (`showResetButton`), `loadingOverlay` (`showLoadingOverlay`), `viewGizmo` (`showViewGizmo`), `mouseController` (`showMouseController`; `{ position, opacity }` also sets `mouseControllerPosition` and `mouseControllerOpacity`), `annotationNavigation` (`showAnnotationNavigation`), `annotationOnHover` (`showAnnotationOnHover`), `highlightOnHover` |
+| `tools` | `measure` (`showMeasureTools`; `{ unit }` also sets `measurementUnit`), `uvChecker` (`showUvCheckerButton`), `explode` (`showExplodeControls`), `texturePositioning` (`texturePositioning`) |
+| `controls` | `enabled` (`enableCameraControls`), `keyboard` (`enableKeyboardNavigation`), `zoom` (the opposite of `disableZoom`), `zoomOnSelect` (`zoomOnSelected`), `autoRotate` (a number also sets `autoRotateSpeed`), `refitOnResize`, `limits` (`cameraLimits`), `moveSensitivity`, `zoomSensitivity` |
+| `perf` | `renderMode`, `maxDpr`, `profile` (`performanceProfile`), `preserveDrawingBuffer` |
+| `tiles` | `url` (`tilesetUrl`), `errorTarget` (`tilesErrorTarget`), `cacheSize` (`tilesCacheSize`) |
+| `xr` | `enabled` (`enableXR`), `usdzUrl`, `scaleMode` (`arScaleMode`), `mobileHandoffUrl` |
+| `decoders` | `draco` (`dracoDecoderPath`), `ktx2` (`ktx2TranscoderPath`), `meshopt` |
+
+A preset only fills in defaults: a flat prop overrides it, and a grouped prop
+overrides both. The flat props keep working exactly as before.
+
 ## Public API
 
 The source code currently defines `ModelViewer` with these props:
 
 ```ts
-type ObjectTransformSpace = "local" | "world";
-
 type Props = {
+  preset?: "minimal" | "showcase" | "configurator" | "inspector";
+  ui?: ModelViewerUiOptions;
+  tools?: ModelViewerToolsOptions;
+  controls?: ModelViewerControlsOptions;
+  perf?: ModelViewerPerfOptions;
+  tiles?: ModelViewerTilesOptions;
+  xr?: ModelViewerXrOptions;
+  decoders?: ModelViewerDecoderOptions;
   modelUrl: string;
+  tilesetUrl?: string | null;
+  tilesErrorTarget?: number;
+  tilesCacheSize?: number;
+  onObjectCatalog?: (objects: ViewerObjectInfo[]) => void;
   modelFormat?: "glb" | "gltf" | "obj" | "fbx" | "usdz";
   licenseKey: string;
-  objectBindings: Record<string, ObjectBinding>;
+  objectBindings?: Record<string, ObjectBinding> | "auto"; // default "auto"
   selectedObject?: ObjectBinding | null;
+  panelHoveredObject?: ObjectBinding | null;
   onObjectBindingsChange?: (next: Record<string, ObjectBinding>) => void;
   onObjectSelect?: (binding: ObjectBinding | null) => void;
   onObjectHover?: (binding: ObjectBinding | null) => void;
-  onModelLoaded?: (scene: Object3D) => void;
+  onObjectDoubleClick?: (event: ObjectPointerEvent) => boolean | void;
+  onObjectContextMenu?: (event: ObjectPointerEvent) => void;
+  onModelLoaded?: (model: ViewerModelInfo) => void;
   onLoadError?: (error: unknown) => void;
+  onProgress?: (event: ProgressEvent) => void;
+  cameraControllerType?: "orbit" | "pointerLock";
+  onCameraControllerChange?: (
+    controller: "orbit" | "pointerLock",
+  ) => void;
   onAction?: (event: ObjectActionEvent) => void;
   onHiddenObjectsChange?: (next: Record<string, boolean>) => void;
-  onCameraChange?: (camera: Camera, controls: CameraControls) => void;
+  onCameraChange?: (state: ViewerCameraState) => void;
   onViewerReady?: (viewer: ViewerReadyState) => void;
   onTextureUpload?: (file: File, objectId: string) => Promise<string>;
+  texturePositioning?: boolean | TexturePositioningControls;
   onAnimationsReady?: (controls: AnimationControls) => void;
   onAnnotationsChange?: (annotations: AnnotationMarker[]) => void;
   activeAnnotation?: AnnotationMarker | null;
   onActiveAnnotationChange?: (annotation: AnnotationMarker | null) => void;
-  lights?: React.ReactNode;
-  camera?: React.ComponentProps<typeof Canvas>["camera"];
+  camera?: ViewerCameraConfig;
+  cameraLimits?: CameraLimits;
   backgroundColor?: string;
   shadows?: boolean;
   showObjectBindingDataPanel?: boolean;
@@ -929,9 +1069,10 @@ type Props = {
   sceneConfig?: SceneConfig;
   disableZoom?: boolean;
   zoomOnSelected?: boolean;
+  highlightOnHover?: boolean;
   enableCameraControls?: boolean;
   moveModeEnabled?: boolean;
-  objectTransformSpace?: ObjectTransformSpace;
+  objectTransformSpace?: "local" | "world";
   enableKeyboardNavigation?: boolean;
   onAutoFit?: () => Promise<boolean>;
   refitOnResize?: boolean;
@@ -953,7 +1094,12 @@ type Props = {
   mobileHandoffUrl?: string;
   showAnnotationNavigation?: boolean;
   showAnnotationOnHover?: boolean;
+  onSceneConfigChange?: (config: SceneConfig) => void;
   showViewGizmo?: boolean;
+  overlay?: React.ReactNode;
+  unsafe_sceneChildren?: React.ReactNode;
+  autoRotate?: boolean;
+  autoRotateSpeed?: number;
 };
 ```
 
@@ -972,13 +1118,44 @@ modelUrl = "/model.glb";
 Optional explicit format for signed or extensionless model URLs. Normal URLs
 ending in `.glb`, `.gltf`, `.obj`, `.fbx`, or `.usdz` are detected automatically.
 
+### 3D Tiles streaming
+
+Use `tilesetUrl` to stream a processed 3D Tiles model instead of downloading
+`modelUrl` as one monolithic asset. `modelUrl` remains required by the component
+API, but `tilesetUrl` is the render source while streaming is enabled.
+
+```tsx
+<ModelViewer
+  modelUrl="/models/campus.glb"
+  tilesetUrl="/models/campus/tileset.json"
+  tilesErrorTarget={8}
+  tilesCacheSize={800}
+  onObjectCatalog={(objects) => console.log(objects)}
+  {...props}
+/>
+```
+
+- `tilesErrorTarget` controls the screen-space error target. Lower values load
+  sharper tiles and use more bandwidth/GPU memory. Default: `8`.
+- `tilesCacheSize` is the maximum number of parsed tiles kept in the client
+  cache. Default: `800`.
+- `onObjectCatalog` receives the bindable-object catalog from `objects.json`
+  before all referenced tiles have loaded. See [`onObjectCatalog`](#onobjectcatalog).
+
+Bindings, selection, hover, material overrides, transforms, exploded view, and
+scene renderer modes use the same public API in streamed and monolithic modes.
+The tileset and its tile payloads must be browser-accessible, and the optional
+object catalog must sit beside `tileset.json` as `objects.json`.
+
 ### `licenseKey`
 
 License key for the library. Required.
 
 ### `objectBindings`
 
-A map keyed by the model node name. Each key should match a mesh name from the GLB/GLTF file.
+A map keyed by the model node name, or `"auto"`, the default (see
+[Generating bindings automatically](#generating-bindings-automatically)). Each
+key should match a mesh name from the GLB/GLTF file.
 
 `objectBindings` is the single source of truth for all visual state. Changes to the binding record drive rendering:
 
@@ -1024,6 +1201,69 @@ const objectBindings = defineObjectBindings({
 
 `defineObjectBindings` validates the complete record while preserving its exact keys and literal values. Use `ObjectBindingKey<typeof objectBindings>` for the binding-key union and `ObjectBindingActionId<typeof objectBindings, "Object_2">` for that binding's action-id union. It returns the input unchanged at runtime.
 
+If a binding's `modelObjectId` (or its key) doesn't match any node in the
+loaded model, that binding can never be selected. `ModelViewer` then shows a
+dismissible banner with the number of mismatched bindings, and logs a console
+warning naming them. Log [`onObjectCatalog`](#onobjectcatalog) to see the
+model's node names.
+
+#### Generating bindings automatically
+
+`objectBindings` defaults to `"auto"`: leave it out and `ModelViewer` generates
+a binding for every mesh when the model loads, so you don't need to know the
+node names up front:
+
+```tsx
+<ModelViewer modelUrl="/model.glb" licenseKey="your-license-key" />
+```
+
+Each generated binding is keyed by the node name, with a readable `label`
+(`"Wheel_FL"` becomes `"Wheel FL"`), an inferred `type`, a unique `id`, and
+built-in actions: `change-color`, `change-material`, and `toggle-visibility`,
+or `toggle-light`, `change-light-color`, and `set-brightness` for meshes whose
+names contain "light". For a streamed model (`tilesetUrl`), the bindings come
+from the object catalog, so objects are bindable before their tiles load.
+
+The generated bindings are passed to `onObjectBindingsChange` once they exist,
+and again after every edit. To keep them, and to refine them later, store them
+and pass them back:
+
+```tsx
+const [objectBindings, setObjectBindings] = useState<
+  Record<string, ObjectBinding> | "auto"
+>("auto");
+
+<ModelViewer
+  modelUrl={modelUrl}
+  licenseKey="your-license-key"
+  objectBindings={objectBindings}
+  onObjectBindingsChange={setObjectBindings}
+/>;
+```
+
+After the first change the viewer is controlled by your state as usual. Set the
+state back to `"auto"` when you switch to a different model. While the prop is
+`"auto"`, bindings the same model already had are kept when it reloads, so
+runtime edits survive; a different `modelUrl` starts from fresh bindings.
+
+The same defaults are available as functions from both entry points (they are
+also what `BindingBuilder` generates):
+
+```ts
+import {
+  buildBindingsFromNodes,
+  createDefaultBinding,
+  inferType,
+} from "@liveroom-tech/react-immersive/utils";
+
+const bindings = buildBindingsFromNodes(["CarBody", "Wheel_FL"]);
+const door = { ...createDefaultBinding("FrontDoor"), label: "Front door" };
+inferType("Wheel_FL"); // "wheel"
+```
+
+Every generated action is one `ModelViewer` performs itself, so every
+generated button works without extra setup.
+
 ### `selectedObject`
 
 Optional currently selected object binding, or `null` when nothing is selected.
@@ -1033,6 +1273,13 @@ If omitted, `ModelViewer` manages its own selection state internally.
 
 When the selected object has a `cameraState` with both `position` and `target`, the viewer uses that saved camera view for focus/select behavior instead of falling back to `fitToBox`.
 
+### `panelHoveredObject`
+
+Optional externally controlled binding to highlight as hovered by a custom
+scene-objects panel. It takes precedence over the built-in panel and canvas
+hover while `highlightOnHover` is enabled. Pass `null` when no panel row is
+hovered.
+
 ### `onObjectSelect`
 
 Optional callback called when the user clicks a mesh or closes the side panel.
@@ -1053,6 +1300,47 @@ Behavior:
 - pointer over a mesh calls `onObjectHover(binding)`
 - pointer out calls `onObjectHover(null)`
 
+### `onObjectDoubleClick`
+
+Optional callback called when the user double-clicks an object.
+
+```ts
+onObjectDoubleClick?: (event: ObjectPointerEvent) => boolean | void
+
+type ObjectPointerEvent = {
+  binding: ObjectBinding;
+  clientX: number; // viewport coordinates
+  clientY: number;
+  pointerType: string; // "mouse" | "pen" | "touch"
+};
+```
+
+Return `true` to say you handled it: the viewer then skips its own double-click
+behavior, which moves the camera's orbit point to that spot (or starts texture
+positioning, when `texturePositioning` is on). Return nothing to keep it.
+
+### `onObjectContextMenu`
+
+Optional callback called when the user right-clicks an object, or long-presses
+it on a touch screen. Use it to open your own menu:
+
+```tsx
+<ModelViewer
+  {...props}
+  onObjectContextMenu={({ binding, clientX, clientY }) =>
+    openMenu({ for: binding.id, x: clientX, y: clientY })
+  }
+/>
+```
+
+It receives the same `ObjectPointerEvent` as `onObjectDoubleClick`, with the
+position where the gesture started, ready for a `position: fixed` menu. A
+right-click fires when the button is released without the pointer moving, so a
+right-drag still pans the camera. A long-press fires after half a second, and
+not if the finger moves or a second finger touches down (a pinch); lifting the
+finger afterwards doesn't select the object. Objects with `selectable: false`
+don't fire it.
+
 ### `onHiddenObjectsChange`
 
 Optional callback fired with the derived hidden-object map whenever the current binding data changes hidden visibility state.
@@ -1071,16 +1359,56 @@ This fires for:
 
 If you want the viewer and your app state to stay in sync, pass `objectBindings` from state and wire this callback back into that state setter.
 
-### `onModelLoaded`
+### `onObjectCatalog`
 
-Optional callback fired after the GLB/GLTF scene has been loaded.
+Optional callback listing every bindable object in the model: each named mesh,
+under the identifier `objectBindings` is keyed by. It's the quickest way to find
+out what your meshes are called:
 
-Current callback shape:
+```tsx
+<ModelViewer
+  modelUrl="/model.glb"
+  licenseKey="your-license-key"
+  onObjectCatalog={(objects) => console.table(objects)}
+/>
+```
+
+It fires each time a model loads. For a streamed model (`tilesetUrl`) the list
+comes from `objects.json` beside `tileset.json`, before the tiles containing
+those objects have necessarily loaded. Each entry is a `ViewerObjectInfo`:
 
 ```ts
-(scene: Object3D) => void
+type ViewerObjectInfo = {
+  name: string; // the key to use in objectBindings
+  triangles: number;
+  minimum: [number, number, number];
+  maximum: [number, number, number];
+};
 ```
 
+`minimum` and `maximum` are the object's bounds in the model's own units, in
+Z-up coordinates as in 3D Tiles: a point at glTF `(x, y, z)` is `(x, -z, y)`
+here. They're the same for loaded and streamed models, and don't change when the
+viewer moves or scales the model. `TileObjectCatalogEntry` is a deprecated
+alias of this type. To keep the list in state, use `useViewerModel` and pass
+its `handleObjectCatalog`.
+
+### `onModelLoaded`
+
+Optional callback fired after the model has loaded, with its bounds and mesh
+count:
+
+```ts
+(model: ViewerModelInfo) => void
+
+type ViewerModelInfo = {
+  bounds: { min: Vec3; max: Vec3; center: Vec3; size: Vec3 }; // world space
+  objectCount: number; // meshes in the loaded scene
+};
+```
+
+For the model's object names, use [`onObjectCatalog`](#onobjectcatalog).
+
 ### `onLoadError`
 
 Optional callback fired if the model fails to load or render.
@@ -1091,6 +1419,22 @@ Current callback shape:
 (error: unknown) => void
 ```
 
+Whether or not you pass it, `ModelViewer` shows a message in place of the
+model that explains the likely cause: a missing file (404), refused access
+(401/403), a blocked cross-origin request (CORS), a web page served instead of
+a model, or a file that isn't the expected format. It includes the URL and the
+underlying error. Set `showLoadingOverlay={false}` to show your own instead.
+
+### `onProgress`
+
+Called with the loader's `ProgressEvent` while a monolithic model is being
+downloaded. When `event.lengthComputable` is true, progress is
+`event.loaded / event.total`; the built-in loading overlay uses the same value.
+
+```ts
+onProgress?: (event: ProgressEvent) => void
+```
+
 ### `onAction`
 
 Optional callback fired when a built-in action button is clicked from the side panel.
@@ -1123,11 +1467,15 @@ Current callback shape:
 
 ```ts
 type ViewerReadyState = {
-  controls: CameraControls;
-  scene: Object3D | null;
   objectBindings: Record<string, ObjectBinding>;
-  nodeRefs: Record<string, Object3D>;
+  homeCameraState: { position: Vec3; target: Vec3 } | null;
   captureImage: (options?: CaptureImageOptions) => Promise<string>;
+  invalidate: () => void;
+  raw: {
+    controls: CameraControls; // camera-controls
+    scene: Object3D | null; // three.js
+    nodes: Record<string, Object3D>; // model nodes by binding key and name
+  };
 };
 
 type CaptureImageOptions = {
@@ -1137,6 +1485,11 @@ type CaptureImageOptions = {
 };
 ```
 
+`raw` holds the live three.js scene, the camera-controls instance, and the
+model's nodes, for integrations the rest of the API doesn't cover. You don't
+need it for anything the hooks and props already do, and its shapes are those
+libraries' own, so they can change when those libraries do.
+
 `captureImage` requires the opt-in `preserveDrawingBuffer` prop, forces a render, and resolves with a `data:image/png` URL. Pass `width`/`height` to render at a resolution other than the canvas's current size, and `transparent` to hide the configured background so the PNG carries an alpha channel instead. It rejects if called before the viewer is ready or when framebuffer preservation is disabled. The Download PNG menu item is also shown only when this prop is enabled.
 
 ```tsx
@@ -1205,6 +1558,41 @@ Example:
 />
 ```
 
+### `texturePositioning`
+
+Turns on texture positioning for objects with an uploaded texture. Off by
+default. When on, the **Change Material** panel gains Offset X/Y and Rotation
+controls, and double-clicking the object puts the viewer in Move/Zoom mode:
+drag to move the texture, scroll to scale it, and click the canvas or
+**Done positioning** to finish.
+
+```tsx
+<ModelViewer modelUrl="/sofa.glb" licenseKey="your-license-key" texturePositioning />
+```
+
+Changes are written to the binding's `style.material.texture` (`offset`,
+`rotation` in radians, and `scale`), so they reach `onObjectBindingsChange`
+and your saved bindings like any other edit.
+
+To handle some of it yourself, pass an object instead of `true`. Any field you
+leave out keeps the viewer's own behavior:
+
+```ts
+type TexturePositioningControls = {
+  offset?: [number, number]; // shown in the Offset fields instead of the binding's
+  rotationDegrees?: number; // shown in the Rotation field, 0–360
+  onOffsetChange?: (objectId: string, axisIndex: 0 | 1, value: number) => void;
+  onRotationChange?: (objectId: string, degrees: number) => void;
+  isPositioning?: boolean; // shows "Done positioning" instead of the hint
+  onEndPositioning?: () => void; // after Done positioning ends the mode
+};
+```
+
+`onOffsetChange` and `onRotationChange` replace the viewer's writes from the
+panel fields; dragging and scrolling on the canvas still write to the binding.
+
+---
+
 ### `onAnimationsReady`
 
 Optional callback fired after the GLB/GLTF model is loaded, providing animation controls. If the model contains no animations, it is still called with an empty `clips` array and no-op control functions.
@@ -1244,38 +1632,69 @@ 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.
 
-### `lights`
-
-Optional custom lighting to render inside the scene.
+### Lighting
 
-If omitted, `ModelViewer` uses the library's default light rig.
-
-Example:
+Lighting lives in `sceneConfig.lighting`: an ambient light plus a list of
+directional, point, spot, and hemisphere lights. Without a `sceneConfig`,
+`ModelViewer` uses its default rig (ambient, a hemisphere fill, and a
+shadow-casting key light). To use your own lights, patch the default scene
+config. `sceneLight` fills in every setting you leave out:
 
 ```tsx
-function CustomLights() {
-  return (
-    <>
-      <ambientLight intensity={0.5} />
-      <directionalLight position={[4, 8, 4]} intensity={1.6} castShadow />
-      <pointLight position={[-3, 3, 2]} intensity={0.8} />
-    </>
-  );
-}
+import {
+  DEFAULT_SCENE_CONFIG,
+  patchSceneConfig,
+  sceneLight,
+} from "@liveroom-tech/react-immersive/utils";
+
+const sceneConfig = patchSceneConfig(DEFAULT_SCENE_CONFIG, {
+  lighting: {
+    ambient: { intensity: 0.5 },
+    lights: [
+      sceneLight({ id: "key", type: "directional", position: [4, 8, 4], intensity: 1.6, castShadow: true }),
+      sceneLight({ id: "fill", type: "point", position: [-3, 3, 2], intensity: 0.8 }),
+    ],
+  },
+});
 
 <ModelViewer
   modelUrl="/model.glb"
   licenseKey="your-license-key"
-  objectBindings={objectBindings}
-  lights={<CustomLights />}
+  sceneConfig={sceneConfig}
 />;
 ```
 
+To change lights while the app runs, use the lights controller from
+`useViewer` (or `useSceneConfig`):
+
+```tsx
+const viewer = useViewer({ sceneConfig });
+
+viewer.scene.lights.setIntensity("key", 2.2);
+viewer.scene.lights.toggle("fill");
+viewer.scene.lights.add({ id: "bulb", type: "point", color: "#ffd27d", intensity: 4 });
+viewer.scene.lights.attach("bulb", { objectId: "Lamp", offset: [0, 1.4, 0] });
+```
+
+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`.
+
 ### `camera`
 
-Optional custom camera configuration passed through to the underlying React Three Fiber `Canvas`.
+Optional starting camera: where it is and its lens.
+
+```ts
+type ViewerCameraConfig = {
+  position?: [number, number, number];
+  fov?: number; // vertical field of view in degrees; default 50
+  near?: number;
+  far?: number;
+  zoom?: number;
+};
+```
 
-`ModelViewer` only sets a default `fov: 50`, it does not set a default position, so an unset position falls back to React Three Fiber's own `Canvas` default (`[0, 0, 5]`). Pass an explicit `position` for predictable framing.
+Without a `position`, the camera starts at `[0, 0, 5]`. Pass one for predictable framing.
 
 Example:
 
@@ -1295,6 +1714,50 @@ Example:
 
 Passing an explicit `camera` counts as choosing the initial view yourself, so the mount-time auto-fit (see [`onAutoFit`](#onautofit)) is skipped automatically and your `position`/`fov` stick. Provide `onAutoFit` as well only if you want to run your _own_ fit-to-scene logic instead.
 
+### `cameraLimits`
+
+Constrains how far the orbit camera can zoom, tilt, turn, and pan. Angles are
+in degrees.
+
+```tsx
+<ModelViewer
+  modelUrl="/car.glb"
+  licenseKey="your-license-key"
+  cameraLimits={{
+    minDistance: 2,
+    maxDistance: 12,
+    maxPolarAngle: 85, // stay above the floor
+    minAzimuthAngle: -60, // turn at most 60° either side of the front
+    maxAzimuthAngle: 60,
+  }}
+/>
+```
+
+```ts
+type CameraLimits = {
+  minDistance?: number; // default 0
+  maxDistance?: number; // default Infinity
+  minPolarAngle?: number; // degrees, default 0
+  maxPolarAngle?: number; // degrees, default 180
+  minAzimuthAngle?: number; // degrees, default -Infinity
+  maxAzimuthAngle?: number; // degrees, default Infinity
+  panBoundary?: [
+    min: [number, number, number],
+    max: [number, number, number],
+  ];
+  boundaryEnclosesCamera?: boolean; // default false
+  boundaryFriction?: number; // default 0
+};
+```
+
+- **Polar** is the vertical angle: `0` looks straight down from above, `90` is
+  level with the target, and `180` looks straight up from below.
+- **Azimuth** is the horizontal angle around the vertical axis: `0` views the
+  target from the front (+Z), `90` from its right (+X), and `-90` from its left.
+
+`panBoundary` is an axis-aligned world-space box. These limits apply to the
+orbit controller; pointer-lock mode is not orbiting around the same target.
+
 ### `backgroundColor`
 
 Optional background color for the viewer canvas.
@@ -1337,14 +1800,25 @@ Example:
 
 ### `onCameraChange`
 
-Optional callback fired whenever the camera controls update the camera.
-
-Current callback shape:
+Optional callback fired whenever the camera moves, with its plain state. It
+fires often while the user orbits, pans, or zooms.
 
 ```ts
-(camera: Camera, controls: CameraControls) => void
+(state: ViewerCameraState) => void
+
+type ViewerCameraState = {
+  position: [number, number, number];
+  target: [number, number, number];
+  fov: number | null;
+  zoom: number;
+  azimuthAngle?: number; // radians, for setCameraState to restore
+  polarAngle?: number; // radians
+};
 ```
 
+It's the same state `useViewerCamera` exposes as `cameraState`, and
+`setCameraState` restores it.
+
 ### `showObjectBindingDataPanel`
 
 Optional boolean that controls whether the built-in left object details panel is rendered.
@@ -1373,6 +1847,57 @@ type CustomObjectBindingDataPanelProps = {
 
 When provided, `ModelViewer` passes its existing internal handlers into your custom panel. Your panel can call them, wrap them, or ignore them.
 
+### `overlay`
+
+Your own UI over the 3D view: badges, HUDs, buttons, custom panels. It sits
+above the model and below the viewer's toolbars and banners.
+
+```tsx
+<ModelViewer
+  modelUrl="/sofa.glb"
+  licenseKey="your-license-key"
+  overlay={
+    <div style={{ position: "absolute", top: 16, left: 16 }}>
+      In stock <button onClick={addToCart}>Add to cart</button>
+    </div>
+  }
+/>
+```
+
+The layer covers the view but lets pointer events through, so the model stays
+draggable around your elements. Its direct children receive pointer events, so
+position them yourself (for example with `position: "absolute"`) rather than
+wrapping everything in one full-size container.
+
+### `unsafe_sceneChildren`
+
+react-three-fiber elements rendered inside the scene, for anything the viewer
+can't do itself, such as custom geometry, a helper, or an effect driven by
+`useFrame`:
+
+```tsx
+import { useFrame } from "@react-three/fiber";
+
+function Marker() {
+  const ref = useRef<Mesh>(null);
+  useFrame((_, delta) => (ref.current!.rotation.y += delta));
+  return (
+    <mesh ref={ref} position={[0, 1.5, 0]}>
+      <boxGeometry args={[0.3, 0.3, 0.3]} />
+      <meshStandardMaterial color="hotpink" />
+    </mesh>
+  );
+}
+
+<ModelViewer {...props} unsafe_sceneChildren={<Marker />} />;
+```
+
+They're rendered inside their own `Suspense` boundary, so a child that loads
+assets doesn't hold up the model. Because they work with three.js directly,
+they're outside the viewer's own API: the name says so, and they can break when
+three.js or react-three-fiber change. Prefer the props and hooks for anything
+they cover.
+
 ### `customSceneObjectsPanel`
 
 Optional render prop for replacing the built-in right scene objects panel.
@@ -1442,7 +1967,7 @@ true;
 
 ### `showLoadingOverlay`
 
-Optional boolean controlling whether the built-in loading overlay is shown while the model is loading and the initial camera fit is settling.
+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)).
 
 Default:
 
@@ -1542,6 +2067,17 @@ magenta and trigger an explanatory notice.
 />
 ```
 
+### `onSceneConfigChange`
+
+Called with an updated `SceneConfig` when viewer-owned scene editing changes
+the configuration. Currently this is used when a light-position or rotation
+gizmo moves a scene-config light. Update controlled `sceneConfig` state with
+the value returned by this callback.
+
+```ts
+onSceneConfigChange?: (config: SceneConfig) => void
+```
+
 ### `disableZoom`
 
 Optional boolean. When `true`, the viewer never zooms the camera to an object on selection (selection still highlights and fires callbacks).
@@ -1562,6 +2098,12 @@ Default:
 true;
 ```
 
+### `highlightOnHover`
+
+Controls hover highlighting for the canvas, built-in object list, and
+`panelHoveredObject`. Default: `true`. On very large models, viewport hover is
+disabled for performance, while panel-row highlighting remains available.
+
 ### Moving and rotating objects
 
 Set `moveModeEnabled` to show a centered Drei `PivotControls` gizmo for the
@@ -1623,6 +2165,41 @@ is managed internally.
 Optional boolean controlling orbit, pan, and zoom input. Default: `true`.
 Camera controls are temporarily disabled whenever `moveModeEnabled` is on.
 
+### `cameraControllerType` / `onCameraControllerChange`
+
+Selects the active camera interaction mode:
+
+- `"orbit"` (default) uses orbit, pan, and zoom controls.
+- `"pointerLock"` captures the pointer for first-person look-around. Leaving
+  pointer lock returns the viewer to orbit mode.
+
+The viewer's camera-controller menu can manage this internally. Pass
+`cameraControllerType` to control it from application state and update that
+state from `onCameraControllerChange`.
+
+```tsx
+const [controller, setController] = useState<"orbit" | "pointerLock">("orbit");
+
+<ModelViewer
+  {...props}
+  cameraControllerType={controller}
+  onCameraControllerChange={setController}
+/>
+```
+
+Auto-rotation pauses while pointer-lock mode is active.
+
+### `autoRotate` / `autoRotateSpeed`
+
+Enables automatic orbiting and controls its speed. Defaults are `false` and
+`1`. When these props aren't passed, `sceneConfig.model.autoRotate` and
+`sceneConfig.model.autoRotateSpeed` apply, so a scene exported from
+`BindingBuilder` can carry the same behavior. When they are passed, they win.
+
+```tsx
+<ModelViewer {...props} autoRotate autoRotateSpeed={0.75} />
+```
+
 ### `enableKeyboardNavigation`
 
 Optional boolean enabling camera shortcuts after the viewer canvas is clicked
@@ -2007,7 +2584,7 @@ type SimpleModelViewerProps = {
   ambientColor?: string;
   directionalIntensity?: number;
   directionalColor?: string;
-  onModelLoaded?: (scene: Object3D) => void;
+  onModelLoaded?: (model: ViewerModelInfo) => void;
   onLoadError?: (error: unknown) => void;
 };
 ```
@@ -2134,7 +2711,8 @@ false;
 
 ### `onModelLoaded`
 
-Optional callback fired after the GLB/GLTF scene has loaded.
+Optional callback fired after the model has loaded, with its bounds and mesh
+count (`(model: ViewerModelInfo) => void`, the same payload as `ModelViewer`'s).
 
 ### `onLoadError`
 
@@ -2175,7 +2753,7 @@ type ObjectBindingTransform = {
 
 type ObjectBinding = {
   id: string;
-  type: ObjectBindingType; // "body" | "light" | "wheel" | "glass" | "interior" | "floor" | "wall" | "door" | "furniture" | "decor" | "electronics" | "other" | ...
+  type?: ObjectBindingType; // any string; suggestions: "body" | "light" | "wheel" | "wall" | "door" | "furniture" | ...; default "other"
   modelObjectId: string;
   label?: string;
   group?: string;
@@ -2208,11 +2786,27 @@ Notes:
 - `BindingBuilder` intentionally omits exact Sketchfab glossiness, cavity, and subsurface-scattering workflows; those require preprocessing or a different material pipeline
 - `cameraState` stores a saved camera view for the object; when both `position` and `target` are set, the viewer uses that view when the object is focused or selected instead of falling back to `fitToBox`
 - `metrics` and `metadata` are displayed in the side panel as nested key/value fields (objects expand into indented child labels)
-- `ObjectBindingType` is a large union covering vehicles, rooms, furniture, characters, weapons, environment, and more
+- `type` groups and filters bindings (for example `hideObject({ type: "wheel" })`). Any string works: `ObjectBindingType` suggests values for vehicles, rooms, furniture, characters, weapons, environment, and more, but a domain it doesn't cover can use its own (`"bone"`, `"turbine-blade"`). Left out, it counts as `"other"`
 
 ## Supported Built-In Actions
 
-Action handling is currently hardcoded in `ModelViewer`.
+`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
+`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
+naming each one. Every action also reaches `onAction`, after the viewer's own
+handling.
+
+`ACTION_CATALOG` lists the ids `BindingBuilder` offers, and whether the viewer
+or your app handles each one (`handling: "viewer" | "host"`):
+
+```ts
+import { ACTION_CATALOG, findCatalogAction } from "@liveroom-tech/react-immersive/utils";
+
+findCatalogAction("toggle-light")?.handling; // "viewer"
+```
 
 ### Implemented behaviors
 
@@ -2222,6 +2816,26 @@ Action handling is currently hardcoded in `ModelViewer`.
   Opens the color picker inline beneath the action; the chosen hex is applied as a live preview while dragging and committed into `binding.style.material.baseColor` via `onObjectBindingsChange` when the picker closes
 - `change-material`
   Opens the texture upload panel inline beneath the action for JPG, PNG, and WebP files; if `onTextureUpload` is provided, the file is passed to it and the returned URL is stored in `binding.style.material.texture.path`; otherwise a session-scoped blob URL is used as the fallback
+- `toggle-light`
+  Turns the object's light off, or back on
+- `change-light-color`
+  Opens a color picker inline beneath the action that sets the light's color
+- `set-brightness`
+  Opens a slider inline beneath the action that sets the light's brightness, from 0 to 200% of what it was when it opened
+
+What "the object's light" is depends on the scene:
+
+- If scene lights are attached to the object (in `BindingBuilder`'s Lighting
+  tab, or with `useSceneConfig().lights.attach`), the actions control those
+  lights, which light up the room around it. The changes go to
+  `sceneConfig.lighting`: to `onSceneConfigChange` if you pass it (`useViewer`
+  does, so `viewer.scene` stays current), otherwise `ModelViewer` keeps them
+  itself, over whatever `sceneConfig` it's given.
+- Otherwise they control the object's own glow: its emissive color and strength,
+  saved on the binding as `style.material.emissive` and
+  `style.material.emissiveIntensity`, like any other edit. This works on any
+  light fixture with no setup, but a glow doesn't light up the objects around
+  it. Toggling off and back on restores the previous strength.
 
 ## How Rendering Works
 
@@ -2247,7 +2861,7 @@ When `shadows` is enabled (the default), the canvas renders soft shadow maps and
 - per-mesh `castShadow`/`receiveShadow`, with one exception: the large enclosing "shell" mesh (walls/ceiling of an interior model) is detected by its bounding-box size and excluded from **casting** so a top-down light still reaches the interior, it continues to **receive** shadows, so furniture casts visible contact shadows onto the floor and walls
 - a post-processing stack (`EffectComposer`) with SSAO ambient occlusion (normal pass enabled), bloom, vignette, and ACES filmic tone mapping
 
-Pass `shadows={false}` to disable shadow rendering entirely, or pass a custom `lights` rig to replace the default lighting.
+Pass `shadows={false}` to disable shadow rendering entirely, or set your own lights in `sceneConfig.lighting` (see [Lighting](#lighting)) to replace the default rig.
 
 ## UI Behavior