Types Reference

type ObjectBinding = {
  id: string;
  type?: ObjectBindingType; // defaults to "other"
  modelObjectId: string;
  label?: string;
  group?: string;
  tags?: string[];
  status?: "normal" | "hidden" | "selected" | "disabled";
  visible?: boolean;
  selectable?: boolean;
  hoverable?: boolean;
  transform?: ObjectBindingTransform;
  style?: ObjectBindingStyle;
  decals?: ObjectBindingDecal[]; // images and text on the surface; see ModelViewer's "Decals"
  actions?: ObjectBindingAction[];
  metrics?: Record<string, number>;
  metadata?: Record<string, unknown>;
  cameraState?: ObjectBindingCameraState;
};

type ObjectBindingStatus = "normal" | "hidden" | "selected" | "disabled";

import {
  defineObjectBindings,
  type ObjectBindingActionId,
  type ObjectBindingKey,
} from "@liveroom-tech/react-immersive/utils";
 
const bindings = defineObjectBindings({
  body: {
    id: "vehicle-body",
    modelObjectId: "body",
    type: "body",
    actions: [{ id: "repaint", label: "Repaint", type: "command" }],
  },
});
 
type BindingKeys = ObjectBindingKey<typeof bindings>; // "body"
type BodyActions = ObjectBindingActionId<typeof bindings, "body">; // "repaint"

type ObjectBindingTransform = {
  position?: [number, number, number]; // local model units
  rotation?: [number, number, number]; // local Euler angles in radians
  scale?: [number, number, number];
};

type ObjectBindingType =
  | "body"
  | "light"
  | "wheel"
  | "glass"
  | "interior"
  | "floor"
  | "wall"
  | "door"
  | "furniture"
  | "decor"
  | "electronics"
  | "other"
  // ... and more suggestions
  | (string & {}); // any other string

type ObjectBindingStyle = {
  material?: ObjectBindingMaterial;
};

type TextureSlot = { path: string };
 
type ObjectBindingMaterial = {
  // ── Base / PBR ──────────────────────────────────────────────
  texture?: TextureSlot; // base color (albedo) map
  baseColor?: string; // hex, e.g. "#ff0000"
  metalness?: number; // 0–1
  metalnessMap?: TextureSlot;
  roughness?: number; // 0–1
  roughnessMap?: TextureSlot;
  reflectivity?: number; // 0–1 (specular F0)
  specularIntensity?: number; // 0–1
  specularIntensityMap?: TextureSlot;
  specularColor?: string; // hex
  specularColorMap?: TextureSlot;
 
  // ── Emission ────────────────────────────────────────────────
  emissive?: string; // hex
  emissiveIntensity?: number; // 0–10
  emissiveMap?: TextureSlot;
 
  // ── Opacity / blending ──────────────────────────────────────
  opacity?: number; // 0–1
  alphaMap?: TextureSlot;
  alphaTest?: number; // 0–1
  alphaHash?: boolean;
  dithering?: boolean; // banding reduction on gradients
  blendingMode?: "normal" | "additive";
 
  // ── Normal / bump ───────────────────────────────────────────
  normalMap?: TextureSlot;
  normalScale?: number;
  flipNormalY?: boolean;
  bumpMap?: TextureSlot;
  bumpScale?: number;
 
  // ── Displacement ────────────────────────────────────────────
  displacementMap?: TextureSlot;
  displacementScale?: number;
  displacementBias?: number;
 
  // ── Ambient occlusion ───────────────────────────────────────
  aoMap?: TextureSlot;
  aoMapIntensity?: number;
 
  // ── Clearcoat ───────────────────────────────────────────────
  clearcoat?: number; // 0–1
  clearcoatMap?: TextureSlot;
  clearcoatRoughness?: number; // 0–1
  clearcoatRoughnessMap?: TextureSlot;
  clearcoatNormalMap?: TextureSlot;
  clearcoatNormalScale?: number;
  flipClearcoatNormalY?: boolean;
 
  // ── Sheen ───────────────────────────────────────────────────
  sheen?: number; // 0–1
  sheenColor?: string; // hex
  sheenColorMap?: TextureSlot;
  sheenRoughness?: number; // 0–1
  sheenRoughnessMap?: TextureSlot;
 
  // ── Anisotropy ──────────────────────────────────────────────
  anisotropy?: number; // 0–1
  anisotropyRotation?: number; // radians
  anisotropyMap?: TextureSlot;
 
  // ── Transmission / volume ───────────────────────────────────
  transmission?: number; // 0–1
  transmissionMap?: TextureSlot;
  thickness?: number;
  thicknessMap?: TextureSlot;
  attenuationColor?: string; // hex (volume tint)
  attenuationDistance?: number;
 
  // ── Faces ───────────────────────────────────────────────────
  side?: "front" | "back" | "double";
};

