@shopify/hydrogen 2026.4.5 → 2026.10.0-preview.2

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

@@ -0,0 +1,248 @@
+---
+name: hydrogen-cart-drawer
+description: >
+  Guide for building an accessible cart drawer using @shopify/hydrogen. Use when
+  creating or reviewing a cart drawer, mini cart, or slide-out cart, including
+  native dialog element (showModal), closedby light dismiss, body scroll lock, exit
+  animations, and wiring window.Shopify.actions.openCart().
+---
+
+# Cart Drawer
+
+Build an accessible cart drawer that opens from the edge of the viewport and integrates with Standard Actions so any code can open it via `window.Shopify.actions.openCart()`.
+
+---
+
+## 1. Prerequisites
+
+Before building the cart drawer, these must be in place:
+
+- **Shopify runtime scripts** — render `ShopifyScripts` once in the root document, or use `getShopifyScriptTags()` / `renderShopifyScriptTags()` from core in framework-agnostic heads plus `initializeShopifyScripts({ routes: routeTemplates })` during browser hydration. Use the local `hydrogen-routing` skill for the required routing options. The drawer uses `window.Shopify.actions.openCart()` from that runtime.
+- **`/cart` route** — the full cart page, used as the fallback route when the drawer is unavailable. For strict no-JS live cart HTML, the cart route must receive resolved cart `initialData`.
+
+---
+
+## 2. Drawer structure
+
+The drawer has three layout zones (header / body / footer):
+
+1. **Header** — title, close button, and error banner (if any cart errors exist). Always visible, never scrolls.
+2. **Body** — line items only. This is the only zone that scrolls when content overflows.
+3. **Footer** — discount codes, order note and/or cart attribute editors, totals, and checkout button. Always visible (pinned to bottom), never scrolls.
+
+**Empty state**: When the cart has no items, the body shows an empty message ("Your cart is empty") and the footer is hidden entirely — no totals, no discounts, no notes, no checkout button.
+
+The drawer is a `<dialog>` (or primitive library equivalent) rendered once in the root layout. The storefront must also have a `/cart` route that renders a full cart page — this is the fallback route when the drawer is unavailable. The drawer is the progressively-enhanced experience that layers on top after hydration.
+
+The full `/cart` page shares the same content components (line items, discounts, note, attributes, totals, checkout) but uses a page layout instead of the fixed header/body/footer zones.
+
+The drawer's line item forms must use the same Hydrogen line-item form contract as the `/cart` page — see `hydrogen-cart-ui` ("Form structure"). The layout may differ by framework and design system; the form contract must not.
+
+---
+
+## 3. Accessibility
+
+See `references/accessibility.md` for the full dialog accessibility spec grounded in the WHATWG HTML specification.
+
+### Must implement (not provided by `<dialog>`)
+
+At-a-glance index — full treatment lives where each concern is implemented:
+
+1. **Body scroll lock** — pure CSS, no JS class toggling (see §6)
+2. **Backdrop click dismissal** — native light dismiss via `<dialog closedby="any">` (see §5)
+3. **Exit animation** — `@starting-style` / discrete transitions (see §6)
+
+### Provided by `<dialog>` + `showModal()`
+
+These are free — **do not reimplement them**: focus containment (background `inert`), focus restoration to the trigger on `close()`, Escape dismissal, `::backdrop` overlay, and implicit `aria-modal="true"`. See `references/accessibility.md` for the full table and how each works.
+
+### Required markup
+
+```html
+<dialog aria-labelledby="cart-drawer-title">
+  <h2 id="cart-drawer-title">Cart</h2>
+  <!-- drawer content -->
+</dialog>
+```
+
+All interactive elements inside the drawer must be `<button>` or `<input>` elements — not `<div>` or `<span>` with click handlers.
+
+---
+
+## 4. Dialog primitive recommendation
+
+**Default**: use native `<dialog>` with `showModal()`. It gives you most accessibility behaviors for free and avoids adding a dependency.
+
+Use a primitive library only when the app already depends on one for dialog-like UI and wants that library's controlled-state or animation model. The accessibility requirements in `references/accessibility.md` are identical regardless of approach.
+
+---
+
+## 5. Open/close behavior
+
+### Opening the drawer
+
+The cart trigger renders in SSR as `<a href="/cart">Cart</a>` so it works before hydration and without JavaScript (the anchor navigates to the full `/cart` page). After hydration, an `onClick` calls `e.preventDefault()` then `openCartDrawer()` (which calls `showModal()`), so the click opens the drawer instead of navigating; no `hasHydrated` swap is needed — the anchor is the no-JS baseline and the `onClick` is the enhancement.
+
+Keep the drawer as hydrated progressive enhancement. Do not make the drawer itself the fallback route; the `/cart` page is that full-page fallback.
+
+```tsx
+export const CART_DRAWER_ID = "cart-drawer";
+const STANDARD_ACTIONS_READY_EVENT = "DOMContentLoaded";
+
+let openCartActionConfigured = false;
+let openCartActionRetryQueued = false;
+
+function getCartDrawer() {
+  if (typeof document === "undefined") return null;
+
+  const drawer = document.getElementById(CART_DRAWER_ID);
+  return drawer instanceof HTMLDialogElement ? drawer : null;
+}
+
+export function openCartDrawer() {
+  const drawer = getCartDrawer();
+  if (!drawer || drawer.open) return;
+  drawer.showModal();
+}
+
+export function closeCartDrawer() {
+  getCartDrawer()?.close();
+}
+
+function configureOpenCartActionNow() {
+  const openCart = typeof window !== "undefined" ? window.Shopify?.actions?.openCart : undefined;
+  if (!openCart) return false;
+
+  openCart.configure({
+    handler: async () => openCartDrawer(),
+  });
+  openCartActionConfigured = true;
+  return true;
+}
+
+export function configureOpenCartAction() {
+  if (typeof document === "undefined" || openCartActionConfigured) return;
+  if (configureOpenCartActionNow()) return;
+  if (openCartActionRetryQueued || document.readyState !== "loading") return;
+
+  openCartActionRetryQueued = true;
+  document.addEventListener(
+    STANDARD_ACTIONS_READY_EVENT,
+    () => {
+      openCartActionRetryQueued = false;
+      configureOpenCartAction();
+    },
+    { once: true },
+  );
+}
+
+configureOpenCartAction();
+```
+
+The module-scope `configureOpenCartAction()` call is intentional. It no-ops during SSR, configures immediately when Standard Actions is already available, and retries once on `DOMContentLoaded` when the runtime loads after this module.
+
+Render the drawer once in the root layout. Use explicit JavaScript open/close helpers for app-owned controls.
+
+```tsx
+import { CART_DRAWER_ID, closeCartDrawer } from "~/lib/cart-drawer";
+
+function CartDrawer() {
+  return (
+    <dialog id={CART_DRAWER_ID} aria-labelledby="cart-drawer-title" closedby="any">
+      <h2 id="cart-drawer-title">Cart</h2>
+      <button
+        type="button"
+        aria-label="Close cart"
+        onClick={closeCartDrawer}
+      >
+        Close
+      </button>
+      {/* cart content */}
+    </dialog>
+  );
+}
+```
+
+The drawer opens from three surfaces. The cart trigger is the canonical one; the other two reuse the same helper.
+
+**1. The cart trigger.** A `/cart` anchor with an `onClick` that opens the drawer after hydration. It carries the accessibility attributes `aria-controls` and `aria-haspopup="dialog"`:
+
+```tsx
+return (
+  <a href="/cart" onClick={(e) => { e.preventDefault(); openCartDrawer(); }} aria-controls={CART_DRAWER_ID} aria-haspopup="dialog">
+    Cart
+  </a>
+);
+```
+
+**2. `window.Shopify.actions.openCart()`** — the Standard Action for programmatic opening, so external code (Standard Actions tools, agents, third-party components) can open the drawer. Register the same stable DOM helper as the `openCart` handler (see §8 for the handler-permanence caveat).
+
+```js
+window.Shopify.actions.openCart();
+```
+
+**3. From add-to-cart** — when the canonical cart trigger is an anchor, open the drawer immediately with optimistic state so pending cart contents remain inspectable. Opening only after success is compatible with the storefront contract only when the page also provides a visible button that opens the drawer while the mutation is pending.
+
+```tsx
+<form {...formProps({ beforeSubmit: openCartDrawer })}>
+  {/* add-to-cart controls */}
+</form>
+```
+
+Validate before calling the drawer helper — for example, call `event.preventDefault()` and return if the quantity is invalid. Do not push this policy into core cart mutations; some storefronts want a toast, a cart page navigation, or no automatic UI change.
+
+### Closing the drawer
+
+Native: Escape and the back gesture (fires `cancel` then `close`). App-provided: the explicit close `<button>` in the header (`aria-label="Close cart"`). Backdrop (light dismiss) requires `<dialog closedby="any">`.
+
+`closedby="any"` is the least compatible part of this pattern. Browsers without `closedby` support will ignore the attribute, so the drawer will still close from Escape and the explicit close button, but backdrop click will not close it. Do not provide a polyfill for `closedby` unless the app explicitly requires backdrop click support in those browsers.
+
+If an app does require that polyfill, use a pointerdown-plus-click guard on the `<dialog>` itself: record whether `pointerdown` started on the dialog backdrop, then close only when the following `click` also targets the dialog. Do not close on a plain `click.self` alone, because a drag that starts inside the drawer and ends on the backdrop can produce an accidental close.
+
+### State management
+
+Open/close is DOM state owned by the `<dialog>` element. Prefer `dialog.showModal()` and `dialog.close()` over duplicating open state in framework state unless a primitive library requires controlled state.
+
+For custom logic, listen to native dialog events instead of duplicating state. Use `toggle` to react after the drawer opens or closes. Use `beforetoggle` with `event.preventDefault()` when the app needs to intercept opening, run custom work such as an animation, and then call `showModal()` manually later.
+
+---
+
+## 6. CSS and animation
+
+See `references/css.md` for the reference drawer shell, entry/exit animation, backdrop, and scroll-lock CSS. In Tailwind apps, keep the dialog shell, `::backdrop`, `@starting-style`, and scroll-lock rules in global CSS or a project `@layer`; use utilities for the drawer's internal content layout.
+
+---
+
+## 7. Verify
+
+After building the cart drawer, test:
+
+- [ ] Cart trigger is a `/cart` anchor pre-hydration; after hydration its `onClick` opens the drawer via `showModal()`
+- [ ] If a no-JS fallback is required, it navigates to `/cart` without JavaScript
+- [ ] `window.Shopify.actions.openCart()` opens drawer (test from browser console)
+- [ ] Drawer closes via Escape, backdrop click (with `closedby="any"`), and the close button
+- [ ] Focus returns to the cart icon after close
+- [ ] Tab cycles only through elements inside the drawer while open
+- [ ] Screen reader announces "Cart" (or equivalent title) on drawer open
+- [ ] While cart data loads, the title and close button remain available and the loading status is announced
+- [ ] Drawer line item forms use the same `hydrogen-cart-ui` progressive form contract as the `/cart` page
+
+---
+
+## 8. Common gotchas
+
+- **`openCart` handler is permanent** — `openCart.configure({ handler })` has no corresponding `unconfigure()`. Once registered, the handler persists for the page lifetime. This is fine when the drawer lives in the root layout. Avoid handlers that close over component refs that can go stale during HMR; prefer a small stable helper that looks up `dialog#cart-drawer` and calls `showModal()`.
+
+- **Astro view transitions** — if the drawer is vanilla JS (like the base example), it must be re-initialized after view transition navigations. Listen for `astro:after-swap`.
+
+- **Cart selectors must be stable** — don't derive arrays or objects inside a cart selector unless the binding accepts an equality function. Select store references such as `state.errors` or `state.data.lines.nodes` and derive banner messages outside the selector with the framework's memoization primitive.
+
+---
+
+## 9. Anti-patterns
+
+- **Drawer as a route instead of overlay** — the drawer is overlay UI in the root layout and must be available on every page; the `/cart` route is the full cart page, not the drawer (see §2).
+
+- **`dialog.show()` instead of `showModal()`** — `show()` does not get top-layer rendering, focus containment, `inert` on background, or `::backdrop`. Always use `showModal()`.
+
+- **Text-only drawer quantities** — rendering line quantities as text with only plus/minus controls breaks the progressive set-quantity path; use the same editable quantity input contract as the `/cart` page (see `hydrogen-cart-ui`).

