@virtualdisplay.io/client 4.0.0-alpha.2 → 4.0.0-alpha.21

package/dist/index.d.ts

@@ -1 +1,1158 @@
-export { }
+/**
+ * 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 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_TOGGLE: "annotation_toggle";
+    readonly FOCUS: "focus";
+    readonly PRICING: "pricing";
+    readonly QR_SHOWN: "qr_shown";
+    readonly SYNC: "sync";
+};
+interface MutationDto {
+    readonly name: string;
+    readonly value: string;
+}
+interface MutationResult {
+    readonly name: string;
+    readonly value: string;
+    readonly success: boolean;
+    readonly error?: string;
+}
+/**
+ * The folded family state riding along on a live sync channel broadcast
+ * (ar-session-handoff, sync-channel.md): the same shape the public
+ * session-state read returns. Authoritative self-heal input; `mutations`
+ * on the same message is only the delta that triggered the broadcast.
+ */
+interface SyncStateSnapshot {
+    readonly license: string;
+    readonly model: string;
+    readonly attributes: Record<string, string>;
+}
+interface MutationMessage {
+    readonly type: typeof MESSAGE_TYPES.MUTATION;
+    readonly mutations: MutationDto[];
+    readonly isInitial: boolean;
+    /**
+     * Live sync channel extras (ar-session-handoff, sync-channel.md), present
+     * only on a mutation the viewer engine's sync module received over the SSE
+     * live-state channel; a MutationMessage posted locally by the client never
+     * carries these. `origin` is the sender's page session id: its presence
+     * marks the mutation as remote, so the tracker must never record it again
+     * (the no-re-track loop guard, decision 15), and the sync module drops it
+     * when it equals the receiving engine's own session id (the echo filter).
+     * `seq` is the sender's per-session sequence number, used by the sync
+     * module to track how far the channel has progressed. `state` is the
+     * authoritative folded family state: the sync module diffs it against the
+     * channel's last-seen state and applies the difference, so a catch-up
+     * (empty `mutations`) or a broadcast the hub dropped still converges the
+     * subscriber. None of these fields are read by `MutationRouter`.
+     */
+    readonly origin?: string;
+    readonly seq?: number;
+    readonly state?: SyncStateSnapshot;
+}
+/**
+ * Sync channel status (server → client, ar-session-handoff, sync-channel.md):
+ * whether the viewer engine's live-state channel is currently connected to its
+ * hand-off family. One-way, latest-wins: no history, no buffering. The public
+ * client exposes it as `onSyncChange`; the studio composes nothing, so its
+ * engine never sends this (it never opens the channel).
+ */
+interface SyncMessage {
+    readonly type: typeof MESSAGE_TYPES.SYNC;
+    readonly connected: boolean;
+}
+interface MutationResultMessage {
+    readonly type: typeof MESSAGE_TYPES.MUTATION;
+    readonly results: MutationResult[];
+    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 {
+    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;
+}
+/**
+ * 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;
+}
+/**
+ * QR shown (client → server): the desktop QR hand-off modal (ar-session-handoff)
+ * was displayed to the shopper. The QR itself is generated client-side; this
+ * only lets the server record the engagement (`qr_shown`, the funnel's
+ * denominator) against the tracking session it owns. One-way, fire-and-forget,
+ * nothing to act on, same shape as FULLSCREEN.
+ */
+interface QrShownMessage {
+    readonly type: typeof MESSAGE_TYPES.QR_SHOWN;
+}
+/**
+ * Config (server → client): viewer settings and camera limits from model metadata.
+ * Sent early — before MAPPING — so the client can show/hide controls and disable
+ * camera buttons at limits as soon as metadata is available.
+ */
+interface ConfigMessage {
+    readonly type: typeof MESSAGE_TYPES.CONFIG;
+    readonly viewerSettings: ViewerSettings$1;
+    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 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$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 {
+    readonly type: typeof MESSAGE_TYPES.PRICING;
+    readonly pricing: PricingDocument$1;
+}
+type Message = HandshakeMessage | SessionMessage | MutationMessage | MutationResultMessage | CameraCommandMessage | CameraPositionMessage | SnapshotRequestMessage | SnapshotResultMessage | MappingMessage | LoadingIndicatorMessage | ArActivateMessage | FullscreenMessage | ConfigMessage | AnnotationToggleMessage | FocusMessage | FocusStateMessage | PricingMessage | QrShownMessage | SyncMessage;
+type MessageCallback = (message: Message) => void | Promise<void>;
+
+/**
+ * Options for IframeMessenger
+ */
+interface MessengerOptions {
+    /**
+     * Buffer incoming messages until markConsumerReady().
+     * When false (default), incoming messages are processed immediately.
+     */
+    bufferIncoming?: boolean;
+    /**
+     * When buffering, messages where this returns false bypass the buffer
+     * and are routed to handlers immediately. Used for urgent messages
+     * like CONFIG that must be handled before the model loads.
+     */
+    shouldBuffer?: (message: Message) => boolean;
+    /**
+     * Restrict postMessage to a specific origin (e.g. 'https://example.com').
+     * Defaults to '*' when not set. Set this when the target origin is known
+     * to prevent messages from being intercepted by unintended recipients.
+     */
+    targetOrigin?: string;
+    /**
+     * Which protocol to validate incoming messages against — not whether to validate.
+     * Both sides always reject browser-extension noise and unknown message types. The
+     * 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;
+}
+/**
+ * Bidirectional iframe message port
+ *
+ * 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 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);
+    /**
+     * Register a handler for a specific message type
+     */
+    on(type: string, handler: MessageCallback): void;
+    /**
+     * Remove a handler for a specific message type
+     */
+    off(type: string): void;
+    /**
+     * Update the target origin for outgoing postMessage calls.
+     * Use when the target origin is discovered at runtime (e.g. from the first incoming message).
+     */
+    setTargetOrigin(origin: string): void;
+    /**
+     * Send a message to the target window
+     * Queued until markReady() is called
+     */
+    send(message: Message): void;
+    /**
+     * Feed a message through the same routing path as one that just arrived via
+     * postMessage, without an actual postMessage round-trip: still validated
+     * against `isValid`, and still respects the consumer queue's buffering and
+     * the `shouldBuffer` bypass. For a transport that delivers messages some
+     * other way than the iframe channel this messenger already listens on (the
+     * viewer engine's SSE-sourced live sync channel, ar-session-handoff) and
+     * needs them to land exactly where a postMessage would.
+     */
+    receive(message: Message): void;
+    /**
+     * Enable sending and flush queued outgoing messages
+     */
+    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;
+}
+
+/**
+ * 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 | undefined;
+    /**
+     * Apply camera limits received from the server CONFIG message.
+     * Fires onChange callbacks so button disabled states update immediately.
+     */
+    applyLimits(limits: CameraLimits | undefined): void;
+    /**
+     * Handle incoming camera position message from server
+     */
+    handlePositionUpdate(message: CameraPositionMessage): void;
+    /**
+     * Update camera position from server transforms
+     */
+    update(transforms: CameraParameter[]): 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;
+}
+
+/** 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
+ * 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): 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;
+}
+
+/**
+ * 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;
+}
+
+/**
+ * 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;
+    /**
+     * A source viewer session id to restore into this mount (ar-session-handoff): the
+     * iframe's metadata fetch merges that session's latest configuration into the
+     * attribute defaults, so the viewer boots straight into it. Internal option, used
+     * by the AR landing, not a customer-facing setting.
+     */
+    readonly session?: string;
+    /**
+     * Override viewer settings from metadata. Omitted fields use the metadata value.
+     * A warning is logged when an override differs from the metadata value.
+     */
+    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];
+
+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;
+
+type SendFn = (message: Message) => void;
+/**
+ * The seam for the AR flow behind the standard interface's AR button. The base
+ * only routes to it: the implementation (mobile AR_ACTIVATE, desktop hand-off
+ * QR) lives in the public client package (`@virtualdisplay.io/client`), which
+ * composes it via {@link BaseClientExtensions.createArActivation}.
+ */
+interface ArFlow {
+    /** The AR button handler. */
+    activate(): void;
+    /** The engine-announced tracking session id (SESSION), which the flow may wait on. */
+    onSession(sessionId: string): void;
+    destroy(): void;
+}
+/**
+ * The seam for the live sync channel's connection status (ar-session-handoff,
+ * sync-channel.md). The base only routes SYNC messages to it; the concrete
+ * tracker (callback list + `onSyncChange`) lives in the public client package,
+ * composed via {@link BaseClientExtensions.createSyncTracker}. The studio
+ * composes nothing, so `onSyncChange` does not exist on the studio client
+ * (its engine never opens the channel, so it never sends SYNC either).
+ */
+interface SyncTracker {
+    /** Latest-wins, no buffering: the channel's current connection state. */
+    handleSync(connected: boolean): void;
+}
+/**
+ * Extensions a subclass (the studio client) layers onto the base composition without
+ * re-implementing it: a custom incoming-message validator and extra message handlers.
+ */
+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;
+    /**
+     * The AR flow behind the standard interface's AR button. The public client
+     * composes its `ArActivation` here; the studio composes nothing (the editor
+     * has no AR use case), so the base wires no AR button at all.
+     */
+    readonly createArActivation?: (send: SendFn) => ArFlow;
+    /**
+     * The live sync channel's connection tracker (ar-session-handoff). The
+     * public client composes a tracker and exposes `onSyncChange`; the studio
+     * composes nothing, so SYNC messages (which its own engine never sends
+     * anyway) are simply dropped.
+     */
+    readonly createSyncTracker?: () => SyncTracker;
+}
+/**
+ * The shared client composition root. Wires the engine (transport, facades, UI) and exposes
+ * 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 BaseClient {
+    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 options;
+    private readonly serverHost;
+    /** The composed AR flow, or undefined in builds without one (the studio). */
+    private readonly arActivation;
+    /** The composed sync tracker, or undefined in builds without one (the studio). */
+    private readonly syncTracker;
+    private iframe;
+    private container;
+    private readyCallbacks;
+    private readonly mutationFailedCallbacks;
+    /** 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;
+    /** Store the tracking session id and hand it to the AR flow, which waits on it for the QR. */
+    private handleSession;
+    /** Forward a failed mutation to every registered `onMutationFailed` callback. */
+    private notifyMutationFailed;
+    /** Flush the queued `onReady` callbacks once, then let the standard interface know. */
+    private notifyReady;
+    /**
+     * Dispatch a bubbling `vd:focus-change` event on the container so a page can
+     * react to focus without registering an `onChange` callback.
+     */
+    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;
+    /** Tell the viewer the user entered fullscreen, so it records the engagement. */
+    private trackFullscreen;
+    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: this) => void): void;
+    onMutationFailed(callback: (event: MutationFailedEvent) => void): void;
+    /**
+     * Trigger the composed AR flow directly (ar-session-handoff task 035): a host
+     * page that hides the built-in corner button (`viewerSettings.ar = false`,
+     * e.g. the AR landing, which owns a single custom AR affordance) still needs
+     * an entry point to the same flow that button would have called. A no-op
+     * where no AR flow is composed (the studio client has none).
+     */
+    activateAr(): void;
+    on<T extends VirtualdisplayUiEventType>(type: T, callback: (event: VirtualdisplayUiEventMap[T]) => void): void;
+    get annotations(): Annotations;
+    get camera(): Camera;
+    get focus(): Focus;
+    get configuration(): Configuration;
+    get cameraPosition(): CameraPosition;
+    get snapshot(): Snapshot;
+    /** 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`.
+ *
+ * The AR flow (mobile AR_ACTIVATE, desktop hand-off QR) is composed here: it is a shopper
+ * feature, so the studio client does not compose it and renders no AR button. The live sync
+ * channel's connection status (`onSyncChange`) is composed the same way: the studio client
+ * has no such method, its engine never opens the channel.
+ */
+declare class VirtualdisplayClient extends BaseClient {
+    private readonly syncStatusTracker;
+    constructor(options: ClientOptions);
+    /** Subscribe to the live sync channel's connection state (ar-session-handoff). Latest-wins, no buffering. */
+    onSyncChange(callback: (connected: boolean) => void): void;
+}
+
+/**
+ * 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 { Availability, ClientOptions, ErrorCode, FocusState, MutationFailedEvent, PhotoData, PricingDocument, PricingRule, ResolvedConfiguration, SubmitOptions, SubmittedConfiguration, VdEvent, ViewerSettings, VirtualdisplaySelectEvent, VirtualdisplaySelectedEvent, VirtualdisplayUiEventMap, VirtualdisplayUiEventType };