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

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 4.0.0-alpha.27
+
+### Minor Changes
+
+Add the per-app annotation visibility modes to the `viewerSettings.annotations` override: `'hide'`, `'show'`, `'toggle-shown'` and `'toggle-hidden'`, besides the existing booleans (`true` maps to `'show'`, `false` to `'hide'`). Markers now follow the mode configured on the app, and an override only speaks up when it differs from that mode.
+
+## 4.0.0-alpha.26
+
+### Minor Changes
+
+Add `app` option to `ClientOptions` as an alternative to the `license` and `model` pair, mounting one specific app by its link key. The pair keeps working unchanged; when both are supplied, `app` wins and a warning is logged that the pair was ignored.
+
+Add `AppType` with the known app types. `ResolvedAppInfo.appType` is typed as a plain string so an app type newer than your bundle still reaches `onAppResolved` for explicit handling.
+
+Add a measurement slider for size attributes. A model that offers a size (width, depth, diameter) now renders it as a slider with the formatted value and unit beside it, and the model follows the drag live while only the released value counts as the chosen size.
+
+Add `slug` to the `onAppResolved` callback payload: the resolved app's public slug, so a host page can address the app it embeds without knowing the slug in advance.
+
+Add `onAppResolved(callback)`. The viewer reports which app it resolved (`appType`, `name`, and public submit settings as `ResolvedAppInfo`), and the callback fires immediately when the report already arrived.
+
 ## 4.0.0-alpha.25
 
 ### Minor Changes

package/README.md

@@ -55,6 +55,26 @@ The server defines which attributes and values are available for each model.
 The client receives this configuration automatically via postMessage. No
 manual mapping required.
 
+### Mounting a specific app
+
+A model can have several apps (a plain viewer, a configurator), each with its
+own link and its own configuration. Pass the app's link key as `app` to mount
+that exact app:
+
+```typescript
+import { VirtualdisplayClient } from '@virtualdisplay.io/client';
+
+const client = new VirtualdisplayClient({
+  parent: '#product-container',
+  app: 'sofa-deluxe-k3f9dm',
+});
+```
+
+`license` + `model` keeps working unchanged and shows the model's default
+viewer. If both forms are supplied, `app` wins and a warning is logged that the
+pair was ignored, so adding `app` to an existing integration is additive. One
+of the two forms is required; supplying neither is a compile error.
+
 ## How it works
 
 The 3D server hosts the viewer in an iframe, keeping WebGL complexity isolated
@@ -229,7 +249,7 @@ exposes an API to toggle their visibility.
 
 ```typescript
 client.annotations.setEnabled(false); // Hide all markers
-client.annotations.setEnabled(true);  // Show them again
+client.annotations.setEnabled(true); // Show them again
 ```
 
 Visibility can also be controlled via `viewerSettings.annotations` (see below).
@@ -243,15 +263,15 @@ settings configured in the Virtualdisplay portal.
 
 ### Available settings
 
-| Field               | Type      | Effect when `false`                                                                            |
-| ------------------- | --------- | ---------------------------------------------------------------------------------------------- |
-| `ar`                | `boolean` | Hides the AR button                                                                            |
-| `fullscreen`        | `boolean` | Hides the fullscreen button                                                                    |
-| `screenshot`        | `boolean` | Hides the screenshot button                                                                    |
-| `cameraControls`    | `boolean` | Hides the camera control buttons                                                               |
-| `annotations`       | `boolean` | Hides all annotation markers                                                                   |
-| `language`          | `string`  | Sets the viewer UI language (BCP 47, e.g. `'nl'`, `'en'`, `'de'`)                              |
-| `configuratorLayout`| `string`  | Where the attribute controls sit, or whether they show: `'inframe-bottom-left'` (default), `'sidebar-right'` (a docked, scrollable right-hand panel), or `'hidden'` (no built-in selector, `client.select()` and `client.onChange()` keep working). |
+| Field                | Type      | Effect when `false`                                                                                                                                                                                                                                 |
+| -------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ar`                 | `boolean` | Hides the AR button                                                                                                                                                                                                                                 |
+| `fullscreen`         | `boolean` | Hides the fullscreen button                                                                                                                                                                                                                         |
+| `screenshot`         | `boolean` | Hides the screenshot button                                                                                                                                                                                                                         |
+| `cameraControls`     | `boolean` | Hides the camera control buttons                                                                                                                                                                                                                    |
+| `annotations`        | `boolean` | Hides all annotation markers                                                                                                                                                                                                                        |
+| `language`           | `string`  | Sets the viewer UI language (BCP 47, e.g. `'nl'`, `'en'`, `'de'`)                                                                                                                                                                                   |
+| `configuratorLayout` | `string`  | Where the attribute controls sit, or whether they show: `'inframe-bottom-left'` (default), `'sidebar-right'` (a docked, scrollable right-hand panel), or `'hidden'` (no built-in selector, `client.select()` and `client.onChange()` keep working). |
 
 ### Overriding settings
 
@@ -290,7 +310,10 @@ automatically.
 ```typescript
 client.onReady(() => {
   const values = client.getValues('Color');
-  console.log('Available colours:', values.map(v => v.value));
+  console.log(
+    'Available colours:',
+    values.map((v) => v.value)
+  );
 });
 ```
 
@@ -306,15 +329,26 @@ client.destroy();
 import type { ViewerSettings } from '@virtualdisplay.io/client';
 
 interface ClientOptions {
-  parent: string | HTMLElement;             // Where to embed the 3D viewer
-  license: string;                          // License key from your Virtualdisplay account
-  model: string;                            // Which 3D model to load
-  debug?: boolean;                          // Shows console logs for troubleshooting
-  language?: string;                        // Viewer language: 'nl', 'en', or 'de'
+  parent: string | HTMLElement; // Where to embed the 3D viewer
+  app?: string; // An app's link key: the alternative to license + model (see Mounting a specific app)
+  license: string; // License key from your Virtualdisplay account; with model, the classic address form
+  model: string; // Which 3D model to load
+  debug?: boolean; // Shows console logs for troubleshooting
+  language?: string; // Viewer language: 'nl', 'en', or 'de'
   viewerSettings?: Partial<ViewerSettings>; // Override fields from model metadata (see Standard interface)
 }
 ```
 