package/skills/hydrogen-cart-drawer/references/accessibility.md

@@ -0,0 +1,109 @@
+# Dialog/Drawer Accessibility Requirements
+
+Framework-agnostic specification for building an accessible modal drawer. Grounded in the WHATWG HTML specification for the `<dialog>` element and WAI-ARIA Authoring Practices.
+
+## The `<dialog>` element with `showModal()`
+
+The native `<dialog>` element with `showModal()` is the recommended foundation. It provides six accessibility behaviors for free, leaving only three concerns for the implementation to handle.
+
+### What `showModal()` provides
+
+| Behavior | How it works |
+|----------|-------------|
+| **Top-layer rendering** | The dialog is promoted above all other content, regardless of `z-index` stacking. No z-index wars. |
+| **`::backdrop` pseudo-element** | A full-viewport overlay rendered behind the dialog in the top layer. Styleable with CSS. |
+| **Escape key dismissal** | Pressing Escape fires a `cancel` event (cancelable), then closes the dialog and fires a `close` event. |
+| **Focus containment** | All content outside the dialog becomes `inert` — unreachable by Tab, click, or assistive technology. Tab and Shift+Tab cycle only through focusable elements inside the dialog. |
+| **Focus restoration** | The browser stores the previously-focused element when `showModal()` is called and restores focus to it when the dialog closes via `close()`. Per the WHATWG spec, this is automatic. |
+| **Implicit `aria-modal="true"`** | Screen readers recognize the dialog as modal without an explicit attribute. |
+
+### What must be implemented manually
+
+These three behaviors are NOT provided by `<dialog>` and must be handled by the implementation or a primitive library:
+
+#### 1. Body scroll lock
+
+`showModal()` does not prevent the background from scrolling. Use the CSS `:has()` selector to apply `overflow: hidden` on `<body>` when the dialog is open — no JS class toggling or cleanup needed:
+
+```css
+body:has(dialog#cart-drawer[open]) {
+  overflow: hidden;
+}
+```
+
+Watch for the scrollbar-gutter shift: when the scrollbar disappears, body width increases by the scrollbar's width. Primitive libraries typically handle this with `padding-right` compensation or `scrollbar-gutter: stable`.
+
+#### 2. Backdrop click dismissal
+
+The default `<dialog>` behavior does not close on backdrop click. The standard pattern detects clicks on the dialog element itself (as opposed to its children):
+
+```js
+dialog.addEventListener('click', (event) => {
+  if (event.target === dialog) dialog.close();
+});
+```
+
+Click events on child elements bubble to the dialog, but `event.target` remains the child — only direct clicks on the dialog element (i.e., the backdrop area) satisfy the condition.
+
+**Preferred:** The `closedby` attribute provides native light dismiss. Setting `closedby="any"` enables both Escape and backdrop click dismissal natively. Browsers that do not support it ignore the attribute; keep an explicit close button as the always-available close mechanism.
+
+#### 3. Exit animations
+
+The hard problem: `close()` removes the dialog from the top layer immediately, making exit animations impossible with the standard approach.
+
+Two strategies:
+
+**CSS `@starting-style` + `allow-discrete` (modern browsers)**
+```css
+dialog[open] {
+  transform: translateX(0);
+  transition: transform 250ms, overlay 250ms allow-discrete, display 250ms allow-discrete;
+}
+@starting-style {
+  dialog[open] { transform: translateX(100%); }
+}
+dialog:not([open]) {
+  transform: translateX(100%);
+}
+```
+
+**JavaScript-deferred close (broadest compatibility)**
+Run the exit animation first, then call `dialog.close()` after the animation completes. This requires intercepting the native close flow (cancel the `cancel` event, run the animation, then close programmatically).
+
+## Labeling
+
+The drawer must have an accessible name. Use `aria-labelledby` pointing to the visible heading element:
+
+```html
+<dialog aria-labelledby="cart-drawer-title">
+  <h2 id="cart-drawer-title">Cart</h2>
+  ...
+</dialog>
+```
+
+If additional context is useful for screen readers (e.g., item count), use `aria-describedby` pointing to a summary element.
+
+## Keyboard interaction
+
+With `<dialog>` + `showModal()` and semantic HTML, all keyboard interactions are native:
+
+| Key | Behavior | Source |
+|-----|----------|--------|
+| Escape | Closes the dialog | Native (`cancel` → `close` events) |
+| Tab | Moves focus to next focusable element inside dialog | Native (background is `inert`) |
+| Shift+Tab | Moves focus to previous focusable element inside dialog | Native |
+| Enter / Space | Activates the focused button or link | Native for `<button>`, `<a>`, `<input>` |
+
+No additional keyboard handlers are needed if all interactive elements use semantic HTML (`<button>`, `<a>`, `<input>`). Custom elements that are not natively focusable require `tabindex="0"` and `role` attributes — prefer native elements instead.
+
+## How primitive libraries handle these concerns
+
+Primitive libraries (Radix UI, Base UI, Melt UI, Kobalte, Headless UI, etc.) implement the same accessibility contract described above. They abstract the manual work:
+
+- **Focus containment**: Some libraries build their own focus trap from `<div>` + portal rather than using `<dialog>`. The result is equivalent — Tab cycles within the dialog, background is inert.
+- **Scroll lock**: Libraries typically add `overflow: hidden` with scrollbar-gutter compensation automatically.
+- **Backdrop click**: Handled via an overlay component with an `onClick` handler, or via the `closedby` attribute where supported.
+- **Exit animations**: Libraries integrate with their framework's animation system (React transition groups, Svelte transitions, CSS animation hooks) to defer unmounting until the animation completes.
+- **Focus restoration**: Most libraries implement their own, even though `<dialog>` handles it natively. This is because some libraries render from `<div>` + portal, not `<dialog>`.
+
+The accessibility requirements are identical regardless of whether you use a library or native `<dialog>`. Libraries reduce implementation effort but don't change what must be true for the drawer to be accessible.

