@liveroom-tech/react-immersive 1.4.0 → 2.1.0

package/README.md

@@ -9,11 +9,15 @@ The library currently exports:
 ```ts
 import {
   BindingBuilder,
+  material,
   ModelViewer,
+  patchBindings,
+  patchSceneConfig,
   SimpleModelViewer,
   useObjectBinding,
   useObjectBindingIds,
-  useObjectVisibility,
+  useObjectBindings,
+  useSceneConfig,
   useViewerActions,
   useViewerAnimations,
   useViewerCamera,
@@ -25,13 +29,13 @@ import {
 } from "@liveroom-tech/react-immersive";
 ```
 
-It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectActionEvent`, `SceneConfig`, `AnimationControls`, `CinematicConfig` / `CinematicWaypoint`, and related shapes used throughout this document.
+It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectBindingsController`, `ObjectActionEvent`, `SceneConfig`, `SceneConfigPatch`, `SceneConfigController`, `AnimationControls`, `CinematicConfig` / `CinematicWaypoint`, 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
+- 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
@@ -44,7 +48,7 @@ It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectActio
 - an optional UV Checker toolbar button through `showUvCheckerButton`, for inspecting UV scale, stretching, seams, orientation, and missing UV0 coordinates directly in `ModelViewer`
 - click-to-measure distance tool and a bounding-box dimensions overlay through `showMeasureTools` and `measurementUnit`
 - an exploded-view slider that slides each bound part outward from the model center to reveal interior/assembly structure through `showExplodeControls`
-- a cinematic auto-camera that glides the camera along authored waypoints (or a zero-config showcase orbit), like a film, through `cinematic` — with a play/pause control that yields the moment you touch the camera
+- a cinematic auto-camera that glides the camera along authored waypoints (or a zero-config showcase orbit), like a film, through `cinematic`, with a play/pause control that yields the moment you touch the camera
 - a guided-tour control cluster (Previous/Stop/Next) for stepping through annotations, toggleable via `showAnnotationNavigation`
 - optional annotation detail popups on marker hover via `showAnnotationOnHover`
 - PBR, Matcap, and UV Checker renderer modes, with the checker exposing UV stretching, seams, rotation, and missing UV0 data directly on the model
@@ -77,10 +81,10 @@ It also exports types for `ObjectBinding`, `ObjectBindingMaterial`, `ObjectActio
 - 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, and cinematic camera paths)
-- a Cinematic sub-tab for authoring a camera path visually — frame the model, capture the current view as a waypoint, reorder/preview/delete waypoints, and toggle loop/auto-play; stored on `sceneConfig.cinematic` and replayed by `ModelViewer`'s `cinematic` prop
+- a Cinematic sub-tab for authoring a camera path visually, frame the model, capture the current view as a waypoint, reorder/preview/delete waypoints, and toggle loop/auto-play; stored on `sceneConfig.cinematic` and replayed by `ModelViewer`'s `cinematic` prop
 - 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
+- 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:
@@ -162,36 +166,36 @@ 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.
+`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
+- [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,
+  useObjectBindings,
   useViewerActions,
   useViewerAnimations,
   useViewerCamera,
   useViewerHover,
   useViewerModel,
   useViewerSelection,
+  type ObjectBinding,
 } from "@liveroom-tech/react-immersive";
 