type ObjectBindingAction = {
  id: string;
  label: string;
  type: "command";
  effects?: ObjectActionEffect[];
};

type ObjectActionEffect =
  | {
      target: ObjectBindingTarget;
      objectBindings: ObjectBindingPatch;
    }
  | { sceneConfig: SceneConfigPatch }
  | {
      target: ObjectBindingTarget;
      visibility: "show" | "hide" | "toggle";
    }
  | { camera: CameraAction }
  | { animation: AnimationAction };
 
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 };
 
// play replaces the clips already playing unless alongside is set; the others
// act on clip, or on every active clip when it's left out.
type AnimationAction =
  | ({ type: "play"; clip: string } & AnimationPlayOptions)
  | { type: "pause"; clip?: string }
  | { type: "stop"; clip?: string }
  | { type: "set-speed"; speed: number; clip?: string }
  | { type: "seek"; time: number; clip?: string };

type ObjectBindingCameraState = {
  position?: [number, number, number];
  target?: [number, number, number];
  fov?: number;
  zoom?: number;
};

type ObjectActionEvent = {
  objectId: string;
  action: ObjectBindingAction;
  binding?: ObjectBinding;
  screenX?: number;
  screenY?: number;
};

type ObjectPointerEvent = {
  binding: ObjectBinding;
  clientX: number; // viewport coordinates, e.g. for a position: fixed menu
  clientY: number;
  pointerType: string; // "mouse" | "pen" | "touch"
  surface?: { position: Vec3; normal: Vec3 }; // where on the object, in its own space
};

type AnimationPlayOptions = {
  alongside?: boolean; // keep the clips already playing (default false: replace them)
  fade?: number; // seconds to fade in, and to fade out the clips it replaces
  reverse?: boolean; // play backwards, from where the clip is or from its end
};
 
type AnimationClipState = {
  clip: string;
  status: "playing" | "paused" | "finished"; // finished: a play-once clip holding its last pose
  time: number; // seconds
  duration: number; // seconds
  speed: number;
  reverse: boolean;
};
 
type AnimationPlaybackState = {
  currentClip: string | null; // the clip played most recently, while it's active
  isPlaying: boolean; // whether any clip is playing
  speed: number; // speed, position and length of currentClip
  time: number;
  duration: number;
  active: AnimationClipState[]; // every active clip, most recently played last
};
 
// Leave out clipName to act on every active clip.
type AnimationControls = {
  clips: string[];
  clipDetails?: { sourceName: string; duration: number }[];
  play: (clipName: string, options?: AnimationPlayOptions) => void;
  pause: (clipName?: string) => void;
  stop: (clipName?: string) => void; // stops and resets the pose
  setSpeed: (speed: number, clipName?: string) => void;
  seek?: (time: number, clipName?: string) => void; // absolute time, in seconds
  getState?: () => AnimationPlaybackState;
  subscribe?: (listener: (state: AnimationPlaybackState) => void) => () => void;
};

type ViewerIsolation = {
  target: ObjectBindingTarget; // an id, a list of ids, { group }, { tag }, or { type }
  mode?: "ghost" | "hide"; // default "ghost"
  ghostOpacity?: number; // 0–1, default 0.12
};