package/skills/hydrogen-cart-drawer/references/css.md

@@ -0,0 +1,67 @@
+# Cart Drawer CSS
+
+Reference drawer shell, entry/exit animation, backdrop, and scroll-lock CSS for the cart drawer.
+
+```css
+dialog#cart-drawer {
+  position: fixed;
+  inset-block: 0;
+  right: 0;
+  left: auto;
+  margin: 0;
+  width: 100%;
+  max-width: 28rem;
+  height: 100dvh;
+  max-height: none;
+  border: 0;
+  padding: 0;
+}
+```
+
+**Entry and exit animation**: slide in from the edge and let the dialog remain transitionable while closing.
+```css
+dialog#cart-drawer {
+  transform: translateX(100%);
+  transition:
+    transform 250ms cubic-bezier(0.22, 1, 0.36, 1),
+    overlay 250ms allow-discrete,
+    display 250ms allow-discrete;
+}
+
+dialog#cart-drawer[open] {
+  transform: translateX(0);
+}
+
+@starting-style {
+  dialog#cart-drawer[open] {
+    transform: translateX(100%);
+  }
+}
+```
+
+**Backdrop**: fade in.
+```css
+dialog#cart-drawer::backdrop {
+  background: rgb(0 0 0 / 0);
+  transition:
+    background-color 250ms ease-out,
+    overlay 250ms allow-discrete,
+    display 250ms allow-discrete;
+}
+dialog#cart-drawer[open]::backdrop {
+  background: rgb(0 0 0 / 0.3);
+}
+
+@starting-style {
+  dialog#cart-drawer[open]::backdrop {
+    background: rgb(0 0 0 / 0);
+  }
+}
+```
+
+**Scroll lock**:
+```css
+body:has(dialog#cart-drawer[open]) { overflow: hidden; }
+```
+
+Exact measurements and colors are not prescribed — the above matches the base example for reference. Adapt to the project's design system.

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

