@snowcone-app/sdk 0.24.2 → 0.24.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,17 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.24.4
4
+
5
+ ### Patch Changes
6
+
7
+ - [#4283](https://github.com/snowcone-app/snowcone-monorepo/pull/4283) [`4fbaaf1`](https://github.com/snowcone-app/snowcone-monorepo/commit/4fbaaf161d0c580a1c56790a9a4c54f676a92abc) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Examples and tool descriptions use live demo products: the iPhone 17 Pro Max Case (`BC43BE`), the Canvas Tote (`CAXHQC`) and the All-Over Print Zip Hoodie (`XTNA6J`), in place of the Framed Canvas (`BEEB77`) and Women's Tee (`KMYKUK`), which are no longer for sale. No API change.
8
+
9
+ ## 0.24.3
10
+
11
+ ### Patch Changes
12
+
13
+ - [#4074](https://github.com/snowcone-app/snowcone-monorepo/pull/4074) [`8682d87`](https://github.com/snowcone-app/snowcone-monorepo/commit/8682d876466cee5ee80ff05b1401a5679a410007) Thanks [@kevinsproles](https://github.com/kevinsproles)! - A selected size with no scene previews a listed variant that differs only by size. The cart, SKU and price keep the selected size.
14
+
3
15
  ## 0.24.2
4
16
 
5
17
  ### Patch Changes
package/README.md CHANGED
@@ -27,7 +27,7 @@ import { getProduct, listProducts, getMockupUrl } from '@snowcone-app/sdk';
27
27
 
28
28
  // 1. Find a product (public catalog read — no key needed)
29
29
  const products = await listProducts({ limit: 10 });
30
- const product = await getProduct('BEEB77'); // by id or slug
30
+ const product = await getProduct('BC43BE'); // by id or slug
31
31
 
32
32
  // 2. Build a mockup URL. A mockup is a PUBLIC image URL — getMockupUrl is a
33
33
  // pure, synchronous builder (no await, no fetch, no secret). The result
@@ -66,7 +66,7 @@ const products = await listProducts(options?: {
66
66
  **Product Object Structure:**
67
67
  ```typescript
68
68
  {
69
- id: string; // Product ID (e.g., "BEEB77")
69
+ id: string; // Product ID (e.g., "BC43BE")
70
70
  name: string; // Product name
71
71
  description?: string; // Product description
72
72
  basePrice: number; // Base price in cents
@@ -126,16 +126,16 @@ type Design = Record<string, Fill>; // placement key → fill
126
126
  #### Multi-placement + variant options
127
127
 
128
128
  ```typescript
129
- // A front + back tee, size M.
130
- const url = getMockupUrl('KMYKUK', {
129
+ // A hoodie's left front + back, size M.
130
+ const url = getMockupUrl('XTNA6J', {
131
131
  shop: shop.id,
132
132
  options: { size: 'm' },
133
133
  design: {
134
- front: 'https://cdn.example.com/front.png',
134
+ front_left: 'https://cdn.example.com/front.png',
135
135
  back: { src: 'https://cdn.example.com/back.png', tile: 2, align: 'top' },
136
136
  },
137
137
  });
138
- // → …/KMYKUK?shop=…&asset.back=…&tile.back=2&align.back=top&asset.front=…&opt.size=m
138
+ // → …/XTNA6J?shop=…&asset.back=…&tile.back=2&align.back=top&asset.front_left=…&opt.size=m
139
139
 
140
140
  // A cap with a printed front + chosen Crown/Strap colors (color placements).
141
141
  const cap = getMockupUrl('RQNU68', {
@@ -211,7 +211,7 @@ const session = new RenderSession({
211
211
  grantUrl: '/api/realtime/grant', // your proxy above
212
212
  // mockupIds are catalog SCENE CODES (product.mockups[].id) — not placement
213
213
  // names. variantId is required for products with a color/size option.
214
- product: { productId: 'BEEB77', mockupIds: ['FV1qjO'], variantId: 'Pv1sLC' },
214
+ product: { productId: 'BC43BE', mockupIds: ['947QAD'], variantId: 'e92f40' },
215
215
  });
216
216
 
217
217
  session.onMockups((results) => { img.src = results[0].imageUrl; });
package/dist/index.cjs CHANGED
@@ -138,6 +138,7 @@ __export(index_exports, {
138
138
  registerStandardComponents: () => registerStandardComponents,
139
139
  resolveBestCombination: () => resolveBestCombination,
140
140
  resolveMockupId: () => resolveMockupId,
141
+ resolvePreviewVariantId: () => resolvePreviewVariantId,
141
142
  resolveVariantId: () => resolveVariantId,
142
143
  retryOperation: () => retryOperation,
143
144
  searchDesigns: () => searchDesigns,
@@ -1951,6 +1952,35 @@ function resolveVariantId(context, providedGvid, providedVariantId) {
1951
1952
  }
1952
1953
  return "default";
1953
1954
  }
1955
+ var SIZE_ATTRIBUTE = /^size$/i;
1956
+ var NOT_THE_PICTURE = /* @__PURE__ */ new Set(["variantId", "price"]);
1957
+ function resolvePreviewVariantId(context, variantId, mockupId) {
1958
+ const all = context?.product?.mockups ?? [];
1959
+ const mockups = mockupId ? all.filter((m) => m.id === mockupId) : all;
1960
+ const lists = (m, id) => (m.gvids ?? []).includes(id);
1961
+ if (mockups.length === 0 || mockups.some((m) => lists(m, variantId))) return variantId;
1962
+ const combinations = context?.combinations ?? [];
1963
+ const selected = combinations.find((c) => c.variantId === variantId);
1964
+ if (!selected) return variantId;
1965
+ const sizeKey = Object.keys(selected).find((k) => SIZE_ATTRIBUTE.test(k));
1966
+ if (!sizeKey) return variantId;
1967
+ const pictureKeys = (row) => Object.keys(row).filter((k) => k !== sizeKey && !NOT_THE_PICTURE.has(k));
1968
+ const sameExceptSize = (row) => {
1969
+ const keys = pictureKeys(row);
1970
+ return keys.length === pictureKeys(selected).length && keys.every((k) => row[k] === selected[k]);
1971
+ };
1972
+ let best = variantId;
1973
+ let bestCount = 0;
1974
+ for (const row of combinations) {
1975
+ if (typeof row.variantId !== "string" || row.variantId === variantId || !sameExceptSize(row)) continue;
1976
+ const count = mockups.filter((m) => lists(m, row.variantId)).length;
1977
+ if (count > bestCount) {
1978
+ best = row.variantId;
1979
+ bestCount = count;
1980
+ }
1981
+ }
1982
+ return best;
1983
+ }
1954
1984
  function resolveMockupId(context, variantId, providedMockupId) {
1955
1985
  if (providedMockupId) return providedMockupId;
1956
1986
  if (context?.product?.mockups?.length) {
@@ -6561,6 +6591,7 @@ function createClient(config) {
6561
6591
  registerStandardComponents,
6562
6592
  resolveBestCombination,
6563
6593
  resolveMockupId,
6594
+ resolvePreviewVariantId,
6564
6595
  resolveVariantId,
6565
6596
  retryOperation,
6566
6597
  searchDesigns,
package/dist/index.d.cts CHANGED
@@ -401,7 +401,7 @@ interface GetMockupUrlOptions {
401
401
  *
402
402
  * // Code-first (preferred): productCode then options.
403
403
  * getMockupUrl("hoodie-black", { shop, asset });
404
- * getMockupUrl("KMYKUK", { shop, options: { size: "m" }, design: {…} });
404
+ * getMockupUrl("XTNA6J", { shop, options: { size: "m" }, design: {…} });
405
405
  *
406
406
  * // Legacy positional: (assetUrl, productCode, opts).
407
407
  * getMockupUrl(assetUrl, "hoodie-black", { shop });
@@ -419,8 +419,8 @@ declare const DEFAULT_BUY_BASE = "https://buy.snowcone.app";
419
419
  * where the mockup URL renders the design as an image, this URL opens the
420
420
  * Snowcone-hosted checkout with that exact design in the cart.
421
421
  *
422
- * const img = getMockupUrl("BEEB77", { shop, asset }); // the picture
423
- * const buy = getBuyUrl("BEEB77", { shop, asset }); // the purchase
422
+ * const img = getMockupUrl("BC43BE", { shop, asset }); // the picture
423
+ * const buy = getBuyUrl("BC43BE", { shop, asset }); // the purchase
424
424
  *
425
425
  * Pure + synchronous, like `getMockupUrl` — drop the result into an
426
426
  * `<a href>`. Pass `base` to override the host.
@@ -1070,6 +1070,16 @@ declare function getVariant(selection: UserSelection, product: {
1070
1070
  * Used by React/Vue/WC components that have context
1071
1071
  */
1072
1072
  declare function resolveVariantId(context: any, providedGvid?: string, providedVariantId?: string): string;
1073
+ /**
1074
+ * The variant to PREVIEW for a selected one. Scenes exist only for the variants a mockup lists, and a size doesn't change
1075
+ * the picture, so a size with no scene previews a listed variant that differs ONLY by size. Anything else about the
1076
+ * row (a colour, another garment) must match, so it can't show the wrong colour; with no such variant this returns the
1077
+ * selected one, and the render's typed failure stands.
1078
+ *
1079
+ * Preview only. The cart, SKU, price and print file keep the selected variant (createCartDetail doesn't read this).
1080
+ * Without a `mockupId` (a realtime session, one variant for all its mockups) it picks the sibling most mockups list.
1081
+ */
1082
+ declare function resolvePreviewVariantId(context: any, variantId: string, mockupId?: string | null): string;
1073
1083
  /**
1074
1084
  * Internal helper - determines the mockup ID based on variant and available mockups
1075
1085
  * Used by React/Vue/WC components that have context
@@ -2866,7 +2876,7 @@ declare function fetchRealtimeGrant(grantUrl: string, shop: string, fetchImpl?:
2866
2876
  * grantUrl: '/api/realtime/grant', // your proxy → mintRealtimeGrant (server)
2867
2877
  * // mockupIds are opaque catalog SCENE CODES (product.mockups[].id) — NOT
2868
2878
  * // placement names. variantId is required for products with a color/size axis.
2869
- * product: { productId: 'BEEB77', mockupIds: ['FV1qjO'], variantId: 'Pv1sLC' },
2879
+ * product: { productId: 'BC43BE', mockupIds: ['947QAD'], variantId: 'e92f40' },
2870
2880
  * });
2871
2881
  * session.onMockups((results) => { img.src = results[0].imageUrl; });
2872
2882
  * // First arg is the PLACEMENT name (placements[].label, e.g. 'Front') — a
@@ -2909,11 +2919,11 @@ interface DesignLike {
2909
2919
  interface RenderProductCombination {
2910
2920
  /** The variant (gvid) this combination resolves to. */
2911
2921
  variantId?: string;
2912
- /** Attribute selections (e.g. `{ Frame: 'Walnut', Size: '5x7' }`). */
2922
+ /** Attribute selections (e.g. `{ Size: 'M', color: 'Black' }`). */
2913
2923
  [attribute: string]: string | number | undefined;
2914
2924
  }
2915
2925
  /**
2916
- * One choice of a variant attribute (e.g. `{ label: 'Walnut', hex: '#5b3d1d' }`).
2926
+ * One choice of a variant attribute (e.g. `{ label: 'Black', hex: '#000000' }`).
2917
2927
  * A `hex` value marks the attribute as a COLOR axis — the one kind of variant
2918
2928
  * the renderer treats as a required placement (auto-filled from `variantId`).
2919
2929
  */
@@ -2981,7 +2991,7 @@ interface RenderProduct {
2981
2991
  productId: string;
2982
2992
  /**
2983
2993
  * The mockup scenes to render — opaque catalog codes (the product's
2984
- * `mockups[].id`, e.g. `'FV1qjO'`). These are a DIFFERENT namespace from the
2994
+ * `mockups[].id`, e.g. `'947QAD'`). These are a DIFFERENT namespace from the
2985
2995
  * `placement` you pass to {@link RenderSession.renderState} (a print-area name
2986
2996
  * like `'Front'`). Don't pass a placement name here.
2987
2997
  */
@@ -3426,4 +3436,4 @@ declare function searchDesigns(query?: string, options?: SearchDesignsOptions):
3426
3436
  */
3427
3437
  declare function createClient(config: SdkConfig): SnowconeClient;
3428
3438
 
3429
- export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogDesign, type CatalogListResponse, type CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, type CreateDesignStateInput, type CreatedDesignState, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_BUY_BASE, DEFAULT_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type DesignLike, type DesignsSearchResponse, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type FailedAsset, type FetchMockupImageOptions, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, type MockupImage, MockupResult, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, PlacementSettings, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, REALTIME_WS_URL, type RateLimitState, type RealtimeGrant, RealtimeMockupService, RealtimeRenderError, type RegularArtwork, type RenderProduct, type RenderProductAttribute, type RenderProductAttributeChoice, type RenderProductCombination, type RenderProductMockup, type RenderProductOptions, type RenderProductRequiredPlacement, RenderSession, type RenderSessionOptions, type RenderState, type SdkConfig, type SeamlessPattern, type SearchDesignsOptions, type SignedUrlResponse, type SnowconeClient, SnowconeSdkError, type SnowconeSdkErrorCode, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, assertVariantSelected, autoRegister, bffSigner, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createDesignState, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, fetchMockupImage, fetchRealtimeGrant, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getBuyUrl, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, imageKindOf, isSelectionComplete, isSnowconeSdkError, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolveVariantId, retryOperation, searchDesigns, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, warnVariantNotSelected, withContext, withErrorHandling, withSyncErrorHandling };
3439
+ export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogDesign, type CatalogListResponse, type CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, type CreateDesignStateInput, type CreatedDesignState, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_BUY_BASE, DEFAULT_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type DesignLike, type DesignsSearchResponse, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type FailedAsset, type FetchMockupImageOptions, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, type MockupImage, MockupResult, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, PlacementSettings, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, REALTIME_WS_URL, type RateLimitState, type RealtimeGrant, RealtimeMockupService, RealtimeRenderError, type RegularArtwork, type RenderProduct, type RenderProductAttribute, type RenderProductAttributeChoice, type RenderProductCombination, type RenderProductMockup, type RenderProductOptions, type RenderProductRequiredPlacement, RenderSession, type RenderSessionOptions, type RenderState, type SdkConfig, type SeamlessPattern, type SearchDesignsOptions, type SignedUrlResponse, type SnowconeClient, SnowconeSdkError, type SnowconeSdkErrorCode, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, assertVariantSelected, autoRegister, bffSigner, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createDesignState, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, fetchMockupImage, fetchRealtimeGrant, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getBuyUrl, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, imageKindOf, isSelectionComplete, isSnowconeSdkError, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolvePreviewVariantId, resolveVariantId, retryOperation, searchDesigns, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, warnVariantNotSelected, withContext, withErrorHandling, withSyncErrorHandling };
package/dist/index.d.ts CHANGED
@@ -401,7 +401,7 @@ interface GetMockupUrlOptions {
401
401
  *
402
402
  * // Code-first (preferred): productCode then options.
403
403
  * getMockupUrl("hoodie-black", { shop, asset });
404
- * getMockupUrl("KMYKUK", { shop, options: { size: "m" }, design: {…} });
404
+ * getMockupUrl("XTNA6J", { shop, options: { size: "m" }, design: {…} });
405
405
  *
406
406
  * // Legacy positional: (assetUrl, productCode, opts).
407
407
  * getMockupUrl(assetUrl, "hoodie-black", { shop });
@@ -419,8 +419,8 @@ declare const DEFAULT_BUY_BASE = "https://buy.snowcone.app";
419
419
  * where the mockup URL renders the design as an image, this URL opens the
420
420
  * Snowcone-hosted checkout with that exact design in the cart.
421
421
  *
422
- * const img = getMockupUrl("BEEB77", { shop, asset }); // the picture
423
- * const buy = getBuyUrl("BEEB77", { shop, asset }); // the purchase
422
+ * const img = getMockupUrl("BC43BE", { shop, asset }); // the picture
423
+ * const buy = getBuyUrl("BC43BE", { shop, asset }); // the purchase
424
424
  *
425
425
  * Pure + synchronous, like `getMockupUrl` — drop the result into an
426
426
  * `<a href>`. Pass `base` to override the host.
@@ -1070,6 +1070,16 @@ declare function getVariant(selection: UserSelection, product: {
1070
1070
  * Used by React/Vue/WC components that have context
1071
1071
  */
1072
1072
  declare function resolveVariantId(context: any, providedGvid?: string, providedVariantId?: string): string;
1073
+ /**
1074
+ * The variant to PREVIEW for a selected one. Scenes exist only for the variants a mockup lists, and a size doesn't change
1075
+ * the picture, so a size with no scene previews a listed variant that differs ONLY by size. Anything else about the
1076
+ * row (a colour, another garment) must match, so it can't show the wrong colour; with no such variant this returns the
1077
+ * selected one, and the render's typed failure stands.
1078
+ *
1079
+ * Preview only. The cart, SKU, price and print file keep the selected variant (createCartDetail doesn't read this).
1080
+ * Without a `mockupId` (a realtime session, one variant for all its mockups) it picks the sibling most mockups list.
1081
+ */
1082
+ declare function resolvePreviewVariantId(context: any, variantId: string, mockupId?: string | null): string;
1073
1083
  /**
1074
1084
  * Internal helper - determines the mockup ID based on variant and available mockups
1075
1085
  * Used by React/Vue/WC components that have context
@@ -2866,7 +2876,7 @@ declare function fetchRealtimeGrant(grantUrl: string, shop: string, fetchImpl?:
2866
2876
  * grantUrl: '/api/realtime/grant', // your proxy → mintRealtimeGrant (server)
2867
2877
  * // mockupIds are opaque catalog SCENE CODES (product.mockups[].id) — NOT
2868
2878
  * // placement names. variantId is required for products with a color/size axis.
2869
- * product: { productId: 'BEEB77', mockupIds: ['FV1qjO'], variantId: 'Pv1sLC' },
2879
+ * product: { productId: 'BC43BE', mockupIds: ['947QAD'], variantId: 'e92f40' },
2870
2880
  * });
2871
2881
  * session.onMockups((results) => { img.src = results[0].imageUrl; });
2872
2882
  * // First arg is the PLACEMENT name (placements[].label, e.g. 'Front') — a
@@ -2909,11 +2919,11 @@ interface DesignLike {
2909
2919
  interface RenderProductCombination {
2910
2920
  /** The variant (gvid) this combination resolves to. */
2911
2921
  variantId?: string;
2912
- /** Attribute selections (e.g. `{ Frame: 'Walnut', Size: '5x7' }`). */
2922
+ /** Attribute selections (e.g. `{ Size: 'M', color: 'Black' }`). */
2913
2923
  [attribute: string]: string | number | undefined;
2914
2924
  }
2915
2925
  /**
2916
- * One choice of a variant attribute (e.g. `{ label: 'Walnut', hex: '#5b3d1d' }`).
2926
+ * One choice of a variant attribute (e.g. `{ label: 'Black', hex: '#000000' }`).
2917
2927
  * A `hex` value marks the attribute as a COLOR axis — the one kind of variant
2918
2928
  * the renderer treats as a required placement (auto-filled from `variantId`).
2919
2929
  */
@@ -2981,7 +2991,7 @@ interface RenderProduct {
2981
2991
  productId: string;
2982
2992
  /**
2983
2993
  * The mockup scenes to render — opaque catalog codes (the product's
2984
- * `mockups[].id`, e.g. `'FV1qjO'`). These are a DIFFERENT namespace from the
2994
+ * `mockups[].id`, e.g. `'947QAD'`). These are a DIFFERENT namespace from the
2985
2995
  * `placement` you pass to {@link RenderSession.renderState} (a print-area name
2986
2996
  * like `'Front'`). Don't pass a placement name here.
2987
2997
  */
@@ -3426,4 +3436,4 @@ declare function searchDesigns(query?: string, options?: SearchDesignsOptions):
3426
3436
  */
3427
3437
  declare function createClient(config: SdkConfig): SnowconeClient;
3428
3438
 
3429
- export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogDesign, type CatalogListResponse, type CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, type CreateDesignStateInput, type CreatedDesignState, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_BUY_BASE, DEFAULT_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type DesignLike, type DesignsSearchResponse, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type FailedAsset, type FetchMockupImageOptions, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, type MockupImage, MockupResult, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, PlacementSettings, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, REALTIME_WS_URL, type RateLimitState, type RealtimeGrant, RealtimeMockupService, RealtimeRenderError, type RegularArtwork, type RenderProduct, type RenderProductAttribute, type RenderProductAttributeChoice, type RenderProductCombination, type RenderProductMockup, type RenderProductOptions, type RenderProductRequiredPlacement, RenderSession, type RenderSessionOptions, type RenderState, type SdkConfig, type SeamlessPattern, type SearchDesignsOptions, type SignedUrlResponse, type SnowconeClient, SnowconeSdkError, type SnowconeSdkErrorCode, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, assertVariantSelected, autoRegister, bffSigner, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createDesignState, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, fetchMockupImage, fetchRealtimeGrant, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getBuyUrl, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, imageKindOf, isSelectionComplete, isSnowconeSdkError, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolveVariantId, retryOperation, searchDesigns, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, warnVariantNotSelected, withContext, withErrorHandling, withSyncErrorHandling };
3439
+ export { AbstractTemplateRenderer, type AddToCartOptions, Animations, type ArtSelectorContext, type ArtSelectorDescriptor, type ArtSelectorOptions, type ArtworkData, type AspectRatio, Attributes, type BaseDescriptor, type BlendConfig, type BuildMockupUrlConfig, type CartDetail, type CatalogDesign, type CatalogListResponse, type CatalogProduct, ClassNames, type ColorDesignElement, ColorPickerUtils, Combination, CommonProps, ComponentContext, type ComponentDefinition, ComponentDescriptor, ComponentEventManager, ComponentFactory, ComponentLifecycle, ComponentLifecycleHooks, type ComponentMetadata, ComponentProps, ComponentRegistry, ComponentState, type ComponentTemplate, ComponentTemplates, type ContainerDescriptor, ContextBridge, type ContextComparator, type ContextConsumer, ContextInjector, type ContextProviderConfig, type ContextSubscriber, ContextSynchronizer, type CreateDesignStateInput, type CreatedDesignState, DEFAULT_ARTWORK_URL, DEFAULT_ASPECT_RATIO, DEFAULT_BUY_BASE, DEFAULT_COLOR, DEFAULT_GRANT_BASE, DEFAULT_MOCKUP_BASE, DEFAULT_PLACEMENT_DIMENSIONS, type Descriptor, type Design, type DesignElement, type DesignGenerationContext, type DesignLike, type DesignsSearchResponse, type Effects, Elements, type ErrorContext, type ErrorHandler, ErrorManager, type EventDefinition, EventDelegator, EventEmitter, EventHandler, type EventListener, type EventPayload, type FailedAsset, type FetchMockupImageOptions, type Fill, Focus, FrameworkAdapter, FrameworkUtilities, type GetMockupUrlOptions, type ImageAlignment, type ImageDesignElement, type LifecycleHook, LifecycleManager, type LifecyclePhase, type LifecycleTransition, LitAdapter, type MaskOverride, type MockupGenerationOptions, type MockupImage, MockupResult, type MockupService, type MockupServiceConfig, OptionAttribute, type OptionChoice, type OptionChoiceRenderData, type OptionRenderData, OptionSelection, type Placement, type PlacementDesign, PlacementSettings, type ProductArtAlignmentContext, type ProductArtAlignmentDescriptor, type ProductArtAlignmentOptions, type ProductContext, type ProductContextEvents, ProductContextManager, type ProductData, type ProductFetcher, type ProductImageDescriptor, type ProductImageOptions, ProductLoader, type ProductMockupData, type ProductOptionChoice, type ProductOptionData, type ProductOptionsDescriptor, type ProductOptionsOptions, type ProductPlacement, type ProductPriceDescriptor, type ProductPriceOptions, ProductProps, type ProductSpec, type ProductTitleDescriptor, type ProductTitleOptions, type ProductVariant, type PropDefinition, type PropSchema, type PropType, PropertyManager, REALTIME_WS_URL, type RateLimitState, type RealtimeGrant, RealtimeMockupService, RealtimeRenderError, type RegularArtwork, type RenderProduct, type RenderProductAttribute, type RenderProductAttributeChoice, type RenderProductCombination, type RenderProductMockup, type RenderProductOptions, type RenderProductRequiredPlacement, RenderSession, type RenderSessionOptions, type RenderState, type SdkConfig, type SeamlessPattern, type SearchDesignsOptions, type SignedUrlResponse, type SnowconeClient, SnowconeSdkError, type SnowconeSdkErrorCode, StandardComponents, StandardEvents, StateManager, type StateManagerOptions, type StateMiddleware, type StateSelector, type StateSubscriber, type StateUpdater, Styles, SvelteAdapter, SwatchUtils, type TagName, TemplateBuilder, type TemplateNode, type TemplateNodeType, type TemplateRenderer, type TextDescriptor, type TileCount, UniversalContextProvider, type UserSelection, type ValidationError, type ValidationResult, VueAdapter, assertVariantSelected, autoRegister, bffSigner, buildMockupUrl, componentRegistry, createAddToCartEvent, createAddToCartHandler, createCartDetail, createClient, createContextProvider, createDesignForPlacements, createDesignState, createErrorHandler, createEventManager, createLifecycle, createLitComponent, createProductContext, createProductLoader, createPropertyManager, createStateHook, createStateStore, createSvelteComponent, createUniversalProvider, createVueComponent, describeArtSelector, describeProductArtAlignment, describeProductImage, describeProductOptions, describeProductPrice, describeProductTitle, extractProductId, fetchMockupImage, fetchRealtimeGrant, filterImagePlacements, findClosestSnapPoint, findVariantForSelection, formatPrice, formatValidationErrors, getBuyUrl, getDefaultVariantId, getEffectiveAlignment, getIncompleteSelectionMessage, getMissingSelections, getMockupUrl, getOptionRenderType, getProduct, getSelectionDisplayText, getSnapPoints, getVariant, handleOptionChange, imageKindOf, isSelectionComplete, isSnowconeSdkError, isValidAlignment, isValidTileCount, listProducts, mintRealtimeGrant, mockupUrl, normalizeChoice, prepareOptionRenderData, registerStandardComponents, resolveMockupId, resolvePreviewVariantId, resolveVariantId, retryOperation, searchDesigns, simulateCartOperation, toCombinations, toOptionAttributes, useFrameworkAdapter as useVueAdapter, validateAlignment, validateDesignElement, validateEffects, validateImageUrl, validateMockupOptions, validateProductSelection, validateProductSpec, validateRequiredOptions, validateTileCount, warnVariantNotSelected, withContext, withErrorHandling, withSyncErrorHandling };
package/dist/index.js CHANGED
@@ -1516,6 +1516,35 @@ function resolveVariantId(context, providedGvid, providedVariantId) {
1516
1516
  }
1517
1517
  return "default";
1518
1518
  }
1519
+ var SIZE_ATTRIBUTE = /^size$/i;
1520
+ var NOT_THE_PICTURE = /* @__PURE__ */ new Set(["variantId", "price"]);
1521
+ function resolvePreviewVariantId(context, variantId, mockupId) {
1522
+ const all = context?.product?.mockups ?? [];
1523
+ const mockups = mockupId ? all.filter((m) => m.id === mockupId) : all;
1524
+ const lists = (m, id) => (m.gvids ?? []).includes(id);
1525
+ if (mockups.length === 0 || mockups.some((m) => lists(m, variantId))) return variantId;
1526
+ const combinations = context?.combinations ?? [];
1527
+ const selected = combinations.find((c) => c.variantId === variantId);
1528
+ if (!selected) return variantId;
1529
+ const sizeKey = Object.keys(selected).find((k) => SIZE_ATTRIBUTE.test(k));
1530
+ if (!sizeKey) return variantId;
1531
+ const pictureKeys = (row) => Object.keys(row).filter((k) => k !== sizeKey && !NOT_THE_PICTURE.has(k));
1532
+ const sameExceptSize = (row) => {
1533
+ const keys = pictureKeys(row);
1534
+ return keys.length === pictureKeys(selected).length && keys.every((k) => row[k] === selected[k]);
1535
+ };
1536
+ let best = variantId;
1537
+ let bestCount = 0;
1538
+ for (const row of combinations) {
1539
+ if (typeof row.variantId !== "string" || row.variantId === variantId || !sameExceptSize(row)) continue;
1540
+ const count = mockups.filter((m) => lists(m, row.variantId)).length;
1541
+ if (count > bestCount) {
1542
+ best = row.variantId;
1543
+ bestCount = count;
1544
+ }
1545
+ }
1546
+ return best;
1547
+ }
1519
1548
  function resolveMockupId(context, variantId, providedMockupId) {
1520
1549
  if (providedMockupId) return providedMockupId;
1521
1550
  if (context?.product?.mockups?.length) {
@@ -5264,6 +5293,7 @@ export {
5264
5293
  registerStandardComponents,
5265
5294
  resolveBestCombination,
5266
5295
  resolveMockupId,
5296
+ resolvePreviewVariantId,
5267
5297
  resolveVariantId,
5268
5298
  retryOperation,
5269
5299
  searchDesigns,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@snowcone-app/sdk",
3
- "version": "0.24.2",
3
+ "version": "0.24.4",
4
4
  "description": "Snowcone SDK for product mockups and print-on-demand",
5
5
  "keywords": [
6
6
  "merch",