@virtualdisplay.io/client 4.0.0-alpha.29 → 4.0.0-alpha.30

package/dist/index.d.ts

@@ -1,29 +1,3 @@
-/**
- * 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";
-    readonly SELECTABLE: "selectable";
-    readonly APP_RESOLVED: "app_resolved";
-};
 /** The app types this protocol version knows. The wire field stays a plain
  * string on purpose: a newer viewer may report a type this bundle predates,
  * and the host must receive it to fail visibly (never a quiet downgrade). */
@@ -35,100 +9,6 @@ interface AppSubmitSettings {
     readonly ctaLabel?: string;
     readonly privacyUrl?: string;
 }
-/**
- * Viewer -> client: which app this viewer resolved, reported up so the parent
- * (the embed host) can load the matching shell without its own resolve (the
- * apps spec's one-read inversion). Sent once, after the resolve, before or
- * with MAPPING.
- */
-interface AppResolvedMessage {
-    readonly type: typeof MESSAGE_TYPES.APP_RESOLVED;
-    /** Known values: {@link AppType}. An unknown value means a newer server; the host reports it, never downgrades. */
-    readonly appType: string;
-    readonly name: string;
-    /** The app's public slug, the address a submit POSTs to. Optional on the
-     * wire: a pre-task-60 server does not send it, and the pair-form host has
-     * no other way to learn it, so the shell treats absence as "submit
-     * unavailable" rather than the guard dropping the whole report. */
-    readonly slug?: string;
-    readonly submit?: AppSubmitSettings;
-}
-/** One mesh or material variant in a model, as reported by STATE. */
-interface ModelNodeDto {
-    readonly id: string;
-    readonly name: string;
-    readonly type: string;
-    readonly visible: boolean;
-}
-/**
- * State (viewer → client): the meshes and material variants of one instance,
- * with their current visibility.
- */
-interface StateMessage {
-    readonly type: typeof MESSAGE_TYPES.STATE;
-    /** Whose meshes and variants these are. */
-    readonly instance: string;
-    readonly nodes: ModelNodeDto[];
-    readonly isInitial: boolean;
-}
-interface MutationDto {
-    readonly name: string;
-    readonly value: string;
-}
-interface MutationResult {
-    readonly name: string;
-    readonly value: string;
-    readonly success: boolean;
-    readonly error?: string;
-}
-/** One instance's configuration: attribute name to the value selected for it. */
-type InstanceAttributes = Readonly<Record<string, string>>;
-/**
- * The folded session state carried by a live sync broadcast: the same shape the
- * public session-state read returns. It is authoritative, where `mutations` on
- * the same message is only the change that triggered the broadcast.
- */
-interface SyncStateSnapshot {
-    readonly license: string;
-    readonly model: string;
-    /** The folded configuration, keyed by instance and then by attribute name. */
-    readonly attributes: Readonly<Record<string, InstanceAttributes>>;
-}
-interface MutationMessage {
-    readonly type: typeof MESSAGE_TYPES.MUTATION;
-    /** Which instance's attributes these mutations change. */
-    readonly instance: string;
-    readonly mutations: MutationDto[];
-    readonly isInitial: boolean;
-    /** The sending page's session id, present when the mutation came from another device. */
-    readonly origin?: string;
-    /** The sender's per-session sequence number. */
-    readonly seq?: number;
-    /** The authoritative session state at the moment of the broadcast. */
-    readonly state?: SyncStateSnapshot;
-    /**
-     * A drag's intermediate step: the viewer applies it so the model follows the
-     * hand but does not record it. The settled value arrives afterwards as an
-     * ordinary mutation without this flag.
-     */
-    readonly transient?: boolean;
-}
-/**
- * Sync status (viewer → client): whether the live channel is connected to the
- * hand-off session. One-way and latest-wins, with no history or buffering. The
- * client exposes it as `onSyncChange`.
- */
-interface SyncMessage {
-    readonly type: typeof MESSAGE_TYPES.SYNC;
-    readonly connected: boolean;
-}
-interface MutationResultMessage {
-    readonly type: typeof MESSAGE_TYPES.MUTATION;
-    /** Which instance these results are for; without it a failure cannot say whose. */
-    readonly instance: string;
-    readonly results: MutationResult[];
-    readonly isInitial: boolean;
-}
 /**
  * How a model's annotations present to the visitor: never (hide), always
  * (show), or under their own control via a viewer toggle, starting visible
@@ -169,61 +49,6 @@ interface CameraLimits {
     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;
-}
-/**
- * Marks an attribute as a measurement (a parametric dimension): the values
- * are millimetre integer strings, and this carries what a client needs to
- * render a measurement control and format the unit. Absent for ordinary
- * attributes; a client that ignores it still renders the value list.
- */
-interface DimensionDescriptor {
-    readonly displayUnit: 'mm' | 'cm' | 'm' | 'in';
-    readonly minMm: number;
-    readonly maxMm: number;
-    readonly stepMm: number;
-}
-interface AttributeDefinition {
-    readonly name: string;
-    readonly values: string[];
-    readonly defaultValue?: string;
-    /** Present when this attribute is a measurement; see DimensionDescriptor. */
-    readonly dimension?: DimensionDescriptor;
-}
-interface MappingMessage {
-    readonly type: typeof MESSAGE_TYPES.MAPPING;
-    /**
-     * Whose attributes these are. One MAPPING per instance, and an instance with
-     * no attributes sends an empty one rather than none: silence would leave the
-     * client unable to name it, click it or report its interactions.
-     */
-    readonly instance: string;
-    readonly attributes: AttributeDefinition[];
-}
 /** Per selector, the values the buyer can still pick right now. */
 interface SelectableAttribute {
     readonly name: string;
@@ -236,132 +61,6 @@ interface SelectableAttribute {
      */
     readonly hidden?: boolean;
 }
-/**
- * Selectability snapshot (viewer → client): which values can still be picked,
- * sent after the mapping and after every choice that changes the picture.
- * Always the complete state, never a difference; a value not in its list is
- * not pickable and the client greys it out.
- */
-interface SelectableMessage {
-    readonly type: typeof MESSAGE_TYPES.SELECTABLE;
-    /** Whose attributes these are, mirroring the MAPPING it follows. */
-    readonly instance: string;
-    readonly attributes: SelectableAttribute[];
-}
-/**
- * Loading indicator (viewer → client): download progress, the phase it is in, or
- * an error, sent while the model loads so the client's loading UI can follow.
- */
-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 → viewer): the desktop hand-off QR was displayed. One-way and
- * fire-and-forget, with nothing to act on.
- */
-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;
-    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;
-    /**
-     * Whose pins to show. This looks scene-wide because the client draws one
-     * button, and it is not: a pin's position is stored in its model's local
-     * space, so it means nothing without the root it belongs to. A client that
-     * wants one button loops over the instances, which is a UI decision.
-     */
-    readonly instance: string;
-    readonly enabled: boolean;
-    /**
-     * Who sent it: `control` marks the client's own visible toggle button, the
-     * only sender that counts as Shopper use in the viewer statistics. Absent
-     * means programmatic (the boot-time config echo, an integrator's
-     * `client.annotations` call), which must never be measured as interest.
-     */
-    readonly origin?: 'control';
-}
-/** 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 → viewer): isolate and frame one component, or return to the
- * overview. `component` is a name from the model's components, or a mesh name as
- * a fallback, and is required when the action is `focus`.
- */
-interface FocusMessage {
-    readonly type: typeof MESSAGE_TYPES.FOCUS;
-    /** Which instance the component name resolves inside. */
-    readonly instance: string;
-    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;
-    /** Which instance this state is about. */
-    readonly instance: string;
-    readonly state: FocusStateValue;
-    readonly component?: string;
-    readonly attributes?: string[];
-}
 /**
  * What the configurator does with a matched configuration.
  */
