@virtualdisplay.io/client 4.0.0-alpha.23 → 4.0.0-alpha.25

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 4.0.0-alpha.25
+
+### Minor Changes
+
+Add `onSelectableChange(callback)` and `getSelectable(name)` to follow which
+attribute values the buyer can still pick under the current selection. The
+standard sidebar greys out values the selection rules out. Models without
+exclusions behave exactly as before.
+
+## 4.0.0-alpha.24
+
+### Patch Changes
+
+Accept `undefined` for the optional `ClientOptions` fields `language`, `debug` and `traceparent`. Projects that enable `exactOptionalPropertyTypes` can now pass a possibly-undefined value straight through without a type error.
+
 ## 4.0.0-alpha.23
 
 ### Patch Changes

package/dist/index.d.ts

@@ -21,6 +21,7 @@ declare const MESSAGE_TYPES: {
     readonly PRICING: "pricing";
     readonly QR_SHOWN: "qr_shown";
     readonly SYNC: "sync";
+    readonly SELECTABLE: "selectable";
 };
 interface MutationDto {
     readonly name: string;
@@ -144,6 +145,23 @@ interface MappingMessage {
     readonly type: typeof MESSAGE_TYPES.MAPPING;
     readonly attributes: AttributeDefinition[];
 }
+/** Per selector, the values the buyer can still pick right now. */
+interface SelectableAttribute {
+    readonly name: string;
+    readonly selectable: string[];
+}
+/**
+ * Selectability snapshot (server → client): sent after the mapping and after
+ * every choice that changes the picture. Always the complete state, never a
+ * diff; a value not in its list is not pickable (the client greys it out).
+ * The client only renders, it never knows the exclusion rules. Named
+ * `selectable`, not availability: that word is taken by pricing
+ * (AVAILABILITY, available/view_only).
+ */
+interface SelectableMessage {
+    readonly type: typeof MESSAGE_TYPES.SELECTABLE;
+    readonly attributes: SelectableAttribute[];
+}
 /**
  * Loading indicator (server → client): progress percentage, phase label, or error.
  * Sent during model download and parse so the client loading indicator can update.
@@ -299,7 +317,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 | QrShownMessage | SyncMessage;
+type Message = HandshakeMessage | SessionMessage | MutationMessage | MutationResultMessage | CameraCommandMessage | CameraPositionMessage | SnapshotRequestMessage | SnapshotResultMessage | MappingMessage | LoadingIndicatorMessage | ArActivateMessage | FullscreenMessage | ConfigMessage | AnnotationToggleMessage | FocusMessage | FocusStateMessage | PricingMessage | QrShownMessage | SyncMessage | SelectableMessage;
 type MessageCallback = (message: Message) => void | Promise<void>;
 
 /**
@@ -311,18 +329,6 @@ interface MessengerOptions {
      * When false (default), incoming messages are processed immediately.
      */
     bufferIncoming?: boolean;
-    /**
-     * When buffering, messages where this returns false bypass the buffer
-     * and are routed to handlers immediately. Used for urgent messages
-     * like CONFIG that must be handled before the model loads.
-     */
-    shouldBuffer?: (message: Message) => boolean;
-    /**
-     * Restrict postMessage to a specific origin (e.g. 'https://example.com').
-     * Defaults to '*' when not set. Set this when the target origin is known
-     * to prevent messages from being intercepted by unintended recipients.
-     */
-    targetOrigin?: string;
     /**
      * Which protocol to validate incoming messages against — not whether to validate.
      * Both sides always reject browser-extension noise and unknown message types. The
@@ -357,11 +363,11 @@ interface MessengerOptions {
  * messenger.send({ type: 'mutation', mutations, isInitial: true });
  * ```
  *
- * @example Server (inside iframe — both queues, CONFIG bypasses consumer)
+ * @example Server (inside iframe — both queues)
  * ```ts
  * const messenger = new IframeMessenger(
  *   () => window.parent !== window ? window.parent : null,
- *   { bufferIncoming: true, shouldBuffer: (msg) => msg.type !== 'config' },
+ *   { bufferIncoming: true },
  * );
  * messenger.on('mutation', processMutation);
  * messenger.on('config', applyConfig);
@@ -376,7 +382,6 @@ declare class IframeMessenger {
     private readonly handlers;
     private readonly publisher;
     private readonly consumer;
-    private readonly shouldBuffer;
     private listener;
     private readonly sourceId;
     private targetOrigin;
@@ -386,10 +391,6 @@ declare class IframeMessenger {
      * Register a handler for a specific message type
      */
     on(type: string, handler: MessageCallback): void;
-    /**
-     * Remove a handler for a specific message type
-     */
-    off(type: string): void;
     /**
      * Update the target origin for outgoing postMessage calls.
      * Use when the target origin is discovered at runtime (e.g. from the first incoming message).
@@ -403,8 +404,8 @@ declare class IframeMessenger {
     /**
      * 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
+     * against `isValid`, and still respects the consumer queue's buffering. 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.
@@ -456,6 +457,8 @@ declare class Annotations {
     setEnabled(enabled: boolean): void;
 }
 
+type SelectableSnapshot = readonly SelectableAttribute[];
+
 /**
  * Camera control API for positioning and zoom
  * Uses chaining pattern for building commands
@@ -866,17 +869,17 @@ interface ClientOptions {
     readonly parent: string | HTMLElement;
     readonly model: string;
     readonly license: string;
-    readonly debug?: boolean;
-    readonly language?: string;
+    readonly debug?: boolean | undefined;
+    readonly language?: string | undefined;
     /** W3C traceparent string to propagate to the viewer iframe for end-to-end tracing. */
-    readonly traceparent?: string;
+    readonly traceparent?: string | undefined;
     /**
      * 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;
+    readonly session?: string | undefined;
     /**
      * Override viewer settings from metadata. Omitted fields use the metadata value.
      * A warning is logged when an override differs from the metadata value.
@@ -966,6 +969,12 @@ interface BaseClientExtensions {
      * so the host cannot be a single build-time env shared by both.
      */
     readonly serverHost?: string;
+    /**
+     * Extra query parameters for the viewer iframe URL. An extension seam like
+     * `serverHost`: a client type's fixed capability flags (the studio client's
+     * metadata-override boot mode), never a per-instance public option.
+     */
+    readonly iframeParams?: Readonly<Record<string, string>>;
     /**
      * The AR flow behind the standard interface's AR button. The public client
      * composes its `ArActivation` here; the studio composes nothing (the editor
@@ -987,6 +996,7 @@ interface BaseClientExtensions {
  */
 declare class BaseClient {
     private readonly attributes;
+    private readonly selectableState;
     private readonly readyStateTracker;
     private readonly messenger;
     private readonly cameraApi;
@@ -999,6 +1009,7 @@ declare class BaseClient {
     private readonly ui;
     private readonly options;
     private readonly serverHost;
+    private readonly iframeParams;
     /** 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). */
@@ -1043,6 +1054,16 @@ declare class BaseClient {
     get isReady(): boolean;
     onReady(callback: (client: this) => void): void;
     onMutationFailed(callback: (event: MutationFailedEvent) => void): void;
+    /**
+     * Subscribe to the viewer's selectability snapshots (kiesbaarheid live):
+     * per attribute, which values the buyer can pick right now. Fires with the
+     * current snapshot immediately when one already arrived. A model without
+     * exclusions never sends one: everything stays selectable and this never
+     * fires.
+     */
+    onSelectableChange(callback: (snapshot: SelectableSnapshot) => void): void;
+    /** The selectable values for one attribute right now, or null when unrestricted. */
+    getSelectable(name: string): readonly string[] | null;
     /**
      * Trigger the composed AR flow directly (ar-session-handoff task 035): a host
      * page that hides the built-in corner button (`viewerSettings.ar = false`,