@snowcone-app/sdk 0.20.1 → 0.20.3

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/dist/react.d.ts CHANGED
@@ -1,4 +1,5 @@
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-DXRDbLDN.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-CScS7UR-.js';
2
+ import { CSSProperties, ReactNode } from 'react';
2
3
 
3
4
  interface UseRealtimeMockupOptions {
4
5
  wsUrl?: string;
@@ -60,6 +61,143 @@ declare function useRealtimeMockup(options?: UseRealtimeMockupOptions): {
60
61
  renderError: RealtimeRenderError | null;
61
62
  };
62
63
 
64
+ /**
65
+ * Mockup stage — the fast-render primitive for live product previews.
66
+ *
67
+ * Wraps a realtime session with the cropped-overlay delivery strategy:
68
+ * the FIRST render arrives full-frame and is frozen as a static background
69
+ * layer; the session then switches to `overlayCrop: 'auto'`, so every
70
+ * subsequent edit ships only the pixels inside the product region (the
71
+ * server derives the rect from the mockup's real mask geometry and reports
72
+ * it back with each frame). The stage composites the tiny frame over the
73
+ * frozen background — visually identical to a full render at a fraction of
74
+ * the bytes and latency.
75
+ *
76
+ * Two layers, use either:
77
+ * - `useMockupStage(options)` — headless. Owns the session + state machine
78
+ * and returns layers/status; bring your own rendering.
79
+ * - `MockupStage` — a ready view over a stage: layered <img>s, double-
80
+ * buffered frame swap (no flicker), feathered crop seam, and a default
81
+ * rendering shimmer. Every state is exposed as `data-sc-*` attributes so
82
+ * hosts key their own loading/animation treatments off it.
83
+ */
84
+
85
+ interface CropRect {
86
+ x: number;
87
+ y: number;
88
+ w: number;
89
+ h: number;
90
+ }
91
+ type MockupStageStatus = "connecting" | "configuring" | "first-frame" | "live" | "error";
92
+ interface UseMockupStageOptions {
93
+ /** Shop id the renders bill to (grant is minted for this shop). */
94
+ shop: string;
95
+ /** Product id. */
96
+ product: string;
97
+ /** Mockup (scene) id to render. */
98
+ mockup: string;
99
+ /** Additional mockup ids rendered by the same session (gallery views).
100
+ * Each gets its own background/frame pair in `stages`. */
101
+ extraMockups?: string[];
102
+ /** Variant id — fills color placements automatically when the product has them. */
103
+ variant?: string;
104
+ /** Render width in px, or a lazy getter (measured at config time — e.g.
105
+ * container width × devicePixelRatio). Default 1400. */
106
+ width?: number | (() => number);
107
+ /** Placement labels this stage sends artwork for. Default ['Front']. */
108
+ placements?: string[];
109
+ /** Aspect ratio, same grammar as the render URL param. Server default 16:9. */
110
+ ar?: string;
111
+ /** Background color behind scene alpha — 6-hex or 'transparent'. */
112
+ bg?: string;
113
+ /**
114
+ * Grant fetcher (recommended; connects to the public endpoint with zero
115
+ * further config). Omit only for self-hosted endpoints via `wsUrl`.
116
+ */
117
+ getToken?: () => Promise<{
118
+ token: string;
119
+ expiresAt: number;
120
+ }>;
121
+ /** Self-hosted realtime endpoint override. */
122
+ wsUrl?: string;
123
+ /**
124
+ * The fast path is the default: after the first full frame the session
125
+ * switches to server-cropped frames. Opt out with "full-frame" (every
126
+ * render ships the whole scene — the pre-crop behavior).
127
+ */
128
+ delivery?: "cropped" | "full-frame";
129
+ /** Operator timing debug key — relays Server-Timing on results. */
130
+ debugKey?: string;
131
+ /** Called with every rendered frame (timing, byte size, crop rect). */
132
+ onFrame?: (result: MockupResult) => void;
133
+ /** Structured render/session error (also exposed on state.error). */
134
+ onError?: (error: RealtimeRenderError) => void;
135
+ /** Placements to blank-initialize once configured (buyer flows render a
136
+ * product preview before any design exists). */
137
+ initialEmptyPlacements?: Array<{
138
+ label: string;
139
+ width?: number;
140
+ height?: number;
141
+ }>;
142
+ }
143
+ interface MockupStageFrame {
144
+ url: string;
145
+ /** Fractional rect the frame covers. Full frame = {0,0,1,1}. */
146
+ rect: CropRect;
147
+ }
148
+ interface MockupStageLayers {
149
+ /** Frozen full-frame background url (null until the first frame lands). */
150
+ background: string | null;
151
+ /** Latest frame to composite over the background. */
152
+ frame: MockupStageFrame | null;
153
+ }
154
+ interface MockupStageState {
155
+ status: MockupStageStatus;
156
+ /** Layers for the PRIMARY mockup (options.mockup). */
157
+ background: string | null;
158
+ frame: MockupStageFrame | null;
159
+ /** Per-mockup layers — primary plus every extraMockups entry. */
160
+ stages: Record<string, MockupStageLayers>;
161
+ /** An edit is in flight. */
162
+ isRendering: boolean;
163
+ error: RealtimeRenderError | null;
164
+ /** Last result's metadata (serverTiming, imageSize, …). */
165
+ lastResult: MockupResult | null;
166
+ /** Send a design (canvas_state JSON) for a placement — the production path. */
167
+ setDesign: (placement: string, state: object) => void;
168
+ /** Send pre-rendered artwork pixels for a placement. */
169
+ setArtwork: (placement: string, blob: Blob) => void;
170
+ /** Promote the latest full frame to the background (e.g. after prop changes). */
171
+ refreeze: () => void;
172
+ }
173
+ declare function useMockupStage(options: UseMockupStageOptions): MockupStageState;
174
+ interface MockupStageProps {
175
+ /** The stage returned by useMockupStage. */
176
+ stage: MockupStageState;
177
+ /** Render a specific mockup's layers (default: the primary mockup). */
178
+ mockupId?: string;
179
+ /** Feather (px) blending the frame edge into the background. Default 12. */
180
+ feather?: number;
181
+ /** Aspect ratio of the scene for layout, e.g. 16/9. Default 16/9. */
182
+ aspect?: number;
183
+ className?: string;
184
+ style?: CSSProperties;
185
+ /**
186
+ * Shown while connecting/configuring/waiting for the first frame. Default
187
+ * is a minimal pulse; pass a node for a custom one, or null to render
188
+ * nothing (host-owned loading UI keyed off data-sc-status).
189
+ */
190
+ placeholder?: ReactNode;
191
+ /** Shown while an edit renders. Default subtle shimmer; null = none. */
192
+ renderingIndicator?: ReactNode;
193
+ }
194
+ /**
195
+ * Default view: background layer + double-buffered frame layer. The next
196
+ * frame's <img> only swaps in after it has loaded, so edits never flash the
197
+ * old pixels away before the new ones are ready.
198
+ */
199
+ declare function MockupStage(props: MockupStageProps): ReactNode;
200
+
63
201
  /**
64
202
  * React framework adapter implementation
65
203
  */
@@ -112,4 +250,4 @@ declare function createReactComponent(descriptor: ComponentDescriptor, React: an
112
250
  */
113
251
  declare function useFrameworkAdapter(React: any): ReactAdapter;
114
252
 
115
- export { MockupResult, ReactAdapter, type UseRealtimeMockupOptions, WebSocketConfig, createReactComponent, useFrameworkAdapter as useReactAdapter, useRealtimeMockup };
253
+ export { MockupResult, MockupStage, type MockupStageFrame, type MockupStageProps, type MockupStageState, type MockupStageStatus, ReactAdapter, type UseMockupStageOptions, type UseRealtimeMockupOptions, WebSocketConfig, createReactComponent, useMockupStage, useFrameworkAdapter as useReactAdapter, useRealtimeMockup };
package/dist/react.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import {
2
2
  RealtimeMockupService
3
- } from "./chunk-MKLLTNKJ.js";
3
+ } from "./chunk-SZZQ2CBF.js";
4
4
 
5
5
  // src/realtime/react.ts
6
6
  import { useCallback, useEffect, useRef, useState } from "react";
@@ -137,6 +137,334 @@ function useRealtimeMockup(options = {}) {
137
137
  };
138
138
  }
