@shopify/hydrogen 2026.10.0-preview.2 → 2026.10.0-preview.4

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

@@ -1,5 +1,5 @@
 import { ShopifyRoutesOptions, ShopifyScriptTagsOptions, ShopifyScriptsAnalyticsConfig, ShopifyScriptsI18n, ShopifyScriptsShop } from "../core/shopify-scripts/types.mjs";
-import { ConsentConfig } from "../core/analytics/types.mjs";
+import { ConsentConfig, ConsentSetup } from "../core/analytics/types.mjs";
 import * as _$vue from "vue";
 
 //#region src/vue/shopify-scripts.d.ts
@@ -26,7 +26,16 @@ declare const ShopifyScripts: _$vue.DefineComponent<_$vue.ExtractPropTypes<{
     default: undefined;
   };
   consent: {
-    type: (new (...args: any[]) => ConsentConfig) | (() => ConsentConfig | undefined);
+    type: (new (...args: any[]) => {
+      mode?: "no-banner";
+      setup?: never;
+    } | {
+      mode: "default-banner";
+      setup?: never;
+    } | {
+      mode: "custom-banner";
+      setup: ConsentSetup;
+    }) | (() => ConsentConfig | undefined);
     default: undefined;
   };
   analytics: {
@@ -49,6 +58,10 @@ declare const ShopifyScripts: _$vue.DefineComponent<_$vue.ExtractPropTypes<{
     type: () => boolean | undefined;
     default: undefined;
   };
+  account: {
+    type: () => boolean | undefined;
+    default: undefined;
+  };
   shopifyAnalytics: {
     type: BooleanConstructor;
     default: undefined;
@@ -77,7 +90,16 @@ declare const ShopifyScripts: _$vue.DefineComponent<_$vue.ExtractPropTypes<{
     default: undefined;
   };
   consent: {
-    type: (new (...args: any[]) => ConsentConfig) | (() => ConsentConfig | undefined);
+    type: (new (...args: any[]) => {
+      mode?: "no-banner";
+      setup?: never;
+    } | {
+      mode: "default-banner";
+      setup?: never;
+    } | {
+      mode: "custom-banner";
+      setup: ConsentSetup;
+    }) | (() => ConsentConfig | undefined);
     default: undefined;
   };
   analytics: {
@@ -100,6 +122,10 @@ declare const ShopifyScripts: _$vue.DefineComponent<_$vue.ExtractPropTypes<{
     type: () => boolean | undefined;
     default: undefined;
   };
+  account: {
+    type: () => boolean | undefined;
+    default: undefined;
+  };
   shopifyAnalytics: {
     type: BooleanConstructor;
     default: undefined;
@@ -109,6 +135,8 @@ declare const ShopifyScripts: _$vue.DefineComponent<_$vue.ExtractPropTypes<{
     required: true;
   };
 }>> & Readonly<{}>, {
+  nonce: string;
+  account: boolean | undefined;
   analytics: ShopifyScriptsAnalyticsConfig | undefined;
   consent: ConsentConfig | undefined;
   debug: {
@@ -116,7 +144,6 @@ declare const ShopifyScripts: _$vue.DefineComponent<_$vue.ExtractPropTypes<{
   } | undefined;
   i18n: ShopifyScriptsI18n;
   inbox: boolean | undefined;
-  nonce: string;
   shopifyAnalytics: boolean;
   navigate: any;
   routes: any;

package/dist/vue/shopify-scripts.mjs

@@ -11,6 +11,7 @@ const consentProp = Object;
 const analyticsProp = Object;
 const debugProp = Object;
 const inboxProp = Boolean;
+const accountProp = Boolean;
 const ShopifyScripts = defineComponent({
 	name: "ShopifyScripts",
 	props: {
@@ -50,6 +51,10 @@ const ShopifyScripts = defineComponent({
 			type: inboxProp,
 			default: void 0
 		},
+		account: {
+			type: accountProp,
+			default: void 0
+		},
 		shopifyAnalytics: {
 			type: Boolean,
 			default: void 0
@@ -62,6 +67,7 @@ const ShopifyScripts = defineComponent({
 	setup(props) {
 		onMounted(() => {
 			initializeShopifyScripts({
+				consent: props.consent,
 				navigate: props.navigate,
 				routes: props.routes,
 				webMcp: props.webMcp !== false

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

@@ -1 +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"}
+{"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;\nconst accountProp: PropType<ShopifyScriptTagsOptions[\"account\"]> = 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    account: {\n      type: accountProp,\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        consent: props.consent,\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;AAC/D,MAAM,cAA6D;AAEnE,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,SAAS;GACP,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,SAAS,MAAM;IACf,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,6 +1,6 @@
 {
   "name": "@shopify/hydrogen",
-  "version": "2026.10.0-preview.2",
+  "version": "2026.10.0-preview.4",
   "description": "Framework-agnostic Shopify storefront SDK and agent skills.",
   "license": "MIT",
   "author": "Shopify",
@@ -16,7 +16,8 @@
     "README.md",
     "bin",
     "dist",
-    "skills"
+    "skills",
+    "ts-plugin"
   ],
   "type": "module",
   "sideEffects": false,
@@ -82,6 +83,7 @@
     "access": "public"
   },
   "dependencies": {
+    "cross-spawn": "7.0.6",
     "gql.tada": "1.9.2"
   },
   "devDependencies": {
@@ -89,6 +91,7 @@
     "@graphql-codegen/introspection": "^6.0.0",
     "@graphql-codegen/typescript": "^6.0.0",
     "@testing-library/react": "^16.3.2",
+    "@types/cross-spawn": "6.0.6",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "@vue/test-utils": "^2.4.0",

package/skills/hydrogen-analytics/SKILL.md

@@ -9,17 +9,17 @@ description: >
 
 # 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.
+Hydrogen's analytics bus owns the event API, event normalization, and consent-gated destination replay. ShopifyScripts owns Shopify consent setup and analytics CDN loading. 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.
+Prerequisite: analytics depends on the same-origin SFAPI proxy (see `hydrogen-request-handlers`) so the browser can observe tracking values from Storefront API responses. The proxy establishes the backend session cookies needed for analytics and checkout continuity; treat analytics as incomplete until it is wired. Key consent setup: Shopify Customer Privacy controls destination delivery in production. Register event consumers with `addDestination()`; live delivery and replay require analytics consent. 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.
+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`. `customData` isn't added to events you publish; destinations read it via `getConfig().customData`. Do not pass market `country` or `language` through analytics consent config.
 
 Read one browser-lazy singleton from the Shopify global created by `ShopifyScripts`:
 
@@ -66,7 +66,8 @@ Required product analytics fields include Shopify Product GID, ProductVariant GI
 
 - 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.
+- Register event consumers with `addDestination()` and use the `subscribe` function provided to its setup callback.
+- For third-party banners, use `consent: {mode: "custom-banner", setup}` and read [Custom consent providers](references/custom-consent.md) for readiness, synchronization, and framework integration.
 - 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.
@@ -75,6 +76,6 @@ Required product analytics fields include Shopify Product GID, ProductVariant GI
 
 - 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`.
+- Confirmed cart data changes flow through `trackCartAnalytics(cartStore)` (React/Vue bindings: `useCartAnalytics()`).
 - Consent-denied visitors do not deliver destination events.
 - No browser module reads private or server-only env variables.

package/skills/hydrogen-analytics/references/custom-consent.md

@@ -0,0 +1,52 @@
+# Custom Consent Providers
+
+Read this when connecting a third-party banner or app-owned consent UI through `consent: {mode: "custom-banner", setup}`. Other consent modes do not accept `setup`.
+
+## Setup Contract
+
+Hydrogen calls `setup()` without arguments in the browser after Shopify's Customer Privacy API loads. Use `window.Shopify.customerPrivacy` directly. Destination events stay buffered from the inline bootstrap through hydration until the setup promise resolves, even if Shopify's regional defaults allow tracking.
+
+The promise is the readiness signal. Subscribe to provider changes before reading saved consent, wait for a resolved provider choice or shopper interaction, and await `customerPrivacy.setTrackingConsent(choice)` before resolving setup. Registering a listener or showing a banner alone does not complete setup.
+
+Map the provider's choice explicitly to all four boolean purposes in `ConsentPreferences`: `analytics`, `marketing`, `preferences`, and `sale_of_data`. Keep unknown provider state pending rather than submitting it as a denial. The provider owns its regional policy.
+
+Once setup resolves, Hydrogen checks Shopify consent and replays allowed events or clears the buffer when denied. Later updates use the existing CTA consent events. This gate covers Hydrogen analytics destinations; independently loaded trackers need their own consent handling.
+
+## Integration Pattern
+
+The provider methods, category mapping, and error handler below are app-owned adapters, not Hydrogen or provider SDK APIs. `whenConsentResolved()` waits for saved consent or interaction; `getResolvedConsent()` reads the latest choice. The subscription continues synchronizing later acceptance, rejection, and preference changes.
+
+```tsx
+<ShopifyScripts
+  shop={shop}
+  consent={{
+    mode: "custom-banner",
+    async setup() {
+      const customerPrivacy = window.Shopify!.customerPrivacy!;
+      const sync = async (choice) => {
+        await customerPrivacy.setTrackingConsent(mapProviderConsent(choice));
+      };
+      const unsubscribe = provider.subscribe((choice) => {
+        void sync(choice).catch(reportConsentError);
+      });
+      try {
+        await provider.whenConsentResolved();
+        await sync(provider.getResolvedConsent());
+      } catch (error) {
+        unsubscribe();
+        throw error;
+      }
+    },
+  }}
+/>
+```
+
+Keep the callback in client code and access browser-only provider globals inside setup. In Next.js App Router, define setup in an app-owned client component that renders `ShopifyScripts`; pass serializable `shop` and `i18n` data from the server. A function prop cannot cross the server-to-client boundary. Hydrogen serializes only the consent mode into HTML and does not expose setup to analytics destinations.
+
+For frameworks using core script helpers, pass the same consent configuration to `getShopifyScriptTags()` / `renderShopifyScriptTags()` and `initializeShopifyScripts({consent})` during browser startup.
+
+## Lifecycle and Failures
+
+Setup runs once per analytics bus and resolves without a return value. The first callback remains active across component unmounts, remounts, and React Strict Mode. Hydrogen owns the bus for the page's lifetime; component unmounts do not tear down the consent integration.
+
+If setup fails, Hydrogen logs the failure and leaves destination delivery blocked for that bus. Hydrogen does not automatically rerun setup. If the provider needs retries, perform them inside setup while its promise remains pending. Handle consent write failures in the app, including later updates, and release any subscriptions created by setup if it fails.

package/skills/hydrogen-analytics/references/react.md

@@ -147,7 +147,7 @@ if (term) {
 
 ## Cart Updates
 
-Use the `useCartAnalytics()` hook from the React binding — rendered inside `CartProvider`, it calls `trackCartAnalytics(store)` in an effect and cleans up on unmount. Outside the binding, call `trackCartAnalytics(store)` once with the cart store from a client-only effect (`useEffect`) — never at cart-store creation time, since it throws when `window.Shopify.analytics` is missing during SSR. It subscribes itself, skips pending/revalidating/note updates, derives cart delta events from confirmed cart changes, returns an unsubscribe function, and uses the global analytics bus created by ShopifyScripts. Do not manually publish `product_added_to_cart`.
+Use the `useCartAnalytics()` hook from the React binding — rendered inside the `CartProvider` returned by `createCartComponents()` (the React entry exports no standalone `CartProvider`), it calls `trackCartAnalytics(store)` in an effect and cleans up on unmount. Outside the binding, call `trackCartAnalytics(store)` once with the cart store from a client-only effect (`useEffect`) — never at cart-store creation time, since it throws when `window.Shopify.analytics` is missing during SSR. It subscribes itself, skips pending/revalidating/note updates, derives cart delta events from confirmed cart changes, returns an unsubscribe function, and uses the global analytics bus created by ShopifyScripts. Do not manually publish `product_added_to_cart`.
 
 Publish `CART_VIEWED` when the cart page or drawer is viewed. The cart payload is `AnalyticsCart | null`: when a compatible cart is available, include `id`, `updatedAt`, and connection-shaped `lines`; otherwise pass `cart: null` instead of a partial cart.
 

package/skills/hydrogen-cart-metafields/SKILL.md

@@ -0,0 +1,133 @@
+---
+name: hydrogen-cart-metafields
+description: >
+  Behavioral guide for reading and writing cart metafields with @shopify/hydrogen.
+  Use when adding, modifying, or reviewing cart metafield reads or writes, an
+  app-owned cart metafield route, cart-to-order metafield copying, or custom cart
+  data such as delivery instructions or gift preferences. Framework agnostic.
+---
+
+# Cart Metafields
+
+Cart metafields store custom data on the cart (for example delivery instructions or a gift preference). They are **server-only**: the Storefront cart ajax API (Standard Actions) does not support them, so they never flow through Hydrogen's optimistic cart store the way line, discount, note, and attribute mutations do.
+
+Because of that, **do not add metafields to the core cart action/intent model.** Compose three pieces Hydrogen already provides:
+
+1. **Read** — a custom `CartFragment` on `createCartServerHandlers`, so metafields appear in cart state.
+2. **Write** — an app-owned route (`createShopifyRouteHandler`) calling `cartMetafieldsSet` / `cartMetafieldDelete`.
+3. **Re-sync** — `useCartActions().refresh()` after a successful write.
+
+See `hydrogen-cart-ui` for cart state, `refresh()`, and form patterns, and `hydrogen-request-handlers` for registering the custom route.
+
+## Golden rule: decouple the write from the read
+
+The mutation route returns **only the mutation's `userErrors`** — it must never refetch and return the cart. Re-syncing is a separate `refresh()` call.
+
+```
+POST /api/cart/metafields  → cartMetafieldsSet → { userErrors }   (truthful: success is success)
+then, on success:
+refresh()                  → re-reads the cart via CartFragment
+```
+
+If the write and a refetch were coupled in one request, a blip on the read would mask a successful save as a "network error." Decoupled, a failed re-sync surfaces as `state.errors.network` (a soft refresh error) and preserves the saved cart — it is never reported as a failed save.
+
+## Reading metafields
+
+Select the metafields you need in a `CartFragment` named `CartFragment`:
+
+```ts
+const CART_FRAGMENT = gql(`
+  fragment CartFragment on Cart {
+    metafields(identifiers: [{ namespace: "custom", key: "delivery_instructions" }]) {
+      namespace
+      key
+      type
+      value
+    }
+  }
+`);
+
+export const cartHandlers = createCartServerHandlers({ fragment: CART_FRAGMENT });
+```
+
+They then appear in cart state. Read a **primitive** in the selector so referential equality can skip re-renders:
+
+```ts
+const instructions = useCart(
+  (state) =>
+    state.data.metafields?.find(
+      (m) => m?.namespace === "custom" && m.key === "delivery_instructions",
+    )?.value ?? "",
+);
+```
+
+## Writing metafields (app-owned route)
+
+Register a custom `POST` route with `createShopifyRouteHandler` in `handleShopifyRoutes`. Do **not** extend `/api/cart` or open up its intents.
+
+```ts
+async function handleCartMetafieldsPost({ request, storefrontClient }) {
+  const body = parseRequest(await request.json()); // validate at the boundary
+  const cartId = getCartId(request); // read the owner from the cookie, never the client body
+
+  // Mutate an existing cart only; never create one here. Two concurrent empty-cart
+  // writes would each call cartCreate and race — the last Set-Cookie wins,
+  // orphaning one cart and dropping its write.
+  if (!cartId) {
+    return { type: "error", error: { code: "missing_cart", message: "No cart exists." } };
+  }
+
+  if (body.intent === "delete") {
+    const result = await storefrontClient.graphql(CART_METAFIELD_DELETE_MUTATION, {
+      variables: { input: { ownerId: cartId, key: body.key } },
+    });
+    return { type: "json", data: { userErrors: result.data?.cartMetafieldDelete?.userErrors ?? [] } };
+  }
+
+  const result = await storefrontClient.graphql(CART_METAFIELDS_SET_MUTATION, {
+    variables: { metafields: body.metafields.map((m) => ({ ...m, ownerId: cartId })) },
+  });
+  return { type: "json", data: { userErrors: result.data?.cartMetafieldsSet?.userErrors ?? [] } };
+}
+```
+
+- **Existing cart** → `cartMetafieldsSet` with `ownerId` = the cart id from `getCartId(request)`.
+- **No cart** → reject with a `missing_cart` error. Do **not** call `cartCreate` here: two concurrent empty-cart writes would each create a cart and race on the cookie, orphaning one and dropping its write. Require callers to add a line first.
+- **Delete** → a single key via `cartMetafieldDelete`. The Storefront API deletes one metafield per call, so keep the contract single-key.
+
+## Re-syncing the store
+
+On success, call `refresh()`:
+
+```ts
+const { refresh } = useCartActions();
+// after the POST resolves ok:
+refresh();
+```
+
+`refresh()` reconciles the `CartFragment` fields for the cart after a write. Never call `refresh()` after ordinary Hydrogen cart forms — their Standard Actions events already synchronize the store.
+
+## Copying to the order
+
+To copy a cart metafield onto the order at checkout, the store must define the metafield with the cart-to-order copyable capability:
+https://shopify.dev/docs/apps/build/metafields/use-metafield-capabilities#cart-to-order-copyable
+Without the definition the cart write still succeeds, but nothing is copied to the order.
+
+## Rules
+
+- **Server-only.** Never route metafields through Standard Actions or the optimistic cart store.
+- **No core intents.** Do not add `metafields-set`/`metafield-delete` to the cart action model; use an app-owned route.
+- **Mutation returns `userErrors` only.** Never refetch and return the cart in the same request.
+- **Re-sync with `refresh()`** after success. Treat a refresh failure as a soft error (`errors.network`), not a failed save.
+- **Inject `ownerId` server-side** from the cart cookie (`getCartId`). Never trust a client-supplied `ownerId`.
+- **Require an existing cart.** Reject writes when no cart cookie is present; never call `cartCreate` in this route — it races on the cookie.
+- **Validate the request body** at the route boundary before calling the Storefront API.
+- **Delete is single-key**, matching `cartMetafieldDelete`.
+
+## Putting it together
+
+Three pieces in your app, each owning one concern:
+
+1. **Cart handlers** — add the `CartFragment` (see *Reading metafields*) so the values load into cart state.
+2. **Metafields route** — an app-owned `POST` handler (see *Writing metafields*) that runs `cartMetafieldsSet` / `cartMetafieldDelete` and returns only `userErrors`.
+3. **Your component** — read with `useCart`, write via the route, then call `refresh()` on success (see *Re-syncing the store*).

package/skills/hydrogen-cart-ui/SKILL.md

@@ -41,7 +41,7 @@ On mutation:
 
 When overlapping mutations make response snapshots ambiguous, the store sets `state.revalidating` to `true`. It starts one authoritative refresh after those mutations settle and clears the flag when the refresh completes or fails. Until then, server-derived values such as costs remain at their last trustworthy value. A refresh failure preserves the locally reconciled cart and appears in `errors.network`.
 
-App-owned cart mutations outside Standard Actions do not emit the events the store normally observes. After such a mutation succeeds, call `CartStore.refresh()` directly or use the framework binding's `useCartActions().refresh()`. The refresh waits for active optimistic work, reconciles custom fragment fields from the configured cart endpoint, and loads the cart when none exists yet (e.g. one just created server-side). Do not call it after ordinary Hydrogen cart forms; their Standard Actions events already synchronize the store.
+App-owned cart mutations outside Standard Actions do not emit the events the store normally observes. After such a mutation succeeds, call `CartStore.refresh()` directly or use the framework binding's `useCartActions().refresh()`. The refresh waits for active optimistic work, reconciles custom fragment fields from the configured cart endpoint, and loads the cart when none exists yet (e.g. one just created server-side). Do not call it after ordinary Hydrogen cart forms; their Standard Actions events already synchronize the store. For cart metafields specifically, see the `hydrogen-cart-metafields` skill.
 
 The store supersedes keyed mutations for the same line, discount batch, note, or complete attribute list. Relative additions remain independent so every submitted quantity reaches the server; their projections are reconciled together without disabling controls.
 
@@ -141,6 +141,7 @@ Errors survive unrelated cart work and clear when a new mutation begins for the
 
 ### Form structure
 
+- **Optionally render visible line-item attributes.** Each cart line may carry `attributes` — an array of `{ key, value }` pairs set during add-to-cart. If your storefront uses line-item attributes (e.g. engraving text, gift messages, custom options), render them below the variant subtitle as secondary text. Filter out attributes whose key starts with `_` (these are internal/private, set by apps or Shopify systems). The same variant with different attributes creates separate cart lines — the optimistic layer uses attributes in line identity matching.
 - **Each line item is its own form.** This gives each line its own identity input and its own submit buttons. A single form containing multiple lines creates ambiguity about which line an action targets.
 - **Each line item form must preserve the progressive-enhancement shape.** The rendered structure will vary by framework and design system, but every line item quantity form needs the same Hydrogen contract: `register("set")`, `register("lineId", { value: line.id })`, and a real editable quantity input using `register("quantity", { value: line.quantity, interactive: true })`. Increase, decrease, and remove buttons are additional submit controls, not replacements for the set intent or the quantity input.
 - **The `set` control is a hidden submit button, not a hidden input.** `register("set")` already returns `{ type: "submit", hidden: true }`; render it on a `<button>`. Do not swap it for `<input type="hidden">` — that removes the submit button, so pressing Enter in the quantity input no longer submits the set action.

package/skills/hydrogen-customer-account/SKILL.md

@@ -71,7 +71,7 @@ The Customer Account handlers own:
 - `GET /account/refresh`
 - `POST /account/logout`
 
-Do not reimplement login, authorize, refresh, or logout unless the app needs custom behavior that preserves the same safeguards: sanitized `return_to`, same-origin logout POST checks, `cache-control: no-store`, committed session cookies on the returned response, and request-context response headers.
+Do not reimplement login, authorize, refresh, or logout unless the app needs custom behavior that preserves the same safeguards: `return_to` limited to the same origin, same-origin logout POST checks, `cache-control: no-store`, committed session cookies on the returned response, and request-context response headers.
 
 ## Server Rendering
 
@@ -81,7 +81,7 @@ Server-rendered account UI must keep session reads and token refresh separate:
 - Use `customerSession.getAccessToken()` before Customer Account GraphQL calls. It returns only a currently usable access token.
 - If `isLoggedIn()` is true but `getAccessToken()` returns `undefined`, redirect once to `/account/refresh?return_to=...` from a dynamic server route, then retry the account page after the refresh route commits cookies.
 - If `isLoggedIn()` is false, show login UI or redirect to `/account/login` instead of sending the user to `/account/refresh`.
-- Include a one-shot refresh guard in `return_to`; if the refreshed page still has no usable access token, fall back to login or an account error state.
+- Include a one-shot refresh guard in the `return_to` path, such as `/account?refreshed=1`; if the refreshed page still has no usable access token, fall back to login or an account error state.
 - Server Components and layouts should only receive `ReadonlyCustomerSessionManager`, so they cannot call `getOrRefreshAccessToken()`.
 
 Wrap header/account-link UI in the framework's streaming primitive when possible so the shell can render before session state resolves.
@@ -104,4 +104,4 @@ The same `@shopify/hydrogen/ts-plugin` and `hydrogen gql check` setup from the `
 
 ## Local OAuth
 
-Customer Account OAuth needs a public HTTPS callback origin. For local examples, use a trusted local HTTPS hostname and register the exact `/account/authorize` callback URL in the Customer Account app configuration.
+Customer Account OAuth needs a public HTTPS origin. For local development, follow the `hydrogen-local-https` skill; its Vite plugin provisions a trusted certificate and pushes the callback, JavaScript origin, and logout URLs through Shopify CLI outside CI.

package/skills/hydrogen-local-https/SKILL.md

@@ -30,7 +30,7 @@ import { localHttps } from "@shopify/hydrogen/vite";
 import { defineConfig } from "vite";
 
 const httpsOptions = {
-  enabled: process.env.npm_lifecycle_event === "dev:https" || process.env.VITE_LOCAL_HTTPS === "1",
+  enabled: process.env.npm_lifecycle_event === "dev:https",
 };
 
 export default defineConfig({
@@ -57,7 +57,7 @@ Astro needs its own host and port in addition to the Vite plugin:
 import { LOCAL_HTTPS_DEFAULTS, localHttps } from "@shopify/hydrogen/vite";
 import { defineConfig } from "astro/config";
 
-const enabled = process.env.npm_lifecycle_event === "dev:https" || process.env.VITE_LOCAL_HTTPS === "1";
+const enabled = process.env.npm_lifecycle_event === "dev:https";
 const httpsOptions = { enabled };
 
 export default defineConfig({
@@ -79,7 +79,7 @@ import type { NuxtConfig } from "nuxt/schema";
 type VitePlugin = NonNullable<NonNullable<NuxtConfig["vite"]>["plugins"]>[number];
 
 const httpsOptions = {
-  enabled: process.env.npm_lifecycle_event === "dev:https" || process.env.VITE_LOCAL_HTTPS === "1",
+  enabled: process.env.npm_lifecycle_event === "dev:https",
 };
 const httpsPlugin = localHttps(httpsOptions);
 
@@ -100,23 +100,30 @@ import { defineConfig } from "@solidjs/start/config";
 import { localHttps } from "@shopify/hydrogen/vite";
 
 const httpsOptions = {
-  enabled: process.env.npm_lifecycle_event === "dev:https" || process.env.VITE_LOCAL_HTTPS === "1",
+  enabled: process.env.npm_lifecycle_event === "dev:https",
 };
 const httpsPlugin = localHttps(httpsOptions);
 const devServer = httpsPlugin.api.getDevServerConfig();
 
+// Vinxi reads its bind target from HOST/PORT when the listener starts, after
+// this config has loaded. Setting them here works on every OS; a `HOST=...`
+// prefix in the package script fails on Windows shells.
+if (devServer) {
+  process.env.HOST = devServer.host;
+  process.env.PORT = String(devServer.port);
+}
+
 export default defineConfig({
   server: { https: devServer?.https },
   vite: { plugins: [httpsPlugin] },
 });
 ```
 
-Vinxi also needs its bind target and port on startup:
-
 ```json
 {
   "scripts": {
-    "dev:https": "vinxi dev --host local.tryhydrogen.dev --port 5173"
+    "dev": "vinxi dev",
+    "dev:https": "vinxi dev"
   }
 }
 ```
@@ -131,6 +138,14 @@ next dev --experimental-https --hostname local.tryhydrogen.dev --port 5173
 
 ## Shopify Admin
 
+Outside CI, the `localHttps` Vite plugin uses the installed Shopify CLI to update Customer Account API settings when the server starts. Shopify CLI must include `@shopify/cli-hydrogen` 13.0.4 or later. If the project is not linked to a Hydrogen storefront, Shopify CLI starts the interactive linking flow before it pushes the callback, JavaScript origin, and logout URLs.
+
+The plugin skips Shopify CLI in CI. It also falls back without stopping the development server when Shopify CLI is missing or outdated, linking is cancelled, or the settings cannot be pushed. In these cases, configure the values printed in the terminal manually.
+
+Next.js does not use the Vite plugin, so configure its values manually too.
+
+### Manual Configuration
+
 In the Hydrogen or Headless sales channel, open the storefront's **Customer Account API settings** and configure:
 
 ```text

package/skills/hydrogen-request-handlers/SKILL.md

@@ -4,7 +4,7 @@ description: >
   Guide for wiring Hydrogen request handlers in server frameworks. Use when
   adding, modifying, or reviewing handleShopifyRoutes, handleShopifyRedirects,
   SFAPI proxy routes, cart, predictive search, and Customer Account server handlers,
-  checkout redirects, cart permalinks, AJAX cart proxy routes, /admin redirects, Storefront URL redirects,
+  checkout redirects, cart and UCP buy permalinks, AJAX cart proxy routes, /admin redirects, Storefront URL redirects,
   requestContext response-header propagation, or framework middleware,
   not-found, and catch-all integration.
 ---
@@ -27,7 +27,7 @@ Request
   -> framework 404 page
 ```
 
-`handleShopifyRoutes` owns Hydrogen routes the framework should never see: SFAPI proxy URLs, the generic `/__shopify/*` API proxy, `/checkout`, cart permalinks like `/cart/{variantId}:{quantity}`, AJAX cart URLs like `/cart.js` and `/cart/add.js`, `/api/mcp`, `/graphiql` in development, Liquid-style `?variant=<numeric id>` product URLs, and app-registered handler groups such as `createCartServerHandlers()` or `createCustomerAccountServerHandlers()`.
+`handleShopifyRoutes` owns Hydrogen routes the framework should never see: SFAPI proxy URLs, the generic `/__shopify/*` API proxy, `/checkout`, cart permalinks like `/cart/{variantId}:{quantity}`, UCP buy permalinks like `/buy/{itemId}:{quantity}`, AJAX cart URLs like `/cart.js` and `/cart/add.js`, `/api/mcp`, `/graphiql` in development, Liquid-style `?variant=<numeric id>` product URLs, and app-registered handler groups such as `createCartServerHandlers()` or `createCustomerAccountServerHandlers()`.
 
 ## Variant Id Redirects
 
@@ -44,7 +44,7 @@ const shopifyRoute = handleShopifyRoutes({
 
 Pass `routeTemplates` to `handleShopifyRoutes` so product `?variant=` links can be recognized before framework routing. `pathPrefix` is inferred from `requestContext.i18n.pathPrefix`, so localized product URLs stay in the localized tree.
 
-`handleShopifyRedirects` is a post-routing 404 check for `/admin`, configured standard route redirects, Storefront URL redirects, and same-origin query-param redirects. Do not run it on every request.
+`handleShopifyRedirects` is a post-routing 404 check for `/admin`, configured standard route redirects, Storefront URL redirects, and same-origin `return_to`/`redirect` query params. Do not run it on every request.
 
 ## Standard Route Redirects
 
@@ -73,7 +73,7 @@ const redirect = await handleShopifyRedirects({
 - `handleShopifyRoutes` and `handleShopifyRedirects` apply request-context response headers before returning matched Shopify responses. Return those responses directly without calling `requestContext.applyResponseHeaders()` again.
 - Link and submit to Customer Account routes (`/account/login`, `/account/authorize`, `/account/refresh`, `/account/logout`) with plain HTML `<a>`/`<form>`, never the framework's client-side navigation component (`<Form>`/`<Link>` in React Router, `next/link` in Next.js, `NuxtLink` in Nuxt). The login and logout handlers return raw HTTP redirects to external Shopify URLs, which client-nav cannot process.
 - Apps authoring Customer Account API documents use the same packed Hydrogen TypeScript plugin as Storefront API documents. Add `@shopify/hydrogen/ts-plugin` to `tsconfig.json` `compilerOptions.plugins` and chain `hydrogen gql check` into a package script. Applies to every framework.
-- For custom or framework-routed responses, commit session headers once at the final response boundary, append those headers, then call `requestContext.applyResponseHeaders(response.headers)` so SFAPI cookies, `Server-Timing`, tracking fallback headers, and personalized-response cache safety survive.
+- For custom or framework-routed responses, commit session headers once at the final response boundary, append those headers, then call `requestContext.applyResponseHeaders(response.headers)` so eligible SFAPI cookies and personalized-response cache safety are applied.
 - Wire this in production runtime code, not dev-only hooks. Only GraphiQL is dev-only.
 
 ## Imports
@@ -103,5 +103,5 @@ Run the app in dev and production modes, then check:
 5. `GET /admin` returns a redirect to the shop admin URL.
 6. An unknown path returns the framework 404 when no Shopify redirect exists.
 7. `GET /products/{handle}?variant={numeric id}` returns a 302 to the option-params URL when `routeTemplates` is passed to `handleShopifyRoutes`; `?variant=garbage` falls through to the product page.
-8. Cart, predictive search, Customer Account, and SFAPI responses preserve `Set-Cookie` and `Server-Timing` headers where the framework exposes them.
+8. Cart, Customer Account, and consent responses preserve eligible `Set-Cookie` headers. Consent responses remain private and non-cacheable even when personal state is returned only in the body.
 9. Authenticated Customer Account responses do not preserve public or CDN cache-control headers.

package/skills/hydrogen-request-handlers/references/nuxt.md

@@ -109,15 +109,9 @@ export default defineNitroPlugin((nitroApp) => {
     copyHeader(event.node.res.getHeader("content-type"), (value) => {
       headers.set("content-type", value);
     });
-    copyHeader(event.node.res.getHeader("server-timing"), (value) => {
-      headers.append("server-timing", value);
-    });
 
     requestContext.applyResponseHeaders(headers);
 
-    const serverTiming = headers.get("server-timing");
-    if (serverTiming) event.node.res.setHeader("server-timing", serverTiming);
-
     const setCookies = headers.getSetCookie();
     if (setCookies.length > 0) {
       event.node.res.setHeader("set-cookie", [