@snowcone-app/sdk 0.16.1 → 0.17.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,13 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.17.0
4
+
5
+ ### Minor Changes
6
+
7
+ - [#765](https://github.com/snowcone-app/snowcone-monorepo/pull/765) [`1d73014`](https://github.com/snowcone-app/snowcone-monorepo/commit/1d73014fef7c9eadb499c14677f85620df5f80c4) Thanks [@kevinsproles](https://github.com/kevinsproles)! - Surface realtime render errors as structured, machine-readable state instead of swallowing them.
8
+ - sdk: new `RealtimeRenderError` (`{code, message}`) mirrors the server's `{type:'error', code}` frame. Exposed as `renderError` on `RealtimeMockupState` / the `useRealtimeMockup` hook return, passed as a second `detail` argument to `onError` callbacks (hook, service callbacks, and `RenderSession.onError`), and cleared automatically once a later render succeeds. `mockupResults` intentionally keeps the last good renders on error so hosts can show "stale + error badge" instead of a blank panel.
9
+ - ui: `RealtimeProvider` exposes `renderError` on its context, and `HeroProductImage` renders a visible error badge with a stable `data-render-error="<code>"` attribute over the (kept) stale mockup when the realtime renderer rejects a render (e.g. `asset_not_allowed`).
10
+
3
11
  ## 0.16.1
4
12
 
5
13
  ### Patch Changes
@@ -25,6 +25,7 @@ var RealtimeMockupService = class {
25
25
  status = "Disconnected";
26
26
  logs = [];
27
27
  lastError = null;
28
+ renderError = null;
28
29
  callbacks = {};
29
30
  // Per-request send timestamps keyed by requestId, for client-observed
30
31
  // round-trip timing in the mockup_rendered log. Pruned to a small cap so an
@@ -82,7 +83,8 @@ var RealtimeMockupService = class {
82
83
  mockupResults: [...this.mockupResults],
83
84
  status: this.status,
84
85
  logs: [...this.logs],
85
- lastError: this.lastError
86
+ lastError: this.lastError,
87
+ renderError: this.renderError
86
88
  };
87
89
  }
88
90
  addLog(message, type = "info") {
@@ -268,6 +270,8 @@ var RealtimeMockupService = class {
268
270
  } else {
269
271
  this.mockupResults.push(mockupResult);
270
272
  }
273
+ this.lastError = null;
274
+ this.renderError = null;
271
275
  this.addLog(`\u2705 Mockup rendered v${responseVersion ?? "?"} for "${responsePlacement ?? "?"}" (${data.imageSize} bytes)`);
272
276
  this.callbacks.onMockupRendered?.(mockupResult);
273
277
  } else {
@@ -294,18 +298,26 @@ var RealtimeMockupService = class {
294
298
  return true;
295
299
  });
296
300
  this.mockupResults = freshMockups;
301
+ this.lastError = null;
302
+ this.renderError = null;
297
303
  this.addLog(`\u{1F389} All mockups rendered: ${freshMockups.length} fresh (${data.mockups.length - freshMockups.length} stale filtered)`);
298
304
  this.callbacks.onAllMockupsRendered?.(freshMockups);
299
305
  } else {
300
306
  this.addLog(`\u26A0\uFE0F all_mockups_rendered message dropped: missing 'mockups' array. Full data keys: [${Object.keys(data).join(", ")}]`);
301
307
  }
302
308
  break;
303
- case "error":
309
+ case "error": {
304
310
  const errorMessage = data.message || "Unknown error occurred";
311
+ const renderError = {
312
+ code: data.code || "render_error",
313
+ message: errorMessage
314
+ };
305
315
  this.lastError = errorMessage;
306
- this.addLog(`\u274C Server Error: ${errorMessage}`);
307
- this.callbacks.onError?.(errorMessage);
316
+ this.renderError = renderError;
317
+ this.addLog(`\u274C Server Error [${renderError.code}]: ${errorMessage}`);
318
+ this.callbacks.onError?.(errorMessage, renderError);
308
319
  break;
320
+ }
309
321
  default:
