@snowcone-app/sdk 0.18.1 → 0.20.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 CHANGED
@@ -1,5 +1,32 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.20.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#1003](https://github.com/snowcone-app/snowcone-monorepo/pull/1003) [`ada5ed2`](https://github.com/snowcone-app/snowcone-monorepo/commit/ada5ed200f219787bc97018e0c5811ea8e4c2fa1) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Background color joins the public mockup-URL grammar and the agent shop API.
8
+ - `bg=<6-hex>` is now a first-class public URL param (`buildPublicMockupUrl`,
9
+ `parsePublicUrl`, strict-param allowlist) — painted behind the mockup wherever
10
+ the scene is transparent. Precedence: per-URL `bg` > the shop's configured
11
+ default (`mockup_bg_color`) > transparent.
12
+ - SDK: `getMockupUrl(..., { bg })` emits the param (normalized 6-hex, `#`
13
+ optional).
14
+ - MCP: new `snowcone_set_mockup_background` tool sets/clears a sandbox shop's
15
+ default background; `snowcone_mint_shop` accepts `mockup_bg_color` at birth;
16
+ `snowcone_render_mockup` / `snowcone_buy_url` accept a per-render `bg`.
17
+
18
+ - [#1008](https://github.com/snowcone-app/snowcone-monorepo/pull/1008) [`f66c9c3`](https://github.com/snowcone-app/snowcone-monorepo/commit/f66c9c3b1ca2ab50bc390feb4a691cd95bb53abd) Thanks [@kevinsproles](https://github.com/kevinsproles)! - `bg=transparent` — the per-render escape hatch from a shop's default mockup
19
+ background. The reserved token (exported as `BG_TRANSPARENT`, accepted by
20
+ `normalizeBgColor`) pins the raw transparent studio cutout for one render even
21
+ when the shop has `mockup_bg_color` set. Accepted by `getMockupUrl({ bg })`,
22
+ the MCP render/buy tools, and the public URL grammar.
23
+
24
+ ## 0.19.0
25
+
26
+ ### Minor Changes
27
+
28
+ - [#887](https://github.com/snowcone-app/snowcone-monorepo/pull/887) [`e731ea4`](https://github.com/snowcone-app/snowcone-monorepo/commit/e731ea4fb0c8f2c642c8d6e06bc3015f00391a30) Thanks [@kevinsproles](https://github.com/kevinsproles)! - `getMockupUrl`/`getBuyUrl`: `asset` is now a base design that broadcasts to every product placement, and a new `placements` override map targets individual placements (ADR-0089). One image now appears on all placements by default; per-placement art is the advanced opt-in. The resolver-side broadcast is already live; this publishes the typed `placements` builder option to match.
29
+
3
30
  ## 0.18.1
4
31
 
5
32
  ### Patch Changes
package/README.md CHANGED
@@ -107,6 +107,9 @@ const url = getMockupUrl(productCode: string, opts: {
107
107
  variant?: string; // Optional: specific resolved variant (gvid)
108
108
  placement?: string; // Optional: specific print area (single-asset only)
109
109
  aspect?: '16:9' | '2:3';// Optional: canvas aspect ratio
110
+ bg?: string; // Optional: background color behind the mockup (6-hex, '#' optional).
111
+ // Visible only where the scene is transparent; omit to use the
112
+ // shop's configured default (mockup_bg_color), else transparent.
110
113
  }): string;
111
114
  ```
112
115
 
@@ -27,6 +27,13 @@ var PARAMS = {
27
27
  width: "width",
28
28
  grain: "grain",
29
29
  aspect: "aspect",
30
+ /**
31
+ * Background color (6-hex, no '#') painted behind the mockup — visible only
32
+ * where the mockup itself has transparency (studio-cutout shots) — or the
33
+ * reserved `transparent` token, which suppresses the shop default for this
34
+ * one render. Absent = the shop's configured default, else transparent.
35
+ */
36
+ bg: "bg",
30
37
  /** Live preview/calibration mask overrides (not cached). */
31
38
  maskOverrides: "maskOverrides",
32
39
  /**
@@ -40,6 +47,21 @@ var PARAMS = {
40
47
  signature: "signature",
41
48
  seal: "seal"
42
49
  };
50
+ var BG_TRANSPARENT = "transparent";
51
+ function normalizeBgColor(raw) {
52
+ const value = raw.trim().replace(/^#/, "").toLowerCase();
53
+ if (value === BG_TRANSPARENT) return BG_TRANSPARENT;
54
+ return /^[0-9a-f]{6}$/.test(value) ? value : null;
55
+ }
56
+ function requireBgColor(raw) {
57
+ const bg = normalizeBgColor(raw);
58
+ if (bg === null) {
59
+ throw new Error(
60
+ `[snowcone] bg must be a 6-digit hex color ('#' optional, e.g. "f5f0ea") or "transparent", got "${raw}"`
61
+ );
62
+ }
63
+ return bg;
64
+ }
43
65
  function asSimpleAsset(design) {
44
66
  if (design.length !== 1) return null;
45
67
  const el = design[0];
@@ -124,6 +146,9 @@ function buildMockupUrl(options, cfg) {
124
146
  if (options.effects?.grain) {
125
147
  queryString += `&${PARAMS.grain}=${options.effects.grain}`;
126
148
  }
149
+ if (options.bg) {
150
+ queryString += `&${PARAMS.bg}=${requireBgColor(options.bg)}`;
151
+ }
127
152
  if (options.aspect && options.aspect !== "16:9") {
128
153
  queryString += `&${PARAMS.aspect}=${encodeURIComponent(options.aspect)}`;
129
154
  }
@@ -147,28 +172,32 @@ function buildPublicMockupUrl(options, cfg = {}) {
147
172
  const enc = encodeURIComponent;
148
173
  const parts = [];
149
174
  parts.push(`${PARAMS.shop}=${enc(options.shop)}`);
150
- if (options.design) {
151
- for (const key of Object.keys(options.design).sort()) {
152
- const fill = options.design[key];
153
- const k = enc(key);
154
- if (typeof fill === "string") {
155
- parts.push(`${PARAM_PREFIX.asset}${k}=${enc(fill)}`);
156
- } else if ("color" in fill) {
157
- parts.push(`${PARAM_PREFIX.color}${k}=${enc(fill.color)}`);
158
- } else {
159
- parts.push(`${PARAM_PREFIX.asset}${k}=${enc(fill.src)}`);
160
- if (fill.tile !== void 0) {
161
- parts.push(`${PARAM_PREFIX.tile}${k}=${fill.tile}`);
162
- }
163
- if (fill.align !== void 0) {
164
- parts.push(`${PARAM_PREFIX.align}${k}=${enc(fill.align)}`);
175
+ if (options.designRef !== void 0) {
176
+ parts.push(`${PARAMS.design}=${enc(options.designRef)}`);
177
+ } else {
178
+ if (options.assetUrl !== void 0) {
179
+ parts.push(`${PARAMS.asset}=${enc(options.assetUrl)}`);
180
+ }
181
+ const overrides = options.design || options.placements ? { ...options.design ?? {}, ...options.placements ?? {} } : void 0;
182
+ if (overrides) {
183
+ for (const key of Object.keys(overrides).sort()) {
184
+ const fill = overrides[key];
185
+ const k = enc(key);
186
+ if (typeof fill === "string") {
187
+ parts.push(`${PARAM_PREFIX.asset}${k}=${enc(fill)}`);
188
+ } else if ("color" in fill) {
189
+ parts.push(`${PARAM_PREFIX.color}${k}=${enc(fill.color)}`);
190
+ } else {
191
+ parts.push(`${PARAM_PREFIX.asset}${k}=${enc(fill.src)}`);
192
+ if (fill.tile !== void 0) {
193
+ parts.push(`${PARAM_PREFIX.tile}${k}=${fill.tile}`);
194
+ }
195
+ if (fill.align !== void 0) {
196
+ parts.push(`${PARAM_PREFIX.align}${k}=${enc(fill.align)}`);
197
+ }
165
198
  }
166
199
  }
167
200
  }
168
- } else if (options.assetUrl !== void 0) {
169
- parts.push(`${PARAMS.asset}=${enc(options.assetUrl)}`);
170
- } else if (options.designRef !== void 0) {
171
- parts.push(`${PARAMS.design}=${enc(options.designRef)}`);
172
201
  }
173
202
  if (options.placement !== void 0) {
174
203
  parts.push(`${PARAMS.placement}=${enc(options.placement)}`);
@@ -191,6 +220,9 @@ function buildPublicMockupUrl(options, cfg = {}) {
191
220
  if (options.aspect !== void 0 && options.aspect !== "16:9") {
192
221
  parts.push(`${PARAMS.aspect}=${enc(options.aspect)}`);
193
222
  }
223
+ if (options.bg) {
224
+ parts.push(`${PARAMS.bg}=${requireBgColor(options.bg)}`);
225
+ }
194
226
  return `${base}${path}?${parts.join("&")}`;
195
227
  }
196
228
  var PUBLIC_PARAM_NAMES = [
@@ -203,6 +235,7 @@ var PUBLIC_PARAM_NAMES = [
203
235
  PARAMS.mockup,
204
236
  PARAMS.width,
205
237
  PARAMS.aspect,
238
+ PARAMS.bg,
206
239
  PARAMS.signature
207
240
  ];
208
241
  function canonicalForSig(url) {
package/dist/index.cjs CHANGED
@@ -506,6 +506,13 @@ var PARAMS = {
506
506
  width: "width",
507
507
  grain: "grain",
508
508
  aspect: "aspect",
509
+ /**
510
+ * Background color (6-hex, no '#') painted behind the mockup — visible only
511
+ * where the mockup itself has transparency (studio-cutout shots) — or the
512
+ * reserved `transparent` token, which suppresses the shop default for this
513
+ * one render. Absent = the shop's configured default, else transparent.
514
+ */
515
+ bg: "bg",
509
516
  /** Live preview/calibration mask overrides (not cached). */
510
517
  maskOverrides: "maskOverrides",
511
518
  /**
@@ -519,6 +526,21 @@ var PARAMS = {
519
526
  signature: "signature",
520
527
  seal: "seal"
521
528
  };
529
+ var BG_TRANSPARENT = "transparent";
530
+ function normalizeBgColor(raw) {
531
+ const value = raw.trim().replace(/^#/, "").toLowerCase();
532
+ if (value === BG_TRANSPARENT) return BG_TRANSPARENT;
533
+ return /^[0-9a-f]{6}$/.test(value) ? value : null;
534
+ }
535
+ function requireBgColor(raw) {
536
+ const bg = normalizeBgColor(raw);
537
+ if (bg === null) {
538
+ throw new Error(
539
+ `[snowcone] bg must be a 6-digit hex color ('#' optional, e.g. "f5f0ea") or "transparent", got "${raw}"`
540
+ );
541
+ }
542
+ return bg;
543
+ }
522
544
  function asSimpleAsset(design) {
523
545
  if (design.length !== 1) return null;
524
546
  const el = design[0];
@@ -603,6 +625,9 @@ function buildMockupUrl(options, cfg) {
603
625
  if (options.effects?.grain) {
604
626
  queryString += `&${PARAMS.grain}=${options.effects.grain}`;
605
627
  }
628
+ if (options.bg) {
629
+ queryString += `&${PARAMS.bg}=${requireBgColor(options.bg)}`;
630
+ }
606
631
  if (options.aspect && options.aspect !== "16:9") {
607
632
  queryString += `&${PARAMS.aspect}=${encodeURIComponent(options.aspect)}`;
608
633
  }
@@ -626,28 +651,32 @@ function buildPublicMockupUrl(options, cfg = {}) {
626
651
  const enc = encodeURIComponent;
627
652
  const parts = [];
628
653
  parts.push(`${PARAMS.shop}=${enc(options.shop)}`);
629
- if (options.design) {
630
- for (const key of Object.keys(options.design).sort()) {
631
- const fill = options.design[key];
632
- const k = enc(key);
633
- if (typeof fill === "string") {
634
- parts.push(`${PARAM_PREFIX.asset}${k}=${enc(fill)}`);
635
- } else if ("color" in fill) {
636
- parts.push(`${PARAM_PREFIX.color}${k}=${enc(fill.color)}`);
637
- } else {
638
- parts.push(`${PARAM_PREFIX.asset}${k}=${enc(fill.src)}`);
639
- if (fill.tile !== void 0) {
640
- parts.push(`${PARAM_PREFIX.tile}${k}=${fill.tile}`);
641
- }
642
- if (fill.align !== void 0) {
643
- parts.push(`${PARAM_PREFIX.align}${k}=${enc(fill.align)}`);
654
+ if (options.designRef !== void 0) {
655
+ parts.push(`${PARAMS.design}=${enc(options.designRef)}`);
656
+ } else {
657
+ if (options.assetUrl !== void 0) {
658
+ parts.push(`${PARAMS.asset}=${enc(options.assetUrl)}`);
659
+ }
660
+ const overrides = options.design || options.placements ? { ...options.design ?? {}, ...options.placements ?? {} } : void 0;
661
+ if (overrides) {
662
+ for (const key of Object.keys(overrides).sort()) {
663
+ const fill = overrides[key];
664
+ const k = enc(key);
665
+ if (typeof fill === "string") {
666
+ parts.push(`${PARAM_PREFIX.asset}${k}=${enc(fill)}`);
667
+ } else if ("color" in fill) {
668
+ parts.push(`${PARAM_PREFIX.color}${k}=${enc(fill.color)}`);
669
+ } else {
670
+ parts.push(`${PARAM_PREFIX.asset}${k}=${enc(fill.src)}`);
671
+ if (fill.tile !== void 0) {
672
+ parts.push(`${PARAM_PREFIX.tile}${k}=${fill.tile}`);
673
+ }
674
+ if (fill.align !== void 0) {
675
+ parts.push(`${PARAM_PREFIX.align}${k}=${enc(fill.align)}`);
676
+ }
644
677
  }
645
678
  }
646
679
  }
647
- } else if (options.assetUrl !== void 0) {
648
- parts.push(`${PARAMS.asset}=${enc(options.assetUrl)}`);
649
- } else if (options.designRef !== void 0) {
650
- parts.push(`${PARAMS.design}=${enc(options.designRef)}`);
651
680
  }
652
681
  if (options.placement !== void 0) {
653
682
  parts.push(`${PARAMS.placement}=${enc(options.placement)}`);
@@ -670,6 +699,9 @@ function buildPublicMockupUrl(options, cfg = {}) {
670
699
  if (options.aspect !== void 0 && options.aspect !== "16:9") {
671
700
  parts.push(`${PARAMS.aspect}=${enc(options.aspect)}`);
672
701
  }
702
+ if (options.bg) {
703
+ parts.push(`${PARAMS.bg}=${requireBgColor(options.bg)}`);
704
+ }
673
705
  return `${base}${path}?${parts.join("&")}`;
674
706
  }
675
707
  var PUBLIC_PARAM_NAMES = [
@@ -682,6 +714,7 @@ var PUBLIC_PARAM_NAMES = [
682
714
  PARAMS.mockup,
683
715
  PARAMS.width,
684
716
  PARAMS.aspect,
717
+ PARAMS.bg,
685
718
  PARAMS.signature
686
719
  ];
687
720
  function canonicalForSig(url) {
@@ -946,12 +979,17 @@ function getMockupUrl(a, b, c) {
946
979
  {
947
980
  productCode,
948
981
  shop: opts.shop,
982
+ // ADR-0089 base+override: the `asset` base and the `design`/`placements`
983
+ // override map COMPOSE (the builder merges them). `placements` is the
984
+ // preferred override name; `design` is the legacy alias.
949
985
  ...opts.design ? { design: opts.design } : {},
986
+ ...opts.placements ? { placements: opts.placements } : {},
950
987
  ...assetUrl !== void 0 ? { assetUrl } : {},
951
988
  ...opts.designRef !== void 0 ? { designRef: opts.designRef } : {},
952
989
  ...opts.options ? { options: opts.options } : {},
953
990
  ...opts.width !== void 0 ? { width: opts.width } : {},
954
991
  ...opts.aspect !== void 0 ? { aspect: opts.aspect } : {},
992
+ ...opts.bg !== void 0 ? { bg: opts.bg } : {},
955
993
  ...opts.mockup ?? opts.view ? { mockup: opts.mockup ?? opts.view } : {},
956
994
  ...opts.variant !== void 0 ? { variant: opts.variant } : {},
957
995
  ...opts.placement !== void 0 ? { placement: opts.placement } : {}
package/dist/index.d.cts CHANGED
@@ -225,9 +225,11 @@ type Design = PublicDesign;
225
225
  /**
226
226
  * Options for the code-first {@link getMockupUrl} form.
227
227
  *
228
- * Exactly one artwork source is expected for an image render: either a single
229
- * default-placement `asset`, OR a multi-placement `design` map. `design` takes
230
- * precedence if both are given.
228
+ * Artwork follows the ADR-0089 base+override model: `asset` is the BASE every
229
+ * placement inherits, and `placements` (or its `design` alias) is a per-key
230
+ * OVERRIDE map. They COMPOSE — give just `asset` to broadcast one image
231
+ * everywhere, add `placements` to retarget specific placements, or give only
232
+ * `placements` to fill named placements and leave the rest blank.
231
233
  */
232
234
  interface GetMockupUrlOptions {
233
235
  /**
@@ -237,17 +239,28 @@ interface GetMockupUrlOptions {
237
239
  */
238
240
  shop: string;
239
241
  /**
240
- * Single default-placement image — the get-started shorthand. Emitted as the
241
- * readable `asset=` param. Ignored when {@link GetMockupUrlOptions.design} is
242
- * supplied.
242
+ * The BASE design — one image every placement inherits (ADR-0089). Emitted as
243
+ * the readable `asset=` param; the resolver broadcasts it across every
244
+ * placement. Composes with {@link GetMockupUrlOptions.placements} /
245
+ * {@link GetMockupUrlOptions.design} overrides (it is no longer ignored when
246
+ * those are present). `asset=default` is the reserved house-blank token.
243
247
  */
244
248
  asset?: string;
245
249
  /**
246
- * Multi-placement design: a map of placement key → {@link Fill}. Emitted as
250
+ * Per-placement OVERRIDES: a map of placement key → {@link Fill}. Emitted as
247
251
  * the dotted `asset.<key>` / `color.<key>` / `tile.<key>` / `align.<key>`
248
- * params. Takes precedence over `asset`.
252
+ * params. Composes WITH `asset` (ADR-0089): the `asset` base seeds every
253
+ * placement; each entry here overrides that one placement. `placements` is the
254
+ * preferred name; `design` is the legacy alias (both merge, override wins).
249
255
  */
250
256
  design?: Design;
257
+ /**
258
+ * Per-placement overrides — the named, ADR-0089 form of {@link
259
+ * GetMockupUrlOptions.design}. A map of placement key → {@link Fill} that
260
+ * overrides the `asset` base on just those placements; unlisted placements
261
+ * keep the base. Merges with `design` if both are supplied.
262
+ */
263
+ placements?: Design;
251
264
  /**
252
265
  * Catalog design reference (ADR-0086): a `pairingId` or `slug` from the
253
266
  * public designs catalog (`searchDesigns`). Emitted as `design=` — the
@@ -290,6 +303,15 @@ interface GetMockupUrlOptions {
290
303
  * dimensions; measure or crop client-side with `object-fit: cover`.
291
304
  */
292
305
  aspect?: "16:9" | "2:3";
306
+ /**
307
+ * Background color painted behind the mockup (6-hex, `#` optional — e.g.
308
+ * `"f5f0ea"` or `"#F5F0EA"`), or `"transparent"` to force the raw cutout by
309
+ * suppressing the shop's default for this one render. Visible only where the
310
+ * mockup scene itself has transparency (studio-cutout shots). Omit to use
311
+ * the shop's configured default background (`mockup_bg_color` in shop
312
+ * settings), else transparent. Emitted as `&bg=`.
313
+ */
314
+ bg?: string;
293
315
  }