@@ -408,172 +107,6 @@ interface PricingDocument {
     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;
-    /**
-     * Which instance is priced. Only one is today, so the id has no alternative
-     * value to hold; it carries one anyway, because a rule with a "not needed
-     * yet" exception erodes, and a scene of separately priced products needs
-     * exactly this field.
-     */
-    readonly instance: string;
-    readonly pricing: PricingDocument;
-}
-type Message = HandshakeMessage | SessionMessage | MutationMessage | MutationResultMessage | CameraCommandMessage | CameraPositionMessage | SnapshotRequestMessage | SnapshotResultMessage | MappingMessage | LoadingIndicatorMessage | ArActivateMessage | FullscreenMessage | ConfigMessage | AnnotationToggleMessage | FocusMessage | FocusStateMessage | PricingMessage | QrShownMessage | SyncMessage | SelectableMessage | AppResolvedMessage | StateMessage;
-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;
-    /**
-     * Which protocol to validate incoming messages against, never whether to
-     * validate: both sides always reject unknown types and browser-extension
-     * noise. Defaults to the public protocol.
-     */
-    isValid?: (data: unknown) => boolean;
-}
-/**
- * A bidirectional message port between a parent page and an iframe.
- *
- * @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 Viewer (inside the iframe, both queues)
- * ```ts
- * const messenger = new IframeMessenger(
- *   () => window.parent !== window ? window.parent : null,
- *   { bufferIncoming: true },
- * );
- * 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 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;
-    /**
-     * 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;
-    /**
-     * Route a message as if it had arrived by postMessage, without the round trip.
-     * Still validated against `isValid` and still subject to the consumer queue.
-     */
-    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;
-    private post;
-    private routeToHandler;
-}
-
-/**
- * The client's DOM event names, in one registry. The two selection events are
- * what `client.on(...)` subscribes to; the other three bubble out of the
- * container, so the host page can reach them with `addEventListener`.
- */
-declare const VD_EVENTS: {
-    /** Attribute selection requested (cancelable, does not bubble). `detail`: `{ attribute, value }`. */
-    readonly SELECT: "vd:select";
-    /** Attribute selection applied (does not bubble). `detail`: `{ attribute, value }`. */
-    readonly SELECTED: "vd: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];
-
-/** Hands a message to the viewer iframe. */
-type SendFn = (message: Message) => void;
-interface MutationFailedEvent {
-    readonly attribute: string;
-    readonly value: string;
-}
-/**
- * Which app the viewer resolved, as handed to an `onAppResolved` callback.
- */
-interface ResolvedAppInfo {
-    /** Known values: `AppType`. An unknown value means a newer server; report it, never downgrade to a viewer. */
-    readonly appType: string;
-    readonly name: string;
-    /** The app's public slug (the address a submit POSTs to). Absent from a pre-slug server. */
-    readonly slug?: string;
-    readonly submit?: AppSubmitSettings;
-}
-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;
 
 /**
  * Annotation display: show or hide the model's existing markers.
@@ -582,9 +115,6 @@ declare class Annotations {
     private readonly send;
     /** Whose pins this facade toggles: a pin lives in one model's local space. */
     private readonly instance;
-    constructor(send: SendFn, 
-    /** Whose pins this facade toggles: a pin lives in one model's local space. */
-    instance: string);
     setEnabled(enabled: boolean): void;
 }
 
