@shopify/hydrogen 2026.4.5 → 2026.10.0-preview.2

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

@@ -0,0 +1,267 @@
+---
+name: hydrogen-variant-form
+description: >
+  Behavioral guide for building product variant selection UI with
+  @shopify/hydrogen. Use when writing, modifying, or
+  reviewing product option selectors, variant pickers, or add-to-cart forms.
+  Framework agnostic.
+---
+
+# Product Form Primitive
+
+The product form primitive is a client-side store that computes per-option-value existence, availability, and selection state from Shopify's encoded variant fields. Variant selection performs no network requests; it is derived from product data provided by the Storefront API, combined with live cart state for error surfacing and line-item matching. Form submission is delegated to the cart store. Framework-specific bindings are thin wrappers over the core `createProductFormStore`.
+
+## How the store works
+
+The store holds a `ProductFormStoreState` and notifies subscribers on change. It is initialized with a product object and a `CartStore` instance. The product includes `encodedVariantExistence`, `encodedVariantAvailability`, product options (each with `firstSelectableVariant` per option value), a sparse variant cache (`adjacentVariants`), and a nullable `selectedOrFirstAvailableVariant`.
+
+On initialization:
+1. The store uses the encoded fields, when present, to determine which option-value combinations **exist** and which are **available** (in stock). Matching is symmetric: every option value is evaluated against all selected options that belong to the current product option matrix, regardless of option order.
+2. It stitches together the sparse variant cache (`adjacentVariants` + `firstSelectableVariant` per option value + `selectedOrFirstAvailableVariant`) to resolve a concrete `variant` object per option value where possible.
+3. It sets the initial selection from `selectedOrFirstAvailableVariant` (server-resolved), falling back to explicitly provided `selectedOptions`, falling back to empty selection.
+4. It subscribes to the `CartStore` to derive `matchedLineItem` and `errors` reactively.
+
+On `selectOption(name, value)`:
+1. The store validates that the option name and value exist on the product.
+2. It validates that the combination exists when Shopify provides an encoded existence field.
+3. It updates `selectedOptions` and recomputes the full options grid.
+4. It returns a `VariantSelectionResult`: `resolved` (full variant matched), `unresolved` (valid, but no full variant resolved locally), or `invalid` (unknown or non-existent, with a `reason` string).
+
+The store does **not** own URL synchronization or navigation. Add-to-cart mutation logic belongs to the cart store and is reached through `handleFormSubmit(event)`.
+
+## State shape
+
+```ts
+interface ProductFormStoreState<TVariant> {
+  options: VariantOptionState<TVariant>[];
+  selectedOptions: SelectedOption[];
+  selectedVariant: TVariant | null;
+  errors: ProductFormErrors;
+  matchedLineItem: CartLine | null;
+}
+```
+
+`options` is the computed grid — one entry per product option, each containing its values:
+
+- `value.name` — the option value label (e.g. "Red", "Small").
+- `value.selected` — whether this value is part of the current selection.
+- `value.exists` — resolved from `encodedVariantExistence` when present. `false` means no variant exists for the current symmetric selection constraints — the control should be disabled and visually de-emphasized.
+- `value.available` — resolved from `encodedVariantAvailability` when present. `false` means no available variant was found for the current symmetric selection constraints.
+- `value.variant` — the resolved variant object, or `null` if the combination is not in the local cache.
+- `value.selectedOptions` — the full option tuple that would result from selecting this value. Used for URL construction.
+- `value.handle` — the product handle for this variant. Differs from the current product's handle in combined listings.
+
+`selectedOptions` is the current selection in product-option order (e.g. `[{name: "Size", value: "Small"}, {name: "Color", value: "Red"}]`).
+
+`selectedVariant` is the currently resolved variant, or `null` when the selection is incomplete or the variant is not in the local cache.
+
+`errors` surfaces cart errors relevant to this product form:
+- `userErrors` — merged cart-level and line-level user errors for the matched line item.
+- `warnings` — merged cart-level and line-level warnings.
+- `networkErrors` — cart network errors.
+
+`matchedLineItem` is the cart line whose `merchandise.id` matches the selected variant's ID, or `null`.
+
+## Selection results
+
+`selectOption` returns one of three outcomes:
+
+- **`resolved`** — a specific variant was matched. Contains `selectedVariant` with the full variant object and `selectedOptions` with the canonical option tuple from the variant.
+- **`unresolved`** — the selection is valid, but no full variant is resolved locally because the selection is incomplete or the exact variant is absent from the bounded cache. If the buyer has not selected every option yet, ask for the remaining options. If the selection is complete but missing from the local cache, fetch or otherwise resolve the exact variant before treating it as complete.
+- **`invalid`** — the option name or value does not exist on the product, or the combination does not exist per the encoded existence field. State is **not** updated. Contains a `reason` string explaining why the selection was rejected.
+
+## Register API
+
+The `register` function binds product form identity and activation handlers. It covers product-relevant fields. It intentionally does not emit option control UI props like `checked`, `disabled`, or `aria-pressed`; derive those from `options`, `selectedVariant`, and caller-owned state.
+
+### `register("merchandiseId", opts)`
+
+Returns `{ name: "merchandiseId", value: selectedVariantId }`. The `value` is an empty string when no variant is resolved.
+
+### `register("quantity", opts)`
+
+Accepts `{ value: number }` for a controlled input or `{ defaultValue: number }` for an uncontrolled input. Returns the appropriate `{ name, value }` or `{ name, defaultValue }` props, with numeric values stringified for HTML form submission.
+
+### `register("optionValue", opts)`
+
+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("addToCart", opts)`
+
+Returns `{ name: "add-to-cart", type: "submit" }` for the add-to-cart submit button.
+
+## Form submission
+
+`handleFormSubmit(event)` delegates to the underlying `CartStore`'s form submission. The store does not own submission logic — it passes the `SubmitEvent` through to the cart layer, plus selected-product event detail when a variant is resolved. Cart errors from the submission are surfaced reactively via the `errors` state.
+
+## Route Placement
+
+When creating a product detail page, use the app's existing route convention when present; otherwise create `/products/{handle}`. Keep variant selection in query params on that product route.
+
+## Framework References
+
+Before building product UI, check whether this skill has a reference file for the app's framework in `references/`. If one exists, read it and use that framework binding or route pattern first.
+
+If there is no matching reference, use `createProductFormStore` from `@shopify/hydrogen` directly, subscribe with the framework's reactivity primitive, and own hydration, URL sync, and `destroy()` yourself. Packaged bindings are thin wrappers over this same store — apply every rule and anti-pattern below; do not invent a different contract.
+
+## Hydration
+
+When the product data changes (e.g. after a URL navigation triggers a data refetch), the store must be hydrated with the new product — not recreated. `hydrate(product, opts?)` replaces the product data, clears the decoded variant cache, and recomputes state. The new product's `selectedOrFirstAvailableVariant` takes priority; if absent, falls back to explicitly provided `opts.selectedOptions`, then to the selection that was active before hydration.
+
+Provider bindings should hydrate automatically when the product's semantic identity changes (`product.id` + `selectedOrFirstAvailableVariant.id`). They should skip hydration on mount to avoid double-initialization, and skip hydration when the product identity is unchanged — preserving user selections through unrelated re-renders. Standalone `useProductForm(store)` users manage hydration themselves.
+
+## Reset
+
+`reset()` restores the store to its initial state — the product and selected options it was created with. It clears the decoded variant cache and recomputes all derived state. Useful for "reset form" interactions.
+
+## Extracting selected options from the URL
+
+`getSelectedProductOptions({ searchParams, allowedOptionNames })` extracts selected options from `URLSearchParams`. Each query parameter is treated as an option name/value pair (e.g. `?Color=Red&Size=M` produces `[{name:"Color",value:"Red"},{name:"Size",value:"M"}]`).
+
+Pass `allowedOptionNames` to filter search params to only known product option names, avoiding unrelated query parameters. Passing an empty array filters out every option.
+
+The `variant` param is reserved for Liquid-style numeric variant ids and is never treated as an option name. Server-side, `handleShopifyRoutes({ routeTemplates })` (see the local `hydrogen-request-handlers` skill) redirects `?variant=<id>` product URLs to their canonical option-params URL before the loader runs; when both `variant` and option params are present, the variant wins.
+
+## Building selection URLs
+
+`buildProductSelectionSearchParams({ style?, selectedOptions, variant?, optionNames, base? })` builds the search params for a selection link. It always removes the reserved `variant` param and every param named in `optionNames`/`selectedOptions` from `base` before writing the new selection, preserving unrelated params (`?ref=campaign`). Compose it with the app's product pathname:
+
+```ts
+const params = buildProductSelectionSearchParams({
+  selectedOptions: result.selectedOptions,
+  optionNames: product.options.map((option) => option.name),
+  base: new URLSearchParams(location.search),
+});
+const url = `/products/${handle}${params.size ? `?${params}` : ""}`;
+```
+
+Pass `style: "variant"` with a resolved `variant` to emit a shareable `?variant=<numeric id>` link instead of option params. When no variant is resolved (partial selection), the variant style falls back to option params — a variant link is not constructible. Prefer option-params links for in-app navigation; `?variant=` links cost a server redirect on landing.
+
+---
+
+## Rules
+
+- **Hide the entire variant picker when no option has more than one value** (`options.every((o) => o.values.length <= 1)`). A single-variant product has nothing to choose — rendering its one option/one value is noise. This is distinct from the value-hiding rule below: it hides the *whole picker* when there's nothing to choose, not individual values based on selection.
+
+### Existence and availability
+
+- **Availability and existence are symmetric.** Selecting a later option can make earlier option values unavailable or non-existent. For example, if `Medium / Olive` is sold out, selecting `Color=Olive` should mark `Size=Medium` as unavailable even though `Medium / Green` is available.
+- **ALWAYS disable and visually de-emphasize option values where `exists` is `false`.** These represent combinations that do not exist in the product's variant matrix. A non-existent combination cannot be selected — showing it as interactive is misleading.
+- **NEVER disable option values where `exists` is `true` but `available` is `false`.** These are sold-out variants. The control must remain interactive so the buyer can see what the variant would be. Show a "Sold out" indicator instead, such as opacity plus line-through styling.
+- **NEVER hide option values based on the current selection.** All values for an option must always be visible. Hiding values based on what's currently selected creates a confusing, collapsing UI that prevents buyers from exploring the full product matrix.
+
+### Selection and navigation
+
+- **With provider bindings, put URL navigation in the provider `onSelect` callback.** Do not navigate inside each same-product option button. Let `register("optionValue", ...)` call `selectOption`; the provider receives the valid selection result and owns URL sync from there.
+- **ALWAYS use URL-based variant selection in URL-routing apps.** When the buyer selects an option, navigate to the URL representing that selection — replacing the history entry and without resetting scroll position. The URL is the durable source of truth — the data loader reads the selection from the URL, queries the Storefront API, and the response hydrates the store when a reload or revalidation happens.
+- **Same-product option values must degrade to GET links (no JS).** In URL-routing apps, render each same-product option value as a real link (the framework's link component or `<a href>`) whose `href` is the option URL for that value, built from `value.selectedOptions` — not a bare `<button onClick>`. The `href` is the no-JS path: with scripting off, activating it issues a GET to the option URL, the loader reads the params, queries the Storefront API, and the server renders the newly selected variant. Hydration enhances the same element — the registered `register("optionValue", ...)` handler calls `selectOption` and the provider's `onSelect` replaces the URL client-side (no full reload). Because the `href` and the client navigation resolve to the same option URL, behavior is identical with or without JS. On a hydrated click the element both runs the registered handler (which calls `selectOption`) and performs its own link navigation to that same URL, so keep the provider `onSelect` idempotent — the redundant navigation is a harmless no-op. An option control that is button-/`onClick`-only renders nothing a no-JS shopper can act on, stranding them on the default variant. Non-existent combinations (`exists: false`) have no valid option URL to degrade to; render those as a disabled `<button>`, not a link. (Cross-product values are already links; this brings same-product values to parity.)
+- **ALWAYS use the `selectOption` return value for navigation, not a reactive effect on state.** `selectOption` returns the result synchronously. Use the returned `selectedOptions` to construct the next URL immediately. Reacting to derived state (e.g. `selectedOptions` from the store) instead introduces an unnecessary update cycle and risks stale values. Framework bindings may wrap this as an `onSelect` callback — the principle is the same.
+- **Skip data refetch only when the resolved local state is sufficient.** When `selectOption` returns `resolved`, the selected variant is already in the local cache. It is safe to skip revalidation only if the route does not need fresh loader data for other UI. When a complete selection returns `unresolved`, fetch or otherwise resolve the exact variant before treating the selection as complete.
+- **NEVER call `selectOption` for combined-listing cross-product values.** When `value.handle !== product.handle`, the value belongs to a different product. Render it as a navigation element (anchor or link component) that navigates to the other product's URL — not a button that calls `selectOption`. The store only knows about the current product's variant matrix.
+
+### Combined listings
+
+- **ALWAYS check `value.handle` against the current `product.handle`.** If they differ, the option value points to a different product in a combined listing. The UI must navigate to that product (full page navigation or a link component), not call `selectOption`.
+- **Use the framework's client-side link component for cross-product values when one exists.** Use the app's idiomatic navigation primitive. Use a raw `<a>` only when that is the app's established routing convention.
+- **Preserve non-option query params on combined-listing links.** When constructing the URL for a combined-listing link, carry forward existing search params (e.g. `?ref=campaign`) and replace only the option params. Use `buildProductSelectionSearchParams` with the current product's option names as `optionNames` — it deletes all option params (and any stale `variant` param) first, then sets the new ones, preventing stale params when combined-listing products have different option names.
+- **Ignore selected options that are not in the current product option matrix.** Divergent combined-listing child products can have different option names. A stale `Color=Black` param must not constrain a child product whose options are `Size` and `Mount`.
+
+### Price display
+
+- **ALWAYS display server-provided prices.** Use `selectedVariant.price` when a variant is resolved. Fall back to `product.priceRange.minVariantPrice` when no variant is selected. Never compute prices client-side.
+- **Format with Hydrogen money helpers**, not string concatenation. Use the local `hydrogen-money` skill for app wrappers around `formatMoney()`.
+
+### 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.
+- **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.
+
+### Store lifecycle
+
+- **Create the store once per component mount.** Do not recreate the store when the product prop changes — use `hydrate()` instead. Recreating the store discards the decoded variant cache and any user interaction state.
+- **Always call `destroy()` on unmount.** This unsubscribes from the `CartStore` and releases internal caches (the decoded variant field cache). Provider bindings handle this automatically; standalone store users must do it themselves.
+- **Do not read stale state after hydration.** Hydration triggers a synchronous state update. Any code that caches the previous state reference before hydration holds a stale reference.
+
+### Accessibility
+
+- **Communicate selected state with the attribute that fits the element.** Same-product and cross-product option values render as links (per the GET-links and combined-listing rules), so mark the selected one with `aria-current` — `aria-pressed` is not a valid state on a link. Reserve `aria-pressed={value.selected}` for values rendered as a `<button>`, chiefly the disabled non-existent (`exists: false`) case. Derive either from the matching option value's `selected` state.
+- **Use `aria-label` on visual-only controls** (e.g. color swatches without visible text).
+- **Disabled controls (`exists: false`) must use the native `disabled` attribute** — not `aria-disabled` with prevented clicks. Non-existent combinations are truly non-interactive.
+
+---
+
+## User Acceptance Tests
+
+### Initial state
+
+1. **Pre-selected variant** — When the product has a `selectedOrFirstAvailableVariant`, the corresponding option values are marked as selected on first render. The variant's price and details are displayed. `selectedVariant` on the state is non-null.
+2. **No pre-selected variant** — When `selectedOrFirstAvailableVariant` is `null`, no option values are selected. `selectedVariant` is `null`. The add-to-cart button shows "Select options" (or equivalent) and is disabled.
+3. **URL-driven selection** — When the URL encodes a variant selection (e.g. via option params like `?Color=Blue&Size=Small`), the data loader resolves the selection and passes it to the Storefront API query. The returned `selectedOrFirstAvailableVariant` reflects the URL selection, and the store initializes with those options selected.
+
+### Option selection
+
+4. **Select a value** — Click an option value button. The value becomes selected (visually indicated). If the selection resolves to a variant, the price and variant details update immediately. `selectedVariant` updates on the state. In URL-routing apps, the URL updates to reflect the new selection without a scroll reset.
+5. **Multi-option selection** — On a product with Size and Color options, select Size=Large then Color=Blue. Both selections are reflected in the state. The resolved variant matches Large/Blue.
+6. **Symmetric availability** — On a product where Medium/Olive is unavailable but Medium/Green is available, selecting Color=Olive marks Size=Medium as `available: false`; selecting Color=Green marks Size=Medium as `available: true`.
+7. **Switch within an option** — With Color=Red selected, click Color=Blue. The selection switches; Red is deselected, Blue is selected. Only one value per option is selected at a time.
+8. **Invalid selection ignored** — Calling `selectOption` with an unknown option name or value returns `invalid` with a `reason` string and does not change state. No navigation occurs.
+9. **Non-existent combination** — An option value where `exists: false` is disabled. Clicking it does nothing.
+10. **Sold-out variant** — An option value where `exists: true` and `available: false` is interactive but shows a "Sold out" indicator. Selecting it updates the state and shows the variant as unavailable.
+
+### Combined listings
+
+11. **Cross-product value** — An option value where `value.handle !== product.handle` renders as a navigation element (anchor or link component), not a button. Clicking it navigates to the other product's page with the appropriate option params.
+12. **Same-product value** — An option value where `value.handle === product.handle` renders as a GET link to its option URL and spreads `register("optionValue", ...)`. With JavaScript disabled the link navigates and the server resolves the variant; hydrated, the registered handler calls `selectOption` and the provider syncs the URL client-side.
+13. **Preserved params** — When navigating via a combined-listing link, non-option query params from the current URL are preserved in the destination URL.
+
+### Hydration
+
+14. **Product navigation** — Navigating from Product A to Product B (different `product.id`) hydrates the store with Product B's data. The selection reflects Product B's `selectedOrFirstAvailableVariant`.
+15. **Same product, different variant** — Navigating to the same product with a different URL-encoded selection (e.g. `?Color=Blue` instead of `?Color=Red`) hydrates with the new pre-selected variant without recreating the store.
+16. **Unrelated re-render** — A re-render that passes the same product identity does not hydrate. User selections made since the last hydration are preserved.
+17. **No double-init on mount** — On initial mount, the store initializes from the constructor — hydration does not fire. A user selection made immediately after mount survives a subsequent re-render with the same product.
+
+### Cart integration
+
+18. **Matched line item** — When the selected variant's ID matches a cart line's `merchandise.id`, `matchedLineItem` is non-null and contains the cart line data.
+19. **Cart error surfacing** — After a failed add-to-cart submission, `errors.userErrors` contains the relevant user errors, `errors.warnings` contains warnings, and `errors.networkErrors` contains any network failures.
+20. **Reactive cart sync** — When the cart updates externally (e.g. quantity change from a cart drawer), the `matchedLineItem` and `errors` update without any manual intervention.
+
+### Add-to-cart
+
+21. **Enabled state** — When `canAddToCart` returns `true` (variant selected, available, no selling plan required), the add-to-cart button is enabled and shows "Add to cart".
+22. **Disabled — no variant** — When no variant is selected, the button is disabled with "Select options" text unless navigation or submission is actually pending.
+23. **Disabled — sold out** — When the selected variant is not available for sale, the button is disabled with "Unavailable" or "Sold out" text.
+24. **Disabled — selling plan required** — When `product.requiresSellingPlan` is `true`, the button is disabled regardless of variant selection.
+25. **Variant ID in form** — `register("merchandiseId", {})` returns `{ name: "merchandiseId", value: selectedVariantId }`. When no variant is selected, `value` is an empty string.
+26. **Form submission** — `handleFormSubmit(event)` delegates to the cart store with the submit event and selected-product detail when a variant is resolved. Cart errors surface reactively via the `errors` state.
+
+### Register API
+
+27. **Option value registration** — `register("optionValue", { optionName: "Color", value: "Red" })` returns `{ name, value, onChange, onClick }`. Calling `onChange` or `onClick` triggers `selectOption`.
+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" }`.
+
+### 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.
+
+### 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.
+
+---
+
+## Anti-patterns
+
+- **Using reactive effects on state to sync selection to URL.** The `selectOption` return value provides the selection result synchronously. Reacting to `state.selectedOptions` instead introduces an extra update cycle and can fire with stale values.
+- **Navigating inside same-product option buttons.** Do not destructure `onClick` / `onChange` from `register("optionValue", ...)`, call `navigate()`, and then call the registered handler manually. This bypasses the provider `onSelect` contract and can navigate from stale or invalid data.
+- **Button-/onClick-only same-product option values.** A same-product option value rendered as `<button onClick={selectOption}>` with no `href` is dead without JavaScript — a no-JS shopper cannot switch variants and is stuck on the default. Render it as a GET link to the option URL and let the registered handler enhance it; the `href` is the progressive-enhancement fallback.
+- **Using raw anchors when the framework has a client-side link component.** Raw `<a>` tags lose client-router behavior such as scroll preservation, pending navigation state, prefetching, and route transitions. Use the app's established link component unless raw anchors are the framework convention.
+- **Putting variant selection inside the add-to-cart form.** Variant selection is button/link interactions that update store state. The add-to-cart form submits `merchandiseId` and `quantity` to the cart. Mixing them creates ambiguous form semantics and breaks progressive enhancement.
+- **Ignoring `errors` state after form submission.** Cart user errors, warnings, and network errors are surfaced reactively on the store state. Failing to display these leaves the buyer with no feedback when something goes wrong.

