@virtualdisplay.io/client 4.0.0-alpha.35 → 4.0.0-alpha.37

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 4.0.0-alpha.37
+
+### Minor Changes
+
+Add the `personalisation` app type. `onAppResolved` reports `personalisation` for a viewer app with a backdrop photo behind the model.
+
+## 4.0.0-alpha.36
+
+### Minor Changes
+
+Add `client.personalisation` to show a Shopper's own picture on a print zone of the model, clear it again, and move and scale it with `place()`; the picture stays in the browser, and `zones` reports each zone's real size. A failed `setImage` or `clear` call rejects with a `VirtualdisplayError` coded `PERSONALISATION_FAILED`.
+
 ## 4.0.0-alpha.35
 
 ### Minor Changes

package/README.md

@@ -264,6 +264,50 @@ In an app that shows several models, this toggles the first model's markers.
 `viewerSettings.annotations` (see below) and the marker button in the standard
 interface govern every model's.
 
+## Personalisation
+
+A print zone is a material the 3D artist named in the model, such as `logo`.
+`setImage` shows a picture the Shopper chose on it, fitted without stretching;
+`clear` brings back the zone's own texture. The picture stays in the browser
+and is never uploaded.
+
+```typescript
+input.addEventListener('change', async () => {
+  const file = input.files?.[0];
+  if (file === undefined) return;
+  try {
+    await client.personalisation.setImage('logo', file);
+  } catch (error) {
+    console.error(error.message); // PERSONALISATION_FAILED
+  }
+});
+
+await client.personalisation.clear('logo');
+```
+
+Each call resolves once the model shows the result. A call rejects when the
+zone is not on the model, when the file is not a picture, and when a later call
+on the same zone replaces it before it shows.
+
+`zones` lists every material of the model with its own texture, each a zone a
+picture can go on, with its real size in millimetres; pick yours by name.
+`onZones` calls back each time the viewer reports them. `place` moves and scales
+the picture on a zone: `x` and `y` are the picture's centre and `scale` its width,
+as fractions of the zone measured from its top left. Calls for one zone within
+one animation frame collapse into the last, so call it on every pointer move.
+A zone that shows no picture yet drops the placement, so call `place` once
+`setImage` has resolved.
+`editing: true` draws the zone's outline while the Shopper edits. The `Placement`
+and `ZoneSize` types are exported.
+
+```typescript
+client.personalisation.onZones((zones) => {
+  // [{ name: 'logo', aspect: 2.95, widthMm: 73.2, heightMm: 24.8 }]
+});
+
+client.personalisation.place('logo', { x: 0.5, y: 0.4, scale: 0.6, editing: true });
+```
+
 ## Standard interface
 
 The client renders a complete viewer UI automatically: loading indicator,
@@ -363,14 +407,15 @@ type ClientAddress =
 
 The client throws `VirtualdisplayError` for known error conditions:
 
-| Code                  | Meaning                                          |
-| --------------------- | ------------------------------------------------ |
-| `NO_MAPPING`          | Attribute data not yet available from the server |
-| `ATTRIBUTE_NOT_FOUND` | Requested attribute doesn't exist in the mapping |
-| `VALUE_NOT_FOUND`     | Requested value doesn't exist for attribute      |
-| `PARENT_NOT_FOUND`    | Parent element for iframe not found              |
-| `INVALID_PARAMETER`   | Invalid parameter (e.g. snapshot filename)       |
-| `SNAPSHOT_FAILED`     | Server could not capture the snapshot            |
+| Code                     | Meaning                                          |
+| ------------------------ | ------------------------------------------------ |
+| `NO_MAPPING`             | Attribute data not yet available from the server |
+| `ATTRIBUTE_NOT_FOUND`    | Requested attribute doesn't exist in the mapping |
+| `VALUE_NOT_FOUND`        | Requested value doesn't exist for attribute      |
+| `PARENT_NOT_FOUND`       | Parent element for iframe not found              |
+| `INVALID_PARAMETER`      | Invalid parameter (e.g. snapshot filename)       |
+| `SNAPSHOT_FAILED`        | Server could not capture the snapshot            |
+| `PERSONALISATION_FAILED` | The picture could not be shown on the print zone |
 
 ## Troubleshooting
 

package/dist/{browser-xDScqAR5.js → browser-DSuT5Y7h.js}

@@ -1,5 +1,5 @@
 import { t as e } from "./rolldown-runtime-CYdcPHCu.js";
