@vctrl/embed 0.22.0

package/README.md

@@ -0,0 +1,103 @@
+# @vctrl/embed
+
+[![npm](https://img.shields.io/npm/v/@vctrl/embed)](https://www.npmjs.com/package/@vctrl/embed)
+[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-orange.svg)](https://www.gnu.org/licenses/agpl-3.0)
+
+Framework-agnostic JavaScript SDK for controlling Vectreal embedded 3D scene previews from any web page.
+
+## Installation
+
+```bash
+npm install @vctrl/embed
+```
+
+**CDN (UMD — no bundler needed):**
+
+```html
+<script src="https://cdn.vectreal.com/embed/latest/vectreal-embed.umd.js"></script>
+```
+
+## Quick start
+
+```html
+<div style="width: 100%; height: 400px;">
+	<iframe
+		id="vectreal-scene"
+		src="https://vectreal.com/preview/fullscreen/<projectId>/<sceneId>?token=YOUR_PREVIEW_API_KEY"
+		style="width: 100%; height: 100%; border: 0;"
+		allow="autoplay; xr-spatial-tracking"
+		allowfullscreen
+	></iframe>
+</div>
+
+<script type="module">
+	import { VectrealEmbed } from '@vctrl/embed'
+
+	const embed = new VectrealEmbed(document.getElementById('vectreal-scene'))
+
+	const { cameras } = await embed.ready()
+	console.log('Available cameras:', cameras)
+
+	embed.on('camera_changed', ({ cameraId }) => {
+		console.log('Camera changed to:', cameraId)
+	})
+
+	embed.activateCamera('detail')
+</script>
+```
+
+## API
+
+### `new VectrealEmbed(iframe, options?)`
+
+| Option         | Type     | Default                         | Description                                      |
+| -------------- | -------- | ------------------------------- | ------------------------------------------------ |
+| `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.                           |
+
+## URL parameter shorthand
+
+For static initial configuration without JavaScript, add query parameters to the iframe `src`:
+
+| 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.     |
+
+## Documentation
+
+Full guide and examples: [vectreal.com/docs/guides/embed-sdk](https://vectreal.com/docs/guides/embed-sdk)
+
+## License
+
+AGPL-3.0-only — see [LICENSE](https://github.com/vectreal/vectreal-platform/blob/main/LICENSE).
+
+Part of the [Vectreal Platform](https://github.com/vectreal/vectreal-platform) monorepo.

package/package.json

@@ -0,0 +1,41 @@
+{
+  "version": "0.22.0",
+  "name": "@vctrl/embed",
+  "description": "Framework-agnostic JavaScript SDK for controlling Vectreal embedded 3D scene previews via postMessage.",
+  "bugs": {
+    "url": "https://github.com/vectreal/vectreal-platform/issues"
+  },
+  "homepage": "https://vectreal.com",
+  "keywords": [
+    "vectreal",
+    "3d",
+    "embed",
+    "sdk",
+    "iframe",
+    "postmessage",
+    "gltf",
+    "glb",
+    "model-viewer"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vectreal/vectreal-platform.git"
+  },
+  "license": "AGPL-3.0-only",
+  "main": "./index.cjs",
+  "module": "./index.js",
+  "browser": "./vectreal-embed.umd.js",
+  "types": "./index.d.ts",
+  "type": "module",
+  "sideEffects": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js",
+      "require": "./index.cjs"
+    }
+  }
+}

package/project.json

@@ -0,0 +1,63 @@
+{
+	"name": "vctrl/embed",
+	"$schema": "../../node_modules/nx/schemas/project-schema.json",
+	"sourceRoot": "packages/embed/src",
+	"projectType": "library",
+	"tags": [],
+	"targets": {
+		"lint": {
+			"executor": "@nx/eslint:lint",
+			"outputs": ["{options.outputFile}"],
+			"options": {
+				"fix": true,
+				"lintFilePatterns": [
+					"packages/embed/src/**/*.{ts,js}",
+					"packages/embed/vite.config.ts",
+					"packages/embed/package.json"
+				]
+			}
+		},
+		"typecheck": {
+			"executor": "nx:run-commands",
+			"outputs": [],
+			"options": {
+				"command": "tsc --noEmit -p packages/embed/tsconfig.json"
+			}
+		},
+		"build": {
+			"executor": "@nx/vite:build",
+			"outputs": ["{options.outputPath}"],
+			"options": {
+				"outputPath": "build/packages/vctrl/embed",
+				"configFile": "packages/embed/vite.config.ts"
+			}
+		},
+		"build-ci": {
+			"executor": "@nx/vite:build",
+			"outputs": ["{options.outputPath}"],
+			"options": {
+				"outputPath": "build/packages/vctrl/embed",
+				"configFile": "packages/embed/vite.config.ts"
+			}
+		},
+		"copy-md": {
+			"dependsOn": ["build"],
+			"executor": "nx:run-commands",
+			"outputs": [],
+			"options": {
+				"commands": [
+					"rsync -rat packages/embed/*.md build/packages/vctrl/embed/"
+				]
+			}
+		},
+		"publish": {
+			"dependsOn": ["copy-md"],
+			"executor": "nx:run-commands",
+			"outputs": [],
+			"options": {
+				"command": "pnpm publish --no-git-checks --access public",
+				"cwd": "build/packages/vctrl/embed"
+			}
+		}
+	}
+}

package/src/embed.ts

@@ -0,0 +1,362 @@
+import {
+	HOSTED_PREVIEW_HOST_SOURCE,
+	HOSTED_PREVIEW_VIEWER_SOURCE,
+	type EmbedCameraDescriptor,
+	type HostedPreviewOutgoingMessage
+} from './protocol'
+
+import type { ViewerCommand, ViewerInteractionEvent } from '@vctrl/viewer'
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface EmbedOptions {
+	/** Override the detected iframe origin for postMessage targeting. */
+	iframeOrigin?: string
+	/** Milliseconds before ready() rejects. Default: 15 000. */
+	readyTimeout?: number
+}
+
+export interface EmbedReadyInfo {
+	sceneId: string | undefined
+	cameras: EmbedCameraDescriptor[]
+}
+
+export interface SetTransitionOptions {
+	type: 'none' | 'linear' | 'object_avoidance'
+	duration?: number
+	easing?: 'linear' | 'ease_in' | 'ease_out' | 'ease_in_out'
+}
+
+export type EmbedEventMap = {
+	viewer_ready: void
+	model_loaded: void
+	camera_changed: { cameraId: string }
+	auto_rotate_changed: { enabled: boolean }
+	interaction_event: {
+		interactionId?: string
+		eventName: string
+		payload?: Record<string, unknown>
+	}
+}
+
+export type EmbedEventType = keyof EmbedEventMap
+export type EmbedEventHandler<K extends EmbedEventType> = (
+	data: EmbedEventMap[K]
+) => void
+
+// ---------------------------------------------------------------------------
+// VectrealEmbed
+// ---------------------------------------------------------------------------
+
+const DEFAULT_READY_TIMEOUT_MS = 15_000
+
+export class VectrealEmbed {
+	private readonly iframe: HTMLIFrameElement
+	private readonly targetOrigin: string
+	private readonly readyTimeout: number
+
+	private handlers = new Map<
+		EmbedEventType,
+		Set<EmbedEventHandler<EmbedEventType>>
+	>()
+	private pendingCommands: Array<{
+		source: string
+		type: string
+		[key: string]: unknown
+	}> = []
+	private isReady = false
+	private boundListener: (event: MessageEvent<unknown>) => void
+	private pingIntervalId: number | null = null
+
+	constructor(iframe: HTMLIFrameElement, options: EmbedOptions = {}) {
+		this.iframe = iframe
+		this.readyTimeout = options.readyTimeout ?? DEFAULT_READY_TIMEOUT_MS
+
+		const src = iframe.src || iframe.getAttribute('src') || ''
+		let detectedOrigin: string | undefined
+		if (src) {
+			try {
+				detectedOrigin = new URL(src, window.location.href).origin
+			} catch {
+				// unparseable src - fall through to require explicit iframeOrigin
+			}
+		}
+		if (!options.iframeOrigin && !detectedOrigin) {
+			throw new Error(
+				'VectrealEmbed: cannot determine iframe origin from src. Pass options.iframeOrigin explicitly.'
+			)
+		}
+		this.targetOrigin = options.iframeOrigin ?? detectedOrigin!
+
+		this.boundListener = this.handleMessage.bind(this)
+		window.addEventListener('message', this.boundListener)
+
+		// Retry ping every 500 ms until we receive a pong. The iframe's React app
+		// may not have hydrated and registered its message listener yet when the
+		// constructor runs, so a single fire-and-forget ping is unreliable.
+		this.startPingPolling()
+	}
+
+	// ---------------------------------------------------------------------------
+	// Lifecycle
+	// ---------------------------------------------------------------------------
+
+	/**
+	 * Resolves when the embedded viewer emits viewer_ready.
+	 * Rejects if no response within readyTimeout.
+	 */
+	ready(): Promise<EmbedReadyInfo> {
+		return new Promise((resolve, reject) => {
+			const timer = window.setTimeout(() => {
+				this.off('viewer_ready', onReady as EmbedEventHandler<'viewer_ready'>)
+				reject(
+					new Error(
+						`VectrealEmbed: viewer did not become ready within ${this.readyTimeout}ms`
+					)
+				)
+			}, this.readyTimeout)
+
+			const onReady = () => {
+				window.clearTimeout(timer)
+				resolve({
+					sceneId: this.sceneId,
+					cameras: this.cameras
+				})
+			}
+
+			if (this.isReady) {
+				window.clearTimeout(timer)
+				resolve({ sceneId: this.sceneId, cameras: this.cameras })
+				return
+			}
+
+			this.on('viewer_ready', onReady as EmbedEventHandler<'viewer_ready'>)
+		})
+	}
+
+	/** Remove all listeners and stop responding to messages. */
+	destroy(): void {
+		this.stopPingPolling()
+		window.removeEventListener('message', this.boundListener)
+		this.handlers.clear()
+		this.pendingCommands = []
+	}
+
+	// ---------------------------------------------------------------------------
+	// Commands
+	// ---------------------------------------------------------------------------
+
+	/** Switch to a named camera. */
+	activateCamera(cameraId: string): void {
+		this.sendCommand({ type: 'activate_camera', cameraId })
+	}
+
+	/** Override the transition behaviour for subsequent camera switches. */
+	setTransition(options: SetTransitionOptions): void {
+		this.sendCommand({
+			type: 'set_transition',
+			transitionType: options.type,
+			duration: options.duration,
+			easing: options.easing
+		})
+	}
+
+	/** Enable or disable orbit controls. */
+	setControlsEnabled(enabled: boolean): void {
+		this.sendCommand({ type: 'set_controls_enabled', enabled })
+	}
+
+	/** Toggle auto-rotate. */
+	setAutoRotate(enabled: boolean, speed?: number): void {
+		this.sendCommand({ type: 'set_auto_rotate', enabled, speed })
+	}
+
+	/** Toggle scroll-zoom. */
+	setZoomEnabled(enabled: boolean): void {
+		this.sendCommand({ type: 'set_controls_options', zoom: enabled })
+	}
+
+	/** Toggle right-click pan. */
+	setPanEnabled(enabled: boolean): void {
+		this.sendCommand({ type: 'set_controls_options', pan: enabled })
+	}
+
+	/**
+	 * Drive scroll-triggered interactions defined in the Publisher.
+	 * @param progress 0 (page top) – 1 (page bottom)
+	 */
+	sendScrollProgress(progress: number): void {
+		this.postToIframe({
+			source: HOSTED_PREVIEW_HOST_SOURCE,
+			type: 'host_scroll_progress',
+			progress: Math.min(1, Math.max(0, progress))
+		})
+	}
+
+	/**
+	 * Trigger a named host_message interaction defined in the Publisher.
+	 */
+	sendMessage(message: string, payload?: Record<string, unknown>): void {
+		this.postToIframe({
+			source: HOSTED_PREVIEW_HOST_SOURCE,
+			type: 'host_message',
+			message,
+			payload
+		})
+	}
+
+	// ---------------------------------------------------------------------------
+	// Events
+	// ---------------------------------------------------------------------------
+
+	/** Subscribe to a viewer event. Returns an unsubscribe function. */
+	on<K extends EmbedEventType>(
+		type: K,
+		handler: EmbedEventHandler<K>
+	): () => void {
+		if (!this.handlers.has(type)) {
+			this.handlers.set(type, new Set())
+		}
+		this.handlers.get(type)!.add(handler as EmbedEventHandler<EmbedEventType>)
+		return () => this.off(type, handler)
+	}
+
+	/** Remove a specific handler. */
+	off<K extends EmbedEventType>(type: K, handler: EmbedEventHandler<K>): void {
+		this.handlers
+			.get(type)
+			?.delete(handler as EmbedEventHandler<EmbedEventType>)
+	}
+
+	// ---------------------------------------------------------------------------
+	// Internal state (populated via pong)
+	// ---------------------------------------------------------------------------
+
+	private sceneId: string | undefined = undefined
+	private cameras: EmbedCameraDescriptor[] = []
+
+	// ---------------------------------------------------------------------------
+	// Private helpers
+	// ---------------------------------------------------------------------------
+
+	private sendCommand(command: ViewerCommand): void {
+		const message = {
+			source: HOSTED_PREVIEW_HOST_SOURCE,
+			type: 'viewer_command' as const,
+			command
+		}
+
+		if (!this.isReady) {
+			this.pendingCommands.push(message)
+			return
+		}
+
+		this.postToIframe(message)
+	}
+
+	private postToIframe(message: Record<string, unknown>): void {
+		try {
+			this.iframe.contentWindow?.postMessage(message, this.targetOrigin)
+		} catch {
+			// iframe may not be loaded yet; silently discard
+		}
+	}
+
+	private startPingPolling(): void {
+		this.postToIframe({ source: HOSTED_PREVIEW_HOST_SOURCE, type: 'ping' })
+		this.pingIntervalId = window.setInterval(() => {
+			if (this.isReady) {
+				this.stopPingPolling()
+				return
+			}
+			this.postToIframe({ source: HOSTED_PREVIEW_HOST_SOURCE, type: 'ping' })
+		}, 500)
+	}
+
+	private stopPingPolling(): void {
+		if (this.pingIntervalId !== null) {
+			window.clearInterval(this.pingIntervalId)
+			this.pingIntervalId = null
+		}
+	}
+
+	private flushPendingCommands(): void {
+		for (const cmd of this.pendingCommands) {
+			this.postToIframe(cmd)
+		}
+		this.pendingCommands = []
+	}
+
+	private emit<K extends EmbedEventType>(
+		type: K,
+		data: EmbedEventMap[K]
+	): void {
+		this.handlers.get(type)?.forEach((handler) => {
+			;(handler as EmbedEventHandler<K>)(data)
+		})
+	}
+
+	private handleMessage(event: MessageEvent<unknown>): void {
+		const data = event.data as HostedPreviewOutgoingMessage
+
+		if (
+			!data ||
+			typeof data !== 'object' ||
+			data.source !== HOSTED_PREVIEW_VIEWER_SOURCE
+		) {
+			return
+		}
+
+		// Validate the message origin matches our iframe
+		if (this.targetOrigin !== '*' && event.origin !== this.targetOrigin) {
+			return
+		}
+
+		switch (data.type) {
+			case 'pong':
+				this.stopPingPolling()
+				this.sceneId = data.sceneId
+				this.cameras = data.cameras
+				this.isReady = true
+				this.flushPendingCommands()
+				break
+
+			case 'viewer_event':
+				this.handleViewerEvent(data.event)
+				break
+
+			case 'interaction_event':
+				this.emit('interaction_event', {
+					interactionId: data.interactionId,
+					eventName: data.eventName,
+					payload: data.payload
+				})
+				break
+		}
+	}
+
+	private handleViewerEvent(event: ViewerInteractionEvent): void {
+		switch (event.type) {
+			case 'viewer_ready':
+				this.isReady = true
+				this.flushPendingCommands()
+				this.emit('viewer_ready', undefined as void)
+				break
+			case 'model_loaded':
+				this.emit('model_loaded', undefined as void)
+				break
+			case 'camera_changed':
+				this.emit('camera_changed', { cameraId: event.cameraId })
+				break
+			case 'auto_rotate_changed':
+				this.emit('auto_rotate_changed', { enabled: event.enabled })
+				break
+			case 'initial_framing_completed':
+				// Translate to model_loaded for embed consumers - signals scene is visible
+				this.emit('model_loaded', undefined as void)
+				break
+		}
+	}
+}

package/src/index.ts

@@ -0,0 +1,28 @@
+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'