type SceneSectionConfig = {
  enabled: boolean;
  axis: "x" | "y" | "z"; // world axis the cut runs across
  position: number; // 0 at the model's minimum along the axis, 1 at its maximum
  flip: boolean; // keep the higher side instead of the lower one
};

type SceneStyleRule = {
  id: string;
  label?: string;
  target?: ObjectBindingTarget; // every bound object when left out
  when?: SceneStyleCondition | SceneStyleCondition[]; // all must match
  material?: ObjectBindingMaterial;
  colorScale?: SceneStyleColorScale;
  pulse?: boolean | SceneStylePulse;
};
 
type SceneStyleCondition =
  | { metric: string; above?: number; below?: number }
  | { status: ObjectBindingStatus | ObjectBindingStatus[] }
  | { metadata: string; equals: string | number | boolean | null }; // "a.b" reaches nested keys
 
type SceneStyleColorScale = {
  metric: string;
  stops: [number, string][]; // [value, "#rrggbb"]
  channel?: "baseColor" | "emissive"; // default "baseColor"
};
 
type SceneStylePulse = {
  color?: string; // default "#ff3b30"
  speed?: number; // pulses per second, default 1
};

type SceneLightAttachment = {
  objectId: string;
  offset: [number, number, number];
};
 
type SceneLight = {
  id: string;
  type: "none" | "directional" | "point" | "spot" | "hemisphere";
  color: string;
  intensity: number;
  position: [number, number, number];
  rotation?: [number, number, number];
  distance?: number;
  decay?: number;
  angle?: number;
  penumbra?: number;
  attachedToCamera: boolean;
  attachment?: SceneLightAttachment;
  castShadow: boolean;
  shadowBias: number;
  visible: boolean;
};

type SceneModelRenderer = "pbr" | "matcap" | "uv-checker";

type SceneConfig = {
  model: {
    rotation: [number, number, number];
    showAdvancedRotation: boolean;
    renderer: "pbr" | "matcap" | "uv-checker";
    shading: "lit" | "unlit" | "normals";
    autoRotate?: boolean;
    autoRotateSpeed?: number;
    activeVariants?: string[]; // glTF material variants shown, one per option group
  };
  camera: SceneCameraConfig;
  lighting: SceneLightingConfig;
  wireframe: SceneWireframeConfig;
  shadows: SceneShadowConfig;
  environment: SceneEnvironmentConfig;
  background: SceneBackgroundConfig;
  groundShadows: SceneGroundShadowConfig;
  postProcessing: ScenePostProcessingConfig;
  animations: SceneAnimationConfig;
  annotations: SceneAnnotationMarker[];
  cinematic?: SceneCinematicConfig;
  styleRules?: SceneStyleRule[]; // data-driven looks; see ModelViewer's "Style rules"
  section?: SceneSectionConfig; // cut-away view; see ModelViewer's showSectionTools
};

type ViewerObjectInfo = {
  name: string; // the key to use in objectBindings
  triangles: number;
  minimum: [number, number, number];
  maximum: [number, number, number];
};

type CinematicConfig = {
  waypoints?: CinematicWaypoint[]; // camera keyframes to glide through
  duration?: number; // seconds for one full pass (auto-scales when omitted)
  loop?: boolean; // default true
  autoPlay?: boolean; // start once the model has loaded and framed (default false)
};
 
type CinematicWaypoint = {
  position: [number, number, number];
  target: [number, number, number]; // world-space look-at point
  azimuthAngle?: number; // radians, captured by BindingBuilder; omit by hand
  polarAngle?: number; // radians
  segmentDuration?: number; // seconds spent reaching the next waypoint
};

type SceneCinematicConfig = {
  enabled: boolean; // turns the auto-camera on at runtime
  waypoints: SceneCinematicWaypoint[];
  duration?: number;
  loop: boolean;
  autoPlay: boolean;
};
 
