chrome-devtools-frontend 1.0.1662289 → 1.0.1664496

package/.agents/skills/{creating-a-model → devtools-model-management}/SKILL.md

@@ -1,4 +1,3 @@
-```
 ---
 name: devtools-model-management
 description: Guidelines for creating, migrating, and registering models in front_end/models/. Covers BUILD.gn, devtools_grd_files.gni, and entrypoints.

package/.agents/skills/devtools-unicode-escaping/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: devtools-unicode-escaping
+description: Guidelines for escaping strings and handling user-controlled data in DevTools to prevent layout bleed-through, XSS, and security issues.
+---
+
+# Unicode Escaping and User-Controlled Data Guidelines
+
+When displaying inspected data, user-controlled strings, or untrusted input in the DevTools UI (e.g., console messages, object properties, DOM tree nodes, or UI titles/descriptions), you must ensure they are properly escaped to prevent layout bleed-through (such as Right-to-Left leaks) or security vulnerabilities.
+
+DevTools provides two primary Unicode escaping functions in `Platform.StringUtilities`:
+
+## 1. Escaping for Text Representation (`escapeUnicodeAsText`)
+
+Use `Platform.StringUtilities.escapeUnicodeAsText(content)` when rendering values that developers need to inspect (e.g. string values inside the Console or the Object properties view) where hidden, invisible, or formatting characters should be made explicitly visible.
+
+* **Behavior**: Escapes all formatting and surrogate characters into literal Unicode escape sequences (e.g., `\u202E`, `\u200B`).
+* **Example Usage**:
+  ```typescript
+  const text = Platform.StringUtilities.escapeUnicodeAsText(JSON.stringify(description));
+  ```
+
+## 2. Escaping for UI Rendering (`safeEscapeUnicode`)
+
+Use `Platform.StringUtilities.safeEscapeUnicode(content)` when rendering content inside templates or HTML markup where you want safe layout-critical zero-width formatting characters to function normally for word wrapping or rendering layout, but want to escape dangerous layout-disrupting characters (like bidi overrides).
+
+* **Behavior**: Escapes dangerous formatting and surrogate characters (like `\u202E`), but leaves safe formatting characters untouched:
+  * Zero Width Space (`\u200B`)
+  * Zero Width Non-Joiner (`\u200C`)
+  * Zero Width Joiner (`\u200D`)
+* **Example Usage**:
+  Used automatically by the global Lit template wrapper.
+
+---
+
+## 3. Global Lit Template Wrapper
+
+DevTools wraps Lit's default `html` function inside `front_end/ui/lit/strip-whitespace.ts` (re-exported via `ui/lit/lit.js`). This wrapper automatically intercepts and escapes standard string values using `Platform.StringUtilities.safeEscapeUnicode(val)` at runtime.
+
+* **What is escaped automatically**: Any standard string interpolated directly in a template (e.g., `html`<span>${myString}</span>``).
+* **Array items**: Array values are traversed recursively, and string elements inside arrays are escaped automatically.
+* **Lit directives**: Directives (like `ifDefined`, `live`, `repeat`, `classMap`, etc.) are automatically traversed, and any string arguments inside their `values` array are escaped recursively.
+
+### Directives Rule:
+Because the wrapper automatically processes directive arguments, you **do not** need to manually escape strings passed to standard Lit directives. They will be handled safely at runtime.
+
+### Correct Example:
+```typescript
+title=${ifDefined(tooLong ? undefined : description)} // Automatically escaped!
+```
+
+---
+
+## 4. Manual DOM Assignments & Non-Lit Rendering
+
+Any manual assignments that bypass Lit entirely (e.g., setting `element.textContent`, `element.title`, or constructing DOM elements imperatively) will also bypass the Lit wrapper.
+
+* Always wrap user-controlled strings in these contexts with the appropriate escaping helper:
+  * Use `escapeUnicodeAsText` if you want hidden characters to display as text (e.g., showing `\\u202E`).
+  * Use `safeEscapeUnicode` if you want zero-width spaces to function but other dangerous characters to be escaped.
+
+### Correct Example:
+```typescript
+nameElement.textContent = Platform.StringUtilities.escapeUnicodeAsText(name);
+```

package/.agents/skills/devtools-ux-writing-refactor/SKILL.md

@@ -52,7 +52,7 @@ Locate all TypeScript files in the target folder that define `const UIStrings =
    * *Check sibling references:* If you change a setting name or label (for example, changing “Preserve log” to “Keep log”), search sibling files in the folder for explanatory text or status strings that reference the old name in quotes (for example, “console.clear() was prevented due to ‘Preserve log’”), and update them to match.
 2. **Cut unnecessary words:** Eliminate politeness (`please`, `sorry`), filler (`very`, `strongly`, `there is` or `there are`), and marketing fluff (`seamless`, `awesome`, `fast`, `quick`).
 3. **Contractions:** Use contractions (`don’t`, `can’t`, `isn’t`, `won’t`) instead of formal spellings (`do not`, `cannot`, `is not`, `will not`).
