@shopify/hydrogen 2026.10.0-preview.4 → 2026.10.0

package/skills/hydrogen-collection-browser/references/react.md

@@ -12,6 +12,7 @@ Use the React binding:
 
 ```tsx
 import {
+  formatMoney,
   getFilterRemovalUrl,
   getSortByValue,
   isFilterInputActive,
@@ -19,10 +20,12 @@ import {
   serializeCollectionParams,
   type AvailableFilter,
   type CollectionState,
+  type MoneyV2,
   type ProductFilter,
 } from "@shopify/hydrogen";
 import { CollectionProvider, useCollection, useCollectionForm } from "@shopify/hydrogen/react";
 import type { ProductFilter as StorefrontApiProductFilter } from "@shopify/hydrogen/storefront-api-types";
+import { useEffect, useRef } from "react";
 ```
 
 Use `getSortByValue(...)` for option values so the `sort_by` query param round-trips through `parseCollectionParams()`:
@@ -73,12 +76,20 @@ export async function loader({ context, params, request }: Route.LoaderArgs) {
     collection: data.collection,
     products: data.collection.products.nodes,
     availableFilters: data.collection.products.filters,
+    // Market-aware stores: `data.localization.country.currency.isoCode` under `@inContext`.
+    currencyCode: data.shop.paymentSettings.currencyCode,
     dataSearch: url.searchParams.toString(),
   };
 }
 ```
 
-Keep `dataSearch` exactly aligned with the query used for the server data.
+Keep `dataSearch` exactly aligned with the query used for the server data. Load `currencyCode` in the same query so it matches the product prices.
+
+For the single-currency loader above, include this root-level selection in `COLLECTION_QUERY`:
+
+```graphql
+shop { paymentSettings { currencyCode } }
+```
 
 ## Provider
 
@@ -114,7 +125,7 @@ export default function CollectionRoute({ loaderData }: Route.ComponentProps) {
 Inside the browse UI:
 
 ```tsx
