@snowcone-app/sdk 0.31.1 → 0.31.2

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,11 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.31.2
4
+
5
+ ### Patch Changes
6
+
7
+ - [#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`.
8
+
3
9
  ## 0.31.1
4
10
 
5
11
  ### Patch Changes
@@ -1,6 +1,6 @@
1
1
  import {
2
2
  SNOWCONE_REALTIME_WS_URL
3
- } from "./chunk-O6I5SJT5.js";
3
+ } from "./chunk-WPVMN73Y.js";
4
4
 
5
5
  // src/realtime/constants.ts
6
6
  var REALTIME_WS_URL = SNOWCONE_REALTIME_WS_URL;
@@ -52,6 +52,11 @@ 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 and never with `width=`: the crop is delivered at its own pixels.
58
+ */
59
+ view: "view",
55
60
  /**
56
61
  * Background color (6-hex, no '#') painted behind the mockup — visible only
57
62
  * where the mockup itself has transparency (studio-cutout shots) — or the
@@ -73,6 +78,32 @@ var PARAMS = {
73
78
  seal: "seal"
74
79
  };
75
80
  var BG_TRANSPARENT = "transparent";
81
+ var viewGrid = (from, to, step) => Array.from({ length: Math.round((to - from) / step) + 1 }, (_, i) => Math.round((from + i * step) * 1e3) / 1e3);
82
+ var MOCKUP_VIEW_SHAPES = viewGrid(1.3, 2.6, 0.1);
83
+ var MOCKUP_VIEW_PLACES = [...viewGrid(0.25, 0.475, 0.025), ...viewGrid(0.525, 0.75, 0.025)];
84
+ function canonicalMockupView(raw) {
85
+ const m = /^\s*(\d+(?:\.\d+)?)@(\d+(?:\.\d+)?)\s*$/.exec(String(raw));
86
+ if (!m) return null;
87
+ const r = MOCKUP_VIEW_SHAPES.find((x) => Math.abs(x - Number(m[1])) < 1e-9);
88
+ const f = MOCKUP_VIEW_PLACES.find((x) => Math.abs(x - Number(m[2])) < 1e-9);
89
+ return r === void 0 || f === void 0 ? null : `${r.toFixed(1)}@${String(f)}`;
90
+ }
91
+ function mockupViewFor(windowWidth, windowHeight, productCentreX) {
92
+ if (!(windowWidth > 0 && windowHeight > 0)) return null;
93
+ const rawR = windowWidth / windowHeight;
94
+ const r = MOCKUP_VIEW_SHAPES.find((x) => x >= rawR - 1e-9);
95
+ if (r === void 0) return null;
96
+ const rawF = productCentreX / windowWidth;
97
+ const f = MOCKUP_VIEW_PLACES.reduce((best, x) => Math.abs(x - rawF) < Math.abs(best - rawF) ? x : best, MOCKUP_VIEW_PLACES[0]);
98
+ return `${r.toFixed(1)}@${String(f)}`;
99
+ }
100
+ function requireMockupView(view, ctx) {
101
+ const v = canonicalMockupView(view);
102
+ 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`);
103
+ 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}"`})`);
104
+ if (ctx.width !== void 0 || ctx.preset !== void 0) throw new Error(`[snowcone] E_VIEW_PARAM_INVALID: view takes no width or preset: the crop is delivered at its own pixels; drop ${ctx.width !== void 0 ? "width" : "preset"}`);
105
+ return v;
106
+ }
76
107
  var MOCKUP_PRESETS = {
77
108
  tiktok: { aspect: "9:16", width: 1200 },
78
109
  // 1080x1920
@@ -186,7 +217,8 @@ function buildMockupUrl(options, cfg) {
186
217
  );
187
218
  }
188
219
  }
189
- const width = normalizeWidth(options.width);
220
+ const view = options.view !== void 0 ? requireMockupView(options.view, { aspect: options.aspect, width: options.width }) : void 0;
221
+ const width = view ? void 0 : normalizeWidth(options.width);
190
222
  const base = cfg.mockupBaseUrl.replace(/\/+$/, "");
191
223
  const path = `/${encodeURIComponent(options.productId)}`;
192
224
  let queryString = `${PARAMS.shop}=${encodeURIComponent(cfg.shop)}`;
@@ -204,7 +236,7 @@ function buildMockupUrl(options, cfg) {
204
236
  }
205
237
  queryString += `&${PARAMS.variant}=${encodeURIComponent(options.variantId)}`;
206
238
  queryString += `&${PARAMS.mockup}=${encodeURIComponent(options.mockupId)}`;
207
- queryString += `&${PARAMS.width}=${width}`;
239
+ if (width !== void 0) queryString += `&${PARAMS.width}=${width}`;
208
240
  if (options.optionSelections && Object.keys(options.optionSelections).length > 0) {
209
241
  const sorted = {};
210
242
  for (const k of Object.keys(options.optionSelections).sort()) {
@@ -224,6 +256,7 @@ function buildMockupUrl(options, cfg) {
224
256
  if (options.aspect && options.aspect !== "16:9") {
225
257
  queryString += `&${PARAMS.aspect}=${encodeURIComponent(options.aspect)}`;
226
258
  }
259
+ if (view) queryString += `&${PARAMS.view}=${encodeURIComponent(view)}`;
227
260
  if (options.maskOverrides && options.maskOverrides.length > 0) {
228
261
  const maskOverridesBase64 = btoa(JSON.stringify(options.maskOverrides));
229
262
  queryString += `&${PARAMS.maskOverrides}=${encodeURIComponent(maskOverridesBase64)}`;
@@ -292,11 +325,13 @@ function buildPublicMockupUrl(options, cfg = {}) {
292
325
  if (options.mockup !== void 0) {
293
326
  parts.push(`${PARAMS.mockup}=${enc(options.mockup)}`);
294
327
  }
328
+ const view = options.view !== void 0 ? requireMockupView(options.view, { aspect: options.aspect, width: options.width, preset: options.preset }) : void 0;
295
329
  const shape = options.preset !== void 0 ? resolvePreset(options.preset, options.aspect, options.width) : { aspect: options.aspect, width: options.width };
296
330
  if (shape.width !== void 0) parts.push(`${PARAMS.width}=${shape.width}`);
297
331
  if (shape.aspect !== void 0 && shape.aspect !== "16:9") {
298
332
  parts.push(`${PARAMS.aspect}=${enc(shape.aspect)}`);
299
333
  }
334
+ if (view) parts.push(`${PARAMS.view}=${enc(view)}`);
300
335
  if (options.bg) {
301
336
  parts.push(`${PARAMS.bg}=${requireBgColor(options.bg)}`);
302
337
  }
@@ -312,6 +347,7 @@ var PUBLIC_PARAM_NAMES = [
312
347
  PARAMS.mockup,
313
348
  PARAMS.width,
314
349
  PARAMS.aspect,
350
+ PARAMS.view,
315
351
  PARAMS.bg,
316
352
  PARAMS.signature
317
353
  ];
@@ -370,6 +406,10 @@ async function signDevSig(canonical, secret) {
370
406
  export {
371
407
  SNOWCONE_HOSTS,
372
408
  SNOWCONE_REALTIME_WS_URL,
409
+ MOCKUP_VIEW_SHAPES,
410
+ MOCKUP_VIEW_PLACES,
411
+ canonicalMockupView,
412
+ mockupViewFor,
373
413
  normalizeWidth,
374
414
  normalizeDesignElements,
375
415
  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,
@@ -189,7 +193,9 @@ var CatalogProductSchema = import_zod.z.object({
189
193
  gvids: import_zod.z.array(import_zod.z.string()),
190
194
  // Kept through a successful parse (zod strips undeclared keys): the PDP shows one size picture, the chosen size's.
191
195
  // 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()
196
+ linkedAs: import_zod.z.string().optional(),
197
+ // A plate's 8:3 strip (the desktop hero's view= crop): kept through a parse like linkedAs.
198
+ strip: import_zod.z.object({ shape: import_zod.z.literal("8:3"), productX: import_zod.z.number().min(0).max(1) }).optional()
193
199
  })
194
200
  ).optional(),
195
201
  options: import_zod.z.object({
@@ -314,6 +320,11 @@ var PARAMS = {
314
320
  width: "width",
315
321
  grain: "grain",
316
322
  aspect: "aspect",
323
+ /**
324
+ * `view=<r>@<f>`: a crop of a plate's 8:3 strip, for a page hero that shows only part of it ({@link canonicalMockupView}).
325
+ * Goes with `aspect=8:3` only and never with `width=`: the crop is delivered at its own pixels.
326
+ */
327
+ view: "view",
317
328
  /**
318
329
  * Background color (6-hex, no '#') painted behind the mockup — visible only
319
330
  * where the mockup itself has transparency (studio-cutout shots) — or the
@@ -335,6 +346,32 @@ var PARAMS = {
335
346
  seal: "seal"
336
347
  };
337
348
  var BG_TRANSPARENT = "transparent";
349
+ var viewGrid = (from, to, step) => Array.from({ length: Math.round((to - from) / step) + 1 }, (_, i) => Math.round((from + i * step) * 1e3) / 1e3);
350
+ var MOCKUP_VIEW_SHAPES = viewGrid(1.3, 2.6, 0.1);
351
+ var MOCKUP_VIEW_PLACES = [...viewGrid(0.25, 0.475, 0.025), ...viewGrid(0.525, 0.75, 0.025)];
352
+ function canonicalMockupView(raw) {
353
+ const m = /^\s*(\d+(?:\.\d+)?)@(\d+(?:\.\d+)?)\s*$/.exec(String(raw));
354
+ if (!m) return null;
355
+ const r = MOCKUP_VIEW_SHAPES.find((x) => Math.abs(x - Number(m[1])) < 1e-9);
356
+ const f = MOCKUP_VIEW_PLACES.find((x) => Math.abs(x - Number(m[2])) < 1e-9);
357
+ return r === void 0 || f === void 0 ? null : `${r.toFixed(1)}@${String(f)}`;
358
+ }
359
+ function mockupViewFor(windowWidth, windowHeight, productCentreX) {
360
+ if (!(windowWidth > 0 && windowHeight > 0)) return null;
361
+ const rawR = windowWidth / windowHeight;
362
+ const r = MOCKUP_VIEW_SHAPES.find((x) => x >= rawR - 1e-9);
363
+ if (r === void 0) return null;
364
+ const rawF = productCentreX / windowWidth;
365
+ const f = MOCKUP_VIEW_PLACES.reduce((best, x) => Math.abs(x - rawF) < Math.abs(best - rawF) ? x : best, MOCKUP_VIEW_PLACES[0]);
366
+ return `${r.toFixed(1)}@${String(f)}`;
367
+ }
368
+ function requireMockupView(view, ctx) {
369
+ const v = canonicalMockupView(view);
370
+ 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`);
371
+ 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}"`})`);
372
+ if (ctx.width !== void 0 || ctx.preset !== void 0) throw new Error(`[snowcone] E_VIEW_PARAM_INVALID: view takes no width or preset: the crop is delivered at its own pixels; drop ${ctx.width !== void 0 ? "width" : "preset"}`);
373
+ return v;
374
+ }
338
375
  var MOCKUP_PRESETS = {
339
376
  tiktok: { aspect: "9:16", width: 1200 },
340
377
  // 1080x1920
@@ -448,7 +485,8 @@ function buildMockupUrl(options, cfg) {
448
485
  );
449
486
  }
450
487
  }
451
- const width = normalizeWidth(options.width);
488
+ const view = options.view !== void 0 ? requireMockupView(options.view, { aspect: options.aspect, width: options.width }) : void 0;
489
+ const width = view ? void 0 : normalizeWidth(options.width);
452
490
  const base = cfg.mockupBaseUrl.replace(/\/+$/, "");
453
491
  const path = `/${encodeURIComponent(options.productId)}`;
454
492
  let queryString = `${PARAMS.shop}=${encodeURIComponent(cfg.shop)}`;
@@ -466,7 +504,7 @@ function buildMockupUrl(options, cfg) {
466
504
  }
467
505
  queryString += `&${PARAMS.variant}=${encodeURIComponent(options.variantId)}`;
468
506
  queryString += `&${PARAMS.mockup}=${encodeURIComponent(options.mockupId)}`;
469
- queryString += `&${PARAMS.width}=${width}`;
507
+ if (width !== void 0) queryString += `&${PARAMS.width}=${width}`;
470
508
  if (options.optionSelections && Object.keys(options.optionSelections).length > 0) {
471
509
  const sorted = {};
472
510
  for (const k of Object.keys(options.optionSelections).sort()) {
@@ -486,6 +524,7 @@ function buildMockupUrl(options, cfg) {
486
524
  if (options.aspect && options.aspect !== "16:9") {
487
525
  queryString += `&${PARAMS.aspect}=${encodeURIComponent(options.aspect)}`;
488
526
  }
527
+ if (view) queryString += `&${PARAMS.view}=${encodeURIComponent(view)}`;
489
528
  if (options.maskOverrides && options.maskOverrides.length > 0) {
490
529
  const maskOverridesBase64 = btoa(JSON.stringify(options.maskOverrides));
491
530
  queryString += `&${PARAMS.maskOverrides}=${encodeURIComponent(maskOverridesBase64)}`;
@@ -554,11 +593,13 @@ function buildPublicMockupUrl(options, cfg = {}) {
554
593
  if (options.mockup !== void 0) {
555
594
  parts.push(`${PARAMS.mockup}=${enc(options.mockup)}`);
556
595
  }
596
+ const view = options.view !== void 0 ? requireMockupView(options.view, { aspect: options.aspect, width: options.width, preset: options.preset }) : void 0;
557
597
  const shape = options.preset !== void 0 ? resolvePreset(options.preset, options.aspect, options.width) : { aspect: options.aspect, width: options.width };
558
598
  if (shape.width !== void 0) parts.push(`${PARAMS.width}=${shape.width}`);
559
599
  if (shape.aspect !== void 0 && shape.aspect !== "16:9") {
560
600
  parts.push(`${PARAMS.aspect}=${enc(shape.aspect)}`);
561
601
  }
602
+ if (view) parts.push(`${PARAMS.view}=${enc(view)}`);
562
603
  if (options.bg) {
563
604
  parts.push(`${PARAMS.bg}=${requireBgColor(options.bg)}`);
564
605
  }
@@ -574,6 +615,7 @@ var PUBLIC_PARAM_NAMES = [
574
615
  PARAMS.mockup,
575
616
  PARAMS.width,
576
617
  PARAMS.aspect,
618
+ PARAMS.view,
577
619
  PARAMS.bg,
578
620
  PARAMS.signature
579
621
  ];
@@ -1071,6 +1113,12 @@ function getMockupUrl(a, b, c) {
1071
1113
  }
1072
1114
  const base = (opts.base ?? DEFAULT_MOCKUP_BASE).replace(/\/+$/, "");
1073
1115
  const assetUrl = opts.asset ?? legacyAsset;
1116
+ const sceneAlias = opts.mockup ?? opts.view;
1117
+ if (sceneAlias !== void 0 && canonicalMockupView(sceneAlias) !== null) {
1118
+ throw new Error(
1119
+ `[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=)`
1120
+ );
1121
+ }
1074
1122
  const url = buildPublicMockupUrl(
1075
1123
  {
1076
1124
  productCode,
@@ -1087,7 +1135,8 @@ function getMockupUrl(a, b, c) {
1087
1135
  ...opts.aspect !== void 0 ? { aspect: opts.aspect } : {},
1088
1136
  ...opts.preset !== void 0 ? { preset: opts.preset } : {},
1089
1137
  ...opts.bg !== void 0 ? { bg: opts.bg } : {},
1090
- ...opts.mockup ?? opts.view ? { mockup: opts.mockup ?? opts.view } : {},
1138
+ ...sceneAlias ? { mockup: sceneAlias } : {},
1139
+ ...opts.stripView !== void 0 ? { view: opts.stripView } : {},
1091
1140
  ...opts.variant !== void 0 ? { variant: opts.variant } : {},
1092
1141
  ...opts.placement !== void 0 ? { placement: opts.placement } : {}
1093
1142
  },
@@ -6750,6 +6799,8 @@ function createClient(config) {
6750
6799
  Focus,
6751
6800
  LifecycleManager,
6752
6801
  LitAdapter,
6802
+ MOCKUP_VIEW_PLACES,
6803
+ MOCKUP_VIEW_SHAPES,
6753
6804
  PDP_GALLERY_LIMIT,
6754
6805
  ProductContextManager,
6755
6806
  ProductLoader,
@@ -6776,6 +6827,7 @@ function createClient(config) {
6776
6827
  autoRegister,
6777
6828
  bffSigner,
6778
6829
  buildMockupUrl,
6830
+ canonicalMockupView,
6779
6831
  componentRegistry,
6780
6832
  computeDisabledChoices,
6781
6833
  createAddToCartEvent,
@@ -6841,6 +6893,7 @@ function createClient(config) {
6841
6893
  mintRealtimeGrant,
6842
6894
  mockupRole,
6843
6895
  mockupUrl,
6896
+ mockupViewFor,
6844
6897
  normalizeChoice,
6845
6898
  ordinaryMockups,
6846
6899
  pictureForVariant,
package/dist/index.d.cts CHANGED
@@ -1,6 +1,6 @@
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
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
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';
@@ -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,17 @@ 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 `width` and `preset` (the
393
+ * crop is delivered at its own pixels). Only mockups whose catalog entry carries `strip` answer it.
394
+ */
395
+ stripView?: MockupView;
380
396
  /** Specific mockup scene/angle override. Alias of {@link GetMockupUrlOptions.view}. */
