docs: document contextMenus alongside menus in WebExtensions API (#46240)

files/en-us/mozilla/add-ons/webextensions/api/menus/create/index.md

@@ -10,7 +10,7 @@ Creates a menu item using an options object defining properties for the item.
 
 Unlike other asynchronous functions, this one does not return a promise, but uses an optional callback to communicate success or failure. This is because its return value is the ID of the new item.
 
-For compatibility with other browsers, Firefox makes this method available in the `contextMenus` namespace and `menus` namespace.
+This page documents the `menus.create()` method, which is also available as `contextMenus.create()` in Firefox. For information about the relationship between these namespaces, their permissions, and their browser support, see [Namespace compatibility](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/menus#namespace-compatibility).
 
 > **Creating menus in persistent and non-persistent extensions**
 >
@@ -121,7 +121,12 @@ browser.menus.create(
 
 ## Examples
 
-This example creates a context menu item that's shown when the user has selected some text in the page. It just logs the selected text to the console:
+The following examples in the [webextensions-examples repository](https://github.com/mdn/webextensions-examples) use the `contextMenus` namespace:
+
+- [context-menu-copy-link-with-types](https://github.com/mdn/webextensions-examples/tree/main/context-menu-copy-link-with-types) adds a context menu item to links that copies the link URL to the clipboard as plain text or rich HTML.
+- [store-collected-images](https://github.com/mdn/webextensions-examples/tree/main/store-collected-images) demonstrates collecting and storing images using context menu items.
+
+This example creates a context menu item that's shown when the user has selected some text in the page. It logs the selected text to the console:
 
 ```js
 browser.menus.create({

files/en-us/mozilla/add-ons/webextensions/api/menus/index.md

@@ -8,13 +8,20 @@ sidebar: addonsidebar
 
 Add items to the browser's menu system.
 
-This API is modeled on Chrome's ["contextMenus"](https://developer.chrome.com/docs/extensions/reference/api/contextMenus) API, which enables Chrome extensions to add items to the browser's context menu. The `browser.menus` API adds a few features to Chrome's API.
+This API is modeled on Chrome's [`contextMenus`](https://developer.chrome.com/docs/extensions/reference/api/contextMenus) API, which enables extensions to add items to the browser's context menu. The `menus` API also provides additional functionality.
 
-Before Firefox 55 this API was also originally named `contextMenus`, and that name has been retained as an alias, so you can use `contextMenus` to write code that works in Firefox and also in other browsers.
+## Namespace compatibility
 
-To use this API you need to have the `menus` [permission](/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json/permissions). You may also use the `contextMenus` alias instead of `menus`, but if you do, the APIs must be accessed as `browser.contextMenus` instead.
+This API is available through the `menus` and `contextMenus` namespaces. The namespaces expose the same API unless otherwise stated, but their availability and required permissions vary by browser.
 
-Except for [`menus.getTargetElement()`](/en-US/docs/Mozilla/Add-ons/WebExtensions/API/menus/getTargetElement), this API cannot be used from content scripts.
+- The `menus` namespace, used with the `menus` permission, is supported in Firefox and Safari.
+- The `contextMenus` namespace, used with the `contextMenus` permission, is supported across browsers, including Firefox.
+
+In Firefox, `contextMenus` is an alias for `menus`. Most methods, events, and types documented on this page are available through either namespace. Exceptions are documented on the relevant reference pages.
+
+The `menus.getTargetElement()` method is available in content scripts when the extension has the `menus` permission. The `contextMenus` namespace is not available in content scripts.
+
+The methods, events, and types documented on this page apply to both namespaces unless otherwise stated. For details about browser support and namespace-specific behavior, see the relevant reference page.
 
 ## Creating menu items
 

files/en-us/mozilla/add-ons/webextensions/user_interface/context_menu_items/index.md

@@ -21,16 +21,23 @@ You can also override the context menus displayed in extension pages, such as cu
 
 ## Specifying context menu items
 
-You manage context menu items programmatically, using the {{WebExtAPIRef("contextMenus")}} API. However, you need to request the `contextMenus` permission in your manifest.json to be able to take advantage of the API.
+You manage context menu items programmatically using the `menus` or `contextMenus` namespace. The namespace and permission to use depend on the browser:
+
+- Use the `menus` namespace with the `menus` permission in Firefox and Safari.
+- Use the `contextMenus` namespace with the `contextMenus` permission in browsers that support it.
+
+In Firefox, `contextMenus` is an alias for `menus`. The examples in this guide use the `menus` namespace.
+
+To use the API with the `menus` namespace, request the `menus` permission in your `manifest.json` file:
 
 ```json
-"permissions": ["contextMenus"]
+"permissions": ["menus"]
 ```
 
-You can then add (and update or delete) the context menu items in your extension's background script. To create a menu item you specify an id, its title, and the context menus it should appear on:
+You can then add, update, or delete context menu items in your extension's background script. To create a menu item, specify an ID, a title, and the contexts in which it should appear:
 
 ```js
-browser.contextMenus.create(
+browser.menus.create(
   {
     id: "log-selection",
     title: browser.i18n.getMessage("contextMenuItemSelectionLogger"),
@@ -40,10 +47,10 @@ browser.contextMenus.create(
 );
 ```
 
-Your extension then listens for clicks on the menu items. The passed information about the item clicked, the context where the click happened, and details of the tab where the click took place can then be used to invoke the appropriate extension functionality.
+Your extension can listen for clicks on menu items. The event provides information about the clicked item, the context in which the click occurred, and the tab where it took place. You can use this information to invoke the appropriate extension functionality.
 
 ```js
-browser.contextMenus.onClicked.addListener((info, tab) => {
+browser.menus.onClicked.addListener((info, tab) => {
   switch (info.menuItemId) {
     case "log-selection":
       console.log(info.selectionText);