@snowcone-app/sdk 0.25.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,26 @@
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
+
16
+ ## 0.26.0
17
+
18
+ ### Minor Changes
19
+
20
+ - [#4415](https://github.com/snowcone-app/snowcone-monorepo/pull/4415) [`ccc4cf3`](https://github.com/snowcone-app/snowcone-monorepo/commit/ccc4cf371c5f4845e679b8c295e0335881664e96) Thanks [@kevinsproles](https://github.com/kevinsproles)! - The SDK reports `isFrameSuperseded(url)`: true once a newer ws frame for the same mockup has arrived and the old one was revoked. The UI uses it when a cropped frame fails to load: a superseded frame is dropped at once instead of waiting on the 2 s grace, which a 31-picture batch can outlast (React only sees the newer frame with the batch's `all_mockups_rendered`). Before, the grace fired first, cropped delivery went off for the session and a visible picture could stay one version behind.
21
+
22
+ `all_mockups_rendered` now merges its batch into `mockupResults` instead of replacing it. A short batch (a `rerender` answer) landing right after a full one replaced it, React coalesced the two updates, and every other picture kept its previous version.
23
+
3
24
  ## 0.25.0
4
25
 
5
26
  ### Minor Changes
@@ -88,6 +88,15 @@ 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;
97
+ // Live frames a newer frame for the same mockup has replaced (and revoked), newest last, bounded. Lets a consumer
98
+ // still loading an old frame tell "superseded" from "broken" the moment it fails (isFrameSuperseded).
99
+ supersededFrameUrls = /* @__PURE__ */ new Set();
91
100
  renewTimer = null;
92
101
  isConnecting = false;
93
102
  connectAttempt = 0;
@@ -100,6 +109,7 @@ var RealtimeMockupService = class {
100
109
  }
101
110
  getState() {
102
111
  return {
112
+ acks: this.acks ? { ...this.acks } : null,
103
113
  isConnected: this.ws?.readyState === WebSocket.OPEN,
104
114
  sessionId: this.sessionId,
105
115
  box: this.box,
@@ -145,6 +155,10 @@ var RealtimeMockupService = class {
145
155
  this.ws = new WebSocket(url);
146
156
  this.ws.binaryType = "arraybuffer";
147
157
  this.ws.onopen = () => {
158
+ this.acks = null;
159
+ this.ackedSeq.clear();
160
+ this.newestSeq.clear();
161
+ this.pendingAcks.clear();
148
162
  console.log(`[WS] connection OPENED to ${this.wsUrl}`);
149
163
  this.addLog("WebSocket connection opened");
150
164
  this.status = "Connected";
@@ -225,6 +239,16 @@ var RealtimeMockupService = class {
225
239
  break;
226
240
  case "config_received":
227
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
+ }
228
252
  this.isConfigured = true;
229
253
  this.status = "Configured";
230
254
  this.addLog("\u2705 Configuration accepted! You can now send blobs.");
@@ -281,12 +305,20 @@ var RealtimeMockupService = class {
281
305
  if (lastAccepted !== void 0 && responseVersion < lastAccepted) {
282
306
  console.log(`[WS] STALE mockup dropped: v${responseVersion} for "${responsePlacement}" (already displayed: v${lastAccepted}, latest sent: v${this.latestSentVersionByPlacement[responsePlacement]})`);
283
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);
284
309
  break;
285
310
  }
286
311
  this.latestAcceptedVersionByPlacement[responsePlacement] = responseVersion;
287
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
+ }
288
318
  const mockupResult = {
289
319
  mockupId: data.mockupId,
320
+ ...typeof data.seq === "number" ? { seq: data.seq } : {},
321
+ ...typeof data.coalesced === "number" ? { coalesced: data.coalesced } : {},
290
322
  imageUrl: data.imageUrl,
291
323
  renderUrl: data.renderUrl || data.imageUrl,
292
324
  imageSize: data.imageSize || 0,
@@ -338,7 +370,7 @@ var RealtimeMockupService = class {
338
370
  }
339
371
  return true;
340
372
  });
341
- this.mockupResults = freshMockups.map((mockup) => {
373
+ const batch = freshMockups.map((mockup) => {
342
374
  const existing = this.mockupResults.find(
343
375
  (m) => m.mockupId === mockup.mockupId && (mockup.requestId === void 0 || m.requestId === mockup.requestId)
344
376
  );
@@ -350,6 +382,11 @@ var RealtimeMockupService = class {
350
382
  }
351
383
  return merged;
352
384
  });
385
+ const batchById = new Map(batch.map((m) => [m.mockupId, m]));
386
+ this.mockupResults = [
387
+ ...this.mockupResults.map((m) => batchById.get(m.mockupId) ?? m),
388
+ ...batch.filter((m) => !this.mockupResults.some((e) => e.mockupId === m.mockupId))
389
+ ];
353
390
  this.lastError = null;
354
391
  this.renderError = null;
355
392
  this.addLog(`\u{1F389} All mockups rendered: ${freshMockups.length} fresh (${data.mockups.length - freshMockups.length} stale filtered)`);
@@ -358,7 +395,23 @@ var RealtimeMockupService = class {
358
395
  this.addLog(`\u26A0\uFE0F all_mockups_rendered message dropped: missing 'mockups' array. Full data keys: [${Object.keys(data).join(", ")}]`);
359
396
  }
360
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
+ }
361
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
+ }
362
415
  const errorMessage = data.message || "Unknown error occurred";
363
416
  const renderError = {
364
417
  code: data.code || "render_error",
@@ -411,7 +464,14 @@ var RealtimeMockupService = class {
411
464
  if (!frame) return;
412
465
  this.pendingFrames.delete(key);
413
466
  const prevLive = this.liveObjectUrls.get(data.mockupId);
414
- if (prevLive) URL.revokeObjectURL(prevLive);
467
+ if (prevLive) {
468
+ URL.revokeObjectURL(prevLive);
469
+ this.supersededFrameUrls.add(prevLive);
470
+ if (this.supersededFrameUrls.size > 512) {
471
+ const oldest = this.supersededFrameUrls.values().next().value;
472
+ if (oldest) this.supersededFrameUrls.delete(oldest);
473
+ }
474
+ }
415
475
  this.liveObjectUrls.set(data.mockupId, frame.objectUrl);
416
476
  data.imageUrl = frame.objectUrl;
417
477
  }
@@ -777,6 +837,47 @@ ${versionToSend}
777
837
  * E_RERENDER_INCOMPLETE | E_RERENDER_RATE_LIMITED). Never changes the
778
838
  * session's mockupIds.
779
839
  */
840
+ /**
841
+ * True when `url` was a ws-delivered frame for a mockup and a newer frame for that mockup has since arrived (the SDK
842
+ * revoked the old one). A consumer whose load of `url` failed uses this to tell supersession (the newer frame is
843
+ * already here; it reaches the results with its batch's all_mockups_rendered) from a real failure.
844
+ */
845
+ isFrameSuperseded(url) {
846
+ return this.supersededFrameUrls.has(url);
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
+ }
780
881
  rerender(mockupIds) {
781
882
  if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.config || mockupIds.length === 0) return false;
782
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,15 @@ 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;
5152
+ // Live frames a newer frame for the same mockup has replaced (and revoked), newest last, bounded. Lets a consumer
5153
+ // still loading an old frame tell "superseded" from "broken" the moment it fails (isFrameSuperseded).
5154
+ supersededFrameUrls = /* @__PURE__ */ new Set();
5121
5155
  renewTimer = null;
5122
5156
  isConnecting = false;
5123
5157
  connectAttempt = 0;
@@ -5130,6 +5164,7 @@ var RealtimeMockupService = class {
5130
5164
  }
5131
5165
  getState() {
5132
5166
  return {
5167
+ acks: this.acks ? { ...this.acks } : null,
5133
5168
  isConnected: this.ws?.readyState === WebSocket.OPEN,
5134
5169
  sessionId: this.sessionId,
5135
5170
  box: this.box,
@@ -5175,6 +5210,10 @@ var RealtimeMockupService = class {
5175
5210
  this.ws = new WebSocket(url);
5176
5211
  this.ws.binaryType = "arraybuffer";
5177
5212
  this.ws.onopen = () => {
5213
+ this.acks = null;
5214
+ this.ackedSeq.clear();
5215
+ this.newestSeq.clear();
5216
+ this.pendingAcks.clear();
5178
5217
  console.log(`[WS] connection OPENED to ${this.wsUrl}`);
5179
5218
  this.addLog("WebSocket connection opened");
5180
5219
  this.status = "Connected";
@@ -5255,6 +5294,16 @@ var RealtimeMockupService = class {
5255
5294
  break;
5256
5295
  case "config_received":
5257
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
+ }
5258
5307
  this.isConfigured = true;
5259
5308
  this.status = "Configured";
5260
5309
  this.addLog("\u2705 Configuration accepted! You can now send blobs.");
@@ -5311,12 +5360,20 @@ var RealtimeMockupService = class {
5311
5360
  if (lastAccepted !== void 0 && responseVersion < lastAccepted) {
5312
5361
  console.log(`[WS] STALE mockup dropped: v${responseVersion} for "${responsePlacement}" (already displayed: v${lastAccepted}, latest sent: v${this.latestSentVersionByPlacement[responsePlacement]})`);
5313
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);
5314
5364
  break;
5315
5365
  }
5316
5366
  this.latestAcceptedVersionByPlacement[responsePlacement] = responseVersion;
5317
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
+ }
5318
5373
  const mockupResult = {
5319
5374
  mockupId: data.mockupId,
5375
+ ...typeof data.seq === "number" ? { seq: data.seq } : {},
5376
+ ...typeof data.coalesced === "number" ? { coalesced: data.coalesced } : {},
5320
5377
  imageUrl: data.imageUrl,
5321
5378
  renderUrl: data.renderUrl || data.imageUrl,
5322
5379
  imageSize: data.imageSize || 0,
@@ -5368,7 +5425,7 @@ var RealtimeMockupService = class {
5368
5425
  }
5369
5426
  return true;
5370
5427
  });
5371
- this.mockupResults = freshMockups.map((mockup) => {
5428
+ const batch = freshMockups.map((mockup) => {
5372
5429
  const existing = this.mockupResults.find(
5373
5430
  (m) => m.mockupId === mockup.mockupId && (mockup.requestId === void 0 || m.requestId === mockup.requestId)
5374
5431
  );
@@ -5380,6 +5437,11 @@ var RealtimeMockupService = class {
5380
5437
  }
5381
5438
  return merged;
5382
5439
  });
5440
+ const batchById = new Map(batch.map((m) => [m.mockupId, m]));
5441
+ this.mockupResults = [
5442
+ ...this.mockupResults.map((m) => batchById.get(m.mockupId) ?? m),
5443
+ ...batch.filter((m) => !this.mockupResults.some((e) => e.mockupId === m.mockupId))
5444
+ ];
5383
5445
  this.lastError = null;
5384
5446
  this.renderError = null;
5385
5447
  this.addLog(`\u{1F389} All mockups rendered: ${freshMockups.length} fresh (${data.mockups.length - freshMockups.length} stale filtered)`);
@@ -5388,7 +5450,23 @@ var RealtimeMockupService = class {
5388
5450
  this.addLog(`\u26A0\uFE0F all_mockups_rendered message dropped: missing 'mockups' array. Full data keys: [${Object.keys(data).join(", ")}]`);
5389
5451
  }
5390
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
+ }
5391
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
+ }
5392
5470
  const errorMessage = data.message || "Unknown error occurred";
5393
5471
  const renderError = {
5394
5472
  code: data.code || "render_error",
@@ -5441,7 +5519,14 @@ var RealtimeMockupService = class {
5441
5519
  if (!frame) return;
5442
5520
  this.pendingFrames.delete(key);
5443
5521
  const prevLive = this.liveObjectUrls.get(data.mockupId);
5444
- if (prevLive) URL.revokeObjectURL(prevLive);
5522
+ if (prevLive) {
5523
+ URL.revokeObjectURL(prevLive);
5524
+ this.supersededFrameUrls.add(prevLive);
5525
+ if (this.supersededFrameUrls.size > 512) {
5526
+ const oldest = this.supersededFrameUrls.values().next().value;
5527
+ if (oldest) this.supersededFrameUrls.delete(oldest);
5528
+ }
5529
+ }
5445
5530
  this.liveObjectUrls.set(data.mockupId, frame.objectUrl);
5446
5531
  data.imageUrl = frame.objectUrl;
5447
5532
  }
@@ -5807,6 +5892,47 @@ ${versionToSend}
5807
5892
  * E_RERENDER_INCOMPLETE | E_RERENDER_RATE_LIMITED). Never changes the
5808
5893
  * session's mockupIds.
5809
5894
  */
5895
+ /**
5896
+ * True when `url` was a ws-delivered frame for a mockup and a newer frame for that mockup has since arrived (the SDK
5897
+ * revoked the old one). A consumer whose load of `url` failed uses this to tell supersession (the newer frame is
5898
+ * already here; it reaches the results with its batch's all_mockups_rendered) from a real failure.
5899
+ */
5900
+ isFrameSuperseded(url) {
5901
+ return this.supersededFrameUrls.has(url);
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
+ }
5810
5936
  rerender(mockupIds) {
5811
5937
  if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.config || mockupIds.length === 0) return false;
5812
5938
  const { requestId, traceparent } = newRenderCorrelation();
@@ -6532,6 +6658,7 @@ function createClient(config) {
6532
6658
  REALTIME_WS_URL,
6533
6659
  RealtimeMockupService,
6534
6660
  RenderSession,
6661
+ SIZE_PICTURE,
6535
6662
  SnowconeSdkError,
6536
6663
  StandardComponents,
6537
6664
  StandardEvents,
@@ -6587,6 +6714,7 @@ function createClient(config) {
6587
6714
  findVariantForSelection,
6588
6715
  formatPrice,
6589
6716
  formatValidationErrors,
6717
+ gallerySizePicture,
6590
6718
  getBuyUrl,
6591
6719
  getDefaultVariantId,
6592
6720
  getEffectiveAlignment,
@@ -6608,9 +6736,13 @@ function createClient(config) {
6608
6736
  isValidTileCount,
6609
6737
  listProducts,
6610
6738
  mintRealtimeGrant,
6739
+ mockupRole,
6611
6740
  mockupUrl,
6612
6741
  normalizeChoice,
6742
+ ordinaryMockups,
6743
+ pictureForVariant,
6613
6744
  prepareOptionRenderData,
6745
+ primaryMockup,
6614
6746
  registerStandardComponents,
6615
6747
  resolveBestCombination,
6616
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-Cy0Y29CW.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-Cy0Y29CW.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 };