@liveroom-tech/react-immersive 2.2.0 → 3.0.0

package/dist/index.d.mts

@@ -8,13 +8,25 @@ import { PresetsType } from '@react-three/drei/helpers/environment-assets';
 
 declare const LIGHT_TYPES: readonly ["none", "directional", "point", "hemisphere"];
 type SceneLightType = (typeof LIGHT_TYPES)[number];
+type SceneLightAttachment = {
+    /** Binding key, binding id, modelObjectId, or raw model node name. */
+    objectId: string;
+    /** Local-space offset from the attached model object. */
+    offset: [number, number, number];
+};
 type SceneLight = {
     id: string;
     type: SceneLightType;
     color: string;
     intensity: number;
     position: [number, number, number];
+    /** Point-light range. Zero means no distance limit. */
+    distance?: number;
+    /** Point-light physically correct decay. */
+    decay?: number;
     attachedToCamera: boolean;
+    /** Follow a model object instead of using the world-space position. */
+    attachment?: SceneLightAttachment;
     castShadow: boolean;
     shadowBias: number;
     visible: boolean;
@@ -322,6 +334,7 @@ type SceneConfig = {
     annotations: SceneAnnotationMarker[];
     cinematic?: SceneCinematicConfig;
 };
+declare const DEFAULT_SCENE_CONFIG: SceneConfig;
 
 type CanvasCamera = ComponentProps<typeof Canvas>["camera"];
 
@@ -368,16 +381,183 @@ type CinematicConfig = {
 
 type MouseControllerPosition = 'bottom-left' | 'bottom-right' | 'top-left' | 'top-right' | 'center' | 'center-bottom' | 'center-top';
 
+type CaptureImageOptions = {
+    width?: number;
+    height?: number;
+    transparent?: boolean;
+};
+
+type ViewerCameraState = {
+    position: [number, number, number];
+    target: [number, number, number];
+    fov: number | null;
+    zoom: number;
+    azimuthAngle?: number;
+    polarAngle?: number;
+};
+type ViewerCameraPreset = {
+    position: [number, number, number];
+    target: [number, number, number];
+    fov?: number | null;
+    zoom?: number;
+    azimuthAngle?: number;
+    polarAngle?: number;
+};
+type UseViewerCameraOptions = {
+    /** Camera position applied once when each model becomes ready. */
+    initialPosition?: [number, number, number];
+    /** Orbit target applied once when each model becomes ready. */
+    initialTarget?: [number, number, number];
+    /** Whether the initial position/target should animate. Defaults to false. */
+    initialTransition?: boolean;
+    /** Named views that can be opened with goToPreset. */
+    presets?: Record<string, ViewerCameraPreset>;
+};
+type HomeCameraState = {
+    position: [number, number, number];
+    target: [number, number, number];
+};
+type ViewerReadyState = {
+    controls: CameraControls;
+    scene: Object3D | null;
+    objectBindings: Record<string, ObjectBinding>;
+    nodeRefs: Record<string, Object3D>;
+    homeCameraState: HomeCameraState | null;
+    captureImage: (options?: CaptureImageOptions) => Promise<string>;
+    invalidate: () => void;
+};
+type ViewerCameraProps = {
+    cameraState: ViewerCameraState | null;
+    cameraPresets: Record<string, ViewerCameraPreset>;
+    resetView: () => Promise<boolean>;
+    focusObject: (objectId: string) => Promise<boolean>;
+    fitScene: () => Promise<boolean>;
+    setCameraTarget: (target: [number, number, number], enableTransition?: boolean) => Promise<boolean>;
+    setCameraState: (state: ViewerCameraState, enableTransition?: boolean) => Promise<boolean>;
+    lookAt: (position: [number, number, number], target: [number, number, number], enableTransition?: boolean) => Promise<boolean>;
+    orbitTo: (azimuthAngle: number, polarAngle: number, enableTransition?: boolean) => Promise<boolean>;
+    dollyTo: (distance: number, enableTransition?: boolean) => Promise<boolean>;
+    savePreset: (name: string) => ViewerCameraState | null;
+    goToPreset: (name: string, enableTransition?: boolean) => Promise<boolean>;
+    handleCameraChange: (camera: Camera, controls: CameraControls) => void;
+    handleViewerReady: (viewer: ViewerReadyState) => void;
+};
+declare function useViewerCamera(options?: UseViewerCameraOptions): ViewerCameraProps;
+
+type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
+    [K in keyof T]?: DeepPartial<T[K]>;
+} : T;
+
+type ObjectBindingSelector = {
+    group: string;
+} | {
+    tag: string;
+} | {
+    type: ObjectBindingType;
+};
+type ObjectBindingTarget = string | readonly string[] | ObjectBindingSelector;
+/**
+ * Resolves IDs and selectors to binding-map keys in stable record order.
+ * Explicit ID arrays keep their supplied order. Duplicate matches are removed.
+ */
+declare function selectBindingKeys(bindings: Record<string, ObjectBinding>, target: ObjectBindingTarget): string[];
+/** Selects bindings by ID, group, tag, or binding type. */
+declare function selectBindings(bindings: Record<string, ObjectBinding>, target: ObjectBindingTarget): ObjectBinding[];
+
+type ObjectBindingPatch = DeepPartial<ObjectBinding>;
+type BindingEdit = {
+    ids: ObjectBindingTarget;
+    patch: ObjectBindingPatch;
+};
+/**
+ * Applies field-level patches to object bindings and returns the updated
+ * record. Pure — nothing is mutated, and the original reference comes back
+ * untouched when no id matched, so React can skip the re-render.
+ *
+ * Ids resolve the same way everywhere else in the library: binding key first,
+ * then `binding.id`, then `binding.modelObjectId`.
+ */
+declare function patchBindings(bindings: Record<string, ObjectBinding>, target: ObjectBindingTarget, patch: ObjectBindingPatch): Record<string, ObjectBinding>;
+declare function patchBindings(bindings: Record<string, ObjectBinding>, edits: BindingEdit[]): Record<string, ObjectBinding>;
+/** Shorthand for the common `{ style: { material: … } }` nesting. */
+declare function material(value: ObjectBindingMaterial): ObjectBindingPatch;
+
+type SceneConfigPatch = DeepPartial<SceneConfig>;
+/**
+ * Applies a nested scene-config patch without mutating either input. Objects
+ * are merged recursively, while arrays and tuples are replaced wholesale.
+ */
+declare function patchSceneConfig(sceneConfig: SceneConfig, patch: SceneConfigPatch): SceneConfig;
+
+type ObjectBindingsActionEffect = {
+    target: ObjectBindingTarget;
+    objectBindings: ObjectBindingPatch;
+};
+type SceneConfigActionEffect = {
+    sceneConfig: SceneConfigPatch;
+};
+type VisibilityActionEffect = {
+    target: ObjectBindingTarget;
+    visibility: "show" | "hide" | "toggle";
+};
+type CameraAction = {
+    type: "focus-object";
+    objectId?: string;
+} | {
+    type: "fit-scene";
+} | {
+    type: "reset";
+} | {
+    type: "set-target";
+    target: [number, number, number];
+    transition?: boolean;
+} | {
+    type: "set-state";
+    state: ViewerCameraState;
+    transition?: boolean;
+};
+type CameraActionEffect = {
+    camera: CameraAction;
+};
+type AnimationAction = {
+    type: "play";
+    clip: string;
+} | {
+    type: "pause";
+} | {
+    type: "stop";
+} | {
+    type: "set-speed";
+    speed: number;
+} | {
+    type: "seek";
+    time: number;
+};
+type AnimationActionEffect = {
+    animation: AnimationAction;
+};
+type ObjectActionEffect = ObjectBindingsActionEffect | SceneConfigActionEffect | VisibilityActionEffect | CameraActionEffect | AnimationActionEffect;
+
 type ObjectBindingAction = {
     id: "change-color" | "apply-texture" | "toggle-visibility" | string;
     label: string;
     type: "command";
+    effects?: ObjectActionEffect[];
 };
 type ObjectBindingType = "body" | "other" | "glass" | "windshield" | "rear-windshield" | "window" | "sunroof" | "wheel" | "rim" | "tire" | "brake-caliper" | "brake-disc" | "suspension" | "spring" | "shock-absorber" | "axle" | "control-arm" | "interior" | "seat" | "headrest" | "seatbelt" | "dashboard" | "steering-wheel" | "gear-shift" | "center-console" | "armrest" | "door-panel" | "carpet" | "headliner" | "sun-visor" | "pedal" | "instrument-cluster" | "infotainment" | "glove-box" | "engine" | "gearbox" | "radiator" | "battery" | "fuel-tank" | "air-filter" | "intercooler" | "alternator" | "turbo" | "light" | "headlight" | "taillight" | "fog-light" | "indicator" | "daytime-running-light" | "interior-light" | "ambient-light" | "floor" | "floor-tile" | "floor-board" | "floor-mat" | "ceiling" | "ceiling-tile" | "wall" | "wall-tile" | "wall-panel" | "wall-trim" | "baseboard" | "crown-molding" | "column" | "pillar" | "beam" | "arch" | "stairs" | "step" | "railing" | "balustrade" | "window-frame" | "window-sill" | "blind" | "curtain" | "shutter" | "door" | "door-frame" | "door-knob" | "furniture" | "sofa" | "armchair" | "ottoman" | "bed" | "headboard" | "mattress" | "nightstand" | "dresser" | "wardrobe" | "closet" | "shelf" | "bookcase" | "desk" | "office-chair" | "dining-table" | "dining-chair" | "bar-stool" | "bench" | "cabinet" | "sideboard" | "coffee-table" | "side-table" | "tv-stand" | "kitchen-island" | "countertop" | "sink" | "bathtub" | "shower" | "toilet" | "vanity" | "decor" | "rug" | "cushion" | "throw" | "curtain-rod" | "artwork" | "mirror" | "vase" | "plant" | "pot" | "candle" | "frame" | "sculpture" | "clock" | "lamp" | "floor-lamp" | "table-lamp" | "pendant-light" | "chandelier" | "sconce" | "ceiling-fan" | "electronics" | "tv" | "monitor" | "speaker" | "soundbar" | "projector" | "remote" | "console" | "router" | "smart-hub" | "thermostat" | "appliance" | "refrigerator" | "oven" | "microwave" | "dishwasher" | "washing-machine" | "dryer" | "air-conditioner" | "heater" | "ventilation" | "root" | "bone" | "joint" | "socket" | "pivot" | "head" | "face" | "eye" | "eyelid" | "eyebrow" | "mouth" | "teeth" | "tongue" | "ear" | "nose" | "hair" | "beard" | "neck" | "torso" | "chest" | "abdomen" | "back" | "shoulder" | "upper-arm" | "forearm" | "hand" | "finger" | "thumb" | "hip" | "thigh" | "shin" | "foot" | "toe" | "tail" | "wing" | "tentacle" | "clothing" | "hat" | "helmet" | "visor" | "mask" | "goggles" | "glasses" | "jacket" | "shirt" | "pants" | "skirt" | "shoes" | "boots" | "gloves" | "belt" | "watch" | "bag" | "backpack" | "jewelry" | "necklace" | "ring" | "armor" | "chest-plate" | "pauldron" | "gauntlet" | "greave" | "shield" | "weapon" | "blade" | "edge" | "tip" | "guard" | "grip" | "pommel" | "barrel" | "stock" | "scope" | "trigger" | "magazine" | "muzzle" | "gear" | "piston" | "lever" | "valve" | "pump" | "motor" | "rotor" | "blade-prop" | "nozzle" | "pipe" | "tube" | "cable" | "wire" | "connector" | "panel" | "hatch" | "vent" | "antenna" | "sensor" | "camera" | "screen" | "dial" | "button" | "knob" | "switch" | "gauge" | "terrain" | "ground" | "rock" | "cliff" | "water" | "ocean" | "river" | "lake" | "wave" | "foam" | "sky" | "cloud" | "sun" | "moon" | "star" | "fog" | "foliage" | "tree" | "branch" | "leaf" | "grass" | "bush" | "flower" | "soil" | "sand" | "snow" | "ice" | "facade" | "foundation" | "roof-structure" | "chimney" | "balcony" | "porch" | "pathway" | "fence" | "gate" | "wall-exterior";
 type ObjectBindingStatus = "normal" | "hidden" | "selected" | "disabled";
 type ObjectBindingTextureSlot = {
     path: string;
 };
+type ObjectBindingTextureChannel = "baseColor" | "metalness" | "roughness" | "emissive" | "alpha" | "normal" | "bump" | "ao" | "displacement" | "clearcoat" | "clearcoatRoughness" | "clearcoatNormal" | "anisotropy" | "transmission" | "thickness" | "sheenColor" | "sheenRoughness" | "specularIntensity" | "specularColor";
+type ObjectBindingTransform = {
+    /** Local-space position in model units. */
+    position?: [number, number, number];
+    /** Local-space Euler rotation in radians. */
+    rotation?: [number, number, number];
+    /** Local-space scale. */
+    scale?: [number, number, number];
+};
 declare const MATERIAL_SIDES: readonly ["front", "back", "double"];
 type ObjectBindingMaterialSide = (typeof MATERIAL_SIDES)[number];
 declare const MATERIAL_BLENDING_MODES: readonly ["normal", "additive"];
@@ -450,10 +630,13 @@ type ObjectBinding = {
     type: ObjectBindingType;
     modelObjectId: string;
     label?: string;
+    group?: string;
+    tags?: string[];
     status?: ObjectBindingStatus;
     visible?: boolean;
     selectable?: boolean;
     hoverable?: boolean;
+    transform?: ObjectBindingTransform;
     style?: ObjectBindingStyle;
     actions?: ObjectBindingAction[];
     metrics?: Record<string, number>;
@@ -468,44 +651,6 @@ type ObjectActionEvent = {
     screenY?: number;
 };
 
-type CaptureImageOptions = {
-    width?: number;
-    height?: number;
-    transparent?: boolean;
-};
-
-type ViewerCameraState = {
-    position: [number, number, number];
-    target: [number, number, number];
-    fov: number | null;
-    zoom: number;
-    azimuthAngle?: number;
-    polarAngle?: number;
-};
-type HomeCameraState = {
-    position: [number, number, number];
-    target: [number, number, number];
-};
-type ViewerReadyState = {
-    controls: CameraControls;
-    scene: Object3D | null;
-    objectBindings: Record<string, ObjectBinding>;
-    nodeRefs: Record<string, Object3D>;
-    homeCameraState: HomeCameraState | null;
-    captureImage: (options?: CaptureImageOptions) => Promise<string>;
-};
-type ViewerCameraProps = {
-    cameraState: ViewerCameraState | null;
-    resetView: () => Promise<boolean>;
-    focusObject: (objectId: string) => Promise<boolean>;
-    fitScene: () => Promise<boolean>;
-    setCameraTarget: (target: [number, number, number], enableTransition?: boolean) => Promise<boolean>;
-    setCameraState: (state: ViewerCameraState, enableTransition?: boolean) => Promise<boolean>;
-    handleCameraChange: (camera: Camera, controls: CameraControls) => void;
-    handleViewerReady: (viewer: ViewerReadyState) => void;
-};
-declare function useViewerCamera(): ViewerCameraProps;
-
 type AnimationClipInfo = {
     sourceName: string;
     duration: number;
@@ -665,45 +810,31 @@ declare function useObjectBinding(objectBindings: Record<string, ObjectBinding>,
 
 declare function useObjectBindingIds(objectBindings: Record<string, ObjectBinding>): string[];
 
-type DeepPartial<T> = T extends readonly unknown[] ? T : T extends object ? {
-    [K in keyof T]?: DeepPartial<T[K]>;
-} : T;
-
-type ObjectBindingPatch = DeepPartial<ObjectBinding>;
-type BindingEdit = {
-    ids: string | string[];
-    patch: ObjectBindingPatch;
-};
-/**
- * Applies field-level patches to object bindings and returns the updated
- * record. Pure — nothing is mutated, and the original reference comes back
- * untouched when no id matched, so React can skip the re-render.
- *
- * Ids resolve the same way everywhere else in the library: binding key first,
- * then `binding.id`, then `binding.modelObjectId`.
- */
-declare function patchBindings(bindings: Record<string, ObjectBinding>, objectId: string | string[], patch: ObjectBindingPatch): Record<string, ObjectBinding>;
-declare function patchBindings(bindings: Record<string, ObjectBinding>, edits: BindingEdit[]): Record<string, ObjectBinding>;
-/** Shorthand for the common `{ style: { material: … } }` nesting. */
-declare function material(value: ObjectBindingMaterial): ObjectBindingPatch;
-
 type HiddenObjectsState = Record<string, boolean>;
 type ObjectBindingsController = {
     objectBindings: Record<string, ObjectBinding>;
     setObjectBindings: React.Dispatch<React.SetStateAction<Record<string, ObjectBinding>>>;
     updateObjectBindings: {
-        (objectId: string | string[], patch: ObjectBindingPatch): void;
+        (target: ObjectBindingTarget, patch: ObjectBindingPatch): void;
         (edits: BindingEdit[]): void;
     };
-    setMaterial: (objectId: string | string[], material: ObjectBindingMaterial) => void;
-    setBaseColor: (objectId: string | string[], color: string) => void;
-    resetMaterial: (objectId: string | string[]) => void;
+    setMaterial: (target: ObjectBindingTarget, material: ObjectBindingMaterial) => void;
+    setBaseColor: (target: ObjectBindingTarget, color: string) => void;
+    setTexture: (target: ObjectBindingTarget, texture: string | ObjectBindingTextureSlot, channel?: ObjectBindingTextureChannel) => void;
+    clearTexture: (target: ObjectBindingTarget, channel?: ObjectBindingTextureChannel) => void;
+    copyMaterial: (source: string, target: ObjectBindingTarget) => void;
+    resetMaterial: (target: ObjectBindingTarget) => void;
     getMaterial: (objectId: string) => ObjectBindingMaterial | null;
+    setTransform: (target: ObjectBindingTarget, transform: ObjectBindingTransform) => void;
+    resetTransform: (target: ObjectBindingTarget) => void;
+    updateMetadata: (target: ObjectBindingTarget, metadata: Record<string, unknown>) => void;
+    selectObjectBindings: (target: ObjectBindingTarget) => ObjectBinding[];
+    selectObjectBindingIds: (target: ObjectBindingTarget) => string[];
     hiddenObjects: HiddenObjectsState;
     hiddenObjectIds: string[];
-    hideObject: (objectId: string | string[]) => void;
-    showObject: (objectId: string | string[]) => void;
-    toggleObjectVisibility: (objectId: string | string[]) => void;
+    hideObject: (target: ObjectBindingTarget) => void;
+    showObject: (target: ObjectBindingTarget) => void;
+    toggleObjectVisibility: (target: ObjectBindingTarget) => void;
     isObjectHidden: (objectId: string) => boolean;
     clearHiddenObjects: () => void;
 };
@@ -716,12 +847,19 @@ type ObjectBindingsController = {
  */
 declare function useObjectBindings(initialBindings: Record<string, ObjectBinding> | (() => Record<string, ObjectBinding>)): ObjectBindingsController;
 
-type SceneConfigPatch = DeepPartial<SceneConfig>;
 /**
- * Applies a nested scene-config patch without mutating either input. Objects
- * are merged recursively, while arrays and tuples are replaced wholesale.
+ * Validates an object-bindings literal while preserving its exact keys and
+ * literal values for TypeScript autocomplete and derived union types.
+ *
+ * This is an identity function at runtime.
  */
-declare function patchSceneConfig(sceneConfig: SceneConfig, patch: SceneConfigPatch): SceneConfig;
+declare function defineObjectBindings<const TBindings extends Record<string, ObjectBinding>>(bindings: TBindings): TBindings;
+/** Binding-map keys preserved by defineObjectBindings. */
+type ObjectBindingKey<TBindings extends Record<string, ObjectBinding>> = Extract<keyof TBindings, string>;
+/** Action ids declared on one binding in a defined bindings map. */
+type ObjectBindingActionId<TBindings extends Record<string, ObjectBinding>, TKey extends ObjectBindingKey<TBindings>> = TBindings[TKey]["actions"] extends readonly (infer TAction)[] ? TAction extends {
+    id: infer TId extends string;
+} ? TId : never : never;
 
 type SceneConfigUpdate = SceneConfigPatch | ((current: SceneConfig) => SceneConfigPatch);
 type SceneConfigController = {
@@ -729,6 +867,23 @@ type SceneConfigController = {
     setSceneConfig: React.Dispatch<React.SetStateAction<SceneConfig>>;
     updateSceneConfig: (update: SceneConfigUpdate) => void;
     resetSceneConfig: () => void;
+    lights: SceneLightsController;
+};
+type SceneLightInput = Pick<SceneLight, "id"> & Partial<Omit<SceneLight, "id">>;
+type SceneLightPatch = Partial<Omit<SceneLight, "id">>;
+type SceneLightsController = {
+    items: SceneLight[];
+    get: (id: string) => SceneLight | undefined;
+    add: (light: SceneLightInput) => void;
+    update: (id: string, patch: SceneLightPatch) => void;
+    remove: (id: string) => void;
+    setIntensity: (id: string, intensity: number) => void;
+    setColor: (id: string, color: string) => void;
+    show: (id: string) => void;
+    hide: (id: string) => void;
+    toggle: (id: string) => void;
+    attach: (id: string, attachment: SceneLightAttachment) => void;
+    detach: (id: string) => void;
 };
 /**
  * Owns scene-config state and applies nested patches through functional React
@@ -760,15 +915,170 @@ type ViewerModelProps = {
 };
 declare function useViewerModel(): ViewerModelProps;
 
+type ViewerActionBindingsController = Pick<ObjectBindingsController, "objectBindings" | "updateObjectBindings" | "showObject" | "hideObject" | "toggleObjectVisibility">;
+type ViewerActionSceneController = Pick<SceneConfigController, "updateSceneConfig">;
+type ViewerActionCameraController = Pick<ViewerCameraProps, "focusObject" | "fitScene" | "resetView" | "setCameraTarget" | "setCameraState">;
+type ViewerActionAnimationController = Pick<ViewerAnimationsProps, "play" | "pause" | "stop" | "setSpeed" | "seek">;
 type ViewerActionsOptions = {
-    onAction?: (event: ObjectActionEvent) => void;
-    onObjectBindingsChange?: (next: Record<string, ObjectBinding>) => void;
+    bindings: ViewerActionBindingsController;
+    scene?: ViewerActionSceneController;
+    camera?: ViewerActionCameraController;
+    animations?: ViewerActionAnimationController;
+    onAction?: (event: ObjectActionEvent) => void | Promise<void>;
 };
 type ViewerActionsProps = {
     getActionsForObject: (objectId: string) => ObjectBindingAction[];
-    runAction: (objectId: string, actionId: string) => ObjectActionEvent | null;
+    handleAction: (event: ObjectActionEvent) => Promise<void>;
+    runAction: (objectId: string, actionId: string) => Promise<ObjectActionEvent | null>;
+};
+/**
+ * Resolves object actions and executes their declarative binding, scene,
+ * visibility, camera, and animation effects in declaration order.
+ */
+declare function useViewerActions({ bindings, scene, camera, animations, onAction, }: ViewerActionsOptions): ViewerActionsProps;
+
+type ViewerReadyHandler = (viewer: ViewerReadyState) => void;
+type ViewerReadyConsumer = ViewerReadyHandler | {
+    handleViewerReady: ViewerReadyHandler;
+} | null | undefined;
+type ViewerConnectionController = {
+    /** The single callback to pass to ModelViewer's onViewerReady prop. */
+    handleViewerReady: ViewerReadyHandler;
+    /** Returns the latest live viewer without causing camera-change rerenders. */
+    getViewer: () => ViewerReadyState | null;
+    /** Captures the connected viewer, or rejects when it is not ready yet. */
+    captureImage: (options?: CaptureImageOptions) => Promise<string>;
+    /** Requests a frame from the connected viewer. */
+    invalidate: () => boolean;
+};
+/**
+ * Composes camera, effects, and custom viewer-ready consumers into one typed
+ * ModelViewer connection. Pass the returned handleViewerReady to ModelViewer.
+ */
+declare function useViewerConnection(...consumers: readonly ViewerReadyConsumer[]): ViewerConnectionController;
+
+type ViewerEffectTarget = ObjectBindingTarget;
+type ViewerVector3 = readonly [number, number, number];
+type ViewerEffectRange = readonly [number, number];
+type RuntimeMaterialPatch = {
+    baseColor?: string;
+    emissive?: string;
+    emissiveIntensity?: number;
+    opacity?: number;
+    metalness?: number;
+    roughness?: number;
+    transmission?: number;
+    clearcoat?: number;
+    clearcoatRoughness?: number;
+    ior?: number;
+    thickness?: number;
+    transparent?: boolean;
+};
+type RuntimeTransformPatch = {
+    position?: ViewerVector3;
+    rotation?: ViewerVector3;
+    scale?: ViewerVector3 | number;
+    visible?: boolean;
+};
+type RuntimeMaterialRanges = Partial<Record<"emissiveIntensity" | "opacity" | "metalness" | "roughness" | "transmission" | "clearcoat" | "clearcoatRoughness" | "ior" | "thickness", ViewerEffectRange>>;
+type RuntimeTransformRanges = {
+    position?: readonly [ViewerVector3, ViewerVector3];
+    rotation?: readonly [ViewerVector3, ViewerVector3];
+    scale?: readonly [ViewerVector3, ViewerVector3];
+};
+type ViewerMaterialEffectChannel = {
+    targets: ViewerEffectTarget;
+    values: RuntimeMaterialRanges;
+};
+type ViewerTransformEffectChannel = {
+    targets: ViewerEffectTarget;
+    values: RuntimeTransformRanges;
+};
+type ViewerLightEffectChannel = {
+    lights: string | readonly string[];
+    intensity: ViewerEffectRange;
+};
+type ViewerEffectChannels = {
+    materials?: ViewerMaterialEffectChannel[];
+    transforms?: ViewerTransformEffectChannel[];
+    lights?: ViewerLightEffectChannel[];
+};
+type ViewerEffectEasing = "linear" | "ease-in" | "ease-out" | "ease-in-out";
+type ViewerTransitionOptions = {
+    id?: string;
+    duration?: number;
+    easing?: ViewerEffectEasing;
+    onComplete?: () => void;
+};
+type ViewerTimelineStep = {
+    channels: ViewerEffectChannels;
+    duration: number;
+    hold?: number;
+    easing?: ViewerEffectEasing;
+};
+type ViewerTimelineOptions = {
+    id?: string;
+    repeat?: number;
+    onComplete?: () => void;
 };
-declare function useViewerActions(objectBindings: Record<string, ObjectBinding>, options?: ViewerActionsOptions): ViewerActionsProps;
+type ViewerPulseOptions = {
+    id?: string;
+    duration?: number;
+    minLevel?: number;
+    maxLevel?: number;
+    repeat?: number;
+    synchronized?: boolean;
+    onComplete?: () => void;
+};
+type ViewerFlickerOptions = {
+    id?: string;
+    minLevel?: number;
+    maxLevel?: number;
+    interval?: number | ViewerEffectRange;
+    response?: number;
+    blackoutChance?: number;
+    flashChance?: number;
+    flashLevel?: number;
+    synchronized?: boolean;
+    duration?: number;
+    onComplete?: () => void;
+};
+type RuntimePointLightOptions = {
+    id: string;
+    target: string;
+    color?: string;
+    intensity?: number;
+    distance?: number;
+    decay?: number;
+    offset?: ViewerVector3;
+    castShadow?: boolean;
+};
+type RuntimePointLightPatch = Partial<Omit<RuntimePointLightOptions, "id">>;
+type UseViewerEffectsOptions = {
+    onViewerReady?: (viewer: ViewerReadyState) => void;
+};
+type ViewerEffectsController = {
+    handleViewerReady: (viewer: ViewerReadyState) => void;
+    setMaterial: (target: ViewerEffectTarget, patch: RuntimeMaterialPatch) => boolean;
+    setTransform: (target: ViewerEffectTarget, patch: RuntimeTransformPatch) => boolean;
+    getWorldPosition: (target: string) => ViewerVector3 | null;
+    addPointLight: (options: RuntimePointLightOptions) => boolean;
+    updatePointLight: (id: string, patch: RuntimePointLightPatch) => boolean;
+    removePointLight: (id: string) => boolean;
+    transition: (channels: ViewerEffectChannels, options?: ViewerTransitionOptions) => string;
+    timeline: (steps: readonly ViewerTimelineStep[], options?: ViewerTimelineOptions) => string;
+    pulse: (channels: ViewerEffectChannels, options?: ViewerPulseOptions) => string;
+    flicker: (channels: ViewerEffectChannels, options?: ViewerFlickerOptions) => string;
+    overrideEffect: (id: string, level: number, duration: number) => boolean;
+    stopEffect: (id: string) => boolean;
+    stopAllEffects: () => void;
+    resetRuntime: () => void;
+};
+/**
+ * Applies live material, transform, and point-light effects without putting
+ * frame-by-frame values in React state or exposing Three.js objects to the app.
+ */
+declare function useViewerEffects(options?: UseViewerEffectsOptions): ViewerEffectsController;
 
 type UseShareableViewerStateOptions = {
     cameraState: ViewerCameraState | null;
@@ -788,4 +1098,4 @@ type ShareableViewerStateProps = {
 };
 declare function useShareableViewerState({ cameraState, setCameraState, objectBindings, onObjectBindingsChange, selectedObjectBinding, setSelectedObjectBinding, paramKey, debounceMs, autoSync, }: UseShareableViewerStateOptions): ShareableViewerStateProps;
 
-export { type AnimationClipInfo, type AnimationControls, type AnimationLoopMode, type AnimationPlaybackState, BindingBuilder, type BindingEdit, type CaptureImageOptions, type CinematicConfig, type CinematicWaypoint, type CustomObjectBindingDataPanelProps, type CustomSceneObjectsPanelProps, type HiddenObjectsState, type HomeCameraState, MATERIAL_BLENDING_MODES, MATERIAL_SIDES, ModelViewer, type ModelViewerProps, type ObjectActionEvent, type ObjectBinding, type ObjectBindingAction, type ObjectBindingMaterial, type ObjectBindingMaterialBlendingMode, type ObjectBindingMaterialSide, type ObjectBindingPatch, type ObjectBindingTextureSlot, type ObjectBindingsController, type SceneAnimationClipConfig, type SceneAnimationConfig, type SceneCinematicConfig, type SceneCinematicWaypoint, type SceneConfig, type SceneConfigController, type SceneConfigPatch, type SceneConfigUpdate, type SceneModelRenderer, SimpleModelViewer, type SimpleModelViewerProps, type ViewerActionsOptions, type ViewerActionsProps, type ViewerAnimationsProps, type ViewerCameraProps, type ViewerCameraState, type ViewerModelBounds, type ViewerModelProps, type ViewerReadyState, type ViewerSelectionProps, type XRScaleMode, material, patchBindings, patchSceneConfig, useObjectBinding, useObjectBindingIds, useObjectBindings, useSceneConfig, useShareableViewerState, useViewerActions, useViewerAnimations, useViewerCamera, useViewerHover, useViewerModel, useViewerSelection };
+export { type AnimationAction, type AnimationActionEffect, type AnimationClipInfo, type AnimationControls, type AnimationLoopMode, type AnimationPlaybackState, BindingBuilder, type BindingEdit, type CameraAction, type CameraActionEffect, type CaptureImageOptions, type CinematicConfig, type CinematicWaypoint, type CustomObjectBindingDataPanelProps, type CustomSceneObjectsPanelProps, DEFAULT_SCENE_CONFIG, type HiddenObjectsState, type HomeCameraState, MATERIAL_BLENDING_MODES, MATERIAL_SIDES, ModelViewer, type ModelViewerProps, type ObjectActionEffect, type ObjectActionEvent, type ObjectBinding, type ObjectBindingAction, type ObjectBindingActionId, type ObjectBindingKey, type ObjectBindingMaterial, type ObjectBindingMaterialBlendingMode, type ObjectBindingMaterialSide, type ObjectBindingPatch, type ObjectBindingSelector, type ObjectBindingTarget, type ObjectBindingTextureChannel, type ObjectBindingTextureSlot, type ObjectBindingTransform, type ObjectBindingsActionEffect, type ObjectBindingsController, type RuntimeMaterialPatch, type RuntimeMaterialRanges, type RuntimePointLightOptions, type RuntimePointLightPatch, type RuntimeTransformPatch, type RuntimeTransformRanges, type SceneAnimationClipConfig, type SceneAnimationConfig, type SceneCinematicConfig, type SceneCinematicWaypoint, type SceneConfig, type SceneConfigActionEffect, type SceneConfigController, type SceneConfigPatch, type SceneConfigUpdate, type SceneLight, type SceneLightAttachment, type SceneLightInput, type SceneLightPatch, type SceneLightType, type SceneLightsController, type SceneModelRenderer, SimpleModelViewer, type SimpleModelViewerProps, type UseViewerCameraOptions, type UseViewerEffectsOptions, type ViewerActionAnimationController, type ViewerActionBindingsController, type ViewerActionCameraController, type ViewerActionSceneController, type ViewerActionsOptions, type ViewerActionsProps, type ViewerAnimationsProps, type ViewerCameraPreset, type ViewerCameraProps, type ViewerCameraState, type ViewerConnectionController, type ViewerEffectChannels, type ViewerEffectEasing, type ViewerEffectRange, type ViewerEffectTarget, type ViewerEffectsController, type ViewerFlickerOptions, type ViewerLightEffectChannel, type ViewerMaterialEffectChannel, type ViewerModelBounds, type ViewerModelProps, type ViewerPulseOptions, type ViewerReadyConsumer, type ViewerReadyHandler, type ViewerReadyState, type ViewerSelectionProps, type ViewerTimelineOptions, type ViewerTimelineStep, type ViewerTransformEffectChannel, type ViewerTransitionOptions, type ViewerVector3, type VisibilityActionEffect, type XRScaleMode, defineObjectBindings, material, patchBindings, patchSceneConfig, selectBindingKeys, selectBindings, useObjectBinding, useObjectBindingIds, useObjectBindings, useSceneConfig, useShareableViewerState, useViewerActions, useViewerAnimations, useViewerCamera, useViewerConnection, useViewerEffects, useViewerHover, useViewerModel, useViewerSelection };