--- name: desktop-theme-probing description: Use when measuring anything off a running Firefox (geometry, a computed style, media-query or pseudo-class state, a pref, window state, focus, a timing) through the Firefox MCP, `firefox-probe.py`, a Marionette chrome-context probe or a scratch browser-chrome test; when writing or editing such a probe, even a small edit; when it needs `--no-headless`, `xvfb-run`, a headless compositor or the live desktop, or a headless run cannot see a value; when a chrome CSS, `.xhtml` or script edit does not show after a reload, or a launch dies on `Missing chrome or resource URL`; when a probe launch's state differs from a user's (remote-control stripes, an empty profile, about:blank); and before trusting a number a probe printed. allowed-tools: - Bash(./mach python --virtualenv wpt .claude/skills/desktop-theme-probing/scripts/firefox-probe.py:*) - Bash(./mach python --virtualenv wpt .agents/skills/desktop-theme-probing/scripts/firefox-probe.py:*) - Bash(./mach python --virtualenv wpt -- .claude/skills/desktop-theme-probing/scripts/firefox-probe.py:*) - Bash(./mach python --virtualenv wpt -- .agents/skills/desktop-theme-probing/scripts/firefox-probe.py:*) - Bash(./mach python --virtualenv wpt .claude/skills/desktop-theme-probing/scripts/marker-probe.py:*) - Bash(./mach python --virtualenv wpt .agents/skills/desktop-theme-probing/scripts/marker-probe.py:*) - Bash(./mach python --virtualenv wpt -- .claude/skills/desktop-theme-probing/scripts/marker-probe.py:*) - Bash(./mach python --virtualenv wpt -- .agents/skills/desktop-theme-probing/scripts/marker-probe.py:*) --- # How the desktop-theme family measures This skill owns getting a trustworthy number out of a running Firefox. The siblings own subjects: `desktop-theme-layout` geometry, `desktop-theme-colors` what a declaration paints in each color regime (forced colors, prefers-contrast, the color scheme), `desktop-theme-tokens` what a token resolves to, `desktop-theme-screenshots` the before/after image pair. A review or a theme bug needs the subject sibling's rules, which this skill does not hold: if you loaded this skill first, load the subject sibling before going further, or `desktop-theme` to pick one. **Measure before you theorise, and after you fix.** **Name the invariant as numbers first**: what would be true if the page were correct, in quantities you can read back (e.g. `documentElement.scrollHeight` unchanged across an interaction, the used `border-color` equal to the surface behind it, `element.height <= innerHeight`). Record the value before the change as well as after. When measuring says the mechanism is platform behavior rather than this component's, report the measurement and stop there: reducing it to a standalone testcase is outside this family. **The host's and the target's platform file.** The host's platform file is `references/platform-linux.md`, `references/platform-macos.md` or `references/platform-windows.md`, for the OS the probe runs on; read it whole before the first probe. The target's platform file is the one for the platform the bug or change concerns; when that is not the host, read it whole too before the first probe, since it says what users there see and which of it this host can reproduce, simulate or not reach at all. All three have the same sections: HEADLESS, DISPLAYS, FONT, SCROLLBARS, CONTRAST, COMPOSITING, MENUS, PATHS and GRABS. Take facts about measuring (HEADLESS, DISPLAYS, MENUS, PATHS, GRABS) from the host's file, and facts about what users see (CONTRAST, COMPOSITING, the FONT and SCROLLBARS defaults) from the target's. ## 1. Pick the instrument **Content document: the Firefox MCP.** `evaluate_script` runs in the page and returns JSON. Read every value you need in one call and return an object. Before the first reading, `get_firefox_info` and compare the binary path with this checkout's objdir: a reading off another tree's binary measures that tree's CSS with no error. When it differs, `restart_firefox` with `firefoxPath`, `headless: true` and a fresh `profilePath`. **Chrome document: the MCP's privileged path**, `evaluate_privileged_script` after a restart with `MOZ_REMOTE_ALLOW_SYSTEM_ACCESS=1`. Use it for `Services`, prefs, and seeding profile state such as form history or engines. Before the first `restart_firefox`, sweep or key press, read §1-§7 in [`references/firefox-mcp.md`](references/firefox-mcp.md): a restart applies the server's launch prefs over yours and a nonempty `env` replaces the configured one, a sweep outlives the command timeout, and `press_key` performs no default action. **A one-shot chrome read without the MCP: the bundled probe runner.** `.claude/skills/desktop-theme-probing/scripts/firefox-probe.py --realm chrome` launches a build, evaluates chrome-context JS and prints the result. It needs the checkout's Marionette, so run it through `./mach python --virtualenv wpt` from the checkout: ```sh ./mach python --virtualenv wpt .claude/skills/desktop-theme-probing/scripts/firefox-probe.py \ --binary /dist/bin/firefox --realm chrome \ --setpref ui.useAccessibilityTheme=1 -e 'return { ... };' # chrome's regime under that pref: the host's platform file, section CONTRAST ``` The first call in a tree, and sometimes the first after a checkout, a clobber or `./mach artifact install`, builds the virtualenv, and its output can land in stdout after the result. Build it with a call of its own before the first probe: `./mach python --virtualenv wpt -c pass`. The help of either bundled script (`firefox-probe.py`, `marker-probe.py`) needs `--` before the script path (`./mach python --virtualenv wpt -- …/firefox-probe.py --help`), since mach takes a bare `--help` for itself. `--script-file FILE` replaces `-e` for a longer snippet. Read [`references/probe-runner.md`](references/probe-runner.md) before writing or running a snippet through it: it has what the help leaves out, such as the pref read-back, parsing the output, teardown, the chrome sandbox, `--async` and `--no-headless`. A headless read through it needs only these before the first launch: the host's platform file, the target's where it differs, and `probe-runner.md`; the others in this section apply when their own condition does. Before any non-headless run (`--no-headless`, on a virtual display or the live desktop), read §1 "Pick the display rung by what the measurement needs" in [`references/running-a-probe.md`](references/running-a-probe.md), then the host's platform file, section DISPLAYS, for the rungs that host has and their commands. `` is `obj-*/` in the checkout, or the path that `./mach environment | rg -A1 '^object directory:'` prints under its label. The binary's path under it is in the host's platform file, section PATHS. **Shape the snippet for the instrument.** A snippet in the wrong shape fails before anything runs, or exits 0 having printed `null`. - `evaluate_script` and `evaluate_privileged_script` take a function expression. - `firefox-probe.py -e` takes a bare body ending in `return`. - `firefox-probe.py --async` takes a bare body that may `await` and must `return` its result. §2 "The chrome sandbox and `--async`" in `references/probe-runner.md` has the timeout triage. - The harness form is a callback passed to `SpecialPowers.spawn`. - In every instrument an element's `ownerGlobal` is gone (bug 2033243). In a privileged realm use `element.documentGlobal`, which is chrome-only like `isInstance`; in a page realm use `element.ownerDocument.defaultView` and `instanceof`. **When the MCP is unusable, use the test harness as the instrument** (§3). ## 2. Keep the probe honest ### Confirm the build you are measuring **Restart after an edit, don't reload**: a running instance caches the chrome stylesheets it loaded. §2 "What is live at the next launch" in [`references/build-freshness.md`](references/build-freshness.md) says which edits need `./mach build faster` first. After a script or markup edit, restart the MCP's kept profile with `MOZ_PURGE_CACHES=1`. A launch that fails, or a service missing from a realm, can mean the build does not match the checkout; before rebuilding, or concluding the service is absent, read §1 "Signatures and repairs" there. ### A probe launch is not a user's profile `firefox-probe.py`, the MCP and a mochitest differ from a user's profile in five ways. Undo what the reading depends on, and name in the bug what you left. - **The remote-control cue.** Every window's root gets `remotecontrol`, which stripes the address bar, stops its animation and adds a robot icon that takes space in it. Run `document.documentElement.removeAttribute("remotecontrol")` in every window you read, a window opened later included. - **The automation pref set**: Marionette's `geckoinstance.py` for `firefox-probe.py`, `testing/profiles` for a mochitest, and for the MCP geckodriver's defaults (`testing/geckodriver/src/prefs.rs`) and its launch prefs, plus the remote agent's `RecommendedPreferences.sys.mjs` unless `remote.prefs.recommended=false`, which the tree's `.mcp.json` passes. All three start on a blank page and override prefs of individual features, so search the set's file for the feature's pref branch (about:newtab renders an empty root under `geckoinstance.py`'s activity-stream prefs). `geckoinstance.py` and `RecommendedPreferences.sys.mjs` also hide the bookmarks toolbar, so read the toolbar's state in an MCP launch rather than assume it. When the subject depends on a pref, pass the user's value back and read it back. A Nimbus variable maps to a pref only as its entry in `FeatureManifest.yaml` says (`fallbackPref`, `setPref`, or none); a pref named after the variable is accepted and the feature silently reads its default. - **The empty profile.** UI that lists stored data (e.g. history, bookmarks, form history, engines, downloads, logins) shows its empty state; seed the store through the product's API (`--chrome-setup`, the privileged context). - **The start page.** `firefox-probe.py` opens on about:blank, so chrome that reflects the loaded page (e.g. its identity, actions, history) shows its empty-page state; load a page (`--url`) before reading it. - **The host's look and feel.** Before the first reading of a system color, font size, scrollbar or color scheme, see the host's platform file, section HEADLESS; without it the reading describes this host, not the user's. Before the first probe of a surface, read how its browser-chrome tests open it and wait for it, as §1 "Open the surface the way its tests do" in [`references/probe-recipes.md`](references/probe-recipes.md) says. Before reading a part inside a shadow root, installing a theme or testing another platform's rule, read the heading there named for that task. ### Reach and read the state - **Before probing a stylesheet you did not load from the product,** read `docs/code-quality/coding-style/css_guidelines.md` "Chrome-only media features go by the stylesheet, not the document": it lists the sheets that parse chrome-only features and `env(hairline)`. - **Never drive internal state by hand to set up a measurement.** Calling `hidePopover()` or stripping an attribute puts the element in a configuration the product never produces; the tell is a computed value that makes no sense, such as an element with `open` set that does not match `:popover-open`. Re-open the page instead. Forcing state is legitimate for a picture (`desktop-theme-screenshots` §1); when you cannot reach the state through the UI, say so in the commit message and the bug. - **Read an element-state pseudo-class through the inspector's lock.** Lock with `InspectorUtils.addPseudoClassLock(el, pc)`, one call per pseudo-class of a compound state (e.g. `:hover`, `:active`, `:focus-visible`, `:focus-within`, `:checked`, `:disabled`, `:open`, `:popover-open`), and assert `InspectorUtils.hasPseudoClassLock(el, pc)` after every lock: a pseudo-class not backed by element state (`:-moz-window-inactive`), or a typo, locks as a silent no-op. Before locking outside chrome, read §5 "Lock a pseudo-class" in [`references/probe-recipes.md`](references/probe-recipes.md). A lock cannot set an attribute state such as `[open]` or `[checked]` (drive it as the next bullet says), and a media-query state comes from a pref, such as `ui.prefersReducedMotion=1`. - **Drive an attribute state (e.g. `open`, `checked`) through the product's entry point, and assert it landed before reading.** When the entry point is out of reach, setting the attribute is acceptable for a computed-style read, said beside the reading and removed in the same call. In an `--async` probe, call that entry point (e.g. a panel's own `show()`, a command) and assert that the DOM changed (a label or a value, not a count): a driven state that does not take leaves the previous one in place, and a poll returns it as a reading. Read the window's real size back too: `resizeTo` stops at the root's `min-width`. - **In a widget with a shadow root, read the state where the widget sets it.** A custom element often sets `selected` or `open` on a part inside its shadow root, not on the host, so select through `el.shadowRoot` and lock the pseudo-class on that same part. - **Finish whatever animates before reading.** Two frames do not finish a CSS transition, so a locked or driven state reads a value partway between the two states: `for (let a of el.getAnimations({ subtree: true })) if (el.documentGlobal.CSSTransition.isInstance(a)) a.finish();` (`instanceof` checks one global's prototype and silently skips an animation from another document; `finish()` throws on an infinite animation such as a spinner). A scroll animates too: set `general.smoothScroll` to false before a scroll measurement, or a read one call later catches it mid-flight. - **An element outside the flat tree reads `""` for every property**: an unslotted child of a shadow host (a ``'s content until its first open), a node still inside a `