userScripts documentation fixups

[Rob--W]

Description

• Add WebExtExamples to main userScripts article
• Clarify execution world behavior.
• Remove incorrect note about user script unregistration.
• Add more cross-references, such as a link to "Glob pattern"

Motivation

Fix inaccuracies and improve discovery of relevant information.

Additional details

Related issues and pull requests

Follow-up to #38073.

[github-actions]

Preview URLs

• /en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts/RegisteredUserScript
• /en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts/WorldProperties
• /en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts

(comment last updated: 2025-03-03 21:53:00)

[rebloor]

@Rob--W A couple of suggestions for you to consider.

[rebloor]

Suggested change

	When a user script is registered or updated (using {{WebExtAPIRef("userScripts.register()")}} or {{WebExtAPIRef("userScripts.update()")}}), your extension can set it to run in an isolated `USER_SCRIPT` world or the `MAIN` world.
	A `USER_SCRIPT` world provides an isolated execution environment that isn't accessible to a host page or other extensions. This means a user script can change its JavaScript environment without affecting the host page or other extensions' user and content scripts. In this environment, user scripts aren't visible to the host page or other extensions' user and content scripts. The API also enables an extension to configure a content security policy (CSP) for the `USER_SCRIPT` world using {{WebExtAPIRef("userScripts.configureWorld()")}}.
	User scripts can share the same world, but they can also be isolated from each other by declaring separate `USER_SCRIPT` worlds through the `worldId` property of a {{WebExtAPIRef("userScripts.RegisteredUserScript", "RegisteredUserScript")}}. The API also enables an extension to configure a content security policy (CSP) for the `USER_SCRIPT` world using {{WebExtAPIRef("userScripts.configureWorld()")}}.
	In the `MAIN` world, host pages and other extensions can see and access running user scripts.
	A `USER_SCRIPT` world provides an isolated execution environment that isn't accessible to a host page or other extensions. This means a user script can change its JavaScript environment without affecting the host page or other extensions' user and content scripts. In this environment, user scripts aren't visible to the host page or other extensions' user and content scripts.
	In the `MAIN` world, host pages and other extensions can see and access running user scripts. The `worldId` property is not supported for `MAIN` worlds.
	There are two types of world for your extension to run user scripts in:
	- `MAIN` world. In this world, host pages and other extensions can see and access the running user scripts. There is only one `MAIN` world that can run one or more user script.
	- `USER_SCRIPT` worlds. These are isolated worlds where user scripts aren't visible to the host page or other extensions' user and content scripts. Similarly, user script in one `USER_SCRIPT` world can't see or access user scripts in another `USER_SCRIPT` world. Each `USER_SCRIPT` world can run one or more user scripts.
	`USER_SCRIPT` worlds are created by setting the `worldId` property of {{WebExtAPIRef("userScripts.RegisteredUserScript", "RegisteredUserScript")}} when registering or updating a user script. The API also enables an extension to configure a content security policy (CSP) for a `USER_SCRIPT` world using {{WebExtAPIRef("userScripts.configureWorld()")}}.

[Rob--W]

The "USER_SCRIPT worlds are created by setting the worldId property" bit is inaccurate. What worldId does is allowing for separate/multiple USER_SCRIPT worlds to be specified. It can be omitted to still have the (default) USER_SCRIPT world.

[Rob--W]

The suggested text does not convey the intended meaning; To avoid unnecessary delays in documentation I'm going to merge this PR. Feel free to submit a new PR to improve the wording if you'd like.

[rebloor]

@Rob--W tidy up suggestions only

[rebloor]

Suggested change

	A `USER_SCRIPT` world provides an isolated execution environment that isn't accessible to a host page or other extensions. This means a user script can change its JavaScript environment without affecting the host page or other extensions' user and content scripts. In this environment, user scripts aren't visible to the host page or other extensions' user and content scripts.
	A `USER_SCRIPT` world provides an isolated execution environment that isn't accessible to the host page or other extensions. This means a user script:
	- isn't visible to and
	- can change its JavaScript environment without affecting
	the host page or other extensions' user and content scripts.

[Rob--W]

This proposed text doesn't look very readable, "isn't visible to and" looks strange.

I think that a follow-up improvement could be to just cut most of the text and refer to https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/userScripts/ExecutionWorld instead for a longer description

[rebloor]

I want to avoid readability issues created by two apparently very similar sentences. How about this?

Suggested change

	A `USER_SCRIPT` world provides an isolated execution environment that isn't accessible to a host page or other extensions. This means a user script can change its JavaScript environment without affecting the host page or other extensions' user and content scripts. In this environment, user scripts aren't visible to the host page or other extensions' user and content scripts.
	A `USER_SCRIPT` world provides an isolated execution environment that isn't accessible to a host page or other extensions. This means a user script can change its JavaScript environment without affecting and isn't visible to its host page or other extensions' user and content scripts.

[Rob--W]

How about this? And maybe switch up with the previous paragraph?

Suggested change

	A `USER_SCRIPT` world provides an isolated execution environment that isn't accessible to a host page or other extensions. This means a user script can change its JavaScript environment without affecting the host page or other extensions' user and content scripts. In this environment, user scripts aren't visible to the host page or other extensions' user and content scripts.
	A `USER_SCRIPT` world provides an isolated execution environment that isn't accessible to a host page or other extensions. This isolation is similar to a [content script environment](/en-US/docs/Mozilla/Add-ons/WebExtensions/Content_scripts#content_script_environment), except `USER_SCRIPT` worlds cannot access extension APIs.