Permission API updates

files/en-us/web/api/permissions/query/index.md

@@ -10,6 +10,10 @@ browser-compat: api.Permissions.query
 
 The **`query()`** method of the {{domxref("Permissions")}} interface returns the state of a user permission on the global scope.
 
+The permissions supported by each browser versions are listed in the [compatibility data of the `Permissions` interface](/en-US/docs/Web/API/Permissions#browser_compatibility) (see also the relevant source code for [Firefox values](https://searchfox.org/mozilla-central/source/dom/webidl/Permissions.webidl#10), [Chromium values](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/third_party/blink/renderer/modules/permissions/permission_descriptor.idl), and [WebKit values](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/Modules/permissions/PermissionName.idl)).
+
+The APIs that are gated by each permission are listed in [Permission-aware APIs](/en-US/docs/Web/API/Permissions_API#permission-aware_apis) in the [Permissions API](/en-US/docs/Web/API/Permissions_API) overview topic.
+
 ## Syntax
 
 ```js-nolint
@@ -20,20 +24,26 @@ query(permissionDescriptor)
 
 - `permissionDescriptor`
 
-  - : An object that sets options for the `query` operation consisting of a comma-separated list of name-value pairs. The available options are:
+  - : An object that sets options for the `query` operation.
+    The available options for this descriptor depend on the permission type.
+
+    All permissions have a name:
 
     - `name`
-      - : The name of the API whose permissions you want to query. Each browser supports a different set of values. You'll find Firefox values [there](https://searchfox.org/mozilla-central/source/dom/webidl/Permissions.webidl#10), Chromium values [there](https://chromium.googlesource.com/chromium/src/+/refs/heads/main/third_party/blink/renderer/modules/permissions/permission_descriptor.idl), and WebKit values [there](https://github.com/WebKit/WebKit/blob/main/Source/WebCore/Modules/permissions/PermissionName.idl).
-    - `userVisibleOnly`
-      - : (Push only, not supported in Firefox — see the Browser Support section below) Indicates whether you want to show a notification for every message or be able to send silent push notifications. The default is `false`.
-    - `sysex` (MIDI only)
-      - : Indicates whether you need and/or receive system exclusive messages. The default is `false`.
+      - : A string containing the name of the API whose permissions you want to query.
+        The returned {{jsxref("Promise")}} will reject with a {{jsxref("TypeError")}} if the permission name is not supported by the browser.
+
+    For the `push` permissions you can also specify:
+
+    - `userVisibleOnly` {{optional_inline}}
+      - : (Push only, not supported in Firefox — see the Browser Support section below) Indicates whether you want to show a notification for every message or be able to send silent push notifications.
+        The default is `false`.
 
-> [!NOTE]
-> As of Firefox 44, the permissions for [Notifications](/en-US/docs/Web/API/Notifications_API) and [Push](/en-US/docs/Web/API/Push_API) have been merged. If permission is granted (e.g. by the user, in the relevant permissions dialog), `navigator.permissions.query()` will return `true` for both `notifications` and `push`.
+    For the `midi` permission you can also specify:
 
-> [!NOTE]
-> The `persistent-storage` permission allows an origin to use a persistent box (i.e., [persistent storage](https://storage.spec.whatwg.org/#persistence)) for its storage, as per the [Storage API](https://storage.spec.whatwg.org/).
+    - `sysex` {{optional_inline}}
+      - : Indicates whether you need and/or receive system exclusive messages.
+        The default is `false`.
 
 ### Return value
 

files/en-us/web/api/permissions_api/index.md

@@ -11,9 +11,10 @@ spec-urls: https://w3c.github.io/permissions/
 
 {{DefaultAPISidebar("Permissions API")}}{{AvailableInWorkers}}
 
-The **Permissions API** provides a consistent programmatic way to query the status of API permissions attributed to the current context. For example, the Permissions API can be used to determine if permission to access a particular API has been granted or denied, or requires specific user permission.
+The **Permissions API** provides a consistent programmatic way to query the status of API permissions attributed to the current context.
+For example, it can be used to determine if permission to access a particular feature or API has been granted, denied, or requires specific user permission.
 
-Note that the permissions from this API effectively aggregate all security restrictions for the context, including any requirement for an API to be used in a secure context, [Permissions-Policy](/en-US/docs/Web/HTTP/Headers/Permissions-Policy) restrictions applied to the document, and user prompts.
+The permissions from this API effectively aggregate all security restrictions for the context, including any requirement for an API to be used in a secure context, [Permissions-Policy](/en-US/docs/Web/HTTP/Headers/Permissions-Policy) restrictions applied to the document, and user prompts.
 So, for example, if an API is restricted by permissions policy, the returned permission would be `denied` and the user would not be prompted for access.
 
 ## Concepts and usage
@@ -46,12 +47,6 @@ A non-exhaustive list of permission-aware APIs includes:
 - [Web MIDI API](/en-US/docs/Web/API/Web_MIDI_API): `midi`
 - [Window Management API](/en-US/docs/Web/API/Window_Management_API): `window-management`
 
-## Examples
-
-We have created a simple example called Location Finder. You can [run the example live](https://chrisdavidmills.github.io/location-finder-permissions-api/), or [view the source code on GitHub](https://github.com/chrisdavidmills/location-finder-permissions-api/tree/gh-pages).
-
-Read more about how it works in our article [Using the Permissions API](/en-US/docs/Web/API/Permissions_API/Using_the_Permissions_API).
-
 ## Interfaces
 
 - {{domxref("Permissions")}}
@@ -64,6 +59,12 @@ Read more about how it works in our article [Using the Permissions API](/en-US/d
 - {{domxref("Navigator.permissions")}} and {{domxref("WorkerNavigator.permissions")}} {{ReadOnlyInline}}
   - : Provides access to the {{domxref("Permissions")}} object from the main context and worker context respectively.
 
+## Examples
+
+We have created a simple example called Location Finder. You can [run the example live](https://chrisdavidmills.github.io/location-finder-permissions-api/), or [view the source code on GitHub](https://github.com/chrisdavidmills/location-finder-permissions-api/tree/gh-pages).
+
+Read more about how it works in our article [Using the Permissions API](/en-US/docs/Web/API/Permissions_API/Using_the_Permissions_API).
+
 ## Specifications
 
 {{Specifications}}

files/en-us/web/api/permissions_api/using_the_permissions_api/index.md

@@ -2,13 +2,11 @@
 title: Using the Permissions API
 slug: Web/API/Permissions_API/Using_the_Permissions_API
 page-type: guide
-status:
-  - experimental
 ---
 
 {{DefaultAPISidebar("Permissions API")}}
 
-This article provides a basic guide to using the W3C [Permissions API](/en-US/docs/Web/API/Permissions_API), which provides a programmatic way to query the status of API permissions attributed to the current context.
+This article provides a basic guide to using the [Permissions API](/en-US/docs/Web/API/Permissions_API), which provides a programmatic way to query the status of API permissions attributed to the current context.
 
 ## The trouble with asking for permission…
 
@@ -90,7 +88,7 @@ You'll notice that we're listening to the {{domxref("PermissionStatus.change_eve
 
 At the moment this doesn't offer much more than what we had already. If we choose to never share our location from the permission prompt (deny permission), then we can't get back to the permission prompt without using the browser menu options:
 
-- **Firefox**: _Tools > Page Info > Permissions > Access Your Location_. Select _Always Ask_.
+- **Firefox**: _Hamburger Menu > Settings > Privacy & Security > Permissions_ (then select the **Settings** button for the permission of interest).
 - **Chrome**: _Hamburger Menu > Settings > Show advanced settings_. In the _Privacy_ section, click _Content Settings_. In the resulting dialog, find the _Location_ section and select _Ask when a site tries to…_. Finally, click _Manage Exceptions_ and remove the permissions you granted to the sites you are interested in.
 
 There are proposals to add the ability for sites to imperatively [request](https://github.com/WICG/permissions-request) and [revoke](https://github.com/WICG/permissions-revoke) permissions, but there has not been much progress as the use case is unclear and they have faced opposition from browser vendors. See the discussions to [remove `permissions.request()`](https://github.com/w3c/permissions/issues/83) and [remove `permissions.revoke()`](https://github.com/w3c/permissions/issues/46) from the main specification.