139
139
 
140
+ // src/realtime/stage.ts
141
+ import {
142
+ createElement,
143
+ useCallback as useCallback2,
144
+ useEffect as useEffect2,
145
+ useMemo,
146
+ useRef as useRef2,
147
+ useState as useState2
148
+ } from "react";
149
+ var FULL_RECT = { x: 0, y: 0, w: 1, h: 1 };
150
+ function useMockupStage(options) {
151
+ const {
152
+ shop,
153
+ product,
154
+ mockup,
155
+ variant,
156
+ placements,
157
+ ar,
158
+ bg,
159
+ getToken,
160
+ wsUrl,
161
+ delivery = "cropped",
162
+ debugKey
163
+ } = options;
164
+ const mockupIds = useMemo(
165
+ () => [mockup, ...options.extraMockups ?? []],
166
+ // eslint-disable-next-line react-hooks/exhaustive-deps
167
+ [mockup, JSON.stringify(options.extraMockups ?? [])]
168
+ );
169
+ const [stages, setStages] = useState2({});
170
+ const [isRendering, setIsRendering] = useState2(false);
171
+ const [error, setError] = useState2(null);
172
+ const [lastResult, setLastResult] = useState2(null);
173
+ const backgroundsRef = useRef2({});
174
+ const croppedActiveRef = useRef2(false);
175
+ const pendingEditsRef = useRef2(0);
176
+ const optionsRef = useRef2(options);
177
+ optionsRef.current = options;
178
+ const mockupIdsRef = useRef2(mockupIds);
179
+ mockupIdsRef.current = mockupIds;
180
+ const onFrameRef = useRef2(options.onFrame);
181
+ onFrameRef.current = options.onFrame;
182
+ const onErrorRef = useRef2(options.onError);
183
+ onErrorRef.current = options.onError;
184
+ const {
185
+ isConnected,
186
+ sessionId,
187
+ isConfigured,
188
+ connect,
189
+ sendConfig,
190
+ sendCanvasState,
191
+ sendCanvasBlob,
192
+ sendInitialEmptyCanvases
193
+ } = useRealtimeMockup({
194
+ wsUrl,
195
+ getToken,
196
+ onMockupRendered: (result) => {
197
+ if (!result.imageUrl || !result.mockupId) return;
198
+ const id = result.mockupId;
199
+ setLastResult(result);
200
+ pendingEditsRef.current = Math.max(0, pendingEditsRef.current - 1);
201
+ if (pendingEditsRef.current === 0) setIsRendering(false);
202
+ onFrameRef.current?.(result);
203
+ if (!backgroundsRef.current[id]) {
204
+ backgroundsRef.current[id] = result.imageUrl;
205
+ setStages((prev) => ({
206
+ ...prev,
207
+ [id]: { background: result.imageUrl, frame: { url: result.imageUrl, rect: FULL_RECT } }
208
+ }));
209
+ const allSeeded = mockupIdsRef.current.every((m) => backgroundsRef.current[m]);
210
+ if (allSeeded && !croppedActiveRef.current && optionsRef.current.delivery !== "full-frame") {
211
+ croppedActiveRef.current = true;
212
+ sendStageConfig(true);
213
+ }
214
+ return;
215
+ }
216
+ setStages((prev) => ({
217
+ ...prev,
218
+ [id]: {
219
+ background: backgroundsRef.current[id],
220
+ frame: { url: result.imageUrl, rect: result.cropRect ?? FULL_RECT }
221
+ }
222
+ }));
223
+ },
224
+ onError: (_msg, detail) => {
225
+ setError(detail);
226
+ setIsRendering(false);
227
+ onErrorRef.current?.(detail);
228
+ }
229
+ });
230
+ const sendConfigRef = useRef2(sendConfig);
231
+ sendConfigRef.current = sendConfig;
232
+ const sendStageConfig = useCallback2(
233
+ (withCrop) => {
234
+ const o = optionsRef.current;
235
+ const width = typeof o.width === "function" ? o.width() : o.width ?? 1400;
236
+ const config = {
237
+ productId: o.product,
238
+ mockupIds: mockupIdsRef.current,
239
+ variantId: o.variant ?? "",
240
+ shop: o.shop,
241
+ width,
242
+ ...o.ar && { ar: o.ar },
243
+ ...o.bg && { bg: o.bg },
244
+ ...withCrop && { overlayCrop: "auto" },
245
+ ...o.debugKey && { debugKey: o.debugKey }
246
+ };
247
+ sendConfigRef.current(config);
248
+ },
249
+ []
250
+ );
251
+ useEffect2(() => {
252
+ connect();
253
+ }, [connect]);
254
+ useEffect2(() => {
255
+ if (isConnected && sessionId) {
256
+ sendStageConfig(croppedActiveRef.current);
257
+ }
258
+ }, [isConnected, sessionId, shop, product, mockupIds, variant, ar, bg, sendStageConfig]);
259
+ const initialSentRef = useRef2(false);
260
+ useEffect2(() => {
261
+ const placementsToSeed = optionsRef.current.initialEmptyPlacements;
262
+ if (isConfigured && placementsToSeed?.length && !initialSentRef.current) {
263
+ initialSentRef.current = true;
264
+ void sendInitialEmptyCanvases(placementsToSeed);
265
+ }
266
+ }, [isConfigured, sendInitialEmptyCanvases]);
267
+ const setDesign = useCallback2(
268
+ (placement, state) => {
269
+ pendingEditsRef.current += 1;
270
+ setIsRendering(true);
271
+ setError(null);
272
+ sendCanvasState(placement, state, 1, 0);
273
+ },
274
+ [sendCanvasState]
275
+ );
276
+ const setArtwork = useCallback2(
277
+ (placement, blob) => {
278
+ pendingEditsRef.current += 1;
279
+ setIsRendering(true);
280
+ setError(null);
281
+ sendCanvasBlob(placement, blob, 1, 0);
282
+ },
283
+ [sendCanvasBlob]
284
+ );
285
+ const refreeze = useCallback2(() => {
286
+ backgroundsRef.current = {};
287
+ croppedActiveRef.current = false;
288
+ setStages({});
289
+ sendStageConfig(false);
290
+ }, [sendStageConfig]);
291
+ const primary = stages[mockup] ?? { background: null, frame: null };
292
+ const status = error ? "error" : !isConnected ? "connecting" : !isConfigured ? "configuring" : !primary.background ? "first-frame" : "live";
293
+ void placements;
294
+ return {
295
+ status,
296
+ background: primary.background,
297
+ frame: primary.frame,
298
+ stages,
299
+ isRendering,
300
+ error,
301
+ lastResult,
302
+ setDesign,
303
+ setArtwork,
304
+ refreeze
305
+ };
306
+ }
307
+ function MockupStage(props) {
308
+ const {
309
+ stage,
310
+ mockupId,
311
+ feather = 12,
312
+ aspect = 16 / 9,
313
+ className,
314
+ style,
315
+ placeholder,
316
+ renderingIndicator
317
+ } = props;
318
+ const layers = mockupId ? stage.stages[mockupId] ?? { background: null, frame: null } : { background: stage.background, frame: stage.frame };
319
+ const [displayed, setDisplayed] = useState2(null);
320
+ const [incoming, setIncoming] = useState2(null);
321
+ useEffect2(() => {
322
+ if (!layers.frame) return;
323
+ if (!displayed) {
324
+ setDisplayed(layers.frame);
325
+ return;
326
+ }
327
+ if (layers.frame.url !== displayed.url) setIncoming(layers.frame);
328
+ }, [layers.frame]);
329
+ const handleIncomingLoad = useCallback2(() => {
330
+ setIncoming((inc) => {
331
+ if (inc) setDisplayed(inc);
332
+ return null;
333
+ });
334
+ }, []);
335
+ const frameStyle = useCallback2(
336
+ (f) => {
337
+ const full = f.rect.x === 0 && f.rect.y === 0 && f.rect.w === 1 && f.rect.h === 1;
338
+ const base = {
339
+ position: "absolute",
340
+ left: `${f.rect.x * 100}%`,
341
+ top: `${f.rect.y * 100}%`,
342
+ width: `${f.rect.w * 100}%`,
343
+ height: `${f.rect.h * 100}%`
344
+ };
345
+ if (!full && feather > 0) {
346
+ const m = `linear-gradient(to right, transparent 0, black ${feather}px, black calc(100% - ${feather}px), transparent 100%), linear-gradient(to bottom, transparent 0, black ${feather}px, black calc(100% - ${feather}px), transparent 100%)`;
347
+ base.WebkitMaskImage = m;
348
+ base.maskImage = m;
349
+ base.WebkitMaskComposite = "source-in";
350
+ base.maskComposite = "intersect";
351
+ }
352
+ return base;
353
+ },
354
+ [feather]
355
+ );
356
+ const containerStyle = useMemo(
357
+ () => ({
358
+ position: "relative",
359
+ aspectRatio: String(aspect),
360
+ overflow: "hidden",
361
+ ...style
362
+ }),
363
+ [aspect, style]
364
+ );
365
+ const children = [];
366
+ if (layers.background) {
367
+ children.push(
368
+ createElement("img", {
369
+ key: "bg",
370
+ src: layers.background,
371
+ alt: "",
372
+ "data-sc-part": "background",
373
+ style: { position: "absolute", inset: 0, width: "100%", height: "100%" }
374
+ })
375
+ );
376
+ }
377
+ if (displayed) {
378
+ children.push(
379
+ createElement("img", {
380
+ key: `frame-${displayed.url}`,
381
+ src: displayed.url,
382
+ alt: "",
383
+ "data-sc-part": "frame",
384
+ style: frameStyle(displayed)
385
+ })
386
+ );
387
+ }
388
+ if (incoming) {
389
+ children.push(
390
+ createElement("img", {
391
+ key: `incoming-${incoming.url}`,
392
+ src: incoming.url,
393
+ alt: "",
394
+ "data-sc-part": "frame-incoming",
395
+ onLoad: handleIncomingLoad,
396
+ style: { ...frameStyle(incoming), opacity: 0.999 }
397
+ })
398
+ );
399
+ }
400
+ if (!layers.background) {
401
+ children.push(
402
+ createElement(
403
+ "div",
404
+ {
405
+ key: "placeholder",
406
+ "data-sc-part": "placeholder",
407
+ style: {
408
+ position: "absolute",
409
+ inset: 0,
410
+ display: "flex",
411
+ alignItems: "center",
412
+ justifyContent: "center"
413
+ }
414
+ },
415
+ placeholder !== void 0 ? placeholder : createElement("div", {
416
+ style: {
417
+ width: "38%",
418
+ height: "55%",
419
+ borderRadius: 12,
420
+ background: "rgba(127,127,127,0.15)",
421
+ animation: "sc-stage-pulse 1.2s ease-in-out infinite"
422
+ }
423
+ })
424
+ )
425
+ );
426
+ }
427
+ if (stage.isRendering && layers.background) {
428
+ children.push(
429
+ createElement(
430
+ "div",
431
+ {
432
+ key: "rendering",
433
+ "data-sc-part": "rendering-indicator",
434
+ style: { position: "absolute", inset: 0, pointerEvents: "none" }
435
+ },
436
+ renderingIndicator !== void 0 ? renderingIndicator : createElement("div", {
437
+ style: {
438
+ position: "absolute",
439
+ top: 8,
440
+ right: 8,
441
+ width: 8,
442
+ height: 8,
443
+ borderRadius: "50%",
444
+ background: "rgba(127,127,127,0.6)",
445
+ animation: "sc-stage-pulse 0.8s ease-in-out infinite"
446
+ }
447
+ })
448
+ )
449
+ );
450
+ }
451
+ children.push(
452
+ createElement("style", { key: "kf" }, "@keyframes sc-stage-pulse{0%,100%{opacity:.35}50%{opacity:.9}}")
453
+ );
454
+ return createElement(
455
+ "div",
456
+ {
457
+ className,
458
+ style: containerStyle,
459
+ "data-sc-part": "stage",
460
+ "data-sc-status": stage.status,
461
+ "data-sc-rendering": stage.isRendering ? "true" : "false",
462
+ ...stage.error && { "data-sc-error": stage.error.code ?? "error" }
463
+ },
464
+ ...children
465
+ );
466
+ }
467
+
140
468
  // src/framework/adapters/react.ts
