@shopify/hydrogen 2026.4.4 → 2026.10.0-preview.1

package/dist/vue/shopify-scripts.d.mts

@@ -0,0 +1,127 @@
+import { ShopifyRoutesOptions, ShopifyScriptTagsOptions, ShopifyScriptsAnalyticsConfig, ShopifyScriptsI18n, ShopifyScriptsShop } from "../core/shopify-scripts/types.mjs";
+import { ConsentConfig } from "../core/analytics/types.mjs";
+import * as _$vue from "vue";
+
+//#region src/vue/shopify-scripts.d.ts
+type ShopifyScriptsProps = ShopifyScriptTagsOptions & {
+  navigate?: ShopifyRoutesOptions["navigate"];
+  routes?: ShopifyRoutesOptions["routes"];
+  webMcp?: boolean;
+};
+declare const ShopifyScripts: _$vue.DefineComponent<_$vue.ExtractPropTypes<{
+  i18n: {
+    type: () => ShopifyScriptsI18n;
+    default: undefined;
+  };
+  nonce: {
+    type: StringConstructor;
+    default: undefined;
+  };
+  routes: {
+    type: null;
+    default: undefined;
+  };
+  navigate: {
+    type: null;
+    default: undefined;
+  };
+  consent: {
+    type: (new (...args: any[]) => ConsentConfig) | (() => ConsentConfig | undefined);
+    default: undefined;
+  };
+  analytics: {
+    type: (new (...args: any[]) => ShopifyScriptsAnalyticsConfig) | (() => ShopifyScriptsAnalyticsConfig | undefined);
+    default: undefined;
+  };
+  debug: {
+    type: (new (...args: any[]) => {
+      standardEventsInspector?: boolean;
+    }) | (() => {
+      standardEventsInspector?: boolean;
+    } | undefined);
+    default: undefined;
+  };
+  webMcp: {
+    type: BooleanConstructor;
+    default: undefined;
+  };
+  inbox: {
+    type: () => boolean | undefined;
+    default: undefined;
+  };
+  shopifyAnalytics: {
+    type: BooleanConstructor;
+    default: undefined;
+  };
+  shop: {
+    type: () => ShopifyScriptsShop;
+    required: true;
+  };
+}>, () => _$vue.VNode<_$vue.RendererNode, _$vue.RendererElement, {
+  [key: string]: any;
+}>[], {}, {}, {}, _$vue.ComponentOptionsMixin, _$vue.ComponentOptionsMixin, {}, string, _$vue.PublicProps, Readonly<_$vue.ExtractPropTypes<{
+  i18n: {
+    type: () => ShopifyScriptsI18n;
+    default: undefined;
+  };
+  nonce: {
+    type: StringConstructor;
+    default: undefined;
+  };
+  routes: {
+    type: null;
+    default: undefined;
+  };
+  navigate: {
+    type: null;
+    default: undefined;
+  };
+  consent: {
+    type: (new (...args: any[]) => ConsentConfig) | (() => ConsentConfig | undefined);
+    default: undefined;
+  };
+  analytics: {
+    type: (new (...args: any[]) => ShopifyScriptsAnalyticsConfig) | (() => ShopifyScriptsAnalyticsConfig | undefined);
+    default: undefined;
+  };
+  debug: {
+    type: (new (...args: any[]) => {
+      standardEventsInspector?: boolean;
+    }) | (() => {
+      standardEventsInspector?: boolean;
+    } | undefined);
+    default: undefined;
+  };
+  webMcp: {
+    type: BooleanConstructor;
+    default: undefined;
+  };
+  inbox: {
+    type: () => boolean | undefined;
+    default: undefined;
+  };
+  shopifyAnalytics: {
+    type: BooleanConstructor;
+    default: undefined;
+  };
+  shop: {
+    type: () => ShopifyScriptsShop;
+    required: true;
+  };
+}>> & Readonly<{}>, {
+  analytics: ShopifyScriptsAnalyticsConfig | undefined;
+  consent: ConsentConfig | undefined;
+  debug: {
+    standardEventsInspector?: boolean;
+  } | undefined;
+  i18n: ShopifyScriptsI18n;
+  inbox: boolean | undefined;
+  nonce: string;
+  shopifyAnalytics: boolean;
+  navigate: any;
+  routes: any;
+  webMcp: boolean;
+}, {}, {}, {}, string, _$vue.ComponentProvideOptions, true, {}, any>;
+//#endregion
+export { ShopifyScripts, ShopifyScriptsProps };
+//# sourceMappingURL=shopify-scripts.d.mts.map

