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

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 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
+
+Add `onSelectableChange(callback)` and `getSelectable(name)` to follow which
+attribute values the buyer can still pick under the current selection. The
+standard sidebar greys out values the selection rules out. Models without
+exclusions behave exactly as before.
+
 ## 4.0.0-alpha.24
 
 ### Patch 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

@@ -21,7 +21,37 @@ declare const MESSAGE_TYPES: {
     readonly PRICING: "pricing";
     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;
+}
 interface MutationDto {
     readonly name: string;
     readonly value: string;
@@ -60,11 +90,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):
@@ -135,15 +173,53 @@ 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;
     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
+ * 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).
+ */
+interface SelectableMessage {
+    readonly type: typeof MESSAGE_TYPES.SELECTABLE;
+    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.
@@ -220,8 +296,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
@@ -256,7 +332,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`).
@@ -299,7 +375,7 @@ interface PricingMessage {
     readonly type: typeof MESSAGE_TYPES.PRICING;
     readonly pricing: PricingDocument$1;
 }
-type Message = HandshakeMessage | SessionMessage | MutationMessage | MutationResultMessage | CameraCommandMessage | CameraPositionMessage | SnapshotRequestMessage | SnapshotResultMessage | MappingMessage | LoadingIndicatorMessage | ArActivateMessage | FullscreenMessage | ConfigMessage | AnnotationToggleMessage | FocusMessage | FocusStateMessage | PricingMessage | QrShownMessage | SyncMessage;
+type Message = HandshakeMessage | SessionMessage | MutationMessage | MutationResultMessage | CameraCommandMessage | CameraPositionMessage | SnapshotRequestMessage | SnapshotResultMessage | MappingMessage | LoadingIndicatorMessage | ArActivateMessage | FullscreenMessage | ConfigMessage | AnnotationToggleMessage | FocusMessage | FocusStateMessage | PricingMessage | QrShownMessage | SyncMessage | SelectableMessage | AppResolvedMessage;
 type MessageCallback = (message: Message) => void | Promise<void>;
 
 /**
@@ -439,6 +515,8 @@ declare class Annotations {
     setEnabled(enabled: boolean): void;
 }
 
+type SelectableSnapshot = readonly SelectableAttribute[];
+
 /**
  * Camera control API for positioning and zoom
  * Uses chaining pattern for building commands
@@ -843,12 +921,10 @@ declare class Attribute {
 }
 
 /**
- * Configuration options for VirtualdisplayClient
+ * 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. */
@@ -866,6 +942,32 @@ interface ClientOptions {
      */
     readonly viewerSettings?: Partial<ViewerSettings$1>;
 }
+/**
+ * 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.
@@ -893,6 +995,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;
@@ -976,6 +1092,7 @@ interface BaseClientExtensions {
  */
 declare class BaseClient {
     private readonly attributes;
+    private readonly selectableState;
     private readonly readyStateTracker;
     private readonly messenger;
     private readonly cameraApi;
@@ -999,9 +1116,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. */
@@ -1033,6 +1157,22 @@ declare class BaseClient {
     get isReady(): boolean;
     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.
+     */
+    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;
     /**
      * Trigger the composed AR flow directly (ar-session-handoff task 035): a host
      * page that hides the built-in corner button (`viewerSettings.ar = false`,
@@ -1055,12 +1195,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;
 
@@ -1082,6 +1227,20 @@ 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;
+}
 /**
  * Viewer settings from model metadata (server → client via MAPPING).
  * Customer-configured in the portal.
@@ -1108,7 +1267,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`).
@@ -1145,4 +1304,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 };