@vctrl/embed 0.25.0 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## [1.0.0](https://github.com/Vectreal/vectreal-platform/compare/embed-v0.25.1...embed-v1.0.0) (2026-09-25)
+
+
+### ⚠ BREAKING CHANGES
+
+* **embed:** `InfoPopoverVectrealFooter` is no longer exported from `@vctrl/viewer`. The info-popover primitives now carry no branding of their own, so a consumer importing it must delete the import and supply their own footer if they want one. The Vectreal mark on hosted embeds is rendered by the platform instead, and is gated on the scene owner's plan.
+* **hooks:** `ShadowsProps` is a plain interface rather than a union discriminated on `type`, so a consumer still passing `type: 'accumulative'` is passing an unknown property.
+
+### Features
+
+* **embed:** author-controlled info popover, plan-gated Vectreal mark ([#828](https://github.com/Vectreal/vectreal-platform/issues/828)) ([d557acb](https://github.com/Vectreal/vectreal-platform/commit/d557acb55ae04f878ee30838052accb3b76767e1))
+* **hotspots:** let a hotspot say something ([#831](https://github.com/Vectreal/vectreal-platform/issues/831)) ([d4c9b3d](https://github.com/Vectreal/vectreal-platform/commit/d4c9b3d1d38d3cdd6e2e268b5e9732d3ad7b2970))
+* **viewer:** play glTF animation clips ([11ff088](https://github.com/Vectreal/vectreal-platform/commit/11ff0880eb32ef0bda03196fe74de4955452d2f1))
+
+
+### Bug Fixes
+
+* **build:** make the package typecheck gates actually compile something ([#723](https://github.com/Vectreal/vectreal-platform/issues/723)) ([38c6487](https://github.com/Vectreal/vectreal-platform/commit/38c64879a00c1774df970effa09cff38396233ec))
+* **hooks:** keep a failed upload from hiding a failed scene load ([5e9676f](https://github.com/Vectreal/vectreal-platform/commit/5e9676f01f61aa53ab74ec3e3fb2d78283fe7045))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * devDependencies
+    * @vctrl/viewer bumped to 1.0.0
+
+## [0.25.1](https://github.com/Vectreal/vectreal-platform/compare/embed-v0.25.0...embed-v0.25.1) (2026-08-08)
+
+
+### Miscellaneous Chores
+
+* **embed:** Synchronize vectreal-monorepo versions
+
 ## [0.25.0](https://github.com/Vectreal/vectreal-platform/compare/embed-v0.24.1...embed-v0.25.0) (2026-08-04)
 
 

package/README.md

@@ -42,8 +42,9 @@ For production, pin a version (`@vctrl/embed@<version>`) and add a [Subresource
 
 	const embed = new VectrealEmbed(document.getElementById('vectreal-scene'))
 
-	const { cameras } = await embed.ready()
+	const { cameras, hotspots } = await embed.ready()
 	console.log('Available cameras:', cameras)
+	console.log('Hotspots a visitor can see:', hotspots)
 
 	embed.on('camera_changed', ({ cameraId }) => {
 		console.log('Camera changed to:', cameraId)
@@ -62,42 +63,33 @@ For production, pin a version (`@vctrl/embed@<version>`) and add a [Subresource
 | `iframeOrigin` | `string` | Auto-detected from `iframe.src` | Expected iframe origin for postMessage security. |
 | `readyTimeout` | `number` | `15000`                         | ms before `ready()` rejects.                     |
 
-### Methods
-
-| Method                           | Description                                                    |
-| -------------------------------- | -------------------------------------------------------------- |
-| `ready()`                        | Resolves with `{ sceneId, cameras }` when the viewer is ready. |
-| `activateCamera(cameraId)`       | Switch to a named camera.                                      |
-| `setTransition(options)`         | Override transition type, duration, and easing.                |
-| `setControlsEnabled(enabled)`    | Enable or disable orbit controls.                              |
-| `setAutoRotate(enabled, speed?)` | Toggle auto-rotate.                                            |
-| `setZoomEnabled(enabled)`        | Toggle scroll-zoom.                                            |
-| `setPanEnabled(enabled)`         | Toggle right-click pan.                                        |
-| `sendScrollProgress(progress)`   | Drive scroll-triggered interactions (0–1).                     |
-| `sendMessage(message, payload?)` | Trigger a named `host_message` interaction.                    |
-| `on(type, handler)`              | Subscribe to a viewer event. Returns unsubscribe.              |
-| `off(type, handler)`             | Remove a specific handler.                                     |
-| `destroy()`                      | Remove all listeners and stop processing messages.             |
-
-### Events
-
-| Type                  | Payload                                   | When                                                    |
-| --------------------- | ----------------------------------------- | ------------------------------------------------------- |
-| `viewer_ready`        | `void`                                    | Viewer command surface is registered.                   |
-| `model_loaded`        | `void`                                    | Model finished loading and initial framing is complete. |
-| `camera_changed`      | `{ cameraId }`                            | Active camera changed.                                  |
-| `auto_rotate_changed` | `{ enabled }`                             | Auto-rotate state changed.                              |
-| `interaction_event`   | `{ eventName, interactionId?, payload? }` | Publisher custom event fired.                           |
+### What you can control
 
-## URL parameter shorthand
+Cameras and transitions, orbit/zoom/pan, animation playback, hotspots, scroll-driven
+interactions, and named host messages - plus events for each. The full method and event
+tables live in one place, the
+[Embed SDK guide](https://vectreal.com/docs/guides/embed-sdk#api-reference), rather than
+being repeated here where the two copies drift apart.
+
+Two behaviours worth knowing before you read it:
+
+The camera, controls, hotspot and animation methods are queued and flushed once the
+viewer reports ready, so you can call them immediately after constructing the SDK.
+`sendScrollProgress` and `sendMessage` are not queued: they post straight to the iframe,
+and a call made before the viewer is ready is silently dropped. Await `ready()` before
+wiring a scroll handler or sending a host message. `destroy()` discards anything still
+queued.
 
-For static initial configuration without JavaScript, add query parameters to the iframe `src`:
+The constructor throws when it cannot determine a target origin, which happens when
+`iframeOrigin` is omitted and the iframe's `src` is empty or unparseable. Construct the
+SDK after the `src` is set, or pass `iframeOrigin` explicitly.
+
+## URL parameter shorthand
 
-| Parameter            | Example              | Effect                                |
-| -------------------- | -------------------- | ------------------------------------- |
-| `?camera=<id>`       | `?camera=hero`       | Activates a camera on `viewer_ready`. |
-| `?autoRotate=0`      | `?autoRotate=1`      | Overrides stored auto-rotate state.   |
-| `?transition=<type>` | `?transition=linear` | Overrides stored transition type.     |
+Opening state, color scheme and hotspot presentation can be set with query parameters on the iframe
+`src`, no JavaScript required — `?camera`, `?autoRotate`, `?transition`, `?theme`,
+`?hotspots`, `?hotspotContent` and `?hotspotColor`. Values and behaviour are tabled once, in the
+[Embed SDK guide](https://vectreal.com/docs/guides/embed-sdk#url-parameters).
 
 ## Documentation
 
@@ -105,6 +97,6 @@ Full guide and examples: [vectreal.com/docs/guides/embed-sdk](https://vectreal.c
 
 ## License
 
-AGPL-3.0-only — see [LICENSE](https://github.com/vectreal/vectreal-platform/blob/main/LICENSE).
+AGPL-3.0-only. See [LICENSE.md](https://github.com/Vectreal/vectreal-platform/blob/main/LICENSE.md).
 
 Part of the [Vectreal Platform](https://github.com/vectreal/vectreal-platform) monorepo.

package/embed.d.ts

@@ -1,4 +1,4 @@
-import { EmbedCameraDescriptor } from './protocol';
+import { EmbedCameraDescriptor, EmbedHotspotDescriptor } from './protocol';
 export interface EmbedOptions {
     /** Override the detected iframe origin for postMessage targeting. */
     iframeOrigin?: string;
@@ -8,6 +8,11 @@ export interface EmbedOptions {
 export interface EmbedReadyInfo {
     sceneId: string | undefined;
     cameras: EmbedCameraDescriptor[];
+    /**
+     * The hotspots a visitor can see. Empty for a scene with none, and also for
+     * an iframe older than this field - see `HostedPreviewPongMessage`.
+     */
+    hotspots: EmbedHotspotDescriptor[];
 }
 export interface SetTransitionOptions {
     type: 'none' | 'linear' | 'object_avoidance';
@@ -23,6 +28,20 @@ export type EmbedEventMap = {
     auto_rotate_changed: {
         enabled: boolean;
     };
+    animation_state_changed: {
+        playing: boolean;
+        /** The clip driving a sequence; null in simultaneous mode. */
+        activeClipId: string | null;
+        /** True once the program has run to its end without looping. */
+        complete: boolean;
+    };
+    animation_clip_finished: {
+        clipId: string;
+    };
+    hotspot_activated: {
+        hotspotId: string;
+        cameraId: string | null;
+    };
     interaction_event: {
         interactionId?: string;
         eventName: string;
@@ -50,6 +69,15 @@ export declare class VectrealEmbed {
     destroy(): void;
     /** Switch to a named camera. */
     activateCamera(cameraId: string): void;
+    /**
+     * Focus a hotspot: reveal what it says and fly its camera, as clicking the
+     * marker would.
+     *
+     * Ids come from `ready()`, which reports only the hotspots a visitor can
+     * see. A hotspot the author hid or kept internal is not drawn, and naming
+     * one here does nothing.
+     */
+    focusHotspot(hotspotId: string): void;
     /** Override the transition behaviour for subsequent camera switches. */
     setTransition(options: SetTransitionOptions): void;
     /** Enable or disable orbit controls. */
@@ -60,6 +88,10 @@ export declare class VectrealEmbed {
     setZoomEnabled(enabled: boolean): void;
     /** Toggle right-click pan. */
     setPanEnabled(enabled: boolean): void;
+    /** Start or suspend playback of the scene's animation clips. */
+    setAnimationPlaying(playing: boolean): void;
+    /** Play the animation program again from the beginning. */
+    restartAnimation(): void;
     /**
      * Drive scroll-triggered interactions defined in the Publisher.
      * @param progress 0 (page top) – 1 (page bottom)
@@ -75,6 +107,7 @@ export declare class VectrealEmbed {
     off<K extends EmbedEventType>(type: K, handler: EmbedEventHandler<K>): void;
     private sceneId;
     private cameras;
+    private hotspots;
     private sendCommand;
     private postToIframe;
     private startPingPolling;

package/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=`vectreal-host`,t=`vectreal-preview`;function n(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function r(e){if(!n(e)||typeof e.type!=`string`)return!1;switch(e.type){case`activate_camera`:return typeof e.cameraId==`string`&&e.cameraId.trim().length>0;case`set_controls_enabled`:return typeof e.enabled==`boolean`;case`set_auto_rotate`:return typeof e.enabled==`boolean`&&(e.speed===void 0||typeof e.speed==`number`);case`set_controls_options`:return(e.zoom===void 0||typeof e.zoom==`boolean`)&&(e.pan===void 0||typeof e.pan==`boolean`);case`set_transition`:return typeof e.transitionType==`string`&&[`none`,`linear`,`object_avoidance`].includes(e.transitionType);default:return!1}}function i(e){if(!n(e)||e.source!==`vectreal-host`||typeof e.type!=`string`)return!1;switch(e.type){case`ping`:return!0;case`viewer_command`:return r(e.command);case`host_scroll_progress`:return typeof e.progress==`number`&&Number.isFinite(e.progress);case`host_message`:return typeof e.message==`string`&&e.message.trim().length>0&&(e.payload===void 0||n(e.payload));default:return!1}}var a=15e3,o=class{constructor(e,t={}){this.handlers=new Map,this.pendingCommands=[],this.isReady=!1,this.pingIntervalId=null,this.sceneId=void 0,this.cameras=[],this.iframe=e,this.readyTimeout=t.readyTimeout??a;let n=e.src||e.getAttribute(`src`)||``,r;if(n)try{r=new URL(n,window.location.href).origin}catch{}if(!t.iframeOrigin&&!r)throw Error(`VectrealEmbed: cannot determine iframe origin from src. Pass options.iframeOrigin explicitly.`);this.targetOrigin=t.iframeOrigin??r,this.boundListener=this.handleMessage.bind(this),window.addEventListener(`message`,this.boundListener),this.startPingPolling()}ready(){return new Promise((e,t)=>{let n=window.setTimeout(()=>{this.off(`viewer_ready`,r),t(Error(`VectrealEmbed: viewer did not become ready within ${this.readyTimeout}ms`))},this.readyTimeout),r=()=>{window.clearTimeout(n),e({sceneId:this.sceneId,cameras:this.cameras})};if(this.isReady){window.clearTimeout(n),e({sceneId:this.sceneId,cameras:this.cameras});return}this.on(`viewer_ready`,r)})}destroy(){this.stopPingPolling(),window.removeEventListener(`message`,this.boundListener),this.handlers.clear(),this.pendingCommands=[]}activateCamera(e){this.sendCommand({type:`activate_camera`,cameraId:e})}setTransition(e){this.sendCommand({type:`set_transition`,transitionType:e.type,duration:e.duration,easing:e.easing})}setControlsEnabled(e){this.sendCommand({type:`set_controls_enabled`,enabled:e})}setAutoRotate(e,t){this.sendCommand({type:`set_auto_rotate`,enabled:e,speed:t})}setZoomEnabled(e){this.sendCommand({type:`set_controls_options`,zoom:e})}setPanEnabled(e){this.sendCommand({type:`set_controls_options`,pan:e})}sendScrollProgress(t){this.postToIframe({source:e,type:`host_scroll_progress`,progress:Math.min(1,Math.max(0,t))})}sendMessage(t,n){this.postToIframe({source:e,type:`host_message`,message:t,payload:n})}on(e,t){return this.handlers.has(e)||this.handlers.set(e,new Set),this.handlers.get(e).add(t),()=>this.off(e,t)}off(e,t){this.handlers.get(e)?.delete(t)}sendCommand(t){let n={source:e,type:`viewer_command`,command:t};if(!this.isReady){this.pendingCommands.push(n);return}this.postToIframe(n)}postToIframe(e){try{this.iframe.contentWindow?.postMessage(e,this.targetOrigin)}catch{}}startPingPolling(){this.postToIframe({source:e,type:`ping`}),this.pingIntervalId=window.setInterval(()=>{if(this.isReady){this.stopPingPolling();return}this.postToIframe({source:e,type:`ping`})},500)}stopPingPolling(){this.pingIntervalId!==null&&(window.clearInterval(this.pingIntervalId),this.pingIntervalId=null)}flushPendingCommands(){for(let e of this.pendingCommands)this.postToIframe(e);this.pendingCommands=[]}emit(e,t){this.handlers.get(e)?.forEach(e=>{e(t)})}handleMessage(e){let t=e.data;if(!(!t||typeof t!=`object`||t.source!==`vectreal-preview`)&&!(this.targetOrigin!==`*`&&e.origin!==this.targetOrigin))switch(t.type){case`pong`:this.stopPingPolling(),this.sceneId=t.sceneId,this.cameras=t.cameras,this.isReady=!0,this.flushPendingCommands();break;case`viewer_event`:this.handleViewerEvent(t.event);break;case`interaction_event`:this.emit(`interaction_event`,{interactionId:t.interactionId,eventName:t.eventName,payload:t.payload});break}}handleViewerEvent(e){switch(e.type){case`viewer_ready`:this.isReady=!0,this.flushPendingCommands(),this.emit(`viewer_ready`,void 0);break;case`model_loaded`:this.emit(`model_loaded`,void 0);break;case`camera_changed`:this.emit(`camera_changed`,{cameraId:e.cameraId});break;case`auto_rotate_changed`:this.emit(`auto_rotate_changed`,{enabled:e.enabled});break;case`initial_framing_completed`:this.emit(`model_loaded`,void 0);break}}};exports.HOSTED_PREVIEW_HOST_SOURCE=e,exports.HOSTED_PREVIEW_VIEWER_SOURCE=t,exports.VectrealEmbed=o,exports.isHostedPreviewIncomingMessage=i,exports.isViewerCommand=r;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=`vectreal-host`,t=`vectreal-preview`;function n(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function r(e){if(!n(e)||typeof e.type!=`string`)return!1;switch(e.type){case`activate_camera`:return typeof e.cameraId==`string`&&e.cameraId.trim().length>0;case`focus_hotspot`:return typeof e.hotspotId==`string`&&e.hotspotId.trim().length>0;case`set_controls_enabled`:return typeof e.enabled==`boolean`;case`set_auto_rotate`:return typeof e.enabled==`boolean`&&(e.speed===void 0||typeof e.speed==`number`);case`set_controls_options`:return(e.zoom===void 0||typeof e.zoom==`boolean`)&&(e.pan===void 0||typeof e.pan==`boolean`);case`set_transition`:return typeof e.transitionType==`string`&&[`none`,`linear`,`object_avoidance`].includes(e.transitionType);case`set_animation_playing`:return typeof e.playing==`boolean`;case`restart_animation`:return!0;case`seek_animation_clip`:return typeof e.clipId==`string`&&e.clipId.trim().length>0&&typeof e.time==`number`&&Number.isFinite(e.time)&&e.time>=0;default:return!1}}function i(e){if(!n(e)||e.source!==`vectreal-host`||typeof e.type!=`string`)return!1;switch(e.type){case`ping`:return!0;case`viewer_command`:return r(e.command);case`host_scroll_progress`:return typeof e.progress==`number`&&Number.isFinite(e.progress);case`host_message`:return typeof e.message==`string`&&e.message.trim().length>0&&(e.payload===void 0||n(e.payload));default:return!1}}var a=15e3,o=class{constructor(e,t={}){this.handlers=new Map,this.pendingCommands=[],this.isReady=!1,this.pingIntervalId=null,this.sceneId=void 0,this.cameras=[],this.hotspots=[],this.iframe=e,this.readyTimeout=t.readyTimeout??a;let n=e.src||e.getAttribute(`src`)||``,r;if(n)try{r=new URL(n,window.location.href).origin}catch{}if(!t.iframeOrigin&&!r)throw Error(`VectrealEmbed: cannot determine iframe origin from src. Pass options.iframeOrigin explicitly.`);this.targetOrigin=t.iframeOrigin??r,this.boundListener=this.handleMessage.bind(this),window.addEventListener(`message`,this.boundListener),this.startPingPolling()}ready(){return new Promise((e,t)=>{let n=window.setTimeout(()=>{this.off(`viewer_ready`,r),t(Error(`VectrealEmbed: viewer did not become ready within ${this.readyTimeout}ms`))},this.readyTimeout),r=()=>{window.clearTimeout(n),e({sceneId:this.sceneId,cameras:this.cameras,hotspots:this.hotspots})};if(this.isReady){window.clearTimeout(n),e({sceneId:this.sceneId,cameras:this.cameras,hotspots:this.hotspots});return}this.on(`viewer_ready`,r)})}destroy(){this.stopPingPolling(),window.removeEventListener(`message`,this.boundListener),this.handlers.clear(),this.pendingCommands=[]}activateCamera(e){this.sendCommand({type:`activate_camera`,cameraId:e})}focusHotspot(e){this.sendCommand({type:`focus_hotspot`,hotspotId:e})}setTransition(e){this.sendCommand({type:`set_transition`,transitionType:e.type,duration:e.duration,easing:e.easing})}setControlsEnabled(e){this.sendCommand({type:`set_controls_enabled`,enabled:e})}setAutoRotate(e,t){this.sendCommand({type:`set_auto_rotate`,enabled:e,speed:t})}setZoomEnabled(e){this.sendCommand({type:`set_controls_options`,zoom:e})}setPanEnabled(e){this.sendCommand({type:`set_controls_options`,pan:e})}setAnimationPlaying(e){this.sendCommand({type:`set_animation_playing`,playing:e})}restartAnimation(){this.sendCommand({type:`restart_animation`})}sendScrollProgress(t){this.postToIframe({source:e,type:`host_scroll_progress`,progress:Math.min(1,Math.max(0,t))})}sendMessage(t,n){this.postToIframe({source:e,type:`host_message`,message:t,payload:n})}on(e,t){return this.handlers.has(e)||this.handlers.set(e,new Set),this.handlers.get(e).add(t),()=>this.off(e,t)}off(e,t){this.handlers.get(e)?.delete(t)}sendCommand(t){let n={source:e,type:`viewer_command`,command:t};if(!this.isReady){this.pendingCommands.push(n);return}this.postToIframe(n)}postToIframe(e){try{this.iframe.contentWindow?.postMessage(e,this.targetOrigin)}catch{}}startPingPolling(){this.postToIframe({source:e,type:`ping`}),this.pingIntervalId=window.setInterval(()=>{if(this.isReady){this.stopPingPolling();return}this.postToIframe({source:e,type:`ping`})},500)}stopPingPolling(){this.pingIntervalId!==null&&(window.clearInterval(this.pingIntervalId),this.pingIntervalId=null)}flushPendingCommands(){for(let e of this.pendingCommands)this.postToIframe(e);this.pendingCommands=[]}emit(e,t){this.handlers.get(e)?.forEach(e=>{e(t)})}handleMessage(e){let t=e.data;if(!(!t||typeof t!=`object`||t.source!==`vectreal-preview`)&&(this.targetOrigin===`*`||e.origin===this.targetOrigin))switch(t.type){case`pong`:this.stopPingPolling(),this.sceneId=t.sceneId,this.cameras=t.cameras,this.hotspots=t.hotspots??[],this.isReady=!0,this.flushPendingCommands();break;case`viewer_event`:this.handleViewerEvent(t.event);break;case`interaction_event`:this.emit(`interaction_event`,{interactionId:t.interactionId,eventName:t.eventName,payload:t.payload})}}handleViewerEvent(e){switch(e.type){case`viewer_ready`:this.isReady=!0,this.flushPendingCommands(),this.emit(`viewer_ready`,void 0);break;case`model_loaded`:this.emit(`model_loaded`,void 0);break;case`camera_changed`:this.emit(`camera_changed`,{cameraId:e.cameraId});break;case`hotspot_activated`:this.emit(`hotspot_activated`,{hotspotId:e.hotspotId,cameraId:e.cameraId});break;case`auto_rotate_changed`:this.emit(`auto_rotate_changed`,{enabled:e.enabled});break;case`animation_state_changed`:this.emit(`animation_state_changed`,{playing:e.playing,activeClipId:e.activeClipId,complete:e.complete});break;case`animation_clip_finished`:this.emit(`animation_clip_finished`,{clipId:e.clipId});break;case`initial_framing_completed`:this.emit(`model_loaded`,void 0)}}};exports.HOSTED_PREVIEW_HOST_SOURCE=e,exports.HOSTED_PREVIEW_VIEWER_SOURCE=t,exports.VectrealEmbed=o,exports.isHostedPreviewIncomingMessage=i,exports.isViewerCommand=r;

package/index.d.ts

@@ -1,4 +1,4 @@
 export { VectrealEmbed } from './embed';
 export type { EmbedEventHandler, EmbedEventMap, EmbedEventType, EmbedOptions, EmbedReadyInfo, SetTransitionOptions } from './embed';
 export { HOSTED_PREVIEW_HOST_SOURCE, HOSTED_PREVIEW_VIEWER_SOURCE, isHostedPreviewIncomingMessage, isViewerCommand } from './protocol';
-export type { EmbedCameraDescriptor, HostedPreviewCustomEventMessage, HostedPreviewHostMessage, HostedPreviewIncomingMessage, HostedPreviewOutgoingMessage, HostedPreviewPingMessage, HostedPreviewPongMessage, HostedPreviewScrollProgressMessage, HostedPreviewViewerCommandMessage, HostedPreviewViewerEventMessage } from './protocol';
+export type { EmbedCameraDescriptor, EmbedHotspotDescriptor, HostedPreviewCustomEventMessage, HostedPreviewHostMessage, HostedPreviewIncomingMessage, HostedPreviewOutgoingMessage, HostedPreviewPingMessage, HostedPreviewPongMessage, HostedPreviewScrollProgressMessage, HostedPreviewViewerCommandMessage, HostedPreviewViewerEventMessage } from './protocol';

package/index.js

@@ -7,6 +7,7 @@ function r(e) {
 	if (!n(e) || typeof e.type != "string") return !1;
 	switch (e.type) {
 		case "activate_camera": return typeof e.cameraId == "string" && e.cameraId.trim().length > 0;
+		case "focus_hotspot": return typeof e.hotspotId == "string" && e.hotspotId.trim().length > 0;
 		case "set_controls_enabled": return typeof e.enabled == "boolean";
 		case "set_auto_rotate": return typeof e.enabled == "boolean" && (e.speed === void 0 || typeof e.speed == "number");
 		case "set_controls_options": return (e.zoom === void 0 || typeof e.zoom == "boolean") && (e.pan === void 0 || typeof e.pan == "boolean");
@@ -15,6 +16,9 @@ function r(e) {
 			"linear",
 			"object_avoidance"
 		].includes(e.transitionType);
+		case "set_animation_playing": return typeof e.playing == "boolean";
+		case "restart_animation": return !0;
+		case "seek_animation_clip": return typeof e.clipId == "string" && e.clipId.trim().length > 0 && typeof e.time == "number" && Number.isFinite(e.time) && e.time >= 0;
 		default: return !1;
 	}
 }
@@ -30,9 +34,9 @@ function i(e) {
 }
 //#endregion
 //#region packages/embed/src/embed.ts
-var a = 15e3, o = class {
+var a = class {
 	constructor(e, t = {}) {
-		this.handlers = /* @__PURE__ */ new Map(), this.pendingCommands = [], this.isReady = !1, this.pingIntervalId = null, this.sceneId = void 0, this.cameras = [], this.iframe = e, this.readyTimeout = t.readyTimeout ?? a;
+		this.handlers = /* @__PURE__ */ new Map(), this.pendingCommands = [], this.isReady = !1, this.pingIntervalId = null, this.sceneId = void 0, this.cameras = [], this.hotspots = [], this.iframe = e, this.readyTimeout = t.readyTimeout ?? 15e3;
 		let n = e.src || e.getAttribute("src") || "", r;
 		if (n) try {
 			r = new URL(n, window.location.href).origin;
@@ -47,13 +51,15 @@ var a = 15e3, o = class {
 			}, this.readyTimeout), r = () => {
 				window.clearTimeout(n), e({
 					sceneId: this.sceneId,
-					cameras: this.cameras
+					cameras: this.cameras,
+					hotspots: this.hotspots
 				});
 			};
 			if (this.isReady) {
 				window.clearTimeout(n), e({
 					sceneId: this.sceneId,
-					cameras: this.cameras
+					cameras: this.cameras,
+					hotspots: this.hotspots
 				});
 				return;
 			}
@@ -69,6 +75,12 @@ var a = 15e3, o = class {
 			cameraId: e
 		});
 	}
+	focusHotspot(e) {
+		this.sendCommand({
+			type: "focus_hotspot",
+			hotspotId: e
+		});
+	}
 	setTransition(e) {
 		this.sendCommand({
 			type: "set_transition",
@@ -102,6 +114,15 @@ var a = 15e3, o = class {
 			pan: e
 		});
 	}
+	setAnimationPlaying(e) {
+		this.sendCommand({
+			type: "set_animation_playing",
+			playing: e
+		});
+	}
+	restartAnimation() {
+		this.sendCommand({ type: "restart_animation" });
+	}
 	sendScrollProgress(t) {
 		this.postToIframe({
 			source: e,
@@ -169,20 +190,18 @@ var a = 15e3, o = class {
 	}
 	handleMessage(e) {
 		let t = e.data;
-		if (!(!t || typeof t != "object" || t.source !== "vectreal-preview") && !(this.targetOrigin !== "*" && e.origin !== this.targetOrigin)) switch (t.type) {
+		if (!(!t || typeof t != "object" || t.source !== "vectreal-preview") && (this.targetOrigin === "*" || e.origin === this.targetOrigin)) switch (t.type) {
 			case "pong":
-				this.stopPingPolling(), this.sceneId = t.sceneId, this.cameras = t.cameras, this.isReady = !0, this.flushPendingCommands();
+				this.stopPingPolling(), this.sceneId = t.sceneId, this.cameras = t.cameras, this.hotspots = t.hotspots ?? [], this.isReady = !0, this.flushPendingCommands();
 				break;
 			case "viewer_event":
 				this.handleViewerEvent(t.event);
 				break;
-			case "interaction_event":
-				this.emit("interaction_event", {
-					interactionId: t.interactionId,
-					eventName: t.eventName,
-					payload: t.payload
-				});
-				break;
+			case "interaction_event": this.emit("interaction_event", {
+				interactionId: t.interactionId,
+				eventName: t.eventName,
+				payload: t.payload
+			});
 		}
 	}
 	handleViewerEvent(e) {
@@ -196,14 +215,28 @@ var a = 15e3, o = class {
 			case "camera_changed":
 				this.emit("camera_changed", { cameraId: e.cameraId });
 				break;
+			case "hotspot_activated":
+				this.emit("hotspot_activated", {
+					hotspotId: e.hotspotId,
+					cameraId: e.cameraId
+				});
+				break;
 			case "auto_rotate_changed":
 				this.emit("auto_rotate_changed", { enabled: e.enabled });
 				break;
-			case "initial_framing_completed":
-				this.emit("model_loaded", void 0);
+			case "animation_state_changed":
+				this.emit("animation_state_changed", {
+					playing: e.playing,
+					activeClipId: e.activeClipId,
+					complete: e.complete
+				});
+				break;
+			case "animation_clip_finished":
+				this.emit("animation_clip_finished", { clipId: e.clipId });
 				break;
+			case "initial_framing_completed": this.emit("model_loaded", void 0);
 		}
 	}
 };
 //#endregion
-export { e as HOSTED_PREVIEW_HOST_SOURCE, t as HOSTED_PREVIEW_VIEWER_SOURCE, o as VectrealEmbed, i as isHostedPreviewIncomingMessage, r as isViewerCommand };
+export { e as HOSTED_PREVIEW_HOST_SOURCE, t as HOSTED_PREVIEW_VIEWER_SOURCE, a as VectrealEmbed, i as isHostedPreviewIncomingMessage, r as isViewerCommand };

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.25.0",
+  "version": "1.0.0",
   "name": "@vctrl/embed",
   "description": "Framework-agnostic JavaScript SDK for controlling Vectreal embedded 3D scene previews via postMessage.",
   "bugs": {
@@ -29,7 +29,8 @@
   "type": "module",
   "sideEffects": false,
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "directory": "../../build/packages/vctrl/embed"
   },
   "exports": {
     ".": {
@@ -37,5 +38,8 @@
       "import": "./index.js",
       "require": "./index.cjs"
     }
+  },
+  "devDependencies": {
+    "@vctrl/viewer": "^1.0.0"
   }
 }

package/protocol.d.ts

@@ -27,11 +27,36 @@ export interface EmbedCameraDescriptor {
     name: string;
     fov?: number;
 }
+/**
+ * One hotspot, as a host page sees it.
+ *
+ * Carries no body, no link and no world position: a host builds navigation
+ * from these, and the content is what the viewer draws. Adding the text here
+ * would put a second copy of it on the page with nothing keeping the two in
+ * step.
+ */
+export interface EmbedHotspotDescriptor {
+    id: string;
+    name: string;
+    /** The camera this hotspot flies, or null when it only reveals content. */
+    cameraId: string | null;
+    /** 1-based place in the navigation sequence, or null when it has none. */
+    step: number | null;
+}
 export interface HostedPreviewPongMessage {
     source: typeof HOSTED_PREVIEW_VIEWER_SOURCE;
     type: 'pong';
     sceneId?: string;
     cameras: EmbedCameraDescriptor[];
+    /**
+     * Optional, unlike `cameras`.
+     *
+     * An iframe and the SDK on the page around it are two separately deployed
+     * artifacts and can be versions apart. A required field here would make an
+     * older iframe's pong fail a newer SDK's parse, and the host would then hang
+     * waiting for a handshake that already arrived.
+     */
+    hotspots?: EmbedHotspotDescriptor[];
 }
 export interface HostedPreviewViewerEventMessage {
     source: typeof HOSTED_PREVIEW_VIEWER_SOURCE;

package/vectreal-embed.umd.js

@@ -1 +1 @@
-(function(e,t){typeof exports==`object`&&typeof module<`u`?t(exports):typeof define==`function`&&define.amd?define([`exports`],t):(e=typeof globalThis<`u`?globalThis:e||self,t(e.VectrealEmbed={}))})(this,function(e){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`});var t=`vectreal-host`,n=`vectreal-preview`;function r(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function i(e){if(!r(e)||typeof e.type!=`string`)return!1;switch(e.type){case`activate_camera`:return typeof e.cameraId==`string`&&e.cameraId.trim().length>0;case`set_controls_enabled`:return typeof e.enabled==`boolean`;case`set_auto_rotate`:return typeof e.enabled==`boolean`&&(e.speed===void 0||typeof e.speed==`number`);case`set_controls_options`:return(e.zoom===void 0||typeof e.zoom==`boolean`)&&(e.pan===void 0||typeof e.pan==`boolean`);case`set_transition`:return typeof e.transitionType==`string`&&[`none`,`linear`,`object_avoidance`].includes(e.transitionType);default:return!1}}function a(e){if(!r(e)||e.source!==`vectreal-host`||typeof e.type!=`string`)return!1;switch(e.type){case`ping`:return!0;case`viewer_command`:return i(e.command);case`host_scroll_progress`:return typeof e.progress==`number`&&Number.isFinite(e.progress);case`host_message`:return typeof e.message==`string`&&e.message.trim().length>0&&(e.payload===void 0||r(e.payload));default:return!1}}var o=15e3,s=class{constructor(e,t={}){this.handlers=new Map,this.pendingCommands=[],this.isReady=!1,this.pingIntervalId=null,this.sceneId=void 0,this.cameras=[],this.iframe=e,this.readyTimeout=t.readyTimeout??o;let n=e.src||e.getAttribute(`src`)||``,r;if(n)try{r=new URL(n,window.location.href).origin}catch{}if(!t.iframeOrigin&&!r)throw Error(`VectrealEmbed: cannot determine iframe origin from src. Pass options.iframeOrigin explicitly.`);this.targetOrigin=t.iframeOrigin??r,this.boundListener=this.handleMessage.bind(this),window.addEventListener(`message`,this.boundListener),this.startPingPolling()}ready(){return new Promise((e,t)=>{let n=window.setTimeout(()=>{this.off(`viewer_ready`,r),t(Error(`VectrealEmbed: viewer did not become ready within ${this.readyTimeout}ms`))},this.readyTimeout),r=()=>{window.clearTimeout(n),e({sceneId:this.sceneId,cameras:this.cameras})};if(this.isReady){window.clearTimeout(n),e({sceneId:this.sceneId,cameras:this.cameras});return}this.on(`viewer_ready`,r)})}destroy(){this.stopPingPolling(),window.removeEventListener(`message`,this.boundListener),this.handlers.clear(),this.pendingCommands=[]}activateCamera(e){this.sendCommand({type:`activate_camera`,cameraId:e})}setTransition(e){this.sendCommand({type:`set_transition`,transitionType:e.type,duration:e.duration,easing:e.easing})}setControlsEnabled(e){this.sendCommand({type:`set_controls_enabled`,enabled:e})}setAutoRotate(e,t){this.sendCommand({type:`set_auto_rotate`,enabled:e,speed:t})}setZoomEnabled(e){this.sendCommand({type:`set_controls_options`,zoom:e})}setPanEnabled(e){this.sendCommand({type:`set_controls_options`,pan:e})}sendScrollProgress(e){this.postToIframe({source:t,type:`host_scroll_progress`,progress:Math.min(1,Math.max(0,e))})}sendMessage(e,n){this.postToIframe({source:t,type:`host_message`,message:e,payload:n})}on(e,t){return this.handlers.has(e)||this.handlers.set(e,new Set),this.handlers.get(e).add(t),()=>this.off(e,t)}off(e,t){this.handlers.get(e)?.delete(t)}sendCommand(e){let n={source:t,type:`viewer_command`,command:e};if(!this.isReady){this.pendingCommands.push(n);return}this.postToIframe(n)}postToIframe(e){try{this.iframe.contentWindow?.postMessage(e,this.targetOrigin)}catch{}}startPingPolling(){this.postToIframe({source:t,type:`ping`}),this.pingIntervalId=window.setInterval(()=>{if(this.isReady){this.stopPingPolling();return}this.postToIframe({source:t,type:`ping`})},500)}stopPingPolling(){this.pingIntervalId!==null&&(window.clearInterval(this.pingIntervalId),this.pingIntervalId=null)}flushPendingCommands(){for(let e of this.pendingCommands)this.postToIframe(e);this.pendingCommands=[]}emit(e,t){this.handlers.get(e)?.forEach(e=>{e(t)})}handleMessage(e){let t=e.data;if(!(!t||typeof t!=`object`||t.source!==`vectreal-preview`)&&!(this.targetOrigin!==`*`&&e.origin!==this.targetOrigin))switch(t.type){case`pong`:this.stopPingPolling(),this.sceneId=t.sceneId,this.cameras=t.cameras,this.isReady=!0,this.flushPendingCommands();break;case`viewer_event`:this.handleViewerEvent(t.event);break;case`interaction_event`:this.emit(`interaction_event`,{interactionId:t.interactionId,eventName:t.eventName,payload:t.payload});break}}handleViewerEvent(e){switch(e.type){case`viewer_ready`:this.isReady=!0,this.flushPendingCommands(),this.emit(`viewer_ready`,void 0);break;case`model_loaded`:this.emit(`model_loaded`,void 0);break;case`camera_changed`:this.emit(`camera_changed`,{cameraId:e.cameraId});break;case`auto_rotate_changed`:this.emit(`auto_rotate_changed`,{enabled:e.enabled});break;case`initial_framing_completed`:this.emit(`model_loaded`,void 0);break}}};e.HOSTED_PREVIEW_HOST_SOURCE=t,e.HOSTED_PREVIEW_VIEWER_SOURCE=n,e.VectrealEmbed=s,e.isHostedPreviewIncomingMessage=a,e.isViewerCommand=i});
+(function(e,t){typeof exports==`object`&&typeof module<`u`?t(exports):typeof define==`function`&&define.amd?define([`exports`],t):(e=typeof globalThis<`u`?globalThis:e||self,t(e.VectrealEmbed={}))})(this,function(e){Object.defineProperty(e,Symbol.toStringTag,{value:`Module`});var t=`vectreal-host`,n=`vectreal-preview`;function r(e){return typeof e==`object`&&!!e&&!Array.isArray(e)}function i(e){if(!r(e)||typeof e.type!=`string`)return!1;switch(e.type){case`activate_camera`:return typeof e.cameraId==`string`&&e.cameraId.trim().length>0;case`focus_hotspot`:return typeof e.hotspotId==`string`&&e.hotspotId.trim().length>0;case`set_controls_enabled`:return typeof e.enabled==`boolean`;case`set_auto_rotate`:return typeof e.enabled==`boolean`&&(e.speed===void 0||typeof e.speed==`number`);case`set_controls_options`:return(e.zoom===void 0||typeof e.zoom==`boolean`)&&(e.pan===void 0||typeof e.pan==`boolean`);case`set_transition`:return typeof e.transitionType==`string`&&[`none`,`linear`,`object_avoidance`].includes(e.transitionType);case`set_animation_playing`:return typeof e.playing==`boolean`;case`restart_animation`:return!0;case`seek_animation_clip`:return typeof e.clipId==`string`&&e.clipId.trim().length>0&&typeof e.time==`number`&&Number.isFinite(e.time)&&e.time>=0;default:return!1}}function a(e){if(!r(e)||e.source!==`vectreal-host`||typeof e.type!=`string`)return!1;switch(e.type){case`ping`:return!0;case`viewer_command`:return i(e.command);case`host_scroll_progress`:return typeof e.progress==`number`&&Number.isFinite(e.progress);case`host_message`:return typeof e.message==`string`&&e.message.trim().length>0&&(e.payload===void 0||r(e.payload));default:return!1}}var o=15e3,s=class{constructor(e,t={}){this.handlers=new Map,this.pendingCommands=[],this.isReady=!1,this.pingIntervalId=null,this.sceneId=void 0,this.cameras=[],this.hotspots=[],this.iframe=e,this.readyTimeout=t.readyTimeout??o;let n=e.src||e.getAttribute(`src`)||``,r;if(n)try{r=new URL(n,window.location.href).origin}catch{}if(!t.iframeOrigin&&!r)throw Error(`VectrealEmbed: cannot determine iframe origin from src. Pass options.iframeOrigin explicitly.`);this.targetOrigin=t.iframeOrigin??r,this.boundListener=this.handleMessage.bind(this),window.addEventListener(`message`,this.boundListener),this.startPingPolling()}ready(){return new Promise((e,t)=>{let n=window.setTimeout(()=>{this.off(`viewer_ready`,r),t(Error(`VectrealEmbed: viewer did not become ready within ${this.readyTimeout}ms`))},this.readyTimeout),r=()=>{window.clearTimeout(n),e({sceneId:this.sceneId,cameras:this.cameras,hotspots:this.hotspots})};if(this.isReady){window.clearTimeout(n),e({sceneId:this.sceneId,cameras:this.cameras,hotspots:this.hotspots});return}this.on(`viewer_ready`,r)})}destroy(){this.stopPingPolling(),window.removeEventListener(`message`,this.boundListener),this.handlers.clear(),this.pendingCommands=[]}activateCamera(e){this.sendCommand({type:`activate_camera`,cameraId:e})}focusHotspot(e){this.sendCommand({type:`focus_hotspot`,hotspotId:e})}setTransition(e){this.sendCommand({type:`set_transition`,transitionType:e.type,duration:e.duration,easing:e.easing})}setControlsEnabled(e){this.sendCommand({type:`set_controls_enabled`,enabled:e})}setAutoRotate(e,t){this.sendCommand({type:`set_auto_rotate`,enabled:e,speed:t})}setZoomEnabled(e){this.sendCommand({type:`set_controls_options`,zoom:e})}setPanEnabled(e){this.sendCommand({type:`set_controls_options`,pan:e})}setAnimationPlaying(e){this.sendCommand({type:`set_animation_playing`,playing:e})}restartAnimation(){this.sendCommand({type:`restart_animation`})}sendScrollProgress(e){this.postToIframe({source:t,type:`host_scroll_progress`,progress:Math.min(1,Math.max(0,e))})}sendMessage(e,n){this.postToIframe({source:t,type:`host_message`,message:e,payload:n})}on(e,t){return this.handlers.has(e)||this.handlers.set(e,new Set),this.handlers.get(e).add(t),()=>this.off(e,t)}off(e,t){this.handlers.get(e)?.delete(t)}sendCommand(e){let n={source:t,type:`viewer_command`,command:e};if(!this.isReady){this.pendingCommands.push(n);return}this.postToIframe(n)}postToIframe(e){try{this.iframe.contentWindow?.postMessage(e,this.targetOrigin)}catch{}}startPingPolling(){this.postToIframe({source:t,type:`ping`}),this.pingIntervalId=window.setInterval(()=>{if(this.isReady){this.stopPingPolling();return}this.postToIframe({source:t,type:`ping`})},500)}stopPingPolling(){this.pingIntervalId!==null&&(window.clearInterval(this.pingIntervalId),this.pingIntervalId=null)}flushPendingCommands(){for(let e of this.pendingCommands)this.postToIframe(e);this.pendingCommands=[]}emit(e,t){this.handlers.get(e)?.forEach(e=>{e(t)})}handleMessage(e){let t=e.data;if(!(!t||typeof t!=`object`||t.source!==`vectreal-preview`)&&(this.targetOrigin===`*`||e.origin===this.targetOrigin))switch(t.type){case`pong`:this.stopPingPolling(),this.sceneId=t.sceneId,this.cameras=t.cameras,this.hotspots=t.hotspots??[],this.isReady=!0,this.flushPendingCommands();break;case`viewer_event`:this.handleViewerEvent(t.event);break;case`interaction_event`:this.emit(`interaction_event`,{interactionId:t.interactionId,eventName:t.eventName,payload:t.payload})}}handleViewerEvent(e){switch(e.type){case`viewer_ready`:this.isReady=!0,this.flushPendingCommands(),this.emit(`viewer_ready`,void 0);break;case`model_loaded`:this.emit(`model_loaded`,void 0);break;case`camera_changed`:this.emit(`camera_changed`,{cameraId:e.cameraId});break;case`hotspot_activated`:this.emit(`hotspot_activated`,{hotspotId:e.hotspotId,cameraId:e.cameraId});break;case`auto_rotate_changed`:this.emit(`auto_rotate_changed`,{enabled:e.enabled});break;case`animation_state_changed`:this.emit(`animation_state_changed`,{playing:e.playing,activeClipId:e.activeClipId,complete:e.complete});break;case`animation_clip_finished`:this.emit(`animation_clip_finished`,{clipId:e.clipId});break;case`initial_framing_completed`:this.emit(`model_loaded`,void 0)}}};e.HOSTED_PREVIEW_HOST_SOURCE=t,e.HOSTED_PREVIEW_VIEWER_SOURCE=n,e.VectrealEmbed=s,e.isHostedPreviewIncomingMessage=a,e.isViewerCommand=i});