@snowcone-app/sdk 0.26.0 → 0.27.1

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,24 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.27.1
4
+
5
+ ### Patch Changes
6
+
7
+ - [#4488](https://github.com/snowcone-app/snowcone-monorepo/pull/4488) [`72cfddc`](https://github.com/snowcone-app/snowcone-monorepo/commit/72cfddc99569dda4ead08c07c11a8af9fc711f2b) Thanks [@kevinsproles](https://github.com/kevinsproles)! - `mockupRole` is an allowlist. A mockup is `ordinary` only when it carries no `linkedAs`, and `'size-picture'` holds its size's role. Any other mark, such as `'size-picture-released'` (a pattern picture that handed its size's role to a lay-flat) or a later role, is `other`: never shown in the gallery and never returned by an ordinary-picture lookup.
8
+
9
+ ## 0.27.0
10
+
11
+ ### Minor Changes
12
+
13
+ - [#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.
14
+ - **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.
15
+ - **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.
16
+ - **Older boxes:** stay unchanged. Acks are dormant until `config_received` carries them.
17
+
18
+ - [#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.
19
+ - **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.
20
+ - **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.
21
+
3
22
  ## 0.26.0
4
23
 
5
24
  ### 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,14 @@ 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
+ // Any mark is kept (a parse must not strip it): only an absent one is an ordinary picture (mockupRole.ts).
188
+ linkedAs: import_zod.z.string().optional()
189
+ })
177
190
  ).optional(),
