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

package/dist/index.d.ts

@@ -24,12 +24,13 @@ declare const MESSAGE_TYPES: {
     readonly SELECTABLE: "selectable";
     readonly APP_RESOLVED: "app_resolved";
 };
-/** The public submit settings of a configurator-type app, as the form renders
- * them. Never the recipient: that section is removed in SQL on the public
- * read and cannot ride any message. Sparse like every config section: an
- * absent field means the renderer's default (the backend stores the section
- * as written and omits empty keys), so nothing here is guaranteed present. */
-interface AppSubmitSettings$1 {
+/** 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). */
+type AppType = 'viewer' | 'configurator';
+/** What a configurator app's submit form renders. Any field may be absent; an
+ * absent field means the form's own default. */
+interface AppSubmitSettings {
     readonly fields?: string[];
     readonly ctaLabel?: string;
     readonly privacyUrl?: string;
@@ -50,7 +51,7 @@ interface AppResolvedMessage {
      * 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$1;
+    readonly submit?: AppSubmitSettings;
 }
 /** One mesh or material variant in a model, as reported by STATE. */
 interface ModelNodeDto {
@@ -62,11 +63,6 @@ interface ModelNodeDto {
 /**
  * State (viewer → client): the meshes and material variants of one instance,
  * with their current visibility.
- *
- * Its shape used to live in server-core, marked "server-only", while its type
- * value sat in the public MESSAGE_TYPES and the client read it: a public
- * message whose shape only one side declared, which is how two shapes of one
- * thing start to drift.
  */
 interface StateMessage {
     readonly type: typeof MESSAGE_TYPES.STATE;
@@ -85,16 +81,18 @@ interface MutationResult {
     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 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.
+ * 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;
-    readonly attributes: Record<string, 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;
@@ -102,39 +100,23 @@ interface MutationMessage {
     readonly instance: string;
     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 `MutationPipeline`.
-     */
+    /** 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 (parametric dimensions): the viewer applies it
-     * so the model follows the hand, but never tracks it, the settled value is
-     * the one recorded choice and it arrives as an ordinary mutation without
-     * this flag. Only the client knows when a drag settles, which is why this
-     * travels on the message instead of being guessed viewer-side.
+     * 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 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).
+ * 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;
@@ -148,17 +130,18 @@ interface MutationResultMessage {
     readonly isInitial: boolean;
 }
 /**
- * How a model's annotations present to the Shopper: never (hide), always
- * (show), or under the Shopper's own control via a viewer toggle, starting
- * visible (toggle-shown) or hidden (toggle-hidden). Resolved per app; the
- * backend's `Resolve` owns the `hide` default.
+ * How a model's annotations present to the visitor: never (hide), always
+ * (show), or under their own control via a viewer toggle, starting visible
+ * (toggle-shown) or hidden (toggle-hidden). Resolved per app, defaulting to
+ * hide.
  */
-type AnnotationVisibility$1 = 'hide' | 'show' | 'toggle-shown' | 'toggle-hidden';
+type AnnotationVisibility = 'hide' | 'show' | 'toggle-shown' | 'toggle-hidden';
 /**
- * Viewer settings from model metadata (server → client via MAPPING).
- * Customer-configured in the portal.
+ * Which viewer controls the model shows, as configured for it. Sent with the
+ * mapping; every field is optional and an absent field means the viewer's own
+ * default.
  */
-interface ViewerSettings$1 {
+interface ViewerSettings {
     readonly ar?: boolean;
     readonly fullscreen?: boolean;
     readonly screenshot?: boolean;
@@ -168,7 +151,7 @@ interface ViewerSettings$1 {
      * annotations, so a control can never render with nothing to govern;
      * absent means there is nothing to show or toggle.
      */
-    readonly annotations?: AnnotationVisibility$1;
+    readonly annotations?: AnnotationVisibility;
     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';
@@ -254,12 +237,10 @@ interface SelectableAttribute {
     readonly hidden?: boolean;
 }
 /**
- * Selectability snapshot (server → client): sent after the mapping and after
- * every choice that changes the picture. Always the complete state, never a
- * diff; a value not in its list is not pickable (the client greys it out).
- * The client only renders, it never knows the exclusion rules. Named
- * `selectable`, not availability: that word is taken by pricing
- * (AVAILABILITY, available/view_only).
+ * 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;
@@ -268,25 +249,8 @@ interface SelectableMessage {
     readonly attributes: SelectableAttribute[];
 }
 /**
- * Loading indicator (server → client): progress percentage, phase label, or error.
- * Sent during model download and parse so the client loading indicator can update.
- *
- * This message concerns one model at five of its seven call sites (download
- * progress, a load error, the rendering phase) and is fatal with no model to
- * blame at the other two (no WebGL, the boot-failure path), so by the
- * message-scope rule it takes an instance id optionally.
- *
- * It does not carry one yet, on purpose. `publishLoadingProgress` is the only
- * publisher and knows no instance, so the field would be absent at all seven
- * sites while its documented meaning is "absent means the viewer could not
- * start". An integrator branching on that would read every progress update as
- * a viewer failure, which is worse than no field at all.
- *
- * Nothing is lost by waiting: an optional field is additive, so unlike the
- * required ids in this file it carries no alpha-window pressure. Composition
- * task 10 brings a second model and with it the choice the spec parked, thread
- * the id through the five model sites, or split the fatal case onto its own
- * message. Decide it there, with a real second instance to test against.
+ * 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;
@@ -310,11 +274,8 @@ 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.
+ * 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;
@@ -326,7 +287,7 @@ interface QrShownMessage {
  */
 interface ConfigMessage {
     readonly type: typeof MESSAGE_TYPES.CONFIG;
-    readonly viewerSettings: ViewerSettings$1;
+    readonly viewerSettings: ViewerSettings;
     readonly cameraLimits?: CameraLimits;
 }
 interface HandshakeMessage {
@@ -356,6 +317,13 @@ interface AnnotationToggleMessage {
      */
     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: {
@@ -370,10 +338,9 @@ declare const FOCUS_STATES: {
 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`.
+ * 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;
@@ -396,10 +363,9 @@ interface FocusStateMessage {
     readonly attributes?: string[];
 }
 /**
- * What the configurator does with a matched configuration. Mirrors the backend
- * `availability` enum (pricing rule provenance lives on `PricingRule.source`).
+ * What the configurator does with a matched configuration.
  */
-declare const AVAILABILITY$1: {
+declare const AVAILABILITY: {
     /** Price and submit button both shown (default). */
     readonly AVAILABLE: "available";
     /** Price shown, submit hidden (sold out / coming soon). */
@@ -407,12 +373,12 @@ declare const AVAILABILITY$1: {
     /** Behaves exactly like an unpriced combination: no price, no button. */
     readonly HIDDEN: "hidden";
 };
-type Availability$1 = (typeof AVAILABILITY$1)[keyof typeof AVAILABILITY$1];
+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`).
+ * One pricing rule: a subset of attribute values mapped to a reference and a
+ * price.
  */
-interface PricingRule$1 {
+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
@@ -423,7 +389,7 @@ interface PricingRule$1 {
     readonly reference: string;
     /** Price in minor units (cents), exactly as the source displays it. */
     readonly priceCents: number;
-    readonly availability: Availability$1;
+    readonly availability: Availability;
     /** Provenance (manual | imported); audit-only, unused by the resolver. */
     readonly source: 'manual' | 'imported';
 }
@@ -431,7 +397,7 @@ interface PricingRule$1 {
  * A model's pricing document. The viewer's fetcher merges it into the model
  * metadata and the server forwards it to the client via {@link PricingMessage}.
  */
-interface PricingDocument$1 {
+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. */
@@ -440,7 +406,7 @@ interface PricingDocument$1 {
     readonly currency: string;
     /** VAT label for bare embeds, e.g. "incl. btw". */
     readonly vatDisplay: string;
-    readonly rules: PricingRule$1[];
+    readonly rules: PricingRule[];
 }
 /**
  * Pricing (server → client): the model's pricing document. Sent once at startup
@@ -455,7 +421,7 @@ interface PricingMessage {
      * exactly this field.
      */
     readonly instance: string;
-    readonly pricing: PricingDocument$1;
+    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>;
@@ -470,29 +436,16 @@ interface MessengerOptions {
      */
     bufferIncoming?: boolean;
     /**
-     * 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.
+     * 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;
 }
 /**
- * Bidirectional iframe message port
+ * A bidirectional message port between a parent page and an iframe.
  *
- * 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)
+ * @example Client (parent page, publisher queue only)
  * ```ts
  * const messenger = new IframeMessenger(() => iframe.contentWindow);
  * messenger.on('mutation', handleMutationResult);
@@ -503,7 +456,7 @@ interface MessengerOptions {
  * messenger.send({ type: 'mutation', mutations, isInitial: true });
  * ```
  *
- * @example Server (inside iframe — both queues)
+ * @example Viewer (inside the iframe, both queues)
  * ```ts
  * const messenger = new IframeMessenger(
  *   () => window.parent !== window ? window.parent : null,
@@ -542,13 +495,8 @@ declare class IframeMessenger {
      */
     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. 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.
+     * 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;
     /**
@@ -576,18 +524,65 @@ declare class IframeMessenger {
     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.
+ * 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.
  */
 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$1, 
+    constructor(send: SendFn, 
     /** Whose pins this facade toggles: a pin lives in one model's local space. */
     instance: string);
     setEnabled(enabled: boolean): void;
@@ -724,15 +719,10 @@ interface SubmitOptions {
     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.
+ * Resolves the current selection to a reference and a price, and carries it to
+ * the host page. `onChange` fires with the resolved configuration, or
+ * `undefined` when nothing matches; `onSubmit` registers the handler the CTA
+ * hands that configuration to.
  */
 declare class Configuration {
     private readonly dispatchChange;
@@ -794,7 +784,7 @@ declare class Configuration {
      */
     submit(): Promise<void>;
     /** Called by the client when a PRICING message arrives from the viewer. */
-    handlePricingReceived(pricing: PricingDocument$1): void;
+    handlePricingReceived(pricing: PricingDocument): void;
     /** Called by the client after every mutation result, with the full selection. */
     handleSelectionChanged(selection: Selection): void;
     private recompute;
@@ -811,12 +801,9 @@ 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.
+ * Isolate and frame one component, or return to the overview. Alongside
+ * `onChange` the container dispatches a bubbling `vd:focus-change` event, so a
+ * page can react without registering a callback.
  */
 declare class Focus {
     private readonly send;
@@ -1008,8 +995,8 @@ declare class Attribute {
  * 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$1>, 'annotations'> & {
-    readonly annotations?: boolean | AnnotationVisibility$1;
+type ViewerSettingsOverride = Omit<Partial<ViewerSettings>, 'annotations'> & {
+    readonly annotations?: boolean | AnnotationVisibility;
 };
 /**
  * Options shared by both address forms.
@@ -1034,17 +1021,9 @@ interface ClientOptionsBase {
     readonly viewerSettings?: ViewerSettingsOverride;
 }
 /**
- * How the client addresses what it shows, one of two forms:
- *
- * - `{ app }`: an app's public link key (the slug in its URL). The viewer
- *   resolves that app and renders it with its own configuration.
- * - `{ license, model }`: the classic pair, which resolves to the model's
- *   default app. Every existing integration keeps working unchanged.
- *
- * Supplying both is allowed so a migration is additive (add `app`, done):
- * `app` wins and a warning is logged that the pair was ignored. Supplying
- * neither is a compile error, which is the guarantee this union buys over a
- * bag of three optional fields.
+ * 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;
@@ -1060,68 +1039,7 @@ type ClientAddress = {
  */
 type ClientOptions = ClientOptionsBase & ClientAddress;
 
-/**
- * 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;
-}
-/**
- * Which app this viewer resolved (the apps spec's one-read inversion): the
- * `onAppResolved` callback payload. The protocol message minus its wire
- * discriminator; only the parent-safe submit settings ride along, never the
- * delivery recipient (removed in SQL on the public read).
- */
-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$1;
-}
-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}.
- */
+/** The AR flow behind the standard interface's AR button. */
 interface ArFlow {
     /** The AR button handler. */
     activate(): void;
@@ -1129,57 +1047,27 @@ interface ArFlow {
     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).
- */
+/** 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;
 }
-/**
- * Extensions a subclass (the studio client) layers onto the base composition without
- * re-implementing it: a custom incoming-message validator and extra message handlers.
- */
+/** 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 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.
-     */
+    /** The viewer host this client's iframe targets. Unset means the default viewer. */
     readonly serverHost?: string;
-    /**
-     * Extra query parameters for the viewer iframe URL. An extension seam like
-     * `serverHost`: a client type's fixed capability flags (the studio client's
-     * metadata-override boot mode), never a per-instance public option.
-     */
+    /** A client type's fixed capability flags, appended to the viewer iframe URL. */
     readonly iframeParams?: Readonly<Record<string, string>>;
-    /**
-     * The AR flow behind the standard interface's AR button. The public client
-     * composes its `ArActivation` here; the studio composes nothing (the editor
-     * has no AR use case), so the base wires no AR button at all.
-     */
+    /** Builds the AR flow behind the standard interface's AR button. */
     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.
-     */
+    /** Builds the tracker behind `onSyncChange`. */
     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}.
+ * The shared client composition root: wires the transport, facades and UI, and
+ * exposes the integrator-facing API.
  */
 declare class BaseClient {
     private readonly attributes;
@@ -1197,9 +1085,9 @@ declare class BaseClient {
     private readonly options;
     private readonly serverHost;
     private readonly iframeParams;
-    /** The composed AR flow, or undefined in builds without one (the studio). */
+    /** The composed AR flow, or undefined in a build that composes none. */
     private readonly arActivation;
-    /** The composed sync tracker, or undefined in builds without one (the studio). */
+    /** The composed sync tracker, or undefined in a build that composes none. */
     private readonly syncTracker;
     private iframe;
     private container;
@@ -1213,6 +1101,7 @@ declare class BaseClient {
     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. */
@@ -1237,11 +1126,8 @@ declare class BaseClient {
     private dispatchConfigurationSubmit;
     private handleConfig;
     /**
-     * The difference echo: the viewer already applied the app-config mode
-     * itself, so the client only speaks up when the merged mode (config plus
-     * integrator override) differs from what CONFIG announced, in either
-     * direction. Equal modes echo nothing, so a boot without overrides sends
-     * no toggle at all.
+     * 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. */
@@ -1257,11 +1143,9 @@ declare class BaseClient {
     onReady(callback: (client: this) => void): void;
     onMutationFailed(callback: (event: MutationFailedEvent) => void): void;
     /**
-     * Subscribe to the viewer's selectability snapshots (kiesbaarheid live):
-     * per attribute, which values the buyer can pick right now. Fires with the
-     * current snapshot immediately when one already arrived. A model without
-     * exclusions never sends one: everything stays selectable and this never
-     * fires.
+     * Subscribe to which values can be picked right now, per attribute. Fires
+     * immediately when a snapshot already arrived. A model with no exclusions
+     * never sends one, so this never fires and everything stays selectable.
      */
     onSelectableChange(callback: (snapshot: SelectableSnapshot) => void): void;
     /**
@@ -1273,11 +1157,8 @@ declare class BaseClient {
     /** The selectable values for one attribute right now, or null when unrestricted. */
     getSelectable(name: string): readonly string[] | null;
     /**
-     * Trigger the composed AR flow directly (ar-session-handoff task 035): a host
-     * page that hides the built-in corner button (`viewerSettings.ar = false`,
-     * 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).
+     * Start the AR flow directly, as the built-in AR button would. Does nothing
+     * when `viewerSettings.ar` is off or the build composes no AR flow.
      */
     activateAr(): void;
     on<T extends VirtualdisplayUiEventType>(type: T, callback: (event: VirtualdisplayUiEventMap[T]) => void): void;
@@ -1289,7 +1170,7 @@ declare class BaseClient {
     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;
+    get viewerSettings(): ViewerSettings;
     destroy(): void;
 }
 
@@ -1309,15 +1190,8 @@ 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.
+ * The Virtualdisplay client: point it at a container and an app or model, and it
+ * renders the viewer with the standard interface, the configurator and AR.
  */
 declare class VirtualdisplayClient extends BaseClient {
     private readonly syncStatusTracker;
@@ -1326,93 +1200,5 @@ declare class VirtualdisplayClient extends BaseClient {
     onSyncChange(callback: (connected: boolean) => void): void;
 }
 
-/** 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). */
-type AppType = 'viewer' | 'configurator';
-/** The public submit settings of a configurator-type app, as the form renders
- * them. Never the recipient: that section is removed in SQL on the public
- * read and cannot ride any message. Sparse like every config section: an
- * absent field means the renderer's default (the backend stores the section
- * as written and omits empty keys), so nothing here is guaranteed present. */
-interface AppSubmitSettings {
-    readonly fields?: string[];
-    readonly ctaLabel?: string;
-    readonly privacyUrl?: string;
-}
-/**
- * How a model's annotations present to the Shopper: never (hide), always
- * (show), or under the Shopper's own control via a viewer toggle, starting
- * visible (toggle-shown) or hidden (toggle-hidden). Resolved per app; the
- * backend's `Resolve` owns the `hide` default.
- */
-type AnnotationVisibility = 'hide' | 'show' | 'toggle-shown' | 'toggle-hidden';
-/**
- * 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;
-    /**
-     * The resolved per-app annotation mode. Present only when the model has
-     * annotations, so a control can never render with nothing to govern;
-     * absent means there is nothing to show or toggle.
-     */
-    readonly annotations?: AnnotationVisibility;
-    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 { AppSubmitSettings, AppType, Availability, ClientOptions, ErrorCode, FocusState, MutationFailedEvent, PhotoData, PricingDocument, PricingRule, ResolvedAppInfo, ResolvedConfiguration, SubmitOptions, SubmittedConfiguration, VdEvent, ViewerSettings, VirtualdisplaySelectEvent, VirtualdisplaySelectedEvent, VirtualdisplayUiEventMap, VirtualdisplayUiEventType };