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

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

@@ -22,11 +22,11 @@
 
 **Prerequisites:**
 
-- A storefront built on `@shopify/hydrogen` with the request interceptors already wired (`handleShopifyRoutes` and `handleShopifyRedirects`). The analytics bus depends on the SFAPI proxy so the browser can observe same-origin Storefront API responses for session cookies. Without the proxy, analytics falls back to deprecated JavaScript-visible cookies and should be treated as incomplete. If you have not installed the interceptors yet, install them first with the local `hydrogen-request-handlers` skill.
+- A storefront built on `@shopify/hydrogen` with the request interceptors already wired (`handleShopifyRoutes` and `handleShopifyRedirects`). The analytics bus depends on the SFAPI proxy so the browser can observe same-origin Storefront API responses for session cookies. Without the proxy, the backend session cookies cannot be established and analytics should be treated as incomplete. If you have not installed the interceptors yet, install them first with the local `hydrogen-request-handlers` skill.
 - Shopify runtime scripts rendered from the root/document head. Use `ShopifyScripts` from your framework binding if it exports one, or `getShopifyScriptTags()` / `renderShopifyScriptTags()` from core in other framework heads. Pass `{country, language, currency?}` as `i18n`; pass `{shopId: env.SHOP_ID, storefrontId: env.PUBLIC_STOREFRONT_ID ?? "0", myshopifyDomain: env.PUBLIC_STORE_DOMAIN}` as `shop`. Resolve both on the server, declare them as consts annotated with the `ShopifyScriptsShop` / `ShopifyScriptsI18n` types from `@shopify/hydrogen` (so wrong or missing fields fail typecheck where they are built), and serialize them into ShopifyScripts. ShopifyScripts creates `window.Shopify.analytics` by default and exposes the permanent domain as `window.Shopify.shop`. Analytics consent config does not accept `country` or `language`.
 - A client-side lifecycle hook in your framework (route-change effect, navigation event, `<script>` tag, etc.) so view events can fire on the right URL transitions.
 
-`ShopifyScripts` creates the zero-dependency analytics bus, sets it on `window.Shopify.analytics`, and owns Shopify consent setup, analytics CDN loading, and deprecated-cookie compatibility. Framework adapters stay thin: they translate framework lifecycle events into bus calls and wire cart delta tracking with `trackCartAnalytics()`.
+`ShopifyScripts` creates the zero-dependency analytics bus, sets it on `window.Shopify.analytics`, and owns Shopify consent setup and analytics CDN loading. Framework adapters stay thin: they translate framework lifecycle events into bus calls and wire cart delta tracking with `trackCartAnalytics()`.
 
 ## What you're installing, and what it does on its own
 
@@ -36,8 +36,7 @@ Your app code
   ▼
 window.Shopify.analytics
   │
-  ├── publish / subscribe / addDestination / destroy  (app-facing)
-  ├── raw live subscribers
+  ├── publish / addDestination / getConfig  (app-facing)
   └── consent-gated destinations with replay
       │
       └── Customer Privacy gates destination delivery and replay
@@ -46,8 +45,7 @@ ShopifyScripts
   │
   ├── loads Shopify Customer Privacy script (consent + region gating)
   ├── loads Privacy Banner script in default-banner mode
-  ├── loads Shopify analytics destination by default
-  └── writes deprecated _shopify_y / _shopify_s cookies
+  └── loads Shopify analytics destination by default
 ```
 
 The bus is **browser-only effective** and is created by ShopifyScripts in the browser. There is no server-side dispatch.
@@ -93,7 +91,7 @@ const consent: ConsentConfig = {
 };
 
 const analytics: NonNullable<ShopifyScriptTagsOptions["analytics"]> = {
-  customData: { theme: "v2" },             // optional, attached to bus-generated payloads
+  customData: { theme: "v2" },             // optional
 };
 ```
 
@@ -115,19 +113,19 @@ Pass the app's resolved `country` and `language` market values. Optional `curren
 
 ### `analytics`
 
-The analytics bus is enabled by default. Pass `analytics` only when you need optional bus configuration such as `customData`, which is attached to bus-generated payloads. Shopify analytics reads currency from `window.Shopify.currency.active`, which is seeded by `i18n.currency` and updated from cart currency when available.
+The analytics bus is enabled by default. Pass `analytics` only when you need optional bus configuration such as `customData`. Shopify analytics reads currency from `window.Shopify.currency.active`, which is seeded by `i18n.currency` and updated from cart currency when available.
 
 ### `consent`
 
 This is where the location/region nuance lives. Shopify's hosted Customer Privacy API decides per-visitor whether tracking requires consent based on the visitor's geography:
 
-- **Visitors in jurisdictions with consent requirements** (EU/EEA/UK GDPR, parts of Canada, California CCPA, etc.) — analytics must wait for consent. Use `mode: "default-banner"` for Shopify's hosted privacy banner, or `mode: "custom-banner"` if your app renders its own banner and calls `window.Shopify.customerPrivacy.setTrackingConsent()`.
-- **Visitors in jurisdictions without consent requirements** — the Customer Privacy SDK auto-allows tracking and the banner does not render. The bus dispatches normally.
+- **Visitors in jurisdictions with consent requirements** (EU/EEA/UK GDPR, parts of Canada, California CCPA, etc.) — analytics must wait for consent. Use `mode: "default-banner"` for Shopify's hosted privacy banner, or `mode: "custom-banner"` with a `setup` callback that connects the app's consent provider.
+- **Visitors in jurisdictions without consent requirements** — the Customer Privacy SDK may allow tracking without showing Shopify's banner. Custom-banner integrations still wait for the provider's resolved consent; the provider owns its regional policy.
 
 `mode` controls how consent is collected:
 
 - `"default-banner"` loads Shopify's hosted privacy banner and waits when the Customer Privacy API says banner interaction is required.
-- `"custom-banner"` loads only the Customer Privacy API and treats the initial consent event as actionable. Your banner must call `setTrackingConsent()` when the shopper accepts or declines.
+- `"custom-banner"` loads only the Customer Privacy API and waits for the required asynchronous `setup` callback to resolve before checking consent. Read [Custom consent providers](../../hydrogen-analytics/references/custom-consent.md) when integrating a third-party banner.
 - `"no-banner"` loads only the Customer Privacy API and releases analytics after consent setup. Use this only when consent is already allowed or managed outside this storefront.
 
 ### Consent Gating
