@liveroom-tech/react-immersive 2.2.1 → 3.0.0

package/dist/index.mjs

@@ -174,7 +174,7 @@ import {
   Raycaster,
   Sphere as Sphere3,
   Vector2 as Vector26,
-  Vector3 as Vector38
+  Vector3 as Vector39
 } from "three";
 
 // #style-inject:#style-inject
@@ -2053,6 +2053,28 @@ function Controls({ controlsRef, onCameraChange }) {
 // src/components/Lights.tsx
 import { useRef as useRef4, useMemo as useMemo5, useEffect as useEffect6 } from "react";
 import { useFrame as useFrame3, useThree as useThree5 } from "@react-three/fiber";
+import {
+  Vector3 as Vector32
+} from "three";
+
+// src/utils/resolveBindingKey.ts
+function resolveBindingKey(objectBindings, objectId) {
+  if (objectBindings[objectId]) {
+    return objectId;
+  }
+  const idMatch = Object.entries(objectBindings).find(
+    ([, binding]) => binding.id === objectId
+  )?.[0];
+  if (idMatch) {
+    return idMatch;
+  }
+  const modelObjectMatch = Object.entries(objectBindings).find(
+    ([, binding]) => binding.modelObjectId === objectId
+  )?.[0];
+  return modelObjectMatch ?? null;
+}
+
+// src/components/Lights.tsx
 import { Fragment as Fragment3, jsx as jsx7, jsxs as jsxs4 } from "react/jsx-runtime";
 function rotatePositionY(pos, deg) {
   if (!deg) return pos;
@@ -2132,21 +2154,42 @@ function LightInstance({
   shadows,
   shadowsEnabled,
   environmentRotation,
-  modelBounds
+  modelBounds,
+  objectBindings,
+  nodeRefs
 }) {
   const dirRef = useRef4(null);
   const pointRef = useRef4(null);
   const spotRef = useRef4(null);
   const camera = useThree5((s) => s.camera);
+  const rootScene = useThree5((s) => s.scene);
+  const attachedPosition = useMemo5(() => new Vector32(), []);
   const position = useMemo5(
-    () => light.attachedToCamera ? light.position : rotatePositionY(light.position, environmentRotation),
-    [light.position, light.attachedToCamera, environmentRotation]
+    () => light.attachedToCamera || light.attachment ? light.position : rotatePositionY(light.position, environmentRotation),
+    [
+      light.position,
+      light.attachedToCamera,
+      light.attachment,
+      environmentRotation
+    ]
   );
   useFrame3(() => {
-    if (!light.attachedToCamera) return;
-    if (dirRef.current) dirRef.current.position.copy(camera.position);
-    if (pointRef.current) pointRef.current.position.copy(camera.position);
-    if (spotRef.current) spotRef.current.position.copy(camera.position);
+    const instance = dirRef.current ?? pointRef.current ?? spotRef.current;
+    if (!instance) return;
+    if (light.attachedToCamera) {
+      instance.position.copy(camera.position);
+      return;
+    }
+    const attachment = light.attachment;
+    if (!attachment) return;
+    const bindingKey = objectBindings ? resolveBindingKey(objectBindings, attachment.objectId) : null;
+    const binding = bindingKey ? objectBindings?.[bindingKey] : void 0;
+    const modelObjectId = binding?.modelObjectId ?? attachment.objectId;
+    const target = (bindingKey ? nodeRefs?.current[bindingKey] : void 0) ?? rootScene.getObjectByName(modelObjectId);
+    if (!target) return;
+    attachedPosition.fromArray(attachment.offset);
+    target.localToWorld(attachedPosition);
+    instance.position.copy(attachedPosition);
   });
   const castShadow = shadowsEnabled && shadows.enabled && light.castShadow;
   const fit = useMemo5(
@@ -2192,6 +2235,8 @@ function LightInstance({
         color: light.color,
         intensity: light.intensity,
         position,
+        distance: light.distance,
+        decay: light.decay,
         castShadow,
         "shadow-mapSize-width": shadows.mapSize,
         "shadow-mapSize-height": shadows.mapSize,
@@ -2217,7 +2262,9 @@ function Lights({
   shadowsEnabled = true,
   environmentRotation = 0,
   environmentConfig,
-  modelBounds
+  modelBounds,
+  objectBindings,
+  nodeRefs
 }) {
   const lighting = lightingConfig ?? DEFAULT_LIGHTING;
   const shadows = shadowConfig ?? DEFAULT_SHADOWS;
@@ -2238,7 +2285,9 @@ function Lights({
         shadows,
         shadowsEnabled,
         environmentRotation,
-        modelBounds
+        modelBounds,
+        objectBindings,
+        nodeRefs
       },
       light.id
     )),
@@ -2259,7 +2308,9 @@ function Lights({
         shadows,
         shadowsEnabled,
         environmentRotation: 0,
-        modelBounds
+        modelBounds,
+        objectBindings,
+        nodeRefs
       }
     )
   ] });
@@ -2368,7 +2419,7 @@ import {
   LoopOnce,
   LoopRepeat,
   Box3 as Box32,
-  Vector3 as Vector32,
+  Vector3 as Vector33,
   Matrix4,
   MathUtils as MathUtils2
 } from "three";
@@ -2984,6 +3035,24 @@ function refreshSkinnedBounds(root) {
 
 // src/components/Model.tsx
 import { jsx as jsx8 } from "react/jsx-runtime";
+function applyBindingTransform(node, transform, original) {
+  if (!original) return;
+  if (transform?.position) node.position.fromArray(transform.position);
+  else node.position.copy(original.position);
+  if (transform?.rotation) {
+    node.rotation.set(
+      transform.rotation[0],
+      transform.rotation[1],
+      transform.rotation[2],
+      original.rotation.order
+    );
+  } else {
+    node.rotation.copy(original.rotation);
+  }
+  if (transform?.scale) node.scale.fromArray(transform.scale);
+  else node.scale.copy(original.scale);
+  node.updateMatrix();
+}
 function firstMaterial(node) {
   const mat = node.material;
   if (!mat) return void 0;
@@ -3037,6 +3106,17 @@ function Model({
     });
     return map;
   }, [scene]);
+  const originalNodeTransforms = useMemo7(() => {
+    const transforms = /* @__PURE__ */ new WeakMap();
+    scene.traverse((node) => {
+      transforms.set(node, {
+        position: node.position.clone(),
+        rotation: node.rotation.clone(),
+        scale: node.scale.clone()
+      });
+    });
+    return transforms;
+  }, [scene]);
   const shellNodeNames = useMemo7(() => {
     const shell = /* @__PURE__ */ new Set();
     const sceneBox = new Box32();
@@ -3048,8 +3128,8 @@ function Model({
       meshNodes.push({ name, box });
       sceneBox.union(box);
     }
-    const sceneSize = sceneBox.getSize(new Vector32());
-    const size = new Vector32();
+    const sceneSize = sceneBox.getSize(new Vector33());
+    const size = new Vector33();
     for (const { name, box } of meshNodes) {
       box.getSize(size);
       const isShell = size.x > sceneSize.x * 0.7 && size.z > sceneSize.z * 0.7 && size.y > sceneSize.y * 0.4;
@@ -3089,6 +3169,43 @@ function Model({
     ).sort().join(""),
     [objectBindings]
   );
+  const bindingTransformSignature = useMemo7(
+    () => Object.entries(objectBindings).map(
+      ([nodeName, binding]) => JSON.stringify([
+        nodeName,
+        binding.modelObjectId ?? nodeName,
+        binding.transform ?? null
+      ])
+    ).sort().join(""),
+    [objectBindings]
+  );
+  const transformedNodesRef = useRef5(/* @__PURE__ */ new Set());
+  useEffect7(() => {
+    for (const node of transformedNodesRef.current) {
+      applyBindingTransform(node, void 0, originalNodeTransforms.get(node));
+    }
+    const nextTransformedNodes = /* @__PURE__ */ new Set();
+    for (const [nodeName, binding] of Object.entries(objectBindings)) {
+      if (!binding.transform) continue;
+      const node = nodeMap[binding.modelObjectId ?? nodeName];
+      if (!node) continue;
+      applyBindingTransform(
+        node,
+        binding.transform,
+        originalNodeTransforms.get(node)
+      );
+      nextTransformedNodes.add(node);
+    }
+    transformedNodesRef.current = nextTransformedNodes;
+    scene.updateMatrixWorld(true);
+    invalidate();
+  }, [
+    scene,
+    nodeMap,
+    originalNodeTransforms,
+    bindingTransformSignature,
+    invalidate
+  ]);
   const perNodeMaterials = useMemo7(() => {
     const map = {};
     for (const [nodeName, binding] of Object.entries(objectBindings)) {
@@ -3592,27 +3709,30 @@ function Model({
   const explodePartsRef = useRef5([]);
   const explodeStrengthRef = useRef5(0);
   const currentExplodeRef = useRef5(0);
-  const explodeTmp = useMemo7(() => new Vector32(), []);
+  const explodeTmp = useMemo7(() => new Vector33(), []);
   useEffect7(() => {
+    const bindingByNode = /* @__PURE__ */ new Map();
+    for (const [nodeName, binding] of Object.entries(objectBindings)) {
+      const node = nodeMap[binding.modelObjectId ?? nodeName];
+      if (node) bindingByNode.set(node, binding);
+    }
     for (const part of explodePartsRef.current) {
-      part.node.position.copy(part.restLocalPos);
+      applyBindingTransform(
+        part.node,
+        bindingByNode.get(part.node)?.transform,
+        originalNodeTransforms.get(part.node)
+      );
     }
     currentExplodeRef.current = 0;
     scene.updateWorldMatrix(true, true);
     const sceneBox = new Box32().setFromObject(scene);
-    const modelCenter = sceneBox.getCenter(new Vector32());
-    const radius = sceneBox.getSize(new Vector32()).length() * 0.5;
+    const modelCenter = sceneBox.getCenter(new Vector33());
+    const radius = sceneBox.getSize(new Vector33()).length() * 0.5;
     explodeStrengthRef.current = Number.isFinite(radius) ? radius : 0;
-    const targets = [];
-    const targetSet = /* @__PURE__ */ new Set();
-    for (const [nodeName, binding] of Object.entries(objectBindings)) {
-      const node = nodeMap[binding.modelObjectId ?? nodeName];
-      if (!node || targetSet.has(node)) continue;
-      targetSet.add(node);
-      targets.push(node);
-    }
+    const targets = [...bindingByNode.keys()];
+    const targetSet = new Set(targets);
     const parts = [];
-    const partCenter = new Vector32();
+    const partCenter = new Vector33();
     for (const node of targets) {
       if (!node.parent) continue;
       let ancestor = node.parent;
@@ -3634,14 +3754,21 @@ function Model({
       parts.push({
         node,
         restLocalPos: node.position.clone(),
-        restWorldPos: node.getWorldPosition(new Vector32()),
+        restWorldPos: node.getWorldPosition(new Vector33()),
         worldDir,
         parentInverse: new Matrix4().copy(node.parent.matrixWorld).invert()
       });
     }
     explodePartsRef.current = parts;
     invalidate();
-  }, [scene, nodeMap, nodeBindingSignature, invalidate]);
+  }, [
+    scene,
+    nodeMap,
+    nodeBindingSignature,
+    bindingTransformSignature,
+    originalNodeTransforms,
+    invalidate
+  ]);
   useEffect7(() => {
     invalidate();
   }, [explodeFactor, invalidate]);
@@ -3733,7 +3860,7 @@ import {
 } from "react";
 import { Html } from "@react-three/drei";
 import { useFrame as useFrame5, useThree as useThree8 } from "@react-three/fiber";
-import { MathUtils as MathUtils3, Vector3 as Vector33 } from "three";
+import { MathUtils as MathUtils3, Vector3 as Vector34 } from "three";
 
 // src/styles/AnnotationsLayer.css
 styleInject(".ri-annotationMarker--hovered {\n  transform: scale(1.08);\n  box-shadow: 0 12px 28px rgba(15, 23, 42, 0.18);\n  background: rgba(40, 40, 40, 0.92);\n}\n.ri-viewAnnotationHeader {\n  display: flex;\n  justify-content: space-between;\n  align-items: center;\n  margin-bottom: 8px;\n}\n.ri-viewAnnotationTitle {\n  margin: 0;\n  color: #e2e8f0;\n  font-size: 14px;\n  font-weight: 600;\n}\n");
@@ -3746,7 +3873,7 @@ function useCameraBiasedAnchor(annotation, worldPositionsRef) {
   const scene = useThree8((state) => state.scene);
   const anchorNodeRef = useRef6(null);
   const baseLocalPosition = useMemo8(
-    () => new Vector33(
+    () => new Vector34(
       ...annotation.anchorLocalPosition ?? annotation.localPosition ?? annotation.worldPosition
     ),
     [
@@ -3755,9 +3882,9 @@ function useCameraBiasedAnchor(annotation, worldPositionsRef) {
       annotation.worldPosition
     ]
   );
-  const worldPosition = useMemo8(() => new Vector33(), []);
-  const biasedWorldPosition = useMemo8(() => new Vector33(), []);
-  const toCamera = useMemo8(() => new Vector33(), []);
+  const worldPosition = useMemo8(() => new Vector34(), []);
+  const biasedWorldPosition = useMemo8(() => new Vector34(), []);
+  const toCamera = useMemo8(() => new Vector34(), []);
   useEffect8(() => {
     anchorNodeRef.current = null;
   }, [annotation.anchorNodeName]);
@@ -3780,7 +3907,7 @@ function useCameraBiasedAnchor(annotation, worldPositionsRef) {
     if (worldPositionsRef) {
       let stored = worldPositionsRef.current.get(annotation.id);
       if (!stored) {
-        stored = new Vector33();
+        stored = new Vector34();
         worldPositionsRef.current.set(annotation.id, stored);
       }
       stored.copy(worldPosition);
@@ -4178,7 +4305,7 @@ function AnnotationsLayer({
 // src/components/ModelViewer/MeasurementLayer.tsx
 import { useEffect as useEffect9, useMemo as useMemo9 } from "react";
 import { Html as Html2, Line } from "@react-three/drei";
-import { BoxGeometry, EdgesGeometry, Vector3 as Vector34 } from "three";
+import { BoxGeometry, EdgesGeometry, Vector3 as Vector35 } from "three";
 import { jsx as jsx10, jsxs as jsxs6 } from "react/jsx-runtime";
 var LINE_COLOR = "#22d3ee";
 var BOX_COLOR = "#facc15";
@@ -4253,7 +4380,7 @@ function MeasurementLayer({
     points.slice(1).map((point, index) => {
       const a = points[index].position;
       const b = point.position;
-      const distance = new Vector34(...a).distanceTo(new Vector34(...b));
+      const distance = new Vector35(...a).distanceTo(new Vector35(...b));
       return /* @__PURE__ */ jsxs6("group", { children: [
         /* @__PURE__ */ jsx10(Line, { points: [a, b], color: LINE_COLOR, lineWidth: 2 }),
         /* @__PURE__ */ jsx10(MeasureLabel, { position: midpoint(a, b), children: formatMeasurement(distance, unit) })
@@ -4274,7 +4401,7 @@ import {
 } from "react";
 import { useXR as useXR2, useXRHitTest, useXRInputSourceEvent } from "@react-three/xr";
 import { useFrame as useFrame6 } from "@react-three/fiber";
-import { Matrix4 as Matrix42, Vector3 as Vector35 } from "three";
+import { Matrix4 as Matrix42, Vector3 as Vector36 } from "three";
 import { Fragment as Fragment4, jsx as jsx11, jsxs as jsxs7 } from "react/jsx-runtime";
 var TARGET_SIZE = 1;
 var FORWARD_DISTANCE = 1;
@@ -4311,13 +4438,13 @@ var XRModelPresenter = forwardRef2(
       () => box ? computeNormalization(box, scaleMode) : null,
       [box, scaleMode]
     );
-    const placedPosition = useRef7(new Vector35(0, 0, -FORWARD_DISTANCE));
+    const placedPosition = useRef7(new Vector36(0, 0, -FORWARD_DISTANCE));
     const userScale = useRef7(1);
     const rotationY = useRef7(0);
     const placementMode = useRef7(true);
     const modelPlaced = useRef7(false);
     const hitMatrix = useMemo10(() => new Matrix42(), []);
-    const hitPosition = useRef7(new Vector35());
+    const hitPosition = useRef7(new Vector36());
     const hasHit = useRef7(false);
     const lastARState = useRef7(null);
     const gesturing = useRef7(false);
@@ -4515,7 +4642,7 @@ import {
   CatmullRomCurve3,
   Sphere,
   Spherical,
-  Vector3 as Vector36
+  Vector3 as Vector37
 } from "three";
 var ENTER_BLEND_SECONDS = 1.2;
 function CinematicCamera({
@@ -4596,13 +4723,13 @@ function CinematicCamera({
     if (!hasPath) return null;
     return {
       position: new CatmullRomCurve3(
-        waypoints.map((w) => new Vector36(...w.position)),
+        waypoints.map((w) => new Vector37(...w.position)),
         loop,
         "catmullrom",
         0.5
       ),
       target: new CatmullRomCurve3(
-        waypoints.map((w) => new Vector36(...w.target)),
+        waypoints.map((w) => new Vector37(...w.target)),
         loop,
         "catmullrom",
         0.5
@@ -4618,8 +4745,8 @@ function CinematicCamera({
     const points = waypoints.map((waypoint) => ({
       azimuth: waypoint.azimuthAngle,
       polar: waypoint.polarAngle,
-      distance: new Vector36(...waypoint.position).distanceTo(
-        new Vector36(...waypoint.target)
+      distance: new Vector37(...waypoint.position).distanceTo(
+        new Vector37(...waypoint.target)
       )
     }));
     for (let index = 1; index < points.length; index += 1) {
@@ -4631,14 +4758,14 @@ function CinematicCamera({
   }, [signature, hasPath]);
   const elapsedRef = useRef8(0);
   const enterElapsedRef = useRef8(0);
-  const enterPos = useRef8(new Vector36());
-  const enterTarget = useRef8(new Vector36());
+  const enterPos = useRef8(new Vector37());
+  const enterTarget = useRef8(new Vector37());
   const startedRef = useRef8(false);
   const pausedElapsedRef = useRef8(0);
   const hasFinishedRef = useRef8(false);
   const orbitRef = useRef8(null);
-  const tmpPos = useMemo11(() => new Vector36(), []);
-  const tmpTarget = useMemo11(() => new Vector36(), []);
+  const tmpPos = useMemo11(() => new Vector37(), []);
+  const tmpTarget = useMemo11(() => new Vector37(), []);
   const tmpSpherical = useMemo11(() => new Spherical(), []);
   useEffect11(() => {
     elapsedRef.current = 0;
@@ -5877,7 +6004,7 @@ import { useRef as useRef11, useEffect as useEffect15, useMemo as useMemo13, use
 import { useThree as useThree10, useFrame as useFrame8 } from "@react-three/fiber";
 import { Sphere as Sphere2, Line as Line2 } from "@react-three/drei";
 import {
-  Vector3 as Vector37,
+  Vector3 as Vector38,
   Vector2 as Vector25,
   AdditiveBlending as AdditiveBlending2,
   Plane,
@@ -5905,7 +6032,7 @@ var RING_SCREEN_SIZE = SUN_SCREEN_SIZE * 3;
 var RING_COLOR = "#4d7dff";
 var LINE_COLOR2 = "#ffcc00";
 var LINE_GLOW_RADIUS = 0.02;
-var UP_AXIS = new Vector37(0, 1, 0);
+var UP_AXIS = new Vector38(0, 1, 0);
 var AXIS_ARROW_LENGTH = 1.4;
 var AXIS_CONE_LENGTH = 0.35;
 var AXIS_CONE_RADIUS = 0.13;
@@ -5917,17 +6044,17 @@ var AXIS_COLORS = {
   z: "#4444ff"
 };
 function axisVector(axis) {
-  return new Vector37(axis === "x" ? 1 : 0, axis === "y" ? 1 : 0, axis === "z" ? 1 : 0);
+  return new Vector38(axis === "x" ? 1 : 0, axis === "y" ? 1 : 0, axis === "z" ? 1 : 0);
 }
 function computeAxisDragPlaneNormal(axis, eye) {
   const axisVec = axisVector(axis);
   if (eye.lengthSq() < 1e-8) {
     eye = axisVec.clone();
   }
-  let normal = new Vector37().crossVectors(axisVec, new Vector37().crossVectors(eye, axisVec));
+  let normal = new Vector38().crossVectors(axisVec, new Vector38().crossVectors(eye, axisVec));
   if (normal.lengthSq() < 1e-8) {
-    const helper = Math.abs(axisVec.y) < 0.9 ? UP_AXIS : new Vector37(1, 0, 0);
-    normal = new Vector37().crossVectors(axisVec, helper);
+    const helper = Math.abs(axisVec.y) < 0.9 ? UP_AXIS : new Vector38(1, 0, 0);
+    normal = new Vector38().crossVectors(axisVec, helper);
   }
   return normal.normalize();
 }
@@ -6000,17 +6127,17 @@ function LightHelpers({
   const shaftZRef = useRef11(null);
   const axisDragRef = useRef11({ dragging: false, axis: null });
   const axisDragPlaneRef = useRef11(new Plane());
-  const dragStartPosRef = useRef11(new Vector37());
+  const dragStartPosRef = useRef11(new Vector38());
   const dragLineRef = useRef11(null);
   const dragLineGeomRef = useRef11(null);
-  const currentPosRef = useRef11(new Vector37());
+  const currentPosRef = useRef11(new Vector38());
   const isDraggingRef = useRef11(false);
   const dragPlaneRef = useRef11(new Plane());
   const onDraggingChangeRef = useRef11(onDraggingChange);
   useEffect15(() => {
     onDraggingChangeRef.current = onDraggingChange;
   }, [onDraggingChange]);
-  const lightPos = useMemo13(() => new Vector37(position[0], position[1], position[2]), [position]);
+  const lightPos = useMemo13(() => new Vector38(position[0], position[1], position[2]), [position]);
   const linePositions = useMemo13(() => new Float32Array(6), []);
   const dragLinePositions = useMemo13(() => new Float32Array(6), []);
   const ringXPositions = useMemo13(() => makeRingPositions("x"), []);
@@ -6169,12 +6296,12 @@ function LightHelpers({
         const axis = axisDragRef.current.axis;
         const currentPos = currentPosRef.current;
         const axisVec = axisVector(axis);
-        const eye = new Vector37().subVectors(camera.position, currentPos);
+        const eye = new Vector38().subVectors(camera.position, currentPos);
         const planeNormal = computeAxisDragPlaneNormal(axis, eye);
         axisDragPlaneRef.current.setFromNormalAndCoplanarPoint(planeNormal, currentPos);
         const mouse2 = getMouseNdc(event);
         raycaster.setFromCamera(mouse2, camera);
-        const intersection2 = new Vector37();
+        const intersection2 = new Vector38();
         const hitPoint2 = raycaster.ray.intersectPlane(axisDragPlaneRef.current, intersection2);
         if (!hitPoint2) return;
         const toPoint = hitPoint2.clone().sub(currentPos);
@@ -6193,7 +6320,7 @@ function LightHelpers({
       if (!isDraggingRef.current) return;
       const mouse = getMouseNdc(event);
       raycaster.setFromCamera(mouse, camera);
-      const intersection = new Vector37();
+      const intersection = new Vector38();
       const hitPoint = raycaster.ray.intersectPlane(dragPlaneRef.current, intersection);
       if (!hitPoint) return;
       const newPos = [
@@ -6240,7 +6367,7 @@ function LightHelpers({
           setActiveTab?.("scene");
           setActiveSubTab?.("Lighting");
         }
-        const cameraDir = new Vector37();
+        const cameraDir = new Vector38();
         camera.getWorldDirection(cameraDir);
         dragPlaneRef.current.setFromNormalAndCoplanarPoint(cameraDir, currentPosRef.current);
         isDraggingRef.current = true;
@@ -6373,17 +6500,17 @@ function LightHelpers({
       ] }),
       gizmoVisible && /* @__PURE__ */ jsx19("group", { ref: axisGroupRef, children: axisArrows.map((axis) => {
         const axisColor = AXIS_COLORS[axis];
-        const end = new Vector37(
+        const end = new Vector38(
           axis === "x" ? AXIS_ARROW_LENGTH : 0,
           axis === "y" ? AXIS_ARROW_LENGTH : 0,
           axis === "z" ? AXIS_ARROW_LENGTH : 0
         );
-        const conePos = new Vector37(
+        const conePos = new Vector38(
           axis === "x" ? AXIS_ARROW_LENGTH - AXIS_CONE_LENGTH / 2 : 0,
           axis === "y" ? AXIS_ARROW_LENGTH - AXIS_CONE_LENGTH / 2 : 0,
           axis === "z" ? AXIS_ARROW_LENGTH - AXIS_CONE_LENGTH / 2 : 0
         );
-        const shaftPos = new Vector37(
+        const shaftPos = new Vector38(
           axis === "x" ? AXIS_ARROW_LENGTH / 2 : 0,
           axis === "y" ? AXIS_ARROW_LENGTH / 2 : 0,
           axis === "z" ? AXIS_ARROW_LENGTH / 2 : 0
@@ -6395,7 +6522,7 @@ function LightHelpers({
           /* @__PURE__ */ jsx19(
             Line2,
             {
-              points: [new Vector37(0, 0, 0), end],
+              points: [new Vector38(0, 0, 0), end],
               color: axisColor,
               transparent: true,
               opacity: 0.9,
@@ -6484,7 +6611,7 @@ function findInfluencingBone(hit) {
   if (!skinIndex || !skinWeight || !position) return null;
   const localHit = mesh.worldToLocal(hit.point.clone());
   const vertices = [hit.face.a, hit.face.b, hit.face.c];
-  const vertex = new Vector38();
+  const vertex = new Vector39();
   let nearest = vertices[0];
   let nearestDist = Infinity;
   for (const vi of vertices) {
@@ -6534,9 +6661,9 @@ function GuidedTourCameraFollow({
   const scene = useThree11((state) => state.scene);
   const nodeRef = useRef12(null);
   const hasPrev = useRef12(false);
-  const live = useMemo14(() => new Vector38(), []);
-  const prev = useMemo14(() => new Vector38(), []);
-  const goal = useMemo14(() => new Vector38(), []);
+  const live = useMemo14(() => new Vector39(), []);
+  const prev = useMemo14(() => new Vector39(), []);
+  const goal = useMemo14(() => new Vector39(), []);
   const nodeName = annotation?.anchorNodeName;
   const localPosition = annotation?.anchorLocalPosition;
   useEffect16(() => {
@@ -6576,7 +6703,7 @@ var DEFAULT_AR_OVERLAY_STATE = {
 };
 function computeMeasureBox(scene) {
   const box = new Box34().setFromObject(scene);
-  const size = new Vector38();
+  const size = new Vector39();
   box.getSize(size);
   return {
     min: [box.min.x, box.min.y, box.min.z],
@@ -6597,8 +6724,8 @@ function computeUvMeshStats(scene) {
 function computeModelBounds(scene) {
   const box = new Box34().setFromObject(scene);
   if (box.isEmpty()) return null;
-  const center = box.getCenter(new Vector38());
-  const radius = box.getSize(new Vector38()).length() / 2;
+  const center = box.getCenter(new Vector39());
+  const radius = box.getSize(new Vector39()).length() / 2;
   if (!Number.isFinite(radius) || radius <= 0) return null;
   return { center: [center.x, center.y, center.z], radius };
 }
@@ -6606,7 +6733,7 @@ function fitClippingPlanesToScene(scene, controls) {
   const camera = controls?.camera;
   if (!(camera instanceof PerspectiveCamera3)) return;
   const box = new Box34().setFromObject(scene);
-  const size = box.getSize(new Vector38()).length();
+  const size = box.getSize(new Vector39()).length();
   if (!Number.isFinite(size) || size <= 0) return;
   camera.near = size / 100;
   camera.far = size * 100;
@@ -6791,8 +6918,8 @@ function ModelViewer({
     if (!controls || initialCameraStateRef.current) {
       return;
     }
-    const position = controls.getPosition(new Vector38());
-    const target = controls.getTarget(new Vector38());
+    const position = controls.getPosition(new Vector39());
+    const target = controls.getTarget(new Vector39());
     initialCameraStateRef.current = {
       position: [position.x, position.y, position.z],
       target: [target.x, target.y, target.z]
@@ -7050,7 +7177,7 @@ function ModelViewer({
       const controls = controlsRef.current;
       const scene = sceneRef.current;
       if (!controls) return;
-      const target = new Vector38();
+      const target = new Vector39();
       const livePosition = annotationWorldPositionsRef.current.get(
         annotation.id
       );
@@ -7069,14 +7196,14 @@ function ModelViewer({
       const storedNormal = annotation.worldNormal;
       if (scene) {
         const box = new Box34().setFromObject(scene);
-        const modelCenter = new Vector38();
+        const modelCenter = new Vector39();
         box.getCenter(modelCenter);
-        const modelSize = new Vector38();
+        const modelSize = new Vector39();
         box.getSize(modelSize);
         const modelRadius = modelSize.length() * 0.2;
         let outwardDir;
         if (storedNormal) {
-          outwardDir = new Vector38(
+          outwardDir = new Vector39(
             storedNormal[0],
             storedNormal[1],
             storedNormal[2]
@@ -7227,6 +7354,16 @@ function ModelViewer({
   const isControlledBindings = onObjectBindingsChange !== void 0;
   const currentObjectBindings = isControlledBindings ? objectBindings : internalObjectBindings;
   currentObjectBindingsRef.current = currentObjectBindings;
+  const currentBindingTransformSignature = useMemo14(
+    () => Object.entries(currentObjectBindings).map(
+      ([bindingKey, binding]) => JSON.stringify([
+        bindingKey,
+        binding.modelObjectId,
+        binding.transform ?? null
+      ])
+    ).sort().join(""),
+    [currentObjectBindings]
+  );
   const currentHiddenObjects = useMemo14(
     () => Object.fromEntries(
       Object.entries(currentObjectBindings).filter(([, binding]) => binding.visible === false).map(([bindingKey]) => [bindingKey, true])
@@ -7366,7 +7503,7 @@ function ModelViewer({
       const fallbackY = Math.max(minOffset, (rect.height - height) / 2);
       const objectKey = resolveObjectKey(objectId, binding);
       const object = objectKey ? nodeRefsMap.current[objectKey] : null;
-      const clamp2 = (value, max) => {
+      const clamp3 = (value, max) => {
         if (max <= minOffset) {
           return minOffset;
         }
@@ -7374,23 +7511,23 @@ function ModelViewer({
       };
       if (canvasContainer && cameraControls && object) {
         const canvasRect = canvasContainer.getBoundingClientRect();
-        const objectCenter = new Vector38();
+        const objectCenter = new Vector39();
         new Box34().setFromObject(object).getCenter(objectCenter);
         objectCenter.project(cameraControls);
         const projectedX = (objectCenter.x + 1) / 2 * canvasRect.width + (canvasRect.left - rect.left);
         const projectedY = (1 - objectCenter.y) / 2 * canvasRect.height + (canvasRect.top - rect.top);
         return {
           objectId,
-          x: clamp2(projectedX + 24, maxX),
-          y: clamp2(projectedY - height / 2, maxY)
+          x: clamp3(projectedX + 24, maxX),
+          y: clamp3(projectedY - height / 2, maxY)
         };
       }
       const rawX = typeof fallbackCoords?.screenX === "number" ? fallbackCoords.screenX - rect.left : fallbackX;
       const rawY = typeof fallbackCoords?.screenY === "number" ? fallbackCoords.screenY - rect.top : fallbackY;
       return {
         objectId,
-        x: clamp2(rawX, maxX),
-        y: clamp2(rawY, maxY)
+        x: clamp3(rawX, maxX),
+        y: clamp3(rawY, maxY)
       };
     },
     [resolveObjectKey]
@@ -7399,7 +7536,6 @@ function ModelViewer({
     (event) => {
       const { objectId, action, binding } = event;
       setCurrentAction(event);
-      onAction?.(event);
       switch (action.id) {
         case "toggle-visibility": {
           let targetKey = objectId;
@@ -7447,6 +7583,7 @@ function ModelViewer({
         default:
           break;
       }
+      onAction?.(event);
     },
     [
       applyObjectBindings,
@@ -7587,7 +7724,8 @@ function ModelViewer({
       objectBindings: currentObjectBindingsRef.current,
       nodeRefs: nodeRefsMap.current,
       homeCameraState: initialCameraStateRef.current,
-      captureImage: (options) => captureImage(rendererCaptureRef.current, options)
+      captureImage: (options) => captureImage(rendererCaptureRef.current, options),
+      invalidate: () => rendererCaptureRef.current?.invalidate()
     });
   }, []);
   const fitScene = useCallback4(
@@ -7599,8 +7737,8 @@ function ModelViewer({
       }
       try {
         if (flyIn) {
-          const target = controls.getTarget(new Vector38());
-          const position = controls.getPosition(new Vector38());
+          const target = controls.getTarget(new Vector39());
+          const position = controls.getPosition(new Vector39());
           const direction = position.clone().sub(target);
           if (direction.lengthSq() < 1e-6) {
             direction.set(0, 0, 1);
@@ -7918,6 +8056,13 @@ function ModelViewer({
     );
     setBindingsMismatch(!hasAnyMatch);
   }, [modelLoaded, currentObjectBindings]);
+  useEffect16(() => {
+    const scene = sceneRef.current;
+    if (!modelLoaded || !scene) return;
+    scene.updateMatrixWorld(true);
+    setMeasureBox(computeMeasureBox(scene));
+    setModelBounds(computeModelBounds(scene));
+  }, [modelLoaded, currentBindingTransformSignature]);
   const clearMeasurements = useCallback4(() => setMeasurePoints([]), []);
   const handleMeasurePointerDown = useCallback4(
     (event) => {
@@ -7961,7 +8106,11 @@ function ModelViewer({
   );
   useEffect16(() => {
     setMeasurePoints([]);
-  }, [modelUrl, resolvedSceneConfig.model.rotation]);
+  }, [
+    modelUrl,
+    resolvedSceneConfig.model.rotation,
+    currentBindingTransformSignature
+  ]);
   const handleDownloadMesh = useCallback4(() => {
     const matRefs = materialRefsOut.current;
     const scene = sceneRef.current;
@@ -8304,11 +8453,13 @@ function ModelViewer({
                         shadowsEnabled: shadows,
                         environmentRotation: resolvedSceneConfig.environment.rotation,
                         environmentConfig: resolvedSceneConfig.environment,
-                        modelBounds
+                        modelBounds,
+                        objectBindings: currentObjectBindings,
+                        nodeRefs: nodeRefsMap
                       }
                     ),
                     showLightHelpers && resolvedSceneConfig.lighting.lights.map((light) => {
-                      if (!light.visible || light.type === "none" || light.type === "hemisphere") {
+                      if (!light.visible || light.type === "none" || light.type === "hemisphere" || light.attachment) {
                         return null;
                       }
                       return /* @__PURE__ */ jsx20(
@@ -8950,7 +9101,7 @@ function ModelViewer({
 }
 
 // src/components/BindingBuilder/BindingBuilder.tsx
-import { useCallback as useCallback9, useEffect as useEffect22, useMemo as useMemo17, useRef as useRef19, useState as useState26 } from "react";
+import { useCallback as useCallback9, useEffect as useEffect23, useMemo as useMemo17, useRef as useRef19, useState as useState27 } from "react";
 import {
   Redo2,
   Undo2,
@@ -8965,32 +9116,13 @@ styleInject('.bb-root {\n  --bb-font-family:\n    Inter,\n    "Segoe UI",\n    H
 
 // src/hooks/useViewerCamera.ts
 import { useCallback as useCallback5, useRef as useRef13, useState as useState11 } from "react";
-import { Vector3 as Vector39 } from "three";
-
-// src/utils/resolveBindingKey.ts
-function resolveBindingKey(objectBindings, objectId) {
-  if (objectBindings[objectId]) {
-    return objectId;
-  }
-  const idMatch = Object.entries(objectBindings).find(
-    ([, binding]) => binding.id === objectId
-  )?.[0];
-  if (idMatch) {
-    return idMatch;
-  }
-  const modelObjectMatch = Object.entries(objectBindings).find(
-    ([, binding]) => binding.modelObjectId === objectId
-  )?.[0];
-  return modelObjectMatch ?? null;
-}
-
-// src/hooks/useViewerCamera.ts
+import { Vector3 as Vector310 } from "three";
 function toTuple(vector) {
   return [vector.x, vector.y, vector.z];
 }
 function buildCameraState(camera, controls) {
-  const position = new Vector39();
-  const target = new Vector39();
+  const position = new Vector310();
+  const target = new Vector310();
   controls.getPosition(position);
   controls.getTarget(target);
   return {
@@ -9017,11 +9149,16 @@ async function runSmoothCameraTransition2(controls, action, smoothTime = 0.6) {
     controls.smoothTime = originalSmoothTime;
   }
 }
-function useViewerCamera() {
+function useViewerCamera(options = {}) {
+  const optionsRef = useRef13(options);
+  optionsRef.current = options;
   const viewerRef = useRef13(null);
   const [cameraState, setCameraStateValue] = useState11(
     null
   );
+  const [cameraPresets, setCameraPresets] = useState11(() => ({ ...options.presets }));
+  const cameraPresetsRef = useRef13(cameraPresets);
+  cameraPresetsRef.current = cameraPresets;
   const updateCameraState = useCallback5((nextState) => {
     setCameraStateValue(
       (previousState) => isSameCameraState(previousState, nextState) ? previousState : nextState
@@ -9035,16 +9172,56 @@ function useViewerCamera() {
   );
   const homeCameraStateRef = useRef13(null);
   const homeSceneRef = useRef13(null);
+  const initializedControlsRef = useRef13(null);
   const handleViewerReady = useCallback5((viewer) => {
     viewerRef.current = viewer;
-    updateCameraState(buildCameraState(viewer.controls.camera, viewer.controls));
+    const currentState = buildCameraState(
+      viewer.controls.camera,
+      viewer.controls
+    );
+    updateCameraState(currentState);
     if (viewer.scene !== homeSceneRef.current) {
       homeSceneRef.current = viewer.scene;
       homeCameraStateRef.current = null;
+      initializedControlsRef.current = null;
     }
     if (viewer.homeCameraState && !homeCameraStateRef.current) {
       homeCameraStateRef.current = viewer.homeCameraState;
     }
+    const { initialPosition, initialTarget, initialTransition = false } = optionsRef.current;
+    if ((initialPosition || initialTarget) && viewer.scene && // A target-only setup should preserve ModelViewer's fitted or authored
+    // camera position. Wait until that initial framing has settled instead
+    // of cancelling auto-fit while the camera is still at its fallback.
+    (initialPosition || viewer.homeCameraState) && initializedControlsRef.current !== viewer.controls) {
+      initializedControlsRef.current = viewer.controls;
+      if (!viewer.homeCameraState) {
+        markInitialAutoFitOverride(viewer.controls);
+      }
+      const position = initialPosition ?? currentState.position;
+      const target = initialTarget ?? currentState.target;
+      void viewer.controls.setLookAt(
+        position[0],
+        position[1],
+        position[2],
+        target[0],
+        target[1],
+        target[2],
+        initialTransition
+      ).then(() => {
+        if (viewerRef.current?.controls !== viewer.controls) {
+          return;
+        }
+        const nextState = buildCameraState(
+          viewer.controls.camera,
+          viewer.controls
+        );
+        homeCameraStateRef.current = {
+          position: nextState.position,
+          target: nextState.target
+        };
+        updateCameraState(nextState);
+      }).catch(() => void 0);
+    }
   }, [updateCameraState]);
   const resetView = useCallback5(async () => {
     const viewer = viewerRef.current;
@@ -9140,27 +9317,33 @@ function useViewerCamera() {
         return false;
       }
       try {
+        if (!viewerRef.current?.homeCameraState) {
+          markInitialAutoFitOverride(controls);
+        }
         await controls.setTarget(
           target[0],
           target[1],
           target[2],
           enableTransition
         );
+        updateCameraState(buildCameraState(controls.camera, controls));
         return true;
       } catch {
         return false;
       }
     },
-    []
+    [updateCameraState]
   );
-  const setCameraState = useCallback5(
+  const applyCameraPreset = useCallback5(
     async (state, enableTransition = true) => {
       const controls = viewerRef.current?.controls;
       if (!controls) {
         return false;
       }
       try {
-        markInitialAutoFitOverride(controls);
+        if (!viewerRef.current?.homeCameraState) {
+          markInitialAutoFitOverride(controls);
+        }
         const transitions = [
           controls.setLookAt(
             state.position[0],
@@ -9184,11 +9367,11 @@ function useViewerCamera() {
         await Promise.all(transitions);
         const camera = controls.camera;
         let projectionChanged = false;
-        if (state.fov !== null && "fov" in camera && typeof camera.fov === "number") {
+        if (state.fov != null && "fov" in camera && typeof camera.fov === "number") {
           camera.fov = state.fov;
           projectionChanged = true;
         }
-        if ("zoom" in camera && typeof camera.zoom === "number") {
+        if (state.zoom != null && "zoom" in camera && typeof camera.zoom === "number") {
           camera.zoom = state.zoom;
           projectionChanged = true;
         }
@@ -9203,13 +9386,94 @@ function useViewerCamera() {
     },
     [updateCameraState]
   );
+  const setCameraState = useCallback5(
+    (state, enableTransition = true) => applyCameraPreset(state, enableTransition),
+    [applyCameraPreset]
+  );
+  const lookAt = useCallback5(
+    (position, target, enableTransition = true) => applyCameraPreset({ position, target }, enableTransition),
+    [applyCameraPreset]
+  );
+  const orbitTo = useCallback5(
+    async (azimuthAngle, polarAngle, enableTransition = true) => {
+      const controls = viewerRef.current?.controls;
+      if (!controls) {
+        return false;
+      }
+      try {
+        if (!viewerRef.current?.homeCameraState) {
+          markInitialAutoFitOverride(controls);
+        }
+        await controls.rotateTo(
+          azimuthAngle,
+          polarAngle,
+          enableTransition
+        );
+        updateCameraState(buildCameraState(controls.camera, controls));
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    [updateCameraState]
+  );
+  const dollyTo = useCallback5(
+    async (distance, enableTransition = true) => {
+      const controls = viewerRef.current?.controls;
+      if (!controls) {
+        return false;
+      }
+      try {
+        if (!viewerRef.current?.homeCameraState) {
+          markInitialAutoFitOverride(controls);
+        }
+        await controls.dollyTo(distance, enableTransition);
+        updateCameraState(buildCameraState(controls.camera, controls));
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    [updateCameraState]
+  );
+  const savePreset = useCallback5((name) => {
+    const controls = viewerRef.current?.controls;
+    const trimmedName = name.trim();
+    if (!controls || !trimmedName) {
+      return null;
+    }
+    const nextState = buildCameraState(controls.camera, controls);
+    cameraPresetsRef.current = {
+      ...cameraPresetsRef.current,
+      [trimmedName]: nextState
+    };
+    setCameraPresets((current) => ({
+      ...current,
+      [trimmedName]: nextState
+    }));
+    updateCameraState(nextState);
+    return nextState;
+  }, [updateCameraState]);
+  const goToPreset = useCallback5(
+    (name, enableTransition = true) => {
+      const preset = cameraPresetsRef.current[name];
+      return preset ? applyCameraPreset(preset, enableTransition) : Promise.resolve(false);
+    },
+    [applyCameraPreset]
+  );
   return {
     cameraState,
+    cameraPresets,
     resetView,
     focusObject,
     fitScene,
     setCameraTarget,
     setCameraState,
+    lookAt,
+    orbitTo,
+    dollyTo,
+    savePreset,
+    goToPreset,
     handleCameraChange,
     handleViewerReady
   };
@@ -15078,6 +15342,9 @@ function IdentityPanel({
   ] }) });
 }
 
+// src/components/BindingBuilder/components/BasicsPanel.tsx
+import { useEffect as useEffect21, useState as useState24 } from "react";
+
 // src/components/BindingBuilder/utils/constants.ts
 var typeSuggestions = [
   "other",
@@ -15117,6 +15384,31 @@ function BasicsPanel({
   onToggle,
   updateBinding
 }) {
+  const [groupDraft, setGroupDraft] = useState24(selectedBinding.group ?? "");
+  const [tagsDraft, setTagsDraft] = useState24(
+    selectedBinding.tags?.join(", ") ?? ""
+  );
+  useEffect21(() => {
+    setGroupDraft(selectedBinding.group ?? "");
+    setTagsDraft(selectedBinding.tags?.join(", ") ?? "");
+  }, [selectedItem, selectedBinding.group, selectedBinding.tags]);
+  const commitGroup = () => {
+    updateBinding(selectedItem, (binding) => ({
+      ...binding,
+      group: groupDraft.trim() || void 0
+    }));
+  };
+  const commitTags = () => {
+    const tags = [
+      ...new Set(
+        tagsDraft.split(",").map((tag) => tag.trim()).filter(Boolean)
+      )
+    ];
+    updateBinding(selectedItem, (binding) => ({
+      ...binding,
+      tags: tags.length > 0 ? tags : void 0
+    }));
+  };
   return /* @__PURE__ */ jsxs36(BBSection, { title: "Basics", open, onToggle, children: [
     /* @__PURE__ */ jsxs36("div", { className: "bb-grid", children: [
       /* @__PURE__ */ jsxs36("div", { className: "bb-field", children: [
@@ -15163,6 +15455,38 @@ function BasicsPanel({
             children: statusOptions.map((option) => /* @__PURE__ */ jsx41("option", { value: option, children: option }, option))
           }
         )
+      ] }),
+      /* @__PURE__ */ jsxs36("div", { className: "bb-field", children: [
+        /* @__PURE__ */ jsx41("label", { className: "bb-label", children: "Group" }),
+        /* @__PURE__ */ jsx41(
+          "input",
+          {
+            className: "bb-input",
+            placeholder: "paint",
+            value: groupDraft,
+            onChange: (event) => setGroupDraft(event.target.value),
+            onBlur: commitGroup,
+            onKeyDown: (event) => {
+              if (event.key === "Enter") event.currentTarget.blur();
+            }
+          }
+        )
+      ] }),
+      /* @__PURE__ */ jsxs36("div", { className: "bb-field", children: [
+        /* @__PURE__ */ jsx41("label", { className: "bb-label", children: "Tags" }),
+        /* @__PURE__ */ jsx41(
+          "input",
+          {
+            className: "bb-input",
+            placeholder: "exterior, configurable",
+            value: tagsDraft,
+            onChange: (event) => setTagsDraft(event.target.value),
+            onBlur: commitTags,
+            onKeyDown: (event) => {
+              if (event.key === "Enter") event.currentTarget.blur();
+            }
+          }
+        )
       ] })
     ] }),
     /* @__PURE__ */ jsxs36("div", { className: "bb-checkboxRow", style: { marginTop: 12 }, children: [
@@ -15213,7 +15537,7 @@ function BasicsPanel({
 }
 
 // src/components/BindingBuilder/components/ActionsPanel.tsx
-import { useEffect as useEffect21, useState as useState24 } from "react";
+import { useEffect as useEffect22, useState as useState25 } from "react";
 
 // src/components/BindingBuilder/utils/actionCatalog.ts
 var ACTION_CATALOG = [
@@ -15239,19 +15563,19 @@ var ACTION_CATALOG = [
     id: "toggle-light",
     label: "Toggle Light",
     handling: "host",
-    description: "Seeded on light bindings. Handle it in your onAction callback."
+    description: "Seeded on light bindings. Add declarative effects for useViewerActions, or handle it in onAction."
   },
   {
     id: "change-light-color",
     label: "Change Light Color",
     handling: "host",
-    description: "Seeded on light bindings. Handle it in your onAction callback."
+    description: "Seeded on light bindings. Add declarative effects for useViewerActions, or handle it in onAction."
   },
   {
     id: "set-brightness",
     label: "Set Brightness",
     handling: "host",
-    description: "Seeded on light bindings. Handle it in your onAction callback."
+    description: "Seeded on light bindings. Add declarative effects for useViewerActions, or handle it in onAction."
   }
 ];
 var CUSTOM_ACTION_ID = "__custom__";
@@ -15312,8 +15636,8 @@ function ActionsPanel({
   onToggle,
   updateBinding
 }) {
-  const [customRows, setCustomRows] = useState24(/* @__PURE__ */ new Set());
-  useEffect21(() => {
+  const [customRows, setCustomRows] = useState25(/* @__PURE__ */ new Set());
+  useEffect22(() => {
     setCustomRows(/* @__PURE__ */ new Set());
   }, [selectedItem]);
   const actions = selectedBinding.actions ?? [];
@@ -15429,8 +15753,8 @@ function ActionsPanel({
                 }
               )
             ] }),
-            catalogEntry ? /* @__PURE__ */ jsx42("span", { className: "bb-note", children: catalogEntry.description }) : trimmedId.length === 0 ? /* @__PURE__ */ jsx42("span", { className: "bb-note", style: { color: "#fca5a5" }, children: "An action ID is required \u2014 the button renders but can never be identified in onAction." }) : /* @__PURE__ */ jsxs37("span", { className: "bb-note", style: { color: "#fcd34d" }, children: [
-              "Unrecognised ID \u2014 the viewer has no built-in behaviour for it, so your app must handle it in onAction.",
+            catalogEntry ? /* @__PURE__ */ jsx42("span", { className: "bb-note", children: catalogEntry.description }) : trimmedId.length === 0 ? /* @__PURE__ */ jsx42("span", { className: "bb-note", style: { color: "#fca5a5" }, children: "An action ID is required, the button renders but can never be identified in onAction." }) : /* @__PURE__ */ jsxs37("span", { className: "bb-note", style: { color: "#fcd34d" }, children: [
+              "Unrecognised ID, the viewer has no built-in behavior for it. Add declarative effects and execute them with useViewerActions, or handle it in onAction.",
               suggestion ? /* @__PURE__ */ jsxs37(Fragment13, { children: [
                 " Did you mean ",
                 /* @__PURE__ */ jsx42(
@@ -15453,7 +15777,13 @@ function ActionsPanel({
                 "?"
               ] }) : null
             ] }),
-            isDuplicate ? /* @__PURE__ */ jsx42("span", { className: "bb-note", style: { color: "#fcd34d" }, children: "Another action on this binding uses the same ID \u2014 they will render as two identical buttons." }) : null
+            action.effects?.length ? /* @__PURE__ */ jsxs37("span", { className: "bb-note", children: [
+              action.effects.length,
+              " declarative effect",
+              action.effects.length === 1 ? "" : "s",
+              ", execute with useViewerActions."
+            ] }) : null,
+            isDuplicate ? /* @__PURE__ */ jsx42("span", { className: "bb-note", style: { color: "#fcd34d" }, children: "Another action on this binding uses the same ID, they will render as two identical buttons." }) : null
           ] }),
           /* @__PURE__ */ jsx42("div", { className: "bb-actionFooter", children: /* @__PURE__ */ jsx42(
             "button",
@@ -15602,7 +15932,7 @@ function CameraPositionPanel({
 }
 
 // src/components/BindingBuilder/components/SceneNodesPanel.tsx
-import { useMemo as useMemo16, useState as useState25 } from "react";
+import { useMemo as useMemo16, useState as useState26 } from "react";
 
 // src/components/BindingBuilder/utils/bindingFactory.ts
 function slugify2(value) {
@@ -15691,7 +16021,7 @@ function SceneNodesPanel({
   isOpen = true,
   onToggle
 }) {
-  const [search, setSearch] = useState25("");
+  const [search, setSearch] = useState26("");
   const nodeKeys = useMemo16(() => Object.keys(bindings), [bindings]);
   const filteredNodeKeys = useMemo16(() => {
     const query = search.trim().toLowerCase();
@@ -15922,9 +16252,9 @@ function toBindingsJson(bindings) {
 }
 function toBindingsTypeScript(bindings) {
   return [
-    'import type { ObjectBinding } from "@liveroom-tech/react-immersive";',
+    'import { defineObjectBindings } from "@liveroom-tech/react-immersive";',
     "",
-    `export const objectBindings: Record<string, ObjectBinding> = ${JSON.stringify(bindings, null, 2)};`,
+    `export const objectBindings = defineObjectBindings(${JSON.stringify(bindings, null, 2)});`,
     ""
   ].join("\n");
 }
@@ -16147,27 +16477,27 @@ function BindingBuilder({ licenseKey }) {
   const modelInputRef = useRef19(null);
   const bindingsInputRef = useRef19(null);
   const sceneConfigInputRef = useRef19(null);
-  const [modelUrl, setModelUrl] = useState26(null);
-  const [modelName, setModelName] = useState26("");
-  const [selectedItem, setSelectedItem] = useState26(null);
+  const [modelUrl, setModelUrl] = useState27(null);
+  const [modelName, setModelName] = useState27("");
+  const [selectedItem, setSelectedItem] = useState27(null);
   const bindingsHistory = useUndoableState({});
   const bindings = bindingsHistory.value;
   const setBindings = bindingsHistory.setValue;
-  const [loading, setLoading] = useState26(false);
-  const [isExporting, setIsExporting] = useState26(false);
-  const [statusMessage, setStatusMessage] = useState26(
+  const [loading, setLoading] = useState27(false);
+  const [isExporting, setIsExporting] = useState27(false);
+  const [statusMessage, setStatusMessage] = useState27(
     "Load the demo model or upload a GLB/GLTF model to generate bindings."
   );
-  const [statusTone, setStatusTone] = useState26("default");
-  const [statusBannerVisible, setStatusBannerVisible] = useState26(false);
-  const [metricsDraft, setMetricsDraft] = useState26("{}");
-  const [metadataDraft, setMetadataDraft] = useState26("{}");
-  const [metricsError, setMetricsError] = useState26(null);
-  const [metadataError, setMetadataError] = useState26(null);
-  const [isPreviewDragActive, setIsPreviewDragActive] = useState26(false);
-  const [isEditorCollapsed, setIsEditorCollapsed] = useState26(false);
-  const [isNodesCollapsed, setIsNodesCollapsed] = useState26(false);
-  const [openObjectSections, setOpenObjectSections] = useState26({
+  const [statusTone, setStatusTone] = useState27("default");
+  const [statusBannerVisible, setStatusBannerVisible] = useState27(false);
+  const [metricsDraft, setMetricsDraft] = useState27("{}");
+  const [metadataDraft, setMetadataDraft] = useState27("{}");
+  const [metricsError, setMetricsError] = useState27(null);
+  const [metadataError, setMetadataError] = useState27(null);
+  const [isPreviewDragActive, setIsPreviewDragActive] = useState27(false);
+  const [isEditorCollapsed, setIsEditorCollapsed] = useState27(false);
+  const [isNodesCollapsed, setIsNodesCollapsed] = useState27(false);
+  const [openObjectSections, setOpenObjectSections] = useState27({
     identity: true,
     basics: true,
     material: false,
@@ -16176,7 +16506,7 @@ function BindingBuilder({ licenseKey }) {
     metrics: false,
     metadata: false
   });
-  const [openMaterialPanels, setOpenMaterialPanels] = useState26({
+  const [openMaterialPanels, setOpenMaterialPanels] = useState27({
     pbr: true,
     roughness: false,
     emission: false,
@@ -16192,24 +16522,24 @@ function BindingBuilder({ licenseKey }) {
   });
   const toggleObjectSection = (key) => setOpenObjectSections((prev) => ({ ...prev, [key]: !prev[key] }));
   const toggleMaterialPanel = (key) => setOpenMaterialPanels((prev) => ({ ...prev, [key]: !prev[key] }));
-  const [activeEditorTab, setActiveEditorTab] = useState26(
+  const [activeEditorTab, setActiveEditorTab] = useState27(
     "object"
   );
-  const [activeSubTab, setActiveSubTab] = useState26("General");
-  const [pbrWorkflow, setPbrWorkflow] = useState26("metalness");
-  const [materialPanelEnabled, setMaterialPanelEnabled] = useState26(createMaterialPanelEnabledState());
+  const [activeSubTab, setActiveSubTab] = useState27("General");
+  const [pbrWorkflow, setPbrWorkflow] = useState27("metalness");
+  const [materialPanelEnabled, setMaterialPanelEnabled] = useState27(createMaterialPanelEnabledState());
   const materialPanelItemRef = useRef19(null);
-  const [zoomOnSelected, setZoomOnSelected] = useState26(false);
-  const [highlightOnHover, setHighlightOnHover] = useState26(true);
-  const [resetDialogOpen, setResetDialogOpen] = useState26(false);
-  const [resetTarget, setResetTarget] = useState26(
+  const [zoomOnSelected, setZoomOnSelected] = useState27(false);
+  const [highlightOnHover, setHighlightOnHover] = useState27(true);
+  const [resetDialogOpen, setResetDialogOpen] = useState27(false);
+  const [resetTarget, setResetTarget] = useState27(
     null
   );
   const sceneConfigHistory = useUndoableState(DEFAULT_SCENE_CONFIG);
   const sceneConfig = sceneConfigHistory.value;
   const setSceneConfig = sceneConfigHistory.setValue;
-  const [activeAnnotation, setActiveAnnotation] = useState26(null);
-  const [panelHoveredBinding, setPanelHoveredBinding] = useState26(null);
+  const [activeAnnotation, setActiveAnnotation] = useState27(null);
+  const [panelHoveredBinding, setPanelHoveredBinding] = useState27(null);
   const license = useLicense(licenseKey);
   const tier = normalizeTier(license.tier);
   const bindingBuilderContextValue = useMemo17(
@@ -16287,7 +16617,7 @@ function BindingBuilder({ licenseKey }) {
     },
     []
   );
-  useEffect22(() => {
+  useEffect23(() => {
     if (!selectedBinding) {
       setMetricsDraft("{}");
       setMetadataDraft("{}");
@@ -16300,7 +16630,7 @@ function BindingBuilder({ licenseKey }) {
     setMetricsError(null);
     setMetadataError(null);
   }, [selectedBinding]);
-  useEffect22(() => {
+  useEffect23(() => {
     const derived = createMaterialPanelEnabledState(selectedMaterial);
     if (materialPanelItemRef.current !== selectedItem) {
       materialPanelItemRef.current = selectedItem;
@@ -16319,12 +16649,12 @@ function BindingBuilder({ licenseKey }) {
       return changed ? next : prev;
     });
   }, [selectedItem, selectedMaterial]);
-  useEffect22(() => {
+  useEffect23(() => {
     return () => {
       uploadedModelRef.current?.cleanup();
     };
   }, []);
-  useEffect22(() => {
+  useEffect23(() => {
     const handleKeyDown = (event) => {
       if (event.key.toLowerCase() !== "z" || !(event.metaKey || event.ctrlKey)) {
         return;
@@ -16345,7 +16675,7 @@ function BindingBuilder({ licenseKey }) {
     window.addEventListener("keydown", handleKeyDown);
     return () => window.removeEventListener("keydown", handleKeyDown);
   }, [activeEditorTab, bindingsHistory, sceneConfigHistory]);
-  useEffect22(() => {
+  useEffect23(() => {
     if (loading || statusTone === "default" || statusTone === "success") return;
     setStatusBannerVisible(true);
     const timeout = window.setTimeout(
@@ -17375,7 +17705,7 @@ function BindingBuilder({ licenseKey }) {
           /* @__PURE__ */ jsx46("strong", { children: resetTarget === "bindings" ? "Object Bindings" : "Scene Config" }),
           "?"
         ] }),
-        /* @__PURE__ */ jsx46("p", { className: "bb-reset-details", children: resetTarget === "bindings" ? "This will remove all your custom changes to object properties, materials, actions, camera positions, metrics, and metadata." : "This will restore all scene settings (camera, lighting, environment, background, animations, annotations, etc.) to their default values." }),
+        /* @__PURE__ */ jsx46("p", { className: "bb-reset-details", children: resetTarget === "bindings" ? "This will remove all your custom changes to object properties, groups, tags, transforms, materials, actions, camera positions, metrics, and metadata." : "This will restore all scene settings (camera, lighting, environment, background, animations, annotations, etc.) to their default values." }),
         /* @__PURE__ */ jsx46("p", { className: "bb-reset-warning", children: "This action cannot be undone!" })
       ] }),
       /* @__PURE__ */ jsxs41("div", { className: "bb-reset-footer", children: [
@@ -17389,9 +17719,9 @@ function BindingBuilder({ licenseKey }) {
 // src/components/SimpleModelViewer/SimpleModelViewer.tsx
 import {
   useRef as useRef20,
-  useState as useState27,
+  useState as useState28,
   useCallback as useCallback10,
-  useEffect as useEffect23,
+  useEffect as useEffect24,
   useMemo as useMemo18,
   Component as Component3,
   Suspense as Suspense3
@@ -17402,7 +17732,7 @@ import { Canvas as Canvas3 } from "@react-three/fiber";
 import {
   Box3 as Box35,
   PerspectiveCamera as PerspectiveCamera4,
-  Vector3 as Vector310
+  Vector3 as Vector311
 } from "three";
 import { SkeletonUtils as SkeletonUtils2 } from "three-stdlib";
 
@@ -17441,7 +17771,7 @@ function applyClippingPlanes(scene, controls) {
   if (!controls) return;
   const camera = controls.camera;
   if (!(camera instanceof PerspectiveCamera4)) return;
-  const size = new Box35().setFromObject(scene).getSize(new Vector310()).length();
+  const size = new Box35().setFromObject(scene).getSize(new Vector311()).length();
   if (!Number.isFinite(size) || size <= 0) return;
   camera.near = size / 100;
   camera.far = size * 100;
@@ -17480,7 +17810,7 @@ function InnerModel({
     meshopt: true
   });
   const invalidate = useThree12((state) => state.invalidate);
-  const [hoveredKey, setHoveredKey] = useState27(null);
+  const [hoveredKey, setHoveredKey] = useState28(null);
   const scene = useMemo18(
     () => SkeletonUtils2.clone(rawScene),
     [rawScene]
@@ -17510,14 +17840,14 @@ function InnerModel({
     }
     return map;
   }, [meshMap]);
-  useEffect23(
+  useEffect24(
     () => () => {
       Object.values(perKeyMaterials).forEach((m) => m.dispose());
     },
     [perKeyMaterials]
   );
   const notifiedUrl = useRef20(null);
-  useEffect23(() => {
+  useEffect24(() => {
     if (notifiedUrl.current === url) return;
     notifiedUrl.current = url;
     scene.updateWorldMatrix(true, true);
@@ -17525,7 +17855,7 @@ function InnerModel({
     onMeshesReady(meshMap);
     onModelLoaded(scene);
   }, [url, scene, meshMap, onMeshesReady, onModelLoaded]);
-  useEffect23(() => {
+  useEffect24(() => {
     const controller = new AbortController();
     void buildSceneBVH(scene, controller.signal);
     return () => {
@@ -17537,22 +17867,22 @@ function InnerModel({
     () => !exceedsBvhBudget(scene),
     [scene]
   );
-  useEffect23(() => {
+  useEffect24(() => {
     for (const [key, { ref }] of Object.entries(meshMap)) {
       nodeRefsOut.current[key] = ref;
     }
   }, [meshMap, nodeRefsOut]);
-  useEffect23(() => {
+  useEffect24(() => {
     if (!highlightOnHover && hoveredKey !== null) {
       setHoveredKey(null);
     }
   }, [highlightOnHover, hoveredKey]);
-  useEffect23(() => {
+  useEffect24(() => {
     return () => {
       document.body.style.cursor = "default";
     };
   }, []);
-  useEffect23(() => {
+  useEffect24(() => {
     for (const [key, { ref }] of Object.entries(meshMap)) {
       ref.visible = !hiddenKeys.has(key);
       const mat = perKeyMaterials[key];
@@ -17626,7 +17956,7 @@ function CameraFitter({
   const invalidate = useThree12((state) => state.invalidate);
   const size = useThree12((state) => state.size);
   const resizeTimerRef = useRef20(null);
-  useEffect23(() => {
+  useEffect24(() => {
     fitted.current = false;
     invalidate();
   }, [invalidate, scene]);
@@ -17646,7 +17976,7 @@ function CameraFitter({
     }).catch(() => {
     }).finally(onInitialFitComplete);
   });
-  useEffect23(() => {
+  useEffect24(() => {
     if (!refitOnResize || !fitted.current || !scene || !controlsRef.current) {
       return;
     }
@@ -17674,7 +18004,7 @@ function CameraFitter({
 function ExposureController({ exposure }) {
   const gl = useThree12((state) => state.gl);
   const invalidate = useThree12((state) => state.invalidate);
-  useEffect23(() => {
+  useEffect24(() => {
     gl.toneMappingExposure = exposure;
     invalidate();
   }, [gl, exposure, invalidate]);
@@ -17782,7 +18112,7 @@ function EnvironmentSection({
   title,
   children
 }) {
-  const [collapsed, setCollapsed] = useState27(false);
+  const [collapsed, setCollapsed] = useState28(false);
   return /* @__PURE__ */ jsxs42("div", { className: "env-section", children: [
     /* @__PURE__ */ jsxs42(
       "button",
@@ -17947,8 +18277,8 @@ function SceneObjectsPanel2({
   onHover,
   onToggleVisibility
 }) {
-  const [search, setSearch] = useState27("");
-  const [rowHovered, setRowHovered] = useState27(null);
+  const [search, setSearch] = useState28("");
+  const [rowHovered, setRowHovered] = useState28(null);
   const entries = Object.values(meshKeys).filter(
     (m) => m.label.toLowerCase().includes(search.toLowerCase())
   );
@@ -18077,30 +18407,30 @@ function SimpleModelViewer({
   const fileInputRef = useRef20(null);
   const uploadedModelRef = useRef20(null);
   const dragDepthRef = useRef20(0);
-  const [loadedScene, setLoadedScene] = useState27(null);
-  const [largeModelTriangles, setLargeModelTriangles] = useState27(
+  const [loadedScene, setLoadedScene] = useState28(null);
+  const [largeModelTriangles, setLargeModelTriangles] = useState28(
     null
   );
-  const [largeModelNoticeDismissed, setLargeModelNoticeDismissed] = useState27(false);
-  const [meshKeys, setMeshKeys] = useState27({});
-  const [hiddenKeys, setHiddenKeys] = useState27(/* @__PURE__ */ new Set());
-  const [selectedKey, setSelectedKey] = useState27(null);
-  const [panelHoveredKey, setPanelHoveredKey] = useState27(null);
-  const [uploadedModelUrl, setUploadedModelUrl] = useState27(null);
-  const [uploadedModelName, setUploadedModelName] = useState27(
+  const [largeModelNoticeDismissed, setLargeModelNoticeDismissed] = useState28(false);
+  const [meshKeys, setMeshKeys] = useState28({});
+  const [hiddenKeys, setHiddenKeys] = useState28(/* @__PURE__ */ new Set());
+  const [selectedKey, setSelectedKey] = useState28(null);
+  const [panelHoveredKey, setPanelHoveredKey] = useState28(null);
+  const [uploadedModelUrl, setUploadedModelUrl] = useState28(null);
+  const [uploadedModelName, setUploadedModelName] = useState28(
     null
   );
-  const [modelLoadFailed, setModelLoadFailed] = useState27(false);
-  const [isResolvingUpload, setIsResolvingUpload] = useState27(false);
-  const [initialFitComplete, setInitialFitComplete] = useState27(false);
-  const [isDragActive, setIsDragActive] = useState27(false);
-  const [isPanelOpen, setIsPanelOpen] = useState27(
+  const [modelLoadFailed, setModelLoadFailed] = useState28(false);
+  const [isResolvingUpload, setIsResolvingUpload] = useState28(false);
+  const [initialFitComplete, setInitialFitComplete] = useState28(false);
+  const [isDragActive, setIsDragActive] = useState28(false);
+  const [isPanelOpen, setIsPanelOpen] = useState28(
     () => typeof window === "undefined" ? true : window.innerWidth > 900
   );
-  const [isEnvPanelOpen, setIsEnvPanelOpen] = useState27(
+  const [isEnvPanelOpen, setIsEnvPanelOpen] = useState28(
     () => typeof window === "undefined" ? true : window.innerWidth > 900
   );
-  const [envSettings, setEnvSettings] = useState27({
+  const [envSettings, setEnvSettings] = useState28({
     backgroundEnabled,
     backgroundColor,
     autoRotate,
@@ -18183,7 +18513,7 @@ function SimpleModelViewer({
     },
     [handleUploadedModel]
   );
-  useEffect23(() => {
+  useEffect24(() => {
     return () => {
       revokeUploadedModelUrl();
     };
@@ -18194,10 +18524,10 @@ function SimpleModelViewer({
     },
     []
   );
-  useEffect23(() => {
+  useEffect24(() => {
     setEnvSettings((prev) => ({ ...prev, backgroundColor }));
   }, [backgroundColor]);
-  useEffect23(() => {
+  useEffect24(() => {
     resetModelState();
   }, [activeModelUrl, resetModelState]);
   const handleMeshesReady = useCallback10((meshes) => {
@@ -18513,9 +18843,9 @@ function SimpleModelViewer({
 }
 
 // src/hooks/useViewerSelection.ts
-import { useCallback as useCallback11, useState as useState28 } from "react";
+import { useCallback as useCallback11, useState as useState29 } from "react";
 function useViewerSelection(initialSelectedObjectBinding = null) {
-  const [selectedObjectBinding, setSelectedObjectBinding] = useState28(
+  const [selectedObjectBinding, setSelectedObjectBinding] = useState29(
     initialSelectedObjectBinding
   );
   const handleObjectSelect = useCallback11(
@@ -18562,7 +18892,7 @@ function useObjectBindingIds(objectBindings) {
 }
 
 // src/hooks/useObjectBindings.ts
-import { useCallback as useCallback12, useMemo as useMemo21, useState as useState29 } from "react";
+import { useCallback as useCallback12, useMemo as useMemo21, useState as useState30 } from "react";
 
 // src/utils/deepMerge.ts
 function isPlainObject2(value) {
@@ -18580,6 +18910,27 @@ function deepMerge(base, patch) {
   return target;
 }
 
+// src/utils/selectBindings.ts
+function isSelector(target) {
+  return typeof target === "object" && !Array.isArray(target);
+}
+function matchesSelector(binding, selector) {
+  if ("group" in selector) return binding.group === selector.group;
+  if ("tag" in selector) return binding.tags?.includes(selector.tag) ?? false;
+  return binding.type === selector.type;
+}
+function selectBindingKeys(bindings, target) {
+  if (isSelector(target)) {
+    return Object.entries(bindings).filter(([, binding]) => matchesSelector(binding, target)).map(([bindingKey]) => bindingKey);
+  }
+  const ids = typeof target === "string" ? [target] : target;
+  const keys = ids.map((id) => resolveBindingKey(bindings, id)).filter((key) => key !== null);
+  return [...new Set(keys)];
+}
+function selectBindings(bindings, target) {
+  return selectBindingKeys(bindings, target).map((key) => bindings[key]).filter((binding) => binding !== void 0);
+}
+
 // src/utils/patchBindings.ts
 function isBindingEditArray(value) {
   return Array.isArray(value) && value.length > 0 && typeof value[0] !== "string";
@@ -18588,10 +18939,7 @@ function patchBindings(bindings, objectIdOrEdits, patch) {
   const edits = isBindingEditArray(objectIdOrEdits) ? objectIdOrEdits : [{ ids: objectIdOrEdits, patch: patch ?? {} }];
   let next = bindings;
   for (const edit of edits) {
-    const ids = Array.isArray(edit.ids) ? edit.ids : [edit.ids];
-    for (const id of ids) {
-      const bindingKey = resolveBindingKey(next, id);
-      if (!bindingKey) continue;
+    for (const bindingKey of selectBindingKeys(next, edit.ids)) {
       const binding = next[bindingKey];
       if (!binding) continue;
       const patchedBinding = deepMerge(binding, edit.patch);
@@ -18606,13 +18954,43 @@ function material(value) {
 }
 
 // src/hooks/useObjectBindings.ts
+var TEXTURE_PROPERTY_BY_CHANNEL = {
+  baseColor: "texture",
+  metalness: "metalnessMap",
+  roughness: "roughnessMap",
+  emissive: "emissiveMap",
+  alpha: "alphaMap",
+  normal: "normalMap",
+  bump: "bumpMap",
+  ao: "aoMap",
+  displacement: "displacementMap",
+  clearcoat: "clearcoatMap",
+  clearcoatRoughness: "clearcoatRoughnessMap",
+  clearcoatNormal: "clearcoatNormalMap",
+  anisotropy: "anisotropyMap",
+  transmission: "transmissionMap",
+  thickness: "thicknessMap",
+  sheenColor: "sheenColorMap",
+  sheenRoughness: "sheenRoughnessMap",
+  specularIntensity: "specularIntensityMap",
+  specularColor: "specularColorMap"
+};
+function cloneMaterial(value) {
+  if (!value) return void 0;
+  return Object.fromEntries(
+    Object.entries(value).map(([key, field]) => [
+      key,
+      field && typeof field === "object" ? { ...field } : field
+    ])
+  );
+}
 function getHiddenObjects(objectBindings) {
   return Object.fromEntries(
     Object.entries(objectBindings).filter(([, binding]) => binding.visible === false).map(([bindingKey]) => [bindingKey, true])
   );
 }
 function useObjectBindings(initialBindings) {
-  const [objectBindings, setObjectBindings] = useState29(initialBindings);
+  const [objectBindings, setObjectBindings] = useState30(initialBindings);
   const updateObjectBindings = useCallback12(
     (objectIdOrEdits, patchValue) => {
       setObjectBindings(
@@ -18626,17 +19004,86 @@ function useObjectBindings(initialBindings) {
     []
   );
   const setMaterial = useCallback12(
-    (objectId, value) => updateObjectBindings(objectId, material(value)),
+    (target, value) => updateObjectBindings(target, material(value)),
     [updateObjectBindings]
   );
   const setBaseColor = useCallback12(
-    (objectId, color) => setMaterial(objectId, { baseColor: color }),
+    (target, color) => setMaterial(target, { baseColor: color }),
     [setMaterial]
   );
+  const setTexture = useCallback12(
+    (target, texture, channel = "baseColor") => {
+      const property = TEXTURE_PROPERTY_BY_CHANNEL[channel];
+      const slot = typeof texture === "string" ? { path: texture } : texture;
+      updateObjectBindings(target, {
+        style: { material: { [property]: slot } }
+      });
+    },
+    [updateObjectBindings]
+  );
+  const clearTexture = useCallback12(
+    (target, channel = "baseColor") => {
+      const property = TEXTURE_PROPERTY_BY_CHANNEL[channel];
+      updateObjectBindings(target, {
+        style: { material: { [property]: void 0 } }
+      });
+    },
+    [updateObjectBindings]
+  );
+  const copyMaterial = useCallback12(
+    (source, target) => {
+      setObjectBindings((current) => {
+        const sourceKey = resolveBindingKey(current, source);
+        if (!sourceKey) return current;
+        const sourceMaterial = cloneMaterial(
+          current[sourceKey]?.style?.material
+        );
+        const targetKeys = selectBindingKeys(current, target);
+        if (targetKeys.length === 0) return current;
+        let next = current;
+        for (const targetKey of targetKeys) {
+          const binding = current[targetKey];
+          if (!binding) continue;
+          if (next === current) next = { ...current };
+          next[targetKey] = {
+            ...binding,
+            style: {
+              ...binding.style,
+              material: cloneMaterial(sourceMaterial)
+            }
+          };
+        }
+        return next;
+      });
+    },
+    []
+  );
   const resetMaterial = useCallback12(
-    (objectId) => updateObjectBindings(objectId, { style: { material: void 0 } }),
+    (target) => updateObjectBindings(target, { style: { material: void 0 } }),
+    [updateObjectBindings]
+  );
+  const setTransform = useCallback12(
+    (target, transform) => updateObjectBindings(target, { transform }),
+    [updateObjectBindings]
+  );
+  const resetTransform = useCallback12(
+    (target) => updateObjectBindings(target, { transform: void 0 }),
     [updateObjectBindings]
   );
+  const updateMetadata = useCallback12(
+    (target, metadata) => updateObjectBindings(target, { metadata }),
+    [updateObjectBindings]
+  );
+  const selectObjectBindings = useCallback12(
+    (target) => selectBindings(objectBindings, target),
+    [objectBindings]
+  );
+  const selectObjectBindingIds = useCallback12(
+    (target) => selectBindingKeys(objectBindings, target).map(
+      (bindingKey) => objectBindings[bindingKey]?.id ?? bindingKey
+    ),
+    [objectBindings]
+  );
   const getMaterial = useCallback12(
     (objectId) => {
       const bindingKey = resolveBindingKey(objectBindings, objectId);
@@ -18645,27 +19092,28 @@ function useObjectBindings(initialBindings) {
     [objectBindings]
   );
   const hideObject = useCallback12(
-    (objectId) => updateObjectBindings(objectId, { visible: false }),
+    (target) => updateObjectBindings(target, { visible: false }),
     [updateObjectBindings]
   );
   const showObject = useCallback12(
-    (objectId) => updateObjectBindings(objectId, { visible: true }),
+    (target) => updateObjectBindings(target, { visible: true }),
     [updateObjectBindings]
   );
   const toggleObjectVisibility = useCallback12(
-    (objectId) => {
+    (target) => {
       setObjectBindings((current) => {
-        const objectIds = Array.isArray(objectId) ? objectId : [objectId];
-        const edits = objectIds.reduce((acc, id) => {
-          const bindingKey = resolveBindingKey(current, id);
-          const binding = bindingKey ? current[bindingKey] : null;
-          if (!bindingKey || !binding) return acc;
-          acc.push({
-            ids: bindingKey,
-            patch: { visible: binding.visible === false }
-          });
-          return acc;
-        }, []);
+        const edits = selectBindingKeys(current, target).reduce(
+          (acc, bindingKey) => {
+            const binding = current[bindingKey];
+            if (!binding) return acc;
+            acc.push({
+              ids: bindingKey,
+              patch: { visible: binding.visible === false }
+            });
+            return acc;
+          },
+          []
+        );
         return patchBindings(current, edits);
       });
     },
@@ -18699,8 +19147,16 @@ function useObjectBindings(initialBindings) {
     updateObjectBindings,
     setMaterial,
     setBaseColor,
+    setTexture,
+    clearTexture,
+    copyMaterial,
     resetMaterial,
     getMaterial,
+    setTransform,
+    resetTransform,
+    updateMetadata,
+    selectObjectBindings,
+    selectObjectBindingIds,
     hiddenObjects,
     hiddenObjectIds,
     hideObject,
@@ -18711,8 +19167,13 @@ function useObjectBindings(initialBindings) {
   };
 }
 
+// src/utils/defineObjectBindings.ts
+function defineObjectBindings(bindings) {
+  return bindings;
+}
+
 // src/hooks/useSceneConfig.ts
-import { useCallback as useCallback13, useRef as useRef21, useState as useState30 } from "react";
+import { useCallback as useCallback13, useMemo as useMemo22, useRef as useRef21, useState as useState31 } from "react";
 
 // src/utils/patchSceneConfig.ts
 function patchSceneConfig(sceneConfig, patch) {
@@ -18720,9 +19181,21 @@ function patchSceneConfig(sceneConfig, patch) {
 }
 
 // src/hooks/useSceneConfig.ts
+var DEFAULT_LIGHT = {
+  type: "point",
+  color: "#ffffff",
+  intensity: 1,
+  position: [0, 0, 0],
+  distance: 0,
+  decay: 2,
+  attachedToCamera: false,
+  castShadow: false,
+  shadowBias: -5e-4,
+  visible: true
+};
 function useSceneConfig(initialSceneConfig) {
   const initialSceneConfigRef = useRef21(null);
-  const [sceneConfig, setSceneConfig] = useState30(() => {
+  const [sceneConfig, setSceneConfig] = useState31(() => {
     const initial = typeof initialSceneConfig === "function" ? initialSceneConfig() : initialSceneConfig;
     initialSceneConfigRef.current = initial;
     return initial;
@@ -18737,18 +19210,124 @@ function useSceneConfig(initialSceneConfig) {
     const initial = initialSceneConfigRef.current;
     if (initial) setSceneConfig(initial);
   }, []);
+  const updateLight = useCallback13(
+    (id, patch) => {
+      updateSceneConfig((current) => ({
+        lighting: {
+          lights: current.lighting.lights.map(
+            (light) => light.id === id ? { ...light, ...patch } : light
+          )
+        }
+      }));
+    },
+    [updateSceneConfig]
+  );
+  const addLight = useCallback13(
+    (light) => {
+      updateSceneConfig((current) => {
+        if (current.lighting.lights.some((item) => item.id === light.id)) {
+          return {};
+        }
+        return {
+          lighting: {
+            lights: [
+              ...current.lighting.lights,
+              { ...DEFAULT_LIGHT, ...light }
+            ]
+          }
+        };
+      });
+    },
+    [updateSceneConfig]
+  );
+  const removeLight = useCallback13(
+    (id) => {
+      updateSceneConfig((current) => ({
+        lighting: {
+          lights: current.lighting.lights.filter((light) => light.id !== id)
+        }
+      }));
+    },
+    [updateSceneConfig]
+  );
+  const setLightIntensity = useCallback13(
+    (id, intensity) => updateLight(id, { intensity }),
+    [updateLight]
+  );
+  const setLightColor = useCallback13(
+    (id, color) => updateLight(id, { color }),
+    [updateLight]
+  );
+  const showLight = useCallback13(
+    (id) => updateLight(id, { visible: true }),
+    [updateLight]
+  );
+  const hideLight = useCallback13(
+    (id) => updateLight(id, { visible: false }),
+    [updateLight]
+  );
+  const toggleLight = useCallback13(
+    (id) => {
+      updateSceneConfig((current) => ({
+        lighting: {
+          lights: current.lighting.lights.map(
+            (light) => light.id === id ? { ...light, visible: !light.visible } : light
+          )
+        }
+      }));
+    },
+    [updateSceneConfig]
+  );
+  const attachLight = useCallback13(
+    (id, attachment) => updateLight(id, { attachment, attachedToCamera: false }),
+    [updateLight]
+  );
+  const detachLight = useCallback13(
+    (id) => updateLight(id, { attachment: void 0 }),
+    [updateLight]
+  );
+  const lights = useMemo22(
+    () => ({
+      items: sceneConfig.lighting.lights,
+      get: (id) => sceneConfig.lighting.lights.find((light) => light.id === id),
+      add: addLight,
+      update: updateLight,
+      remove: removeLight,
+      setIntensity: setLightIntensity,
+      setColor: setLightColor,
+      show: showLight,
+      hide: hideLight,
+      toggle: toggleLight,
+      attach: attachLight,
+      detach: detachLight
+    }),
+    [
+      sceneConfig.lighting.lights,
+      addLight,
+      updateLight,
+      removeLight,
+      setLightIntensity,
+      setLightColor,
+      showLight,
+      hideLight,
+      toggleLight,
+      attachLight,
+      detachLight
+    ]
+  );
   return {
     sceneConfig,
     setSceneConfig,
     updateSceneConfig,
-    resetSceneConfig
+    resetSceneConfig,
+    lights
   };
 }
 
 // src/hooks/useViewerHover.ts
-import { useCallback as useCallback14, useState as useState31 } from "react";
+import { useCallback as useCallback14, useState as useState32 } from "react";
 function useViewerHover() {
-  const [hoveredObjectBinding, setHoveredObjectBinding] = useState31(null);
+  const [hoveredObjectBinding, setHoveredObjectBinding] = useState32(null);
   const handleHoveredObject = useCallback14(
     (binding) => {
       setHoveredObjectBinding(binding);
@@ -18762,23 +19341,23 @@ function useViewerHover() {
 }
 
 // src/hooks/useViewerModel.ts
-import { useCallback as useCallback15, useState as useState32 } from "react";
-import { Box3 as Box36, Vector3 as Vector311 } from "three";
+import { useCallback as useCallback15, useState as useState33 } from "react";
+import { Box3 as Box36, Vector3 as Vector312 } from "three";
 function toTuple2(vector) {
   return [vector.x, vector.y, vector.z];
 }
 function useViewerModel() {
-  const [isLoading, setIsLoading] = useState32(true);
-  const [isReady, setIsReady] = useState32(false);
-  const [error, setError] = useState32(null);
-  const [bounds, setBounds] = useState32(null);
-  const [objectCount, setObjectCount] = useState32(0);
+  const [isLoading, setIsLoading] = useState33(true);
+  const [isReady, setIsReady] = useState33(false);
+  const [error, setError] = useState33(null);
+  const [bounds, setBounds] = useState33(null);
+  const [objectCount, setObjectCount] = useState33(0);
   const handleModelLoaded = useCallback15((scene) => {
     const box = new Box36().setFromObject(scene);
     const min = box.min.clone();
     const max = box.max.clone();
-    const center = new Vector311();
-    const size = new Vector311();
+    const center = new Vector312();
+    const size = new Vector312();
     let nextObjectCount = 0;
     scene.traverse((child) => {
       if ("isMesh" in child && child.isMesh) {
@@ -18826,61 +19405,777 @@ function useViewerModel() {
 
 // src/hooks/useViewerActions.ts
 import { useCallback as useCallback16 } from "react";
-function useViewerActions(objectBindings, options = {}) {
-  const { onAction, onObjectBindingsChange } = options;
+function useViewerActions({
+  bindings,
+  scene,
+  camera,
+  animations,
+  onAction
+}) {
+  const {
+    objectBindings,
+    updateObjectBindings,
+    showObject,
+    hideObject,
+    toggleObjectVisibility
+  } = bindings;
+  const updateSceneConfig = scene?.updateSceneConfig;
+  const focusObject = camera?.focusObject;
+  const fitScene = camera?.fitScene;
+  const resetView = camera?.resetView;
+  const setCameraTarget = camera?.setCameraTarget;
+  const setCameraState = camera?.setCameraState;
+  const playAnimation = animations?.play;
+  const pauseAnimation = animations?.pause;
+  const stopAnimation = animations?.stop;
+  const setAnimationSpeed = animations?.setSpeed;
+  const seekAnimation = animations?.seek;
   const getActionsForObject = useCallback16(
     (objectId) => {
       const bindingKey = resolveBindingKey(objectBindings, objectId);
-      if (!bindingKey) {
-        return [];
-      }
-      return objectBindings[bindingKey]?.actions ?? [];
+      return bindingKey ? objectBindings[bindingKey]?.actions ?? [] : [];
     },
     [objectBindings]
   );
+  const handleAction = useCallback16(
+    async (event) => {
+      for (const effect of event.action.effects ?? []) {
+        if ("objectBindings" in effect) {
+          updateObjectBindings(effect.target, effect.objectBindings);
+          continue;
+        }
+        if ("sceneConfig" in effect) {
+          updateSceneConfig?.(effect.sceneConfig);
+          continue;
+        }
+        if ("visibility" in effect) {
+          if (effect.visibility === "show") showObject(effect.target);
+          else if (effect.visibility === "hide") hideObject(effect.target);
+          else toggleObjectVisibility(effect.target);
+          continue;
+        }
+        if ("camera" in effect) {
+          const action2 = effect.camera;
+          if (action2.type === "focus-object") {
+            await focusObject?.(action2.objectId ?? event.objectId);
+          } else if (action2.type === "fit-scene") {
+            await fitScene?.();
+          } else if (action2.type === "reset") {
+            await resetView?.();
+          } else if (action2.type === "set-target") {
+            await setCameraTarget?.(action2.target, action2.transition ?? true);
+          } else {
+            await setCameraState?.(action2.state, action2.transition ?? true);
+          }
+          continue;
+        }
+        const action = effect.animation;
+        if (action.type === "play") playAnimation?.(action.clip);
+        else if (action.type === "pause") pauseAnimation?.();
+        else if (action.type === "stop") stopAnimation?.();
+        else if (action.type === "set-speed") {
+          setAnimationSpeed?.(action.speed);
+        } else {
+          seekAnimation?.(action.time);
+        }
+      }
+      await onAction?.(event);
+    },
+    [
+      fitScene,
+      focusObject,
+      hideObject,
+      onAction,
+      pauseAnimation,
+      playAnimation,
+      resetView,
+      seekAnimation,
+      setAnimationSpeed,
+      setCameraState,
+      setCameraTarget,
+      showObject,
+      stopAnimation,
+      toggleObjectVisibility,
+      updateObjectBindings,
+      updateSceneConfig
+    ]
+  );
   const runAction = useCallback16(
-    (objectId, actionId) => {
+    async (objectId, actionId) => {
       const bindingKey = resolveBindingKey(objectBindings, objectId);
-      if (!bindingKey) {
-        return null;
-      }
+      if (!bindingKey) return null;
       const binding = objectBindings[bindingKey];
-      if (!binding) {
-        return null;
-      }
-      const action = (binding.actions ?? []).find(
-        (entry) => entry.id === actionId
-      );
-      if (!action) {
-        return null;
-      }
+      const action = binding?.actions?.find((entry) => entry.id === actionId);
+      if (!binding || !action) return null;
       const event = {
         objectId: bindingKey,
         action,
         binding
       };
-      if (action.id === "toggle-visibility" && onObjectBindingsChange) {
-        onObjectBindingsChange({
-          ...objectBindings,
-          [bindingKey]: {
-            ...binding,
-            visible: binding.visible === false
-          }
-        });
-      }
-      onAction?.(event);
+      await handleAction(event);
       return event;
     },
-    [objectBindings, onAction, onObjectBindingsChange]
+    [handleAction, objectBindings]
   );
   return {
     getActionsForObject,
+    handleAction,
     runAction
   };
 }
 
+// src/hooks/useViewerConnection.ts
+import { useCallback as useCallback17, useRef as useRef22 } from "react";
+function getReadyHandler(consumer) {
+  if (typeof consumer === "function") {
+    return consumer;
+  }
+  return consumer?.handleViewerReady ?? null;
+}
+function useViewerConnection(...consumers) {
+  const viewerRef = useRef22(null);
+  const consumersRef = useRef22(consumers);
+  consumersRef.current = consumers;
+  const handleViewerReady = useCallback17((viewer) => {
+    viewerRef.current = viewer;
+    const invoked = /* @__PURE__ */ new Set();
+    for (const consumer of consumersRef.current) {
+      const handler = getReadyHandler(consumer);
+      if (handler && !invoked.has(handler)) {
+        invoked.add(handler);
+        handler(viewer);
+      }
+    }
+  }, []);
+  const getViewer = useCallback17(() => viewerRef.current, []);
+  const captureImage2 = useCallback17((options) => {
+    const viewer = viewerRef.current;
+    if (!viewer) {
+      return Promise.reject(new Error("ModelViewer is not ready yet."));
+    }
+    return viewer.captureImage(options);
+  }, []);
+  const invalidate = useCallback17(() => {
+    const viewer = viewerRef.current;
+    if (!viewer) {
+      return false;
+    }
+    viewer.invalidate();
+    return true;
+  }, []);
+  return {
+    handleViewerReady,
+    getViewer,
+    captureImage: captureImage2,
+    invalidate
+  };
+}
+
+// src/hooks/useViewerEffects.ts
+import { useCallback as useCallback18, useEffect as useEffect25, useRef as useRef23 } from "react";
+import {
+  Material as Material3,
+  PointLight,
+  Vector3 as Vector313
+} from "three";
+var NUMERIC_MATERIAL_KEYS = [
+  "emissiveIntensity",
+  "opacity",
+  "metalness",
+  "roughness",
+  "transmission",
+  "clearcoat",
+  "clearcoatRoughness",
+  "ior",
+  "thickness"
+];
+var nextEffectId = 1;
+function stringList(target) {
+  return typeof target === "string" ? [target] : target;
+}
+function clamp2(value, min = 0, max = 1) {
+  return Math.min(max, Math.max(min, value));
+}
+function randomBetween(min, max) {
+  return min + Math.random() * (max - min);
+}
+function interpolate([from, to], level) {
+  return from + (to - from) * level;
+}
+function interpolateVector([from, to], level) {
+  return [
+    from[0] + (to[0] - from[0]) * level,
+    from[1] + (to[1] - from[1]) * level,
+    from[2] + (to[2] - from[2]) * level
+  ];
+}
+function ease(value, easing) {
+  const t = clamp2(value);
+  switch (easing) {
+    case "ease-in":
+      return t * t;
+    case "ease-out":
+      return 1 - (1 - t) * (1 - t);
+    case "ease-in-out":
+      return t < 0.5 ? 2 * t * t : 1 - Math.pow(-2 * t + 2, 2) / 2;
+    default:
+      return t;
+  }
+}
+function materialList(node) {
+  const value = node.material;
+  if (!value) return [];
+  return (Array.isArray(value) ? value : [value]).filter(
+    (entry) => entry instanceof Material3
+  );
+}
+function readMaterial(material2) {
+  const snapshot = {
+    opacity: material2.opacity,
+    transparent: material2.transparent
+  };
+  if (material2.color) snapshot.baseColor = `#${material2.color.getHexString()}`;
+  if (material2.emissive) snapshot.emissive = `#${material2.emissive.getHexString()}`;
+  for (const key of NUMERIC_MATERIAL_KEYS) {
+    const value = material2[key];
+    if (typeof value === "number") snapshot[key] = value;
+  }
+  return snapshot;
+}
+function applyMaterial(material2, patch) {
+  if (patch.baseColor !== void 0 && material2.color) {
+    material2.color.set(patch.baseColor);
+  }
+  if (patch.emissive !== void 0 && material2.emissive) {
+    material2.emissive.set(patch.emissive);
+  }
+  for (const key of NUMERIC_MATERIAL_KEYS) {
+    const value = patch[key];
+    if (value !== void 0 && typeof material2[key] === "number") {
+      material2[key] = value;
+    }
+  }
+  if (patch.transparent !== void 0) material2.transparent = patch.transparent;
+  material2.needsUpdate = true;
+}
+function readTransform(node) {
+  return {
+    position: [node.position.x, node.position.y, node.position.z],
+    rotation: [node.rotation.x, node.rotation.y, node.rotation.z],
+    scale: [node.scale.x, node.scale.y, node.scale.z],
+    visible: node.visible
+  };
+}
+function applyTransform(node, patch) {
+  if (patch.position) node.position.set(...patch.position);
+  if (patch.rotation) node.rotation.set(...patch.rotation);
+  if (patch.scale !== void 0) {
+    const scale = typeof patch.scale === "number" ? [patch.scale, patch.scale, patch.scale] : patch.scale;
+    node.scale.set(...scale);
+  }
+  if (patch.visible !== void 0) node.visible = patch.visible;
+  node.updateMatrix();
+  node.updateMatrixWorld(true);
+}
+function useViewerEffects(options = {}) {
+  const optionsRef = useRef23(options);
+  optionsRef.current = options;
+  const viewerRef = useRef23(null);
+  const sceneRef = useRef23(null);
+  const frameRef = useRef23(null);
+  const effectsRef = useRef23(/* @__PURE__ */ new Map());
+  const lightsRef = useRef23(/* @__PURE__ */ new Map());
+  const materialSnapshotsRef = useRef23(
+    /* @__PURE__ */ new Map()
+  );
+  const transformSnapshotsRef = useRef23(/* @__PURE__ */ new Map());
+  const resolveObject = useCallback18((target) => {
+    const viewer = viewerRef.current;
+    if (!viewer) return null;
+    const bindingKey = resolveBindingKey(viewer.objectBindings, target);
+    return viewer.nodeRefs[target] ?? (bindingKey ? viewer.nodeRefs[bindingKey] : null) ?? viewer.scene?.getObjectByName(target) ?? null;
+  }, []);
+  const resolveTargets = useCallback18(
+    (target) => {
+      const viewer = viewerRef.current;
+      if (!viewer) {
+        return typeof target === "string" ? [target] : Array.isArray(target) ? target : [];
+      }
+      if (typeof target === "object" && !Array.isArray(target)) {
+        return selectBindingKeys(viewer.objectBindings, target);
+      }
+      return stringList(target).map(
+        (id) => resolveBindingKey(viewer.objectBindings, id) ?? id
+      );
+    },
+    []
+  );
+  const invalidate = useCallback18(() => {
+    viewerRef.current?.invalidate();
+  }, []);
+  const setMaterialInternal = useCallback18(
+    (target, patch) => {
+      let changed = false;
+      for (const id of resolveTargets(target)) {
+        const node = resolveObject(id);
+        if (!node) continue;
+        for (const entry of materialList(node)) {
+          if (!materialSnapshotsRef.current.has(entry)) {
+            materialSnapshotsRef.current.set(entry, readMaterial(entry));
+          }
+          applyMaterial(entry, patch);
+          changed = true;
+        }
+      }
+      return changed;
+    },
+    [resolveObject, resolveTargets]
+  );
+  const setMaterial = useCallback18(
+    (target, patch) => {
+      const changed = setMaterialInternal(target, patch);
+      if (changed) invalidate();
+      return changed;
+    },
+    [invalidate, setMaterialInternal]
+  );
+  const setTransformInternal = useCallback18(
+    (target, patch) => {
+      let changed = false;
+      for (const id of resolveTargets(target)) {
+        const node = resolveObject(id);
+        if (!node) continue;
+        if (!transformSnapshotsRef.current.has(node)) {
+          transformSnapshotsRef.current.set(node, readTransform(node));
+        }
+        applyTransform(node, patch);
+        changed = true;
+      }
+      return changed;
+    },
+    [resolveObject, resolveTargets]
+  );
+  const setTransform = useCallback18(
+    (target, patch) => {
+      const changed = setTransformInternal(target, patch);
+      if (changed) invalidate();
+      return changed;
+    },
+    [invalidate, setTransformInternal]
+  );
+  const getWorldPosition = useCallback18(
+    (target) => {
+      const node = resolveObject(target);
+      if (!node) return null;
+      node.updateWorldMatrix(true, false);
+      const position = node.getWorldPosition(new Vector313());
+      return [position.x, position.y, position.z];
+    },
+    [resolveObject]
+  );
+  const removePointLight = useCallback18(
+    (id) => {
+      const runtime = lightsRef.current.get(id);
+      if (!runtime) return false;
+      runtime.light.removeFromParent();
+      runtime.light.dispose();
+      lightsRef.current.delete(id);
+      invalidate();
+      return true;
+    },
+    [invalidate]
+  );
+  const addPointLight = useCallback18(
+    (lightOptions) => {
+      const target = resolveObject(lightOptions.target);
+      if (!target) return false;
+      const existing = lightsRef.current.get(lightOptions.id);
+      const light = existing?.light ?? new PointLight();
+      if (existing && existing.target !== lightOptions.target) {
+        light.removeFromParent();
+      }
+      light.name = `react-immersive-runtime-light:${lightOptions.id}`;
+      light.color.set(lightOptions.color ?? "#ffffff");
+      light.intensity = lightOptions.intensity ?? 1;
+      light.distance = lightOptions.distance ?? 0;
+      light.decay = lightOptions.decay ?? 2;
+      light.castShadow = lightOptions.castShadow ?? false;
+      light.position.set(...lightOptions.offset ?? [0, 0, 0]);
+      if (light.parent !== target) target.add(light);
+      lightsRef.current.set(lightOptions.id, {
+        light,
+        target: lightOptions.target
+      });
+      invalidate();
+      return true;
+    },
+    [invalidate, resolveObject]
+  );
+  const updatePointLight = useCallback18(
+    (id, patch) => {
+      const runtime = lightsRef.current.get(id);
+      if (!runtime) return false;
+      if (patch.target && patch.target !== runtime.target) {
+        const target = resolveObject(patch.target);
+        if (!target) return false;
+        runtime.light.removeFromParent();
+        target.add(runtime.light);
+        runtime.target = patch.target;
+      }
+      if (patch.color !== void 0) runtime.light.color.set(patch.color);
+      if (patch.intensity !== void 0) {
+        runtime.light.intensity = patch.intensity;
+      }
+      if (patch.distance !== void 0) runtime.light.distance = patch.distance;
+      if (patch.decay !== void 0) runtime.light.decay = patch.decay;
+      if (patch.offset !== void 0) {
+        runtime.light.position.set(...patch.offset);
+      }
+      if (patch.castShadow !== void 0) {
+        runtime.light.castShadow = patch.castShadow;
+      }
+      invalidate();
+      return true;
+    },
+    [invalidate, resolveObject]
+  );
+  const applyChannels = useCallback18(
+    (channels, levels) => {
+      const levelFor = (index) => levels[index % levels.length] ?? 0;
+      for (const channel of channels.materials ?? []) {
+        resolveTargets(channel.targets).forEach((target, index) => {
+          const level = levelFor(index);
+          const patch = {};
+          for (const key of NUMERIC_MATERIAL_KEYS) {
+            const range = channel.values[key];
+            if (range) patch[key] = interpolate(range, level);
+          }
+          setMaterialInternal(target, patch);
+        });
+      }
+      for (const channel of channels.transforms ?? []) {
+        resolveTargets(channel.targets).forEach((target, index) => {
+          const level = levelFor(index);
+          const patch = {};
+          if (channel.values.position) {
+            patch.position = interpolateVector(channel.values.position, level);
+          }
+          if (channel.values.rotation) {
+            patch.rotation = interpolateVector(channel.values.rotation, level);
+          }
+          if (channel.values.scale) {
+            patch.scale = interpolateVector(channel.values.scale, level);
+          }
+          setTransformInternal(target, patch);
+        });
+      }
+      for (const channel of channels.lights ?? []) {
+        stringList(channel.lights).forEach((id, index) => {
+          const runtime = lightsRef.current.get(id);
+          if (runtime) {
+            runtime.light.intensity = interpolate(
+              channel.intensity,
+              levelFor(index)
+            );
+          }
+        });
+      }
+    },
+    [resolveTargets, setMaterialInternal, setTransformInternal]
+  );
+  const scheduleFrameRef = useRef23(() => void 0);
+  const runFrameRef = useRef23(() => void 0);
+  runFrameRef.current = (now) => {
+    frameRef.current = null;
+    let rendered = false;
+    for (const [id, effect] of effectsRef.current) {
+      if (effect.startedAt === null) effect.startedAt = now;
+      const previous = effect.lastFrameAt ?? now;
+      effect.lastFrameAt = now;
+      const override = effect.override && effect.override.until > now ? effect.override.level : null;
+      if (effect.override && override === null) effect.override = null;
+      const keepRunning = effect.update(
+        now,
+        now - effect.startedAt,
+        Math.min(100, now - previous),
+        override
+      );
+      rendered = true;
+      if (!keepRunning) {
+        effectsRef.current.delete(id);
+        effect.onComplete?.();
+      }
+    }
+    if (rendered) invalidate();
+    if (effectsRef.current.size > 0) scheduleFrameRef.current();
+  };
+  scheduleFrameRef.current = () => {
+    if (frameRef.current !== null || typeof requestAnimationFrame === "undefined") {
+      return;
+    }
+    frameRef.current = requestAnimationFrame((now) => runFrameRef.current(now));
+  };
+  const registerEffect = useCallback18((effect) => {
+    effectsRef.current.set(effect.id, effect);
+    scheduleFrameRef.current();
+    return effect.id;
+  }, []);
+  const transition = useCallback18(
+    (channels, transitionOptions = {}) => {
+      const id = transitionOptions.id ?? `transition-${nextEffectId++}`;
+      const duration = Math.max(1, transitionOptions.duration ?? 400);
+      const easing = transitionOptions.easing ?? "ease-in-out";
+      return registerEffect({
+        id,
+        startedAt: null,
+        lastFrameAt: null,
+        override: null,
+        onComplete: transitionOptions.onComplete,
+        update: (_now, elapsed, _delta, override) => {
+          const progress = override ?? ease(elapsed / duration, easing);
+          applyChannels(channels, [progress]);
+          return elapsed < duration;
+        }
+      });
+    },
+    [applyChannels, registerEffect]
+  );
+  const pulse = useCallback18(
+    (channels, pulseOptions = {}) => {
+      const id = pulseOptions.id ?? `pulse-${nextEffectId++}`;
+      const duration = Math.max(1, pulseOptions.duration ?? 1e3);
+      const minLevel = pulseOptions.minLevel ?? 0;
+      const maxLevel = pulseOptions.maxLevel ?? 1;
+      const repeat = pulseOptions.repeat ?? Infinity;
+      const synchronized = pulseOptions.synchronized ?? true;
+      const unitCount = Math.max(
+        1,
+        ...[...channels.materials ?? [], ...channels.transforms ?? []].map(
+          (channel) => resolveTargets(channel.targets).length
+        ),
+        ...(channels.lights ?? []).map(
+          (channel) => stringList(channel.lights).length
+        )
+      );
+      return registerEffect({
+        id,
+        startedAt: null,
+        lastFrameAt: null,
+        override: null,
+        onComplete: pulseOptions.onComplete,
+        update: (_now, elapsed, _delta, override) => {
+          const cycles = elapsed / duration;
+          const levels = Array.from(
+            { length: synchronized ? 1 : unitCount },
+            (_, index) => {
+              if (override !== null) return override;
+              const phase = cycles + (synchronized ? 0 : index / unitCount);
+              const wave = 0.5 - Math.cos(phase % 1 * Math.PI * 2) / 2;
+              return minLevel + (maxLevel - minLevel) * wave;
+            }
+          );
+          applyChannels(channels, levels);
+          return repeat === Infinity || cycles < repeat;
+        }
+      });
+    },
+    [applyChannels, registerEffect, resolveTargets]
+  );
+  const timeline = useCallback18(
+    (steps, timelineOptions = {}) => {
+      const id = timelineOptions.id ?? `timeline-${nextEffectId++}`;
+      const repeat = timelineOptions.repeat ?? 1;
+      const normalizedSteps = steps.map((step) => ({
+        ...step,
+        duration: Math.max(1, step.duration),
+        hold: Math.max(0, step.hold ?? 0)
+      }));
+      const cycleDuration = Math.max(
+        1,
+        normalizedSteps.reduce(
+          (total, step) => total + step.duration + step.hold,
+          0
+        )
+      );
+      return registerEffect({
+        id,
+        startedAt: null,
+        lastFrameAt: null,
+        override: null,
+        onComplete: timelineOptions.onComplete,
+        update: (_now, elapsed, _delta, override) => {
+          if (normalizedSteps.length === 0 || repeat <= 0) return false;
+          const cycles = elapsed / cycleDuration;
+          if (repeat !== Infinity && cycles >= repeat) {
+            for (const step of normalizedSteps) {
+              applyChannels(step.channels, [1]);
+            }
+            return false;
+          }
+          const cycleTime = elapsed % cycleDuration;
+          let cursor = 0;
+          for (const step of normalizedSteps) {
+            const transitionEnd = cursor + step.duration;
+            const stepEnd = transitionEnd + step.hold;
+            if (cycleTime >= transitionEnd) {
+              applyChannels(step.channels, [override ?? 1]);
+              cursor = stepEnd;
+              continue;
+            }
+            if (cycleTime >= cursor) {
+              const progress = override ?? ease(
+                (cycleTime - cursor) / step.duration,
+                step.easing ?? "ease-in-out"
+              );
+              applyChannels(step.channels, [progress]);
+              break;
+            }
+          }
+          return true;
+        }
+      });
+    },
+    [applyChannels, registerEffect]
+  );
+  const flicker = useCallback18(
+    (channels, flickerOptions = {}) => {
+      const id = flickerOptions.id ?? `flicker-${nextEffectId++}`;
+      const synchronized = flickerOptions.synchronized ?? true;
+      const minLevel = flickerOptions.minLevel ?? 0.15;
+      const maxLevel = flickerOptions.maxLevel ?? 1;
+      const interval = flickerOptions.interval ?? [45, 160];
+      const rawIntervalRange = typeof interval === "number" ? [interval, interval] : interval;
+      const intervalRange = [
+        Math.max(1, Math.min(...rawIntervalRange)),
+        Math.max(1, Math.max(...rawIntervalRange))
+      ];
+      const response = clamp2(flickerOptions.response ?? 0.7, 0.01, 1);
+      const blackoutChance = clamp2(flickerOptions.blackoutChance ?? 0.08);
+      const flashChance = clamp2(flickerOptions.flashChance ?? 0.12);
+      const flashLevel = flickerOptions.flashLevel ?? 1.15;
+      const unitCount = Math.max(
+        1,
+        ...[...channels.materials ?? [], ...channels.transforms ?? []].map(
+          (channel) => resolveTargets(channel.targets).length
+        ),
+        ...(channels.lights ?? []).map(
+          (channel) => stringList(channel.lights).length
+        )
+      );
+      const count = synchronized ? 1 : unitCount;
+      const levels = Array.from({ length: count }, () => minLevel);
+      const targets = Array.from({ length: count }, () => minLevel);
+      const nextChanges = Array.from({ length: count }, () => 0);
+      return registerEffect({
+        id,
+        startedAt: null,
+        lastFrameAt: null,
+        override: null,
+        onComplete: flickerOptions.onComplete,
+        update: (now, elapsed, delta, override) => {
+          for (let index = 0; index < count; index += 1) {
+            if (override !== null) {
+              targets[index] = override;
+            } else if (now >= nextChanges[index]) {
+              const roll = Math.random();
+              targets[index] = roll < blackoutChance ? randomBetween(0, Math.min(0.04, minLevel)) : roll < blackoutChance + flashChance ? flashLevel : randomBetween(minLevel, maxLevel);
+              nextChanges[index] = now + randomBetween(...intervalRange);
+            }
+            const frameResponse = 1 - Math.pow(1 - response, Math.max(1, delta) / 16.67);
+            levels[index] += (targets[index] - levels[index]) * frameResponse;
+          }
+          applyChannels(channels, levels);
+          return flickerOptions.duration === void 0 || elapsed < flickerOptions.duration;
+        }
+      });
+    },
+    [applyChannels, registerEffect, resolveTargets]
+  );
+  const overrideEffect = useCallback18(
+    (id, level, duration) => {
+      const effect = effectsRef.current.get(id);
+      if (!effect) return false;
+      const now = typeof performance === "undefined" ? Date.now() : performance.now();
+      effect.override = { level, until: now + Math.max(0, duration) };
+      scheduleFrameRef.current();
+      return true;
+    },
+    []
+  );
+  const stopEffect = useCallback18((id) => {
+    return effectsRef.current.delete(id);
+  }, []);
+  const stopAllEffects = useCallback18(() => {
+    effectsRef.current.clear();
+    if (frameRef.current !== null && typeof cancelAnimationFrame !== "undefined") {
+      cancelAnimationFrame(frameRef.current);
+      frameRef.current = null;
+    }
+  }, []);
+  const restoreRuntimeValues = useCallback18(() => {
+    for (const [entry, snapshot] of materialSnapshotsRef.current) {
+      applyMaterial(entry, snapshot);
+    }
+    materialSnapshotsRef.current.clear();
+    for (const [node, snapshot] of transformSnapshotsRef.current) {
+      node.position.set(...snapshot.position);
+      node.rotation.set(...snapshot.rotation);
+      node.scale.set(...snapshot.scale);
+      node.visible = snapshot.visible;
+      node.updateMatrix();
+      node.updateMatrixWorld(true);
+    }
+    transformSnapshotsRef.current.clear();
+    for (const runtime of lightsRef.current.values()) {
+      runtime.light.removeFromParent();
+      runtime.light.dispose();
+    }
+    lightsRef.current.clear();
+    invalidate();
+  }, [invalidate]);
+  const resetRuntime = useCallback18(() => {
+    stopAllEffects();
+    restoreRuntimeValues();
+  }, [restoreRuntimeValues, stopAllEffects]);
+  const handleViewerReady = useCallback18(
+    (viewer) => {
+      if (sceneRef.current && sceneRef.current !== viewer.scene) {
+        restoreRuntimeValues();
+      }
+      viewerRef.current = viewer;
+      sceneRef.current = viewer.scene;
+      optionsRef.current.onViewerReady?.(viewer);
+    },
+    [restoreRuntimeValues]
+  );
+  useEffect25(() => {
+    return () => {
+      resetRuntime();
+      viewerRef.current = null;
+      sceneRef.current = null;
+    };
+  }, [resetRuntime]);
+  return {
+    handleViewerReady,
+    setMaterial,
+    setTransform,
+    getWorldPosition,
+    addPointLight,
+    updatePointLight,
+    removePointLight,
+    transition,
+    timeline,
+    pulse,
+    flicker,
+    overrideEffect,
+    stopEffect,
+    stopAllEffects,
+    resetRuntime
+  };
+}
+
 // src/hooks/useShareableViewerState.ts
-import { useCallback as useCallback17, useEffect as useEffect24, useRef as useRef22, useState as useState33 } from "react";
+import { useCallback as useCallback19, useEffect as useEffect26, useRef as useRef24, useState as useState34 } from "react";
 function serializeState(cameraState, objectBindings, selectedObjectBinding) {
   const hidden = Object.values(objectBindings).filter((binding) => binding.visible === false).map((binding) => binding.id);
   return {
@@ -18900,8 +20195,8 @@ function useShareableViewerState({
   debounceMs = 400,
   autoSync = true
 }) {
-  const lastWrittenRawRef = useRef22(null);
-  const buildHash = useCallback17(() => {
+  const lastWrittenRawRef = useRef24(null);
+  const buildHash = useCallback19(() => {
     const state = serializeState(
       cameraState,
       objectBindings,
@@ -18909,12 +20204,12 @@ function useShareableViewerState({
     );
     return `${paramKey}=${encodeURIComponent(JSON.stringify(state))}`;
   }, [cameraState, objectBindings, selectedObjectBinding, paramKey]);
-  const getShareUrl = useCallback17(() => {
+  const getShareUrl = useCallback19(() => {
     const url = new URL(window.location.href);
     url.hash = buildHash();
     return url.toString();
   }, [buildHash]);
-  const syncUrl = useCallback17(() => {
+  const syncUrl = useCallback19(() => {
     const url = new URL(window.location.href);
     url.hash = buildHash();
     window.history.replaceState(null, "", url.toString());
@@ -18922,7 +20217,7 @@ function useShareableViewerState({
       paramKey
     );
   }, [buildHash, paramKey]);
-  const latestStateRef = useRef22({
+  const latestStateRef = useRef24({
     cameraState,
     objectBindings,
     selectedObjectBinding
@@ -18932,9 +20227,9 @@ function useShareableViewerState({
     objectBindings,
     selectedObjectBinding
   };
-  const [restoreAttempted, setRestoreAttempted] = useState33(false);
-  const lastSyncedHashRef = useRef22(null);
-  useEffect24(() => {
+  const [restoreAttempted, setRestoreAttempted] = useState34(false);
+  const lastSyncedHashRef = useRef24(null);
+  useEffect26(() => {
     if (!autoSync || !restoreAttempted) return;
     const tick = () => {
       const current = latestStateRef.current;
@@ -18956,9 +20251,9 @@ function useShareableViewerState({
     const id = window.setInterval(tick, debounceMs);
     return () => window.clearInterval(id);
   }, [autoSync, restoreAttempted, debounceMs, paramKey]);
-  const lastRestoredRawRef = useRef22(null);
-  const restoringRawRef = useRef22(null);
-  const restoreFromUrl = useCallback17(async () => {
+  const lastRestoredRawRef = useRef24(null);
+  const restoringRawRef = useRef24(null);
+  const restoreFromUrl = useCallback19(async () => {
     setRestoreAttempted(true);
     const rawHash = window.location.hash.startsWith("#") ? window.location.hash.slice(1) : window.location.hash;
     const raw = new URLSearchParams(rawHash).get(paramKey);
@@ -19011,7 +20306,7 @@ function useShareableViewerState({
     setCameraState,
     setSelectedObjectBinding
   ]);
-  useEffect24(() => {
+  useEffect26(() => {
     const handleHashChange = () => {
       void restoreFromUrl();
     };
@@ -19024,13 +20319,17 @@ function useShareableViewerState({
 }
 export {
   BindingBuilder,
+  DEFAULT_SCENE_CONFIG,
   MATERIAL_BLENDING_MODES,
   MATERIAL_SIDES,
   ModelViewer,
   SimpleModelViewer,
+  defineObjectBindings,
   material,
   patchBindings,
   patchSceneConfig,
+  selectBindingKeys,
+  selectBindings,
   useObjectBinding,
   useObjectBindingIds,
   useObjectBindings,
@@ -19039,6 +20338,8 @@ export {
   useViewerActions,
   useViewerAnimations,
   useViewerCamera,
+  useViewerConnection,
+  useViewerEffects,
   useViewerHover,
   useViewerModel,
   useViewerSelection