-4. **Curly apostrophes, quotation marks, and ellipses:** Use curly apostrophes (`’`) and quotation marks (`“ ”`) for improved readability. Use the ellipsis character (`…`) instead of three periods (`...`). Use prime (`′`) and double prime (`″`) symbols as needed for measurements like length or coordinates.
+4. **Curly apostrophes, quotation marks, and ellipses:** Use curly apostrophes (`’`) in user-facing `UIStrings` values for contractions and possessives, and quotation marks (`“ ”`) for improved readability. Use the ellipsis character (`…`) instead of three periods (`...`). Use prime (`′`) and double prime (`″`) symbols as needed for measurements like length or coordinates.
 5. **Sentence case and capitalization:** Use sentence case for headings, labels, and UI element names. Capitalize only the first word, proper nouns, product names (`Chrome DevTools`), and web APIs (`Background Fetch API`).
    * Don’t capitalize feature names (for example, `conditional breakpoint` or `command menu`).
    * Capitalize panel names and UX elements that are named after panels (for example, `Show Application`, `Toggle Console`, `Console sidebar`, or `Styles`).
@@ -62,6 +62,7 @@ Locate all TypeScript files in the target folder that define `const UIStrings =
 6. **Punctuation and actionability:** Remove trailing periods from single-sentence labels or titles. Ensure that error messages instruct the user how to recover (for example, `Shorten filename to 64 characters or less` instead of `Invalid filename`). Ensure that ARIA labels and multi-sentence tooltips have consistent terminal punctuation.
 7. **Terminology (glossary):** Strictly follow standard DevTools UI terminology and letter casing (`panel`, `tab`, `drawer`, `sidebar`, `datagrid` or `table`, `action bar`, `status bar`, and `live expressions section`). Never use `pane` or call tabs `panes` in UI strings or localization (L10n) comments.
 8. **Localization (L10n) comments:** Ensure that every string in `UIStrings` has a preceding `@description` comment that explains where and when it appears. This information is used for translators who need to understand the context in which the string is used.
+   * **Straight apostrophes in comments:** Always use straight apostrophes (`'`) in code comments (such as `@description` comments and L10n annotations), even if the UI string itself uses curly apostrophes (`’`).
    * Use precise terminology and correct letter casing (see rule 7). Ensure that the description is easy to understand and provides enough context for translators. For descriptions that are underspecified or
    ambiguous, figure out the context by looking at the use site of the
    string and come up with a better description.

package/.agents/skills/fixing-skipped-tests/SKILL.md

@@ -20,10 +20,10 @@ This skill outlines the workflow for fixing skipped tests in the DevTools codeba
    - You should look for occurrences like `it.skip('[crbug.com/<bugid>] ...', ...)` or skipped describes that mention the bug ID.
 
 4. **Iterative Fix Process**
-   - **Step 1:** Change `it.skip` or `describe.skip` to `it.only` or `describe.only` for *one* of the tests associated with the bug, so that only that specific test runs.
-   - **Step 2:** Re-run the tests (e.g., `npm run test -- <path_to_test_file>`) using the guidelines from the `devtools-verification` skill. If you are dealing with flaky tests, you can use the `--repeat=x` flag (e.g. `npm run test -- <path_to_test_file> --repeat=20`) to run the test multiple times to reproduce the flakiness.
+   - **Step 1:** Remove `it.skip` or `describe.skip` for *one* of the tests associated with the bug.
+   - **Step 2:** Re-run the specific test using its exact test ID (e.g., `npm run test path/to/foo.test.ts:test_name`) using the guidelines from the `devtools-verification` skill. If you are dealing with flaky tests, you can use the `--repeat=x` flag (e.g. `npm run test -- --repeat=20 path/to/foo.test.ts:test_name`) to run the test multiple times to reproduce the flakiness. This flag works for both E2E and unit tests.
    - **Step 3:** Analyze the test failure and make the necessary fixes to the code or the test itself.