310
322
  this.addLog(`\u{1F914} Unknown message type: ${data.type}`, "received");
311
323
  break;
package/dist/index.cjs CHANGED
@@ -4981,6 +4981,7 @@ var RealtimeMockupService = class {
4981
4981
  status = "Disconnected";
4982
4982
  logs = [];
4983
4983
  lastError = null;
4984
+ renderError = null;
4984
4985
  callbacks = {};
4985
4986
  // Per-request send timestamps keyed by requestId, for client-observed
4986
4987
  // round-trip timing in the mockup_rendered log. Pruned to a small cap so an
@@ -5038,7 +5039,8 @@ var RealtimeMockupService = class {
5038
5039
  mockupResults: [...this.mockupResults],
5039
5040
  status: this.status,
5040
5041
  logs: [...this.logs],
5041
- lastError: this.lastError
5042
+ lastError: this.lastError,
5043
+ renderError: this.renderError
5042
5044
  };
5043
5045
  }
5044
5046
  addLog(message, type = "info") {
@@ -5224,6 +5226,8 @@ var RealtimeMockupService = class {
5224
5226
  } else {
5225
5227
  this.mockupResults.push(mockupResult);
5226
5228
  }
5229
+ this.lastError = null;
5230
+ this.renderError = null;
5227
5231
  this.addLog(`\u2705 Mockup rendered v${responseVersion ?? "?"} for "${responsePlacement ?? "?"}" (${data.imageSize} bytes)`);
5228
5232
  this.callbacks.onMockupRendered?.(mockupResult);
5229
5233
  } else {
@@ -5250,18 +5254,26 @@ var RealtimeMockupService = class {
5250
5254
  return true;
5251
5255
  });
5252
5256
  this.mockupResults = freshMockups;
5257
+ this.lastError = null;
5258
+ this.renderError = null;
5253
5259
  this.addLog(`\u{1F389} All mockups rendered: ${freshMockups.length} fresh (${data.mockups.length - freshMockups.length} stale filtered)`);
5254
5260
  this.callbacks.onAllMockupsRendered?.(freshMockups);
5255
5261
  } else {
5256
5262
  this.addLog(`\u26A0\uFE0F all_mockups_rendered message dropped: missing 'mockups' array. Full data keys: [${Object.keys(data).join(", ")}]`);
5257
5263
  }
5258
5264
  break;
5259
- case "error":
5265
+ case "error": {
5260
5266
  const errorMessage = data.message || "Unknown error occurred";
5267
+ const renderError = {
5268
+ code: data.code || "render_error",
5269
+ message: errorMessage
5270
+ };
5261
5271
  this.lastError = errorMessage;
5262
- this.addLog(`\u274C Server Error: ${errorMessage}`);
5263
- this.callbacks.onError?.(errorMessage);
5272
+ this.renderError = renderError;
5273
+ this.addLog(`\u274C Server Error [${renderError.code}]: ${errorMessage}`);
5274
+ this.callbacks.onError?.(errorMessage, renderError);
5264
5275
  break;
5276
+ }
5265
5277
  default:
5266
5278
  this.addLog(`\u{1F914} Unknown message type: ${data.type}`, "received");
5267
5279
  break;
@@ -5893,7 +5905,12 @@ var RenderSession = class {
5893
5905
  this.mockupCb = cb;
5894
5906
  return this;
5895
5907
  }