package/dist/vue/shopify-scripts.mjs

@@ -0,0 +1,79 @@
+import { initializeShopifyScripts } from "../core/shopify-scripts/initialize.mjs";
+import { getShopifyScriptTags } from "../core/shopify-scripts/index.mjs";
+import { defineComponent, h, onMounted } from "vue";
+
+//#region src/vue/shopify-scripts.ts
+const i18nProp = Object;
+const navigateProp = null;
+const routesProp = null;
+const shopProp = Object;
+const consentProp = Object;
+const analyticsProp = Object;
+const debugProp = Object;
+const inboxProp = Boolean;
+const ShopifyScripts = defineComponent({
+	name: "ShopifyScripts",
+	props: {
+		i18n: {
+			type: i18nProp,
+			default: void 0
+		},
+		nonce: {
+			type: String,
+			default: void 0
+		},
+		routes: {
+			type: routesProp,
+			default: void 0
+		},
+		navigate: {
+			type: navigateProp,
+			default: void 0
+		},
+		consent: {
+			type: consentProp,
+			default: void 0
+		},
+		analytics: {
+			type: analyticsProp,
+			default: void 0
+		},
+		debug: {
+			type: debugProp,
+			default: void 0
+		},
+		webMcp: {
+			type: Boolean,
+			default: void 0
+		},
+		inbox: {
+			type: inboxProp,
+			default: void 0
+		},
+		shopifyAnalytics: {
+			type: Boolean,
+			default: void 0
+		},
+		shop: {
+			type: shopProp,
+			required: true
+		}
+	},
+	setup(props) {
+		onMounted(() => {
+			initializeShopifyScripts({
+				navigate: props.navigate,
+				routes: props.routes,
+				webMcp: props.webMcp !== false
+			});
+		});
+		return () => getShopifyScriptTags(props).tags.map(({ tagName, attributes, innerHTML }) => h(tagName, {
+			...attributes,
+			...innerHTML ? { innerHTML } : {}
+		}));
+	}
+});
+
+//#endregion
+export { ShopifyScripts };
+//# sourceMappingURL=shopify-scripts.mjs.map

