@shopify/hydrogen 2026.4.5 → 2026.10.0-preview.2

package/skills/hydrogen-setup/steps/7-shopify-runtime-scripts.md

@@ -0,0 +1,69 @@
+# Shopify Runtime Scripts
+
+## Install Shopify Runtime Scripts
+
+Render Shopify runtime scripts once in the root document.
+
+- Use the `ShopifyScripts` component from your framework binding if it exports one. Frameworks without a binding should render `getShopifyScriptTags()` / `renderShopifyScriptTags()` during SSR and call `initializeShopifyScripts()` during browser hydration.
+- Invoke the `hydrogen-routing` skill for the required script routing options; reuse the shared route template manifest from the scaffold step.
+
+### The `shop` and `i18n` props
+
+Build both in a server-only module, annotated with the types exported from `@shopify/hydrogen`, so TypeScript rejects wrong or missing fields at the declaration — not at the distant `ShopifyScripts` call site:
+
+```ts
+import type { ShopifyScriptsI18n, ShopifyScriptsShop } from "@shopify/hydrogen";
+
+const shop: ShopifyScriptsShop = {
+  shopId: env.SHOP_ID,
+  storefrontId: env.PUBLIC_STOREFRONT_ID || "0",
+  myshopifyDomain: env.PUBLIC_STORE_DOMAIN,
+};
+
+const i18n: ShopifyScriptsI18n = {
+  country, // resolved market country, e.g. "US"
+  language, // resolved market language, e.g. "EN"
+};
+```
+
+All three `shop` fields are required and identify different things:
+
+- `shopId` — the **shop** itself: the numeric Shopify shop ID (or Shop GID `gid://shopify/Shop/{id}`). Same shop as the Customer Account API `SHOP_ID`. Shopify analytics attributes events to it.
+- `storefrontId` — the specific **headless/Hydrogen storefront instance** attached to the shop. A shop can have several storefronts; analytics and PerfKit use this ID to attribute traffic to this one. Use `"0"` when the app has no provisioned storefront ID.
+- `myshopifyDomain` — the shop's permanent `*.myshopify.com` domain, exposed as `window.Shopify.shop`.
+
+`i18n` is the same resolved market used by Storefront API requests (`country` + `language`, optional `currency`) — not a locale string, and not the analytics consent config.
+
+For vanilla browser code that does not use SSR or a framework head API, render the HTML from core and include it in the document shell. If your app renders tags through core helpers instead of a framework binding, call `initializeShopifyScripts()` from bundled client code:
+
+```ts
+import { initializeShopifyScripts, renderShopifyScriptTags } from "@shopify/hydrogen";
+import { routeTemplates } from "./route-templates";
+
+const tags = renderShopifyScriptTags({ i18n, shop });
+initializeShopifyScripts({ routes: routeTemplates });
+```
+
+### Continue when
+
+- [ ] The Shopify script tags appear exactly once in the server-rendered document (check view-source, not just the hydrated DOM)
+- [ ] `window.Shopify.actions` is defined in the browser console after page load
+- [ ] `shop` values (`shopId`, `storefrontId`, `myshopifyDomain`) are resolved server-side and serialized; no client module reads `process.env`, `import.meta.env`, or framework env modules
+
+## Configure Shopify Navigation
+
+When Shopify or Hydrogen browser utilities need to navigate through the framework router, set the top-level navigation hook. WebMCP is one consumer of this hook. Pass `navigate={navigate}` to the framework `ShopifyScripts` component when the router hook is available there, or call `initializeShopifyScripts()` from client code when scripts are rendered through core helpers or a framework head API:
+
+```ts
+import { initializeShopifyScripts } from "@shopify/hydrogen";
+import { routeTemplates } from "./route-templates";
+
+initializeShopifyScripts({ routes: routeTemplates, navigate: (url) => router.push(url) });
+```
+
+Use the framework's normal client lifecycle primitive when the app is already bundling frontend code, such as a mounted hook, client-only effect, or processed browser script.
+
+### Continue when
+
+- [ ] The navigation hook is wired through the framework router (`navigate` prop on `ShopifyScripts`, or the `navigate` option of `initializeShopifyScripts()`)
+- [ ] Navigation triggered through the hook performs client-side routing without a full page reload

package/skills/hydrogen-setup/steps/8-cart-drawer-and-navbar.md

