@snowcone-app/sdk 0.20.3 → 0.23.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,23 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.23.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#2249](https://github.com/snowcone-app/snowcone-monorepo/pull/2249) [`19f7ee5`](https://github.com/snowcone-app/snowcone-monorepo/commit/19f7ee583638ccedd8fd5f309ad3e5ba6a06c0f9) Thanks [@kevinsproles](https://github.com/kevinsproles)! - A mockup whose scene failed render parity is refused by the server (`E_MOCKUP_NOT_BLESSED`) instead of silently rendering on the slow path. `RealtimeRenderError` gains `mockupId` for per-mockup errors; `RealtimeProvider` exposes `unavailableMockups` (mockupId → error) and `HeroProductImage` shows that mockup as unavailable (`data-mockup-unavailable`) while the others keep streaming.
8
+
9
+ ## 0.22.0
10
+
11
+ ### Minor Changes
12
+
13
+ - [#2240](https://github.com/snowcone-app/snowcone-monorepo/pull/2240) [`61c4826`](https://github.com/snowcone-app/snowcone-monorepo/commit/61c48267d77b93628ef525df5a6aee66421d67f7) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Realtime send policy: pipeline depth two. `CanvasExportService` now keeps up to two edits in flight (`maxInFlight`, default 2) before holding the latest state — the box's window is ~30 ms of a ~96 ms edit→frame, so one in flight left it idle ~70% of every drag cycle. `RealtimeProvider` settles once per landed send (every mockup of a `requestVersion`) instead of on the first frame after any send, using the SDK's new `getLastSentVersion()` on the realtime service and hook.
14
+
15
+ ## 0.21.0
16
+
17
+ ### Minor Changes
18
+
19
+ - [#2223](https://github.com/snowcone-app/snowcone-monorepo/pull/2223) [`aaa73cc`](https://github.com/snowcone-app/snowcone-monorepo/commit/aaa73ccb4b2d4c7c107b66f18be29f67032422b8) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Realtime frames now carry their own timing. Every `MockupResult` gets `rtTiming` (the render node's per-frame Server-Timing envelope: receive → guard → canvas raster → coalesce wait → composite → store → deliver, with byte sizes and the box id), `clientRoundTripMs` (the canvas_state send this frame answers → its arrival, as the client saw it) and `imageDelivery` ('ws' | 'url'). `onConnected` receives `{ box }` and `getState().box` names the render node that answered the handshake.
20
+
3
21
  ## 0.20.3
4
22
 
5
23
  ### Patch Changes
@@ -85,6 +85,7 @@ var ALLOWED_WIDTHS = [
85
85
  3e3,
86
86
  4e3
87
87
  ];
88
+ var MAX_RENDER_URL_LENGTH = 12 * 1024;
88
89
  function normalizeWidth(width) {
89
90
  for (let i = ALLOWED_WIDTHS.length - 1; i >= 0; i--) {
90
91
  if (ALLOWED_WIDTHS[i] <= width) return ALLOWED_WIDTHS[i];
@@ -27,6 +27,9 @@ var RealtimeMockupService = class {
27
27
  config = null;
28
28
  configSent = false;
29
29
  sessionId = null;
30
+ // Render node that answered the handshake (`connected.box`), for labs and
31
+ // support: a realtime session has no response headers to read it from.
32
+ box = null;
30
33
  isConfigured = false;
31
34
  mockupResults = [];
32
35
  status = "Disconnected";
@@ -93,6 +96,7 @@ var RealtimeMockupService = class {
93
96
  return {
94
97
  isConnected: this.ws?.readyState === WebSocket.OPEN,
95
98
  sessionId: this.sessionId,
99
+ box: this.box,
96
100
  isConfigured: this.isConfigured,
97
101
  mockupResults: [...this.mockupResults],
98
102
  status: this.status,
@@ -158,6 +162,7 @@ var RealtimeMockupService = class {
158
162
  this.addLog(`WebSocket connection closed (code: ${event.code})`);
159
163
  this.status = "Disconnected";
160
164
  this.sessionId = null;
165
+ this.box = null;
161
166
  this.isConfigured = false;
162
167
  this.configSent = false;
163
168
  this.clearRenew();
@@ -197,10 +202,11 @@ var RealtimeMockupService = class {
197
202
  switch (data.type) {
198
203
  case "connected":
199
204
  this.sessionId = data.sessionId || null;
205
+ this.box = data.box ?? null;
200
206
  this.status = `Connected (Session: ${data.sessionId || "N/A"})`;
201
- this.addLog(`\u2705 Session established: ${data.sessionId}`);
207
+ this.addLog(`\u2705 Session established: ${data.sessionId}${this.box ? ` on ${this.box}` : ""}`);
202
208
  if (data.sessionId) {
203
- this.callbacks.onConnected?.(data.sessionId);
209
+ this.callbacks.onConnected?.(data.sessionId, { box: this.box ?? void 0 });
204
210
  }
205
211
  if (this.config && !this.configSent) {
206
212
  this.addLog("\u{1F4E4} Auto-sending cached config after connection...");
@@ -284,7 +290,10 @@ var RealtimeMockupService = class {
284
290
  renderCache: data.renderCache,
285
291
  cropRect: data.cropRect,
286
292
  serverTiming: data.serverTiming,
287
- canvasRenderTiming: data.canvasRenderTiming
293
+ canvasRenderTiming: data.canvasRenderTiming,
294
+ rtTiming: data.rtTiming,
295
+ clientRoundTripMs,
296
+ imageDelivery: data.imageDelivery === "ws" ? "ws" : "url"
288
297
  };
289
298
  const existingIndex = this.mockupResults.findIndex((m) => m.mockupId === data.mockupId);
290
299
  if (existingIndex >= 0) {
@@ -343,7 +352,8 @@ var RealtimeMockupService = class {
343
352
  const errorMessage = data.message || "Unknown error occurred";
344
353
  const renderError = {
345
354
  code: data.code || "render_error",
346
- message: errorMessage
355
+ message: errorMessage,
356
+ ...typeof data.mockupId === "string" ? { mockupId: data.mockupId } : {}
347
357
  };
348
358
  this.lastError = errorMessage;
349
359
  this.renderError = renderError;
@@ -739,6 +749,15 @@ ${versionToSend}
739
749
  hasPendingBlobs() {
740
750
  return Object.keys(this.throttleTimeouts).length > 0;
741
751
  }
752
+ /**
753
+ * Version stamped on the most recent canvas_state send (0 before any).
754
+ * Every frame answers with `requestVersion`, so a caller can tell which
755
+ * send a frame belongs to — the pipeline-depth send policy counts a send
756
+ * as landed when every mockup of its version has arrived.
757
+ */
758
+ getLastSentVersion() {
759
+ return this.lastSentVersion;
760
+ }
742
761
  sendColorBlob(placement, hexColor) {
743
762
  this.colors.set(placement, hexColor);
744
763
  if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.isConfigured) {
package/dist/index.cjs CHANGED
@@ -564,6 +564,7 @@ var ALLOWED_WIDTHS = [
564
564
  3e3,
565
565
  4e3
566
566
  ];
567
+ var MAX_RENDER_URL_LENGTH = 12 * 1024;
567
568
  function normalizeWidth(width) {
568
569
  for (let i = ALLOWED_WIDTHS.length - 1; i >= 0; i--) {
569
570
  if (ALLOWED_WIDTHS[i] <= width) return ALLOWED_WIDTHS[i];
@@ -5022,6 +5023,9 @@ var RealtimeMockupService = class {
5022
5023
  config = null;
5023
5024
  configSent = false;
5024
5025
  sessionId = null;
5026
+ // Render node that answered the handshake (`connected.box`), for labs and
5027
+ // support: a realtime session has no response headers to read it from.
5028
+ box = null;
5025
5029
  isConfigured = false;
5026
5030
  mockupResults = [];
5027
5031
  status = "Disconnected";
@@ -5088,6 +5092,7 @@ var RealtimeMockupService = class {
5088
5092
  return {
5089
5093
  isConnected: this.ws?.readyState === WebSocket.OPEN,
5090
5094
  sessionId: this.sessionId,
5095
+ box: this.box,
5091
5096
  isConfigured: this.isConfigured,
5092
5097
  mockupResults: [...this.mockupResults],
5093
5098
  status: this.status,
@@ -5153,6 +5158,7 @@ var RealtimeMockupService = class {
5153
5158
  this.addLog(`WebSocket connection closed (code: ${event.code})`);
5154
5159
  this.status = "Disconnected";
5155
5160
  this.sessionId = null;
5161
+ this.box = null;
5156
5162
  this.isConfigured = false;
5157
5163
  this.configSent = false;
5158
5164
  this.clearRenew();
@@ -5192,10 +5198,11 @@ var RealtimeMockupService = class {
5192
5198
  switch (data.type) {
5193
5199
  case "connected":
5194
5200
  this.sessionId = data.sessionId || null;
5201
+ this.box = data.box ?? null;
5195
5202
  this.status = `Connected (Session: ${data.sessionId || "N/A"})`;
5196
- this.addLog(`\u2705 Session established: ${data.sessionId}`);
5203
+ this.addLog(`\u2705 Session established: ${data.sessionId}${this.box ? ` on ${this.box}` : ""}`);
5197
5204
  if (data.sessionId) {
5198
- this.callbacks.onConnected?.(data.sessionId);
5205
+ this.callbacks.onConnected?.(data.sessionId, { box: this.box ?? void 0 });
5199
5206
  }
5200
5207
  if (this.config && !this.configSent) {
5201
5208
  this.addLog("\u{1F4E4} Auto-sending cached config after connection...");
@@ -5279,7 +5286,10 @@ var RealtimeMockupService = class {
5279
5286
  renderCache: data.renderCache,
5280
5287
  cropRect: data.cropRect,
5281
5288
  serverTiming: data.serverTiming,
5282
- canvasRenderTiming: data.canvasRenderTiming
5289
+ canvasRenderTiming: data.canvasRenderTiming,
5290
+ rtTiming: data.rtTiming,
5291
+ clientRoundTripMs,
5292
+ imageDelivery: data.imageDelivery === "ws" ? "ws" : "url"
5283
5293
  };
5284
5294
  const existingIndex = this.mockupResults.findIndex((m) => m.mockupId === data.mockupId);
5285
5295
  if (existingIndex >= 0) {
@@ -5338,7 +5348,8 @@ var RealtimeMockupService = class {
5338
5348
  const errorMessage = data.message || "Unknown error occurred";
5339
5349
  const renderError = {
5340
5350
  code: data.code || "render_error",
5341
- message: errorMessage
5351
+ message: errorMessage,
5352
+ ...typeof data.mockupId === "string" ? { mockupId: data.mockupId } : {}
5342
5353
  };
5343
5354
  this.lastError = errorMessage;
5344
5355
  this.renderError = renderError;
@@ -5734,6 +5745,15 @@ ${versionToSend}
5734
5745
  hasPendingBlobs() {
5735
5746
  return Object.keys(this.throttleTimeouts).length > 0;
5736
5747
  }
5748
+ /**
5749
+ * Version stamped on the most recent canvas_state send (0 before any).
5750
+ * Every frame answers with `requestVersion`, so a caller can tell which
5751
+ * send a frame belongs to — the pipeline-depth send policy counts a send
5752
+ * as landed when every mockup of its version has arrived.
5753
+ */
5754
+ getLastSentVersion() {
5755
+ return this.lastSentVersion;
5756
+ }
5737
5757
  sendColorBlob(placement, hexColor) {
5738
5758
  this.colors.set(placement, hexColor);
5739
5759
  if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.isConfigured) {
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-CScS7UR-.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-CScS7UR-.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-DjAOhBaN.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-DjAOhBaN.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-CScS7UR-.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-CScS7UR-.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-DjAOhBaN.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-DjAOhBaN.js';
5
5
 
6
6
  interface CatalogProduct {
7
7
  id: string;
package/dist/index.js CHANGED
@@ -4,14 +4,14 @@ import {
4
4
  import {
5
5
  REALTIME_WS_URL,
6
6
  RealtimeMockupService
7
- } from "./chunk-SZZQ2CBF.js";
7
+ } from "./chunk-P3ZYTA5F.js";
8
8
  import {
9
9
  buildMockupUrl,
10
10
  buildPublicMockupUrl,
11
11
  canonicalForSig,
12
12
  normalizeDesignElements,
13
13
  normalizeWidth
14
- } from "./chunk-553YYMDY.js";
14
+ } from "./chunk-FPR6ABXM.js";
15
15
 
16
16
  // src/validation.ts
17
17
  import { z } from "zod";
package/dist/react.cjs CHANGED
@@ -61,6 +61,9 @@ var RealtimeMockupService = class {
61
61
  config = null;
62
62
  configSent = false;
63
63
  sessionId = null;
64
+ // Render node that answered the handshake (`connected.box`), for labs and
65
+ // support: a realtime session has no response headers to read it from.
66
+ box = null;
64
67
  isConfigured = false;
65
68
  mockupResults = [];
66
69
  status = "Disconnected";
@@ -127,6 +130,7 @@ var RealtimeMockupService = class {
127
130
  return {
128
131
  isConnected: this.ws?.readyState === WebSocket.OPEN,
129
132
  sessionId: this.sessionId,
133
+ box: this.box,
130
134
  isConfigured: this.isConfigured,
131
135
  mockupResults: [...this.mockupResults],
132
136
  status: this.status,
@@ -192,6 +196,7 @@ var RealtimeMockupService = class {
192
196
  this.addLog(`WebSocket connection closed (code: ${event.code})`);
193
197
  this.status = "Disconnected";
194
198
  this.sessionId = null;
199
+ this.box = null;
195
200
  this.isConfigured = false;
196
201
  this.configSent = false;
197
202
  this.clearRenew();
@@ -231,10 +236,11 @@ var RealtimeMockupService = class {
231
236
  switch (data.type) {
232
237
  case "connected":
233
238
  this.sessionId = data.sessionId || null;
239
+ this.box = data.box ?? null;
234
240
  this.status = `Connected (Session: ${data.sessionId || "N/A"})`;
235
- this.addLog(`\u2705 Session established: ${data.sessionId}`);
241
+ this.addLog(`\u2705 Session established: ${data.sessionId}${this.box ? ` on ${this.box}` : ""}`);
236
242
  if (data.sessionId) {
237
- this.callbacks.onConnected?.(data.sessionId);
243
+ this.callbacks.onConnected?.(data.sessionId, { box: this.box ?? void 0 });
238
244
  }
239
245
  if (this.config && !this.configSent) {
240
246
  this.addLog("\u{1F4E4} Auto-sending cached config after connection...");
@@ -318,7 +324,10 @@ var RealtimeMockupService = class {
318
324
  renderCache: data.renderCache,
319
325
  cropRect: data.cropRect,
320
326
  serverTiming: data.serverTiming,
321
- canvasRenderTiming: data.canvasRenderTiming
327
+ canvasRenderTiming: data.canvasRenderTiming,
328
+ rtTiming: data.rtTiming,
329
+ clientRoundTripMs,
330
+ imageDelivery: data.imageDelivery === "ws" ? "ws" : "url"
322
331
  };
323
332
  const existingIndex = this.mockupResults.findIndex((m) => m.mockupId === data.mockupId);
324
333
  if (existingIndex >= 0) {
@@ -377,7 +386,8 @@ var RealtimeMockupService = class {
377
386
  const errorMessage = data.message || "Unknown error occurred";
378
387
  const renderError = {
379
388
  code: data.code || "render_error",
380
- message: errorMessage
389
+ message: errorMessage,
390
+ ...typeof data.mockupId === "string" ? { mockupId: data.mockupId } : {}
381
391
  };
382
392
  this.lastError = errorMessage;
383
393
  this.renderError = renderError;
@@ -773,6 +783,15 @@ ${versionToSend}
773
783
  hasPendingBlobs() {
774
784
  return Object.keys(this.throttleTimeouts).length > 0;
775
785
  }
786
+ /**
787
+ * Version stamped on the most recent canvas_state send (0 before any).
788
+ * Every frame answers with `requestVersion`, so a caller can tell which
789
+ * send a frame belongs to — the pipeline-depth send policy counts a send
790
+ * as landed when every mockup of its version has arrived.
791
+ */
792
+ getLastSentVersion() {
793
+ return this.lastSentVersion;
794
+ }
776
795
  sendColorBlob(placement, hexColor) {
777
796
  this.colors.set(placement, hexColor);
778
797
  if (!this.ws || this.ws.readyState !== WebSocket.OPEN || !this.isConfigured) {
@@ -878,6 +897,7 @@ function useRealtimeMockup(options = {}) {
878
897
  const [state, setState] = (0, import_react.useState)({
879
898
  isConnected: false,
880
899
  sessionId: null,
900
+ box: null,
881
901
  isConfigured: false,
882
902
  mockupResults: [],
883
903
  status: "Disconnected",
@@ -889,9 +909,9 @@ function useRealtimeMockup(options = {}) {
889
909
  const service = new RealtimeMockupService(wsUrl);
890
910
  serviceRef.current = service;
891
911
  service.setCallbacks({
892
- onConnected: (sessionId) => {
912
+ onConnected: (sessionId, info) => {
893
913
  setState(service.getState());
894
- options.onConnected?.(sessionId);
914
+ options.onConnected?.(sessionId, info);
895
915
  },
896
916
  onDisconnected: () => {
897
917
  setState(service.getState());
@@ -981,6 +1001,9 @@ function useRealtimeMockup(options = {}) {
981
1001
  const hasPendingBlobs = (0, import_react.useCallback)(() => {
982
1002
  return serviceRef.current?.hasPendingBlobs() || false;
983
1003
  }, []);
1004
+ const getLastSentVersion = (0, import_react.useCallback)(() => {
1005
+ return serviceRef.current?.getLastSentVersion() ?? 0;
1006
+ }, []);
984
1007
  return {
985
1008
  ...state,
986
1009
  connect,
@@ -998,7 +1021,8 @@ function useRealtimeMockup(options = {}) {
998
1021
  clearLogs,
999
1022
  clearMockups,
1000
1023
  flushPendingBlobs,
1001
- hasPendingBlobs
1024
+ hasPendingBlobs,
1025
+ getLastSentVersion
1002
1026
  };
1003
1027
  }
1004
1028
 
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-CScS7UR-.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-DjAOhBaN.cjs';
2
2
  import { CSSProperties, ReactNode } from 'react';
3
3
 
4
4
  interface UseRealtimeMockupOptions {
@@ -13,7 +13,9 @@ interface UseRealtimeMockupOptions {
13
13
  token: string;
14
14
  expiresAt: number;
15
15
  }>;
16
- onConnected?: (sessionId: string) => void;
16
+ onConnected?: (sessionId: string, info: {
17
+ box?: string;
18
+ }) => void;
17
19
  onDisconnected?: () => void;
18
20
  onConfigReceived?: () => void;
19
21
  /** Called when server confirms it received a blob for a placement */
@@ -51,8 +53,10 @@ declare function useRealtimeMockup(options?: UseRealtimeMockupOptions): {
51
53
  clearMockups: () => void;
52
54
  flushPendingBlobs: () => void;
53
55
  hasPendingBlobs: () => boolean;
56
+ getLastSentVersion: () => number;
54
57
  isConnected: boolean;
55
58
  sessionId: string | null;
59
+ box: string | null;
56
60
  isConfigured: boolean;
57
61
  mockupResults: MockupResult[];
58
62
  status: string;
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-CScS7UR-.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-DjAOhBaN.js';
2
2
  import { CSSProperties, ReactNode } from 'react';
3
3
 
4
4
  interface UseRealtimeMockupOptions {
@@ -13,7 +13,9 @@ interface UseRealtimeMockupOptions {
13
13
  token: string;
14
14
  expiresAt: number;
15
15
  }>;
16
- onConnected?: (sessionId: string) => void;
16
+ onConnected?: (sessionId: string, info: {
17
+ box?: string;
18
+ }) => void;
17
19
  onDisconnected?: () => void;
18
20
  onConfigReceived?: () => void;
19
21
  /** Called when server confirms it received a blob for a placement */
@@ -51,8 +53,10 @@ declare function useRealtimeMockup(options?: UseRealtimeMockupOptions): {
51
53
  clearMockups: () => void;
52
54
  flushPendingBlobs: () => void;
53
55
  hasPendingBlobs: () => boolean;
56
+ getLastSentVersion: () => number;
54
57
  isConnected: boolean;
55
58
  sessionId: string | null;
59
+ box: string | null;
56
60
  isConfigured: boolean;
57
61
  mockupResults: MockupResult[];
58
62
  status: string;
package/dist/react.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import {
2
2
  RealtimeMockupService
3
- } from "./chunk-SZZQ2CBF.js";
3
+ } from "./chunk-P3ZYTA5F.js";
4
4
 
5
5
  // src/realtime/react.ts
6
6
  import { useCallback, useEffect, useRef, useState } from "react";
@@ -13,6 +13,7 @@ function useRealtimeMockup(options = {}) {
13
13
  const [state, setState] = useState({
14
14
  isConnected: false,
15
15
  sessionId: null,
16
+ box: null,
16
17
  isConfigured: false,
17
18
  mockupResults: [],
18
19
  status: "Disconnected",
@@ -24,9 +25,9 @@ function useRealtimeMockup(options = {}) {
24
25
  const service = new RealtimeMockupService(wsUrl);
25
26
  serviceRef.current = service;
26
27
  service.setCallbacks({
27
- onConnected: (sessionId) => {
28
+ onConnected: (sessionId, info) => {
28
29
  setState(service.getState());
29
- options.onConnected?.(sessionId);
30
+ options.onConnected?.(sessionId, info);
30
31
  },
31
32
  onDisconnected: () => {
32
33
  setState(service.getState());
@@ -116,6 +117,9 @@ function useRealtimeMockup(options = {}) {
116
117
  const hasPendingBlobs = useCallback(() => {
117
118
  return serviceRef.current?.hasPendingBlobs() || false;
118
119
  }, []);
120
+ const getLastSentVersion = useCallback(() => {
121
+ return serviceRef.current?.getLastSentVersion() ?? 0;
122
+ }, []);
119
123
  return {
120
124
  ...state,
121
125
  connect,
@@ -133,7 +137,8 @@ function useRealtimeMockup(options = {}) {
133
137
  clearLogs,
134
138
  clearMockups,
135
139
  flushPendingBlobs,
136
- hasPendingBlobs
140
+ hasPendingBlobs,
141
+ getLastSentVersion
137
142
  };
138
143
  }
139
144
 
package/dist/server.cjs CHANGED
@@ -80,6 +80,7 @@ var PARAMS = {
80
80
  signature: "signature",
81
81
  seal: "seal"
82
82
  };
83
+ var MAX_RENDER_URL_LENGTH = 12 * 1024;
83
84
  var PUBLIC_PARAM_NAMES = [
84
85
  PARAMS.asset,
85
86
  PARAMS.design,
package/dist/server.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import {
2
2
  canonicalForSig,
3
3
  signDevSig
4
- } from "./chunk-553YYMDY.js";
4
+ } from "./chunk-FPR6ABXM.js";
5
5
 
6
6
  // src/server.ts
7
7
  function json(body, status = 200) {
@@ -301,6 +301,23 @@ interface MockupResult {
301
301
  serverTiming?: string;
302
302
  /** Server-side canvas render timing breakdown (present when canvas_state was used) */
303
303
  canvasRenderTiming?: any;
304
+ /**
305
+ * Box-window envelope of this frame in Server-Timing grammar — receive →
306
+ * send on the render node: `rt_total`, `rt_guard`, `rt_canvas` (+
307
+ * `rt_canvas_hop`, `canvas_*`), `rt_coalesce` (desc `superseded N`),
308
+ * `rt_composite`, `rt_store`, `rt_deliver` (desc `sz=<bytes> ws|url`),
309
+ * `rt_box`. Present on every frame from a server that emits it — no
310
+ * debug key needed. `clientRoundTripMs − rt_total` is the round-trip
311
+ * transport (browser ↔ edge ↔ box, both directions).
312
+ */
313
+ rtTiming?: string;
314
+ /** Client-observed edit → frame: the canvas_state send this frame answers
315
+ * → this message's arrival, in ms. Undefined when the frame was not
316
+ * triggered by a send from this client (config re-render, replay). */
317
+ clientRoundTripMs?: number;
318
+ /** How the bytes arrived: pushed down the socket ('ws') or via the
319
+ * imageUrl fetch ('url'). */
320
+ imageDelivery?: 'ws' | 'url';
304
321
  }
305
322
  interface WebSocketMessage {
306
323
  type: string;
@@ -336,6 +353,12 @@ interface WebSocketMessage {
336
353
  };
337
354
  /** Raw Server-Timing breakdown (only when the session's debugKey matched) */
338
355
  serverTiming?: string;
356
+ /** Box-window envelope of the frame (see MockupResult.rtTiming) */
357
+ rtTiming?: string;
358
+ /** Render node identity, on `connected` */
359
+ box?: string;
360
+ /** 'ws' when the image bytes were pushed as a mockup_frame before this message */
361
+ imageDelivery?: string;
339
362
  /** Server-side canvas render timing (only present when canvas_state was used) */
340
363
  canvasRenderTiming?: {
341
364
  poolAcquireMs: number;
@@ -361,10 +384,21 @@ interface RealtimeRenderError {
361
384
  code: string;
362
385
  /** Human-readable detail (includes specifics such as the blocked asset URL). */
363
386
  message: string;
387
+ /**
388
+ * Set when the error is about ONE mockup, not the session (the others keep
389
+ * streaming); show it as unavailable. Codes: 'E_MOCKUP_NOT_BLESSED' — the
390
+ * scene failed render parity; 'E_MOCKUP_INELIGIBLE' — no compiled scene
391
+ * can express the request (a colour-only or URL-less placement; `message`
392
+ * carries the reason); 'E_MOCKUP_UNRENDERABLE' — any other typed refusal.
393
+ */
394
+ mockupId?: string;
364
395
  }
365
396
  interface RealtimeMockupState {
366
397
  isConnected: boolean;
367
398
  sessionId: string | null;
399
+ /** Render node that answered the handshake (`connected.box`); null until
400
+ * connected or on servers that don't report it. */
401
+ box: string | null;
368
402
  isConfigured: boolean;
369
403
  mockupResults: MockupResult[];
370
404
  status: string;
@@ -381,7 +415,11 @@ interface RealtimeMockupState {
381
415
  renderError: RealtimeRenderError | null;
382
416
  }
383
417
  interface RealtimeMockupCallbacks {
384
- onConnected?: (sessionId: string) => void;
418
+ /** `info.box` names the render node that answered (undefined on servers
419
+ * that don't report it). */
420
+ onConnected?: (sessionId: string, info: {
421
+ box?: string;
422
+ }) => void;
385
423
  onDisconnected?: () => void;
386
424
  onConfigReceived?: () => void;
387
425
  /** Called when server confirms it received a blob for a placement */
@@ -405,6 +443,7 @@ declare class RealtimeMockupService {
405
443
  private config;
406
444
  private configSent;
407
445
  private sessionId;
446
+ private box;
408
447
  private isConfigured;
409
448
  private mockupResults;
410
449
  private status;
@@ -500,6 +539,13 @@ declare class RealtimeMockupService {
500
539
  * Check if there are pending blobs waiting to be sent (in throttle queue)
501
540
  */
502
541
  hasPendingBlobs(): boolean;
542
+ /**
543
+ * Version stamped on the most recent canvas_state send (0 before any).
544
+ * Every frame answers with `requestVersion`, so a caller can tell which
545
+ * send a frame belongs to — the pipeline-depth send policy counts a send
546
+ * as landed when every mockup of its version has arrived.
547
+ */
548
+ getLastSentVersion(): number;
503
549
  sendColorBlob(placement: string, hexColor: string): boolean;
504
550
  createEmptyCanvasBlob(width?: number, height?: number): Promise<Blob>;
505
551
  sendInitialEmptyCanvases(placements: Array<{
@@ -301,6 +301,23 @@ interface MockupResult {
301
301
  serverTiming?: string;
302
302
  /** Server-side canvas render timing breakdown (present when canvas_state was used) */
303
303
  canvasRenderTiming?: any;
304
+ /**
305
+ * Box-window envelope of this frame in Server-Timing grammar — receive →
306
+ * send on the render node: `rt_total`, `rt_guard`, `rt_canvas` (+
307
+ * `rt_canvas_hop`, `canvas_*`), `rt_coalesce` (desc `superseded N`),
308
+ * `rt_composite`, `rt_store`, `rt_deliver` (desc `sz=<bytes> ws|url`),
309
+ * `rt_box`. Present on every frame from a server that emits it — no
310
+ * debug key needed. `clientRoundTripMs − rt_total` is the round-trip
311
+ * transport (browser ↔ edge ↔ box, both directions).
312
+ */
313
+ rtTiming?: string;
314
+ /** Client-observed edit → frame: the canvas_state send this frame answers
315
+ * → this message's arrival, in ms. Undefined when the frame was not
316
+ * triggered by a send from this client (config re-render, replay). */
317
+ clientRoundTripMs?: number;
318
+ /** How the bytes arrived: pushed down the socket ('ws') or via the
319
+ * imageUrl fetch ('url'). */
320
+ imageDelivery?: 'ws' | 'url';
304
321
  }
305
322
  interface WebSocketMessage {
306
323
  type: string;
@@ -336,6 +353,12 @@ interface WebSocketMessage {
336
353
  };
337
354
  /** Raw Server-Timing breakdown (only when the session's debugKey matched) */
338
355
  serverTiming?: string;
356
+ /** Box-window envelope of the frame (see MockupResult.rtTiming) */
357
+ rtTiming?: string;
358
+ /** Render node identity, on `connected` */
359
+ box?: string;
360
+ /** 'ws' when the image bytes were pushed as a mockup_frame before this message */
361
+ imageDelivery?: string;
339
362
  /** Server-side canvas render timing (only present when canvas_state was used) */
340
363
  canvasRenderTiming?: {
341
364
  poolAcquireMs: number;
@@ -361,10 +384,21 @@ interface RealtimeRenderError {
361
384
  code: string;
362
385
  /** Human-readable detail (includes specifics such as the blocked asset URL). */
363
386
  message: string;
387
+ /**
388
+ * Set when the error is about ONE mockup, not the session (the others keep
389
+ * streaming); show it as unavailable. Codes: 'E_MOCKUP_NOT_BLESSED' — the
390
+ * scene failed render parity; 'E_MOCKUP_INELIGIBLE' — no compiled scene
391
+ * can express the request (a colour-only or URL-less placement; `message`
392
+ * carries the reason); 'E_MOCKUP_UNRENDERABLE' — any other typed refusal.
393
+ */
394
+ mockupId?: string;
364
395
  }
365
396
  interface RealtimeMockupState {
366
397
  isConnected: boolean;
367
398
  sessionId: string | null;
399
+ /** Render node that answered the handshake (`connected.box`); null until
400
+ * connected or on servers that don't report it. */
401
+ box: string | null;
368
402
  isConfigured: boolean;
369
403
  mockupResults: MockupResult[];
370
404
  status: string;
@@ -381,7 +415,11 @@ interface RealtimeMockupState {
381
415
  renderError: RealtimeRenderError | null;
382
416
  }
383
417
  interface RealtimeMockupCallbacks {
384
- onConnected?: (sessionId: string) => void;
418
+ /** `info.box` names the render node that answered (undefined on servers
419
+ * that don't report it). */
420
+ onConnected?: (sessionId: string, info: {
421
+ box?: string;
422
+ }) => void;
385
423
  onDisconnected?: () => void;
386
424
  onConfigReceived?: () => void;
387
425
  /** Called when server confirms it received a blob for a placement */
@@ -405,6 +443,7 @@ declare class RealtimeMockupService {
405
443
  private config;
406
444
  private configSent;
407
445
  private sessionId;
446
+ private box;
408
447
  private isConfigured;
409
448
  private mockupResults;
410
449
  private status;
@@ -500,6 +539,13 @@ declare class RealtimeMockupService {
500
539
  * Check if there are pending blobs waiting to be sent (in throttle queue)
501
540
  */
502
541
  hasPendingBlobs(): boolean;
542
+ /**
543
+ * Version stamped on the most recent canvas_state send (0 before any).
544
+ * Every frame answers with `requestVersion`, so a caller can tell which
545
+ * send a frame belongs to — the pipeline-depth send policy counts a send
546
+ * as landed when every mockup of its version has arrived.
547
+ */
548
+ getLastSentVersion(): number;
503
549
  sendColorBlob(placement: string, hexColor: string): boolean;
504
550
  createEmptyCanvasBlob(width?: number, height?: number): Promise<Blob>;
505
551
  sendInitialEmptyCanvases(placements: Array<{
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@snowcone-app/sdk",
3
- "version": "0.20.3",
3
+ "version": "0.23.0",
4
4
  "description": "Snowcone SDK for product mockups and print-on-demand",
5
5
  "keywords": [
6
6
  "merch",
@@ -85,7 +85,7 @@
85
85
  "tsup": "^8.1.0",
86
86
  "typescript": "^5.5.4",
87
87
  "vitest": "^2.0.5",
88
- "@snowcone-app/mockup-url": "0.3.4"
88
+ "@snowcone-app/mockup-url": "0.4.0"
89
89
  },
90
90
  "engines": {
91
91
  "node": ">=18"