@snowcone-app/sdk 0.31.1 → 0.31.4

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.31.4
4
+
5
+ ### Patch Changes
6
+
7
+ - [#5688](https://github.com/snowcone-app/snowcone-monorepo/pull/5688) [`cec468f`](https://github.com/snowcone-app/snowcone-monorepo/commit/cec468fc5799297a192a5183edbf1a6b460c6d56) Thanks [@kevinsproles](https://github.com/kevinsproles)! - `getMockupUrl`'s `stripView` doc: a `width` beside it is a downscale (the crop is never enlarged), as the grammar accepts since #5684.
8
+
9
+ ## 0.31.3
10
+
11
+ ### Patch Changes
12
+
13
+ - [#5682](https://github.com/snowcone-app/snowcone-monorepo/pull/5682) [`5fda4b9`](https://github.com/snowcone-app/snowcone-monorepo/commit/5fda4b9c7fbb226c1bd61024cf01c38ac31bddeb) Thanks [@kevinsproles](https://github.com/kevinsproles)! - The editor's live preview is cropped like the product page's hero. SDK: the realtime config takes `views: { <mockupId>: MockupView }` (that mockup's live frame is `aspect=8:3&view=<v>`, the hero's crop); `sendConfig` sends only the views of the config's own `mockupIds` and throws before sending what the box refuses (`E_VIEW_PARAM_INVALID` off the grid, `E_REALTIME_VIEWS_WITH_CROP_RECT` beside an overlayCrop rect); `sessionViews` is exported. UI: `RealtimeProvider` gets `setMockupViews(views)` (carried on every config it sends; a change re-sends the config and re-seeds the cropped-delivery backgrounds) and `frameViewOf(url)` (which crop a frame it handed out is).
14
+
15
+ ## 0.31.2
16
+
17
+ ### Patch Changes
18
+
19
+ - [#5680](https://github.com/snowcone-app/snowcone-monorepo/pull/5680) [`792b4f5`](https://github.com/snowcone-app/snowcone-monorepo/commit/792b4f55b2b662906d3aeacf5d246524f2444dd0) Thanks [@kevinsproles](https://github.com/kevinsproles)! - The desktop product-page hero of a plate asks for only the part of its 8:3 strip the window shows. SDK: `getMockupUrl` takes `stripView` (`view=<r>@<f>`, with `aspect: "8:3"` and no width; a crop written as the scene alias `view` throws `E_VIEW_IS_STRIP_VIEW`), re-exports the view grid (`mockupViewFor`, `canonicalMockupView`, `MOCKUP_VIEW_SHAPES`, `MOCKUP_VIEW_PLACES`, `MockupView`), and the catalog product type carries `mockups[].strip` (`{ shape: "8:3", productX }`). UI: `HeroProductImage` takes `stripView` (a crop, or `"whole-strip"`) and `onShown`; `CarouselImage` carries `strip`.
20
+
3
21
  ## 0.31.1
4
22
 
5
23
  ### Patch Changes
@@ -1,11 +1,32 @@
1
1
  import {
2
- SNOWCONE_REALTIME_WS_URL
3
- } from "./chunk-O6I5SJT5.js";
2
+ SNOWCONE_REALTIME_WS_URL,
3
+ canonicalMockupView
4
+ } from "./chunk-KCIDK2T7.js";
4
5
 
5
6
  // src/realtime/constants.ts
6
7
  var REALTIME_WS_URL = SNOWCONE_REALTIME_WS_URL;
7
8
 
8
9
  // src/realtime/websocket.ts
10
+ function sessionViews(config) {
11
+ const raw = config.views;
12
+ if (raw === void 0) return void 0;
13
+ if (config.overlayCrop !== void 0 && config.overlayCrop !== "auto") {
14
+ throw new Error(
15
+ "[snowcone] E_REALTIME_VIEWS_WITH_CROP_RECT: a config with views takes no overlayCrop rect (a view IS the crop); send overlayCrop 'auto' (the print area inside the view) or none"
16
+ );
17
+ }
18
+ const out = {};
19
+ for (const [mockupId, v] of Object.entries(raw)) {
20
+ const canonical = canonicalMockupView(String(v));
21
+ if (!canonical) {
22
+ throw new Error(
23
+ `[snowcone] E_VIEW_PARAM_INVALID: views[${mockupId}] = ${JSON.stringify(v)} is not on the view grid <r>@<f> (compute it with mockupViewFor from @snowcone-app/sdk)`
24
+ );
25
+ }
26
+ if (config.mockupIds.includes(mockupId)) out[mockupId] = canonical;
27
+ }
28
+ return Object.keys(out).length ? out : void 0;
29
+ }
9
30
  function pruneUndefined(obj) {
10
31
  const out = {};
11
32
  for (const [k, v] of Object.entries(obj)) {
@@ -486,6 +507,7 @@ var RealtimeMockupService = class {
486
507
  data.imageUrl = frame.objectUrl;
487
508
  }
488
509
  sendConfig(config) {
510
+ const views = sessionViews(config);
489
511
  if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
490
512
  this.addLog("WebSocket not connected, caching config");
491
513
  this.config = config;
@@ -535,7 +557,8 @@ var RealtimeMockupService = class {
535
557
  // socket (mockup_frame binary messages) instead of making us fetch the
536
558
  // imageUrl — saves a network round trip per render. Servers that don't
537
559
  // know the flag ignore it and we fall back to the URL.
538
- config: { ...config, binaryFrames: true }
560
+ // views go out pruned to this config's mockupIds (undefined = the key is dropped by JSON).
561
+ config: { ...config, views, binaryFrames: true }
539
562
  };
540
563
  const messageStr = JSON.stringify(message);
541
564
  this.addLog(`\u{1F4E4} Sending config: ${JSON.stringify(message, null, 2)}`, "sent");
@@ -995,5 +1018,6 @@ ${versionToSend}
995
1018
 
996
1019
  export {
997
1020
  REALTIME_WS_URL,
1021
+ sessionViews,
998
1022
  RealtimeMockupService
999
1023
  };
@@ -52,6 +52,12 @@ var PARAMS = {
52
52
  width: "width",
53
53
  grain: "grain",
54
54
  aspect: "aspect",
55
+ /**
56
+ * `view=<r>@<f>`: a crop of a plate's 8:3 strip, for a page hero that shows only part of it ({@link canonicalMockupView}).
57
+ * Goes with `aspect=8:3` only. Without `width=` the crop is delivered at its own pixels; with `width=` at that width when
58
+ * smaller (the box only ever downscales: a page asks crop width x DPR, capped at the crop).
59
+ */
60
+ view: "view",
55
61
  /**
56
62
  * Background color (6-hex, no '#') painted behind the mockup — visible only
57
63
  * where the mockup itself has transparency (studio-cutout shots) — or the
@@ -73,6 +79,33 @@ var PARAMS = {
73
79
  seal: "seal"
74
80
  };
75
81
  var BG_TRANSPARENT = "transparent";
82
+ var viewGrid = (from, to, step) => Array.from({ length: Math.round((to - from) / step) + 1 }, (_, i) => Math.round((from + i * step) * 1e3) / 1e3);
83
+ var MOCKUP_VIEW_SHAPES = viewGrid(1.3, 2.6, 0.1);
84
+ var MOCKUP_VIEW_PLACES = [...viewGrid(0.25, 0.475, 0.025), ...viewGrid(0.525, 0.75, 0.025)];
85
+ function canonicalMockupView(raw) {
86
+ const m = /^\s*(\d+(?:\.\d+)?)@(\d+(?:\.\d+)?)\s*$/.exec(String(raw));
87
+ if (!m) return null;
88
+ const r = MOCKUP_VIEW_SHAPES.find((x) => Math.abs(x - Number(m[1])) < 1e-9);
89
+ const f = MOCKUP_VIEW_PLACES.find((x) => Math.abs(x - Number(m[2])) < 1e-9);
90
+ return r === void 0 || f === void 0 ? null : `${r.toFixed(1)}@${String(f)}`;
91
+ }
92
+ function mockupViewFor(windowWidth, windowHeight, productCentreX) {
93
+ if (!(windowWidth > 0 && windowHeight > 0)) return null;
94
+ const rawR = windowWidth / windowHeight;
95
+ const r = MOCKUP_VIEW_SHAPES.find((x) => x >= rawR - 1e-9);
96
+ if (r === void 0) return null;
97
+ const rawF = productCentreX / windowWidth;
98
+ const f = MOCKUP_VIEW_PLACES.reduce((best, x) => Math.abs(x - rawF) < Math.abs(best - rawF) ? x : best, MOCKUP_VIEW_PLACES[0]);
99
+ return `${r.toFixed(1)}@${String(f)}`;
100
+ }
101
+ function requireMockupView(view, ctx) {
102
+ const v = canonicalMockupView(view);
103
+ if (!v) throw new Error(`[snowcone] E_VIEW_PARAM_INVALID: view "${view}" is not on the grid: <r>@<f>, r one of ${MOCKUP_VIEW_SHAPES.join(", ")} and f one of ${MOCKUP_VIEW_PLACES.join(", ")} (mockupViewFor computes it); a scene is mockup=<sceneId>, not view`);
104
+ if (ctx.aspect !== "8:3") throw new Error(`[snowcone] E_VIEW_PARAM_INVALID: view is a crop of a plate's 8:3 strip and goes with aspect "8:3" only (got ${ctx.aspect === void 0 ? "no aspect" : `"${ctx.aspect}"`})`);
105
+ if (ctx.preset !== void 0) throw new Error(`[snowcone] E_VIEW_PARAM_INVALID: view takes no preset (a preset sets its own aspect); drop preset`);
106
+ if (ctx.width !== void 0 && !(Number.isFinite(ctx.width) && ctx.width > 0)) throw new Error(`[snowcone] E_VIEW_PARAM_INVALID: width ${ctx.width} beside view must be a positive number of px (or omit it: the crop's own px)`);
107
+ return v;
108
+ }
76
109
  var MOCKUP_PRESETS = {
77
110
  tiktok: { aspect: "9:16", width: 1200 },
78
111
  // 1080x1920
@@ -186,7 +219,8 @@ function buildMockupUrl(options, cfg) {
186
219
  );
187
220
  }
188
221
  }
189
- const width = normalizeWidth(options.width);
222
+ const view = options.view !== void 0 ? requireMockupView(options.view, { aspect: options.aspect, width: options.width }) : void 0;
223
+ const width = view ? options.width !== void 0 ? normalizeWidth(options.width) : void 0 : normalizeWidth(options.width);
190
224
  const base = cfg.mockupBaseUrl.replace(/\/+$/, "");
191
225
  const path = `/${encodeURIComponent(options.productId)}`;
192
226
  let queryString = `${PARAMS.shop}=${encodeURIComponent(cfg.shop)}`;
@@ -204,7 +238,7 @@ function buildMockupUrl(options, cfg) {
204
238
  }
205
239
  queryString += `&${PARAMS.variant}=${encodeURIComponent(options.variantId)}`;
206
240
  queryString += `&${PARAMS.mockup}=${encodeURIComponent(options.mockupId)}`;
207
- queryString += `&${PARAMS.width}=${width}`;
241
+ if (width !== void 0) queryString += `&${PARAMS.width}=${width}`;
208
242
  if (options.optionSelections && Object.keys(options.optionSelections).length > 0) {
209
243
  const sorted = {};
210
244
  for (const k of Object.keys(options.optionSelections).sort()) {
@@ -224,6 +258,7 @@ function buildMockupUrl(options, cfg) {
224
258
  if (options.aspect && options.aspect !== "16:9") {
225
259
  queryString += `&${PARAMS.aspect}=${encodeURIComponent(options.aspect)}`;
226
260
  }
261
+ if (view) queryString += `&${PARAMS.view}=${encodeURIComponent(view)}`;
227
262
  if (options.maskOverrides && options.maskOverrides.length > 0) {
228
263
  const maskOverridesBase64 = btoa(JSON.stringify(options.maskOverrides));
229
264
  queryString += `&${PARAMS.maskOverrides}=${encodeURIComponent(maskOverridesBase64)}`;
@@ -292,11 +327,13 @@ function buildPublicMockupUrl(options, cfg = {}) {
292
327
  if (options.mockup !== void 0) {
293
328
  parts.push(`${PARAMS.mockup}=${enc(options.mockup)}`);
294
329
  }
330
+ const view = options.view !== void 0 ? requireMockupView(options.view, { aspect: options.aspect, width: options.width, preset: options.preset }) : void 0;
295
331
  const shape = options.preset !== void 0 ? resolvePreset(options.preset, options.aspect, options.width) : { aspect: options.aspect, width: options.width };
296
332
  if (shape.width !== void 0) parts.push(`${PARAMS.width}=${shape.width}`);
297
333
  if (shape.aspect !== void 0 && shape.aspect !== "16:9") {
298
334
  parts.push(`${PARAMS.aspect}=${enc(shape.aspect)}`);
299
335
  }
336
+ if (view) parts.push(`${PARAMS.view}=${enc(view)}`);
300
337
  if (options.bg) {
301
338
  parts.push(`${PARAMS.bg}=${requireBgColor(options.bg)}`);
302
339
  }
@@ -312,6 +349,7 @@ var PUBLIC_PARAM_NAMES = [
312
349
  PARAMS.mockup,
313
350
  PARAMS.width,
314
351
  PARAMS.aspect,
352
+ PARAMS.view,
315
353
  PARAMS.bg,
316
354
  PARAMS.signature
317
355
  ];
@@ -370,6 +408,10 @@ async function signDevSig(canonical, secret) {
370
408
  export {
371
409
  SNOWCONE_HOSTS,
372
410
  SNOWCONE_REALTIME_WS_URL,
411
+ MOCKUP_VIEW_SHAPES,
412
+ MOCKUP_VIEW_PLACES,
413
+ canonicalMockupView,
414
+ mockupViewFor,
373
415
  normalizeWidth,
374
416
  normalizeDesignElements,
375
417
  buildMockupUrl,
package/dist/index.cjs CHANGED
@@ -49,6 +49,8 @@ __export(src_exports, {
49
49
  Focus: () => Focus,
50
50
  LifecycleManager: () => LifecycleManager,
51
51
  LitAdapter: () => LitAdapter,
52
+ MOCKUP_VIEW_PLACES: () => MOCKUP_VIEW_PLACES,
53
+ MOCKUP_VIEW_SHAPES: () => MOCKUP_VIEW_SHAPES,
52
54
  PDP_GALLERY_LIMIT: () => PDP_GALLERY_LIMIT,
53
55
  ProductContextManager: () => ProductContextManager,
54
56
  ProductLoader: () => ProductLoader,
@@ -75,6 +77,7 @@ __export(src_exports, {
75
77
  autoRegister: () => autoRegister,
76
78
  bffSigner: () => bffSigner,
77
79
  buildMockupUrl: () => buildMockupUrl2,
80
+ canonicalMockupView: () => canonicalMockupView,
78
81
  componentRegistry: () => componentRegistry,
79
82
  computeDisabledChoices: () => computeDisabledChoices,
80
83
  createAddToCartEvent: () => createAddToCartEvent,
@@ -140,6 +143,7 @@ __export(src_exports, {
140
143
  mintRealtimeGrant: () => mintRealtimeGrant,
141
144
  mockupRole: () => mockupRole,
142
145
  mockupUrl: () => mockupUrl,
146
+ mockupViewFor: () => mockupViewFor,
143
147
  normalizeChoice: () => normalizeChoice,
144
148
  ordinaryMockups: () => ordinaryMockups,
145
149
  pictureForVariant: () => pictureForVariant,
@@ -152,6 +156,7 @@ __export(src_exports, {
152
156
  resolveVariantId: () => resolveVariantId,
153
157
  retryOperation: () => retryOperation,
154
158
  searchDesigns: () => searchDesigns,
159
+ sessionViews: () => sessionViews,
155
160
  simulateCartOperation: () => simulateCartOperation,
156
161
  toCombinations: () => toCombinations,
157
162
  toOptionAttributes: () => toOptionAttributes,
@@ -189,7 +194,9 @@ var CatalogProductSchema = import_zod.z.object({
189
194
  gvids: import_zod.z.array(import_zod.z.string()),
190
195
  // Kept through a successful parse (zod strips undeclared keys): the PDP shows one size picture, the chosen size's.
191
196
  // Any mark is kept (a parse must not strip it): only an absent one is an ordinary picture (mockupRole.ts).
192
- linkedAs: import_zod.z.string().optional()
197
+ linkedAs: import_zod.z.string().optional(),
198
+ // A plate's 8:3 strip (the desktop hero's view= crop): kept through a parse like linkedAs.
199
+ strip: import_zod.z.object({ shape: import_zod.z.literal("8:3"), productX: import_zod.z.number().min(0).max(1) }).optional()
193
200
  })
194
201
  ).optional(),
195
202
  options: import_zod.z.object({
@@ -314,6 +321,12 @@ var PARAMS = {
314
321
  width: "width",
315
322
  grain: "grain",
316
323
  aspect: "aspect",
324
+ /**
325
+ * `view=<r>@<f>`: a crop of a plate's 8:3 strip, for a page hero that shows only part of it ({@link canonicalMockupView}).
326
+ * Goes with `aspect=8:3` only. Without `width=` the crop is delivered at its own pixels; with `width=` at that width when
327
+ * smaller (the box only ever downscales: a page asks crop width x DPR, capped at the crop).
328
+ */
329
+ view: "view",
317
330
  /**
318
331
  * Background color (6-hex, no '#') painted behind the mockup — visible only
319
332
  * where the mockup itself has transparency (studio-cutout shots) — or the
@@ -335,6 +348,33 @@ var PARAMS = {
335
348
  seal: "seal"
336
349
  };
337
350
  var BG_TRANSPARENT = "transparent";
351
+ var viewGrid = (from, to, step) => Array.from({ length: Math.round((to - from) / step) + 1 }, (_, i) => Math.round((from + i * step) * 1e3) / 1e3);
352
+ var MOCKUP_VIEW_SHAPES = viewGrid(1.3, 2.6, 0.1);
353
+ var MOCKUP_VIEW_PLACES = [...viewGrid(0.25, 0.475, 0.025), ...viewGrid(0.525, 0.75, 0.025)];
354
+ function canonicalMockupView(raw) {
355
+ const m = /^\s*(\d+(?:\.\d+)?)@(\d+(?:\.\d+)?)\s*$/.exec(String(raw));
356
+ if (!m) return null;
357
+ const r = MOCKUP_VIEW_SHAPES.find((x) => Math.abs(x - Number(m[1])) < 1e-9);
358
+ const f = MOCKUP_VIEW_PLACES.find((x) => Math.abs(x - Number(m[2])) < 1e-9);
359
+ return r === void 0 || f === void 0 ? null : `${r.toFixed(1)}@${String(f)}`;
360
+ }
361
+ function mockupViewFor(windowWidth, windowHeight, productCentreX) {
362
+ if (!(windowWidth > 0 && windowHeight > 0)) return null;
363
+ const rawR = windowWidth / windowHeight;
364
+ const r = MOCKUP_VIEW_SHAPES.find((x) => x >= rawR - 1e-9);
365
+ if (r === void 0) return null;
366
+ const rawF = productCentreX / windowWidth;
367
+ const f = MOCKUP_VIEW_PLACES.reduce((best, x) => Math.abs(x - rawF) < Math.abs(best - rawF) ? x : best, MOCKUP_VIEW_PLACES[0]);
368
+ return `${r.toFixed(1)}@${String(f)}`;
369
+ }
370
+ function requireMockupView(view, ctx) {
371
+ const v = canonicalMockupView(view);
372
+ if (!v) throw new Error(`[snowcone] E_VIEW_PARAM_INVALID: view "${view}" is not on the grid: <r>@<f>, r one of ${MOCKUP_VIEW_SHAPES.join(", ")} and f one of ${MOCKUP_VIEW_PLACES.join(", ")} (mockupViewFor computes it); a scene is mockup=<sceneId>, not view`);
373
+ if (ctx.aspect !== "8:3") throw new Error(`[snowcone] E_VIEW_PARAM_INVALID: view is a crop of a plate's 8:3 strip and goes with aspect "8:3" only (got ${ctx.aspect === void 0 ? "no aspect" : `"${ctx.aspect}"`})`);
374
+ if (ctx.preset !== void 0) throw new Error(`[snowcone] E_VIEW_PARAM_INVALID: view takes no preset (a preset sets its own aspect); drop preset`);
375
+ if (ctx.width !== void 0 && !(Number.isFinite(ctx.width) && ctx.width > 0)) throw new Error(`[snowcone] E_VIEW_PARAM_INVALID: width ${ctx.width} beside view must be a positive number of px (or omit it: the crop's own px)`);
376
+ return v;
377
+ }
338
378
  var MOCKUP_PRESETS = {
339
379
  tiktok: { aspect: "9:16", width: 1200 },
340
380
  // 1080x1920
@@ -448,7 +488,8 @@ function buildMockupUrl(options, cfg) {
448
488
  );
449
489
  }
450
490
  }
451
- const width = normalizeWidth(options.width);
491
+ const view = options.view !== void 0 ? requireMockupView(options.view, { aspect: options.aspect, width: options.width }) : void 0;
492
+ const width = view ? options.width !== void 0 ? normalizeWidth(options.width) : void 0 : normalizeWidth(options.width);
452
493
  const base = cfg.mockupBaseUrl.replace(/\/+$/, "");
453
494
  const path = `/${encodeURIComponent(options.productId)}`;
454
495
  let queryString = `${PARAMS.shop}=${encodeURIComponent(cfg.shop)}`;
@@ -466,7 +507,7 @@ function buildMockupUrl(options, cfg) {
466
507
  }
467
508
  queryString += `&${PARAMS.variant}=${encodeURIComponent(options.variantId)}`;
468
509
  queryString += `&${PARAMS.mockup}=${encodeURIComponent(options.mockupId)}`;
469
- queryString += `&${PARAMS.width}=${width}`;
510
+ if (width !== void 0) queryString += `&${PARAMS.width}=${width}`;
470
511
  if (options.optionSelections && Object.keys(options.optionSelections).length > 0) {
471
512
  const sorted = {};
472
513
  for (const k of Object.keys(options.optionSelections).sort()) {
@@ -486,6 +527,7 @@ function buildMockupUrl(options, cfg) {
486
527
  if (options.aspect && options.aspect !== "16:9") {
487
528
  queryString += `&${PARAMS.aspect}=${encodeURIComponent(options.aspect)}`;
488
529
  }
530
+ if (view) queryString += `&${PARAMS.view}=${encodeURIComponent(view)}`;
489
531
  if (options.maskOverrides && options.maskOverrides.length > 0) {
490
532
  const maskOverridesBase64 = btoa(JSON.stringify(options.maskOverrides));
491
533
  queryString += `&${PARAMS.maskOverrides}=${encodeURIComponent(maskOverridesBase64)}`;
@@ -554,11 +596,13 @@ function buildPublicMockupUrl(options, cfg = {}) {
554
596
  if (options.mockup !== void 0) {
555
597
  parts.push(`${PARAMS.mockup}=${enc(options.mockup)}`);
556
598
  }
599
+ const view = options.view !== void 0 ? requireMockupView(options.view, { aspect: options.aspect, width: options.width, preset: options.preset }) : void 0;
557
600
  const shape = options.preset !== void 0 ? resolvePreset(options.preset, options.aspect, options.width) : { aspect: options.aspect, width: options.width };
558
601
  if (shape.width !== void 0) parts.push(`${PARAMS.width}=${shape.width}`);
559
602
  if (shape.aspect !== void 0 && shape.aspect !== "16:9") {
560
603
  parts.push(`${PARAMS.aspect}=${enc(shape.aspect)}`);
561
604
  }
605
+ if (view) parts.push(`${PARAMS.view}=${enc(view)}`);
562
606
  if (options.bg) {
563
607
  parts.push(`${PARAMS.bg}=${requireBgColor(options.bg)}`);
564
608
  }
@@ -574,6 +618,7 @@ var PUBLIC_PARAM_NAMES = [
574
618
  PARAMS.mockup,
575
619
  PARAMS.width,
576
620
  PARAMS.aspect,
621
+ PARAMS.view,
577
622
  PARAMS.bg,
578
623
  PARAMS.signature
579
624
  ];
@@ -1071,6 +1116,12 @@ function getMockupUrl(a, b, c) {
1071
1116
  }
1072
1117
  const base = (opts.base ?? DEFAULT_MOCKUP_BASE).replace(/\/+$/, "");
1073
1118
  const assetUrl = opts.asset ?? legacyAsset;
1119
+ const sceneAlias = opts.mockup ?? opts.view;
1120
+ if (sceneAlias !== void 0 && canonicalMockupView(sceneAlias) !== null) {
1121
+ throw new Error(
1122
+ `[snowcone] E_VIEW_IS_STRIP_VIEW: "${sceneAlias}" is a crop of the 8:3 strip, not a mockup id; pass it as stripView (with aspect: "8:3", no width): view/mockup name the scene (emitted mockup=)`
1123
+ );
1124
+ }
1074
1125
  const url = buildPublicMockupUrl(
1075
1126
  {
1076
1127
  productCode,
@@ -1087,7 +1138,8 @@ function getMockupUrl(a, b, c) {
1087
1138
  ...opts.aspect !== void 0 ? { aspect: opts.aspect } : {},
1088
1139
  ...opts.preset !== void 0 ? { preset: opts.preset } : {},
1089
1140
  ...opts.bg !== void 0 ? { bg: opts.bg } : {},
1090
- ...opts.mockup ?? opts.view ? { mockup: opts.mockup ?? opts.view } : {},
1141
+ ...sceneAlias ? { mockup: sceneAlias } : {},
1142
+ ...opts.stripView !== void 0 ? { view: opts.stripView } : {},
1091
1143
  ...opts.variant !== void 0 ? { variant: opts.variant } : {},
1092
1144
  ...opts.placement !== void 0 ? { placement: opts.placement } : {}
1093
1145
  },
@@ -5150,6 +5202,26 @@ function createSvelteComponent(descriptor, svelte) {
5150
5202
  var REALTIME_WS_URL = SNOWCONE_REALTIME_WS_URL;
5151
5203
 
5152
5204
  // src/realtime/websocket.ts
5205
+ function sessionViews(config) {
5206
+ const raw = config.views;
5207
+ if (raw === void 0) return void 0;
5208
+ if (config.overlayCrop !== void 0 && config.overlayCrop !== "auto") {
5209
+ throw new Error(
5210
+ "[snowcone] E_REALTIME_VIEWS_WITH_CROP_RECT: a config with views takes no overlayCrop rect (a view IS the crop); send overlayCrop 'auto' (the print area inside the view) or none"
5211
+ );
5212
+ }
5213
+ const out = {};
5214
+ for (const [mockupId, v] of Object.entries(raw)) {
5215
+ const canonical = canonicalMockupView(String(v));
5216
+ if (!canonical) {
5217
+ throw new Error(
5218
+ `[snowcone] E_VIEW_PARAM_INVALID: views[${mockupId}] = ${JSON.stringify(v)} is not on the view grid <r>@<f> (compute it with mockupViewFor from @snowcone-app/sdk)`
5219
+ );
5220
+ }
5221
+ if (config.mockupIds.includes(mockupId)) out[mockupId] = canonical;
5222
+ }
5223
+ return Object.keys(out).length ? out : void 0;
5224
+ }
5153
5225
  function pruneUndefined(obj) {
5154
5226
  const out = {};
5155
5227
  for (const [k, v] of Object.entries(obj)) {
@@ -5630,6 +5702,7 @@ var RealtimeMockupService = class {
5630
5702
  data.imageUrl = frame.objectUrl;
5631
5703
  }
5632
5704
  sendConfig(config) {
5705
+ const views = sessionViews(config);
5633
5706
  if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
5634
5707
  this.addLog("WebSocket not connected, caching config");
5635
5708
  this.config = config;
@@ -5679,7 +5752,8 @@ var RealtimeMockupService = class {
5679
5752
  // socket (mockup_frame binary messages) instead of making us fetch the
5680
5753
  // imageUrl — saves a network round trip per render. Servers that don't
5681
5754
  // know the flag ignore it and we fall back to the URL.
5682
- config: { ...config, binaryFrames: true }
5755
+ // views go out pruned to this config's mockupIds (undefined = the key is dropped by JSON).
5756
+ config: { ...config, views, binaryFrames: true }
5683
5757
  };
5684
5758
  const messageStr = JSON.stringify(message);
5685
5759
  this.addLog(`\u{1F4E4} Sending config: ${JSON.stringify(message, null, 2)}`, "sent");
@@ -6750,6 +6824,8 @@ function createClient(config) {
6750
6824
  Focus,
6751
6825
  LifecycleManager,
6752
6826
  LitAdapter,
6827
+ MOCKUP_VIEW_PLACES,
6828
+ MOCKUP_VIEW_SHAPES,
6753
6829
  PDP_GALLERY_LIMIT,
6754
6830
  ProductContextManager,
6755
6831
  ProductLoader,
@@ -6776,6 +6852,7 @@ function createClient(config) {
6776
6852
  autoRegister,
6777
6853
  bffSigner,
6778
6854
  buildMockupUrl,
6855
+ canonicalMockupView,
6779
6856
  componentRegistry,
6780
6857
  computeDisabledChoices,
6781
6858
  createAddToCartEvent,
@@ -6841,6 +6918,7 @@ function createClient(config) {
6841
6918
  mintRealtimeGrant,
6842
6919
  mockupRole,
6843
6920
  mockupUrl,
6921
+ mockupViewFor,
6844
6922
  normalizeChoice,
6845
6923
  ordinaryMockups,
6846
6924
  pictureForVariant,
@@ -6853,6 +6931,7 @@ function createClient(config) {
6853
6931
  resolveVariantId,
6854
6932
  retryOperation,
6855
6933
  searchDesigns,
6934
+ sessionViews,
6856
6935
  simulateCartOperation,
6857
6936
  toCombinations,
6858
6937
  toOptionAttributes,
package/dist/index.d.cts CHANGED
@@ -1,9 +1,9 @@
1
1
  export { createDevFetcher } from './dev-fetcher.cjs';
2
- import { PublicDesign, PublicFill, PublicOptions, MockupAspect, MockupPreset } from '@snowcone-app/mockup-url';
3
- export { SNOWCONE_HOSTS, SNOWCONE_REALTIME_WS_URL, SnowconeHostRole } from '@snowcone-app/mockup-url';
2
+ import { PublicDesign, PublicFill, PublicOptions, MockupView, MockupAspect, MockupPreset } from '@snowcone-app/mockup-url';
3
+ export { MOCKUP_VIEW_PLACES, MOCKUP_VIEW_SHAPES, MockupView, SNOWCONE_HOSTS, SNOWCONE_REALTIME_WS_URL, SnowconeHostRole, canonicalMockupView, mockupViewFor } from '@snowcone-app/mockup-url';
4
4
  export { GalleryReason, GalleryStanding, MockupRole, OrdinaryMockups, PDP_GALLERY_LIMIT, SIZE_PICTURE, gallerySizePicture, galleryStanding, mockupRole, ordinaryMockups, pictureForVariant, primaryMockup } from './mockup-role.cjs';
5
- 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-CvN0UU2j.cjs';
6
- 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-CvN0UU2j.cjs';
5
+ 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-CSJT_g8j.cjs';
6
+ 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, w as sessionViews } from './websocket-CSJT_g8j.cjs';
7
7
 
8
8
  interface CatalogProduct {
9
9
  id: string;
@@ -29,6 +29,13 @@ interface CatalogProduct {
29
29
  * What this mockup is on the product page. 'size-picture': the picture of ONE size (its gvids are that size). The gallery shows only the chosen size's one, last; ordinary-picture lookups (a variant's picture, a card) never return it. 'size-picture-released': a picture that handed its size's role to another (never shown, never an ordinary picture). Absent on ordinary mockups.
30
30
  */
31
31
  linkedAs?: "size-picture" | "size-picture-released";
32
+ /**
33
+ * A PLATE's wide strip (lane shapes #5520): present only when this mockup answers `aspect=8:3&view=<r>@<f>` (a crop of its 8:3 strip: it holds an 8:3 window and the product's box). `productX` is the product's centre along the strip, 0 (its left end) to 1 (its right end). The product page's desktop hero asks for the crop its window shows; a mockup without a strip keeps the 16:9 hero.
34
+ */
35
+ strip?: {
36
+ shape: "8:3";
37
+ productX: number;
38
+ };
32
39
  }[];
33
40
  options?: {
34
41
  selected?: {
@@ -375,8 +382,18 @@ interface GetMockupUrlOptions {
375
382
  * {@link GetMockupUrlOptions.aspect}.
376
383
  */
377
384
  width?: number;
378
- /** Camera view / mockup scene override (`view=<mockupId>`). Emitted as `mockup=`. */
385
+ /**
386
+ * Mockup scene override (a mockup id). Emitted as `mockup=` (legacy name: the wire's `view=` is the strip crop, see
387
+ * {@link GetMockupUrlOptions.stripView}). A `<r>@<f>` value here throws E_VIEW_IS_STRIP_VIEW.
388
+ */
379
389
  view?: string;
390
+ /**
391
+ * A crop of a plate's 8:3 strip, emitted as `view=<r>@<f>` ({@link mockupViewFor} computes it from the window the page
392
+ * shows): for a page hero that shows only part of the strip. Needs `aspect: "8:3"`; refuses `preset`. Without `width`
393
+ * the crop comes at its own pixels; a `width` is a downscale (ask the crop's CSS width x devicePixelRatio, capped at the
394
+ * crop: the box never enlarges). Only mockups whose catalog entry carries `strip` answer it.
395
+ */
396
+ stripView?: MockupView;
380
397
  /** Specific mockup scene/angle override. Alias of {@link GetMockupUrlOptions.view}. */
381
398
  mockup?: string;
382
399
  /** Specific variant override (a resolved gvid). */
package/dist/index.d.ts CHANGED
@@ -1,9 +1,9 @@
1
1
  export { createDevFetcher } from './dev-fetcher.js';
2
- import { PublicDesign, PublicFill, PublicOptions, MockupAspect, MockupPreset } from '@snowcone-app/mockup-url';
3
- export { SNOWCONE_HOSTS, SNOWCONE_REALTIME_WS_URL, SnowconeHostRole } from '@snowcone-app/mockup-url';
2
+ import { PublicDesign, PublicFill, PublicOptions, MockupView, MockupAspect, MockupPreset } from '@snowcone-app/mockup-url';
3
+ export { MOCKUP_VIEW_PLACES, MOCKUP_VIEW_SHAPES, MockupView, SNOWCONE_HOSTS, SNOWCONE_REALTIME_WS_URL, SnowconeHostRole, canonicalMockupView, mockupViewFor } from '@snowcone-app/mockup-url';
4
4
  export { GalleryReason, GalleryStanding, MockupRole, OrdinaryMockups, PDP_GALLERY_LIMIT, SIZE_PICTURE, gallerySizePicture, galleryStanding, mockupRole, ordinaryMockups, pictureForVariant, primaryMockup } from './mockup-role.js';
5
- 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-CvN0UU2j.js';
6
- 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-CvN0UU2j.js';
5
+ 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-CSJT_g8j.js';
6
+ 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, w as sessionViews } from './websocket-CSJT_g8j.js';
7
7
 
8
8
  interface CatalogProduct {
9
9
  id: string;
@@ -29,6 +29,13 @@ interface CatalogProduct {
29
29
  * What this mockup is on the product page. 'size-picture': the picture of ONE size (its gvids are that size). The gallery shows only the chosen size's one, last; ordinary-picture lookups (a variant's picture, a card) never return it. 'size-picture-released': a picture that handed its size's role to another (never shown, never an ordinary picture). Absent on ordinary mockups.
30
30
  */
31
31
  linkedAs?: "size-picture" | "size-picture-released";
32
+ /**
33
+ * A PLATE's wide strip (lane shapes #5520): present only when this mockup answers `aspect=8:3&view=<r>@<f>` (a crop of its 8:3 strip: it holds an 8:3 window and the product's box). `productX` is the product's centre along the strip, 0 (its left end) to 1 (its right end). The product page's desktop hero asks for the crop its window shows; a mockup without a strip keeps the 16:9 hero.
34
+ */
35
+ strip?: {
36
+ shape: "8:3";
37
+ productX: number;
38
+ };
32
39
  }[];
33
40
  options?: {
34
41
  selected?: {
@@ -375,8 +382,18 @@ interface GetMockupUrlOptions {
375
382
  * {@link GetMockupUrlOptions.aspect}.
376
383
  */
377
384
  width?: number;
378
- /** Camera view / mockup scene override (`view=<mockupId>`). Emitted as `mockup=`. */
385
+ /**
386
+ * Mockup scene override (a mockup id). Emitted as `mockup=` (legacy name: the wire's `view=` is the strip crop, see
387
+ * {@link GetMockupUrlOptions.stripView}). A `<r>@<f>` value here throws E_VIEW_IS_STRIP_VIEW.
388
+ */
379
389
  view?: string;
390
+ /**
391
+ * A crop of a plate's 8:3 strip, emitted as `view=<r>@<f>` ({@link mockupViewFor} computes it from the window the page
392
+ * shows): for a page hero that shows only part of the strip. Needs `aspect: "8:3"`; refuses `preset`. Without `width`
393
+ * the crop comes at its own pixels; a `width` is a downscale (ask the crop's CSS width x devicePixelRatio, capped at the
394
+ * crop: the box never enlarges). Only mockups whose catalog entry carries `strip` answer it.
395
+ */
396
+ stripView?: MockupView;
380
397
  /** Specific mockup scene/angle override. Alias of {@link GetMockupUrlOptions.view}. */
381
398
  mockup?: string;
382
399
  /** Specific variant override (a resolved gvid). */
package/dist/index.js CHANGED
@@ -1,19 +1,24 @@
1
1
  import {
2
2
  REALTIME_WS_URL,
3
- RealtimeMockupService
4
- } from "./chunk-KMDKCI4T.js";
3
+ RealtimeMockupService,
4
+ sessionViews
5
+ } from "./chunk-2MNYYJHG.js";
5
6
  import {
6
7
  createDevFetcher
7
8
  } from "./chunk-7VO4EL2V.js";
8
9
  import {
10
+ MOCKUP_VIEW_PLACES,
11
+ MOCKUP_VIEW_SHAPES,
9
12
  SNOWCONE_HOSTS,
10
13
  SNOWCONE_REALTIME_WS_URL,
11
14
  buildMockupUrl,
12
15
  buildPublicMockupUrl,
13
16
  canonicalForSig,
17
+ canonicalMockupView,
18
+ mockupViewFor,
14
19
  normalizeDesignElements,
15
20
  normalizeWidth
16
- } from "./chunk-O6I5SJT5.js";
21
+ } from "./chunk-KCIDK2T7.js";
17
22
  import {
18
23
  PDP_GALLERY_LIMIT,
19
24
  SIZE_PICTURE,
@@ -42,7 +47,9 @@ var CatalogProductSchema = z.object({
42
47
  gvids: z.array(z.string()),
43
48
  // Kept through a successful parse (zod strips undeclared keys): the PDP shows one size picture, the chosen size's.
44
49
  // Any mark is kept (a parse must not strip it): only an absent one is an ordinary picture (mockupRole.ts).
45
- linkedAs: z.string().optional()
50
+ linkedAs: z.string().optional(),
51
+ // A plate's 8:3 strip (the desktop hero's view= crop): kept through a parse like linkedAs.
52
+ strip: z.object({ shape: z.literal("8:3"), productX: z.number().min(0).max(1) }).optional()
46
53
  })
47
54
  ).optional(),
48
55
  options: z.object({
@@ -565,6 +572,12 @@ function getMockupUrl(a, b, c) {
565
572
  }
566
573
  const base = (opts.base ?? DEFAULT_MOCKUP_BASE).replace(/\/+$/, "");
567
574
  const assetUrl = opts.asset ?? legacyAsset;
575
+ const sceneAlias = opts.mockup ?? opts.view;
576
+ if (sceneAlias !== void 0 && canonicalMockupView(sceneAlias) !== null) {
577
+ throw new Error(
578
+ `[snowcone] E_VIEW_IS_STRIP_VIEW: "${sceneAlias}" is a crop of the 8:3 strip, not a mockup id; pass it as stripView (with aspect: "8:3", no width): view/mockup name the scene (emitted mockup=)`
579
+ );
580
+ }
568
581
  const url = buildPublicMockupUrl(
569
582
  {
570
583
  productCode,
@@ -581,7 +594,8 @@ function getMockupUrl(a, b, c) {
581
594
  ...opts.aspect !== void 0 ? { aspect: opts.aspect } : {},
582
595
  ...opts.preset !== void 0 ? { preset: opts.preset } : {},
583
596
  ...opts.bg !== void 0 ? { bg: opts.bg } : {},
584
- ...opts.mockup ?? opts.view ? { mockup: opts.mockup ?? opts.view } : {},
597
+ ...sceneAlias ? { mockup: sceneAlias } : {},
598
+ ...opts.stripView !== void 0 ? { view: opts.stripView } : {},
585
599
  ...opts.variant !== void 0 ? { variant: opts.variant } : {},
586
600
  ...opts.placement !== void 0 ? { placement: opts.placement } : {}
587
601
  },
@@ -5213,6 +5227,8 @@ export {
5213
5227
  Focus,
5214
5228
  LifecycleManager,
5215
5229
  LitAdapter,
5230
+ MOCKUP_VIEW_PLACES,
5231
+ MOCKUP_VIEW_SHAPES,
5216
5232
  PDP_GALLERY_LIMIT,
5217
5233
  ProductContextManager,
5218
5234
  ProductLoader,
@@ -5239,6 +5255,7 @@ export {
5239
5255
  autoRegister,
5240
5256
  bffSigner,
5241
5257
  buildMockupUrl2 as buildMockupUrl,
5258
+ canonicalMockupView,
5242
5259
  componentRegistry,
5243
5260
  computeDisabledChoices,
5244
5261
  createAddToCartEvent,
@@ -5304,6 +5321,7 @@ export {
5304
5321
  mintRealtimeGrant,
5305
5322
  mockupRole,
5306
5323
  mockupUrl,
5324
+ mockupViewFor,
5307
5325
  normalizeChoice,
5308
5326
  ordinaryMockups,
5309
5327
  pictureForVariant,
@@ -5316,6 +5334,7 @@ export {
5316
5334
  resolveVariantId,
5317
5335
  retryOperation,
5318
5336
  searchDesigns,
5337
+ sessionViews,
5319
5338
  simulateCartOperation,
5320
5339
  toCombinations,
5321
5340
  toOptionAttributes,
package/dist/react.cjs CHANGED
@@ -86,6 +86,12 @@ var PARAMS = {
86
86
  width: "width",
87
87
  grain: "grain",
88
88
  aspect: "aspect",
89
+ /**
90
+ * `view=<r>@<f>`: a crop of a plate's 8:3 strip, for a page hero that shows only part of it ({@link canonicalMockupView}).
91
+ * Goes with `aspect=8:3` only. Without `width=` the crop is delivered at its own pixels; with `width=` at that width when
92
+ * smaller (the box only ever downscales: a page asks crop width x DPR, capped at the crop).
93
+ */
94
+ view: "view",
89
95
  /**
90
96
  * Background color (6-hex, no '#') painted behind the mockup — visible only
91
97
  * where the mockup itself has transparency (studio-cutout shots) — or the
@@ -106,6 +112,16 @@ var PARAMS = {
106
112
  signature: "signature",
107
113
  seal: "seal"
108
114
  };
115
+ var viewGrid = (from, to, step) => Array.from({ length: Math.round((to - from) / step) + 1 }, (_, i) => Math.round((from + i * step) * 1e3) / 1e3);
116
+ var MOCKUP_VIEW_SHAPES = viewGrid(1.3, 2.6, 0.1);
117
+ var MOCKUP_VIEW_PLACES = [...viewGrid(0.25, 0.475, 0.025), ...viewGrid(0.525, 0.75, 0.025)];
118
+ function canonicalMockupView(raw) {
119
+ const m = /^\s*(\d+(?:\.\d+)?)@(\d+(?:\.\d+)?)\s*$/.exec(String(raw));
120
+ if (!m) return null;
121
+ const r = MOCKUP_VIEW_SHAPES.find((x) => Math.abs(x - Number(m[1])) < 1e-9);
122
+ const f = MOCKUP_VIEW_PLACES.find((x) => Math.abs(x - Number(m[2])) < 1e-9);
123
+ return r === void 0 || f === void 0 ? null : `${r.toFixed(1)}@${String(f)}`;
124
+ }
109
125
  var MOCKUP_PRESETS = {
110
126
  tiktok: { aspect: "9:16", width: 1200 },
111
127
  // 1080x1920
@@ -156,6 +172,7 @@ var PUBLIC_PARAM_NAMES = [
156
172
  PARAMS.mockup,
157
173
  PARAMS.width,
158
174
  PARAMS.aspect,
175
+ PARAMS.view,
159
176
  PARAMS.bg,
160
177
  PARAMS.signature
161
178
  ];
@@ -164,6 +181,26 @@ var PUBLIC_PARAM_NAMES = [
164
181
  var REALTIME_WS_URL = SNOWCONE_REALTIME_WS_URL;
165
182
 
166
183
  // src/realtime/websocket.ts
184
+ function sessionViews(config) {
185
+ const raw = config.views;
186
+ if (raw === void 0) return void 0;
187
+ if (config.overlayCrop !== void 0 && config.overlayCrop !== "auto") {
188
+ throw new Error(
189
+ "[snowcone] E_REALTIME_VIEWS_WITH_CROP_RECT: a config with views takes no overlayCrop rect (a view IS the crop); send overlayCrop 'auto' (the print area inside the view) or none"
190
+ );
191
+ }
192
+ const out = {};
193
+ for (const [mockupId, v] of Object.entries(raw)) {
194
+ const canonical = canonicalMockupView(String(v));
195
+ if (!canonical) {
196
+ throw new Error(
197
+ `[snowcone] E_VIEW_PARAM_INVALID: views[${mockupId}] = ${JSON.stringify(v)} is not on the view grid <r>@<f> (compute it with mockupViewFor from @snowcone-app/sdk)`
198
+ );
199
+ }
200
+ if (config.mockupIds.includes(mockupId)) out[mockupId] = canonical;
201
+ }
202
+ return Object.keys(out).length ? out : void 0;
203
+ }
167
204
  function pruneUndefined(obj) {
168
205
  const out = {};
169
206
  for (const [k, v] of Object.entries(obj)) {
@@ -644,6 +681,7 @@ var RealtimeMockupService = class {
644
681
  data.imageUrl = frame.objectUrl;
645
682
  }
646
683
  sendConfig(config) {
684
+ const views = sessionViews(config);
647
685
  if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
648
686
  this.addLog("WebSocket not connected, caching config");
649
687
  this.config = config;
@@ -693,7 +731,8 @@ var RealtimeMockupService = class {
693
731
  // socket (mockup_frame binary messages) instead of making us fetch the
694
732
  // imageUrl — saves a network round trip per render. Servers that don't
695
733
  // know the flag ignore it and we fall back to the URL.
696
- config: { ...config, binaryFrames: true }
734
+ // views go out pruned to this config's mockupIds (undefined = the key is dropped by JSON).
735
+ config: { ...config, views, binaryFrames: true }
697
736
  };
698
737
  const messageStr = JSON.stringify(message);
699
738
  this.addLog(`\u{1F4E4} Sending config: ${JSON.stringify(message, null, 2)}`, "sent");
package/dist/react.d.cts CHANGED
@@ -1,5 +1,6 @@
1
- import { M as MockupResult, R as RealtimeRenderError, j as RealtimeMockupCallbacks, W as WebSocketConfig, P as PlacementSettings, w as RealtimeAcksState, 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-CvN0UU2j.cjs';
1
+ import { M as MockupResult, R as RealtimeRenderError, j as RealtimeMockupCallbacks, W as WebSocketConfig, P as PlacementSettings, x as RealtimeAcksState, 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-CSJT_g8j.cjs';
2
2
  import { CSSProperties, ReactNode } from 'react';
3
+ import '@snowcone-app/mockup-url';
3
4
 
4
5
  interface UseRealtimeMockupOptions {
5
6
  wsUrl?: string;
package/dist/react.d.ts CHANGED
@@ -1,5 +1,6 @@
1
- import { M as MockupResult, R as RealtimeRenderError, j as RealtimeMockupCallbacks, W as WebSocketConfig, P as PlacementSettings, w as RealtimeAcksState, 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-CvN0UU2j.js';
1
+ import { M as MockupResult, R as RealtimeRenderError, j as RealtimeMockupCallbacks, W as WebSocketConfig, P as PlacementSettings, x as RealtimeAcksState, 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-CSJT_g8j.js';
2
2
  import { CSSProperties, ReactNode } from 'react';
3
+ import '@snowcone-app/mockup-url';
3
4
 
4
5
  interface UseRealtimeMockupOptions {
5
6
  wsUrl?: string;
package/dist/react.js CHANGED
@@ -1,8 +1,8 @@
1
1
  import {
2
2
  REALTIME_WS_URL,
3
3
  RealtimeMockupService
4
- } from "./chunk-KMDKCI4T.js";
5
- import "./chunk-O6I5SJT5.js";
4
+ } from "./chunk-2MNYYJHG.js";
5
+ import "./chunk-KCIDK2T7.js";
6
6
 
7
7
  // src/realtime/react.ts
8
8
  import { useCallback, useEffect, useRef, useState } from "react";
package/dist/server.cjs CHANGED
@@ -85,6 +85,12 @@ var PARAMS = {
85
85
  width: "width",
86
86
  grain: "grain",
87
87
  aspect: "aspect",
88
+ /**
89
+ * `view=<r>@<f>`: a crop of a plate's 8:3 strip, for a page hero that shows only part of it ({@link canonicalMockupView}).
90
+ * Goes with `aspect=8:3` only. Without `width=` the crop is delivered at its own pixels; with `width=` at that width when
91
+ * smaller (the box only ever downscales: a page asks crop width x DPR, capped at the crop).
92
+ */
93
+ view: "view",
88
94
  /**
89
95
  * Background color (6-hex, no '#') painted behind the mockup — visible only
90
96
  * where the mockup itself has transparency (studio-cutout shots) — or the
@@ -105,6 +111,9 @@ var PARAMS = {
105
111
  signature: "signature",
106
112
  seal: "seal"
107
113
  };
114
+ var viewGrid = (from, to, step) => Array.from({ length: Math.round((to - from) / step) + 1 }, (_, i) => Math.round((from + i * step) * 1e3) / 1e3);
115
+ var MOCKUP_VIEW_SHAPES = viewGrid(1.3, 2.6, 0.1);
116
+ var MOCKUP_VIEW_PLACES = [...viewGrid(0.25, 0.475, 0.025), ...viewGrid(0.525, 0.75, 0.025)];
108
117
  var MOCKUP_PRESETS = {
109
118
  tiktok: { aspect: "9:16", width: 1200 },
110
119
  // 1080x1920
@@ -155,6 +164,7 @@ var PUBLIC_PARAM_NAMES = [
155
164
  PARAMS.mockup,
156
165
  PARAMS.width,
157
166
  PARAMS.aspect,
167
+ PARAMS.view,
158
168
  PARAMS.bg,
159
169
  PARAMS.signature
160
170
  ];
package/dist/server.js CHANGED
@@ -2,7 +2,7 @@ import {
2
2
  SNOWCONE_HOSTS,
3
3
  canonicalForSig,
4
4
  signDevSig
5
- } from "./chunk-O6I5SJT5.js";
5
+ } from "./chunk-KCIDK2T7.js";
6
6
 
7
7
  // src/server.ts
8
8
  function json(body, status = 200) {
@@ -1,3 +1,5 @@
1
+ import { MockupView } from '@snowcone-app/mockup-url';
2
+
1
3
  type OptionSelection = Record<string, string>;
2
4
  interface OptionAttribute {
3
5
  key: string;
@@ -205,6 +207,13 @@ declare class AdapterRegistry {
205
207
  }
206
208
  declare const adapterRegistry: AdapterRegistry;
207
209
 
210
+ /**
211
+ * The `views` a config goes out with (lane shapes #5520, rendercenter rc#898): canonical, and only for mockups the config
212
+ * renders (`mockupIds`), so a session that narrows its set (the viewport policy, a priority update) never names a mockup
213
+ * the box would refuse; undefined when none is left. Throws, the fix in the message, on what the box refuses outright:
214
+ * a value off the view grid, or views beside an overlayCrop RECT (overlayCrop 'auto' is the print area inside the view).
215
+ */
216
+ declare function sessionViews(config: Pick<WebSocketConfig, 'views' | 'mockupIds' | 'overlayCrop'>): Record<string, MockupView> | undefined;
208
217
  interface PlacementSettings {
209
218
  tiles?: 0.25 | 0.5 | 1 | 2 | 4 | 8 | 16;
210
219
  scaleMode?: 'fill' | 'fit';
@@ -291,6 +300,13 @@ interface WebSocketConfig {
291
300
  * single product it is refused (`E_NOT_A_BUNDLE`).
292
301
  */
293
302
  picks?: Record<string, string>;
303
+ /**
304
+ * Per mockup, the crop of its plate's 8:3 strip the page's hero shows (`view=<r>@<f>`, lane shapes #5520): that
305
+ * mockup's live frame is `aspect=8:3&view=<v>` with no width, the same crop the static hero asks for, so it drops into
306
+ * the hero's box; with overlayCrop 'auto' the cropped frame's rect comes in the VIEW's fractions. Sent only for mockups
307
+ * in `mockupIds` ({@link sessionViews}); every other mockup renders as before. Not with an overlayCrop rect.
308
+ */
309
+ views?: Record<string, MockupView>;
294
310
  /**
295
311
  * ADR-0099 (bundle records only): the variant per slot — `role → gvid`.
296
312
  * A bundle session names its variants per ROLE; a bare `variantId` on a
@@ -668,4 +684,4 @@ declare class RealtimeMockupService {
668
684
  clearMockups(): void;
669
685
  }
670
686
 
671
- export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type PlacementSettings as P, type RealtimeRenderError as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, RealtimeMockupService as h, type ProductComponentContext as i, type RealtimeMockupCallbacks as j, type RealtimeMockupState as k, type RenderResult as l, type WebSocketMessage as m, adapterRegistry as n, computeDisabledChoices as o, createComponent as p, defineComponent as q, deriveDefaultSelection as r, findBestCombination as s, getPricePreview as t, isOptionAvailable as u, resolveBestCombination as v, type RealtimeAcksState as w };
687
+ export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type PlacementSettings as P, type RealtimeRenderError as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, RealtimeMockupService as h, type ProductComponentContext as i, type RealtimeMockupCallbacks as j, type RealtimeMockupState as k, type RenderResult as l, type WebSocketMessage as m, adapterRegistry as n, computeDisabledChoices as o, createComponent as p, defineComponent as q, deriveDefaultSelection as r, findBestCombination as s, getPricePreview as t, isOptionAvailable as u, resolveBestCombination as v, sessionViews as w, type RealtimeAcksState as x };
@@ -1,3 +1,5 @@
1
+ import { MockupView } from '@snowcone-app/mockup-url';
2
+
1
3
  type OptionSelection = Record<string, string>;
2
4
  interface OptionAttribute {
3
5
  key: string;
@@ -205,6 +207,13 @@ declare class AdapterRegistry {
205
207
  }
206
208
  declare const adapterRegistry: AdapterRegistry;
207
209
 
210
+ /**
211
+ * The `views` a config goes out with (lane shapes #5520, rendercenter rc#898): canonical, and only for mockups the config
212
+ * renders (`mockupIds`), so a session that narrows its set (the viewport policy, a priority update) never names a mockup
213
+ * the box would refuse; undefined when none is left. Throws, the fix in the message, on what the box refuses outright:
214
+ * a value off the view grid, or views beside an overlayCrop RECT (overlayCrop 'auto' is the print area inside the view).
215
+ */
216
+ declare function sessionViews(config: Pick<WebSocketConfig, 'views' | 'mockupIds' | 'overlayCrop'>): Record<string, MockupView> | undefined;
208
217
  interface PlacementSettings {
209
218
  tiles?: 0.25 | 0.5 | 1 | 2 | 4 | 8 | 16;
210
219
  scaleMode?: 'fill' | 'fit';
@@ -291,6 +300,13 @@ interface WebSocketConfig {
291
300
  * single product it is refused (`E_NOT_A_BUNDLE`).
292
301
  */
293
302
  picks?: Record<string, string>;
303
+ /**
304
+ * Per mockup, the crop of its plate's 8:3 strip the page's hero shows (`view=<r>@<f>`, lane shapes #5520): that
305
+ * mockup's live frame is `aspect=8:3&view=<v>` with no width, the same crop the static hero asks for, so it drops into
306
+ * the hero's box; with overlayCrop 'auto' the cropped frame's rect comes in the VIEW's fractions. Sent only for mockups
307
+ * in `mockupIds` ({@link sessionViews}); every other mockup renders as before. Not with an overlayCrop rect.
308
+ */
309
+ views?: Record<string, MockupView>;
294
310
  /**
295
311
  * ADR-0099 (bundle records only): the variant per slot — `role → gvid`.
296
312
  * A bundle session names its variants per ROLE; a bare `variantId` on a
@@ -668,4 +684,4 @@ declare class RealtimeMockupService {
668
684
  clearMockups(): void;
669
685
  }
670
686
 
671
- export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type PlacementSettings as P, type RealtimeRenderError as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, RealtimeMockupService as h, type ProductComponentContext as i, type RealtimeMockupCallbacks as j, type RealtimeMockupState as k, type RenderResult as l, type WebSocketMessage as m, adapterRegistry as n, computeDisabledChoices as o, createComponent as p, defineComponent as q, deriveDefaultSelection as r, findBestCombination as s, getPricePreview as t, isOptionAvailable as u, resolveBestCombination as v, type RealtimeAcksState as w };
687
+ export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type PlacementSettings as P, type RealtimeRenderError as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, RealtimeMockupService as h, type ProductComponentContext as i, type RealtimeMockupCallbacks as j, type RealtimeMockupState as k, type RenderResult as l, type WebSocketMessage as m, adapterRegistry as n, computeDisabledChoices as o, createComponent as p, defineComponent as q, deriveDefaultSelection as r, findBestCombination as s, getPricePreview as t, isOptionAvailable as u, resolveBestCombination as v, sessionViews as w, type RealtimeAcksState as x };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@snowcone-app/sdk",
3
- "version": "0.31.1",
3
+ "version": "0.31.4",
4
4
  "description": "Snowcone SDK for product mockups and print-on-demand",
5
5
  "keywords": [
6
6
  "merch",