@snowcone-app/sdk 0.20.3 → 0.24.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,29 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.24.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#2337](https://github.com/snowcone-app/snowcone-monorepo/pull/2337) [`4b68ab9`](https://github.com/snowcone-app/snowcone-monorepo/commit/4b68ab971b99e0dfa4e6f096e50bb0e5ceb2ec70) Thanks [@kevinsproles](https://github.com/kevinsproles)! - ADR-0099 slice 4 (client): a realtime session on a BUNDLE record. SDK: `RenderProduct` / `WebSocketConfig` gain `picks` (role → member product) and `variants` (role → gvid), forwarded verbatim on the config message; a pick or per-role variant change is a full config reset (not a mockupIds-only update). `CatalogProduct` gains the `bundle` block, `placements[].role` / `memberProductId`, `requiredPlacements[].role` and `mockups[].picks`. Canvas: `bundleToRenderConfig()` — the bundle counterpart of `productToRenderConfig()` (role-scoped placement keys, per-role variants with defaults, picks per slot, scene selection by pick set, `variantToken`), `isBundleProduct`, `splitRoleKey`, `bundleVariantToken`; `Editor.Root` sends a new config on the live session when `product.picks` / `product.variants` change. Typed refusals: `E_BUNDLE_CONFIG_REQUIRED` (single-product adapter given a bundle), `E_NOT_A_BUNDLE`, `E_BUNDLE_ROLE_REQUIRED`, `E_BUNDLE_ROLE_NOT_FOUND`, `E_BUNDLE_PICK_NOT_FOUND`, `E_BUNDLE_VARIANT_NOT_FOUND`; embed issues `bundle-role-required` / `bundle-variant-required`. Single-product behaviour is byte-for-byte unchanged.
8
+
9
+ ## 0.23.0
10
+
11
+ ### Minor Changes
12
+
13
+ - [#2249](https://github.com/snowcone-app/snowcone-monorepo/pull/2249) [`19f7ee5`](https://github.com/snowcone-app/snowcone-monorepo/commit/19f7ee583638ccedd8fd5f309ad3e5ba6a06c0f9) Thanks [@kevinsproles](https://github.com/kevinsproles)! - A mockup whose scene failed render parity is refused by the server (`E_MOCKUP_NOT_BLESSED`) instead of silently rendering on the slow path. `RealtimeRenderError` gains `mockupId` for per-mockup errors; `RealtimeProvider` exposes `unavailableMockups` (mockupId → error) and `HeroProductImage` shows that mockup as unavailable (`data-mockup-unavailable`) while the others keep streaming.
14
+
15
+ ## 0.22.0
16
+
17
+ ### Minor Changes
18
+
19
+ - [#2240](https://github.com/snowcone-app/snowcone-monorepo/pull/2240) [`61c4826`](https://github.com/snowcone-app/snowcone-monorepo/commit/61c48267d77b93628ef525df5a6aee66421d67f7) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Realtime send policy: pipeline depth two. `CanvasExportService` now keeps up to two edits in flight (`maxInFlight`, default 2) before holding the latest state — the box's window is ~30 ms of a ~96 ms edit→frame, so one in flight left it idle ~70% of every drag cycle. `RealtimeProvider` settles once per landed send (every mockup of a `requestVersion`) instead of on the first frame after any send, using the SDK's new `getLastSentVersion()` on the realtime service and hook.
20
+
21
+ ## 0.21.0
22
+
23
+ ### Minor Changes
24
+
25
+ - [#2223](https://github.com/snowcone-app/snowcone-monorepo/pull/2223) [`aaa73cc`](https://github.com/snowcone-app/snowcone-monorepo/commit/aaa73ccb4b2d4c7c107b66f18be29f67032422b8) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Realtime frames now carry their own timing. Every `MockupResult` gets `rtTiming` (the render node's per-frame Server-Timing envelope: receive → guard → canvas raster → coalesce wait → composite → store → deliver, with byte sizes and the box id), `clientRoundTripMs` (the canvas_state send this frame answers → its arrival, as the client saw it) and `imageDelivery` ('ws' | 'url'). `onConnected` receives `{ box }` and `getState().box` names the render node that answered the handshake.
26
+
3
27
  ## 0.20.3
4
28
 
5
29
  ### Patch Changes
@@ -19,6 +19,12 @@ function newRenderCorrelation() {
19
19
  const spanId = randHex(8);
20
20
  return { requestId: traceId, traceparent: `00-${traceId}-${spanId}-01` };
21
21
  }
22
+ function sameRoleMap(a, b) {
23
+ const ka = Object.keys(a ?? {}).sort();
24
+ const kb = Object.keys(b ?? {}).sort();
25
+ if (ka.length !== kb.length) return false;
26
+ return ka.every((k, i) => k === kb[i] && a[k] === b[k]);
27
+ }
22
28
  var RealtimeMockupService = class {
23
29
  constructor(wsUrl = REALTIME_WS_URL) {
24
30
  this.wsUrl = wsUrl;
@@ -27,6 +33,9 @@ var RealtimeMockupService = class {
27
33
  config = null;
28
34
  configSent = false;
29
35
  sessionId = null;
36
+ // Render node that answered the handshake (`connected.box`), for labs and
37
+ // support: a realtime session has no response headers to read it from.
38
+ box = null;
30
39
  isConfigured = false;
31
40
  mockupResults = [];
32
41
  status = "Disconnected";
@@ -93,6 +102,7 @@ var RealtimeMockupService = class {
93
102
  return {
94
103
  isConnected: this.ws?.readyState === WebSocket.OPEN,
95
104
  sessionId: this.sessionId,
105
+ box: this.box,
96
106
  isConfigured: this.isConfigured,
97
107
  mockupResults: [...this.mockupResults],
98
108
  status: this.status,
@@ -158,6 +168,7 @@ var RealtimeMockupService = class {
158
168
  this.addLog(`WebSocket connection closed (code: ${event.code})`);
159
169
  this.status = "Disconnected";
160
170
  this.sessionId = null;
171
+ this.box = null;
161
172
  this.isConfigured = false;
162
173
  this.configSent = false;
163
174
  this.clearRenew();
@@ -197,10 +208,11 @@ var RealtimeMockupService = class {
197
208
  switch (data.type) {
198
209
  case "connected":
199
210
  this.sessionId = data.sessionId || null;
211
+ this.box = data.box ?? null;
200
212
  this.status = `Connected (Session: ${data.sessionId || "N/A"})`;
201
- this.addLog(`\u2705 Session established: ${data.sessionId}`);
213
+ this.addLog(`\u2705 Session established: ${data.sessionId}${this.box ? ` on ${this.box}` : ""}`);
202
214
  if (data.sessionId) {
203
- this.callbacks.onConnected?.(data.sessionId);
215
+ this.callbacks.onConnected?.(data.sessionId, { box: this.box ?? void 0 });
204
216
  }
205
217
  if (this.config && !this.configSent) {
206
218
  this.addLog("\u{1F4E4} Auto-sending cached config after connection...");
@@ -284,7 +296,10 @@ var RealtimeMockupService = class {
284
296
  renderCache: data.renderCache,
285
297
  cropRect: data.cropRect,
286
298
  serverTiming: data.serverTiming,
287
- canvasRenderTiming: data.canvasRenderTiming
299
+ canvasRenderTiming: data.canvasRenderTiming,
300
+ rtTiming: data.rtTiming,
301
+ clientRoundTripMs,
302
+ imageDelivery: data.imageDelivery === "ws" ? "ws" : "url"
288
303
  };
289
304
  const existingIndex = this.mockupResults.findIndex((m) => m.mockupId === data.mockupId);
290
305
  if (existingIndex >= 0) {
@@ -343,7 +358,8 @@ var RealtimeMockupService = class {
343
358
  const errorMessage = data.message || "Unknown error occurred";
344
359
  const renderError = {
345
360
  code: data.code || "render_error",
346
- message: errorMessage
361
+ message: errorMessage,
362
+ ...typeof data.mockupId === "string" ? { mockupId: data.mockupId } : {}
347
363
  };
348
364
  this.lastError = errorMessage;
349
365
  this.renderError = renderError;
@@ -414,7 +430,7 @@ var RealtimeMockupService = class {
414
430
  return false;
415
431
  }
416
432
  if (this.configSent && hasConfigChanged) {
417
- const isOnlyMockupIdsChange = this.config && this.config.productId === config.productId && this.config.variantId === config.variantId;
433
+ const isOnlyMockupIdsChange = this.config && this.config.productId === config.productId && this.config.variantId === config.variantId && sameRoleMap(this.config.picks, config.picks) && sameRoleMap(this.config.variants, config.variants);
418
434
  if (isOnlyMockupIdsChange) {
419
435
  this.addLog("\u{1F504} MockupIds changed, keeping cached blobs (server will reuse)");
420
436
  this.isConfigured = false;
@@ -739,6 +755,15 @@ ${versionToSend}
739
755
  hasPendingBlobs() {
740
756
  return Object.keys(this.throttleTimeouts).length > 0;
741
757
  }
758
+ /**
759
+ * Version stamped on the most recent canvas_state send (0 before any).
760
+ * Every frame answers with `requestVersion`, so a caller can tell which
761
+ * send a frame belongs to — the pipeline-depth send policy counts a send
762
+ * as landed when every mockup of its version has arrived.
763
+ */
764
+ getLastSentVersion() {
765
+ return this.lastSentVersion;
766
+ }
742
767
  sendColorBlob(placement, hexColor) {
743
768
  this.colors.set(placement, hexColor);
744
769
  if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.isConfigured) {
@@ -85,6 +85,7 @@ var ALLOWED_WIDTHS = [
85
85
  3e3,
86
86
  4e3
87
87
  ];
88
+ var MAX_RENDER_URL_LENGTH = 12 * 1024;
88
89
  function normalizeWidth(width) {
89
90
  for (let i = ALLOWED_WIDTHS.length - 1; i >= 0; i--) {
90
91
  if (ALLOWED_WIDTHS[i] <= width) return ALLOWED_WIDTHS[i];
@@ -163,7 +164,11 @@ var PARAM_PREFIX = {
163
164
  color: "color.",
164
165
  tile: "tile.",
165
166
  align: "align.",
166
- opt: "opt."
167
+ opt: "opt.",
168
+ /** ADR-0099 bundles: `variant.<role>=<gvid>` — one SKU per member slot. */
169
+ variant: "variant.",
170
+ /** ADR-0099 bundles: `pick.<role>=<productCode>` — which alternative fills a slot. */
171
+ pick: "pick."
167
172
  };
168
173
  var DEFAULT_PUBLIC_BASE_URL = "https://img.snowcone.app";
169
174
  function buildPublicMockupUrl(options, cfg = {}) {
package/dist/index.cjs CHANGED
@@ -564,6 +564,7 @@ var ALLOWED_WIDTHS = [
564
564
  3e3,
565
565
  4e3
566
566
  ];
567
+ var MAX_RENDER_URL_LENGTH = 12 * 1024;
567
568
  function normalizeWidth(width) {
568
569
  for (let i = ALLOWED_WIDTHS.length - 1; i >= 0; i--) {
569
570
  if (ALLOWED_WIDTHS[i] <= width) return ALLOWED_WIDTHS[i];
@@ -642,7 +643,11 @@ var PARAM_PREFIX = {
642
643
  color: "color.",
643
644
  tile: "tile.",
644
645
  align: "align.",
645
- opt: "opt."
646
+ opt: "opt.",
647
+ /** ADR-0099 bundles: `variant.<role>=<gvid>` — one SKU per member slot. */
648
+ variant: "variant.",
649
+ /** ADR-0099 bundles: `pick.<role>=<productCode>` — which alternative fills a slot. */
650
+ pick: "pick."
646
651
  };
647
652
  var DEFAULT_PUBLIC_BASE_URL = "https://img.snowcone.app";
648
653
  function buildPublicMockupUrl(options, cfg = {}) {
@@ -5014,6 +5019,12 @@ function newRenderCorrelation() {
5014
5019
  const spanId = randHex(8);
5015
5020
  return { requestId: traceId, traceparent: `00-${traceId}-${spanId}-01` };
5016
5021
  }
5022
+ function sameRoleMap(a, b) {
5023
+ const ka = Object.keys(a ?? {}).sort();
5024
+ const kb = Object.keys(b ?? {}).sort();
5025
+ if (ka.length !== kb.length) return false;
5026
+ return ka.every((k, i) => k === kb[i] && a[k] === b[k]);
5027
+ }
5017
5028
  var RealtimeMockupService = class {
5018
5029
  constructor(wsUrl = REALTIME_WS_URL) {
5019
5030
  this.wsUrl = wsUrl;
@@ -5022,6 +5033,9 @@ var RealtimeMockupService = class {
5022
5033
  config = null;
5023
5034
  configSent = false;
5024
5035
  sessionId = null;
5036
+ // Render node that answered the handshake (`connected.box`), for labs and
5037
+ // support: a realtime session has no response headers to read it from.
5038
+ box = null;
5025
5039
  isConfigured = false;
5026
5040
  mockupResults = [];
5027
5041
  status = "Disconnected";
@@ -5088,6 +5102,7 @@ var RealtimeMockupService = class {
5088
5102
  return {
5089
5103
  isConnected: this.ws?.readyState === WebSocket.OPEN,
5090
5104
  sessionId: this.sessionId,
5105
+ box: this.box,
5091
5106
  isConfigured: this.isConfigured,
5092
5107
  mockupResults: [...this.mockupResults],
5093
5108
  status: this.status,
@@ -5153,6 +5168,7 @@ var RealtimeMockupService = class {
5153
5168
  this.addLog(`WebSocket connection closed (code: ${event.code})`);
5154
5169
  this.status = "Disconnected";
5155
5170
  this.sessionId = null;
5171
+ this.box = null;
5156
5172
  this.isConfigured = false;
5157
5173
  this.configSent = false;
5158
5174
  this.clearRenew();
@@ -5192,10 +5208,11 @@ var RealtimeMockupService = class {
5192
5208
  switch (data.type) {
5193
5209
  case "connected":
5194
5210
  this.sessionId = data.sessionId || null;
5211
+ this.box = data.box ?? null;
5195
5212
  this.status = `Connected (Session: ${data.sessionId || "N/A"})`;
5196
- this.addLog(`\u2705 Session established: ${data.sessionId}`);
5213
+ this.addLog(`\u2705 Session established: ${data.sessionId}${this.box ? ` on ${this.box}` : ""}`);
5197
5214
  if (data.sessionId) {
5198
- this.callbacks.onConnected?.(data.sessionId);
5215
+ this.callbacks.onConnected?.(data.sessionId, { box: this.box ?? void 0 });
5199
5216
  }
5200
5217
  if (this.config && !this.configSent) {
5201
5218
  this.addLog("\u{1F4E4} Auto-sending cached config after connection...");
@@ -5279,7 +5296,10 @@ var RealtimeMockupService = class {
5279
5296
  renderCache: data.renderCache,
5280
5297
  cropRect: data.cropRect,
5281
5298
  serverTiming: data.serverTiming,
5282
- canvasRenderTiming: data.canvasRenderTiming
5299
+ canvasRenderTiming: data.canvasRenderTiming,
5300
+ rtTiming: data.rtTiming,
5301
+ clientRoundTripMs,
5302
+ imageDelivery: data.imageDelivery === "ws" ? "ws" : "url"
5283
5303
  };
5284
5304
  const existingIndex = this.mockupResults.findIndex((m) => m.mockupId === data.mockupId);
5285
5305
  if (existingIndex >= 0) {
@@ -5338,7 +5358,8 @@ var RealtimeMockupService = class {
5338
5358
  const errorMessage = data.message || "Unknown error occurred";
5339
5359
  const renderError = {
5340
5360
  code: data.code || "render_error",
5341
- message: errorMessage
5361
+ message: errorMessage,
5362
+ ...typeof data.mockupId === "string" ? { mockupId: data.mockupId } : {}
5342
5363
  };
5343
5364
  this.lastError = errorMessage;
5344
5365
  this.renderError = renderError;
@@ -5409,7 +5430,7 @@ var RealtimeMockupService = class {
5409
5430
  return false;
5410
5431
  }
5411
5432
  if (this.configSent && hasConfigChanged) {
5412
- const isOnlyMockupIdsChange = this.config && this.config.productId === config.productId && this.config.variantId === config.variantId;
5433
+ const isOnlyMockupIdsChange = this.config && this.config.productId === config.productId && this.config.variantId === config.variantId && sameRoleMap(this.config.picks, config.picks) && sameRoleMap(this.config.variants, config.variants);
5413
5434
  if (isOnlyMockupIdsChange) {
5414
5435
  this.addLog("\u{1F504} MockupIds changed, keeping cached blobs (server will reuse)");
5415
5436
  this.isConfigured = false;
@@ -5734,6 +5755,15 @@ ${versionToSend}
5734
5755
  hasPendingBlobs() {
5735
5756
  return Object.keys(this.throttleTimeouts).length > 0;
5736
5757
  }
5758
+ /**
5759
+ * Version stamped on the most recent canvas_state send (0 before any).
5760
+ * Every frame answers with `requestVersion`, so a caller can tell which
5761
+ * send a frame belongs to — the pipeline-depth send policy counts a send
5762
+ * as landed when every mockup of its version has arrived.
5763
+ */
5764
+ getLastSentVersion() {
5765
+ return this.lastSentVersion;
5766
+ }
5737
5767
  sendColorBlob(placement, hexColor) {
5738
5768
  this.colors.set(placement, hexColor);
5739
5769
  if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.isConfigured) {
@@ -6268,7 +6298,12 @@ var RenderSession = class {
6268
6298
  variantId: product.variantId ?? "",
6269
6299
  width: product.width ?? 1e3,
6270
6300
  ...product.ar ? { ar: product.ar } : {},
6271
- ...product.placementSettings ? { placementSettings: product.placementSettings } : {}
6301
+ ...product.placementSettings ? { placementSettings: product.placementSettings } : {},
6302
+ // ADR-0099 bundle session: per-role picks + variants ride the config
6303
+ // verbatim; the server resolves each slot and derives the role-scoped
6304
+ // required placement set from them.
6305
+ ...product.picks ? { picks: product.picks } : {},
6306
+ ...product.variants ? { variants: product.variants } : {}
6272
6307
  };
6273
6308
  }
6274
6309
  };
package/dist/index.d.cts CHANGED
@@ -1,7 +1,7 @@
1
1
  export { createDevFetcher } from './dev-fetcher.cjs';
2
2
  import { PublicDesign, PublicFill, PublicOptions } from '@snowcone-app/mockup-url';
3
- import { O as OptionAttribute, a as OptionSelection, C as Combination, F as FrameworkAdapter, b as ComponentProps, c as ComponentDescriptor, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, g as FrameworkUtilities, P as PlacementSettings, M as MockupResult, R as RealtimeRenderError, h as RealtimeMockupService } from './websocket-CScS7UR-.cjs';
4
- export { A as AdapterRegistry, i as ProductComponentContext, j as RealtimeMockupCallbacks, k as RealtimeMockupState, l as RenderResult, W as WebSocketConfig, m as WebSocketMessage, n as adapterRegistry, o as computeDisabledChoices, p as createComponent, q as defineComponent, r as deriveDefaultSelection, s as findBestCombination, t as getPricePreview, u as isOptionAvailable, v as resolveBestCombination } from './websocket-CScS7UR-.cjs';
3
+ import { O as OptionAttribute, a as OptionSelection, C as Combination, F as FrameworkAdapter, b as ComponentProps, c as ComponentDescriptor, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, g as FrameworkUtilities, P as PlacementSettings, M as MockupResult, R as RealtimeRenderError, h as RealtimeMockupService } from './websocket-DXO35yrh.cjs';
4
+ export { A as AdapterRegistry, i as ProductComponentContext, j as RealtimeMockupCallbacks, k as RealtimeMockupState, l as RenderResult, W as WebSocketConfig, m as WebSocketMessage, n as adapterRegistry, o as computeDisabledChoices, p as createComponent, q as defineComponent, r as deriveDefaultSelection, s as findBestCombination, t as getPricePreview, u as isOptionAvailable, v as resolveBestCombination } from './websocket-DXO35yrh.cjs';
5
5
 
6
6
  interface CatalogProduct {
7
7
  id: string;
@@ -17,6 +17,12 @@ interface CatalogProduct {
17
17
  mockups?: {
18
18
  id: string;
19
19
  gvids: string[];
20
+ /**
21
+ * ADR-0099 (bundle records only): which alternative each slot shows in this scene's photo, `role -> member product code`. A bundle session selects the scenes whose picks agree with its own; single products never carry it.
22
+ */
23
+ picks?: {
24
+ [k: string]: string;
25
+ };
20
26
  }[];
21
27
  options?: {
22
28
  selected?: {
@@ -79,6 +85,14 @@ interface CatalogProduct {
79
85
  scale?: number;
80
86
  offsetX?: number;
81
87
  offsetY?: number;
88
+ /**
89
+ * ADR-0099 (bundle records only): the slot this placement belongs to. The wire key is then role-scoped (`key` = `<role>.<member key>`, e.g. "top.front") and it is the placement NAME a realtime `canvas_state` / `renderState` must use.
90
+ */
91
+ role?: string;
92
+ /**
93
+ * ADR-0099 (bundle records only): the member product (slot alternative) this placement belongs to. Two alternatives in one slot share the key; the session's pick decides which one is live.
94
+ */
95
+ memberProductId?: string;
82
96
  }[];
83
97
  /**
84
98
  * The renderer's required-placement contract, surfaced so a developer reads exactly which placements `renderState` will demand. Image placements are always sent by the caller; color placements (autoFilledByVariant: true) are filled from `variantId` — omit them when you pass a variantId, send them otherwise.
@@ -94,6 +108,10 @@ interface CatalogProduct {
94
108
  * When true, this (color) placement is auto-filled from the variant's option choice when a `variantId` is sent; otherwise the caller must send it explicitly.
95
109
  */
96
110
  autoFilledByVariant: boolean;
111
+ /**
112
+ * ADR-0099 (bundle records only): the slot this required placement belongs to; `key` is the role-scoped name to send.
113
+ */
114
+ role?: string;
97
115
  }[];
98
116
  defaultGvid?: string | null;
99
117
  /**
@@ -117,6 +135,68 @@ interface CatalogProduct {
117
135
  step: number;
118
136
  };
119
137
  };
138
+ /**
139
+ * ADR-0099: marks a BUNDLE — several products photographed in one mockup, sold together. Each member is a SLOT (`role`) with one or more alternative products (`products`, first = default pick). A bundle's placements are role-scoped (`placements[].role`, key `<role>.<key>`), its variants are named per role, and a realtime session on it sends `picks` + `variants` instead of `variantId`. Additive: products without this block are unaffected.
140
+ */
141
+ bundle?: {
142
+ members: {
143
+ /**
144
+ * The slot name (e.g. "top", "shorts"). Prefixes every placement key and variant of the slot.
145
+ */
146
+ role: string;
147
+ required?: boolean;
148
+ /**
149
+ * The slot's alternatives, first = default pick.
150
+ */
151
+ products: {
152
+ productId: string;
153
+ /**
154
+ * The variant a session renders for this alternative when `variants.<role>` is omitted.
155
+ */
156
+ defaultGvid?: string | null;
157
+ /**
158
+ * The alternative's selectable variants for a session (`variants.<role>` must be one of these gvids when the list is non-empty) and the render gvid each maps to.
159
+ */
160
+ variants?: {
161
+ gvid: string;
162
+ gvidForMockup?: string | null;
163
+ }[];
164
+ /**
165
+ * The alternative's own `options` block (attributes + combinations), underlays stripped — labels a per-slot variant picker.
166
+ */
167
+ options?: {
168
+ attributes?: {
169
+ [k: string]: {
170
+ type?: string;
171
+ affectsCombinations?: boolean;
172
+ choices?: {
173
+ label: string;
174
+ hex?: string;
175
+ imageUrl?: string;
176
+ }[];
177
+ };
178
+ };
179
+ combinations?: {
180
+ price?: number;
181
+ variantId?: string;
182
+ [k: string]: string | number | undefined;
183
+ }[];
184
+ };
185
+ }[];
186
+ }[];
187
+ /**
188
+ * The bundle discount (e.g. { "kind": "percent_off", "bps": 1000 }).
189
+ */
190
+ priceRule?: unknown;
191
+ /**
192
+ * Pick sets no published scene photographs yet.
193
+ */
194
+ uncoveredPickSets?: {
195
+ [k: string]: string;
196
+ }[];
197
+ warmEstimate?: number;
198
+ warmBudget?: number;
199
+ };
120
200
  }
121
201
 
122
202
  /**
@@ -2977,6 +3057,27 @@ interface RenderProduct {
2977
3057
  ar?: AspectRatio;
2978
3058
  /** Per-placement settings (tiling, scale mode). */
2979
3059
  placementSettings?: Record<string, PlacementSettings>;
3060
+ /**
3061
+ * ADR-0099 — BUNDLE records only (a product whose catalog payload carries a
3062
+ * `bundle` block: several products in one mockup). Which alternative fills
3063
+ * each slot, `role → member product code`; omitted roles take the slot's
3064
+ * first alternative. Sent verbatim as the config's `picks`; the server
3065
+ * re-validates every config message (`E_BUNDLE_PICK_NOT_FOUND` lists the
3066
+ * slot's alternatives, `E_BUNDLE_ROLE_NOT_FOUND` the roles) and refuses it
3067
+ * on a single product (`E_NOT_A_BUNDLE`). Build it with
3068
+ * `bundleToRenderConfig()` from `@snowcone-app/canvas/embed` rather than by
3069
+ * hand — the builder fills defaults and throws typed errors up front.
3070
+ */
3071
+ picks?: Record<string, string>;
3072
+ /**
3073
+ * ADR-0099 — BUNDLE records only. The variant per slot, `role → gvid`. On a
3074
+ * bundle the placement names you pass to {@link RenderSession.renderState}
3075
+ * are role-scoped keys (`"top.front"`, the catalog `placements[].key`), and
3076
+ * the variant is named per ROLE: leave {@link variantId} unset — a bare
3077
+ * `variantId` on a bundle is refused by the server (`E_BUNDLE_ROLE_REQUIRED`
3078
+ * listing the roles). Refused on a single product (`E_NOT_A_BUNDLE`).
3079
+ */
3080
+ variants?: Record<string, string>;
2980
3081
  }
2981
3082
  /**
2982
3083
  * Throws immediately if the product has a COLOR variant axis (an
package/dist/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  export { createDevFetcher } from './dev-fetcher.js';
2
2
  import { PublicDesign, PublicFill, PublicOptions } from '@snowcone-app/mockup-url';
3
- import { O as OptionAttribute, a as OptionSelection, C as Combination, F as FrameworkAdapter, b as ComponentProps, c as ComponentDescriptor, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, g as FrameworkUtilities, P as PlacementSettings, M as MockupResult, R as RealtimeRenderError, h as RealtimeMockupService } from './websocket-CScS7UR-.js';
4
- export { A as AdapterRegistry, i as ProductComponentContext, j as RealtimeMockupCallbacks, k as RealtimeMockupState, l as RenderResult, W as WebSocketConfig, m as WebSocketMessage, n as adapterRegistry, o as computeDisabledChoices, p as createComponent, q as defineComponent, r as deriveDefaultSelection, s as findBestCombination, t as getPricePreview, u as isOptionAvailable, v as resolveBestCombination } from './websocket-CScS7UR-.js';
3
+ import { O as OptionAttribute, a as OptionSelection, C as Combination, F as FrameworkAdapter, b as ComponentProps, c as ComponentDescriptor, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, g as FrameworkUtilities, P as PlacementSettings, M as MockupResult, R as RealtimeRenderError, h as RealtimeMockupService } from './websocket-DXO35yrh.js';
4
+ export { A as AdapterRegistry, i as ProductComponentContext, j as RealtimeMockupCallbacks, k as RealtimeMockupState, l as RenderResult, W as WebSocketConfig, m as WebSocketMessage, n as adapterRegistry, o as computeDisabledChoices, p as createComponent, q as defineComponent, r as deriveDefaultSelection, s as findBestCombination, t as getPricePreview, u as isOptionAvailable, v as resolveBestCombination } from './websocket-DXO35yrh.js';
5
5
 
6
6
  interface CatalogProduct {
7
7
  id: string;
@@ -17,6 +17,12 @@ interface CatalogProduct {
17
17
  mockups?: {
18
18
  id: string;
19
19
  gvids: string[];
20
+ /**
21
+ * ADR-0099 (bundle records only): which alternative each slot shows in this scene's photo, `role -> member product code`. A bundle session selects the scenes whose picks agree with its own; single products never carry it.
22
+ */
23
+ picks?: {
24
+ [k: string]: string;
25
+ };
20
26
  }[];
21
27
  options?: {
22
28
  selected?: {
@@ -79,6 +85,14 @@ interface CatalogProduct {
79
85
  scale?: number;
80
86
  offsetX?: number;
81
87
  offsetY?: number;
88
+ /**
89
+ * ADR-0099 (bundle records only): the slot this placement belongs to. The wire key is then role-scoped (`key` = `<role>.<member key>`, e.g. "top.front") and it is the placement NAME a realtime `canvas_state` / `renderState` must use.
90
+ */
91
+ role?: string;
92
+ /**
93
+ * ADR-0099 (bundle records only): the member product (slot alternative) this placement belongs to. Two alternatives in one slot share the key; the session's pick decides which one is live.
94
+ */
95
+ memberProductId?: string;
82
96
  }[];
83
97
  /**
84
98
  * The renderer's required-placement contract, surfaced so a developer reads exactly which placements `renderState` will demand. Image placements are always sent by the caller; color placements (autoFilledByVariant: true) are filled from `variantId` — omit them when you pass a variantId, send them otherwise.
@@ -94,6 +108,10 @@ interface CatalogProduct {
94
108
  * When true, this (color) placement is auto-filled from the variant's option choice when a `variantId` is sent; otherwise the caller must send it explicitly.
95
109
  */
96
110
  autoFilledByVariant: boolean;
111
+ /**
112
+ * ADR-0099 (bundle records only): the slot this required placement belongs to; `key` is the role-scoped name to send.
113
+ */
114
+ role?: string;
97
115
  }[];
98
116
  defaultGvid?: string | null;
99
117
  /**
@@ -117,6 +135,68 @@ interface CatalogProduct {
117
135
  step: number;
118
136
  };
119
137
  };
138
+ /**
139
+ * ADR-0099: marks a BUNDLE — several products photographed in one mockup, sold together. Each member is a SLOT (`role`) with one or more alternative products (`products`, first = default pick). A bundle's placements are role-scoped (`placements[].role`, key `<role>.<key>`), its variants are named per role, and a realtime session on it sends `picks` + `variants` instead of `variantId`. Additive: products without this block are unaffected.
140
+ */
141
+ bundle?: {
142
+ members: {
143
+ /**
144
+ * The slot name (e.g. "top", "shorts"). Prefixes every placement key and variant of the slot.
145
+ */
146
+ role: string;
147
+ required?: boolean;
148
+ /**
149
+ * The slot's alternatives, first = default pick.
150
+ */
151
+ products: {
152
+ productId: string;
153
+ /**
154
+ * The variant a session renders for this alternative when `variants.<role>` is omitted.
155
+ */
156
+ defaultGvid?: string | null;
157
+ /**
158
+ * The alternative's selectable variants for a session (`variants.<role>` must be one of these gvids when the list is non-empty) and the render gvid each maps to.
159
+ */
160
+ variants?: {
161
+ gvid: string;
162
+ gvidForMockup?: string | null;
163
+ }[];
164
+ /**
165
+ * The alternative's own `options` block (attributes + combinations), underlays stripped — labels a per-slot variant picker.
166
+ */
167
+ options?: {
168
+ attributes?: {
169
+ [k: string]: {
170
+ type?: string;
171
+ affectsCombinations?: boolean;
172
+ choices?: {
173
+ label: string;
174
+ hex?: string;
175
+ imageUrl?: string;
176
+ }[];
177
+ };
178
+ };
179
+ combinations?: {
180
+ price?: number;
181
+ variantId?: string;
182
+ [k: string]: string | number | undefined;
183
+ }[];
184
+ };
185
+ }[];
186
+ }[];
187
+ /**
188
+ * The bundle discount (e.g. { "kind": "percent_off", "bps": 1000 }).
189
+ */
190
+ priceRule?: unknown;
191
+ /**
192
+ * Pick sets no published scene photographs yet.
193
+ */
194
+ uncoveredPickSets?: {
195
+ [k: string]: string;
196
+ }[];
197
+ warmEstimate?: number;
198
+ warmBudget?: number;
199
+ };
120
200
  }
121
201
 
122
202
  /**
@@ -2977,6 +3057,27 @@ interface RenderProduct {
2977
3057
  ar?: AspectRatio;
2978
3058
  /** Per-placement settings (tiling, scale mode). */
2979
3059
  placementSettings?: Record<string, PlacementSettings>;
3060
+ /**
3061
+ * ADR-0099 — BUNDLE records only (a product whose catalog payload carries a
3062
+ * `bundle` block: several products in one mockup). Which alternative fills
3063
+ * each slot, `role → member product code`; omitted roles take the slot's
3064
+ * first alternative. Sent verbatim as the config's `picks`; the server
3065
+ * re-validates every config message (`E_BUNDLE_PICK_NOT_FOUND` lists the
3066
+ * slot's alternatives, `E_BUNDLE_ROLE_NOT_FOUND` the roles) and refuses it
3067
+ * on a single product (`E_NOT_A_BUNDLE`). Build it with
3068
+ * `bundleToRenderConfig()` from `@snowcone-app/canvas/embed` rather than by
3069
+ * hand — the builder fills defaults and throws typed errors up front.
3070
+ */
3071
+ picks?: Record<string, string>;
3072
+ /**
3073
+ * ADR-0099 — BUNDLE records only. The variant per slot, `role → gvid`. On a
3074
+ * bundle the placement names you pass to {@link RenderSession.renderState}
3075
+ * are role-scoped keys (`"top.front"`, the catalog `placements[].key`), and
3076
+ * the variant is named per ROLE: leave {@link variantId} unset — a bare
3077
+ * `variantId` on a bundle is refused by the server (`E_BUNDLE_ROLE_REQUIRED`
3078
+ * listing the roles). Refused on a single product (`E_NOT_A_BUNDLE`).
3079
+ */
3080
+ variants?: Record<string, string>;
2980
3081
  }
2981
3082
  /**
2982
3083
  * Throws immediately if the product has a COLOR variant axis (an
package/dist/index.js CHANGED
@@ -4,14 +4,14 @@ import {
4
4
  import {
5
5
  REALTIME_WS_URL,
6
6
  RealtimeMockupService
7
- } from "./chunk-SZZQ2CBF.js";
7
+ } from "./chunk-5DNY477E.js";
8
8
  import {
9
9
  buildMockupUrl,
10
10
  buildPublicMockupUrl,
11
11
  canonicalForSig,
12
12
  normalizeDesignElements,
13
13
  normalizeWidth
14
- } from "./chunk-553YYMDY.js";
14
+ } from "./chunk-ZBJBBIH3.js";
15
15
 
16
16
  // src/validation.ts
17
17
  import { z } from "zod";
@@ -5002,7 +5002,12 @@ var RenderSession = class {
5002
5002
  variantId: product.variantId ?? "",
5003
5003
  width: product.width ?? 1e3,
5004
5004
  ...product.ar ? { ar: product.ar } : {},
5005
- ...product.placementSettings ? { placementSettings: product.placementSettings } : {}
5005
+ ...product.placementSettings ? { placementSettings: product.placementSettings } : {},
5006
+ // ADR-0099 bundle session: per-role picks + variants ride the config
5007
+ // verbatim; the server resolves each slot and derives the role-scoped
5008
+ // required placement set from them.
5009
+ ...product.picks ? { picks: product.picks } : {},
5010
+ ...product.variants ? { variants: product.variants } : {}
5006
5011
  };
5007
5012
  }
5008
5013
  };
package/dist/react.cjs CHANGED
@@ -53,6 +53,12 @@ function newRenderCorrelation() {
53
53
  const spanId = randHex(8);
54
54
  return { requestId: traceId, traceparent: `00-${traceId}-${spanId}-01` };
55
55
  }
56
+ function sameRoleMap(a, b) {
57
+ const ka = Object.keys(a ?? {}).sort();
58
+ const kb = Object.keys(b ?? {}).sort();
59
+ if (ka.length !== kb.length) return false;
60
+ return ka.every((k, i) => k === kb[i] && a[k] === b[k]);
61
+ }
56
62
  var RealtimeMockupService = class {
57
63
  constructor(wsUrl = REALTIME_WS_URL) {
58
64
  this.wsUrl = wsUrl;
@@ -61,6 +67,9 @@ var RealtimeMockupService = class {
61
67
  config = null;
62
68
  configSent = false;
63
69
  sessionId = null;
70
+ // Render node that answered the handshake (`connected.box`), for labs and
71
+ // support: a realtime session has no response headers to read it from.
72
+ box = null;
64
73
  isConfigured = false;
65
74
  mockupResults = [];
66
75
  status = "Disconnected";
@@ -127,6 +136,7 @@ var RealtimeMockupService = class {
127
136
  return {
128
137
  isConnected: this.ws?.readyState === WebSocket.OPEN,
129
138
  sessionId: this.sessionId,
139
+ box: this.box,
130
140
  isConfigured: this.isConfigured,
131
141
  mockupResults: [...this.mockupResults],
132
142
  status: this.status,
@@ -192,6 +202,7 @@ var RealtimeMockupService = class {
192
202
  this.addLog(`WebSocket connection closed (code: ${event.code})`);
193
203
  this.status = "Disconnected";
194
204
  this.sessionId = null;
205
+ this.box = null;
195
206
  this.isConfigured = false;
196
207
  this.configSent = false;
197
208
  this.clearRenew();
@@ -231,10 +242,11 @@ var RealtimeMockupService = class {
231
242
  switch (data.type) {
232
243
  case "connected":
233
244
  this.sessionId = data.sessionId || null;
245
+ this.box = data.box ?? null;
234
246
  this.status = `Connected (Session: ${data.sessionId || "N/A"})`;
235
- this.addLog(`\u2705 Session established: ${data.sessionId}`);
247
+ this.addLog(`\u2705 Session established: ${data.sessionId}${this.box ? ` on ${this.box}` : ""}`);
236
248
  if (data.sessionId) {
237
- this.callbacks.onConnected?.(data.sessionId);
249
+ this.callbacks.onConnected?.(data.sessionId, { box: this.box ?? void 0 });
238
250
  }
239
251
  if (this.config && !this.configSent) {
240
252
  this.addLog("\u{1F4E4} Auto-sending cached config after connection...");
@@ -318,7 +330,10 @@ var RealtimeMockupService = class {
318
330
  renderCache: data.renderCache,
319
331
  cropRect: data.cropRect,
320
332
  serverTiming: data.serverTiming,
321
- canvasRenderTiming: data.canvasRenderTiming
333
+ canvasRenderTiming: data.canvasRenderTiming,
334
+ rtTiming: data.rtTiming,
335
+ clientRoundTripMs,
336
+ imageDelivery: data.imageDelivery === "ws" ? "ws" : "url"
322
337
  };
323
338
  const existingIndex = this.mockupResults.findIndex((m) => m.mockupId === data.mockupId);
324
339
  if (existingIndex >= 0) {
@@ -377,7 +392,8 @@ var RealtimeMockupService = class {
377
392
  const errorMessage = data.message || "Unknown error occurred";
378
393
  const renderError = {
379
394
  code: data.code || "render_error",
380
- message: errorMessage
395
+ message: errorMessage,
396
+ ...typeof data.mockupId === "string" ? { mockupId: data.mockupId } : {}
381
397
  };
382
398
  this.lastError = errorMessage;
383
399
  this.renderError = renderError;
@@ -448,7 +464,7 @@ var RealtimeMockupService = class {
448
464
  return false;
449
465
  }
450
466
  if (this.configSent && hasConfigChanged) {
451
- const isOnlyMockupIdsChange = this.config && this.config.productId === config.productId && this.config.variantId === config.variantId;
467
+ const isOnlyMockupIdsChange = this.config && this.config.productId === config.productId && this.config.variantId === config.variantId && sameRoleMap(this.config.picks, config.picks) && sameRoleMap(this.config.variants, config.variants);
452
468
  if (isOnlyMockupIdsChange) {
453
469
  this.addLog("\u{1F504} MockupIds changed, keeping cached blobs (server will reuse)");
454
470
  this.isConfigured = false;
@@ -773,6 +789,15 @@ ${versionToSend}
773
789
  hasPendingBlobs() {
774
790
  return Object.keys(this.throttleTimeouts).length > 0;
775
791
  }
792
+ /**
793
+ * Version stamped on the most recent canvas_state send (0 before any).
794
+ * Every frame answers with `requestVersion`, so a caller can tell which
795
+ * send a frame belongs to — the pipeline-depth send policy counts a send
796
+ * as landed when every mockup of its version has arrived.
797
+ */
798
+ getLastSentVersion() {
799
+ return this.lastSentVersion;
800
+ }
776
801
  sendColorBlob(placement, hexColor) {
777
802
  this.colors.set(placement, hexColor);
778
803
  if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.isConfigured) {
@@ -878,6 +903,7 @@ function useRealtimeMockup(options = {}) {
878
903
  const [state, setState] = (0, import_react.useState)({
879
904
  isConnected: false,
880
905
  sessionId: null,
906
+ box: null,
881
907
  isConfigured: false,
882
908
  mockupResults: [],
883
909
  status: "Disconnected",
@@ -889,9 +915,9 @@ function useRealtimeMockup(options = {}) {
889
915
  const service = new RealtimeMockupService(wsUrl);
890
916
  serviceRef.current = service;
891
917
  service.setCallbacks({
892
- onConnected: (sessionId) => {
918
+ onConnected: (sessionId, info) => {
893
919
  setState(service.getState());
894
- options.onConnected?.(sessionId);
920
+ options.onConnected?.(sessionId, info);
895
921
  },
896
922
  onDisconnected: () => {
897
923
  setState(service.getState());
@@ -981,6 +1007,9 @@ function useRealtimeMockup(options = {}) {
981
1007
  const hasPendingBlobs = (0, import_react.useCallback)(() => {
982
1008
  return serviceRef.current?.hasPendingBlobs() || false;
983
1009
  }, []);
1010
+ const getLastSentVersion = (0, import_react.useCallback)(() => {
1011
+ return serviceRef.current?.getLastSentVersion() ?? 0;
1012
+ }, []);
984
1013
  return {
985
1014
  ...state,
986
1015
  connect,
@@ -998,7 +1027,8 @@ function useRealtimeMockup(options = {}) {
998
1027
  clearLogs,
999
1028
  clearMockups,
1000
1029
  flushPendingBlobs,
1001
- hasPendingBlobs
1030
+ hasPendingBlobs,
1031
+ getLastSentVersion
1002
1032
  };
1003
1033
  }
1004
1034
 
package/dist/react.d.cts CHANGED
@@ -1,4 +1,4 @@
1
- import { M as MockupResult, R as RealtimeRenderError, W as WebSocketConfig, P as PlacementSettings, F as FrameworkAdapter, b as ComponentProps, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, c as ComponentDescriptor, g as FrameworkUtilities } from './websocket-CScS7UR-.cjs';
1
+ import { M as MockupResult, R as RealtimeRenderError, W as WebSocketConfig, P as PlacementSettings, F as FrameworkAdapter, b as ComponentProps, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, c as ComponentDescriptor, g as FrameworkUtilities } from './websocket-DXO35yrh.cjs';
2
2
  import { CSSProperties, ReactNode } from 'react';
3
3
 
4
4
  interface UseRealtimeMockupOptions {
@@ -13,7 +13,9 @@ interface UseRealtimeMockupOptions {
13
13
  token: string;
14
14
  expiresAt: number;
15
15
  }>;
16
- onConnected?: (sessionId: string) => void;
16
+ onConnected?: (sessionId: string, info: {
17
+ box?: string;
18
+ }) => void;
17
19
  onDisconnected?: () => void;
18
20
  onConfigReceived?: () => void;
19
21
  /** Called when server confirms it received a blob for a placement */
@@ -51,8 +53,10 @@ declare function useRealtimeMockup(options?: UseRealtimeMockupOptions): {
51
53
  clearMockups: () => void;
52
54
  flushPendingBlobs: () => void;
53
55
  hasPendingBlobs: () => boolean;
56
+ getLastSentVersion: () => number;
54
57
  isConnected: boolean;
55
58
  sessionId: string | null;
59
+ box: string | null;
56
60
  isConfigured: boolean;
57
61
  mockupResults: MockupResult[];
58
62
  status: string;
package/dist/react.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { M as MockupResult, R as RealtimeRenderError, W as WebSocketConfig, P as PlacementSettings, F as FrameworkAdapter, b as ComponentProps, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, c as ComponentDescriptor, g as FrameworkUtilities } from './websocket-CScS7UR-.js';
1
+ import { M as MockupResult, R as RealtimeRenderError, W as WebSocketConfig, P as PlacementSettings, F as FrameworkAdapter, b as ComponentProps, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, c as ComponentDescriptor, g as FrameworkUtilities } from './websocket-DXO35yrh.js';
2
2
  import { CSSProperties, ReactNode } from 'react';
3
3
 
4
4
  interface UseRealtimeMockupOptions {
@@ -13,7 +13,9 @@ interface UseRealtimeMockupOptions {
13
13
  token: string;
14
14
  expiresAt: number;
15
15
  }>;
16
- onConnected?: (sessionId: string) => void;
16
+ onConnected?: (sessionId: string, info: {
17
+ box?: string;
18
+ }) => void;
17
19
  onDisconnected?: () => void;
18
20
  onConfigReceived?: () => void;
19
21
  /** Called when server confirms it received a blob for a placement */
@@ -51,8 +53,10 @@ declare function useRealtimeMockup(options?: UseRealtimeMockupOptions): {
51
53
  clearMockups: () => void;
52
54
  flushPendingBlobs: () => void;
53
55
  hasPendingBlobs: () => boolean;
56
+ getLastSentVersion: () => number;
54
57
  isConnected: boolean;
55
58
  sessionId: string | null;
59
+ box: string | null;
56
60
  isConfigured: boolean;
57
61
  mockupResults: MockupResult[];
58
62
  status: string;
package/dist/react.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import {
2
2
  RealtimeMockupService
3
- } from "./chunk-SZZQ2CBF.js";
3
+ } from "./chunk-5DNY477E.js";
4
4
 
5
5
  // src/realtime/react.ts
6
6
  import { useCallback, useEffect, useRef, useState } from "react";
@@ -13,6 +13,7 @@ function useRealtimeMockup(options = {}) {
13
13
  const [state, setState] = useState({
14
14
  isConnected: false,
15
15
  sessionId: null,
16
+ box: null,
16
17
  isConfigured: false,
17
18
  mockupResults: [],
18
19
  status: "Disconnected",
@@ -24,9 +25,9 @@ function useRealtimeMockup(options = {}) {
24
25
  const service = new RealtimeMockupService(wsUrl);
25
26
  serviceRef.current = service;
26
27
  service.setCallbacks({
27
- onConnected: (sessionId) => {
28
+ onConnected: (sessionId, info) => {
28
29
  setState(service.getState());
29
- options.onConnected?.(sessionId);
30
+ options.onConnected?.(sessionId, info);
30
31
  },
31
32
  onDisconnected: () => {
32
33
  setState(service.getState());
@@ -116,6 +117,9 @@ function useRealtimeMockup(options = {}) {
116
117
  const hasPendingBlobs = useCallback(() => {
117
118
  return serviceRef.current?.hasPendingBlobs() || false;
118
119
  }, []);
120
+ const getLastSentVersion = useCallback(() => {
121
+ return serviceRef.current?.getLastSentVersion() ?? 0;
122
+ }, []);
119
123
  return {
120
124
  ...state,
121
125
  connect,
@@ -133,7 +137,8 @@ function useRealtimeMockup(options = {}) {
133
137
  clearLogs,
134
138
  clearMockups,
135
139
  flushPendingBlobs,
136
- hasPendingBlobs
140
+ hasPendingBlobs,
141
+ getLastSentVersion
137
142
  };
138
143
  }
139
144
 
package/dist/server.cjs CHANGED
@@ -80,6 +80,7 @@ var PARAMS = {
80
80
  signature: "signature",
81
81
  seal: "seal"
82
82
  };
83
+ var MAX_RENDER_URL_LENGTH = 12 * 1024;
83
84
  var PUBLIC_PARAM_NAMES = [
84
85
  PARAMS.asset,
85
86
  PARAMS.design,
package/dist/server.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import {
2
2
  canonicalForSig,
3
3
  signDevSig
4
- } from "./chunk-553YYMDY.js";
4
+ } from "./chunk-ZBJBBIH3.js";
5
5
 
6
6
  // src/server.ts
7
7
  function json(body, status = 200) {
@@ -268,6 +268,22 @@ interface WebSocketConfig {
268
268
  */
269
269
  debugKey?: string;
270
270
  placementSettings?: Record<string, PlacementSettings>;
271
+ /**
272
+ * ADR-0099 (bundle records only): which alternative fills each slot —
273
+ * `role → member product code`. Omitted roles take the slot's first
274
+ * alternative. The server re-validates every config message
275
+ * (`E_BUNDLE_PICK_NOT_FOUND` lists the slot's alternatives); on a
276
+ * single product it is refused (`E_NOT_A_BUNDLE`).
277
+ */
278
+ picks?: Record<string, string>;
279
+ /**
280
+ * ADR-0099 (bundle records only): the variant per slot — `role → gvid`.
281
+ * A bundle session names its variants per ROLE; a bare `variantId` on a
282
+ * bundle is refused by the server (`E_BUNDLE_ROLE_REQUIRED`), so send
283
+ * `variantId: ''` alongside this. On a single product it is refused
284
+ * (`E_NOT_A_BUNDLE`).
285
+ */
286
+ variants?: Record<string, string>;
271
287
  }
272
288
  interface MockupResult {
273
289
  mockupId: string;
@@ -301,6 +317,23 @@ interface MockupResult {
301
317
  serverTiming?: string;
302
318
  /** Server-side canvas render timing breakdown (present when canvas_state was used) */
303
319
  canvasRenderTiming?: any;
320
+ /**
321
+ * Box-window envelope of this frame in Server-Timing grammar — receive →
322
+ * send on the render node: `rt_total`, `rt_guard`, `rt_canvas` (+
323
+ * `rt_canvas_hop`, `canvas_*`), `rt_coalesce` (desc `superseded N`),
324
+ * `rt_composite`, `rt_store`, `rt_deliver` (desc `sz=<bytes> ws|url`),
325
+ * `rt_box`. Present on every frame from a server that emits it — no
326
+ * debug key needed. `clientRoundTripMs − rt_total` is the round-trip
327
+ * transport (browser ↔ edge ↔ box, both directions).
328
+ */
329
+ rtTiming?: string;
330
+ /** Client-observed edit → frame: the canvas_state send this frame answers
331
+ * → this message's arrival, in ms. Undefined when the frame was not
332
+ * triggered by a send from this client (config re-render, replay). */
333
+ clientRoundTripMs?: number;
334
+ /** How the bytes arrived: pushed down the socket ('ws') or via the
335
+ * imageUrl fetch ('url'). */
336
+ imageDelivery?: 'ws' | 'url';
304
337
  }
305
338
  interface WebSocketMessage {
306
339
  type: string;
@@ -336,6 +369,12 @@ interface WebSocketMessage {
336
369
  };
337
370
  /** Raw Server-Timing breakdown (only when the session's debugKey matched) */
338
371
  serverTiming?: string;
372
+ /** Box-window envelope of the frame (see MockupResult.rtTiming) */
373
+ rtTiming?: string;
374
+ /** Render node identity, on `connected` */
375
+ box?: string;
376
+ /** 'ws' when the image bytes were pushed as a mockup_frame before this message */
377
+ imageDelivery?: string;
339
378
  /** Server-side canvas render timing (only present when canvas_state was used) */
340
379
  canvasRenderTiming?: {
341
380
  poolAcquireMs: number;
@@ -361,10 +400,21 @@ interface RealtimeRenderError {
361
400
  code: string;
362
401
  /** Human-readable detail (includes specifics such as the blocked asset URL). */
363
402
  message: string;
403
+ /**
404
+ * Set when the error is about ONE mockup, not the session (the others keep
405
+ * streaming); show it as unavailable. Codes: 'E_MOCKUP_NOT_BLESSED' — the
406
+ * scene failed render parity; 'E_MOCKUP_INELIGIBLE' — no compiled scene
407
+ * can express the request (a colour-only or URL-less placement; `message`
408
+ * carries the reason); 'E_MOCKUP_UNRENDERABLE' — any other typed refusal.
409
+ */
410
+ mockupId?: string;
364
411
  }
365
412
  interface RealtimeMockupState {
366
413
  isConnected: boolean;
367
414
  sessionId: string | null;
415
+ /** Render node that answered the handshake (`connected.box`); null until
416
+ * connected or on servers that don't report it. */
417
+ box: string | null;
368
418
  isConfigured: boolean;
369
419
  mockupResults: MockupResult[];
370
420
  status: string;
@@ -381,7 +431,11 @@ interface RealtimeMockupState {
381
431
  renderError: RealtimeRenderError | null;
382
432
  }
383
433
  interface RealtimeMockupCallbacks {
384
- onConnected?: (sessionId: string) => void;
434
+ /** `info.box` names the render node that answered (undefined on servers
435
+ * that don't report it). */
436
+ onConnected?: (sessionId: string, info: {
437
+ box?: string;
438
+ }) => void;
385
439
  onDisconnected?: () => void;
386
440
  onConfigReceived?: () => void;
387
441
  /** Called when server confirms it received a blob for a placement */
@@ -405,6 +459,7 @@ declare class RealtimeMockupService {
405
459
  private config;
406
460
  private configSent;
407
461
  private sessionId;
462
+ private box;
408
463
  private isConfigured;
409
464
  private mockupResults;
410
465
  private status;
@@ -500,6 +555,13 @@ declare class RealtimeMockupService {
500
555
  * Check if there are pending blobs waiting to be sent (in throttle queue)
501
556
  */
502
557
  hasPendingBlobs(): boolean;
558
+ /**
559
+ * Version stamped on the most recent canvas_state send (0 before any).
560
+ * Every frame answers with `requestVersion`, so a caller can tell which
561
+ * send a frame belongs to — the pipeline-depth send policy counts a send
562
+ * as landed when every mockup of its version has arrived.
563
+ */
564
+ getLastSentVersion(): number;
503
565
  sendColorBlob(placement: string, hexColor: string): boolean;
504
566
  createEmptyCanvasBlob(width?: number, height?: number): Promise<Blob>;
505
567
  sendInitialEmptyCanvases(placements: Array<{
@@ -268,6 +268,22 @@ interface WebSocketConfig {
268
268
  */
269
269
  debugKey?: string;
270
270
  placementSettings?: Record<string, PlacementSettings>;
271
+ /**
272
+ * ADR-0099 (bundle records only): which alternative fills each slot —
273
+ * `role → member product code`. Omitted roles take the slot's first
274
+ * alternative. The server re-validates every config message
275
+ * (`E_BUNDLE_PICK_NOT_FOUND` lists the slot's alternatives); on a
276
+ * single product it is refused (`E_NOT_A_BUNDLE`).
277
+ */
278
+ picks?: Record<string, string>;
279
+ /**
280
+ * ADR-0099 (bundle records only): the variant per slot — `role → gvid`.
281
+ * A bundle session names its variants per ROLE; a bare `variantId` on a
282
+ * bundle is refused by the server (`E_BUNDLE_ROLE_REQUIRED`), so send
283
+ * `variantId: ''` alongside this. On a single product it is refused
284
+ * (`E_NOT_A_BUNDLE`).
285
+ */
286
+ variants?: Record<string, string>;
271
287
  }
272
288
  interface MockupResult {
273
289
  mockupId: string;
@@ -301,6 +317,23 @@ interface MockupResult {
301
317
  serverTiming?: string;
302
318
  /** Server-side canvas render timing breakdown (present when canvas_state was used) */
303
319
  canvasRenderTiming?: any;
320
+ /**
321
+ * Box-window envelope of this frame in Server-Timing grammar — receive →
322
+ * send on the render node: `rt_total`, `rt_guard`, `rt_canvas` (+
323
+ * `rt_canvas_hop`, `canvas_*`), `rt_coalesce` (desc `superseded N`),
324
+ * `rt_composite`, `rt_store`, `rt_deliver` (desc `sz=<bytes> ws|url`),
325
+ * `rt_box`. Present on every frame from a server that emits it — no
326
+ * debug key needed. `clientRoundTripMs − rt_total` is the round-trip
327
+ * transport (browser ↔ edge ↔ box, both directions).
328
+ */
329
+ rtTiming?: string;
330
+ /** Client-observed edit → frame: the canvas_state send this frame answers
331
+ * → this message's arrival, in ms. Undefined when the frame was not
332
+ * triggered by a send from this client (config re-render, replay). */
333
+ clientRoundTripMs?: number;
334
+ /** How the bytes arrived: pushed down the socket ('ws') or via the
335
+ * imageUrl fetch ('url'). */
336
+ imageDelivery?: 'ws' | 'url';
304
337
  }
305
338
  interface WebSocketMessage {
306
339
  type: string;
@@ -336,6 +369,12 @@ interface WebSocketMessage {
336
369
  };
337
370
  /** Raw Server-Timing breakdown (only when the session's debugKey matched) */
338
371
  serverTiming?: string;
372
+ /** Box-window envelope of the frame (see MockupResult.rtTiming) */
373
+ rtTiming?: string;
374
+ /** Render node identity, on `connected` */
375
+ box?: string;
376
+ /** 'ws' when the image bytes were pushed as a mockup_frame before this message */
377
+ imageDelivery?: string;
339
378
  /** Server-side canvas render timing (only present when canvas_state was used) */
340
379
  canvasRenderTiming?: {
341
380
  poolAcquireMs: number;
@@ -361,10 +400,21 @@ interface RealtimeRenderError {
361
400
  code: string;
362
401
  /** Human-readable detail (includes specifics such as the blocked asset URL). */
363
402
  message: string;
403
+ /**
404
+ * Set when the error is about ONE mockup, not the session (the others keep
405
+ * streaming); show it as unavailable. Codes: 'E_MOCKUP_NOT_BLESSED' — the
406
+ * scene failed render parity; 'E_MOCKUP_INELIGIBLE' — no compiled scene
407
+ * can express the request (a colour-only or URL-less placement; `message`
408
+ * carries the reason); 'E_MOCKUP_UNRENDERABLE' — any other typed refusal.
409
+ */
410
+ mockupId?: string;
364
411
  }
365
412
  interface RealtimeMockupState {
366
413
  isConnected: boolean;
367
414
  sessionId: string | null;
415
+ /** Render node that answered the handshake (`connected.box`); null until
416
+ * connected or on servers that don't report it. */
417
+ box: string | null;
368
418
  isConfigured: boolean;
369
419
  mockupResults: MockupResult[];
370
420
  status: string;
@@ -381,7 +431,11 @@ interface RealtimeMockupState {
381
431
  renderError: RealtimeRenderError | null;
382
432
  }
383
433
  interface RealtimeMockupCallbacks {
384
- onConnected?: (sessionId: string) => void;
434
+ /** `info.box` names the render node that answered (undefined on servers
435
+ * that don't report it). */
436
+ onConnected?: (sessionId: string, info: {
437
+ box?: string;
438
+ }) => void;
385
439
  onDisconnected?: () => void;
386
440
  onConfigReceived?: () => void;
387
441
  /** Called when server confirms it received a blob for a placement */
@@ -405,6 +459,7 @@ declare class RealtimeMockupService {
405
459
  private config;
406
460
  private configSent;
407
461
  private sessionId;
462
+ private box;
408
463
  private isConfigured;
409
464
  private mockupResults;
410
465
  private status;
@@ -500,6 +555,13 @@ declare class RealtimeMockupService {
500
555
  * Check if there are pending blobs waiting to be sent (in throttle queue)
501
556
  */
502
557
  hasPendingBlobs(): boolean;
558
+ /**
559
+ * Version stamped on the most recent canvas_state send (0 before any).
560
+ * Every frame answers with `requestVersion`, so a caller can tell which
561
+ * send a frame belongs to — the pipeline-depth send policy counts a send
562
+ * as landed when every mockup of its version has arrived.
563
+ */
564
+ getLastSentVersion(): number;
503
565
  sendColorBlob(placement: string, hexColor: string): boolean;
504
566
  createEmptyCanvasBlob(width?: number, height?: number): Promise<Blob>;
505
567
  sendInitialEmptyCanvases(placements: Array<{
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@snowcone-app/sdk",
3
- "version": "0.20.3",
3
+ "version": "0.24.0",
4
4
  "description": "Snowcone SDK for product mockups and print-on-demand",
5
5
  "keywords": [
6
6
  "merch",
@@ -85,7 +85,7 @@
85
85
  "tsup": "^8.1.0",
86
86
  "typescript": "^5.5.4",
87
87
  "vitest": "^2.0.5",
88
- "@snowcone-app/mockup-url": "0.3.4"
88
+ "@snowcone-app/mockup-url": "0.6.0"
89
89
  },
90
90
  "engines": {
91
91
  "node": ">=18"