@virtualdisplay.io/client 4.0.0-alpha.20 → 4.0.0-alpha.22

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # Changelog
 
+## 4.0.0-alpha.22
+
+### Patch Changes
+
+Fix the 3D model rendering behind the docked sidebar panel instead of next to it. On wide embeds the viewer now narrows to leave room for the panel, instead of the panel floating over part of the model.
+
+## 4.0.0-alpha.21
+
+### Minor Changes
+
+Add `activateAr()` method to `VirtualdisplayClient`. Triggers the AR flow directly, useful when the built-in AR button is hidden with `viewerSettings.ar = false` and a custom control should start AR instead.
+
+Add `client.onSyncChange(callback)`: subscribe to whether the viewer is currently live-syncing its configuration with another device in a hand-off (e.g. a desktop and the phone it was scanned to). The callback receives a boolean and fires again each time the connection state changes.
+
+### Patch Changes
+
+Change the desktop AR button's QR code to open the model in AR on the phone with the shopper's current configuration, instead of a fresh default viewer. The QR dialog now opens immediately and shows the code as soon as it is ready.
+
 ## 4.0.0-alpha.20
 
 ### Patch Changes

package/dist/index.d.ts

@@ -19,6 +19,8 @@ declare const MESSAGE_TYPES: {
     readonly ANNOTATION_TOGGLE: "annotation_toggle";
     readonly FOCUS: "focus";
     readonly PRICING: "pricing";
+    readonly QR_SHOWN: "qr_shown";
+    readonly SYNC: "sync";
 };
 interface MutationDto {
     readonly name: string;
@@ -30,10 +32,50 @@ interface MutationResult {
     readonly success: boolean;
     readonly error?: string;
 }
+/**
+ * The folded family state riding along on a live sync channel broadcast
+ * (ar-session-handoff, sync-channel.md): the same shape the public
+ * session-state read returns. Authoritative self-heal input; `mutations`
+ * on the same message is only the delta that triggered the broadcast.
+ */
+interface SyncStateSnapshot {
+    readonly license: string;
+    readonly model: string;
+    readonly attributes: Record<string, string>;
+}
 interface MutationMessage {
     readonly type: typeof MESSAGE_TYPES.MUTATION;
     readonly mutations: MutationDto[];
     readonly isInitial: boolean;
+    /**
+     * Live sync channel extras (ar-session-handoff, sync-channel.md), present
+     * only on a mutation the viewer engine's sync module received over the SSE
+     * live-state channel; a MutationMessage posted locally by the client never
+     * carries these. `origin` is the sender's page session id: its presence
+     * marks the mutation as remote, so the tracker must never record it again
+     * (the no-re-track loop guard, decision 15), and the sync module drops it
+     * when it equals the receiving engine's own session id (the echo filter).
+     * `seq` is the sender's per-session sequence number, used by the sync
+     * module to track how far the channel has progressed. `state` is the
+     * authoritative folded family state: the sync module diffs it against the
+     * channel's last-seen state and applies the difference, so a catch-up
+     * (empty `mutations`) or a broadcast the hub dropped still converges the
+     * subscriber. None of these fields are read by `MutationRouter`.
+     */
+    readonly origin?: string;
+    readonly seq?: number;
+    readonly state?: SyncStateSnapshot;
+}
+/**
+ * Sync channel status (server → client, ar-session-handoff, sync-channel.md):
+ * whether the viewer engine's live-state channel is currently connected to its
+ * hand-off family. One-way, latest-wins: no history, no buffering. The public
+ * client exposes it as `onSyncChange`; the studio composes nothing, so its
+ * engine never sends this (it never opens the channel).
+ */
+interface SyncMessage {
+    readonly type: typeof MESSAGE_TYPES.SYNC;
+    readonly connected: boolean;
 }
 interface MutationResultMessage {
     readonly type: typeof MESSAGE_TYPES.MUTATION;
@@ -127,6 +169,16 @@ interface ArActivateMessage {
 interface FullscreenMessage {
     readonly type: typeof MESSAGE_TYPES.FULLSCREEN;
 }
+/**
+ * QR shown (client → server): the desktop QR hand-off modal (ar-session-handoff)
+ * was displayed to the shopper. The QR itself is generated client-side; this
+ * only lets the server record the engagement (`qr_shown`, the funnel's
+ * denominator) against the tracking session it owns. One-way, fire-and-forget,
+ * nothing to act on, same shape as FULLSCREEN.
+ */
+interface QrShownMessage {
+    readonly type: typeof MESSAGE_TYPES.QR_SHOWN;
+}
 /**
  * Config (server → client): viewer settings and camera limits from model metadata.
  * Sent early — before MAPPING — so the client can show/hide controls and disable
@@ -247,7 +299,7 @@ interface PricingMessage {
     readonly type: typeof MESSAGE_TYPES.PRICING;
     readonly pricing: PricingDocument$1;
 }
-type Message = HandshakeMessage | SessionMessage | MutationMessage | MutationResultMessage | CameraCommandMessage | CameraPositionMessage | SnapshotRequestMessage | SnapshotResultMessage | MappingMessage | LoadingIndicatorMessage | ArActivateMessage | FullscreenMessage | ConfigMessage | AnnotationToggleMessage | FocusMessage | FocusStateMessage | PricingMessage;
+type Message = HandshakeMessage | SessionMessage | MutationMessage | MutationResultMessage | CameraCommandMessage | CameraPositionMessage | SnapshotRequestMessage | SnapshotResultMessage | MappingMessage | LoadingIndicatorMessage | ArActivateMessage | FullscreenMessage | ConfigMessage | AnnotationToggleMessage | FocusMessage | FocusStateMessage | PricingMessage | QrShownMessage | SyncMessage;
 type MessageCallback = (message: Message) => void | Promise<void>;
 
 /**
@@ -348,6 +400,16 @@ declare class IframeMessenger {
      * Queued until markReady() is called
      */
     send(message: Message): void;
+    /**
+     * Feed a message through the same routing path as one that just arrived via
+     * postMessage, without an actual postMessage round-trip: still validated
+     * against `isValid`, and still respects the consumer queue's buffering and
+     * the `shouldBuffer` bypass. For a transport that delivers messages some
+     * other way than the iframe channel this messenger already listens on (the
+     * viewer engine's SSE-sourced live sync channel, ar-session-handoff) and
+     * needs them to land exactly where a postMessage would.
+     */
+    receive(message: Message): void;
     /**
      * Enable sending and flush queued outgoing messages
      */
@@ -808,6 +870,13 @@ interface ClientOptions {
     readonly language?: string;
     /** W3C traceparent string to propagate to the viewer iframe for end-to-end tracing. */
     readonly traceparent?: string;
+    /**
+     * A source viewer session id to restore into this mount (ar-session-handoff): the
+     * iframe's metadata fetch merges that session's latest configuration into the
+     * attribute defaults, so the viewer boots straight into it. Internal option, used
+     * by the AR landing, not a customer-facing setting.
+     */
+    readonly session?: string;
     /**
      * Override viewer settings from metadata. Omitted fields use the metadata value.
      * A warning is logged when an override differs from the metadata value.
@@ -857,6 +926,31 @@ type VirtualdisplayUiEventMap = {
 type VirtualdisplayUiEventType = keyof VirtualdisplayUiEventMap;
 
 type SendFn = (message: Message) => void;
+/**
+ * The seam for the AR flow behind the standard interface's AR button. The base
+ * only routes to it: the implementation (mobile AR_ACTIVATE, desktop hand-off
+ * QR) lives in the public client package (`@virtualdisplay.io/client`), which
+ * composes it via {@link BaseClientExtensions.createArActivation}.
+ */
+interface ArFlow {
+    /** The AR button handler. */
+    activate(): void;
+    /** The engine-announced tracking session id (SESSION), which the flow may wait on. */
+    onSession(sessionId: string): void;
+    destroy(): void;
+}
+/**
+ * The seam for the live sync channel's connection status (ar-session-handoff,
+ * sync-channel.md). The base only routes SYNC messages to it; the concrete
+ * tracker (callback list + `onSyncChange`) lives in the public client package,
+ * composed via {@link BaseClientExtensions.createSyncTracker}. The studio
+ * composes nothing, so `onSyncChange` does not exist on the studio client
+ * (its engine never opens the channel, so it never sends SYNC either).
+ */
+interface SyncTracker {
+    /** Latest-wins, no buffering: the channel's current connection state. */
+    handleSync(connected: boolean): void;
+}
 /**
  * Extensions a subclass (the studio client) layers onto the base composition without
  * re-implementing it: a custom incoming-message validator and extra message handlers.
@@ -872,6 +966,19 @@ interface BaseClientExtensions {
      * so the host cannot be a single build-time env shared by both.
      */
     readonly serverHost?: string;
+    /**
+     * The AR flow behind the standard interface's AR button. The public client
+     * composes its `ArActivation` here; the studio composes nothing (the editor
+     * has no AR use case), so the base wires no AR button at all.
+     */
+    readonly createArActivation?: (send: SendFn) => ArFlow;
+    /**
+     * The live sync channel's connection tracker (ar-session-handoff). The
+     * public client composes a tracker and exposes `onSyncChange`; the studio
+     * composes nothing, so SYNC messages (which its own engine never sends
+     * anyway) are simply dropped.
+     */
+    readonly createSyncTracker?: () => SyncTracker;
 }
 /**
  * The shared client composition root. Wires the engine (transport, facades, UI) and exposes
@@ -890,9 +997,12 @@ declare class BaseClient {
     private readonly annotationsApi;
     private readonly eventBus;
     private readonly ui;
-    private readonly qrModal;
     private readonly options;
     private readonly serverHost;
+    /** The composed AR flow, or undefined in builds without one (the studio). */
+    private readonly arActivation;
+    /** The composed sync tracker, or undefined in builds without one (the studio). */
+    private readonly syncTracker;
     private iframe;
     private container;
     private readyCallbacks;
@@ -902,6 +1012,12 @@ declare class BaseClient {
     constructor(options: ClientOptions, extensions?: BaseClientExtensions);
     /** Wire the inbound viewer protocol to the facades. */
     private wireIncomingMessages;
+    /** Store the tracking session id and hand it to the AR flow, which waits on it for the QR. */
+    private handleSession;
+    /** Forward a failed mutation to every registered `onMutationFailed` callback. */
+    private notifyMutationFailed;
+    /** Flush the queued `onReady` callbacks once, then let the standard interface know. */
+    private notifyReady;
     /**
      * Dispatch a bubbling `vd:focus-change` event on the container so a page can
      * react to focus without registering an `onChange` callback.
@@ -915,7 +1031,6 @@ declare class BaseClient {
     /** Dispatch a bubbling `vd:configuration-submit` event when the CTA is used. */
     private dispatchConfigurationSubmit;
     private handleConfig;
-    private activateAr;
     /** Tell the viewer the user entered fullscreen, so it records the engagement. */
     private trackFullscreen;
     private initializeLogging;
@@ -928,6 +1043,14 @@ declare class BaseClient {
     get isReady(): boolean;
     onReady(callback: (client: this) => void): void;
     onMutationFailed(callback: (event: MutationFailedEvent) => void): void;
+    /**
+     * Trigger the composed AR flow directly (ar-session-handoff task 035): a host
+     * page that hides the built-in corner button (`viewerSettings.ar = false`,
+     * e.g. the AR landing, which owns a single custom AR affordance) still needs
+     * an entry point to the same flow that button would have called. A no-op
+     * where no AR flow is composed (the studio client has none).
+     */
+    activateAr(): void;
     on<T extends VirtualdisplayUiEventType>(type: T, callback: (event: VirtualdisplayUiEventMap[T]) => void): void;
     get annotations(): Annotations;
     get camera(): Camera;
@@ -956,8 +1079,17 @@ declare function isDebugMode(): boolean;
  * standard interface) with no studio capability. This is the buyer-facing SDK published as
  * `@virtualdisplay.io/client`. The internal studio client adds the editing facades over the
  * same base in `@virtualdisplay.io/client-studio`.
+ *
+ * The AR flow (mobile AR_ACTIVATE, desktop hand-off QR) is composed here: it is a shopper
+ * feature, so the studio client does not compose it and renders no AR button. The live sync
+ * channel's connection status (`onSyncChange`) is composed the same way: the studio client
+ * has no such method, its engine never opens the channel.
  */
 declare class VirtualdisplayClient extends BaseClient {
+    private readonly syncStatusTracker;
+    constructor(options: ClientOptions);
+    /** Subscribe to the live sync channel's connection state (ar-session-handoff). Latest-wins, no buffering. */
+    onSyncChange(callback: (connected: boolean) => void): void;
 }
 
 /**