# Probe recipes Recipes for setting up a probe and for finding what a rule does, one heading per task. `SKILL.md` §2 routes here by heading. ## 1. Open the surface the way its tests do Before probing any surface, read the feature's browser-chrome tests and the helpers they import (e.g. the directory's `head.js`, a `*TestUtils.sys.mjs` module): they show how the product's own tests open the surface, fill it and wait for it to settle, and a probe can do the same once it undoes what a probe launch changes (`SKILL.md` §2 "A probe launch is not a user's profile"). The helpers load in a chrome probe once `resource://testing-common/`, which only a test harness registers, points at the objdir's `_tests/modules`: ```js const dir = new FileUtils.File("/_tests/modules"); Services.io.getProtocolHandler("resource") .QueryInterface(Ci.nsIResProtocolHandler) .setSubstitution("testing-common", Services.io.newFileURI(dir)); ``` Then import a helper with `ChromeUtils.importESModule` and call it as the tests do. A helper with an `init(scope)` method takes a stub holding the members it calls (e.g. `Assert`, `info`, `registerCleanupFunction`), and an argument that a harness global fills in a test (e.g. `waitForFocus`) needs a stand-in. Where a helper needs more of the harness than a stub gives, write the probe as a scratch browser-chrome test instead (`SKILL.md` §3). A second browser window takes `BrowserWindowTracker.promiseOpenWindow()` (from `resource:///modules/BrowserWindowTracker.sys.mjs`) in place of `BrowserTestUtils.openNewBrowserWindow()`, which does not settle in a probe; it resolves once the window has finished delayed startup. `OpenBrowserWindow()` returns while the new window is still `about:blank` and has no `delayedStartupPromise` yet, so awaiting that property right after the call waits for nothing, and the window's globals read `undefined`. Reach a panel view with `PanelMultiView.getViewNode(document, id)` (from `moz-src:///browser/components/customizableui/PanelMultiView.sys.mjs`), not `document.getElementById` (`browser/components/customizableui/docs/panelmultiview.md`, "Open or closed"). `PanelUI.show()` returns undefined, so poll until `getComputedStyle(el).display` is non-empty before reading. ## 2. Read a part inside a shadow root A `part` attribute is a list of names: select it with `shadowRoot.querySelector('[part~="name"]')`, since `[part=name]` misses a part that lists a second name. A climb by `parentElement` from a slotted child skips the shadow tree; climb through `assignedSlot`, as `./mach theme check-hcm-colors` and `./mach theme contrast` do. ## 3. Install a theme in the probe profile **An add-on theme.** A theme hosted on addons.mozilla.org is not in the tree, so install its XPI from `--chrome-setup-async`: `AddonManager.installTemporaryAddon(new FileUtils.File(path))` (both modules import from `resource://gre/modules/`), which takes an unsigned XPI too, then wait for `lwtheme` on the root before resolving. The temporary add-on goes with the throwaway profile. Pick the variant with `ui.systemUsesDarkTheme`: a theme with a `dark_theme` applies it when the chrome is dark. When the theme's XPI is out of reach, zip a `manifest.json` with `"theme": {"colors": {...}}` holding the keys under test into a stand-in; installTemporaryAddon takes it the same way. A copy of the real manifest with the proposed colors tests a fix that belongs in the theme. **A built-in theme.** A probe profile holds only the default theme until idle startup installs the others, so enable one from `--chrome-setup-async`: first `await BuiltInThemes.ensureBuiltInThemes()` (`resource:///modules/BuiltInThemes.sys.mjs`), then `(await AddonManager.getAddonByID(id)).enable()` with an id from `browser/themes/BuiltInThemeConfig.sys.mjs`, then wait for the root's `theme-effective-id` to name it before resolving. Which token layer each kind of theme paints is in `desktop-theme-tokens`' `references/token-layers.md` §2. ## 4. Test another platform's rule A `ui.*` look-and-feel override in `widget/nsXPLookAndFeel.cpp` makes a platform media feature match anywhere (`ui.windowsMica=1` for `(-moz-windows-mica)`), but the platform's own sheet (`browser/themes/windows/`, `osx/`, `linux/`) builds only on that platform. To test the shipped rule text, read its block from the source file with `IOUtils.readUTF8` (a chrome global, awaited; there is no module to import), inject it into the document that loads the sheet (`browser.xhtml` or another window's document) as `doc.documentElement.appendChild(doc.createElementNS("http://www.w3.org/1999/xhtml", "style"))`, since a XUL document has no `head`, set the root attribute it selects on (`customtitlebar`, for one), read the values, then remove both and read again. When you inject a whole file whose chrome URL the host platform also ships, disable the host's sheet at that URL first (`node.sheet.disabled = true`, the node being its `` or its `` processing instruction), or both cascade. That checks the cascade, not the platform's paint; report the paint as environment-limited. ## 5. Lock a pseudo-class `InspectorUtils.addPseudoClassLock(el, pc)`, then `clearPseudoClassLocks(el)` in the same call. Confirm each lock with `InspectorUtils.hasPseudoClassLock(el, pc)` (`SKILL.md` §2). `el.matches(pc)` is no substitute, since it can match natively (`:-moz-window-inactive` in a headless window) and a bare `:hover` never matches a non-link element in a quirks-mode page, locked or not (`*:hover` does). Where it is reachable: - the Marionette chrome sandbox, as `window.InspectorUtils`; - a privileged content page such as about:preferences (`firefox-probe.py --realm content`); - any page, a web page included, under `firefox-probe.py --sandbox system`; - a `SpecialPowers.spawn` task. The Firefox MCP's `evaluate_script` runs in a web page's own realm and lacks it; there `hover_by_uid` delivers a real pointer. ## 6. Match rules to an element `prop` is a longhand; a shorthand reads `""` off a rule that sets only a longhand. The filter keeps rules that set `prop` or a custom property its value references, since a state rule often sets the token rather than the property; a token set on an ancestor shows only in that ancestor's rules, so run it there too. The same holds for an inherited property such as `color` or `fill`: an empty list on an icon or label whose value is set means the rule sits on an ancestor, such as the button that holds it. Never filter on `cssText`: an outer rule's `cssText` contains every nested rule, so a hit there alone means the nested rule did not apply, and some entries have no `cssText` at all. A nested rule's `selectorText` is the bare `&:hover`, so the snippet walks `parentRule` for the outer selectors. ```js const rules = [...InspectorUtils.getMatchingCSSRules(el)]; const names = new Set([prop]); for (const r of rules) { const v = r.style?.getPropertyValue(prop) ?? ""; for (const [, n] of v.matchAll(/var\((--[\w-]+)/g)) names.add(n); } rules .filter(r => [...names].some(n => r.style?.getPropertyValue(n))) .map(r => { const sel = []; for (let x = r; x; x = x.parentRule) { sel.unshift(x.selectorText ?? x.conditionText ?? ""); } return `${r.parentStyleSheet?.href?.split("/").pop()}: ${sel.join(" ")}`; }); ``` ## 7. Find the layer a declaration sits in This probe checks `desktop-theme-tokens` §3's rule that an unlayered redefinition outranks every token layer at the live document. It runs in the chrome context, or in content through `firefox-probe.py --sandbox system` (`InspectorUtils` and `ChromeUtils` need a system principal). Set `el` and `name`. ```js const cls = o => ChromeUtils.getClassName(o); const layerOf = rule => { for (let r = rule; r; ) { if (cls(r) == "CSSLayerBlockRule") return r.name || "(anonymous)"; if (r.parentRule) { r = r.parentRule; continue; } const owner = r.parentStyleSheet?.ownerRule; if (owner && cls(owner) == "CSSImportRule" && owner.layerName !== null) return owner.layerName || "(anonymous)"; r = owner; } return null; // unlayered }; // The nearest element that declares `name` decides the inherited value. const declarers = (el, name) => { for (let n = el; n; n = n.parentElement || n.getRootNode().host || null) { const found = InspectorUtils.getMatchingCSSRules(n) .filter(r => r.style?.getPropertyValue(name)) .map(r => ({ rule: r, layer: layerOf(r), value: r.style.getPropertyValue(name).trim() })); if (n.style?.getPropertyValue(name)) found.push({ rule: null, layer: null, value: n.style.getPropertyValue(name) }); if (found.length) return { element: n, found }; } return null; }; const d = declarers(el, name); const read = () => getComputedStyle(el).getPropertyValue(name).trim(); const before = read(); const saved = d.found.filter(f => f.rule && f.layer === null) .map(f => [f.rule, f.rule.style.getPropertyValue(name), f.rule.style.getPropertyPriority(name)]); for (const [r] of saved) r.style.removeProperty(name); const without = read(); for (const [r, v, p] of saved) r.style.setProperty(name, v, p); return { element: d.element.localName, found: d.found.map(f => [f.layer, f.value]), before, without, restored: read() }; ``` A `without` that snaps to the layered value means the unlayered redefinition is what paints. `getMatchingCSSRules` lists the rules in cascade order, so the last normal declaration is the winner unless an earlier one is `!important`, which reverses the layer order. Removing the property edits the live sheet of that document only; `restored` should equal `before`. The probe finds the layer of a `@layer` block, of a `@layer` block around `@media` and of an `@import … layer()` rule. ## 8. Measure what a changed selector drops or adds When a patch narrows an existing selector (e.g. a compound added or a rule moved under an ancestor), enumerate the elements that fall out of it and measure one of each: `[...document.querySelectorAll(oldSelector)].filter(el => !el.matches(newSelector))`. When it widens one (e.g. a compound dropped or a rule moved out from under an ancestor), swap the two selectors to enumerate the elements it newly reaches. A selector rewritten both ways (e.g. a renamed class, or one compound added while another is dropped) does both, so run the snippet in both directions. A result of zero or one in a fresh window means the population is state-dependent (e.g. a panel not yet populated or a mode not entered), not that nothing falls out or is newly reached; create it through the product's own path first, then enumerate.