-function CollectionPage({ availableFilters, products }: Props) {
+function CollectionPage({ availableFilters, currencyCode, products }: Props) {
   const state = useCollection();
   const { formProps } = useCollectionForm();
   const isLoading = state.status === "loading";
@@ -124,9 +135,9 @@ function CollectionPage({ availableFilters, products }: Props) {
       <FilterSidebar
         availableFilters={availableFilters}
         activeFilters={state.filters}
-        disabled={isLoading}
+        currencyCode={currencyCode}
       />
-      <select name="sort_by" defaultValue={currentSortValue(state)} onChange={requestFormSubmit}>
+      <select name="sort_by" value={currentSortValue(state)} onChange={requestFormSubmit}>
         {COLLECTION_SORT_OPTIONS.map((option) => (
           <option key={option.label} value={option.value}>
             {option.label}
@@ -145,7 +156,7 @@ function requestFormSubmit(event: React.ChangeEvent<HTMLInputElement | HTMLSelec
 
 Pass `method="get"` and an explicit `action={collectionPath}` (the current `/collections/:handle` or `/search` route URL) literally — `formProps()` only wires the submit handler (see the SKILL.md UI rule).
 
-Use uncontrolled form controls. When a route needs to remount them after external navigation, put `key={serializeCollectionParams({ filters: state.filters, sortKey: undefined, reverse: false }).toString()}` on the filter subtree (for search, include the term in the key) — keyed by serialized **filter state**, not the live URL. The URL clears before the `CollectionProvider` reconciler settles `state.filters`, so a URL-keyed remount bakes in stale defaults. This resets checkbox and price-input DOM state without coupling active filter chips to the form remount.
+Keep every filter control mounted and enabled during submission and loading, and show loading on the product grid (`pending`). Keep the filter subtree key stable across filter updates, so focused controls stay mounted. Bind the sort `value` and checkbox `checked` to browse state so chips and back/forward navigation update them in place. Keep price inputs uncontrolled and sync external bounds through input refs, as below.
 
 ## Filters
 
@@ -154,13 +165,15 @@ Choose the control at the filter-group level. `PRICE_RANGE` uses min/max number
 ```tsx
 function FilterGroup({
   activeFilters,
+  currencyCode,
   filter,
 }: {
   activeFilters: ProductFilter[];
+  currencyCode: MoneyV2["currencyCode"];
   filter: AvailableFilter;
 }) {
   if (filter.type === "PRICE_RANGE") {
-    return <PriceRangeInput activeFilters={activeFilters} />;
+    return <PriceRangeInput activeFilters={activeFilters} currencyCode={currencyCode} />;
   }
 
   return filter.values.map((value) => (
@@ -173,38 +186,130 @@ function FilterGroup({
   ));
 }
 
-function PriceRangeInput({ activeFilters }: { activeFilters: ProductFilter[] }) {
+// Use the resolved market locale in market-aware stores.
+const LOCALE = "en-US";
+
+function PriceRangeInput({
+  activeFilters,
+  currencyCode,
+}: {
+  activeFilters: ProductFilter[];
+  currencyCode: MoneyV2["currencyCode"];
+}) {
+  // One timer for both inputs, so editing min then max submits once.
+  const timer = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const minInput = useRef<HTMLInputElement>(null);
+  const maxInput = useRef<HTMLInputElement>(null);
   const price = activeFilters.find((filter) => filter.price)?.price;
+  const min = price?.min ?? "";
+  const max = price?.max ?? "";
+  const symbol = formatMoney(
+    { amount: "0", currencyCode },
+    { locale: LOCALE },
+  ).currencyNarrowSymbol;
+
+  useEffect(() => {
+    for (const [input, value] of [
+      [minInput.current, min],
+      [maxInput.current, max],
+    ] as const) {
+      if (!input) continue;
+      const matches =
+        value === "" ? input.value === "" : input.value !== "" && Number(input.value) === value;
+      if (!matches) {
+        if (timer.current) clearTimeout(timer.current);
+        timer.current = null;
+        input.value = String(value);
+      }
+    }
+  }, [min, max]);
+
+  useEffect(() => {
+    function cancelPendingSubmit() {
+      if (timer.current) clearTimeout(timer.current);
+      timer.current = null;
+    }
+
+    function restoreHistoryPrice() {
+      // Cancel drafts before history data loads, even if the price is unchanged.
+      cancelPendingSubmit();
+      const { filters } = parseCollectionParams(new URLSearchParams(window.location.search));
+      const price = filters.find((filter) => filter.price)?.price;
+      if (minInput.current) minInput.current.value = String(price?.min ?? "");
+      if (maxInput.current) maxInput.current.value = String(price?.max ?? "");
+    }
+
+    // Any form submission (native Enter included) already carries the typed price.
+    const form = minInput.current?.form;
+    form?.addEventListener("submit", cancelPendingSubmit);
+    window.addEventListener("popstate", restoreHistoryPrice);
+    return () => {
+      form?.removeEventListener("submit", cancelPendingSubmit);
+      window.removeEventListener("popstate", restoreHistoryPrice);
+      cancelPendingSubmit();
+    };
+  }, []);
+
+  function submitAfterTyping(event: React.ChangeEvent<HTMLInputElement>) {
+    if (timer.current) clearTimeout(timer.current);
+    const form = event.currentTarget.form;
+    timer.current = setTimeout(() => {
+      timer.current = null;
+      form?.requestSubmit();
+    }, 350);
+  }
+
   return (
     <>
-      <PriceInput name="filter.v.price.gte" defaultValue={price?.min} label="Minimum price" />
-      <PriceInput name="filter.v.price.lte" defaultValue={price?.max} label="Maximum price" />
+      <PriceInput
+        inputRef={minInput}
+        name="filter.v.price.gte"
+        defaultValue={min}
+        label={`Minimum price in ${currencyCode}`}
+        symbol={symbol}
+        onChange={submitAfterTyping}
+      />
+      <PriceInput
+        inputRef={maxInput}
+        name="filter.v.price.lte"
+        defaultValue={max}
+        label={`Maximum price in ${currencyCode}`}
+        symbol={symbol}
+        onChange={submitAfterTyping}
+      />
     </>
   );
 }
 
-function PriceInput({ name, defaultValue, label }: { name: string; defaultValue?: number; label: string }) {
-  const initialValue = defaultValue == null ? "" : String(defaultValue);
+function PriceInput({
+  inputRef,
+  name,
+  defaultValue,
+  label,
+  symbol,
+  onChange,
+}: {
+  inputRef: React.Ref<HTMLInputElement>;
+  name: string;
+  defaultValue: number | "";
+  label: string;
+  symbol: string;
+  onChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
+}) {
   return (
-    <input
-      type="number"
-      name={name}
-      defaultValue={defaultValue}
-      aria-label={label}
-      min="0"
-      step="any"
-      onBlur={(event) => {
-        if (event.currentTarget.value !== initialValue) {
-          event.currentTarget.form?.requestSubmit();
-        }
-      }}
-      onKeyDown={(event) => {
-        if (event.key === "Enter") {
-          event.preventDefault();
-          event.currentTarget.blur();
-        }
-      }}
-    />
+    <span className="price-input">
+      <span aria-hidden="true">{symbol}</span>
+      <input
+        ref={inputRef}
+        type="number"
+        name={name}
+        defaultValue={defaultValue}
+        aria-label={label}
+        min="0"
+        step="any"
+        onChange={onChange}
+      />
+    </span>
   );
 }
 
@@ -241,7 +346,7 @@ function CheckboxFilterValue({
       type="checkbox"
       name={name}
       value={paramValue}
-      defaultChecked={isFilterInputActive(activeFilters, value.input)}
+      checked={isFilterInputActive(activeFilters, value.input)}
       onChange={(event) => {
         if (isMutuallyExclusive(filter) && event.currentTarget.checked) {
           uncheckSiblings(event.currentTarget);
@@ -253,6 +358,20 @@ function CheckboxFilterValue({
 }
 ```
 
+The symbol prefix sits outside the input, so the submitted value stays a plain number. Keep the wrapper simple so the prefix and input share one line at all widths:
+
+```css
+.price-input {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+}
+
+.price-input input {
+  min-width: 0;
+}
+```
+
 Use `filter.type` only to choose the control shape. For checkbox values, keep `filterValueInputParamEntries` as thin app glue: `JSON.parse(value.input)` plus `serializeCollectionParams(...)`. Do not derive checkbox params from IDs, labels, or filter types.
 
 For active chips, use parsed active `ProductFilter` values from collection state:
@@ -298,4 +417,4 @@ Use the same binding with a synthetic handle:
 </CollectionProvider>
 ```
 
-When the search term changes, include it in the browse form `key` so old unchecked/checked inputs do not carry over.
+Use a stable form identity while filters update, so controls keep focus. Use the submitted search term as the key when the form must reset for a new search. Keep that identity unchanged while the shopper types.

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

@@ -100,6 +100,8 @@ Hydrogen ships no account UI yet — the app owns it. A storefront with the hand
 
 Use `gql` and `createCustomerAccountClient` from `@shopify/hydrogen/customer-account` in server code only. Pass the access token per GraphQL call.
 
+`requestContext.signal`, per-call `signal`, and the client's timeout signal are raced with `AbortSignal.any`. The Next.js edge sandbox does not have it, so an edge route or middleware that calls this client needs an `AbortSignal.any` polyfill installed before the first request.
+
 The same `@shopify/hydrogen/ts-plugin` and `hydrogen gql check` setup from the `hydrogen-storefront-client` skill validates Customer Account API documents too. If the check is not already chained into the app's `typecheck` package script, add it there (create the script if the app has none), then run it before treating setup as complete — framework typecheck commands do not validate `gql()` documents on their own.
 
 ## Local OAuth

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

@@ -4,7 +4,8 @@ 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 and UCP buy permalinks, AJAX cart proxy routes, /admin redirects, Storefront URL redirects,
+  UCP business profiles, 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 +28,15 @@ 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}`, 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()`.
+`handleShopifyRoutes` owns Hydrogen routes the framework should never see: SFAPI proxy URLs, the generic `/__shopify/*` API proxy, `/.well-known/ucp`, `/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`, `/api/ucp/mcp`, `/graphiql` in development, Liquid-style `?variant=<numeric id>` product URLs, and app-registered handler groups such as `createCartServerHandlers()` or `createCustomerAccountServerHandlers()`.
+
+## UCP Business Profile
+
+`GET /.well-known/ucp` serves Shopify's managed UCP business profile from the headless storefront origin; `HEAD` returns the response headers without a body. Hydrogen forwards `If-None-Match` and `If-Modified-Since`, but not shopper cookies or authorization, and preserves `304 Not Modified` responses. Response headers are filtered through the small `UCP_RESPONSE_HEADERS` allowlist in the profile interceptor; upstream `Vary` is omitted because Hydrogen always requests JSON.
+
+Successful profiles and `304` responses use public caching with a 60-second freshness lifetime and a 300-second stale-if-error window. Unpublished profiles return a JSON `404`, and other non-JSON upstream errors become JSON errors with the upstream status. Redirects and non-JSON successes return `502`; fetch timeouts return `504`. All errors use `Cache-Control: no-store`. Methods other than `GET` and `HEAD` continue to framework routing.
+
+Serve the storefront over HTTPS and wire `handleShopifyRoutes` before framework routing so the profile is available without an app-owned route. Return the matched response directly without adding session headers or applying request-context headers again.
 
 ## Variant Id Redirects
 
@@ -96,12 +105,13 @@ import { createCustomerAccountServerHandlers } from "@shopify/hydrogen/customer-
 
 Run the app in dev and production modes, then check:
 
-1. `POST /api/{api-version}/graphql.json` returns Storefront API JSON, not the app 404.
-2. `GET /api/cart` returns cart handler JSON when cart handlers are registered. With no cart id, the body is `{cart: null}` and no Storefront API cart lookup is made.
-3. `GET /api/predictive-search?q=snow` returns predictive search JSON when predictive search handlers are registered.
-4. `GET /account/login`, `GET /account/authorize`, `GET /account/refresh`, and `POST /account/logout` are handled before the app router when Customer Account handlers are registered.
-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, 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.
+1. `GET /.well-known/ucp` returns Shopify's UCP business profile with a public cache policy and no shopper cookies. `HEAD` returns headers without a body. A conditional request with a matching `If-None-Match` returns `304`; an unpublished profile returns an uncached JSON `404`.
+2. `POST /api/{api-version}/graphql.json` returns Storefront API JSON, not the app 404.
+3. `GET /api/cart` returns cart handler JSON when cart handlers are registered. With no cart id, the body is `{cart: null}` and no Storefront API cart lookup is made.
+4. `GET /api/predictive-search?q=snow` returns predictive search JSON when predictive search handlers are registered.
+5. `GET /account/login`, `GET /account/authorize`, `GET /account/refresh`, and `POST /account/logout` are handled before the app router when Customer Account handlers are registered.
+6. `GET /admin` returns a redirect to the shop admin URL.
+7. An unknown path returns the framework 404 when no Shopify redirect exists.
+8. `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.
+9. 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.
+10. Authenticated Customer Account responses do not preserve public or CDN cache-control headers.

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

@@ -60,6 +60,7 @@ What it does **not** do:
 - Server-side analytics dispatch.
 - Third-party destination integrations (GA4, Meta Pixel, Klaviyo) — wire those with `addDestination()`.
 - Cart event publishing without `trackCartAnalytics()`. App code should not manually publish `cart_updated` etc.
+- Forwarding `cart_viewed`, `cart_updated`, or `product_removed_from_cart` to Monorail. They stay on the bus for your own destinations.
 - DOM event ingestion or Standard Events. Explicit `publish()` is the API.
 
 ---
@@ -109,11 +110,11 @@ Resolve shop metadata on the server and pass it to ShopifyScripts. Shopify analy
 
 ### `i18n`
 
-Pass the app's resolved `country` and `language` market values. Optional `currency` sets `window.Shopify.currency.active` for Shopify runtime scripts and Shopify analytics. Shopify analytics reads its content language from `window.Shopify.locale`.
+Pass the app's resolved `country` and `language` market values. Optional `currency` sets `window.Shopify.currency.active` for Shopify runtime scripts and Shopify analytics. For `product_viewed`, Shopify analytics reads the currency from `products[].price.currencyCode`. For `product_added_to_cart`, it reads the cart line's `cost.amountPerQuantity.currencyCode`. Both fall back to `window.Shopify.currency.active`. Page, collection, and search views take only the global. When it is unset, Shopify analytics sends them without a currency. The cart tracker also writes the global from cart cost once a cart exists. Shopify analytics reads its content language from `window.Shopify.locale`.
 
 ### `analytics`
 
-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.
+The analytics bus is enabled by default. Pass `analytics` only when you need optional bus configuration such as `customData`.
 
 ### `consent`
 
@@ -320,7 +321,7 @@ Per-page view events go in the route's `$effect`. The route loader must include
       products: [{
         id: data.product.id,
         title: data.product.title,
-        price: variant?.price.amount ?? data.product.priceRange.minVariantPrice.amount,
+        price: variant?.price ?? data.product.priceRange.minVariantPrice,
         vendor: data.product.vendor,
         variantId: variant?.id ?? data.product.id,
         variantTitle: variant?.title ?? data.product.title,
@@ -386,6 +387,7 @@ Per-page trackers are thin client components that take server-resolved data and
 // app/components/ProductViewedTracker.tsx
 "use client";
 import { useEffect } from "react";
+import type { CurrencyCode } from "@shopify/hydrogen/storefront-api-types";
 import { getAnalytics, AnalyticsEvent } from "../lib/analytics";
 
 type Props = {
@@ -397,10 +399,10 @@ type Props = {
     selectedOrFirstAvailableVariant: {
       id: string;
       title: string;
-      price: { amount: string };
+      price: { amount: string; currencyCode: CurrencyCode };
       sku?: string | null;
     } | null;
-    priceRange: { minVariantPrice: { amount: string } };
+    priceRange: { minVariantPrice: { amount: string; currencyCode: CurrencyCode } };
   };
 };
 
@@ -413,8 +415,8 @@ export function ProductViewedTracker({ product }: Props) {
         id: product.id,
         title: product.title,
         price:
-          product.selectedOrFirstAvailableVariant?.price.amount ??
-          product.priceRange.minVariantPrice.amount,
+          product.selectedOrFirstAvailableVariant?.price ??
+          product.priceRange.minVariantPrice,
         vendor: product.vendor,
         variantId: product.selectedOrFirstAvailableVariant?.id ?? product.id,
         variantTitle:
@@ -482,6 +484,7 @@ const product = await fetchProduct(Astro.params.handle);
     data-title={product.title}
     data-vendor={product.vendor}
     data-price={product.selectedOrFirstAvailableVariant?.price.amount ?? product.priceRange.minVariantPrice.amount}
+    data-currency-code={product.selectedOrFirstAvailableVariant?.price.currencyCode ?? product.priceRange.minVariantPrice.currencyCode}
     data-variant-id={product.selectedOrFirstAvailableVariant?.id ?? product.id}
     data-variant-title={product.selectedOrFirstAvailableVariant?.title ?? product.title}
     data-sku={product.selectedOrFirstAvailableVariant?.sku ?? ""}
@@ -489,6 +492,7 @@ const product = await fetchProduct(Astro.params.handle);
   ></div>
 
   <script>
+    import type { CurrencyCode } from "@shopify/hydrogen/storefront-api-types";
     import { getAnalytics, AnalyticsEvent } from "../../lib/analytics";
     const el = document.getElementById("product-analytics");
     const analytics = getAnalytics();
@@ -497,7 +501,8 @@ const product = await fetchProduct(Astro.params.handle);
         products: [{
           id: el.dataset.id ?? "",
           title: el.dataset.title ?? "",
-          price: el.dataset.price ?? "",
+          // data-* values are strings. This one was rendered from the Storefront API CurrencyCode.
+          price: { amount: el.dataset.price ?? "", currencyCode: el.dataset.currencyCode as CurrencyCode },
           vendor: el.dataset.vendor ?? "",
           variantId: el.dataset.variantId ?? el.dataset.id ?? "",
           variantTitle: el.dataset.variantTitle ?? el.dataset.title ?? "",
@@ -609,6 +614,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.
+- **A product event without a currency logs a warning. Shopify analytics still sends it.** `[shopify:warn:analytics] product_added_to_cart was sent without a currency` means the cart fragment's `cost.amountPerQuantity` has no `currencyCode` and `window.Shopify.currency.active` is unset. Select `currencyCode` in the fragment or pass `i18n.currency`. `product_viewed` cannot reach this warning through the typed `ProductPayload`, whose `price` is `MoneyV2`.
 - **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.
 

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

@@ -6,12 +6,12 @@ Read `package.json` in the current directory.
 
 If it does not exist, stop and tell the user this skill must run in a javascript application with a `package.json` at its root.
 
-If it does not contain `@shopify/hydrogen@preview` (or a more specific hash) in its dependencies, ask the user to install it. Do not assume package managers or install for the user.
+If it does not contain `@shopify/hydrogen` 2026.10.0 or later in its dependencies, ask the user to install it. Do not assume package managers or install for the user.
 
 ### Continue when
 
 - [ ] Current directory has `package.json`
-- [ ] Current project includes `@shopify/hydrogen@preview` or similar in its dependencies
+- [ ] Current project includes `@shopify/hydrogen` 2026.10.0 or later in its dependencies
 
 ## Styling
 

package/skills/hydrogen-setup/steps/6-product-detail-page.md

@@ -207,21 +207,27 @@ export const { ProductProvider, useProduct, useProductForm } =
 Wrap the purchase UI in `ProductProvider`. Put same-product URL navigation in `onSelect`, not inside each option control:
 
 ```tsx
+import { useLocation, useNavigate } from "react-router";
 import { ProductProvider, useProductForm } from "~/lib/product";
+import type { ProductData } from "~/lib/product-query";
 
 export function ProductDetails({ product }: { product: ProductData }) {
-  const navigate = useNavigate(); // or Next.js router.replace
+  const navigate = useNavigate();
+  const location = useLocation();
 
   return (
     <ProductProvider
       product={product}
       onSelect={(result) => {
-        const targetHandle =
-          result.selectedVariant?.product?.handle ?? product.handle;
-        void navigate(variantUrl(targetHandle, result.selectedOptions), {
-          replace: true,
-          preventScrollReset: true,
-        });
+        void navigate(
+          variantUrl(
+            product,
+            result.selectedOptions,
+            result.selectedVariant?.product?.handle,
+            new URLSearchParams(location.search),
+          ),
+          { replace: true, preventScrollReset: true },
+        );
       }}
     >
       <ProductPurchasePanel product={product} />
@@ -230,6 +236,8 @@ export function ProductDetails({ product }: { product: ProductData }) {
 }
 ```
 
+This sample uses React Router. `variantUrl(product, selectedOptions, handle, base)` is the URL builder from the `hydrogen-variant-form` React Router reference. Use the same current-query `base` for option link URLs. In Next.js, use `useRouter().replace` with the `useSearchParams()` base, as the `hydrogen-variant-form` Next.js reference shows.
+
 `useProduct` is for read-only selection state (price, gallery, analytics). `useProductForm` adds form bindings (`register`, `formProps`, `pending`):
 
 ```tsx
@@ -272,8 +280,8 @@ function ProductPurchasePanel({ product }: { product: ProductData }) {
 
 Framework notes:
 
-- Next.js App Router: fetch in the server page; put `ProductProvider` and the form in a `"use client"` component. Use `router.replace(url, { scroll: false })` in `onSelect`.
-- React Router: put URL sync in provider `onSelect`. Same-product option values are GET `<Link>`s that spread `register("optionValue", ...)` (no-JS fallback). Cross-product values use `<Link preventScrollReset>`. See the `hydrogen-variant-form` React reference.
+- Next.js App Router: fetch in the server page; put `ProductProvider` and the form in a `"use client"` component. Use `router.replace(url, { scroll: false })` in `onSelect`. For existing same-product values, render GET links and use `onNavigate` to prevent Link navigation before calling the registered handler. A cross-product combined-listing navigation remounts the page component, so restore focus to the activated value as the `hydrogen-variant-form` Next.js reference shows. A no-JS fallback also requires the product content to render without client-side scripts; a streamed Suspense boundary can prevent this.
+- React Router: put URL sync in provider `onSelect`. Same-product option values are GET `<Link>`s for the no-JS fallback. On an unmodified primary click, prevent Link navigation and call the registered `onClick`; leave modified and other-target clicks alone. Cross-product values use `<Link preventScrollReset>`. See the `hydrogen-variant-form` React Router reference.
 
 ### Vue
 
@@ -394,7 +402,7 @@ const addable = computed(() => canAddToCart(props.product, form.options));
 </template>
 ```
 
-Same-product option values should be `NuxtLink` (or the app's link component) GET links that `v-bind` `form.register('optionValue', ...)`. Cross-product combined-listing values navigate to the other product. See the `hydrogen-variant-form` Nuxt reference.
+For existing same-product option values, use `NuxtLink` custom mode to render a native anchor with its resolved `href`. On an unmodified primary click, prevent the anchor's default navigation and call the registered `onClick`; the provider's `onSelect` owns navigation. Leave modified and other-target clicks alone. Cross-product combined-listing values navigate to the other product without selecting in the current provider. See the `hydrogen-variant-form` Nuxt reference.
 
 ### Other Framework Gotchas
 
@@ -402,6 +410,8 @@ Same-product option values should be `NuxtLink` (or the app's link component) GE
 - Astro: only build this route when the app has server output or a server adapter. Put the interactive product form in a hydrated island or client script that owns the store lifecycle.
 - SolidStart: manage the core store lifecycle inside the client component unless a local binding already exists.
 
+For SolidStart and SvelteKit, render existing same-product options as GET anchors. On an unmodified primary click, prevent default navigation, select through the core store, and navigate once through the existing selection callback. Use the same query-parameter base for the anchor URL and the callback. Leave modified and other-target clicks alone. Keep nonexistent combinations as disabled buttons.
+
 ## Continue when
 
 - [ ] Directly loading `/products/{handle}` renders product data and a selected or first available variant when one exists
@@ -411,6 +421,6 @@ Same-product option values should be `NuxtLink` (or the app's link component) GE
 - [ ] An invalid or failing product query (e.g.: invalid field) logs the GraphQL error server-side and returns 500, not 404
 - [ ] A valid query for a missing product returns 404
 - [ ] Selecting a variant and refreshing the page persists the same variant selected
-- [ ] With javascript disabled, clicking on a variant option navigates to the selected variant
+- [ ] With JavaScript disabled, clicking a variant link loads its selected variant when the product page supports no-JS rendering; record any rendering limitation rather than claim a link alone provides that fallback
 - [ ] Cross-product option values use the framework's client-side link component when the app has one.
 - [ ] The product variants form passes the `hydrogen-variant-form` skill's user acceptance tests.

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

@@ -258,7 +258,7 @@ const { data } = await client.graphql(QUERY);
 const { data } = await client.graphql(QUERY, { signal });
 ```
 
-`requestContext.signal`, per-call `signal`, and the client's timeout signal are raced automatically. At the final response boundary, append committed session headers first, then call `requestContext.applyResponseHeaders(response.headers)`.
+`requestContext.signal`, per-call `signal`, and the client's timeout signal are raced automatically. They are combined with `AbortSignal.any`, which the Next.js edge sandbox does not have, so an edge route or middleware that calls this client needs an `AbortSignal.any` polyfill installed before the first request. At the final response boundary, append committed session headers first, then call `requestContext.applyResponseHeaders(response.headers)`.
 
 Read `references/caching.md` to cache catalog reads across sub-requests on Oxygen-style runtimes.
 

package/skills/hydrogen-storefront-client/references/caching.md

@@ -20,6 +20,8 @@ const { data, errors } = await client.graphql(PRODUCTS, { variables, cache: Cach
 
 **Caching only engages when you pass `cache` per query.** Configuring `cache` on the client alone caches nothing — queries without a `cache` strategy (and all mutations) are never cached.
 
+A stale-while-revalidate refresh runs under `waitUntil` after the caller already has the stale result, so request and per-call aborts don't cancel it. It is bounded by the client's `defaultTimeoutInMs`, or 30 seconds when that is `0`. A custom `runWithCache` passed to `createFetchWithCache` should call `run({ background: true })` for these refreshes so the `backgroundSignal` cache option applies.
+
 ## Never cache private data
 
 Do not pass a `cache` strategy to personalized reads (cart, customer); keep them on a request-scoped client. Cache mode `private` is unsupported — for buyer-specific caching use `createRunWithCache` with an explicit private key.