@snowcone-app/sdk 0.23.0 → 0.24.1

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,17 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.24.1
4
+
5
+ ### Patch Changes
6
+
7
+ - [#2346](https://github.com/snowcone-app/snowcone-monorepo/pull/2346) [`1804866`](https://github.com/snowcone-app/snowcone-monorepo/commit/1804866916ee79bf7e3db0ea65ce803a1fc005b8) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Realtime: `onAllMockupsRendered` (and therefore `RenderSession.onMockups`) now receives the merged results — a ws-delivered binary frame's `blob:` `imageUrl` included — instead of the server's lean summary entries. A session whose frames rode the socket without a fallback `imageUrl` rendered but never showed: `Editor.Preview` stayed "rendering" forever.
8
+
9
+ ## 0.24.0
10
+
11
+ ### Minor Changes
12
+
13
+ - [#2337](https://github.com/snowcone-app/snowcone-monorepo/pull/2337) [`4b68ab9`](https://github.com/snowcone-app/snowcone-monorepo/commit/4b68ab971b99e0dfa4e6f096e50bb0e5ceb2ec70) Thanks [@kevinsproles](https://github.com/kevinsproles)! - ADR-0099 slice 4 (client): a realtime session on a BUNDLE record. SDK: `RenderProduct` / `WebSocketConfig` gain `picks` (role → member product) and `variants` (role → gvid), forwarded verbatim on the config message; a pick or per-role variant change is a full config reset (not a mockupIds-only update). `CatalogProduct` gains the `bundle` block, `placements[].role` / `memberProductId`, `requiredPlacements[].role` and `mockups[].picks`. Canvas: `bundleToRenderConfig()` — the bundle counterpart of `productToRenderConfig()` (role-scoped placement keys, per-role variants with defaults, picks per slot, scene selection by pick set, `variantToken`), `isBundleProduct`, `splitRoleKey`, `bundleVariantToken`; `Editor.Root` sends a new config on the live session when `product.picks` / `product.variants` change. Typed refusals: `E_BUNDLE_CONFIG_REQUIRED` (single-product adapter given a bundle), `E_NOT_A_BUNDLE`, `E_BUNDLE_ROLE_REQUIRED`, `E_BUNDLE_ROLE_NOT_FOUND`, `E_BUNDLE_PICK_NOT_FOUND`, `E_BUNDLE_VARIANT_NOT_FOUND`; embed issues `bundle-role-required` / `bundle-variant-required`. Single-product behaviour is byte-for-byte unchanged.
14
+
3
15
  ## 0.23.0
4
16
 
5
17
  ### Minor Changes
@@ -19,6 +19,12 @@ function newRenderCorrelation() {
19
19
  const spanId = randHex(8);
20
20
  return { requestId: traceId, traceparent: `00-${traceId}-${spanId}-01` };
21
21
  }
22
+ function sameRoleMap(a, b) {
23
+ const ka = Object.keys(a ?? {}).sort();
24
+ const kb = Object.keys(b ?? {}).sort();
25
+ if (ka.length !== kb.length) return false;
26
+ return ka.every((k, i) => k === kb[i] && a[k] === b[k]);
27
+ }
22
28
  var RealtimeMockupService = class {
23
29
  constructor(wsUrl = REALTIME_WS_URL) {
24
30
  this.wsUrl = wsUrl;
@@ -343,7 +349,7 @@ var RealtimeMockupService = class {
343
349
  this.lastError = null;
344
350
  this.renderError = null;
345
351
  this.addLog(`\u{1F389} All mockups rendered: ${freshMockups.length} fresh (${data.mockups.length - freshMockups.length} stale filtered)`);
346
- this.callbacks.onAllMockupsRendered?.(freshMockups);
352
+ this.callbacks.onAllMockupsRendered?.(this.mockupResults);
347
353
  } else {
348
354
  this.addLog(`\u26A0\uFE0F all_mockups_rendered message dropped: missing 'mockups' array. Full data keys: [${Object.keys(data).join(", ")}]`);
349
355
  }
@@ -424,7 +430,7 @@ var RealtimeMockupService = class {
424
430
  return false;
425
431
  }
426
432
  if (this.configSent && hasConfigChanged) {
427
- const isOnlyMockupIdsChange = this.config && this.config.productId === config.productId && this.config.variantId === config.variantId;
433
+ const isOnlyMockupIdsChange = this.config && this.config.productId === config.productId && this.config.variantId === config.variantId && sameRoleMap(this.config.picks, config.picks) && sameRoleMap(this.config.variants, config.variants);
428
434
  if (isOnlyMockupIdsChange) {
429
435
  this.addLog("\u{1F504} MockupIds changed, keeping cached blobs (server will reuse)");
430
436
  this.isConfigured = false;
@@ -164,7 +164,11 @@ var PARAM_PREFIX = {
164
164
  color: "color.",
165
165
  tile: "tile.",
166
166
  align: "align.",
167
- opt: "opt."
167
+ opt: "opt.",
168
+ /** ADR-0099 bundles: `variant.<role>=<gvid>` — one SKU per member slot. */
169
+ variant: "variant.",
170
+ /** ADR-0099 bundles: `pick.<role>=<productCode>` — which alternative fills a slot. */
171
+ pick: "pick."
168
172
  };
169
173
  var DEFAULT_PUBLIC_BASE_URL = "https://img.snowcone.app";
170
174
  function buildPublicMockupUrl(options, cfg = {}) {
package/dist/index.cjs CHANGED
@@ -643,7 +643,11 @@ var PARAM_PREFIX = {
643
643
  color: "color.",
644
644
  tile: "tile.",
645
645
  align: "align.",
646
- opt: "opt."
646
+ opt: "opt.",
647
+ /** ADR-0099 bundles: `variant.<role>=<gvid>` — one SKU per member slot. */
648
+ variant: "variant.",
649
+ /** ADR-0099 bundles: `pick.<role>=<productCode>` — which alternative fills a slot. */
650
+ pick: "pick."
647
651
  };
648
652
  var DEFAULT_PUBLIC_BASE_URL = "https://img.snowcone.app";
649
653
  function buildPublicMockupUrl(options, cfg = {}) {
@@ -5015,6 +5019,12 @@ function newRenderCorrelation() {
5015
5019
  const spanId = randHex(8);
5016
5020
  return { requestId: traceId, traceparent: `00-${traceId}-${spanId}-01` };
5017
5021
  }
5022
+ function sameRoleMap(a, b) {
5023
+ const ka = Object.keys(a ?? {}).sort();
5024
+ const kb = Object.keys(b ?? {}).sort();
5025
+ if (ka.length !== kb.length) return false;
5026
+ return ka.every((k, i) => k === kb[i] && a[k] === b[k]);
5027
+ }
5018
5028
  var RealtimeMockupService = class {
5019
5029
  constructor(wsUrl = REALTIME_WS_URL) {
5020
5030
  this.wsUrl = wsUrl;
@@ -5339,7 +5349,7 @@ var RealtimeMockupService = class {
5339
5349
  this.lastError = null;
5340
5350
  this.renderError = null;
5341
5351
  this.addLog(`\u{1F389} All mockups rendered: ${freshMockups.length} fresh (${data.mockups.length - freshMockups.length} stale filtered)`);
5342
- this.callbacks.onAllMockupsRendered?.(freshMockups);
5352
+ this.callbacks.onAllMockupsRendered?.(this.mockupResults);
5343
5353
  } else {
5344
5354
  this.addLog(`\u26A0\uFE0F all_mockups_rendered message dropped: missing 'mockups' array. Full data keys: [${Object.keys(data).join(", ")}]`);
5345
5355
  }
@@ -5420,7 +5430,7 @@ var RealtimeMockupService = class {
5420
5430
  return false;
5421
5431
  }
5422
5432
  if (this.configSent && hasConfigChanged) {
5423
- const isOnlyMockupIdsChange = this.config && this.config.productId === config.productId && this.config.variantId === config.variantId;
5433
+ const isOnlyMockupIdsChange = this.config && this.config.productId === config.productId && this.config.variantId === config.variantId && sameRoleMap(this.config.picks, config.picks) && sameRoleMap(this.config.variants, config.variants);
5424
5434
  if (isOnlyMockupIdsChange) {
5425
5435
  this.addLog("\u{1F504} MockupIds changed, keeping cached blobs (server will reuse)");
5426
5436
  this.isConfigured = false;
@@ -6288,7 +6298,12 @@ var RenderSession = class {
6288
6298
  variantId: product.variantId ?? "",
6289
6299
  width: product.width ?? 1e3,
6290
6300
  ...product.ar ? { ar: product.ar } : {},
6291
- ...product.placementSettings ? { placementSettings: product.placementSettings } : {}
6301
+ ...product.placementSettings ? { placementSettings: product.placementSettings } : {},
6302
+ // ADR-0099 bundle session: per-role picks + variants ride the config
6303
+ // verbatim; the server resolves each slot and derives the role-scoped
6304
+ // required placement set from them.
6305
+ ...product.picks ? { picks: product.picks } : {},
6306
+ ...product.variants ? { variants: product.variants } : {}
6292
6307
  };
6293
6308
  }
6294
6309
  };
package/dist/index.d.cts CHANGED
@@ -1,7 +1,7 @@
1
1
  export { createDevFetcher } from './dev-fetcher.cjs';
2
2
  import { PublicDesign, PublicFill, PublicOptions } from '@snowcone-app/mockup-url';
3
- 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-DjAOhBaN.cjs';
4
- 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-DjAOhBaN.cjs';
3
+ 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-DXO35yrh.cjs';
4
+ 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-DXO35yrh.cjs';
5
5
 
6
6
  interface CatalogProduct {
7
7
  id: string;
@@ -17,6 +17,12 @@ interface CatalogProduct {
17
17
  mockups?: {
18
18
  id: string;
19
19
  gvids: string[];
20
+ /**
21
+ * ADR-0099 (bundle records only): which alternative each slot shows in this scene's photo, `role -> member product code`. A bundle session selects the scenes whose picks agree with its own; single products never carry it.
22
+ */
23
+ picks?: {
24
+ [k: string]: string;
25
+ };
20
26
  }[];
21
27
  options?: {
22
28
  selected?: {
@@ -79,6 +85,14 @@ interface CatalogProduct {
79
85
  scale?: number;
80
86
  offsetX?: number;
81
87
  offsetY?: number;
88
+ /**
89
+ * ADR-0099 (bundle records only): the slot this placement belongs to. The wire key is then role-scoped (`key` = `<role>.<member key>`, e.g. "top.front") and it is the placement NAME a realtime `canvas_state` / `renderState` must use.
90
+ */
91
+ role?: string;
92
+ /**
93
+ * ADR-0099 (bundle records only): the member product (slot alternative) this placement belongs to. Two alternatives in one slot share the key; the session's pick decides which one is live.
94
+ */
95
+ memberProductId?: string;
82
96
  }[];
83
97
  /**
84
98
  * The renderer's required-placement contract, surfaced so a developer reads exactly which placements `renderState` will demand. Image placements are always sent by the caller; color placements (autoFilledByVariant: true) are filled from `variantId` — omit them when you pass a variantId, send them otherwise.
@@ -94,6 +108,10 @@ interface CatalogProduct {
94
108
  * When true, this (color) placement is auto-filled from the variant's option choice when a `variantId` is sent; otherwise the caller must send it explicitly.
95
109
  */
96
110
  autoFilledByVariant: boolean;
111
+ /**
112
+ * ADR-0099 (bundle records only): the slot this required placement belongs to; `key` is the role-scoped name to send.
113
+ */
114
+ role?: string;
97
115
  }[];
98
116
  defaultGvid?: string | null;
99
117
  /**
@@ -117,6 +135,68 @@ interface CatalogProduct {
117
135
  step: number;
118
136
  };
119
137
  };
138
+ /**
139
+ * ADR-0099: marks a BUNDLE — several products photographed in one mockup, sold together. Each member is a SLOT (`role`) with one or more alternative products (`products`, first = default pick). A bundle's placements are role-scoped (`placements[].role`, key `<role>.<key>`), its variants are named per role, and a realtime session on it sends `picks` + `variants` instead of `variantId`. Additive: products without this block are unaffected.
140
+ */
141
+ bundle?: {
142
+ members: {
143
+ /**
144
+ * The slot name (e.g. "top", "shorts"). Prefixes every placement key and variant of the slot.
145
+ */
146
+ role: string;
147
+ required?: boolean;
148
+ /**
149
+ * The slot's alternatives, first = default pick.
150
+ */
151
+ products: {
152
+ productId: string;
153
+ /**
154
+ * The variant a session renders for this alternative when `variants.<role>` is omitted.
155
+ */
156
+ defaultGvid?: string | null;
157
+ /**
158
+ * The alternative's selectable variants for a session (`variants.<role>` must be one of these gvids when the list is non-empty) and the render gvid each maps to.
159
+ */
160
+ variants?: {
161
+ gvid: string;
162
+ gvidForMockup?: string | null;
163
+ }[];
164
+ /**
165
+ * The alternative's own `options` block (attributes + combinations), underlays stripped — labels a per-slot variant picker.
166
+ */
167
+ options?: {
168
+ attributes?: {
169
+ [k: string]: {
170
+ type?: string;
171
+ affectsCombinations?: boolean;
172
+ choices?: {
173
+ label: string;
174
+ hex?: string;
175
+ imageUrl?: string;
176
+ }[];
177
+ };
178
+ };
179
+ combinations?: {
180
+ price?: number;
181
+ variantId?: string;
182
+ [k: string]: string | number | undefined;
183
+ }[];
184
+ };
185
+ }[];
186
+ }[];
187
+ /**
188
+ * The bundle discount (e.g. { "kind": "percent_off", "bps": 1000 }).
189
+ */
190
+ priceRule?: unknown;
191
+ /**
192
+ * Pick sets no published scene photographs yet.
193
+ */
194
+ uncoveredPickSets?: {
195
+ [k: string]: string;
196
+ }[];
197
+ warmEstimate?: number;
198
+ warmBudget?: number;
199
+ };
120
200
  }
121
201
 
122
202
  /**
@@ -2977,6 +3057,27 @@ interface RenderProduct {
2977
3057
  ar?: AspectRatio;
2978
3058
  /** Per-placement settings (tiling, scale mode). */
2979
3059
  placementSettings?: Record<string, PlacementSettings>;
3060
+ /**
3061
+ * ADR-0099 — BUNDLE records only (a product whose catalog payload carries a
3062
+ * `bundle` block: several products in one mockup). Which alternative fills
3063
+ * each slot, `role → member product code`; omitted roles take the slot's
3064
+ * first alternative. Sent verbatim as the config's `picks`; the server
3065
+ * re-validates every config message (`E_BUNDLE_PICK_NOT_FOUND` lists the
3066
+ * slot's alternatives, `E_BUNDLE_ROLE_NOT_FOUND` the roles) and refuses it
3067
+ * on a single product (`E_NOT_A_BUNDLE`). Build it with
3068
+ * `bundleToRenderConfig()` from `@snowcone-app/canvas/embed` rather than by
3069
+ * hand — the builder fills defaults and throws typed errors up front.
3070
+ */
3071
+ picks?: Record<string, string>;
3072
+ /**
3073
+ * ADR-0099 — BUNDLE records only. The variant per slot, `role → gvid`. On a
3074
+ * bundle the placement names you pass to {@link RenderSession.renderState}
3075
+ * are role-scoped keys (`"top.front"`, the catalog `placements[].key`), and
3076
+ * the variant is named per ROLE: leave {@link variantId} unset — a bare
3077
+ * `variantId` on a bundle is refused by the server (`E_BUNDLE_ROLE_REQUIRED`
3078
+ * listing the roles). Refused on a single product (`E_NOT_A_BUNDLE`).
3079
+ */
3080
+ variants?: Record<string, string>;
2980
3081
  }
2981
3082
  /**
2982
3083
  * Throws immediately if the product has a COLOR variant axis (an
package/dist/index.d.ts CHANGED
@@ -1,7 +1,7 @@
1
1
  export { createDevFetcher } from './dev-fetcher.js';
2
2
  import { PublicDesign, PublicFill, PublicOptions } from '@snowcone-app/mockup-url';
3
- 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-DjAOhBaN.js';
4
- 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-DjAOhBaN.js';
3
+ 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-DXO35yrh.js';
4
+ 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-DXO35yrh.js';
5
5
 
6
6
  interface CatalogProduct {
7
7
  id: string;
@@ -17,6 +17,12 @@ interface CatalogProduct {
17
17
  mockups?: {
18
18
  id: string;
19
19
  gvids: string[];
20
+ /**
21
+ * ADR-0099 (bundle records only): which alternative each slot shows in this scene's photo, `role -> member product code`. A bundle session selects the scenes whose picks agree with its own; single products never carry it.
22
+ */
23
+ picks?: {
24
+ [k: string]: string;
25
+ };
20
26
  }[];
21
27
  options?: {
22
28
  selected?: {
@@ -79,6 +85,14 @@ interface CatalogProduct {
79
85
  scale?: number;
80
86
  offsetX?: number;
81
87
  offsetY?: number;
88
+ /**
89
+ * ADR-0099 (bundle records only): the slot this placement belongs to. The wire key is then role-scoped (`key` = `<role>.<member key>`, e.g. "top.front") and it is the placement NAME a realtime `canvas_state` / `renderState` must use.
90
+ */
91
+ role?: string;
92
+ /**
93
+ * ADR-0099 (bundle records only): the member product (slot alternative) this placement belongs to. Two alternatives in one slot share the key; the session's pick decides which one is live.
94
+ */
95
+ memberProductId?: string;
82
96
  }[];
83
97
  /**
84
98
  * The renderer's required-placement contract, surfaced so a developer reads exactly which placements `renderState` will demand. Image placements are always sent by the caller; color placements (autoFilledByVariant: true) are filled from `variantId` — omit them when you pass a variantId, send them otherwise.
@@ -94,6 +108,10 @@ interface CatalogProduct {
94
108
  * When true, this (color) placement is auto-filled from the variant's option choice when a `variantId` is sent; otherwise the caller must send it explicitly.
95
109
  */
96
110
  autoFilledByVariant: boolean;
111
+ /**
112
+ * ADR-0099 (bundle records only): the slot this required placement belongs to; `key` is the role-scoped name to send.
113
+ */
114
+ role?: string;
97
115
  }[];
98
116
  defaultGvid?: string | null;
99
117
  /**
@@ -117,6 +135,68 @@ interface CatalogProduct {
117
135
  step: number;
118
136
  };
119
137
  };
138
+ /**
139
+ * ADR-0099: marks a BUNDLE — several products photographed in one mockup, sold together. Each member is a SLOT (`role`) with one or more alternative products (`products`, first = default pick). A bundle's placements are role-scoped (`placements[].role`, key `<role>.<key>`), its variants are named per role, and a realtime session on it sends `picks` + `variants` instead of `variantId`. Additive: products without this block are unaffected.
140
+ */
141
+ bundle?: {
142
+ members: {
143
+ /**
144
+ * The slot name (e.g. "top", "shorts"). Prefixes every placement key and variant of the slot.
145
+ */
146
+ role: string;
147
+ required?: boolean;
148
+ /**
149
+ * The slot's alternatives, first = default pick.
150
+ */
151
+ products: {
152
+ productId: string;
153
+ /**
154
+ * The variant a session renders for this alternative when `variants.<role>` is omitted.
155
+ */
156
+ defaultGvid?: string | null;
157
+ /**
158
+ * The alternative's selectable variants for a session (`variants.<role>` must be one of these gvids when the list is non-empty) and the render gvid each maps to.
159
+ */
160
+ variants?: {
161
+ gvid: string;
162
+ gvidForMockup?: string | null;
163
+ }[];
164
+ /**
165
+ * The alternative's own `options` block (attributes + combinations), underlays stripped — labels a per-slot variant picker.
166
+ */
167
+ options?: {
168
+ attributes?: {
169
+ [k: string]: {
170
+ type?: string;
171
+ affectsCombinations?: boolean;
172
+ choices?: {
173
+ label: string;
174
+ hex?: string;
175
+ imageUrl?: string;
176
+ }[];
177
+ };
178
+ };
179
+ combinations?: {
180
+ price?: number;
181
+ variantId?: string;
182
+ [k: string]: string | number | undefined;
183
+ }[];
184
+ };
185
+ }[];
186
+ }[];
187
+ /**
188
+ * The bundle discount (e.g. { "kind": "percent_off", "bps": 1000 }).
189
+ */
190
+ priceRule?: unknown;
191
+ /**
192
+ * Pick sets no published scene photographs yet.
193
+ */
194
+ uncoveredPickSets?: {
195
+ [k: string]: string;
196
+ }[];
197
+ warmEstimate?: number;
198
+ warmBudget?: number;
199
+ };
120
200
  }
121
201
 
122
202
  /**
@@ -2977,6 +3057,27 @@ interface RenderProduct {
2977
3057
  ar?: AspectRatio;
2978
3058
  /** Per-placement settings (tiling, scale mode). */
2979
3059
  placementSettings?: Record<string, PlacementSettings>;
3060
+ /**
3061
+ * ADR-0099 — BUNDLE records only (a product whose catalog payload carries a
3062
+ * `bundle` block: several products in one mockup). Which alternative fills
3063
+ * each slot, `role → member product code`; omitted roles take the slot's
3064
+ * first alternative. Sent verbatim as the config's `picks`; the server
3065
+ * re-validates every config message (`E_BUNDLE_PICK_NOT_FOUND` lists the
3066
+ * slot's alternatives, `E_BUNDLE_ROLE_NOT_FOUND` the roles) and refuses it
3067
+ * on a single product (`E_NOT_A_BUNDLE`). Build it with
3068
+ * `bundleToRenderConfig()` from `@snowcone-app/canvas/embed` rather than by
3069
+ * hand — the builder fills defaults and throws typed errors up front.
3070
+ */
3071
+ picks?: Record<string, string>;
3072
+ /**
3073
+ * ADR-0099 — BUNDLE records only. The variant per slot, `role → gvid`. On a
3074
+ * bundle the placement names you pass to {@link RenderSession.renderState}
3075
+ * are role-scoped keys (`"top.front"`, the catalog `placements[].key`), and
3076
+ * the variant is named per ROLE: leave {@link variantId} unset — a bare
3077
+ * `variantId` on a bundle is refused by the server (`E_BUNDLE_ROLE_REQUIRED`
3078
+ * listing the roles). Refused on a single product (`E_NOT_A_BUNDLE`).
3079
+ */
3080
+ variants?: Record<string, string>;
2980
3081
  }
2981
3082
  /**
2982
3083
  * Throws immediately if the product has a COLOR variant axis (an
package/dist/index.js CHANGED
@@ -4,14 +4,14 @@ import {
4
4
  import {
5
5
  REALTIME_WS_URL,
6
6
  RealtimeMockupService
7
- } from "./chunk-P3ZYTA5F.js";
7
+ } from "./chunk-FQC2FPV7.js";
8
8
  import {
9
9
  buildMockupUrl,
10
10
  buildPublicMockupUrl,
11
11
  canonicalForSig,
12
12
  normalizeDesignElements,
13
13
  normalizeWidth
14
- } from "./chunk-FPR6ABXM.js";
14
+ } from "./chunk-ZBJBBIH3.js";
15
15
 
16
16
  // src/validation.ts
17
17
  import { z } from "zod";
@@ -5002,7 +5002,12 @@ var RenderSession = class {
5002
5002
  variantId: product.variantId ?? "",
5003
5003
  width: product.width ?? 1e3,
5004
5004
  ...product.ar ? { ar: product.ar } : {},
5005
- ...product.placementSettings ? { placementSettings: product.placementSettings } : {}
5005
+ ...product.placementSettings ? { placementSettings: product.placementSettings } : {},
5006
+ // ADR-0099 bundle session: per-role picks + variants ride the config
5007
+ // verbatim; the server resolves each slot and derives the role-scoped
5008
+ // required placement set from them.
5009
+ ...product.picks ? { picks: product.picks } : {},
5010
+ ...product.variants ? { variants: product.variants } : {}
5006
5011
  };
5007
5012
  }
5008
5013
  };
package/dist/react.cjs CHANGED
@@ -53,6 +53,12 @@ function newRenderCorrelation() {
53
53
  const spanId = randHex(8);
54
54
  return { requestId: traceId, traceparent: `00-${traceId}-${spanId}-01` };
55
55
  }
56
+ function sameRoleMap(a, b) {
57
+ const ka = Object.keys(a ?? {}).sort();
58
+ const kb = Object.keys(b ?? {}).sort();
59
+ if (ka.length !== kb.length) return false;
60
+ return ka.every((k, i) => k === kb[i] && a[k] === b[k]);
61
+ }
56
62
  var RealtimeMockupService = class {
57
63
  constructor(wsUrl = REALTIME_WS_URL) {
58
64
  this.wsUrl = wsUrl;
@@ -377,7 +383,7 @@ var RealtimeMockupService = class {
377
383
  this.lastError = null;
378
384
  this.renderError = null;
379
385
  this.addLog(`\u{1F389} All mockups rendered: ${freshMockups.length} fresh (${data.mockups.length - freshMockups.length} stale filtered)`);
380
- this.callbacks.onAllMockupsRendered?.(freshMockups);
386
+ this.callbacks.onAllMockupsRendered?.(this.mockupResults);
381
387
  } else {
382
388
  this.addLog(`\u26A0\uFE0F all_mockups_rendered message dropped: missing 'mockups' array. Full data keys: [${Object.keys(data).join(", ")}]`);
383
389
  }
@@ -458,7 +464,7 @@ var RealtimeMockupService = class {
458
464
  return false;
459
465
  }
460
466
  if (this.configSent && hasConfigChanged) {
461
- const isOnlyMockupIdsChange = this.config && this.config.productId === config.productId && this.config.variantId === config.variantId;
467
+ const isOnlyMockupIdsChange = this.config && this.config.productId === config.productId && this.config.variantId === config.variantId && sameRoleMap(this.config.picks, config.picks) && sameRoleMap(this.config.variants, config.variants);
462
468
  if (isOnlyMockupIdsChange) {
463
469
  this.addLog("\u{1F504} MockupIds changed, keeping cached blobs (server will reuse)");
464
470
  this.isConfigured = false;
package/dist/react.d.cts CHANGED
@@ -1,4 +1,4 @@
1
- import { M as MockupResult, R as RealtimeRenderError, W as WebSocketConfig, P as PlacementSettings, F as FrameworkAdapter, b as ComponentProps, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, c as ComponentDescriptor, g as FrameworkUtilities } from './websocket-DjAOhBaN.cjs';
1
+ import { M as MockupResult, R as RealtimeRenderError, W as WebSocketConfig, P as PlacementSettings, F as FrameworkAdapter, b as ComponentProps, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, c as ComponentDescriptor, g as FrameworkUtilities } from './websocket-DXO35yrh.cjs';
2
2
  import { CSSProperties, ReactNode } from 'react';
3
3
 
4
4
  interface UseRealtimeMockupOptions {
package/dist/react.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { M as MockupResult, R as RealtimeRenderError, W as WebSocketConfig, P as PlacementSettings, F as FrameworkAdapter, b as ComponentProps, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, c as ComponentDescriptor, g as FrameworkUtilities } from './websocket-DjAOhBaN.js';
1
+ import { M as MockupResult, R as RealtimeRenderError, W as WebSocketConfig, P as PlacementSettings, F as FrameworkAdapter, b as ComponentProps, d as ComponentState, e as ComponentContext, f as ComponentLifecycleHooks, E as EventHandler, c as ComponentDescriptor, g as FrameworkUtilities } from './websocket-DXO35yrh.js';
2
2
  import { CSSProperties, ReactNode } from 'react';
3
3
 
4
4
  interface UseRealtimeMockupOptions {
package/dist/react.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import {
2
2
  RealtimeMockupService
3
- } from "./chunk-P3ZYTA5F.js";
3
+ } from "./chunk-FQC2FPV7.js";
4
4
 
5
5
  // src/realtime/react.ts
6
6
  import { useCallback, useEffect, useRef, useState } from "react";
package/dist/server.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import {
2
2
  canonicalForSig,
3
3
  signDevSig
4
- } from "./chunk-FPR6ABXM.js";
4
+ } from "./chunk-ZBJBBIH3.js";
5
5
 
6
6
  // src/server.ts
7
7
  function json(body, status = 200) {
@@ -268,6 +268,22 @@ interface WebSocketConfig {
268
268
  */
269
269
  debugKey?: string;
270
270
  placementSettings?: Record<string, PlacementSettings>;
271
+ /**
272
+ * ADR-0099 (bundle records only): which alternative fills each slot —
273
+ * `role → member product code`. Omitted roles take the slot's first
274
+ * alternative. The server re-validates every config message
275
+ * (`E_BUNDLE_PICK_NOT_FOUND` lists the slot's alternatives); on a
276
+ * single product it is refused (`E_NOT_A_BUNDLE`).
277
+ */
278
+ picks?: Record<string, string>;
279
+ /**
280
+ * ADR-0099 (bundle records only): the variant per slot — `role → gvid`.
281
+ * A bundle session names its variants per ROLE; a bare `variantId` on a
282
+ * bundle is refused by the server (`E_BUNDLE_ROLE_REQUIRED`), so send
283
+ * `variantId: ''` alongside this. On a single product it is refused
284
+ * (`E_NOT_A_BUNDLE`).
285
+ */
286
+ variants?: Record<string, string>;
271
287
  }
272
288
  interface MockupResult {
273
289
  mockupId: string;
@@ -268,6 +268,22 @@ interface WebSocketConfig {
268
268
  */
269
269
  debugKey?: string;
270
270
  placementSettings?: Record<string, PlacementSettings>;
271
+ /**
272
+ * ADR-0099 (bundle records only): which alternative fills each slot —
273
+ * `role → member product code`. Omitted roles take the slot's first
274
+ * alternative. The server re-validates every config message
275
+ * (`E_BUNDLE_PICK_NOT_FOUND` lists the slot's alternatives); on a
276
+ * single product it is refused (`E_NOT_A_BUNDLE`).
277
+ */
278
+ picks?: Record<string, string>;
279
+ /**
280
+ * ADR-0099 (bundle records only): the variant per slot — `role → gvid`.
281
+ * A bundle session names its variants per ROLE; a bare `variantId` on a
282
+ * bundle is refused by the server (`E_BUNDLE_ROLE_REQUIRED`), so send
283
+ * `variantId: ''` alongside this. On a single product it is refused
284
+ * (`E_NOT_A_BUNDLE`).
285
+ */
286
+ variants?: Record<string, string>;
271
287
  }
272
288
  interface MockupResult {
273
289
  mockupId: string;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@snowcone-app/sdk",
3
- "version": "0.23.0",
3
+ "version": "0.24.1",
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.4.0"
88
+ "@snowcone-app/mockup-url": "0.6.0"
89
89
  },
90
90
  "engines": {
91
91
  "node": ">=18"