-   - **Step 4:** Re-run the test to ensure the fix is correct. Remove `.only`.
+   - **Step 4:** Re-run the test to ensure the fix is correct.
    - **Step 5:** Remove the `[crbug.com/<bugid>]` prefix from the test name string if it is present.
    - **Step 6:** Remove any comments directly above the test that explain the reason why the test was skipped (e.g., `// TODO(crbug...): Flaky`).
    - **Step 7:** Apply the fix to the remaining tests, un-skipping them one by one or in batches, and verifying until all are passing.

package/.agents/skills/merging-devtools-module/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: devtools-module-merging
+name: merging-devtools-module
 description: Workflow for merging a DevTools submodule into its parent module. Covers BUILD.gn consolidation and updating devtools_grd_files.gni.
 ---
 

package/.agents/skills/migrate-chromium-test/SKILL.md

@@ -1,5 +1,5 @@
 ---
-name: devtools-migrate-chromium-test
+name: migrate-chromium-test
 description: Use when migrating Chromium layout tests to DevTools unit tests
 ---
 
@@ -26,6 +26,7 @@ description: Use when migrating Chromium layout tests to DevTools unit tests
 - If tests require a repetitive setup extract it into a test helper function at the top of the file.
 - Code comments must be full sentences ending with a period, except when the entire comment is a URL.
 - Do not include comments of the form `// Replaces web test: http/tests/devtools/persistence/automapping-absolute-paths.js`. Since we plan to remove migrated web tests, these are not useful references.
+- **Important** If the test imports only `TestRunner` and no other TestRunner helper or DevTools code. The test should be move to the inspector-protocol test, and the issue should be closed as "Won't Fix (Infeasible)" and add the issue to the hotlist with ID 8691563.
 
 4.  **Update BUILD.gn**:
 
@@ -40,12 +41,37 @@ description: Use when migrating Chromium layout tests to DevTools unit tests
 
 - Critically review the newly created test to ensure it provides meaningful coverage. Cross-reference it with the original Chromium layout test to verify that all original behaviors, edge cases, and assertions have been fully migrated and are actively being tested.
 - If the newly added test does not test any logic from the component but just the getters from the mocked data explain to the user that this test does not add value and it's better to close it without adding the test. Provide a command without executing it to close the issue as "Fixed".
-- If the newly added test uses too extensive mocks of CDP objects and methods explain to the user that the test should be foundation e2e test instead of unit test and we won't migrate it. Provide a command without executing it to close the issue as "Won't Fix (Infeasible)".
+- If the newly added test uses too extensive mocks of CDP objects and methods explain to the user that the test should be foundation e2e test instead of unit test and we won't migrate it. **CRITICAL**  upload a comment to the issue with your investigation and the reason why you won't submit a CL and close the issue as "Won't Fix (Infeasible)" and add the issue to the hotlist with ID 8687901.
 
-7. Uploading a CL with your changes using the `version-control` skill. And **STRICTLY** follow the following additional template
-- **Title**: `[test-migration] Migrating <chromium-test-name> to unit test`
-- **Body**: `Migrated <link-to-chromium-test> to <devtools-test-name>`
-- **Footer**: Use `Fixed: <issue number>` trailer instead of `Bug: <issue number>`.
+7. **Upload the CL:**
+
+## Commit message & CL upload requirements
+
+When committing and uploading CLs, **STRICTLY** follow this format and constraints:
+
+1. **Title line**: `[test-migration] Migrate <short test name> test to unit test`
+2. **Body**: `This CL migrates the legacy layout test <long test name> to a unit test in <new test name>. <optional additional explanation>`
+2. **Body appendix**: `https://crsrc.org/c/third_party/blink/web_tests/<long test name>;drc=4d51e9cab50efd0f8029c45a486e199a1d519fd1`
+3. **Bug line**: `Fixed: <issue number>`
+4. **Formatting constraints**: Wrap all lines to a maximum of 72 characters per line.
+
+Example commit message:
+
+```text
+[test-migration] Migrate console-eval-global test to unit test
+
+This CL migrates the legacy layout test
+http/tests/devtools/console/console-eval-global.js to a unit test in
+ConsolePrompt.test.ts. It verifies that the evaluation in ConsolePrompt
+is performed in the correct execution context (the active one) and with
+the correct expression.
+
+https://crsrc.org/c/third_party/blink/web_tests/http/tests/devtools/console/console-eval-global.js;drc=4d51e9cab50efd0f8029c45a486e199a1d519fd1
+
+Fixed: <issue number>
+```
+
+Use the `version-control` skill to upload the CL.
 
 ## Example Conversion
 

