@liveroom-tech/react-immersive 2.2.0 → 3.0.0

package/README.md

@@ -21,6 +21,8 @@ import {
   useViewerActions,
   useViewerAnimations,
   useViewerCamera,
+  useViewerConnection,
+  useViewerEffects,
   useViewerHover,
   useViewerModel,
   useViewerSelection,
@@ -183,6 +185,7 @@ Peer dependencies:
 
 ```tsx
 import {
+  defineObjectBindings,
   ModelViewer,
   useObjectBinding,
   useObjectBindings,
@@ -192,10 +195,9 @@ import {
   useViewerHover,
   useViewerModel,
   useViewerSelection,
-  type ObjectBinding,
 } from "@liveroom-tech/react-immersive";
 
-const initialBindings: Record<string, ObjectBinding> = {
+const initialBindings = defineObjectBindings({
   CarBody: {
     id: "car-body",
     modelObjectId: "CarBody",
@@ -219,19 +221,27 @@ const initialBindings: Record<string, ObjectBinding> = {
       { id: "change-color", label: "Change Color", type: "command" },
       { id: "change-material", label: "Change Material", type: "command" },
       { id: "toggle-visibility", label: "Toggle Visibility", type: "command" },
+      {
+        id: "toggle-body",
+        label: "Toggle Body",
+        type: "command",
+        effects: [{ target: "CarBody", visibility: "toggle" }],
+      },
     ],
   },
-};
+});
 
 export default function Example() {
+  const bindings = useObjectBindings(initialBindings);
   const {
     objectBindings,
     setObjectBindings,
     hiddenObjects,
     toggleObjectVisibility,
-  } = useObjectBindings(initialBindings);
+  } = bindings;
   const { selectedObjectBinding, handleObjectSelect } = useViewerSelection();
   const { hoveredObjectBinding, handleHoveredObject } = useViewerHover();
+  const camera = useViewerCamera();
   const {
     cameraState,
     resetView,
@@ -240,7 +250,7 @@ export default function Example() {
     setCameraTarget,
     handleCameraChange,
     handleViewerReady,
-  } = useViewerCamera();
+  } = camera;
   const {
     isLoading,
     isReady,
@@ -250,9 +260,12 @@ export default function Example() {
     handleModelLoaded,
     handleLoadError,
   } = useViewerModel();
-  const { getActionsForObject, runAction } = useViewerActions(objectBindings, {
+  const animations = useViewerAnimations();
+  const { getActionsForObject, handleAction, runAction } = useViewerActions({
+    bindings,
+    camera,
+    animations,
     onAction: (event) => {},
-    onObjectBindingsChange: setObjectBindings,
   });
   const focusedBinding = useObjectBinding(objectBindings, "car-body");
 
@@ -270,14 +283,15 @@ export default function Example() {
         onLoadError={handleLoadError}
         onObjectBindingsChange={setObjectBindings}
         onViewerReady={handleViewerReady}
-        onAction={(event) => {}}
+        onAnimationsReady={animations.handleAnimationsReady}
+        onAction={handleAction}
       />
 
       <button onClick={() => toggleObjectVisibility("car-body")}>
         Toggle Visibility
       </button>
-      <button onClick={() => runAction("car-body", "toggle-visibility")}>
-        Run visibility action
+      <button onClick={() => runAction("car-body", "toggle-body")}>
+        Run declarative action
       </button>
       <button onClick={() => resetView()}>Reset view</button>
       <button onClick={() => focusObject("car-body")}>Focus Object</button>
@@ -337,10 +351,18 @@ const {
   objectBindings,
   setObjectBindings,
   updateObjectBindings,
+  selectObjectBindings,
+  selectObjectBindingIds,
   setMaterial,
   setBaseColor,
+  setTexture,
+  clearTexture,
+  copyMaterial,
   resetMaterial,
   getMaterial,
+  setTransform,
+  resetTransform,
+  updateMetadata,
   hiddenObjects,
   hiddenObjectIds,
   hideObject,
@@ -366,11 +388,40 @@ Object identifiers accepted by its methods can be:
 - `binding.id`
 - `binding.modelObjectId`
 
+You can also target bindings by a shared `group`, `tag`, or object `type`. Groups
+represent one named set, while tags let a binding participate in several sets:
+
+```tsx
+updateObjectBindings({ group: "paint" }, { selectable: false });
+setBaseColor({ tag: "exterior" }, "#2563eb");
+hideObject({ type: "wheel" });
+
+const exteriorBindings = selectObjectBindings({ tag: "exterior" });
+const paintIds = selectObjectBindingIds({ group: "paint" });
+
+setTexture({ group: "screens" }, "/images/dashboard.png");
+clearTexture({ tag: "printable" }, "baseColor");
+copyMaterial("wheel-front", { group: "wheels" });
+
+setTransform("door-left", {
+  rotation: [0, Math.PI / 2, 0],
+});
+resetTransform("door-left");
+updateMetadata({ group: "lights" }, { state: "on" });
+```
+
+When a parent or store owns the state, use the pure `selectBindings` and
+`selectBindingKeys` helpers for the same queries, and `patchBindings` to update
+all matches.
+
 The hook returns:
 
 - `objectBindings` and `setObjectBindings`
 - `updateObjectBindings` for any binding field or atomic edit batch
-- `setMaterial`, `setBaseColor`, `resetMaterial`, and `getMaterial`
+- `selectObjectBindings` and `selectObjectBindingIds` for group, tag, or type queries
+- `setMaterial`, `setBaseColor`, `setTexture`, `clearTexture`, `copyMaterial`, `resetMaterial`, and `getMaterial`
+- `setTransform` and `resetTransform` for persistent local-space model transforms
+- `updateMetadata` for recursively merged application data
 - `hiddenObjects`: a derived map of hidden binding keys
 - `hiddenObjectIds`: the currently hidden binding IDs
 - `hideObject`, `showObject`, `toggleObjectVisibility`
@@ -385,6 +436,7 @@ const {
   setSceneConfig,
   updateSceneConfig,
   resetSceneConfig,
+  lights,
 } = useSceneConfig(initialSceneConfig);
 
 const enableUvChecker = () =>
@@ -393,6 +445,14 @@ const enableUvChecker = () =>
     lighting: { ambient: { intensity: 0.5 } },
   });
 
+lights.setIntensity("bulb-light", 4);
+lights.setColor("bulb-light", "#ffd27d");
+lights.toggle("bulb-light");
+lights.attach("bulb-light", {
+  objectId: "bulb-filament",
+  offset: [0, -0.2, 0],
+});
+
 <ModelViewer
   modelUrl="/model.glb"
   licenseKey="your-license-key"
@@ -406,7 +466,72 @@ const enableUvChecker = () =>
 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.
+the scene state. The namespaced `lights` controller also provides `add`,
+`update`, `remove`, `show`, `hide`, `toggle`, `setIntensity`, `setColor`,
+`attach`, and `detach`. Attached lights follow a bound model object without an
+R3F light component. The custom `lights` prop replaces scene-config lights, so
+leave it unset when using this controller.
+
+For high-frequency visual effects, use `useViewerEffects`. It mutates the live
+viewer efficiently, requests demand-rendered frames automatically, and restores
+its runtime changes on cleanup. Application code does not need Three.js node or
+material access:
+
+```tsx
+const {
+  addPointLight,
+  flicker,
+  handleViewerReady,
+  overrideEffect,
+  stopEffect,
+} = useViewerEffects();
+
+useEffect(() => {
+  flicker(
+    {
+      materials: [
+        {
+          targets: { group: "filaments" },
+          values: { emissiveIntensity: [0.02, 8] },
+        },
+      ],
+      lights: [
+        {
+          lights: ["light-left", "light-right"],
+          intensity: [0, 180],
+        },
+      ],
+    },
+    { id: "bulbs", synchronized: true, blackoutChance: 0.1 },
+  );
+
+  return () => stopEffect("bulbs");
+}, [flicker, stopEffect]);
+
+<ModelViewer
+  modelUrl="/bulbs.glb"
+  licenseKey="your-license-key"
+  objectBindings={objectBindings}
+  onViewerReady={(viewer) => {
+    handleViewerReady(viewer);
+    addPointLight({
+      id: "light-left",
+      target: "filament-left",
+      color: "#ff9a3c",
+      intensity: 0,
+      distance: 30,
+    });
+  }}
+/>;
+
+<button onClick={() => overrideEffect("bulbs", 0, 800)}>Blackout</button>;
+```
+
+`transition`, `timeline`, `pulse`, and `flicker` share material, transform, and
+light channels. `setMaterial`, `setTransform`, and `getWorldPosition` cover
+immediate runtime work. `addPointLight`, `updatePointLight`, and
+`removePointLight` manage lights attached to model objects. `resetRuntime` stops
+active effects, restores snapshotted values, and disposes runtime lights.
 
 If you want to keep hover state in sync with the viewer, the library also exports:
 
@@ -461,24 +586,29 @@ const {
 If you want to inspect or trigger binding actions programmatically, the library also exports:
 
 ```tsx
-const { getActionsForObject, runAction } = useViewerActions(objectBindings, {
+const { getActionsForObject, handleAction, runAction } = useViewerActions({
+  bindings,
+  scene,
+  camera,
+  animations,
   onAction: (event) => {},
-  onObjectBindingsChange: setObjectBindings,
 });
 
 const actions = getActionsForObject("car-body");
-runAction("car-body", "toggle-visibility");
+await runAction("car-body", "power-on");
+
+<ModelViewer onAction={handleAction} />;
 ```
 
 `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
+- `handleAction`: executes an action event and can be passed directly to `ModelViewer.onAction`
+- `runAction`: finds and executes an action, then resolves to its event, or `null` if the binding or action cannot be found
 
-Current note:
+Actions can declare ordered `effects` for object-binding patches, scene patches, visibility, camera controls, and animation controls. Pass the corresponding hook controllers into `useViewerActions`; omitted optional controllers cause only their effect category to be skipped.
 
-- visibility-style actions (`toggle-visibility`) update binding data through `onObjectBindingsChange`
-- color/material actions still rely on `ModelViewer`'s built-in UI, so `runAction` dispatches those events but does not open the built-in color picker or texture upload panel by itself
+`runAction` executes declarative effects only. It does not invoke viewer-owned behavior such as opening a picker or running the built-in visibility toggle. For programmatic visibility, call the bindings controller directly or declare a custom action with a visibility effect.
 
 ## `BindingBuilder`
 
@@ -512,7 +642,7 @@ 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, with TypeScript exports wrapped in `defineObjectBindings` to preserve literal IDs, 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:
 
@@ -578,15 +708,25 @@ Use `ModelViewer` when you need binding-driven styling, actions, metadata, custo
 If you want camera state and imperative camera helpers, the library also exports:
 
 ```tsx
+const camera = useViewerCamera({
+  initialPosition: [0, 2, 8],
+  initialTarget: [0, 1.2, 0],
+});
+
 const {
   cameraState,
   resetView,
   focusObject,
   fitScene,
   setCameraTarget,
+  lookAt,
+  orbitTo,
+  dollyTo,
+  savePreset,
+  goToPreset,
   handleCameraChange,
   handleViewerReady,
-} = useViewerCamera();
+} = camera;
 
 <ModelViewer
   modelUrl="/model.glb"
@@ -605,9 +745,16 @@ const {
 - `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`
+- `lookAt`: moves the position and target together
+- `orbitTo`: moves to azimuth and polar angles in radians
+- `dollyTo`: moves to a distance from the current target
+- `savePreset`: captures the current camera under a name
+- `goToPreset`: moves to a named camera preset
 - `handleCameraChange`: a callback you can pass directly to `onCameraChange`
 - `handleViewerReady`: a callback you can pass directly to `onViewerReady`
 
+Pass `initialPosition`, `initialTarget`, and optional named `presets` to `useViewerCamera` to configure the first view without writing an `onViewerReady` wrapper.
+
 If your GLB/GLTF model contains animations, the library also exports:
 
 ```tsx
@@ -785,7 +932,9 @@ A map keyed by the model node name. Each key should match a mesh name from the G
 Example:
 
 ```ts
-const objectBindings = {
+import { defineObjectBindings } from "@liveroom-tech/react-immersive";
+
+const objectBindings = defineObjectBindings({
   Object_2: {
     id: "obj-2",
     modelObjectId: "Object_2",
@@ -811,9 +960,11 @@ const objectBindings = {
     metrics: {},
     metadata: {},
   },
-};
+});
 ```
 
+`defineObjectBindings` validates the complete record while preserving its exact keys and literal values. Use `ObjectBindingKey<typeof objectBindings>` for the binding-key union and `ObjectBindingActionId<typeof objectBindings, "Object_2">` for that binding's action-id union. It returns the input unchanged at runtime.
+
 ### `selectedObject`
 
 Optional currently selected object binding, or `null` when nothing is selected.
@@ -940,13 +1091,16 @@ 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.
 
-If you're also using `useViewerCamera`'s `handleViewerReady`, call both from your own `onViewerReady` to get camera helpers and `captureImage` together:
+If camera, effects, screenshots, or custom setup all need the ready viewer, combine them with `useViewerConnection`:
 
 ```tsx
-onViewerReady={(viewer) => {
-  handleViewerReady(viewer);
-  captureImageRef.current = viewer.captureImage;
-}}
+const camera = useViewerCamera();
+const effects = useViewerEffects();
+const connection = useViewerConnection(camera, effects);
+
+<ModelViewer onViewerReady={connection.handleViewerReady} />;
+
+const dataUrl = await connection.captureImage({ width: 1920, height: 1080 });
 ```
 
 ### `onTextureUpload`
@@ -1813,14 +1967,23 @@ type ObjectBindingStyle = {
   material?: ObjectBindingMaterial;
 };
 
+type ObjectBindingTransform = {
+  position?: [number, number, number];
+  rotation?: [number, number, number]; // radians
+  scale?: [number, number, number];
+};
+
 type ObjectBinding = {
   id: string;
   type: ObjectBindingType; // "body" | "light" | "wheel" | "glass" | "interior" | "floor" | "wall" | "door" | "furniture" | "decor" | "electronics" | "other" | ...
   modelObjectId: string;
   label?: string;
+  group?: string;
+  tags?: string[];
   visible?: boolean;
   selectable?: boolean;
   hoverable?: boolean;
+  transform?: ObjectBindingTransform;
   style?: ObjectBindingStyle;
   actions?: ObjectBindingAction[];
   metrics?: Record<string, number>;
@@ -1832,7 +1995,9 @@ type ObjectBinding = {
 Notes:
 
 - the `objectBindings` record is keyed by node name, not by `id`
+- `group` and `tags` can be assigned in `BindingBuilder` and used as targets by binding helpers and runtime material or transform effects
 - `visible` is live render state, not just an initial default
+- `transform` is persistent local-space render state; missing fields retain their model-authored values and removing it restores the authored transform
 - `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