package/dist/vue/shopify-scripts.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"shopify-scripts.mjs","names":[],"sources":["../../src/vue/shopify-scripts.ts"],"sourcesContent":["import { defineComponent, h, onMounted, type PropType } from \"vue\";\n\nimport {\n  getShopifyScriptTags,\n  initializeShopifyScripts,\n  type ShopifyScriptsShop,\n  type ShopifyScriptsI18n,\n  type ShopifyScriptTagsOptions,\n  type ShopifyRoutesOptions,\n} from \"../core/shopify-scripts/index\";\n\nexport type ShopifyScriptsProps = ShopifyScriptTagsOptions & {\n  navigate?: ShopifyRoutesOptions[\"navigate\"];\n  routes?: ShopifyRoutesOptions[\"routes\"];\n  webMcp?: boolean;\n};\n\ntype CompletePropOptions<T> = {\n  [K in keyof T]-?: unknown;\n};\n\nconst i18nProp: PropType<ShopifyScriptsI18n> = Object;\nconst navigateProp: PropType<NonNullable<ShopifyRoutesOptions[\"navigate\"]>> | null = null;\nconst routesProp: PropType<NonNullable<ShopifyRoutesOptions[\"routes\"]>> | null = null;\nconst shopProp: PropType<ShopifyScriptsShop> = Object;\nconst consentProp: PropType<ShopifyScriptTagsOptions[\"consent\"]> = Object;\nconst analyticsProp: PropType<ShopifyScriptTagsOptions[\"analytics\"]> = Object;\nconst debugProp: PropType<ShopifyScriptTagsOptions[\"debug\"]> = Object;\nconst inboxProp: PropType<ShopifyScriptTagsOptions[\"inbox\"]> = Boolean;\n\nexport const ShopifyScripts = defineComponent({\n  name: \"ShopifyScripts\",\n  props: {\n    i18n: {\n      type: i18nProp,\n      default: undefined,\n    },\n    nonce: {\n      type: String,\n      default: undefined,\n    },\n    routes: {\n      type: routesProp,\n      default: undefined,\n    },\n    navigate: {\n      type: navigateProp,\n      default: undefined,\n    },\n    consent: {\n      type: consentProp,\n      default: undefined,\n    },\n    analytics: {\n      type: analyticsProp,\n      default: undefined,\n    },\n    debug: {\n      type: debugProp,\n      default: undefined,\n    },\n    webMcp: {\n      type: Boolean,\n      default: undefined,\n    },\n    inbox: {\n      type: inboxProp,\n      default: undefined,\n    },\n    shopifyAnalytics: {\n      type: Boolean,\n      default: undefined,\n    },\n    shop: {\n      type: shopProp,\n      required: true as const,\n    },\n  } satisfies CompletePropOptions<ShopifyScriptsProps>,\n  setup(props) {\n    onMounted(() => {\n      void initializeShopifyScripts({\n        navigate: props.navigate,\n        routes: props.routes,\n        webMcp: props.webMcp !== false,\n      });\n    });\n\n    return () =>\n      getShopifyScriptTags(props).tags.map(({ tagName, attributes, innerHTML }) =>\n        h(tagName, {\n          ...attributes,\n          ...(innerHTML ? { innerHTML } : {}),\n        }),\n      );\n  },\n});\n"],"mappings":";;;;;AAqBA,MAAM,WAAyC;AAC/C,MAAM,eAA+E;AACrF,MAAM,aAA2E;AACjF,MAAM,WAAyC;AAC/C,MAAM,cAA6D;AACnE,MAAM,gBAAiE;AACvE,MAAM,YAAyD;AAC/D,MAAM,YAAyD;AAE/D,MAAa,iBAAiB,gBAAgB;CAC5C,MAAM;CACN,OAAO;EACL,MAAM;GACJ,MAAM;GACN,SAAS;GACV;EACD,OAAO;GACL,MAAM;GACN,SAAS;GACV;EACD,QAAQ;GACN,MAAM;GACN,SAAS;GACV;EACD,UAAU;GACR,MAAM;GACN,SAAS;GACV;EACD,SAAS;GACP,MAAM;GACN,SAAS;GACV;EACD,WAAW;GACT,MAAM;GACN,SAAS;GACV;EACD,OAAO;GACL,MAAM;GACN,SAAS;GACV;EACD,QAAQ;GACN,MAAM;GACN,SAAS;GACV;EACD,OAAO;GACL,MAAM;GACN,SAAS;GACV;EACD,kBAAkB;GAChB,MAAM;GACN,SAAS;GACV;EACD,MAAM;GACJ,MAAM;GACN,UAAU;GACX;EACF;CACD,MAAM,OAAO;AACX,kBAAgB;AACd,GAAK,yBAAyB;IAC5B,UAAU,MAAM;IAChB,QAAQ,MAAM;IACd,QAAQ,MAAM,WAAW;IAC1B,CAAC;IACF;AAEF,eACE,qBAAqB,MAAM,CAAC,KAAK,KAAK,EAAE,SAAS,YAAY,gBAC3D,EAAE,SAAS;GACT,GAAG;GACH,GAAI,YAAY,EAAE,WAAW,GAAG,EAAE;GACnC,CAAC,CACH;;CAEN,CAAC"}

package/package.json

@@ -1,125 +1,155 @@
 {
   "name": "@shopify/hydrogen",
-  "publishConfig": {
-    "access": "public",
-    "@shopify:registry": "https://registry.npmjs.org"
-  },
-  "type": "module",
-  "version": "2026.4.4",
+  "version": "2026.10.0-preview.1",
+  "description": "Framework-agnostic Shopify storefront SDK and agent skills.",
   "license": "MIT",
-  "main": "dist/index.cjs",
-  "module": "dist/production/index.js",
-  "types": "dist/production/index.d.ts",
-  "sideEffects": false,
+  "author": "Shopify",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Shopify/hydrogen.git",
     "directory": "packages/hydrogen"
   },