@@ -597,7 +127,6 @@ type SelectableSnapshot = readonly SelectableAttribute[];
 declare class Camera {
     private readonly send;
     private commands;
-    constructor(send: MessageCallback);
     /**
      * Rotate camera horizontally
      * @param degrees - Absolute rotation in degrees (0 = front view)
@@ -645,7 +174,6 @@ declare class CameraPosition {
     private readonly state;
     private limitsState;
     private readonly changeCallbacks;
-    constructor();
     /**
      * Get current rotation in degrees
      */
@@ -659,9 +187,9 @@ declare class CameraPosition {
      */
     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.
+     * Subscribe to camera position changes. Also fires when the viewer reports new
+     * movement limits, so controls can re-evaluate their disabled state without a
+     * second callback.
      */
     onChange(callback: (position: CameraPositionState) => void): void;
     /**
@@ -669,24 +197,8 @@ declare class CameraPosition {
      * 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
@@ -710,9 +222,6 @@ 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). */
@@ -734,7 +243,6 @@ declare class Configuration {
     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. */
@@ -762,20 +270,13 @@ declare class Configuration {
      * Subscribe to configuration changes. Fires after every selection change with
      * the resolved configuration, including undefined when nothing matches.
      */
-    onChange(callback: ChangeCallback): void;
+    onChange(callback: (configuration: ResolvedConfiguration | undefined) => void): 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;
+    onSubmit(callback: (configuration: SubmittedConfiguration) => void | Promise<unknown>, options?: SubmitOptions): void;
     /**
      * Hand the current configuration to the registered handler and fire the
      * bubbling `vd:configuration-submit` event. No-op without a handler or a
@@ -783,10 +284,6 @@ declare class Configuration {
      * reflect the result (bezig / gelukt / mislukt).
      */
     submit(): Promise<void>;
-    /** Called by the client when a PRICING message arrives from the viewer. */
-    handlePricingReceived(pricing: PricingDocument): void;
-    /** Called by the client after every mutation result, with the full selection. */
-    handleSelectionChanged(selection: Selection): void;
     private recompute;
     private notifyRender;
     private resolve;
@@ -797,9 +294,6 @@ interface FocusState {
     readonly component: string;
     readonly attributes: string[];
 }
-type FocusChange = FocusState | null;
-type FocusChangeCallback = (state: FocusChange) => void;
-type DispatchFn = (state: FocusChange) => void;
 /**
  * Isolate and frame one component, or return to the overview. Alongside
  * `onChange` the container dispatches a bubbling `vd:focus-change` event, so a
@@ -813,9 +307,6 @@ declare class Focus {
     private focused;
     private attributes;
     private readonly changeCallbacks;
-    constructor(send: MessageCallback, dispatch: DispatchFn, 
-    /** Which instance this facade addresses; every message it sends carries it. */
-    instance: string);
     /** The focused component name, or null in overview. */
     get current(): string | null;
     /**
@@ -829,9 +320,7 @@ declare class Focus {
      * 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;
+    onChange(callback: (state: FocusState | null) => void): void;
 }
 
 /**
@@ -872,7 +361,6 @@ declare class Photo {
     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
@@ -892,15 +380,6 @@ declare class Photo {
      * 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;
 }
 
 /**
@@ -911,7 +390,6 @@ declare class Snapshot {
     private readonly send;
     private readonly validExtensions;
     private readonly pendingPhotos;
-    constructor(send: MessageCallback);
     /**
      * Take a snapshot of the current 3D model view
      *
@@ -920,11 +398,6 @@ declare class Snapshot {
      * @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
@@ -945,17 +418,9 @@ 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
@@ -966,7 +431,6 @@ declare class Attribute {
     private readonly values;
     private readonly onSelect;
     private onChangeCallback?;
-    constructor(options: AttributeOptions);
     /**
      * Select a value for this attribute
      * @throws {VirtualdisplayError} When value not found
@@ -981,90 +445,58 @@ declare class Attribute {
      * 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;
 }
 
 /**
- * The integrator-facing viewer settings override. Identical to the wire
- * `ViewerSettings`, except `annotations` also accepts the legacy booleans:
- * they normalise before the merge (`true` → `show`, `false` → `hide`), so
- * existing mounts keep compiling while the package is in alpha.
+ * The client's DOM event names, in one registry. The two selection events are
+ * what `client.on(...)` subscribes to; the other three bubble out of the
+ * container, so the host page can reach them with `addEventListener`.
  */
-type ViewerSettingsOverride = Omit<Partial<ViewerSettings>, 'annotations'> & {
-    readonly annotations?: boolean | AnnotationVisibility;
+declare const VD_EVENTS: {
+    /** Attribute selection requested (cancelable, does not bubble). `detail`: `{ attribute, value }`. */
+    readonly SELECT: "vd:select";
+    /** Attribute selection applied (does not bubble). `detail`: `{ attribute, value }`. */
+    readonly SELECTED: "vd: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";
 };
-/**
- * Options shared by both address forms.
- */
-interface ClientOptionsBase {
-    readonly parent: string | HTMLElement;
-    readonly debug?: boolean | undefined;
-    readonly language?: string | undefined;
-    /** W3C traceparent string to propagate to the viewer iframe for end-to-end tracing. */
-    readonly traceparent?: string | undefined;
-    /**
-     * A source viewer session id to restore into this mount (ar-session-handoff): the
-     * iframe's metadata fetch merges that session's latest configuration into the
-     * attribute defaults, so the viewer boots straight into it. Internal option, used
-     * by the AR landing, not a customer-facing setting.
-     */
-    readonly session?: string | undefined;
-    /**
-     * 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?: ViewerSettingsOverride;
+type VdEvent = typeof VD_EVENTS[keyof typeof VD_EVENTS];
+
+interface MutationFailedEvent {
+    readonly attribute: string;
+    readonly value: string;
 }
 /**
- * What the client shows, given either way of naming it: `{ app }`, an app's
- * public link key, or `{ license, model }`, which resolves to that model's
- * default app. Given both, `app` wins and the pair is ignored with a warning.
- */
-type ClientAddress = {
-    readonly app: string;
-    readonly license?: string | undefined;
-    readonly model?: string | undefined;
-} | {
-    readonly license: string;
-    readonly model: string;
-    readonly app?: undefined;
-};
-/**
- * Configuration options for VirtualdisplayClient
+ * Which app the viewer resolved, as handed to an `onAppResolved` callback.
  */
-type ClientOptions = ClientOptionsBase & ClientAddress;
-
-/** The AR flow behind the standard interface's AR button. */
-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;
+interface ResolvedAppInfo {
+    /** Known values: `AppType`. An unknown value means a newer server; report it, never downgrade to a viewer. */
+    readonly appType: string;
+    readonly name: string;
+    /** The app's public slug (the address a submit POSTs to). Absent from a pre-slug server. */
+    readonly slug?: string;
+    readonly submit?: AppSubmitSettings;
 }
-/** The live channel's connection status, as the client surfaces it. */
-interface SyncTracker {
-    /** Latest-wins, no buffering: the channel's current connection state. */
-    handleSync(connected: boolean): void;
+interface VirtualdisplaySelectEvent {
+    readonly attribute: string;
+    readonly value: string;
+    preventDefault(): void;
 }
-/** What a subclass layers onto the base composition instead of re-implementing it. */
-interface BaseClientExtensions {
-    readonly messengerOptions?: MessengerOptions;
-    readonly registerHandlers?: (messenger: IframeMessenger, send: SendFn) => void;
-    /** The viewer host this client's iframe targets. Unset means the default viewer. */
-    readonly serverHost?: string;
-    /** A client type's fixed capability flags, appended to the viewer iframe URL. */
-    readonly iframeParams?: Readonly<Record<string, string>>;
-    /** Builds the AR flow behind the standard interface's AR button. */
-    readonly createArActivation?: (send: SendFn) => ArFlow;
-    /** Builds the tracker behind `onSyncChange`. */
-    readonly createSyncTracker?: () => SyncTracker;
+interface VirtualdisplaySelectedEvent {
+    readonly attribute: string;
+    readonly value: string;
 }
+type VirtualdisplayUiEventMap = {
+    [VD_EVENTS.SELECT]: VirtualdisplaySelectEvent;
+    [VD_EVENTS.SELECTED]: VirtualdisplaySelectedEvent;
+};
+type VirtualdisplayUiEventType = keyof VirtualdisplayUiEventMap;
+
 /**
  * The shared client composition root: wires the transport, facades and UI, and
  * exposes the integrator-facing API.
@@ -1085,52 +517,27 @@ declare class BaseClient {
     private readonly options;
     private readonly serverHost;
     private readonly iframeParams;
-    /** The composed AR flow, or undefined in a build that composes none. */
     private readonly arActivation;
-    /** The composed sync tracker, or undefined in a build that composes none. */
     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;
-    /** Which app the viewer resolved, once reported (APP_RESOLVED). */
     private resolvedApp;
     private readonly appResolvedCallbacks;
-    constructor(options: ClientOptions, extensions?: BaseClientExtensions);
-    /** The configurator UI, every callback bridging it to the facade that owns the action. */
     private createStandardInterface;
     private sendControlAnnotationToggle;
-    /** Wire the inbound viewer protocol to the facades. */
     private wireIncomingMessages;
-    /** Store the resolved app and notify every registered `onAppResolved` callback. */
     private handleAppResolved;
-    /** 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 about the annotation mode only when the merged mode differs
-     * from the one it announced.
-     */
     private echoAnnotationsDifference;
-    /** Tell the viewer the user entered fullscreen, so it records the engagement. */
     private trackFullscreen;
     private initializeLogging;
     private createAndConnectIframe;
@@ -1174,16 +581,65 @@ declare class BaseClient {
     destroy(): void;
 }
 
-type Attrs = Record<string, unknown> | unknown;
+/**
+ * The integrator-facing viewer settings override. Identical to the wire
+ * `ViewerSettings`, except `annotations` also accepts the legacy booleans:
+ * they normalise before the merge (`true` → `show`, `false` → `hide`), so
+ * existing mounts keep compiling while the package is in alpha.
+ */
+type ViewerSettingsOverride = Omit<Partial<ViewerSettings>, 'annotations'> & {
+    readonly annotations?: boolean | AnnotationVisibility;
+};
+/**
+ * Options shared by both address forms.
+ */
+interface ClientOptionsBase {
+    readonly parent: string | HTMLElement;
+    readonly debug?: boolean | undefined;
+    readonly language?: string | undefined;
+    /** W3C traceparent string to propagate to the viewer iframe for end-to-end tracing. */
+    readonly traceparent?: string | undefined;
+    /**
+     * A source viewer session id to restore into this mount (ar-session-handoff): the
+     * iframe's metadata fetch merges that session's latest configuration into the
+     * attribute defaults, so the viewer boots straight into it. Internal option, used
+     * by the AR landing, not a customer-facing setting.
+     */
+    readonly session?: string | undefined;
+    /**
+     * 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?: ViewerSettingsOverride;
+}
+/**
+ * What the client shows, given either way of naming it: `{ app }`, an app's
+ * public link key, or `{ license, model }`, which resolves to that model's
+ * default app. Given both, `app` wins and the pair is ignored with a warning.
+ */
+type ClientAddress = {
+    readonly app: string;
+    readonly license?: string | undefined;
+    readonly model?: string | undefined;
+} | {
+    readonly license: string;
+    readonly model: string;
+    readonly app?: undefined;
+};
+/**
+ * Configuration options for VirtualdisplayClient
+ */
+type ClientOptions = ClientOptionsBase & ClientAddress;
+
 /**
  * The logger the client exposes: the same four levels as the base logger, but
  * accepting any value as attributes so callers can pass an Error or a bare value.
  */
 interface ClientLogger {
-    debug: (msg: string, attrs?: Attrs) => void;
-    info: (msg: string, attrs?: Attrs) => void;
-    warn: (msg: string, attrs?: Attrs) => void;
-    error: (msg: string, attrs?: Attrs) => void;
+    debug: (msg: string, attrs?: unknown) => void;
+    info: (msg: string, attrs?: unknown) => void;
+    warn: (msg: string, attrs?: unknown) => void;
+    error: (msg: string, attrs?: unknown) => void;
 }
 declare let logger: ClientLogger;
 declare function enableDebugMode(): void;
@@ -1200,5 +656,5 @@ declare class VirtualdisplayClient extends BaseClient {
     onSyncChange(callback: (connected: boolean) => void): void;
 }
 
-export { Annotations, Attribute, AttributeValue, Camera, Configuration, ERROR_CODES, Focus, Photo, Snapshot, VD_EVENTS, VirtualdisplayClient, VirtualdisplayError, enableDebugMode, isDebugMode, logger };
-export type { AppSubmitSettings, AppType, Availability, ClientOptions, ErrorCode, FocusState, MutationFailedEvent, PhotoData, PricingDocument, PricingRule, ResolvedAppInfo, ResolvedConfiguration, SubmitOptions, SubmittedConfiguration, VdEvent, ViewerSettings, VirtualdisplaySelectEvent, VirtualdisplaySelectedEvent, VirtualdisplayUiEventMap, VirtualdisplayUiEventType };
+export { AVAILABILITY, Annotations, Attribute, AttributeValue, Camera, CameraPosition, Configuration, ERROR_CODES, Focus, Photo, Snapshot, VD_EVENTS, VirtualdisplayClient, VirtualdisplayError, enableDebugMode, isDebugMode, logger };
+export type { AnnotationVisibility, AppSubmitSettings, AppType, Availability, CameraLimits, CameraPositionState, ClientAddress, ClientLogger, ClientOptions, ClientOptionsBase, ErrorCode, FocusState, MutationFailedEvent, PhotoData, PricingDocument, PricingRule, ResolvedAppInfo, ResolvedConfiguration, SelectableAttribute, SelectableSnapshot, SubmitOptions, SubmittedConfiguration, VdEvent, ViewerSettings, ViewerSettingsOverride, VirtualdisplaySelectEvent, VirtualdisplaySelectedEvent, VirtualdisplayUiEventMap, VirtualdisplayUiEventType };