178
191
  options: import_zod.z.object({
179
192
  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 +1078,32 @@ function bffSigner(endpoint = "/api/sign", opts) {
1065
1078
  };
1066
1079
  }
1067
1080
 
1081
+ // src/mockup/mockupRole.ts
1082
+ var SIZE_PICTURE = "size-picture";
1083
+ function mockupRole(m) {
1084
+ const mark = m?.linkedAs;
1085
+ if (mark === void 0 || mark === null || mark === "") return "ordinary";
1086
+ return mark === SIZE_PICTURE ? SIZE_PICTURE : "other";
1087
+ }
1088
+ function ordinaryMockups(mockups) {
1089
+ return (mockups ?? []).filter((m) => mockupRole(m) === "ordinary");
1090
+ }
1091
+ function pictureForVariant(mockups, variantId) {
1092
+ const ordinary = ordinaryMockups(mockups);
1093
+ if (variantId) {
1094
+ const listed = ordinary.find((m) => (m.gvids ?? []).includes(variantId));
1095
+ if (listed) return listed;
1096
+ }
1097
+ return ordinary[0] ?? null;
1098
+ }
1099
+ function primaryMockup(mockups) {
1100
+ return ordinaryMockups(mockups)[0] ?? null;
1101
+ }
1102
+ function gallerySizePicture(mockups, selectedVariantId) {
1103
+ if (!selectedVariantId) return null;
1104
+ return (mockups ?? []).find((m) => mockupRole(m) === SIZE_PICTURE && (m.gvids ?? []).includes(selectedVariantId)) ?? null;
1105
+ }
1106
+
1068
1107
  // src/state/optionSelection.ts
1069
1108
  function resolveBestCombination(selection, attributes, combinations) {
1070
1109
  const relevant = Object.fromEntries(
@@ -1914,10 +1953,7 @@ function getVariant(selection, product) {
1914
1953
  const variantId = combination?.variantId;
1915
1954
  let mockupId;
1916
1955
  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;
1956
+ mockupId = pictureForVariant(product.mockups, variantId)?.id;
1921
1957
  }
1922
1958
  return {
1923
1959
  variantId,
@@ -1956,7 +1992,7 @@ var SIZE_ATTRIBUTE = /^size$/i;
1956
1992
  var NOT_THE_PICTURE = /* @__PURE__ */ new Set(["variantId", "price"]);
1957
1993
  function resolvePreviewVariantId(context, variantId, mockupId) {
1958
1994
  const all = context?.product?.mockups ?? [];
1959
- const mockups = mockupId ? all.filter((m) => m.id === mockupId) : all;
1995
+ const mockups = mockupId ? all.filter((m) => m.id === mockupId) : [...ordinaryMockups(all)];
1960
1996
  const lists = (m, id) => (m.gvids ?? []).includes(id);
1961
1997
  if (mockups.length === 0 || mockups.some((m) => lists(m, variantId))) return variantId;
1962
1998
  const combinations = context?.combinations ?? [];
@@ -1984,15 +2020,7 @@ function resolvePreviewVariantId(context, variantId, mockupId) {
1984
2020
  function resolveMockupId(context, variantId, providedMockupId) {
1985
2021
  if (providedMockupId) return providedMockupId;
1986
2022
  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;
2023
+ return pictureForVariant(context.product.mockups, variantId)?.id ?? null;
1996
2024
  }
1997
2025
  return null;
1998
2026
  }
@@ -5118,6 +5146,12 @@ var RealtimeMockupService = class {
5118
5146
  pendingFrames = /* @__PURE__ */ new Map();
5119
5147
  // Last object URL handed out per mockup — revoked when replaced.
5120
5148
  liveObjectUrls = /* @__PURE__ */ new Map();
5149
+ // Frame flow control (negotiated per config): window, acked/newest seq per mockup, acks waiting for the next flush.
5150
+ acks = null;
5151
+ ackedSeq = /* @__PURE__ */ new Map();
5152
+ newestSeq = /* @__PURE__ */ new Map();
5153
+ pendingAcks = /* @__PURE__ */ new Map();
5154
+ ackFlushScheduled = false;
5121
5155
  // Live frames a newer frame for the same mockup has replaced (and revoked), newest last, bounded. Lets a consumer
5122
5156
  // still loading an old frame tell "superseded" from "broken" the moment it fails (isFrameSuperseded).
5123
5157
  supersededFrameUrls = /* @__PURE__ */ new Set();
@@ -5133,6 +5167,7 @@ var RealtimeMockupService = class {
5133
5167
  }
5134
5168
  getState() {
5135
5169
  return {
5170
+ acks: this.acks ? { ...this.acks } : null,
5136
5171
  isConnected: this.ws?.readyState === WebSocket.OPEN,
5137
5172
  sessionId: this.sessionId,
5138
5173
  box: this.box,
@@ -5178,6 +5213,10 @@ var RealtimeMockupService = class {
5178
5213
  this.ws = new WebSocket(url);
5179
5214
  this.ws.binaryType = "arraybuffer";
5180
5215
  this.ws.onopen = () => {
5216
+ this.acks = null;
5217
+ this.ackedSeq.clear();
5218
+ this.newestSeq.clear();
5219
+ this.pendingAcks.clear();
5181
5220
  console.log(`[WS] connection OPENED to ${this.wsUrl}`);
5182
5221
  this.addLog("WebSocket connection opened");
5183
5222
  this.status = "Connected";
@@ -5258,6 +5297,16 @@ var RealtimeMockupService = class {
5258
5297
  break;
5259
5298
  case "config_received":
5260
5299
  case "configured":
5300
+ if (this.config?.acks && data.acks && typeof data.acks.window === "number") {
5301
+ this.acks = {
5302
+ window: data.acks.window,
5303
+ timeoutMs: typeof data.acks.timeoutMs === "number" ? data.acks.timeoutMs : 0,
5304
+ timeouts: this.acks?.timeouts ?? 0,
5305
+ badAcks: this.acks?.badAcks ?? 0
5306
+ };
5307
+ } else {
5308
+ this.acks = null;
5309
+ }
5261
5310
  this.isConfigured = true;
5262
5311
  this.status = "Configured";
5263
5312
  this.addLog("\u2705 Configuration accepted! You can now send blobs.");
@@ -5314,12 +5363,20 @@ var RealtimeMockupService = class {
5314
5363
  if (lastAccepted !== void 0 && responseVersion < lastAccepted) {
5315
5364
  console.log(`[WS] STALE mockup dropped: v${responseVersion} for "${responsePlacement}" (already displayed: v${lastAccepted}, latest sent: v${this.latestSentVersionByPlacement[responsePlacement]})`);
5316
5365
  this.addLog(`\u23ED\uFE0F Ignoring stale mockup v${responseVersion} for "${responsePlacement}" (displayed: v${lastAccepted})`);
5366
+ if (typeof data.seq === "number") this.ackFrame(data.mockupId, data.seq);
5317
5367
  break;
5318
5368
  }
5319
5369
  this.latestAcceptedVersionByPlacement[responsePlacement] = responseVersion;
5320
5370
  }
5371
+ if (typeof data.seq === "number") {
5372
+ const prevSeq = this.newestSeq.get(data.mockupId);
5373
+ if (prevSeq !== void 0 && prevSeq < data.seq) this.ackFrame(data.mockupId, prevSeq);
5374
+ if (prevSeq === void 0 || prevSeq < data.seq) this.newestSeq.set(data.mockupId, data.seq);
5375
+ }
5321
5376
  const mockupResult = {
5322
5377
  mockupId: data.mockupId,
5378
+ ...typeof data.seq === "number" ? { seq: data.seq } : {},
5379
+ ...typeof data.coalesced === "number" ? { coalesced: data.coalesced } : {},
5323
5380
  imageUrl: data.imageUrl,
5324
5381
  renderUrl: data.renderUrl || data.imageUrl,
5325
5382
  imageSize: data.imageSize || 0,
@@ -5396,7 +5453,23 @@ var RealtimeMockupService = class {
5396
5453
  this.addLog(`\u26A0\uFE0F all_mockups_rendered message dropped: missing 'mockups' array. Full data keys: [${Object.keys(data).join(", ")}]`);
5397
5454
  }
5398
5455
  break;
5456
+ case "ack_timeout": {
5457
+ if (this.acks) this.acks.timeouts += 1;
5458
+ 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).`;
5459
+ console.error(`[WS] ${message}`);
5460
+ this.addLog(`\u23F1\uFE0F ${message}`);
5461
+ this.callbacks.onAckFault?.({ code: "E_RT_ACK_TIMEOUT", mockupId: data.mockupId, seq: data.seq, message });
5462
+ break;
5463
+ }
5399
5464
  case "error": {
5465
+ if (data.code === "E_RT_ACK_BAD") {
5466
+ if (this.acks) this.acks.badAcks += 1;
5467
+ const message = `E_RT_ACK_BAD (${data.reason ?? "?"}) for ${data.mockupId ?? "?"}: ${data.message ?? ""}`;
5468
+ console.error(`[WS] ${message}`);
5469
+ this.addLog(`\u274C ${message}`);
5470
+ this.callbacks.onAckFault?.({ code: "E_RT_ACK_BAD", mockupId: data.mockupId, reason: data.reason, message });
5471
+ break;
5472
+ }
5400
5473
  const errorMessage = data.message || "Unknown error occurred";
5401
5474
  const renderError = {
5402
5475
  code: data.code || "render_error",
@@ -5830,6 +5903,39 @@ ${versionToSend}
5830
5903
  isFrameSuperseded(url) {
5831
5904
  return this.supersededFrameUrls.has(url);
5832
5905
  }
5906
+ /**
5907
+ * The client is done with frame `seq` of `mockupId`: drawn on screen, superseded, not shown by any element, or
5908
+ * failed. Cumulative per mockup. A no-op unless flow control was negotiated (see WebSocketConfig.acks). Acks are
5909
+ * batched into one frame_ack message per animation frame.
5910
+ */
5911
+ ackFrame(mockupId, seq) {
5912
+ if (!this.acks || !(seq > 0)) return false;
5913
+ if (seq <= (this.ackedSeq.get(mockupId) ?? 0) || seq <= (this.pendingAcks.get(mockupId) ?? 0)) return true;
5914
+ this.pendingAcks.set(mockupId, seq);
5915
+ if (!this.ackFlushScheduled) {
5916
+ this.ackFlushScheduled = true;
5917
+ const flush = () => this.flushAcks();
5918
+ if (typeof requestAnimationFrame === "function") requestAnimationFrame(flush);
5919
+ else setTimeout(flush, 16);
5920
+ }
5921
+ return true;
5922
+ }
5923
+ flushAcks() {
5924
+ this.ackFlushScheduled = false;
5925
+ if (!this.acks || this.pendingAcks.size === 0) {
5926
+ this.pendingAcks.clear();
5927
+ return;
5928
+ }
5929
+ if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
5930
+ const acks = [...this.pendingAcks].map(([mockupId, seq]) => ({ mockupId, seq }));
5931
+ this.pendingAcks.clear();
5932
+ acks.forEach(({ mockupId, seq }) => this.ackedSeq.set(mockupId, seq));
5933
+ this.ws.send(JSON.stringify(acks.length === 1 ? { type: "frame_ack", ...acks[0] } : { type: "frame_ack", acks }));
5934
+ }
5935
+ /** Whether frame flow control is active on this session (negotiated with the box for the current config). */
5936
+ isAcking() {
5937
+ return this.acks !== null;
5938
+ }
5833
5939
  rerender(mockupIds) {
5834
5940
  if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.config || mockupIds.length === 0) return false;
5835
5941
  const { requestId, traceparent } = newRenderCorrelation();
@@ -6555,6 +6661,7 @@ function createClient(config) {
6555
6661
  REALTIME_WS_URL,
6556
6662
  RealtimeMockupService,
6557
6663
  RenderSession,
6664
+ SIZE_PICTURE,
6558
6665
  SnowconeSdkError,
6559
6666
  StandardComponents,
6560
6667
  StandardEvents,
@@ -6610,6 +6717,7 @@ function createClient(config) {
6610
6717
  findVariantForSelection,
6611
6718
  formatPrice,
6612
6719
  formatValidationErrors,
6720
+ gallerySizePicture,
6613
6721
  getBuyUrl,
6614
6722
  getDefaultVariantId,
6615
6723
  getEffectiveAlignment,
@@ -6631,9 +6739,13 @@ function createClient(config) {
6631
6739
  isValidTileCount,
6632
6740
  listProducts,
6633
6741
  mintRealtimeGrant,
6742
+ mockupRole,
6634
6743
  mockupUrl,
6635
6744
  normalizeChoice,
6745
+ ordinaryMockups,
6746
+ pictureForVariant,
6636
6747
  prepareOptionRenderData,
6748
+ primaryMockup,
6637
6749
  registerStandardComponents,
6638
6750
  resolveBestCombination,
6639
6751
  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. 'size-picture-released': a picture that handed its size's role to another (never shown, never an ordinary picture). Absent on ordinary mockups.
28
+ */
29
+ linkedAs?: "size-picture" | "size-picture-released";
26
30
  }[];
27
31
  options?: {
28
32
  selected?: {
@@ -471,6 +475,51 @@ 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
+ /**
489
+ * `ordinary` ONLY when the mockup carries no `linkedAs` (an allowlist): any other value is never an ordinary picture.
490
+ * `size-picture` holds the role for its size; `other` is every other mark, e.g. 'size-picture-released' (a pattern
491
+ * picture that handed its size's role to a lay-flat, rendercenter linker #4487) or a role added later: never shown in
492
+ * the gallery, never returned by an ordinary-picture lookup.
493
+ */
494
+ type MockupRole = "ordinary" | typeof SIZE_PICTURE | "other";
495
+ type WithRole = {
496
+ id?: unknown;
497
+ linkedAs?: unknown;
498
+ };
499
+ type WithGvids = {
500
+ id?: string;
501
+ gvids?: string[] | null;
502
+ };
503
+ declare function mockupRole(m: WithRole | null | undefined): MockupRole;
504
+ declare const ORDINARY: unique symbol;
505
+ /** A product's ordinary pictures (never a size picture). Only `ordinaryMockups` makes one. */
506
+ type OrdinaryMockups<T> = readonly T[] & {
507
+ readonly [ORDINARY]: true;
508
+ };
509
+ declare function ordinaryMockups<T extends WithRole>(mockups: readonly T[] | null | undefined): OrdinaryMockups<T>;
510
+ /**
511
+ * The picture for a variant: the first ordinary mockup that lists it, else the product's first ordinary mockup (its
512
+ * fallback picture), else null. Never a size picture, even when a size picture is the only mockup listing the variant.
513
+ */
514
+ declare function pictureForVariant<T extends WithRole & WithGvids>(mockups: readonly T[] | null | undefined, variantId: string | null | undefined): T | null;
515
+ /** The product's picture for cards, links and previews: its first ordinary mockup. Never a size picture. */
516
+ declare function primaryMockup<T extends WithRole>(mockups: readonly T[] | null | undefined): T | null;
517
+ /**
518
+ * The ONE size picture the gallery shows: the size picture whose gvids list the chosen variant, or null (no size
519
+ * pictures, or none for this size: never another size's picture).
520
+ */
521
+ declare function gallerySizePicture<T extends WithRole & WithGvids>(mockups: readonly T[] | null | undefined, selectedVariantId: string | null | undefined): T | null;
522
+
474
523
  /**
475
524
  * Framework-agnostic state management utilities
476
525
  * Provides consistent state management patterns for React and Web Components
@@ -1057,6 +1106,7 @@ declare function getVariant(selection: UserSelection, product: {
1057
1106
  mockups: Array<{
1058
1107
  id: string;
1059
1108
  gvids?: string[];
1109
+ linkedAs?: unknown;
1060
1110
  }>;
1061
1111
  attributes?: Record<string, any>;
1062
1112
  }): {
@@ -3436,4 +3486,4 @@ declare function searchDesigns(query?: string, options?: SearchDesignsOptions):
3436
3486
  */
3437
3487
  declare function createClient(config: SdkConfig): SnowconeClient;
3438
3488
 
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 };
3489
+ 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. 'size-picture-released': a picture that handed its size's role to another (never shown, never an ordinary picture). Absent on ordinary mockups.
28
+ */
29
+ linkedAs?: "size-picture" | "size-picture-released";
26
30
  }[];
27
31
  options?: {
28
32
  selected?: {
@@ -471,6 +475,51 @@ 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
+ /**
489
+ * `ordinary` ONLY when the mockup carries no `linkedAs` (an allowlist): any other value is never an ordinary picture.
490
+ * `size-picture` holds the role for its size; `other` is every other mark, e.g. 'size-picture-released' (a pattern
491
+ * picture that handed its size's role to a lay-flat, rendercenter linker #4487) or a role added later: never shown in
492
+ * the gallery, never returned by an ordinary-picture lookup.
493
+ */
494
+ type MockupRole = "ordinary" | typeof SIZE_PICTURE | "other";
495
+ type WithRole = {
496
+ id?: unknown;
497
+ linkedAs?: unknown;
498
+ };
499
+ type WithGvids = {
500
+ id?: string;
501
+ gvids?: string[] | null;
502
+ };
503
+ declare function mockupRole(m: WithRole | null | undefined): MockupRole;
504
+ declare const ORDINARY: unique symbol;
505
+ /** A product's ordinary pictures (never a size picture). Only `ordinaryMockups` makes one. */
506
+ type OrdinaryMockups<T> = readonly T[] & {
507
+ readonly [ORDINARY]: true;
508
+ };
509
+ declare function ordinaryMockups<T extends WithRole>(mockups: readonly T[] | null | undefined): OrdinaryMockups<T>;
510
+ /**
511
+ * The picture for a variant: the first ordinary mockup that lists it, else the product's first ordinary mockup (its
512
+ * fallback picture), else null. Never a size picture, even when a size picture is the only mockup listing the variant.
513
+ */
514
+ declare function pictureForVariant<T extends WithRole & WithGvids>(mockups: readonly T[] | null | undefined, variantId: string | null | undefined): T | null;
515
+ /** The product's picture for cards, links and previews: its first ordinary mockup. Never a size picture. */
516
+ declare function primaryMockup<T extends WithRole>(mockups: readonly T[] | null | undefined): T | null;
517
+ /**
518
+ * The ONE size picture the gallery shows: the size picture whose gvids list the chosen variant, or null (no size
519
+ * pictures, or none for this size: never another size's picture).
520
+ */
521
+ declare function gallerySizePicture<T extends WithRole & WithGvids>(mockups: readonly T[] | null | undefined, selectedVariantId: string | null | undefined): T | null;
522
+
474
523
  /**
475
524
  * Framework-agnostic state management utilities
476
525
  * Provides consistent state management patterns for React and Web Components
@@ -1057,6 +1106,7 @@ declare function getVariant(selection: UserSelection, product: {
1057
1106
  mockups: Array<{
1058
1107
  id: string;
1059
1108
  gvids?: string[];
1109
+ linkedAs?: unknown;
1060
1110
  }>;
1061
1111
  attributes?: Record<string, any>;
1062
1112
  }): {
@@ -3436,4 +3486,4 @@ declare function searchDesigns(query?: string, options?: SearchDesignsOptions):
3436
3486
  */
3437
3487
  declare function createClient(config: SdkConfig): SnowconeClient;
3438
3488
 
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 };
3489
+ 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 };