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

package/dist/index.d.ts

@@ -4,7 +4,7 @@
  * All message types exchanged between client (parent page)
  * and server (iframe viewer engine) via postMessage.
  */
-declare const MESSAGE_TYPES$1: {
+declare const MESSAGE_TYPES: {
     readonly HANDSHAKE: "handshake";
     readonly SESSION: "session";
     readonly MUTATION: "mutation";
@@ -16,30 +16,28 @@ declare const MESSAGE_TYPES$1: {
     readonly AR_ACTIVATE: "ar_activate";
     readonly FULLSCREEN: "fullscreen";
     readonly CONFIG: "config";
-    readonly ANNOTATION_PLACE_MODE: "annotation_place_mode";
-    readonly ANNOTATION_PLACED: "annotation_placed";
     readonly ANNOTATION_TOGGLE: "annotation_toggle";
     readonly FOCUS: "focus";
     readonly PRICING: "pricing";
 };
-interface MutationDto$1 {
+interface MutationDto {
     readonly name: string;
     readonly value: string;
 }
-interface MutationResult$1 {
+interface MutationResult {
     readonly name: string;
     readonly value: string;
     readonly success: boolean;
     readonly error?: string;
 }
-interface MutationMessage$1 {
-    readonly type: typeof MESSAGE_TYPES$1.MUTATION;
-    readonly mutations: MutationDto$1[];
+interface MutationMessage {
+    readonly type: typeof MESSAGE_TYPES.MUTATION;
+    readonly mutations: MutationDto[];
     readonly isInitial: boolean;
 }
-interface MutationResultMessage$1 {
-    readonly type: typeof MESSAGE_TYPES$1.MUTATION;
-    readonly results: MutationResult$1[];
+interface MutationResultMessage {
+    readonly type: typeof MESSAGE_TYPES.MUTATION;
+    readonly results: MutationResult[];
     readonly isInitial: boolean;
 }
 /**
@@ -61,7 +59,7 @@ interface ViewerSettings$1 {
  * Used to disable camera control buttons when a limit is reached.
  * Units match the camera position: zoom = percentage (0–200), tilt/rotate = degrees.
  */
-interface CameraLimits$1 {
+interface CameraLimits {
     readonly minZoom?: number;
     readonly maxZoom?: number;
     readonly minTilt?: number;
@@ -69,47 +67,47 @@ interface CameraLimits$1 {
     readonly minRotate?: number;
     readonly maxRotate?: number;
 }
-interface CameraCommand$1 {
+interface CameraCommand {
     readonly action: 'rotate' | 'tilt' | 'zoom' | 'reset';
     readonly value?: number;
 }
-interface CameraParameter$1 {
+interface CameraParameter {
     readonly type: 'rotation' | 'tilt' | 'zoom';
     readonly value: number;
 }
-interface CameraCommandMessage$1 {
-    readonly type: typeof MESSAGE_TYPES$1.CAMERA;
-    readonly commands: CameraCommand$1[];
+interface CameraCommandMessage {
+    readonly type: typeof MESSAGE_TYPES.CAMERA;
+    readonly commands: CameraCommand[];
 }
-interface CameraPositionMessage$1 {
-    readonly type: typeof MESSAGE_TYPES$1.CAMERA;
-    readonly transforms: CameraParameter$1[];
+interface CameraPositionMessage {
+    readonly type: typeof MESSAGE_TYPES.CAMERA;
+    readonly transforms: CameraParameter[];
 }
-interface SnapshotRequestMessage$1 {
-    readonly type: typeof MESSAGE_TYPES$1.SNAPSHOT;
+interface SnapshotRequestMessage {
+    readonly type: typeof MESSAGE_TYPES.SNAPSHOT;
     readonly filename: string;
 }
-interface SnapshotResultMessage$1 {
-    readonly type: typeof MESSAGE_TYPES$1.SNAPSHOT;
+interface SnapshotResultMessage {
+    readonly type: typeof MESSAGE_TYPES.SNAPSHOT;
     readonly filename: string;
     readonly data?: string;
     readonly error?: string;
 }
-interface AttributeDefinition$1 {
+interface AttributeDefinition {
     readonly name: string;
     readonly values: string[];
     readonly defaultValue?: string;
 }
-interface MappingMessage$1 {
-    readonly type: typeof MESSAGE_TYPES$1.MAPPING;
-    readonly attributes: AttributeDefinition$1[];
+interface MappingMessage {
+    readonly type: typeof MESSAGE_TYPES.MAPPING;
+    readonly attributes: AttributeDefinition[];
 }
 /**
  * Loading indicator (server → client): progress percentage, phase label, or error.
  * Sent during model download and parse so the client loading indicator can update.
  */
-interface LoadingIndicatorMessage$1 {
-    readonly type: typeof MESSAGE_TYPES$1.LOADING_INDICATOR;
+interface LoadingIndicatorMessage {
+    readonly type: typeof MESSAGE_TYPES.LOADING_INDICATOR;
     /** 0–100 */
     readonly progress: number;
     /** Human-readable phase label, e.g. "downloading" */
@@ -118,29 +116,29 @@ interface LoadingIndicatorMessage$1 {
     readonly error?: string;
 }
 /** AR activate (client → server): user clicked the AR button. Server handles activation. */
-interface ArActivateMessage$1 {
-    readonly type: typeof MESSAGE_TYPES$1.AR_ACTIVATE;
+interface ArActivateMessage {
+    readonly type: typeof MESSAGE_TYPES.AR_ACTIVATE;
 }
 /**
  * Fullscreen (client → server): the user entered fullscreen via the client's
  * toolbar button. Fullscreen itself is handled client-side; this only lets the
  * server record the engagement against the tracking session it owns.
  */
-interface FullscreenMessage$1 {
-    readonly type: typeof MESSAGE_TYPES$1.FULLSCREEN;
+interface FullscreenMessage {
+    readonly type: typeof MESSAGE_TYPES.FULLSCREEN;
 }
 /**
  * Config (server → client): viewer settings and camera limits from model metadata.
  * Sent early — before MAPPING — so the client can show/hide controls and disable
  * camera buttons at limits as soon as metadata is available.
  */
-interface ConfigMessage$1 {
-    readonly type: typeof MESSAGE_TYPES$1.CONFIG;
+interface ConfigMessage {
+    readonly type: typeof MESSAGE_TYPES.CONFIG;
     readonly viewerSettings: ViewerSettings$1;
-    readonly cameraLimits?: CameraLimits$1;
+    readonly cameraLimits?: CameraLimits;
 }
-interface HandshakeMessage$1 {
-    readonly type: typeof MESSAGE_TYPES$1.HANDSHAKE;
+interface HandshakeMessage {
+    readonly type: typeof MESSAGE_TYPES.HANDSHAKE;
 }
 /**
  * Session (server → client): the tracking session id, announced once the viewer
@@ -148,61 +146,39 @@ interface HandshakeMessage$1 {
  * client learns it). The client exposes it so a host page can correlate its own
  * actions (e.g. a configurator conversion) with the viewer session.
  */
-interface SessionMessage$1 {
-    readonly type: typeof MESSAGE_TYPES$1.SESSION;
+interface SessionMessage {
+    readonly type: typeof MESSAGE_TYPES.SESSION;
     readonly sessionId: string;
 }
-/**
- * Annotation place mode (parent → server): enable or disable click-to-place.
- * When enabled, clicking on the model surface sends back an ANNOTATION_PLACED message.
- */
-interface AnnotationPlaceModeMessage$1 {
-    readonly type: typeof MESSAGE_TYPES$1.ANNOTATION_PLACE_MODE;
-    readonly enabled: boolean;
-}
-/** Position on the model surface returned by raycasting. */
-interface AnnotationPosition$1 {
-    readonly x: number;
-    readonly y: number;
-    readonly z: number;
-}
-/**
- * Annotation placed (server → parent): user clicked on the model surface.
- * Only sent when place mode is active.
- */
-interface AnnotationPlacedMessage$1 {
-    readonly type: typeof MESSAGE_TYPES$1.ANNOTATION_PLACED;
-    readonly position: AnnotationPosition$1;
-}
 /**
  * Annotation toggle (parent → server): show or hide annotation markers.
  * Only works when annotations exist in metadata (grand switch).
  */
-interface AnnotationToggleMessage$1 {
-    readonly type: typeof MESSAGE_TYPES$1.ANNOTATION_TOGGLE;
+interface AnnotationToggleMessage {
+    readonly type: typeof MESSAGE_TYPES.ANNOTATION_TOGGLE;
     readonly enabled: boolean;
 }
 /** Focus actions (client → server). */
-declare const FOCUS_ACTIONS$1: {
+declare const FOCUS_ACTIONS: {
     readonly FOCUS: "focus";
     readonly UNFOCUS: "unfocus";
 };
 /** Focus states (server → client). */
-declare const FOCUS_STATES$1: {
+declare const FOCUS_STATES: {
     readonly FOCUSED: "focused";
     readonly UNFOCUSED: "unfocused";
 };
-type FocusAction$1 = typeof FOCUS_ACTIONS$1[keyof typeof FOCUS_ACTIONS$1];
-type FocusStateValue$1 = typeof FOCUS_STATES$1[keyof typeof FOCUS_STATES$1];
+type FocusAction = typeof FOCUS_ACTIONS[keyof typeof FOCUS_ACTIONS];
+type FocusStateValue = typeof FOCUS_STATES[keyof typeof FOCUS_STATES];
 /**
  * Focus (client → server): isolate and frame a component, or return to overview.
  * Programmatic — the API, the (future) component menu, and the portal editors all
  * send this. `component` is a name from the `components` metadata, or a raw mesh
  * name as a fallback (resolved server-side); required when action is `focus`.
  */
-interface FocusMessage$1 {
-    readonly type: typeof MESSAGE_TYPES$1.FOCUS;
-    readonly action: FocusAction$1;
+interface FocusMessage {
+    readonly type: typeof MESSAGE_TYPES.FOCUS;
+    readonly action: FocusAction;
     readonly component?: string;
 }
 /**
@@ -210,9 +186,9 @@ interface FocusMessage$1 {
  * opacity transition. `attributes` lists which attributes are relevant to the
  * focused component, so a custom UI can filter its selectors.
  */
-interface FocusStateMessage$1 {
-    readonly type: typeof MESSAGE_TYPES$1.FOCUS;
-    readonly state: FocusStateValue$1;
+interface FocusStateMessage {
+    readonly type: typeof MESSAGE_TYPES.FOCUS;
+    readonly state: FocusStateValue;
     readonly component?: string;
     readonly attributes?: string[];
 }
@@ -267,145 +243,155 @@ interface PricingDocument$1 {
  * Pricing (server → client): the model's pricing document. Sent once at startup
  * after MAPPING so the client's resolver can price the current configuration.
  */
-interface PricingMessage$1 {
-    readonly type: typeof MESSAGE_TYPES$1.PRICING;
+interface PricingMessage {
+    readonly type: typeof MESSAGE_TYPES.PRICING;
     readonly pricing: PricingDocument$1;
 }
-type Message$1 = HandshakeMessage$1 | SessionMessage$1 | MutationMessage$1 | MutationResultMessage$1 | CameraCommandMessage$1 | CameraPositionMessage$1 | SnapshotRequestMessage$1 | SnapshotResultMessage$1 | MappingMessage$1 | LoadingIndicatorMessage$1 | ArActivateMessage$1 | FullscreenMessage$1 | ConfigMessage$1 | AnnotationPlaceModeMessage$1 | AnnotationPlacedMessage$1 | AnnotationToggleMessage$1 | FocusMessage$1 | FocusStateMessage$1 | PricingMessage$1;
-type MessageCallback = (message: Message$1) => void | Promise<void>;
+type Message = HandshakeMessage | SessionMessage | MutationMessage | MutationResultMessage | CameraCommandMessage | CameraPositionMessage | SnapshotRequestMessage | SnapshotResultMessage | MappingMessage | LoadingIndicatorMessage | ArActivateMessage | FullscreenMessage | ConfigMessage | AnnotationToggleMessage | FocusMessage | FocusStateMessage | PricingMessage;
+type MessageCallback = (message: Message) => void | Promise<void>;
 
 /**
- * Configuration options for VirtualdisplayClient
+ * Options for IframeMessenger
  */
-interface ClientOptions {
-    readonly parent: string | HTMLElement;
-    readonly model: string;
-    readonly license: string;
-    readonly debug?: boolean;
-    readonly language?: string;
-    /** W3C traceparent string to propagate to the viewer iframe for end-to-end tracing. */
-    readonly traceparent?: string;
+interface MessengerOptions {
     /**
-     * Override viewer settings from metadata. Omitted fields use the metadata value.
-     * A warning is logged when an override differs from the metadata value.
+     * Buffer incoming messages until markConsumerReady().
+     * When false (default), incoming messages are processed immediately.
      */
-    readonly viewerSettings?: Partial<ViewerSettings$1>;
+    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
+     * default (`isValidMessageData`) accepts the public protocol; the studio side passes
+     * `isValidStudioMessageData`, which accepts the public protocol plus the studio
+     * messages (e.g. annotation placement), so the public bundle stays lean.
+     */
+    isValid?: (data: unknown) => boolean;
 }
-
 /**
- * The Virtualdisplay client's DOM event names, in one registry.
+ * Bidirectional iframe message port
  *
- * - `ui:*` events dispatch on the container (non-bubbling). They are the typed
- *   surface of `client.on(...)` — payloads in `VirtualdisplayUiEventMap` (./types).
- * - `vd:*` events bubble into the customer's page, so a page can react with
- *   `addEventListener` without registering a client callback.
- */
-declare const VD_EVENTS: {
-    /** Attribute selection requested (cancelable). `detail`: `{ attribute, value }`. */
-    readonly SELECT: "ui:select";
-    /** Attribute selection applied. `detail`: `{ attribute, value }`. */
-    readonly SELECTED: "ui:selected";
-    /** Focus changed (bubbles). `detail`: `{ component, attributes }`, or `null` for the overview. */
-    readonly FOCUS_CHANGE: "vd:focus-change";
-    /** Resolved configuration changed (bubbles). `detail`: the resolved configuration, or `null` when nothing matches. */
-    readonly CONFIGURATION_CHANGE: "vd:configuration-change";
-    /** Configuration submitted (bubbles). `detail`: the resolved configuration handed to the host. */
-    readonly CONFIGURATION_SUBMIT: "vd:configuration-submit";
-};
-type VdEvent = typeof VD_EVENTS[keyof typeof VD_EVENTS];
-
-/**
- * Error codes for Virtualdisplay client errors
- */
-declare const ERROR_CODES: {
-    readonly NO_MAPPING: "NO_MAPPING";
-    readonly ATTRIBUTE_NOT_FOUND: "ATTRIBUTE_NOT_FOUND";
-    readonly VALUE_NOT_FOUND: "VALUE_NOT_FOUND";
-    readonly PARENT_NOT_FOUND: "PARENT_NOT_FOUND";
-    readonly INVALID_PARAMETER: "INVALID_PARAMETER";
-    readonly SNAPSHOT_FAILED: "SNAPSHOT_FAILED";
-};
-type ErrorCode = typeof ERROR_CODES[keyof typeof ERROR_CODES];
-/**
- * Custom error class for Virtualdisplay client errors
- */
-declare class VirtualdisplayError extends Error {
-    readonly code: ErrorCode;
-    constructor(message: string, code: ErrorCode);
-    static valueNotFound(attributeName: string, valueName: string): VirtualdisplayError;
-    static parentNotFound(selector: string): VirtualdisplayError;
-    static invalidParameter(reason: string): VirtualdisplayError;
-}
-
-interface MutationFailedEvent {
-    readonly attribute: string;
-    readonly value: string;
-}
-interface VirtualdisplaySelectEvent {
-    readonly attribute: string;
-    readonly value: string;
-    preventDefault(): void;
-}
-interface VirtualdisplaySelectedEvent {
-    readonly attribute: string;
-    readonly value: string;
-}
-type VirtualdisplayUiEventMap = {
-    [VD_EVENTS.SELECT]: VirtualdisplaySelectEvent;
-    [VD_EVENTS.SELECTED]: VirtualdisplaySelectedEvent;
-};
-type VirtualdisplayUiEventType = keyof VirtualdisplayUiEventMap;
-
-/**
- * Pure domain entity representing a single attribute value
- * No side effects - only state
- */
-declare class AttributeValue {
-    readonly value: string;
-    readonly attribute: string;
-    private isSelectedValue;
-    constructor(value: string, attribute: string);
-    get isSelected(): boolean;
-    setSelected(selected: boolean): void;
-}
-
-interface AttributeOptions {
-    readonly name: string;
-    readonly values: string[];
-    readonly onSelect: (name: string, value: string) => void;
-    readonly defaultValue?: string;
-}
-/**
- * Represents a single attribute with its available values
- * Flat API - no source/target translation, works with server values directly
+ * Handles sending and receiving messages via postMessage between
+ * a parent page and an iframe. Both client and server use this —
+ * the only difference is the target window.
+ *
+ * Features:
+ * - Publisher queue: outgoing messages buffered until markReady()
+ * - Consumer queue: incoming messages buffered until markConsumerReady() (opt-in)
+ * - Handler registration: route incoming messages by type
+ * - Echo prevention: tags outgoing messages to filter self-delivery
+ * - Cleanup: removes listener on destroy
+ *
+ * @example Client (parent page — publisher queue only)
+ * ```ts
+ * const messenger = new IframeMessenger(() => iframe.contentWindow);
+ * messenger.on('mutation', handleMutationResult);
+ * messenger.on('mapping', handleMapping);
+ * messenger.start();
+ * // When iframe loads:
+ * messenger.markReady();
+ * messenger.send({ type: 'mutation', mutations, isInitial: true });
+ * ```
+ *
+ * @example Server (inside iframe — both queues, CONFIG bypasses consumer)
+ * ```ts
+ * const messenger = new IframeMessenger(
+ *   () => window.parent !== window ? window.parent : null,
+ *   { bufferIncoming: true, shouldBuffer: (msg) => msg.type !== 'config' },
+ * );
+ * messenger.on('mutation', processMutation);
+ * messenger.on('config', applyConfig);
+ * messenger.start();
+ * messenger.markReady();
+ * // When model loads:
+ * messenger.markConsumerReady();
+ * ```
  */
-declare class Attribute {
-    readonly name: string;
-    readonly defaultValue: string | undefined;
-    private readonly values;
-    private readonly onSelect;
-    private onChangeCallback?;
-    constructor(options: AttributeOptions);
+declare class IframeMessenger {
+    private readonly getTarget;
+    private readonly handlers;
+    private readonly publisher;
+    private readonly consumer;
+    private readonly shouldBuffer;
+    private listener;
+    private readonly sourceId;
+    private targetOrigin;
+    private readonly isValid;
+    constructor(getTarget: () => Window | null, options?: MessengerOptions);
     /**
-     * Select a value for this attribute
-     * @throws {VirtualdisplayError} When value not found
+     * Register a handler for a specific message type
      */
-    select(value: string): void;
-    getValues(): AttributeValue[];
-    getValue(value: string): AttributeValue | undefined;
-    /** The currently selected value, or undefined before any selection lands. */
-    get selected(): string | undefined;
+    on(type: string, handler: MessageCallback): void;
     /**
-     * Register callback that fires when selection changes
-     * Receives the newly selected AttributeValue
+     * Remove a handler for a specific message type
      */
-    onChange(callback: (selectedValue: AttributeValue) => void): void;
+    off(type: string): void;
     /**
-     * Update selection state from server mutation result
-     * Direct value comparison - no source/target translation
+     * Update the target origin for outgoing postMessage calls.
+     * Use when the target origin is discovered at runtime (e.g. from the first incoming message).
      */
-    handleResult(serverValue: string): void;
-    private createValues;
+    setTargetOrigin(origin: string): void;
+    /**
+     * Send a message to the target window
+     * Queued until markReady() is called
+     */
+    send(message: Message): void;
+    /**
+     * Enable sending and flush queued outgoing messages
+     */
+    markReady(): void;
+    /**
+     * Enable processing of buffered incoming messages
+     * Only relevant when constructed with bufferIncoming: true
+     */
+    markConsumerReady(): void;
+    /**
+     * Check if an incoming message of a specific type is pending in the consumer buffer
+     */
+    consumerHasPending(type: string): boolean;
+    /**
+     * Start listening for incoming messages
+     */
+    start(): void;
+    /**
+     * Stop listening and clean up all state
+     */
+    destroy(): void;
+    /**
+     * Whether the messenger is ready to send
+     */
+    get ready(): boolean;
+    /**
+     * Number of messages waiting in the outgoing queue
+     */
+    get pendingCount(): number;
+    private post;
+    private routeToHandler;
+}
+
+type SendFn$1 = (message: Message) => void;
+/**
+ * Annotation display controls for the viewer: show or hide existing markers.
+ *
+ * Placement (click-to-place for the editor) is a studio capability and lives in
+ * `@virtualdisplay.io/client-studio`, never in the public client or its engine surface.
+ */
+declare class Annotations {
+    private readonly send;
+    constructor(send: SendFn$1);
+    setEnabled(enabled: boolean): void;
 }
 
 /**
@@ -486,61 +472,20 @@ declare class CameraPosition {
      * Current camera movement limits (set from CONFIG message).
      * Undefined until the server sends limits in its CONFIG payload.
      */
-    get limits(): CameraLimits$1 | undefined;
+    get limits(): CameraLimits | undefined;
     /**
      * Apply camera limits received from the server CONFIG message.
      * Fires onChange callbacks so button disabled states update immediately.
      */
-    applyLimits(limits: CameraLimits$1 | undefined): void;
+    applyLimits(limits: CameraLimits | undefined): void;
     /**
      * Handle incoming camera position message from server
      */
-    handlePositionUpdate(message: CameraPositionMessage$1): void;
+    handlePositionUpdate(message: CameraPositionMessage): void;
     /**
      * Update camera position from server transforms
      */
-    update(transforms: CameraParameter$1[]): void;
-}
-
-/** The focus state reported to `onChange` and the `vd:focus-change` event. */
-interface FocusState {
-    readonly component: string;
-    readonly attributes: string[];
-}
-type FocusChange = FocusState | null;
-type FocusChangeCallback = (state: FocusChange) => void;
-type DispatchFn = (state: FocusChange) => void;
-/**
- * Focus control API — isolate and frame a component, or return to overview.
- *
- * Programmatic by design: `set('Seat')` needs no user selection, which is how the
- * (future) component menu and the portal/admin editors drive it over the same
- * message bus. Alongside `onChange`, the container dispatches a bubbling
- * `vd:focus-change` CustomEvent so a page can react without registering a callback.
- */
-declare class Focus {
-    private readonly send;
-    private readonly dispatch;
-    private focused;
-    private attributes;
-    private readonly changeCallbacks;
-    constructor(send: MessageCallback, dispatch: DispatchFn);
-    /** The focused component name, or null in overview. */
-    get current(): string | null;
-    /**
-     * Focus a component by name. Sends a focus message to the viewer.
-     * @throws VirtualdisplayError if component is not a non-empty string
-     */
-    set(component: string): void;
-    /** Return to the overview — unfocus the current component. */
-    clear(): void;
-    /**
-     * Subscribe to focus changes. The callback fires with the focus state when a
-     * component is focused, and with null when returning to overview.
-     */
-    onChange(callback: FocusChangeCallback): void;
-    /** Called by the client when a FocusStateMessage is received from the viewer. */
-    handleStateReceived(message: FocusStateMessage$1): void;
+    update(transforms: CameraParameter[]): void;
 }
 
 /** The buyer's current configuration as attribute name→value pairs. */
@@ -656,9 +601,73 @@ declare class Configuration {
     private resolve;
 }
 
-interface PhotoData {
-    readonly filename: string;
-    readonly data: string;
+/** The focus state reported to `onChange` and the `vd:focus-change` event. */
+interface FocusState {
+    readonly component: string;
+    readonly attributes: string[];
+}
+type FocusChange = FocusState | null;
+type FocusChangeCallback = (state: FocusChange) => void;
+type DispatchFn = (state: FocusChange) => void;
+/**
+ * Focus control API — isolate and frame a component, or return to overview.
+ *
+ * Programmatic by design: `set('Seat')` needs no user selection, which is how the
+ * (future) component menu and the portal/admin editors drive it over the same
+ * message bus. Alongside `onChange`, the container dispatches a bubbling
+ * `vd:focus-change` CustomEvent so a page can react without registering a callback.
+ */
+declare class Focus {
+    private readonly send;
+    private readonly dispatch;
+    private focused;
+    private attributes;
+    private readonly changeCallbacks;
+    constructor(send: MessageCallback, dispatch: DispatchFn);
+    /** The focused component name, or null in overview. */
+    get current(): string | null;
+    /**
+     * Focus a component by name. Sends a focus message to the viewer.
+     * @throws VirtualdisplayError if component is not a non-empty string
+     */
+    set(component: string): void;
+    /** Return to the overview — unfocus the current component. */
+    clear(): void;
+    /**
+     * Subscribe to focus changes. The callback fires with the focus state when a
+     * component is focused, and with null when returning to overview.
+     */
+    onChange(callback: FocusChangeCallback): void;
+    /** Called by the client when a FocusStateMessage is received from the viewer. */
+    handleStateReceived(message: FocusStateMessage): void;
+}
+
+/**
+ * Error codes for Virtualdisplay client errors
+ */
+declare const ERROR_CODES: {
+    readonly NO_MAPPING: "NO_MAPPING";
+    readonly ATTRIBUTE_NOT_FOUND: "ATTRIBUTE_NOT_FOUND";
+    readonly VALUE_NOT_FOUND: "VALUE_NOT_FOUND";
+    readonly PARENT_NOT_FOUND: "PARENT_NOT_FOUND";
+    readonly INVALID_PARAMETER: "INVALID_PARAMETER";
+    readonly SNAPSHOT_FAILED: "SNAPSHOT_FAILED";
+};
+type ErrorCode = typeof ERROR_CODES[keyof typeof ERROR_CODES];
+/**
+ * Custom error class for Virtualdisplay client errors
+ */
+declare class VirtualdisplayError extends Error {
+    readonly code: ErrorCode;
+    constructor(message: string, code: ErrorCode);
+    static valueNotFound(attributeName: string, valueName: string): VirtualdisplayError;
+    static parentNotFound(selector: string): VirtualdisplayError;
+    static invalidParameter(reason: string): VirtualdisplayError;
+}
+
+interface PhotoData {
+    readonly filename: string;
+    readonly data: string;
 }
 /**
  * Represents a photo being captured
@@ -723,7 +732,7 @@ declare class Snapshot {
      * Handle incoming snapshot result from server
      * Matches the message to a pending photo by filename, then develops or fails it
      */
-    handleSnapshotResult(message: SnapshotResultMessage$1): void;
+    handleSnapshotResult(message: SnapshotResultMessage): void;
     /**
      * Fail any pending photos and forget them. Called from client destroy
      * so callers awaiting onError() see a deterministic outcome instead of
@@ -736,314 +745,140 @@ declare class Snapshot {
     private validateFilename;
 }
 
-type Attrs = Record<string, unknown> | unknown;
-declare let logger: {
-    debug: (msg: string, attrs?: Attrs) => void;
-    info: (msg: string, attrs?: Attrs) => void;
-    warn: (msg: string, attrs?: Attrs) => void;
-    error: (msg: string, attrs?: Attrs) => void;
-};
-declare function enableDebugMode(): void;
-declare function isDebugMode(): boolean;
-
 /**
- * Virtualdisplay iframe messaging protocol
- *
- * All message types exchanged between client (parent page)
- * and server (iframe viewer engine) via postMessage.
+ * Pure domain entity representing a single attribute value
+ * No side effects - only state
  */
-declare const MESSAGE_TYPES: {
-    readonly HANDSHAKE: "handshake";
-    readonly SESSION: "session";
-    readonly MUTATION: "mutation";
-    readonly STATE: "state";
-    readonly LOADING_INDICATOR: "loading_indicator";
-    readonly CAMERA: "camera";
-    readonly SNAPSHOT: "snapshot";
-    readonly MAPPING: "mapping";
-    readonly AR_ACTIVATE: "ar_activate";
-    readonly FULLSCREEN: "fullscreen";
-    readonly CONFIG: "config";
-    readonly ANNOTATION_PLACE_MODE: "annotation_place_mode";
-    readonly ANNOTATION_PLACED: "annotation_placed";
-    readonly ANNOTATION_TOGGLE: "annotation_toggle";
-    readonly FOCUS: "focus";
-    readonly PRICING: "pricing";
-};
-interface MutationDto {
-    readonly name: string;
-    readonly value: string;
-}
-interface MutationResult {
-    readonly name: string;
+declare class AttributeValue {
     readonly value: string;
-    readonly success: boolean;
-    readonly error?: string;
-}
-interface MutationMessage {
-    readonly type: typeof MESSAGE_TYPES.MUTATION;
-    readonly mutations: MutationDto[];
-    readonly isInitial: boolean;
-}
-interface MutationResultMessage {
-    readonly type: typeof MESSAGE_TYPES.MUTATION;
-    readonly results: MutationResult[];
-    readonly isInitial: boolean;
-}
-/**
- * Viewer settings from model metadata (server → client via MAPPING).
- * Customer-configured in the portal.
- */
-interface ViewerSettings {
-    readonly ar?: boolean;
-    readonly fullscreen?: boolean;
-    readonly screenshot?: boolean;
-    readonly cameraControls?: boolean;
-    readonly annotations?: boolean;
-    readonly language?: string;
-    /** Where the attribute controls sit: in-frame bottom-left (default) or a docked right panel. */
-    readonly configuratorLayout?: 'inframe-bottom-left' | 'sidebar-right' | 'hidden';
-}
-/**
- * Camera movement limits sent to the client via CONFIG.
- * Used to disable camera control buttons when a limit is reached.
- * Units match the camera position: zoom = percentage (0–200), tilt/rotate = degrees.
- */
-interface CameraLimits {
-    readonly minZoom?: number;
-    readonly maxZoom?: number;
-    readonly minTilt?: number;
-    readonly maxTilt?: number;
-    readonly minRotate?: number;
-    readonly maxRotate?: number;
-}
-interface CameraCommand {
-    readonly action: 'rotate' | 'tilt' | 'zoom' | 'reset';
-    readonly value?: number;
-}
-interface CameraParameter {
-    readonly type: 'rotation' | 'tilt' | 'zoom';
-    readonly value: number;
-}
-interface CameraCommandMessage {
-    readonly type: typeof MESSAGE_TYPES.CAMERA;
-    readonly commands: CameraCommand[];
-}
-interface CameraPositionMessage {
-    readonly type: typeof MESSAGE_TYPES.CAMERA;
-    readonly transforms: CameraParameter[];
-}
-interface SnapshotRequestMessage {
-    readonly type: typeof MESSAGE_TYPES.SNAPSHOT;
-    readonly filename: string;
-}
-interface SnapshotResultMessage {
-    readonly type: typeof MESSAGE_TYPES.SNAPSHOT;
-    readonly filename: string;
-    readonly data?: string;
-    readonly error?: string;
+    readonly attribute: string;
+    private isSelectedValue;
+    constructor(value: string, attribute: string);
+    get isSelected(): boolean;
+    setSelected(selected: boolean): void;
 }
-interface AttributeDefinition {
+
+interface AttributeOptions {
     readonly name: string;
     readonly values: string[];
+    readonly onSelect: (name: string, value: string) => void;
     readonly defaultValue?: string;
 }
-interface MappingMessage {
-    readonly type: typeof MESSAGE_TYPES.MAPPING;
-    readonly attributes: AttributeDefinition[];
-}
 /**
- * Loading indicator (server → client): progress percentage, phase label, or error.
- * Sent during model download and parse so the client loading indicator can update.
- */
-interface LoadingIndicatorMessage {
-    readonly type: typeof MESSAGE_TYPES.LOADING_INDICATOR;
-    /** 0–100 */
-    readonly progress: number;
-    /** Human-readable phase label, e.g. "downloading" */
-    readonly phase: string;
-    /** Set when loading failed; client shows error state instead of hiding the overlay. */
-    readonly error?: string;
-}
-/** AR activate (client → server): user clicked the AR button. Server handles activation. */
-interface ArActivateMessage {
-    readonly type: typeof MESSAGE_TYPES.AR_ACTIVATE;
-}
-/**
- * Fullscreen (client → server): the user entered fullscreen via the client's
- * toolbar button. Fullscreen itself is handled client-side; this only lets the
- * server record the engagement against the tracking session it owns.
- */
-interface FullscreenMessage {
-    readonly type: typeof MESSAGE_TYPES.FULLSCREEN;
-}
-/**
- * Config (server → client): viewer settings and camera limits from model metadata.
- * Sent early — before MAPPING — so the client can show/hide controls and disable
- * camera buttons at limits as soon as metadata is available.
- */
-interface ConfigMessage {
-    readonly type: typeof MESSAGE_TYPES.CONFIG;
-    readonly viewerSettings: ViewerSettings;
-    readonly cameraLimits?: CameraLimits;
-}
-interface HandshakeMessage {
-    readonly type: typeof MESSAGE_TYPES.HANDSHAKE;
-}
-/**
- * Session (server → client): the tracking session id, announced once the viewer
- * has established it (the id is generated in the iframe, so this is how the
- * client learns it). The client exposes it so a host page can correlate its own
- * actions (e.g. a configurator conversion) with the viewer session.
- */
-interface SessionMessage {
-    readonly type: typeof MESSAGE_TYPES.SESSION;
-    readonly sessionId: string;
-}
-/**
- * Annotation place mode (parent → server): enable or disable click-to-place.
- * When enabled, clicking on the model surface sends back an ANNOTATION_PLACED message.
- */
-interface AnnotationPlaceModeMessage {
-    readonly type: typeof MESSAGE_TYPES.ANNOTATION_PLACE_MODE;
-    readonly enabled: boolean;
-}
-/** Position on the model surface returned by raycasting. */
-interface AnnotationPosition {
-    readonly x: number;
-    readonly y: number;
-    readonly z: number;
-}
-/**
- * Annotation placed (server → parent): user clicked on the model surface.
- * Only sent when place mode is active.
- */
-interface AnnotationPlacedMessage {
-    readonly type: typeof MESSAGE_TYPES.ANNOTATION_PLACED;
-    readonly position: AnnotationPosition;
-}
-/**
- * Annotation toggle (parent → server): show or hide annotation markers.
- * Only works when annotations exist in metadata (grand switch).
- */
-interface AnnotationToggleMessage {
-    readonly type: typeof MESSAGE_TYPES.ANNOTATION_TOGGLE;
-    readonly enabled: boolean;
-}
-/** Focus actions (client → server). */
-declare const FOCUS_ACTIONS: {
-    readonly FOCUS: "focus";
-    readonly UNFOCUS: "unfocus";
-};
-/** Focus states (server → client). */
-declare const FOCUS_STATES: {
-    readonly FOCUSED: "focused";
-    readonly UNFOCUSED: "unfocused";
-};
-type FocusAction = typeof FOCUS_ACTIONS[keyof typeof FOCUS_ACTIONS];
-type FocusStateValue = typeof FOCUS_STATES[keyof typeof FOCUS_STATES];
-/**
- * Focus (client → server): isolate and frame a component, or return to overview.
- * Programmatic — the API, the (future) component menu, and the portal editors all
- * send this. `component` is a name from the `components` metadata, or a raw mesh
- * name as a fallback (resolved server-side); required when action is `focus`.
- */
-interface FocusMessage {
-    readonly type: typeof MESSAGE_TYPES.FOCUS;
-    readonly action: FocusAction;
-    readonly component?: string;
-}
-/**
- * Focus state (server → client): confirms the focus state after the camera and
- * opacity transition. `attributes` lists which attributes are relevant to the
- * focused component, so a custom UI can filter its selectors.
+ * Represents a single attribute with its available values
+ * Flat API - no source/target translation, works with server values directly
  */
-interface FocusStateMessage {
-    readonly type: typeof MESSAGE_TYPES.FOCUS;
-    readonly state: FocusStateValue;
-    readonly component?: string;
-    readonly attributes?: string[];
+declare class Attribute {
+    readonly name: string;
+    readonly defaultValue: string | undefined;
+    private readonly values;
+    private readonly onSelect;
+    private onChangeCallback?;
+    constructor(options: AttributeOptions);
+    /**
+     * Select a value for this attribute
+     * @throws {VirtualdisplayError} When value not found
+     */
+    select(value: string): void;
+    getValues(): AttributeValue[];
+    getValue(value: string): AttributeValue | undefined;
+    /** The currently selected value, or undefined before any selection lands. */
+    get selected(): string | undefined;
+    /**
+     * Register callback that fires when selection changes
+     * Receives the newly selected AttributeValue
+     */
+    onChange(callback: (selectedValue: AttributeValue) => void): void;
+    /**
+     * Update selection state from server mutation result
+     * Direct value comparison - no source/target translation
+     */
+    handleResult(serverValue: string): void;
+    private createValues;
 }
+
 /**
- * What the configurator does with a matched configuration. Mirrors the backend
- * `availability` enum (pricing rule provenance lives on `PricingRule.source`).
- */
-declare const AVAILABILITY: {
-    /** Price and submit button both shown (default). */
-    readonly AVAILABLE: "available";
-    /** Price shown, submit hidden (sold out / coming soon). */
-    readonly VIEW_ONLY: "view_only";
-    /** Behaves exactly like an unpriced combination: no price, no button. */
-    readonly HIDDEN: "hidden";
-};
-type Availability = typeof AVAILABILITY[keyof typeof AVAILABILITY];
-/**
- * One pricing rule: a subset of attribute values mapped to a reference + price.
- * Matches the backend pricing read contract (`GET /api/public/models/.../pricing`).
+ * Configuration options for VirtualdisplayClient
  */
-interface PricingRule {
+interface ClientOptions {
+    readonly parent: string | HTMLElement;
+    readonly model: string;
+    readonly license: string;
+    readonly debug?: boolean;
+    readonly language?: string;
+    /** W3C traceparent string to propagate to the viewer iframe for end-to-end tracing. */
+    readonly traceparent?: string;
     /**
-     * The attribute name→value pairs this rule names. `{}` is a catch-all;
-     * omitted names are wildcards. A rule matches when every pair equals the
-     * current selection; the rule naming the most attributes wins.
+     * Override viewer settings from metadata. Omitted fields use the metadata value.
+     * A warning is logged when an override differs from the metadata value.
      */
-    readonly attributes: Record<string, string>;
-    /** The customer's own identifier (SKU, EAN, artikelnummer, name code). */
-    readonly reference: string;
-    /** Price in minor units (cents), exactly as the source displays it. */
-    readonly priceCents: number;
-    readonly availability: Availability;
-    /** Provenance (manual | imported); audit-only, unused by the resolver. */
-    readonly source: 'manual' | 'imported';
+    readonly viewerSettings?: Partial<ViewerSettings$1>;
 }
+
 /**
- * A model's pricing document. The viewer's fetcher merges it into the model
- * metadata and the server forwards it to the client via {@link PricingMessage}.
+ * The Virtualdisplay client's DOM event names, in one registry.
+ *
+ * - `ui:*` events dispatch on the container (non-bubbling). They are the typed
+ *   surface of `client.on(...)` — payloads in `VirtualdisplayUiEventMap` (./types).
+ * - `vd:*` events bubble into the customer's page, so a page can react with
+ *   `addEventListener` without registering a client callback.
  */
-interface PricingDocument {
-    /** Optimistic-concurrency version from the editor; unused by the viewer. */
-    readonly version: number;
-    /** Customer-authored CTA label; null when the adapter's defaultLabel fills in. */
-    readonly buttonLabel: string | null;
-    /** ISO 4217 currency code for price formatting. */
-    readonly currency: string;
-    /** VAT label for bare embeds, e.g. "incl. btw". */
-    readonly vatDisplay: string;
-    readonly rules: PricingRule[];
+declare const VD_EVENTS: {
+    /** Attribute selection requested (cancelable). `detail`: `{ attribute, value }`. */
+    readonly SELECT: "ui:select";
+    /** Attribute selection applied. `detail`: `{ attribute, value }`. */
+    readonly SELECTED: "ui:selected";
+    /** Focus changed (bubbles). `detail`: `{ component, attributes }`, or `null` for the overview. */
+    readonly FOCUS_CHANGE: "vd:focus-change";
+    /** Resolved configuration changed (bubbles). `detail`: the resolved configuration, or `null` when nothing matches. */
+    readonly CONFIGURATION_CHANGE: "vd:configuration-change";
+    /** Configuration submitted (bubbles). `detail`: the resolved configuration handed to the host. */
+    readonly CONFIGURATION_SUBMIT: "vd:configuration-submit";
+};
+type VdEvent = typeof VD_EVENTS[keyof typeof VD_EVENTS];
+
+interface MutationFailedEvent {
+    readonly attribute: string;
+    readonly value: string;
 }
-/**
- * Pricing (server → client): the model's pricing document. Sent once at startup
- * after MAPPING so the client's resolver can price the current configuration.
- */
-interface PricingMessage {
-    readonly type: typeof MESSAGE_TYPES.PRICING;
-    readonly pricing: PricingDocument;
+interface VirtualdisplaySelectEvent {
+    readonly attribute: string;
+    readonly value: string;
+    preventDefault(): void;
 }
-type Message = HandshakeMessage | SessionMessage | MutationMessage | MutationResultMessage | CameraCommandMessage | CameraPositionMessage | SnapshotRequestMessage | SnapshotResultMessage | MappingMessage | LoadingIndicatorMessage | ArActivateMessage | FullscreenMessage | ConfigMessage | AnnotationPlaceModeMessage | AnnotationPlacedMessage | AnnotationToggleMessage | FocusMessage | FocusStateMessage | PricingMessage;
+interface VirtualdisplaySelectedEvent {
+    readonly attribute: string;
+    readonly value: string;
+}
+type VirtualdisplayUiEventMap = {
+    [VD_EVENTS.SELECT]: VirtualdisplaySelectEvent;
+    [VD_EVENTS.SELECTED]: VirtualdisplaySelectedEvent;
+};
+type VirtualdisplayUiEventType = keyof VirtualdisplayUiEventMap;
 
 type SendFn = (message: Message) => void;
-type PlacedCallback = (position: AnnotationPosition) => void;
 /**
- * Annotation controls for the viewer.
- * Toggle visibility, and manage click-to-place for the annotation editor.
+ * Extensions a subclass (the studio client) layers onto the base composition without
+ * re-implementing it: a custom incoming-message validator and extra message handlers.
  */
-declare class Annotations {
-    private readonly send;
-    private readonly placedCallbacks;
-    constructor(send: SendFn);
-    setEnabled(enabled: boolean): void;
-    startPlacing(): void;
-    stopPlacing(): void;
-    onPlaced(callback: PlacedCallback): void;
-    /** Called by the client when an ANNOTATION_PLACED message is received. */
-    handlePlaced(position: AnnotationPosition): void;
+interface BaseClientExtensions {
+    readonly messengerOptions?: MessengerOptions;
+    readonly registerHandlers?: (messenger: IframeMessenger, send: SendFn) => void;
+    /**
+     * The server host this client's viewer iframe targets — a fixed fact per client
+     * type, injected like the validator, not a per-instance setting. The studio client
+     * fixes it to the studio viewer build; the public client leaves it unset and uses
+     * the default public viewer. Both clients are bundled into one portal/admin build,
+     * so the host cannot be a single build-time env shared by both.
+     */
+    readonly serverHost?: string;
 }
-
 /**
- * Main Virtualdisplay Client — composition root.
- * Wires all services together and exposes the public API.
+ * The shared client composition root. Wires the engine (transport, facades, UI) and exposes
+ * the buyer-facing API. The public `VirtualdisplayClient` is this base as-is; the studio
+ * client extends it with the studio facades via {@link BaseClientExtensions}.
  */
-declare class VirtualdisplayClient {
+declare class BaseClient {
     private readonly attributes;
     private readonly readyStateTracker;
     private readonly messenger;
@@ -1057,17 +892,16 @@ declare class VirtualdisplayClient {
     private readonly ui;
     private readonly qrModal;
     private readonly options;
+    private readonly serverHost;
     private iframe;
     private container;
-    private viewerSessionId;
     private readyCallbacks;
     private readonly mutationFailedCallbacks;
-    constructor(options: ClientOptions);
-    private registerHandlers;
-    /** Lifecycle handlers: the handshake (queue flush) and the tracking session id. */
-    private registerLifecycleHandlers;
-    /** Handlers that feed viewer-reported state into the facades (focus, pricing). */
-    private registerFacadeStateHandlers;
+    /** The viewer's tracking session id, once the server announces it (SESSION). */
+    private viewerSessionId;
+    constructor(options: ClientOptions, extensions?: BaseClientExtensions);
+    /** Wire the inbound viewer protocol to the facades. */
+    private wireIncomingMessages;
     /**
      * Dispatch a bubbling `vd:focus-change` event on the container so a page can
      * react to focus without registering an `onChange` callback.
@@ -1092,7 +926,7 @@ declare class VirtualdisplayClient {
     onChange(name: string, callback: (selectedValue: AttributeValue) => void): void;
     getAttribute(name: string): Attribute | undefined;
     get isReady(): boolean;
-    onReady(callback: (client: VirtualdisplayClient) => void): void;
+    onReady(callback: (client: this) => void): void;
     onMutationFailed(callback: (event: MutationFailedEvent) => void): void;
     on<T extends VirtualdisplayUiEventType>(type: T, callback: (event: VirtualdisplayUiEventMap[T]) => void): void;
     get annotations(): Annotations;
@@ -1101,16 +935,92 @@ declare class VirtualdisplayClient {
     get configuration(): Configuration;
     get cameraPosition(): CameraPosition;
     get snapshot(): Snapshot;
-    get viewerSettings(): ViewerSettings;
-    /**
-     * The viewer's tracking session id, once the viewer has established it (the id
-     * is generated inside the iframe and announced to the client). `undefined`
-     * until then. A host page can use it to correlate its own actions, e.g. a
-     * configurator conversion, with the viewer session.
-     */
+    /** The viewer's tracking session id, for a host page to correlate its own actions. */
     get sessionId(): string | undefined;
+    get viewerSettings(): ViewerSettings$1;
     destroy(): void;
 }
 
+type Attrs = Record<string, unknown> | unknown;
+declare let logger: {
+    debug: (msg: string, attrs?: Attrs) => void;
+    info: (msg: string, attrs?: Attrs) => void;
+    warn: (msg: string, attrs?: Attrs) => void;
+    error: (msg: string, attrs?: Attrs) => void;
+};
+declare function enableDebugMode(): void;
+declare function isDebugMode(): boolean;
+
+/**
+ * The public Virtualdisplay client: the shared base composition (transport, facades, the
+ * 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`.
+ */
+declare class VirtualdisplayClient extends BaseClient {
+}
+
+/**
+ * Viewer settings from model metadata (server → client via MAPPING).
+ * Customer-configured in the portal.
+ */
+interface ViewerSettings {
+    readonly ar?: boolean;
+    readonly fullscreen?: boolean;
+    readonly screenshot?: boolean;
+    readonly cameraControls?: boolean;
+    readonly annotations?: boolean;
+    readonly language?: string;
+    /** Where the attribute controls sit: in-frame bottom-left (default) or a docked right panel. */
+    readonly configuratorLayout?: 'inframe-bottom-left' | 'sidebar-right' | 'hidden';
+}
+/**
+ * What the configurator does with a matched configuration. Mirrors the backend
+ * `availability` enum (pricing rule provenance lives on `PricingRule.source`).
+ */
+declare const AVAILABILITY: {
+    /** Price and submit button both shown (default). */
+    readonly AVAILABLE: "available";
+    /** Price shown, submit hidden (sold out / coming soon). */
+    readonly VIEW_ONLY: "view_only";
+    /** Behaves exactly like an unpriced combination: no price, no button. */
+    readonly HIDDEN: "hidden";
+};
+type Availability = typeof AVAILABILITY[keyof typeof AVAILABILITY];
+/**
+ * One pricing rule: a subset of attribute values mapped to a reference + price.
+ * Matches the backend pricing read contract (`GET /api/public/models/.../pricing`).
+ */
+interface PricingRule {
+    /**
+     * The attribute name→value pairs this rule names. `{}` is a catch-all;
+     * omitted names are wildcards. A rule matches when every pair equals the
+     * current selection; the rule naming the most attributes wins.
+     */
+    readonly attributes: Record<string, string>;
+    /** The customer's own identifier (SKU, EAN, artikelnummer, name code). */
+    readonly reference: string;
+    /** Price in minor units (cents), exactly as the source displays it. */
+    readonly priceCents: number;
+    readonly availability: Availability;
+    /** Provenance (manual | imported); audit-only, unused by the resolver. */
+    readonly source: 'manual' | 'imported';
+}
+/**
+ * A model's pricing document. The viewer's fetcher merges it into the model
+ * metadata and the server forwards it to the client via {@link PricingMessage}.
+ */
+interface PricingDocument {
+    /** Optimistic-concurrency version from the editor; unused by the viewer. */
+    readonly version: number;
+    /** Customer-authored CTA label; null when the adapter's defaultLabel fills in. */
+    readonly buttonLabel: string | null;
+    /** ISO 4217 currency code for price formatting. */
+    readonly currency: string;
+    /** VAT label for bare embeds, e.g. "incl. btw". */
+    readonly vatDisplay: string;
+    readonly rules: PricingRule[];
+}
+
 export { Annotations, Attribute, AttributeValue, Camera, Configuration, ERROR_CODES, Focus, Photo, Snapshot, VD_EVENTS, VirtualdisplayClient, VirtualdisplayError, enableDebugMode, isDebugMode, logger };
-export type { AnnotationPosition, Availability, ClientOptions, ErrorCode, FocusState, MutationFailedEvent, PhotoData, PricingDocument, PricingRule, ResolvedConfiguration, SubmitOptions, SubmittedConfiguration, VdEvent, ViewerSettings, VirtualdisplaySelectEvent, VirtualdisplaySelectedEvent, VirtualdisplayUiEventMap, VirtualdisplayUiEventType };
+export type { Availability, ClientOptions, ErrorCode, FocusState, MutationFailedEvent, PhotoData, PricingDocument, PricingRule, ResolvedConfiguration, SubmitOptions, SubmittedConfiguration, VdEvent, ViewerSettings, VirtualdisplaySelectEvent, VirtualdisplaySelectedEvent, VirtualdisplayUiEventMap, VirtualdisplayUiEventType };