381
397
  mockup?: string;
382
398
  /** Specific variant override (a resolved gvid). */
package/dist/index.d.ts CHANGED
@@ -1,6 +1,6 @@
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
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
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';
@@ -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,17 @@ 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 `width` and `preset` (the
393
+ * crop is delivered at its own pixels). Only mockups whose catalog entry carries `strip` answer it.
394
+ */
395
+ stripView?: MockupView;
380
396
  /** Specific mockup scene/angle override. Alias of {@link GetMockupUrlOptions.view}. */
381
397
  mockup?: string;
382
398
  /** Specific variant override (a resolved gvid). */
package/dist/index.js CHANGED
@@ -1,19 +1,23 @@
1
1
  import {
2
2
  REALTIME_WS_URL,
3
3
  RealtimeMockupService
4
- } from "./chunk-KMDKCI4T.js";
4
+ } from "./chunk-5LYS3YP5.js";
5
5
  import {
6
6
  createDevFetcher
7
7
  } from "./chunk-7VO4EL2V.js";
8
8
  import {
9
+ MOCKUP_VIEW_PLACES,
10
+ MOCKUP_VIEW_SHAPES,
9
11
  SNOWCONE_HOSTS,
10
12
  SNOWCONE_REALTIME_WS_URL,
11
13
  buildMockupUrl,
12
14
  buildPublicMockupUrl,
13
15
  canonicalForSig,
16
+ canonicalMockupView,
17
+ mockupViewFor,
14
18
  normalizeDesignElements,
15
19
  normalizeWidth
16
- } from "./chunk-O6I5SJT5.js";
20
+ } from "./chunk-WPVMN73Y.js";
17
21
  import {
18
22
  PDP_GALLERY_LIMIT,
19
23
  SIZE_PICTURE,
@@ -42,7 +46,9 @@ var CatalogProductSchema = z.object({
42
46
  gvids: z.array(z.string()),
43
47
  // Kept through a successful parse (zod strips undeclared keys): the PDP shows one size picture, the chosen size's.
44
48
  // 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()
49
+ linkedAs: z.string().optional(),
50
+ // A plate's 8:3 strip (the desktop hero's view= crop): kept through a parse like linkedAs.
51
+ strip: z.object({ shape: z.literal("8:3"), productX: z.number().min(0).max(1) }).optional()
46
52
  })
47
53
  ).optional(),