+  "bin": {
+    "hydrogen": "./bin/hydrogen.mjs"
+  },
+  "files": [
+    "README.md",
+    "bin",
+    "dist",
+    "skills"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/core/index.mjs",
+  "types": "./dist/core/index.d.mts",
   "exports": {
     ".": {
-      "types": "./dist/production/index.d.ts",
-      "module": {
-        "development": "./dist/development/index.js",
-        "default": "./dist/production/index.js"
+      "types": {
+        "development": "./dist/development/core/development.d.mts",
+        "default": "./dist/core/index.d.mts"
       },
-      "require": "./dist/index.cjs",
       "import": {
-        "development": "./dist/development/index.js",
-        "default": "./dist/production/index.js"
+        "development": "./dist/development/core/development.mjs",
+        "default": "./dist/core/index.mjs"
       },
       "default": {
-        "development": "./dist/development/index.js",
-        "default": "./dist/production/index.js"
+        "development": "./dist/development/core/development.mjs",
+        "default": "./dist/core/index.mjs"
       }
     },
-    "./vite": {
-      "types": "./dist/vite/plugin.d.ts",
-      "default": "./dist/vite/plugin.js"
-    },
-    "./oxygen": {
-      "types": "./dist/oxygen/index.d.ts",
-      "default": "./dist/oxygen/index.js"
+    "./customer-account": {
+      "types": "./dist/customer-account/index.d.mts",
+      "import": "./dist/customer-account/index.mjs"
     },
-    "./storefront-api-types": "./dist/storefront-api-types.d.ts",
-    "./storefront.schema.json": "./dist/storefront.schema.json",
     "./customer-account-api-types": "./dist/customer-account-api-types.d.ts",
     "./customer-account.schema.json": "./dist/customer-account.schema.json",
-    "./react-router-types": {
-      "types": "./dist/react-router.d.ts"
+    "./package.json": "./package.json",
+    "./skills/*": "./skills/*",
+    "./storefront-api-types": "./dist/storefront-api-types.d.ts",
+    "./storefront.schema.json": "./dist/storefront.schema.json",
+    "./ts-plugin": {
+      "types": "./dist/ts-plugin/index.d.cts",
+      "require": "./dist/ts-plugin/index.cjs",
+      "default": "./dist/ts-plugin/index.cjs"
     },
-    "./react-router-preset": {
-      "types": "./dist/production/react-router-preset.d.ts",
-      "import": {
-        "development": "./dist/development/react-router-preset.js",
-        "default": "./dist/production/react-router-preset.js"
+    "./vite": {
+      "types": "./dist/vite/index.d.mts",
+      "import": "./dist/vite/index.mjs"
+    },
+    "./react": {
+      "types": {
+        "development": "./dist/development/react/index.d.mts",
+        "default": "./dist/react/index.d.mts"
       },
-      "default": "./dist/production/react-router-preset.js"
+      "import": {
+        "development": "./dist/development/react/index.mjs",
+        "default": "./dist/react/index.mjs"
+      }
     },
-    "./package.json": "./package.json"
-  },
-  "typesVersions": {
-    "*": {
-      "storefront-api-types": [
-        "./dist/storefront-api-types.d.ts"
-      ],
-      "customer-account-api-types": [
-        "./dist/customer-account-api-types.d.ts"
-      ]
+    "./vue": {
+      "types": {
+        "development": "./dist/development/vue/index.d.mts",
+        "default": "./dist/vue/index.d.mts"
+      },
+      "import": {
+        "development": "./dist/development/vue/index.mjs",
+        "default": "./dist/vue/index.mjs"
+      }
     }
   },
-  "files": [
-    "dist"
-  ],
+  "publishConfig": {
+    "@shopify:registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
   "dependencies": {
-    "content-security-policy-builder": "^2.2.0",
-    "flame-chart-js": "2.3.1",
-    "isbot": "^5.1.21",
-    "source-map-support": "^0.5.21",
-    "type-fest": "^4.33.0",
-    "use-resize-observer": "^9.1.0",
-    "worktop": "^0.7.3",
-    "@shopify/graphql-client": "1.4.1",
-    "@shopify/hydrogen-react": "2026.4.3"
+    "gql.tada": "1.9.2"
   },
   "devDependencies": {
-    "react-router": "7.16.0",
-    "@react-router/dev": "7.16.0",
-    "@shopify/generate-docs": "1.2.2",
-    "@testing-library/jest-dom": "^6.6.3",
-    "@types/node": "22.19.15",
-    "@types/react": "^18.3.28",
-    "@types/react-dom": "^18.3.7",
-    "@testing-library/react": "^14.0.0",
-    "@types/source-map-support": "^0.5.10",
-    "formdata-polyfill": "^4.0.10",
-    "graphql": "^16.12.0",
-    "happy-dom": "^20.8.9",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "schema-dts": "^1.1.2",
-    "vitest": "^3.2.4",
-    "@shopify/hydrogen-codegen": "0.3.3"
+    "@graphql-codegen/cli": "^7.0.0",
+    "@graphql-codegen/introspection": "^6.0.0",
+    "@graphql-codegen/typescript": "^6.0.0",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@vue/test-utils": "^2.4.0",
+    "graphql": "^16.13.2",
+    "happy-dom": "^20.9.0",
+    "magic-string": "^0.30.21",
+    "oxc-parser": "0.135.0",
+    "oxc-walker": "^1.0.0",
+    "react": "^19.2.5",
+    "react-dom": "^19.2.5",
+    "tsdown": "^0.21.10",
+    "typescript": "^5.9.3",
+    "vite": "^8.0.7",
+    "vitest": "^3.0.0"
   },
   "peerDependencies": {
-    "react-router": "~7.16.0",
-    "@react-router/dev": "~7.16.0",
-    "react": "^18.3.1 || ~19.0.3 || ~19.1.4 || ^19.2.3",
-    "vite": "^5.1.0 || ^6.2.1 || ^7.0.0 || ^8.0.0"
+    "react": "^18.0.0 || ^19.0.0",
+    "vite": "^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0",
+    "vue": "^3.5.0"
   },
   "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
     "vite": {
       "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "shopify": {
+    "cli": {
+      "disabledCommands": [
+        "hydrogen:build",
+        "hydrogen:check",
+        "hydrogen:codegen",
+        "hydrogen:debug:cpu",
+        "hydrogen:dev",
+        "hydrogen:g",
+        "hydrogen:generate:route",
+        "hydrogen:generate:routes",
+        "hydrogen:preview",
+        "hydrogen:setup",
+        "hydrogen:setup:css",
+        "hydrogen:setup:markets",
+        "hydrogen:setup:vite",
+        "hydrogen:shortcut",
+        "hydrogen:upgrade"
+      ]
     }
   },
   "scripts": {
-    "build": "tsup --clean",
-    "dev": "tsup --watch ./src --watch ../../node_modules/@shopify/hydrogen-react/dist/browser-prod/index.mjs",
+    "build": "tsdown && node scripts/copy-generated-graphql-assets.ts",
+    "dev": "tsdown --watch ./src",
     "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "build-docs": "sh ./docs/build-docs.sh && pnpm run format",
-    "format": "prettier --write \"{src,docs}/**/*\" --ignore-unknown",
-    "preview-docs": "pnpm --dir ../../docs/preview run dev"
+    "libcheck": "node scripts/libcheck-package.ts",
+    "test": "pnpm run build && vitest run",
+    "test:watch": "pnpm run build && vitest",
+    "test:types": "pnpm run build && vitest --typecheck --run",
+    "codegen": "graphql-codegen --config codegen.ts && gql.tada generate-output --tsconfig tsconfig.codegen.json",
+    "postcodegen": "node scripts/postprocess-tada-env.ts && oxfmt src/graphql/generated/*.d.ts src/graphql/generated/*.json"
   }
 }

package/skills/hydrogen-analytics/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: hydrogen-analytics
+description: >
+  Guide for adding or reviewing Hydrogen storefront analytics. Use when working
+  with ShopifyScripts analytics, AnalyticsEvent, consent mode, page/product/
+  collection/search/cart view events, cart update tracking, custom analytics
+  destinations, or framework route-change analytics wiring.
+---
+
+# Storefront Analytics
+
+Hydrogen's analytics bus owns the event API, event normalization, and consent-gated destination replay. ShopifyScripts owns Shopify consent setup, analytics CDN loading, and deprecated cookie compatibility. App code owns when to publish route/view events and when to call cart delta tracking.
+
+## Framework References
+
+Before wiring route events, check whether this skill has a reference file for the app's framework in `references/`. If one exists, read it and use that framework's route-change and lifecycle primitives. If there is no matching reference, keep the core singleton below and adapt page-view, product-view, collection-view, search-view, and cart tracking to the app's own route lifecycle.
+
+Prerequisite: analytics depends on the same-origin SFAPI proxy (see `hydrogen-request-handlers`) so the browser can observe tracking values from Storefront API responses. Without it, analytics falls back to deprecated JavaScript-visible cookies and session continuity into checkout breaks — treat it as incomplete until the proxy is wired. Key consent setup: Shopify Customer Privacy controls destination delivery in production. Raw subscribers can observe events before consent; destinations receive only consent-allowed replay. Do not bypass Customer Privacy consent gating in production.
+
+## Core Pattern
+
+Render Shopify runtime scripts once from the app root/document head with the same resolved market used by Storefront API requests. Use `ShopifyScripts` from your framework binding if it exports one, or `getShopifyScriptTags()` / `renderShopifyScriptTags()` from core in other framework heads. Pass the `shop` object matching the `ShopifyScriptsShop` type, and `i18n` matching the `ShopifyScriptsI18n` type and serialize them into ShopifyScripts. — declare them as constants with type annotations to keep errors located close to the source of writing. The analytics bus is created by default; pass `analytics` only for optional bus configuration such as `customData`. Do not pass market `country` or `language` through analytics consent config.
+
+Read one browser-lazy singleton from the Shopify global created by `ShopifyScripts`:
+
+```ts
+import {
+  AnalyticsEvent,
+  type StorefrontAnalytics,
+  trackCartAnalytics,
+} from "@shopify/hydrogen";
+
+export { AnalyticsEvent };
+
+let bus: StorefrontAnalytics | null = null;
+
+export function getAnalytics(): StorefrontAnalytics | null {
+  if (typeof window === "undefined") return null;
+  bus ??= window.Shopify?.analytics ?? null;
+  return bus;
+}
+
+export { trackCartAnalytics };
+```
+
+Read `shop` and `i18n` values on the server and pass them to `ShopifyScripts`. Do not read env APIs in browser modules.
+
+In the ShopifyScripts `analytics` config, `channel` is optional and defaults to `"hydrogen"`. The `"hydrogen"` channel is the one that requires `storefrontId` — it is pulled from the ShopifyScripts `shop` config into analytics payloads. Headless storefronts pass `channel: "headless"` in the ShopifyScripts `analytics` config; the analytics payload then omits `storefrontId`, but `shop.storefrontId` itself is still required (pass `"0"` when the app has no storefront ID).
+
+## Publish Events
+
+Publish these from route/page boundaries:
+
+- `PAGE_VIEWED` on each page transition.
+- `PRODUCT_VIEWED` when product data is resolved on a product page.
+- `COLLECTION_VIEWED` when collection data is resolved.
+- `SEARCH_VIEWED` when a non-empty search term has results metadata.
+- `CART_VIEWED` when the full cart page or cart drawer is viewed.
+- Wire cart tracking once per cart store lifecycle with `trackCartAnalytics(cartStore)` — React apps use the `useCartAnalytics()` hook from `@shopify/hydrogen/react` and Vue apps use the `useCartAnalytics()` composable from `@shopify/hydrogen/vue`; both call it with the provider's cart store and clean up on unmount. The tracker subscribes to the cart store itself, skips pending/revalidating/note updates, publishes cart delta events on confirmed cart changes, and returns an unsubscribe function. Call it from a client-only effect (`useEffect` / `onMounted`), never at cart-store creation time — it throws when `window.Shopify.analytics` is missing (SSR). Do not manually publish cart delta events.
+
+The bus defaults `shop` from the top-level `shop` config passed to ShopifyScripts; pass `shop` in an event payload only when intentionally overriding that configured value. Shopify analytics reads language and currency from `window.Shopify.locale` and `window.Shopify.currency.active`.
+
+Required product analytics fields include Shopify Product GID, ProductVariant GID when available, title, price, vendor, quantity, and variant title.
+
+## Rules
+
+- Let Shopify Customer Privacy control destination delivery in production.
+- Initialize one single bus per page lifetime through ShopifyScripts.
+- Raw subscribers can observe events before consent; destinations receive only consent-allowed replay.
+- Render ShopifyScripts before route components publish events.
+- Do not dispatch server-side analytics through this browser bus.
+- Keep ShopifyScripts i18n aligned with the resolved market when the storefront uses markets.
+
+## Verify
+
+- Page view fires on initial load and client navigations.
+- Product, collection, search, and cart view events fire once per relevant route data change.
+- Confirmed cart data changes flow through `trackCartAnalytics(cartStore)` (React/Vue bindings: `useCartAnalytics()`), and the cart query includes `updatedAt`.
+- Consent-denied visitors do not deliver destination events.
+- No browser module reads private or server-only env variables.