package/.agents/skills/repro-flaky-tests/SKILL.md

@@ -1,53 +1,93 @@
 ---
-name: repro-flaky-test
+name: repro-flaky-tests
 description: Reproduce and investigate flakiness in a test.
 ---
 
-# Fixing flaky Tests
+# Workflow
 
-This skill outlines the workflow for reproducing and fixing a flaky test in the DevTools codebase.
-
-## Workflow
+This skill outlines the workflow for reproducing and fixing a flaky test in the DevTools codebase. The work should be divided into sub-agents that should only be started when certain criteria are met.
 
 - You will be given as input, either a Chromium bug link (e.g. `crbug.com/1234567`), or a name of a test file and (optionally) the test name.
 - For example: e2e/extensions/debugger-language-plugins.test.ts and "The Debugger Language Plugins/shows sensible error messages".
-- If nothing is provided, as the user which test you should run.
-- Find the test in the codebase and look at its implementation.
-- Run the test three times to note how long the test runs (on average) per minute.
+- If nothing is provided, ask the user which test you should run.
+- Before starting the sub-agents, explain the workflow. For example:
+
+```
+I will attempt to reproduce the flakiness (simultaneously) locally and using the 'stressor bots'. Once issues are discovered, I will attempt to fix them.
+```
 
-## Reproduction
+## Reproduction agents
 
-- Run the test enough times for a full test run to take one minute. For example, if a test takes a second to run, set it to repeat 60 times. If a test takes 5 seconds to run, run it 12 times.
-- Start with one minute and, if the failure does not repeat, try again and increase the time by a minute (up to a maximum of 5 minutes per run).
-- Use `npm run test -- path/to/foo.test.ts --grep "<test name>" --repeat <count>` to run the tests repeatedly.
-- Be sure to keep track of the cumulative count of how often you run the test and how often they fail, so that you can calculate a 'flaky percentage' before and after making a fix.
+First, create and start two sub-agents simultaneously. One called 'local-repro' (that should attempt to reproduce the problem locally) and one called 'bot-repro' (that attempts to use the stressor bots to reproduce).
 
-After every round, display the *cumulative* results in a table:
+### Local reproduction (local-repro)
+
+- Use command: `npm run test -- --repeat=<count> path/to/foo.test.ts:exact_test_id` to locally run the tests repeatedly. Both E2E and unit tests support this. Use the exact test ID printed in the test runner output (usually the suite and test names with spaces replaced by underscores). Do not use `--grep` or a `bash` script with a `for` loop.
+- First run the test three times to note how long the test runs (on average).
+- Then run the test continuously for 4 minutes, while noting any failures and failure rates. If the failure rate is still 0% after that, assume the problem does not reproduce locally.
+- After the local test run completes, then show the results in a table. For example:
 
 ```
-Test:                                                 Runs  Time   Failures
-"Recorder/should be able to start a replay..."         30    60s   0 (0.00%)
-"The Debugger Language Plugins/shows sensible..."      60    60s   1 (1.67%)
+Test:                                                 Runs  Sec   Failures
+"Recorder/should be able to start a replay..."         30   180   0 (0.00%)
+"The Debugger Language Plugins/shows sensible..."      60   180   1 (1.67%)
 ```
 
-Once you have one or more failures, show the error message and ask the user if they want to:
+If problems were detected, list the different problems found and how often they occurred. Ask the user if the errors match the ones they are trying to get rid of.
 
-1) Start investigating the test failures.
-2) Continue running all the tests.
-3) Run only the failed tests (to get a clearer indication of their failure rate).
-4) Run only the tests that haven't failed (to attempt to get a reproduction).
+### Bot reproduction agent (bot-repro)
 
-## Investigation
+The second bot should do the following:
 
-- Create a branch flaky_tests and append a datestamp, such as _2026_07_04_14h16m.
+- Create a branch with a meaningful name, such as `deflake_<test_name>`.
 - Ensure you use the instructions from the `devtools-version-control` skill to create and switch branches appropriately.