package/skills/hydrogen-variant-form/references/nextjs.md

@@ -0,0 +1,207 @@
+# Next.js App Router
+
+## Contents
+
+- Server Page
+- Client Details Component
+- Same-Product And Cross-Product Values
+- Add To Cart
+
+Product data is fetched in the server page. Variant selection and add-to-cart live in a `"use client"` component because they use `ProductProvider`, browser routing, and cart forms.
+
+## Server Page
+
+In `app/products/[handle]/page.tsx`, read selected options from URL search params and query Storefront API with Hydrogen's product fields:
+
+```tsx
+import { getSelectedProductOptions, gql } from "@shopify/hydrogen";
+
+export const PRODUCT_QUERY = gql(`
+  query Product($handle: String!, $selectedOptions: [SelectedOptionInput!]!) {
+    product(handle: $handle) {
+      id
+      handle
+      title
+      vendor
+      requiresSellingPlan
+      encodedVariantExistence
+      encodedVariantAvailability
+      options {
+        name
+        optionValues {
+          name
+          firstSelectableVariant {
+            id
+            title
+            availableForSale
+            selectedOptions { name value }
+            price { amount currencyCode }
+            compareAtPrice { amount currencyCode }
+            product { handle title }
+            sku
+          }
+          swatch { color image { previewImage { url } } }
+        }
+      }
+      selectedOrFirstAvailableVariant(
+        selectedOptions: $selectedOptions
+        ignoreUnknownOptions: true
+        caseInsensitiveMatch: true
+      ) {
+        id
+        title
+        availableForSale
+        selectedOptions { name value }
+        price { amount currencyCode }
+        compareAtPrice { amount currencyCode }
+        product { handle title }
+        sku
+      }
+      adjacentVariants(
+        selectedOptions: $selectedOptions
+        ignoreUnknownOptions: true
+        caseInsensitiveMatch: true
+      ) {
+        id
+        title
+        availableForSale
+        selectedOptions { name value }
+        price { amount currencyCode }
+        compareAtPrice { amount currencyCode }
+        product { handle title }
+        sku
+      }
+      priceRange {
+        minVariantPrice { amount currencyCode }
+      }
+    }
+  }
+`);
+
+export default async function ProductPage({ params, searchParams }: Props) {
+  const { handle } = await params;
+  const selectedOptions = getSelectedProductOptions({
+    searchParams: toURLSearchParams(await searchParams),
+  });
+  const storefront = await getStorefrontClient();
+  const { data } = await storefront.graphql(PRODUCT_QUERY, {
+    variables: { handle, selectedOptions },
+  });
+  if (!data?.product) notFound();
+  return <ProductDetails product={data.product} />;
+}
+
+function toURLSearchParams(input: Record<string, string | string[] | undefined>) {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(input)) {
+    if (Array.isArray(value)) {
+      for (const item of value) params.append(key, item);
+    } else if (value != null) {
+      params.set(key, value);
+    }
+  }
+  return params;
+}
+```
+
+Use the route's existing search-param normalization helper if present.
+
+## Client Details Component
+
+```tsx
+"use client";
+
+import { canAddToCart, type SelectedOption, type StorefrontApi } from "@shopify/hydrogen";
+import { createProductComponents } from "@shopify/hydrogen/react";
+import { useRouter, useSearchParams } from "next/navigation";
+import type { PRODUCT_QUERY } from "../products/[handle]/page";
+
+type ProductQuery = StorefrontApi.ResultOf<typeof PRODUCT_QUERY>;
+type ProductData = NonNullable<ProductQuery["product"]>;
+
+const { ProductProvider, useProductForm } = createProductComponents<ProductData>();
+
+export function ProductDetails({ product }: { product: ProductData }) {
+  const router = useRouter();
+  const searchParams = useSearchParams();
+
+  return (
+    <ProductProvider
+      product={product}
+      onSelect={(result) => {
+        router.replace(
+          variantUrl(product, result.selectedOptions, result.selectedVariant?.product?.handle, searchParams),
+          { scroll: false },
+        );
+      }}
+    >
+      <VariantSelector product={product} />
+      <AddToCart product={product} />
+    </ProductProvider>
+  );
+}
+```
+
+Wrap this tree in the app's `CartProvider` from `hydrogen-cart-ui`; `ProductProvider` reads the cart store for add-to-cart submission and product-scoped cart errors.
+
+## Same-Product And Cross-Product Values
+
+Render same-product option values as GET links (`next/link`) so variant selection degrades without JavaScript (the skill's GET-links rule and accessibility guidance cover the `aria-current`, idempotent-`onSelect`, and no-JS rationale). The `href` is the option URL built from `value.selectedOptions`; spread `register("optionValue", ...)` to enhance the link so a hydrated click selects client-side via the provider's `onSelect`. Keep sold-out-but-existing values interactive and derive their visual treatment from `value.available`. Render non-existent combinations (`exists: false`) as a disabled `<button>` instead of a link.
+
+```tsx
+<Link
+  href={variantUrl(product, value.selectedOptions, value.handle, searchParams)}
+  replace
+  scroll={false}
+  aria-current={value.selected ? "true" : undefined}
+  data-available={value.available ? "true" : "false"}
+  {...register("optionValue", { optionName: option.name, value: value.name })}
+>
+  {value.name}
+  {!value.available ? <span className="sr-only"> (Sold out)</span> : null}
+</Link>
+```
+
+Cross-product combined-listing values point at a different `value.handle` and navigate to that product. Prefer `next/link`; if using a button for cross-product navigation, keep it clearly outside the add-to-cart form and call `router.replace(...)`. Both use the same URL helper:
+
+```tsx
+import { buildProductSelectionSearchParams, type SelectedOption } from "@shopify/hydrogen";
+
+function variantUrl(
+  product: { handle: string; options: Array<{ name: string }> },
+  selectedOptions: SelectedOption[],
+  handle = product.handle,
+  base: URLSearchParams | ReturnType<typeof useSearchParams> = new URLSearchParams(),
+) {
+  const params = buildProductSelectionSearchParams({
+    selectedOptions,
+    optionNames: product.options.map((option) => option.name),
+    base: new URLSearchParams(base),
+  });
+  const query = params.toString();
+  return `/products/${handle}${query ? `?${query}` : ""}`;
+}
+```
+
+## Add To Cart
+
+Use the local `hydrogen-shop-pay` skill when adding Shop Pay. Use the local `hydrogen-money` skill for prices.
+
+Do not put option controls inside the add-to-cart form. The form submits `merchandiseId` and `quantity`; option controls are buttons/links outside it. Register the submit button with `addToCart`.
+
+```tsx
+function AddToCart({ product }: { product: ProductData }) {
+  const { options, register, formProps, pending } = useProductForm();
+  const addable = canAddToCart(product, options);
+
+  return (
+    <form {...formProps({ beforeSubmit: openCartDrawer })}>
+      <input type="hidden" {...register("merchandiseId", {})} />
+      <input {...register("quantity", { value: 1 })} />
+      <button {...register("addToCart", {})} disabled={!addable || pending}>
+        Add to cart
+      </button>
+    </form>
+  );
+}
+```

package/skills/hydrogen-variant-form/references/nuxt.md

@@ -0,0 +1,95 @@
+# Nuxt
+
+Use `@shopify/hydrogen/vue` product bindings. Server page data resolves the selected variant from URL query params; client components own option interaction and add-to-cart.
+
+## Storefront Module
+
+```ts
+// storefront/product.ts
+import { createProductComponents } from "@shopify/hydrogen/vue";
+import type { ProductData } from "./product-types";
+
+export const { ProductProvider, useProductForm } = createProductComponents<ProductData>();
+```
+
+`ProductData` is app-owned. It must include Hydrogen's product form fields: `id`, `handle`, `title`, `options`, `selectedOrFirstAvailableVariant`, `adjacentVariants`, `encodedVariantExistence`, `encodedVariantAvailability`, `requiresSellingPlan`, and variant `price`/`availableForSale` fields used by the UI.
+
+Wrap this tree in the app's `CartProvider` from `hydrogen-cart-ui`; `ProductProvider` reads the cart store for add-to-cart submission and product-scoped cart errors.
+
+## Page
+
+In `pages/products/[handle].vue`, pass selected options from `getSelectedProductOptions({searchParams})` into the Storefront API query. Use one reusable variant fragment for `firstSelectableVariant`, `selectedOrFirstAvailableVariant`, and `adjacentVariants`; it must include variant `price`, `availableForSale`, `selectedOptions`, and `product { handle title }` so price display and combined-listing navigation work. Use the injected server/client Storefront client from the Nuxt storefront-client recipe.
+
+Wrap the UI:
+
+```vue
+<template>
+  <ProductProvider
+    :product="product"
+    :on-select="
+      (result) =>
+        navigateTo(variantRoute(result.selectedOptions, result.selectedVariant?.product?.handle), {
+          replace: true,
+        })
+    "
+  >
+    <ProductVariantSelector :product="product" />
+    <ProductAddToCart :product="product" />
+  </ProductProvider>
+</template>
+```
+
+## Variant Selector
+
+Same-product option values are GET links (`NuxtLink`) so selection degrades without JavaScript; non-existent combinations render as a disabled `<button>`, and cross-product combined-listing values are also links. The skill's GET-links rule and accessibility guidance cover the `aria-current`, idempotent-`onSelect`, and no-JS rationale:
+
+```vue
+<!-- cross-product: navigate to a different product -->
+<NuxtLink
+  v-if="value.handle !== product.handle"
+  :to="variantRoute(value.selectedOptions, value.handle)"
+  replace
+>
+  {{ value.name }}
+</NuxtLink>
+
+<!-- same-product, non-existent combination: no option URL to degrade to -->
+<button
+  v-else-if="!value.exists"
+  type="button"
+  disabled
+  :aria-pressed="value.selected"
+>
+  {{ value.name }}
+</button>
+
+<!-- same-product, existing value: GET link enhanced by the registered handler -->
+<NuxtLink
+  v-else
+  :to="variantRoute(value.selectedOptions, value.handle)"
+  replace
+  :aria-current="value.selected ? 'true' : undefined"
+  v-bind="form.register('optionValue', { optionName: option.name, value: value.name })"
+>
+  {{ value.name }}
+  <template v-if="!value.available"> - Sold out</template>
+</NuxtLink>
+```
+
+Build route query objects with `buildProductSelectionSearchParams`, passing the product option names as `optionNames`. Convert Nuxt's current route query to `URLSearchParams` for `base` by appending every scalar or array value, then convert the returned params back to a Nuxt query object while preserving repeated keys. This preserves non-option params while removing stale option params and the reserved `variant` param.
+
+## Add To Cart
+
+```vue
+<form v-bind="form.formProps({ beforeSubmit: openCartDrawer })">
+  <input type="hidden" v-bind="form.register('merchandiseId', {})" />
+  <input v-bind="form.register('quantity', { value: quantity })" />
+  <button v-bind="form.register('addToCart', {})" :disabled="!addable || form.pending.value">
+    Add to cart
+  </button>
+</form>
+```
+
+`addable` must use `canAddToCart(product, form.options)`.
+
+Use the local `hydrogen-shop-pay` skill for Shop Pay and `hydrogen-money` for price formatting.

package/skills/hydrogen-variant-form/references/react.md

@@ -0,0 +1,71 @@
+# React Product Bindings
+
+Create typed React product bindings once from `@shopify/hydrogen/react`, usually in a shared product module:
+
+```ts
+import { createProductComponents } from "@shopify/hydrogen/react";
+import type { ProductData } from "./types";
+
+export const { ProductProvider, useProductForm } =
+  createProductComponents<ProductData>();
+```
+
+Use the provider's `onSelect` callback for same-product URL sync:
+
+```tsx
+<ProductProvider
+  product={product}
+  onSelect={(result) => {
+    void navigate(
+      toRouterLocation(
+        variantUrl(product, result.selectedOptions, result.selectedVariant?.product?.handle),
+      ),
+      {
+        replace: true,
+        preventScrollReset: true,
+      },
+    );
+  }}
+>
+  <ProductPurchasePanel product={product} />
+</ProductProvider>
+```
+
+If a route should skip loader revalidation for locally resolved selections, use the framework's supported route-level revalidation API. Do not pass unsupported revalidation flags to `navigate()`.
+
+Same-product option values are GET links so selection works without JavaScript (the skill's GET-links rule and accessibility guidance cover the `aria-current`, idempotent-`onSelect`, and no-JS rationale). The `to` is the option URL built from `value.selectedOptions`; spreading the registered handlers enhances the link so a hydrated click selects client-side through the provider's `onSelect`. Keep sold-out-but-existing values interactive and derive their visual treatment from `value.available`:
+
+```tsx
+<Link
+  to={toRouterLocation(variantUrl(product, value.selectedOptions, value.handle))}
+  replace
+  preventScrollReset
+  aria-current={value.selected ? "true" : undefined}
+  data-available={value.available ? "true" : "false"}
+  {...register("optionValue", { optionName: option.name, value: value.name })}
+>
+  {value.name}
+  {!value.available ? <span className="sr-only"> (Sold out)</span> : null}
+</Link>
+```
+
+Non-existent combinations (`exists: false`) render as a disabled `<button>` instead of a `<Link>`:
+
+```tsx
+<button type="button" disabled aria-pressed={value.selected}>
+  {value.name}
+</button>
+```
+
+Cross-product option values are framework links that reuse the same URL helper:
+
+```tsx
+<Link
+  to={toRouterLocation(variantUrl(product, value.selectedOptions, value.handle))}
+  preventScrollReset
+  data-available={value.available ? "true" : "false"}
+>
+  {value.name}
+  {!value.available ? <span className="sr-only"> (Sold out)</span> : null}
+</Link>
+```