294
316
  /**
295
317
  * Build the public mockup image URL. Pure + synchronous — drop the result
package/dist/index.d.ts CHANGED
@@ -225,9 +225,11 @@ type Design = PublicDesign;
225
225
  /**
226
226
  * Options for the code-first {@link getMockupUrl} form.
227
227
  *
228
- * Exactly one artwork source is expected for an image render: either a single
229
- * default-placement `asset`, OR a multi-placement `design` map. `design` takes
230
- * precedence if both are given.
228
+ * Artwork follows the ADR-0089 base+override model: `asset` is the BASE every
229
+ * placement inherits, and `placements` (or its `design` alias) is a per-key
230
+ * OVERRIDE map. They COMPOSE — give just `asset` to broadcast one image
231
+ * everywhere, add `placements` to retarget specific placements, or give only
232
+ * `placements` to fill named placements and leave the rest blank.
231
233
  */
232
234
  interface GetMockupUrlOptions {
233
235
  /**
@@ -237,17 +239,28 @@ interface GetMockupUrlOptions {
237
239
  */
238
240
  shop: string;
239
241
  /**
240
- * Single default-placement image — the get-started shorthand. Emitted as the
241
- * readable `asset=` param. Ignored when {@link GetMockupUrlOptions.design} is
242
- * supplied.
242
+ * The BASE design — one image every placement inherits (ADR-0089). Emitted as
243
+ * the readable `asset=` param; the resolver broadcasts it across every
244
+ * placement. Composes with {@link GetMockupUrlOptions.placements} /
245
+ * {@link GetMockupUrlOptions.design} overrides (it is no longer ignored when
246
+ * those are present). `asset=default` is the reserved house-blank token.
243
247
  */
244
248
  asset?: string;
245
249
  /**
246
- * Multi-placement design: a map of placement key → {@link Fill}. Emitted as
250
+ * Per-placement OVERRIDES: a map of placement key → {@link Fill}. Emitted as
247
251
  * the dotted `asset.<key>` / `color.<key>` / `tile.<key>` / `align.<key>`
248
- * params. Takes precedence over `asset`.
252
+ * params. Composes WITH `asset` (ADR-0089): the `asset` base seeds every
253
+ * placement; each entry here overrides that one placement. `placements` is the
254
+ * preferred name; `design` is the legacy alias (both merge, override wins).
249
255
  */
250
256
  design?: Design;
257
+ /**
258
+ * Per-placement overrides — the named, ADR-0089 form of {@link
259
+ * GetMockupUrlOptions.design}. A map of placement key → {@link Fill} that
260
+ * overrides the `asset` base on just those placements; unlisted placements
261
+ * keep the base. Merges with `design` if both are supplied.
262
+ */
263
+ placements?: Design;
251
264
  /**
252
265
  * Catalog design reference (ADR-0086): a `pairingId` or `slug` from the
253
266
  * public designs catalog (`searchDesigns`). Emitted as `design=` — the
@@ -290,6 +303,15 @@ interface GetMockupUrlOptions {
290
303
  * dimensions; measure or crop client-side with `object-fit: cover`.
291
304
  */
292
305
  aspect?: "16:9" | "2:3";
306
+ /**
307
+ * Background color painted behind the mockup (6-hex, `#` optional — e.g.
308
+ * `"f5f0ea"` or `"#F5F0EA"`), or `"transparent"` to force the raw cutout by
309
+ * suppressing the shop's default for this one render. Visible only where the
310
+ * mockup scene itself has transparency (studio-cutout shots). Omit to use
311
+ * the shop's configured default background (`mockup_bg_color` in shop
312
+ * settings), else transparent. Emitted as `&bg=`.
313
+ */
314
+ bg?: string;
293
315
  }