48
54
  options: z.object({
@@ -565,6 +571,12 @@ function getMockupUrl(a, b, c) {
565
571
  }
566
572
  const base = (opts.base ?? DEFAULT_MOCKUP_BASE).replace(/\/+$/, "");
567
573
  const assetUrl = opts.asset ?? legacyAsset;
574
+ const sceneAlias = opts.mockup ?? opts.view;
575
+ if (sceneAlias !== void 0 && canonicalMockupView(sceneAlias) !== null) {
576
+ throw new Error(
577
+ `[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=)`
578
+ );
579
+ }
568
580
  const url = buildPublicMockupUrl(
569
581
  {
570
582
  productCode,
@@ -581,7 +593,8 @@ function getMockupUrl(a, b, c) {
581
593
  ...opts.aspect !== void 0 ? { aspect: opts.aspect } : {},
582
594
  ...opts.preset !== void 0 ? { preset: opts.preset } : {},
583
595
  ...opts.bg !== void 0 ? { bg: opts.bg } : {},
584
- ...opts.mockup ?? opts.view ? { mockup: opts.mockup ?? opts.view } : {},
596
+ ...sceneAlias ? { mockup: sceneAlias } : {},
597
+ ...opts.stripView !== void 0 ? { view: opts.stripView } : {},
585
598
  ...opts.variant !== void 0 ? { variant: opts.variant } : {},
586
599
  ...opts.placement !== void 0 ? { placement: opts.placement } : {}
587
600
  },
@@ -5213,6 +5226,8 @@ export {
5213
5226
  Focus,
5214
5227
  LifecycleManager,
5215
5228
  LitAdapter,
5229
+ MOCKUP_VIEW_PLACES,
5230
+ MOCKUP_VIEW_SHAPES,
5216
5231
  PDP_GALLERY_LIMIT,
5217
5232
  ProductContextManager,
5218
5233
  ProductLoader,
@@ -5239,6 +5254,7 @@ export {
5239
5254
  autoRegister,
5240
5255
  bffSigner,
5241
5256
  buildMockupUrl2 as buildMockupUrl,
5257
+ canonicalMockupView,
5242
5258
  componentRegistry,
5243
5259
  computeDisabledChoices,
5244
5260
  createAddToCartEvent,
@@ -5304,6 +5320,7 @@ export {
5304
5320
  mintRealtimeGrant,
5305
5321
  mockupRole,
5306
5322
  mockupUrl,
5323
+ mockupViewFor,
5307
5324
  normalizeChoice,
5308
5325
  ordinaryMockups,
5309
5326
  pictureForVariant,
package/dist/react.cjs CHANGED
@@ -86,6 +86,11 @@ 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 and never with `width=`: the crop is delivered at its own pixels.
92
+ */
93
+ view: "view",
89
94
  /**
90
95
  * Background color (6-hex, no '#') painted behind the mockup — visible only
91
96
  * where the mockup itself has transparency (studio-cutout shots) — or the
@@ -106,6 +111,9 @@ var PARAMS = {
106
111
  signature: "signature",
107
112
  seal: "seal"
108
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)];
109
117
  var MOCKUP_PRESETS = {
110
118
  tiktok: { aspect: "9:16", width: 1200 },
111
119
  // 1080x1920
@@ -156,6 +164,7 @@ var PUBLIC_PARAM_NAMES = [
156
164
  PARAMS.mockup,
157
165
  PARAMS.width,
158
166
  PARAMS.aspect,
167
+ PARAMS.view,
159
168
  PARAMS.bg,
160
169
  PARAMS.signature
161
170
  ];
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-5LYS3YP5.js";
5
+ import "./chunk-WPVMN73Y.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,11 @@ 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 and never with `width=`: the crop is delivered at its own pixels.
91
+ */
92
+ view: "view",
88
93
  /**
89
94
  * Background color (6-hex, no '#') painted behind the mockup — visible only
90
95
  * where the mockup itself has transparency (studio-cutout shots) — or the
@@ -105,6 +110,9 @@ var PARAMS = {
105
110
  signature: "signature",
106
111
  seal: "seal"
107
112
  };
113
+ var viewGrid = (from, to, step) => Array.from({ length: Math.round((to - from) / step) + 1 }, (_, i) => Math.round((from + i * step) * 1e3) / 1e3);
114
+ var MOCKUP_VIEW_SHAPES = viewGrid(1.3, 2.6, 0.1);
115
+ var MOCKUP_VIEW_PLACES = [...viewGrid(0.25, 0.475, 0.025), ...viewGrid(0.525, 0.75, 0.025)];
108
116
  var MOCKUP_PRESETS = {
109
117
  tiktok: { aspect: "9:16", width: 1200 },
110
118
  // 1080x1920
@@ -155,6 +163,7 @@ var PUBLIC_PARAM_NAMES = [
155
163
  PARAMS.mockup,
156
164
  PARAMS.width,
157
165
  PARAMS.aspect,
166
+ PARAMS.view,
158
167
  PARAMS.bg,
159
168
  PARAMS.signature
160
169
  ];
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-WPVMN73Y.js";
6
6
 
7
7
  // src/server.ts
8
8
  function json(body, status = 200) {
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.2",
4
4
  "description": "Snowcone SDK for product mockups and print-on-demand",
5
5
  "keywords": [
6
6
  "merch",