@snowcone-app/sdk 0.20.2 → 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 +24 -0
- package/dist/{chunk-IL3FXE2X.js → chunk-FPR6ABXM.js} +2 -0
- package/dist/{chunk-MKLLTNKJ.js → chunk-P3ZYTA5F.js} +91 -6
- package/dist/index.cjs +93 -6
- package/dist/index.d.cts +9 -3
- package/dist/index.d.ts +9 -3
- package/dist/index.js +2 -2
- package/dist/react.cjs +424 -9
- package/dist/react.d.cts +145 -3
- package/dist/react.d.ts +145 -3
- package/dist/react.js +339 -4
- package/dist/server.cjs +2 -0
- package/dist/server.js +1 -1
- package/dist/{websocket-BG81_dZv.d.cts → websocket-DjAOhBaN.d.cts} +91 -1
- package/dist/{websocket-BG81_dZv.d.ts → websocket-DjAOhBaN.d.ts} +91 -1
- package/package.json +2 -2
|
@@ -248,6 +248,25 @@ interface WebSocketConfig {
|
|
|
248
248
|
height: number;
|
|
249
249
|
}>;
|
|
250
250
|
}>;
|
|
251
|
+
/**
|
|
252
|
+
* Cropped-overlay delivery: {x,y,w,h} fractions of the OUTPUT frame. Each
|
|
253
|
+
* rendered mockup is cropped server-side to this rect just before AVIF
|
|
254
|
+
* encode, so every realtime frame carries only that region's bytes — the
|
|
255
|
+
* client positions it over a static full-frame render using the same
|
|
256
|
+
* fractions. Full-frame ({x:0,y:0,w:1,h:1}) is a no-op.
|
|
257
|
+
*/
|
|
258
|
+
overlayCrop?: {
|
|
259
|
+
x: number;
|
|
260
|
+
y: number;
|
|
261
|
+
w: number;
|
|
262
|
+
h: number;
|
|
263
|
+
} | 'auto';
|
|
264
|
+
/**
|
|
265
|
+
* Operator-only: when this matches the render server's debug secret, every
|
|
266
|
+
* MockupResult carries `serverTiming` — the render's per-stage breakdown.
|
|
267
|
+
* Wrong values fail renders loudly (never pass user input here).
|
|
268
|
+
*/
|
|
269
|
+
debugKey?: string;
|
|
251
270
|
placementSettings?: Record<string, PlacementSettings>;
|
|
252
271
|
}
|
|
253
272
|
interface MockupResult {
|
|
@@ -269,8 +288,36 @@ interface MockupResult {
|
|
|
269
288
|
costUsd?: number;
|
|
270
289
|
/** Whether the underlying render was served from cache */
|
|
271
290
|
renderCache?: 'hit' | 'miss';
|
|
291
|
+
/** The rect this payload was cropped with (fractions of the full frame) —
|
|
292
|
+
* present on overlayCrop renders; position the overlay with these numbers. */
|
|
293
|
+
cropRect?: {
|
|
294
|
+
x: number;
|
|
295
|
+
y: number;
|
|
296
|
+
w: number;
|
|
297
|
+
h: number;
|
|
298
|
+
};
|
|
299
|
+
/** Raw Server-Timing header of the render — per-stage breakdown, present
|
|
300
|
+
* only when the session's debugKey matched the server's debug secret. */
|
|
301
|
+
serverTiming?: string;
|
|
272
302
|
/** Server-side canvas render timing breakdown (present when canvas_state was used) */
|
|
273
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';
|
|
274
321
|
}
|
|
275
322
|
interface WebSocketMessage {
|
|
276
323
|
type: string;
|
|
@@ -297,6 +344,21 @@ interface WebSocketMessage {
|
|
|
297
344
|
costUsd?: number;
|
|
298
345
|
/** Whether the underlying render was served from cache */
|
|
299
346
|
renderCache?: 'hit' | 'miss';
|
|
347
|
+
/** Rect the payload was cropped with (overlayCrop renders) */
|
|
348
|
+
cropRect?: {
|
|
349
|
+
x: number;
|
|
350
|
+
y: number;
|
|
351
|
+
w: number;
|
|
352
|
+
h: number;
|
|
353
|
+
};
|
|
354
|
+
/** Raw Server-Timing breakdown (only when the session's debugKey matched) */
|
|
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;
|
|
300
362
|
/** Server-side canvas render timing (only present when canvas_state was used) */
|
|
301
363
|
canvasRenderTiming?: {
|
|
302
364
|
poolAcquireMs: number;
|
|
@@ -322,10 +384,21 @@ interface RealtimeRenderError {
|
|
|
322
384
|
code: string;
|
|
323
385
|
/** Human-readable detail (includes specifics such as the blocked asset URL). */
|
|
324
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;
|
|
325
395
|
}
|
|
326
396
|
interface RealtimeMockupState {
|
|
327
397
|
isConnected: boolean;
|
|
328
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;
|
|
329
402
|
isConfigured: boolean;
|
|
330
403
|
mockupResults: MockupResult[];
|
|
331
404
|
status: string;
|
|
@@ -342,7 +415,11 @@ interface RealtimeMockupState {
|
|
|
342
415
|
renderError: RealtimeRenderError | null;
|
|
343
416
|
}
|
|
344
417
|
interface RealtimeMockupCallbacks {
|
|
345
|
-
|
|
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;
|
|
346
423
|
onDisconnected?: () => void;
|
|
347
424
|
onConfigReceived?: () => void;
|
|
348
425
|
/** Called when server confirms it received a blob for a placement */
|
|
@@ -366,6 +443,7 @@ declare class RealtimeMockupService {
|
|
|
366
443
|
private config;
|
|
367
444
|
private configSent;
|
|
368
445
|
private sessionId;
|
|
446
|
+
private box;
|
|
369
447
|
private isConfigured;
|
|
370
448
|
private mockupResults;
|
|
371
449
|
private status;
|
|
@@ -387,6 +465,8 @@ declare class RealtimeMockupService {
|
|
|
387
465
|
private latestAcceptedVersionByPlacement;
|
|
388
466
|
private sendVersionInBlob;
|
|
389
467
|
private tokenProvider?;
|
|
468
|
+
private pendingFrames;
|
|
469
|
+
private liveObjectUrls;
|
|
390
470
|
private renewTimer;
|
|
391
471
|
private isConnecting;
|
|
392
472
|
private connectAttempt;
|
|
@@ -406,6 +486,9 @@ declare class RealtimeMockupService {
|
|
|
406
486
|
private renew;
|
|
407
487
|
private handleMessage;
|
|
408
488
|
disconnect(): void;
|
|
489
|
+
private handleBinaryFrame;
|
|
490
|
+
/** Swap a ws-delivered frame in for the imageUrl on a render result. */
|
|
491
|
+
private applyBinaryFrame;
|
|
409
492
|
sendConfig(config: WebSocketConfig): boolean;
|
|
410
493
|
/**
|
|
411
494
|
* Update only the mockupIds without changing other config.
|
|
@@ -456,6 +539,13 @@ declare class RealtimeMockupService {
|
|
|
456
539
|
* Check if there are pending blobs waiting to be sent (in throttle queue)
|
|
457
540
|
*/
|
|
458
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;
|
|
459
549
|
sendColorBlob(placement: string, hexColor: string): boolean;
|
|
460
550
|
createEmptyCanvasBlob(width?: number, height?: number): Promise<Blob>;
|
|
461
551
|
sendInitialEmptyCanvases(placements: Array<{
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@snowcone-app/sdk",
|
|
3
|
-
"version": "0.
|
|
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.
|
|
88
|
+
"@snowcone-app/mockup-url": "0.4.0"
|
|
89
89
|
},
|
|
90
90
|
"engines": {
|
|
91
91
|
"node": ">=18"
|