-// ../../../../../../../../../pnpm-stores/dec039ed73fa4586176507e1829e0d90ef7d17bbd32cd1c1b43a9aa9c94aa7d1/v11/links/@/qrcode/1.5.4/38431ab3ce46851b9c5211f56296031bcdd3ab8a89e17d0d2a55d25922dcc7fe/node_modules/qrcode/lib/can-promise.js
+// ../../../../../../../../../pnpm-stores/7817d7635beec3e681fa52ee7cd8f0ca6d20e45c60fe0344fc76ab1877d532c3/v11/links/@/qrcode/1.5.4/38431ab3ce46851b9c5211f56296031bcdd3ab8a89e17d0d2a55d25922dcc7fe/node_modules/qrcode/lib/can-promise.js
 var t = /* @__PURE__ */ e(((e, t) => {
 	t.exports = function() {
 		return typeof Promise == "function" && Promise.prototype && Promise.prototype.then;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /** 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';
+type AppType = 'viewer' | 'configurator' | 'personalisation';
 /** What a configurator app's submit form renders. Any field may be absent; an
  * absent field means the form's own default. */
 interface AppSubmitSettings {
@@ -61,6 +61,15 @@ interface SelectableAttribute {
      */
     readonly hidden?: boolean;
 }
+/** One print zone the viewer can show a picture on, measured on its surface. */
+interface ZoneSize {
+    /** The zone's material name, as the 3D artist named it in the GLB. */
+    readonly name: string;
+    /** Width over height. */
+    readonly aspect: number;
+    readonly widthMm: number;
+    readonly heightMm: number;
+}
 /**
  * What the configurator does with a matched configuration.
  */
@@ -324,6 +333,56 @@ declare class Focus {
     onChange(callback: (state: FocusState | null) => void): void;
 }
 
+/** Where the picture sits on a print zone. `x` and `y` are its centre, measured from the zone's top left. */
+interface Placement {
+    /** The centre, as a fraction of the zone width, 0 to 1. */
+    readonly x: number;
+    /** The centre, as a fraction of the zone height, 0 to 1. */
+    readonly y: number;
+    /** The picture width as a fraction of the zone width, where 1 is the full width. */
+    readonly scale: number;
+    /** True while the Shopper edits, which draws the zone outline. */
+    readonly editing: boolean;
+}
+/**
+ * Shows the Shopper's own picture on a print zone of the model, or clears it.
+ * The picture stays in the browser: it is sent to the viewer and never uploaded.
+ */
+declare class Personalisation {
+    private readonly send;
+    private readonly instance;
+    private readonly pending;
+    private readonly zoneListeners;
+    private zoneReport;
+    private sequence;
+    private readonly pendingPlacements;
+    private frame;
+    /**
+     * Show a picture on a print zone. Resolves once the picture shows on the model.
+     * Rejects with the viewer's message when the picture cannot be shown, and when
+     * a later call on the same zone replaces it before it shows.
+     */
+    setImage(zone: string, image: Blob): Promise<void>;
+    /**
+     * Restore the zone's own picture. Resolves once the model shows it again.
+     * Rejects with the viewer's message when the zone is not on the model.
+     */
+    clear(zone: string): Promise<void>;
+    /** The print zones of the model, from the last report. Empty until the model loads. */
+    get zones(): readonly ZoneSize[];
+    /** Call back with the print zones each time the viewer reports them. */
+    onZones(callback: (zones: readonly ZoneSize[]) => void): void;
+    /**
+     * Move the picture on a zone. Calls for one zone within one animation frame collapse into
+     * the last, so a drag sends at most one message per zone per frame. A zone that shows no
+     * picture yet drops the placement, so call it once `setImage` has resolved.
+     */
+    place(zone: string, placement: Placement): void;
+    private sendPlacements;
+    private request;
+    private expire;
+}
+
 /**
  * Error codes for Virtualdisplay client errors
  */
@@ -334,6 +393,7 @@ declare const ERROR_CODES: {
     readonly PARENT_NOT_FOUND: "PARENT_NOT_FOUND";
     readonly INVALID_PARAMETER: "INVALID_PARAMETER";
     readonly SNAPSHOT_FAILED: "SNAPSHOT_FAILED";
+    readonly PERSONALISATION_FAILED: "PERSONALISATION_FAILED";
 };
 type ErrorCode = typeof ERROR_CODES[keyof typeof ERROR_CODES];
 /**
@@ -520,6 +580,7 @@ declare class BaseClient {
     private readonly cameraApi;
     private readonly cameraPositionApi;
     private readonly focusApi;
+    private readonly personalisationApi;
     private readonly configurationApi;
     private readonly snapshotApi;
     private readonly annotationsApi;
@@ -584,6 +645,7 @@ declare class BaseClient {
     get annotations(): Annotations;
     get camera(): Camera;
     get focus(): Focus;
+    get personalisation(): Personalisation;
     get configuration(): Configuration;
     get cameraPosition(): CameraPosition;
     get snapshot(): Snapshot;
@@ -668,5 +730,5 @@ declare class VirtualdisplayClient extends BaseClient {
     onSyncChange(callback: (connected: boolean) => void): void;
 }
 
-export { AVAILABILITY, Annotations, Attribute, AttributeValue, Camera, CameraPosition, Configuration, ERROR_CODES, Focus, Photo, Snapshot, VD_EVENTS, VirtualdisplayClient, VirtualdisplayError, enableDebugMode, isDebugMode, logger };
-export type { AnnotationVisibility, AppSubmitSettings, AppType, Availability, CameraLimits, CameraPositionState, ClientAddress, ClientLogger, ClientOptions, ClientOptionsBase, ErrorCode, FocusState, MutationFailedEvent, PhotoData, PricingDocument, PricingRule, ResolvedAppInfo, ResolvedConfiguration, SelectableAttribute, SelectableSnapshot, SubmitOptions, SubmittedConfiguration, VdEvent, ViewerSettings, ViewerSettingsOverride, VirtualdisplaySelectEvent, VirtualdisplaySelectedEvent, VirtualdisplayUiEventMap, VirtualdisplayUiEventType };
+export { AVAILABILITY, Annotations, Attribute, AttributeValue, Camera, CameraPosition, Configuration, ERROR_CODES, Focus, Personalisation, Photo, Snapshot, VD_EVENTS, VirtualdisplayClient, VirtualdisplayError, enableDebugMode, isDebugMode, logger };
+export type { AnnotationVisibility, AppSubmitSettings, AppType, Availability, CameraLimits, CameraPositionState, ClientAddress, ClientLogger, ClientOptions, ClientOptionsBase, ErrorCode, FocusState, MutationFailedEvent, PhotoData, Placement, PricingDocument, PricingRule, ResolvedAppInfo, ResolvedConfiguration, SelectableAttribute, SelectableSnapshot, SubmitOptions, SubmittedConfiguration, VdEvent, ViewerSettings, ViewerSettingsOverride, VirtualdisplaySelectEvent, VirtualdisplaySelectedEvent, VirtualdisplayUiEventMap, VirtualdisplayUiEventType, ZoneSize };