@virtualdisplay.io/client 4.0.0-alpha.26 → 4.0.0-alpha.28

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 4.0.0-alpha.28
+
+### Minor Changes
+
+Add a marker toggle button to the viewer action bar for apps set to the `toggle-shown` or `toggle-hidden` annotation mode: the visitor shows or hides the annotation markers themselves, with the starting state you configured. The button only appears when the model has annotations and a toggle mode is active.
+
+## 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

package/dist/index.d.ts

@@ -52,6 +52,29 @@ interface AppResolvedMessage {
     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;
@@ -75,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;
     /**
@@ -117,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.
@@ -129,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';
@@ -194,6 +233,12 @@ interface AttributeDefinition {
 }
 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. */
@@ -218,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;
@@ -284,7 +348,21 @@ 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;
+    /**
+     * 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: {
@@ -306,6 +384,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;
 }
@@ -316,6 +396,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[];
@@ -373,9 +455,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 | AppResolvedMessage;
+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>;
 
 /**
@@ -490,14 +579,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;
 }
@@ -511,7 +592,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;
 }
 
@@ -743,10 +828,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;
     /**
@@ -920,6 +1009,15 @@ declare class Attribute {
     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.
+ */
+type ViewerSettingsOverride = Omit<Partial<ViewerSettings$1>, 'annotations'> & {
+    readonly annotations?: boolean | AnnotationVisibility$1;
+};
 /**
  * Options shared by both address forms.
  */
@@ -940,7 +1038,7 @@ interface ClientOptionsBase {
      * 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:
@@ -1122,6 +1220,14 @@ declare class BaseClient {
     constructor(options: ClientOptions, extensions?: BaseClientExtensions);
     /** The configurator UI, every callback bridging it to the facade that owns the action. */
     private createStandardInterface;
+    /**
+     * The visible toggle composes its message here, on the internal transport,
+     * because it is the one sender allowed to stamp `origin: 'control'`: the
+     * viewer only counts control-originated flips as Shopper use. The public
+     * `client.annotations` facade stays origin-less on purpose. One send per
+     * member instance once composition lands; today the host is the only one.
+     */
+    private sendControlAnnotationToggle;
     /** Wire the inbound viewer protocol to the facades. */
     private wireIncomingMessages;
     /** Store the resolved app and notify every registered `onAppResolved` callback. */
@@ -1145,6 +1251,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;
@@ -1241,6 +1355,13 @@ interface AppSubmitSettings {
     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.
@@ -1250,7 +1371,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';