@@ -0,0 +1,224 @@
+---
+name: hydrogen-cart-ui
+description: >
+  Behavioral guide for building cart UI with @shopify/hydrogen: line items,
+  quantity and remove controls, optimistic updates, discount, note, and cart
+  attribute inputs, and the full-page /cart fallback. Use when writing,
+  modifying, or reviewing cart line-item UI, quantity/remove controls, or cart
+  mutation forms. Framework agnostic.
+---
+
+# Cart Primitive
+
+The cart primitive is a client-side store that syncs with Shopify via Standard Actions events. It provides optimistic updates, scoped error handling, and a form-based mutation API. The store is framework-neutral; framework-specific bindings are thin wrappers over the core store.
+
+## Framework Bindings
+
+Before building 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 first; the reference owns provider setup, state selectors, and form helpers for that runtime.
+
+If there is no matching reference, there may be no packaged `@shopify/hydrogen/<framework>` export. Use the framework-neutral `createCartStore` and `createCartFormRegister` from `@shopify/hydrogen` directly, subscribe to store changes with the framework's reactivity primitive, and apply every rule in this skill yourself. Packaged bindings are thin wrappers over these same core APIs — match their behavior, do not invent a new contract.
+
+In island-based frameworks, use the binding for the island's UI framework when a matching reference exists; otherwise use the core store directly.
+
+## Route Placement
+
+When creating a full cart page, use the app's existing route convention when present; otherwise create `/cart`. This page is separate from Hydrogen's `/api/cart` server handler, which is registered with `createCartServerHandlers()` through `handleShopifyRoutes`.
+
+**The `/cart` page must render from the server data path.** It is the fallback route for the cart drawer (reachable as a real `/cart` link in the footer), so its line items and totals must not depend only on an ad hoc client store read. Seed `CartProvider` with `initialData` from the server data path (React Router loader, Next.js server layout/page). When the framework can preserve streamed promises, pass the unresolved cart promise as `initialData` instead of awaiting it; the Next.js reference is the best current non-blocking pattern. If strict no-JS HTML must include the real cart today, pass the resolved handler envelope instead. A `/cart` page whose only data source is a client `useCart` read renders "Your cart is empty" without JS even when the shopper has items. See the framework reference for the exact wiring.
+
+**The native no-JS add-to-cart POST must set the cart cookie server-side.** With scripting off, the add-to-cart `<form method="post">` submits natively and the cart server handler must respond with the cart cookie so the next `/cart` request server-renders the seeded cart — not only service the hydrated `fetch`. See the `hydrogen-request-handlers` skill for the endpoint contract.
+
+## How the store works
+
+The store holds a `CartState` and notifies subscribers when it changes. `state.readyPromise` is present while an applicable full-cart load is pending and resolves after the resulting state is published. Mutations flow through Shopify Standard Actions — the store listens for `shopify:cart:lines-update`, `shopify:cart:discount-update`, `shopify:cart:note-update`, and `shopify:cart:attributes-update` DOM events. Each event carries a `promise` that resolves with the server response.
+
+On mutation:
+
+1. The store applies an **optimistic projection** over its settled state, so the UI-visible state changes immediately.
+2. The affected entity is added to `pending` — a set of in-flight line IDs or discount codes, or a note/attributes boolean.
+3. When the promise resolves, the store folds that transaction into settled state and reapplies remaining projections. Overlapping mutations discard ambiguous response snapshots, then coalesce one authoritative cart refresh after the burst settles.
+4. On failure, the store removes only the failed projection, preserves unrelated work, and clears the matching pending entry.
+
+When overlapping mutations make response snapshots ambiguous, the store sets `state.revalidating` to `true`. It starts one authoritative refresh after those mutations settle and clears the flag when the refresh completes or fails. Until then, server-derived values such as costs remain at their last trustworthy value. A refresh failure preserves the locally reconciled cart and appears in `errors.network`.
+
+App-owned cart mutations outside Standard Actions do not emit the events the store normally observes. After such a mutation succeeds, call `CartStore.refresh()` directly or use the framework binding's `useCartActions().refresh()`. The refresh waits for active optimistic work, reconciles custom fragment fields from the configured cart endpoint, and loads the cart when none exists yet (e.g. one just created server-side). Do not call it after ordinary Hydrogen cart forms; their Standard Actions events already synchronize the store.
+
+The store supersedes keyed mutations for the same line, discount batch, note, or complete attribute list. Relative additions remain independent so every submitted quantity reaches the server; their projections are reconciled together without disabling controls.
+
+## Stable selectors
+
+Store selectors should select primitives or stable references from the store. Do not allocate arrays, objects, maps, sets, or derived view models inside a selector unless the framework binding also accepts an equality function.
+
+Bad:
+
+```ts
+const selectMessages = (state) => [
+  ...state.errors.network.map((error) => error.message),
+  ...state.errors.cart.userErrors.map((error) => error.message),
+];
+```
+
+That selector returns a new array whenever the store notifies subscribers, so bindings that rely on referential equality cannot skip unchanged output. Select stable slices first, then derive:
+
+```ts
+const selectErrors = (state) => state.errors;
+const messages = deriveFromErrors(errors, () => {
+  return [
+    ...errors.network.map((error) => error.message),
+    ...errors.cart.userErrors.map((error) => error.message),
+  ];
+});
+```
+
+## Pending state
+
+`state.pending` tracks what is currently in-flight:
+
+- `pending.lines` — `Set<string>` of line IDs with mutations in flight.
+- `pending.discountCodes` — `Set<string>` of discount codes being applied or removed.
+- `pending.cost` — `true` when pending line or discount mutations can leave totals stale.
+- `pending.note` — `boolean` indicating whether a note save is in flight.
+- `pending.attributes` — `boolean` indicating whether a complete attribute-list update is in flight.
+
+Any value whose entity is in a pending set is **optimistic and unconfirmed**. The UI must treat it differently from confirmed values.
+
+`state.revalidating` is `true` while the store refreshes authoritative cart-wide fields after overlapping mutations. Treat totals as unconfirmed and suppress cart analytics while it is true.
+
+## Error state
+
+`state.errors` is scoped to the entity that caused the error:
+
+- `errors.lines` — `Map<string, CartErrorGroup>` keyed by line ID.
+- `errors.discountCodes` — `Map<string, CartErrorGroup>` keyed by discount code string.
+- `errors.note` — `CartErrorGroup` for note-related errors.
+- `errors.attributes` — `Map<string, CartErrorGroup>` keyed by attribute key.
+- `errors.cart` — `CartErrorGroup` for cart-level errors not attributable to a specific entity.
+- `errors.network` — `CartNetworkEntry[]` for transport failures (timeouts, HTTP errors).
+- `errors.lastUpdatedAt` — timestamp of the most recent error update across any scope. Per-scope timestamps also exist (`linesUpdatedAt`, `discountCodesUpdatedAt`, `attributesUpdatedAt`, etc.).
+
+Each `CartErrorGroup` contains `{ userErrors: CartUserError[], warnings: CartWarning[] }`.
+
+Errors survive unrelated cart work and clear when a new mutation begins for the same key.
+
+---
+
+## Rules
+
+### Money
+
+- **NEVER calculate currency amounts on the client.** Display server-provided amounts (`line.cost.totalAmount`, `state.data.cost.subtotalAmount`, etc.) directly. Client-side arithmetic drifts from the truth when discounts, taxes, duties, or rounding apply. If a value is stale because a mutation is in-flight, show it with pending UI — not a client-computed estimate.
+- **Format with Hydrogen money helpers**, not string concatenation. Use the local `hydrogen-money` skill for an app wrapper around `formatMoney()`. The store provides `amount` (string) and `currencyCode` (string).
+
+### Optimistic interactions
+
+- **Keep rapid-action controls interactive during pending state.** Increase, decrease, remove, apply, and remove-discount controls must remain interactive. The store's abort-controller pattern makes concurrent mutations safe — a new click supersedes the in-flight request. A save-style editor, such as a gift-message attribute form, may disable its own submit button while its scoped mutation is pending when duplicate saves provide no value. Disabling for a non-pending reason is also fine — for example, the decrease control may be disabled when the quantity is already `<= 1`.
+- **Inventory-aware set-quantity clamping is opt-in.** The default cart query does not request `ProductVariant.quantityAvailable` because that field requires the `unauthenticated_read_product_inventory` Storefront API scope. If a cart UI needs the entered quantity to clamp to sellable inventory before submission, add `quantityAvailable` to the app's custom cart fragment and enable the Hydrogen channel's product inventory permission (`unauthenticated_read_product_inventory`). Without that field, let Shopify validate inventory and surface the returned line error.
+- **NEVER show a spinner or skeleton where a stale value would do.** The user already sees a quantity and a price. Replacing confirmed-looking content with a loading state is a regression. Show the previous value with a visual indicator that it's unconfirmed.
+- **ALWAYS visually indicate unconfirmed data.** Any value whose entity is in a `pending` set must look visually distinct from confirmed values. Reduced opacity is the reference pattern — the stale text acts as a spatial placeholder (like a skeleton), not as readable content. Rules of contrast can be disregarded because the pending value is a signal, not content the user needs to read.
+- **NEVER block navigation during pending.** Cart mutations are fire-and-forget from the user's perspective. No confirmation dialogs on route change.
+
+### Errors
+
+- **ALWAYS display errors closest to the element they describe.** A line item error appears next to that line item. A discount code error appears next to that discount code. Errors should not only live in a distant banner.
+- **Use a banner only for errors that have no inline home.** This includes: network errors, cart-level errors, and orphaned line errors.
+- **Orphaned line errors** — when `errors.lines` contains entries for line IDs not present in `state.data.lines.nodes`, those errors have no inline target. Surface them in the banner. This happens when a line was removed but the server returned errors referencing its ID.
+- **Inline errors must be accessible** — use `role="alert"` and link them to the nearest interactive element via `aria-describedby`. Mark the associated input as `aria-invalid="true"`.
+- **Use `errors.lastUpdatedAt` for dismissal.** Track a local `dismissedAt` timestamp. If `lastUpdatedAt <= dismissedAt`, the banner is hidden. If a new error arrives with a newer timestamp, the banner reappears.
+
+### Note editing
+
+- **Maintain a local draft** for the note, synced from the store. When the server responds with an updated note, only overwrite the local draft if `pending.note` is `false`. This prevents the server response from clobbering the user's in-progress typing.
+- **Allow users to click the save button even when the draft matches the stored note** (nothing to save), but prevent any action. This enables progressive enhancement and prevents frustration.
+- **Show a pending indicator** while the note mutation is pending.
+
+### Cart attribute editing
+
+- **Treat an attribute update as complete-list replacement.** `attributes-update` sends the full next attribute list; attributes omitted from the submission are removed. When editing one attribute, explicitly include every unrelated existing attribute as a hidden keyed `attributeValue` field. Submit no attribute fields to clear all attributes.
+- **Keep each key attached to its value.** Pass the attribute key to every `register("attributeValue", {key, ...})` call. The generated `attributes.<key>` field name encodes that key, so the server never relies on parallel field positions. Storefront API mutation inputs require string values, so normalize a nullable returned value deliberately (usually to `""`) before resubmitting it.
+- **Use the register contract exactly.** Call `register("attributeValue", {key, ...})` rather than spelling its generated `attributes.<key>` field name by hand. The submit intent is kebab-case (`attributes-update`) because action intents follow the existing `discount-apply`, `discount-remove`, and `note-update` convention.
+- **Maintain a local draft** for an editable attribute when the UI can remain mounted across server responses. Only sync confirmed attribute data into that draft while `pending.attributes` is `false`, so a response does not clobber typing that happened during the request.
+- **Show scoped pending and errors.** Use `pending.attributes` for the save state and display entries from `errors.attributes` next to the editor for the matching key. A save-style submit button may be disabled until the attribute promise settles.
+
+### Form structure
+
+- **Each line item is its own form.** This gives each line its own identity input and its own submit buttons. A single form containing multiple lines creates ambiguity about which line an action targets.
+- **Each line item form must preserve the progressive-enhancement shape.** The rendered structure will vary by framework and design system, but every line item quantity form needs the same Hydrogen contract: `register("set")`, `register("lineId", { value: line.id })`, and a real editable quantity input using `register("quantity", { value: line.quantity, interactive: true })`. Increase, decrease, and remove buttons are additional submit controls, not replacements for the set intent or the quantity input.
+- **The `set` control is a hidden submit button, not a hidden input.** `register("set")` already returns `{ type: "submit", hidden: true }`; render it on a `<button>`. Do not swap it for `<input type="hidden">` — that removes the submit button, so pressing Enter in the quantity input no longer submits the set action.
+- **Each discount "remove" button is its own form** — separate from the "apply" form. The apply form needs input validation (empty/duplicate prevention); each remove form is a single action.
+- **Attribute forms submit keyed values.** Render one `register("attributeValue", {key, value})` control for every attribute in the complete next list, then submit with `register("attributes-update")`.
+
+### Loading
+
+- **While `loading` is `true`**, show skeleton placeholders — not empty state. The cart hasn't been fetched yet.
+- **When `loading` is `false` and `lines` is empty**, show empty state ("Your cart is empty" or equivalent).
+- **If resolved `initialData` is provided** when creating the store, `loading` starts as `false` and the initial fetch is skipped. `initialData` is the cart handler data envelope (`{cart, errors?}`), not only the cart object. Use resolved data when the response should include full cart HTML. **If promise `initialData` is provided**, `loading` starts as `true`, `state.readyPromise` tracks readiness, and `useSuspenseCart` can suspend cart content while the app shell stays non-blocking. Use promises when the backend can stream them into the HTML response. `{cart: null}` means the server already completed the bootstrap with no usable cart, so the UI should render empty state without a browser retry. `undefined` means no server bootstrap was provided, so the store fetches `/api/cart` after hydration; use this only when a client-side fetch is acceptable, such as an SPA. Cart server handlers log bootstrap errors before returning them, so app loaders should forward handler data instead of logging or throwing those errors again.
+
+---
+
+## User Acceptance Tests
+
+### Line items
+
+1. **Increase quantity** — Click the increase control. The displayed quantity increments immediately. The quantity and totals appear in their pending visual state until the server confirms.
+2. **Decrease quantity** — Click the decrease control. Same optimistic behavior. At quantity 1, decreasing removes the line.
+3. **Remove line** — Activate the remove control. The line disappears immediately. Totals update optimistically.
+4. **Rapid clicks** — Click increase five times quickly. Each click increments the displayed quantity by one. The store aborts intermediate requests. The final server-confirmed state matches the quantity the user sees.
+5. **Failure rollback** — If the server rejects a line update, the quantity reverts to the last confirmed value. An error message appears inline next to the affected line item.
+6. **Line-scoped error** — When the server returns a `userError` scoped to a specific line, the message appears adjacent to that line (not only in a banner). The relevant input is marked `aria-invalid`.
+7. **Progressive quantity set** — The line item form contains a hidden `set` submit control, hidden/read-only `lineId`, and an editable quantity input. Pressing Enter in the quantity input submits a set-quantity action.
+8. **No-JS line update** — If JavaScript fails or hydration has not run, the line item form can still submit an explicit quantity value to the cart action endpoint.
+
+### Discount codes
+
+9. **Apply discount** — Enter a code and submit. The code appears in the list immediately in its pending visual state. When the server confirms, the pending indicator clears and the "applied" / "not applicable" status updates.
+10. **Duplicate prevention** — Submitting a code that is already present does nothing.
+11. **Empty input prevention** — Submitting with a blank input does nothing.
+12. **Remove discount** — Activate the remove control next to a code. The code disappears optimistically.
+13. **Discount-scoped error** — If the server returns an error for a specific code, the message appears next to that code in the list.
+
+### Order note
+
+14. **Save note** — Edit the text and submit. A pending indicator appears while the mutation is in-flight.
+15. **No-op save** — When the draft matches the stored note, clicking on save does nothing (but can still be clicked).
+16. **Server sync without clobber** — After save completes, the local draft updates to match the server response — but only when `pending.note` is `false`, preserving any typing the user did in the meantime.
+
+### Cart attributes
+
+17. **Save attribute** — Edit an attribute and submit. The optimistic value appears immediately, `pending.attributes` is `true`, and the editor shows a saving state until confirmation.
+18. **Preserve unrelated attributes** — Saving one attribute includes all unrelated existing key/value pairs; those attributes remain after the server response.
+19. **Clear attributes** — Submitting an empty attribute list removes every cart attribute.
+20. **Failure rollback** — If the update fails, the complete attribute list returns to the last confirmed baseline.
+21. **Attribute-scoped error** — An error for a key appears next to that key's editor and marks its input invalid.
+22. **No draft clobber** — Typing that occurs while an attribute save is pending is not overwritten by the confirming response.
+
+### Error banner
+
+23. **Network error** — When a mutation fails due to a transport error, a banner appears with the error message and a dismiss control.
+24. **Cart-level error** — Errors not attributable to a line, code, note, or attribute appear in the banner.
+25. **Orphaned line error** — If a line no longer exists in `state.data.lines.nodes` but `errors.lines` has an entry for its ID, that error appears in the banner.
+26. **Dismiss and re-trigger** — Dismissing the banner hides it. A subsequent error (with a newer `lastUpdatedAt`) re-shows it.
+
+### Totals
+
+27. **Pending totals** — While any line or discount mutation is in-flight, subtotal and total appear in their pending visual state. The amounts shown are the last server-confirmed values — never client-computed.
+28. **Settled totals** — After an ordinary mutation settles, totals display the latest server values. Overlapping mutation bursts retain pending styling and the last trustworthy amounts while one authoritative cart refresh is in flight.
+
+### Loading
+
+29. **Initial load** — Before the cart is fetched, show skeleton placeholders.
+30. **Empty cart** — After fetch completes with zero lines, show empty state.
+
+### Out-of-band mutations
+
+31. **Refresh custom data** — After an app-owned cart mutation succeeds, request a cart refresh. Every cart consumer receives the updated custom fragment data, `revalidating` represents the refresh, and a refresh failure preserves the confirmed cart while appearing in `errors.network`.
+
+---
+
+## Anti-patterns
+
+- **Hand-rolled framework cart state.** If the skill has a matching framework reference, use its provider/hooks/helpers. Otherwise, use the core store directly instead of duplicating cart data in component state or custom reducers.
+- **Client-seeded `/cart` page.** Mounting `CartProvider` with no `initialData` (or reading the cart only through a `"use client"` `useCart` hook) leaves the SSR HTML empty, so the `/cart` page cannot render the server cart. Read the cart in the server data path and pass `initialData`. Use resolved `initialData` when strict no-JS live cart HTML is required; use promise `initialData` when the framework can stream and hydrated cart content is wrapped in Suspense.
+- **Quantity as text only.** Rendering quantity as a `<span>` with only plus/minus buttons breaks the set-quantity path and the no-JS fallback. Use a real input wired with `register("quantity", { value, interactive: true })`.
+- **Plus/minus-only line forms.** Increase/decrease/remove buttons do not replace `register("set")` and the interactive quantity input. Omitting them breaks the form invariant even if hydrated clicks appear to work.
+- **Drawer-specific line form drift.** The cart drawer may have a different layout from the `/cart` page, but its line item forms must keep the same Hydrogen form contract. Prefer sharing line item form components between the page and drawer.
+- **Banner-only errors.** A line-level error displayed far from the line it refers to is effectively invisible. Show inline first; promote to the banner only when there's no inline target.