type SceneCinematicWaypoint = {
  position: [number, number, number];
  target: [number, number, number];
  azimuthAngle?: number; // radians, captured by BindingBuilder; omit by hand
  polarAngle?: number; // radians
  segmentDuration?: number;
};

type CustomObjectBindingDataPanelProps = {
  isOpen: boolean;
  selectedObject: ObjectBinding | null;
  currentAction: ObjectActionEvent | null;
  onClose: () => void;
  onAction: (event: ObjectActionEvent) => void;
};

type CustomSceneObjectsPanelProps = {
  objectBindings: Record<string, ObjectBinding>;
  onAction?: (event: ObjectActionEvent) => void;
  onFocus?: (binding: ObjectBinding) => void;
  onHover?: (binding: ObjectBinding | null) => void;
};

type CaptureVideoOptions = {
  /** Defaults to cinematic when a path is enabled, otherwise turntable. */
  mode?: "cinematic" | "turntable";
  /** Auto prefers WebM, then MP4. "gif" makes a looping GIF. Explicit formats reject if unsupported. */
  format?: "auto" | "webm" | "mp4" | "gif";
  /** Seconds per pass, in (0, 300]. Defaults to path timing, or a 24s orbit (8s for a GIF). */
  duration?: number;
  /** Capture frame rate, from 1 to 60. Default 30 (15 for a GIF). */
  fps?: number;
  /** Encoder target bitrate in bits per second. Default 8,000,000. Not used for GIFs. */
  videoBitsPerSecond?: number;
  /** GIF width in pixels, 16 to 4096, never wider than the canvas; the height follows. Default 480. */
  gifWidth?: number;
  /** Aborting discards the recording and restores the viewer. */
  signal?: AbortSignal;
};

/** Engagement from deliberate viewer interactions, with model/session context. */
type ViewerEngagementEvent = {
  /** Ephemeral identifier for this viewer/model session; no persistent storage. */
  sessionId: string;
  /** ISO timestamp of the event. */
  timestamp: string;
  /** Milliseconds since tracking started for this model. */
  elapsedMs: number;
  modelUrl: string;
  tilesetUrl: string | null;
} & (
  | {
      type: "part-viewed";
      objectId: string;
      objectKey: string;
      label?: string;
      source: "canvas" | "panel" | "keyboard";
    }
  | {
      type: "variant-chosen";
      variant: string | null; // null when a group's choice was cleared
      previousVariant: string | null; // the group's previous choice
      group: string | null; // the option group's name; null for an unnamed group
    }
  | { type: "ar-started" }
  | {
      type: "ar-ended";
      durationMs: number;
      reason: "session-ended" | "interrupted";
    }
  | {
      type: "ar-launch-requested";
      channel: "quick-look" | "mobile-handoff";
    }
  | { type: "tour-started"; annotationCount: number }
  | { type: "tour-completed"; annotationCount: number; durationMs: number }
  | {
      type: "tour-stopped";
      annotationCount: number;
      durationMs: number;
      reason: "stopped" | "restarted" | "annotations-changed" | "interrupted";
    }
);
 

type SceneAnnotationCameraView = {
  position: [number, number, number];
  target: [number, number, number];
  azimuthAngle?: number; // radians
  polarAngle?: number; // radians
  fov?: number | null;
  zoom?: number;
};
 
type SceneAnnotationImage = { src: string; alt?: string };
type SceneAnnotationLink = { href: string; label: string };
 
type SceneAnnotationMarker = {
  id: number;
  worldPosition: [number, number, number];
  localPosition: [number, number, number];
  worldNormal?: [number, number, number];
  anchorNodeName?: string;
  anchorLocalPosition?: [number, number, number];
  title: string;
  description: string;
  cameraView?: SceneAnnotationCameraView;
  images?: SceneAnnotationImage[];
  links?: SceneAnnotationLink[];
  category?: string;
  minDistance?: number;
  maxDistance?: number;
};