@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/dist/react.d.cts 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-BG81_dZv.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
+ import { CSSProperties, ReactNode } from 'react';
2
3
 
3
4
  interface UseRealtimeMockupOptions {
4
5
  wsUrl?: string;
@@ -12,7 +13,9 @@ interface UseRealtimeMockupOptions {
12
13
  token: string;
13
14
  expiresAt: number;
14
15
  }>;
15
- onConnected?: (sessionId: string) => void;
16
+ onConnected?: (sessionId: string, info: {
17
+ box?: string;
18
+ }) => void;
16
19
  onDisconnected?: () => void;
17
20
  onConfigReceived?: () => void;
18
21
  /** Called when server confirms it received a blob for a placement */
@@ -50,8 +53,10 @@ declare function useRealtimeMockup(options?: UseRealtimeMockupOptions): {
50
53
  clearMockups: () => void;
51
54
  flushPendingBlobs: () => void;
52
55
  hasPendingBlobs: () => boolean;
56
+ getLastSentVersion: () => number;
53
57
  isConnected: boolean;
54
58
  sessionId: string | null;
59
+ box: string | null;
55
60
  isConfigured: boolean;
56
61
  mockupResults: MockupResult[];
57
62
  status: string;
@@ -60,6 +65,143 @@ declare function useRealtimeMockup(options?: UseRealtimeMockupOptions): {
60
65
  renderError: RealtimeRenderError | null;
61
66
  };
62
67
 
68
+ /**
69
+ * Mockup stage — the fast-render primitive for live product previews.
70
+ *
71
+ * Wraps a realtime session with the cropped-overlay delivery strategy:
72
+ * the FIRST render arrives full-frame and is frozen as a static background
73
+ * layer; the session then switches to `overlayCrop: 'auto'`, so every
74
+ * subsequent edit ships only the pixels inside the product region (the
75
+ * server derives the rect from the mockup's real mask geometry and reports
76
+ * it back with each frame). The stage composites the tiny frame over the
77
+ * frozen background — visually identical to a full render at a fraction of
78
+ * the bytes and latency.
79
+ *
80
+ * Two layers, use either:
81
+ * - `useMockupStage(options)` — headless. Owns the session + state machine
82
+ * and returns layers/status; bring your own rendering.
83
+ * - `MockupStage` — a ready view over a stage: layered <img>s, double-
84
+ * buffered frame swap (no flicker), feathered crop seam, and a default
85
+ * rendering shimmer. Every state is exposed as `data-sc-*` attributes so
86
+ * hosts key their own loading/animation treatments off it.
87
+ */
88
+
89
+ interface CropRect {
90
+ x: number;
91
+ y: number;
92
+ w: number;
93
+ h: number;
94
+ }
95
+ type MockupStageStatus = "connecting" | "configuring" | "first-frame" | "live" | "error";
96
+ interface UseMockupStageOptions {
97
+ /** Shop id the renders bill to (grant is minted for this shop). */
98
+ shop: string;
99
+ /** Product id. */
100
+ product: string;
101
+ /** Mockup (scene) id to render. */
102
+ mockup: string;
103
+ /** Additional mockup ids rendered by the same session (gallery views).
104
+ * Each gets its own background/frame pair in `stages`. */
105
+ extraMockups?: string[];
106
+ /** Variant id — fills color placements automatically when the product has them. */
107
+ variant?: string;
108
+ /** Render width in px, or a lazy getter (measured at config time — e.g.
109
+ * container width × devicePixelRatio). Default 1400. */
110
+ width?: number | (() => number);
111
+ /** Placement labels this stage sends artwork for. Default ['Front']. */
112
+ placements?: string[];
113
+ /** Aspect ratio, same grammar as the render URL param. Server default 16:9. */
114
+ ar?: string;
115
+ /** Background color behind scene alpha — 6-hex or 'transparent'. */
116
+ bg?: string;
117
+ /**
118
+ * Grant fetcher (recommended; connects to the public endpoint with zero
119
+ * further config). Omit only for self-hosted endpoints via `wsUrl`.
120
+ */
121
+ getToken?: () => Promise<{
122
+ token: string;
123
+ expiresAt: number;
124
+ }>;
125
+ /** Self-hosted realtime endpoint override. */
126
+ wsUrl?: string;
127
+ /**
128
+ * The fast path is the default: after the first full frame the session
129
+ * switches to server-cropped frames. Opt out with "full-frame" (every
130
+ * render ships the whole scene — the pre-crop behavior).
131
+ */
132
+ delivery?: "cropped" | "full-frame";
133
+ /** Operator timing debug key — relays Server-Timing on results. */
134
+ debugKey?: string;
135
+ /** Called with every rendered frame (timing, byte size, crop rect). */
136
+ onFrame?: (result: MockupResult) => void;
137
+ /** Structured render/session error (also exposed on state.error). */
138
+ onError?: (error: RealtimeRenderError) => void;
139
+ /** Placements to blank-initialize once configured (buyer flows render a
140
+ * product preview before any design exists). */
141
+ initialEmptyPlacements?: Array<{
142
+ label: string;
143
+ width?: number;
144
+ height?: number;
145
+ }>;
146
+ }
147
+ interface MockupStageFrame {
148
+ url: string;
149
+ /** Fractional rect the frame covers. Full frame = {0,0,1,1}. */
150
+ rect: CropRect;
151
+ }
152
+ interface MockupStageLayers {
153
+ /** Frozen full-frame background url (null until the first frame lands). */
154
+ background: string | null;
155
+ /** Latest frame to composite over the background. */
156
+ frame: MockupStageFrame | null;
157
+ }
158
+ interface MockupStageState {
159
+ status: MockupStageStatus;
160
+ /** Layers for the PRIMARY mockup (options.mockup). */
161
+ background: string | null;
162
+ frame: MockupStageFrame | null;
163
+ /** Per-mockup layers — primary plus every extraMockups entry. */
164
+ stages: Record<string, MockupStageLayers>;
165
+ /** An edit is in flight. */
166
+ isRendering: boolean;
167
+ error: RealtimeRenderError | null;
168
+ /** Last result's metadata (serverTiming, imageSize, …). */
169
+ lastResult: MockupResult | null;
170
+ /** Send a design (canvas_state JSON) for a placement — the production path. */
171
+ setDesign: (placement: string, state: object) => void;
172
+ /** Send pre-rendered artwork pixels for a placement. */
173
+ setArtwork: (placement: string, blob: Blob) => void;
174
+ /** Promote the latest full frame to the background (e.g. after prop changes). */
175
+ refreeze: () => void;
176
+ }
177
+ declare function useMockupStage(options: UseMockupStageOptions): MockupStageState;
178
+ interface MockupStageProps {
179
+ /** The stage returned by useMockupStage. */
180
+ stage: MockupStageState;
181
+ /** Render a specific mockup's layers (default: the primary mockup). */
182
+ mockupId?: string;
183
+ /** Feather (px) blending the frame edge into the background. Default 12. */
184
+ feather?: number;
185
+ /** Aspect ratio of the scene for layout, e.g. 16/9. Default 16/9. */
186
+ aspect?: number;
187
+ className?: string;
188
+ style?: CSSProperties;
189
+ /**
190
+ * Shown while connecting/configuring/waiting for the first frame. Default
191
+ * is a minimal pulse; pass a node for a custom one, or null to render
192
+ * nothing (host-owned loading UI keyed off data-sc-status).
193
+ */
194
+ placeholder?: ReactNode;
195
+ /** Shown while an edit renders. Default subtle shimmer; null = none. */
196
+ renderingIndicator?: ReactNode;
197
+ }
198
+ /**
199
+ * Default view: background layer + double-buffered frame layer. The next
200
+ * frame's <img> only swaps in after it has loaded, so edits never flash the
201
+ * old pixels away before the new ones are ready.
202
+ */
203
+ declare function MockupStage(props: MockupStageProps): ReactNode;
204
+
63
205
  /**
64
206
  * React framework adapter implementation
65
207
  */
@@ -112,4 +254,4 @@ declare function createReactComponent(descriptor: ComponentDescriptor, React: an
112
254
  */
113
255
  declare function useFrameworkAdapter(React: any): ReactAdapter;
114
256
 
115
- export { MockupResult, ReactAdapter, type UseRealtimeMockupOptions, WebSocketConfig, createReactComponent, useFrameworkAdapter as useReactAdapter, useRealtimeMockup };
257
+ 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.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-BG81_dZv.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
+ import { CSSProperties, ReactNode } from 'react';
2
3
 
3
4
  interface UseRealtimeMockupOptions {
4
5
  wsUrl?: string;
@@ -12,7 +13,9 @@ interface UseRealtimeMockupOptions {
12
13
  token: string;
13
14
  expiresAt: number;
14
15
  }>;
15
- onConnected?: (sessionId: string) => void;
16
+ onConnected?: (sessionId: string, info: {
17
+ box?: string;
18
+ }) => void;
16
19
  onDisconnected?: () => void;
17
20
  onConfigReceived?: () => void;
18
21
  /** Called when server confirms it received a blob for a placement */
@@ -50,8 +53,10 @@ declare function useRealtimeMockup(options?: UseRealtimeMockupOptions): {
50
53
  clearMockups: () => void;
51
54
  flushPendingBlobs: () => void;
52
55
  hasPendingBlobs: () => boolean;
56
+ getLastSentVersion: () => number;
53
57
  isConnected: boolean;
54
58
  sessionId: string | null;
59
+ box: string | null;
55
60
  isConfigured: boolean;
56
61
  mockupResults: MockupResult[];
57
62
  status: string;
@@ -60,6 +65,143 @@ declare function useRealtimeMockup(options?: UseRealtimeMockupOptions): {
60
65
  renderError: RealtimeRenderError | null;
61
66
  };
62
67
 
68
+ /**
69
+ * Mockup stage — the fast-render primitive for live product previews.
70
+ *
71
+ * Wraps a realtime session with the cropped-overlay delivery strategy:
72
+ * the FIRST render arrives full-frame and is frozen as a static background
73
+ * layer; the session then switches to `overlayCrop: 'auto'`, so every
74
+ * subsequent edit ships only the pixels inside the product region (the
75
+ * server derives the rect from the mockup's real mask geometry and reports
76
+ * it back with each frame). The stage composites the tiny frame over the
77
+ * frozen background — visually identical to a full render at a fraction of
78
+ * the bytes and latency.
79
+ *
80
+ * Two layers, use either:
81
+ * - `useMockupStage(options)` — headless. Owns the session + state machine
82
+ * and returns layers/status; bring your own rendering.
83
+ * - `MockupStage` — a ready view over a stage: layered <img>s, double-
84
+ * buffered frame swap (no flicker), feathered crop seam, and a default
85
+ * rendering shimmer. Every state is exposed as `data-sc-*` attributes so
86
+ * hosts key their own loading/animation treatments off it.
87
+ */
88
+
89
+ interface CropRect {
90
+ x: number;
91
+ y: number;
92
+ w: number;
93
+ h: number;
94
+ }
95
+ type MockupStageStatus = "connecting" | "configuring" | "first-frame" | "live" | "error";
96
+ interface UseMockupStageOptions {
97
+ /** Shop id the renders bill to (grant is minted for this shop). */
98
+ shop: string;
99
+ /** Product id. */
100
+ product: string;
101
+ /** Mockup (scene) id to render. */
102
+ mockup: string;
103
+ /** Additional mockup ids rendered by the same session (gallery views).
104
+ * Each gets its own background/frame pair in `stages`. */
105
+ extraMockups?: string[];
106
+ /** Variant id — fills color placements automatically when the product has them. */
107
+ variant?: string;
108
+ /** Render width in px, or a lazy getter (measured at config time — e.g.
109
+ * container width × devicePixelRatio). Default 1400. */
110
+ width?: number | (() => number);
111
+ /** Placement labels this stage sends artwork for. Default ['Front']. */
112
+ placements?: string[];
113
+ /** Aspect ratio, same grammar as the render URL param. Server default 16:9. */
114
+ ar?: string;
115
+ /** Background color behind scene alpha — 6-hex or 'transparent'. */
116
+ bg?: string;
117
+ /**
118
+ * Grant fetcher (recommended; connects to the public endpoint with zero
119
+ * further config). Omit only for self-hosted endpoints via `wsUrl`.
120
+ */
121
+ getToken?: () => Promise<{
122
+ token: string;
123
+ expiresAt: number;
124
+ }>;
125
+ /** Self-hosted realtime endpoint override. */
126
+ wsUrl?: string;
127
+ /**
128
+ * The fast path is the default: after the first full frame the session
129
+ * switches to server-cropped frames. Opt out with "full-frame" (every
130
+ * render ships the whole scene — the pre-crop behavior).
131
+ */
132
+ delivery?: "cropped" | "full-frame";
133
+ /** Operator timing debug key — relays Server-Timing on results. */
134
+ debugKey?: string;
135
+ /** Called with every rendered frame (timing, byte size, crop rect). */
136
+ onFrame?: (result: MockupResult) => void;
137
+ /** Structured render/session error (also exposed on state.error). */
138
+ onError?: (error: RealtimeRenderError) => void;
139
+ /** Placements to blank-initialize once configured (buyer flows render a
140
+ * product preview before any design exists). */
141
+ initialEmptyPlacements?: Array<{
142
+ label: string;
143
+ width?: number;
144
+ height?: number;
145
+ }>;
146
+ }
147
+ interface MockupStageFrame {
148
+ url: string;
149
+ /** Fractional rect the frame covers. Full frame = {0,0,1,1}. */
150
+ rect: CropRect;
151
+ }
152
+ interface MockupStageLayers {
153
+ /** Frozen full-frame background url (null until the first frame lands). */
154
+ background: string | null;
155
+ /** Latest frame to composite over the background. */
156
+ frame: MockupStageFrame | null;
157
+ }
158
+ interface MockupStageState {
159
+ status: MockupStageStatus;
160
+ /** Layers for the PRIMARY mockup (options.mockup). */
161
+ background: string | null;
162
+ frame: MockupStageFrame | null;
163
+ /** Per-mockup layers — primary plus every extraMockups entry. */
164
+ stages: Record<string, MockupStageLayers>;
165
+ /** An edit is in flight. */
166
+ isRendering: boolean;
167
+ error: RealtimeRenderError | null;
168
+ /** Last result's metadata (serverTiming, imageSize, …). */
169
+ lastResult: MockupResult | null;
170
+ /** Send a design (canvas_state JSON) for a placement — the production path. */
171
+ setDesign: (placement: string, state: object) => void;
172
+ /** Send pre-rendered artwork pixels for a placement. */
173
+ setArtwork: (placement: string, blob: Blob) => void;
174
+ /** Promote the latest full frame to the background (e.g. after prop changes). */
175
+ refreeze: () => void;
176
+ }
177
+ declare function useMockupStage(options: UseMockupStageOptions): MockupStageState;
178
+ interface MockupStageProps {
179
+ /** The stage returned by useMockupStage. */
180
+ stage: MockupStageState;
181
+ /** Render a specific mockup's layers (default: the primary mockup). */
182
+ mockupId?: string;
183
+ /** Feather (px) blending the frame edge into the background. Default 12. */
184
+ feather?: number;
185
+ /** Aspect ratio of the scene for layout, e.g. 16/9. Default 16/9. */
186
+ aspect?: number;
187
+ className?: string;
188
+ style?: CSSProperties;
189
+ /**
190
+ * Shown while connecting/configuring/waiting for the first frame. Default
191
+ * is a minimal pulse; pass a node for a custom one, or null to render
192
+ * nothing (host-owned loading UI keyed off data-sc-status).
193
+ */
194
+ placeholder?: ReactNode;
195
+ /** Shown while an edit renders. Default subtle shimmer; null = none. */
196
+ renderingIndicator?: ReactNode;
197
+ }
198
+ /**
199
+ * Default view: background layer + double-buffered frame layer. The next
200
+ * frame's <img> only swaps in after it has loaded, so edits never flash the
201
+ * old pixels away before the new ones are ready.
202
+ */
203
+ declare function MockupStage(props: MockupStageProps): ReactNode;
204
+
63
205
  /**
64
206
  * React framework adapter implementation
65
207
  */
@@ -112,4 +254,4 @@ declare function createReactComponent(descriptor: ComponentDescriptor, React: an
112
254
  */
113
255
  declare function useFrameworkAdapter(React: any): ReactAdapter;
114
256
 
115
- export { MockupResult, ReactAdapter, type UseRealtimeMockupOptions, WebSocketConfig, createReactComponent, useFrameworkAdapter as useReactAdapter, useRealtimeMockup };
257
+ export { MockupResult, MockupStage, type MockupStageFrame, type MockupStageProps, type MockupStageState, type MockupStageStatus, ReactAdapter, type UseMockupStageOptions, type UseRealtimeMockupOptions, WebSocketConfig, createReactComponent, useMockupStage, useFrameworkAdapter as useReactAdapter, useRealtimeMockup };