@doswiftly/storefront-operations 16.1.0 → 18.0.0

package/CHANGELOG.md

@@ -1,5 +1,885 @@
 # Changelog
 
+## 18.0.0
+
+### Major Changes
+
+- 1d51cc7: Schema MAJOR: nine String/`[String]` image URL fields replaced with `Image`/`[Image!]!`. Every storefront-facing image field now supports `Image.url(transform: ...)` and multi-tenant CDN signing on shop-owned media. Migration touches return, brand, shipping carrier, loyalty benefit, product review, attribute swatch, and payment surfaces.
+
+  **Why**: This is the final batch of the image-transform pipeline sweep. Previously these nine fields returned a raw string (or list of strings), so storefronts could not request specific sizes, formats, or crops. After this change, every image-bearing field on the storefront API exposes the same `Image` shape as `Product` and `ProductVariant` — pass an `ImageTransformInput` to the `url` argument to get a responsive variant, and rely on imgproxy signing where the merchant uploaded media to our CDN.
+
+  **Schema diff (9 fields)**:
+
+  | Type                      | Before                  | After               |
+  | ------------------------- | ----------------------- | ------------------- |
+  | `ReturnLineItem`          | `imageUrl: String`      | `image: Image`      |
+  | `Brand`                   | `logo: String`          | `logo: Image`       |
+  | `BrandFilterValue`        | `logo: String`          | `logo: Image`       |
+  | `ShippingCarrier`         | `logoUrl: String`       | `logo: Image`       |
+  | `TierBenefit`             | `icon: String`          | `icon: Image`       |
+  | `ProductReview`           | `images: [String]`      | `images: [Image!]!` |
+  | `AttributeSwatch`         | `imageUrl: String`      | `image: Image`      |
+  | `PaymentMethod`           | `icon: String`          | `icon: Image`       |
+  | `PaymentMethodInstrument` | `brandImageUrl: String` | `brandImage: Image` |
+
+  **Migration — pick a thumbnail fragment and replace selections**:
+
+  The storefront-operations package ships an `ImageThumbnail` fragment (`{ id, url(transform: { maxWidth: 300 }), altText, width, height, thumbhash }`) plus `ImageCard` (maxWidth 800) and `ImageFull` (maxWidth 1600). Pick the size that matches where you render the image.
+
+  ```diff
+  fragment ReturnItem on ReturnItem {
+     id
+     variantTitle
+  -  imageUrl
+  +  image {
+  +    ...ImageThumbnail
+  +  }
+  }
+
+  fragment ShippingCarrier on ShippingCarrier {
+     id
+     name
+  -  logoUrl
+  +  logo {
+  +    ...ImageThumbnail
+  +  }
+     serviceCode
+  }
+
+  fragment AttributeSwatch on AttributeSwatch {
+     colorHex
+  -  imageUrl
+  +  image {
+  +    ...ImageThumbnail
+  +  }
+  }
+
+  fragment ProductReview on ProductReview {
+     id
+     rating
+  -  images
+  +  images {
+  +    ...ImageThumbnail
+  +  }
+  }
+
+  fragment LoyaltyTier on LoyaltyTier {
+     id
+     name
+     customBenefits {
+       name
+       description
+  -    icon
+  +    icon {
+  +      ...ImageThumbnail
+  +    }
+     }
+  }
+
+  fragment PaymentMethod on PaymentMethod {
+     id
+     name
+     type
+  -  icon
+  +  icon {
+  +    ...ImageThumbnail
+  +  }
+  }
+
+  fragment PaymentMethodInstrument on PaymentMethodInstrument {
+     providerCode
+     instrumentCode
+     displayName
+  -  brandImageUrl
+  +  brandImage {
+  +    ...ImageThumbnail
+  +  }
+     enabled
+  }
+
+  # Brand (used inside MenuItem.resource union and as Product.brand)
+  {
+     brand {
+       id
+       handle
+       name
+  -    logo
+  +    logo {
+  +      ...ImageThumbnail
+  +    }
+     }
+  }
+
+  # BrandFilterValue (used inside AvailableFilters.brands)
+  {
+     brands {
+       id
+       handle
+       name
+  -    logo
+  +    logo {
+  +      ...ImageThumbnail
+  +    }
+       productCount
+     }
+  }
+  ```
+
+  **Field renames** (additional to type changes):
+  - `ShippingCarrier.logoUrl` → `ShippingCarrier.logo`
+  - `AttributeSwatch.imageUrl` → `AttributeSwatch.image`
+  - `ReturnLineItem.imageUrl` → `ReturnLineItem.image`
+  - `PaymentMethodInstrument.brandImageUrl` → `PaymentMethodInstrument.brandImage`
+
+  Rename + type change happen in the same release; you have to update both the field name and the selection set.
+
+  **Inline transform alternative**: if you do not want to use `ImageThumbnail`, you can request the URL with an explicit transform — the result is identical:
+
+  ```graphql
+  {
+    carrier {
+      logo {
+        url(transform: { maxWidth: 64, preferredContentType: WEBP })
+        altText
+      }
+    }
+  }
+  ```
+
+  **Migration checklist**:
+  - [ ] Update every fragment listed above so the selection set requests `url`/`altText`/etc. instead of treating the field as a scalar.
+  - [ ] Rename selections for the four fields that changed name (`logoUrl`/`imageUrl`/`brandImageUrl`).
+  - [ ] Re-run codegen so your generated TypedDocumentNode bindings reflect the new shape.
+  - [ ] If your UI rendered the old string URL directly, switch to consuming `field.url` (and optionally `field.altText`); pick the transform size that matches your component.
+  - [ ] `ProductReview.images` is now a non-null list of non-null `Image` values — drop any defensive null handling around individual elements but keep the empty-array case.
+
+  **No backend-input breakage**: `ReviewCreateInput.images` still takes `[String]` URLs from the customer at submission time. Only the response field changed shape.
+
+- e28e902: Payment schema naming overhaul — one coherent provider / method / instrument model.
+
+  **Why**: payment fields mixed three concepts under inconsistent names — a `ProviderCode` enum, a `PaymentMethodInstrument` object whose fields were `instrumentCode` / `providerCode`, and `*Code`-suffixed mutation inputs. Every payment field now follows a single convention: **provider** (who processes the payment — `PAYU`, `PRZELEWY24`), **method** (the category the buyer picks — `BLIK`, `CARD`), **instrument** (the concrete option within a method — a specific BLIK code or bank deep-link).
+
+  **Breaking**:
+  1. Enum `ProviderCode` → `PaymentProvider` (values unchanged: `PAYU`, `PRZELEWY24`, `STRIPE`, ...).
+  2. Object `PaymentMethodInstrument` → `PaymentInstrument`; field `instrumentCode` → `code`, field `providerCode` → `provider`.
+  3. Enums `PaymentMethodInstrumentType` → `PaymentInstrumentType`, `PaymentMethodInstrumentDisplayHint` → `PaymentInstrumentDisplayHint`.
+  4. `Cart.selectedPaymentInstrumentCode` → `Cart.selectedPaymentInstrument`.
+  5. `CartSelectPaymentMethodInput`: `preferredProviderCode` → `preferredProvider`, `preferredInstrumentCode` → `preferredInstrument`.
+  6. `CartSelectPaymentMethodInput.preferredProvider` is now the `PaymentProvider` enum (UPPERCASE: `PAYU`, `PRZELEWY24`, ...) instead of a lowercase `String`. It matches the output — `PaymentInstrument.provider` and `PaymentMethod.preferredProvider` are already `PaymentProvider` — so you read the value off the API and pass it straight back, no case conversion. The schema now self-documents the selectable gateways. (`preferredInstrument` stays `String` — instrument codes are gateway-specific.)
+
+  **Usage example**:
+
+  ```graphql
+  # before
+  fragment Instrument on PaymentMethodInstrument {
+    providerCode
+    instrumentCode
+    displayName
+  }
+  mutation Select($input: CartSelectPaymentMethodInput!) {
+    cartSelectPaymentMethod(input: $input) {
+      cart {
+        selectedPaymentInstrumentCode
+      }
+    }
+  }
+  # $input: { cartId, methodType: BLIK, preferredProviderCode: "payu", preferredInstrumentCode: "blik" }
+
+  # after
+  fragment Instrument on PaymentInstrument {
+    provider
+    code
+    displayName
+  }
+  mutation Select($input: CartSelectPaymentMethodInput!) {
+    cartSelectPaymentMethod(input: $input) {
+      cart {
+        selectedPaymentInstrument
+      }
+    }
+  }
+  # $input: { cartId, methodType: BLIK, preferredProvider: PAYU, preferredInstrument: "blik" }
+  #   ^ preferredProvider is the PaymentProvider enum (UPPERCASE) — read it from
+  #     `instrument.provider` / `method.preferredProvider` and pass it back verbatim.
+  ```
+
+  ```ts
+  // SDK types — before
+  import type {
+    PaymentMethodInstrument,
+    ProviderCode,
+  } from "@doswiftly/storefront-sdk";
+  const code = instrument.instrumentCode;
+  const who = instrument.providerCode;
+
+  // after
+  import type {
+    PaymentInstrument,
+    PaymentProvider,
+  } from "@doswiftly/storefront-sdk";
+  const code = instrument.code;
+  const who = instrument.provider;
+  ```
+
+  The pre-built `<PaymentInstrumentSection>` / `<PaymentInstrumentTile>` component props (`selectedInstrumentCode`, `onSelectInstrument`) are unchanged — only the instrument data shape (`.code`) changed.
+
+  **Migration checklist for existing storefronts**:
+  - [ ] Rename type references: `PaymentMethodInstrument` → `PaymentInstrument`, `ProviderCode` → `PaymentProvider`, `PaymentMethodInstrumentType`/`PaymentMethodInstrumentDisplayHint` → `PaymentInstrumentType`/`PaymentInstrumentDisplayHint`
+  - [ ] Field access: `instrument.instrumentCode` → `instrument.code`, `instrument.providerCode` → `instrument.provider`
+  - [ ] Cart selection: `cart.selectedPaymentInstrumentCode` → `cart.selectedPaymentInstrument`
+  - [ ] Mutation input: `preferredProviderCode` → `preferredProvider`, `preferredInstrumentCode` → `preferredInstrument`
+  - [ ] Mutation input value: pass the `PaymentProvider` enum (UPPERCASE) to `preferredProvider`, not a lowercase string — `preferredProvider: "payu"` → `preferredProvider: PAYU`. Drop any `.toLowerCase()` you applied to `instrument.provider` before sending it back.
+  - [ ] If you hand-write GraphQL operations: update fragments + re-run codegen against the published `schema.graphql`
+
+- 159184c: `ShipmentItem.imageUrl: String` replaced with `ShipmentItem.image: Image`.
+
+  **Why**: The previous `imageUrl` field returned a raw URL without transform support and was unreachable due to a resolver mapping bug (snapshot field names did not match what the storefront-facing mapper expected). The new `image: Image` field aligns shipment item images with `Product` and `ProductVariant` patterns — storefronts can request specific sizes, formats, and crops via `image { url(transform: { maxWidth: 200, preferredContentType: WEBP }) }`.
+
+  **Image source**: live variant image with snapshot fallback. The variant is loaded per-request via DataLoader (no N+1 cost when rendering many shipment items at once), and the resolved URL passes through the storefront's image transform pipeline so the requested dimensions/format are honored. When the variant has been deleted since the shipment was created, `image` returns `null` — render a placeholder client-side. The `title`, `variantTitle`, and `sku` fields stay as immutable snapshots from the time of fulfillment, so the tracking page still shows what was shipped even after a product is removed from the catalog.
+
+  **Migration**:
+
+  ```diff
+  fragment ShipmentItem on ShipmentItem {
+    id
+    title
+    variantTitle
+    sku
+    quantity
+  -  imageUrl
+  +  image {
+  +    ...ImageThumbnail
+  +  }
+  }
+  ```
+
+  Or, if you prefer to inline the transform without using the `ImageThumbnail` fragment:
+
+  ```diff
+  fragment ShipmentItem on ShipmentItem {
+    id
+    title
+    variantTitle
+    sku
+    quantity
+  -  imageUrl
+  +  image {
+  +    url(transform: { maxWidth: 200, preferredContentType: WEBP })
+  +    altText
+  +  }
+  }
+  ```
+
+  **Migration checklist**:
+  - [ ] Replace `imageUrl` selections in your `ShipmentItem` fragments / inline queries with `image { ...ImageThumbnail }` (or inline transform).
+  - [ ] Handle the `image: null` case in your ShipmentItem rendering (variant deleted after fulfillment — render a placeholder).
+  - [ ] Re-run codegen so your TypedDocumentNode bindings reflect the new shape.
+  - [ ] No SDK code changes are required beyond the regenerated operation types — the linked SDK bump exists to keep `@doswiftly/storefront-sdk` in version parity with `@doswiftly/storefront-operations`.
+
+- cc7edbe: SDK-BFF customer authentication — same-origin route handlers + automatic session refresh.
+
+  **Why**: Customer auth now runs entirely same-origin on your storefront domain through a backend-for-frontend layer. The browser never calls the commerce API for auth, and the refresh token never reaches JavaScript — it lives in a first-party httpOnly cookie read only server-side and exchanged server-to-server. This behaves identically on a platform subdomain, a custom domain, and off-platform hosting (e.g. Vercel), because the route handlers live on your own domain rather than depending on any edge layer.
+
+  **New**
+  - `createStorefrontAuthRoute({ apiUrl, shopSlug, isTrustedOrigin? })` (from `@doswiftly/storefront-sdk/react/server`) generates the `login` / `refresh` / `logout` / `whoami` route handlers. Mount once:
+
+    ```ts
+    // app/api/auth/[action]/route.ts
+    import {
+      createStorefrontAuthRoute,
+      trustedForwardedHostValidator,
+    } from "@doswiftly/storefront-sdk/react/server";
+
+    export const { GET, POST } = createStorefrontAuthRoute({
+      apiUrl: process.env.NEXT_PUBLIC_API_URL!,
+      shopSlug: process.env.NEXT_PUBLIC_SHOP_SLUG!,
+      isTrustedOrigin: trustedForwardedHostValidator, // when running behind a reverse proxy
+    });
+    ```
+
+  - `getInitialAuth()` (server-only) reads the first-party cookies and returns `{ isAuthenticated, accessToken, expiresAt }` to seed the provider on the first render — no flash of signed-out UI, no extra round-trip:
+
+    ```tsx
+    // app/layout.tsx (Server Component)
+    const { isAuthenticated, accessToken, expiresAt } = await getInitialAuth();
+    return (
+      <StorefrontProvider
+        initialIsAuthenticated={isAuthenticated}
+        initialAccessToken={accessToken}
+        initialExpiresAt={expiresAt}
+        /* ...config, shopData */
+      >
+        {children}
+      </StorefrontProvider>
+    );
+    ```
+
+  - `AuthClient.refreshSession()` refreshes the session via the same-origin `POST /api/auth/refresh`, returning `{ accessToken, expiresAt }`. The proactive scheduler (`autoRefresh`, on by default in the browser) and the reactive 401 retry now use it — so an already-expired access token still refreshes silently.
+
+  **Breaking**
+  1. Automatic refresh (the proactive scheduler and the 401 retry) now goes through `POST /api/auth/refresh` instead of a GraphQL refresh. You **must** mount `createStorefrontAuthRoute` for refresh to work.
+  2. `useSessionRefresh` no longer accepts an `authBasePath` option — the base path comes from the provider-configured auth client.
+  3. The refresh cookie is scoped to the auth base path (so logout can revoke the session), and the readable session-expiry hint cookie is long-lived (so a returning visitor is not shown as signed-out on a cold start).
+
+  **Migration checklist**
+  - [ ] Add `app/api/auth/[action]/route.ts` exporting `createStorefrontAuthRoute(...)`.
+  - [ ] Seed the provider from `getInitialAuth()` in your root layout (Server Component).
+  - [ ] Remove any `authBasePath` argument passed to `useSessionRefresh`.
+  - [ ] Subscribe with `useSessionExpired(cb)` to react globally (notice + redirect to sign-in).
+  - [ ] Behind a reverse proxy that rewrites `Host`, pass `isTrustedOrigin: trustedForwardedHostValidator`.
+
+  **Standards reference**: RFC 6265 (cookie path-matching), RFC 9700 (OAuth 2.0 security best current practice — token endpoints are public; security is protocol-level, not network allowlists).
+
+  `@doswiftly/storefront-operations` is version-synced with this release (linked pair); it has no operation changes in this entry.
+
+### Minor Changes
+
+- 9969bdd: Keep customer sessions alive automatically — proactive refresh + session-expiry awareness.
+
+  **Why**: an active buyer should never be logged out mid-session. The SDK now renews the access token for you, ahead of expiry, and exposes a single global signal for when a session truly cannot be saved.
+
+  **Additive (backward-compatible)**:
+  1. **Automatic proactive refresh** — on by default in the browser (off on the server): `<StorefrontProvider>` renews the access token shortly before it expires, reschedules from each new expiry, and recovers on tab wake. Nothing to pass and nothing to copy into your app; opt out with `autoRefresh={false}`. This is the primary protection — in the happy path the token is renewed before it ever expires.
+  2. **Global session-expired signal** — `useSessionExpired((event) => { ... })` fires when the session cannot be renewed (a refresh failed on tab wake, or a reactive refresh after a 401 also failed). Use it to show a notice and redirect to sign-in. The new `ErrorCodes.SESSION_EXPIRED` names the condition.
+  3. **Reactive recovery on a 401** — if a read request comes back with HTTP 401, the SDK runs a single, deduped refresh and replays the request automatically; a state-changing request never auto-retries — it bails and emits the session-expired signal instead.
+  4. **Session expiry in state** — the auth store now tracks `expiresAt` (ISO 8601), populated from login, refresh and the current-customer query; the access token stays in memory only and `expiresAt` is never persisted. A new `sessionExpiresAt` field is available on the `Customer` type, and `<StorefrontProvider initialExpiresAt>` seeds it during server rendering for an instant cold-start schedule.
+
+  **Usage**:
+
+  ```tsx
+  // works out of the box — proactive refresh is on by default in the browser
+  // (nothing to pass; opt out with autoRefresh={false})
+  <StorefrontProvider config={config} shopData={shopData}>
+    {children}
+  </StorefrontProvider>;
+
+  // anywhere near the root — react globally when a session could not be saved
+  useSessionExpired(() => {
+    toast("Your session expired — please sign in again.");
+    router.push("/login");
+  });
+  ```
+
+  **Migration**: none — everything is additive. `autoRefresh` is opt-out (default-on in the browser) and existing manual refresh flows keep working. The proactive refresh syncs the renewed token through the same `/api/auth/set-token` route you already use for login — no extra wiring. Point it elsewhere with `authBasePath` if your auth routes are mounted on a different base path.
+
+  ```
+
+  ```
+
+- 5525fd4: Version sync with `@doswiftly/storefront-sdk` (linked release group). No code change in this package — see the `@doswiftly/storefront-sdk` changelog for the additive `debug: 'verbose'` mode and `DebugOptions` granular controls.
+- 5525fd4: Version sync with `@doswiftly/storefront-sdk` (linked release group). No code change in this package — see the `@doswiftly/storefront-sdk` changelog for the additive runtime const exports of schema enums.
+- 9b62091: `PaymentMethodType` exposes two additional categories that the platform already supports server-side: `WALLET` (Apple Pay / Google Pay / Visa Mobile) and `INSTALLMENT` (Klarna, PayPo, Twisto, Alior Raty). Storefront code can now branch on them without falling through to `OTHER`.
+
+  **Why** — the GraphQL `PaymentMethodType` enum had drifted away from the underlying domain enum: PayU and Przelewy24 adapters were already mapping payByLink / method names to `WALLET` and `INSTALLMENT` (Apple Pay, Google Pay, BNPL providers), but the public GraphQL enum only declared `CARD / BLIK / BANK_TRANSFER / CASH_ON_DELIVERY / OTHER`. A storefront calling `getAvailablePaymentMethods` against a shop with Apple Pay enabled would crash with `Enum "PaymentMethodType" cannot represent value: "WALLET"`. The enum is now sourced from a single domain definition — drift between the platform's internal enum and the public GraphQL enum is structurally impossible going forward.
+
+  **Additive (backward-compatible)**:
+
+  Two new runtime values exposed by the const + type alias (per `enumsAsConst` codegen):
+
+  ```ts
+  import { PaymentMethodType } from "@doswiftly/storefront-sdk";
+
+  PaymentMethodType.Wallet; // 'WALLET'
+  PaymentMethodType.Installment; // 'INSTALLMENT'
+
+  Object.values(PaymentMethodType);
+  // ['BANK_TRANSFER', 'BLIK', 'CARD', 'CASH_ON_DELIVERY', 'INSTALLMENT', 'OTHER', 'WALLET']
+  ```
+
+  The TypeScript union type widens correspondingly to include `'WALLET' | 'INSTALLMENT'`. Existing code that handled `'OTHER'` as a catch-all keeps working — methods previously falling through to `OTHER` now report their specific category, and any exhaustive switch on `PaymentMethodType` gets a compile error pointing at the missing case.
+
+  **Usage example** — render brand-correct iconography for wallet checkouts:
+
+  ```tsx
+  import { PaymentMethodType } from "@doswiftly/storefront-sdk";
+
+  function PaymentMethodIcon({ type }: { type: PaymentMethodType }) {
+    switch (type) {
+      case PaymentMethodType.Card:
+        return <CardIcon />;
+      case PaymentMethodType.Blik:
+        return <BlikIcon />;
+      case PaymentMethodType.BankTransfer:
+        return <BankIcon />;
+      case PaymentMethodType.Wallet:
+        return <WalletIcon />; // NEW — Apple Pay / Google Pay
+      case PaymentMethodType.Installment:
+        return <InstallmentIcon />; // NEW — Klarna / PayPo / Twisto
+      case PaymentMethodType.CashOnDelivery:
+        return <CashIcon />;
+      case PaymentMethodType.Other:
+        return <GenericPaymentIcon />;
+    }
+  }
+  ```
+
+  **Migration checklist** — none required for storefronts that already routed `OTHER` to a generic icon:
+  - [ ] (Optional) Add explicit branches for `Wallet` / `Installment` in payment method UI to render brand-correct iconography (Apple Pay logo, Klarna logo, etc.) instead of the generic fallback.
+  - [ ] (Optional) If you ran exhaustive `switch (method.type)` blocks asserted with `never`-check, add the two new cases — the compiler points at them on the next build.
+
+  **Standards reference** — Apple Pay / Google Pay are typically classified under "digital wallet" payment methods in industry catalogues (Stripe, Adyen, Braintree all use `wallet` as a top-level category). `INSTALLMENT` covers Buy-Now-Pay-Later providers that present multi-instalment options at checkout.
+
+- 78bd561: Version sync with `@doswiftly/storefront-sdk` (linked release group). No code change in this package — see the `@doswiftly/storefront-sdk` changelog for the additive `<StorefrontProvider initialAccessToken>` prop and `authStore.setAuth` signature relax.
+- 5525fd4: Version sync with `@doswiftly/storefront-sdk` (linked release group). No code change in this package — see the `@doswiftly/storefront-sdk` changelog for the additive `useCartManager` checkout suite and `complete()` auto-cleanup.
+- 468f70b: Version sync with `@doswiftly/storefront-sdk` (linked release group). No code change in this package — see the `@doswiftly/storefront-sdk` changelog for the additive `useCartManager({ initialCartId })` server-known seed.
+
+### Patch Changes
+
+- 9bac7e9: Fix stale field names in the `CartSelectPaymentMethodInput` description. The input's description still referenced `preferredProviderCode` / `preferredInstrumentCode` after those fields were renamed to `preferredProvider` / `preferredInstrument`. Description-only correction — field names, types and behavior are unchanged.
+- 9857460: Polished all GraphQL schema descriptions to consistent professional English (documentation only — no contract changes).
+- a5a3f4b: Image transform pipeline extended to shop-owned content surfaces: `BlogCategory.image`, `BlogPost.featuredImage`, `LoyaltyReward.image`, and `MenuItem.image`.
+
+  These four fields already accepted an `Image.url(transform: ...)` selection, but the URL was not threaded through the storefront CDN context, so any URL stored as a relative path (rather than a full https URL) skipped the imgproxy signing step. Now all four resolvers build the CDN context per query and pass it to `mapImageToGraphQL`, so transform-aware URLs honor multi-tenant signing on shop-owned media.
+
+  No schema changes. Selections that already used `image { url(transform: ...) }` keep working — the only behavior change is that URLs stored as relative paths are now CDN-signed before transforms apply. URLs stored as absolute https values keep returning unchanged (the helper falls back to the raw value when there is no path component).
+
+  **What this enables**:
+
+  ```graphql
+  query BlogList {
+    blogPosts(first: 10) {
+      edges {
+        node {
+          title
+          featuredImage {
+            url(transform: { maxWidth: 800, preferredContentType: WEBP })
+            altText
+          }
+        }
+      }
+    }
+  }
+  ```
+
+  The same `image { url(transform: ...) }` pattern is also valid on `BlogCategory`, `LoyaltyReward`, and `MenuItem`.
+
+  **No migration required.**
+
+- 0c0205d: Image transform support extended to `Cart.lines[].variant.image`, `Order.lineItems[].variant.image`, `Collection.image`, and `Category.image`.
+
+  Previously these four image fields returned a plain object that did not pass through the storefront image pipeline, so calling `image { url(transform: { maxWidth: 200, preferredContentType: WEBP }) }` silently returned a raw URL without applying the requested size/format. Now all four resolvers map images through the same transform pipeline used by `Product` and `ProductVariant`, so `Image.url(transform: ...)` honors the requested dimensions and format.
+
+  No schema changes — selections that already used `image { url }` keep working and start receiving the transform-aware URL when a transform argument is supplied. Selections that already used `image { url(transform: ...) }` now apply the transform end-to-end.
+
+  **What you can do now**:
+
+  ```graphql
+  query CartThumbnails {
+    cart {
+      lines {
+        edges {
+          node {
+            variant {
+              image {
+                url(transform: { maxWidth: 200, preferredContentType: WEBP })
+                altText
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+  ```
+
+  The same `image { url(transform: ...) }` pattern is now valid on `Order.lineItems[].variant`, `Collection.image`, and `Category.image`.
+
+  **No migration required** — existing storefronts continue to work. To take advantage of transforms on these surfaces, switch hardcoded sizes in your `<img src>` rendering to a parametrized `url(transform: ...)` selection.
+
+- 9c55b39: Export the payment enums `PaymentProvider`, `PaymentInstrumentType`, `PaymentInstrumentDisplayHint` and `PaymentMethodUnavailableReason` from the package root.
+
+  **Why**: these enums were already generated but only reachable via a deep import path, which reads as private API. They are now re-exported from the package entry point alongside the other schema enums (`PaymentMethodType`, `DeliveryType`, ...), so you can type a wrapper around `cartSelectPaymentMethod` — whose `preferredProvider` input is the `PaymentProvider` enum — without reaching into internals.
+
+  **Additive (backward-compatible)**: each enum is both a runtime value (`Object.values(PaymentProvider)`) and a type (`import type { PaymentProvider }`). No existing import changes.
+
+  **Usage example**:
+
+  ```ts
+  import { PaymentProvider } from "@doswiftly/storefront-sdk";
+
+  // Type a wrapper prop:
+  type SelectArgs = { preferredProvider?: PaymentProvider };
+
+  // Or read the value at runtime:
+  const all = Object.values(PaymentProvider); // ['PAYU', 'PRZELEWY24', ...]
+  ```
+
+  **Migration checklist**: optional — if you used a deep import to reach these enums, switch to the package root import.
+
+  `@doswiftly/storefront-operations` carries a version-sync bump only — no operation or schema change.
+
+- 8c0d8fa: Expose `operations.json` through the package `exports` map.
+
+  **Why**: Documentation generators, MDX components, and other build-time tools need structural access to operation metadata (name, kind, section, description, variables, fragmentRefs, body) without parsing raw `.graphql` files. The `operations.json` file was already published in the npm tarball; this change makes it consumable via a typed subpath import.
+
+  **Additive (backward-compatible)**:
+
+  ```ts
+  // New: structural import of all operations
+  import operations from "@doswiftly/storefront-operations/operations.json";
+
+  console.log(operations.queries.length); // 52
+  console.log(operations.mutations.length); // 41
+
+  // Existing imports unchanged:
+  import schema from "@doswiftly/storefront-operations/schema.graphql";
+  ```
+
+  **Usage example** — build-time docs generation:
+
+  ```ts
+  import operations from "@doswiftly/storefront-operations/operations.json";
+
+  const cartOps = operations.mutations.filter(
+    (op) => op.section === "Cart Mutations",
+  );
+
+  for (const op of cartOps) {
+    console.log(`${op.name}: ${op.description}`);
+    console.log(
+      `  Variables: ${op.variables.map((v) => `${v.name}: ${v.type}`).join(", ")}`,
+    );
+  }
+  ```
+
+  **Migration checklist**: none — additive change, existing consumers unaffected.
+
+## 17.0.0
+
+### Major Changes
+
+- d3f0f04: `cartSelectPaymentMethod` mutation is now method-centric.
+
+  The buyer picks a payment **category** (`BLIK`, `CARD`, `BANK_TRANSFER`, ...) and the backend resolves the preferred gateway from the merchant's `MerchantPaymentConfig` at `paymentCreate` time. Previously the storefront had to look up a per-provider tile UUID via `availablePaymentMethods` and pass it as `paymentMethodId`.
+
+  **Breaking** — `CartSelectPaymentMethodInput` shape changed:
+
+  ```graphql
+  # Before
+  input CartSelectPaymentMethodInput {
+    cartId: ID!
+    paymentMethodId: ID! # UUID of a per-provider tile
+  }
+
+  # After
+  input CartSelectPaymentMethodInput {
+    cartId: ID!
+    methodType: PaymentMethodType! # BLIK, CARD, BANK_TRANSFER, ...
+    preferredProviderId: String # optional override (provider code)
+  }
+  ```
+
+  Migration:
+
+  ```ts
+  // Before
+  await sdk.cartSelectPaymentMethod({ input: { cartId, paymentMethodId } });
+
+  // After
+  await sdk.cartSelectPaymentMethod({ input: { cartId, methodType: "BLIK" } });
+  // Or with explicit gateway override:
+  await sdk.cartSelectPaymentMethod({
+    input: { cartId, methodType: "BLIK", preferredProviderId: "payu" },
+  });
+  ```
+
+  The `availablePaymentMethods` query now returns deduplicated rows per `PaymentMethodType` (one row per BLIK, CARD, ...) with `providersAvailable` (gateway codes sorted by merchant priority) and `preferredProvider` (head of the list). The legacy `group: BY_PROVIDER` argument was removed — there is one canonical shape.
+
+  **Why** — A merchant configuring PayU + Przelewy24 would previously see "PayU BLIK" and "P24 BLIK" as two separate tiles on the storefront. After this change the storefront shows one BLIK tile; the merchant chooses which gateway handles BLIK via priority settings, and the buyer never sees the internal routing.
+
+  **Live capability sync (opt-in)** — gateway adapters may expose an optional `getAvailablePaymentMethods(credentials, { currency, amount, country })` capability returning the gateway-reported active methods (min/max amount, brand image, enabled flag). When supported, the platform caches the response per shop/currency and uses it to refine the storefront picker. Gateways without the capability fall back to a static capability matrix. Gateway HTTP failures are soft-failed — the buyer always sees the merchant's configured methods even when the upstream is temporarily unreachable.
+
+- 7931668: Payment instrument preselection — direct deep-link to a specific instrument screen on the hosted gateway page (BLIK code, branded bank, wallet, card brand) instead of the gateway default landing.
+
+  **Why**: shoppers picking BLIK from the storefront UI now skip the gateway method picker entirely — the redirect lands directly on the BLIK code entry. Same flow for picking mBank, ING, Apple Pay, etc. Industry shorthand calls this "deep-link checkout" — 5-15% conversion uplift on single-instrument funnels.
+
+  **Breaking schema changes**:
+  1. `CartSelectPaymentMethodInput.preferredProviderId` → `preferredProviderCode`. Rename only — same semantics (override the merchant's preferred provider). Aligns with the `*Code` naming convention (`*Id` reserved for UUIDs, `*Code` for lowercase string identifiers like `payu` / `przelewy24`).
+
+     ```graphql
+     # Before
+     input CartSelectPaymentMethodInput {
+       cartId: ID!
+       methodType: PaymentMethodType!
+       preferredProviderId: String # ← removed
+     }
+
+     # After
+     input CartSelectPaymentMethodInput {
+       cartId: ID!
+       methodType: PaymentMethodType!
+       preferredProviderCode: String # ← renamed
+       preferredInstrumentCode: String # ← new (additive)
+     }
+     ```
+
+  2. `PaymentMethod.provider` / `PaymentMethod.providersAvailable` / `PaymentMethod.preferredProvider` / `Order.paymentMethod` / `Payment.provider` are now the typed `ProviderCode` enum (UPPERCASE: `PAYU`, `PRZELEWY24`, `STRIPE`, `CASH_ON_DELIVERY`, `BANK_TRANSFER`, `MANUAL_PAYMENT`, `GIFT_CARD`, `TEST_GATEWAY`) instead of `String`. Replace any `if (provider === 'payu')` storefront branches with the imported enum.
+
+     ```ts
+     // Before
+     if (paymentMethod.provider === "payu") {
+       /* ... */
+     }
+
+     // After
+     import { ProviderCode } from "@doswiftly/storefront-sdk";
+     if (paymentMethod.provider === ProviderCode.PAYU) {
+       /* ... */
+     }
+     ```
+
+  3. `PaymentMethod.amountLimits` removed from the SDK fragment. The field still exists on the schema for backward-compat, but the SDK no longer selects it — most storefronts never used it and the data is provider-specific (PayU/P24 report limits per method, not per checkout). Re-add it to your local fragment if you need it.
+
+  **Additive (backward-compatible)**:
+  - `PaymentMethod.instruments: [PaymentMethodInstrument!]` — concrete instruments exposed by the gateway (BLIK code, branded banks, wallets, card brands). Each instrument carries `providerCode`, `instrumentCode`, `displayName`, `brandImageUrl`, `displayHint` (semantic UX hint: `PIN_ENTRY` / `WALLET_TAP` / `BANK_LIST` / `CARD_FORM`), `enabled`. `null` when the gateway doesn't expose granular data; empty array when all instruments are disabled.
+  - `cartSelectPaymentMethod(input: { preferredInstrumentCode })` — pass the chosen instrument's `instrumentCode` to persist it on the cart. Eager validation cross-checks against the gateway's live capabilities — invalid codes return `userErrors[].code = 'CART_INVALID_INSTRUMENT_CODE'`.
+  - `Cart.selectedPaymentInstrumentCode: String` — round-trips the persisted choice so the storefront can re-render the selected instrument on cart refresh.
+  - `Order.paymentInstrumentCode: String` — propagated from cart at `cartComplete`; the gateway adapter uses it to build the deep-link payload at `paymentCreate`.
+
+  **Usage example** — instrument-level deep-link checkout:
+
+  ```ts
+  import { useCartManager, ProviderCode } from "@doswiftly/storefront-sdk";
+
+  const { selectPaymentMethod, complete, createPayment } = useCartManager();
+
+  // 1. Render the instrument tiles from the gateway-reported list
+  const method = availablePaymentMethods.methods.find((m) => m.type === "BLIK");
+  const instrument = method?.instruments?.find(
+    (i) => i.instrumentCode === "blik",
+  );
+
+  // 2. Persist the buyer's choice on the cart
+  await selectPaymentMethod({
+    methodType: "BLIK",
+    preferredProviderCode: "payu",
+    preferredInstrumentCode: instrument.instrumentCode,
+  });
+
+  // 3. Complete the cart — instrument propagates to the Order
+  const { order } = await complete();
+
+  // 4. Initiate payment — gateway redirects directly to the BLIK code screen
+  const session = await createPayment(order.id);
+  window.location.href = session.redirectUrl;
+  ```
+
+  **Error handling**:
+  - `userErrors[].code === 'CART_INVALID_INSTRUMENT_CODE'` — instrument code is not available with the chosen provider (gateway disabled it, merchant config changed, typo). Refresh `availablePaymentMethods` and re-prompt the buyer.
+  - `paymentCreate` failed gateway initiation with the preselected instrument? The order's `paymentInstrumentCode` is automatically cleared (best-effort) — the next `paymentCreate` call falls back to the gateway default landing page. Storefront just retries.
+
+  **Rate limits**:
+  - `availablePaymentMethods` Query: 60 requests/min per IP+shop. Live capability lookups (OAuth + gateway list call) are expensive — hitting the limit returns `extensions.code: 'THROTTLED'` with `retryAfter`. Don't poll; cache the result for the duration of the checkout step.
+
+  **Gateway API version pinning**:
+  - PayU API pinned to `v2_1`, Przelewy24 API pinned to `v1`. When the upstream gateway ships a major version migration, the SDK / operations packages will bump major together with the constant update.
+
+  **Migration checklist for existing storefronts**:
+  - [ ] Rename `preferredProviderId` → `preferredProviderCode` everywhere in storefront mutations.
+  - [ ] Replace string comparisons (`provider === 'payu'`) with `ProviderCode` enum.
+  - [ ] Re-add `amountLimits` to your local PaymentMethod fragment if you used it.
+  - [ ] (Optional) Render the new `instruments` array as tiles to enable instrument-level deep-link checkout — 1-2 extra hours of UI work, measurable conversion impact on single-instrument flows.
+
+### Minor Changes
+
+- fd82b62: `PaymentMethod` type gains availability + amount limit fields.
+
+  The storefront `PaymentMethod` returned by `availablePaymentMethods` (and `Cart.availablePaymentMethods` / `Cart.selectedPaymentMethod`) now carries three additional fields:
+  - **`available: Boolean!`** — `false` when the resolving gateway is temporarily unavailable (incident, maintenance) or reported the method as disabled. Storefront should gray-out the tile instead of hiding it — gives merchants observability into routing failures.
+  - **`unavailableReason: PaymentMethodUnavailableReason`** — diagnostic enum (`GATEWAY_DOWN`, `GATEWAY_DISABLED`, `NO_INSTRUMENTS`, `CREDENTIALS_INVALID`). Null when `available` is true. Use for context-aware copy ("Provider is temporarily down" vs "Method not configured").
+  - **`amountLimits: PaymentMethodAmountLimits`** — gateway-reported min/max transaction amount in the resolving currency (e.g. BLIK 1-20000 PLN). Filter the picker against cart total. Null when the gateway does not report limits.
+
+  ```graphql
+  fragment PaymentMethod on PaymentMethod {
+    # existing fields (id, name, provider, type, icon, ...)
+    providersAvailable
+    preferredProvider
+    available
+    unavailableReason
+    amountLimits {
+      min
+      max
+      currency
+    }
+  }
+  ```
+
+  **Currency** is automatically resolved from the storefront context (cascade: `@inContext(currency:)` directive → `X-Preferred-Currency` header → cookie → `Accept-Language` → shop default). Override per query via the `@inContext(currency: "EUR")` directive — no new schema argument.
+
+  **Migration example** for storefront pickers:
+
+  ```ts
+  const { methods } = await sdk.cart.availablePaymentMethods();
+  return methods.map((method) => (
+    <PaymentTile
+      key={method.type}
+      type={method.type}
+      disabled={!method.available}
+      tooltip={method.unavailableReason && reasonCopy[method.unavailableReason]}
+      badge={method.amountLimits && cart.total > method.amountLimits.max ? 'Cart too large' : null}
+    />
+  ));
+  ```
+
+  Backend additionally sanitizes provider error messages (strips OAuth tokens, URLs, JSON secret keys, stack traces) before returning them in admin diagnostic responses — internal logs keep the full error for diagnostics.
+
+- c878d14: Payment instrument preselection — storefront UX completion (distinct error code + warnings array + explicit deselect mutation).
+
+  **Why**: storefront dispatching dla instrument failure stał się context-aware. Dziś generic `PAYMENT_FAILED` post-auto-clear nie pozwalał odróżnić "instrument cleared, retry default landing OK" od "real gateway outage, retry kolejnym attempt". Plus brak explicit deselect — accordion "wróć do wyboru metody" UI wymagał hack typu re-select method.
+
+  **Additive (backward-compatible)**:
+  1. `PaymentErrorCode.INSTRUMENT_PRESELECTION_FAILED` — new enum value. Wystawiany po auto-clear `Order.paymentInstrumentCode` post-`InvalidPaymentInstrumentError`. Distinct od `PAYMENT_FAILED` (generic gateway failure fallback dla credentials / network / 5xx / circuit breaker).
+  2. `PaymentCreatePayload.warnings: [PaymentWarning!]!` — new field, default empty array. Emitted post-auto-clear z entry `{ code: INSTRUMENT_CLEARED_FOR_RETRY, message, retryHint: null }`. Storefront dispatches retry hint differently (accordion reset / progress bar / itp.).
+  3. `cartClearPaymentSelection(input: { cartId: ID! })` — new mutation. Atomic NULL across all payment selection fields. Idempotent. The cart must be `ACTIVE` — `CONVERTED` carts reject with `userErrors[0].code = 'ALREADY_COMPLETED'`. Rate limit 30/min.
+
+  **Storefront usage** — handle instrument failure z context-aware retry:
+
+  ```ts
+  import {
+    useCartManager,
+    type CartMutationOutcome,
+  } from "@doswiftly/storefront-sdk";
+
+  const { selectPaymentMethod, clearPaymentSelection, createPayment } =
+    useCartManager();
+
+  // 1. Klient wybiera BLIK preselect
+  await selectPaymentMethod({
+    methodType: "BLIK",
+    preferredProviderCode: "payu",
+    preferredInstrumentCode: "blik",
+  });
+
+  // 2. Try paymentCreate — może rzucić instrument-specific error
+  try {
+    const session = await createPayment(orderId);
+    window.location.href = session.redirectUrl;
+  } catch (err) {
+    if (err.userErrors?.[0]?.code === "INSTRUMENT_PRESELECTION_FAILED") {
+      // Backend auto-cleared instrument — show retry button
+      // Warning message available via err.warnings[0].message
+      showRetryUI({
+        title: "Instrument płatności niedostępny",
+        message: err.warnings?.[0]?.message ?? err.message,
+        onRetry: () => createPayment(orderId), // next attempt = default landing
+      });
+    } else if (err.userErrors?.[0]?.code === "PAYMENT_FAILED") {
+      // Generic gateway outage — retry z tym samym instrumentem
+      showOutageUI({
+        message: err.message,
+        onRetry: () => createPayment(orderId),
+      });
+    }
+  }
+
+  // 3. Accordion "wróć do wyboru metody" — explicit deselect
+  await clearPaymentSelection({ cartId });
+  // Cart.selectedPaymentMethod === null, Cart.selectedPaymentInstrumentCode === null
+  ```
+
+  **Migration guide for existing storefronts**:
+  - [ ] Add `warnings[]` to your `paymentCreate` selection set (if you use a custom GraphQL document instead of the SDK helpers).
+  - [ ] Branch UI dispatch on `userErrors[0].code === 'INSTRUMENT_PRESELECTION_FAILED'` distinct from `PAYMENT_FAILED`.
+  - [ ] (Optional) Replace any accordion-reset hack with `cartClearPaymentSelection({ cartId })` — clearer API, idempotent, single round-trip.
+
+  **Standards note**: splitting `userErrors[]` (blocking) and `warnings[]` (non-blocking) is a common e-commerce convention. The `INSTRUMENT_PRESELECTION_FAILED` semantics match retry-hint patterns used by major payment gateway SDKs (Stripe `payment_method_unavailable`, etc.).
+
+- c553c80: Payment instrument preselection — cart re-validation stale signal + headless instrument components + browser data helper.
+
+  **Why**: previously the storefront kept showing an obsolete instrument selection until the buyer clicked "pay" — only then did the gateway reject it. The signal is now **proactive**: every cart query re-validates the selection against live gateway capabilities and emits a warning when the method or instrument disappeared. Plus a set of pre-built headless React components so the instrument picker no longer requires manual `displayHint` dispatch.
+
+  **Additive (backward-compatible)**:
+  1. `Cart.warnings: [CartWarning!]!` — new field, default empty array. Computed at query time. Currently emitted: `PAYMENT_SELECTION_STALE` (code) when `selectedPaymentMethod` or `selectedPaymentInstrumentCode` no longer matches live gateway capabilities. Read-only signal — backend persistence is preserved (clear via `cartClearPaymentSelection` or a fresh `cartSelectPaymentMethod`).
+  2. `Cart.selectedPaymentMethod` re-validation — when the method disappeared from live caps the field returns `null` plus a warning with `target: 'selectedPaymentMethod'`.
+  3. `Cart.selectedPaymentInstrumentCode` re-validation — when only the instrument disappeared (method preserved), the field returns `null` plus a warning with `target: 'selectedPaymentInstrumentCode'` (method-level signal stays intact). Backend persistence is preserved — a re-select gets a fresh state.
+  4. `CartWarningCode.PAYMENT_SELECTION_STALE` — new enum value in the existing `CartWarning` envelope.
+  5. Graceful degradation — when the live capability check fails (gateway timeout / network outage), `Cart` returns the existing selection without a warning (UX continuity over freshness; `cartComplete` time-of-payment validation is the final safety net).
+  6. `<PaymentInstrumentTile>` — new pre-built headless component. Single instrument button with full ARIA contract (`role="radio"`, `aria-checked`, `aria-label`, `data-instrument-code`, `data-display-hint`, `data-selected`). Zero opinionated styling — class props per part (button, icon, label). `displayHint` is emitted as a `data-display-hint` attribute so you can style via CSS attribute selectors.
+  7. `<PaymentInstrumentSection>` — new pre-built headless component. Radio-group container with keyboard navigation (ArrowUp/Down/Left/Right wrap, Home/End jump). Renders one `<PaymentInstrumentTile>` per instrument in the order received from `availablePaymentMethods` (no client-side resort — the backend ordering is the source of truth).
+  8. `getBrowserDataForPayment()` — new helper. Collects PSD2/3DS2 browser context (`userAgent`, `language`, screen dimensions, color depth, timezone offset, IANA timezone, `javaEnabled` fallback). Browser-only — throws `BrowserDataNotAvailableError` in SSR. Forward-looking utility for future 3DS challenge flows.
+
+  **Storefront usage** — listen to the stale signal in your cart query:
+
+  ```ts
+  const { cart } = useCart(cartId);
+
+  const staleWarning = cart?.warnings?.find(
+    (w) => w.code === "PAYMENT_SELECTION_STALE",
+  );
+
+  if (staleWarning) {
+    // The backend signals that the buyer picked a method which is no longer
+    // available at the gateway — show a "pick another method" dialog.
+    // `target` distinguishes method vs instrument level:
+    if (staleWarning.target === "selectedPaymentMethod") {
+      // cart.selectedPaymentMethod === null — full re-select required
+    } else if (staleWarning.target === "selectedPaymentInstrumentCode") {
+      // cart.selectedPaymentMethod is still set, only the instrument cleared
+    }
+    // Backend persistence is preserved — `cartClearPaymentSelection` or
+    // a fresh `cartSelectPaymentMethod` is the consumer's responsibility.
+  }
+  ```
+
+  **Storefront usage** — instrument picker with pre-built components:
+
+  ```tsx
+  import { PaymentInstrumentSection } from "@doswiftly/storefront-sdk/react";
+  import { useState } from "react";
+
+  function CheckoutPaymentStep({ method }: { method: PaymentMethod }) {
+    const [instrumentCode, setInstrumentCode] = useState<string | undefined>(
+      undefined,
+    );
+
+    return (
+      <PaymentInstrumentSection
+        method={method}
+        selectedInstrumentCode={instrumentCode}
+        onSelectInstrument={(code) => {
+          setInstrumentCode(code);
+          cart.selectPaymentMethod({
+            methodType: method.type,
+            preferredProviderCode: method.preferredProvider,
+            preferredInstrumentCode: code,
+          });
+        }}
+        sectionClassName="grid grid-cols-2 gap-2"
+        tileClassName="rounded border p-3 hover:bg-gray-50 data-[selected=true]:border-blue-500"
+        labelClassName="font-semibold"
+        ariaLabel="Pick a payment instrument"
+      />
+    );
+  }
+  ```
+
+  **Storefront usage** — browser data for future 3DS flows:
+
+  ```ts
+  import { getBrowserDataForPayment, BrowserDataNotAvailableError } from '@doswiftly/storefront-sdk/react';
+
+  function handleCheckoutSubmit() {
+    try {
+      const browserData = getBrowserDataForPayment();
+      // Pass to paymentCreate input when the gateway requires a 3DS challenge
+      await cart.createPayment({ ..., browserData });
+    } catch (err) {
+      if (err instanceof BrowserDataNotAvailableError) {
+        // SSR / no DOM — skip browser data; the gateway uses its default flow
+      }
+      throw err;
+    }
+  }
+  ```
+
+  **Migration checklist for existing storefronts**:
+  - [ ] Add `warnings { message code target }` to your cart query selection set (if you use a custom GraphQL document instead of the SDK fragments — SDK fragments are updated automatically).
+  - [ ] Branch UI on `cart.warnings[].code === 'PAYMENT_SELECTION_STALE'` to show a re-prompt dialog before checkout submit.
+  - [ ] (Optional) Replace a custom instrument picker with `<PaymentInstrumentSection>` — saves boilerplate, ships full ARIA + keyboard nav out of the box.
+  - [ ] (Forward-looking) Adopt `getBrowserDataForPayment()` in checkout submit handlers when 3DS flows become relevant (currently optional — the gateway accepts an undefined `browserData`).
+
+  **Standards reference**: `PaymentInstrumentSection` follows the WAI-ARIA radiogroup pattern (https://www.w3.org/WAI/ARIA/apg/patterns/radio/). The browser data helper shape matches the EMVCo 3DS2 BrowserData specification.
+
 ## 16.1.0
 
 ### Minor Changes