@vtex/faststore 0.0.4 → 0.0.6

package/dist/sdk/cart/operations.d.ts

@@ -3,18 +3,18 @@ import "./operations.js";
 import { TypedDocumentNode } from "@apollo/client";
 //#region src/sdk/cart/operations.d.ts
 /**
- * Cart-related GraphQL operations and shared fragments (T6 / specs/mutation-contract.md).
+ * Cart-related GraphQL operations and shared fragments (T6 / mutation-contract.md (archived at the specs-archive tag)).
  *
  * The `CartFragment` is the canonical Cart selection set: every mutation operation spreads it so
  * the cache normalisation reaches every reactive subscriber (CartTotal, CartCount, CartItems, …)
  * through a single response. The contract regression test (`contract.test.ts`) parses these
- * documents and asserts the spread is present — see specs/mutation-contract.md AD-D3 / AD-8.
+ * documents and asserts the spread is present — see mutation-contract.md (archived at the specs-archive tag).
  *
- * T7 ([specs/graphql-codegen-pipeline.md][T7]) routes the domain types and the operation factory
+ * T7 ([Typed documents and the shared cache][T7]) routes the domain types and the operation factory
  * through @graphql-codegen. Public type names (`CartEntity`, `CartItemEntity`, `Money`, payload
  * + input aliases) are preserved as re-exports / aliases so consumer call sites do not change.
  *
- * [T7]: ../../../../../specs/graphql-codegen-pipeline.md
+ * [T7]: ../../../../../docs/storefront-core/reference-free-particle-model.md#typed-documents-and-the-shared-cache
  */
 export type Money = MoneyFragmentFragment;
 export type CartItemEntity = CartItemFragmentFragment;

package/dist/sdk/cart/operations.js

@@ -189,7 +189,7 @@ const CART_COUPON_REMOVE = graphql(`
 `);
 /**
 * Re-check the active cart against the platform and adopt corrected availability. Read-only upstream
-* (specs/mini-cart-validate-operation.md): the payload is the cart with each line's
+* (docs/storefront-api-core/CONTEXT.md § Language, Cart Validation): the payload is the cart with each line's
 * `variant.availability` refreshed, shaped like every other cart mutation so the correction lands in
 * the normalized cache. Takes no arguments — the cart resolves from the request context. Spreading
 * `CartFragment` is what makes the guard, the per-line alert, and the badge re-render as subscribers,

package/dist/sdk/cart/operations.js.map

@@ -1 +1 @@
-{"version":3,"file":"operations.js","names":[],"sources":["../../../src/sdk/cart/operations.ts"],"sourcesContent":["import type { TypedDocumentNode } from '@apollo/client';\nimport { graphql } from '../generated/gql.js';\nimport type {\n  CartCouponApplyMutation,\n  CartCouponApplyMutationVariables,\n  CartCouponRemoveMutation,\n  CartCouponRemoveMutationVariables,\n  CartFragmentFragment,\n  CartItemAddMutation,\n  CartItemAddMutationVariables,\n  CartItemFragmentFragment,\n  CartItemQuantityDecreaseMutation,\n  CartItemQuantityDecreaseMutationVariables,\n  CartItemQuantityIncreaseMutation,\n  CartItemQuantityIncreaseMutationVariables,\n  CartItemRemoveMutation,\n  CartItemRemoveMutationVariables,\n  CartItemsRemoveMutation,\n  CartItemsRemoveMutationVariables,\n  CartValidateMutation,\n  CartValidateMutationVariables,\n  MoneyFragmentFragment,\n} from '../generated/graphql.js';\n\n/**\n * Cart-related GraphQL operations and shared fragments (T6 / specs/mutation-contract.md).\n *\n * The `CartFragment` is the canonical Cart selection set: every mutation operation spreads it so\n * the cache normalisation reaches every reactive subscriber (CartTotal, CartCount, CartItems, …)\n * through a single response. The contract regression test (`contract.test.ts`) parses these\n * documents and asserts the spread is present — see specs/mutation-contract.md AD-D3 / AD-8.\n *\n * T7 ([specs/graphql-codegen-pipeline.md][T7]) routes the domain types and the operation factory\n * through @graphql-codegen. Public type names (`CartEntity`, `CartItemEntity`, `Money`, payload\n * + input aliases) are preserved as re-exports / aliases so consumer call sites do not change.\n *\n * [T7]: ../../../../../specs/graphql-codegen-pipeline.md\n */\n\n// ---------------------------------------------------------------------------\n// Domain type aliases — re-exports from codegen artifacts (T7)\n// ---------------------------------------------------------------------------\n\nexport type Money = MoneyFragmentFragment;\nexport type CartItemEntity = CartItemFragmentFragment;\nexport type CartEntity = CartFragmentFragment;\nexport type CartTotalizer = CartFragmentFragment['totalizers'][number];\nexport type CartMessage = CartFragmentFragment['messages'][number];\nexport type AppliedCoupon = CartFragmentFragment['appliedCoupons'][number];\n\nexport type CartUserError = Readonly<{ code: string; message: string }>;\n\n// ---------------------------------------------------------------------------\n// Mutation input types — direct re-exports from codegen\n// ---------------------------------------------------------------------------\n\nexport type {\n  CartCouponApplyInput,\n  CartCouponRemoveInput,\n  CartItemAddInput,\n  CartItemQuantityDecreaseInput,\n  CartItemQuantityIncreaseInput,\n  CartItemRemoveInput,\n  CartItemsRemoveInput,\n} from '../generated/graphql.js';\n\n// ---------------------------------------------------------------------------\n// Mutation payload types — derived from operation result types\n// ---------------------------------------------------------------------------\n\nexport type CartItemAddPayload = CartItemAddMutation['cartItemAdd'];\nexport type CartItemRemovePayload = CartItemRemoveMutation['cartItemRemove'];\nexport type CartItemsRemovePayload = CartItemsRemoveMutation['cartItemsRemove'];\nexport type CartItemQuantityIncreasePayload = CartItemQuantityIncreaseMutation['cartItemQuantityIncrease'];\nexport type CartItemQuantityDecreasePayload = CartItemQuantityDecreaseMutation['cartItemQuantityDecrease'];\nexport type CartCouponApplyPayload = CartCouponApplyMutation['cartCouponApply'];\nexport type CartCouponRemovePayload = CartCouponRemoveMutation['cartCouponRemove'];\nexport type CartValidatePayload = CartValidateMutation['cartValidate'];\n\n// ---------------------------------------------------------------------------\n// Shared fragments — authored via the codegen `graphql()` factory so codegen can scan and type\n// every operation that spreads them.\n// ---------------------------------------------------------------------------\n\nexport const MoneyFragment: TypedDocumentNode<MoneyFragmentFragment, never> = graphql(`\n  fragment MoneyFragment on Money {\n    __typename\n    amount\n    currencyCode\n  }\n`);\n\nexport const CartItemFragment: TypedDocumentNode<CartItemFragmentFragment, never> = graphql(`\n  fragment CartItemFragment on CartItem {\n    __typename\n    id\n    quantity\n    price {\n      ...MoneyFragment\n    }\n    listPrice {\n      ...MoneyFragment\n    }\n    sellingPrice {\n      ...MoneyFragment\n    }\n    gift\n    ownTotal {\n      ...MoneyFragment\n    }\n    total {\n      ...MoneyFragment\n    }\n    variant {\n      __typename\n      variantId\n      sku\n      name\n      image {\n        url\n        altText\n      }\n      availability\n    }\n    product {\n      __typename\n      productId\n      title\n      detailUrl\n      categories {\n        categoryId\n        name\n      }\n      brand {\n        brandId\n        name\n      }\n    }\n  }\n`);\n\n/**\n * Canonical Cart selection set. Every cart mutation MUST spread this fragment so the cache\n * receives the entity slices that all subscribers depend on (id + items + totalizers + total +\n * messages). The regression test in contract.test.ts enforces this.\n */\nexport const CartFragment: TypedDocumentNode<CartFragmentFragment, never> = graphql(`\n  fragment CartFragment on Cart {\n    __typename\n    id\n    items {\n      ...CartItemFragment\n    }\n    totalizers {\n      __typename\n      id\n      name\n      value {\n        ...MoneyFragment\n      }\n    }\n    total {\n      ...MoneyFragment\n    }\n    messages {\n      __typename\n      code\n      text\n      status\n    }\n    appliedCoupons {\n      code\n      isUnmatchedCondition\n    }\n  }\n`);\n\n// ---------------------------------------------------------------------------\n// Mutation operations — authored via `graphql()`, typed via the codegen-derived\n// TypedDocumentNode generic so Apollo's `useMutation` infers TData / TVariables correctly.\n// ---------------------------------------------------------------------------\n\nexport const CART_ITEM_ADD: TypedDocumentNode<CartItemAddMutation, CartItemAddMutationVariables> = graphql(`\n  mutation CartItemAdd($input: CartItemAddInput!) {\n    cartItemAdd(input: $input) {\n      __typename\n      cart {\n        ...CartFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n`);\n\nexport const CART_ITEM_REMOVE: TypedDocumentNode<CartItemRemoveMutation, CartItemRemoveMutationVariables> = graphql(`\n  mutation CartItemRemove($input: CartItemRemoveInput!) {\n    cartItemRemove(input: $input) {\n      __typename\n      cart {\n        ...CartFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n`);\n\nexport const CART_ITEMS_REMOVE: TypedDocumentNode<CartItemsRemoveMutation, CartItemsRemoveMutationVariables> = graphql(`\n  mutation CartItemsRemove($input: CartItemsRemoveInput!) {\n    cartItemsRemove(input: $input) {\n      __typename\n      cart {\n        ...CartFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n`);\n\nexport const CART_ITEM_QUANTITY_INCREASE: TypedDocumentNode<\n  CartItemQuantityIncreaseMutation,\n  CartItemQuantityIncreaseMutationVariables\n> = graphql(`\n  mutation CartItemQuantityIncrease($input: CartItemQuantityIncreaseInput!) {\n    cartItemQuantityIncrease(input: $input) {\n      __typename\n      cart {\n        ...CartFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n`);\n\nexport const CART_ITEM_QUANTITY_DECREASE: TypedDocumentNode<\n  CartItemQuantityDecreaseMutation,\n  CartItemQuantityDecreaseMutationVariables\n> = graphql(`\n  mutation CartItemQuantityDecrease($input: CartItemQuantityDecreaseInput!) {\n    cartItemQuantityDecrease(input: $input) {\n      __typename\n      cart {\n        ...CartFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n`);\n\nexport const CART_COUPON_APPLY: TypedDocumentNode<CartCouponApplyMutation, CartCouponApplyMutationVariables> = graphql(`\n  mutation CartCouponApply($input: CartCouponApplyInput!) {\n    cartCouponApply(input: $input) {\n      __typename\n      cart {\n        ...CartFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n`);\n\nexport const CART_COUPON_REMOVE: TypedDocumentNode<CartCouponRemoveMutation, CartCouponRemoveMutationVariables> =\n  graphql(`\n  mutation CartCouponRemove($input: CartCouponRemoveInput!) {\n    cartCouponRemove(input: $input) {\n      __typename\n      cart {\n        ...CartFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n`);\n\n/**\n * Re-check the active cart against the platform and adopt corrected availability. Read-only upstream\n * (specs/mini-cart-validate-operation.md): the payload is the cart with each line's\n * `variant.availability` refreshed, shaped like every other cart mutation so the correction lands in\n * the normalized cache. Takes no arguments — the cart resolves from the request context. Spreading\n * `CartFragment` is what makes the guard, the per-line alert, and the badge re-render as subscribers,\n * so T13 needs no fragment or codegen change beyond registering this document.\n */\nexport const CART_VALIDATE: TypedDocumentNode<CartValidateMutation, CartValidateMutationVariables> = graphql(`\n  mutation CartValidate {\n    cartValidate {\n      __typename\n      cart {\n        ...CartFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n`);\n\n/**\n * Canonical list of cart mutation documents. Used by the contract regression test to iterate\n * over every shipped operation without hard-coding names.\n */\nexport const CART_MUTATIONS = [\n  { name: 'CartItemAdd', document: CART_ITEM_ADD },\n  { name: 'CartItemRemove', document: CART_ITEM_REMOVE },\n  { name: 'CartItemsRemove', document: CART_ITEMS_REMOVE },\n  { name: 'CartItemQuantityIncrease', document: CART_ITEM_QUANTITY_INCREASE },\n  { name: 'CartItemQuantityDecrease', document: CART_ITEM_QUANTITY_DECREASE },\n  { name: 'CartCouponApply', document: CART_COUPON_APPLY },\n  { name: 'CartCouponRemove', document: CART_COUPON_REMOVE },\n  { name: 'CartValidate', document: CART_VALIDATE },\n] as const;\n"],"mappings":";AAoF8E,QAAQ;;;;;;CAMrF;AAEmF,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+C3F;;;;;;AAOD,MAAa,eAA+D,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BnF;AAOD,MAAa,gBAAsF,QAAQ;;;;;;;;;;;;;CAa1G;AAED,MAAa,mBAA+F,QAAQ;;;;;;;;;;;;;CAanH;AAED,MAAa,oBAAkG,QAAQ;;;;;;;;;;;;;CAatH;AAED,MAAa,8BAGT,QAAQ;;;;;;;;;;;;;CAaX;AAED,MAAa,8BAGT,QAAQ;;;;;;;;;;;;;CAaX;AAED,MAAa,oBAAkG,QAAQ;;;;;;;;;;;;;CAatH;AAED,MAAa,qBACX,QAAQ;;;;;;;;;;;;;CAaT;;;;;;;;;AAUD,MAAa,gBAAwF,QAAQ;;;;;;;;;;;;;CAa5G"}
+{"version":3,"file":"operations.js","names":[],"sources":["../../../src/sdk/cart/operations.ts"],"sourcesContent":["import type { TypedDocumentNode } from '@apollo/client';\nimport { graphql } from '../generated/gql.js';\nimport type {\n  CartCouponApplyMutation,\n  CartCouponApplyMutationVariables,\n  CartCouponRemoveMutation,\n  CartCouponRemoveMutationVariables,\n  CartFragmentFragment,\n  CartItemAddMutation,\n  CartItemAddMutationVariables,\n  CartItemFragmentFragment,\n  CartItemQuantityDecreaseMutation,\n  CartItemQuantityDecreaseMutationVariables,\n  CartItemQuantityIncreaseMutation,\n  CartItemQuantityIncreaseMutationVariables,\n  CartItemRemoveMutation,\n  CartItemRemoveMutationVariables,\n  CartItemsRemoveMutation,\n  CartItemsRemoveMutationVariables,\n  CartValidateMutation,\n  CartValidateMutationVariables,\n  MoneyFragmentFragment,\n} from '../generated/graphql.js';\n\n/**\n * Cart-related GraphQL operations and shared fragments (T6 / mutation-contract.md (archived at the specs-archive tag)).\n *\n * The `CartFragment` is the canonical Cart selection set: every mutation operation spreads it so\n * the cache normalisation reaches every reactive subscriber (CartTotal, CartCount, CartItems, …)\n * through a single response. The contract regression test (`contract.test.ts`) parses these\n * documents and asserts the spread is present — see mutation-contract.md (archived at the specs-archive tag).\n *\n * T7 ([Typed documents and the shared cache][T7]) routes the domain types and the operation factory\n * through @graphql-codegen. Public type names (`CartEntity`, `CartItemEntity`, `Money`, payload\n * + input aliases) are preserved as re-exports / aliases so consumer call sites do not change.\n *\n * [T7]: ../../../../../docs/storefront-core/reference-free-particle-model.md#typed-documents-and-the-shared-cache\n */\n\n// ---------------------------------------------------------------------------\n// Domain type aliases — re-exports from codegen artifacts (T7)\n// ---------------------------------------------------------------------------\n\nexport type Money = MoneyFragmentFragment;\nexport type CartItemEntity = CartItemFragmentFragment;\nexport type CartEntity = CartFragmentFragment;\nexport type CartTotalizer = CartFragmentFragment['totalizers'][number];\nexport type CartMessage = CartFragmentFragment['messages'][number];\nexport type AppliedCoupon = CartFragmentFragment['appliedCoupons'][number];\n\nexport type CartUserError = Readonly<{ code: string; message: string }>;\n\n// ---------------------------------------------------------------------------\n// Mutation input types — direct re-exports from codegen\n// ---------------------------------------------------------------------------\n\nexport type {\n  CartCouponApplyInput,\n  CartCouponRemoveInput,\n  CartItemAddInput,\n  CartItemQuantityDecreaseInput,\n  CartItemQuantityIncreaseInput,\n  CartItemRemoveInput,\n  CartItemsRemoveInput,\n} from '../generated/graphql.js';\n\n// ---------------------------------------------------------------------------\n// Mutation payload types — derived from operation result types\n// ---------------------------------------------------------------------------\n\nexport type CartItemAddPayload = CartItemAddMutation['cartItemAdd'];\nexport type CartItemRemovePayload = CartItemRemoveMutation['cartItemRemove'];\nexport type CartItemsRemovePayload = CartItemsRemoveMutation['cartItemsRemove'];\nexport type CartItemQuantityIncreasePayload = CartItemQuantityIncreaseMutation['cartItemQuantityIncrease'];\nexport type CartItemQuantityDecreasePayload = CartItemQuantityDecreaseMutation['cartItemQuantityDecrease'];\nexport type CartCouponApplyPayload = CartCouponApplyMutation['cartCouponApply'];\nexport type CartCouponRemovePayload = CartCouponRemoveMutation['cartCouponRemove'];\nexport type CartValidatePayload = CartValidateMutation['cartValidate'];\n\n// ---------------------------------------------------------------------------\n// Shared fragments — authored via the codegen `graphql()` factory so codegen can scan and type\n// every operation that spreads them.\n// ---------------------------------------------------------------------------\n\nexport const MoneyFragment: TypedDocumentNode<MoneyFragmentFragment, never> = graphql(`\n  fragment MoneyFragment on Money {\n    __typename\n    amount\n    currencyCode\n  }\n`);\n\nexport const CartItemFragment: TypedDocumentNode<CartItemFragmentFragment, never> = graphql(`\n  fragment CartItemFragment on CartItem {\n    __typename\n    id\n    quantity\n    price {\n      ...MoneyFragment\n    }\n    listPrice {\n      ...MoneyFragment\n    }\n    sellingPrice {\n      ...MoneyFragment\n    }\n    gift\n    ownTotal {\n      ...MoneyFragment\n    }\n    total {\n      ...MoneyFragment\n    }\n    variant {\n      __typename\n      variantId\n      sku\n      name\n      image {\n        url\n        altText\n      }\n      availability\n    }\n    product {\n      __typename\n      productId\n      title\n      detailUrl\n      categories {\n        categoryId\n        name\n      }\n      brand {\n        brandId\n        name\n      }\n    }\n  }\n`);\n\n/**\n * Canonical Cart selection set. Every cart mutation MUST spread this fragment so the cache\n * receives the entity slices that all subscribers depend on (id + items + totalizers + total +\n * messages). The regression test in contract.test.ts enforces this.\n */\nexport const CartFragment: TypedDocumentNode<CartFragmentFragment, never> = graphql(`\n  fragment CartFragment on Cart {\n    __typename\n    id\n    items {\n      ...CartItemFragment\n    }\n    totalizers {\n      __typename\n      id\n      name\n      value {\n        ...MoneyFragment\n      }\n    }\n    total {\n      ...MoneyFragment\n    }\n    messages {\n      __typename\n      code\n      text\n      status\n    }\n    appliedCoupons {\n      code\n      isUnmatchedCondition\n    }\n  }\n`);\n\n// ---------------------------------------------------------------------------\n// Mutation operations — authored via `graphql()`, typed via the codegen-derived\n// TypedDocumentNode generic so Apollo's `useMutation` infers TData / TVariables correctly.\n// ---------------------------------------------------------------------------\n\nexport const CART_ITEM_ADD: TypedDocumentNode<CartItemAddMutation, CartItemAddMutationVariables> = graphql(`\n  mutation CartItemAdd($input: CartItemAddInput!) {\n    cartItemAdd(input: $input) {\n      __typename\n      cart {\n        ...CartFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n`);\n\nexport const CART_ITEM_REMOVE: TypedDocumentNode<CartItemRemoveMutation, CartItemRemoveMutationVariables> = graphql(`\n  mutation CartItemRemove($input: CartItemRemoveInput!) {\n    cartItemRemove(input: $input) {\n      __typename\n      cart {\n        ...CartFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n`);\n\nexport const CART_ITEMS_REMOVE: TypedDocumentNode<CartItemsRemoveMutation, CartItemsRemoveMutationVariables> = graphql(`\n  mutation CartItemsRemove($input: CartItemsRemoveInput!) {\n    cartItemsRemove(input: $input) {\n      __typename\n      cart {\n        ...CartFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n`);\n\nexport const CART_ITEM_QUANTITY_INCREASE: TypedDocumentNode<\n  CartItemQuantityIncreaseMutation,\n  CartItemQuantityIncreaseMutationVariables\n> = graphql(`\n  mutation CartItemQuantityIncrease($input: CartItemQuantityIncreaseInput!) {\n    cartItemQuantityIncrease(input: $input) {\n      __typename\n      cart {\n        ...CartFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n`);\n\nexport const CART_ITEM_QUANTITY_DECREASE: TypedDocumentNode<\n  CartItemQuantityDecreaseMutation,\n  CartItemQuantityDecreaseMutationVariables\n> = graphql(`\n  mutation CartItemQuantityDecrease($input: CartItemQuantityDecreaseInput!) {\n    cartItemQuantityDecrease(input: $input) {\n      __typename\n      cart {\n        ...CartFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n`);\n\nexport const CART_COUPON_APPLY: TypedDocumentNode<CartCouponApplyMutation, CartCouponApplyMutationVariables> = graphql(`\n  mutation CartCouponApply($input: CartCouponApplyInput!) {\n    cartCouponApply(input: $input) {\n      __typename\n      cart {\n        ...CartFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n`);\n\nexport const CART_COUPON_REMOVE: TypedDocumentNode<CartCouponRemoveMutation, CartCouponRemoveMutationVariables> =\n  graphql(`\n  mutation CartCouponRemove($input: CartCouponRemoveInput!) {\n    cartCouponRemove(input: $input) {\n      __typename\n      cart {\n        ...CartFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n`);\n\n/**\n * Re-check the active cart against the platform and adopt corrected availability. Read-only upstream\n * (docs/storefront-api-core/CONTEXT.md § Language, Cart Validation): the payload is the cart with each line's\n * `variant.availability` refreshed, shaped like every other cart mutation so the correction lands in\n * the normalized cache. Takes no arguments — the cart resolves from the request context. Spreading\n * `CartFragment` is what makes the guard, the per-line alert, and the badge re-render as subscribers,\n * so T13 needs no fragment or codegen change beyond registering this document.\n */\nexport const CART_VALIDATE: TypedDocumentNode<CartValidateMutation, CartValidateMutationVariables> = graphql(`\n  mutation CartValidate {\n    cartValidate {\n      __typename\n      cart {\n        ...CartFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n`);\n\n/**\n * Canonical list of cart mutation documents. Used by the contract regression test to iterate\n * over every shipped operation without hard-coding names.\n */\nexport const CART_MUTATIONS = [\n  { name: 'CartItemAdd', document: CART_ITEM_ADD },\n  { name: 'CartItemRemove', document: CART_ITEM_REMOVE },\n  { name: 'CartItemsRemove', document: CART_ITEMS_REMOVE },\n  { name: 'CartItemQuantityIncrease', document: CART_ITEM_QUANTITY_INCREASE },\n  { name: 'CartItemQuantityDecrease', document: CART_ITEM_QUANTITY_DECREASE },\n  { name: 'CartCouponApply', document: CART_COUPON_APPLY },\n  { name: 'CartCouponRemove', document: CART_COUPON_REMOVE },\n  { name: 'CartValidate', document: CART_VALIDATE },\n] as const;\n"],"mappings":";AAoF8E,QAAQ;;;;;;CAMrF;AAEmF,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+C3F;;;;;;AAOD,MAAa,eAA+D,QAAQ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6BnF;AAOD,MAAa,gBAAsF,QAAQ;;;;;;;;;;;;;CAa1G;AAED,MAAa,mBAA+F,QAAQ;;;;;;;;;;;;;CAanH;AAED,MAAa,oBAAkG,QAAQ;;;;;;;;;;;;;CAatH;AAED,MAAa,8BAGT,QAAQ;;;;;;;;;;;;;CAaX;AAED,MAAa,8BAGT,QAAQ;;;;;;;;;;;;;CAaX;AAED,MAAa,oBAAkG,QAAQ;;;;;;;;;;;;;CAatH;AAED,MAAa,qBACX,QAAQ;;;;;;;;;;;;;CAaT;;;;;;;;;AAUD,MAAa,gBAAwF,QAAQ;;;;;;;;;;;;;CAa5G"}

