@liveroom-tech/react-immersive 1.0.0

package/README.md

@@ -0,0 +1,1730 @@
+# `@liveroom-tech/react-immersive`
+
+`@liveroom-tech/react-immersive` is a React-based 3D model viewer for interactive GLB/GLTF assets. It renders a model with React Three Fiber, lets users click named meshes, shows a built-in side panel for the selected object, and supports per-object actions such as color changes, texture uploads, and visibility toggles.
+
+## What It Does
+
+The library currently exports:
+
+```ts
+import {
+  BindingBuilder,
+  ModelViewer,
+  SimpleModelViewer,
+  useObjectBinding,
+  useObjectBindingIds,
+  useObjectVisibility,
+  useViewerActions,
+  useViewerAnimations,
+  useViewerCamera,
+  useViewerHover,
+  useViewerModel,
+  useViewerSelection,
+  MATERIAL_BLENDING_MODES,
+  MATERIAL_SIDES,
+} from "@liveroom-tech/react-immersive";
+```
+
+It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectActionEvent`, `SceneConfig`, `AnimationControls`, and related shapes used throughout this document.
+
+`ModelViewer` provides:
+
+- GLB/GLTF model rendering through `@react-three/fiber` and `@react-three/drei`
+- 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
+- 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)
+- optional on-screen movement controller through `showMouseController` and its tuning props
+- optional custom left object data panel through `customObjectBindingDataPanel`
+- optional custom right scene objects panel through `customSceneObjectsPanel`
+- optional hiding of either built-in panel through `showObjectBindingDataPanel` and `showSceneObjectsPanel`
+- optional model export button through `showDownloadButton` and `downloadFilename`, plus independent `showResetButton` / `showDownloadButtons` toggles for the rest of that action bar
+- click-to-measure distance tool and a bounding-box dimensions overlay through `showMeasureTools` and `measurementUnit`
+- a guided-tour control cluster (Previous/Stop/Next) for stepping through annotations, toggleable via `showAnnotationNavigation`
+- a `sceneConfig` prop accepting the same scene-wide config (lighting, environment, background, post-processing, animations, annotations) authored by `BindingBuilder`'s Scene tab
+- 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
+- a built-in left side panel for the selected object
+- object-specific action buttons driven by `objectBindings`
+- built-in color picking that commits the chosen hex into `objectBindings.style.material.baseColor`
+- 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`
+- hover and selected-state highlighting
+- external selection state control through `selectedObject` and `onObjectSelect`
+- hover callbacks through `onObjectHover`
+- model-ready callbacks through `onModelLoaded`
+- model-load error callbacks through `onLoadError`
+- camera change callbacks through `onCameraChange`
+- viewer-ready callbacks through `onViewerReady`
+- action event callbacks through `onAction`
+- animation playback for GLB/GLTF models with embedded animations through `onAnimationsReady`
+- annotation marker callbacks through `onAnnotationsChange` and controlled/uncontrolled `activeAnnotation` / `onActiveAnnotationChange`
+
+`BindingBuilder` provides:
+
+- a design-time UI for generating starter bindings from GLB/GLTF assets, gated by `licenseKey` (see "`BindingBuilder` licensing & plan tiers" below)
+- demo model loading or custom `.glb`, `.gltf`, or zipped GLTF upload
+- editable binding fields for identity, basics, style, actions, metrics, metadata, and saved camera state
+- a one-click material preset gallery (wood, metal, chrome, glass, plastic, fabric, ceramic, concrete, etc.)
+- undo/redo for both the Object tab's bindings and the Scene tab's config, independently, with `Cmd/Ctrl+Z` / `Cmd/Ctrl+Shift+Z` shortcuts
+- a Scene tab for the same `sceneConfig` shape `ModelViewer` accepts (lighting, environment, background, post-processing, animations, annotations)
+- 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)
+
+`SimpleModelViewer` provides:
+
+- a lightweight GLB/GLTF viewer that does not require `objectBindings` and does not require a `licenseKey`
+- optional local `.glb`, standalone/data-URI `.gltf`, or zipped GLTF upload mode for ad-hoc inspection without relying on the `modelUrl` asset
+- built-in scene objects panel with search and visibility toggles
+- a built-in environment/scene settings panel (background color, environment preset, auto-rotate, exposure, ambient + directional light) toggleable via `showSceneSettingsPanel`, with each control's initial value seedable via props
+- click-to-select and fit-to-object focus behavior
+- optional background color and model lifecycle callbacks
+- a smaller API surface for simple inspection use cases
+
+## Why `objectBindings` Exists
+
+`objectBindings` solves the gap between a raw GLB/GLTF file and an interactive
+product experience. A model file gives you geometry, materials, and mesh node
+names. It does not know that `"CarBody"` is configurable, that `"FrontDoor"`
+should open a panel, or that `"Wall_A"` should expose metadata and a saved
+camera view.
+
+`objectBindings` is the bridge between those raw mesh names and your app's
+domain model. It is a serializable record, keyed by mesh node name, that lets
+you:
+
+- declare which meshes are interactive
+- carry live render state such as visibility and per-object material overrides
+- attach actions like `change-color`, `change-material`, and `toggle-visibility`
+- store metadata and metrics alongside the 3D scene
+- save camera framing so object focus can use curated views
+
+Because it is plain data, bindings can be authored by hand, generated through
+`BindingBuilder`, stored in a database, versioned as JSON, and round-tripped
+through `onObjectBindingsChange` so your app state and the 3D scene stay in
+sync.
+
+## Why It Is Worth The Setup
+
+At first glance, `objectBindings` can look like extra setup. That is true only
+if your goal is to render a model and do nothing else with it.
+
+If the model needs to behave like part of your application, bindings stop being
+overhead and start being the abstraction that keeps the project maintainable.
+They give you a single source of truth instead of scattering logic across mesh
+refs, material mutations, raycasting handlers, and custom UI glue.
+
+The short version:
+
+- without bindings, the model is a visual asset
+- with bindings, the model becomes application state
+
+If you only need a viewer, use `SimpleModelViewer`. If you need selection,
+customization, persistence, metadata, object-level actions, or app-driven
+behavior, bindings are usually the right tradeoff.
+
+## Example Applications Where Bindings Shine
+
+- product configurators for cars, furniture, apparel, appliances, or custom goods
+- e-commerce customization flows where meshes map to real purchasable options
+- CPQ and sales tools where 3D parts correspond to business rules and pricing
+- real estate and interior design tools with clickable rooms, walls, fixtures, and finishes
+- industrial and engineering viewers for assemblies, equipment, and maintenance workflows
+- training and guided walkthroughs with annotations, steps, and saved object viewpoints
+- digital twins and operational dashboards where scene parts map to live assets, metrics, and alerts
+- smart building controls where lights, switches, sensors, HVAC units, and doors map to real-time app behavior
+
+The pattern is consistent: if users need to say "this exact part of the model
+has its own meaning, state, or behavior," object bindings are a strong fit.
+
+## Installation
+
+```bash
+npm install @liveroom-tech/react-immersive
+```
+
+The component ships with its own internal UI styles through a CSS import. Tailwind is not required in the consuming app.
+
+Peer dependencies:
+
+- `react >= 17`
+- `react-dom >= 17`
+
+`ModelViewer` and `BindingBuilder` require a `licenseKey` at runtime (see [`licenseKey`](#licensekey)). Get one from the Developer Portal — see [Resources](#resources) below.
+
+## Resources
+
+- [Developer Portal](https://react-immersive.liveroom.dev) — sign in, pick a plan, and generate a `licenseKey`
+- [Docs](https://react-immersive.liveroom.dev/docs) — full reference for every component, hook, and prop
+- [Examples & community repo](https://github.com/liveroom-technologies/react-immersive) — public docs source, starter examples, and community resources
+- [Report a bug / request a feature](https://github.com/liveroom-technologies/react-immersive-docs/issues) — for public bug reports, docs issues, and feature requests
+- [Discussions & Q&A](https://github.com/liveroom-technologies/react-immersive-docs/discussions) — ask questions, share ideas, and compare approaches
+- [Private support / security](mailto:developers@liveroom.xyz?subject=React%20Immersive%20Support) — for license, account, confidential customer, or security-sensitive issues
+- [Live editor](https://react-immersive.liveroom.dev/editor) — try `BindingBuilder` in the browser without installing anything
+- [npm package](https://www.npmjs.com/package/@liveroom-tech/react-immersive)
+
+## Quick Start
+
+```tsx
+import { useState } from "react";
+import {
+  ModelViewer,
+  useObjectBinding,
+  useObjectVisibility,
+  useViewerActions,
+  useViewerAnimations,
+  useViewerCamera,
+  useViewerHover,
+  useViewerModel,
+  useViewerSelection,
+} from "@liveroom-tech/react-immersive";
+
+const initialBindings = {
+  CarBody: {
+    id: "car-body",
+    modelObjectId: "CarBody",
+    type: "body",
+    label: "Car Body",
+    selectable: true,
+    hoverable: true,
+    visible: true,
+    style: {
+      material: {
+        texture: {
+          path: "/materials/oak-wood.jpg",
+        },
+      },
+    },
+    metrics: {},
+    metadata: {
+      category: "exterior",
+    },
+    actions: [
+      { id: "change-color", label: "Change Color", type: "command" },
+      { id: "change-material", label: "Change Material", type: "command" },
+      { id: "toggle-visibility", label: "Toggle Visibility", type: "command" },
+    ],
+  },
+};
+
+export default function Example() {
+  const [objectBindings, setObjectBindings] = useState(initialBindings);
+  const { selectedObjectBinding, handleObjectSelect } = useViewerSelection();
+  const { hoveredObjectBinding, handleHoveredObject } = useViewerHover();
+  const {
+    cameraState,
+    resetView,
+    focusObject,
+    fitScene,
+    setCameraTarget,
+    handleCameraChange,
+    handleViewerReady,
+  } = useViewerCamera();
+  const {
+    isLoading,
+    isReady,
+    error,
+    bounds,
+    objectCount,
+    handleModelLoaded,
+    handleLoadError,
+  } = useViewerModel();
+  const { hiddenObjects, toggleObjectVisibility } = useObjectVisibility(
+    objectBindings,
+    setObjectBindings,
+  );
+  const { getActionsForObject, runAction } = useViewerActions(objectBindings, {
+    onAction: (event) => {},
+    onObjectBindingsChange: setObjectBindings,
+  });
+  const focusedBinding = useObjectBinding(objectBindings, "car-body");
+
+  return (
+    <div style={{ height: "100vh", overflow: "hidden" }}>
+      <ModelViewer
+        modelUrl="/model.glb"
+        licenseKey="your-license-key"
+        objectBindings={objectBindings}
+        selectedObject={selectedObjectBinding}
+        onObjectSelect={handleObjectSelect}
+        onObjectHover={handleHoveredObject}
+        onCameraChange={handleCameraChange}
+        onModelLoaded={handleModelLoaded}
+        onLoadError={handleLoadError}
+        onObjectBindingsChange={setObjectBindings}
+        onViewerReady={handleViewerReady}
+        onAction={(event) => {}}
+      />
+
+      <button onClick={() => toggleObjectVisibility("car-body")}>
+        Toggle Visibility
+      </button>
+      <button onClick={() => runAction("car-body", "toggle-visibility")}>
+        Run visibility action
+      </button>
+      <button onClick={() => resetView()}>Reset view</button>
+      <button onClick={() => focusObject("car-body")}>Focus Object</button>
+      <button onClick={() => fitScene()}>Fit scene</button>
+      <button onClick={() => setCameraTarget([0, 0, 0])}>Target origin</button>
+      <pre>{JSON.stringify(getActionsForObject("car-body"), null, 2)}</pre>
+      <pre>{JSON.stringify(cameraState, null, 2)}</pre>
+      <pre>
+        {JSON.stringify(
+          { isLoading, isReady, error, bounds, objectCount },
+          null,
+          2,
+        )}
+      </pre>
+      <pre>{JSON.stringify(hiddenObjects, null, 2)}</pre>
+      <pre>{JSON.stringify(hoveredObjectBinding, null, 2)}</pre>
+      <pre>{JSON.stringify(focusedBinding, null, 2)}</pre>
+    </div>
+  );
+}
+```
+
+If you want a simple helper for selection state, the library also exports:
+
+```tsx
+const {
+  selectedObjectBinding,
+  setSelectedObjectBinding,
+  handleObjectSelect,
+  clearSelection,
+} = useViewerSelection();
+```
+
+If you want to resolve a binding from an object identifier, the library also exports:
+
+```tsx
+const binding = useObjectBinding(objectBindings, "car-body");
+```
+
+`useObjectBinding` checks, in order:
+
+- the object binding map key
+- `binding.id`
+- `binding.modelObjectId`
+
+If you want a flat list of every `modelObjectId` across your bindings, the library also exports:
+
+```tsx
+const ids = useObjectBindingIds(objectBindings);
+// → ["CarBody", "WheelFL", "WheelFR", ...]
+```
+
+If you want to control object visibility outside the viewer, the library also exports:
+
+```tsx
+const [objectBindings, setObjectBindings] = useState(initialBindings);
+
+const {
+  hiddenObjects,
+  hiddenObjectIds,
+  hideObject,
+  showObject,
+  toggleObjectVisibility,
+  isObjectHidden,
+  clearHiddenObjects,
+} = useObjectVisibility(objectBindings, setObjectBindings);
+
+<ModelViewer
+  modelUrl="/model.glb"
+  licenseKey="your-license-key"
+  objectBindings={objectBindings}
+  onObjectBindingsChange={setObjectBindings}
+/>;
+```
+
+`useObjectVisibility` is a stateless utility hook. It does not own its own copy of `objectBindings` — the consumer owns the state and passes both the current value and its setter. The hook's methods (`hideObject`, `showObject`, etc.) call the setter directly, so there is no risk of the hook and the viewer drifting out of sync.
+
+It accepts either:
+
+- the object binding map key
+- `binding.id`
+- `binding.modelObjectId`
+
+and returns:
+
+- `hiddenObjects`: a derived map of hidden binding keys
+- `hiddenObjectIds`: the currently hidden binding IDs
+- `hideObject`, `showObject`, `toggleObjectVisibility`
+- `isObjectHidden`
+- `clearHiddenObjects`
+
+If you want to keep hover state in sync with the viewer, the library also exports:
+
+```tsx
+const { hoveredObjectBinding, handleHoveredObject } = useViewerHover();
+
+<ModelViewer
+  modelUrl="/model.glb"
+  licenseKey="your-license-key"
+  objectBindings={objectBindings}
+  onObjectHover={handleHoveredObject}
+/>;
+```
+
+`useViewerHover` returns:
+
+- `hoveredObjectBinding`: the currently hovered binding or `null`
+- `handleHoveredObject`: a callback you can pass directly to `onObjectHover`
+
+If you want model lifecycle and scene metadata, the library also exports:
+
+```tsx
+const {
+  isLoading,
+  isReady,
+  error,
+  bounds,
+  objectCount,
+  handleModelLoaded,
+  handleLoadError,
+} = useViewerModel();
+
+<ModelViewer
+  modelUrl="/model.glb"
+  licenseKey="your-license-key"
+  objectBindings={objectBindings}
+  onModelLoaded={handleModelLoaded}
+  onLoadError={handleLoadError}
+/>;
+```
+
+`useViewerModel` returns:
+
+- `isLoading`: `true` until the model has loaded or failed
+- `isReady`: `true` after a successful model load
+- `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
+- `handleModelLoaded`: a callback you can pass directly to `onModelLoaded`
+- `handleLoadError`: a callback you can pass directly to `onLoadError`
+
+If you want to inspect or trigger binding actions programmatically, the library also exports:
+
+```tsx
+const { getActionsForObject, runAction } = useViewerActions(objectBindings, {
+  onAction: (event) => {},
+  onObjectBindingsChange: setObjectBindings,
+});
+
+const actions = getActionsForObject("car-body");
+runAction("car-body", "toggle-visibility");
+```
+
+`useViewerActions` returns:
+
+- `getActionsForObject`: resolves the actions configured for a binding by key, `binding.id`, or `binding.modelObjectId`
+- `runAction`: dispatches an `ObjectActionEvent` and returns it, or `null` if the binding or action cannot be found
+
+Current note:
+
+- visibility-style actions (`toggle-visibility`) update binding data through `onObjectBindingsChange`
+- color/material actions still rely on `ModelViewer`'s built-in UI popovers, so `runAction` dispatches those events but does not open the internal color picker or texture upload popover by itself
+
+## `BindingBuilder`
+
+`BindingBuilder` is an exported design-time helper component for authoring `objectBindings` in the browser.
+
+Basic usage:
+
+```tsx
+import { BindingBuilder } from "@liveroom-tech/react-immersive";
+
+export default function App() {
+  return <BindingBuilder licenseKey="your-license-key" />;
+}
+```
+
+`BindingBuilder` accepts one required prop:
+
+```ts
+type BindingBuilderProps = {
+  licenseKey: string;
+};
+```
+
+`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:
+
+- load the bundled demo model or upload a `.glb`, standalone/data-URI `.gltf`, or `.zip` containing a `.gltf` plus its referenced `.bin` and texture files
+- traverse renderable mesh nodes and generate starter bindings automatically
+- edit binding identity, label, type, status, booleans, style, actions, metrics, metadata, and saved camera state
+- 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
+- import a previously exported `objectBindings.json`, merged onto the current model by `modelObjectId`
+- export the current bindings as JSON or TypeScript — bundled into a `.zip` (with a `materials/` folder) when any texture field was filled by uploading a file, otherwise a plain file
+
+Current behavior — Scene tab:
+
+- configure the same `SceneConfig` shape `ModelViewer`'s `sceneConfig` prop accepts (lighting, environment, background, ground shadows, wireframe, post-processing, animations, annotations)
+- 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
+
+Preview:
+
+- the selected node previews live in an embedded `ModelViewer`
+
+### `BindingBuilder` licensing & plan tiers
+
+Some editor features are gated by the license's plan tier (the server-returned `tier`, normalized to `"free" | "starter" | "growth"`):
+
+| 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                                                                   |
+| `growth`  | + Post-processing effects                                                                                                                                                                                                     |
+
+A locked feature renders in place (not hidden) with a message naming the required plan, so it stays discoverable while editing.
+
+## `SimpleModelViewer`
+
+`SimpleModelViewer` is an exported lightweight viewer for cases where you want to load a GLB/GLTF asset, inspect meshes, and toggle visibility without building `objectBindings`. It can either load a fixed `modelUrl` or, when `enableModelUpload` is turned on, let the user drag-and-drop or choose a local model at runtime.
+
+Basic usage:
+
+```tsx
+import { SimpleModelViewer } from "@liveroom-tech/react-immersive";
+
+export default function App() {
+  return (
+    <div style={{ height: "100vh" }}>
+      <SimpleModelViewer modelUrl="/model.glb" />
+    </div>
+  );
+}
+```
+
+`SimpleModelViewer` does not take a `licenseKey` — licensing is enforced by `ModelViewer` and `BindingBuilder` only.
+
+Sizing note:
+
+- `SimpleModelViewer` fills the width and height of its parent container
+- give the parent an explicit height (for example `100vh`, `480px`, or a Tailwind class like `h-[100px]`) when you want a fixed viewer height
+
+Current behavior:
+
+- discovers renderable meshes directly from the loaded GLB/GLTF scene
+- renders a right-side scene objects panel with search and visibility toggles
+- renders a left-side environment/scene settings panel (background color, environment preset, auto-rotate, exposure, ambient + directional light) toggleable via `showSceneSettingsPanel`, with every control seedable via props
+- optionally replaces `modelUrl` with a drag-and-drop / file-picker flow when `enableModelUpload` is enabled
+- lets users click a mesh or panel row to select and focus it
+- fits the full scene on initial load
+- uses built-in ambient, directional, and environment lighting
+
+Use `SimpleModelViewer` when you want a quick inspection viewer.
+Use `ModelViewer` when you need binding-driven styling, actions, metadata, custom panels, exports, or animation integrations.
+
+If you want camera state and imperative camera helpers, the library also exports:
+
+```tsx
+const {
+  cameraState,
+  resetView,
+  focusObject,
+  fitScene,
+  setCameraTarget,
+  handleCameraChange,
+  handleViewerReady,
+} = useViewerCamera();
+
+<ModelViewer
+  modelUrl="/model.glb"
+  licenseKey="your-license-key"
+  objectBindings={objectBindings}
+  onCameraChange={handleCameraChange}
+  onViewerReady={handleViewerReady}
+/>;
+```
+
+`useViewerCamera` returns:
+
+- `cameraState`: the latest camera `position`, `target`, `fov`, and `zoom`
+- `resetView`: resets the controls to their initial saved state
+- `focusObject`: fits the camera to a binding by key, `binding.id`, or `binding.modelObjectId`
+- `fitScene`: fits the camera to the whole loaded scene
+- `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`
+- `handleCameraChange`: a callback you can pass directly to `onCameraChange`
+- `handleViewerReady`: a callback you can pass directly to `onViewerReady`
+
+If your GLB/GLTF model contains animations, the library also exports:
+
+```tsx
+const {
+  clips,
+  currentClip,
+  isPlaying,
+  speed,
+  play,
+  pause,
+  stop,
+  setSpeed,
+  handleAnimationsReady,
+} = useViewerAnimations();
+
+<ModelViewer
+  modelUrl="/character.glb"
+  licenseKey="your-license-key"
+  objectBindings={objectBindings}
+  onAnimationsReady={handleAnimationsReady}
+/>;
+```
+
+`useViewerAnimations` returns:
+
+- `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
+- `handleAnimationsReady`: a callback you can pass directly to `onAnimationsReady`
+
+Example with playback controls:
+
+```tsx
+const { clips, currentClip, isPlaying, play, pause, stop, setSpeed } =
+  useViewerAnimations();
+
+// Play/pause toggle
+<button onClick={() => (isPlaying ? pause() : play(currentClip ?? clips[0]))}>
+  {isPlaying ? "Pause" : "Play"}
+</button>
+
+// Stop
+<button onClick={stop}>Stop</button>
+
+// Speed slider
+<input
+  type="range"
+  min="0.1"
+  max="3"
+  step="0.1"
+  defaultValue="1"
+  onChange={(e) => setSpeed(Number(e.target.value))}
+/>
+
+// Clip selector
+{clips.map((name) => (
+  <button key={name} onClick={() => play(name)}>
+    {name} {currentClip === name && isPlaying ? "▶" : ""}
+  </button>
+))}
+```
+
+## Public API
+
+The source code currently defines `ModelViewer` with these props:
+
+```ts
+type Props = {
+  modelUrl: string;
+  licenseKey: string;
+  objectBindings: Record<string, ObjectBinding>;
+  selectedObject?: ObjectBinding | null;
+  onObjectBindingsChange?: (next: Record<string, ObjectBinding>) => void;
+  onObjectSelect?: (binding: ObjectBinding | null) => void;
+  onObjectHover?: (binding: ObjectBinding | null) => void;
+  onModelLoaded?: (scene: Object3D) => void;
+  onLoadError?: (error: unknown) => void;
+  onAction?: (event: ObjectActionEvent) => void;
+  onHiddenObjectsChange?: (next: Record<string, boolean>) => void;
+  onCameraChange?: (camera: Camera, controls: CameraControls) => void;
+  onViewerReady?: (viewer: ViewerReadyState) => void;
+  onTextureUpload?: (file: File, objectId: string) => Promise<string>;
+  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"];
+  backgroundColor?: string;
+  shadows?: boolean;
+  showObjectBindingDataPanel?: boolean;
+  customObjectBindingDataPanel?: (
+    props: CustomObjectBindingDataPanelProps,
+  ) => React.ReactNode;
+  customSceneObjectsPanel?: (
+    props: CustomSceneObjectsPanelProps,
+  ) => React.ReactNode;
+  showSceneObjectsPanel?: boolean;
+  showDownloadButton?: boolean;
+  downloadFilename?: string;
+  showResetButton?: boolean;
+  showDownloadButtons?: boolean;
+  showLoadingOverlay?: boolean;
+  showMouseController?: boolean;
+  mouseControllerPosition?:
+    | "bottom-left"
+    | "bottom-right"
+    | "top-left"
+    | "top-right"
+    | "center"
+    | "center-bottom"
+    | "center-top";
+  mouseControllerOpacity?: number;
+  moveSensitivity?: number;
+  zoomSensitivity?: number;
+  sceneConfig?: SceneConfig;
+  disableZoom?: boolean;
+  zoomOnSelected?: boolean;
+  onAutoFit?: () => Promise<boolean>;
+  refitOnResize?: boolean;
+  renderMode?: "always" | "demand";
+  maxDpr?: number;
+  performanceProfile?: "auto" | "high" | "low";
+  dracoDecoderPath?: string | false;
+  ktx2TranscoderPath?: string | false;
+  meshopt?: boolean;
+  showMeasureTools?: boolean;
+  measurementUnit?: string;
+  enableXR?: boolean;
+  usdzUrl?: string;
+  showAnnotationNavigation?: boolean;
+};
+```
+
+### `modelUrl`
+
+URL or public path to the `.glb` or `.gltf` model. For `.gltf` URLs with external `.bin` or texture files, those files must be hosted at the relative paths declared in the `.gltf`.
+
+Example:
+
+```tsx
+modelUrl = "/model.glb";
+```
+
+### `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.
+
+`objectBindings` is the single source of truth for all visual state. Changes to the binding record drive rendering:
+
+- `visible` controls mesh visibility
+- `style.material.baseColor` sets the mesh color (committed by the built-in color picker on close)
+- `style.material.texture.path` sets the mesh texture (committed by the built-in texture upload; uses `onTextureUpload` for a durable URL when provided, otherwise a session-scoped blob URL)
+- `style.material.*` applies per-object `MeshPhysicalMaterial` overrides such as emissive, metalness, roughness, opacity, clearcoat, sheen, anisotropy, specular, transmission, thickness, reflectivity, and sidedness
+- `cameraState.position` and `cameraState.target` define the camera view to use when that object is focused or selected from the viewer UI
+
+Example:
+
+```ts
+const objectBindings = {
+  Object_2: {
+    id: "obj-2",
+    modelObjectId: "Object_2",
+    type: "body",
+    visible: true,
+    cameraState: {
+      position: [2.8, 1.6, 4.2],
+      target: [0, 0.8, 0],
+    },
+    style: {
+      material: {
+        baseColor: "#ff0000",
+        texture: {
+          path: "/materials/body-finish.jpg",
+        },
+      },
+    },
+    actions: [
+      { id: "change-color", label: "Change Color", type: "command" },
+      { id: "change-material", label: "Change Material", type: "command" },
+      { id: "toggle-visibility", label: "Toggle Visibility", type: "command" },
+    ],
+    metrics: {},
+    metadata: {},
+  },
+};
+```
+
+### `selectedObject`
+
+Optional currently selected object binding, or `null` when nothing is selected.
+
+If provided, `ModelViewer` behaves as a controlled component.
+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`.
+
+### `onObjectSelect`
+
+Optional callback called when the user clicks a mesh or closes the side panel.
+
+Behavior:
+
+- clicking a mesh calls `onObjectSelect(binding)`
+- closing the panel calls `onObjectSelect(null)`
+- clicking the same mesh again still selects it; selection is not toggled off automatically
+- if the binding includes `cameraState.position` and `cameraState.target`, the viewer moves the camera to that saved view when focusing that object
+
+### `onObjectHover`
+
+Optional callback called when the user hovers a mesh in the model.
+
+Behavior:
+
+- pointer over a mesh calls `onObjectHover(binding)`
+- pointer out calls `onObjectHover(null)`
+
+### `onHiddenObjectsChange`
+
+Optional callback fired with the derived hidden-object map whenever the current binding data changes hidden visibility state.
+
+### `onObjectBindingsChange`
+
+Optional callback fired when the viewer's built-in UI updates binding data.
+
+This fires for:
+
+- visibility toggles (`binding.visible`)
+- color picks (`binding.style.material.baseColor`) — committed when the color picker closes
+- texture uploads (`binding.style.material.texture.path`) — committed immediately (via `onTextureUpload` when provided, otherwise as a blob URL)
+- texture removal (`binding.style.material.texture` cleared)
+
+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`
+
+Optional callback fired after the GLB/GLTF scene has been loaded.
+
+Current callback shape:
+
+```ts
+(scene: Object3D) => void
+```
+
+### `onLoadError`
+
+Optional callback fired if the model fails to load or render.
+
+Current callback shape:
+
+```ts
+(error: unknown) => void
+```
+
+### `onAction`
+
+Optional callback fired when a built-in action button is clicked from the side panel.
+
+Current event shape:
+
+```ts
+type ObjectActionEvent = {
+  objectId: string;
+  action: ObjectBindingAction;
+  binding?: ObjectBinding;
+  screenX?: number;
+  screenY?: number;
+};
+```
+
+### `onViewerReady`
+
+Optional callback fired once camera controls are available and again when the
+viewer publishes updated ready-state data (for example after model load,
+camera changes, or binding changes).
+
+Current callback shape:
+
+```ts
+(viewer: ViewerReadyState) => void
+```
+
+`ViewerReadyState` includes `captureImage`, an imperative method for grabbing a PNG snapshot of the canvas:
+
+```ts
+type ViewerReadyState = {
+  controls: CameraControls;
+  scene: Object3D | null;
+  objectBindings: Record<string, ObjectBinding>;
+  nodeRefs: Record<string, Object3D>;
+  captureImage: (options?: CaptureImageOptions) => Promise<string>;
+};
+
+type CaptureImageOptions = {
+  width?: number;
+  height?: number;
+  transparent?: boolean;
+};
+```
+
+`captureImage` 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.
+
+```tsx
+onViewerReady={(viewer) => {
+  viewer
+    .captureImage({ width: 1920, height: 1080, transparent: true })
+    .then((dataUrl) => {
+      // upload, preview, etc.
+    });
+}}
+```
+
+Note: requesting a custom `width`/`height` briefly resizes the live canvas to render at that resolution before restoring it, which can cause a momentary flicker on screen — fine for an occasional snapshot, not for rapid/looped calls.
+
+If you're also using `useViewerCamera`'s `handleViewerReady`, call both from your own `onViewerReady` to get camera helpers and `captureImage` together:
+
+```tsx
+onViewerReady={(viewer) => {
+  handleViewerReady(viewer);
+  captureImageRef.current = viewer.captureImage;
+}}
+```
+
+### `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.
+
+Current callback shape:
+
+```ts
+(file: File, objectId: string) => Promise<string>;
+```
+
+The returned string is stored in `binding.style.material.texture.path` via `onObjectBindingsChange`.
+
+If omitted, the viewer falls back to `URL.createObjectURL(file)` which produces a short blob URL that works for the current session but is lost on reload.
+
+Example:
+
+```tsx
+<ModelViewer
+  modelUrl="/model.glb"
+  licenseKey="your-license-key"
+  objectBindings={objectBindings}
+  onObjectBindingsChange={setObjectBindings}
+  onTextureUpload={async (file, objectId) => {
+    const formData = new FormData();
+    formData.append("file", file);
+    formData.append("objectId", objectId);
+    const res = await fetch("/api/upload-texture", {
+      method: "POST",
+      body: formData,
+    });
+    const { url } = await res.json();
+    return url; // e.g. "https://cdn.example.com/textures/abc123.png"
+  }}
+/>
+```
+
+### `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.
+
+Current callback shape:
+
+```ts
+(controls: AnimationControls) => void
+```
+
+Where `AnimationControls` is:
+
+```ts
+type AnimationPlaybackState = {
+  currentClip: string | null;
+  isPlaying: boolean;
+  speed: number;
+  time: number; // live position of the current clip, in seconds
+  duration: number; // length of the current clip, in seconds
+};
+
+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)
+  getState?: () => AnimationPlaybackState;
+  subscribe?: (listener: (state: AnimationPlaybackState) => void) => () => void;
+};
+```
+
+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.
+
+### `lights`
+
+Optional custom lighting to render inside the scene.
+
+If omitted, `ModelViewer` uses the library's default light rig.
+
+Example:
+
+```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} />
+    </>
+  );
+}
+
+<ModelViewer
+  modelUrl="/model.glb"
+  licenseKey="your-license-key"
+  objectBindings={objectBindings}
+  lights={<CustomLights />}
+/>;
+```
+
+### `camera`
+
+Optional custom camera configuration passed through to the underlying React Three Fiber `Canvas`.
+
+`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.
+
+Example:
+
+```tsx
+<ModelViewer
+  modelUrl="/model.glb"
+  licenseKey="your-license-key"
+  objectBindings={objectBindings}
+  camera={{
+    position: [0, 2.2, 7],
+    fov: 40,
+    near: 0.1,
+    far: 1000,
+  }}
+/>
+```
+
+### `backgroundColor`
+
+Optional background color for the viewer canvas.
+
+Example:
+
+```tsx
+<ModelViewer
+  modelUrl="/model.glb"
+  licenseKey="your-license-key"
+  objectBindings={objectBindings}
+  backgroundColor="#0f172a"
+/>
+```
+
+### `shadows`
+
+Optional boolean that controls whether the viewer renders shadows.
+
+Default:
+
+```ts
+true;
+```
+
+When `true`, the canvas renders soft shadows: the default light rig casts a shadow from a directional key light, furniture and decor meshes cast and receive shadows, and ambient occlusion is applied through post-processing. When `false`, shadow map rendering is disabled entirely on the canvas, so there is no shadow-pass cost (the per-mesh and light `castShadow`/`receiveShadow` flags are simply ignored).
+
+Example:
+
+```tsx
+<ModelViewer
+  modelUrl="/model.glb"
+  licenseKey="your-license-key"
+  objectBindings={objectBindings}
+  shadows={false}
+/>
+```
+
+> **Interior models (rooms, dollhouses):** a single large mesh usually forms the walls/ceiling enclosure. If that shell cast shadows it would seal the whole interior in darkness when lit from outside, so the viewer automatically detects the enclosure (a mesh spanning most of the scene footprint in both horizontal axes) and excludes it from casting while still letting it **receive** shadows. Furniture and decor then cast realistic contact shadows onto the floor. See [How Rendering Works](#how-rendering-works).
+
+### `onCameraChange`
+
+Optional callback fired whenever the camera controls update the camera.
+
+Current callback shape:
+
+```ts
+(camera: Camera, controls: CameraControls) => void
+```
+
+### `showObjectBindingDataPanel`
+
+Optional boolean that controls whether the built-in left object details panel is rendered.
+
+Default:
+
+```ts
+true;
+```
+
+### `customObjectBindingDataPanel`
+
+Optional render prop for replacing the built-in left object details panel.
+
+Current prop shape:
+
+```ts
+type CustomObjectBindingDataPanelProps = {
+  isOpen: boolean;
+  selectedObject: ObjectBinding | null;
+  currentAction: ObjectActionEvent | null;
+  onClose: () => void;
+  onAction: (event: ObjectActionEvent) => void;
+};
+```
+
+When provided, `ModelViewer` passes its existing internal handlers into your custom panel. Your panel can call them, wrap them, or ignore them.
+
+### `customSceneObjectsPanel`
+
+Optional render prop for replacing the built-in right scene objects panel.
+
+Current prop shape:
+
+```ts
+type CustomSceneObjectsPanelProps = {
+  objectBindings: Record<string, ObjectBinding>;
+  onAction?: (event: ObjectActionEvent) => void;
+  onFocus?: (binding: ObjectBinding) => void;
+  onHover?: (binding: ObjectBinding | null) => void;
+};
+```
+
+When provided, `ModelViewer` passes the current bindings plus its built-in action, focus, and hover handlers into your custom panel.
+
+### `showSceneObjectsPanel`
+
+Optional boolean that controls whether the built-in right scene objects panel is rendered.
+
+Default:
+
+```ts
+true;
+```
+
+### `showDownloadButton`
+
+Optional boolean that enables the download split-button (export GLB / export PNG screenshot).
+
+Default:
+
+```ts
+true;
+```
+
+The bottom-right action bar only renders at all when at least one of `showResetButton`, `showDownloadButtons`, or (`showAnnotationNavigation` with annotations present) is `true`. Within that bar, the download button itself requires **both** `showDownloadButtons` and `showDownloadButton` to be `true`.
+
+### `downloadFilename`
+
+Optional filename stem for the built-in model export button.
+
+Default:
+
+```ts
+"model";
+```
+
+### `showResetButton`
+
+Optional boolean that shows the "reset camera view" button in the bottom-right action bar.
+
+Default:
+
+```ts
+true;
+```
+
+### `showDownloadButtons`
+
+Optional boolean — master toggle for the download split-button area in the bottom-right action bar. Set to `false` to hide it regardless of `showDownloadButton`.
+
+Default:
+
+```ts
+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.
+
+Default:
+
+```ts
+true;
+```
+
+### `showMouseController`
+
+Optional boolean that renders an on-screen joystick controller for moving the camera with a mouse or touch — useful on touch devices or kiosk layouts where drag-to-orbit is awkward.
+
+Default:
+
+```ts
+false;
+```
+
+### `mouseControllerPosition`
+
+Optional placement for the on-screen controller.
+
+```ts
+type MouseControllerPosition =
+  | "bottom-left"
+  | "bottom-right"
+  | "top-left"
+  | "top-right"
+  | "center"
+  | "center-bottom"
+  | "center-top";
+```
+
+### `mouseControllerOpacity`
+
+Optional opacity for the on-screen controller.
+
+Default:
+
+```ts
+1;
+```
+
+### `moveSensitivity`
+
+Optional movement sensitivity for the on-screen controller.
+
+Default:
+
+```ts
+0.08;
+```
+
+### `zoomSensitivity`
+
+Optional zoom sensitivity for the underlying `CameraControls` zoom interaction (mouse wheel / trackpad / pinch).
+
+Default:
+
+```ts
+1.0;
+```
+
+Example:
+
+```tsx
+<ModelViewer
+  modelUrl="/model.glb"
+  licenseKey="your-license-key"
+  objectBindings={objectBindings}
+  showMouseController
+  mouseControllerPosition="bottom-right"
+  mouseControllerOpacity={0.8}
+  moveSensitivity={0.1}
+  zoomSensitivity={1.2}
+/>
+```
+
+### `sceneConfig`
+
+Optional scene-wide configuration object (`SceneConfig`) covering model, camera, lighting, wireframe, shadows, environment, background, ground shadows, post-processing, animations, and annotations. It is the same shape authored by `BindingBuilder`'s Scene tab. If omitted, the viewer uses its built-in default scene config.
+
+`sceneConfig.animations` drives autoplay and per-clip playback settings, and `sceneConfig.annotations` seeds the annotation markers rendered on the model.
+
+### `disableZoom`
+
+Optional boolean. When `true`, the viewer never zooms the camera to an object on selection (selection still highlights and fires callbacks).
+
+Default:
+
+```ts
+false;
+```
+
+### `zoomOnSelected`
+
+Optional boolean controlling whether selecting an object zooms/fits the camera to it. Set to `false` to keep the current camera framing on selection. Zooming is also skipped when `disableZoom` is `true`.
+
+Default:
+
+```ts
+true;
+```
+
+### `onAutoFit`
+
+Optional async callback fired once the model has loaded and the scene is ready. When provided, the viewer calls it so consumers can run their own fit-to-scene behavior (e.g. an animated fit); if omitted, the viewer falls back to its internal `fitScene`.
+
+Current callback shape:
+
+```ts
+() => Promise<boolean>;
+```
+
+### `refitOnResize`
+
+Optional boolean controlling whether the camera re-frames the model to fit whenever the canvas is resized — a browser window resize, a device rotation, or a side panel opening/closing (which changes how much width the canvas has). Set to `false` to preserve the user's current orbit/zoom across resizes; the camera aspect stays correct either way, so the model never distorts, it just isn't re-centered. This only affects re-fits _after_ the initial mount-time auto-fit.
+
+Default:
+
+```ts
+true;
+```
+
+### `onAnnotationsChange`
+
+Optional callback fired when the annotation markers on the model change (added, edited, or removed through the viewer UI).
+
+Current callback shape:
+
+```ts
+(annotations: AnnotationMarker[]) => void
+```
+
+Where `AnnotationMarker` is the `SceneAnnotationMarker` shape:
+
+```ts
+type AnnotationMarker = {
+  id: number;
+  worldPosition: [number, number, number];
+  localPosition: [number, number, number];
+  title: string;
+  description: string;
+};
+```
+
+### `activeAnnotation` / `onActiveAnnotationChange`
+
+Optional controlled state for which annotation is currently open. Pass `activeAnnotation` to control it from your app, and `onActiveAnnotationChange` to be notified when the viewer wants to open (`AnnotationMarker`) or close (`null`) one. If `activeAnnotation` is left `undefined`, the viewer manages this state internally (uncontrolled).
+
+Current shapes:
+
+```ts
+activeAnnotation?: AnnotationMarker | null;
+onActiveAnnotationChange?: (annotation: AnnotationMarker | null) => void;
+```
+
+### `renderMode`
+
+Optional render loop mode. `"demand"` (default) only re-renders the canvas when something changes (camera move, state update, animation frame); `"always"` runs a continuous render loop.
+
+### `maxDpr`
+
+Optional upper bound for the device pixel ratio used when rendering, so retina/4K displays don't render at full 2–3x cost.
+
+Default:
+
+```ts
+2;
+```
+
+### `performanceProfile`
+
+Optional control over how aggressively the viewer trades visual fidelity for a stable WebGL context on constrained GPUs.
+
+```ts
+performanceProfile?: "auto" | "high" | "low";
+```
+
+- `"auto"` (default) — applies a reduced profile on handheld/mobile browsers and other low-power touch devices: the postprocessing pipeline is skipped, soft shadows are disabled, and the device pixel ratio is capped. Desktop-class touch devices may still keep the higher-quality path when they advertise plenty of memory. This keeps mobile GPUs within their memory budget so the context isn't lost — which also keeps WebXR (`enableXR`) usable, since a lost context can't start a session.
+- `"high"` — always render at full quality (postprocessing, soft shadows, full `maxDpr`), even on mobile. Use when you know the target devices can handle it.
+- `"low"` — always apply the reduced profile, on any device.
+
+Default:
+
+```ts
+"auto";
+```
+
+### `dracoDecoderPath` / `ktx2TranscoderPath` / `meshopt`
+
+Optional controls for the compressed-asset decoders used when loading the GLB/GLTF asset.
+
+```ts
+dracoDecoderPath?: string | false;
+ktx2TranscoderPath?: string | false;
+meshopt?: boolean;
+```
+
+DRACO, Meshopt, and KTX2 decoding are enabled by default via hosted decoder/transcoder bundles, fetched lazily only when the model needs them. Pass a path to self-host the decoder/transcoder files, or `false` to disable that decoder.
+
+### `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.
+
+Default:
+
+```ts
+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.
+
+Default:
+
+```ts
+"m";
+```
+
+### `enableXR`
+
+Optional boolean that enables XR entry points. On WebXR-capable browsers, the viewer shows a **"View in your space"** (AR) and/or **"Enter VR"** button once `navigator.xr.isSessionSupported(...)` resolves `true` for that mode. On iPhone/iPad, WebXR AR is not available, but if you also pass [`usdzUrl`](#usdzUrl), the viewer shows a **"View in AR"** button that launches Apple Quick Look instead.
+
+On entering a session the model is normalized (scaled to ~1 m on its longest axis) and rested on the floor a short distance in front of the viewer, so large/real-scale scenes are framed instead of engulfing the viewer.
+
+**AR placement gestures** — inside an AR session the viewer now uses an explicit placement flow:
+
+- before placement, a bottom label says **"Move your device over a flat surface"** until a hit-testable surface is found
+- once a surface is found, a reticle appears on it and the label changes to **"Tap to place"**
+- tapping the screen or the label places the model at the reticle
+- after placement, **pinch** (two fingers) resizes the model and **twist** rotates it around its vertical axis without changing its position
+- a bottom **"Relocate"** button lets the user press-and-hold to bring the reticle back; releasing the button places the model at the current reticle position
+
+VR sessions keep the initial framed placement (there are no real surfaces to hit-test against).
+
+> Postprocessing is automatically disabled during an XR session (the effect composer isn't WebXR-aware). Note also that on low-power devices the default [`performanceProfile`](#performanceprofile) of `"auto"` already disables postprocessing and soft shadows — important for keeping the WebGL context alive so AR can start at all.
+
+Default:
+
+```ts
+false;
+```
+
+### `usdzUrl`
+
+Optional `USDZ` URL used as an Apple-device fallback when `enableXR` is `true`.
+On iPhone/iPad, if WebXR AR is unavailable and this prop is provided, the viewer
+shows a **"View in AR"** button that launches Apple Quick Look for the given
+asset.
+
+```ts
+usdzUrl?: string;
+```
+
+Notes:
+
+- this should point to a `.usdz` file that Safari can fetch directly
+- Android / WebXR-capable devices ignore this and continue using the normal WebXR AR flow
+- if `usdzUrl` is omitted, Apple handheld devices simply won't get an AR button
+
+### `showAnnotationNavigation`
+
+Optional boolean that shows the "Guided Tour" control cluster when the model has at least one annotation: a single "Guided Tour" button that, once started, becomes Previous/Stop/Next controls for stepping through annotations in order.
+
+Default:
+
+```ts
+true;
+```
+
+### Theming the scene objects / object binding panels
+
+The scene objects panel and object binding data panel read their colors,
+borders, shadows, and fonts from CSS custom properties (`--ri-sidepanel-*`
+and `--ri-databinding-*`) instead of hardcoded values, each with the current
+look baked in as a fallback. Override them on a `.ri-viewer` ancestor to
+re-skin those panels:
+
+```css
+.my-app .ri-viewer {
+  --ri-sidepanel-bg: #1a0033;
+  --ri-sidepanel-accent: #ff2d75;
+}
+```
+
+See the full variable list in the [`ModelViewer` docs](https://react-immersive.liveroom.dev/docs/reference/model-viewer#theming).
+
+## `SimpleModelViewer` Public API
+
+```ts
+type SimpleModelViewerProps = {
+  modelUrl: string;
+  backgroundColor?: string;
+  showSceneObjectsPanel?: boolean;
+  showSceneSettingsPanel?: boolean;
+  enableModelUpload?: boolean;
+  zoomOnSelected?: boolean;
+  highlightOnHover?: boolean;
+  showLoadingOverlay?: boolean;
+  refitOnResize?: boolean;
+  // Initial values for the scene settings (environment) panel
+  backgroundEnabled?: boolean;
+  autoRotate?: boolean;
+  envPreset?: PresetsType; // @react-three/drei environment preset
+  exposure?: number;
+  ambientIntensity?: number;
+  ambientColor?: string;
+  directionalIntensity?: number;
+  directionalColor?: string;
+  onModelLoaded?: (scene: Object3D) => void;
+  onLoadError?: (error: unknown) => void;
+};
+```
+
+`SimpleModelViewer` does not take a `licenseKey` — licensing is enforced by `ModelViewer` and `BindingBuilder` only.
+
+### `modelUrl`
+
+URL or public path to the `.glb` or `.gltf` model to inspect. For `.gltf` URLs with external `.bin` or texture files, those files must be hosted at the relative paths declared in the `.gltf`.
+
+### `backgroundColor`
+
+Optional canvas background color.
+
+Default:
+
+```ts
+"#1a1a1a";
+```
+
+### `showSceneObjectsPanel`
+
+Optional boolean that controls whether the right-side scene objects panel is rendered.
+
+Default:
+
+```ts
+true;
+```
+
+### `showSceneSettingsPanel`
+
+Optional boolean that controls whether the left-side environment/scene settings panel is rendered. It exposes background color/visibility, the `@react-three/drei` environment preset, auto-rotate, exposure, and ambient/directional light color and intensity.
+
+Default:
+
+```ts
+true;
+```
+
+### Scene settings defaults
+
+The following optional props seed the initial values of the scene settings (environment) panel. Each maps to one control, and the panel stays interactive so the user can still adjust them at runtime. They are initial values (not controlled props): changing one after mount does not override a value the user has since changed in the panel — the exception is `backgroundColor`, which stays in sync live.
+
+| Prop                   | Type          | Panel control           | Default     |
+| ---------------------- | ------------- | ----------------------- | ----------- |
+| `backgroundEnabled`    | `boolean`     | Background on/off       | `false`     |
+| `autoRotate`           | `boolean`     | Auto Rotate             | `false`     |
+| `envPreset`            | `PresetsType` | Environment preset      | `"city"`    |
+| `exposure`             | `number`      | Exposure                | `1`         |
+| `ambientIntensity`     | `number`      | Ambient Light Intensity | `0.6`       |
+| `ambientColor`         | `string`      | Ambient Light Color     | `"#ffffff"` |
+| `directionalIntensity` | `number`      | Direct Light Intensity  | `1.2`       |
+| `directionalColor`     | `string`      | Direct Light Color      | `"#ffffff"` |
+
+`envPreset` accepts any `@react-three/drei` `PresetsType` (for example `"city"`, `"sunset"`, `"dawn"`, `"night"`, `"warehouse"`, `"forest"`, `"apartment"`, `"studio"`, `"park"`, `"lobby"`).
+
+```tsx
+<SimpleModelViewer
+  modelUrl="/model.glb"
+  backgroundEnabled
+  envPreset="sunset"
+  exposure={1.2}
+  ambientIntensity={0.4}
+  directionalColor="#fff4e0"
+  autoRotate
+/>
+```
+
+### `zoomOnSelected`
+
+Optional boolean. When `true`, selecting a mesh (via click or the objects panel) zooms/frames the camera on it.
+
+Default:
+
+```ts
+false;
+```
+
+### `highlightOnHover`
+
+Optional boolean. When `true`, hovering a mesh (in the viewport or the objects panel) highlights it.
+
+Default:
+
+```ts
+false;
+```
+
+### `showLoadingOverlay`
+
+Optional boolean controlling whether the built-in loading overlay is shown while the model is loading, uploaded files are being prepared, and the initial camera fit is settling.
+
+Default:
+
+```ts
+true;
+```
+
+### `refitOnResize`
+
+Optional boolean controlling whether the camera re-frames the model to fit whenever the canvas is resized — a browser window resize, a device rotation, or a side panel (scene settings / scene objects) opening or closing. Set to `false` to preserve the user's current orbit/zoom across resizes; the camera aspect stays correct either way, so the model never distorts, it just isn't re-centered.
+
+Default:
+
+```ts
+true;
+```
+
+### `enableModelUpload`
+
+Optional boolean that swaps the fixed `modelUrl` workflow for a built-in upload UI. When enabled, the viewer starts with a drag-and-drop / file-picker empty state and loads the uploaded `.glb`, standalone/data-URI `.gltf`, or `.zip` containing a `.gltf` plus its referenced `.bin` and texture files instead of the asset passed via `modelUrl`.
+
+Default:
+
+```ts
+false;
+```
+
+### `onModelLoaded`
+
+Optional callback fired after the GLB/GLTF scene has loaded.
+
+### `onLoadError`
+
+Optional callback fired if the model fails to load or render.
+
+## Object Binding Shape
+
+The current source defines these binding types internally:
+
+```ts
+type ObjectBindingAction = {
+  id: string;
+  label: string;
+  type: "command";
+};
+
+type ObjectBindingCameraState = {
+  position?: [number, number, number];
+  target?: [number, number, number];
+  fov?: number;
+  zoom?: number;
+};
+
+type ObjectBindingMaterial = {
+  // exported by the package; includes texture/baseColor plus the supported
+  // MeshPhysicalMaterial overrides used by the viewer and BindingBuilder
+};
+
+type ObjectBindingStyle = {
+  material?: ObjectBindingMaterial;
+};
+
+type ObjectBinding = {
+  id: string;
+  type: ObjectBindingType; // "body" | "light" | "wheel" | "glass" | "interior" | "floor" | "wall" | "door" | "furniture" | "decor" | "electronics" | "other" | ...
+  modelObjectId: string;
+  label?: string;
+  visible?: boolean;
+  selectable?: boolean;
+  hoverable?: boolean;
+  style?: ObjectBindingStyle;
+  actions?: ObjectBindingAction[];
+  metrics?: Record<string, number>;
+  metadata?: Record<string, unknown>;
+  cameraState?: ObjectBindingCameraState;
+};
+```
+
+Notes:
+
+- the `objectBindings` record is keyed by node name, not by `id`
+- `visible` is live render state, not just an initial default
+- `style.material.baseColor` is read by the renderer and is the committed source of truth for color picks
+- `style.material.texture.path` is read by the renderer and is the committed source of truth for texture uploads (stored as durable URLs via `onTextureUpload` when provided, or session-scoped blob URLs otherwise)
+- if no `texture.path` is provided and no `style.material.baseColor` is set, the viewer falls back to the node's original GLB/GLTF material
+- supported `style.material` fields are applied as per-object `MeshPhysicalMaterial` overrides, including metalness, roughness, emissive, opacity, alpha masking, normal/bump, AO, displacement, clearcoat, sheen, anisotropy, specular, transmission, thickness, attenuation tint/distance, reflectivity, and side selection
+- each `style.material` group also accepts a texture-map slot (`metalnessMap`, `roughnessMap`, `normalMap`, `aoMap`, `clearcoatMap`, etc.); color maps are decoded as sRGB and data maps as linear automatically
+- `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 JSON preview
+- `ObjectBindingType` is a large union covering vehicles, rooms, furniture, characters, weapons, environment, and more
+
+## Supported Built-In Actions
+
+Action handling is currently hardcoded in `ModelViewer`.
+
+### Implemented behaviors
+
+- `toggle-visibility`
+  Hides or shows the selected mesh by setting `binding.visible` and calling `onObjectBindingsChange`
+- `change-color`
+  Opens the color picker; 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 popup 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
+
+## How Rendering Works
+
+At a high level, the current viewer does the following:
+
+1. creates a Three.js canvas; only `fov: 50` is defaulted, so camera position falls back to React Three Fiber's `Canvas` default (`[0, 0, 5]`) unless `camera.position` is passed
+2. loads the GLB/GLTF asset with `useGLTF`
+3. looks up meshes by the keys in `objectBindings` (resolving `modelObjectId` to find the actual model node)
+4. clones each referenced material so edits stay isolated per object (keyed on a structural signature of the binding-to-mesh mapping, not the `objectBindings` reference, so materials are not recreated on every binding update)
+5. applies runtime color, texture, and style overrides from `objectBindings` in a `useEffect` (not during render)
+6. manages a reference-counted texture cache so the same texture URL is decoded once and disposed when no longer referenced; each texture is decoded in the correct color space — color maps (base color/albedo, emissive, sheen color, specular color) as sRGB and data maps (normal, roughness, metalness, AO, displacement, etc.) as linear — and the cache is keyed by URL **and** color space, so the same image can be reused safely as both a color and a data map
+7. adds hover, selected, and panel-hover emissive highlighting
+8. creates an `AnimationMixer` for the loaded scene, ticked every frame via `useFrame`, and exposes playback controls through `onAnimationsReady`
+9. renders a side panel for the selected object and its configured actions
+
+Only objects listed in `objectBindings` are rendered interactively by the current `Model` component.
+
+### Lighting, shadows, and post-processing
+
+When `shadows` is enabled (the default), the canvas renders soft shadow maps and the viewer applies:
+
+- a default light rig (`Lights`) with ambient + hemisphere fill and a directional key light that casts shadows, sized to the model
+- 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.
+
+## UI Behavior
+
+The current component includes its own UI shell:
+
+- a viewer layout that fills its parent container
+- a sliding left side panel about `280px` wide
+- a canvas area that fills the remaining width
+- a floating color picker popover
+- a floating texture upload popover
+- a right scene objects panel with search and per-object visibility toggles
+
+Because of that, it works best when mounted in a container with an explicit height.
+
+## Usage Expectations For Models
+
+To use this library successfully, your GLB/GLTF asset should follow these expectations:
+
+- the mesh node names must match the keys in `objectBindings` (or be referenced via `modelObjectId`)
+- target nodes should have geometry and a `MeshStandardMaterial`
+- the file should be accessible from the browser at `modelUrl`; hosted `.gltf` files must also serve external `.bin` and texture files at their declared relative paths
+
+If a node name or material name does not match, that object will not render through the interactive binding flow.
+
+## License
+
+Proprietary — see [LICENSE](./LICENSE). Installing the package does not itself grant a right to use it in production; a valid `licenseKey` from the [Developer Portal](https://react-immersive.liveroom.dev) is required, and usage is bound to the terms of your license tier.