Commit b6393fd38b9 for woocommerce

commit b6393fd38b921d7e1ac183e3c9bae891bff9530a
Author: Mario Santos <34552881+SantosGuillamot@users.noreply.github.com>
Date:   Thu Nov 19 16:35:39 2026 +0100

    Reorganize the Interactivity API stores folder and split the cart store by concern (#69034)

    * Move the products and shopper-lists stores into the stores folder

    * Assemble the woocommerce store from cart part files

    * Move the Interactivity API stores README to the stores folder

    * Describe the stores folder layout and point the stores README at the moved files

    * Point the blocks guide at the reorganized Interactivity API stores folder

    * Limit the stores README changes to the moved file paths

    * Drop the blocks guide's stores README summary that the README does not support

    * Declare the cart-only store types in cart/types.ts

    * Name both type files of the woocommerce store in the blocks guide

    * Add a changelog entry for the stores folder reorganization

    * Port trunk's new stores path references to the reorganized layout

    Trunk added a link to the stores README in AGENTS.md (#70171) and a
    pointer to the cart store's Jest tests in the mutation batcher E2E spec
    (#68179), both naming paths this PR moves. Point them at the new
    locations.

    Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

    * Explain why the woocommerce store's side-effect imports survive tree-shaking

    The store is assembled from side-effect-only imports in index.ts, which
    webpack keeps only because package.json lists the store folder in
    sideEffects. Without that entry the production module builds empty.

    Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

    * Move the cart-line helpers from notices.ts to cart/utils.ts

    isCartItem and lineMatchesProduct are used by the cart actions as well
    as the notices, so they don't belong to the notices concern.

    Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

    ---------

    Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

diff --git a/AGENTS.md b/AGENTS.md
index c00cff8e7d5..b73d3500b44 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -332,7 +332,7 @@ Do not import these user-facing strings from `block.json`, pass JSON properties

 ## Interactivity API Stores

-Before changing WooCommerce Interactivity API stores or blocks that use them, please read the [Woo iAPI stores README](plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/README.md).```
+Before changing WooCommerce Interactivity API stores or blocks that use them, please read the [Woo iAPI stores README](plugins/woocommerce/client/blocks/assets/js/base/stores/README.md).```

 Most WooCommerce Interactivity API stores are **private by design**. Exception: the `woocommerce/product-filters` store is public for Product Filters inner-block extensibility.

diff --git a/plugins/woocommerce/changelog/wooplug-7779-01-split-cart-store b/plugins/woocommerce/changelog/wooplug-7779-01-split-cart-store
new file mode 100644
index 00000000000..888b07549fc
--- /dev/null
+++ b/plugins/woocommerce/changelog/wooplug-7779-01-split-cart-store
@@ -0,0 +1,3 @@
+Significance: patch
+Type: dev
+Comment: Reorganize the Interactivity API stores folder and split the cart store by concern; no behavior change.
diff --git a/plugins/woocommerce/client/blocks/CLAUDE.md b/plugins/woocommerce/client/blocks/CLAUDE.md
index 5971cf9fa8f..c5ff58769e7 100644
--- a/plugins/woocommerce/client/blocks/CLAUDE.md
+++ b/plugins/woocommerce/client/blocks/CLAUDE.md
@@ -47,7 +47,7 @@ client/blocks/
 │   ├── blocks/              # Block implementations (cart, checkout, filters, products)
 │   │   └── product-elements-blocks/ # Reusable product element blocks
 │   ├── base/                # Shared components, context, hooks, stores
-│   │   └── stores/woocommerce/  # Interactivity API stores (LOCKED)
+│   │   └── stores/          # Interactivity API stores (LOCKED)
 │   ├── editor-components/   # 33+ shared editor UI components
 │   ├── extensions/          # Extension integrations
 │   └── utils/               # Shared utility functions
@@ -142,7 +142,8 @@ For private stores:

 - Not intended for third-party extension
 - Removing/changing store state is NOT a breaking change
-- `assets/js/base/stores/woocommerce/` contains cart, product-data, products stores
+- `assets/js/base/stores/` holds each separate store as one file (`products.ts`, `shopper-lists.ts`, `store-notices.ts`)
+- The `woocommerce` store lives in `assets/js/base/stores/woocommerce/`: `index.ts` registers it, `types.ts` declares its store-wide types, and `cart/` holds the cart code split by concern, with the cart-only types in `cart/types.ts`
 - Cart store uses mutation batching for performance

 ### IntegrationRegistry (Extension API)
diff --git a/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/README.md b/plugins/woocommerce/client/blocks/assets/js/base/stores/README.md
similarity index 95%
rename from plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/README.md
rename to plugins/woocommerce/client/blocks/assets/js/base/stores/README.md
index 7dba7746dc0..e0acf871b41 100644
--- a/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/README.md
+++ b/plugins/woocommerce/client/blocks/assets/js/base/stores/README.md
@@ -15,10 +15,10 @@ A locked, server-populated iAPI store that exposes WooCommerce products and vari

 **Source files:**

--   JS: `plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/products.ts`
+-   JS: `plugins/woocommerce/client/blocks/assets/js/base/stores/products.ts`
 -   PHP: `plugins/woocommerce/src/Blocks/SharedStores/ProductsStore.php`
 -   PHP procedural wrappers: `plugins/woocommerce/includes/wc-interactivity-api-functions.php`
--   Behavioral tests: `plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/test/products.test.ts`
+-   Behavioral tests: `plugins/woocommerce/client/blocks/assets/js/base/stores/test/products.test.ts`

 ### When to use it

@@ -237,7 +237,7 @@ For variable products, `findProduct` returns `null` when no variation matches th

 ## `woocommerce` store

-The `woocommerce` Interactivity API store (`base/stores/woocommerce/cart.ts`) is served as the script module `@woocommerce/stores/woocommerce`, and blocks load it from that id. It holds cart state and actions, with mutation batching for performance. This section covers the `addCartItem` outcome contract and the once-per-cycle cross-cutting side effects below — it is not a write-up of the store's full state shape, its other actions, or the rest of the mutation batcher's internals.
+The `woocommerce` Interactivity API store (`base/stores/woocommerce/`) is served as the script module `@woocommerce/stores/woocommerce`, and blocks load it from that id. It holds cart state and actions, with mutation batching for performance. This section covers the `addCartItem` outcome contract and the once-per-cycle cross-cutting side effects below — it is not a write-up of the store's full state shape, its other actions, or the rest of the mutation batcher's internals.

 ### The `addCartItem` outcome contract

@@ -298,9 +298,9 @@ The store emits three cart-wide side effects whenever a mutation succeeds:
 -   the legacy `wc-blocks_added_to_cart` event (payload `{ preserveCartData: true }`), consumed outside this store;
 -   the screen-reader "added to cart" announcement, made only when the store is configured with an `addedToCartText` message.

-These fire **exactly once per mutation batch cycle, not once per request**. When the mutation batcher (`mutation-batcher.ts`) coalesces several concurrent mutations — e.g. N concurrent `addCartItem` calls issued in the same tick — into one processing cycle and one `/wc/store/v1/batch` request, each of the three effects fires only once for that cycle, not once per coalesced request. Before this mechanism existed, each of the three effects was wired per request rather than per cycle, so N coalesced mutations produced N sync events (N redundant resync GETs), N legacy events, and N announcements; a single successful mutation still produces exactly one of each, unchanged.
+These fire **exactly once per mutation batch cycle, not once per request**. When the mutation batcher (`woocommerce/cart/mutation-batcher.ts`) coalesces several concurrent mutations — e.g. N concurrent `addCartItem` calls issued in the same tick — into one processing cycle and one `/wc/store/v1/batch` request, each of the three effects fires only once for that cycle, not once per coalesced request. Before this mechanism existed, each of the three effects was wired per request rather than per cycle, so N coalesced mutations produced N sync events (N redundant resync GETs), N legacy events, and N announcements; a single successful mutation still produces exactly one of each, unchanged.

-**Mechanism.** Every action that calls `sendCartRequest` attaches a per-request `meta: { quantityChanges, origin }` (type `CartMutationMeta`) describing that one mutation: `quantityChanges` is its contribution to the sync event's payload (`productsPendingAdd` / `cartItemsPendingQuantity` / `cartItemsPendingDelete`), and `origin` is `'add'` (set by `addCartItem` and `batchAddCartItems`, regardless of whether the mutation hit `add-item` or `update-item`) or `'remove'` (set by `removeCartItem`). The batcher carries `meta` through unchanged and, once a cycle settles — synchronously, after the cycle's server state is committed (or rolled back) and before the queue's `isProcessing` state clears — invokes the mutation queue's `onCycleSettled` config callback exactly once, with one `{ success, meta }` entry per request in the cycle. The `onCycleSettled` callback built into the queue passed to `createMutationQueue` inside `sendCartRequest` is the single place in `cart.ts` that emits the three effects; no action emits them itself.
+**Mechanism.** Every action that calls `sendCartRequest` attaches a per-request `meta: { quantityChanges, origin }` (type `CartMutationMeta`) describing that one mutation: `quantityChanges` is its contribution to the sync event's payload (`productsPendingAdd` / `cartItemsPendingQuantity` / `cartItemsPendingDelete`), and `origin` is `'add'` (set by `addCartItem` and `batchAddCartItems`, regardless of whether the mutation hit `add-item` or `update-item`) or `'remove'` (set by `removeCartItem`). The batcher carries `meta` through unchanged and, once a cycle settles — synchronously, after the cycle's server state is committed (or rolled back) and before the queue's `isProcessing` state clears — invokes the mutation queue's `onCycleSettled` config callback exactly once, with one `{ success, meta }` entry per request in the cycle. The `onCycleSettled` callback built into the queue passed to `createMutationQueue` inside `sendCartRequest` is the single place in `woocommerce/cart/actions.ts` that emits the three effects; no action emits them itself.

 **Gates.** The callback applies three rules to the cycle's successful entries (`entry.success && entry.meta`):

diff --git a/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/products.ts b/plugins/woocommerce/client/blocks/assets/js/base/stores/products.ts
similarity index 100%
rename from plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/products.ts
rename to plugins/woocommerce/client/blocks/assets/js/base/stores/products.ts
diff --git a/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/shopper-lists.ts b/plugins/woocommerce/client/blocks/assets/js/base/stores/shopper-lists.ts
similarity index 98%
rename from plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/shopper-lists.ts
rename to plugins/woocommerce/client/blocks/assets/js/base/stores/shopper-lists.ts
index fbfd77e4b28..5304e08dbbe 100644
--- a/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/shopper-lists.ts
+++ b/plugins/woocommerce/client/blocks/assets/js/base/stores/shopper-lists.ts
@@ -170,7 +170,7 @@ async function restRequest< T >(
 // JS-supplied state win over the existing (PHP-seeded) state for primitives,
 // so an empty-string default would clobber the values seeded server-side via
 // `wp_interactivity_state`. State for those fields comes purely from PHP. Same
-// reason the cart store doesn't ship state defaults — see cart.ts.
+// reason the cart store doesn't ship state defaults — see woocommerce/cart/actions.ts.
 const { state, actions } = store< Store >(
 	'woocommerce/shopper-lists',
 	{
@@ -289,7 +289,7 @@ const { state, actions } = store< Store >(
 				}
 			},

-			// Mirrors `cart.ts::showNoticeError`.
+			// Mirrors `woocommerce/cart/notices.ts::showNoticeError`.
 			*showNoticeError( error: Error ): AsyncAction< void > {
 				yield import( '@woocommerce/stores/store-notices' );
 				const { actions: noticeActions } = store< StoreNotices >(
diff --git a/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/test/products.test.ts b/plugins/woocommerce/client/blocks/assets/js/base/stores/test/products.test.ts
similarity index 100%
rename from plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/test/products.test.ts
rename to plugins/woocommerce/client/blocks/assets/js/base/stores/test/products.test.ts
diff --git a/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/cart.ts b/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/cart/actions.ts
similarity index 71%
rename from plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/cart.ts
rename to plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/cart/actions.ts
index 98e9bd13b17..7394e17321f 100644
--- a/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/cart.ts
+++ b/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/cart/actions.ts
@@ -5,16 +5,9 @@ import { getConfig, store } from '@wordpress/interactivity';
 import type { AsyncAction, TypeYield } from '@wordpress/interactivity';
 import type {
 	Cart,
-	CartItem,
 	CartVariationItem,
 	ApiErrorResponse,
-	CartResponseTotals,
-	Currency,
 } from '@woocommerce/types';
-import type {
-	Store as StoreNotices,
-	Notice,
-} from '@woocommerce/stores/store-notices';

 /**
  * Internal dependencies
@@ -27,102 +20,21 @@ import {
 	type MutationQueue,
 	type MutationResult,
 } from './mutation-batcher';
-import { doesCartItemMatchAttributes } from '../../utils/variations/does-cart-item-match-attributes';
-
-export type WooCommerceConfig = {
-	messages?: {
-		addedToCartText?: string;
-	};
-	placeholderImgSrc?: string;
-	currency?: Currency;
-	nonOptimisticProperties?: string[];
-};
-
-export type SelectedAttributes = Omit< CartVariationItem, 'raw_attribute' >;
-
-export type OptimisticCartItem = {
-	key?: string | undefined;
-	id: number;
-	quantity: number;
-	variation?: CartVariationItem[];
-	type: string;
-};
-
-export type ClientCartItem = Omit<
+import {
+	computeKeylessAddSuppressKeys,
+	generateErrorNotice,
+	getInfoNoticesFromCartUpdates,
+} from './notices';
+import { isCartItem, lineMatchesProduct } from './utils';
+import type { SelectedAttributes, WooCommerceConfig } from '../types';
+import type {
+	AddCartItemOutcome,
+	CartUpdateOptions,
+	ClientCartItem,
 	OptimisticCartItem,
-	'variation' | 'quantity'
-> & {
-	variation?: SelectedAttributes[];
-	/** The target quantity (absolute). Either this or quantityToAdd must be provided. */
-	quantity?: number;
-	/** Optional: add this delta to current quantity instead of setting absolute quantity */
-	quantityToAdd?: number;
-};
-
-type CartUpdateOptions = { showCartUpdatesNotices?: boolean };
-
-/**
- * The failure detail carried by a rejected `AddCartItemOutcome`.
- */
-export type AddCartItemError = {
-	/**
-	 * Server error code for a per-item rejection (e.g.
-	 * `woocommerce_rest_product_out_of_stock`), or the batcher's
-	 * `unknown_error` fallback. Absent on whole-batch/transport failures.
-	 */
-	code?: string;
-	/** Human-readable failure description. Always non-empty. */
-	message: string;
-};
-
-/**
- * The per-call outcome `addCartItem` resolves with, captured at the moment
- * its own request settles (accepted or rejected). A later throw in
- * post-success processing (notices) never downgrades an already-captured
- * success into a failure.
- */
-export type AddCartItemOutcome =
-	{ success: true } | { success: false; error: AddCartItemError };
-
-export type Store = {
-	state: {
-		errorMessages?: {
-			[ key: string ]: string;
-		};
-		restUrl: string;
-		nonce: string;
-		// Whether a cart update request is in progress.
-		isCartUpdating?: boolean;
-		findItemInCart: ( args: {
-			id: ClientCartItem[ 'id' ];
-			key?: ClientCartItem[ 'key' ];
-			variation?: ClientCartItem[ 'variation' ];
-		} ) => CartItem | OptimisticCartItem | undefined;
-		cart: Omit< Cart, 'items' > & {
-			items: ( OptimisticCartItem | CartItem )[];
-			totals: CartResponseTotals;
-		};
-	};
-	actions: {
-		removeCartItem: ( key: string ) => Promise< void >;
-		addCartItem: (
-			args: ClientCartItem,
-			options?: CartUpdateOptions
-		) => Promise< AddCartItemOutcome >;
-		batchAddCartItems: (
-			items: ClientCartItem[],
-			options?: CartUpdateOptions
-		) => Promise< void >;
-		// Todo: Check why if I switch to an async function here the types of the store stop working.
-		refreshCartItems: () => Promise< void >;
-		waitForIdle: () => Promise< void >;
-		showNoticeError: ( error: Error | ApiErrorResponse ) => Promise< void >;
-		updateNotices: (
-			notices: Notice[],
-			removeOthers?: boolean
-		) => Promise< void >;
-	};
-};
+	Store,
+} from './types';
+import { doesCartItemMatchAttributes } from '../../../utils/variations/does-cart-item-match-attributes';

 type QuantityChanges = {
 	cartItemsPendingQuantity?: string[];
@@ -148,11 +60,6 @@ type CartMutationMeta = {
 	origin: 'add' | 'remove';
 };

-// Guard to distinguish between optimistic and cart items.
-function isCartItem( item: OptimisticCartItem | CartItem ): item is CartItem {
-	return 'name' in item;
-}
-
 function isApiErrorResponse(
 	res: Response,
 	json: unknown
@@ -166,18 +73,6 @@ function generateError( error: ApiErrorResponse ): Error {
 	} );
 }

-const generateErrorNotice = ( error: Error | ApiErrorResponse ): Notice => ( {
-	notice: error.message,
-	type: 'error',
-	dismissible: true,
-} );
-
-const generateInfoNotice = ( message: string ): Notice => ( {
-	notice: message,
-	type: 'notice',
-	dismissible: true,
-} );
-
 /**
  * Computes the canonical product token for accumulating per-product totals
  * across a batch.
@@ -204,94 +99,6 @@ function productToken(
 	return `${ id }|${ attrs }`;
 }

-/**
- * Returns `true` when the given cart line matches the product identified by
- * `id` and `variation`, using the same matching logic as `findItemInCart`.
- *
- * Simple items match by `id` equality. Variation items additionally require
- * `variation.length` equality and `doesCartItemMatchAttributes`.
- *
- * @param item      The cart line to test.
- * @param id        The product id to match against.
- * @param variation The variation attributes to match against, if any.
- * @return `true` when the line belongs to the specified product.
- */
-function lineMatchesProduct(
-	item: OptimisticCartItem | CartItem,
-	id: number,
-	variation?: CartVariationItem[] | SelectedAttributes[]
-): boolean {
-	if ( item.type === 'variation' ) {
-		if (
-			id !== item.id ||
-			! item.variation ||
-			! variation ||
-			item.variation.length !== variation.length
-		) {
-			return false;
-		}
-		return doesCartItemMatchAttributes( item, variation );
-	}
-	return id === item.id;
-}
-
-/**
- * Builds a `Set` of pre-existing cart-line keys to suppress from the
- * "quantity changed" auto-update notice after a successful keyless add.
- *
- * For each product entry in `products`, computes:
- *   - `serverTotal` = sum of the committed server cart's lines matching that
- *     product (using the same matcher as `findItemInCart`).
- *   - `expectedTotal` = pre-add total + sum of posted deltas.
- *
- * When `serverTotal === expectedTotal`, the add was exact for that product
- * (no server-initiated cap, redistribution, or concurrent change), so every
- * pre-existing line key captured for that product is added to the returned
- * set and will be skipped in the auto-UPDATE notice diff.
- *
- * When the totals diverge, the product's keys are left out of the set and
- * the diff fires normally, reporting the server's actual quantity.
- *
- * Only keyless adds should call this helper. Keyed `update-item` changes
- * must never populate `products`; leaving their line keys out of the
- * suppression set ensures the "your change was undone" notice keeps firing.
- *
- * @param products   Per-product capture records, one per added product.
- * @param serverCart The committed server cart to sum against.
- * @return The flat set of pre-existing line keys to suppress.
- */
-function computeKeylessAddSuppressKeys(
-	products: Array< {
-		/** The product id used for matching. */
-		id: number;
-		/** The variation attributes used for matching, if any. */
-		variation?: CartVariationItem[] | SelectedAttributes[] | undefined;
-		/** Sum of all pre-add quantities across matching lines, captured before the optimistic bump. */
-		preAddTotal: number;
-		/** Sum of all posted deltas for this product in this add cycle. */
-		deltaTotal: number;
-		/** The pre-existing cart-line keys belonging to this product, captured before the optimistic bump. */
-		preExistingKeys: string[];
-	} >,
-	serverCart: Cart
-): Set< string > {
-	const suppressKeys = new Set< string >();
-	for ( const product of products ) {
-		const serverTotal = serverCart.items
-			.filter( ( item ) =>
-				lineMatchesProduct( item, product.id, product.variation )
-			)
-			.reduce( ( sum, item ) => sum + item.quantity, 0 );
-		const expectedTotal = product.preAddTotal + product.deltaTotal;
-		if ( serverTotal === expectedTotal ) {
-			for ( const key of product.preExistingKeys ) {
-				suppressKeys.add( key );
-			}
-		}
-	}
-	return suppressKeys;
-}
-
 /**
  * Merges the per-mutation `quantityChanges` records of every successful
  * mutation in a settled cycle into the single record dispatched with the
@@ -337,91 +144,6 @@ function mergeQuantityChanges( list: QuantityChanges[] ): QuantityChanges {
 	return merged;
 }

-/**
- * Derives the auto-update and auto-removal info notices from the diff between
- * the post-optimistic cart and the committed server cart.
- *
- * Auto-removal notices fire for lines present in `oldCart` that the server
- * dropped entirely (stock removal, product deletion, etc.). Because
- * `oldCart` is the post-optimistic snapshot, user-initiated removals are
- * already absent and do not produce spurious notices.
- *
- * Auto-update notices fire for server lines whose quantity differs from the
- * post-optimistic snapshot, with one suppression rule: any line whose key
- * appears in `suppressKeys` is skipped unconditionally. The action populates
- * `suppressKeys` with the pre-existing keys of products whose keyless add was
- * exact (server total == pre-add total + posted delta), so a successful keyless
- * add never emits a spurious "quantity changed" notice regardless of which
- * server line received the delta. Genuine server changes (cap, clamp, concurrent
- * mutation) still notify because they make the per-product totals diverge and
- * the keys are left out of the set.
- *
- * Keyed `update-item` changes and `removeCartItem` never populate
- * `suppressKeys` (the parameter defaults to an empty set), so their notice
- * behavior is byte-for-byte unchanged.
- *
- * @param oldCart      The post-optimistic cart snapshot used as the diff baseline.
- * @param newCart      The committed server cart to diff against.
- * @param suppressKeys Keys of pre-existing lines whose product's add was exact;
- *                     these lines are skipped in the auto-UPDATE filter.
- * @return The list of info notices to surface to the shopper.
- */
-const getInfoNoticesFromCartUpdates = (
-	oldCart: Store[ 'state' ][ 'cart' ],
-	newCart: Cart,
-	suppressKeys: Set< string > = new Set()
-): Notice[] => {
-	const oldItems = oldCart.items;
-	const newItems = newCart.items;
-
-	// Items auto-removed by the server (stock change, product deleted, etc.).
-	// We pass the optimistic snapshot as oldCart, so user-initiated removals
-	// are already absent and do not generate spurious notices here.
-	// Filtering on the `isCartItem` type guard first (rather than folding it
-	// into a single predicate) narrows the result to `CartItem[]`, so `.name`
-	// below type-checks without a cast.
-	const autoDeletedToNotify = oldItems
-		.filter( isCartItem )
-		.filter(
-			( old ) => ! newItems.some( ( item ) => old.key === item.key )
-		);
-
-	// Items whose quantity was adjusted by the server (stock cap, sold-individually).
-	// By default a line is compared optimistic → server, so intentional user
-	// changes are already reflected in oldItems and do not trigger this notice.
-	// Lines whose key appears in suppressKeys are skipped: the action proved that
-	// the product's add was exact (server total == expected total), so any
-	// quantity difference on those lines is an intentional add result, not a
-	// server-initiated change. Keyed update-item lines and removeCartItem lines
-	// are never in suppressKeys, so their notice behavior is unchanged.
-	const autoUpdatedToNotify = newItems.filter( ( item ) => {
-		if ( ! isCartItem( item ) ) {
-			return false;
-		}
-		if ( suppressKeys.has( item.key ) ) {
-			return false; // The action proved this product's add was exact.
-		}
-		const old = oldItems.find( ( o ) => o.key === item.key );
-		return old && item.quantity !== old.quantity;
-	} );
-	return [
-		...autoDeletedToNotify.map( ( item ) =>
-			// TODO: move the message template to iAPI config.
-			generateInfoNotice(
-				'"%s" was removed from your cart.'.replace( '%s', item.name )
-			)
-		),
-		...autoUpdatedToNotify.map( ( item ) =>
-			// TODO: move the message template to iAPI config.
-			generateInfoNotice(
-				'The quantity of "%1$s" was changed to %2$d.'
-					.replace( '%1$s', item.name )
-					.replace( '%2$d', item.quantity.toString() )
-			)
-		),
-	];
-};
-
 let pendingRefresh = false;
 let refreshTimeout = 3000;
 let resolveNonceReady: ( () => void ) | null = null;
@@ -1245,67 +967,6 @@ const { actions } = store< Store >(
 					yield cartQueue.waitForIdle();
 				}
 			},
-
-			*showNoticeError(
-				error: Error | ApiErrorResponse
-			): AsyncAction< void > {
-				// Todo: Use the module exports instead of `store()` once the store-notices
-				// store is public.
-				yield import( '@woocommerce/stores/store-notices' );
-				const { actions: noticeActions } = store< StoreNotices >(
-					'woocommerce/store-notices',
-					{},
-					{
-						lock: 'I acknowledge that using a private store means my plugin will inevitably break on the next store release.',
-					}
-				);
-
-				const { code, message } = error as ApiErrorResponse;
-
-				const userFriendlyMessage =
-					state.errorMessages?.[ code ] || message;
-
-				// Todo: Check what should happen if the notice is already displayed.
-				noticeActions.addNotice( {
-					notice: userFriendlyMessage,
-					type: 'error',
-					dismissible: true,
-				} );
-
-				// Emits console.error for troubleshooting.
-				// eslint-disable-next-line no-console
-				console.error( error );
-			},
-
-			*updateNotices(
-				newNotices: Notice[] = [],
-				removeOthers = false
-			): AsyncAction< void > {
-				// Todo: Use the module exports instead of `store()` once the store-notices
-				// store is public.
-				yield import( '@woocommerce/stores/store-notices' );
-				const { state: noticeState, actions: noticeActions } =
-					store< StoreNotices >(
-						'woocommerce/store-notices',
-						{},
-						{
-							lock: 'I acknowledge that using a private store means my plugin will inevitably break on the next store release.',
-						}
-					);
-
-				// Todo: Check what should happen if the notice is already displayed.
-				const noticeIds = newNotices.map( ( notice ) =>
-					noticeActions.addNotice( notice )
-				);
-
-				const { notices } = noticeState;
-				if ( removeOthers ) {
-					notices
-						.map( ( { id } ) => id )
-						.filter( ( id ) => ! noticeIds.includes( id ) )
-						.forEach( ( id ) => noticeActions.removeNotice( id ) );
-				}
-			},
 		},
 	},
 	{ lock: universalLock }
diff --git a/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/legacy-events.ts b/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/cart/legacy-events.ts
similarity index 100%
rename from plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/legacy-events.ts
rename to plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/cart/legacy-events.ts
diff --git a/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/mutation-batcher.ts b/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/cart/mutation-batcher.ts
similarity index 100%
rename from plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/mutation-batcher.ts
rename to plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/cart/mutation-batcher.ts
diff --git a/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/cart/notices.ts b/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/cart/notices.ts
new file mode 100644
index 00000000000..d2def66a60a
--- /dev/null
+++ b/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/cart/notices.ts
@@ -0,0 +1,250 @@
+/**
+ * External dependencies
+ */
+import { store } from '@wordpress/interactivity';
+import type { AsyncAction } from '@wordpress/interactivity';
+import type {
+	Cart,
+	CartVariationItem,
+	ApiErrorResponse,
+} from '@woocommerce/types';
+import type {
+	Store as StoreNotices,
+	Notice,
+} from '@woocommerce/stores/store-notices';
+
+/**
+ * Internal dependencies
+ */
+import type { SelectedAttributes } from '../types';
+import type { Store } from './types';
+import { isCartItem, lineMatchesProduct } from './utils';
+
+export const generateErrorNotice = (
+	error: Error | ApiErrorResponse
+): Notice => ( {
+	notice: error.message,
+	type: 'error',
+	dismissible: true,
+} );
+
+const generateInfoNotice = ( message: string ): Notice => ( {
+	notice: message,
+	type: 'notice',
+	dismissible: true,
+} );
+
+/**
+ * Builds a `Set` of pre-existing cart-line keys to suppress from the
+ * "quantity changed" auto-update notice after a successful keyless add.
+ *
+ * For each product entry in `products`, computes:
+ *   - `serverTotal` = sum of the committed server cart's lines matching that
+ *     product (using the same matcher as `findItemInCart`).
+ *   - `expectedTotal` = pre-add total + sum of posted deltas.
+ *
+ * When `serverTotal === expectedTotal`, the add was exact for that product
+ * (no server-initiated cap, redistribution, or concurrent change), so every
+ * pre-existing line key captured for that product is added to the returned
+ * set and will be skipped in the auto-UPDATE notice diff.
+ *
+ * When the totals diverge, the product's keys are left out of the set and
+ * the diff fires normally, reporting the server's actual quantity.
+ *
+ * Only keyless adds should call this helper. Keyed `update-item` changes
+ * must never populate `products`; leaving their line keys out of the
+ * suppression set ensures the "your change was undone" notice keeps firing.
+ *
+ * @param products   Per-product capture records, one per added product.
+ * @param serverCart The committed server cart to sum against.
+ * @return The flat set of pre-existing line keys to suppress.
+ */
+export function computeKeylessAddSuppressKeys(
+	products: Array< {
+		/** The product id used for matching. */
+		id: number;
+		/** The variation attributes used for matching, if any. */
+		variation?: CartVariationItem[] | SelectedAttributes[] | undefined;
+		/** Sum of all pre-add quantities across matching lines, captured before the optimistic bump. */
+		preAddTotal: number;
+		/** Sum of all posted deltas for this product in this add cycle. */
+		deltaTotal: number;
+		/** The pre-existing cart-line keys belonging to this product, captured before the optimistic bump. */
+		preExistingKeys: string[];
+	} >,
+	serverCart: Cart
+): Set< string > {
+	const suppressKeys = new Set< string >();
+	for ( const product of products ) {
+		const serverTotal = serverCart.items
+			.filter( ( item ) =>
+				lineMatchesProduct( item, product.id, product.variation )
+			)
+			.reduce( ( sum, item ) => sum + item.quantity, 0 );
+		const expectedTotal = product.preAddTotal + product.deltaTotal;
+		if ( serverTotal === expectedTotal ) {
+			for ( const key of product.preExistingKeys ) {
+				suppressKeys.add( key );
+			}
+		}
+	}
+	return suppressKeys;
+}
+
+/**
+ * Derives the auto-update and auto-removal info notices from the diff between
+ * the post-optimistic cart and the committed server cart.
+ *
+ * Auto-removal notices fire for lines present in `oldCart` that the server
+ * dropped entirely (stock removal, product deletion, etc.). Because
+ * `oldCart` is the post-optimistic snapshot, user-initiated removals are
+ * already absent and do not produce spurious notices.
+ *
+ * Auto-update notices fire for server lines whose quantity differs from the
+ * post-optimistic snapshot, with one suppression rule: any line whose key
+ * appears in `suppressKeys` is skipped unconditionally. The action populates
+ * `suppressKeys` with the pre-existing keys of products whose keyless add was
+ * exact (server total == pre-add total + posted delta), so a successful keyless
+ * add never emits a spurious "quantity changed" notice regardless of which
+ * server line received the delta. Genuine server changes (cap, clamp, concurrent
+ * mutation) still notify because they make the per-product totals diverge and
+ * the keys are left out of the set.
+ *
+ * Keyed `update-item` changes and `removeCartItem` never populate
+ * `suppressKeys` (the parameter defaults to an empty set), so their notice
+ * behavior is byte-for-byte unchanged.
+ *
+ * @param oldCart      The post-optimistic cart snapshot used as the diff baseline.
+ * @param newCart      The committed server cart to diff against.
+ * @param suppressKeys Keys of pre-existing lines whose product's add was exact;
+ *                     these lines are skipped in the auto-UPDATE filter.
+ * @return The list of info notices to surface to the shopper.
+ */
+export const getInfoNoticesFromCartUpdates = (
+	oldCart: Store[ 'state' ][ 'cart' ],
+	newCart: Cart,
+	suppressKeys: Set< string > = new Set()
+): Notice[] => {
+	const oldItems = oldCart.items;
+	const newItems = newCart.items;
+
+	// Items auto-removed by the server (stock change, product deleted, etc.).
+	// We pass the optimistic snapshot as oldCart, so user-initiated removals
+	// are already absent and do not generate spurious notices here.
+	// Filtering on the `isCartItem` type guard first (rather than folding it
+	// into a single predicate) narrows the result to `CartItem[]`, so `.name`
+	// below type-checks without a cast.
+	const autoDeletedToNotify = oldItems
+		.filter( isCartItem )
+		.filter(
+			( old ) => ! newItems.some( ( item ) => old.key === item.key )
+		);
+
+	// Items whose quantity was adjusted by the server (stock cap, sold-individually).
+	// By default a line is compared optimistic → server, so intentional user
+	// changes are already reflected in oldItems and do not trigger this notice.
+	// Lines whose key appears in suppressKeys are skipped: the action proved that
+	// the product's add was exact (server total == expected total), so any
+	// quantity difference on those lines is an intentional add result, not a
+	// server-initiated change. Keyed update-item lines and removeCartItem lines
+	// are never in suppressKeys, so their notice behavior is unchanged.
+	const autoUpdatedToNotify = newItems.filter( ( item ) => {
+		if ( ! isCartItem( item ) ) {
+			return false;
+		}
+		if ( suppressKeys.has( item.key ) ) {
+			return false; // The action proved this product's add was exact.
+		}
+		const old = oldItems.find( ( o ) => o.key === item.key );
+		return old && item.quantity !== old.quantity;
+	} );
+	return [
+		...autoDeletedToNotify.map( ( item ) =>
+			// TODO: move the message template to iAPI config.
+			generateInfoNotice(
+				'"%s" was removed from your cart.'.replace( '%s', item.name )
+			)
+		),
+		...autoUpdatedToNotify.map( ( item ) =>
+			// TODO: move the message template to iAPI config.
+			generateInfoNotice(
+				'The quantity of "%1$s" was changed to %2$d.'
+					.replace( '%1$s', item.name )
+					.replace( '%2$d', item.quantity.toString() )
+			)
+		),
+	];
+};
+
+// Stores are locked to prevent 3PD usage until the API is stable.
+const universalLock =
+	'I acknowledge that using a private store means my plugin will inevitably break on the next store release.';
+
+const { state } = store< Store >(
+	'woocommerce',
+	{
+		actions: {
+			*showNoticeError(
+				error: Error | ApiErrorResponse
+			): AsyncAction< void > {
+				// Todo: Use the module exports instead of `store()` once the store-notices
+				// store is public.
+				yield import( '@woocommerce/stores/store-notices' );
+				const { actions: noticeActions } = store< StoreNotices >(
+					'woocommerce/store-notices',
+					{},
+					{
+						lock: 'I acknowledge that using a private store means my plugin will inevitably break on the next store release.',
+					}
+				);
+
+				const { code, message } = error as ApiErrorResponse;
+
+				const userFriendlyMessage =
+					state.errorMessages?.[ code ] || message;
+
+				// Todo: Check what should happen if the notice is already displayed.
+				noticeActions.addNotice( {
+					notice: userFriendlyMessage,
+					type: 'error',
+					dismissible: true,
+				} );
+
+				// Emits console.error for troubleshooting.
+				// eslint-disable-next-line no-console
+				console.error( error );
+			},
+
+			*updateNotices(
+				newNotices: Notice[] = [],
+				removeOthers = false
+			): AsyncAction< void > {
+				// Todo: Use the module exports instead of `store()` once the store-notices
+				// store is public.
+				yield import( '@woocommerce/stores/store-notices' );
+				const { state: noticeState, actions: noticeActions } =
+					store< StoreNotices >(
+						'woocommerce/store-notices',
+						{},
+						{
+							lock: 'I acknowledge that using a private store means my plugin will inevitably break on the next store release.',
+						}
+					);
+
+				// Todo: Check what should happen if the notice is already displayed.
+				const noticeIds = newNotices.map( ( notice ) =>
+					noticeActions.addNotice( notice )
+				);
+
+				const { notices } = noticeState;
+				if ( removeOthers ) {
+					notices
+						.map( ( { id } ) => id )
+						.filter( ( id ) => ! noticeIds.includes( id ) )
+						.forEach( ( id ) => noticeActions.removeNotice( id ) );
+				}
+			},
+		},
+	},
+	{ lock: universalLock }
+);
diff --git a/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/test/cart.ts b/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/cart/test/cart.ts
similarity index 98%
rename from plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/test/cart.ts
rename to plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/cart/test/cart.ts
index c65a2f14765..a0e0c5f4d35 100644
--- a/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/test/cart.ts
+++ b/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/cart/test/cart.ts
@@ -9,7 +9,7 @@ import { speak } from '@wordpress/a11y';
 /**
  * Internal dependencies
  */
-import type { Store, OptimisticCartItem, AddCartItemOutcome } from '../cart';
+import type { Store, OptimisticCartItem, AddCartItemOutcome } from '../types';
 import { triggerAddedToCartEvent } from '../legacy-events';

 type MockStore = { state: Store[ 'state' ]; actions: Store[ 'actions' ] };
@@ -19,26 +19,36 @@ const mockState = {
 	restUrl: 'https://example.com/wp-json/',
 	nonce: 'test-nonce-123',
 } as Store[ 'state' ];
+const mockActions = {} as Store[ 'actions' ];

 jest.mock(
 	'@wordpress/interactivity',
 	() => ( {
 		getConfig: jest.fn(),
 		store: jest.fn( ( _name, definition ) => {
-			// The cart store calls `store()` twice: once to read `state` and
-			// once to register `actions`. Merge the definition's `state`
-			// descriptors (e.g. the `findItemInCart` selector) onto the shared
-			// mock state so the real selector runs against seeded cart lines,
-			// and carry the action generators through both calls.
+			// The `woocommerce` store is assembled from several `store()`
+			// calls, one per file, which the library merges into one store.
+			// Mirror that: merge each call's `state` descriptors (e.g. the
+			// `findItemInCart` selector) onto the shared mock state so the real
+			// selector runs against seeded cart lines, and merge each call's
+			// `actions` into one object that every call returns. Actions
+			// registered by one file are then reachable from the others, and a
+			// spy assigned to the object replaces the action for all of them.
 			if ( definition?.state ) {
 				Object.defineProperties(
 					mockState,
 					Object.getOwnPropertyDescriptors( definition.state )
 				);
 			}
+			if ( definition?.actions ) {
+				Object.defineProperties(
+					mockActions,
+					Object.getOwnPropertyDescriptors( definition.actions )
+				);
+			}
 			mockRegisteredStore = {
 				state: mockState,
-				actions: definition?.actions ?? mockRegisteredStore?.actions,
+				actions: mockActions,
 			} as MockStore;
 			return mockRegisteredStore;
 		} ),
@@ -157,7 +167,7 @@ function mockBatchFetch(): CapturedRequest[] {
  * @return A promise resolving to the freshly registered cart store actions.
  */
 async function loadCartStore(): Promise< Store[ 'actions' ] > {
-	jest.isolateModules( () => require( '../cart' ) );
+	jest.isolateModules( () => require( '../../index' ) );
 	const actions = mockRegisteredStore?.actions as Store[ 'actions' ];
 	// Drive the refresh so the module-level nonce-ready promise resolves.
 	await runAction( actions.refreshCartItems() );
@@ -580,7 +590,7 @@ describe( 'WooCommerce Cart Interactivity API Store', () => {
 			);
 		global.fetch = mockFetch;

-		jest.isolateModules( () => require( '../cart' ) );
+		jest.isolateModules( () => require( '../../index' ) );

 		const iterator = mockRegisteredStore?.actions.refreshCartItems();

@@ -608,7 +618,7 @@ describe( 'WooCommerce Cart Interactivity API Store', () => {
 			const mockFetch = jest.fn();
 			global.fetch = mockFetch;

-			jest.isolateModules( () => require( '../cart' ) );
+			jest.isolateModules( () => require( '../../index' ) );
 			await runAction( mockRegisteredStore?.actions.refreshCartItems() );

 			expect( mockFetch ).not.toHaveBeenCalled();
@@ -620,7 +630,7 @@ describe( 'WooCommerce Cart Interactivity API Store', () => {
 				.fn()
 				.mockRejectedValue( new TypeError( 'Failed to fetch' ) );

-			jest.isolateModules( () => require( '../cart' ) );
+			jest.isolateModules( () => require( '../../index' ) );
 			const actions = mockRegisteredStore?.actions as Store[ 'actions' ];
 			await runAction( actions.refreshCartItems() );
 			seedCart( [] );
diff --git a/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/test/mutation-batcher.test.ts b/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/cart/test/mutation-batcher.test.ts
similarity index 100%
rename from plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/test/mutation-batcher.test.ts
rename to plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/cart/test/mutation-batcher.test.ts
diff --git a/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/cart/types.ts b/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/cart/types.ts
new file mode 100644
index 00000000000..e13d55656df
--- /dev/null
+++ b/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/cart/types.ts
@@ -0,0 +1,100 @@
+/**
+ * External dependencies
+ */
+import type {
+	Cart,
+	CartItem,
+	CartVariationItem,
+	ApiErrorResponse,
+	CartResponseTotals,
+} from '@woocommerce/types';
+import type { Notice } from '@woocommerce/stores/store-notices';
+
+/**
+ * Internal dependencies
+ */
+import type { SelectedAttributes } from '../types';
+
+export type OptimisticCartItem = {
+	key?: string | undefined;
+	id: number;
+	quantity: number;
+	variation?: CartVariationItem[];
+	type: string;
+};
+
+export type ClientCartItem = Omit<
+	OptimisticCartItem,
+	'variation' | 'quantity'
+> & {
+	variation?: SelectedAttributes[];
+	/** The target quantity (absolute). Either this or quantityToAdd must be provided. */
+	quantity?: number;
+	/** Optional: add this delta to current quantity instead of setting absolute quantity */
+	quantityToAdd?: number;
+};
+
+export type CartUpdateOptions = { showCartUpdatesNotices?: boolean };
+
+/**
+ * The failure detail carried by a rejected `AddCartItemOutcome`.
+ */
+export type AddCartItemError = {
+	/**
+	 * Server error code for a per-item rejection (e.g.
+	 * `woocommerce_rest_product_out_of_stock`), or the batcher's
+	 * `unknown_error` fallback. Absent on whole-batch/transport failures.
+	 */
+	code?: string;
+	/** Human-readable failure description. Always non-empty. */
+	message: string;
+};
+
+/**
+ * The per-call outcome `addCartItem` resolves with, captured at the moment
+ * its own request settles (accepted or rejected). A later throw in
+ * post-success processing (notices) never downgrades an already-captured
+ * success into a failure.
+ */
+export type AddCartItemOutcome =
+	{ success: true } | { success: false; error: AddCartItemError };
+
+export type Store = {
+	state: {
+		errorMessages?: {
+			[ key: string ]: string;
+		};
+		restUrl: string;
+		nonce: string;
+		// Whether a cart update request is in progress.
+		isCartUpdating?: boolean;
+		findItemInCart: ( args: {
+			id: ClientCartItem[ 'id' ];
+			key?: ClientCartItem[ 'key' ];
+			variation?: ClientCartItem[ 'variation' ];
+		} ) => CartItem | OptimisticCartItem | undefined;
+		cart: Omit< Cart, 'items' > & {
+			items: ( OptimisticCartItem | CartItem )[];
+			totals: CartResponseTotals;
+		};
+	};
+	actions: {
+		removeCartItem: ( key: string ) => Promise< void >;
+		addCartItem: (
+			args: ClientCartItem,
+			options?: CartUpdateOptions
+		) => Promise< AddCartItemOutcome >;
+		batchAddCartItems: (
+			items: ClientCartItem[],
+			options?: CartUpdateOptions
+		) => Promise< void >;
+		// Todo: Check why if I switch to an async function here the types of the store stop working.
+		refreshCartItems: () => Promise< void >;
+		waitForIdle: () => Promise< void >;
+		showNoticeError: ( error: Error | ApiErrorResponse ) => Promise< void >;
+		updateNotices: (
+			notices: Notice[],
+			removeOthers?: boolean
+		) => Promise< void >;
+	};
+};
diff --git a/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/cart/utils.ts b/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/cart/utils.ts
new file mode 100644
index 00000000000..d726c2b339d
--- /dev/null
+++ b/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/cart/utils.ts
@@ -0,0 +1,49 @@
+/**
+ * External dependencies
+ */
+import type { CartItem, CartVariationItem } from '@woocommerce/types';
+
+/**
+ * Internal dependencies
+ */
+import type { SelectedAttributes } from '../types';
+import type { OptimisticCartItem } from './types';
+import { doesCartItemMatchAttributes } from '../../../utils/variations/does-cart-item-match-attributes';
+
+// Guard to distinguish between optimistic and cart items.
+export function isCartItem(
+	item: OptimisticCartItem | CartItem
+): item is CartItem {
+	return 'name' in item;
+}
+
+/**
+ * Returns `true` when the given cart line matches the product identified by
+ * `id` and `variation`, using the same matching logic as `findItemInCart`.
+ *
+ * Simple items match by `id` equality. Variation items additionally require
+ * `variation.length` equality and `doesCartItemMatchAttributes`.
+ *
+ * @param item      The cart line to test.
+ * @param id        The product id to match against.
+ * @param variation The variation attributes to match against, if any.
+ * @return `true` when the line belongs to the specified product.
+ */
+export function lineMatchesProduct(
+	item: OptimisticCartItem | CartItem,
+	id: number,
+	variation?: CartVariationItem[] | SelectedAttributes[]
+): boolean {
+	if ( item.type === 'variation' ) {
+		if (
+			id !== item.id ||
+			! item.variation ||
+			! variation ||
+			item.variation.length !== variation.length
+		) {
+			return false;
+		}
+		return doesCartItemMatchAttributes( item, variation );
+	}
+	return id === item.id;
+}
diff --git a/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/index.ts b/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/index.ts
index ebe93b67668..c973be569c2 100644
--- a/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/index.ts
+++ b/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/index.ts
@@ -1 +1,20 @@
-export type { ProductsStore, ProductsStoreState } from './products';
+/**
+ * Registers the `woocommerce` store.
+ *
+ * Each file below contributes its members to the store through its own
+ * `store( 'woocommerce', … )` call, so loading this module is what assembles
+ * the store. These imports are side-effect-only: they survive production
+ * tree-shaking only because `package.json` lists
+ * `./assets/js/base/stores/woocommerce/**` in `sideEffects`.
+ */
+import './cart/notices';
+import './cart/actions';
+
+export type { WooCommerceConfig, SelectedAttributes } from './types';
+export type {
+	OptimisticCartItem,
+	ClientCartItem,
+	AddCartItemError,
+	AddCartItemOutcome,
+	Store,
+} from './cart/types';
diff --git a/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/types.ts b/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/types.ts
new file mode 100644
index 00000000000..3d4f592d1a1
--- /dev/null
+++ b/plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/types.ts
@@ -0,0 +1,15 @@
+/**
+ * External dependencies
+ */
+import type { CartVariationItem, Currency } from '@woocommerce/types';
+
+export type WooCommerceConfig = {
+	messages?: {
+		addedToCartText?: string;
+	};
+	placeholderImgSrc?: string;
+	currency?: Currency;
+	nonOptimisticProperties?: string[];
+};
+
+export type SelectedAttributes = Omit< CartVariationItem, 'raw_attribute' >;
diff --git a/plugins/woocommerce/client/blocks/assets/js/blocks/mini-cart/frontend.ts b/plugins/woocommerce/client/blocks/assets/js/blocks/mini-cart/frontend.ts
index dcd77af6d26..a75286d5a9c 100644
--- a/plugins/woocommerce/client/blocks/assets/js/blocks/mini-cart/frontend.ts
+++ b/plugins/woocommerce/client/blocks/assets/js/blocks/mini-cart/frontend.ts
@@ -26,7 +26,7 @@ import {
  */
 import type { CartItem, Currency } from '@woocommerce/types';
 import { getFocusableElements } from '../../utils/get-focusable-elements';
-import { translateJQueryEventToNative } from '../../base/stores/woocommerce/legacy-events';
+import { translateJQueryEventToNative } from '../../base/stores/woocommerce/cart/legacy-events';
 import {
 	isItemDataEntryVisible,
 	isLastVisibleEntry,
diff --git a/plugins/woocommerce/client/blocks/bin/webpack-config-interactive-blocks.js b/plugins/woocommerce/client/blocks/bin/webpack-config-interactive-blocks.js
index 5bdb4189ec1..2f25a91db42 100644
--- a/plugins/woocommerce/client/blocks/bin/webpack-config-interactive-blocks.js
+++ b/plugins/woocommerce/client/blocks/bin/webpack-config-interactive-blocks.js
@@ -57,13 +57,13 @@ const entries = {
 		'./assets/js/blocks/product-collection/cart-reference-frontend.ts',
 	// Other
 	'@woocommerce/stores/woocommerce':
-		'./assets/js/base/stores/woocommerce/cart.ts',
+		'./assets/js/base/stores/woocommerce/index.ts',
 	'@woocommerce/stores/store-notices':
 		'./assets/js/base/stores/store-notices.ts',
 	'@woocommerce/stores/woocommerce/products':
-		'./assets/js/base/stores/woocommerce/products.ts',
+		'./assets/js/base/stores/products.ts',
 	'@woocommerce/stores/woocommerce/shopper-lists':
-		'./assets/js/base/stores/woocommerce/shopper-lists.ts',
+		'./assets/js/base/stores/shopper-lists.ts',
 };

 module.exports = {
diff --git a/plugins/woocommerce/client/blocks/package.json b/plugins/woocommerce/client/blocks/package.json
index 278ea089045..517c5f512c4 100644
--- a/plugins/woocommerce/client/blocks/package.json
+++ b/plugins/woocommerce/client/blocks/package.json
@@ -30,6 +30,7 @@
 		"./assets/js/blocks/cart/inner-blocks/register-components.ts",
 		"./assets/js/blocks/mini-cart/mini-cart-contents/inner-blocks/**/index.tsx",
 		"./assets/js/base/components/**/*.{tsx,ts}",
+		"./assets/js/base/stores/woocommerce/**",
 		"./assets/js/blocks/cart-checkout-shared/sidebar-notices/index.tsx",
 		"./assets/js/blocks/cart-checkout-shared/view-switcher/index.tsx",
 		"./assets/js/blocks/filter-wrapper/register-components.ts",
diff --git a/plugins/woocommerce/client/blocks/tests/js/jest.config.js b/plugins/woocommerce/client/blocks/tests/js/jest.config.js
index 149ac54f6b1..3e8fab394d9 100644
--- a/plugins/woocommerce/client/blocks/tests/js/jest.config.js
+++ b/plugins/woocommerce/client/blocks/tests/js/jest.config.js
@@ -107,7 +107,11 @@ module.exports = {
 		'^@woocommerce/entities/(.*)$': 'packages/internal/entities/$1',
 		'^@woocommerce/entities$': 'packages/internal/entities',
 		'^@woocommerce/stores/woocommerce$':
-			'assets/js/base/stores/woocommerce/cart',
+			'assets/js/base/stores/woocommerce/index',
+		'^@woocommerce/stores/woocommerce/products$':
+			'assets/js/base/stores/products',
+		'^@woocommerce/stores/woocommerce/shopper-lists$':
+			'assets/js/base/stores/shopper-lists',
 		'@woocommerce/stores/(.*)$': 'assets/js/base/stores/$1',
 		'^react$': '<rootDir>/node_modules/react',
 		'^react-dom$': '<rootDir>/node_modules/react-dom',
diff --git a/plugins/woocommerce/client/blocks/tsconfig.base.json b/plugins/woocommerce/client/blocks/tsconfig.base.json
index 777daf86990..90e8b715ae2 100644
--- a/plugins/woocommerce/client/blocks/tsconfig.base.json
+++ b/plugins/woocommerce/client/blocks/tsconfig.base.json
@@ -149,13 +149,13 @@
 				"assets/js/base/stores/store-notices"
 			],
 			"@woocommerce/stores/woocommerce": [
-				"assets/js/base/stores/woocommerce/cart"
+				"assets/js/base/stores/woocommerce/index"
 			],
 			"@woocommerce/stores/woocommerce/products": [
-				"assets/js/base/stores/woocommerce/products"
+				"assets/js/base/stores/products"
 			],
 			"@woocommerce/stores/woocommerce/shopper-lists": [
-				"assets/js/base/stores/woocommerce/shopper-lists"
+				"assets/js/base/stores/shopper-lists"
 			],
 			"@woocommerce/type-defs/*": [
 				"packages/public-api/types/type-defs/*"
diff --git a/plugins/woocommerce/includes/wc-interactivity-api-functions.php b/plugins/woocommerce/includes/wc-interactivity-api-functions.php
index ae9cc51b1fb..2164e25bd54 100644
--- a/plugins/woocommerce/includes/wc-interactivity-api-functions.php
+++ b/plugins/woocommerce/includes/wc-interactivity-api-functions.php
@@ -21,7 +21,7 @@ if ( ! defined( 'ABSPATH' ) ) {
  *
  * This is an experimental API and may change in future versions.
  *
- * @see plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/README.md
+ * @see plugins/woocommerce/client/blocks/assets/js/base/stores/README.md
  *
  * @param string $consent_statement The consent statement acknowledging this is an experimental API.
  * @param int    $product_id        The product ID to load.
@@ -37,7 +37,7 @@ function wc_interactivity_api_load_product( string $consent_statement, int $prod
  *
  * This is an experimental API and may change in future versions.
  *
- * @see plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/README.md
+ * @see plugins/woocommerce/client/blocks/assets/js/base/stores/README.md
  *
  * @param string $consent_statement The consent statement acknowledging this is an experimental API.
  * @param int    $parent_id         The parent product ID.
@@ -53,7 +53,7 @@ function wc_interactivity_api_load_purchasable_child_products( string $consent_s
  *
  * This is an experimental API and may change in future versions.
  *
- * @see plugins/woocommerce/client/blocks/assets/js/base/stores/woocommerce/README.md
+ * @see plugins/woocommerce/client/blocks/assets/js/base/stores/README.md
  *
  * @param string $consent_statement The consent statement acknowledging this is an experimental API.
  * @param int    $parent_id         The parent product ID.
diff --git a/plugins/woocommerce/src/Blocks/SharedStores/ProductsStore.php b/plugins/woocommerce/src/Blocks/SharedStores/ProductsStore.php
index 709bd69abb4..c58706780f2 100644
--- a/plugins/woocommerce/src/Blocks/SharedStores/ProductsStore.php
+++ b/plugins/woocommerce/src/Blocks/SharedStores/ProductsStore.php
@@ -21,11 +21,11 @@ use InvalidArgumentException;
  *   `register_getters()`.
  *
  * The derived getters are mirrored in the JS store
- * (client/blocks/assets/js/base/stores/woocommerce/products.ts) so that
+ * (client/blocks/assets/js/base/stores/products.ts) so that
  * directive bindings like `state.productInContext.sku` resolve during
  * server-side rendering as well as on the client.
  *
- * See client/blocks/assets/js/base/stores/woocommerce/README.md for the
+ * See client/blocks/assets/js/base/stores/README.md for the
  * full model and consumer examples.
  *
  * This is an experimental API and may change in future versions.
@@ -93,7 +93,7 @@ class ProductsStore {
 	 * Register the derived-state getters once.
 	 *
 	 * These closures mirror the JS getters in
-	 * client/blocks/assets/js/base/stores/woocommerce/products.ts so that
+	 * client/blocks/assets/js/base/stores/products.ts so that
 	 * directives referencing state.mainProductInContext /
 	 * state.productVariationInContext / state.productInContext resolve
 	 * during SSR. Because they read from
diff --git a/plugins/woocommerce/tests/e2e/tests/blocks/cart-store/mutation-batcher.block_theme.spec.ts b/plugins/woocommerce/tests/e2e/tests/blocks/cart-store/mutation-batcher.block_theme.spec.ts
index ef523a9905c..f509d6d809d 100644
--- a/plugins/woocommerce/tests/e2e/tests/blocks/cart-store/mutation-batcher.block_theme.spec.ts
+++ b/plugins/woocommerce/tests/e2e/tests/blocks/cart-store/mutation-batcher.block_theme.spec.ts
@@ -3,7 +3,7 @@
  *
  * Request grouping, state reconciliation and the per-cycle cross-cutting
  * effects are covered by Jest unit tests in
- * `client/blocks/assets/js/base/stores/woocommerce/test/`. What is left here
+ * `client/blocks/assets/js/base/stores/woocommerce/cart/test/`. What is left here
  * is the one behaviour those cannot reach: a real Interactivity API rollback
  * repainting rendered block markup after a whole batch fails.
  */
diff --git a/plugins/woocommerce/tests/e2e/tsconfig.json b/plugins/woocommerce/tests/e2e/tsconfig.json
index e0f1431cea1..2aa95cc20b4 100644
--- a/plugins/woocommerce/tests/e2e/tsconfig.json
+++ b/plugins/woocommerce/tests/e2e/tsconfig.json
@@ -8,7 +8,7 @@
 		"paths": {
 			"@woocommerce/e2e-utils": [ "./utils/blocks" ],
 			"@woocommerce/stores/woocommerce": [
-				"../../client/blocks/assets/js/base/stores/woocommerce/cart"
+				"../../client/blocks/assets/js/base/stores/woocommerce/index"
 			]
 		},
 		"esModuleInterop": true,