@snowcone-app/sdk 0.26.0 → 0.27.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,18 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.27.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#4455](https://github.com/snowcone-app/snowcone-monorepo/pull/4455) [`965c3d6`](https://github.com/snowcone-app/snowcone-monorepo/commit/965c3d647258bf8735bdda6080f27cb42305a406) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Realtime frame flow control. With `config.acks`, the box keeps at most `window` un-acked frames per mockup and sends only the newest when the client falls behind, instead of queueing a backlog behind Cloudflare.
8
+ - **SDK:** `ackFrame(mockupId, seq)` is a cumulative per-mockup ack, batched once per animation frame. The service acks superseded and stale-dropped frames itself, and updates state per frame while acking. `E_RT_ACK_TIMEOUT` and `E_RT_ACK_BAD` are typed faults (`state.acks`, `onAckFault`), never `renderError` or a picture refusal.
9
+ - **UI:** `RealtimeProvider` asks for acks and reports every frame done: drawn (`markBlobShown`), failed (`frameFailed`), not shown, or a dropped or failed composite. A version the box coalesced away settles once each mockup has a newer frame.
10
+ - **Older boxes:** stay unchanged. Acks are dormant until `config_received` carries them.
11
+
12
+ - [#4474](https://github.com/snowcone-app/snowcone-monorepo/pull/4474) [`e41bdc8`](https://github.com/snowcone-app/snowcone-monorepo/commit/e41bdc8293a5b20e199402047d416f17b6e9113e) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Size pictures (`linkedAs: 'size-picture'`, the picture of one size). The product gallery shows exactly one, the chosen size's, last. No "picture for this product / variant" lookup ever returns one.
13
+ - **SDK:** `mockupRole`, `ordinaryMockups` (a branded list), `pictureForVariant`, `primaryMockup` and `gallerySizePicture`. `getVariant`, `resolveMockupId` and `resolvePreviewVariantId` search ordinary mockups only. A size that no ordinary mockup lists gets the product's fallback picture. `linkedAs` is declared in the product schema and the zod schema.
14
+ - **UI:** `CarouselImage.galleryRole`. Slides carry `data-gallery-role` and `data-mockup-id`. A size picture renders on the per-picture URL path (`HeroProductImage mode="static"`, which stamps `data-render-state="static"`). Until the render box resolves the variant per mockup, `RealtimeProvider` leaves size pictures out of the session and never marks one pending.
15
+
3
16
  ## 0.26.0
4
17
 
5
18
  ### Minor Changes
@@ -88,6 +88,12 @@ var RealtimeMockupService = class {
88
88
  pendingFrames = /* @__PURE__ */ new Map();
89
89
  // Last object URL handed out per mockup — revoked when replaced.
90
90
  liveObjectUrls = /* @__PURE__ */ new Map();
91
+ // Frame flow control (negotiated per config): window, acked/newest seq per mockup, acks waiting for the next flush.
92
+ acks = null;
93
+ ackedSeq = /* @__PURE__ */ new Map();
94
+ newestSeq = /* @__PURE__ */ new Map();
95
+ pendingAcks = /* @__PURE__ */ new Map();
96
+ ackFlushScheduled = false;
91
97
  // Live frames a newer frame for the same mockup has replaced (and revoked), newest last, bounded. Lets a consumer
92
98
  // still loading an old frame tell "superseded" from "broken" the moment it fails (isFrameSuperseded).
93
99
  supersededFrameUrls = /* @__PURE__ */ new Set();
@@ -103,6 +109,7 @@ var RealtimeMockupService = class {
103
109
  }
104
110
  getState() {
105
111
  return {
112
+ acks: this.acks ? { ...this.acks } : null,
106
113
  isConnected: this.ws?.readyState === WebSocket.OPEN,
107
114
  sessionId: this.sessionId,
108
115
  box: this.box,
@@ -148,6 +155,10 @@ var RealtimeMockupService = class {
148
155
  this.ws = new WebSocket(url);
149
156
  this.ws.binaryType = "arraybuffer";
150
157
  this.ws.onopen = () => {
158
+ this.acks = null;
159
+ this.ackedSeq.clear();
160
+ this.newestSeq.clear();
161
+ this.pendingAcks.clear();
151
162
  console.log(`[WS] connection OPENED to ${this.wsUrl}`);
152
163
  this.addLog("WebSocket connection opened");
153
164
  this.status = "Connected";
@@ -228,6 +239,16 @@ var RealtimeMockupService = class {
228
239
  break;
229
240
  case "config_received":
230
241
  case "configured":
242
+ if (this.config?.acks && data.acks && typeof data.acks.window === "number") {
243
+ this.acks = {
244
+ window: data.acks.window,
245
+ timeoutMs: typeof data.acks.timeoutMs === "number" ? data.acks.timeoutMs : 0,
246
+ timeouts: this.acks?.timeouts ?? 0,
247
+ badAcks: this.acks?.badAcks ?? 0
248
+ };
249
+ } else {
250
+ this.acks = null;
251
+ }
231
252
  this.isConfigured = true;
232
253
  this.status = "Configured";
233
254
  this.addLog("\u2705 Configuration accepted! You can now send blobs.");
@@ -284,12 +305,20 @@ var RealtimeMockupService = class {
284
305
  if (lastAccepted !== void 0 && responseVersion < lastAccepted) {
285
306
  console.log(`[WS] STALE mockup dropped: v${responseVersion} for "${responsePlacement}" (already displayed: v${lastAccepted}, latest sent: v${this.latestSentVersionByPlacement[responsePlacement]})`);
286
307
  this.addLog(`\u23ED\uFE0F Ignoring stale mockup v${responseVersion} for "${responsePlacement}" (displayed: v${lastAccepted})`);
308
+ if (typeof data.seq === "number") this.ackFrame(data.mockupId, data.seq);
287
309
  break;
288
310
  }
289
311
  this.latestAcceptedVersionByPlacement[responsePlacement] = responseVersion;
290
312
  }
313
+ if (typeof data.seq === "number") {
314
+ const prevSeq = this.newestSeq.get(data.mockupId);
315
+ if (prevSeq !== void 0 && prevSeq < data.seq) this.ackFrame(data.mockupId, prevSeq);
316
+ if (prevSeq === void 0 || prevSeq < data.seq) this.newestSeq.set(data.mockupId, data.seq);
317
+ }
291
318
  const mockupResult = {
292
319
  mockupId: data.mockupId,
320
+ ...typeof data.seq === "number" ? { seq: data.seq } : {},
321
+ ...typeof data.coalesced === "number" ? { coalesced: data.coalesced } : {},
293
322
  imageUrl: data.imageUrl,
294
323
  renderUrl: data.renderUrl || data.imageUrl,
295
324
  imageSize: data.imageSize || 0,
@@ -366,7 +395,23 @@ var RealtimeMockupService = class {
366
395
  this.addLog(`\u26A0\uFE0F all_mockups_rendered message dropped: missing 'mockups' array. Full data keys: [${Object.keys(data).join(", ")}]`);
367
396
  }
368
397
  break;
398
+ case "ack_timeout": {
399
+ if (this.acks) this.acks.timeouts += 1;
400
+ const message = `E_RT_ACK_TIMEOUT: the box waited ${this.acks?.timeoutMs ?? "?"} ms for an ack of ${data.mockupId} seq ${data.seq}; fix: every frame must be acked once drawn, superseded, not shown or failed (ackFrame).`;
401
+ console.error(`[WS] ${message}`);
402
+ this.addLog(`\u23F1\uFE0F ${message}`);
403
+ this.callbacks.onAckFault?.({ code: "E_RT_ACK_TIMEOUT", mockupId: data.mockupId, seq: data.seq, message });
404
+ break;
405
+ }
369
406
  case "error": {
407
+ if (data.code === "E_RT_ACK_BAD") {
408
+ if (this.acks) this.acks.badAcks += 1;
409
+ const message = `E_RT_ACK_BAD (${data.reason ?? "?"}) for ${data.mockupId ?? "?"}: ${data.message ?? ""}`;
410
+ console.error(`[WS] ${message}`);
411
+ this.addLog(`\u274C ${message}`);
412
+ this.callbacks.onAckFault?.({ code: "E_RT_ACK_BAD", mockupId: data.mockupId, reason: data.reason, message });
413
+ break;
414
+ }
370
415
  const errorMessage = data.message || "Unknown error occurred";
371
416
  const renderError = {
372
417
  code: data.code || "render_error",
@@ -800,6 +845,39 @@ ${versionToSend}
800
845
  isFrameSuperseded(url) {
801
846
  return this.supersededFrameUrls.has(url);
802
847
  }
848
+ /**
849
+ * The client is done with frame `seq` of `mockupId`: drawn on screen, superseded, not shown by any element, or
850
+ * failed. Cumulative per mockup. A no-op unless flow control was negotiated (see WebSocketConfig.acks). Acks are
851
+ * batched into one frame_ack message per animation frame.
852
+ */
853
+ ackFrame(mockupId, seq) {
854
+ if (!this.acks || !(seq > 0)) return false;
855
+ if (seq <= (this.ackedSeq.get(mockupId) ?? 0) || seq <= (this.pendingAcks.get(mockupId) ?? 0)) return true;
856
+ this.pendingAcks.set(mockupId, seq);
857
+ if (!this.ackFlushScheduled) {
858
+ this.ackFlushScheduled = true;
859
+ const flush = () => this.flushAcks();
860
+ if (typeof requestAnimationFrame === "function") requestAnimationFrame(flush);
861
+ else setTimeout(flush, 16);
862
+ }
863
+ return true;
864
+ }
865
+ flushAcks() {
866
+ this.ackFlushScheduled = false;
867
+ if (!this.acks || this.pendingAcks.size === 0) {
868
+ this.pendingAcks.clear();
869
+ return;
870
+ }
871
+ if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
872
+ const acks = [...this.pendingAcks].map(([mockupId, seq]) => ({ mockupId, seq }));
873
+ this.pendingAcks.clear();
874
+ acks.forEach(({ mockupId, seq }) => this.ackedSeq.set(mockupId, seq));
875
+ this.ws.send(JSON.stringify(acks.length === 1 ? { type: "frame_ack", ...acks[0] } : { type: "frame_ack", acks }));
876
+ }
877
+ /** Whether frame flow control is active on this session (negotiated with the box for the current config). */
878
+ isAcking() {
879
+ return this.acks !== null;
880
+ }
803
881
  rerender(mockupIds) {
804
882
  if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.config || mockupIds.length === 0) return false;
805
883
  const { requestId, traceparent } = newRenderCorrelation();
package/dist/index.cjs CHANGED
@@ -56,6 +56,7 @@ __export(index_exports, {
56
56
  REALTIME_WS_URL: () => REALTIME_WS_URL,
57
57
  RealtimeMockupService: () => RealtimeMockupService,
58
58
  RenderSession: () => RenderSession,
59
+ SIZE_PICTURE: () => SIZE_PICTURE,
59
60
  SnowconeSdkError: () => SnowconeSdkError,
60
61
  StandardComponents: () => StandardComponents,
61
62
  StandardEvents: () => StandardEvents,
@@ -111,6 +112,7 @@ __export(index_exports, {
111
112
  findVariantForSelection: () => findVariantForSelection,
112
113
  formatPrice: () => formatPrice,
113
114
  formatValidationErrors: () => formatValidationErrors,
115
+ gallerySizePicture: () => gallerySizePicture,
114
116
  getBuyUrl: () => getBuyUrl,
115
117
  getDefaultVariantId: () => getDefaultVariantId,
116
118
  getEffectiveAlignment: () => getEffectiveAlignment,
@@ -132,9 +134,13 @@ __export(index_exports, {
132
134
  isValidTileCount: () => isValidTileCount,
133
135
  listProducts: () => listProducts,
134
136
  mintRealtimeGrant: () => mintRealtimeGrant,
137
+ mockupRole: () => mockupRole,
135
138
  mockupUrl: () => mockupUrl,
136
139
  normalizeChoice: () => normalizeChoice,
140
+ ordinaryMockups: () => ordinaryMockups,
141
+ pictureForVariant: () => pictureForVariant,
137
142
  prepareOptionRenderData: () => prepareOptionRenderData,
143
+ primaryMockup: () => primaryMockup,
138
144
  registerStandardComponents: () => registerStandardComponents,
139
145
  resolveBestCombination: () => resolveBestCombination,
140
146
  resolveMockupId: () => resolveMockupId,
@@ -173,7 +179,13 @@ var CatalogProductSchema = import_zod.z.object({
173
179
  lowestPrice: import_zod.z.number().int().optional(),
174
180
  highestPrice: import_zod.z.number().int().optional(),
175
181
  mockups: import_zod.z.array(
176
- import_zod.z.object({ id: import_zod.z.string(), ar: import_zod.z.number(), gvids: import_zod.z.array(import_zod.z.string()) })
182
+ import_zod.z.object({
183
+ id: import_zod.z.string(),
184
+ ar: import_zod.z.number(),
185
+ gvids: import_zod.z.array(import_zod.z.string()),
186
+ // Kept through a successful parse (zod strips undeclared keys): the PDP shows one size picture, the chosen size's.
187
+ linkedAs: import_zod.z.literal("size-picture").optional()
188
+ })
177
189
  ).optional(),
178
190
  options: import_zod.z.object({
179
191
  selected: import_zod.z.record(import_zod.z.string(), import_zod.z.union([import_zod.z.string(), import_zod.z.number(), import_zod.z.null()])).optional(),
@@ -1065,6 +1077,30 @@ function bffSigner(endpoint = "/api/sign", opts) {
1065
1077
  };
1066
1078
  }
1067
1079
 
1080
+ // src/mockup/mockupRole.ts
1081
+ var SIZE_PICTURE = "size-picture";
1082
+ function mockupRole(m) {
1083
+ return m?.linkedAs === SIZE_PICTURE ? SIZE_PICTURE : "ordinary";
1084
+ }
1085
+ function ordinaryMockups(mockups) {
1086
+ return (mockups ?? []).filter((m) => mockupRole(m) === "ordinary");
1087
+ }
1088
+ function pictureForVariant(mockups, variantId) {
1089
+ const ordinary = ordinaryMockups(mockups);
1090
+ if (variantId) {
1091
+ const listed = ordinary.find((m) => (m.gvids ?? []).includes(variantId));
1092
+ if (listed) return listed;
1093
+ }
1094
+ return ordinary[0] ?? null;
1095
+ }
1096
+ function primaryMockup(mockups) {
1097
+ return ordinaryMockups(mockups)[0] ?? null;
1098
+ }
1099
+ function gallerySizePicture(mockups, selectedVariantId) {
1100
+ if (!selectedVariantId) return null;
1101
+ return (mockups ?? []).find((m) => mockupRole(m) === SIZE_PICTURE && (m.gvids ?? []).includes(selectedVariantId)) ?? null;
1102
+ }
1103
+
1068
1104
  // src/state/optionSelection.ts
1069
1105
  function resolveBestCombination(selection, attributes, combinations) {
1070
1106
  const relevant = Object.fromEntries(
@@ -1914,10 +1950,7 @@ function getVariant(selection, product) {
1914
1950
  const variantId = combination?.variantId;
1915
1951
  let mockupId;
1916
1952
  if (variantId && product.mockups && product.mockups.length > 0) {
1917
- const mockupForVariant = product.mockups.find(
1918
- (m) => m.gvids && m.gvids.includes(variantId)
1919
- );
1920
- mockupId = mockupForVariant?.id || product.mockups[0].id;
1953
+ mockupId = pictureForVariant(product.mockups, variantId)?.id;
1921
1954
  }
1922
1955
  return {
1923
1956
  variantId,
@@ -1956,7 +1989,7 @@ var SIZE_ATTRIBUTE = /^size$/i;
1956
1989
  var NOT_THE_PICTURE = /* @__PURE__ */ new Set(["variantId", "price"]);
1957
1990
  function resolvePreviewVariantId(context, variantId, mockupId) {
1958
1991
  const all = context?.product?.mockups ?? [];
1959
- const mockups = mockupId ? all.filter((m) => m.id === mockupId) : all;
1992
+ const mockups = mockupId ? all.filter((m) => m.id === mockupId) : [...ordinaryMockups(all)];
1960
1993
  const lists = (m, id) => (m.gvids ?? []).includes(id);
1961
1994
  if (mockups.length === 0 || mockups.some((m) => lists(m, variantId))) return variantId;
1962
1995
  const combinations = context?.combinations ?? [];
@@ -1984,15 +2017,7 @@ function resolvePreviewVariantId(context, variantId, mockupId) {
1984
2017
  function resolveMockupId(context, variantId, providedMockupId) {
1985
2018
  if (providedMockupId) return providedMockupId;
1986
2019
  if (context?.product?.mockups?.length) {
1987
- if (variantId) {
1988
- const mockupForVariant = context.product.mockups.find(
1989
- (m) => m.gvids && m.gvids.includes(variantId)
1990
- );
1991
- if (mockupForVariant) {
1992
- return mockupForVariant.id;
1993
- }
1994
- }
1995
- return context.product.mockups[0].id;
2020
+ return pictureForVariant(context.product.mockups, variantId)?.id ?? null;
1996
2021
  }
1997
2022
  return null;
1998
2023
  }
@@ -5118,6 +5143,12 @@ var RealtimeMockupService = class {
5118
5143
  pendingFrames = /* @__PURE__ */ new Map();
5119
5144
  // Last object URL handed out per mockup — revoked when replaced.
5120
5145
  liveObjectUrls = /* @__PURE__ */ new Map();
5146
+ // Frame flow control (negotiated per config): window, acked/newest seq per mockup, acks waiting for the next flush.
5147
+ acks = null;
5148
+ ackedSeq = /* @__PURE__ */ new Map();
5149
+ newestSeq = /* @__PURE__ */ new Map();
5150
+ pendingAcks = /* @__PURE__ */ new Map();
5151
+ ackFlushScheduled = false;
5121
5152
  // Live frames a newer frame for the same mockup has replaced (and revoked), newest last, bounded. Lets a consumer
5122
5153
  // still loading an old frame tell "superseded" from "broken" the moment it fails (isFrameSuperseded).
5123
5154
  supersededFrameUrls = /* @__PURE__ */ new Set();
@@ -5133,6 +5164,7 @@ var RealtimeMockupService = class {
5133
5164
  }
5134
5165
  getState() {
5135
5166
  return {
5167
+ acks: this.acks ? { ...this.acks } : null,
5136
5168
  isConnected: this.ws?.readyState === WebSocket.OPEN,
5137
5169
  sessionId: this.sessionId,
5138
5170
  box: this.box,
@@ -5178,6 +5210,10 @@ var RealtimeMockupService = class {
5178
5210
  this.ws = new WebSocket(url);
5179
5211
  this.ws.binaryType = "arraybuffer";
5180
5212
  this.ws.onopen = () => {
5213
+ this.acks = null;
5214
+ this.ackedSeq.clear();
5215
+ this.newestSeq.clear();
5216
+ this.pendingAcks.clear();
5181
5217
  console.log(`[WS] connection OPENED to ${this.wsUrl}`);
5182
5218
  this.addLog("WebSocket connection opened");
5183
5219
  this.status = "Connected";
@@ -5258,6 +5294,16 @@ var RealtimeMockupService = class {
5258
5294
  break;
5259
5295
  case "config_received":
5260
5296
  case "configured":
5297
+ if (this.config?.acks && data.acks && typeof data.acks.window === "number") {
5298
+ this.acks = {
5299
+ window: data.acks.window,
5300
+ timeoutMs: typeof data.acks.timeoutMs === "number" ? data.acks.timeoutMs : 0,
5301
+ timeouts: this.acks?.timeouts ?? 0,
5302
+ badAcks: this.acks?.badAcks ?? 0
5303
+ };
5304
+ } else {
5305
+ this.acks = null;
5306
+ }
5261
5307
  this.isConfigured = true;
5262
5308
  this.status = "Configured";
5263
5309
  this.addLog("\u2705 Configuration accepted! You can now send blobs.");
@@ -5314,12 +5360,20 @@ var RealtimeMockupService = class {
5314
5360
  if (lastAccepted !== void 0 && responseVersion < lastAccepted) {
5315
5361
  console.log(`[WS] STALE mockup dropped: v${responseVersion} for "${responsePlacement}" (already displayed: v${lastAccepted}, latest sent: v${this.latestSentVersionByPlacement[responsePlacement]})`);
5316
5362
  this.addLog(`\u23ED\uFE0F Ignoring stale mockup v${responseVersion} for "${responsePlacement}" (displayed: v${lastAccepted})`);
5363
+ if (typeof data.seq === "number") this.ackFrame(data.mockupId, data.seq);
5317
5364
  break;
5318
5365
  }
5319
5366
  this.latestAcceptedVersionByPlacement[responsePlacement] = responseVersion;
5320
5367
  }
5368
+ if (typeof data.seq === "number") {
5369
+ const prevSeq = this.newestSeq.get(data.mockupId);
5370
+ if (prevSeq !== void 0 && prevSeq < data.seq) this.ackFrame(data.mockupId, prevSeq);
5371
+ if (prevSeq === void 0 || prevSeq < data.seq) this.newestSeq.set(data.mockupId, data.seq);
5372
+ }
5321
5373
  const mockupResult = {
5322
5374
  mockupId: data.mockupId,
5375
+ ...typeof data.seq === "number" ? { seq: data.seq } : {},
5376
+ ...typeof data.coalesced === "number" ? { coalesced: data.coalesced } : {},
5323
5377
  imageUrl: data.imageUrl,
5324
5378
  renderUrl: data.renderUrl || data.imageUrl,
5325
5379
  imageSize: data.imageSize || 0,
@@ -5396,7 +5450,23 @@ var RealtimeMockupService = class {
5396
5450
  this.addLog(`\u26A0\uFE0F all_mockups_rendered message dropped: missing 'mockups' array. Full data keys: [${Object.keys(data).join(", ")}]`);
5397
5451
  }
5398
5452
  break;
5453
+ case "ack_timeout": {
5454
+ if (this.acks) this.acks.timeouts += 1;
5455
+ const message = `E_RT_ACK_TIMEOUT: the box waited ${this.acks?.timeoutMs ?? "?"} ms for an ack of ${data.mockupId} seq ${data.seq}; fix: every frame must be acked once drawn, superseded, not shown or failed (ackFrame).`;
5456
+ console.error(`[WS] ${message}`);
5457
+ this.addLog(`\u23F1\uFE0F ${message}`);
5458
+ this.callbacks.onAckFault?.({ code: "E_RT_ACK_TIMEOUT", mockupId: data.mockupId, seq: data.seq, message });
5459
+ break;
5460
+ }
5399
5461
  case "error": {
5462
+ if (data.code === "E_RT_ACK_BAD") {
5463
+ if (this.acks) this.acks.badAcks += 1;
5464
+ const message = `E_RT_ACK_BAD (${data.reason ?? "?"}) for ${data.mockupId ?? "?"}: ${data.message ?? ""}`;
5465
+ console.error(`[WS] ${message}`);
5466
+ this.addLog(`\u274C ${message}`);
5467
+ this.callbacks.onAckFault?.({ code: "E_RT_ACK_BAD", mockupId: data.mockupId, reason: data.reason, message });
5468
+ break;
5469
+ }
5400
5470
  const errorMessage = data.message || "Unknown error occurred";
5401
5471
  const renderError = {
5402
5472
  code: data.code || "render_error",
@@ -5830,6 +5900,39 @@ ${versionToSend}
5830
5900
  isFrameSuperseded(url) {
5831
5901
  return this.supersededFrameUrls.has(url);
5832
5902
  }
5903
+ /**
5904
+ * The client is done with frame `seq` of `mockupId`: drawn on screen, superseded, not shown by any element, or
5905
+ * failed. Cumulative per mockup. A no-op unless flow control was negotiated (see WebSocketConfig.acks). Acks are
5906
+ * batched into one frame_ack message per animation frame.
5907
+ */
5908
+ ackFrame(mockupId, seq) {
5909
+ if (!this.acks || !(seq > 0)) return false;
5910
+ if (seq <= (this.ackedSeq.get(mockupId) ?? 0) || seq <= (this.pendingAcks.get(mockupId) ?? 0)) return true;
5911
+ this.pendingAcks.set(mockupId, seq);
5912
+ if (!this.ackFlushScheduled) {
5913
+ this.ackFlushScheduled = true;
5914
+ const flush = () => this.flushAcks();
5915
+ if (typeof requestAnimationFrame === "function") requestAnimationFrame(flush);
5916
+ else setTimeout(flush, 16);
5917
+ }
5918
+ return true;
5919
+ }
5920
+ flushAcks() {
5921
+ this.ackFlushScheduled = false;
5922
+ if (!this.acks || this.pendingAcks.size === 0) {
5923
+ this.pendingAcks.clear();
5924
+ return;
5925
+ }
5926
+ if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
5927
+ const acks = [...this.pendingAcks].map(([mockupId, seq]) => ({ mockupId, seq }));
5928
+ this.pendingAcks.clear();
5929
+ acks.forEach(({ mockupId, seq }) => this.ackedSeq.set(mockupId, seq));
5930
+ this.ws.send(JSON.stringify(acks.length === 1 ? { type: "frame_ack", ...acks[0] } : { type: "frame_ack", acks }));
5931
+ }
5932
+ /** Whether frame flow control is active on this session (negotiated with the box for the current config). */
5933
+ isAcking() {
5934
+ return this.acks !== null;
5935
+ }
5833
5936
  rerender(mockupIds) {
5834
5937
  if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.config || mockupIds.length === 0) return false;
5835
5938
  const { requestId, traceparent } = newRenderCorrelation();
@@ -6555,6 +6658,7 @@ function createClient(config) {
6555
6658
  REALTIME_WS_URL,
6556
6659
  RealtimeMockupService,
6557
6660
  RenderSession,
6661
+ SIZE_PICTURE,
6558
6662
  SnowconeSdkError,
6559
6663
  StandardComponents,
6560
6664
  StandardEvents,
@@ -6610,6 +6714,7 @@ function createClient(config) {
6610
6714
  findVariantForSelection,
6611
6715
  formatPrice,
6612
6716
  formatValidationErrors,
6717
+ gallerySizePicture,
6613
6718
  getBuyUrl,
6614
6719
  getDefaultVariantId,
6615
6720
  getEffectiveAlignment,
@@ -6631,9 +6736,13 @@ function createClient(config) {
6631
6736
  isValidTileCount,
6632
6737
  listProducts,
6633
6738
  mintRealtimeGrant,
6739
+ mockupRole,
6634
6740
  mockupUrl,
6635
6741
  normalizeChoice,
6742
+ ordinaryMockups,
6743
+ pictureForVariant,
6636
6744
  prepareOptionRenderData,
6745
+ primaryMockup,
6637
6746
  registerStandardComponents,
6638
6747
  resolveBestCombination,
6639
6748
  resolveMockupId,
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-CTbhT64Y.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-CTbhT64Y.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-CvN0UU2j.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-CvN0UU2j.cjs';
5
5
 
6
6
  interface CatalogProduct {
7
7
  id: string;
@@ -23,6 +23,10 @@ interface CatalogProduct {
23
23
  picks?: {
24
24
  [k: string]: string;
25
25
  };
26
+ /**
27
+ * What this mockup is on the product page. 'size-picture': the picture of ONE size (its gvids are that size). The gallery shows only the chosen size's one, last; ordinary-picture lookups (a variant's picture, a card) never return it. Absent on ordinary mockups.
28
+ */
29
+ linkedAs?: "size-picture";
26
30
  }[];
27
31
  options?: {
28
32
  selected?: {
@@ -471,6 +475,45 @@ interface BffSignerOptions {
471
475
  }
472
476
  declare function bffSigner(endpoint?: string, opts?: BffSignerOptions): (url: string) => Promise<string>;
473
477
 
478
+ /**
479
+ * What a mockup IS on a product page: an ordinary picture, or the picture of ONE size (`json.linkedAs =
480
+ * 'size-picture'`: its gvids are that size; a hoodie has eight, S..5XL).
481
+ *
482
+ * The rule (lead + Kevin, 2026-11-11): the gallery shows exactly ONE size picture, the chosen size's, last; and no
483
+ * "the picture for this product / this variant" lookup (cards, links, a variant's preview) ever returns a size
484
+ * picture. Every such lookup goes through `pictureForVariant` / `primaryMockup`, which search `ordinaryMockups` only: a
485
+ * branded list, so code that forgot the filter does not type-check where an ordinary list is required.
486
+ */
487
+ declare const SIZE_PICTURE: "size-picture";
488
+ type MockupRole = "ordinary" | typeof SIZE_PICTURE;
489
+ type WithRole = {
490
+ id?: unknown;
491
+ linkedAs?: unknown;
492
+ };
493
+ type WithGvids = {
494
+ id?: string;
495
+ gvids?: string[] | null;
496
+ };
497
+ declare function mockupRole(m: WithRole | null | undefined): MockupRole;
498
+ declare const ORDINARY: unique symbol;
499
+ /** A product's ordinary pictures (never a size picture). Only `ordinaryMockups` makes one. */
500
+ type OrdinaryMockups<T> = readonly T[] & {
501
+ readonly [ORDINARY]: true;
502
+ };
503
+ declare function ordinaryMockups<T extends WithRole>(mockups: readonly T[] | null | undefined): OrdinaryMockups<T>;
504
+ /**
505
+ * The picture for a variant: the first ordinary mockup that lists it, else the product's first ordinary mockup (its
506
+ * fallback picture), else null. Never a size picture, even when a size picture is the only mockup listing the variant.
507
+ */
508
+ declare function pictureForVariant<T extends WithRole & WithGvids>(mockups: readonly T[] | null | undefined, variantId: string | null | undefined): T | null;
509
+ /** The product's picture for cards, links and previews: its first ordinary mockup. Never a size picture. */
510
+ declare function primaryMockup<T extends WithRole>(mockups: readonly T[] | null | undefined): T | null;
511
+ /**
512
+ * The ONE size picture the gallery shows: the size picture whose gvids list the chosen variant, or null (no size
513
+ * pictures, or none for this size: never another size's picture).
514
+ */
515
+ declare function gallerySizePicture<T extends WithRole & WithGvids>(mockups: readonly T[] | null | undefined, selectedVariantId: string | null | undefined): T | null;
516
+
474
517
  /**
475
518
  * Framework-agnostic state management utilities
476
519
  * Provides consistent state management patterns for React and Web Components
@@ -1057,6 +1100,7 @@ declare function getVariant(selection: UserSelection, product: {
1057
1100
  mockups: Array<{
1058
1101
  id: string;
1059
1102
  gvids?: string[];
1103
+ linkedAs?: unknown;
1060
1104
  }>;
1061
1105
  attributes?: Record<string, any>;
1062
1106
  }): {
@@ -3436,4 +3480,4 @@ declare function searchDesigns(query?: string, options?: SearchDesignsOptions):
3436
3480
  */
3437
3481
  declare function createClient(config: SdkConfig): SnowconeClient;
3438
3482
 
3439
- export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogDesign, type CatalogListResponse, type CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, type CreateDesignStateInput, type CreatedDesignState, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_BUY_BASE, DEFAULT_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type DesignLike, type DesignsSearchResponse, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type FailedAsset, type FetchMockupImageOptions, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, type MockupImage, MockupResult, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, PlacementSettings, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, REALTIME_WS_URL, type RateLimitState, type RealtimeGrant, RealtimeMockupService, RealtimeRenderError, type RegularArtwork, type RenderProduct, type RenderProductAttribute, type RenderProductAttributeChoice, type RenderProductCombination, type RenderProductMockup, type RenderProductOptions, type RenderProductRequiredPlacement, RenderSession, type RenderSessionOptions, type RenderState, type SdkConfig, type SeamlessPattern, type SearchDesignsOptions, type SignedUrlResponse, type SnowconeClient, SnowconeSdkError, type SnowconeSdkErrorCode, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, assertVariantSelected, autoRegister, bffSigner, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createDesignState, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, fetchMockupImage, fetchRealtimeGrant, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getBuyUrl, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, imageKindOf, isSelectionComplete, isSnowconeSdkError, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolvePreviewVariantId, resolveVariantId, retryOperation, searchDesigns, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, warnVariantNotSelected, withContext, withErrorHandling, withSyncErrorHandling };
3483
+ export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogDesign, type CatalogListResponse, type CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, type CreateDesignStateInput, type CreatedDesignState, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_BUY_BASE, DEFAULT_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type DesignLike, type DesignsSearchResponse, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type FailedAsset, type FetchMockupImageOptions, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, type MockupImage, MockupResult, type MockupRole, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type OrdinaryMockups, type Placement, type PlacementDesign, PlacementSettings, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, REALTIME_WS_URL, type RateLimitState, type RealtimeGrant, RealtimeMockupService, RealtimeRenderError, type RegularArtwork, type RenderProduct, type RenderProductAttribute, type RenderProductAttributeChoice, type RenderProductCombination, type RenderProductMockup, type RenderProductOptions, type RenderProductRequiredPlacement, RenderSession, type RenderSessionOptions, type RenderState, SIZE_PICTURE, type SdkConfig, type SeamlessPattern, type SearchDesignsOptions, type SignedUrlResponse, type SnowconeClient, SnowconeSdkError, type SnowconeSdkErrorCode, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, assertVariantSelected, autoRegister, bffSigner, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createDesignState, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, fetchMockupImage, fetchRealtimeGrant, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, gallerySizePicture, getBuyUrl, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, imageKindOf, isSelectionComplete, isSnowconeSdkError, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mockupRole, mockupUrl, normalizeChoice, ordinaryMockups, pictureForVariant, prepareOptionRenderData, primaryMockup, registerStandardComponents, resolveMockupId, resolvePreviewVariantId, resolveVariantId, retryOperation, searchDesigns, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, warnVariantNotSelected, withContext, withErrorHandling, withSyncErrorHandling };
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-CTbhT64Y.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-CTbhT64Y.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-CvN0UU2j.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-CvN0UU2j.js';
5
5
 
6
6
  interface CatalogProduct {
7
7
  id: string;
@@ -23,6 +23,10 @@ interface CatalogProduct {
23
23
  picks?: {
24
24
  [k: string]: string;
25
25
  };
26
+ /**
27
+ * What this mockup is on the product page. 'size-picture': the picture of ONE size (its gvids are that size). The gallery shows only the chosen size's one, last; ordinary-picture lookups (a variant's picture, a card) never return it. Absent on ordinary mockups.
28
+ */
29
+ linkedAs?: "size-picture";
26
30
  }[];
27
31
  options?: {
28
32
  selected?: {
@@ -471,6 +475,45 @@ interface BffSignerOptions {
471
475
  }
472
476
  declare function bffSigner(endpoint?: string, opts?: BffSignerOptions): (url: string) => Promise<string>;
473
477
 
478
+ /**
479
+ * What a mockup IS on a product page: an ordinary picture, or the picture of ONE size (`json.linkedAs =
480
+ * 'size-picture'`: its gvids are that size; a hoodie has eight, S..5XL).
481
+ *
482
+ * The rule (lead + Kevin, 2026-11-11): the gallery shows exactly ONE size picture, the chosen size's, last; and no
483
+ * "the picture for this product / this variant" lookup (cards, links, a variant's preview) ever returns a size
484
+ * picture. Every such lookup goes through `pictureForVariant` / `primaryMockup`, which search `ordinaryMockups` only: a
485
+ * branded list, so code that forgot the filter does not type-check where an ordinary list is required.
486
+ */
487
+ declare const SIZE_PICTURE: "size-picture";
488
+ type MockupRole = "ordinary" | typeof SIZE_PICTURE;
489
+ type WithRole = {
490
+ id?: unknown;
491
+ linkedAs?: unknown;
492
+ };
493
+ type WithGvids = {
494
+ id?: string;
495
+ gvids?: string[] | null;
496
+ };
497
+ declare function mockupRole(m: WithRole | null | undefined): MockupRole;
498
+ declare const ORDINARY: unique symbol;
499
+ /** A product's ordinary pictures (never a size picture). Only `ordinaryMockups` makes one. */
500
+ type OrdinaryMockups<T> = readonly T[] & {
501
+ readonly [ORDINARY]: true;
502
+ };
503
+ declare function ordinaryMockups<T extends WithRole>(mockups: readonly T[] | null | undefined): OrdinaryMockups<T>;
504
+ /**
505
+ * The picture for a variant: the first ordinary mockup that lists it, else the product's first ordinary mockup (its
506
+ * fallback picture), else null. Never a size picture, even when a size picture is the only mockup listing the variant.
507
+ */
508
+ declare function pictureForVariant<T extends WithRole & WithGvids>(mockups: readonly T[] | null | undefined, variantId: string | null | undefined): T | null;
509
+ /** The product's picture for cards, links and previews: its first ordinary mockup. Never a size picture. */
510
+ declare function primaryMockup<T extends WithRole>(mockups: readonly T[] | null | undefined): T | null;
511
+ /**
512
+ * The ONE size picture the gallery shows: the size picture whose gvids list the chosen variant, or null (no size
513
+ * pictures, or none for this size: never another size's picture).
514
+ */
515
+ declare function gallerySizePicture<T extends WithRole & WithGvids>(mockups: readonly T[] | null | undefined, selectedVariantId: string | null | undefined): T | null;
516
+
474
517
  /**
475
518
  * Framework-agnostic state management utilities
476
519
  * Provides consistent state management patterns for React and Web Components
@@ -1057,6 +1100,7 @@ declare function getVariant(selection: UserSelection, product: {
1057
1100
  mockups: Array<{
1058
1101
  id: string;
1059
1102
  gvids?: string[];
1103
+ linkedAs?: unknown;
1060
1104
  }>;
1061
1105
  attributes?: Record<string, any>;
1062
1106
  }): {
@@ -3436,4 +3480,4 @@ declare function searchDesigns(query?: string, options?: SearchDesignsOptions):
3436
3480
  */
3437
3481
  declare function createClient(config: SdkConfig): SnowconeClient;
3438
3482
 
3439
- export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogDesign, type CatalogListResponse, type CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, type CreateDesignStateInput, type CreatedDesignState, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_BUY_BASE, DEFAULT_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type DesignLike, type DesignsSearchResponse, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type FailedAsset, type FetchMockupImageOptions, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, type MockupImage, MockupResult, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, PlacementSettings, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, REALTIME_WS_URL, type RateLimitState, type RealtimeGrant, RealtimeMockupService, RealtimeRenderError, type RegularArtwork, type RenderProduct, type RenderProductAttribute, type RenderProductAttributeChoice, type RenderProductCombination, type RenderProductMockup, type RenderProductOptions, type RenderProductRequiredPlacement, RenderSession, type RenderSessionOptions, type RenderState, type SdkConfig, type SeamlessPattern, type SearchDesignsOptions, type SignedUrlResponse, type SnowconeClient, SnowconeSdkError, type SnowconeSdkErrorCode, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, assertVariantSelected, autoRegister, bffSigner, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createDesignState, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, fetchMockupImage, fetchRealtimeGrant, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getBuyUrl, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, imageKindOf, isSelectionComplete, isSnowconeSdkError, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolvePreviewVariantId, resolveVariantId, retryOperation, searchDesigns, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, warnVariantNotSelected, withContext, withErrorHandling, withSyncErrorHandling };
3483
+ export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogDesign, type CatalogListResponse, type CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, type CreateDesignStateInput, type CreatedDesignState, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_BUY_BASE, DEFAULT_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type DesignLike, type DesignsSearchResponse, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type FailedAsset, type FetchMockupImageOptions, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, type MockupImage, MockupResult, type MockupRole, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type OrdinaryMockups, type Placement, type PlacementDesign, PlacementSettings, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, REALTIME_WS_URL, type RateLimitState, type RealtimeGrant, RealtimeMockupService, RealtimeRenderError, type RegularArtwork, type RenderProduct, type RenderProductAttribute, type RenderProductAttributeChoice, type RenderProductCombination, type RenderProductMockup, type RenderProductOptions, type RenderProductRequiredPlacement, RenderSession, type RenderSessionOptions, type RenderState, SIZE_PICTURE, type SdkConfig, type SeamlessPattern, type SearchDesignsOptions, type SignedUrlResponse, type SnowconeClient, SnowconeSdkError, type SnowconeSdkErrorCode, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, assertVariantSelected, autoRegister, bffSigner, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createDesignState, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, fetchMockupImage, fetchRealtimeGrant, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, gallerySizePicture, getBuyUrl, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, imageKindOf, isSelectionComplete, isSnowconeSdkError, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mockupRole, mockupUrl, normalizeChoice, ordinaryMockups, pictureForVariant, prepareOptionRenderData, primaryMockup, registerStandardComponents, resolveMockupId, resolvePreviewVariantId, resolveVariantId, retryOperation, searchDesigns, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, warnVariantNotSelected, withContext, withErrorHandling, withSyncErrorHandling };
package/dist/index.js CHANGED
@@ -4,7 +4,7 @@ import {
4
4
  import {
5
5
  REALTIME_WS_URL,
6
6
  RealtimeMockupService
7
- } from "./chunk-4NCMFK5L.js";
7
+ } from "./chunk-IW7DXXGY.js";
8
8
  import {
9
9
  buildMockupUrl,
10
10
  buildPublicMockupUrl,
@@ -24,7 +24,13 @@ var CatalogProductSchema = z.object({
24
24
  lowestPrice: z.number().int().optional(),
25
25
  highestPrice: z.number().int().optional(),
26
26
  mockups: z.array(
27
- z.object({ id: z.string(), ar: z.number(), gvids: z.array(z.string()) })
27
+ z.object({
28
+ id: z.string(),
29
+ ar: z.number(),
30
+ gvids: z.array(z.string()),
31
+ // Kept through a successful parse (zod strips undeclared keys): the PDP shows one size picture, the chosen size's.
32
+ linkedAs: z.literal("size-picture").optional()
33
+ })
28
34
  ).optional(),
29
35
  options: z.object({
30
36
  selected: z.record(z.string(), z.union([z.string(), z.number(), z.null()])).optional(),
@@ -629,6 +635,30 @@ function bffSigner(endpoint = "/api/sign", opts) {
629
635
  };
630
636
  }
631
637
 
638
+ // src/mockup/mockupRole.ts
639
+ var SIZE_PICTURE = "size-picture";
640
+ function mockupRole(m) {
641
+ return m?.linkedAs === SIZE_PICTURE ? SIZE_PICTURE : "ordinary";
642
+ }
643
+ function ordinaryMockups(mockups) {
644
+ return (mockups ?? []).filter((m) => mockupRole(m) === "ordinary");
645
+ }
646
+ function pictureForVariant(mockups, variantId) {
647
+ const ordinary = ordinaryMockups(mockups);
648
+ if (variantId) {
649
+ const listed = ordinary.find((m) => (m.gvids ?? []).includes(variantId));
650
+ if (listed) return listed;
651
+ }
652
+ return ordinary[0] ?? null;
653
+ }
654
+ function primaryMockup(mockups) {
655
+ return ordinaryMockups(mockups)[0] ?? null;
656
+ }
657
+ function gallerySizePicture(mockups, selectedVariantId) {
658
+ if (!selectedVariantId) return null;
659
+ return (mockups ?? []).find((m) => mockupRole(m) === SIZE_PICTURE && (m.gvids ?? []).includes(selectedVariantId)) ?? null;
660
+ }
661
+
632
662
  // src/state/optionSelection.ts
633
663
  function resolveBestCombination(selection, attributes, combinations) {
634
664
  const relevant = Object.fromEntries(
@@ -1478,10 +1508,7 @@ function getVariant(selection, product) {
1478
1508
  const variantId = combination?.variantId;
1479
1509
  let mockupId;
1480
1510
  if (variantId && product.mockups && product.mockups.length > 0) {
1481
- const mockupForVariant = product.mockups.find(
1482
- (m) => m.gvids && m.gvids.includes(variantId)
1483
- );
1484
- mockupId = mockupForVariant?.id || product.mockups[0].id;
1511
+ mockupId = pictureForVariant(product.mockups, variantId)?.id;
1485
1512
  }
1486
1513
  return {
1487
1514
  variantId,
@@ -1520,7 +1547,7 @@ var SIZE_ATTRIBUTE = /^size$/i;
1520
1547
  var NOT_THE_PICTURE = /* @__PURE__ */ new Set(["variantId", "price"]);
1521
1548
  function resolvePreviewVariantId(context, variantId, mockupId) {
1522
1549
  const all = context?.product?.mockups ?? [];
1523
- const mockups = mockupId ? all.filter((m) => m.id === mockupId) : all;
1550
+ const mockups = mockupId ? all.filter((m) => m.id === mockupId) : [...ordinaryMockups(all)];
1524
1551
  const lists = (m, id) => (m.gvids ?? []).includes(id);
1525
1552
  if (mockups.length === 0 || mockups.some((m) => lists(m, variantId))) return variantId;
1526
1553
  const combinations = context?.combinations ?? [];
@@ -1548,15 +1575,7 @@ function resolvePreviewVariantId(context, variantId, mockupId) {
1548
1575
  function resolveMockupId(context, variantId, providedMockupId) {
1549
1576
  if (providedMockupId) return providedMockupId;
1550
1577
  if (context?.product?.mockups?.length) {
1551
- if (variantId) {
1552
- const mockupForVariant = context.product.mockups.find(
1553
- (m) => m.gvids && m.gvids.includes(variantId)
1554
- );
1555
- if (mockupForVariant) {
1556
- return mockupForVariant.id;
1557
- }
1558
- }
1559
- return context.product.mockups[0].id;
1578
+ return pictureForVariant(context.product.mockups, variantId)?.id ?? null;
1560
1579
  }
1561
1580
  return null;
1562
1581
  }
@@ -5211,6 +5230,7 @@ export {
5211
5230
  REALTIME_WS_URL,
5212
5231
  RealtimeMockupService,
5213
5232
  RenderSession,
5233
+ SIZE_PICTURE,
5214
5234
  SnowconeSdkError,
5215
5235
  StandardComponents,
5216
5236
  StandardEvents,
@@ -5266,6 +5286,7 @@ export {
5266
5286
  findVariantForSelection,
5267
5287
  formatPrice,
5268
5288
  formatValidationErrors,
5289
+ gallerySizePicture,
5269
5290
  getBuyUrl,
5270
5291
  getDefaultVariantId,
5271
5292
  getEffectiveAlignment,
@@ -5287,9 +5308,13 @@ export {
5287
5308
  isValidTileCount,
5288
5309
  listProducts,
5289
5310
  mintRealtimeGrant,
5311
+ mockupRole,
5290
5312
  mockupUrl,
5291
5313
  normalizeChoice,
5314
+ ordinaryMockups,
5315
+ pictureForVariant,
5292
5316
  prepareOptionRenderData,
5317
+ primaryMockup,
5293
5318
  registerStandardComponents,
5294
5319
  resolveBestCombination,
5295
5320
  resolveMockupId,
package/dist/react.cjs CHANGED
@@ -122,6 +122,12 @@ var RealtimeMockupService = class {
122
122
  pendingFrames = /* @__PURE__ */ new Map();
123
123
  // Last object URL handed out per mockup — revoked when replaced.
124
124
  liveObjectUrls = /* @__PURE__ */ new Map();
125
+ // Frame flow control (negotiated per config): window, acked/newest seq per mockup, acks waiting for the next flush.
126
+ acks = null;
127
+ ackedSeq = /* @__PURE__ */ new Map();
128
+ newestSeq = /* @__PURE__ */ new Map();
129
+ pendingAcks = /* @__PURE__ */ new Map();
130
+ ackFlushScheduled = false;
125
131
  // Live frames a newer frame for the same mockup has replaced (and revoked), newest last, bounded. Lets a consumer
126
132
  // still loading an old frame tell "superseded" from "broken" the moment it fails (isFrameSuperseded).
127
133
  supersededFrameUrls = /* @__PURE__ */ new Set();
@@ -137,6 +143,7 @@ var RealtimeMockupService = class {
137
143
  }
138
144
  getState() {
139
145
  return {
146
+ acks: this.acks ? { ...this.acks } : null,
140
147
  isConnected: this.ws?.readyState === WebSocket.OPEN,
141
148
  sessionId: this.sessionId,
142
149
  box: this.box,
@@ -182,6 +189,10 @@ var RealtimeMockupService = class {
182
189
  this.ws = new WebSocket(url);
183
190
  this.ws.binaryType = "arraybuffer";
184
191
  this.ws.onopen = () => {
192
+ this.acks = null;
193
+ this.ackedSeq.clear();
194
+ this.newestSeq.clear();
195
+ this.pendingAcks.clear();
185
196
  console.log(`[WS] connection OPENED to ${this.wsUrl}`);
186
197
  this.addLog("WebSocket connection opened");
187
198
  this.status = "Connected";
@@ -262,6 +273,16 @@ var RealtimeMockupService = class {
262
273
  break;
263
274
  case "config_received":
264
275
  case "configured":
276
+ if (this.config?.acks && data.acks && typeof data.acks.window === "number") {
277
+ this.acks = {
278
+ window: data.acks.window,
279
+ timeoutMs: typeof data.acks.timeoutMs === "number" ? data.acks.timeoutMs : 0,
280
+ timeouts: this.acks?.timeouts ?? 0,
281
+ badAcks: this.acks?.badAcks ?? 0
282
+ };
283
+ } else {
284
+ this.acks = null;
285
+ }
265
286
  this.isConfigured = true;
266
287
  this.status = "Configured";
267
288
  this.addLog("\u2705 Configuration accepted! You can now send blobs.");
@@ -318,12 +339,20 @@ var RealtimeMockupService = class {
318
339
  if (lastAccepted !== void 0 && responseVersion < lastAccepted) {
319
340
  console.log(`[WS] STALE mockup dropped: v${responseVersion} for "${responsePlacement}" (already displayed: v${lastAccepted}, latest sent: v${this.latestSentVersionByPlacement[responsePlacement]})`);
320
341
  this.addLog(`\u23ED\uFE0F Ignoring stale mockup v${responseVersion} for "${responsePlacement}" (displayed: v${lastAccepted})`);
342
+ if (typeof data.seq === "number") this.ackFrame(data.mockupId, data.seq);
321
343
  break;
322
344
  }
323
345
  this.latestAcceptedVersionByPlacement[responsePlacement] = responseVersion;
324
346
  }
347
+ if (typeof data.seq === "number") {
348
+ const prevSeq = this.newestSeq.get(data.mockupId);
349
+ if (prevSeq !== void 0 && prevSeq < data.seq) this.ackFrame(data.mockupId, prevSeq);
350
+ if (prevSeq === void 0 || prevSeq < data.seq) this.newestSeq.set(data.mockupId, data.seq);
351
+ }
325
352
  const mockupResult = {
326
353
  mockupId: data.mockupId,
354
+ ...typeof data.seq === "number" ? { seq: data.seq } : {},
355
+ ...typeof data.coalesced === "number" ? { coalesced: data.coalesced } : {},
327
356
  imageUrl: data.imageUrl,
328
357
  renderUrl: data.renderUrl || data.imageUrl,
329
358
  imageSize: data.imageSize || 0,
@@ -400,7 +429,23 @@ var RealtimeMockupService = class {
400
429
  this.addLog(`\u26A0\uFE0F all_mockups_rendered message dropped: missing 'mockups' array. Full data keys: [${Object.keys(data).join(", ")}]`);
401
430
  }
402
431
  break;
432
+ case "ack_timeout": {
433
+ if (this.acks) this.acks.timeouts += 1;
434
+ const message = `E_RT_ACK_TIMEOUT: the box waited ${this.acks?.timeoutMs ?? "?"} ms for an ack of ${data.mockupId} seq ${data.seq}; fix: every frame must be acked once drawn, superseded, not shown or failed (ackFrame).`;
435
+ console.error(`[WS] ${message}`);
436
+ this.addLog(`\u23F1\uFE0F ${message}`);
437
+ this.callbacks.onAckFault?.({ code: "E_RT_ACK_TIMEOUT", mockupId: data.mockupId, seq: data.seq, message });
438
+ break;
439
+ }
403
440
  case "error": {
441
+ if (data.code === "E_RT_ACK_BAD") {
442
+ if (this.acks) this.acks.badAcks += 1;
443
+ const message = `E_RT_ACK_BAD (${data.reason ?? "?"}) for ${data.mockupId ?? "?"}: ${data.message ?? ""}`;
444
+ console.error(`[WS] ${message}`);
445
+ this.addLog(`\u274C ${message}`);
446
+ this.callbacks.onAckFault?.({ code: "E_RT_ACK_BAD", mockupId: data.mockupId, reason: data.reason, message });
447
+ break;
448
+ }
404
449
  const errorMessage = data.message || "Unknown error occurred";
405
450
  const renderError = {
406
451
  code: data.code || "render_error",
@@ -834,6 +879,39 @@ ${versionToSend}
834
879
  isFrameSuperseded(url) {
835
880
  return this.supersededFrameUrls.has(url);
836
881
  }
882
+ /**
883
+ * The client is done with frame `seq` of `mockupId`: drawn on screen, superseded, not shown by any element, or
884
+ * failed. Cumulative per mockup. A no-op unless flow control was negotiated (see WebSocketConfig.acks). Acks are
885
+ * batched into one frame_ack message per animation frame.
886
+ */
887
+ ackFrame(mockupId, seq) {
888
+ if (!this.acks || !(seq > 0)) return false;
889
+ if (seq <= (this.ackedSeq.get(mockupId) ?? 0) || seq <= (this.pendingAcks.get(mockupId) ?? 0)) return true;
890
+ this.pendingAcks.set(mockupId, seq);
891
+ if (!this.ackFlushScheduled) {
892
+ this.ackFlushScheduled = true;
893
+ const flush = () => this.flushAcks();
894
+ if (typeof requestAnimationFrame === "function") requestAnimationFrame(flush);
895
+ else setTimeout(flush, 16);
896
+ }
897
+ return true;
898
+ }
899
+ flushAcks() {
900
+ this.ackFlushScheduled = false;
901
+ if (!this.acks || this.pendingAcks.size === 0) {
902
+ this.pendingAcks.clear();
903
+ return;
904
+ }
905
+ if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
906
+ const acks = [...this.pendingAcks].map(([mockupId, seq]) => ({ mockupId, seq }));
907
+ this.pendingAcks.clear();
908
+ acks.forEach(({ mockupId, seq }) => this.ackedSeq.set(mockupId, seq));
909
+ this.ws.send(JSON.stringify(acks.length === 1 ? { type: "frame_ack", ...acks[0] } : { type: "frame_ack", acks }));
910
+ }
911
+ /** Whether frame flow control is active on this session (negotiated with the box for the current config). */
912
+ isAcking() {
913
+ return this.acks !== null;
914
+ }
837
915
  rerender(mockupIds) {
838
916
  if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.config || mockupIds.length === 0) return false;
839
917
  const { requestId, traceparent } = newRenderCorrelation();
@@ -944,9 +1022,11 @@ var DEFAULT_REALTIME_WS_URL = "wss://cdn.snowcone.app/realtime";
944
1022
  function useRealtimeMockup(options = {}) {
945
1023
  const wsUrl = options.wsUrl ?? (options.getToken ? DEFAULT_REALTIME_WS_URL : void 0);
946
1024
  const serviceRef = (0, import_react.useRef)(null);
1025
+ const stateFrameScheduledRef = (0, import_react.useRef)(false);
947
1026
  const getTokenRef = (0, import_react.useRef)(options.getToken);
948
1027
  getTokenRef.current = options.getToken;
949
1028
  const [state, setState] = (0, import_react.useState)({
1029
+ acks: null,
950
1030
  isConnected: false,
951
1031
  sessionId: null,
952
1032
  box: null,
@@ -980,7 +1060,15 @@ function useRealtimeMockup(options = {}) {
980
1060
  options.onBlobSent?.(placement);
981
1061
  },
982
1062
  onMockupRendered: (result) => {
983
- console.log(`[useRealtimeMockup] onMockupRendered: mockupId=${result.mockupId} hasImageUrl=${!!result.imageUrl}`);
1063
+ if (service.isAcking() && !stateFrameScheduledRef.current) {
1064
+ stateFrameScheduledRef.current = true;
1065
+ const apply = () => {
1066
+ stateFrameScheduledRef.current = false;
1067
+ setState(service.getState());
1068
+ };
1069
+ if (typeof requestAnimationFrame === "function") requestAnimationFrame(apply);
1070
+ else setTimeout(apply, 16);
1071
+ }
984
1072
  options.onMockupRendered?.(result);
985
1073
  },
986
1074
  onAllMockupsRendered: (results) => {
@@ -989,6 +1077,10 @@ function useRealtimeMockup(options = {}) {
989
1077
  setState(newState);
990
1078
  options.onAllMockupsRendered?.(results);
991
1079
  },
1080
+ onAckFault: (fault) => {
1081
+ setState(service.getState());
1082
+ options.onAckFault?.(fault);
1083
+ },
992
1084
  onError: (error, detail) => {
993
1085
  setState(service.getState());
994
1086
  options.onError?.(error, detail);
@@ -1062,6 +1154,9 @@ function useRealtimeMockup(options = {}) {
1062
1154
  const isFrameSuperseded = (0, import_react.useCallback)((url) => {
1063
1155
  return serviceRef.current?.isFrameSuperseded(url) ?? false;
1064
1156
  }, []);
1157
+ const ackFrame = (0, import_react.useCallback)((mockupId, seq) => {
1158
+ return serviceRef.current?.ackFrame(mockupId, seq) ?? false;
1159
+ }, []);
1065
1160
  const getLastSentVersion = (0, import_react.useCallback)(() => {
1066
1161
  return serviceRef.current?.getLastSentVersion() ?? 0;
1067
1162
  }, []);
@@ -1086,7 +1181,8 @@ function useRealtimeMockup(options = {}) {
1086
1181
  getLastSentVersion,
1087
1182
  getLatestSentVersions,
1088
1183
  rerender,
1089
- isFrameSuperseded
1184
+ isFrameSuperseded,
1185
+ ackFrame
1090
1186
  };
1091
1187
  }
1092
1188
 
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-CTbhT64Y.cjs';
1
+ import { M as MockupResult, R as RealtimeRenderError, j as RealtimeMockupCallbacks, W as WebSocketConfig, P as PlacementSettings, w as RealtimeAcksState, 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-CvN0UU2j.cjs';
2
2
  import { CSSProperties, ReactNode } from 'react';
3
3
 
4
4
  interface UseRealtimeMockupOptions {
@@ -31,6 +31,8 @@ interface UseRealtimeMockupOptions {
31
31
  * stale mockup) instead of only logging it.
32
32
  */
33
33
  onError?: (error: string, detail: RealtimeRenderError) => void;
34
+ /** Flow-control fault (E_RT_ACK_TIMEOUT / E_RT_ACK_BAD): never a picture refusal; see RealtimeMockupCallbacks. */
35
+ onAckFault?: RealtimeMockupCallbacks['onAckFault'];
34
36
  }
35
37
  declare function useRealtimeMockup(options?: UseRealtimeMockupOptions): {
36
38
  connect: () => void;
@@ -57,6 +59,8 @@ declare function useRealtimeMockup(options?: UseRealtimeMockupOptions): {
57
59
  getLatestSentVersions: () => Record<string, number>;
58
60
  rerender: (mockupIds: string[]) => boolean;
59
61
  isFrameSuperseded: (url: string) => boolean;
62
+ ackFrame: (mockupId: string, seq: number) => boolean;
63
+ acks: RealtimeAcksState | null;
60
64
  isConnected: boolean;
61
65
  sessionId: string | null;
62
66
  box: string | null;
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-CTbhT64Y.js';
1
+ import { M as MockupResult, R as RealtimeRenderError, j as RealtimeMockupCallbacks, W as WebSocketConfig, P as PlacementSettings, w as RealtimeAcksState, 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-CvN0UU2j.js';
2
2
  import { CSSProperties, ReactNode } from 'react';
3
3
 
4
4
  interface UseRealtimeMockupOptions {
@@ -31,6 +31,8 @@ interface UseRealtimeMockupOptions {
31
31
  * stale mockup) instead of only logging it.
32
32
  */
33
33
  onError?: (error: string, detail: RealtimeRenderError) => void;
34
+ /** Flow-control fault (E_RT_ACK_TIMEOUT / E_RT_ACK_BAD): never a picture refusal; see RealtimeMockupCallbacks. */
35
+ onAckFault?: RealtimeMockupCallbacks['onAckFault'];
34
36
  }
35
37
  declare function useRealtimeMockup(options?: UseRealtimeMockupOptions): {
36
38
  connect: () => void;
@@ -57,6 +59,8 @@ declare function useRealtimeMockup(options?: UseRealtimeMockupOptions): {
57
59
  getLatestSentVersions: () => Record<string, number>;
58
60
  rerender: (mockupIds: string[]) => boolean;
59
61
  isFrameSuperseded: (url: string) => boolean;
62
+ ackFrame: (mockupId: string, seq: number) => boolean;
63
+ acks: RealtimeAcksState | null;
60
64
  isConnected: boolean;
61
65
  sessionId: string | null;
62
66
  box: string | null;
package/dist/react.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import {
2
2
  RealtimeMockupService
3
- } from "./chunk-4NCMFK5L.js";
3
+ } from "./chunk-IW7DXXGY.js";
4
4
 
5
5
  // src/realtime/react.ts
6
6
  import { useCallback, useEffect, useRef, useState } from "react";
@@ -8,9 +8,11 @@ var DEFAULT_REALTIME_WS_URL = "wss://cdn.snowcone.app/realtime";
8
8
  function useRealtimeMockup(options = {}) {
9
9
  const wsUrl = options.wsUrl ?? (options.getToken ? DEFAULT_REALTIME_WS_URL : void 0);
10
10
  const serviceRef = useRef(null);
11
+ const stateFrameScheduledRef = useRef(false);
11
12
  const getTokenRef = useRef(options.getToken);
12
13
  getTokenRef.current = options.getToken;
13
14
  const [state, setState] = useState({
15
+ acks: null,
14
16
  isConnected: false,
15
17
  sessionId: null,
16
18
  box: null,
@@ -44,7 +46,15 @@ function useRealtimeMockup(options = {}) {
44
46
  options.onBlobSent?.(placement);
45
47
  },
46
48
  onMockupRendered: (result) => {
47
- console.log(`[useRealtimeMockup] onMockupRendered: mockupId=${result.mockupId} hasImageUrl=${!!result.imageUrl}`);
49
+ if (service.isAcking() && !stateFrameScheduledRef.current) {
50
+ stateFrameScheduledRef.current = true;
51
+ const apply = () => {
52
+ stateFrameScheduledRef.current = false;
53
+ setState(service.getState());
54
+ };
55
+ if (typeof requestAnimationFrame === "function") requestAnimationFrame(apply);
56
+ else setTimeout(apply, 16);
57
+ }
48
58
  options.onMockupRendered?.(result);
49
59
  },
50
60
  onAllMockupsRendered: (results) => {
@@ -53,6 +63,10 @@ function useRealtimeMockup(options = {}) {
53
63
  setState(newState);
54
64
  options.onAllMockupsRendered?.(results);
55
65
  },
66
+ onAckFault: (fault) => {
67
+ setState(service.getState());
68
+ options.onAckFault?.(fault);
69
+ },
56
70
  onError: (error, detail) => {
57
71
  setState(service.getState());
58
72
  options.onError?.(error, detail);
@@ -126,6 +140,9 @@ function useRealtimeMockup(options = {}) {
126
140
  const isFrameSuperseded = useCallback((url) => {
127
141
  return serviceRef.current?.isFrameSuperseded(url) ?? false;
128
142
  }, []);
143
+ const ackFrame = useCallback((mockupId, seq) => {
144
+ return serviceRef.current?.ackFrame(mockupId, seq) ?? false;
145
+ }, []);
129
146
  const getLastSentVersion = useCallback(() => {
130
147
  return serviceRef.current?.getLastSentVersion() ?? 0;
131
148
  }, []);
@@ -150,7 +167,8 @@ function useRealtimeMockup(options = {}) {
150
167
  getLastSentVersion,
151
168
  getLatestSentVersions,
152
169
  rerender,
153
- isFrameSuperseded
170
+ isFrameSuperseded,
171
+ ackFrame
154
172
  };
155
173
  }
156
174
 
@@ -211,6 +211,14 @@ interface PlacementSettings {
211
211
  }
212
212
  interface WebSocketConfig {
213
213
  productId: string;
214
+ /**
215
+ * Ask the box for frame flow control: it keeps at most `window` un-acked frames per mockup and coalesces the rest
216
+ * (latest wins), so a slow link or a slow screen never queues a backlog behind Cloudflare. ONLY for a client that
217
+ * calls {@link RealtimeMockupService.ackFrame} when it has drawn a frame: every frame must be acked (the service
218
+ * acks superseded and stale-dropped frames itself). Dormant on a box that does not negotiate it (config_received
219
+ * without `acks`).
220
+ */
221
+ acks?: boolean;
214
222
  mockupIds: string[];
215
223
  variantId: string;
216
224
  shop: string;
@@ -311,6 +319,10 @@ interface MockupResult {
311
319
  * (see {@link RealtimeMockupService.getLatestSentVersions}).
312
320
  */
313
321
  versions?: Record<string, number>;
322
+ /** Frame sequence number (per socket, increasing; boxes with flow control). Ack it with ackFrame once drawn. */
323
+ seq?: number;
324
+ /** Older frames of this mockup the box dropped in favour of this one (flow control, latest wins). */
325
+ coalesced?: number;
314
326
  /** Server-side render time in ms */
315
327
  renderMs?: number;
316
328
  /** Time from blob received to render start in ms */
@@ -352,6 +364,17 @@ interface MockupResult {
352
364
  }
353
365
  interface WebSocketMessage {
354
366
  type: string;
367
+ /** config_received: frame flow control the box agreed to (only when the config asked for acks). */
368
+ acks?: {
369
+ window: number;
370
+ timeoutMs?: number;
371
+ };
372
+ /** Frame sequence number (mockup_rendered, mockup_frame, ack_timeout). */
373
+ seq?: number;
374
+ /** Older frames of this mockup dropped in favour of this one (flow control). */
375
+ coalesced?: number;
376
+ /** E_RT_ACK_BAD: why the ack was rejected. */
377
+ reason?: string;
355
378
  sessionId?: string;
356
379
  mockups?: MockupResult[];
357
380
  imageUrl?: string;
@@ -428,7 +451,18 @@ interface RealtimeRenderError {
428
451
  */
429
452
  mockupId?: string;
430
453
  }
454
+ /** Frame flow control as negotiated with the box (null: not asked, or the box does not support it). */
455
+ interface RealtimeAcksState {
456
+ window: number;
457
+ timeoutMs: number;
458
+ /** Frames the box gave up waiting for (E_RT_ACK_TIMEOUT): a frame the client never acked within timeoutMs. */
459
+ timeouts: number;
460
+ /** Acks the box rejected (E_RT_ACK_BAD): a client protocol fault. */
461
+ badAcks: number;
462
+ }
431
463
  interface RealtimeMockupState {
464
+ /** Frame flow control, when negotiated (see WebSocketConfig.acks). */
465
+ acks: RealtimeAcksState | null;
432
466
  isConnected: boolean;
433
467
  sessionId: string | null;
434
468
  /** Render node that answered the handshake (`connected.box`); null until
@@ -471,6 +505,15 @@ interface RealtimeMockupCallbacks {
471
505
  */
472
506
  onError?: (error: string, detail: RealtimeRenderError) => void;
473
507
  onLog?: (message: string, type: 'info' | 'sent' | 'received') => void;
508
+ /** A flow-control fault: the box timed out waiting for an ack (E_RT_ACK_TIMEOUT) or rejected one (E_RT_ACK_BAD).
509
+ * Never a picture refusal and never the session's renderError: the frames keep coming. */
510
+ onAckFault?: (fault: {
511
+ code: 'E_RT_ACK_TIMEOUT' | 'E_RT_ACK_BAD';
512
+ mockupId?: string;
513
+ seq?: number;
514
+ reason?: string;
515
+ message: string;
516
+ }) => void;
474
517
  }
475
518
  declare class RealtimeMockupService {
476
519
  private wsUrl;
@@ -502,6 +545,11 @@ declare class RealtimeMockupService {
502
545
  private tokenProvider?;
503
546
  private pendingFrames;
504
547
  private liveObjectUrls;
548
+ private acks;
549
+ private ackedSeq;
550
+ private newestSeq;
551
+ private pendingAcks;
552
+ private ackFlushScheduled;
505
553
  private supersededFrameUrls;
506
554
  private renewTimer;
507
555
  private isConnecting;
@@ -597,6 +645,15 @@ declare class RealtimeMockupService {
597
645
  * already here; it reaches the results with its batch's all_mockups_rendered) from a real failure.
598
646
  */
599
647
  isFrameSuperseded(url: string): boolean;
648
+ /**
649
+ * The client is done with frame `seq` of `mockupId`: drawn on screen, superseded, not shown by any element, or
650
+ * failed. Cumulative per mockup. A no-op unless flow control was negotiated (see WebSocketConfig.acks). Acks are
651
+ * batched into one frame_ack message per animation frame.
652
+ */
653
+ ackFrame(mockupId: string, seq: number): boolean;
654
+ private flushAcks;
655
+ /** Whether frame flow control is active on this session (negotiated with the box for the current config). */
656
+ isAcking(): boolean;
600
657
  rerender(mockupIds: string[]): boolean;
601
658
  getLastSentVersion(): number;
602
659
  sendColorBlob(placement: string, hexColor: string): boolean;
@@ -611,4 +668,4 @@ declare class RealtimeMockupService {
611
668
  clearMockups(): void;
612
669
  }
613
670
 
614
- export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type PlacementSettings as P, type RealtimeRenderError as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, RealtimeMockupService as h, type ProductComponentContext as i, type RealtimeMockupCallbacks as j, type RealtimeMockupState as k, type RenderResult as l, type WebSocketMessage as m, adapterRegistry as n, computeDisabledChoices as o, createComponent as p, defineComponent as q, deriveDefaultSelection as r, findBestCombination as s, getPricePreview as t, isOptionAvailable as u, resolveBestCombination as v };
671
+ export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type PlacementSettings as P, type RealtimeRenderError as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, RealtimeMockupService as h, type ProductComponentContext as i, type RealtimeMockupCallbacks as j, type RealtimeMockupState as k, type RenderResult as l, type WebSocketMessage as m, adapterRegistry as n, computeDisabledChoices as o, createComponent as p, defineComponent as q, deriveDefaultSelection as r, findBestCombination as s, getPricePreview as t, isOptionAvailable as u, resolveBestCombination as v, type RealtimeAcksState as w };
@@ -211,6 +211,14 @@ interface PlacementSettings {
211
211
  }
212
212
  interface WebSocketConfig {
213
213
  productId: string;
214
+ /**
215
+ * Ask the box for frame flow control: it keeps at most `window` un-acked frames per mockup and coalesces the rest
216
+ * (latest wins), so a slow link or a slow screen never queues a backlog behind Cloudflare. ONLY for a client that
217
+ * calls {@link RealtimeMockupService.ackFrame} when it has drawn a frame: every frame must be acked (the service
218
+ * acks superseded and stale-dropped frames itself). Dormant on a box that does not negotiate it (config_received
219
+ * without `acks`).
220
+ */
221
+ acks?: boolean;
214
222
  mockupIds: string[];
215
223
  variantId: string;
216
224
  shop: string;
@@ -311,6 +319,10 @@ interface MockupResult {
311
319
  * (see {@link RealtimeMockupService.getLatestSentVersions}).
312
320
  */
313
321
  versions?: Record<string, number>;
322
+ /** Frame sequence number (per socket, increasing; boxes with flow control). Ack it with ackFrame once drawn. */
323
+ seq?: number;
324
+ /** Older frames of this mockup the box dropped in favour of this one (flow control, latest wins). */
325
+ coalesced?: number;
314
326
  /** Server-side render time in ms */
315
327
  renderMs?: number;
316
328
  /** Time from blob received to render start in ms */
@@ -352,6 +364,17 @@ interface MockupResult {
352
364
  }
353
365
  interface WebSocketMessage {
354
366
  type: string;
367
+ /** config_received: frame flow control the box agreed to (only when the config asked for acks). */
368
+ acks?: {
369
+ window: number;
370
+ timeoutMs?: number;
371
+ };
372
+ /** Frame sequence number (mockup_rendered, mockup_frame, ack_timeout). */
373
+ seq?: number;
374
+ /** Older frames of this mockup dropped in favour of this one (flow control). */
375
+ coalesced?: number;
376
+ /** E_RT_ACK_BAD: why the ack was rejected. */
377
+ reason?: string;
355
378
  sessionId?: string;
356
379
  mockups?: MockupResult[];
357
380
  imageUrl?: string;
@@ -428,7 +451,18 @@ interface RealtimeRenderError {
428
451
  */
429
452
  mockupId?: string;
430
453
  }
454
+ /** Frame flow control as negotiated with the box (null: not asked, or the box does not support it). */
455
+ interface RealtimeAcksState {
456
+ window: number;
457
+ timeoutMs: number;
458
+ /** Frames the box gave up waiting for (E_RT_ACK_TIMEOUT): a frame the client never acked within timeoutMs. */
459
+ timeouts: number;
460
+ /** Acks the box rejected (E_RT_ACK_BAD): a client protocol fault. */
461
+ badAcks: number;
462
+ }
431
463
  interface RealtimeMockupState {
464
+ /** Frame flow control, when negotiated (see WebSocketConfig.acks). */
465
+ acks: RealtimeAcksState | null;
432
466
  isConnected: boolean;
433
467
  sessionId: string | null;
434
468
  /** Render node that answered the handshake (`connected.box`); null until
@@ -471,6 +505,15 @@ interface RealtimeMockupCallbacks {
471
505
  */
472
506
  onError?: (error: string, detail: RealtimeRenderError) => void;
473
507
  onLog?: (message: string, type: 'info' | 'sent' | 'received') => void;
508
+ /** A flow-control fault: the box timed out waiting for an ack (E_RT_ACK_TIMEOUT) or rejected one (E_RT_ACK_BAD).
509
+ * Never a picture refusal and never the session's renderError: the frames keep coming. */
510
+ onAckFault?: (fault: {
511
+ code: 'E_RT_ACK_TIMEOUT' | 'E_RT_ACK_BAD';
512
+ mockupId?: string;
513
+ seq?: number;
514
+ reason?: string;
515
+ message: string;
516
+ }) => void;
474
517
  }
475
518
  declare class RealtimeMockupService {
476
519
  private wsUrl;
@@ -502,6 +545,11 @@ declare class RealtimeMockupService {
502
545
  private tokenProvider?;
503
546
  private pendingFrames;
504
547
  private liveObjectUrls;
548
+ private acks;
549
+ private ackedSeq;
550
+ private newestSeq;
551
+ private pendingAcks;
552
+ private ackFlushScheduled;
505
553
  private supersededFrameUrls;
506
554
  private renewTimer;
507
555
  private isConnecting;
@@ -597,6 +645,15 @@ declare class RealtimeMockupService {
597
645
  * already here; it reaches the results with its batch's all_mockups_rendered) from a real failure.
598
646
  */
599
647
  isFrameSuperseded(url: string): boolean;
648
+ /**
649
+ * The client is done with frame `seq` of `mockupId`: drawn on screen, superseded, not shown by any element, or
650
+ * failed. Cumulative per mockup. A no-op unless flow control was negotiated (see WebSocketConfig.acks). Acks are
651
+ * batched into one frame_ack message per animation frame.
652
+ */
653
+ ackFrame(mockupId: string, seq: number): boolean;
654
+ private flushAcks;
655
+ /** Whether frame flow control is active on this session (negotiated with the box for the current config). */
656
+ isAcking(): boolean;
600
657
  rerender(mockupIds: string[]): boolean;
601
658
  getLastSentVersion(): number;
602
659
  sendColorBlob(placement: string, hexColor: string): boolean;
@@ -611,4 +668,4 @@ declare class RealtimeMockupService {
611
668
  clearMockups(): void;
612
669
  }
613
670
 
614
- export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type PlacementSettings as P, type RealtimeRenderError as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, RealtimeMockupService as h, type ProductComponentContext as i, type RealtimeMockupCallbacks as j, type RealtimeMockupState as k, type RenderResult as l, type WebSocketMessage as m, adapterRegistry as n, computeDisabledChoices as o, createComponent as p, defineComponent as q, deriveDefaultSelection as r, findBestCombination as s, getPricePreview as t, isOptionAvailable as u, resolveBestCombination as v };
671
+ export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type PlacementSettings as P, type RealtimeRenderError as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, RealtimeMockupService as h, type ProductComponentContext as i, type RealtimeMockupCallbacks as j, type RealtimeMockupState as k, type RenderResult as l, type WebSocketMessage as m, adapterRegistry as n, computeDisabledChoices as o, createComponent as p, defineComponent as q, deriveDefaultSelection as r, findBestCombination as s, getPricePreview as t, isOptionAvailable as u, resolveBestCombination as v, type RealtimeAcksState as w };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@snowcone-app/sdk",
3
- "version": "0.26.0",
3
+ "version": "0.27.0",
4
4
  "description": "Snowcone SDK for product mockups and print-on-demand",
5
5
  "keywords": [
6
6
  "merch",