@@ -138,9 +136,9 @@ Default:
 () => window.Shopify?.customerPrivacy?.analyticsProcessingAllowed() ?? false
 ```
 
-This is conservative by design: if the Customer Privacy script is blocked, hasn't loaded, or is unavailable, **destination delivery is blocked**. Raw `subscribe()` listeners still see live events, but analytics destinations do not receive events until `analyticsProcessingAllowed()` returns true.
+If the Customer Privacy script is blocked, hasn't loaded, or is unavailable, **destination delivery is blocked**. Destinations receive events only after consent is loaded and analytics processing is allowed.
 
-Events published before consent is ready are buffered for destinations and replayed only if analytics consent is granted. Destinations only receive supported event names they subscribe to. If the visitor explicitly denies analytics consent, the replay buffer is cleared.
+The bus retains up to 500 events for destination replay, including events published while analytics consent was already allowed. New destinations receive that retained history only when analytics consent allows delivery, and only for supported event names they subscribe to. If the visitor explicitly denies analytics consent, the replay buffer is cleared.
 
 Custom event names such as `custom_*` are temporarily unsupported. Publishing or subscribing to an unsupported event name logs a small warning and the event is ignored.
 
@@ -179,7 +177,7 @@ Non-optional constraints:
 - **One instance per page.** The singleton means every route, every effect, every script tag shares the same bus. Multiple instances on the same page overwrite `window.Shopify.customerPrivacy.config`; the latest initialized config wins. Multi-store on one page is not supported.
 - **Lazy.** Reading the bus happens on first `getAnalytics()` call. ShopifyScripts owns bus construction.
 
-App code can add explicit destinations for development logging or third-party integrations, then publish from each route:
+Register destinations once during browser app initialization, after ShopifyScripts has created the bus. Keep destination registration outside route component mount/unmount cycles; route components publish events through the shared bus:
 
 ```ts
 const cleanup = analytics.addDestination({
@@ -205,7 +203,7 @@ const cleanup = analytics.addDestination({
 });
 ```
 
-Destinations are consent-gated and receive replayed buffered events once tracking is allowed.
+Destinations are consent-gated and receive retained history once tracking is allowed. The returned cleanup function removes the destination when the app intentionally stops that integration.
 
 ---
 
@@ -555,7 +553,7 @@ type AnalyticsCart = {
 };
 ```
 
-Manually published `AnalyticsCart` payloads (like `CART_VIEWED`) accept both `lines.nodes` and `lines.edges` (GraphQL connection) shapes at the type level; the bus forwards them unchanged, so subscribers that read lines should flatten them with the exported `flattenConnection()` helper. The cart store consumed by `trackCartAnalytics` is different: it reads `cart.lines.nodes` directly, so the app's cart query must select `lines.nodes`. The tracker falls back to the current time internally if store data is missing `updatedAt`, but include `updatedAt` in the cart query for stable dedupe.
+Manually published `AnalyticsCart` payloads (like `CART_VIEWED`) accept both `lines.nodes` and `lines.edges` (GraphQL connection) shapes at the type level; the bus forwards them unchanged, so subscribers that read lines should flatten them with the exported `flattenConnection()` helper. The cart store consumed by `trackCartAnalytics` is different: it reads `cart.lines.nodes` directly, so the app's cart query must select `lines.nodes`.
 
 Application code should not manually publish `cart_updated`, `product_added_to_cart`, or `product_removed_from_cart`. Always go through `trackCartAnalytics`.
 
@@ -563,7 +561,7 @@ Application code should not manually publish `cart_updated`, `product_added_to_c
 
 ## Wiring third-party destinations
 
-The bus is the right integration point for GA4, Meta Pixel, Klaviyo, etc. Register third-party analytics with `addDestination()`. The bus gates destination callbacks with Shopify Customer Privacy and replays buffered events after analytics consent is granted:
+The bus is the right integration point for GA4, Meta Pixel, Klaviyo, etc. Register each integration once with `addDestination()` during browser app initialization, after ShopifyScripts has created the bus. The bus gates destination callbacks with Shopify Customer Privacy and replays retained history when analytics consent allows:
 
 ```ts
 const analytics = getAnalytics();
@@ -578,7 +576,11 @@ analytics?.addDestination({
 });
 ```
 
-Consent gating happens at the bus level before destination callbacks see the payload. Raw `analytics.subscribe()` is live-only and consent-agnostic; use `addDestination()` for logging or analytics destinations that should respect consent and replay.
+Register all event consumers with `addDestination()` and subscribe inside its setup callback. Consent gating happens at the bus level before destination callbacks see the payload.
+
+Removing and re-adding a destination, even with the same name, creates a fresh registration and replays retained history again. This can duplicate deliveries on component remounts, including React Strict Mode's development effect replay. Keep destinations registered for the page's lifetime; use the returned cleanup when intentionally removing an integration.
+
+Destinations that need Shopify visitor IDs can call `getTrackingValues()` from the callback's second argument: `subscribe(event, (payload, { getTrackingValues }) => { ... })`. It reads current `uniqueToken` and `visitToken` values from the consent API when called, including during replay, and requests fallback generation with the tag `hydrogen:<destination name>`. Unavailable tokens are empty strings, and the getter also returns empty strings whenever analytics tracking is not currently allowed, so a retained getter cannot read or generate tokens after consent is revoked. Call it inside the destination callback; registration itself does not read or generate tokens.
 
 ---
 
@@ -589,7 +591,7 @@ After wiring, smoke-test each event in the browser dev tools:
 1. **Destination log fires** — open the page with the dev console open. You should see `[analytics] page_viewed` (or whichever events you logged) after consent allows tracking. If nothing logs, either `getAnalytics()` is no-op'ing on the server, the bus is unavailable, or `analyticsProcessingAllowed()` is false.
 2. **Monorail request fires** — Network tab, filter for `monorail-edge.shopifysvc.com`. A `produce_batch` POST should land within ~1s of consent being granted (or immediately if the visitor is in a no-consent-required region). If it never fires, either consent has not been granted, the schemas are missing required fields (check console for warnings about missing `id`/`title`/`vendor`/etc.), or `hasUserConsent` is false on the payload.
 3. **Per-route navigation fires page_viewed** — click around. Each navigation should produce a fresh `page_viewed` event. If only the initial page load fires, the route-change hook is wired wrong (e.g. effect dependency missing in React, reactive read missing in Solid).
-4. **Cart events fire** — add an item to the cart. You should see `cart_updated` followed by `product_added_to_cart`. If you see `cart_updated` repeating with the same payload, the dedupe key (`updatedAt`) is stale — confirm your cart query selects `updatedAt`.
+4. **Cart events fire** — add an item to the cart. You should see `cart_updated` followed by `product_added_to_cart`.
 5. **Privacy banner renders for EU/UK visitors** — if `mode: "default-banner"`, simulate a GDPR-protected region with browser dev-tools location override or VPN. The banner should render. If it does not, check that `cdn.shopify.com` is not blocked by your CSP.
 
 For production, re-verify against the production bundle. Several gotchas only appear once the SSR/CSR boundary stabilizes.
@@ -598,7 +600,7 @@ For production, re-verify against the production bundle. Several gotchas only ap
 
 ## Common gotchas
 
-- **Replay is destination-only.** Raw `analytics.subscribe()` listeners only receive live events. `analytics.addDestination()` callbacks receive consent-gated live events plus buffered replay after analytics consent is granted. If the visitor explicitly denies analytics consent, the buffer is cleared and those pre-denial events are never replayed.
+- **Destinations receive live events and buffered replay after analytics consent is granted.** If the visitor explicitly denies analytics consent, the buffer is cleared and those pre-denial events are never replayed.
 - **The singleton must be lazy.** Reading the global bus at module top-level can run on the server during SSR and crash on `window` access. Always wrap in a `typeof window === 'undefined'` guard.
 - **Use the right shop shape for each API.** `ShopifyScripts` accepts a numeric Shop ID or Shopify Shop GID plus `storefrontId` and the permanent `myshopifyDomain`; the analytics bus normalizes `shop.shopId` to a Shopify Shop GID before dispatch, while the bootstrap exposes the domain as `window.Shopify.shop`.
 - **Customer Privacy script blocked by CSP.** If your CSP does not allow `cdn.shopify.com`, the consent script never loads, `analyticsProcessingAllowed()` stays `false`, and destination events never deliver. Check Network tab for blocked requests; add `cdn.shopify.com` to `script-src`.
@@ -607,8 +609,7 @@ For production, re-verify against the production bundle. Several gotchas only ap
 - **Astro inline scripts cannot reference component scope.** Astro hoists `<script>` tags at build time. Bridge SSR data through hidden DOM (`data-*` attributes) and read it from the script. Trying to interpolate `{product.id}` directly into a script body silently fails — the script ships as a static string.
 - **Astro page-view fires only on full loads.** Astro is MPA-by-default. If you adopt View Transitions, listen for `astro:after-swap` instead of relying on the inline-script-runs-on-load behavior — otherwise SPA-nav transitions skip `page_viewed`.
 - **Required product fields silently drop the Monorail leg.** Missing `id`/`title`/`vendor`/`variantId`/`variantTitle`/`price` causes the Shopify analytics subscriber to skip Monorail dispatch and log a field-specific error. The bus event still fires for your subscribers — the loss is only in Shopify analytics. Watch the console.
-- **`updatedAt` missing from cart query weakens dedupe.** The cart tracker prefers cart `updatedAt`, but falls back to the current time when it is absent. Include `updatedAt` in cart queries for stable dedupe across navigations and reloads.
-- **`destroy()` is not called by any of the framework adapter sketches.** During HMR or React Strict Mode double-mount, this means duplicate event subscribers and possibly duplicate Monorail events in dev. For production this is rarely visible (one bus per page lifetime). If duplicate dev events bother you, wire `analytics.destroy()` into your framework's teardown (React effect cleanup, Svelte `onDestroy`, Solid `onCleanup`, or equivalent).
+- **Register destinations once per page lifetime.** Hydrogen owns the shared bus. Removing and re-adding a destination resets its replay position, so component remounts can deliver retained events again.
 - **Lighthouse skip is silent.** Monorail dispatch is skipped for Chrome Lighthouse user-agents. If your synthetic monitoring runs Lighthouse, you will see no Monorail requests in those runs — this is intentional.
 
 ---
@@ -621,4 +622,4 @@ For production, re-verify against the production bundle. Several gotchas only ap
 - **Don't reimplement Monorail dispatch.** If you need a third-party destination, register it with `addDestination()` and forward from there — do not parallel-publish to Monorail yourself.
 - **Don't put per-route view events in a global subscriber.** A single subscriber that watches `page_viewed` and synthesizes `product_viewed` from URL parsing is brittle and loses payload context. Publish each view event from the route that has the data.
 - **Don't construct multiple buses for "different consent contexts" on the same page.** Customer Privacy config is global; the latest initialized config takes effect. If you need conditional behavior, branch inside subscribers, not at construction.
-- **Don't skip the request-handler prerequisite.** Without the SFAPI proxy, modern same-origin Shopify cookies cannot be set. Analytics may appear to work via deprecated JS-visible cookies, but session continuity into checkout breaks. Treat analytics as incomplete until the proxy is live in production.
+- **Don't skip the request-handler prerequisite.** Without the SFAPI proxy, modern same-origin Shopify cookies cannot be set. Session continuity into checkout depends on these backend cookies. Treat analytics as incomplete until the proxy is live in production.

package/skills/hydrogen-setup/steps/1-inspect-app.md

@@ -10,7 +10,7 @@ If it does not contain `@shopify/hydrogen@preview` (or a more specific hash) in
 
 ### Continue when
 
-- [ ] Current directrory has `package.json`
+- [ ] Current directory has `package.json`
 - [ ] Current project includes `@shopify/hydrogen@preview` or similar in its dependencies
 
 ## Styling

package/skills/hydrogen-setup/steps/11-verify.md

@@ -20,6 +20,7 @@ If Playwright is present, run it headless.
 
 - [ ] Every applicable script was executed in this session, after the last code change, and passed
 - [ ] `hydrogen gql check` ran as part of static checks (not skipped)
+- [ ] `dev` still starts with `hydrogen skills check --mode=warn` and prints no skills warning
 
 ## Run Runtime Smoke Tests
 

package/skills/hydrogen-setup/steps/2-scaffold.md

@@ -10,7 +10,7 @@ Preserve the app's existing route shape when present. When there is no establish
 - `/products/{handle}` for product detail. Use plural `products`, not `/product`.
 - `/cart` for the full cart page.
 
-Hydrogen-owned handlers are not page routes: `/api/cart`, `/api/{api-version}/graphql.json`, 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 redirects, `/admin` redirects, and Storefront URL redirects belong in the `hydrogen-request-handlers` wiring.
+Hydrogen-owned handlers are not page routes: `/api/cart`, `/api/{api-version}/graphql.json`, 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 redirects, `/admin` redirects, and Storefront URL redirects belong in the `hydrogen-request-handlers` wiring.
 
 Invoke the `hydrogen-routing` skill and create the shared route template manifest for Shopify resources such as products, collections, pages, blogs, or articles.
 
@@ -18,6 +18,25 @@ Invoke the `hydrogen-routing` skill and create the shared route template manifes
 
 - [ ] Route templates are set up
 
+## Keep Skills In Sync
+
+The packaged skills describe the installed Hydrogen version. Chain `hydrogen skills check --mode=warn` in front of the app's `dev` script so a later `@shopify/hydrogen` bump prints the resync command the next time the dev server starts, without blocking it:
+
+```json
+{
+  "scripts": {
+    "dev": "hydrogen skills check --mode=warn && <framework dev command>"
+  }
+}
+```
+
+Keep the framework's own dev command exactly as it was; only prefix it. Apply the same prefix to any sibling dev script such as `dev:https`. Do not add the plain `hydrogen skills check` (error mode) to `dev`; that belongs in CI, where a stale skill copy should fail the build.
+
+### Continue when
+
+- [ ] `dev` runs `hydrogen skills check --mode=warn` before the framework dev command
+- [ ] Running the `dev` script prints no skills warning (skills were synced by `hydrogen setup`)
+
 ## Use Standard Environment Names
 
 Use these canonical environment variable names throughout the app (kept in sync with `hydrogen-storefront-client`):
@@ -35,6 +54,8 @@ If the framework requires a prefix to expose client-side variables, preserve the
 
 List `PUBLIC_STOREFRONT_API_TOKEN` in the app's env example file as a commented-out entry (`# PUBLIC_STOREFRONT_API_TOKEN=`). The Storefront client accepts `undefined` as tokenless access, which is all mock.shop supports, so the scaffold works before the user has tokens and upgrades in place when they add one. Do not write an uncommented empty assignment (`PUBLIC_STOREFRONT_API_TOKEN=`): env loaders parse that as an empty string, and the client rejects empty tokens. Recommend filling it in (or switching to a private client) once the app targets a real store.
 
+When the user has no store yet, point `PUBLIC_STORE_DOMAIN` at a mock.shop store. `mock.shop` is the default apparel catalog; https://mock.shop/llms.txt lists every other fictional store with its host (for example `pets.mock.shop`) and what it sells. Pick the store closest to what the user is building, and see the `hydrogen-storefront-client` skill for the details.
+
 ### Continue when
 
 - [ ] Env vars follow the canonical names (plus any required framework prefix)

package/skills/hydrogen-smoke-test/SKILL.md

@@ -68,7 +68,7 @@ Collection and search:
 Analytics:
 - [ ] Page view fires on initial load and client navigations
 - [ ] Product/collection/search/cart view events fire once per route data change
-- [ ] Cart tracking is wired once via trackCartAnalytics(cartStore) (React/Vue: useCartAnalytics()), delta events fire on confirmed cart data changes, and the cart query includes updatedAt
+- [ ] Cart tracking is wired once via trackCartAnalytics(cartStore) (React/Vue: useCartAnalytics()), and delta events fire on confirmed cart data changes
 - [ ] No browser module reads private env variables
 - [ ] Production does not bypass Customer Privacy consent gating (no forced-always-true consent checks)
 
@@ -190,7 +190,7 @@ Expected: a redirect whose `location` header points at Shopify's hosted login, n
 
 - Page view fires on initial load and client navigations.
 - Product/collection/search/cart view events fire once per route data change.
-- Cart tracking is wired once per cart store lifecycle via `trackCartAnalytics(cartStore)` (React/Vue: `useCartAnalytics()`), cart delta events fire on confirmed cart data changes, and the cart query includes `updatedAt`.
+- Cart tracking is wired once per cart store lifecycle via `trackCartAnalytics(cartStore)` (React/Vue: `useCartAnalytics()`), and cart delta events fire on confirmed cart data changes.
 - No browser module reads private env variables.
 - Analytics destinations only receive events after Shopify Customer Privacy allows analytics processing.
 

package/skills/hydrogen-storefront-client/SKILL.md

@@ -43,6 +43,10 @@ Environment variables are still a **server-side input boundary**. Do not read `p
 
 Default to a public client. `publicStorefrontToken` accepts `undefined`, which means tokenless access — there is no rate limit for tokenless clients, and it is all mock.shop supports. Always recommend a token-backed client (public or private) once the app targets a real store: token-based Storefront API access is required for product tags, metaobjects, metafields, menus, and customers. Public and private tokens can query the same token-required fields; the difference is whether the token is safe to expose and whether the request has trusted buyer context.
 
+### mock.shop is a catalog of stores
+
+mock.shop is not one store. The default store at `mock.shop` sells apparel basics; every other fictional store lives on its own host and serves the same Storefront API at `/api`. When the user has no store yet, read the directory at https://mock.shop/llms.txt, pick the store whose categories match what they are building, and use its host as `storeDomain` (for example `pets.mock.shop`). Each store describes its own catalog at `https://<store>.mock.shop/llms.txt`. Every mock.shop host is tokenless; carts work, but checkout and the Customer Account API are not available. Moving to a real store changes only `storeDomain` and the token.
+
 ### Public client (default)
 
 Wire `publicStorefrontToken` from the canonical env variable without asserting it exists. When `PUBLIC_STOREFRONT_API_TOKEN` is unset the client runs tokenless, so the same scaffold works against mock.shop before the user has tokens and upgrades in place when they add one. In env example files list the variable commented out (`# PUBLIC_STOREFRONT_API_TOKEN=`) rather than as an empty assignment: env loaders parse `PUBLIC_STOREFRONT_API_TOKEN=` as an empty string, and the client rejects empty tokens.
@@ -280,8 +284,6 @@ Every successful result includes `headers` (the raw `Headers` object from the re
 
 A 200 response with GraphQL `errors` does NOT throw — partial success is valid in GraphQL. Non-200 responses, timeouts, network failures, and JSON parse errors all throw `StorefrontApiError` (or the `StorefrontTimeoutError` subclass).
 
-`StorefrontApiError` carries GraphQL error context (`locations`, `path`, `extensions`) when available. `extensions.code` enables programmatic branching (e.g. retry on `"THROTTLED"`). `toJSON()` strips dev-only fields (`queryText`, `variables`, `stack`) — safe for error reporters.
-
 ---
 
 ## Testing

package/skills/hydrogen-variant-form/SKILL.md

@@ -86,6 +86,10 @@ Accepts `{ value: number }` for a controlled input or `{ defaultValue: number }`
 
 Requires `{ optionName, value }`. Returns `{ name, value, onChange, onClick }` — form identity plus activation handlers. Derive caller-owned UI props from the matching option value state, such as `value.exists`, `value.available`, and `value.selected`.
 
+### `register("attributeValue", opts)`
+
+Requires `{ key: string; value: string }` (controlled) or `{ key: string; defaultValue: string }` (uncontrolled). Returns `{ name: "attributes.<key>", value }` — a hidden input that attaches a line-item attribute to the add-to-cart submission. Use for per-line metadata like engraving text, gift messages, or custom options. Multiple `attributeValue` fields can be registered for different keys. The `key` must be non-empty (throws `TypeError` otherwise). Attributes with keys starting with `_` are conventionally internal/private and should not be set from the storefront UI.
+
 ### `register("addToCart", opts)`
 
 Returns `{ name: "add-to-cart", type: "submit" }` for the add-to-cart submit button.
@@ -174,8 +178,8 @@ Pass `style: "variant"` with a resolved `variant` to emit a shareable `?variant=
 ### Add-to-cart
 
 - **ALWAYS use `canAddToCart(product, options)` to determine if the add-to-cart button should be enabled.** This checks three conditions: a variant is selected, it is available for sale, and the product does not require a selling plan. Checking only `selectedVariant !== null` misses the selling-plan and availability constraints.
-- **The add-to-cart form is separate from the variant selector.** Variant selection uses buttons and links — not form submissions. The add-to-cart form contains `merchandiseId` (the selected variant ID) and `quantity`. Do not put variant selection controls inside the cart form.
-- **Use `register` to bind form fields.** `register("merchandiseId", {})` returns the hidden input props with the current variant ID. `register("quantity", { value: 1 })` returns the quantity input props. `register("addToCart", {})` returns stable add-to-cart submit button props. These stay synchronized with store state automatically.
+- **The add-to-cart form is separate from the variant selector.** Variant selection uses buttons and links — not form submissions. The add-to-cart form contains `merchandiseId` (the selected variant ID), `quantity`, and optionally `attributeValue` fields for line-item attributes. Do not put variant selection controls inside the cart form.
+- **Use `register` to bind form fields.** `register("merchandiseId", {})` returns the hidden input props with the current variant ID. `register("quantity", { value: 1 })` returns the quantity input props. `register("attributeValue", { key: "Engraving", value })` returns a hidden input for a line-item attribute. `register("addToCart", {})` returns stable add-to-cart submit button props. These stay synchronized with store state automatically.
 - **Use the local `hydrogen-shop-pay` skill** when adding accelerated checkout near the add-to-cart form.
 - **Show contextual CTA text.** When `canAddToCart` is `true`: "Add to cart". When no variant is selected (`selectedVariant === null`): "Select options" unless a navigation or submission is actually pending. When a variant is selected but unavailable: "Unavailable" or "Sold out".
 - **Surface cart errors from `errors` state.** After form submission, user errors, warnings, and network errors relevant to the current product form are available on `state.errors`. Display these to the buyer.
@@ -246,14 +250,16 @@ Pass `style: "variant"` with a resolved `variant` to emit a shareable `?variant=
 28. **Caller-owned option attributes** — `register("optionValue", { optionName: "Color", value: "Red" })` returns only `{ name, value, onChange, onClick }`. Derive `disabled`, `aria-pressed`, and visual state from the matching `options` value.
 29. **Quantity registration** — `register("quantity", { value: 1 })` returns `{ name: "quantity", value: "1" }`. `register("quantity", { defaultValue: 1 })` returns `{ name: "quantity", defaultValue: "1" }`.
 30. **Add-to-cart registration** — `register("addToCart", {})` returns `{ name: "add-to-cart", type: "submit" }`.
+31. **Attribute value registration** — `register("attributeValue", { key: "Engraving", value: "Hello" })` returns `{ name: "attributes.Engraving", value: "Hello" }`. `register("attributeValue", { key: "Engraving", defaultValue: "" })` returns `{ name: "attributes.Engraving", defaultValue: "" }`. An empty `key` throws a `TypeError`.
+32. **Attribute in add-to-cart** — When `register("attributeValue", { key: "Engraving", value: "Hello" })` is included as a hidden input in the add-to-cart form, the submitted cart line carries the attribute. The attribute appears on the matched line item in the cart drawer (with `_`-prefixed internal attributes filtered out).
 
 ### Unresolved selection
 
-31. **Transient unresolved** — In URL-routing apps, when a complete selection returns `unresolved` because the exact variant is absent from the local cache, the app navigates to the new URL and re-fetches product data. The subsequent hydration resolves the variant. Incomplete selections should remain in selection UI until the buyer chooses the remaining options.
+33. **Transient unresolved** — In URL-routing apps, when a complete selection returns `unresolved` because the exact variant is absent from the local cache, the app navigates to the new URL and re-fetches product data. The subsequent hydration resolves the variant. Incomplete selections should remain in selection UI until the buyer chooses the remaining options.
 
 ### Reset
 
-32. **Reset to initial state** — Calling `reset()` restores the store to the product and selected options it was created with. All user selections are discarded.
+34. **Reset to initial state** — Calling `reset()` restores the store to the product and selected options it was created with. All user selections are discarded.
 
 ---
 

package/ts-plugin/package.json

@@ -0,0 +1,5 @@
+{
+  "private": true,
+  "main": "../dist/ts-plugin/index.cjs",
+  "types": "../dist/ts-plugin/index.d.cts"
+}

package/dist/core/shopify-scripts/consent.mjs

@@ -1,17 +0,0 @@
-import { asInlineScript } from "./utils/inline-script.mjs";
-import { SHOPIFY_CONSENT_SCRIPT_ID, VISITOR_CONSENT_COLLECTED_EVENT } from "./constants.mjs";
-
-//#region src/core/shopify-scripts/consent.ts
-const initializeShopifyConsentTracking = (scriptData) => decodeURIComponent("(function()%7Bfunction%20e(e)%7Breturn%20typeof%20e%3D%3D%60object%60%26%26!!e%7Dfunction%20t(e%2Ct)%7Blet%20n%3D%5B%60%5Bhydrogen%3Aerror%3Aconsent%5D%20%24%7Be%7D%60%5D%3Bt!%3D%3Dvoid%200%26%26n.push(t)%2Cconsole.error(...n)%7Dfunction%20n(n)%7Blet%20r%3Dwindow%2Ci%3Dn.mode%3D%3D%3D%60default-banner%60%2Ca%3D!1%2Co%3D!1%2Cs%3D%60initial%60%2Cc%3D()%3D%3Er.Shopify%3F.customerPrivacy%2Cl%3D()%3D%3E%7Blet%20e%3Dc()%3Be%26%26(e.consentStatus%3D%60loaded%60)%7D%2Cu%3D()%3D%3E%7Bo%3D!0%2Ca%26%26l()%7D%2Cd%3D()%3D%3E%7Blet%20e%3Dc()%3F.setTrackingConsent%3Bif(typeof%20e!%3D%60function%60)return%20t(%60unable%20to%20request%20initial%20consent%60)%2Cu()%3Be(%7BheadlessStorefront%3A!0%7D%2Ce%3D%3E%7Bif(e%3F.error)%7Bt(%60unable%20to%20request%20initial%20consent%60%2Ce.error)%3Breturn%7Du()%7D)%7D%2Cf%3D()%3D%3E%7Blet%20e%3Dc()%3Breturn%20typeof%20e%3F.setTrackingConsent%3D%3D%60function%60%7C%7Ctypeof%20e%3F.shouldShowBanner%3D%3D%60function%60%7C%7Ctypeof%20window.privacyBanner%3D%3D%60object%60%7D%2Cp%3D()%3D%3E%7Ba%7C%7C(a%3D!0%2Ci%3Fo%26%26u()%3Ad())%7D%3Bdocument.addEventListener(n.eventName%2Ct%3D%3E%7Blet%20n%3D%60detail%60in%20t%3Ft.detail%3Avoid%200%3Be(n)%26%26(n.source%3F%3F%3Ds)%2Cs%3D%60interaction%60%7D%2C%7Bcapture%3A!0%7D)%2Cdocument.addEventListener(n.eventName%2Cu%2C%7Bcapture%3A!0%7D)%3Blet%20m%3Ddocument.getElementById(n.scriptId)%3Bf()%3Fp()%3Am%3F.addEventListener(%60load%60%2Cp%2C%7Bonce%3A!0%7D)%7Dn(__SHOPIFY_SCRIPT_DATA__)%7D)()%3B").replace("__SHOPIFY_SCRIPT_DATA__", () => (JSON.stringify(scriptData) ?? "undefined").replace(/</g, "\\u003c").replace(/\u2028/g, "\\u2028").replace(/\u2029/g, "\\u2029"));
-function getShopifyConsentTrackingScript(consent = {}) {
-	const config = {
-		eventName: VISITOR_CONSENT_COLLECTED_EVENT,
-		mode: consent.mode ?? "no-banner",
-		scriptId: SHOPIFY_CONSENT_SCRIPT_ID
-	};
-	return asInlineScript(initializeShopifyConsentTracking)(config);
-}
-
-//#endregion
-export { getShopifyConsentTrackingScript };
-//# sourceMappingURL=consent.mjs.map

package/dist/core/shopify-scripts/consent.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"consent.mjs","names":[],"sources":["../../../src/core/shopify-scripts/consent.ts"],"sourcesContent":["import type { ConsentConfig } from \"../analytics/types\";\nimport initializeShopifyConsentTracking from \"./consent-script\" with { type: \"script\" };\nimport type { ShopifyConsentTrackingConfig } from \"./consent-script\";\nimport { SHOPIFY_CONSENT_SCRIPT_ID, VISITOR_CONSENT_COLLECTED_EVENT } from \"./constants\";\nimport { asInlineScript } from \"./utils/inline-script\";\n\nexport function getShopifyConsentTrackingScript(consent: ConsentConfig = {}): string {\n  const config: ShopifyConsentTrackingConfig = {\n    eventName: VISITOR_CONSENT_COLLECTED_EVENT,\n    mode: consent.mode ?? \"no-banner\",\n    scriptId: SHOPIFY_CONSENT_SCRIPT_ID,\n  };\n\n  return asInlineScript(initializeShopifyConsentTracking)(config);\n}\n"],"mappings":";;;;AACA,MAAM,oCAAkC,eAAgB,mBAAqB,q8CAAU,CAAA,QAAA,kCAAA,KAAA,UAAA,WAAA,IAAA,aAAA,QAAA,MAAA,UAAA,CAAA,QAAA,WAAA,UAAA,CAAA,QAAA,WAAA,UAAA,CAAA;AAKvF,SAAgB,gCAAgC,UAAyB,EAAE,EAAU;CACnF,MAAM,SAAuC;EAC3C,WAAW;EACX,MAAM,QAAQ,QAAQ;EACtB,UAAU;EACX;AAED,QAAO,eAAe,iCAAiC,CAAC,OAAO"}

package/dist/core/shopify-scripts/deprecated-cookies.mjs

@@ -1,97 +0,0 @@
-import { VISITOR_CONSENT_COLLECTED_EVENT } from "./constants.mjs";
-import { findWritableCookieDomain } from "./utils/cookie-domain.mjs";
-import { getTrackingValues } from "./utils/tracking-values.mjs";
-import { buildUUID } from "./utils/uuid.mjs";
-
-//#region src/core/shopify-scripts/deprecated-cookies.ts
-/**
-* @deprecated This module manages the legacy `_shopify_y` and `_shopify_s`
-* JavaScript-visible cookies. Modern Shopify storefronts use http-only cookies
-* set by the Storefront API via the SFAPI proxy. This module exists only for
-* backward compatibility with downstream systems that may still read these
-* JS cookies directly.
-*
-* To remove: delete this file and remove the ShopifyScripts startup call.
-*/
-const SHOPIFY_Y = "_shopify_y";
-const SHOPIFY_S = "_shopify_s";
-const LONG_TERM_EXPIRY_IN_SECONDS = 3600 * 24 * 360;
-const SHORT_TERM_EXPIRY_IN_SECONDS = 1800;
-/**
-* Computes the cookie domain as the broadest wildcard domain the browser will
-* accept for the consent domain. Returns empty string for localhost or when
-* probing fails (cookies use current domain).
-*
-* @deprecated Part of legacy cookie management.
-*/
-function computeCookieDomain(consentDomain) {
-	if (typeof window === "undefined") return "";
-	return findWritableCookieDomain(consentDomain || window.location.host);
-}
-function setCookie(name, value, maxAgeInSeconds, domain) {
-	const parts = [`${name}=${encodeURIComponent(value)}`];
-	parts.push(`max-age=${maxAgeInSeconds}`);
-	parts.push("path=/");
-	parts.push("SameSite=Lax");
-	if (domain) parts.push(`domain=${domain}`);
-	document.cookie = parts.join("; ");
-}
-/**
-* @deprecated Sets or removes the legacy `_shopify_y` and `_shopify_s` cookies
-* based on the current consent state and tracking values.
-*/
-function updateCookies(hasConsent, domain) {
-	if (hasConsent) {
-		const trackingValues = getTrackingValues();
-		if ((trackingValues.uniqueToken || trackingValues.visitToken || "").startsWith("00000000-")) return;
-		setCookie(SHOPIFY_Y, trackingValues.uniqueToken || buildUUID(), LONG_TERM_EXPIRY_IN_SECONDS, domain);
-		setCookie(SHOPIFY_S, trackingValues.visitToken || buildUUID(), SHORT_TERM_EXPIRY_IN_SECONDS, domain);
-	} else {
-		setCookie(SHOPIFY_Y, "", 0, domain);
-		setCookie(SHOPIFY_S, "", 0, domain);
-	}
-}
-function hasAnalyticsConsent() {
-	try {
-		return (window.Shopify?.customerPrivacy)?.analyticsProcessingAllowed?.() ?? false;
-	} catch {
-		return false;
-	}
-}
-function isConsentLoaded() {
-	return window.Shopify?.customerPrivacy?.consentStatus === "loaded";
-}
-function getConsentDomain() {
-	return window.Shopify?.customerPrivacy?.config?.consentDomain;
-}
-let didInitializeDeprecatedCookies = false;
-const noOpCleanup = () => {};
-/**
-* @deprecated Starts page-lifetime legacy cookie management from ShopifyScripts.
-*/
-function initializeDeprecatedCookies() {
-	if (typeof window === "undefined" || typeof document === "undefined") return noOpCleanup;
-	if (didInitializeDeprecatedCookies) return noOpCleanup;
-	didInitializeDeprecatedCookies = true;
-	const domain = computeCookieDomain(getConsentDomain());
-	const syncConsent = () => {
-		updateCookies(hasAnalyticsConsent(), domain);
-	};
-	document.addEventListener(VISITOR_CONSENT_COLLECTED_EVENT, syncConsent);
-	if (isConsentLoaded()) syncConsent();
-	const syncPageView = () => {
-		if (hasAnalyticsConsent()) updateCookies(true, domain);
-	};
-	const subscribeToAnalytics = () => {
-		const subscribe = window.Shopify?.analytics?.subscribe;
-		if (typeof subscribe !== "function") return false;
-		subscribe("page_viewed", syncPageView);
-		return true;
-	};
-	if (!subscribeToAnalytics() && document.readyState === "loading") document.addEventListener("DOMContentLoaded", subscribeToAnalytics, { once: true });
-	return noOpCleanup;
-}
-
-//#endregion
-export { initializeDeprecatedCookies };
-//# sourceMappingURL=deprecated-cookies.mjs.map

package/dist/core/shopify-scripts/deprecated-cookies.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"deprecated-cookies.mjs","names":[],"sources":["../../../src/core/shopify-scripts/deprecated-cookies.ts"],"sourcesContent":["/**\n * @deprecated This module manages the legacy `_shopify_y` and `_shopify_s`\n * JavaScript-visible cookies. Modern Shopify storefronts use http-only cookies\n * set by the Storefront API via the SFAPI proxy. This module exists only for\n * backward compatibility with downstream systems that may still read these\n * JS cookies directly.\n *\n * To remove: delete this file and remove the ShopifyScripts startup call.\n */\n\nimport { VISITOR_CONSENT_COLLECTED_EVENT } from \"./constants\";\nimport { findWritableCookieDomain } from \"./utils/cookie-domain\";\nimport { getTrackingValues } from \"./utils/tracking-values\";\nimport { buildUUID } from \"./utils/uuid\";\n\nconst SHOPIFY_Y = \"_shopify_y\";\nconst SHOPIFY_S = \"_shopify_s\";\n\nconst LONG_TERM_EXPIRY_IN_SECONDS = 60 * 60 * 24 * 360;\nconst SHORT_TERM_EXPIRY_IN_SECONDS = 60 * 30;\n\n/**\n * Computes the cookie domain as the broadest wildcard domain the browser will\n * accept for the consent domain. Returns empty string for localhost or when\n * probing fails (cookies use current domain).\n *\n * @deprecated Part of legacy cookie management.\n */\nexport function computeCookieDomain(consentDomain?: string): string {\n  if (typeof window === \"undefined\") return \"\";\n\n  return findWritableCookieDomain(consentDomain || window.location.host);\n}\n\nfunction setCookie(name: string, value: string, maxAgeInSeconds: number, domain: string): void {\n  const parts = [`${name}=${encodeURIComponent(value)}`];\n  parts.push(`max-age=${maxAgeInSeconds}`);\n  parts.push(\"path=/\");\n  parts.push(\"SameSite=Lax\");\n  if (domain) parts.push(`domain=${domain}`);\n  document.cookie = parts.join(\"; \");\n}\n\n/**\n * @deprecated Sets or removes the legacy `_shopify_y` and `_shopify_s` cookies\n * based on the current consent state and tracking values.\n */\nfunction updateCookies(hasConsent: boolean, domain: string): void {\n  if (hasConsent) {\n    const trackingValues = getTrackingValues();\n    const tokenValue = trackingValues.uniqueToken || trackingValues.visitToken || \"\";\n    if (tokenValue.startsWith(\"00000000-\")) return;\n\n    setCookie(\n      SHOPIFY_Y,\n      trackingValues.uniqueToken || buildUUID(),\n      LONG_TERM_EXPIRY_IN_SECONDS,\n      domain,\n    );\n    setCookie(\n      SHOPIFY_S,\n      trackingValues.visitToken || buildUUID(),\n      SHORT_TERM_EXPIRY_IN_SECONDS,\n      domain,\n    );\n  } else {\n    setCookie(SHOPIFY_Y, \"\", 0, domain);\n    setCookie(SHOPIFY_S, \"\", 0, domain);\n  }\n}\n\nfunction hasAnalyticsConsent(): boolean {\n  try {\n    const privacy = window.Shopify?.customerPrivacy;\n    return privacy?.analyticsProcessingAllowed?.() ?? false;\n  } catch {\n    return false;\n  }\n}\n\nfunction isConsentLoaded(): boolean {\n  return window.Shopify?.customerPrivacy?.consentStatus === \"loaded\";\n}\n\nfunction getConsentDomain(): string | undefined {\n  return window.Shopify?.customerPrivacy?.config?.consentDomain;\n}\n\nlet didInitializeDeprecatedCookies = false;\nconst noOpCleanup = () => {};\n\n/**\n * @deprecated Starts page-lifetime legacy cookie management from ShopifyScripts.\n */\nexport function initializeDeprecatedCookies(): () => void {\n  if (typeof window === \"undefined\" || typeof document === \"undefined\") return noOpCleanup;\n  if (didInitializeDeprecatedCookies) return noOpCleanup;\n\n  didInitializeDeprecatedCookies = true;\n  const domain = computeCookieDomain(getConsentDomain());\n\n  const syncConsent = () => {\n    updateCookies(hasAnalyticsConsent(), domain);\n  };\n\n  document.addEventListener(VISITOR_CONSENT_COLLECTED_EVENT, syncConsent);\n  if (isConsentLoaded()) syncConsent();\n\n  const syncPageView = () => {\n    if (hasAnalyticsConsent()) {\n      updateCookies(true, domain);\n    }\n  };\n\n  const subscribeToAnalytics = () => {\n    const subscribe = window.Shopify?.analytics?.subscribe;\n    if (typeof subscribe !== \"function\") return false;\n\n    subscribe(\"page_viewed\", syncPageView);\n    return true;\n  };\n\n  if (!subscribeToAnalytics() && document.readyState === \"loading\") {\n    // The bus is inline today, but if it moves to a module/defer script it will\n    // still be available before DOMContentLoaded.\n    document.addEventListener(\"DOMContentLoaded\", subscribeToAnalytics, { once: true });\n  }\n\n  return noOpCleanup;\n}\n"],"mappings":";;;;;;;;;;;;;;;AAeA,MAAM,YAAY;AAClB,MAAM,YAAY;AAElB,MAAM,8BAA8B,OAAU,KAAK;AACnD,MAAM,+BAA+B;;;;;;;;AASrC,SAAgB,oBAAoB,eAAgC;AAClE,KAAI,OAAO,WAAW,YAAa,QAAO;AAE1C,QAAO,yBAAyB,iBAAiB,OAAO,SAAS,KAAK;;AAGxE,SAAS,UAAU,MAAc,OAAe,iBAAyB,QAAsB;CAC7F,MAAM,QAAQ,CAAC,GAAG,KAAK,GAAG,mBAAmB,MAAM,GAAG;AACtD,OAAM,KAAK,WAAW,kBAAkB;AACxC,OAAM,KAAK,SAAS;AACpB,OAAM,KAAK,eAAe;AAC1B,KAAI,OAAQ,OAAM,KAAK,UAAU,SAAS;AAC1C,UAAS,SAAS,MAAM,KAAK,KAAK;;;;;;AAOpC,SAAS,cAAc,YAAqB,QAAsB;AAChE,KAAI,YAAY;EACd,MAAM,iBAAiB,mBAAmB;AAE1C,OADmB,eAAe,eAAe,eAAe,cAAc,IAC/D,WAAW,YAAY,CAAE;AAExC,YACE,WACA,eAAe,eAAe,WAAW,EACzC,6BACA,OACD;AACD,YACE,WACA,eAAe,cAAc,WAAW,EACxC,8BACA,OACD;QACI;AACL,YAAU,WAAW,IAAI,GAAG,OAAO;AACnC,YAAU,WAAW,IAAI,GAAG,OAAO;;;AAIvC,SAAS,sBAA+B;AACtC,KAAI;AAEF,UADgB,OAAO,SAAS,kBAChB,8BAA8B,IAAI;SAC5C;AACN,SAAO;;;AAIX,SAAS,kBAA2B;AAClC,QAAO,OAAO,SAAS,iBAAiB,kBAAkB;;AAG5D,SAAS,mBAAuC;AAC9C,QAAO,OAAO,SAAS,iBAAiB,QAAQ;;AAGlD,IAAI,iCAAiC;AACrC,MAAM,oBAAoB;;;;AAK1B,SAAgB,8BAA0C;AACxD,KAAI,OAAO,WAAW,eAAe,OAAO,aAAa,YAAa,QAAO;AAC7E,KAAI,+BAAgC,QAAO;AAE3C,kCAAiC;CACjC,MAAM,SAAS,oBAAoB,kBAAkB,CAAC;CAEtD,MAAM,oBAAoB;AACxB,gBAAc,qBAAqB,EAAE,OAAO;;AAG9C,UAAS,iBAAiB,iCAAiC,YAAY;AACvE,KAAI,iBAAiB,CAAE,cAAa;CAEpC,MAAM,qBAAqB;AACzB,MAAI,qBAAqB,CACvB,eAAc,MAAM,OAAO;;CAI/B,MAAM,6BAA6B;EACjC,MAAM,YAAY,OAAO,SAAS,WAAW;AAC7C,MAAI,OAAO,cAAc,WAAY,QAAO;AAE5C,YAAU,eAAe,aAAa;AACtC,SAAO;;AAGT,KAAI,CAAC,sBAAsB,IAAI,SAAS,eAAe,UAGrD,UAAS,iBAAiB,oBAAoB,sBAAsB,EAAE,MAAM,MAAM,CAAC;AAGrF,QAAO"}

package/dist/core/shopify-scripts/utils/cookie-domain.mjs

@@ -1,43 +0,0 @@
-//#region src/core/shopify-scripts/utils/cookie-domain.ts
-function normalizeHost(host) {
-	return host.replace(/^https?:\/\//, "").split("/")[0]?.split(":")[0]?.replace(/^\./, "").toLowerCase() ?? "";
-}
-function isIpAddress(host) {
-	return /^\d{1,3}(?:\.\d{1,3}){3}$/.test(host) || host.includes(":");
-}
-function canUseDomainCookie(domain) {
-	if (typeof document === "undefined") return false;
-	const name = `hydrogen_domain_probe_${Math.random().toString(36).slice(2)}`;
-	const nameValuePair = `${name}=1`;
-	const cookie = `${nameValuePair}; domain=${domain}; path=/; SameSite=Lax`;
-	const cleanup = `${name}=; domain=${domain}; path=/; max-age=0; SameSite=Lax`;
-	try {
-		document.cookie = cookie;
-		const found = document.cookie.split(";").some((part) => part.trim() === nameValuePair);
-		document.cookie = cleanup;
-		return found;
-	} catch {
-		return false;
-	}
-}
-/**
-* Finds the broadest wildcard cookie domain the current document can set for a
-* host. Browsers reject public suffixes like `.com` and `.co.uk`, so probing is
-* the only reliable way to find the earliest usable wildcard without shipping a
-* public suffix list.
-*/
-function findWritableCookieDomain(host, probe = canUseDomainCookie) {
-	const normalizedHost = normalizeHost(host);
-	if (!normalizedHost || normalizedHost === "localhost" || isIpAddress(normalizedHost)) return "";
-	const parts = normalizedHost.split(".").filter(Boolean);
-	if (parts.length < 2) return "";
-	for (let index = parts.length - 2; index >= 0; index--) {
-		const domain = `.${parts.slice(index).join(".")}`;
-		if (probe(domain)) return domain;
-	}
-	return "";
-}
-
-//#endregion
-export { findWritableCookieDomain };
-//# sourceMappingURL=cookie-domain.mjs.map

package/dist/core/shopify-scripts/utils/cookie-domain.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"cookie-domain.mjs","names":[],"sources":["../../../../src/core/shopify-scripts/utils/cookie-domain.ts"],"sourcesContent":["function normalizeHost(host: string): string {\n  const withoutProtocol = host.replace(/^https?:\\/\\//, \"\");\n  return withoutProtocol.split(\"/\")[0]?.split(\":\")[0]?.replace(/^\\./, \"\").toLowerCase() ?? \"\";\n}\n\nfunction isIpAddress(host: string): boolean {\n  return /^\\d{1,3}(?:\\.\\d{1,3}){3}$/.test(host) || host.includes(\":\");\n}\n\nfunction canUseDomainCookie(domain: string): boolean {\n  if (typeof document === \"undefined\") return false;\n\n  const name = `hydrogen_domain_probe_${Math.random().toString(36).slice(2)}`;\n  const value = \"1\";\n  const nameValuePair = `${name}=${value}`;\n  const cookie = `${nameValuePair}; domain=${domain}; path=/; SameSite=Lax`;\n  const cleanup = `${name}=; domain=${domain}; path=/; max-age=0; SameSite=Lax`;\n\n  try {\n    document.cookie = cookie;\n    const found = document.cookie.split(\";\").some((part) => part.trim() === nameValuePair);\n    document.cookie = cleanup;\n    return found;\n  } catch {\n    return false;\n  }\n}\n\n/**\n * Finds the broadest wildcard cookie domain the current document can set for a\n * host. Browsers reject public suffixes like `.com` and `.co.uk`, so probing is\n * the only reliable way to find the earliest usable wildcard without shipping a\n * public suffix list.\n */\nexport function findWritableCookieDomain(\n  host: string,\n  probe: (domain: string) => boolean = canUseDomainCookie,\n): string {\n  const normalizedHost = normalizeHost(host);\n  if (!normalizedHost || normalizedHost === \"localhost\" || isIpAddress(normalizedHost)) return \"\";\n\n  const parts = normalizedHost.split(\".\").filter(Boolean);\n  if (parts.length < 2) return \"\";\n\n  for (let index = parts.length - 2; index >= 0; index--) {\n    const domain = `.${parts.slice(index).join(\".\")}`;\n    if (probe(domain)) return domain;\n  }\n\n  return \"\";\n}\n"],"mappings":";AAAA,SAAS,cAAc,MAAsB;AAE3C,QADwB,KAAK,QAAQ,gBAAgB,GAC/B,CAAC,MAAM,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,IAAI,QAAQ,OAAO,GAAG,CAAC,aAAa,IAAI;;AAG3F,SAAS,YAAY,MAAuB;AAC1C,QAAO,4BAA4B,KAAK,KAAK,IAAI,KAAK,SAAS,IAAI;;AAGrE,SAAS,mBAAmB,QAAyB;AACnD,KAAI,OAAO,aAAa,YAAa,QAAO;CAE5C,MAAM,OAAO,yBAAyB,KAAK,QAAQ,CAAC,SAAS,GAAG,CAAC,MAAM,EAAE;CAEzE,MAAM,gBAAgB,GAAG,KAAK;CAC9B,MAAM,SAAS,GAAG,cAAc,WAAW,OAAO;CAClD,MAAM,UAAU,GAAG,KAAK,YAAY,OAAO;AAE3C,KAAI;AACF,WAAS,SAAS;EAClB,MAAM,QAAQ,SAAS,OAAO,MAAM,IAAI,CAAC,MAAM,SAAS,KAAK,MAAM,KAAK,cAAc;AACtF,WAAS,SAAS;AAClB,SAAO;SACD;AACN,SAAO;;;;;;;;;AAUX,SAAgB,yBACd,MACA,QAAqC,oBAC7B;CACR,MAAM,iBAAiB,cAAc,KAAK;AAC1C,KAAI,CAAC,kBAAkB,mBAAmB,eAAe,YAAY,eAAe,CAAE,QAAO;CAE7F,MAAM,QAAQ,eAAe,MAAM,IAAI,CAAC,OAAO,QAAQ;AACvD,KAAI,MAAM,SAAS,EAAG,QAAO;AAE7B,MAAK,IAAI,QAAQ,MAAM,SAAS,GAAG,SAAS,GAAG,SAAS;EACtD,MAAM,SAAS,IAAI,MAAM,MAAM,MAAM,CAAC,KAAK,IAAI;AAC/C,MAAI,MAAM,OAAO,CAAE,QAAO;;AAG5B,QAAO"}

package/dist/core/shopify-scripts/utils/tracking-values.mjs

@@ -1,65 +0,0 @@
-//#region src/core/shopify-scripts/utils/tracking-values.ts
-const cachedTrackingValues = { current: null };
-function getTrackingValues() {
-	let trackingValues;
-	if (typeof window !== "undefined" && typeof window.performance !== "undefined") try {
-		const resourceRE = /^https?:\/\/([^/]+)(\/api\/(?:unstable|2\d{3}-\d{2})\/graphql\.json(?=$|\?))?/;
-		const entries = performance.getEntriesByType("resource");
-		let matchedValues;
-		for (let i = entries.length - 1; i >= 0; i--) {
-			const entry = entries[i];
-			if (entry.initiatorType !== "fetch") continue;
-			const currentHost = window.location.host;
-			const match = entry.name.match(resourceRE);
-			if (!match) continue;
-			const [, matchedHost, sfapiPath] = match;
-			if (matchedHost === currentHost || sfapiPath && matchedHost?.endsWith(`.${currentHost}`)) {
-				const values = extractFromPerformanceEntry(entry);
-				if (values) {
-					matchedValues = values;
-					break;
-				}
-			}
-		}
-		if (matchedValues) trackingValues = matchedValues;
-		if (trackingValues) cachedTrackingValues.current = trackingValues;
-		else if (cachedTrackingValues.current) trackingValues = cachedTrackingValues.current;
-		if (!trackingValues) {
-			const navigationEntries = performance.getEntriesByType("navigation")[0];
-			trackingValues = extractFromPerformanceEntry(navigationEntries, false);
-		}
-	} catch {}
-	if (!trackingValues) {
-		const cookie = typeof document !== "undefined" ? document.cookie : "";
-		trackingValues = {
-			uniqueToken: cookie.match(/\b_shopify_y=([^;]+)/)?.[1] || "",
-			visitToken: cookie.match(/\b_shopify_s=([^;]+)/)?.[1] || "",
-			consent: cookie.match(/\b_tracking_consent=([^;]+)/)?.[1] || ""
-		};
-	}
-	return trackingValues;
-}
-function extractFromPerformanceEntry(entry, isConsentRequired = true) {
-	let uniqueToken = "";
-	let visitToken = "";
-	let consent = "";
-	const serverTiming = entry.serverTiming;
-	const minimumEntries = isConsentRequired ? 3 : 2;
-	if (serverTiming && serverTiming.length >= minimumEntries) for (let i = serverTiming.length - 1; i >= 0; i--) {
-		const { name, description } = serverTiming[i];
-		if (!name || !description) continue;
-		if (name === "_y") uniqueToken = description;
-		else if (name === "_s") visitToken = description;
-		else if (name === "_cmp") consent = description;
-		if (uniqueToken && visitToken && consent) break;
-	}
-	return uniqueToken && visitToken && (isConsentRequired ? consent : true) ? {
-		uniqueToken,
-		visitToken,
-		consent
-	} : void 0;
-}
-
-//#endregion
-export { getTrackingValues };
-//# sourceMappingURL=tracking-values.mjs.map

package/dist/core/shopify-scripts/utils/tracking-values.mjs.map

@@ -1 +0,0 @@
-{"version":3,"file":"tracking-values.mjs","names":[],"sources":["../../../../src/core/shopify-scripts/utils/tracking-values.ts"],"sourcesContent":["/**\n * Inlined from @shopify/hydrogen-react/tracking-utils.\n * Retrieves user session tracking values from Server-Timing headers\n * and the Performance API.\n */\n\ntype TrackingValues = {\n  uniqueToken: string;\n  visitToken: string;\n  consent: string;\n};\n\nconst cachedTrackingValues: { current: null | TrackingValues } = { current: null };\n\nexport function getTrackingValues(): TrackingValues {\n  // Tracking values are returned in Server-Timing headers from SFAPI responses.\n  // Prefer recent fetch/resource entries, then cached values, then the initial\n  // navigation entry, and finally the deprecated JS-visible cookies.\n  let trackingValues: TrackingValues | undefined;\n\n  if (typeof window !== \"undefined\" && typeof window.performance !== \"undefined\") {\n    try {\n      // Extract host and optionally match the SFAPI GraphQL pathname.\n      const resourceRE =\n        /^https?:\\/\\/([^/]+)(\\/api\\/(?:unstable|2\\d{3}-\\d{2})\\/graphql\\.json(?=$|\\?))?/;\n\n      // Search backwards so the latest matching fetch with complete tracking\n      // values wins. Same-origin fetches cover Hydrogen proxy/server responses;\n      // subdomain SFAPI requests cover direct Storefront API calls.\n      const entries = performance.getEntriesByType(\"resource\") as PerformanceResourceTiming[];\n\n      let matchedValues: TrackingValues | undefined;\n\n      for (let i = entries.length - 1; i >= 0; i--) {\n        const entry = entries[i];\n        if (entry.initiatorType !== \"fetch\") continue;\n\n        const currentHost = window.location.host;\n        const match = entry.name.match(resourceRE);\n        if (!match) continue;\n\n        const [, matchedHost, sfapiPath] = match;\n        const isMatch =\n          matchedHost === currentHost || (sfapiPath && matchedHost?.endsWith(`.${currentHost}`));\n\n        if (isMatch) {\n          const values = extractFromPerformanceEntry(entry);\n          if (values) {\n            matchedValues = values;\n            break;\n          }\n        }\n      }\n\n      if (matchedValues) {\n        trackingValues = matchedValues;\n      }\n\n      // Resource entries have a limited buffer and can be removed over time.\n      // A cached resource entry is newer than the navigation entry.\n      if (trackingValues) {\n        cachedTrackingValues.current = trackingValues;\n      } else if (cachedTrackingValues.current) {\n        trackingValues = cachedTrackingValues.current;\n      }\n\n      if (!trackingValues) {\n        // The document navigation entry can omit _cmp when the server generated\n        // tracking tokens, so only _y and _s are required for this fallback.\n        const navigationEntries = performance.getEntriesByType(\n          \"navigation\",\n        )[0] as PerformanceNavigationTiming;\n        trackingValues = extractFromPerformanceEntry(navigationEntries, false);\n      }\n    } catch {}\n  }\n\n  if (!trackingValues) {\n    const cookie = typeof document !== \"undefined\" ? document.cookie : \"\";\n\n    trackingValues = {\n      uniqueToken: cookie.match(/\\b_shopify_y=([^;]+)/)?.[1] || \"\",\n      visitToken: cookie.match(/\\b_shopify_s=([^;]+)/)?.[1] || \"\",\n      consent: cookie.match(/\\b_tracking_consent=([^;]+)/)?.[1] || \"\",\n    };\n  }\n\n  return trackingValues;\n}\n\nfunction extractFromPerformanceEntry(\n  entry: PerformanceNavigationTiming | PerformanceResourceTiming,\n  isConsentRequired = true,\n): TrackingValues | undefined {\n  let uniqueToken = \"\";\n  let visitToken = \"\";\n  let consent = \"\";\n\n  const serverTiming = entry.serverTiming;\n  const minimumEntries = isConsentRequired ? 3 : 2;\n  if (serverTiming && serverTiming.length >= minimumEntries) {\n    // Iterate backwards since Shopify tracking metrics are usually appended\n    // after framework/server metrics.\n    for (let i = serverTiming.length - 1; i >= 0; i--) {\n      const { name, description } = serverTiming[i];\n      if (!name || !description) continue;\n\n      if (name === \"_y\") uniqueToken = description;\n      else if (name === \"_s\") visitToken = description;\n      else if (name === \"_cmp\") {\n        // Consent value used by consent-tracking-api and privacy-banner scripts.\n        consent = description;\n      }\n\n      if (uniqueToken && visitToken && consent) break;\n    }\n  }\n\n  return uniqueToken && visitToken && (isConsentRequired ? consent : true)\n    ? { uniqueToken, visitToken, consent }\n    : undefined;\n}\n"],"mappings":";AAYA,MAAM,uBAA2D,EAAE,SAAS,MAAM;AAElF,SAAgB,oBAAoC;CAIlD,IAAI;AAEJ,KAAI,OAAO,WAAW,eAAe,OAAO,OAAO,gBAAgB,YACjE,KAAI;EAEF,MAAM,aACJ;EAKF,MAAM,UAAU,YAAY,iBAAiB,WAAW;EAExD,IAAI;AAEJ,OAAK,IAAI,IAAI,QAAQ,SAAS,GAAG,KAAK,GAAG,KAAK;GAC5C,MAAM,QAAQ,QAAQ;AACtB,OAAI,MAAM,kBAAkB,QAAS;GAErC,MAAM,cAAc,OAAO,SAAS;GACpC,MAAM,QAAQ,MAAM,KAAK,MAAM,WAAW;AAC1C,OAAI,CAAC,MAAO;GAEZ,MAAM,GAAG,aAAa,aAAa;AAInC,OAFE,gBAAgB,eAAgB,aAAa,aAAa,SAAS,IAAI,cAAc,EAE1E;IACX,MAAM,SAAS,4BAA4B,MAAM;AACjD,QAAI,QAAQ;AACV,qBAAgB;AAChB;;;;AAKN,MAAI,cACF,kBAAiB;AAKnB,MAAI,eACF,sBAAqB,UAAU;WACtB,qBAAqB,QAC9B,kBAAiB,qBAAqB;AAGxC,MAAI,CAAC,gBAAgB;GAGnB,MAAM,oBAAoB,YAAY,iBACpC,aACD,CAAC;AACF,oBAAiB,4BAA4B,mBAAmB,MAAM;;SAElE;AAGV,KAAI,CAAC,gBAAgB;EACnB,MAAM,SAAS,OAAO,aAAa,cAAc,SAAS,SAAS;AAEnE,mBAAiB;GACf,aAAa,OAAO,MAAM,uBAAuB,GAAG,MAAM;GAC1D,YAAY,OAAO,MAAM,uBAAuB,GAAG,MAAM;GACzD,SAAS,OAAO,MAAM,8BAA8B,GAAG,MAAM;GAC9D;;AAGH,QAAO;;AAGT,SAAS,4BACP,OACA,oBAAoB,MACQ;CAC5B,IAAI,cAAc;CAClB,IAAI,aAAa;CACjB,IAAI,UAAU;CAEd,MAAM,eAAe,MAAM;CAC3B,MAAM,iBAAiB,oBAAoB,IAAI;AAC/C,KAAI,gBAAgB,aAAa,UAAU,eAGzC,MAAK,IAAI,IAAI,aAAa,SAAS,GAAG,KAAK,GAAG,KAAK;EACjD,MAAM,EAAE,MAAM,gBAAgB,aAAa;AAC3C,MAAI,CAAC,QAAQ,CAAC,YAAa;AAE3B,MAAI,SAAS,KAAM,eAAc;WACxB,SAAS,KAAM,cAAa;WAC5B,SAAS,OAEhB,WAAU;AAGZ,MAAI,eAAe,cAAc,QAAS;;AAI9C,QAAO,eAAe,eAAe,oBAAoB,UAAU,QAC/D;EAAE;EAAa;EAAY;EAAS,GACpC"}