@virtualdisplay.io/client 4.0.0-alpha.15 → 4.0.0-alpha.16

package/dist/index.d.ts

@@ -0,0 +1,1064 @@
+/**
+ * Virtualdisplay iframe messaging protocol
+ *
+ * All message types exchanged between client (parent page)
+ * and server (iframe viewer engine) via postMessage.
+ */
+declare const MESSAGE_TYPES$1: {
+    readonly HANDSHAKE: "handshake";
+    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 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 {
+    readonly name: string;
+    readonly value: string;
+}
+interface MutationResult$1 {
+    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[];
+    readonly isInitial: boolean;
+}
+interface MutationResultMessage$1 {
+    readonly type: typeof MESSAGE_TYPES$1.MUTATION;
+    readonly results: MutationResult$1[];
+    readonly isInitial: boolean;
+}
+/**
+ * Viewer settings from model metadata (server → client via MAPPING).
+ * Customer-configured in the portal.
+ */
+interface ViewerSettings$1 {
+    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$1 {
+    readonly minZoom?: number;
+    readonly maxZoom?: number;
+    readonly minTilt?: number;
+    readonly maxTilt?: number;
+    readonly minRotate?: number;
+    readonly maxRotate?: number;
+}
+interface CameraCommand$1 {
+    readonly action: 'rotate' | 'tilt' | 'zoom' | 'reset';
+    readonly value?: number;
+}
+interface CameraParameter$1 {
+    readonly type: 'rotation' | 'tilt' | 'zoom';
+    readonly value: number;
+}
+interface CameraCommandMessage$1 {
+    readonly type: typeof MESSAGE_TYPES$1.CAMERA;
+    readonly commands: CameraCommand$1[];
+}
+interface CameraPositionMessage$1 {
+    readonly type: typeof MESSAGE_TYPES$1.CAMERA;
+    readonly transforms: CameraParameter$1[];
+}
+interface SnapshotRequestMessage$1 {
+    readonly type: typeof MESSAGE_TYPES$1.SNAPSHOT;
+    readonly filename: string;
+}
+interface SnapshotResultMessage$1 {
+    readonly type: typeof MESSAGE_TYPES$1.SNAPSHOT;
+    readonly filename: string;
+    readonly data?: string;
+    readonly error?: string;
+}
+interface AttributeDefinition$1 {
+    readonly name: string;
+    readonly values: string[];
+    readonly defaultValue?: string;
+}
+interface MappingMessage$1 {
+    readonly type: typeof MESSAGE_TYPES$1.MAPPING;
+    readonly attributes: AttributeDefinition$1[];
+}
+/**
+ * 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;
+    /** 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$1 {
+    readonly type: typeof MESSAGE_TYPES$1.AR_ACTIVATE;
+}
+/**
+ * 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;
+    readonly viewerSettings: ViewerSettings$1;
+    readonly cameraLimits?: CameraLimits$1;
+}
+interface HandshakeMessage$1 {
+    readonly type: typeof MESSAGE_TYPES$1.HANDSHAKE;
+}
+/**
+ * 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;
+    readonly enabled: boolean;
+}
+/** Focus actions (client → server). */
+declare const FOCUS_ACTIONS$1: {
+    readonly FOCUS: "focus";
+    readonly UNFOCUS: "unfocus";
+};
+/** Focus states (server → client). */
+declare const FOCUS_STATES$1: {
+    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];
+/**
+ * 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;
+    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.
+ */
+interface FocusStateMessage$1 {
+    readonly type: typeof MESSAGE_TYPES$1.FOCUS;
+    readonly state: FocusStateValue$1;
+    readonly component?: string;
+    readonly attributes?: string[];
+}
+/**
+ * What the configurator does with a matched configuration. Mirrors the backend
+ * `availability` enum (pricing rule provenance lives on `PricingRule.source`).
+ */
+declare const AVAILABILITY$1: {
+    /** 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$1 = typeof AVAILABILITY$1[keyof typeof AVAILABILITY$1];
+/**
+ * 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$1 {
+    /**
+     * 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$1;
+    /** 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$1 {
+    /** 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$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;
+    readonly pricing: PricingDocument$1;
+}
+type Message$1 = HandshakeMessage$1 | MutationMessage$1 | MutationResultMessage$1 | CameraCommandMessage$1 | CameraPositionMessage$1 | SnapshotRequestMessage$1 | SnapshotResultMessage$1 | MappingMessage$1 | LoadingIndicatorMessage$1 | ArActivateMessage$1 | ConfigMessage$1 | AnnotationPlaceModeMessage$1 | AnnotationPlacedMessage$1 | AnnotationToggleMessage$1 | FocusMessage$1 | FocusStateMessage$1 | PricingMessage$1;
+type MessageCallback = (message: Message$1) => void | Promise<void>;
+
+/**
+ * Configuration options for VirtualdisplayClient
+ */
+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;
+    /**
+     * Override viewer settings from metadata. Omitted fields use the metadata value.
+     * A warning is logged when an override differs from the metadata value.
+     */
+    readonly viewerSettings?: Partial<ViewerSettings$1>;
+}
+
+/**
+ * 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.
+ */
+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
+ */
+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;
+}
+
+/**
+ * Camera control API for positioning and zoom
+ * Uses chaining pattern for building commands
+ */
+declare class Camera {
+    private readonly send;
+    private commands;
+    constructor(send: MessageCallback);
+    /**
+     * Rotate camera horizontally
+     * @param degrees - Absolute rotation in degrees (0 = front view)
+     * @throws VirtualdisplayError if value is not a finite number
+     */
+    rotate(degrees: number): this;
+    /**
+     * Tilt camera vertically
+     * @param degrees - Absolute tilt in degrees (0 = top view, 90 = horizontal)
+     * @throws VirtualdisplayError if value is not a finite number
+     */
+    tilt(degrees: number): this;
+    /**
+     * Zoom camera
+     * @param percentage - Zoom percentage (100 = normal, >100 = zoom in, <100 = zoom out)
+     * @throws VirtualdisplayError if value is not a finite number
+     */
+    zoom(percentage: number): this;
+    /**
+     * Execute accumulated camera commands
+     * @throws VirtualdisplayError if no commands have been accumulated
+     */
+    set(): void;
+    private validateFiniteNumber;
+    /**
+     * Reset camera to initial position
+     * This is not chainable and executes immediately
+     */
+    reset(): void;
+}
+
+/**
+ * Camera position state object
+ */
+interface CameraPositionState {
+    rotation: number;
+    tilt: number;
+    zoom: number;
+}
+/**
+ * Camera position state
+ * Tracks current rotation, tilt, zoom, and movement limits from server updates.
+ */
+declare class CameraPosition {
+    private readonly state;
+    private limitsState;
+    private readonly changeCallbacks;
+    constructor();
+    /**
+     * Get current rotation in degrees
+     */
+    get rotation(): number;
+    /**
+     * Get current tilt in degrees
+     */
+    get tilt(): number;
+    /**
+     * Get current zoom percentage
+     */
+    get zoom(): number;
+    /**
+     * Subscribe to camera position changes.
+     * Also fires when limits are applied via applyLimits() so components
+     * can re-evaluate disabled states without a separate callback.
+     */
+    onChange(callback: (position: CameraPositionState) => void): void;
+    /**
+     * Current camera movement limits (set from CONFIG message).
+     * Undefined until the server sends limits in its CONFIG payload.
+     */
+    get limits(): CameraLimits$1 | 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;
+    /**
+     * Handle incoming camera position message from server
+     */
+    handlePositionUpdate(message: CameraPositionMessage$1): 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;
+}
+
+/** The buyer's current configuration as attribute name→value pairs. */
+type Selection = Record<string, string>;
+
+/**
+ * The buyer's current configuration once it resolves to a price. `availability`
+ * is `available` (price + submit) or `view_only` (price, no submit); a matched
+ * `hidden` rule and a no-match both surface as `undefined` instead.
+ */
+interface ResolvedConfiguration {
+    readonly attributes: Record<string, string>;
+    readonly reference: string;
+    /** Price in minor units (cents), exactly as the source displays it. */
+    readonly price: number;
+    readonly currency: string;
+    readonly availability: 'available' | 'view_only';
+}
+/**
+ * What submit hands to the host: the buyer's selection and the reference to act
+ * on. Deliberately carries no price — the shop's checkout price is binding and
+ * ours is display-only, so handing it into the cart hand-off would only invite a
+ * wrong-price error. Price stays on the display side (`current`, `onChange`).
+ */
+interface SubmittedConfiguration {
+    readonly attributes: Record<string, string>;
+    readonly reference: string;
+}
+type ChangeCallback = (configuration: ResolvedConfiguration | undefined) => void;
+type SubmitCallback = (configuration: SubmittedConfiguration) => void | Promise<unknown>;
+type Dispatch<T> = (detail: T) => void;
+/** Options for {@link Configuration.onSubmit}. */
+interface SubmitOptions {
+    /** Fallback button label when the customer authored none (the adapter brings it). */
+    readonly defaultLabel?: string;
+}
+/**
+ * Configuration API — resolves the buyer's selection to a reference + price and
+ * carries it to the host page.
+ *
+ * Follows the existing facade style (`client.camera`, `client.focus`). It holds
+ * the pricing document and the latest selection, re-resolving on every change.
+ * `onChange` fires with the resolved configuration (or `undefined` when nothing
+ * matches); alongside it the container dispatches a bubbling `vd:configuration-change`
+ * CustomEvent so a page reacts without registering a callback. `onSubmit` registers
+ * the host handler that the CTA hands the configuration to.
+ */
+declare class Configuration {
+    private readonly dispatchChange;
+    private readonly dispatchSubmit;
+    private pricing;
+    private selection;
+    private resolved;
+    private readonly changeCallbacks;
+    private readonly renderCallbacks;
+    private submitCallback;
+    private submitDefaultLabel;
+    constructor(dispatchChange: Dispatch<ResolvedConfiguration | undefined>, dispatchSubmit: Dispatch<SubmittedConfiguration>);
+    /** The resolved configuration, or undefined when nothing matches. */
+    get current(): ResolvedConfiguration | undefined;
+    /** The VAT label for bare embeds (e.g. "incl. btw"), or undefined without pricing. */
+    get vatDisplay(): string | undefined;
+    /**
+     * The CTA label: the customer's `button_label`, or the adapter's `defaultLabel`
+     * when that is empty. Undefined when neither is set — a button must know what
+     * it says, so the CTA does not render.
+     */
+    get buttonLabel(): string | undefined;
+    /**
+     * Whether the current configuration may be submitted: a handler is registered
+     * and the configuration is either price-less or an `available` priced one. The
+     * CTA's visibility ({@link submitEnabled}) layers a label requirement on top of
+     * this; a programmatic `submit()` does not need a label.
+     */
+    private get submittable();
+    /**
+     * Whether the CTA should render: the configuration is submittable and a label
+     * exists. A button must say something, so an empty label hides the CTA rather
+     * than rendering blank.
+     */
+    get submitEnabled(): boolean;
+    /**
+     * Subscribe to configuration changes. Fires after every selection change with
+     * the resolved configuration, including undefined when nothing matches.
+     */
+    onChange(callback: ChangeCallback): void;
+    /**
+     * Register the submit handler the CTA hands the configuration to. Registering
+     * one is what switches the button on (capability driven). `defaultLabel` fills
+     * in when the customer authored no button label.
+     */
+    onSubmit(callback: SubmitCallback, options?: SubmitOptions): void;
+    /**
+     * Subscribe the built-in UI to re-render the price + CTA. Fires on every
+     * resolve and when a submit handler is registered (which can switch the button
+     * on without a configuration change). Separate from `onChange`, which stays the
+     * host-facing, mutation-driven contract. Returns a disposer.
+     */
+    onRender(callback: () => void): () => void;
+    /**
+     * Hand the current configuration to the registered handler and fire the
+     * bubbling `vd:configuration-submit` event. No-op without a handler or a
+     * resolved configuration. Returns the handler's promise so the caller can
+     * reflect the result (bezig / gelukt / mislukt).
+     */
+    submit(): Promise<void>;
+    /** Called by the client when a PRICING message arrives from the viewer. */
+    handlePricingReceived(pricing: PricingDocument$1): void;
+    /** Called by the client after every mutation result, with the full selection. */
+    handleSelectionChanged(selection: Selection): void;
+    private recompute;
+    private notifyRender;
+    private resolve;
+}
+
+interface PhotoData {
+    readonly filename: string;
+    readonly data: string;
+}
+/**
+ * Represents a photo being captured
+ * Pure domain object that manages callbacks for when the photo is developed
+ */
+declare class Photo {
+    private readonly filename;
+    private readonly developedCallbacks;
+    private readonly errorCallbacks;
+    private developed;
+    private failed;
+    private photoData;
+    constructor(filename: string);
+    /**
+     * Register a callback for when the photo is developed
+     * If the photo is already developed, the callback is called immediately
+     *
+     * @param callback Function to call with photo data
+     * @returns This Photo instance for chaining
+     */
+    onDeveloped(callback: (photo: PhotoData) => void): this;
+    /**
+     * Register a callback for when the photo capture fails
+     *
+     * @param callback Function to call with error
+     * @returns This Photo instance for chaining
+     */
+    onError(callback: (error: VirtualdisplayError) => void): this;
+    /**
+     * Get the filename for this photo
+     */
+    getFilename(): string;
+    /**
+     * Mark the photo as developed and notify all callbacks
+     * This method is called by Snapshot when the photo data arrives from the server
+     */
+    develop(photoData: PhotoData): void;
+    /**
+     * Mark the photo as failed and notify error callbacks
+     */
+    fail(error: VirtualdisplayError): void;
+}
+
+/**
+ * API for taking screenshots of the 3D model
+ * Following the camera analogy: take() triggers capture, onDeveloped() gets result
+ */
+declare class Snapshot {
+    private readonly send;
+    private readonly validExtensions;
+    private readonly pendingPhotos;
+    constructor(send: MessageCallback);
+    /**
+     * Take a snapshot of the current 3D model view
+     *
+     * @param filename The filename for the snapshot (must include valid extension)
+     * @returns Photo object for registering callbacks
+     * @throws VirtualdisplayError if filename is invalid
+     */
+    take(filename: string): Photo;
+    /**
+     * 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;
+    /**
+     * Fail any pending photos and forget them. Called from client destroy
+     * so callers awaiting onError() see a deterministic outcome instead of
+     * leaking captures whose results will never arrive.
+     */
+    clear(): void;
+    /**
+     * Validate filename has a valid image extension
+     */
+    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.
+ */
+declare const MESSAGE_TYPES: {
+    readonly HANDSHAKE: "handshake";
+    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 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;
+    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;
+}
+interface AttributeDefinition {
+    readonly name: string;
+    readonly values: string[];
+    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;
+}
+/**
+ * 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;
+}
+/**
+ * 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.
+ */
+interface FocusStateMessage {
+    readonly type: typeof MESSAGE_TYPES.FOCUS;
+    readonly state: FocusStateValue;
+    readonly component?: string;
+    readonly attributes?: string[];
+}
+/**
+ * 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[];
+}
+/**
+ * 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;
+}
+type Message = HandshakeMessage | MutationMessage | MutationResultMessage | CameraCommandMessage | CameraPositionMessage | SnapshotRequestMessage | SnapshotResultMessage | MappingMessage | LoadingIndicatorMessage | ArActivateMessage | ConfigMessage | AnnotationPlaceModeMessage | AnnotationPlacedMessage | AnnotationToggleMessage | FocusMessage | FocusStateMessage | PricingMessage;
+
+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.
+ */
+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;
+}
+
+/**
+ * Main Virtualdisplay Client — composition root.
+ * Wires all services together and exposes the public API.
+ */
+declare class VirtualdisplayClient {
+    private readonly attributes;
+    private readonly readyStateTracker;
+    private readonly messenger;
+    private readonly cameraApi;
+    private readonly cameraPositionApi;
+    private readonly focusApi;
+    private readonly configurationApi;
+    private readonly snapshotApi;
+    private readonly annotationsApi;
+    private readonly eventBus;
+    private readonly ui;
+    private readonly qrModal;
+    private readonly options;
+    private iframe;
+    private container;
+    private readyCallbacks;
+    private readonly mutationFailedCallbacks;
+    constructor(options: ClientOptions);
+    private registerHandlers;
+    /** Handlers that feed viewer-reported state into the facades (focus, pricing). */
+    private registerFacadeStateHandlers;
+    /**
+     * Dispatch a bubbling `vd:focus-change` event on the container so a page can
+     * react to focus without registering an `onChange` callback.
+     */
+    private dispatchFocusChange;
+    /**
+     * Dispatch a bubbling `vd:configuration-change` event on the container so a
+     * page or tag manager can react to price changes without a client callback.
+     */
+    private dispatchConfigurationChange;
+    /** Dispatch a bubbling `vd:configuration-submit` event when the CTA is used. */
+    private dispatchConfigurationSubmit;
+    private handleConfig;
+    private activateAr;
+    private initializeLogging;
+    private createAndConnectIframe;
+    select(name: string, value: string): void;
+    getValues(name: string): AttributeValue[];
+    getValue(name: string, value: string): AttributeValue | undefined;
+    onChange(name: string, callback: (selectedValue: AttributeValue) => void): void;
+    getAttribute(name: string): Attribute | undefined;
+    get isReady(): boolean;
+    onReady(callback: (client: VirtualdisplayClient) => void): void;
+    onMutationFailed(callback: (event: MutationFailedEvent) => void): void;
+    on<T extends VirtualdisplayUiEventType>(type: T, callback: (event: VirtualdisplayUiEventMap[T]) => void): void;
+    get annotations(): Annotations;
+    get camera(): Camera;
+    get focus(): Focus;
+    get configuration(): Configuration;
+    get cameraPosition(): CameraPosition;
+    get snapshot(): Snapshot;
+    get viewerSettings(): ViewerSettings;
+    destroy(): void;
+}
+
+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 };