294
316
  /**
295
317
  * Build the public mockup image URL. Pure + synchronous — drop the result
package/dist/index.js CHANGED
@@ -11,7 +11,7 @@ import {
11
11
  canonicalForSig,
12
12
  normalizeDesignElements,
13
13
  normalizeWidth
14
- } from "./chunk-7DRH6S4D.js";
14
+ } from "./chunk-IL3FXE2X.js";
15
15
 
16
16
  // src/validation.ts
17
17
  import { z } from "zod";
@@ -550,12 +550,17 @@ function getMockupUrl(a, b, c) {
550
550
  {
551
551
  productCode,
552
552
  shop: opts.shop,
553
+ // ADR-0089 base+override: the `asset` base and the `design`/`placements`
554
+ // override map COMPOSE (the builder merges them). `placements` is the
555
+ // preferred override name; `design` is the legacy alias.
553
556
  ...opts.design ? { design: opts.design } : {},
557
+ ...opts.placements ? { placements: opts.placements } : {},
554
558
  ...assetUrl !== void 0 ? { assetUrl } : {},
555
559
  ...opts.designRef !== void 0 ? { designRef: opts.designRef } : {},
556
560
  ...opts.options ? { options: opts.options } : {},
557
561
  ...opts.width !== void 0 ? { width: opts.width } : {},
558
562
  ...opts.aspect !== void 0 ? { aspect: opts.aspect } : {},
563
+ ...opts.bg !== void 0 ? { bg: opts.bg } : {},
559
564
  ...opts.mockup ?? opts.view ? { mockup: opts.mockup ?? opts.view } : {},
560
565
  ...opts.variant !== void 0 ? { variant: opts.variant } : {},
561
566
  ...opts.placement !== void 0 ? { placement: opts.placement } : {}
package/dist/server.cjs CHANGED
@@ -60,6 +60,13 @@ var PARAMS = {
60
60
  width: "width",
61
61
  grain: "grain",
62
62
  aspect: "aspect",
63
+ /**
64
+ * Background color (6-hex, no '#') painted behind the mockup — visible only
65
+ * where the mockup itself has transparency (studio-cutout shots) — or the
66
+ * reserved `transparent` token, which suppresses the shop default for this
67
+ * one render. Absent = the shop's configured default, else transparent.
68
+ */
69
+ bg: "bg",
63
70
  /** Live preview/calibration mask overrides (not cached). */
