@weaverse/hydrogen 5.17.1 → 5.18.0

package/dist/index.mjs

@@ -207,9 +207,13 @@ function isProjectIdFunction(projectId) {
   return typeof projectId === "function";
 }
 var WeaverseError = class _WeaverseError extends Error {
+  /** Machine-readable error code. */
   code;
+  /** HTTP status associated with the failure, when available. */
   statusCode;
+  /** Structured diagnostic details for logging and error handling. */
   context;
+  /** Creates a Weaverse request error with a stable code and diagnostics. */
   constructor(message, code = "WEAVERSE_ERROR", statusCode, context) {
     super(message);
     this.name = "WeaverseError";
@@ -515,18 +519,24 @@ function getPreviewData(type, components, weaverseHost) {
 
 // src/utils/translation-store.ts
 var TranslationStore = class {
+  /** Current flat translation overrides keyed by dot-path. */
   overrides = {};
   listeners = /* @__PURE__ */ new Set();
+  /** Replaces all overrides and notifies subscribers. */
   setOverrides = (overrides) => {
     this.overrides = { ...overrides };
     this.emit();
   };
+  /** Merges changed overrides and notifies subscribers. */
   updateOverrides = (newOverrides) => {
     this.overrides = { ...this.overrides, ...newOverrides };
     this.emit();
   };
+  /** Returns the current client snapshot for `useSyncExternalStore`. */
   getSnapshot = () => this.overrides;
+  /** Returns the current server snapshot for `useSyncExternalStore`. */
   getServerSnapshot = () => this.overrides;
+  /** Subscribes to override changes and returns an unsubscribe callback. */
   subscribe = (callback) => {
     this.listeners.add(callback);
     return () => {
@@ -658,12 +668,16 @@ function registerPixelInstance() {
   };
 }
 var ThemeSettingsStore = class {
+  /** Current merged theme setting values. */
   settings = {};
+  /** Theme schema exposed to Studio, when available. */
   schema;
+  /** Storefront-safe environment values, when available. */
   publicEnv;
   listeners = /* @__PURE__ */ new Set();
   hasWarnedListenerCount = false;
   isDestroyed = false;
+  /** Creates a theme settings store from root-loader theme data. */
   constructor(data) {
     const { theme, schema: schema2, publicEnv } = data || {};
     this.settings = { ...theme };
@@ -673,6 +687,7 @@ var ThemeSettingsStore = class {
       window.__weaverseThemeSettingsStore = this;
     }
   }
+  /** Merges setting changes into the current snapshot and notifies subscribers. */
   updateThemeSettings = (newSettings) => {
     if (this.isDestroyed) {
       console.warn("ThemeSettingsStore: Cannot update destroyed store");
@@ -684,8 +699,11 @@ var ThemeSettingsStore = class {
     };
     this.emit();
   };
+  /** Returns the current client snapshot for `useSyncExternalStore`. */
   getSnapshot = () => this.settings;
+  /** Returns the current server snapshot for `useSyncExternalStore`. */
   getServerSnapshot = () => this.settings;
+  /** Subscribes to setting changes and returns an unsubscribe callback. */
   subscribe = (callback) => {
     if (this.isDestroyed) {
       console.warn("ThemeSettingsStore: Cannot subscribe to destroyed store");
@@ -716,6 +734,7 @@ var ThemeSettingsStore = class {
       }
     }
   };
+  /** Clears subscribers and detaches the browser-global store reference. */
   destroy = () => {
     if (this.isDestroyed) {
       return;
@@ -865,6 +884,7 @@ var WeaverseHydrogenItem = class extends WeaverseItemStore {
   _cachedSnapshot = null;
   _snapshotStoreRef = null;
   _snapshotTranslationRef = null;
+  /** Creates an item store from serialized component data and its owner. */
   constructor(initialData, weaverse) {
     super(initialData, weaverse);
     const { data, ...rest } = initialData;
@@ -875,6 +895,7 @@ var WeaverseHydrogenItem = class extends WeaverseItemStore {
     const schemaData = generateDataFromSchema(this.Element.schema);
     Object.assign(this._store, schemaData, data, rest);
   }
+  /** Registered component definition for this item's type. */
   get Element() {
     return super.Element;
   }
@@ -907,17 +928,32 @@ var WeaverseHydrogenItem = class extends WeaverseItemStore {
 };
 Weaverse.ItemConstructor = WeaverseHydrogenItem;
 var WeaverseHydrogen = class extends Weaverse {
+  /** Identifier of the rendered page. */
   pageId;
+  /** Runtime services and project metadata exposed to integrations. */
   internal;
+  /** Normalized URL and locale information for the current request. */
   requestInfo;
+  /** Identifier of the project supplying the page. */
   projectId;
+  /** Origin used for Studio assets and editor communication. */
   weaverseHost;
+  /** Base URL used for public content API requests. */
   weaverseApiBase;
+  /**
+   * API key read from environment/configuration for storefront requests or
+   * supplied by Studio requests while editing and previewing.
+   */
   weaverseApiKey;
+  /** Studio asset version supplied by the preview request. */
   weaverseVersion;
+  /** Whether the page is running inside the visual editor. */
   isDesignMode;
+  /** Whether a single component preview is being rendered. */
   isPreviewMode;
+  /** Whether a saved page revision is being previewed. */
   isRevisionPreview;
+  /** Component type requested by section preview mode. */
   sectionType;
   // ─── Translation sidecar (design mode only) ────────────────────────
   /**
@@ -927,8 +963,11 @@ var WeaverseHydrogen = class extends Weaverse {
    * returned to components, so translations render without monkey-patching.
    */
   translationMap = {};
+  /** Locale code for the active translation sidecar. */
   translationLocale = "";
+  /** Builder language identifier for the active translation sidecar. */
   translationLanguageId = "";
+  /** Creates a page runtime from resolved loader data and request settings. */
   constructor(params) {
     const { internal, pageId, requestInfo, ...coreParams } = params;
     super({ ...coreParams });
@@ -1231,25 +1270,38 @@ var SMART_CACHE_STRATEGIES = {
   }
 };
 var WeaverseClient = class {
+  /** Builder API version used by this client. */
   API = API_PATH;
+  /** Stable project configuration shared by page requests. */
   basePageConfigs;
+  /** Stable request body fields shared by page requests. */
   basePageRequestBody;
+  /** Resolved project and rendering-mode configuration. */
   configs;
+  /** Hydrogen cache wrapper used for Builder API requests. */
   withCache;
-  // Required dependencies
+  /** Incoming request associated with this client instance. */
   request;
+  /** Hydrogen customer-account client, when configured. */
   customerAccount;
+  /** Hydrogen Storefront API client and locale context. */
   storefront;
+  /** Components registered for page rendering and component loaders. */
   components;
+  /** Theme schema used for defaults and Studio editing. */
   themeSchema;
+  /** Hydrogen runtime environment variables. */
   env;
+  /** Cache storage supplied by the Hydrogen runtime. */
   cache;
+  /** Background execution hook supplied by the Oxygen runtime. */
   waitUntil;
   // Performance optimizations
   parsedUrl;
   componentsByType;
   // Configuration
   fetchTimeoutMs;
+  /** Creates a request-scoped client from the Hydrogen app context. */
   constructor(args) {
     this.request = args.request;
     this.storefront = args.storefront;
@@ -1998,6 +2050,7 @@ var WeaverseClient = class {
       return null;
     }
   };
+  /** Executes the registered loader for one component and attaches its result. */
   execComponentLoader = async (item) => {
     const { data = {}, type, id } = item;
     const component = this.componentsByType.get(type);
@@ -2030,34 +2083,63 @@ function getSelectedProductOptions(request) {
   );
 }
 var IMAGES_PLACEHOLDERS = {
+  /** White Weaverse logo placeholder. */
   logo_white: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-logo-w-600x200.svg",
+  /** Black Weaverse logo placeholder. */
   logo_black: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-logo-k-600x200.svg",
+  /** Generic square image placeholder. */
   image: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-image-1024x1024.svg",
+  /** First landscape banner placeholder. */
   banner_1: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-lifestyle-1-1800x900.svg",
+  /** Second landscape banner placeholder. */
   banner_2: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-lifestyle-2-1800x900.svg",
+  /** Hats collection placeholder. */
   collection_1: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-collection-hats-1024x1024.svg",
+  /** Shoes collection placeholder. */
   collection_2: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-collection-shoes-1024x1024.svg",
+  /** Glasses collection placeholder. */
   collection_3: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-collection-glasses-1024x1024.svg",
+  /** Lamps collection placeholder. */
   collection_4: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-collection-lamps-1024x1024.svg",
+  /** Bags collection placeholder. */
   collection_5: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-collection-bags-1024x1024.svg",
+  /** Watches collection placeholder. */
   collection_6: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-collection-watches-1024x1024.svg",
+  /** Third watch product placeholder. */
   product_1: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-product-watch-3-1024x1024.svg",
+  /** Second bag product placeholder. */
   product_2: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-product-bag-2-1024x1024.svg",
+  /** First shoe product placeholder. */
   product_3: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-product-shoe-1-1024x1024.svg",
+  /** Second lamp product placeholder. */
   product_4: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-product-lamp-2-1024x1024.svg",
+  /** First glasses product placeholder. */
   product_5: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-product-glasses-1-1024x1024.svg",
+  /** First lamp product placeholder. */
   product_6: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-product-lamp-1-1024x1024.svg",
+  /** Second glasses product placeholder. */
   product_7: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-product-glasses-2-1024x1024.svg",
+  /** Third hat product placeholder. */
   product_8: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-product-hat-3-1024x1024.svg",
+  /** First bag product placeholder. */
   product_9: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-product-bag-1-1024x1024.svg",
+  /** Second shoe product placeholder. */
   product_10: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-product-shoe-2-1024x1024.svg",
+  /** Second hat product placeholder. */
   product_11: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-product-hat-2-1024x1024.svg",
+  /** Third glasses product placeholder. */
   product_12: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-product-glasses-3-1024x1024.svg",
+  /** Third shoe product placeholder. */
   product_13: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-product-shoe-3-1024x1024.svg",
+  /** Third bag product placeholder. */
   product_14: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-product-bag-3-1024x1024.svg",
+  /** First hat product placeholder. */
   product_15: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-product-hat-1-1024x1024.svg",
+  /** Third lamp product placeholder. */
   product_16: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-product-lamp-3-1024x1024.svg",
+  /** First watch product placeholder. */
   product_17: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-product-watch-1-1024x1024.svg",
+  /** Second watch product placeholder. */
   product_18: "https://cdn.shopify.com/s/files/1/0838/0052/3057/files/fpo-product-watch-2-1024x1024.svg"
 };