-const initialBindings = {
+const initialBindings: Record<string, ObjectBinding> = {
   CarBody: {
     id: "car-body",
     modelObjectId: "CarBody",
@@ -220,7 +224,12 @@ const initialBindings = {
 };
 
 export default function Example() {
-  const [objectBindings, setObjectBindings] = useState(initialBindings);
+  const {
+    objectBindings,
+    setObjectBindings,
+    hiddenObjects,
+    toggleObjectVisibility,
+  } = useObjectBindings(initialBindings);
   const { selectedObjectBinding, handleObjectSelect } = useViewerSelection();
   const { hoveredObjectBinding, handleHoveredObject } = useViewerHover();
   const {
@@ -241,10 +250,6 @@ export default function Example() {
     handleModelLoaded,
     handleLoadError,
   } = useViewerModel();
-  const { hiddenObjects, toggleObjectVisibility } = useObjectVisibility(
-    objectBindings,
-    setObjectBindings,
-  );
   const { getActionsForObject, runAction } = useViewerActions(objectBindings, {
     onAction: (event) => {},
     onObjectBindingsChange: setObjectBindings,
@@ -325,12 +330,17 @@ const ids = useObjectBindingIds(objectBindings);
 // → ["CarBody", "WheelFL", "WheelFR", ...]
 ```
 
-If you want to control object visibility outside the viewer, the library also exports:
+If you want one state owner for binding patches, materials, and visibility, use `useObjectBindings`:
 
 ```tsx
-const [objectBindings, setObjectBindings] = useState(initialBindings);
-
 const {
+  objectBindings,
+  setObjectBindings,
+  updateObjectBindings,
+  setMaterial,
+  setBaseColor,
+  resetMaterial,
+  getMaterial,
   hiddenObjects,
   hiddenObjectIds,
   hideObject,
@@ -338,7 +348,7 @@ const {
   toggleObjectVisibility,
   isObjectHidden,
   clearHiddenObjects,
-} = useObjectVisibility(objectBindings, setObjectBindings);
+} = useObjectBindings(initialBindings);
 
 <ModelViewer
   modelUrl="/model.glb"
@@ -348,22 +358,56 @@ const {
 />;
 ```
 
-`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.
+`useObjectBindings` owns the state used by the viewer. Every setter uses a functional update, so consecutive material, visibility, and general binding updates in the same tick compose instead of overwriting each other.
 
-It accepts either:
+Object identifiers accepted by its methods can be:
 
 - the object binding map key
 - `binding.id`
 - `binding.modelObjectId`
 
-and returns:
+The hook returns:
 
+- `objectBindings` and `setObjectBindings`
+- `updateObjectBindings` for any binding field or atomic edit batch
+- `setMaterial`, `setBaseColor`, `resetMaterial`, and `getMaterial`
 - `hiddenObjects`: a derived map of hidden binding keys
 - `hiddenObjectIds`: the currently hidden binding IDs
 - `hideObject`, `showObject`, `toggleObjectVisibility`
 - `isObjectHidden`
 - `clearHiddenObjects`
 
+For scene-wide state, use `useSceneConfig`:
+
+```tsx
+const {
+  sceneConfig,
+  setSceneConfig,
+  updateSceneConfig,
+  resetSceneConfig,
+} = useSceneConfig(initialSceneConfig);
+
+const enableUvChecker = () =>
+  updateSceneConfig({
+    model: { renderer: "uv-checker" },
+    lighting: { ambient: { intensity: 0.5 } },
+  });
+
+<ModelViewer
+  modelUrl="/model.glb"
+  licenseKey="your-license-key"
+  objectBindings={objectBindings}
+  sceneConfig={sceneConfig}
+/>;
+
+<button onClick={enableUvChecker}>Show UV checker</button>;
+```
+
+Nested objects merge recursively, while arrays and tuples are replaced. Every
+update uses a functional state updater, so consecutive calls compose. Use the
+pure `patchSceneConfig(sceneConfig, patch)` utility when a store or parent owns
+the scene state.
+
 If you want to keep hover state in sync with the viewer, the library also exports:
 
 ```tsx
@@ -460,7 +504,7 @@ type BindingBuilderProps = {
 
 `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:
+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
@@ -468,9 +512,9 @@ Current behavior — Object tab:
 - 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
+- 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:
+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
@@ -511,7 +555,7 @@ export default function App() {
 }
 ```
 
-`SimpleModelViewer` does not take a `licenseKey` — licensing is enforced by `ModelViewer` and `BindingBuilder` only.
+`SimpleModelViewer` does not take a `licenseKey`, licensing is enforced by `ModelViewer` and `BindingBuilder` only.
 
 Sizing note:
 
@@ -810,8 +854,8 @@ 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)
+- 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.
@@ -894,7 +938,7 @@ onViewerReady={(viewer) => {
 }}
 ```
 
-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.
+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:
 
@@ -1011,7 +1055,7 @@ function CustomLights() {
 
 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.
+`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:
 
@@ -1187,7 +1231,7 @@ 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.
+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:
 
@@ -1299,7 +1343,7 @@ 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` — unless an explicit [`camera`](#camera) prop was given, in which case that position is treated as the chosen initial view and `fitScene` is skipped.
+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`, unless an explicit [`camera`](#camera) prop was given, in which case that position is treated as the chosen initial view and `fitScene` is skipped.
 
 Current callback shape:
 
@@ -1309,7 +1353,7 @@ Current callback shape:
 
 ### `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.
+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:
 
@@ -1372,9 +1416,9 @@ Optional control over how aggressively the viewer trades visual fidelity for a s
 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.
+- `"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:
 
@@ -1420,7 +1464,7 @@ false;
 
 ### `measurementUnit`
 
-Optional unit suffix appended to measurement readouts. glTF models are authored in meters by spec, so values are not converted — this only changes the displayed label.
+Optional unit suffix appended to measurement readouts. glTF models are authored in meters by spec, so values are not converted, this only changes the displayed label.
 
 Default:
 
@@ -1430,7 +1474,7 @@ Default:
 
 ### `showExplodeControls`
 
-Optional boolean that shows an exploded-view slider over the canvas. It slides each bound part outward from the model center to reveal interior/assembly structure, then back to reassemble. Best suited to static product/CAD models — the offset writes node positions each frame, so it conflicts with a playing skeletal animation.
+Optional boolean that shows an exploded-view slider over the canvas. It slides each bound part outward from the model center to reveal interior/assembly structure, then back to reassemble. Best suited to static product/CAD models, the offset writes node positions each frame, so it conflicts with a playing skeletal animation.
 
 Default:
 
@@ -1440,7 +1484,7 @@ false;
 
 ### `cinematic`
 
-Optional cinematic auto-camera. The camera glides along a path on its own, like a film — ideal for showing off a gallery, apartment, or product with no user interaction. Renders a play/pause button over the canvas; grabbing the camera (or selecting a part) pauses it.
+Optional cinematic auto-camera. The camera glides along a path on its own, like a film, ideal for showing off a gallery, apartment, or product with no user interaction. Renders a play/pause button over the canvas; grabbing the camera (or selecting a part) pauses it.
 
 ```ts
 cinematic?: boolean | CinematicConfig;
@@ -1462,7 +1506,7 @@ type CinematicWaypoint = {
 - Two or more `waypoints` author a **walkthrough**: the camera follows a smooth Catmull-Rom spline through them at a constant on-screen speed, looping seamlessly.
 - Waypoints are easiest to capture visually in `BindingBuilder`'s **Cinematic** tab, which stores them on `sceneConfig.cinematic`.
 
-A path can also come from `sceneConfig.cinematic`. The `cinematic` prop overrides it: a boolean toggles the feature (`true` keeps any authored waypoints, `false` forces it off), and an object overrides field-by-field — so you can keep the authored waypoints while overriding, say, `autoPlay` or `loop`.
+A path can also come from `sceneConfig.cinematic`. The `cinematic` prop overrides it: a boolean toggles the feature (`true` keeps any authored waypoints, `false` forces it off), and an object overrides field-by-field, so you can keep the authored waypoints while overriding, say, `autoPlay` or `loop`.
 
 ```tsx
 // Zero-config showcase orbit
@@ -1498,7 +1542,7 @@ arbitrary uploads and room scenes are framed safely. Set
 [`arScaleMode`](#arscalemode) to `"real-world"` for product AR, which preserves
 the GLB's authored metre scale.
 
-**AR placement gestures** — inside an AR session the viewer now uses an explicit placement flow:
+**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"**
@@ -1508,7 +1552,7 @@ the GLB's authored metre scale.
 
 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.
+> 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:
 
@@ -1619,7 +1663,7 @@ type SimpleModelViewerProps = {
 };
 ```
 
-`SimpleModelViewer` does not take a `licenseKey` — licensing is enforced by `ModelViewer` and `BindingBuilder` only.
+`SimpleModelViewer` does not take a `licenseKey`, licensing is enforced by `ModelViewer` and `BindingBuilder` only.
 
 ### `modelUrl`
 
@@ -1657,7 +1701,7 @@ 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.
+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     |
 | ---------------------- | ------------- | ----------------------- | ----------- |
@@ -1716,7 +1760,7 @@ 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.
+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:
 
@@ -1821,7 +1865,7 @@ At a high level, the current viewer does the following:
 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
+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
@@ -1833,7 +1877,7 @@ Only objects listed in `objectBindings` are rendered interactively by the curren
 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
+- 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.
@@ -1874,16 +1918,16 @@ instead of freezing:
   still works
 - a dismissible banner tells the user the model is very large, may render
   slowly on their device, and that selection is available through the panel
-- the loading overlay calls out the extra work — uploading that much geometry
+- the loading overlay calls out the extra work, uploading that much geometry
   to the GPU is a single synchronous operation that can block the page for
   tens of seconds in any WebGL viewer
 
 Orbit, zoom, animations, annotations, and the panels keep working. There is no
-viewer-side way to make models of this size feel fast — the per-frame cost is
+viewer-side way to make models of this size feel fast, the per-frame cost is
 inherent, and on mobile devices the decoded geometry alone can exceed the
 tab's memory budget. Decimate such assets at ingestion (to roughly 2–3M
 triangles) instead of shipping the raw export; note that very large
-Draco-compressed files need Blender or native tooling to decimate — the WASM
+Draco-compressed files need Blender or native tooling to decimate, the WASM
 builds of `gltf-transform` and `gltfpack` cannot decode them within their 4GB
 address space.
 
@@ -1891,9 +1935,9 @@ Two related picking notes that apply to models of every size:
 
 - clicks resolve the front-most surface under the pointer; a mesh with
   `selectable: false` does not pass the click through to meshes behind it
-- `SimpleModelViewer` renders on demand — an idle viewer draws no frames, so
+- `SimpleModelViewer` renders on demand, an idle viewer draws no frames, so
   it costs no GPU time or battery until something changes
 
 ## 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.
+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.

package/dist/index.d.mts

@@ -664,17 +664,76 @@ declare function useObjectBinding(objectBindings: Record<string, ObjectBinding>,
 
 declare function useObjectBindingIds(objectBindings: Record<string, ObjectBinding>): string[];
 
+type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+
+type ObjectBindingPatch = DeepPartial<ObjectBinding>;
+type BindingEdit = {
+    ids: string | string[];
+    patch: ObjectBindingPatch;
+};
+/**
+ * Applies field-level patches to object bindings and returns the updated
+ * record. Pure — nothing is mutated, and the original reference comes back
+ * untouched when no id matched, so React can skip the re-render.
+ *
+ * Ids resolve the same way everywhere else in the library: binding key first,
+ * then `binding.id`, then `binding.modelObjectId`.
+ */
+declare function patchBindings(bindings: Record<string, ObjectBinding>, objectId: string | string[], patch: ObjectBindingPatch): Record<string, ObjectBinding>;
+declare function patchBindings(bindings: Record<string, ObjectBinding>, edits: BindingEdit[]): Record<string, ObjectBinding>;
+/** Shorthand for the common `{ style: { material: … } }` nesting. */
+declare function material(value: ObjectBindingMaterial): ObjectBindingPatch;
+
 type HiddenObjectsState = Record<string, boolean>;
-type ObjectVisibilityProps = {
+type ObjectBindingsController = {
+    objectBindings: Record<string, ObjectBinding>;
+    setObjectBindings: React.Dispatch<React.SetStateAction<Record<string, ObjectBinding>>>;
+    updateObjectBindings: {
+        (objectId: string | string[], patch: ObjectBindingPatch): void;
+        (edits: BindingEdit[]): void;
+    };
+    setMaterial: (objectId: string | string[], material: ObjectBindingMaterial) => void;
+    setBaseColor: (objectId: string | string[], color: string) => void;
+    resetMaterial: (objectId: string | string[]) => void;
+    getMaterial: (objectId: string) => ObjectBindingMaterial | null;
     hiddenObjects: HiddenObjectsState;
     hiddenObjectIds: string[];
-    hideObject: (objectId: string) => void;
-    showObject: (objectId: string) => void;
-    toggleObjectVisibility: (objectId: string) => void;
+    hideObject: (objectId: string | string[]) => void;
+    showObject: (objectId: string | string[]) => void;
+    toggleObjectVisibility: (objectId: string | string[]) => void;
     isObjectHidden: (objectId: string) => boolean;
     clearHiddenObjects: () => void;
 };
-declare function useObjectVisibility(objectBindings: Record<string, ObjectBinding>, onObjectBindingsChange: (next: Record<string, ObjectBinding>) => void): ObjectVisibilityProps;
+/**
+ * Owns object-binding state and exposes field-level, material, and visibility
+ * operations over the same functional state updater.
+ *
+ * Consecutive calls in the same tick compose instead of overwriting each other,
+ * including calls across material and visibility concerns.
+ */
+declare function useObjectBindings(initialBindings: Record<string, ObjectBinding> | (() => Record<string, ObjectBinding>)): ObjectBindingsController;
+
+type SceneConfigPatch = DeepPartial<SceneConfig>;
+/**
+ * Applies a nested scene-config patch without mutating either input. Objects
+ * are merged recursively, while arrays and tuples are replaced wholesale.
+ */
+declare function patchSceneConfig(sceneConfig: SceneConfig, patch: SceneConfigPatch): SceneConfig;
+
+type SceneConfigUpdate = SceneConfigPatch | ((current: SceneConfig) => SceneConfigPatch);
+type SceneConfigController = {
+    sceneConfig: SceneConfig;
+    setSceneConfig: React.Dispatch<React.SetStateAction<SceneConfig>>;
+    updateSceneConfig: (update: SceneConfigUpdate) => void;
+    resetSceneConfig: () => void;
+};
+/**
+ * Owns scene-config state and applies nested patches through functional React
+ * updates, so consecutive calls in the same tick compose safely.
+ */
+declare function useSceneConfig(initialSceneConfig: SceneConfig | (() => SceneConfig)): SceneConfigController;
 
 type ViewerHoverProps = {
     hoveredObjectBinding: ObjectBinding | null;
@@ -728,4 +787,4 @@ type ShareableViewerStateProps = {
 };
 declare function useShareableViewerState({ cameraState, setCameraState, objectBindings, onObjectBindingsChange, selectedObjectBinding, setSelectedObjectBinding, paramKey, debounceMs, autoSync, }: UseShareableViewerStateOptions): ShareableViewerStateProps;
 
-export { type AnimationClipInfo, type AnimationControls, type AnimationLoopMode, type AnimationPlaybackState, BindingBuilder, type CaptureImageOptions, type CinematicConfig, type CinematicWaypoint, type CustomObjectBindingDataPanelProps, type CustomSceneObjectsPanelProps, type HiddenObjectsState, type HomeCameraState, MATERIAL_BLENDING_MODES, MATERIAL_SIDES, ModelViewer, type ModelViewerProps, type ObjectActionEvent, type ObjectBinding, type ObjectBindingAction, type ObjectBindingMaterial, type ObjectBindingMaterialBlendingMode, type ObjectBindingMaterialSide, type ObjectBindingTextureSlot, type ObjectVisibilityProps, type SceneAnimationClipConfig, type SceneAnimationConfig, type SceneCinematicConfig, type SceneCinematicWaypoint, type SceneConfig, type SceneModelRenderer, SimpleModelViewer, type SimpleModelViewerProps, type ViewerActionsOptions, type ViewerActionsProps, type ViewerAnimationsProps, type ViewerCameraProps, type ViewerCameraState, type ViewerModelBounds, type ViewerModelProps, type ViewerReadyState, type ViewerSelectionProps, type XRScaleMode, useObjectBinding, useObjectBindingIds, useObjectVisibility, useShareableViewerState, useViewerActions, useViewerAnimations, useViewerCamera, useViewerHover, useViewerModel, useViewerSelection };
+export { type AnimationClipInfo, type AnimationControls, type AnimationLoopMode, type AnimationPlaybackState, BindingBuilder, type BindingEdit, type CaptureImageOptions, type CinematicConfig, type CinematicWaypoint, type CustomObjectBindingDataPanelProps, type CustomSceneObjectsPanelProps, type HiddenObjectsState, type HomeCameraState, MATERIAL_BLENDING_MODES, MATERIAL_SIDES, ModelViewer, type ModelViewerProps, type ObjectActionEvent, type ObjectBinding, type ObjectBindingAction, type ObjectBindingMaterial, type ObjectBindingMaterialBlendingMode, type ObjectBindingMaterialSide, type ObjectBindingPatch, type ObjectBindingTextureSlot, type ObjectBindingsController, type SceneAnimationClipConfig, type SceneAnimationConfig, type SceneCinematicConfig, type SceneCinematicWaypoint, type SceneConfig, type SceneConfigController, type SceneConfigPatch, type SceneConfigUpdate, type SceneModelRenderer, SimpleModelViewer, type SimpleModelViewerProps, type ViewerActionsOptions, type ViewerActionsProps, type ViewerAnimationsProps, type ViewerCameraProps, type ViewerCameraState, type ViewerModelBounds, type ViewerModelProps, type ViewerReadyState, type ViewerSelectionProps, type XRScaleMode, material, patchBindings, patchSceneConfig, useObjectBinding, useObjectBindingIds, useObjectBindings, useSceneConfig, useShareableViewerState, useViewerActions, useViewerAnimations, useViewerCamera, useViewerHover, useViewerModel, useViewerSelection };

package/dist/index.d.ts

@@ -664,17 +664,76 @@ declare function useObjectBinding(objectBindings: Record<string, ObjectBinding>,
 
 declare function useObjectBindingIds(objectBindings: Record<string, ObjectBinding>): string[];
 
+type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+
+type ObjectBindingPatch = DeepPartial<ObjectBinding>;
+type BindingEdit = {
+    ids: string | string[];
+    patch: ObjectBindingPatch;
+};
+/**
+ * Applies field-level patches to object bindings and returns the updated
+ * record. Pure — nothing is mutated, and the original reference comes back
+ * untouched when no id matched, so React can skip the re-render.
+ *
+ * Ids resolve the same way everywhere else in the library: binding key first,
+ * then `binding.id`, then `binding.modelObjectId`.
+ */
+declare function patchBindings(bindings: Record<string, ObjectBinding>, objectId: string | string[], patch: ObjectBindingPatch): Record<string, ObjectBinding>;
+declare function patchBindings(bindings: Record<string, ObjectBinding>, edits: BindingEdit[]): Record<string, ObjectBinding>;
+/** Shorthand for the common `{ style: { material: … } }` nesting. */
+declare function material(value: ObjectBindingMaterial): ObjectBindingPatch;
+
 type HiddenObjectsState = Record<string, boolean>;
-type ObjectVisibilityProps = {
+type ObjectBindingsController = {
+    objectBindings: Record<string, ObjectBinding>;
+    setObjectBindings: React.Dispatch<React.SetStateAction<Record<string, ObjectBinding>>>;
+    updateObjectBindings: {
+        (objectId: string | string[], patch: ObjectBindingPatch): void;
+        (edits: BindingEdit[]): void;
+    };
+    setMaterial: (objectId: string | string[], material: ObjectBindingMaterial) => void;
+    setBaseColor: (objectId: string | string[], color: string) => void;
+    resetMaterial: (objectId: string | string[]) => void;
+    getMaterial: (objectId: string) => ObjectBindingMaterial | null;
     hiddenObjects: HiddenObjectsState;
     hiddenObjectIds: string[];
-    hideObject: (objectId: string) => void;
-    showObject: (objectId: string) => void;
-    toggleObjectVisibility: (objectId: string) => void;
+    hideObject: (objectId: string | string[]) => void;
+    showObject: (objectId: string | string[]) => void;
+    toggleObjectVisibility: (objectId: string | string[]) => void;
     isObjectHidden: (objectId: string) => boolean;
     clearHiddenObjects: () => void;
 };
-declare function useObjectVisibility(objectBindings: Record<string, ObjectBinding>, onObjectBindingsChange: (next: Record<string, ObjectBinding>) => void): ObjectVisibilityProps;
+/**
+ * Owns object-binding state and exposes field-level, material, and visibility
+ * operations over the same functional state updater.
+ *
+ * Consecutive calls in the same tick compose instead of overwriting each other,
+ * including calls across material and visibility concerns.
+ */
+declare function useObjectBindings(initialBindings: Record<string, ObjectBinding> | (() => Record<string, ObjectBinding>)): ObjectBindingsController;
+
+type SceneConfigPatch = DeepPartial<SceneConfig>;
+/**
+ * Applies a nested scene-config patch without mutating either input. Objects
+ * are merged recursively, while arrays and tuples are replaced wholesale.
+ */
+declare function patchSceneConfig(sceneConfig: SceneConfig, patch: SceneConfigPatch): SceneConfig;
+
+type SceneConfigUpdate = SceneConfigPatch | ((current: SceneConfig) => SceneConfigPatch);
+type SceneConfigController = {
+    sceneConfig: SceneConfig;
+    setSceneConfig: React.Dispatch<React.SetStateAction<SceneConfig>>;
+    updateSceneConfig: (update: SceneConfigUpdate) => void;
+    resetSceneConfig: () => void;
+};
+/**
+ * Owns scene-config state and applies nested patches through functional React
+ * updates, so consecutive calls in the same tick compose safely.
+ */
+declare function useSceneConfig(initialSceneConfig: SceneConfig | (() => SceneConfig)): SceneConfigController;
 
 type ViewerHoverProps = {
     hoveredObjectBinding: ObjectBinding | null;
@@ -728,4 +787,4 @@ type ShareableViewerStateProps = {
 };
 declare function useShareableViewerState({ cameraState, setCameraState, objectBindings, onObjectBindingsChange, selectedObjectBinding, setSelectedObjectBinding, paramKey, debounceMs, autoSync, }: UseShareableViewerStateOptions): ShareableViewerStateProps;
 
-export { type AnimationClipInfo, type AnimationControls, type AnimationLoopMode, type AnimationPlaybackState, BindingBuilder, type CaptureImageOptions, type CinematicConfig, type CinematicWaypoint, type CustomObjectBindingDataPanelProps, type CustomSceneObjectsPanelProps, type HiddenObjectsState, type HomeCameraState, MATERIAL_BLENDING_MODES, MATERIAL_SIDES, ModelViewer, type ModelViewerProps, type ObjectActionEvent, type ObjectBinding, type ObjectBindingAction, type ObjectBindingMaterial, type ObjectBindingMaterialBlendingMode, type ObjectBindingMaterialSide, type ObjectBindingTextureSlot, type ObjectVisibilityProps, type SceneAnimationClipConfig, type SceneAnimationConfig, type SceneCinematicConfig, type SceneCinematicWaypoint, type SceneConfig, type SceneModelRenderer, SimpleModelViewer, type SimpleModelViewerProps, type ViewerActionsOptions, type ViewerActionsProps, type ViewerAnimationsProps, type ViewerCameraProps, type ViewerCameraState, type ViewerModelBounds, type ViewerModelProps, type ViewerReadyState, type ViewerSelectionProps, type XRScaleMode, useObjectBinding, useObjectBindingIds, useObjectVisibility, useShareableViewerState, useViewerActions, useViewerAnimations, useViewerCamera, useViewerHover, useViewerModel, useViewerSelection };
+export { type AnimationClipInfo, type AnimationControls, type AnimationLoopMode, type AnimationPlaybackState, BindingBuilder, type BindingEdit, type CaptureImageOptions, type CinematicConfig, type CinematicWaypoint, type CustomObjectBindingDataPanelProps, type CustomSceneObjectsPanelProps, type HiddenObjectsState, type HomeCameraState, MATERIAL_BLENDING_MODES, MATERIAL_SIDES, ModelViewer, type ModelViewerProps, type ObjectActionEvent, type ObjectBinding, type ObjectBindingAction, type ObjectBindingMaterial, type ObjectBindingMaterialBlendingMode, type ObjectBindingMaterialSide, type ObjectBindingPatch, type ObjectBindingTextureSlot, type ObjectBindingsController, type SceneAnimationClipConfig, type SceneAnimationConfig, type SceneCinematicConfig, type SceneCinematicWaypoint, type SceneConfig, type SceneConfigController, type SceneConfigPatch, type SceneConfigUpdate, type SceneModelRenderer, SimpleModelViewer, type SimpleModelViewerProps, type ViewerActionsOptions, type ViewerActionsProps, type ViewerAnimationsProps, type ViewerCameraProps, type ViewerCameraState, type ViewerModelBounds, type ViewerModelProps, type ViewerReadyState, type ViewerSelectionProps, type XRScaleMode, material, patchBindings, patchSceneConfig, useObjectBinding, useObjectBindingIds, useObjectBindings, useSceneConfig, useShareableViewerState, useViewerActions, useViewerAnimations, useViewerCamera, useViewerHover, useViewerModel, useViewerSelection };