@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 +19 -0
- package/dist/{chunk-4NCMFK5L.js → chunk-IW7DXXGY.js} +78 -0
- package/dist/index.cjs +127 -15
- package/dist/index.d.cts +53 -3
- package/dist/index.d.ts +53 -3
- package/dist/index.js +44 -16
- package/dist/react.cjs +98 -2
- package/dist/react.d.cts +5 -1
- package/dist/react.d.ts +5 -1
- package/dist/react.js +21 -3
- package/dist/{websocket-CTbhT64Y.d.cts → websocket-CvN0UU2j.d.cts} +58 -1
- package/dist/{websocket-CTbhT64Y.d.ts → websocket-CvN0UU2j.d.ts} +58 -1
- package/package.json +1 -1
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({
|
|
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
|
-
|
|
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
|
-
|
|
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-
|
|
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-
|
|
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-
|
|
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-
|
|
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 };
|