141
469
  var ReactAdapter = class {
142
470
  name = "react";
@@ -256,8 +584,10 @@ function useFrameworkAdapter(React) {
256
584
  return new ReactAdapter(React, React);
257
585
  }
258
586
  export {
587
+ MockupStage,
259
588
  ReactAdapter,
260
589
  createReactComponent,
590
+ useMockupStage,
261
591
  useFrameworkAdapter as useReactAdapter,
262
592
  useRealtimeMockup
263
593
  };
package/dist/server.cjs CHANGED
@@ -117,6 +117,7 @@ function canonicalForSig(url) {
117
117
  const rawValue = eq === -1 ? "" : segment.slice(eq + 1);
118
118
  const key = decodeURIComponent(rawKey);
119
119
  if (key === "signature") continue;
120
+ if (key === "debug") continue;
120
121
  pairs.push({ key, raw: rawValue });
121
122
  }
122
123
  }
package/dist/server.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import {
2
2
  canonicalForSig,
3
3
  signDevSig
4
- } from "./chunk-IL3FXE2X.js";
4
+ } from "./chunk-553YYMDY.js";
5
5
 
6
6
  // src/server.ts
7
7
  function json(body, status = 200) {
@@ -230,6 +230,43 @@ interface WebSocketConfig {
230
230
  * consistent with static renders that carry `bg=`.
231
231
  */
232
232
  bg?: string;
233
+ /**
234
+ * Spread-mode crop map (ADR-0060): when the client canvas runs combined
235
+ * spread/group artboards, each canvas_state render of that artboard is
236
+ * cropped server-side into per-placement images by these bounds. Keyed by
237
+ * artboard name; piece rects are in artboard units and `placement` must be
238
+ * the product's placement label.
239
+ */
240
+ spreadCrops?: Record<string, {
241
+ width: number;
242
+ height: number;
243
+ pieces: Array<{
244
+ placement: string;
245
+ x: number;
246
+ y: number;
247
+ width: number;
248
+ height: number;
249
+ }>;
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;
233
270
  placementSettings?: Record<string, PlacementSettings>;
234
271
  }
235
272
  interface MockupResult {
@@ -251,6 +288,17 @@ interface MockupResult {
251
288
  costUsd?: number;
252
289
  /** Whether the underlying render was served from cache */
253
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;
254
302
  /** Server-side canvas render timing breakdown (present when canvas_state was used) */
255
303
  canvasRenderTiming?: any;
256
304
  }
@@ -279,6 +327,15 @@ interface WebSocketMessage {
279
327
  costUsd?: number;
280
328
  /** Whether the underlying render was served from cache */
281
329
  renderCache?: 'hit' | 'miss';
330
+ /** Rect the payload was cropped with (overlayCrop renders) */
331
+ cropRect?: {
332
+ x: number;
333
+ y: number;
334
+ w: number;
335
+ h: number;
336
+ };
337
+ /** Raw Server-Timing breakdown (only when the session's debugKey matched) */
338
+ serverTiming?: string;
282
339
  /** Server-side canvas render timing (only present when canvas_state was used) */
283
340
  canvasRenderTiming?: {
284
341
  poolAcquireMs: number;
@@ -369,6 +426,8 @@ declare class RealtimeMockupService {
369
426
  private latestAcceptedVersionByPlacement;
370
427
  private sendVersionInBlob;
371
428
  private tokenProvider?;
429
+ private pendingFrames;
430
+ private liveObjectUrls;
372
431
  private renewTimer;
373
432
  private isConnecting;
374
433
  private connectAttempt;
@@ -388,6 +447,9 @@ declare class RealtimeMockupService {
388
447
  private renew;
389
448
  private handleMessage;
390
449
  disconnect(): void;
450
+ private handleBinaryFrame;
451
+ /** Swap a ws-delivered frame in for the imageUrl on a render result. */
452
+ private applyBinaryFrame;
391
453
  sendConfig(config: WebSocketConfig): boolean;
392
454
  /**
393
455
  * Update only the mockupIds without changing other config.