@@ -0,0 +1,35 @@
+# Cart Drawer And Navbar
+
+## Add The Cart Drawer
+
+Invoke the `hydrogen-cart-drawer` skill to render an accessible cart drawer once in the root layout. Keep the `/cart` route as the full-page fallback when the drawer is unavailable, wire the drawer's Standard Actions `openCart` handler, and preserve the `hydrogen-cart-ui` progressive line item form contract in drawer content.
+
+The drawer's `openCart` handler depends on the Shopify runtime scripts installed in the previous step; `window.Shopify.actions` must exist before the drawer's Standard Actions wiring can work.
+
+### Continue when
+
+- [ ] The drawer renders once in the root layout and can open on every page
+- [ ] `window.Shopify.actions.openCart()` opens the drawer from the browser console
+- [ ] Adding a product to cart opens the drawer and shows the added line item
+- [ ] Drawer line item forms use the same `hydrogen-cart-ui` progressive form contract as the `/cart` page
+- [ ] The drawer passes the `hydrogen-cart-drawer` skill's verification checklist
+
+## Build The Navbar
+
+Create or update the shared site navigation. Do this after the cart drawer, so the cart trigger can follow the drawer's markup contract.
+
+### Requirements
+
+- Preserve the app's existing layout component and styling conventions. Do not remove existing navigation items unless they directly conflict with the setup.
+- Ensure a home link exists, if not, make one and point to `/`.
+- Every navbar link must resolve: the route must exist in the app, and dynamic destinations (collection or page handles) must exist in the shop. Do not invent handles. In particular, do not link to `/collections/all` — the "all" collection is a Liquid storefront convention with no Storefront API equivalent; `collection(handle: "all")` returns null and the route 404s unless the merchant explicitly created a collection with that handle. For a browse-everything destination link to the `/collections` listing route or `/search`; for specific collections use handles returned by the Storefront API (e.g. from the home page collections query).
+- The cart trigger is a `/cart` anchor that opens the drawer via `showModal()` after hydration; follow the `hydrogen-cart-drawer` skill for the markup.
+- Make `/cart` reachable as a real link in the **footer** (site chrome). `/cart` is the full-page fallback when the cart drawer is unavailable. For strict no-JS live cart HTML, the cart route must receive resolved cart `initialData`.
+- Use the framework's native link component when one is already used in the app.
+- Keep the navbar server-renderable unless the app already uses a client-only navigation shell.
+- Do not block the response by waiting for the cart contents to load.
+
+### Continue when
+
+- [ ] The navbar appears on the home, collection, product, and cart routes
+- [ ] Every navbar and footer link href returns a 200 when requested directly against the dev server (`curl -s -o /dev/null -w "%{http_code}" http://localhost:<port><href>` for each one) — no 404s, no invented collection handles

package/skills/hydrogen-setup/steps/9-account-page.md