5896
- /** Register an error callback (server/transport errors). */
5908
+ /**
5909
+ * Register an error callback (server/transport errors). `detail` is present
5910
+ * for server error frames and carries the stable machine-readable `code`
5911
+ * (e.g. 'asset_not_allowed') plus the human message; client-side errors
5912
+ * (watchdog timeout, variant validation) pass only the message.
5913
+ */
5897
5914
  onError(cb) {
5898
5915
  this.errorCb = cb;
5899
5916
  return this;
@@ -5947,8 +5964,8 @@ var RenderSession = class {
5947
5964
  this.clearWatchdog();
5948
5965
  this.mockupCb?.(results);
5949
5966
  },
5950
- onError: (error) => {
5951
- this.errorCb?.(error);
5967
+ onError: (error, detail) => {
5968
+ this.errorCb?.(error, detail);
5952
5969
  if (!settled) {
5953
5970
  settled = true;
5954
5971
  reject(new Error(error));
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 RealtimeMockupService } from './websocket-Bfc3nsyG.cjs';
4
- export { A as AdapterRegistry, h as ProductComponentContext, i as RealtimeMockupCallbacks, j as RealtimeMockupState, k as RenderResult, W as WebSocketConfig, l as WebSocketMessage, m as adapterRegistry, n as computeDisabledChoices, o as createComponent, p as defineComponent, q as deriveDefaultSelection, r as findBestCombination, s as getPricePreview, t as isOptionAvailable, u as resolveBestCombination } from './websocket-Bfc3nsyG.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-C2hbBgve.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-C2hbBgve.cjs';
5
5
 
6
6
  interface CatalogProduct {
7
7
  id: string;
@@ -3027,8 +3027,13 @@ declare class RenderSession {
3027
3027
  constructor(opts: RenderSessionOptions);
3028
3028
  /** Register a callback fired whenever rendered mockup URLs update. */
3029
3029
  onMockups(cb: (results: MockupResult[]) => void): this;
3030
- /** Register an error callback (server/transport errors). */
3031
- onError(cb: (error: string) => void): this;
3030
+ /**
3031
+ * Register an error callback (server/transport errors). `detail` is present
3032
+ * for server error frames and carries the stable machine-readable `code`
3033
+ * (e.g. 'asset_not_allowed') plus the human message; client-side errors
3034
+ * (watchdog timeout, variant validation) pass only the message.
3035
+ */
3036
+ onError(cb: (error: string, detail?: RealtimeRenderError) => void): this;
3032
3037
  /** Set or update the product. Sends config immediately if already connected. */
3033
3038
  setProduct(product: RenderProduct): void;
3034
3039
  /**
@@ -3292,4 +3297,4 @@ declare function searchDesigns(query?: string, options?: SearchDesignsOptions):
3292
3297
  */
3293
3298
  declare function createClient(config: SdkConfig): SnowconeClient;
3294
3299
 
3295
- 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, 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 };
3300
+ 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 };
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 RealtimeMockupService } from './websocket-Bfc3nsyG.js';
4
- export { A as AdapterRegistry, h as ProductComponentContext, i as RealtimeMockupCallbacks, j as RealtimeMockupState, k as RenderResult, W as WebSocketConfig, l as WebSocketMessage, m as adapterRegistry, n as computeDisabledChoices, o as createComponent, p as defineComponent, q as deriveDefaultSelection, r as findBestCombination, s as getPricePreview, t as isOptionAvailable, u as resolveBestCombination } from './websocket-Bfc3nsyG.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-C2hbBgve.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-C2hbBgve.js';
5
5
 
6
6
  interface CatalogProduct {
7
7
  id: string;
@@ -3027,8 +3027,13 @@ declare class RenderSession {
3027
3027
  constructor(opts: RenderSessionOptions);
3028
3028
  /** Register a callback fired whenever rendered mockup URLs update. */
3029
3029
  onMockups(cb: (results: MockupResult[]) => void): this;
3030
- /** Register an error callback (server/transport errors). */
3031
- onError(cb: (error: string) => void): this;
3030
+ /**
3031
+ * Register an error callback (server/transport errors). `detail` is present
3032
+ * for server error frames and carries the stable machine-readable `code`
3033
+ * (e.g. 'asset_not_allowed') plus the human message; client-side errors
3034
+ * (watchdog timeout, variant validation) pass only the message.
3035
+ */
3036
+ onError(cb: (error: string, detail?: RealtimeRenderError) => void): this;
3032
3037
  /** Set or update the product. Sends config immediately if already connected. */
3033
3038
  setProduct(product: RenderProduct): void;
3034
3039
  /**
@@ -3292,4 +3297,4 @@ declare function searchDesigns(query?: string, options?: SearchDesignsOptions):
3292
3297
  */
3293
3298
  declare function createClient(config: SdkConfig): SnowconeClient;
3294
3299
 
3295
- 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, 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 };
3300
+ 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 };
package/dist/index.js CHANGED
@@ -4,7 +4,7 @@ import {
4
4
  import {
5
5
  REALTIME_WS_URL,
6
6
  RealtimeMockupService
7
- } from "./chunk-QHRQ3VJD.js";
7
+ } from "./chunk-MKLLTNKJ.js";
8
8
  import {
9
9
  buildMockupUrl,
10
10
  buildPublicMockupUrl,
@@ -4739,7 +4739,12 @@ var RenderSession = class {
4739
4739
  this.mockupCb = cb;
4740
4740
  return this;
4741
4741
  }
4742
- /** Register an error callback (server/transport errors). */
4742
+ /**
4743
+ * Register an error callback (server/transport errors). `detail` is present
4744
+ * for server error frames and carries the stable machine-readable `code`
4745
+ * (e.g. 'asset_not_allowed') plus the human message; client-side errors
4746
+ * (watchdog timeout, variant validation) pass only the message.
4747
+ */
4743
4748
  onError(cb) {
4744
4749
  this.errorCb = cb;
4745
4750
  return this;
@@ -4793,8 +4798,8 @@ var RenderSession = class {
4793
4798
  this.clearWatchdog();
4794
4799
  this.mockupCb?.(results);
4795
4800
  },
4796
- onError: (error) => {
4797
- this.errorCb?.(error);
4801
+ onError: (error, detail) => {
4802
+ this.errorCb?.(error, detail);
4798
4803
  if (!settled) {
4799
4804
  settled = true;
4800
4805
  reject(new Error(error));
package/dist/react.cjs CHANGED
@@ -57,6 +57,7 @@ var RealtimeMockupService = class {
57
57
  status = "Disconnected";
58
58
  logs = [];
59
59
  lastError = null;
60
+ renderError = null;
60
61
  callbacks = {};
61
62
  // Per-request send timestamps keyed by requestId, for client-observed
62
63
  // round-trip timing in the mockup_rendered log. Pruned to a small cap so an
@@ -114,7 +115,8 @@ var RealtimeMockupService = class {
114
115
  mockupResults: [...this.mockupResults],
115
116
  status: this.status,
116
117
  logs: [...this.logs],
117
- lastError: this.lastError
118
+ lastError: this.lastError,
119
+ renderError: this.renderError
118
120
  };
119
121
  }
120
122
  addLog(message, type = "info") {
@@ -300,6 +302,8 @@ var RealtimeMockupService = class {
300
302
  } else {
301
303
  this.mockupResults.push(mockupResult);
302
304
  }
305
+ this.lastError = null;
306
+ this.renderError = null;
303
307
  this.addLog(`\u2705 Mockup rendered v${responseVersion ?? "?"} for "${responsePlacement ?? "?"}" (${data.imageSize} bytes)`);
304
308
  this.callbacks.onMockupRendered?.(mockupResult);
305
309
  } else {
@@ -326,18 +330,26 @@ var RealtimeMockupService = class {
326
330
  return true;
327
331
  });
328
332
  this.mockupResults = freshMockups;
333
+ this.lastError = null;
334
+ this.renderError = null;
329
335
  this.addLog(`\u{1F389} All mockups rendered: ${freshMockups.length} fresh (${data.mockups.length - freshMockups.length} stale filtered)`);
330
336
  this.callbacks.onAllMockupsRendered?.(freshMockups);
331
337
  } else {
332
338
  this.addLog(`\u26A0\uFE0F all_mockups_rendered message dropped: missing 'mockups' array. Full data keys: [${Object.keys(data).join(", ")}]`);
333
339
  }
334
340
  break;
335
- case "error":
341
+ case "error": {
336
342
  const errorMessage = data.message || "Unknown error occurred";
343
+ const renderError = {
344
+ code: data.code || "render_error",
345
+ message: errorMessage
346
+ };
337
347
  this.lastError = errorMessage;
338
- this.addLog(`\u274C Server Error: ${errorMessage}`);
339
- this.callbacks.onError?.(errorMessage);
348
+ this.renderError = renderError;
349
+ this.addLog(`\u274C Server Error [${renderError.code}]: ${errorMessage}`);
350
+ this.callbacks.onError?.(errorMessage, renderError);
340
351
  break;
352
+ }
341
353
  default:
342
354
  this.addLog(`\u{1F914} Unknown message type: ${data.type}`, "received");
343
355
  break;
@@ -802,7 +814,8 @@ function useRealtimeMockup(options = {}) {
802
814
  mockupResults: [],
803
815
  status: "Disconnected",
804
816
  logs: [],
805
- lastError: null
817
+ lastError: null,
818
+ renderError: null
806
819
  });
807
820
  (0, import_react.useEffect)(() => {
808
821
  const service = new RealtimeMockupService(wsUrl);
@@ -836,9 +849,9 @@ function useRealtimeMockup(options = {}) {
836
849
  setState(newState);
837
850
  options.onAllMockupsRendered?.(results);
838
851
  },
839
- onError: (error) => {
852
+ onError: (error, detail) => {
840
853
  setState(service.getState());
841
- options.onError?.(error);
854
+ options.onError?.(error, detail);
842
855
  }
843
856
  // REMOVED: onLog callback was causing setState on every log message,
844
857
  // which triggered re-renders during canvas drag operations
package/dist/react.d.cts CHANGED
@@ -1,4 +1,4 @@
1
- import { M as MockupResult, 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-Bfc3nsyG.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-C2hbBgve.cjs';
2
2
 
3
3
  interface UseRealtimeMockupOptions {
4
4
  wsUrl?: string;
@@ -21,7 +21,13 @@ interface UseRealtimeMockupOptions {
21
21
  onBlobSent?: (placement: string) => void;
22
22
  onMockupRendered?: (result: MockupResult) => void;
23
23
  onAllMockupsRendered?: (results: MockupResult[]) => void;
24
- onError?: (error: string) => void;
24
+ /**
25
+ * Server/transport error. `detail.code` is the stable machine-readable
26
+ * code (e.g. 'asset_not_allowed'); the same structured error is exposed on
27
+ * the hook's returned state as `renderError` — render it visibly (badge the
28
+ * stale mockup) instead of only logging it.
29
+ */
30
+ onError?: (error: string, detail: RealtimeRenderError) => void;
25
31
  }
26
32
  declare function useRealtimeMockup(options?: UseRealtimeMockupOptions): {
27
33
  connect: () => void;
@@ -51,6 +57,7 @@ declare function useRealtimeMockup(options?: UseRealtimeMockupOptions): {
51
57
  status: string;
52
58
  logs: string[];
53
59
  lastError: string | null;
60
+ renderError: RealtimeRenderError | null;
54
61
  };
55
62
 
56
63
  /**
package/dist/react.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { M as MockupResult, 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-Bfc3nsyG.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-C2hbBgve.js';
2
2
 
3
3
  interface UseRealtimeMockupOptions {
4
4
  wsUrl?: string;
@@ -21,7 +21,13 @@ interface UseRealtimeMockupOptions {
21
21
  onBlobSent?: (placement: string) => void;
22
22
  onMockupRendered?: (result: MockupResult) => void;
23
23
  onAllMockupsRendered?: (results: MockupResult[]) => void;
24
- onError?: (error: string) => void;
24
+ /**
25
+ * Server/transport error. `detail.code` is the stable machine-readable
26
+ * code (e.g. 'asset_not_allowed'); the same structured error is exposed on
27
+ * the hook's returned state as `renderError` — render it visibly (badge the
28
+ * stale mockup) instead of only logging it.
29
+ */
30
+ onError?: (error: string, detail: RealtimeRenderError) => void;
25
31
  }
26
32
  declare function useRealtimeMockup(options?: UseRealtimeMockupOptions): {
27
33
  connect: () => void;
@@ -51,6 +57,7 @@ declare function useRealtimeMockup(options?: UseRealtimeMockupOptions): {
51
57
  status: string;
52
58
  logs: string[];
53
59
  lastError: string | null;
60
+ renderError: RealtimeRenderError | null;
54
61
  };
55
62
 
56
63
  /**
package/dist/react.js CHANGED
@@ -1,6 +1,6 @@
1
1
  import {
2
2
  RealtimeMockupService
3
- } from "./chunk-QHRQ3VJD.js";
3
+ } from "./chunk-MKLLTNKJ.js";
4
4
 
5
5
  // src/realtime/react.ts
6
6
  import { useCallback, useEffect, useRef, useState } from "react";
@@ -17,7 +17,8 @@ function useRealtimeMockup(options = {}) {
17
17
  mockupResults: [],
18
18
  status: "Disconnected",
19
19
  logs: [],
20
- lastError: null
20
+ lastError: null,
21
+ renderError: null
21
22
  });
22
23
  useEffect(() => {
23
24
  const service = new RealtimeMockupService(wsUrl);
@@ -51,9 +52,9 @@ function useRealtimeMockup(options = {}) {
51
52
  setState(newState);
52
53
  options.onAllMockupsRendered?.(results);
53
54
  },
54
- onError: (error) => {
55
+ onError: (error, detail) => {
55
56
  setState(service.getState());
56
- options.onError?.(error);
57
+ options.onError?.(error, detail);
57
58
  }
58
59
  // REMOVED: onLog callback was causing setState on every log message,
59
60
  // which triggered re-renders during canvas drag operations
@@ -256,6 +256,8 @@ interface WebSocketMessage {
256
256
  mockupId?: string;
257
257
  imageSize?: number;
258
258
  message?: string;
259
+ /** Machine-readable error code on `type: 'error'` frames (e.g. 'asset_not_allowed') */
260
+ code?: string;
259
261
  placement?: string;
260
262
  missingPlacements?: string[];
261
263
  /** Per-render correlation id (== OTel trace-id) echoed back by the server */
@@ -282,6 +284,20 @@ interface WebSocketMessage {
282
284
  totalMs: number;
283
285
  };
284
286
  }
287
+ /**
288
+ * Structured render/server error from the realtime session.
289
+ *
290
+ * Mirrors the server's `{type:'error', code, message}` frame. `message` carries
291
+ * the human detail (e.g. the blocked asset URL for `asset_not_allowed`);
292
+ * `code` is the stable machine-readable identifier UIs should key on (e.g. a
293
+ * `data-render-error` attribute) so agents and tests can assert the failure.
294
+ */
295
+ interface RealtimeRenderError {
296
+ /** Stable error code, e.g. 'asset_not_allowed'. 'render_error' when the server sent none. */
297
+ code: string;
298
+ /** Human-readable detail (includes specifics such as the blocked asset URL). */
299
+ message: string;
300
+ }
285
301
  interface RealtimeMockupState {
286
302
  isConnected: boolean;
287
303
  sessionId: string | null;
@@ -290,6 +306,15 @@ interface RealtimeMockupState {
290
306
  status: string;
291
307
  logs: string[];
292
308
  lastError: string | null;
309
+ /**
310
+ * Structured form of {@link RealtimeMockupState.lastError}: the most recent
311
+ * server error, with its machine-readable `code`. Cleared when a later
312
+ * render succeeds, so it always reflects whether the CURRENT mockupResults
313
+ * are stale relative to the latest request. `mockupResults` intentionally
314
+ * keeps the last good renders on error — mark them stale in the UI instead
315
+ * of blanking them.
316
+ */
317
+ renderError: RealtimeRenderError | null;
293
318
  }
294
319
  interface RealtimeMockupCallbacks {
295
320
  onConnected?: (sessionId: string) => void;
@@ -301,7 +326,13 @@ interface RealtimeMockupCallbacks {
301
326
  onBlobSent?: (placement: string) => void;
302
327
  onMockupRendered?: (result: MockupResult) => void;
303
328
  onAllMockupsRendered?: (results: MockupResult[]) => void;
304
- onError?: (error: string) => void;
329
+ /**
330
+ * Server/transport error. `detail` carries the structured form (stable
331
+ * `code` + human message) — surface it visibly in the UI; the previous
332
+ * mockupResults are kept on purpose so hosts can show "stale + error
333
+ * badge" instead of a blank panel.
334
+ */
335
+ onError?: (error: string, detail: RealtimeRenderError) => void;
305
336
  onLog?: (message: string, type: 'info' | 'sent' | 'received') => void;
306
337
  }
307
338
  declare class RealtimeMockupService {
@@ -315,6 +346,7 @@ declare class RealtimeMockupService {
315
346
  private status;
316
347
  private logs;
317
348
  private lastError;
349
+ private renderError;
318
350
  private callbacks;
319
351
  private requestSendTimes;
320
352
  private canvasBlobs;
@@ -411,4 +443,4 @@ declare class RealtimeMockupService {
411
443
  clearMockups(): void;
412
444
  }
413
445
 
414
- export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type PlacementSettings as P, RealtimeMockupService as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, type ProductComponentContext as h, type RealtimeMockupCallbacks as i, type RealtimeMockupState as j, type RenderResult as k, type WebSocketMessage as l, adapterRegistry as m, computeDisabledChoices as n, createComponent as o, defineComponent as p, deriveDefaultSelection as q, findBestCombination as r, getPricePreview as s, isOptionAvailable as t, resolveBestCombination as u };
446
+ export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type PlacementSettings as P, type RealtimeRenderError as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, RealtimeMockupService as h, type ProductComponentContext as i, type RealtimeMockupCallbacks as j, type RealtimeMockupState as k, type RenderResult as l, type WebSocketMessage as m, adapterRegistry as n, computeDisabledChoices as o, createComponent as p, defineComponent as q, deriveDefaultSelection as r, findBestCombination as s, getPricePreview as t, isOptionAvailable as u, resolveBestCombination as v };
@@ -256,6 +256,8 @@ interface WebSocketMessage {
256
256
  mockupId?: string;
257
257
  imageSize?: number;
258
258
  message?: string;
259
+ /** Machine-readable error code on `type: 'error'` frames (e.g. 'asset_not_allowed') */
260
+ code?: string;
259
261
  placement?: string;
260
262
  missingPlacements?: string[];
261
263
  /** Per-render correlation id (== OTel trace-id) echoed back by the server */
@@ -282,6 +284,20 @@ interface WebSocketMessage {
282
284
  totalMs: number;
283
285
  };
284
286
  }
287
+ /**
288
+ * Structured render/server error from the realtime session.
289
+ *
290
+ * Mirrors the server's `{type:'error', code, message}` frame. `message` carries
291
+ * the human detail (e.g. the blocked asset URL for `asset_not_allowed`);
292
+ * `code` is the stable machine-readable identifier UIs should key on (e.g. a
293
+ * `data-render-error` attribute) so agents and tests can assert the failure.
294
+ */
295
+ interface RealtimeRenderError {
296
+ /** Stable error code, e.g. 'asset_not_allowed'. 'render_error' when the server sent none. */
297
+ code: string;
298
+ /** Human-readable detail (includes specifics such as the blocked asset URL). */
299
+ message: string;
300
+ }
285
301
  interface RealtimeMockupState {
286
302
  isConnected: boolean;
287
303
  sessionId: string | null;
@@ -290,6 +306,15 @@ interface RealtimeMockupState {
290
306
  status: string;
291
307
  logs: string[];
292
308
  lastError: string | null;
309
+ /**
310
+ * Structured form of {@link RealtimeMockupState.lastError}: the most recent
311
+ * server error, with its machine-readable `code`. Cleared when a later
312
+ * render succeeds, so it always reflects whether the CURRENT mockupResults
313
+ * are stale relative to the latest request. `mockupResults` intentionally
314
+ * keeps the last good renders on error — mark them stale in the UI instead
315
+ * of blanking them.
316
+ */
317
+ renderError: RealtimeRenderError | null;
293
318
  }
294
319
  interface RealtimeMockupCallbacks {
295
320
  onConnected?: (sessionId: string) => void;
@@ -301,7 +326,13 @@ interface RealtimeMockupCallbacks {
301
326
  onBlobSent?: (placement: string) => void;
302
327
  onMockupRendered?: (result: MockupResult) => void;
303
328
  onAllMockupsRendered?: (results: MockupResult[]) => void;
304
- onError?: (error: string) => void;
329
+ /**
330
+ * Server/transport error. `detail` carries the structured form (stable
331
+ * `code` + human message) — surface it visibly in the UI; the previous
332
+ * mockupResults are kept on purpose so hosts can show "stale + error
333
+ * badge" instead of a blank panel.
334
+ */
335
+ onError?: (error: string, detail: RealtimeRenderError) => void;
305
336
  onLog?: (message: string, type: 'info' | 'sent' | 'received') => void;
306
337
  }
307
338
  declare class RealtimeMockupService {
@@ -315,6 +346,7 @@ declare class RealtimeMockupService {
315
346
  private status;
316
347
  private logs;
317
348
  private lastError;
349
+ private renderError;
318
350
  private callbacks;
319
351
  private requestSendTimes;
320
352
  private canvasBlobs;
@@ -411,4 +443,4 @@ declare class RealtimeMockupService {
411
443
  clearMockups(): void;
412
444
  }
413
445
 
414
- export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type PlacementSettings as P, RealtimeMockupService as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, type ProductComponentContext as h, type RealtimeMockupCallbacks as i, type RealtimeMockupState as j, type RenderResult as k, type WebSocketMessage as l, adapterRegistry as m, computeDisabledChoices as n, createComponent as o, defineComponent as p, deriveDefaultSelection as q, findBestCombination as r, getPricePreview as s, isOptionAvailable as t, resolveBestCombination as u };
446
+ export { AdapterRegistry as A, type Combination as C, type EventHandler as E, type FrameworkAdapter as F, type MockupResult as M, type OptionAttribute as O, type PlacementSettings as P, type RealtimeRenderError as R, type WebSocketConfig as W, type OptionSelection as a, type ComponentProps as b, type ComponentDescriptor as c, type ComponentState as d, type ComponentContext as e, type ComponentLifecycleHooks as f, type FrameworkUtilities as g, RealtimeMockupService as h, type ProductComponentContext as i, type RealtimeMockupCallbacks as j, type RealtimeMockupState as k, type RenderResult as l, type WebSocketMessage as m, adapterRegistry as n, computeDisabledChoices as o, createComponent as p, defineComponent as q, deriveDefaultSelection as r, findBestCombination as s, getPricePreview as t, isOptionAvailable as u, resolveBestCombination as v };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@snowcone-app/sdk",
3
- "version": "0.16.1",
3
+ "version": "0.17.0",
4
4
  "description": "Snowcone SDK for product mockups and print-on-demand",
5
5
  "keywords": [
6
6
  "merch",