@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
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-
|
|
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
|
|
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-
|
|
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
|
|
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 };
|