64
71
  maskOverrides: "maskOverrides",
65
72
  /**
@@ -83,6 +90,7 @@ var PUBLIC_PARAM_NAMES = [
83
90
  PARAMS.mockup,
84
91
  PARAMS.width,
85
92
  PARAMS.aspect,
93
+ PARAMS.bg,
86
94
  PARAMS.signature
87
95
  ];
88
96
  function canonicalForSig(url) {
package/dist/server.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import {
2
2
  canonicalForSig,
3
3
  signDevSig
4
- } from "./chunk-7DRH6S4D.js";
4
+ } from "./chunk-IL3FXE2X.js";
5
5
 
6
6
  // src/server.ts
7
7
  function json(body, status = 200) {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@snowcone-app/sdk",
3
- "version": "0.18.1",
3
+ "version": "0.20.0",
4
4
  "description": "Snowcone SDK for product mockups and print-on-demand",
5
5
  "keywords": [
6
6
  "merch",
@@ -85,7 +85,7 @@
85
85
  "tsup": "^8.1.0",
86
86
  "typescript": "^5.5.4",
87
87
  "vitest": "^2.0.5",
88
- "@snowcone-app/mockup-url": "0.2.1"
88
+ "@snowcone-app/mockup-url": "0.3.0"
89
89
  },
90
90
  "engines": {
91
91
  "node": ">=18"