@@ -0,0 +1,54 @@
+# Account Page
+
+Create a minimal server-rendered account page and wire it into the navbar. The scaffold step already registered the Customer Account handlers (`/account/login`, `/account/authorize`, `/account/refresh`, `/account/logout`); those are server routes, not UI. This step builds the app-owned UI on top of them: without it the storefront has working auth endpoints and no way for a buyer to see their account or log out.
+
+Invoke the `hydrogen-customer-account` skill for the session/token rules (read-only vs writable session managers, `isLoggedIn()` vs `getAccessToken()`, the one-shot refresh redirect) and follow its Account Page section for the UI contract.
+
+## Requirements
+
+- **Navbar account link.** Add an `/account` link to the navbar. A static link is enough — the account page handles both signed-in and signed-out states. Do not block navbar rendering on session reads.
+- **`/account` route**, server-rendered:
+  - Signed out: render a sign-in panel with a link to `/account/login?return_to=/account`. The login link must be a full-document navigation (plain `<a>` or the framework link's reload-document mode) — the login handler returns a raw redirect to Shopify's hosted login page that client-side routing cannot follow.
+  - Signed in: fetch a minimal profile with the Customer Account API and render it:
+
+    ```ts
+    import { gql } from "@shopify/hydrogen/customer-account";
+
+    const CUSTOMER_QUERY = gql(`
+      query CurrentCustomer {
+        customer {
+          firstName
+          lastName
+          emailAddress {
+            emailAddress
+          }
+        }
+      }
+    `);
+    ```
+
+  - Check GraphQL `errors` and render an error state; a failing Customer Account call must not crash the route.
+- **Logout button.** Render a plain HTML form — not the framework's client-side form component:
+
+  ```html
+  <form method="post" action="/account/logout">
+    <button type="submit">Log out</button>
+  </form>
+  ```
+
+  The logout handler requires a same-origin POST and returns a raw redirect (to Shopify's logout endpoint when an `id_token` exists). Client-side form handling cannot process that redirect; a native browser submit follows it correctly. This also keeps logout working without JavaScript.
+- **No token exposure.** Access, refresh, and ID tokens stay server-side. Only render derived profile fields (name, email); never serialize session or token objects into loader data or HTML.
+
+## OAuth Caveat
+
+Completing a real login requires a public HTTPS origin whose `/account/authorize` callback is registered in the Customer Account app configuration. When the local origin is not registered, verify the signed-out rendering and handler wiring; skip the signed-in checks and say so instead of faking them.
+
+## Continue when
+
+- [ ] The navbar has an `/account` link and it returns 200
+- [ ] Signed out, `/account` renders the sign-in panel without touching access tokens
+- [ ] `GET /account/login` responds with a redirect to Shopify's login page (curl and check the `location` header)
+- [ ] The logout control is a native `<form method="post" action="/account/logout">` — not a client-side form component or a fetch call
+- [ ] Signed in (when the origin is registered for OAuth): `/account` renders the customer's name and email, and submitting the logout form signs the buyer out and lands back on the storefront
+- [ ] No access/refresh/ID token appears in serialized loader data or page HTML
+- [ ] `typecheck` (with `hydrogen gql check` chained) passes with the customer query in place

package/skills/hydrogen-shop-pay/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: hydrogen-shop-pay
+description: >
+  Guide for adding or reviewing Shop Pay buttons in Hydrogen storefronts. Use
+  when working with ShopPayButton, renderShopPayButton, createShopPayButton,
+  product buy buttons, cart checkout acceleration, variant IDs, quantities, or
+  source attribution attributes.
+---
+
+# Shop Pay
+
+Hydrogen renders the Shop Pay button locally as a `<hydrogen-shop-pay-button>`
+with a declarative shadow root. The shadow root protects the branded styles and
+contains an anchor pointing at the storefront's own `/checkout` or
+`/cart/<id>:<qty>` permalink paths, which `handleShopifyRoutes` redirects to the
+store's real checkout. No external script loads and the server-rendered button
+works before any JavaScript runs.
+
+## Framework References
+
+Before writing 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. If there is no matching reference, use `references/core.md` and wire the framework-neutral helpers into the app's existing component and routing conventions.
+
+## Rules
+
+- For product buy buttons, render Shop Pay only when there is a resolved ProductVariant ID.
+- Pass ProductVariant GIDs or bare numeric ProductVariant IDs. Product IDs are invalid.
+- Use quantity objects when quantity is known: `{ id: selectedVariant.id, quantity }`.
+- For cart checkout buttons, omit `variants`; checkout mode uses the current cart.
+- Disable Shop Pay whenever the add-to-cart button is disabled or a product/cart mutation is pending.
+- Omit `channel` unless the integration needs explicit `headless` or `hydrogen` checkout attribution and knows which sales channel issued its Storefront API token.
+- Omit `checkoutUrl` when the app routes same-origin checkout paths through `handleShopifyRoutes`. Otherwise pass the cart checkout URL.
+- Pass `nonce` only when the storefront's Content Security Policy requires nonces for inline `<style>` elements. The nonce authorizes the shadow-root stylesheet, not the `style` attribute used by `width` and `borderRadius`; strict policies must allow inline style attributes for those custom dimensions.
+- Keep Shop Pay near the primary purchase action, and keep its disabled state aligned with `canAddToCart(...)`.
+- Size with `width` and `borderRadius`; arbitrary `className` and `style` overrides are intentionally not supported because the branded button is isolated inside its shadow root. Pass `accessibilityLabel` when the storefront language is not English, and never translate the `Shop Pay` brand name.
+
+## Product Page Pattern
+
+```tsx
+{selectedVariant ? (
+  <ShopPayButton
+    variants={[{ id: selectedVariant.id, quantity }]}
+    disabled={!addable || pending}
+    width="100%"
+    borderRadius="9999px"
+  />
+) : null}
+```
+
+`addable` should come from `canAddToCart(product, options)`, not from checking `selectedVariant` alone.
+
+## Cart Pattern
+
+For a full-cart checkout shortcut, render Shop Pay without `variants` and hide or disable it when the cart is empty or a cart mutation is pending.
+
+```tsx
+{cart.lines.nodes.length > 0 ? (
+  <ShopPayButton
+    disabled={cartPending}
+    width="100%"
+    borderRadius="4px"
+  />
+) : null}
+```
+
+## Verify
+
+Done when:
+
+- [ ] Product buy buttons render Shop Pay only when a resolved ProductVariant ID exists.
+- [ ] Shop Pay's disabled state matches the add-to-cart button (disabled when add-to-cart is disabled or a product/cart mutation is pending).
+- [ ] Product buttons pass ProductVariant GIDs or bare numeric variant IDs (never Product IDs), with a quantity object when quantity is known.
+- [ ] Cart checkout buttons omit `variants` and are hidden or disabled when the cart is empty or a mutation is pending.
+- [ ] `checkoutUrl` is omitted only when `handleShopifyRoutes` handles the same-origin checkout paths.
+
+## Gotchas
+
+- The button's same-origin URLs only check out if the app routes requests through `handleShopifyRoutes`, which redirects `/checkout` and `/cart/<id>:<qty>` permalinks to the store's checkout.
+- Disabled buttons render without an `href` (with `aria-disabled="true"`), so nothing navigates while a mutation is pending.
+- If the button renders but checkout fails, verify variant ID format and that `handleShopifyRoutes` handles the request first.

package/skills/hydrogen-shop-pay/references/core.md

@@ -0,0 +1,66 @@
+# Core Helpers
+
+Use core helpers when not using the React or Vue bindings:
+
+```ts
+import {
+  createShopPayButton,
+  renderShopPayButton,
+} from "@shopify/hydrogen";
+```
+
+Both helpers create a self-contained `<hydrogen-shop-pay-button>` with an open
+shadow root containing the protected styles and an anchor with the Shop Pay
+logo. Pick by integration shape:
+
+- `renderShopPayButton(options)` returns an HTML string. Use it in server
+  templates or frameworks with raw-HTML rendering (`{@html}`, `v-html`,
+  `innerHTML`). Server output includes a declarative shadow root and needs no
+  client JavaScript. Browser calls register the custom element and return an
+  empty host that creates its shadow root when connected; use
+  `createShopPayButton` instead for client-created strict-CSP buttons that need
+  a `nonce`.
+- `createShopPayButton(options)` returns a detached self-contained
+  `<hydrogen-shop-pay-button>` with an imperative shadow root. Use it for
+  imperative DOM UIs.
+
+For product buy buttons, pass variants:
+
+```ts
+const button = createShopPayButton({
+  variants: [{ id: selectedVariant.id, quantity: 1 }],
+  width: "100%",
+});
+container.append(button);
+```
+
+The open shadow root can be inspected with browser developer tools, but page CSS
+cannot select its internal anchor or logo. The supported style controls are
+`width` and `borderRadius`; do not treat the open root as a styling API.
+Pass `nonce` when the storefront's Content Security Policy requires nonces for
+inline `<style>` elements. The nonce does not authorize the `style` attribute
+used by `width` and `borderRadius`; strict policies must allow inline style
+attributes for those custom dimensions.
+
+For cart checkout buttons, omit `variants`; the button links to the same-origin
+`/checkout` path and `handleShopifyRoutes` redirects it to the current cart's
+checkout:
+
+```ts
+const button = createShopPayButton({
+  width: "100%",
+});
+container.append(button);
+```
+
+## Validation Rules
+
+- Variant IDs must be Shopify ProductVariant GIDs or bare numeric variant IDs.
+- Quantities must be positive integers.
+- Mixed variant formats are invalid: use all strings or all `{ id, quantity }` objects.
+- Cart checkout mode omits `variants`; the current cart checks out.
+- `disabled` renders the button without an `href` and with `aria-disabled="true"`.
+- `accessibilityLabel` sets the accessible name for the logo-only button, which otherwise defaults to English. Localize words around the brand, but never translate `Shop Pay` itself.
+- `channel` is optional. Set it to `headless` or `hydrogen` only when checkout needs explicit attribution to the sales channel that issued the Storefront API token.
+- `nonce` is optional. It is applied to the shadow root's `<style>` element for strict Content Security Policies in server output, `createShopPayButton`, and framework bindings.
+- Pass `checkoutUrl` when the app does not route same-origin checkout paths through `handleShopifyRoutes`.

package/skills/hydrogen-shop-pay/references/react.md

@@ -0,0 +1,50 @@
+# React
+
+Import from the React entrypoint:
+
+```tsx
+import { ShopPayButton } from "@shopify/hydrogen/react";
+```
+
+In a product form:
+
+```tsx
+function AddToCart({ product }: { product: ProductData }) {
+  const { options, selectedVariant, formProps, register, errors, pending } = useProductForm();
+  const [quantity, setQuantity] = useState(1);
+  const addable = canAddToCart(product, options);
+
+  return (
+    <>
+      <form {...formProps({ beforeSubmit: openCartDrawer })}>
+        <input type="hidden" {...register("merchandiseId", {})} />
+        <input {...register("quantity", { value: quantity })} />
+        <button {...register("addToCart", {})} disabled={!addable || pending}>Add to cart</button>
+      </form>
+
+      {selectedVariant ? (
+        <ShopPayButton
+          variants={[{ id: selectedVariant.id, quantity }]}
+          disabled={!addable || pending}
+          width="100%"
+          borderRadius="9999px"
+          accessibilityLabel="Shop Payで購入"
+        />
+      ) : null}
+    </>
+  );
+}
+```
+
+`ShopPayButton` server-renders a `<hydrogen-shop-pay-button>` with a declarative
+shadow root. The shadow root preserves the branded styles before JavaScript runs
+and upgrades client-created instances without hydration errors.
+
+Size with `width`/`borderRadius`. `className` and `style` are intentionally not
+supported because page CSS cannot reach the internal anchor. Pass
+`accessibilityLabel` when the storefront language is not English. Localize words
+around the brand, but never translate `Shop Pay` itself. Pass `nonce` when the
+storefront's Content Security Policy requires nonces for inline `<style>`
+elements. The nonce does not authorize the `style` attribute used by `width` and
+`borderRadius`; strict policies must allow inline style attributes for those
+custom dimensions.

package/skills/hydrogen-shop-pay/references/vue.md

@@ -0,0 +1,39 @@
+# Vue And Nuxt
+
+Import from the Vue entrypoint:
+
+```vue
+<script setup lang="ts">
+import { canAddToCart } from "@shopify/hydrogen";
+import { ShopPayButton } from "@shopify/hydrogen/vue";
+
+const form = useProductForm();
+const quantity = ref(1);
+const addable = computed(() => canAddToCart(props.product, form.options));
+</script>
+```
+
+Render only when a variant is resolved:
+
+```vue
+<ShopPayButton
+  v-if="form.selectedVariant"
+  :variants="[{ id: form.selectedVariant.id, quantity }]"
+  :disabled="!addable || form.pending.value"
+  width="100%"
+  border-radius="9999px"
+  accessibility-label="Shop Pay से खरीदें"
+/>
+```
+
+The component server-renders a `<hydrogen-shop-pay-button>` with a declarative
+shadow root, so it works with Nuxt server rendering and needs no client-only
+wrapper. The shadow root protects the branded internal styles.
+
+Size with `width`/`border-radius`. Extra `class` and `style` attributes are
+intentionally not forwarded into the shadow root. Pass `accessibility-label`
+when the storefront language is not English. Localize words around the brand,
+but never translate `Shop Pay` itself. Pass `nonce` when the storefront's
+Content Security Policy requires nonces for inline `<style>` elements. The nonce
+does not authorize the `style` attribute used by `width` and `border-radius`;
+strict policies must allow inline style attributes for those custom dimensions.

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

@@ -0,0 +1,205 @@
+---
+name: hydrogen-smoke-test
+description: >
+  Smoke-test checklist for Hydrogen storefronts built by agents. Use after
+  creating or modifying a Hydrogen storefront, setup flow, cart, product page,
+  collection/search browsing, analytics, request handlers, Shopify redirects,
+  Shop Pay, or framework middleware integration.
+---
+
+# Hydrogen Storefront Smoke Tests
+
+Run the app in the framework's dev server and, when practical, in a production build. Type checks are not enough for Hydrogen wiring.
+
+If any check below fails, fix the app and re-run the failing check before treating verification as complete.
+
+Copyable checklist (details for each check are in the sections below):
+
+```
+Static checks:
+- [ ] Formatting fixer, if present
+- [ ] lint, typecheck, or check
+- [ ] GraphQL validation (`hydrogen gql check`) when `gql()` documents changed
+- [ ] build
+- [ ] test
+- [ ] Formatting check, if distinct from the fixer
+
+Request handlers:
+- [ ] POST /api/{api-version}/graphql.json returns Storefront API JSON, not the framework 404
+- [ ] GET /api/cart returns cart handler JSON (no cart cookie -> {cart: null})
+- [ ] GET /admin redirects to the configured shop/admin domain
+- [ ] Unknown path returns framework 404 unless a Shopify URL redirect matches
+
+Navigation:
+- [ ] Every navbar and footer link href returns 200 when curled directly (no invented routes)
+
+Product page:
+- [ ] Server-renders title, gallery, price, variant options, add-to-cart form, and related products when available
+- [ ] URL option params select the expected variant on reload
+- [ ] Selecting same-product options updates the URL without scroll reset
+- [ ] Combined-listing values navigate to the target product handle instead of calling selectOption
+- [ ] Sold-out values remain selectable and show sold-out text
+- [ ] Non-existent combinations are disabled
+- [ ] Add-to-cart is enabled only when canAddToCart(product, options) is true
+- [ ] Shop Pay renders only when a selected variant exists and is disabled when add-to-cart is disabled or pending
+
+Cart:
+- [ ] /cart works without JavaScript and is reachable via a real /cart link in the footer
+- [ ] Header cart trigger is a `/cart` anchor that opens the drawer via `showModal()` after hydration
+- [ ] window.Shopify.actions.openCart() opens the drawer after Standard Actions loads
+- [ ] A mutation driven through the real Add to cart UI or framework cart action issues `Set-Cookie` and propagates expected response headers
+- [ ] Add-to-cart can open the drawer after a successful submit when the product UX chooses that behavior
+- [ ] Each line item form includes hidden set, scoped lineId, and editable quantity
+- [ ] Quantity Enter key submits a set action
+- [ ] Rapid quantity clicks settle to the final expected quantity
+- [ ] Line, discount, note, attribute, network, and cart-level errors appear in the right scope
+- [ ] Attribute editing submits the complete list, preserves unrelated attributes, and shows scoped pending UI
+- [ ] Totals are server-provided and visually pending during cart mutations
+
+Collection and search:
+- [ ] Collection filters and sort update the URL and product grid
+- [ ] Checkbox filters and price min/max controls both render, apply, and persist after reload
+- [ ] Reloading a filtered URL server-renders the same filter/sort state
+- [ ] Active filter chips remove one filter and preserve unrelated params
+- [ ] Search filters preserve q
+- [ ] JavaScript-disabled filter forms still submit with GET
+- [ ] Back/forward navigation does not leave browse state stuck in loading
+
+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
+- [ ] No browser module reads private env variables
+- [ ] Production does not bypass Customer Privacy consent gating (no forced-always-true consent checks)
+
+Markets and money:
+- [ ] Market-aware Storefront API queries declare $country, $language, and @inContext
+- [ ] Money renders from Storefront API money fields via formatMoney()
+- [ ] No client-side subtotal/total arithmetic exists
+
+Production pass:
+- [ ] Build and run the production bundle and repeat the request-handler checks against production mode
+```
+
+## Static Checks
+
+Run the app's available scripts:
+
+1. Formatting fixer, if present.
+2. `lint`, `typecheck`, or `check`.
+3. GraphQL validation (`hydrogen gql check`) when `gql()` documents changed.
+4. `build`.
+5. `test`.
+6. Formatting check, if distinct from the fixer.
+
+## Request Handlers
+
+Replace `<port>` with the running app port, and `{api-version}` with the Storefront API version configured by the app:
+
+```bash
+curl -i -X POST http://localhost:<port>/api/{api-version}/graphql.json \
+  -H "content-type: application/json" \
+  -H "X-Shopify-Storefront-Access-Token: <public-token>" \
+  -d '{"query":"{ shop { name } }"}'
+```
+
+Expected: Storefront API JSON, not the framework 404.
+
+The SFAPI proxy forwards the incoming public token header; it does not inject a token from server config.
+
+```bash
+curl -i http://localhost:<port>/api/cart
+```
+
+Expected: cart handler JSON, not 404. With no cart cookie, the body should be `{cart: null}`.
+
+```bash
+curl -i http://localhost:<port>/admin
+```
+
+Expected: redirect to `/admin` on the configured shop/admin domain.
+
+```bash
+curl -i http://localhost:<port>/this-does-not-exist
+```
+
+Expected: framework 404 unless Shopify has a matching URL redirect.
+
+## Navigation
+
+Extract every `href` from the rendered navbar and footer and request each one directly:
+
+```bash
+curl -s -o /dev/null -w "%{http_code} <href>\n" http://localhost:<port><href>
+```
+
+Expected: 200 for every link. A 404 means the link points to a route the app never created or a handle the shop does not have. `/collections/all` is the classic failure: the Liquid "all" collection does not exist in the Storefront API, so only link to it when the shop really has a collection with that handle.
+
+## Account
+
+```bash
+curl -i http://localhost:<port>/account/login
+```
+
+Expected: a redirect whose `location` header points at Shopify's hosted login, not a framework 404 or 500.
+
+- `/account` renders the signed-out panel when no session exists, without touching access tokens.
+- The logout control is a native `<form method="post" action="/account/logout">`; the handler enforces same-origin POST and returns a raw redirect only a native browser submit can follow.
+- Completing a real login requires a public HTTPS origin registered for the OAuth callback; when the local origin is not registered, verify the signed-out checks and say so instead of faking signed-in ones.
+
+## Product Page
+
+- Product page server-renders title, gallery, price, variant options, add-to-cart form, and related products when available.
+- URL option params select the expected variant on reload.
+- Selecting same-product options updates the URL without scroll reset.
+- Combined-listing values navigate to the target product handle instead of calling `selectOption`.
+- Sold-out values remain selectable and show sold-out text.
+- Non-existent combinations are disabled.
+- Add-to-cart is enabled only when `canAddToCart(product, options)` is true.
+- Shop Pay renders only when a selected variant exists and is disabled when add-to-cart is disabled or pending.
+
+## Cart
+
+- `/cart` works without JavaScript and is reachable via a real `/cart` link in the footer.
+- The header cart trigger is a `/cart` anchor that opens the drawer via `showModal()` after hydration.
+- `window.Shopify.actions.openCart()` opens the drawer after Standard Actions loads.
+- Exercise a mutation through the real Add to cart UI or the framework's cart action. Do not hand-craft an internal
+  Hydrogen cart payload. Confirm the response issues the expected cart or session `Set-Cookie` and propagates the
+  action's response headers.
+- `handleShopifyRoutes` can intercept `/api/cart` and predictive-search requests, so the absence of a matching route
+  file does not mean the handler is missing.
+- Add-to-cart can open the drawer after a successful submit when the product UX chooses that behavior.
+- Each line item form includes hidden `set`, scoped `lineId`, and editable `quantity`.
+- Quantity Enter key submits a set action.
+- Rapid quantity clicks settle to the final expected quantity.
+- Line, discount, note, attribute, network, and cart-level errors appear in the right scope.
+- Saving one cart attribute submits the complete next list, preserves unrelated attributes, and shows a saving state while `pending.attributes` is true. Submitting no attribute fields clears the list.
+- Totals are server-provided and visually pending during cart mutations.
+
+## Collection And Search
+
+- Collection filters and sort update the URL and product grid.
+- Checkbox filters and price min/max controls both render, apply, and persist after reload.
+- Reloading a filtered URL server-renders the same filter/sort state.
+- Active filter chips remove one filter and preserve unrelated params.
+- Search filters preserve `q`.
+- JavaScript-disabled filter forms still submit with GET.
+- Back/forward navigation does not leave browse state stuck in loading.
+
+## 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 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`.
+- No browser module reads private env variables.
+- Analytics destinations only receive events after Shopify Customer Privacy allows analytics processing.
+
+## Markets And Money
+
+- Storefront API queries that should be market-aware declare `$country`, `$language`, and `@inContext`.
+- Money renders from Storefront API money fields via `formatMoney()`.
+- No client-side subtotal/total arithmetic exists.
+
+## Production Pass
+
+Build and run the production bundle. Repeat request-handler checks against production mode because dev-only middleware or development export conditions can hide broken production wiring.