@snowcone-app/sdk 0.24.4 → 0.26.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,19 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.26.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#4415](https://github.com/snowcone-app/snowcone-monorepo/pull/4415) [`ccc4cf3`](https://github.com/snowcone-app/snowcone-monorepo/commit/ccc4cf371c5f4845e679b8c295e0335881664e96) Thanks [@kevinsproles](https://github.com/kevinsproles)! - The SDK reports `isFrameSuperseded(url)`: true once a newer ws frame for the same mockup has arrived and the old one was revoked. The UI uses it when a cropped frame fails to load: a superseded frame is dropped at once instead of waiting on the 2 s grace, which a 31-picture batch can outlast (React only sees the newer frame with the batch's `all_mockups_rendered`). Before, the grace fired first, cropped delivery went off for the session and a visible picture could stay one version behind.
8
+
9
+ `all_mockups_rendered` now merges its batch into `mockupResults` instead of replacing it. A short batch (a `rerender` answer) landing right after a full one replaced it, React coalesced the two updates, and every other picture kept its previous version.
10
+
11
+ ## 0.25.0
12
+
13
+ ### Minor Changes
14
+
15
+ - [#4344](https://github.com/snowcone-app/snowcone-monorepo/pull/4344) [`379a042`](https://github.com/snowcone-app/snowcone-monorepo/commit/379a042eb69a26f98fe0050f694c4ccf342e55b8) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Per-placement render versions and an explicit re-render. SDK: `MockupResult.versions` (every placement folded into a frame, from boxes that stamp it), `getLatestSentVersions()`, and `rerender(mockupIds)` (answered by `rerender_queued`; refusals are typed `E_RERENDER_*` errors). UI: a picture's `data-render-state` is `current` only when every placement is at its latest sent version, and a picture whose cropped frame failed is re-rendered with `rerender` once the box stamps versions (falling back to forcing it with configs on an `E_RERENDER_*` refusal or an older box).
16
+
3
17
  ## 0.24.4
4
18
 
5
19
  ### Patch Changes
@@ -88,6 +88,9 @@ 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
+ // Live frames a newer frame for the same mockup has replaced (and revoked), newest last, bounded. Lets a consumer
92
+ // still loading an old frame tell "superseded" from "broken" the moment it fails (isFrameSuperseded).
93
+ supersededFrameUrls = /* @__PURE__ */ new Set();
91
94
  renewTimer = null;
92
95
  isConnecting = false;
93
96
  connectAttempt = 0;
@@ -262,6 +265,9 @@ var RealtimeMockupService = class {
262
265
  case "have_all_blobs":
263
266
  this.addLog("\u{1F389} All blobs received! Starting render...");
264
267
  break;
268
+ case "rerender_queued":
269
+ this.addLog(`\u{1F501} Re-render queued for [${(data.mockupIds ?? []).join(", ")}]`, "received");
270
+ break;
265
271
  case "rendering_started":
266
272
  this.addLog("\u{1F3A8} Mockup rendering has started...");
267
273
  break;
@@ -290,6 +296,7 @@ var RealtimeMockupService = class {
290
296
  requestId: data.requestId,
291
297
  requestVersion: responseVersion,
292
298
  placement: responsePlacement,
299
+ ...data.versions && typeof data.versions === "object" ? { versions: data.versions } : {},
293
300
  renderMs: data.renderMs,
294
301
  blobToRenderMs: data.blobToRenderMs,
295
302
  costUsd: data.costUsd,
@@ -334,7 +341,7 @@ var RealtimeMockupService = class {
334
341
  }
335
342
  return true;
336
343
  });
337
- this.mockupResults = freshMockups.map((mockup) => {
344
+ const batch = freshMockups.map((mockup) => {
338
345
  const existing = this.mockupResults.find(
339
346
  (m) => m.mockupId === mockup.mockupId && (mockup.requestId === void 0 || m.requestId === mockup.requestId)
340
347
  );
@@ -346,6 +353,11 @@ var RealtimeMockupService = class {
346
353
  }
347
354
  return merged;
348
355
  });
356
+ const batchById = new Map(batch.map((m) => [m.mockupId, m]));
357
+ this.mockupResults = [
358
+ ...this.mockupResults.map((m) => batchById.get(m.mockupId) ?? m),
359
+ ...batch.filter((m) => !this.mockupResults.some((e) => e.mockupId === m.mockupId))
360
+ ];
349
361
  this.lastError = null;
350
362
  this.renderError = null;
351
363
  this.addLog(`\u{1F389} All mockups rendered: ${freshMockups.length} fresh (${data.mockups.length - freshMockups.length} stale filtered)`);
@@ -407,7 +419,14 @@ var RealtimeMockupService = class {
407
419
  if (!frame) return;
408
420
  this.pendingFrames.delete(key);
409
421
  const prevLive = this.liveObjectUrls.get(data.mockupId);
410
- if (prevLive) URL.revokeObjectURL(prevLive);
422
+ if (prevLive) {
423
+ URL.revokeObjectURL(prevLive);
424
+ this.supersededFrameUrls.add(prevLive);
425
+ if (this.supersededFrameUrls.size > 512) {
426
+ const oldest = this.supersededFrameUrls.values().next().value;
427
+ if (oldest) this.supersededFrameUrls.delete(oldest);
428
+ }
429
+ }
411
430
  this.liveObjectUrls.set(data.mockupId, frame.objectUrl);
412
431
  data.imageUrl = frame.objectUrl;
413
432
  }
@@ -761,6 +780,33 @@ ${versionToSend}
761
780
  * send a frame belongs to — the pipeline-depth send policy counts a send
762
781
  * as landed when every mockup of its version has arrived.
763
782
  */
783
+ /** The latest canvas version sent per placement (copy). */
784
+ getLatestSentVersions() {
785
+ return { ...this.latestSentVersionByPlacement };
786
+ }
787
+ /**
788
+ * Re-render these mockups now from the session's current state (servers with
789
+ * the `rerender` message). Answered by `rerender_queued` and then one
790
+ * mockup_rendered per mockup; refusals arrive as typed errors
791
+ * (E_RERENDER_NOT_CONFIGURED | E_RERENDER_BAD_REQUEST | E_RERENDER_UNKNOWN_MOCKUP |
792
+ * E_RERENDER_INCOMPLETE | E_RERENDER_RATE_LIMITED). Never changes the
793
+ * session's mockupIds.
794
+ */
795
+ /**
796
+ * True when `url` was a ws-delivered frame for a mockup and a newer frame for that mockup has since arrived (the SDK
797
+ * revoked the old one). A consumer whose load of `url` failed uses this to tell supersession (the newer frame is
798
+ * already here; it reaches the results with its batch's all_mockups_rendered) from a real failure.
799
+ */
800
+ isFrameSuperseded(url) {
801
+ return this.supersededFrameUrls.has(url);
802
+ }
803
+ rerender(mockupIds) {
804
+ if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.config || mockupIds.length === 0) return false;
805
+ const { requestId, traceparent } = newRenderCorrelation();
806
+ this.ws.send(JSON.stringify({ type: "rerender", mockupIds, requestId, traceparent }));
807
+ this.addLog(`\u{1F501} Re-render requested for [${mockupIds.join(", ")}] (req ${requestId})`, "sent");
808
+ return true;
809
+ }
764
810
  getLastSentVersion() {
765
811
  return this.lastSentVersion;
766
812
  }
package/dist/index.cjs CHANGED
@@ -5118,6 +5118,9 @@ var RealtimeMockupService = class {
5118
5118
  pendingFrames = /* @__PURE__ */ new Map();
5119
5119
  // Last object URL handed out per mockup — revoked when replaced.
5120
5120
  liveObjectUrls = /* @__PURE__ */ new Map();
5121
+ // Live frames a newer frame for the same mockup has replaced (and revoked), newest last, bounded. Lets a consumer
5122
+ // still loading an old frame tell "superseded" from "broken" the moment it fails (isFrameSuperseded).
5123
+ supersededFrameUrls = /* @__PURE__ */ new Set();
5121
5124
  renewTimer = null;
5122
5125
  isConnecting = false;
5123
5126
  connectAttempt = 0;
@@ -5292,6 +5295,9 @@ var RealtimeMockupService = class {
5292
5295
  case "have_all_blobs":
5293
5296
  this.addLog("\u{1F389} All blobs received! Starting render...");
5294
5297
  break;
5298
+ case "rerender_queued":
5299
+ this.addLog(`\u{1F501} Re-render queued for [${(data.mockupIds ?? []).join(", ")}]`, "received");
5300
+ break;
5295
5301
  case "rendering_started":
5296
5302
  this.addLog("\u{1F3A8} Mockup rendering has started...");
5297
5303
  break;
@@ -5320,6 +5326,7 @@ var RealtimeMockupService = class {
5320
5326
  requestId: data.requestId,
5321
5327
  requestVersion: responseVersion,
5322
5328
  placement: responsePlacement,
5329
+ ...data.versions && typeof data.versions === "object" ? { versions: data.versions } : {},
5323
5330
  renderMs: data.renderMs,
5324
5331
  blobToRenderMs: data.blobToRenderMs,
5325
5332
  costUsd: data.costUsd,
@@ -5364,7 +5371,7 @@ var RealtimeMockupService = class {
5364
5371
  }
5365
5372
  return true;
5366
5373
  });
5367
- this.mockupResults = freshMockups.map((mockup) => {
5374
+ const batch = freshMockups.map((mockup) => {
5368
5375
  const existing = this.mockupResults.find(
5369
5376
  (m) => m.mockupId === mockup.mockupId && (mockup.requestId === void 0 || m.requestId === mockup.requestId)
5370
5377
  );
@@ -5376,6 +5383,11 @@ var RealtimeMockupService = class {
5376
5383
  }
5377
5384
  return merged;
5378
5385
  });
5386
+ const batchById = new Map(batch.map((m) => [m.mockupId, m]));
5387
+ this.mockupResults = [
5388
+ ...this.mockupResults.map((m) => batchById.get(m.mockupId) ?? m),
5389
+ ...batch.filter((m) => !this.mockupResults.some((e) => e.mockupId === m.mockupId))
5390
+ ];
5379
5391
  this.lastError = null;
5380
5392
  this.renderError = null;
5381
5393
  this.addLog(`\u{1F389} All mockups rendered: ${freshMockups.length} fresh (${data.mockups.length - freshMockups.length} stale filtered)`);
@@ -5437,7 +5449,14 @@ var RealtimeMockupService = class {
5437
5449
  if (!frame) return;
5438
5450
  this.pendingFrames.delete(key);
5439
5451
  const prevLive = this.liveObjectUrls.get(data.mockupId);
5440
- if (prevLive) URL.revokeObjectURL(prevLive);
5452
+ if (prevLive) {
5453
+ URL.revokeObjectURL(prevLive);
5454
+ this.supersededFrameUrls.add(prevLive);
5455
+ if (this.supersededFrameUrls.size > 512) {
5456
+ const oldest = this.supersededFrameUrls.values().next().value;
5457
+ if (oldest) this.supersededFrameUrls.delete(oldest);
5458
+ }
5459
+ }
5441
5460
  this.liveObjectUrls.set(data.mockupId, frame.objectUrl);
5442
5461
  data.imageUrl = frame.objectUrl;
5443
5462
  }
@@ -5791,6 +5810,33 @@ ${versionToSend}
5791
5810
  * send a frame belongs to — the pipeline-depth send policy counts a send
5792
5811
  * as landed when every mockup of its version has arrived.
5793
5812
  */
5813
+ /** The latest canvas version sent per placement (copy). */
5814
+ getLatestSentVersions() {
5815
+ return { ...this.latestSentVersionByPlacement };
5816
+ }
5817
+ /**
5818
+ * Re-render these mockups now from the session's current state (servers with
5819
+ * the `rerender` message). Answered by `rerender_queued` and then one
5820
+ * mockup_rendered per mockup; refusals arrive as typed errors
5821
+ * (E_RERENDER_NOT_CONFIGURED | E_RERENDER_BAD_REQUEST | E_RERENDER_UNKNOWN_MOCKUP |
5822
+ * E_RERENDER_INCOMPLETE | E_RERENDER_RATE_LIMITED). Never changes the
5823
+ * session's mockupIds.
5824
+ */
5825
+ /**
5826
+ * True when `url` was a ws-delivered frame for a mockup and a newer frame for that mockup has since arrived (the SDK
5827
+ * revoked the old one). A consumer whose load of `url` failed uses this to tell supersession (the newer frame is
5828
+ * already here; it reaches the results with its batch's all_mockups_rendered) from a real failure.
5829
+ */
5830
+ isFrameSuperseded(url) {
5831
+ return this.supersededFrameUrls.has(url);
5832
+ }
5833
+ rerender(mockupIds) {
5834
+ if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.config || mockupIds.length === 0) return false;
5835
+ const { requestId, traceparent } = newRenderCorrelation();
5836
+ this.ws.send(JSON.stringify({ type: "rerender", mockupIds, requestId, traceparent }));
5837
+ this.addLog(`\u{1F501} Re-render requested for [${mockupIds.join(", ")}] (req ${requestId})`, "sent");
5838
+ return true;
5839
+ }
5794
5840
  getLastSentVersion() {
5795
5841
  return this.lastSentVersion;
5796
5842
  }
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-BYnhkMSH.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-BYnhkMSH.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-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';
5
5
 
6
6
  interface CatalogProduct {
7
7
  id: string;
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-BYnhkMSH.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-BYnhkMSH.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-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';
5
5
 
6
6
  interface CatalogProduct {
7
7
  id: string;
package/dist/index.js CHANGED
@@ -4,7 +4,7 @@ import {
4
4
  import {
5
5
  REALTIME_WS_URL,
6
6
  RealtimeMockupService
7
- } from "./chunk-FQC2FPV7.js";
7
+ } from "./chunk-4NCMFK5L.js";
8
8
  import {
9
9
  buildMockupUrl,
10
10
  buildPublicMockupUrl,
package/dist/react.cjs CHANGED
@@ -122,6 +122,9 @@ var RealtimeMockupService = class {
122
122
  pendingFrames = /* @__PURE__ */ new Map();
123
123
  // Last object URL handed out per mockup — revoked when replaced.
124
124
  liveObjectUrls = /* @__PURE__ */ new Map();
125
+ // Live frames a newer frame for the same mockup has replaced (and revoked), newest last, bounded. Lets a consumer
126
+ // still loading an old frame tell "superseded" from "broken" the moment it fails (isFrameSuperseded).
127
+ supersededFrameUrls = /* @__PURE__ */ new Set();
125
128
  renewTimer = null;
126
129
  isConnecting = false;
127
130
  connectAttempt = 0;
@@ -296,6 +299,9 @@ var RealtimeMockupService = class {
296
299
  case "have_all_blobs":
297
300
  this.addLog("\u{1F389} All blobs received! Starting render...");
298
301
  break;
302
+ case "rerender_queued":
303
+ this.addLog(`\u{1F501} Re-render queued for [${(data.mockupIds ?? []).join(", ")}]`, "received");
304
+ break;
299
305
  case "rendering_started":
300
306
  this.addLog("\u{1F3A8} Mockup rendering has started...");
301
307
  break;
@@ -324,6 +330,7 @@ var RealtimeMockupService = class {
324
330
  requestId: data.requestId,
325
331
  requestVersion: responseVersion,
326
332
  placement: responsePlacement,
333
+ ...data.versions && typeof data.versions === "object" ? { versions: data.versions } : {},
327
334
  renderMs: data.renderMs,
328
335
  blobToRenderMs: data.blobToRenderMs,
329
336
  costUsd: data.costUsd,
@@ -368,7 +375,7 @@ var RealtimeMockupService = class {
368
375
  }
369
376
  return true;
370
377
  });
371
- this.mockupResults = freshMockups.map((mockup) => {
378
+ const batch = freshMockups.map((mockup) => {
372
379
  const existing = this.mockupResults.find(
373
380
  (m) => m.mockupId === mockup.mockupId && (mockup.requestId === void 0 || m.requestId === mockup.requestId)
374
381
  );
@@ -380,6 +387,11 @@ var RealtimeMockupService = class {
380
387
  }
381
388
  return merged;
382
389
  });
390
+ const batchById = new Map(batch.map((m) => [m.mockupId, m]));
391
+ this.mockupResults = [
392
+ ...this.mockupResults.map((m) => batchById.get(m.mockupId) ?? m),
393
+ ...batch.filter((m) => !this.mockupResults.some((e) => e.mockupId === m.mockupId))
394
+ ];
383
395
  this.lastError = null;
384
396
  this.renderError = null;
385
397
  this.addLog(`\u{1F389} All mockups rendered: ${freshMockups.length} fresh (${data.mockups.length - freshMockups.length} stale filtered)`);
@@ -441,7 +453,14 @@ var RealtimeMockupService = class {
441
453
  if (!frame) return;
442
454
  this.pendingFrames.delete(key);
443
455
  const prevLive = this.liveObjectUrls.get(data.mockupId);
444
- if (prevLive) URL.revokeObjectURL(prevLive);
456
+ if (prevLive) {
457
+ URL.revokeObjectURL(prevLive);
458
+ this.supersededFrameUrls.add(prevLive);
459
+ if (this.supersededFrameUrls.size > 512) {
460
+ const oldest = this.supersededFrameUrls.values().next().value;
461
+ if (oldest) this.supersededFrameUrls.delete(oldest);
462
+ }
463
+ }
445
464
  this.liveObjectUrls.set(data.mockupId, frame.objectUrl);
446
465
  data.imageUrl = frame.objectUrl;
447
466
  }
@@ -795,6 +814,33 @@ ${versionToSend}
795
814
  * send a frame belongs to — the pipeline-depth send policy counts a send
796
815
  * as landed when every mockup of its version has arrived.
797
816
  */
817
+ /** The latest canvas version sent per placement (copy). */
818
+ getLatestSentVersions() {
819
+ return { ...this.latestSentVersionByPlacement };
820
+ }
821
+ /**
822
+ * Re-render these mockups now from the session's current state (servers with
823
+ * the `rerender` message). Answered by `rerender_queued` and then one
824
+ * mockup_rendered per mockup; refusals arrive as typed errors
825
+ * (E_RERENDER_NOT_CONFIGURED | E_RERENDER_BAD_REQUEST | E_RERENDER_UNKNOWN_MOCKUP |
826
+ * E_RERENDER_INCOMPLETE | E_RERENDER_RATE_LIMITED). Never changes the
827
+ * session's mockupIds.
828
+ */
829
+ /**
830
+ * True when `url` was a ws-delivered frame for a mockup and a newer frame for that mockup has since arrived (the SDK
831
+ * revoked the old one). A consumer whose load of `url` failed uses this to tell supersession (the newer frame is
832
+ * already here; it reaches the results with its batch's all_mockups_rendered) from a real failure.
833
+ */
834
+ isFrameSuperseded(url) {
835
+ return this.supersededFrameUrls.has(url);
836
+ }
837
+ rerender(mockupIds) {
838
+ if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.config || mockupIds.length === 0) return false;
839
+ const { requestId, traceparent } = newRenderCorrelation();
840
+ this.ws.send(JSON.stringify({ type: "rerender", mockupIds, requestId, traceparent }));
841
+ this.addLog(`\u{1F501} Re-render requested for [${mockupIds.join(", ")}] (req ${requestId})`, "sent");
842
+ return true;
843
+ }
798
844
  getLastSentVersion() {
799
845
  return this.lastSentVersion;
800
846
  }
@@ -1007,6 +1053,15 @@ function useRealtimeMockup(options = {}) {
1007
1053
  const hasPendingBlobs = (0, import_react.useCallback)(() => {
1008
1054
  return serviceRef.current?.hasPendingBlobs() || false;
1009
1055
  }, []);
1056
+ const getLatestSentVersions = (0, import_react.useCallback)(() => {
1057
+ return serviceRef.current?.getLatestSentVersions() ?? {};
1058
+ }, []);
1059
+ const rerender = (0, import_react.useCallback)((mockupIds) => {
1060
+ return serviceRef.current?.rerender(mockupIds) ?? false;
1061
+ }, []);
1062
+ const isFrameSuperseded = (0, import_react.useCallback)((url) => {
1063
+ return serviceRef.current?.isFrameSuperseded(url) ?? false;
1064
+ }, []);
1010
1065
  const getLastSentVersion = (0, import_react.useCallback)(() => {
1011
1066
  return serviceRef.current?.getLastSentVersion() ?? 0;
1012
1067
  }, []);
@@ -1028,7 +1083,10 @@ function useRealtimeMockup(options = {}) {
1028
1083
  clearMockups,
1029
1084
  flushPendingBlobs,
1030
1085
  hasPendingBlobs,
1031
- getLastSentVersion
1086
+ getLastSentVersion,
1087
+ getLatestSentVersions,
1088
+ rerender,
1089
+ isFrameSuperseded
1032
1090
  };
1033
1091
  }
1034
1092
 
package/dist/react.d.cts CHANGED
@@ -1,4 +1,4 @@
1
- import { M as MockupResult, R as RealtimeRenderError, W as WebSocketConfig, P as PlacementSettings, F as FrameworkAdapter, b as ComponentProps, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, c as ComponentDescriptor, g as FrameworkUtilities } from './websocket-BYnhkMSH.cjs';
1
+ import { M as MockupResult, R as RealtimeRenderError, W as WebSocketConfig, P as PlacementSettings, F as FrameworkAdapter, b as ComponentProps, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, c as ComponentDescriptor, g as FrameworkUtilities } from './websocket-CTbhT64Y.cjs';
2
2
  import { CSSProperties, ReactNode } from 'react';
3
3
 
4
4
  interface UseRealtimeMockupOptions {
@@ -54,6 +54,9 @@ declare function useRealtimeMockup(options?: UseRealtimeMockupOptions): {
54
54
  flushPendingBlobs: () => void;
55
55
  hasPendingBlobs: () => boolean;
56
56
  getLastSentVersion: () => number;
57
+ getLatestSentVersions: () => Record<string, number>;
58
+ rerender: (mockupIds: string[]) => boolean;
59
+ isFrameSuperseded: (url: string) => boolean;
57
60
  isConnected: boolean;
58
61
  sessionId: string | null;
59
62
  box: string | null;
package/dist/react.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { M as MockupResult, R as RealtimeRenderError, W as WebSocketConfig, P as PlacementSettings, F as FrameworkAdapter, b as ComponentProps, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, c as ComponentDescriptor, g as FrameworkUtilities } from './websocket-BYnhkMSH.js';
1
+ import { M as MockupResult, R as RealtimeRenderError, W as WebSocketConfig, P as PlacementSettings, F as FrameworkAdapter, b as ComponentProps, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, c as ComponentDescriptor, g as FrameworkUtilities } from './websocket-CTbhT64Y.js';
2
2
  import { CSSProperties, ReactNode } from 'react';
3
3
 
4
4
  interface UseRealtimeMockupOptions {
@@ -54,6 +54,9 @@ declare function useRealtimeMockup(options?: UseRealtimeMockupOptions): {
54
54
  flushPendingBlobs: () => void;
55
55
  hasPendingBlobs: () => boolean;
56
56
  getLastSentVersion: () => number;
57
+ getLatestSentVersions: () => Record<string, number>;
58
+ rerender: (mockupIds: string[]) => boolean;
59
+ isFrameSuperseded: (url: string) => boolean;
57
60
  isConnected: boolean;
58
61
  sessionId: string | null;
59
62
  box: string | null;
package/dist/react.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import {
2
2
  RealtimeMockupService
3
- } from "./chunk-FQC2FPV7.js";
3
+ } from "./chunk-4NCMFK5L.js";
4
4
 
5
5
  // src/realtime/react.ts
6
6
  import { useCallback, useEffect, useRef, useState } from "react";
@@ -117,6 +117,15 @@ function useRealtimeMockup(options = {}) {
117
117
  const hasPendingBlobs = useCallback(() => {
118
118
  return serviceRef.current?.hasPendingBlobs() || false;
119
119
  }, []);
120
+ const getLatestSentVersions = useCallback(() => {
121
+ return serviceRef.current?.getLatestSentVersions() ?? {};
122
+ }, []);
123
+ const rerender = useCallback((mockupIds) => {
124
+ return serviceRef.current?.rerender(mockupIds) ?? false;
125
+ }, []);
126
+ const isFrameSuperseded = useCallback((url) => {
127
+ return serviceRef.current?.isFrameSuperseded(url) ?? false;
128
+ }, []);
120
129
  const getLastSentVersion = useCallback(() => {
121
130
  return serviceRef.current?.getLastSentVersion() ?? 0;
122
131
  }, []);
@@ -138,7 +147,10 @@ function useRealtimeMockup(options = {}) {
138
147
  clearMockups,
139
148
  flushPendingBlobs,
140
149
  hasPendingBlobs,
141
- getLastSentVersion
150
+ getLastSentVersion,
151
+ getLatestSentVersions,
152
+ rerender,
153
+ isFrameSuperseded
142
154
  };
143
155
  }
144
156
 
@@ -303,6 +303,14 @@ interface MockupResult {
303
303
  requestVersion?: number;
304
304
  /** The placement this mockup corresponds to */
305
305
  placement?: string;
306
+ /**
307
+ * Every canvas_state placement folded into this frame, with the version the
308
+ * box used for it (servers with per-placement stamps; then `requestVersion`
309
+ * is their max). A frame is current when, for every placement this session
310
+ * sent, `versions[placement]` is at least the latest version sent for it
311
+ * (see {@link RealtimeMockupService.getLatestSentVersions}).
312
+ */
313
+ versions?: Record<string, number>;
306
314
  /** Server-side render time in ms */
307
315
  renderMs?: number;
308
316
  /** Time from blob received to render start in ms */
@@ -349,6 +357,10 @@ interface WebSocketMessage {
349
357
  imageUrl?: string;
350
358
  renderUrl?: string;
351
359
  mockupId?: string;
360
+ /** `rerender_queued`: the mockups the box queued. */
361
+ mockupIds?: string[];
362
+ /** Per-placement versions folded into a frame (see MockupResult.versions). */
363
+ versions?: Record<string, number>;
352
364
  imageSize?: number;
353
365
  message?: string;
354
366
  /** Machine-readable error code on `type: 'error'` frames (e.g. 'asset_not_allowed') */
@@ -490,6 +502,7 @@ declare class RealtimeMockupService {
490
502
  private tokenProvider?;
491
503
  private pendingFrames;
492
504
  private liveObjectUrls;
505
+ private supersededFrameUrls;
493
506
  private renewTimer;
494
507
  private isConnecting;
495
508
  private connectAttempt;
@@ -568,6 +581,23 @@ declare class RealtimeMockupService {
568
581
  * send a frame belongs to — the pipeline-depth send policy counts a send
569
582
  * as landed when every mockup of its version has arrived.
570
583
  */
584
+ /** The latest canvas version sent per placement (copy). */
585
+ getLatestSentVersions(): Record<string, number>;
586
+ /**
587
+ * Re-render these mockups now from the session's current state (servers with
588
+ * the `rerender` message). Answered by `rerender_queued` and then one
589
+ * mockup_rendered per mockup; refusals arrive as typed errors
590
+ * (E_RERENDER_NOT_CONFIGURED | E_RERENDER_BAD_REQUEST | E_RERENDER_UNKNOWN_MOCKUP |
591
+ * E_RERENDER_INCOMPLETE | E_RERENDER_RATE_LIMITED). Never changes the
592
+ * session's mockupIds.
593
+ */
594
+ /**
595
+ * True when `url` was a ws-delivered frame for a mockup and a newer frame for that mockup has since arrived (the SDK
596
+ * revoked the old one). A consumer whose load of `url` failed uses this to tell supersession (the newer frame is
597
+ * already here; it reaches the results with its batch's all_mockups_rendered) from a real failure.
598
+ */
599
+ isFrameSuperseded(url: string): boolean;
600
+ rerender(mockupIds: string[]): boolean;
571
601
  getLastSentVersion(): number;
572
602
  sendColorBlob(placement: string, hexColor: string): boolean;
573
603
  createEmptyCanvasBlob(width?: number, height?: number): Promise<Blob>;
@@ -303,6 +303,14 @@ interface MockupResult {
303
303
  requestVersion?: number;
304
304
  /** The placement this mockup corresponds to */
305
305
  placement?: string;
306
+ /**
307
+ * Every canvas_state placement folded into this frame, with the version the
308
+ * box used for it (servers with per-placement stamps; then `requestVersion`
309
+ * is their max). A frame is current when, for every placement this session
310
+ * sent, `versions[placement]` is at least the latest version sent for it
311
+ * (see {@link RealtimeMockupService.getLatestSentVersions}).
312
+ */
313
+ versions?: Record<string, number>;
306
314
  /** Server-side render time in ms */
307
315
  renderMs?: number;
308
316
  /** Time from blob received to render start in ms */
@@ -349,6 +357,10 @@ interface WebSocketMessage {
349
357
  imageUrl?: string;
350
358
  renderUrl?: string;
351
359
  mockupId?: string;
360
+ /** `rerender_queued`: the mockups the box queued. */
361
+ mockupIds?: string[];
362
+ /** Per-placement versions folded into a frame (see MockupResult.versions). */
363
+ versions?: Record<string, number>;
352
364
  imageSize?: number;
353
365
  message?: string;
354
366
  /** Machine-readable error code on `type: 'error'` frames (e.g. 'asset_not_allowed') */
@@ -490,6 +502,7 @@ declare class RealtimeMockupService {
490
502
  private tokenProvider?;
491
503
  private pendingFrames;
492
504
  private liveObjectUrls;
505
+ private supersededFrameUrls;
493
506
  private renewTimer;
494
507
  private isConnecting;
495
508
  private connectAttempt;
@@ -568,6 +581,23 @@ declare class RealtimeMockupService {
568
581
  * send a frame belongs to — the pipeline-depth send policy counts a send
569
582
  * as landed when every mockup of its version has arrived.
570
583
  */
584
+ /** The latest canvas version sent per placement (copy). */
585
+ getLatestSentVersions(): Record<string, number>;
586
+ /**
587
+ * Re-render these mockups now from the session's current state (servers with
588
+ * the `rerender` message). Answered by `rerender_queued` and then one
589
+ * mockup_rendered per mockup; refusals arrive as typed errors
590
+ * (E_RERENDER_NOT_CONFIGURED | E_RERENDER_BAD_REQUEST | E_RERENDER_UNKNOWN_MOCKUP |
591
+ * E_RERENDER_INCOMPLETE | E_RERENDER_RATE_LIMITED). Never changes the
592
+ * session's mockupIds.
593
+ */
594
+ /**
595
+ * True when `url` was a ws-delivered frame for a mockup and a newer frame for that mockup has since arrived (the SDK
596
+ * revoked the old one). A consumer whose load of `url` failed uses this to tell supersession (the newer frame is
597
+ * already here; it reaches the results with its batch's all_mockups_rendered) from a real failure.
598
+ */
599
+ isFrameSuperseded(url: string): boolean;
600
+ rerender(mockupIds: string[]): boolean;
571
601
  getLastSentVersion(): number;
572
602
  sendColorBlob(placement: string, hexColor: string): boolean;
573
603
  createEmptyCanvasBlob(width?: number, height?: number): Promise<Blob>;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@snowcone-app/sdk",
3
- "version": "0.24.4",
3
+ "version": "0.26.0",
4
4
  "description": "Snowcone SDK for product mockups and print-on-demand",
5
5
  "keywords": [
6
6
  "merch",