package/dist/sdk/cart/optimistic.js

@@ -1,7 +1,7 @@
 //#region src/sdk/cart/optimistic.ts
 /**
 * Pure optimistic-response builders for the three cache-propagating cart mutations
-* (specs/mutation-contract.md AD-3 / AD-D6).
+* (mutation-contract.md (archived at the specs-archive tag)).
 *
 * Each builder takes the current `CartEntity` and the affected `CartItemEntity` and returns the
 * predicted post-mutation `Cart` carrying every field the canonical `CartFragment` selects:

package/dist/sdk/cart/optimistic.js.map

@@ -1 +1 @@
-{"version":3,"file":"optimistic.js","names":[],"sources":["../../../src/sdk/cart/optimistic.ts"],"sourcesContent":["import type {\n  CartEntity,\n  CartItemEntity,\n  CartItemQuantityDecreasePayload,\n  CartItemQuantityIncreasePayload,\n  CartItemRemovePayload,\n  CartItemsRemovePayload,\n  CartTotalizer,\n  Money,\n} from './operations.js';\n\n/**\n * Pure optimistic-response builders for the three cache-propagating cart mutations\n * (specs/mutation-contract.md AD-3 / AD-D6).\n *\n * Each builder takes the current `CartEntity` and the affected `CartItemEntity` and returns the\n * predicted post-mutation `Cart` carrying every field the canonical `CartFragment` selects:\n * `id`, `items`, `totalizers`, `total`. The shape MUST match Apollo's normalised cache slot for\n * the entity, so `__typename` and the same `id` are preserved.\n *\n * Lines are matched by their opaque `id` (Base64(\"CartItem:<orderFormId>:<uniqueId>\")).\n *\n * Recomputation rules (kept simple — server reconciles drift on response):\n *   - `Items` totalizer (matched by `id === 'Items'`) is adjusted by `item.sellingPrice * delta`.\n *   - `total` (the cart's grand total) is adjusted by the same delta.\n *   - All other totalizers (Shipping, Discounts, …) stay as-is until the server response lands.\n */\n\nfunction moneyAdd(money: Money, delta: number): Money {\n  // `Money.amount` is typed as `number` by codegen but arrives over the wire as a decimal *string*\n  // (the server's `Decimal` scalar = `(cents / 100).toFixed(2)`). Without coercing, `string + number`\n  // concatenates (e.g. \"49.99\" + 49.99 → \"49.9949.99\"), which formats to NaN during the optimistic\n  // window until the server response replaces it. Number() restores numeric addition.\n  return { __typename: 'Money', amount: Number(money.amount) + delta, currencyCode: money.currencyCode };\n}\n\nfunction adjustItemsTotalizer(totalizers: readonly CartTotalizer[], delta: number): CartTotalizer[] {\n  return totalizers.map((t) => (t.id === 'Items' ? { ...t, value: moneyAdd(t.value, delta) } : t));\n}\n\nfunction emptyUserErrors<T>(): T[] {\n  return [];\n}\n\n/**\n * Predicts the cart after `cartItemQuantityIncrease(input: { variantId, quantityToAdd })`.\n */\nexport function buildOptimisticIncrease(\n  cart: CartEntity,\n  item: CartItemEntity,\n  by = 1,\n): { cartItemQuantityIncrease: CartItemQuantityIncreasePayload } {\n  if (by <= 0) {\n    return {\n      cartItemQuantityIncrease: {\n        __typename: 'CartItemQuantityIncreasePayload',\n        cart,\n        userErrors: emptyUserErrors(),\n      },\n    };\n  }\n\n  const currentItem = cart.items.find((i) => i.id === item.id);\n  if (!currentItem) {\n    return {\n      cartItemQuantityIncrease: {\n        __typename: 'CartItemQuantityIncreasePayload',\n        cart,\n        userErrors: emptyUserErrors(),\n      },\n    };\n  }\n\n  const newQuantity = currentItem.quantity + by;\n  const delta = currentItem.sellingPrice.amount * by;\n\n  const updatedItems = cart.items.map((i) => (i.id === item.id ? { ...i, quantity: newQuantity } : i));\n\n  return {\n    cartItemQuantityIncrease: {\n      __typename: 'CartItemQuantityIncreasePayload',\n      cart: {\n        __typename: 'Cart',\n        id: cart.id,\n        items: updatedItems,\n        totalizers: adjustItemsTotalizer(cart.totalizers, delta),\n        total: moneyAdd(cart.total, delta),\n        messages: cart.messages,\n        appliedCoupons: cart.appliedCoupons,\n      },\n      userErrors: emptyUserErrors(),\n    },\n  };\n}\n\n/**\n * Predicts the cart after `cartItemQuantityDecrease(input: { variantId, quantityToRemove })`.\n *\n * If the resulting quantity would be `<= 0`, the line is removed entirely.\n */\nexport function buildOptimisticDecrease(\n  cart: CartEntity,\n  item: CartItemEntity,\n  by = 1,\n): { cartItemQuantityDecrease: CartItemQuantityDecreasePayload } {\n  if (by <= 0) {\n    return {\n      cartItemQuantityDecrease: {\n        __typename: 'CartItemQuantityDecreasePayload',\n        cart,\n        userErrors: emptyUserErrors(),\n      },\n    };\n  }\n\n  const currentItem = cart.items.find((i) => i.id === item.id);\n  if (!currentItem) {\n    return {\n      cartItemQuantityDecrease: {\n        __typename: 'CartItemQuantityDecreasePayload',\n        cart,\n        userErrors: emptyUserErrors(),\n      },\n    };\n  }\n\n  const requestedQuantity = currentItem.quantity - by;\n  const removed = requestedQuantity <= 0;\n  const actualDelta = removed ? currentItem.quantity : by;\n  const priceDelta = -currentItem.sellingPrice.amount * actualDelta;\n\n  const updatedItems = removed\n    ? cart.items.filter((i) => i.id !== item.id)\n    : cart.items.map((i) => (i.id === item.id ? { ...i, quantity: requestedQuantity } : i));\n\n  return {\n    cartItemQuantityDecrease: {\n      __typename: 'CartItemQuantityDecreasePayload',\n      cart: {\n        __typename: 'Cart',\n        id: cart.id,\n        items: updatedItems,\n        totalizers: adjustItemsTotalizer(cart.totalizers, priceDelta),\n        total: moneyAdd(cart.total, priceDelta),\n        messages: cart.messages,\n        appliedCoupons: cart.appliedCoupons,\n      },\n      userErrors: emptyUserErrors(),\n    },\n  };\n}\n\n/**\n * Predicts the cart after `cartItemRemove(input: { variantId })`.\n */\nexport function buildOptimisticRemove(\n  cart: CartEntity,\n  item: CartItemEntity,\n): { cartItemRemove: CartItemRemovePayload } {\n  const currentItem = cart.items.find((i) => i.id === item.id);\n  if (!currentItem) {\n    return {\n      cartItemRemove: {\n        __typename: 'CartItemRemovePayload',\n        cart,\n        userErrors: emptyUserErrors(),\n      },\n    };\n  }\n\n  const priceDelta = -currentItem.sellingPrice.amount * currentItem.quantity;\n\n  return {\n    cartItemRemove: {\n      __typename: 'CartItemRemovePayload',\n      cart: {\n        __typename: 'Cart',\n        id: cart.id,\n        items: cart.items.filter((i) => i.id !== item.id),\n        totalizers: adjustItemsTotalizer(cart.totalizers, priceDelta),\n        total: moneyAdd(cart.total, priceDelta),\n        messages: cart.messages,\n        appliedCoupons: cart.appliedCoupons,\n      },\n      userErrors: emptyUserErrors(),\n    },\n  };\n}\n\n/**\n * Predicts the cart after `cartItemsRemove(input: { variantIds })` — the N-line generalisation of\n * `buildOptimisticRemove`. Lines absent from the cart are ignored; the summed price delta of the\n * matched lines adjusts the `Items` totalizer and the grand total.\n */\nexport function buildOptimisticRemoveItems(\n  cart: CartEntity,\n  items: readonly CartItemEntity[],\n): { cartItemsRemove: CartItemsRemovePayload } {\n  const removedIds = new Set(items.map((item) => item.id));\n  const removedLines = cart.items.filter((i) => removedIds.has(i.id));\n  if (removedLines.length === 0) {\n    return {\n      cartItemsRemove: {\n        __typename: 'CartItemsRemovePayload',\n        cart,\n        userErrors: emptyUserErrors(),\n      },\n    };\n  }\n\n  const priceDelta = removedLines.reduce((sum, line) => sum - line.sellingPrice.amount * line.quantity, 0);\n\n  return {\n    cartItemsRemove: {\n      __typename: 'CartItemsRemovePayload',\n      cart: {\n        __typename: 'Cart',\n        id: cart.id,\n        items: cart.items.filter((i) => !removedIds.has(i.id)),\n        totalizers: adjustItemsTotalizer(cart.totalizers, priceDelta),\n        total: moneyAdd(cart.total, priceDelta),\n        messages: cart.messages,\n        appliedCoupons: cart.appliedCoupons,\n      },\n      userErrors: emptyUserErrors(),\n    },\n  };\n}\n"],"mappings":"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"}
+{"version":3,"file":"optimistic.js","names":[],"sources":["../../../src/sdk/cart/optimistic.ts"],"sourcesContent":["import type {\n  CartEntity,\n  CartItemEntity,\n  CartItemQuantityDecreasePayload,\n  CartItemQuantityIncreasePayload,\n  CartItemRemovePayload,\n  CartItemsRemovePayload,\n  CartTotalizer,\n  Money,\n} from './operations.js';\n\n/**\n * Pure optimistic-response builders for the three cache-propagating cart mutations\n * (mutation-contract.md (archived at the specs-archive tag)).\n *\n * Each builder takes the current `CartEntity` and the affected `CartItemEntity` and returns the\n * predicted post-mutation `Cart` carrying every field the canonical `CartFragment` selects:\n * `id`, `items`, `totalizers`, `total`. The shape MUST match Apollo's normalised cache slot for\n * the entity, so `__typename` and the same `id` are preserved.\n *\n * Lines are matched by their opaque `id` (Base64(\"CartItem:<orderFormId>:<uniqueId>\")).\n *\n * Recomputation rules (kept simple — server reconciles drift on response):\n *   - `Items` totalizer (matched by `id === 'Items'`) is adjusted by `item.sellingPrice * delta`.\n *   - `total` (the cart's grand total) is adjusted by the same delta.\n *   - All other totalizers (Shipping, Discounts, …) stay as-is until the server response lands.\n */\n\nfunction moneyAdd(money: Money, delta: number): Money {\n  // `Money.amount` is typed as `number` by codegen but arrives over the wire as a decimal *string*\n  // (the server's `Decimal` scalar = `(cents / 100).toFixed(2)`). Without coercing, `string + number`\n  // concatenates (e.g. \"49.99\" + 49.99 → \"49.9949.99\"), which formats to NaN during the optimistic\n  // window until the server response replaces it. Number() restores numeric addition.\n  return { __typename: 'Money', amount: Number(money.amount) + delta, currencyCode: money.currencyCode };\n}\n\nfunction adjustItemsTotalizer(totalizers: readonly CartTotalizer[], delta: number): CartTotalizer[] {\n  return totalizers.map((t) => (t.id === 'Items' ? { ...t, value: moneyAdd(t.value, delta) } : t));\n}\n\nfunction emptyUserErrors<T>(): T[] {\n  return [];\n}\n\n/**\n * Predicts the cart after `cartItemQuantityIncrease(input: { variantId, quantityToAdd })`.\n */\nexport function buildOptimisticIncrease(\n  cart: CartEntity,\n  item: CartItemEntity,\n  by = 1,\n): { cartItemQuantityIncrease: CartItemQuantityIncreasePayload } {\n  if (by <= 0) {\n    return {\n      cartItemQuantityIncrease: {\n        __typename: 'CartItemQuantityIncreasePayload',\n        cart,\n        userErrors: emptyUserErrors(),\n      },\n    };\n  }\n\n  const currentItem = cart.items.find((i) => i.id === item.id);\n  if (!currentItem) {\n    return {\n      cartItemQuantityIncrease: {\n        __typename: 'CartItemQuantityIncreasePayload',\n        cart,\n        userErrors: emptyUserErrors(),\n      },\n    };\n  }\n\n  const newQuantity = currentItem.quantity + by;\n  const delta = currentItem.sellingPrice.amount * by;\n\n  const updatedItems = cart.items.map((i) => (i.id === item.id ? { ...i, quantity: newQuantity } : i));\n\n  return {\n    cartItemQuantityIncrease: {\n      __typename: 'CartItemQuantityIncreasePayload',\n      cart: {\n        __typename: 'Cart',\n        id: cart.id,\n        items: updatedItems,\n        totalizers: adjustItemsTotalizer(cart.totalizers, delta),\n        total: moneyAdd(cart.total, delta),\n        messages: cart.messages,\n        appliedCoupons: cart.appliedCoupons,\n      },\n      userErrors: emptyUserErrors(),\n    },\n  };\n}\n\n/**\n * Predicts the cart after `cartItemQuantityDecrease(input: { variantId, quantityToRemove })`.\n *\n * If the resulting quantity would be `<= 0`, the line is removed entirely.\n */\nexport function buildOptimisticDecrease(\n  cart: CartEntity,\n  item: CartItemEntity,\n  by = 1,\n): { cartItemQuantityDecrease: CartItemQuantityDecreasePayload } {\n  if (by <= 0) {\n    return {\n      cartItemQuantityDecrease: {\n        __typename: 'CartItemQuantityDecreasePayload',\n        cart,\n        userErrors: emptyUserErrors(),\n      },\n    };\n  }\n\n  const currentItem = cart.items.find((i) => i.id === item.id);\n  if (!currentItem) {\n    return {\n      cartItemQuantityDecrease: {\n        __typename: 'CartItemQuantityDecreasePayload',\n        cart,\n        userErrors: emptyUserErrors(),\n      },\n    };\n  }\n\n  const requestedQuantity = currentItem.quantity - by;\n  const removed = requestedQuantity <= 0;\n  const actualDelta = removed ? currentItem.quantity : by;\n  const priceDelta = -currentItem.sellingPrice.amount * actualDelta;\n\n  const updatedItems = removed\n    ? cart.items.filter((i) => i.id !== item.id)\n    : cart.items.map((i) => (i.id === item.id ? { ...i, quantity: requestedQuantity } : i));\n\n  return {\n    cartItemQuantityDecrease: {\n      __typename: 'CartItemQuantityDecreasePayload',\n      cart: {\n        __typename: 'Cart',\n        id: cart.id,\n        items: updatedItems,\n        totalizers: adjustItemsTotalizer(cart.totalizers, priceDelta),\n        total: moneyAdd(cart.total, priceDelta),\n        messages: cart.messages,\n        appliedCoupons: cart.appliedCoupons,\n      },\n      userErrors: emptyUserErrors(),\n    },\n  };\n}\n\n/**\n * Predicts the cart after `cartItemRemove(input: { variantId })`.\n */\nexport function buildOptimisticRemove(\n  cart: CartEntity,\n  item: CartItemEntity,\n): { cartItemRemove: CartItemRemovePayload } {\n  const currentItem = cart.items.find((i) => i.id === item.id);\n  if (!currentItem) {\n    return {\n      cartItemRemove: {\n        __typename: 'CartItemRemovePayload',\n        cart,\n        userErrors: emptyUserErrors(),\n      },\n    };\n  }\n\n  const priceDelta = -currentItem.sellingPrice.amount * currentItem.quantity;\n\n  return {\n    cartItemRemove: {\n      __typename: 'CartItemRemovePayload',\n      cart: {\n        __typename: 'Cart',\n        id: cart.id,\n        items: cart.items.filter((i) => i.id !== item.id),\n        totalizers: adjustItemsTotalizer(cart.totalizers, priceDelta),\n        total: moneyAdd(cart.total, priceDelta),\n        messages: cart.messages,\n        appliedCoupons: cart.appliedCoupons,\n      },\n      userErrors: emptyUserErrors(),\n    },\n  };\n}\n\n/**\n * Predicts the cart after `cartItemsRemove(input: { variantIds })` — the N-line generalisation of\n * `buildOptimisticRemove`. Lines absent from the cart are ignored; the summed price delta of the\n * matched lines adjusts the `Items` totalizer and the grand total.\n */\nexport function buildOptimisticRemoveItems(\n  cart: CartEntity,\n  items: readonly CartItemEntity[],\n): { cartItemsRemove: CartItemsRemovePayload } {\n  const removedIds = new Set(items.map((item) => item.id));\n  const removedLines = cart.items.filter((i) => removedIds.has(i.id));\n  if (removedLines.length === 0) {\n    return {\n      cartItemsRemove: {\n        __typename: 'CartItemsRemovePayload',\n        cart,\n        userErrors: emptyUserErrors(),\n      },\n    };\n  }\n\n  const priceDelta = removedLines.reduce((sum, line) => sum - line.sellingPrice.amount * line.quantity, 0);\n\n  return {\n    cartItemsRemove: {\n      __typename: 'CartItemsRemovePayload',\n      cart: {\n        __typename: 'Cart',\n        id: cart.id,\n        items: cart.items.filter((i) => !removedIds.has(i.id)),\n        totalizers: adjustItemsTotalizer(cart.totalizers, priceDelta),\n        total: moneyAdd(cart.total, priceDelta),\n        messages: cart.messages,\n        appliedCoupons: cart.appliedCoupons,\n      },\n      userErrors: emptyUserErrors(),\n    },\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AA4BA,SAAS,SAAS,OAAc,OAAsB;CAKpD,OAAO;EAAE,YAAY;EAAS,QAAQ,OAAO,MAAM,MAAM,IAAI;EAAO,cAAc,MAAM;CAAa;AACvG;AAEA,SAAS,qBAAqB,YAAsC,OAAgC;CAClG,OAAO,WAAW,KAAK,MAAO,EAAE,OAAO,UAAU;EAAE,GAAG;EAAG,OAAO,SAAS,EAAE,OAAO,KAAK;CAAE,IAAI,CAAE;AACjG;AAEA,SAAS,kBAA0B;CACjC,OAAO,CAAC;AACV;;;;AAKA,SAAgB,wBACd,MACA,MACA,KAAK,GAC0D;CAC/D,IAAI,MAAM,GACR,OAAO,EACL,0BAA0B;EACxB,YAAY;EACZ;EACA,YAAY,gBAAgB;CAC9B,EACF;CAGF,MAAM,cAAc,KAAK,MAAM,MAAM,MAAM,EAAE,OAAO,KAAK,EAAE;CAC3D,IAAI,CAAC,aACH,OAAO,EACL,0BAA0B;EACxB,YAAY;EACZ;EACA,YAAY,gBAAgB;CAC9B,EACF;CAGF,MAAM,cAAc,YAAY,WAAW;CAC3C,MAAM,QAAQ,YAAY,aAAa,SAAS;CAEhD,MAAM,eAAe,KAAK,MAAM,KAAK,MAAO,EAAE,OAAO,KAAK,KAAK;EAAE,GAAG;EAAG,UAAU;CAAY,IAAI,CAAE;CAEnG,OAAO,EACL,0BAA0B;EACxB,YAAY;EACZ,MAAM;GACJ,YAAY;GACZ,IAAI,KAAK;GACT,OAAO;GACP,YAAY,qBAAqB,KAAK,YAAY,KAAK;GACvD,OAAO,SAAS,KAAK,OAAO,KAAK;GACjC,UAAU,KAAK;GACf,gBAAgB,KAAK;EACvB;EACA,YAAY,gBAAgB;CAC9B,EACF;AACF;;;;;;AAOA,SAAgB,wBACd,MACA,MACA,KAAK,GAC0D;CAC/D,IAAI,MAAM,GACR,OAAO,EACL,0BAA0B;EACxB,YAAY;EACZ;EACA,YAAY,gBAAgB;CAC9B,EACF;CAGF,MAAM,cAAc,KAAK,MAAM,MAAM,MAAM,EAAE,OAAO,KAAK,EAAE;CAC3D,IAAI,CAAC,aACH,OAAO,EACL,0BAA0B;EACxB,YAAY;EACZ;EACA,YAAY,gBAAgB;CAC9B,EACF;CAGF,MAAM,oBAAoB,YAAY,WAAW;CACjD,MAAM,UAAU,qBAAqB;CACrC,MAAM,cAAc,UAAU,YAAY,WAAW;CACrD,MAAM,aAAa,CAAC,YAAY,aAAa,SAAS;CAEtD,MAAM,eAAe,UACjB,KAAK,MAAM,QAAQ,MAAM,EAAE,OAAO,KAAK,EAAE,IACzC,KAAK,MAAM,KAAK,MAAO,EAAE,OAAO,KAAK,KAAK;EAAE,GAAG;EAAG,UAAU;CAAkB,IAAI,CAAE;CAExF,OAAO,EACL,0BAA0B;EACxB,YAAY;EACZ,MAAM;GACJ,YAAY;GACZ,IAAI,KAAK;GACT,OAAO;GACP,YAAY,qBAAqB,KAAK,YAAY,UAAU;GAC5D,OAAO,SAAS,KAAK,OAAO,UAAU;GACtC,UAAU,KAAK;GACf,gBAAgB,KAAK;EACvB;EACA,YAAY,gBAAgB;CAC9B,EACF;AACF;;;;AAKA,SAAgB,sBACd,MACA,MAC2C;CAC3C,MAAM,cAAc,KAAK,MAAM,MAAM,MAAM,EAAE,OAAO,KAAK,EAAE;CAC3D,IAAI,CAAC,aACH,OAAO,EACL,gBAAgB;EACd,YAAY;EACZ;EACA,YAAY,gBAAgB;CAC9B,EACF;CAGF,MAAM,aAAa,CAAC,YAAY,aAAa,SAAS,YAAY;CAElE,OAAO,EACL,gBAAgB;EACd,YAAY;EACZ,MAAM;GACJ,YAAY;GACZ,IAAI,KAAK;GACT,OAAO,KAAK,MAAM,QAAQ,MAAM,EAAE,OAAO,KAAK,EAAE;GAChD,YAAY,qBAAqB,KAAK,YAAY,UAAU;GAC5D,OAAO,SAAS,KAAK,OAAO,UAAU;GACtC,UAAU,KAAK;GACf,gBAAgB,KAAK;EACvB;EACA,YAAY,gBAAgB;CAC9B,EACF;AACF;;;;;;AAOA,SAAgB,2BACd,MACA,OAC6C;CAC7C,MAAM,aAAa,IAAI,IAAI,MAAM,KAAK,SAAS,KAAK,EAAE,CAAC;CACvD,MAAM,eAAe,KAAK,MAAM,QAAQ,MAAM,WAAW,IAAI,EAAE,EAAE,CAAC;CAClE,IAAI,aAAa,WAAW,GAC1B,OAAO,EACL,iBAAiB;EACf,YAAY;EACZ;EACA,YAAY,gBAAgB;CAC9B,EACF;CAGF,MAAM,aAAa,aAAa,QAAQ,KAAK,SAAS,MAAM,KAAK,aAAa,SAAS,KAAK,UAAU,CAAC;CAEvG,OAAO,EACL,iBAAiB;EACf,YAAY;EACZ,MAAM;GACJ,YAAY;GACZ,IAAI,KAAK;GACT,OAAO,KAAK,MAAM,QAAQ,MAAM,CAAC,WAAW,IAAI,EAAE,EAAE,CAAC;GACrD,YAAY,qBAAqB,KAAK,YAAY,UAAU;GAC5D,OAAO,SAAS,KAAK,OAAO,UAAU;GACtC,UAAU,KAAK;GACf,gBAAgB,KAAK;EACvB;EACA,YAAY,gBAAgB;CAC9B,EACF;AACF"}

package/dist/sdk/cart/use-cart-actions.d.ts

@@ -27,7 +27,7 @@ export type CartCouponPayload = Readonly<{
 /**
  * The `cart` namespace surface. Item writes return the resulting `userErrors` (empty on success)
  * and publish them to `cartUserErrorsVar`; coupon writes publish to the dedicated
- * `cartCouponErrorsVar` (specs/fspg-830-coupon-entry.md AD-2).
+ * `cartCouponErrorsVar` (docs/storefront-core/reference-free-particle-model.md § The cart write contract).
  */
 export type CartActions = Readonly<{
   /** Add an item to the cart. Async (no optimistic response). Creates the cart on first add. */

package/dist/sdk/cart/use-cart-actions.js

@@ -1,8 +1,8 @@
 "use client";
 import { defineActions } from "../../core/dist/actions/registry.js";
 import "../../core/dist/index.js";
-import { cartCouponErrorsVar, cartLastAddVar, cartUserErrorsVar, orderFormIdVar } from "../state/cart.js";
 import { CART_COUPON_APPLY, CART_COUPON_REMOVE, CART_ITEMS_REMOVE, CART_ITEM_ADD, CART_ITEM_QUANTITY_DECREASE, CART_ITEM_QUANTITY_INCREASE, CART_ITEM_REMOVE, CART_VALIDATE, CartFragment } from "./operations.js";
+import { cartCouponErrorsVar, cartLastAddVar, cartUserErrorsVar, orderFormIdVar } from "../state/cart.js";
 import { buildOptimisticDecrease, buildOptimisticIncrease, buildOptimisticRemove, buildOptimisticRemoveItems } from "./optimistic.js";
 import { markAvailabilityFresh, trackCartWrite } from "./write-gate.js";
 import { useApolloClient, useMutation } from "@apollo/client/react";
@@ -10,7 +10,7 @@ import { useCallback, useMemo } from "react";
 //#region src/sdk/cart/use-cart-actions.ts
 /**
 * The `cart` action namespace — the consolidated, context-free owner of every cart write
-* (specs/actions.md, docs/storefront-core/adr-0010-actions-own-the-write-side.md).
+* (docs/storefront-core/reference-free-particle-model.md § The cart write contract, docs/storefront-core/adr-0010-actions-own-the-write-side.md).
 *
 * It replaces `useCartMutations` + the mutation handlers `CartRoot` used to publish through
 * `CartDataContext`. A handler reads the current cart from the normalized Apollo cache (keyed by
@@ -48,7 +48,7 @@ function publishCoupon(errors) {
 /**
 * Publish a write's outcome and, when it came back clean, stamp the availability freshness window —
 * a clean write's payload carries the platform's recomputed cart, which is what lets the
-* validate-on-open call skip (specs/mini-cart-validation-wiring.md, Decision 2). Used only on paths
+* validate-on-open call skip (docs/storefront-core/reference-free-particle-model.md § The cart write contract). Used only on paths
 * where a mutation actually reached the server: a `userErrors` response carries `cart: null` and a
 * no-op (unknown line) issues no request, so neither refreshes availability.
 */
@@ -75,7 +75,7 @@ function hydrateCartId(cartId) {
 * null before the cart is minted/loaded. Module-level so it can be shared with the read-only callers
 * that live outside this hook — the pre-checkout gate re-reads the corrected cart this way after
 * `validate` resolves, because Apollo commits the mutation's cache write before the promise settles
-* (specs/mini-cart-validation-wiring.md, Decision 3). The codegen `CartFragment` document embeds its
+* (docs/storefront-core/reference-cart.md § Validation). The codegen `CartFragment` document embeds its
 * nested fragments, so it is a self-contained read.
 */
 function readCartFromCache(client) {

package/dist/sdk/cart/use-cart-actions.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-cart-actions.js","names":[],"sources":["../../../src/sdk/cart/use-cart-actions.ts"],"sourcesContent":["'use client';\n\nimport type { ApolloClient } from '@apollo/client';\nimport { useApolloClient, useMutation } from '@apollo/client/react';\nimport { defineActions } from '@vtex/fs-core';\nimport { useCallback, useMemo } from 'react';\nimport { cartCouponErrorsVar, cartLastAddVar, cartUserErrorsVar, orderFormIdVar } from '../state/cart.js';\nimport {\n  CART_COUPON_APPLY,\n  CART_COUPON_REMOVE,\n  CART_ITEM_ADD,\n  CART_ITEM_QUANTITY_DECREASE,\n  CART_ITEM_QUANTITY_INCREASE,\n  CART_ITEM_REMOVE,\n  CART_ITEMS_REMOVE,\n  CART_VALIDATE,\n  type CartEntity,\n  CartFragment,\n  type CartItemEntity,\n  type CartUserError,\n} from './operations.js';\nimport {\n  buildOptimisticDecrease,\n  buildOptimisticIncrease,\n  buildOptimisticRemove,\n  buildOptimisticRemoveItems,\n} from './optimistic.js';\nimport { markAvailabilityFresh, trackCartWrite } from './write-gate.js';\n\n/**\n * The `cart` action namespace — the consolidated, context-free owner of every cart write\n * (specs/actions.md, docs/storefront-core/adr-0010-actions-own-the-write-side.md).\n *\n * It replaces `useCartMutations` + the mutation handlers `CartRoot` used to publish through\n * `CartDataContext`. A handler reads the current cart from the normalized Apollo cache (keyed by\n * `orderFormIdVar`), not from component props or React context, so any component anywhere in the\n * tree can dispatch a write through the compiler-injected `$actions.cart.*` prop — the cache is the\n * only meeting point between the read side and the write side (ADR-0010).\n *\n * `userErrors` from every call are published to `cartUserErrorsVar` (cleared at the start of the\n * next call) so `CartError` can surface them without a data context, and also returned to the caller.\n */\n\n/**\n * Thrown by the existing-line handlers (remove / quantity) when invoked before the cart resolves.\n * The first `addItem` mints the cart and hydrates `orderFormIdVar`; until then there is no cached\n * cart entity to read for the optimistic response.\n */\nexport class CartNotReadyError extends Error {\n  constructor(message?: string) {\n    super(message ?? 'CartNotReadyError: no cart in cache yet; add an item (or load the cart) before mutating a line.');\n    this.name = 'CartNotReadyError';\n  }\n}\n\nexport type AddItemPayload = Readonly<{\n  variantId: string;\n  quantity?: number;\n  /** Seller global Node ID, e.g. base64(\"Seller:1\"). The server rejects raw ids with INVALID_SELLER_ID. */\n  seller: string;\n}>;\n\n/** Existing-line payloads address the line by its opaque cart-item `id`; the handler reads the rest from cache. */\nexport type CartLinePayload = Readonly<{ id: string }>;\n\n/** Batch payloads address several lines by their opaque cart-item `id`s. */\nexport type CartLinesPayload = Readonly<{ ids: readonly string[] }>;\n\nexport type CartQuantityPayload = Readonly<{ id: string; by?: number }>;\n\n/** Coupon writes address the coupon by its `code`; the server resolves the cart from the cookie. */\nexport type CartCouponPayload = Readonly<{ code: string }>;\n\n/**\n * The `cart` namespace surface. Item writes return the resulting `userErrors` (empty on success)\n * and publish them to `cartUserErrorsVar`; coupon writes publish to the dedicated\n * `cartCouponErrorsVar` (specs/fspg-830-coupon-entry.md AD-2).\n */\nexport type CartActions = Readonly<{\n  /** Add an item to the cart. Async (no optimistic response). Creates the cart on first add. */\n  addItem: (payload: AddItemPayload) => Promise<readonly CartUserError[]>;\n  /** Remove a line entirely. Optimistic. */\n  removeItem: (payload: CartLinePayload) => Promise<readonly CartUserError[]>;\n  /** Remove several lines in one mutation. Optimistic. Ids missing from the cache are skipped. */\n  removeItems: (payload: CartLinesPayload) => Promise<readonly CartUserError[]>;\n  /** Increase a line's quantity by N (default 1). Optimistic. */\n  increaseQuantity: (payload: CartQuantityPayload) => Promise<readonly CartUserError[]>;\n  /** Decrease a line's quantity by N (default 1). Optimistic. Removes the line when result <= 0. */\n  decreaseQuantity: (payload: CartQuantityPayload) => Promise<readonly CartUserError[]>;\n  /** Apply a coupon code. Async (no optimistic). Publishes userErrors to cartCouponErrorsVar. */\n  applyCoupon: (payload: CartCouponPayload) => Promise<readonly CartUserError[]>;\n  /** Remove a coupon code by code. Async (no optimistic). Publishes userErrors to cartCouponErrorsVar. */\n  removeCoupon: (payload: CartCouponPayload) => Promise<readonly CartUserError[]>;\n  /**\n   * Re-check the active cart against the platform and adopt corrected availability. Async (no\n   * optimistic), read-only upstream. Returns userErrors (empty on success) to its caller and stamps\n   * the freshness window on success. Unlike the item writes it does NOT publish to\n   * `cartUserErrorsVar` — a speculative open-time failure must raise no error banner (Decision 6).\n   */\n  validate: () => Promise<readonly CartUserError[]>;\n}>;\n\nconst NETWORK_USER_ERROR: CartUserError = {\n  code: 'NETWORK_ERROR',\n  message: 'Unable to update cart. Please try again.',\n};\n\nfunction publish(errors: readonly CartUserError[]): readonly CartUserError[] {\n  cartUserErrorsVar(errors);\n  return errors;\n}\n\n/** Coupon-scoped publish — keeps coupon feedback off the shared item-error channel (AD-2). */\nfunction publishCoupon(errors: readonly CartUserError[]): readonly CartUserError[] {\n  cartCouponErrorsVar(errors);\n  return errors;\n}\n\n/**\n * Publish a write's outcome and, when it came back clean, stamp the availability freshness window —\n * a clean write's payload carries the platform's recomputed cart, which is what lets the\n * validate-on-open call skip (specs/mini-cart-validation-wiring.md, Decision 2). Used only on paths\n * where a mutation actually reached the server: a `userErrors` response carries `cart: null` and a\n * no-op (unknown line) issues no request, so neither refreshes availability.\n */\nfunction publishWrite(errors: readonly CartUserError[]): readonly CartUserError[] {\n  if (errors.length === 0) markAvailabilityFresh();\n  return publish(errors);\n}\n\n/** Coupon-channel counterpart of `publishWrite`. */\nfunction publishCouponWrite(errors: readonly CartUserError[]): readonly CartUserError[] {\n  if (errors.length === 0) markAvailabilityFresh();\n  return publishCoupon(errors);\n}\n\n/**\n * Backfill `orderFormIdVar` from a mutation's returned `cart.id` when local state is still cold.\n * A coupon op can be the first cart write (SSR cold / drawer closed on first load); without this the\n * later `requireLine` paths short-circuit on `orderFormIdVar() === null` and throw `CartNotReadyError`.\n * Mirrors the `addItem` first-add handoff.\n */\nfunction hydrateCartId(cartId: string | null): void {\n  if (cartId && orderFormIdVar() === null) orderFormIdVar(cartId);\n}\n\n/**\n * Read the live cart entity from the normalized cache (ADR-0010), keyed by `orderFormIdVar`. Returns\n * null before the cart is minted/loaded. Module-level so it can be shared with the read-only callers\n * that live outside this hook — the pre-checkout gate re-reads the corrected cart this way after\n * `validate` resolves, because Apollo commits the mutation's cache write before the promise settles\n * (specs/mini-cart-validation-wiring.md, Decision 3). The codegen `CartFragment` document embeds its\n * nested fragments, so it is a self-contained read.\n */\nexport function readCartFromCache(client: ApolloClient): CartEntity | null {\n  const cartId = orderFormIdVar();\n  if (!cartId) return null;\n  const cacheId = client.cache.identify({ __typename: 'Cart', id: cartId });\n  if (!cacheId) return null;\n  return (\n    client.cache.readFragment<CartEntity>({ id: cacheId, fragment: CartFragment, fragmentName: 'CartFragment' }) ?? null\n  );\n}\n\n/**\n * The `cart` namespace hook. Registered with the first-party action registry via `cartActions`\n * below; the compiler-emitted `CartActionProvider` calls it and threads the narrowed methods into\n * each consumer's `$actions.cart`.\n */\nexport function useCartActions(): CartActions {\n  const client = useApolloClient();\n\n  const [addMutation] = useMutation(CART_ITEM_ADD);\n  const [removeMutation] = useMutation(CART_ITEM_REMOVE);\n  const [removeItemsMutation] = useMutation(CART_ITEMS_REMOVE);\n  const [increaseMutation] = useMutation(CART_ITEM_QUANTITY_INCREASE);\n  const [decreaseMutation] = useMutation(CART_ITEM_QUANTITY_DECREASE);\n  const [applyCouponMutation] = useMutation(CART_COUPON_APPLY);\n  const [removeCouponMutation] = useMutation(CART_COUPON_REMOVE);\n  const [validateMutation] = useMutation(CART_VALIDATE);\n\n  const readCart = useCallback((): CartEntity | null => readCartFromCache(client), [client]);\n\n  const requireLine = useCallback(\n    (id: string): { cart: CartEntity; line: CartItemEntity } | null => {\n      const cart = readCart();\n      if (!cart) throw new CartNotReadyError();\n      const line = cart.items.find((item) => item.id === id);\n      if (!line) return null;\n      return { cart, line };\n    },\n    [readCart],\n  );\n\n  const addItem = useCallback<CartActions['addItem']>(\n    async (payload) => {\n      cartUserErrorsVar([]);\n      try {\n        const result = await trackCartWrite(\n          addMutation({\n            variables: {\n              input: { variantId: payload.variantId, quantity: payload.quantity ?? 1, seller: payload.seller },\n            },\n          }),\n        );\n        // Very-first add: the server minted a cart from the empty transport context. Hydrate the\n        // var so the existing-line handlers unlock without requiring a cart query.\n        if (orderFormIdVar() === null) {\n          const newId = result.data?.cartItemAdd?.cart?.id ?? null;\n          if (newId) orderFormIdVar(newId);\n        }\n        const errors = result.data?.cartItemAdd?.userErrors ?? [];\n        // Bump the add-success pulse only on the clean branch; the post-add behavior components\n        // (CartOpenOnAdd / CartRedirectOnAdd) key their effect on it. The userErrors and\n        // network-catch branches leave it untouched (specs/fspg-822-minicart-open-on-add.md).\n        if (errors.length === 0) cartLastAddVar(cartLastAddVar() + 1);\n        return publishWrite(errors);\n      } catch (error) {\n        console.error('[cart.addItem] cartItemAdd failed', error);\n        return publish([NETWORK_USER_ERROR]);\n      }\n    },\n    [addMutation],\n  );\n\n  const removeItem = useCallback<CartActions['removeItem']>(\n    async (payload) => {\n      const found = requireLine(payload.id);\n      if (!found) return publish([]);\n      cartUserErrorsVar([]);\n      try {\n        const result = await trackCartWrite(\n          removeMutation({\n            variables: { input: { variantId: found.line.variant.variantId } },\n            optimisticResponse: buildOptimisticRemove(found.cart, found.line),\n          }),\n        );\n        return publishWrite(result.data?.cartItemRemove?.userErrors ?? []);\n      } catch (error) {\n        console.error('[cart.removeItem] cartItemRemove failed', error);\n        return publish([NETWORK_USER_ERROR]);\n      }\n    },\n    [requireLine, removeMutation],\n  );\n\n  const removeItems = useCallback<CartActions['removeItems']>(\n    async (payload) => {\n      const cart = readCart();\n      if (!cart) throw new CartNotReadyError();\n      // Client-side tolerance mirroring removeItem's not-found no-op: ids without a cached line\n      // are skipped, and the surviving set is deduped before the single mutation.\n      const lines = cart.items.filter((item) => payload.ids.includes(item.id));\n      if (lines.length === 0) return publish([]);\n      const variantIds = [...new Set(lines.map((line) => line.variant.variantId))];\n      cartUserErrorsVar([]);\n      try {\n        const result = await trackCartWrite(\n          removeItemsMutation({\n            variables: { input: { variantIds } },\n            optimisticResponse: buildOptimisticRemoveItems(cart, lines),\n          }),\n        );\n        return publishWrite(result.data?.cartItemsRemove?.userErrors ?? []);\n      } catch (error) {\n        console.error('[cart.removeItems] cartItemsRemove failed', error);\n        return publish([NETWORK_USER_ERROR]);\n      }\n    },\n    [readCart, removeItemsMutation],\n  );\n\n  const increaseQuantity = useCallback<CartActions['increaseQuantity']>(\n    async (payload) => {\n      const by = payload.by ?? 1;\n      const found = requireLine(payload.id);\n      if (!found) return publish([]);\n      cartUserErrorsVar([]);\n      try {\n        const result = await trackCartWrite(\n          increaseMutation({\n            variables: { input: { variantId: found.line.variant.variantId, quantityToAdd: by } },\n            optimisticResponse: buildOptimisticIncrease(found.cart, found.line, by),\n          }),\n        );\n        return publishWrite(result.data?.cartItemQuantityIncrease?.userErrors ?? []);\n      } catch (error) {\n        console.error('[cart.increaseQuantity] cartItemQuantityIncrease failed', error);\n        return publish([NETWORK_USER_ERROR]);\n      }\n    },\n    [requireLine, increaseMutation],\n  );\n\n  const decreaseQuantity = useCallback<CartActions['decreaseQuantity']>(\n    async (payload) => {\n      const by = payload.by ?? 1;\n      const found = requireLine(payload.id);\n      if (!found) return publish([]);\n      cartUserErrorsVar([]);\n      try {\n        const result = await trackCartWrite(\n          decreaseMutation({\n            variables: { input: { variantId: found.line.variant.variantId, quantityToRemove: by } },\n            optimisticResponse: buildOptimisticDecrease(found.cart, found.line, by),\n          }),\n        );\n        return publishWrite(result.data?.cartItemQuantityDecrease?.userErrors ?? []);\n      } catch (error) {\n        console.error('[cart.decreaseQuantity] cartItemQuantityDecrease failed', error);\n        return publish([NETWORK_USER_ERROR]);\n      }\n    },\n    [requireLine, decreaseMutation],\n  );\n\n  // Coupons are cart-level: no `requireLine` gate (AD-9). No optimistic response and no client\n  // rollback — totals and `isUnmatchedCondition` are server-computed and the server rolls back its\n  // own single-coupon rejections; the returned cart (spreading the extended CartFragment)\n  // self-updates the cache and every reactive subscriber (specs/fspg-830-coupon-entry.md AD-3/AD-8).\n  const applyCoupon = useCallback<CartActions['applyCoupon']>(\n    async (payload) => {\n      cartCouponErrorsVar([]);\n      try {\n        const result = await trackCartWrite(applyCouponMutation({ variables: { input: { code: payload.code } } }));\n        hydrateCartId(result.data?.cartCouponApply?.cart?.id ?? null);\n        return publishCouponWrite(result.data?.cartCouponApply?.userErrors ?? []);\n      } catch (error) {\n        console.error('[cart.applyCoupon] cartCouponApply failed', error);\n        return publishCoupon([NETWORK_USER_ERROR]);\n      }\n    },\n    [applyCouponMutation],\n  );\n\n  const removeCoupon = useCallback<CartActions['removeCoupon']>(\n    async (payload) => {\n      cartCouponErrorsVar([]);\n      try {\n        const result = await trackCartWrite(removeCouponMutation({ variables: { input: { code: payload.code } } }));\n        hydrateCartId(result.data?.cartCouponRemove?.cart?.id ?? null);\n        return publishCouponWrite(result.data?.cartCouponRemove?.userErrors ?? []);\n      } catch (error) {\n        console.error('[cart.removeCoupon] cartCouponRemove failed', error);\n        return publishCoupon([NETWORK_USER_ERROR]);\n      }\n    },\n    [removeCouponMutation],\n  );\n\n  // Read-only upstream (specs/mini-cart-validate-operation.md): re-simulates the cart and returns it\n  // with `variant.availability` corrected, spreading CartFragment so the guard, the per-line alert,\n  // and the badge re-render off the cache. Deliberately unlike the item writes: it does NOT register\n  // as an in-flight write (it would gate itself) and it does NOT publish to cartUserErrorsVar — the\n  // open call is speculative and the pre-checkout call is fail-open, so a failure must raise no error\n  // banner (Decision 6). It stamps the freshness window on success so open-on-add does not re-check.\n  const validate = useCallback<CartActions['validate']>(async () => {\n    try {\n      const result = await validateMutation();\n      // Hydrate as the coupon writes do: the corrected cart is now in the cache, and the pre-checkout\n      // gate finds it by `orderFormIdVar`. Without this a cold var would leave the gate reading null\n      // and passing a cart it never actually checked.\n      hydrateCartId(result.data?.cartValidate?.cart?.id ?? null);\n      const errors = result.data?.cartValidate?.userErrors ?? [];\n      if (errors.length === 0) markAvailabilityFresh();\n      return errors;\n    } catch (error) {\n      console.error('[cart.validate] cartValidate failed', error);\n      return [NETWORK_USER_ERROR];\n    }\n  }, [validateMutation]);\n\n  return useMemo(\n    () => ({\n      addItem,\n      removeItem,\n      removeItems,\n      increaseQuantity,\n      decreaseQuantity,\n      applyCoupon,\n      removeCoupon,\n      validate,\n    }),\n    [addItem, removeItem, removeItems, increaseQuantity, decreaseQuantity, applyCoupon, removeCoupon, validate],\n  );\n}\n\n/**\n * Declares the `cart` action namespace — the single source of truth for its method/payload metadata,\n * runtime provider, and `use` hook (mirrors `defineComponent`). The native catalog builder\n * (`@vtex/faststore-catalog`'s `buildPackageCatalog`) statically reads this call to emit `actions.json`;\n * at runtime `CartActionProvider` calls `useCartActions` directly.\n */\nexport const cartActions = defineActions({\n  namespace: 'cart',\n  description: 'Mutation-backed writes against the current cart (consolidates useCartMutations / CartRoot).',\n  provider: { name: 'CartActionProvider', importPath: '@vtex/faststore/internal/client' },\n  methods: {\n    addItem: {\n      description: 'Add an item to the cart (async strategy). Creates the cart on first add.',\n      payload: [\n        { name: 'variantId', type: 'string' },\n        { name: 'seller', type: 'string' },\n        { name: 'quantity', type: 'number', optional: true },\n      ],\n    },\n    removeItem: {\n      description: 'Remove a line from the cart (optimistic strategy).',\n      payload: [{ name: 'id', type: 'string' }],\n    },\n    removeItems: {\n      description: 'Remove several lines from the cart in one call (optimistic strategy).',\n      payload: [{ name: 'ids', type: 'string[]' }],\n    },\n    increaseQuantity: {\n      description: \"Increase a line's quantity by N (default 1, optimistic strategy).\",\n      payload: [\n        { name: 'id', type: 'string' },\n        { name: 'by', type: 'number', optional: true },\n      ],\n    },\n    decreaseQuantity: {\n      description: \"Decrease a line's quantity by N (default 1, optimistic). Removes the line at <= 0.\",\n      payload: [\n        { name: 'id', type: 'string' },\n        { name: 'by', type: 'number', optional: true },\n      ],\n    },\n    applyCoupon: {\n      description: 'Apply a coupon code to the cart (async strategy). Server recomputes totals.',\n      payload: [{ name: 'code', type: 'string' }],\n    },\n    removeCoupon: {\n      description: 'Remove a coupon code from the cart (async strategy). Server recomputes totals.',\n      payload: [{ name: 'code', type: 'string' }],\n    },\n    validate: {\n      description:\n        'Re-check the active cart against the platform and adopt corrected availability (async, read-only upstream).',\n      payload: [],\n    },\n  },\n  use: useCartActions,\n});\n"],"mappings":"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"}
+{"version":3,"file":"use-cart-actions.js","names":[],"sources":["../../../src/sdk/cart/use-cart-actions.ts"],"sourcesContent":["'use client';\n\nimport type { ApolloClient } from '@apollo/client';\nimport { useApolloClient, useMutation } from '@apollo/client/react';\nimport { defineActions } from '@vtex/fs-core';\nimport { useCallback, useMemo } from 'react';\nimport { cartCouponErrorsVar, cartLastAddVar, cartUserErrorsVar, orderFormIdVar } from '../state/cart.js';\nimport {\n  CART_COUPON_APPLY,\n  CART_COUPON_REMOVE,\n  CART_ITEM_ADD,\n  CART_ITEM_QUANTITY_DECREASE,\n  CART_ITEM_QUANTITY_INCREASE,\n  CART_ITEM_REMOVE,\n  CART_ITEMS_REMOVE,\n  CART_VALIDATE,\n  type CartEntity,\n  CartFragment,\n  type CartItemEntity,\n  type CartUserError,\n} from './operations.js';\nimport {\n  buildOptimisticDecrease,\n  buildOptimisticIncrease,\n  buildOptimisticRemove,\n  buildOptimisticRemoveItems,\n} from './optimistic.js';\nimport { markAvailabilityFresh, trackCartWrite } from './write-gate.js';\n\n/**\n * The `cart` action namespace — the consolidated, context-free owner of every cart write\n * (docs/storefront-core/reference-free-particle-model.md § The cart write contract, docs/storefront-core/adr-0010-actions-own-the-write-side.md).\n *\n * It replaces `useCartMutations` + the mutation handlers `CartRoot` used to publish through\n * `CartDataContext`. A handler reads the current cart from the normalized Apollo cache (keyed by\n * `orderFormIdVar`), not from component props or React context, so any component anywhere in the\n * tree can dispatch a write through the compiler-injected `$actions.cart.*` prop — the cache is the\n * only meeting point between the read side and the write side (ADR-0010).\n *\n * `userErrors` from every call are published to `cartUserErrorsVar` (cleared at the start of the\n * next call) so `CartError` can surface them without a data context, and also returned to the caller.\n */\n\n/**\n * Thrown by the existing-line handlers (remove / quantity) when invoked before the cart resolves.\n * The first `addItem` mints the cart and hydrates `orderFormIdVar`; until then there is no cached\n * cart entity to read for the optimistic response.\n */\nexport class CartNotReadyError extends Error {\n  constructor(message?: string) {\n    super(message ?? 'CartNotReadyError: no cart in cache yet; add an item (or load the cart) before mutating a line.');\n    this.name = 'CartNotReadyError';\n  }\n}\n\nexport type AddItemPayload = Readonly<{\n  variantId: string;\n  quantity?: number;\n  /** Seller global Node ID, e.g. base64(\"Seller:1\"). The server rejects raw ids with INVALID_SELLER_ID. */\n  seller: string;\n}>;\n\n/** Existing-line payloads address the line by its opaque cart-item `id`; the handler reads the rest from cache. */\nexport type CartLinePayload = Readonly<{ id: string }>;\n\n/** Batch payloads address several lines by their opaque cart-item `id`s. */\nexport type CartLinesPayload = Readonly<{ ids: readonly string[] }>;\n\nexport type CartQuantityPayload = Readonly<{ id: string; by?: number }>;\n\n/** Coupon writes address the coupon by its `code`; the server resolves the cart from the cookie. */\nexport type CartCouponPayload = Readonly<{ code: string }>;\n\n/**\n * The `cart` namespace surface. Item writes return the resulting `userErrors` (empty on success)\n * and publish them to `cartUserErrorsVar`; coupon writes publish to the dedicated\n * `cartCouponErrorsVar` (docs/storefront-core/reference-free-particle-model.md § The cart write contract).\n */\nexport type CartActions = Readonly<{\n  /** Add an item to the cart. Async (no optimistic response). Creates the cart on first add. */\n  addItem: (payload: AddItemPayload) => Promise<readonly CartUserError[]>;\n  /** Remove a line entirely. Optimistic. */\n  removeItem: (payload: CartLinePayload) => Promise<readonly CartUserError[]>;\n  /** Remove several lines in one mutation. Optimistic. Ids missing from the cache are skipped. */\n  removeItems: (payload: CartLinesPayload) => Promise<readonly CartUserError[]>;\n  /** Increase a line's quantity by N (default 1). Optimistic. */\n  increaseQuantity: (payload: CartQuantityPayload) => Promise<readonly CartUserError[]>;\n  /** Decrease a line's quantity by N (default 1). Optimistic. Removes the line when result <= 0. */\n  decreaseQuantity: (payload: CartQuantityPayload) => Promise<readonly CartUserError[]>;\n  /** Apply a coupon code. Async (no optimistic). Publishes userErrors to cartCouponErrorsVar. */\n  applyCoupon: (payload: CartCouponPayload) => Promise<readonly CartUserError[]>;\n  /** Remove a coupon code by code. Async (no optimistic). Publishes userErrors to cartCouponErrorsVar. */\n  removeCoupon: (payload: CartCouponPayload) => Promise<readonly CartUserError[]>;\n  /**\n   * Re-check the active cart against the platform and adopt corrected availability. Async (no\n   * optimistic), read-only upstream. Returns userErrors (empty on success) to its caller and stamps\n   * the freshness window on success. Unlike the item writes it does NOT publish to\n   * `cartUserErrorsVar` — a speculative open-time failure must raise no error banner (Decision 6).\n   */\n  validate: () => Promise<readonly CartUserError[]>;\n}>;\n\nconst NETWORK_USER_ERROR: CartUserError = {\n  code: 'NETWORK_ERROR',\n  message: 'Unable to update cart. Please try again.',\n};\n\nfunction publish(errors: readonly CartUserError[]): readonly CartUserError[] {\n  cartUserErrorsVar(errors);\n  return errors;\n}\n\n/** Coupon-scoped publish — keeps coupon feedback off the shared item-error channel (AD-2). */\nfunction publishCoupon(errors: readonly CartUserError[]): readonly CartUserError[] {\n  cartCouponErrorsVar(errors);\n  return errors;\n}\n\n/**\n * Publish a write's outcome and, when it came back clean, stamp the availability freshness window —\n * a clean write's payload carries the platform's recomputed cart, which is what lets the\n * validate-on-open call skip (docs/storefront-core/reference-free-particle-model.md § The cart write contract). Used only on paths\n * where a mutation actually reached the server: a `userErrors` response carries `cart: null` and a\n * no-op (unknown line) issues no request, so neither refreshes availability.\n */\nfunction publishWrite(errors: readonly CartUserError[]): readonly CartUserError[] {\n  if (errors.length === 0) markAvailabilityFresh();\n  return publish(errors);\n}\n\n/** Coupon-channel counterpart of `publishWrite`. */\nfunction publishCouponWrite(errors: readonly CartUserError[]): readonly CartUserError[] {\n  if (errors.length === 0) markAvailabilityFresh();\n  return publishCoupon(errors);\n}\n\n/**\n * Backfill `orderFormIdVar` from a mutation's returned `cart.id` when local state is still cold.\n * A coupon op can be the first cart write (SSR cold / drawer closed on first load); without this the\n * later `requireLine` paths short-circuit on `orderFormIdVar() === null` and throw `CartNotReadyError`.\n * Mirrors the `addItem` first-add handoff.\n */\nfunction hydrateCartId(cartId: string | null): void {\n  if (cartId && orderFormIdVar() === null) orderFormIdVar(cartId);\n}\n\n/**\n * Read the live cart entity from the normalized cache (ADR-0010), keyed by `orderFormIdVar`. Returns\n * null before the cart is minted/loaded. Module-level so it can be shared with the read-only callers\n * that live outside this hook — the pre-checkout gate re-reads the corrected cart this way after\n * `validate` resolves, because Apollo commits the mutation's cache write before the promise settles\n * (docs/storefront-core/reference-cart.md § Validation). The codegen `CartFragment` document embeds its\n * nested fragments, so it is a self-contained read.\n */\nexport function readCartFromCache(client: ApolloClient): CartEntity | null {\n  const cartId = orderFormIdVar();\n  if (!cartId) return null;\n  const cacheId = client.cache.identify({ __typename: 'Cart', id: cartId });\n  if (!cacheId) return null;\n  return (\n    client.cache.readFragment<CartEntity>({ id: cacheId, fragment: CartFragment, fragmentName: 'CartFragment' }) ?? null\n  );\n}\n\n/**\n * The `cart` namespace hook. Registered with the first-party action registry via `cartActions`\n * below; the compiler-emitted `CartActionProvider` calls it and threads the narrowed methods into\n * each consumer's `$actions.cart`.\n */\nexport function useCartActions(): CartActions {\n  const client = useApolloClient();\n\n  const [addMutation] = useMutation(CART_ITEM_ADD);\n  const [removeMutation] = useMutation(CART_ITEM_REMOVE);\n  const [removeItemsMutation] = useMutation(CART_ITEMS_REMOVE);\n  const [increaseMutation] = useMutation(CART_ITEM_QUANTITY_INCREASE);\n  const [decreaseMutation] = useMutation(CART_ITEM_QUANTITY_DECREASE);\n  const [applyCouponMutation] = useMutation(CART_COUPON_APPLY);\n  const [removeCouponMutation] = useMutation(CART_COUPON_REMOVE);\n  const [validateMutation] = useMutation(CART_VALIDATE);\n\n  const readCart = useCallback((): CartEntity | null => readCartFromCache(client), [client]);\n\n  const requireLine = useCallback(\n    (id: string): { cart: CartEntity; line: CartItemEntity } | null => {\n      const cart = readCart();\n      if (!cart) throw new CartNotReadyError();\n      const line = cart.items.find((item) => item.id === id);\n      if (!line) return null;\n      return { cart, line };\n    },\n    [readCart],\n  );\n\n  const addItem = useCallback<CartActions['addItem']>(\n    async (payload) => {\n      cartUserErrorsVar([]);\n      try {\n        const result = await trackCartWrite(\n          addMutation({\n            variables: {\n              input: { variantId: payload.variantId, quantity: payload.quantity ?? 1, seller: payload.seller },\n            },\n          }),\n        );\n        // Very-first add: the server minted a cart from the empty transport context. Hydrate the\n        // var so the existing-line handlers unlock without requiring a cart query.\n        if (orderFormIdVar() === null) {\n          const newId = result.data?.cartItemAdd?.cart?.id ?? null;\n          if (newId) orderFormIdVar(newId);\n        }\n        const errors = result.data?.cartItemAdd?.userErrors ?? [];\n        // Bump the add-success pulse only on the clean branch; the post-add behavior components\n        // (CartOpenOnAdd / CartRedirectOnAdd) key their effect on it. The userErrors and\n        // network-catch branches leave it untouched (docs/storefront-core/reference-free-particle-model.md § The cart write contract).\n        if (errors.length === 0) cartLastAddVar(cartLastAddVar() + 1);\n        return publishWrite(errors);\n      } catch (error) {\n        console.error('[cart.addItem] cartItemAdd failed', error);\n        return publish([NETWORK_USER_ERROR]);\n      }\n    },\n    [addMutation],\n  );\n\n  const removeItem = useCallback<CartActions['removeItem']>(\n    async (payload) => {\n      const found = requireLine(payload.id);\n      if (!found) return publish([]);\n      cartUserErrorsVar([]);\n      try {\n        const result = await trackCartWrite(\n          removeMutation({\n            variables: { input: { variantId: found.line.variant.variantId } },\n            optimisticResponse: buildOptimisticRemove(found.cart, found.line),\n          }),\n        );\n        return publishWrite(result.data?.cartItemRemove?.userErrors ?? []);\n      } catch (error) {\n        console.error('[cart.removeItem] cartItemRemove failed', error);\n        return publish([NETWORK_USER_ERROR]);\n      }\n    },\n    [requireLine, removeMutation],\n  );\n\n  const removeItems = useCallback<CartActions['removeItems']>(\n    async (payload) => {\n      const cart = readCart();\n      if (!cart) throw new CartNotReadyError();\n      // Client-side tolerance mirroring removeItem's not-found no-op: ids without a cached line\n      // are skipped, and the surviving set is deduped before the single mutation.\n      const lines = cart.items.filter((item) => payload.ids.includes(item.id));\n      if (lines.length === 0) return publish([]);\n      const variantIds = [...new Set(lines.map((line) => line.variant.variantId))];\n      cartUserErrorsVar([]);\n      try {\n        const result = await trackCartWrite(\n          removeItemsMutation({\n            variables: { input: { variantIds } },\n            optimisticResponse: buildOptimisticRemoveItems(cart, lines),\n          }),\n        );\n        return publishWrite(result.data?.cartItemsRemove?.userErrors ?? []);\n      } catch (error) {\n        console.error('[cart.removeItems] cartItemsRemove failed', error);\n        return publish([NETWORK_USER_ERROR]);\n      }\n    },\n    [readCart, removeItemsMutation],\n  );\n\n  const increaseQuantity = useCallback<CartActions['increaseQuantity']>(\n    async (payload) => {\n      const by = payload.by ?? 1;\n      const found = requireLine(payload.id);\n      if (!found) return publish([]);\n      cartUserErrorsVar([]);\n      try {\n        const result = await trackCartWrite(\n          increaseMutation({\n            variables: { input: { variantId: found.line.variant.variantId, quantityToAdd: by } },\n            optimisticResponse: buildOptimisticIncrease(found.cart, found.line, by),\n          }),\n        );\n        return publishWrite(result.data?.cartItemQuantityIncrease?.userErrors ?? []);\n      } catch (error) {\n        console.error('[cart.increaseQuantity] cartItemQuantityIncrease failed', error);\n        return publish([NETWORK_USER_ERROR]);\n      }\n    },\n    [requireLine, increaseMutation],\n  );\n\n  const decreaseQuantity = useCallback<CartActions['decreaseQuantity']>(\n    async (payload) => {\n      const by = payload.by ?? 1;\n      const found = requireLine(payload.id);\n      if (!found) return publish([]);\n      cartUserErrorsVar([]);\n      try {\n        const result = await trackCartWrite(\n          decreaseMutation({\n            variables: { input: { variantId: found.line.variant.variantId, quantityToRemove: by } },\n            optimisticResponse: buildOptimisticDecrease(found.cart, found.line, by),\n          }),\n        );\n        return publishWrite(result.data?.cartItemQuantityDecrease?.userErrors ?? []);\n      } catch (error) {\n        console.error('[cart.decreaseQuantity] cartItemQuantityDecrease failed', error);\n        return publish([NETWORK_USER_ERROR]);\n      }\n    },\n    [requireLine, decreaseMutation],\n  );\n\n  // Coupons are cart-level: no `requireLine` gate (AD-9). No optimistic response and no client\n  // rollback — totals and `isUnmatchedCondition` are server-computed and the server rolls back its\n  // own single-coupon rejections; the returned cart (spreading the extended CartFragment)\n  // self-updates the cache and every reactive subscriber (docs/storefront-core/reference-free-particle-model.md § The cart write contract).\n  const applyCoupon = useCallback<CartActions['applyCoupon']>(\n    async (payload) => {\n      cartCouponErrorsVar([]);\n      try {\n        const result = await trackCartWrite(applyCouponMutation({ variables: { input: { code: payload.code } } }));\n        hydrateCartId(result.data?.cartCouponApply?.cart?.id ?? null);\n        return publishCouponWrite(result.data?.cartCouponApply?.userErrors ?? []);\n      } catch (error) {\n        console.error('[cart.applyCoupon] cartCouponApply failed', error);\n        return publishCoupon([NETWORK_USER_ERROR]);\n      }\n    },\n    [applyCouponMutation],\n  );\n\n  const removeCoupon = useCallback<CartActions['removeCoupon']>(\n    async (payload) => {\n      cartCouponErrorsVar([]);\n      try {\n        const result = await trackCartWrite(removeCouponMutation({ variables: { input: { code: payload.code } } }));\n        hydrateCartId(result.data?.cartCouponRemove?.cart?.id ?? null);\n        return publishCouponWrite(result.data?.cartCouponRemove?.userErrors ?? []);\n      } catch (error) {\n        console.error('[cart.removeCoupon] cartCouponRemove failed', error);\n        return publishCoupon([NETWORK_USER_ERROR]);\n      }\n    },\n    [removeCouponMutation],\n  );\n\n  // Read-only upstream (docs/storefront-core/reference-free-particle-model.md § The cart write contract): re-simulates the cart and returns it\n  // with `variant.availability` corrected, spreading CartFragment so the guard, the per-line alert,\n  // and the badge re-render off the cache. Deliberately unlike the item writes: it does NOT register\n  // as an in-flight write (it would gate itself) and it does NOT publish to cartUserErrorsVar — the\n  // open call is speculative and the pre-checkout call is fail-open, so a failure must raise no error\n  // banner (Decision 6). It stamps the freshness window on success so open-on-add does not re-check.\n  const validate = useCallback<CartActions['validate']>(async () => {\n    try {\n      const result = await validateMutation();\n      // Hydrate as the coupon writes do: the corrected cart is now in the cache, and the pre-checkout\n      // gate finds it by `orderFormIdVar`. Without this a cold var would leave the gate reading null\n      // and passing a cart it never actually checked.\n      hydrateCartId(result.data?.cartValidate?.cart?.id ?? null);\n      const errors = result.data?.cartValidate?.userErrors ?? [];\n      if (errors.length === 0) markAvailabilityFresh();\n      return errors;\n    } catch (error) {\n      console.error('[cart.validate] cartValidate failed', error);\n      return [NETWORK_USER_ERROR];\n    }\n  }, [validateMutation]);\n\n  return useMemo(\n    () => ({\n      addItem,\n      removeItem,\n      removeItems,\n      increaseQuantity,\n      decreaseQuantity,\n      applyCoupon,\n      removeCoupon,\n      validate,\n    }),\n    [addItem, removeItem, removeItems, increaseQuantity, decreaseQuantity, applyCoupon, removeCoupon, validate],\n  );\n}\n\n/**\n * Declares the `cart` action namespace — the single source of truth for its method/payload metadata,\n * runtime provider, and `use` hook (mirrors `defineComponent`). The native catalog builder\n * (`@vtex/faststore-catalog`'s `buildPackageCatalog`) statically reads this call to emit `actions.json`;\n * at runtime `CartActionProvider` calls `useCartActions` directly.\n */\nexport const cartActions = defineActions({\n  namespace: 'cart',\n  description: 'Mutation-backed writes against the current cart (consolidates useCartMutations / CartRoot).',\n  provider: { name: 'CartActionProvider', importPath: '@vtex/faststore/internal/client' },\n  methods: {\n    addItem: {\n      description: 'Add an item to the cart (async strategy). Creates the cart on first add.',\n      payload: [\n        { name: 'variantId', type: 'string' },\n        { name: 'seller', type: 'string' },\n        { name: 'quantity', type: 'number', optional: true },\n      ],\n    },\n    removeItem: {\n      description: 'Remove a line from the cart (optimistic strategy).',\n      payload: [{ name: 'id', type: 'string' }],\n    },\n    removeItems: {\n      description: 'Remove several lines from the cart in one call (optimistic strategy).',\n      payload: [{ name: 'ids', type: 'string[]' }],\n    },\n    increaseQuantity: {\n      description: \"Increase a line's quantity by N (default 1, optimistic strategy).\",\n      payload: [\n        { name: 'id', type: 'string' },\n        { name: 'by', type: 'number', optional: true },\n      ],\n    },\n    decreaseQuantity: {\n      description: \"Decrease a line's quantity by N (default 1, optimistic). Removes the line at <= 0.\",\n      payload: [\n        { name: 'id', type: 'string' },\n        { name: 'by', type: 'number', optional: true },\n      ],\n    },\n    applyCoupon: {\n      description: 'Apply a coupon code to the cart (async strategy). Server recomputes totals.',\n      payload: [{ name: 'code', type: 'string' }],\n    },\n    removeCoupon: {\n      description: 'Remove a coupon code from the cart (async strategy). Server recomputes totals.',\n      payload: [{ name: 'code', type: 'string' }],\n    },\n    validate: {\n      description:\n        'Re-check the active cart against the platform and adopt corrected availability (async, read-only upstream).',\n      payload: [],\n    },\n  },\n  use: useCartActions,\n});\n"],"mappings":"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"}

package/dist/sdk/cart/use-cart-validate-on-open.js

@@ -5,7 +5,7 @@ import { useApolloClient, useReactiveVar } from "@apollo/client/react";
 import { useEffect, useRef } from "react";
 //#region src/sdk/cart/use-cart-validate-on-open.ts
 /**
-* Runs stock validation when the mini-cart overlay opens (specs/mini-cart-validation-wiring.md, FR-5).
+* Runs stock validation when the mini-cart overlay opens (docs/storefront-core/reference-cart.md § Validation).
 *
 * `miniCartOpenVar` is the overlay's single source of truth — the add-pulse open, the header trigger,
 * and manual close all route through it — so watching its closed→open edge covers every way the

package/dist/sdk/cart/use-cart-validate-on-open.js.map

@@ -1 +1 @@
-{"version":3,"file":"use-cart-validate-on-open.js","names":[],"sources":["../../../src/sdk/cart/use-cart-validate-on-open.ts"],"sourcesContent":["'use client';\n\nimport { useApolloClient, useReactiveVar } from '@apollo/client/react';\nimport { useEffect, useRef } from 'react';\nimport {\n  CART_VALIDATE_STALENESS_MS,\n  cartAvailabilityFreshAtVar,\n  cartWritesInFlightVar,\n  miniCartOpenVar,\n} from '../state/cart.js';\nimport { readCartFromCache } from './use-cart-actions.js';\n\n/**\n * Runs stock validation when the mini-cart overlay opens (specs/mini-cart-validation-wiring.md, FR-5).\n *\n * `miniCartOpenVar` is the overlay's single source of truth — the add-pulse open, the header trigger,\n * and manual close all route through it — so watching its closed→open edge covers every way the\n * drawer opens. The call is bounded and cooperative: it fires at most once per transition, and skips\n * when there is nothing to gain — no validate action wired, a cart write in flight, availability\n * refreshed within the staleness window (which is why open-on-add does not re-validate), or an empty\n * cart. `validate` is the compiler-injected `$actions.cart.validate`; when it is absent the hook is a\n * no-op, so a store without the action wired pays nothing.\n *\n * A dispatch is reserved synchronously with a ref latch, cleared when the call settles. Freshness is\n * only stamped once `validate` resolves, so a close-and-reopen during that window would otherwise slip\n * past the staleness guard and fire a second call; the latch closes that gap.\n */\nexport function useCartValidateOnOpen(validate: (() => Promise<unknown>) | undefined): void {\n  const client = useApolloClient();\n  const open = useReactiveVar(miniCartOpenVar);\n  const wasOpen = useRef(open);\n  const pending = useRef(false);\n\n  useEffect(() => {\n    const opened = open && !wasOpen.current;\n    wasOpen.current = open;\n    if (!opened || !validate || pending.current) return;\n    // A write in flight (or one that just settled, inside the window) already refreshed availability.\n    if (cartWritesInFlightVar() > 0) return;\n    if (Date.now() - cartAvailabilityFreshAtVar() < CART_VALIDATE_STALENESS_MS) return;\n    // Nothing to validate on an empty cart, and T1 would only round-trip a single read for it.\n    const cart = readCartFromCache(client);\n    if (!cart || cart.items.length === 0) return;\n    pending.current = true;\n    // The current wiring never rejects (useCartActions().validate catches and resolves with\n    // [NETWORK_USER_ERROR]); this guards a differently-injected validate so a rejection cannot\n    // escape as an unhandled promise rejection.\n    void Promise.resolve(validate())\n      .catch((error) => {\n        console.error('[cart.validateOnOpen] validate rejected', error);\n      })\n      .finally(() => {\n        pending.current = false;\n      });\n  }, [open, validate, client]);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AA2BA,SAAgB,sBAAsB,UAAsD;CAC1F,MAAM,SAAS,gBAAgB;CAC/B,MAAM,OAAO,eAAe,eAAe;CAC3C,MAAM,UAAU,OAAO,IAAI;CAC3B,MAAM,UAAU,OAAO,KAAK;CAE5B,gBAAgB;EACd,MAAM,SAAS,QAAQ,CAAC,QAAQ;EAChC,QAAQ,UAAU;EAClB,IAAI,CAAC,UAAU,CAAC,YAAY,QAAQ,SAAS;EAE7C,IAAI,sBAAsB,IAAI,GAAG;EACjC,IAAI,KAAK,IAAI,IAAI,2BAA2B,IAAA,KAAgC;EAE5E,MAAM,OAAO,kBAAkB,MAAM;EACrC,IAAI,CAAC,QAAQ,KAAK,MAAM,WAAW,GAAG;EACtC,QAAQ,UAAU;EAIlB,QAAa,QAAQ,SAAS,CAAC,CAAC,CAC7B,OAAO,UAAU;GAChB,QAAQ,MAAM,2CAA2C,KAAK;EAChE,CAAC,CAAC,CACD,cAAc;GACb,QAAQ,UAAU;EACpB,CAAC;CACL,GAAG;EAAC;EAAM;EAAU;CAAM,CAAC;AAC7B"}
+{"version":3,"file":"use-cart-validate-on-open.js","names":[],"sources":["../../../src/sdk/cart/use-cart-validate-on-open.ts"],"sourcesContent":["'use client';\n\nimport { useApolloClient, useReactiveVar } from '@apollo/client/react';\nimport { useEffect, useRef } from 'react';\nimport {\n  CART_VALIDATE_STALENESS_MS,\n  cartAvailabilityFreshAtVar,\n  cartWritesInFlightVar,\n  miniCartOpenVar,\n} from '../state/cart.js';\nimport { readCartFromCache } from './use-cart-actions.js';\n\n/**\n * Runs stock validation when the mini-cart overlay opens (docs/storefront-core/reference-cart.md § Validation).\n *\n * `miniCartOpenVar` is the overlay's single source of truth — the add-pulse open, the header trigger,\n * and manual close all route through it — so watching its closed→open edge covers every way the\n * drawer opens. The call is bounded and cooperative: it fires at most once per transition, and skips\n * when there is nothing to gain — no validate action wired, a cart write in flight, availability\n * refreshed within the staleness window (which is why open-on-add does not re-validate), or an empty\n * cart. `validate` is the compiler-injected `$actions.cart.validate`; when it is absent the hook is a\n * no-op, so a store without the action wired pays nothing.\n *\n * A dispatch is reserved synchronously with a ref latch, cleared when the call settles. Freshness is\n * only stamped once `validate` resolves, so a close-and-reopen during that window would otherwise slip\n * past the staleness guard and fire a second call; the latch closes that gap.\n */\nexport function useCartValidateOnOpen(validate: (() => Promise<unknown>) | undefined): void {\n  const client = useApolloClient();\n  const open = useReactiveVar(miniCartOpenVar);\n  const wasOpen = useRef(open);\n  const pending = useRef(false);\n\n  useEffect(() => {\n    const opened = open && !wasOpen.current;\n    wasOpen.current = open;\n    if (!opened || !validate || pending.current) return;\n    // A write in flight (or one that just settled, inside the window) already refreshed availability.\n    if (cartWritesInFlightVar() > 0) return;\n    if (Date.now() - cartAvailabilityFreshAtVar() < CART_VALIDATE_STALENESS_MS) return;\n    // Nothing to validate on an empty cart, and T1 would only round-trip a single read for it.\n    const cart = readCartFromCache(client);\n    if (!cart || cart.items.length === 0) return;\n    pending.current = true;\n    // The current wiring never rejects (useCartActions().validate catches and resolves with\n    // [NETWORK_USER_ERROR]); this guards a differently-injected validate so a rejection cannot\n    // escape as an unhandled promise rejection.\n    void Promise.resolve(validate())\n      .catch((error) => {\n        console.error('[cart.validateOnOpen] validate rejected', error);\n      })\n      .finally(() => {\n        pending.current = false;\n      });\n  }, [open, validate, client]);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AA2BA,SAAgB,sBAAsB,UAAsD;CAC1F,MAAM,SAAS,gBAAgB;CAC/B,MAAM,OAAO,eAAe,eAAe;CAC3C,MAAM,UAAU,OAAO,IAAI;CAC3B,MAAM,UAAU,OAAO,KAAK;CAE5B,gBAAgB;EACd,MAAM,SAAS,QAAQ,CAAC,QAAQ;EAChC,QAAQ,UAAU;EAClB,IAAI,CAAC,UAAU,CAAC,YAAY,QAAQ,SAAS;EAE7C,IAAI,sBAAsB,IAAI,GAAG;EACjC,IAAI,KAAK,IAAI,IAAI,2BAA2B,IAAA,KAAgC;EAE5E,MAAM,OAAO,kBAAkB,MAAM;EACrC,IAAI,CAAC,QAAQ,KAAK,MAAM,WAAW,GAAG;EACtC,QAAQ,UAAU;EAIlB,QAAa,QAAQ,SAAS,CAAC,CAAC,CAC7B,OAAO,UAAU;GAChB,QAAQ,MAAM,2CAA2C,KAAK;EAChE,CAAC,CAAC,CACD,cAAc;GACb,QAAQ,UAAU;EACpB,CAAC;CACL,GAAG;EAAC;EAAM;EAAU;CAAM,CAAC;AAC7B"}

package/dist/sdk/cart/write-gate.js

@@ -1,7 +1,7 @@
 import { cartAvailabilityFreshAtVar, cartWritesInFlightVar } from "../state/cart.js";
 //#region src/sdk/cart/write-gate.ts
 /**
-* In-flight cart-write registry (specs/mini-cart-validation-wiring.md, Decision 2).
+* In-flight cart-write registry (docs/storefront-core/reference-free-particle-model.md § The cart write contract).
 *
 * The stock-validation wiring needs two things the mutation contract never had to expose, because
 * the open-time validate is the first cart call that is not user-initiated:

package/dist/sdk/cart/write-gate.js.map

@@ -1 +1 @@
-{"version":3,"file":"write-gate.js","names":[],"sources":["../../../src/sdk/cart/write-gate.ts"],"sourcesContent":["import { cartAvailabilityFreshAtVar, cartWritesInFlightVar } from '../state/cart.js';\n\n/**\n * In-flight cart-write registry (specs/mini-cart-validation-wiring.md, Decision 2).\n *\n * The stock-validation wiring needs two things the mutation contract never had to expose, because\n * the open-time validate is the first cart call that is not user-initiated:\n *\n *   - an observable \"is a write running\" signal, so the open call can *skip* while one is (that\n *     write's response already carries current availability); and\n *   - an `await`-settlement primitive, so the pre-checkout call can *wait* for any write before it\n *     re-checks the cart it is about to send to checkout.\n *\n * Both derive from one module-scoped set of pending write promises. `validate` is read-only upstream\n * and must never register here — it would gate itself.\n */\n\nconst inFlight = new Set<Promise<unknown>>();\n\n/**\n * Stamp \"availability is fresh as of now\". Called only where the client actually received current\n * availability: a cart write that came back clean, or a successful `validate`. A write answered with\n * `userErrors` carries `cart: null` (mutation contract), so it learned nothing and must not stamp —\n * otherwise the next overlay open would skip validation on the strength of a rejected write.\n */\nexport function markAvailabilityFresh(): void {\n  cartAvailabilityFreshAtVar(Date.now());\n}\n\n/**\n * Register a cart write's promise for the lifetime of the call, publishing the reactive in-flight\n * count so the validate-on-open call can skip while a write is outstanding. Tracking only — the\n * freshness stamp belongs to the caller, which is the only place that can see whether the payload\n * came back clean. Returns the same promise so callers can `await trackCartWrite(mutation(...))`.\n */\nexport function trackCartWrite<T>(promise: Promise<T>): Promise<T> {\n  inFlight.add(promise);\n  cartWritesInFlightVar(inFlight.size);\n  const clear = () => {\n    inFlight.delete(promise);\n    cartWritesInFlightVar(inFlight.size);\n  };\n  promise.then(clear, clear);\n  return promise;\n}\n\n/**\n * Resolve once every write registered at call time has settled (fulfilled or rejected). Writes\n * started afterwards are not awaited — this captures \"any in-flight write\" at the moment the\n * pre-checkout call fires, which is exactly the ordering guarantee the checkout gate needs.\n */\nexport function awaitCartWrites(): Promise<void> {\n  return Promise.allSettled(inFlight).then(() => undefined);\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiBA,MAAM,2BAAW,IAAI,IAAsB;;;;;;;AAQ3C,SAAgB,wBAA8B;CAC5C,2BAA2B,KAAK,IAAI,CAAC;AACvC;;;;;;;AAQA,SAAgB,eAAkB,SAAiC;CACjE,SAAS,IAAI,OAAO;CACpB,sBAAsB,SAAS,IAAI;CACnC,MAAM,cAAc;EAClB,SAAS,OAAO,OAAO;EACvB,sBAAsB,SAAS,IAAI;CACrC;CACA,QAAQ,KAAK,OAAO,KAAK;CACzB,OAAO;AACT;;;;;;AAOA,SAAgB,kBAAiC;CAC/C,OAAO,QAAQ,WAAW,QAAQ,CAAC,CAAC,WAAW,KAAA,CAAS;AAC1D"}
+{"version":3,"file":"write-gate.js","names":[],"sources":["../../../src/sdk/cart/write-gate.ts"],"sourcesContent":["import { cartAvailabilityFreshAtVar, cartWritesInFlightVar } from '../state/cart.js';\n\n/**\n * In-flight cart-write registry (docs/storefront-core/reference-free-particle-model.md § The cart write contract).\n *\n * The stock-validation wiring needs two things the mutation contract never had to expose, because\n * the open-time validate is the first cart call that is not user-initiated:\n *\n *   - an observable \"is a write running\" signal, so the open call can *skip* while one is (that\n *     write's response already carries current availability); and\n *   - an `await`-settlement primitive, so the pre-checkout call can *wait* for any write before it\n *     re-checks the cart it is about to send to checkout.\n *\n * Both derive from one module-scoped set of pending write promises. `validate` is read-only upstream\n * and must never register here — it would gate itself.\n */\n\nconst inFlight = new Set<Promise<unknown>>();\n\n/**\n * Stamp \"availability is fresh as of now\". Called only where the client actually received current\n * availability: a cart write that came back clean, or a successful `validate`. A write answered with\n * `userErrors` carries `cart: null` (mutation contract), so it learned nothing and must not stamp —\n * otherwise the next overlay open would skip validation on the strength of a rejected write.\n */\nexport function markAvailabilityFresh(): void {\n  cartAvailabilityFreshAtVar(Date.now());\n}\n\n/**\n * Register a cart write's promise for the lifetime of the call, publishing the reactive in-flight\n * count so the validate-on-open call can skip while a write is outstanding. Tracking only — the\n * freshness stamp belongs to the caller, which is the only place that can see whether the payload\n * came back clean. Returns the same promise so callers can `await trackCartWrite(mutation(...))`.\n */\nexport function trackCartWrite<T>(promise: Promise<T>): Promise<T> {\n  inFlight.add(promise);\n  cartWritesInFlightVar(inFlight.size);\n  const clear = () => {\n    inFlight.delete(promise);\n    cartWritesInFlightVar(inFlight.size);\n  };\n  promise.then(clear, clear);\n  return promise;\n}\n\n/**\n * Resolve once every write registered at call time has settled (fulfilled or rejected). Writes\n * started afterwards are not awaited — this captures \"any in-flight write\" at the moment the\n * pre-checkout call fires, which is exactly the ordering guarantee the checkout gate needs.\n */\nexport function awaitCartWrites(): Promise<void> {\n  return Promise.allSettled(inFlight).then(() => undefined);\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiBA,MAAM,2BAAW,IAAI,IAAsB;;;;;;;AAQ3C,SAAgB,wBAA8B;CAC5C,2BAA2B,KAAK,IAAI,CAAC;AACvC;;;;;;;AAQA,SAAgB,eAAkB,SAAiC;CACjE,SAAS,IAAI,OAAO;CACpB,sBAAsB,SAAS,IAAI;CACnC,MAAM,cAAc;EAClB,SAAS,OAAO,OAAO;EACvB,sBAAsB,SAAS,IAAI;CACrC;CACA,QAAQ,KAAK,OAAO,KAAK;CACzB,OAAO;AACT;;;;;;AAOA,SAAgB,kBAAiC;CAC/C,OAAO,QAAQ,WAAW,QAAQ,CAAC,CAAC,WAAW,KAAA,CAAS;AAC1D"}

package/dist/sdk/data/entity-resolution-context.js

@@ -0,0 +1,31 @@
+"use client";
+import { createContext, useContext } from "react";
+//#region src/sdk/data/entity-resolution-context.ts
+/**
+* Is the `$data` reaching this subtree the cache's own answer for the entity the page query
+* currently points at, or the server-rendered `fallbackData` standing in for one?
+*
+* `DataOverrideContext` carries the slice and cannot carry this: a fallback slice and a resolved
+* one are the same shape, and an entity whose saved values are genuinely absent looks exactly like
+* an entity whose cache read regressed. Only `useReactiveEntity` knows which of the two it just
+* handed down, so it is the one that publishes here — see its `resolved` return.
+*
+* Default `true`: with no reactive provider above, nothing is outstanding. Storybook, unit tests and
+* any tree handing `$data` over as a plain prop read the default and gate nothing, exactly as they
+* do with `useReactiveDataSettled`.
+*/
+const EntityResolutionContext = createContext(true);
+/**
+* Every entity slice composed into this subtree's `$data` is the cache's own answer.
+*
+* Unlike `useReactiveDataSettled`, this is not latched: it re-arms on its own whenever the entity
+* ref moves or its cache read stops being complete, which is the whole point — a latched page-level
+* signal cannot tell a form that the data under it has gone back to being a placeholder.
+*/
+function useEntityDataResolved() {
+	return useContext(EntityResolutionContext);
+}
+//#endregion
+export { EntityResolutionContext, useEntityDataResolved };
+
+//# sourceMappingURL=entity-resolution-context.js.map

package/dist/sdk/data/entity-resolution-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-resolution-context.js","names":[],"sources":["../../../src/sdk/data/entity-resolution-context.ts"],"sourcesContent":["'use client';\n\nimport { createContext, useContext } from 'react';\n\n/**\n * Is the `$data` reaching this subtree the cache's own answer for the entity the page query\n * currently points at, or the server-rendered `fallbackData` standing in for one?\n *\n * `DataOverrideContext` carries the slice and cannot carry this: a fallback slice and a resolved\n * one are the same shape, and an entity whose saved values are genuinely absent looks exactly like\n * an entity whose cache read regressed. Only `useReactiveEntity` knows which of the two it just\n * handed down, so it is the one that publishes here — see its `resolved` return.\n *\n * Default `true`: with no reactive provider above, nothing is outstanding. Storybook, unit tests and\n * any tree handing `$data` over as a plain prop read the default and gate nothing, exactly as they\n * do with `useReactiveDataSettled`.\n */\nexport const EntityResolutionContext = createContext<boolean>(true);\n\n/**\n * Every entity slice composed into this subtree's `$data` is the cache's own answer.\n *\n * Unlike `useReactiveDataSettled`, this is not latched: it re-arms on its own whenever the entity\n * ref moves or its cache read stops being complete, which is the whole point — a latched page-level\n * signal cannot tell a form that the data under it has gone back to being a placeholder.\n */\nexport function useEntityDataResolved(): boolean {\n  return useContext(EntityResolutionContext);\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiBA,MAAa,0BAA0B,cAAuB,IAAI;;;;;;;;AASlE,SAAgB,wBAAiC;CAC/C,OAAO,WAAW,uBAAuB;AAC3C"}

package/dist/sdk/data/entity-subscriber.js

@@ -1,7 +1,8 @@
 "use client";
 import { DataOverrideContext } from "./data-override-context.js";
+import { EntityResolutionContext } from "./entity-resolution-context.js";
 import { useReactiveEntity } from "./use-reactive-entity.js";
-import { useContext } from "react";
+import { useContext, useMemo } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/sdk/data/entity-subscriber.tsx
 /**
@@ -12,14 +13,23 @@ import { jsx } from "react/jsx-runtime";
 */
 function EntitySubscriber({ entityFragment, fragmentName, rootField, fallbackData, reset, children }) {
 	const outer = useContext(DataOverrideContext);
-	const resolved = useReactiveEntity(entityFragment, fragmentName, rootField, fallbackData);
-	const value = reset ? { [rootField]: resolved } : {
+	const outerResolved = useContext(EntityResolutionContext);
+	const { data, resolved } = useReactiveEntity(entityFragment, fragmentName, rootField, fallbackData);
+	const value = useMemo(() => reset ? { [rootField]: data } : {
 		...outer && typeof outer === "object" ? outer : {},
-		[rootField]: resolved
-	};
-	return /* @__PURE__ */ jsx(DataOverrideContext, {
-		value,
-		children
+		[rootField]: data
+	}, [
+		reset,
+		rootField,
+		data,
+		outer
+	]);
+	return /* @__PURE__ */ jsx(EntityResolutionContext, {
+		value: reset ? resolved : outerResolved && resolved,
+		children: /* @__PURE__ */ jsx(DataOverrideContext, {
+			value,
+			children
+		})
 	});
 }
 //#endregion

package/dist/sdk/data/entity-subscriber.js.map

@@ -1 +1 @@
-{"version":3,"file":"entity-subscriber.js","names":[],"sources":["../../../src/sdk/data/entity-subscriber.tsx"],"sourcesContent":["'use client';\n\nimport type { DocumentNode } from '@apollo/client';\nimport type { ReactNode } from 'react';\nimport { useContext } from 'react';\nimport { DataOverrideContext } from './data-override-context.js';\nimport { useReactiveEntity } from './use-reactive-entity.js';\n\nexport type EntitySubscriberProps = Readonly<{\n  /** Derived `fragment <X>_<EntityType> on <EntityType>` document emitted by the compiler. */\n  entityFragment: DocumentNode;\n  /** Name of the derived fragment, passed to `useFragment`. */\n  fragmentName: string;\n  /** Top-level field of the page query (e.g. 'cart') used to extract the entity ref, and the key\n   * under which the resolved slice is merged into the composed `$data` object. */\n  rootField: string;\n  /** Server-rendered fragment payload; used until the cache resolves a complete entity slice. */\n  fallbackData: unknown;\n  /**\n   * When `true`, RESETS the context to `{ [rootField]: resolved }`, discarding any outer\n   * `DataOverrideContext` value — this is the outermost subscriber of a component's nested stack,\n   * and prevents a parent component's `$data` from leaking into this component's descendants. When\n   * `false`, merges this subscriber's slice into the SAME-stack outer value instead.\n   */\n  reset: boolean;\n  children: ReactNode;\n}>;\n\n/**\n * Per-entity subscriber used internally by `MultipleReactiveDataProvider` to compose several\n * entities' cache slices into one keyed `$data` object for a single component. Resolves its own\n * slice exactly like `ReactiveDataProvider` (see `useReactiveEntity`), then merges it under\n * `rootField` into the outer `DataOverrideContext` value.\n */\nexport function EntitySubscriber({\n  entityFragment,\n  fragmentName,\n  rootField,\n  fallbackData,\n  reset,\n  children,\n}: EntitySubscriberProps): ReactNode {\n  const outer = useContext(DataOverrideContext);\n  const resolved = useReactiveEntity(entityFragment, fragmentName, rootField, fallbackData);\n\n  const value = reset\n    ? { [rootField]: resolved }\n    : { ...(outer && typeof outer === 'object' ? outer : {}), [rootField]: resolved };\n\n  return <DataOverrideContext value={value}>{children}</DataOverrideContext>;\n}\n"],"mappings":";;;;;;;;;;;;AAkCA,SAAgB,iBAAiB,EAC/B,gBACA,cACA,WACA,cACA,OACA,YACmC;CACnC,MAAM,QAAQ,WAAW,mBAAmB;CAC5C,MAAM,WAAW,kBAAkB,gBAAgB,cAAc,WAAW,YAAY;CAExF,MAAM,QAAQ,QACV,GAAG,YAAY,SAAS,IACxB;EAAE,GAAI,SAAS,OAAO,UAAU,WAAW,QAAQ,CAAC;GAAK,YAAY;CAAS;CAElF,OAAO,oBAAC,qBAAD;EAA4B;EAAQ;CAA8B,CAAA;AAC3E"}
+{"version":3,"file":"entity-subscriber.js","names":[],"sources":["../../../src/sdk/data/entity-subscriber.tsx"],"sourcesContent":["'use client';\n\nimport type { DocumentNode } from '@apollo/client';\nimport type { ReactNode } from 'react';\nimport { useContext, useMemo } from 'react';\nimport { DataOverrideContext } from './data-override-context.js';\nimport { EntityResolutionContext } from './entity-resolution-context.js';\nimport { useReactiveEntity } from './use-reactive-entity.js';\n\nexport type EntitySubscriberProps = Readonly<{\n  /** Derived `fragment <X>_<EntityType> on <EntityType>` document emitted by the compiler. */\n  entityFragment: DocumentNode;\n  /** Name of the derived fragment, passed to `useFragment`. */\n  fragmentName: string;\n  /** Top-level field of the page query (e.g. 'cart') used to extract the entity ref, and the key\n   * under which the resolved slice is merged into the composed `$data` object. */\n  rootField: string;\n  /** Server-rendered fragment payload; used until the cache resolves a complete entity slice. */\n  fallbackData: unknown;\n  /**\n   * When `true`, RESETS the context to `{ [rootField]: resolved }`, discarding any outer\n   * `DataOverrideContext` value — this is the outermost subscriber of a component's nested stack,\n   * and prevents a parent component's `$data` from leaking into this component's descendants. When\n   * `false`, merges this subscriber's slice into the SAME-stack outer value instead.\n   */\n  reset: boolean;\n  children: ReactNode;\n}>;\n\n/**\n * Per-entity subscriber used internally by `MultipleReactiveDataProvider` to compose several\n * entities' cache slices into one keyed `$data` object for a single component. Resolves its own\n * slice exactly like `ReactiveDataProvider` (see `useReactiveEntity`), then merges it under\n * `rootField` into the outer `DataOverrideContext` value.\n */\nexport function EntitySubscriber({\n  entityFragment,\n  fragmentName,\n  rootField,\n  fallbackData,\n  reset,\n  children,\n}: EntitySubscriberProps): ReactNode {\n  const outer = useContext(DataOverrideContext);\n  const outerResolved = useContext(EntityResolutionContext);\n  const { data, resolved } = useReactiveEntity(entityFragment, fragmentName, rootField, fallbackData);\n\n  // Memoised because this object is the context value: a fresh identity on every render makes every\n  // consumer below re-render, and in a form that is every keystroke. Its two sibling providers pass a\n  // stable reference already.\n  const value = useMemo(\n    () => (reset ? { [rootField]: data } : { ...(outer && typeof outer === 'object' ? outer : {}), [rootField]: data }),\n    [reset, rootField, data, outer],\n  );\n\n  // Mirrors the data merge exactly: the composed `$data` is resolved only when every slice merged\n  // into it is. `reset` discards the outer verdict for the same reason it discards the outer value —\n  // that verdict belongs to an ancestor component's own entities, not to this component's.\n  const resolution = reset ? resolved : outerResolved && resolved;\n\n  return (\n    <EntityResolutionContext value={resolution}>\n      <DataOverrideContext value={value}>{children}</DataOverrideContext>\n    </EntityResolutionContext>\n  );\n}\n"],"mappings":";;;;;;;;;;;;;AAmCA,SAAgB,iBAAiB,EAC/B,gBACA,cACA,WACA,cACA,OACA,YACmC;CACnC,MAAM,QAAQ,WAAW,mBAAmB;CAC5C,MAAM,gBAAgB,WAAW,uBAAuB;CACxD,MAAM,EAAE,MAAM,aAAa,kBAAkB,gBAAgB,cAAc,WAAW,YAAY;CAKlG,MAAM,QAAQ,cACL,QAAQ,GAAG,YAAY,KAAK,IAAI;EAAE,GAAI,SAAS,OAAO,UAAU,WAAW,QAAQ,CAAC;GAAK,YAAY;CAAK,GACjH;EAAC;EAAO;EAAW;EAAM;CAAK,CAChC;CAOA,OACE,oBAAC,yBAAD;EAAyB,OAHR,QAAQ,WAAW,iBAAiB;EAInD,UAAA,oBAAC,qBAAD;GAA4B;GAAQ;EAA8B,CAAA;CAC3C,CAAA;AAE7B"}

package/dist/sdk/data/index.js

@@ -2,6 +2,7 @@ import { DataOverrideContext, useDataOverride } from "./data-override-context.js
 import { HotDataProvider } from "./hot-data-provider.js";
 import { ListItemRefContext, useListItemRef } from "./list-item-ref-context.js";
 import { PageReactiveDataRoot, ReactiveRootContext } from "./page-reactive-data-root.js";
+import "./entity-resolution-context.js";
 import { MultipleReactiveDataProvider } from "./multiple-reactive-data-provider.js";
 import { ReactiveDataProvider } from "./reactive-data-provider.js";
 import { ReactiveListItemDataProvider } from "./reactive-list-item-data-provider.js";

package/dist/sdk/data/page-reactive-data-root.d.ts

@@ -30,9 +30,27 @@ export type ReactiveRootContextValue<TData = unknown> = Readonly<{
   /**
    * Error from the underlying useQuery. With non-null root fields (e.g. `cart: Cart!`), a failed
    * fetch nulls the whole operation's `data` — descendants need this to tell "fetch failed" apart
-   * from "entity is legitimately absent" (specs/cart-context-client-migrate.md US-5).
+   * from "entity is legitimately absent" (docs/storefront-core/reference-free-particle-model.md § Read side — data).
    */
   error: ErrorLike | undefined;
+  /**
+   * True only under a real `PageReactiveDataRoot`. Every other field above is ambiguous between
+   * "no root at all" and "a root with nothing to give right now" — `rootQueryData: undefined` and
+   * `loading: false` describe both the context default and a root whose query is skipped for want
+   * of a reactive variable. `useReactiveEntity` needs that distinction to tell a placeholder slice
+   * apart from the only slice there is.
+   *
+   * Required, not optional, and deliberately so. This flag is the whole of what arms the gate in
+   * `useReactiveEntity`, so a provider that omits it disarms the gate silently — measured: a value
+   * that `satisfies ReactiveRootContextValue` without it reproduces the corrupting payload byte for
+   * byte on an otherwise-fixed tree, and no test fails. `ReactiveRootContext` is public surface via
+   * `sdk/data/index.ts`, so that provider need not live in this repo. Making it required moves that
+   * failure to compile time.
+   *
+   * A hand-built context value stands in for a root's *output*, not for the reactive runtime, so it
+   * declares `false` and its subtree keeps gating on nothing.
+   */
+  hasRoot: boolean;
 }>;
 export declare const ReactiveRootContext: import("react").Context<Readonly<{
   /** Current root query data exposed to descendant `ReactiveDataProvider`s. */
@@ -44,9 +62,27 @@ export declare const ReactiveRootContext: import("react").Context<Readonly<{
   /**
    * Error from the underlying useQuery. With non-null root fields (e.g. `cart: Cart!`), a failed
    * fetch nulls the whole operation's `data` — descendants need this to tell "fetch failed" apart
-   * from "entity is legitimately absent" (specs/cart-context-client-migrate.md US-5).
+   * from "entity is legitimately absent" (docs/storefront-core/reference-free-particle-model.md § Read side — data).
    */
   error: ErrorLike | undefined;
+  /**
+   * True only under a real `PageReactiveDataRoot`. Every other field above is ambiguous between
+   * "no root at all" and "a root with nothing to give right now" — `rootQueryData: undefined` and
+   * `loading: false` describe both the context default and a root whose query is skipped for want
+   * of a reactive variable. `useReactiveEntity` needs that distinction to tell a placeholder slice
+   * apart from the only slice there is.
+   *
+   * Required, not optional, and deliberately so. This flag is the whole of what arms the gate in
+   * `useReactiveEntity`, so a provider that omits it disarms the gate silently — measured: a value
+   * that `satisfies ReactiveRootContextValue` without it reproduces the corrupting payload byte for
+   * byte on an otherwise-fixed tree, and no test fails. `ReactiveRootContext` is public surface via
+   * `sdk/data/index.ts`, so that provider need not live in this repo. Making it required moves that
+   * failure to compile time.
+   *
+   * A hand-built context value stands in for a root's *output*, not for the reactive runtime, so it
+   * declares `false` and its subtree keeps gating on nothing.
+   */
+  hasRoot: boolean;
 }>>;
 export declare function PageReactiveDataRoot<TData = unknown, TVars extends OperationVariables = OperationVariables>(props: PageReactiveDataRootProps<TData, TVars>): ReactNode;
 //#endregion

package/dist/sdk/data/page-reactive-data-root.js

@@ -15,7 +15,8 @@ const ReactiveRootContext = createContext({
 	rootQueryData: void 0,
 	loading: false,
 	hasAllRequiredVariables: false,
-	error: void 0
+	error: void 0,
+	hasRoot: false
 });
 function getOperationDefinition(query) {
 	for (const definition of query.definitions) if (definition.kind === Kind.OPERATION_DEFINITION) return definition;
@@ -135,7 +136,8 @@ function PageReactiveDataRoot(props) {
 		rootQueryData: data ?? void 0,
 		loading,
 		hasAllRequiredVariables,
-		error
+		error,
+		hasRoot: true
 	}), [
 		data,
 		loading,