-- Investigate each test failure and propose a fix.
-- Don't commit the changes to the branch.
+- Make a minor, harmless modification directly to the test file being investigated (e.g., adding a comment `// Trigger stressor bot`) to ensure the commit is not empty.
+- Add this file (with `git add`) and commit it using a meaningful commit message (e.g., `git commit -m "Deflake <test name>"`). Ask the user which bug number to use for the changelist description.
+- Upload this change using `git cl upload`. This creates a debugging CL that all agents (like the fix agent) will continue to work on.
+- Note the <issue number> created during upload.
+- To start the stressor bot, run this command (substituting `<test file>:exact_test_id` with the actual file and exact test ID):
+  `git cl try -B devtools-frontend/try -b e2e_stressor_linux -b e2e_stressor_win64 -b e2e_stressor_mac -p runner_args='<test file>:exact_test_id --repeat=100'`
+  - **Note on Screenshot Tests:** If the test involves screenshot assertions (`assertScreenshot`), it should ONLY be run on the Linux stressor bot (`-b e2e_stressor_linux`), because screenshot assertions are not supported on Mac or Windows. Furthermore, they cannot be reproduced locally on a Mac.
+  - **Auth Issues:** If `git cl try` fails with a login error (e.g., `Login required: run bb auth-login`), inform the user so they can resolve the auth issue and ask you to retry.
+
+- Note that the test file name needs to be relative to the root, so use `test/e2e/foo.test.ts` instead of `e2e/foo.test.ts`.
+- Check the results of the stressor tests with `git cl try-results --issue=<issue number> --patchset=<patchset number>`. You can dive into each result by id using `bb get <id>`.
+- Once a test run completes, always report to the user how often the tests ran and what the failure rate was.
+- Critical: Make sure that at least one test ran to completion on the bot (to catch incorrect syntax for `git cl try` or incorrect test IDs).
+
+## Next steps
+
+- Monitor the results of the two agents. The local reproduction bot will likely finish sooner.
+- If it does but doesn't reproduced the failure, ask the user this question:
+
+```
+While we wait for the bots to complete their run, would you like to:
+
+1) Continue trying to reproduce locally
+2) Start investigating the test
+```
+
+If they opt for investigating the test, start a new agent called 'fix-test'.
+
+### Fixing the test (fix-test)
+
+The test fixing sub-agent should do the following:
+
+- Find the test in the codebase and look at its implementation. Look at the relevant production code that is being testing.
+- Look at the failures reproduced in the test (if any) by prior sub-agents.
+- Suggest a fix for the failure(s).
+- IMPORTANT: Ensure any dummy comments added earlier to trigger the stressor bot are removed before finalizing the fix.
+- Run the full verification process (TypeScript checks, and linters) as required by the repository best practices.
+- Compile and run the test locally, to make sure there are no obvious errors introduced.
+- Commit the changes (to the branch created earlier). Make sure to list (in the changelist description) the test name, the fix, reasoning for why the test failed, why the fix fixes the issue and the failure rate (if non-zero). If you were not able to reproduce the error, state that the fix is speculative. Ask the user to provide the bug number to use in the changelist description.
+- CRITICAL: Iff the 'local-repro' bot does not reproduce the error, the 'fix-test' agent MUST wait until the stressor bot finishes its run before uploading the fix to the server (so that the stressor try run isn't aborted prematurely). If the error reproduces locally, you can upload immediately.
+- Once it is safe to do so, upload the change with `git cl upload`.
 
 ## Results
 
-- Before finishing, run the full verification process (TypeScript checks, and linters) as required by the repository best practices.
-- Request to run the test again for as long as you think it would take to be sure the problem is gone, but get permission from the user before starting very long runs (anything over 4 minutes).
-- For things that have a 33% failure rate before fixing (for example), only a handful of runs are needed to verify, but tests with lower failure rate need more.
-- NOTE: If the test fails again with the same error as before, you don't need to finish the test run but instead you should augment or replace your fix with a better one.
-- At the end, list the tests, state briefly why each test was failing and how the fix addresses the issue along with the failure rate before and after.
+- Always verify, by running the tests again that the problem has been fixed.
+  - If the problem reproduces locally during your initially attempt, then always prefer a local reproduction run (don't use the bots).
+  - But if the problem doesn't reproduce locally, always prefer the bot-repro but run the test locally (once only per fix) to verify the fix compiles and doesn't introduce a regression..
+- For things that have (let's say) a 33% failure rate before fixing (for example), a smaller amount of run is needed to verify, than for tests with lower failure rate.
+- CRITICAL: If the test fails again with the same error as before (or a new error), it is clear that the fix is not working and a new fix must be implemented (repeat the verification cycle).
+- Upon completion, list the tests, state briefly why each test was failing and how the fix addresses the issue along with the failure rate before and after.

package/.agents/skills/ui-eng-vision-widget-promoter/SKILL.md

@@ -21,6 +21,7 @@ clean `UI.Widget` classes that use native update rendering delegates.
     *   Clean up and remove older constructors that perform custom container
         initializations or access `.element` directly for manual append
         operations.
+    *   Note that `VBox` and `HBox` inherit directly from `Widget`. They fully support view injection (`view = DEFAULT_VIEW`), `performUpdate()`, and `requestUpdate()` without modification.
 
 2.  **Upgrade View Delegates & Inject View**:
 

package/docs/ui_engineering.md

@@ -34,6 +34,8 @@ This approach has two main benefits:
 1.  **Testability**: In unit tests, we can pass a simple stub as the view function, which allows us to test the presenter's logic without any DOM manipulation.
 2.  **Clarity**: It cleanly separates the presenter's logic from its rendering logic.
 
+Note that `VBox` and `HBox` inherit directly from `Widget`. They fully support view injection (`view = DEFAULT_VIEW`), `performUpdate()`, and `requestUpdate()` without modification.
+
 To test the `DEFAULT_VIEW` function itself, we should use screenshot and e2e tests.
 
 ## Declarative and orchestrated DOM updates

package/eslint.config.mjs

@@ -624,6 +624,7 @@ export default defineConfig([
       '@devtools/l10n-no-locked-or-placeholder-only-phrase': 'error',
       '@devtools/l10n-no-uistrings-export': 'error',
       '@devtools/l10n-no-unused-message': 'error',
+      '@devtools/l10n-use-curly-apostrophes': 'error',
     },
   },
   {

package/front_end/core/common/SettingRegistration.ts

@@ -268,11 +268,6 @@ export interface SettingRegistration {
    * Determines if the setting value is stored in the global, local or session storage.
    */
   storageType?: SettingStorageType;
-  /**
-   * A condition that, when present in the queryParamsObject of Runtime, constraints the value
-   * of the setting to be changed only if the user set it.
-   */
-  userActionCondition?: string;
   /**
    * A condition is a function that will make the setting available if it
    * returns true, and not available, otherwise. Make sure that objects you

package/front_end/core/common/Settings.ts

@@ -23,6 +23,75 @@ import {
 } from './SettingRegistration.js';
 import {VersionController} from './VersionController.js';
 
+/**
+ * Describes and configures a Setting.
+ *
+ * Use `Settings#resolve` to get the concrete `Setting` instance for a descriptor.
+ */
+export interface SettingDescriptor<ValueT> {
+  /** The unique identifier of a setting */
+  readonly name: string;
+
+  /**
+   * Determines how the possible values of the setting are expressed.
+   *
+   * - If the setting can only be enabled and disabled use BOOLEAN
+   * - If the setting has a list of possible values use ENUM
+   * - If each setting value is a set of objects use ARRAY
+   * - If the setting value is a regular expression use REGEX
+   */
+  readonly type: SettingType;
+
+  /**
+   * The default value for this setting.
+   *
+   * Can be computed based on the `hostConfig` (but NOTHING ELSE).
+   */
+  readonly defaultValue: ValueT|((hostConfig: Root.Runtime.HostConfig) => ValueT);
+
+  /**
+   * Determines if the setting value is stored in the global, local or session storage.
+   */
+  readonly storageType?: SettingStorageType;
+}
+
+/**
+ * Describes and configures a Setting that might be unavailable or disabled depending on the HostConfig.
+ *
+ * See {@link SettingAvailability} for details.
+ *
+ * Use `Settings#maybeResolve` to get the concrete `Setting` instance (or a reason why it's not available).
+ */
+export interface ConditionalSettingDescriptor<ValueT, ReasonT> extends SettingDescriptor<ValueT> {
+  /** The function used as `isAvailable` must only read the host config, NOTHING ELSE. */
+  isAvailable: (hostConfig: Root.Runtime.HostConfig) => SettingAvailabilityStatus<ReasonT>;
+}
+
+export type SettingAvailabilityStatus<ReasonT> = {
+  status: SettingAvailability.AVAILABLE,
+}|{
+  status: SettingAvailability.UNAVAILABLE | SettingAvailability.DISABLED,
+  reason: ReasonT,
+};
+
+export const enum SettingAvailability {
+  /**
+   * Setting is available and can be changed by the user or programmatically.
+   */
+  AVAILABLE = 1,
+
+  /**
+   * Setting is not available at all. Any `maybeResolve` or `resolve` call will fail.
+   * The setting should be hidden from the user.
+   */
+  UNAVAILABLE = 2,
+
+  /**
+   * Setting is available, but its value can't be read or written.
+   */
+  DISABLED = 3,
+}
+
 export interface SettingsCreationOptions {
   syncedStorage: SettingsStorage;
   globalStorage: SettingsStorage;
@@ -33,6 +102,8 @@ export interface SettingsCreationOptions {
   console: Console;
 }
 
+type NoFunction<T> = T extends(...args: never[]) => unknown ? never : T;
+
 export class Settings {
   readonly syncedStorage: SettingsStorage;
   readonly globalStorage: SettingsStorage;
@@ -75,9 +146,6 @@ export class Settings {
           this.createSetting(settingName, evaluatedDefaultValue, storageType);
 
       setting.setTitleFunction(registration.title);
-      if (registration.userActionCondition) {
-        setting.setRequiresUserAction(Boolean(Root.Runtime.Runtime.queryParam(registration.userActionCondition)));
-      }
       setting.setRegistration(registration);
 
       this.registerModuleSetting(setting);
@@ -257,6 +325,70 @@ export class Settings {
   getRegistry(): Map<string, Setting<unknown>> {
     return this.#registry;
   }
+
+  /**
+   * Resolves a setting descriptor to a concrete {@link Setting} instance.
+   *
+   * If a setting with the same name already exists (either pre-registered or
+   * previously resolved), that instance is returned. Otherwise, a new setting
+   * is created and registered.
+   *
+   * @param descriptor The descriptor defining the setting. Must not be conditional.
+   * @throws If the descriptor is conditional (contains `isAvailable`). Use `maybeResolve` instead.
+   */
+  resolve<T>(descriptor: SettingDescriptor<NoFunction<T>>&{isAvailable?: never}): Setting<T> {
+    if ('isAvailable' in descriptor) {
+      // TS can only do so much if developers downcast explicitly.
+      throw new Error('Use Settings#maybeResolve for conditional descriptors.');
+    }
+
+    return this.#resolve(descriptor);
+  }
+
+  #resolve<T>(descriptor: SettingDescriptor<T>): Setting<T> {
+    let setting = this.moduleSettings.get(descriptor.name);
+    if (setting) {
+      return setting as Setting<T>;
+    }
+
+    const {name, type, defaultValue, storageType} = descriptor;
+    const isRegex = type === SettingType.REGEX;
+
+    const isGetter =
+        (value: T|((config: Root.Runtime.HostConfig) => T)): value is((config: Root.Runtime.HostConfig) => T) =>
+            typeof value === 'function';
+
+    const evaluatedDefaultValue = isGetter(defaultValue) ? defaultValue(Root.Runtime.hostConfig) : defaultValue;
+    setting = isRegex && typeof evaluatedDefaultValue === 'string' ?
+        this.createRegExpSetting(name, evaluatedDefaultValue, undefined, storageType) :
+        this.createSetting(name, evaluatedDefaultValue, storageType);
+
+    this.registerModuleSetting(setting);
+    return setting as Setting<T>;
+  }
+
+  /**
+   * Resolves a conditional setting descriptor to a concrete {@link Setting} instance if it is available.
+   *
+   * This method checks the availability of the setting using the descriptor's `isAvailable` function
+   * and the current `hostConfig`. If available, it resolves and returns the setting (caching it if
+   * necessary). If not available (either unavailable or disabled), it returns the availability status
+   * and the reason.
+   *
+   * @param descriptor The conditional descriptor defining the setting.
+   * @returns An object with either the resolved `setting` or the availability `status` and `reason`.
+   */
+  maybeResolve<T, R>(descriptor: ConditionalSettingDescriptor<NoFunction<T>, R>): {setting: Setting<T>}|{
+    status: SettingAvailability.UNAVAILABLE|SettingAvailability.DISABLED, reason: R,
+  }
+  {
+    const available = descriptor.isAvailable(Root.Runtime.hostConfig);
+    if (available.status === SettingAvailability.AVAILABLE) {
+      return {setting: this.#resolve(descriptor)};
+    }
+
+    return available;
+  }
 }
 
 export interface SettingsBackingStore {
@@ -405,6 +537,15 @@ export class Setting<V> {
     this.#serializer = serializer;
   }
 
+  descriptor(): SettingDescriptor<V> {
+    return {
+      name: this.name,
+      type: this.type() ?? SettingType.BOOLEAN,
+      defaultValue: this.defaultValue,
+      storageType: this.#registration?.storageType,
+    };
+  }
+
   addChangeListener(listener: (arg0: EventTargetEvent<V>) => void, thisObject?: Object): EventDescriptor {
     return this.eventSupport.addEventListener(this.name, listener, thisObject);
   }

package/front_end/core/platform/StringUtilities.ts

@@ -50,8 +50,40 @@ const escapedReplacements = new Map([
   ['</script', '\\x3C/script'],
 ]);
 
-export const escapeUnicode = (content: string): string => {
-  return content.replaceAll(/[\p{Format}\p{Surrogate}]/gu, match => {
+const UNICODE_ESCAPE_SOURCE = '[\\p{Format}\\p{Surrogate}]';
+const UNICODE_ESCAPE_REGEX = new RegExp(UNICODE_ESCAPE_SOURCE, 'u');
+const UNICODE_ESCAPE_GLOBAL_REGEX = new RegExp(UNICODE_ESCAPE_SOURCE, 'gu');
+
+const UNICODE_ESCAPE_EXCEPT_ZWSP_SOURCE = '(?![\\u200B\\u200C\\u200D])[\\p{Format}]|\\p{Surrogate}';
+const UNICODE_ESCAPE_EXCEPT_ZWSP_REGEX = new RegExp(UNICODE_ESCAPE_EXCEPT_ZWSP_SOURCE, 'u');
+const UNICODE_ESCAPE_EXCEPT_ZWSP_GLOBAL_REGEX = new RegExp(UNICODE_ESCAPE_EXCEPT_ZWSP_SOURCE, 'gu');
+
+/**
+ * Escapes formatting and surrogate characters in the string into literal Unicode escape sequences (e.g. \u200B).
+ * Use this when displaying strings to developers for inspection (e.g. in the Console or Object properties)
+ * where you want hidden or invisible characters to be explicitly visible as literal text.
+ */
+export const escapeUnicodeAsText = (content: string): string => {
+  if (!UNICODE_ESCAPE_REGEX.test(content)) {
+    return content;
+  }
+  return content.replaceAll(UNICODE_ESCAPE_GLOBAL_REGEX, match => {
+    return match.split('').map(char => '\\u' + toHexadecimal(char.charCodeAt(0), 4)).join('');
+  });
+};
+
+/**
+ * Escapes dangerous formatting and surrogate characters (like bidi override characters) to prevent
+ * security and layout issues, but leaves safe, layout-critical zero-width formatting characters
+ * (Zero Width Space \u200B, Zero Width Non-Joiner \u200C, and Zero Width Joiner \u200D) untouched.
+ * Use this when rendering user-controlled content inside templates or HTML markup where you want formatting
+ * characters to function normally for word wrapping or rendering layout, rather than showing as literal text.
+ */
+export const safeEscapeUnicode = (content: string): string => {
+  if (!UNICODE_ESCAPE_EXCEPT_ZWSP_REGEX.test(content)) {
+    return content;
+  }
+  return content.replaceAll(UNICODE_ESCAPE_EXCEPT_ZWSP_GLOBAL_REGEX, match => {
     return match.split('').map(char => '\\u' + toHexadecimal(char.charCodeAt(0), 4)).join('');
   });
 };
@@ -176,8 +208,8 @@ export const toBase64 = (inputString: string): string => {
     shift = i % 3;
     v |= data[i] << (16 >>> shift & 24);
     if (shift === 2) {
-      encoded += String.fromCharCode(
-          encodeBits(v >>> 18 & 63), encodeBits(v >>> 12 & 63), encodeBits(v >>> 6 & 63), encodeBits(v & 63));
+      encoded += String.fromCharCode(encodeBits(v >>> 18 & 63), encodeBits(v >>> 12 & 63), encodeBits(v >>> 6 & 63),
+                                     encodeBits(v & 63));
       v = 0;
     }
   }
@@ -312,8 +344,8 @@ export const filterRegex = function(query: string): RegExp {
   return new RegExp(regexString, 'i');
 };
 
-export const createSearchRegex = function(
-    query: string, caseSensitive: boolean, isRegex: boolean, matchWholeWord = false): RegExp {
+export const createSearchRegex = function(query: string, caseSensitive: boolean, isRegex: boolean,
+                                          matchWholeWord = false): RegExp {
   const regexFlags = caseSensitive ? 'g' : 'gi';
   let regexObject;