+One of the two address forms is required: `app`, or `license` + `model`. The
+real type is a union that enforces this at compile time; the block above is the
+flattened reference.
+
+```typescript
+type ClientAddress =
+  | { app: string } // an app's link key
+  | { license: string; model: string }; // the classic address form
+```
+
 ## Error codes
 
 The client throws `VirtualdisplayError` for known error conditions:

package/dist/index.d.ts

@@ -22,7 +22,59 @@ declare const MESSAGE_TYPES: {
     readonly QR_SHOWN: "qr_shown";
     readonly SYNC: "sync";
     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 {
+    readonly fields?: string[];
+    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$1;
+}
+/** 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.
+ *
+ * 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;
+    /** Whose meshes and variants these are. */
+    readonly instance: string;
+    readonly nodes: ModelNodeDto[];
+    readonly isInitial: boolean;
+}
 interface MutationDto {
     readonly name: string;
     readonly value: string;
@@ -46,6 +98,8 @@ interface SyncStateSnapshot {
 }
 interface MutationMessage {
     readonly type: typeof MESSAGE_TYPES.MUTATION;
+    /** Which instance's attributes these mutations change. */
+    readonly instance: string;
     readonly mutations: MutationDto[];
     readonly isInitial: boolean;
     /**
@@ -61,11 +115,19 @@ interface MutationMessage {
      * 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`.
+     * subscriber. None of these fields are read by `MutationPipeline`.
      */
     readonly origin?: string;
     readonly seq?: number;
     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.
+     */
+    readonly transient?: boolean;
 }
 /**
  * Sync channel status (server → client, ar-session-handoff, sync-channel.md):
@@ -80,9 +142,18 @@ interface SyncMessage {
 }
 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 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$1 = 'hide' | 'show' | 'toggle-shown' | 'toggle-hidden';
 /**
  * Viewer settings from model metadata (server → client via MAPPING).
  * Customer-configured in the portal.
@@ -92,7 +163,12 @@ interface ViewerSettings$1 {
     readonly fullscreen?: boolean;
     readonly screenshot?: boolean;
     readonly cameraControls?: boolean;
-    readonly annotations?: 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$1;
     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';
@@ -136,19 +212,46 @@ interface SnapshotResultMessage {
     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;
     readonly selectable: string[];
+    /**
+     * The control should not render at all: a dimension whose component is
+     * currently hidden by its show-when conditions (parametric dimensions).
+     * Different from an empty `selectable`, which greys values out but keeps
+     * the control visible. Absent means visible.
+     */
+    readonly hidden?: boolean;
 }
 /**
  * Selectability snapshot (server → client): sent after the mapping and after
@@ -160,11 +263,30 @@ interface SelectableAttribute {
  */
 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 (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.
  */
 interface LoadingIndicatorMessage {
     readonly type: typeof MESSAGE_TYPES.LOADING_INDICATOR;
@@ -226,6 +348,13 @@ interface SessionMessage {
  */
 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;
 }
 /** Focus actions (client → server). */
@@ -238,8 +367,8 @@ 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];
+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
@@ -248,6 +377,8 @@ type FocusStateValue = typeof FOCUS_STATES[keyof typeof FOCUS_STATES];
  */
 interface FocusMessage {
     readonly type: typeof MESSAGE_TYPES.FOCUS;
+    /** Which instance the component name resolves inside. */
+    readonly instance: string;
     readonly action: FocusAction;
     readonly component?: string;
 }
@@ -258,6 +389,8 @@ interface FocusMessage {
  */
 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[];
@@ -274,7 +407,7 @@ 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$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`).
@@ -315,9 +448,16 @@ interface PricingDocument$1 {
  */
 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$1;
 }
-type Message = HandshakeMessage | SessionMessage | MutationMessage | MutationResultMessage | CameraCommandMessage | CameraPositionMessage | SnapshotRequestMessage | SnapshotResultMessage | MappingMessage | LoadingIndicatorMessage | ArActivateMessage | FullscreenMessage | ConfigMessage | AnnotationToggleMessage | FocusMessage | FocusStateMessage | PricingMessage | QrShownMessage | SyncMessage | SelectableMessage;
+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>;
 
 /**
@@ -432,14 +572,6 @@ declare class IframeMessenger {
      * 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;
 }
@@ -453,7 +585,11 @@ type SendFn$1 = (message: Message) => void;
  */
 declare class Annotations {
     private readonly send;
-    constructor(send: SendFn$1);
+    /** Whose pins this facade toggles: a pin lives in one model's local space. */
+    private readonly instance;
+    constructor(send: SendFn$1, 
+    /** Whose pins this facade toggles: a pin lives in one model's local space. */
+    instance: string);
     setEnabled(enabled: boolean): void;
 }
 
@@ -685,10 +821,14 @@ type DispatchFn = (state: FocusChange) => void;
 declare class Focus {
     private readonly send;
     private readonly dispatch;
+    /** Which instance this facade addresses; every message it sends carries it. */
+    private readonly instance;
     private focused;
     private attributes;
     private readonly changeCallbacks;
-    constructor(send: MessageCallback, dispatch: DispatchFn);
+    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;
     /**
@@ -863,12 +1003,19 @@ declare class Attribute {
 }
 
 /**
- * Configuration options for VirtualdisplayClient
+ * 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$1>, 'annotations'> & {
+    readonly annotations?: boolean | AnnotationVisibility$1;
+};
+/**
+ * Options shared by both address forms.
  */
-interface ClientOptions {
+interface ClientOptionsBase {
     readonly parent: string | HTMLElement;
-    readonly model: string;
-    readonly license: string;
     readonly debug?: boolean | undefined;
     readonly language?: string | undefined;
     /** W3C traceparent string to propagate to the viewer iframe for end-to-end tracing. */
@@ -884,8 +1031,34 @@ interface ClientOptions {
      * 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>;
+    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.
+ */
+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 Virtualdisplay client's DOM event names, in one registry.
@@ -913,6 +1086,20 @@ 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;
@@ -1020,9 +1207,16 @@ declare class BaseClient {
     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;
     /** 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. */
@@ -1042,6 +1236,14 @@ declare class BaseClient {
     /** Dispatch a bubbling `vd:configuration-submit` event when the CTA is used. */
     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.
+     */
+    private echoAnnotationsDifference;
     /** Tell the viewer the user entered fullscreen, so it records the engagement. */
     private trackFullscreen;
     private initializeLogging;
@@ -1062,6 +1264,12 @@ declare class BaseClient {
      * fires.
      */
     onSelectableChange(callback: (snapshot: SelectableSnapshot) => void): void;
+    /**
+     * Subscribe to which app this viewer resolved (type, name, public submit
+     * settings). Reported once by the viewer after its resolve; fires immediately
+     * when the report already arrived, so registration order does not matter.
+     */
+    onAppResolved(callback: (app: ResolvedAppInfo) => void): void;
     /** The selectable values for one attribute right now, or null when unrestricted. */
     getSelectable(name: string): readonly string[] | null;
     /**
@@ -1086,12 +1294,17 @@ declare class BaseClient {
 }
 
 type Attrs = Record<string, unknown> | unknown;
-declare let logger: {
+/**
+ * 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;
-};
+}
+declare let logger: ClientLogger;
 declare function enableDebugMode(): void;
 declare function isDebugMode(): boolean;
 
@@ -1113,6 +1326,27 @@ 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.
@@ -1122,7 +1356,12 @@ interface ViewerSettings {
     readonly fullscreen?: boolean;
     readonly screenshot?: boolean;
     readonly cameraControls?: boolean;
-    readonly annotations?: 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';
@@ -1139,7 +1378,7 @@ declare const AVAILABILITY: {
     /** Behaves exactly like an unpriced combination: no price, no button. */
     readonly HIDDEN: "hidden";
 };
-type Availability = typeof AVAILABILITY[keyof typeof AVAILABILITY];
+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`).
@@ -1176,4 +1415,4 @@ interface PricingDocument {
 }
 
 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 };
+export type { AppSubmitSettings, AppType, Availability, ClientOptions, ErrorCode, FocusState, MutationFailedEvent, PhotoData, PricingDocument, PricingRule, ResolvedAppInfo, ResolvedConfiguration, SubmitOptions, SubmittedConfiguration, VdEvent, ViewerSettings, VirtualdisplaySelectEvent, VirtualdisplaySelectedEvent, VirtualdisplayUiEventMap, VirtualdisplayUiEventType };