@hominis/fireforge 0.19.5 → 0.19.6

package/CHANGELOG.md

@@ -12,9 +12,14 @@
 - **`modified-file-missing-header` — standard Mozilla MPL-2.0 block headers with wrapped line breaks.** The upstream fallback scan required a contiguous `Mozilla Public License` substring in the first few lines, so files that follow Mozilla’s usual `/* … Mozilla Public` / ` * License, v. 2.0 … */` wrap (including after Emacs/vim directive blocks) were warned despite a valid notice. `containsUpstreamLicenseText` in `src/core/license-headers.ts` now normalizes common block-comment continuation prefixes before matching, so forks need not add SPDX solely to satisfy patch lint.
 - **`fireforge test` — `--marionette-port` auto-forward matches toolkit mochitests and mixed suites.** Auto-forward of `--setpref=marionette.port=<n>` previously keyed off a path heuristic that missed `toolkit/content/tests/**` widget HTML tests (no `/mochitest/` segment), so the preflight could use the operator’s port while mach still defaulted to **2828**. Forwarding now runs whenever `--marionette-port` is set unless `--mach-arg` explicitly includes `--flavor=xpcshell` / `xpcshell-tests` (the pref is unused there). `isMarionetteFlavor` also treats `toolkit/content/tests/` paths as Marionette-relevant unless they sit under `/tests/xpcshell/`, for consistency with other callers of that helper.
 
+### Compatibility
+
+- **`furnace create --with-tests` defaults to `browser-chrome` again** (not `mochikit`, which was the default after the `--test-style` split). Forks whose top-level chrome document has no `tabbrowser` should pass **`--test-style=mochikit`** explicitly. On macOS, toolkit MochiKit / mochitest-chrome-style widget tests can idle until ~370s with no subtests; README documents the tradeoff.
+
 ### Documentation
 
 - **README — mochitest timeouts vs Marionette.** The Test harness section documents long idle timeouts (~370s, `TEST_END: TIMEOUT`) on fork custom chrome, `--marionette-port` behaviour with xpcshell flavor, and pointers to fork-side prefs and investigation (for example Hominis `AGENT_RULES.md`).
+- **README — default test harness and macOS mochitest-chrome.** The README sections “Picking a test harness for `furnace create`”, “Test harness options”, and “Known upstream build issues” describe the browser-chrome default, macOS single-process idle timeout, explicit `--test-style=mochikit`, and `--with-tests` + `--xpcshell` resolution.
 
 ## 0.18.0
 

package/README.md

@@ -59,6 +59,8 @@ Your project now has `fireforge.json`, an `engine/` directory with Firefox sourc
 
 - **macOS 15 (Darwin 25+) — `gecko-profiler` bindgen error `cannot find type _CharT in this scope`.** An Apple toolchain update changed `std::__CharT_pointer` to `_CharT_pointer` in the libc++ headers Firefox's bindgen walks, so `toolkit/library/rust/target-objects` fails during `mach build` even on a clean `fireforge bootstrap`. This is an upstream Firefox issue, not a FireForge bug. Two workarounds: pin Xcode's command line tools to a pre-September-2025 release via `xcode-select --install` / [Apple developer downloads](https://developer.apple.com/download/all/), or apply a one-line bindgen-basic-string-workaround patch (a downstream consumer may ship one in its patch queue). If you interrupt the resulting `fireforge build` and re-run `fireforge doctor`, the download/engine state is unaffected — the failure is isolated to the Rust compile phase.
 
+- **macOS (including Apple Silicon) — toolkit / MochiKit widget tests idle until ~370s (`TEST_END: TIMEOUT`, no subtests).** The **mochitest-chrome** flavor used for `toolkit/content/tests/widgets/test_*.html` runs **single-process** (`e10s: false`), which interacts badly with headed or headless compositing (for example SWGL) in some setups. Prefer **`furnace create --with-tests`** (defaults to **`browser-chrome`**, multi-process) for interactive chrome coverage, or place tests alongside your fork's browser modules (for example `engine/browser/modules/<fork>/test/`). If you must use **`--test-style=mochikit`**, expect possible hangs on macOS. Details: [Picking a test harness for `furnace create`](#picking-a-test-harness-for-furnace-create), [Test harness options](#test-harness-options).
+
 ### Workflow Overview
 
 1. Make changes inside the `engine/` directory.
@@ -417,15 +419,17 @@ The packaging-verification test that `--with-tests` scaffolds is what FireForge
 
 ### Picking a test harness for `furnace create`
 
-`furnace create --with-tests` defaults to a MochiKit test at `engine/toolkit/content/tests/widgets/test_<tag>.html`. MochiKit tests load the component module via `chrome://global/` and don't need a `tabbrowser`, so they run against any fork — including bespoke chrome documents (`mybrowser.xhtml`-class) that deliberately omit the upstream browser chrome.
+`furnace create --with-tests` defaults to a **browser-chrome** mochitest: `browser_<binary>_<tag>.js` under `engine/browser/base/content/test/<binary-name>/`, registered via `browser.toml` (and `browser/base/moz.build` when the scaffolder appends there). Use this when the component participates in real browser chrome (tabs, `gBrowser`, and similar).
+
+**MochiKit** (`--test-style=mochikit`) is opt-in: it emits `test_<tag>.html` under `engine/toolkit/content/tests/widgets/`, loads the module via `chrome://global/`, and does not need a `tabbrowser` — so it is the right choice for bespoke chrome documents that omit the upstream tab strip. On **macOS**, that harness can hit a long idle timeout (see [Known upstream build issues](#known-upstream-build-issues)); prefer browser-chrome tests when your fork has a normal tabbed window.
 
 Three styles are available via `--test-style`:
 
-| Style            | When to use                                                                                                                                                                                                         |
-| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `mochikit`       | Default. Pure-UI custom elements. Runs today against non-tabbrowser chrome. Emits `test_<tag>.html` under `toolkit/content/tests/widgets/`.                                                                         |
-| `browser-chrome` | Element talks to the browser window (open URLs, manipulate tabs). Requires a working `tabbrowser` in the chrome document. Emits the `browser_<bin>_<tag>.js` scaffold and registers it in `browser/base/moz.build`. |
-| `xpcshell`       | Storage-layer, observer-driven, or ESM-loading code. Headless, no tabbrowser. Emits `test_<name>_module_loads.js` + `xpcshell.toml` (registration in `XPCSHELL_TESTS_MANIFESTS` is left to the operator).           |
+| Style            | When to use                                                                                                                                                                                               |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `browser-chrome` | **Default** with `--with-tests`. Interactive chrome, tab strip, `gBrowser`. Requires a working `tabbrowser`. Emits `browser_<bin>_<tag>.js` and registers via `browser.toml` / `browser/base/moz.build`.  |
+| `mochikit`       | Pure-UI custom elements on forks **without** a `tabbrowser`. Emits `test_<tag>.html` under `toolkit/content/tests/widgets/`. May be unreliable on macOS (mochitest-chrome / single-process).              |
+| `xpcshell`       | Storage-layer, observer-driven, or ESM-loading code. Headless, no tabbrowser. Emits `test_<name>_module_loads.js` + `xpcshell.toml` (registration in `XPCSHELL_TESTS_MANIFESTS` is left to the operator). |
 
 `--xpcshell` is preserved as an alias for `--test-style=xpcshell`; conflicting flag combinations (`--xpcshell --test-style=mochikit`) are rejected.
 
@@ -628,7 +632,7 @@ Set this in `furnace.json` to extend the list (forks with additional platform pr
 
 ### Test harness options
 
-`fireforge furnace create --with-tests` scaffolds a **browser-chrome mochitest**. Use this when the component renders UI that depends on the tab strip (`openLinkIn` → `URILoadingHelper`, `gBrowser`, etc.).
+`fireforge furnace create --with-tests` scaffolds a **browser-chrome mochitest** by default. Use this when the component renders UI that depends on the tab strip (`openLinkIn` → `URILoadingHelper`, `gBrowser`, etc.). On **macOS**, avoid relying on **`--test-style=mochikit`** (toolkit `test_*.html` under `toolkit/content/tests/widgets/`) for primary chrome/widget coverage: the **mochitest-chrome** flavor runs **single-process** (`e10s: false`) and has been observed to **idle ~370s** with no subtests (headless or headed compositing / SWGL). Prefer browser-chrome tests (multi-process); for forks that organize interactive tests under `engine/browser/modules/<fork>/test/`, extend that tree rather than adding new `test_<tag>.html` scaffolds when browser-chrome is sufficient.
 
 `fireforge furnace create --xpcshell` scaffolds an **xpcshell test harness** instead. Use this when the component's code path is storage-only, observer-driven, or module-loading logic that does not touch a `tabbrowser`. xpcshell runs headless without browser chrome, so forks without an upstream tab strip can still cover these paths. The scaffolder writes `test_<name>_packaged.js` + `xpcshell.toml` into `engine/browser/base/content/test/<binary-name>-xpcshell/<component-name>/` and prints a note: registration in `XPCSHELL_TESTS_MANIFESTS` is the operator's call (the moz.build that should own the entry depends on where the component actually lives). `fireforge register <path>/xpcshell.toml` surfaces the same guidance when run directly rather than silently routing to a browser.toml-shaped advice.
 
@@ -636,7 +640,7 @@ The scaffolded xpcshell test is a **packaging probe**, not a module-load test. L
 
 xpcshell has a chrome-URI boundary that is worth knowing before writing assertions: `chrome://global/*` (toolkit chrome) IS registered and resolvable from the harness, but `chrome://browser/*` (browser chrome) is NOT — even when `firefox-appdir = "browser"` is set in the xpcshell.toml, the manifest set xpcshell loads lags what the real browser loads, so `NetUtil.asyncFetch("chrome://browser/content/…")` can still fail with `NS_ERROR_FILE_NOT_FOUND` against an artifact that IS present in `obj-*/dist/`. Assertions that need browser chrome URIs belong in a browser-chrome mochitest (`furnace create --test-style=browser-chrome`).
 
-The two flags can be combined — `--with-tests --xpcshell` writes both harnesses.
+If you pass **`--with-tests` and `--xpcshell` together**, FireForge resolves the harness to **xpcshell only** (`--xpcshell` takes precedence). To get the default browser-chrome mochitest as well, run a second `furnace create` with `--with-tests` only or add the browser test files manually.
 
 ### Mochitest stalls and `--marionette-port`
 

package/dist/src/commands/furnace/create.d.ts

@@ -5,14 +5,14 @@ export type ResolvedTestStyle = 'mochikit' | 'browser-chrome' | 'xpcshell' | 'no
  * Collapses `--with-tests`, `--xpcshell`, and `--test-style` into the single
  * scaffold dispatch used inside the mutation phase.
  *
- * Backwards-compat invariants:
+ * Invariants:
  * - `--xpcshell` alone is equivalent to `--test-style=xpcshell`.
- * - `--with-tests` alone (no `--test-style`) now defaults to `mochikit`
- *   (previously it defaulted to browser-chrome; the dogfooding pass
- *   flagged browser-chrome as unrunnable against non-tabbrowser chrome).
- *   Operators who need the old behavior can pass
- *   `--with-tests --test-style=browser-chrome`.
- * - `--xpcshell --with-tests` is rejected as ambiguous.
+ * - `--with-tests` alone (no `--test-style`) defaults to `browser-chrome`
+ *   (multi-process mochitest; reliable on macOS for interactive chrome).
+ *   Forks whose chrome document has no `tabbrowser` should pass
+ *   `--test-style=mochikit` explicitly.
+ * - When both `--xpcshell` and `--with-tests` are set, `--xpcshell` wins
+ *   (resolved style is `xpcshell` only).
  * @throws InvalidArgumentError when flags conflict.
  */
 export declare function resolveTestStyle(options: FurnaceCreateOptions): ResolvedTestStyle;

package/dist/src/commands/furnace/create.js

@@ -204,14 +204,14 @@ async function writeComponentFiles(componentDir, componentName, className, descr
  * Collapses `--with-tests`, `--xpcshell`, and `--test-style` into the single
  * scaffold dispatch used inside the mutation phase.
  *
- * Backwards-compat invariants:
+ * Invariants:
  * - `--xpcshell` alone is equivalent to `--test-style=xpcshell`.
- * - `--with-tests` alone (no `--test-style`) now defaults to `mochikit`
- *   (previously it defaulted to browser-chrome; the dogfooding pass
- *   flagged browser-chrome as unrunnable against non-tabbrowser chrome).
- *   Operators who need the old behavior can pass
- *   `--with-tests --test-style=browser-chrome`.
- * - `--xpcshell --with-tests` is rejected as ambiguous.
+ * - `--with-tests` alone (no `--test-style`) defaults to `browser-chrome`
+ *   (multi-process mochitest; reliable on macOS for interactive chrome).
+ *   Forks whose chrome document has no `tabbrowser` should pass
+ *   `--test-style=mochikit` explicitly.
+ * - When both `--xpcshell` and `--with-tests` are set, `--xpcshell` wins
+ *   (resolved style is `xpcshell` only).
  * @throws InvalidArgumentError when flags conflict.
  */
 export function resolveTestStyle(options) {
@@ -226,7 +226,7 @@ export function resolveTestStyle(options) {
     if (xpcshellFlag)
         return 'xpcshell';
     if (withTests)
-        return 'mochikit';
+        return 'browser-chrome';
     return 'none';
 }
 /**

package/dist/src/commands/furnace/index.js

@@ -71,9 +71,9 @@ function registerFurnaceInfoCommands(furnace, context) {
         .option('-d, --description <desc>', 'Component description')
         .option('--localized', 'Include Fluent l10n support')
         .option('--no-register', 'Skip customElements.js registration')
-        .option('--with-tests', 'Scaffold a test harness (defaults to MochiKit; see --test-style)')
+        .option('--with-tests', 'Scaffold a test harness (defaults to browser-chrome; use --test-style=mochikit for tabbrowser-less chrome — may be flaky on macOS)')
         .option('--xpcshell', 'Scaffold an xpcshell test harness (for storage-layer code on forks without tabbrowser); equivalent to --test-style=xpcshell. Note: xpcshell resolves chrome://global/* URIs but not chrome://browser/* — use --test-style=browser-chrome for browser-chrome-dependent tests.')
-        .option('--test-style <style>', "Override the harness written by --with-tests: mochikit (default, runs against non-tabbrowser chrome), browser-chrome (today's scaffold, needs tabbrowser), or xpcshell (headless)", (value) => {
+        .option('--test-style <style>', 'Override the harness written by --with-tests: browser-chrome (default, needs tabbrowser), mochikit (toolkit/widgets, non-tabbrowser chrome), or xpcshell (headless)', (value) => {
         if (value !== 'mochikit' && value !== 'browser-chrome' && value !== 'xpcshell') {
             throw new Error(`--test-style must be one of: mochikit, browser-chrome, xpcshell. Got: "${value}".`);
         }

package/dist/src/types/commands/options.d.ts

@@ -426,15 +426,15 @@ export interface FurnaceCreateOptions {
     /**
      * Test harness style to scaffold when `--with-tests` is set.
      *
-     * - `mochikit` (default when `--with-tests` is set alone) — a MochiKit
-     *   test at `engine/toolkit/content/tests/widgets/test_<tag>.html` that
-     *   loads the component module directly via `chrome://global/` and
-     *   asserts against `customElements`. Runs today on forks whose
-     *   top-level chrome document (e.g. `mybrowser.xhtml`) lacks a
-     *   `tabbrowser`, because it doesn't go through `URILoadingHelper`.
-     * - `browser-chrome` — today's browser-mochitest scaffold, requires a
-     *   working tabbrowser. Use for components that talk to the browser
-     *   window or open URLs.
+     * - `browser-chrome` (default when `--with-tests` is set without
+     *   `--test-style`) — browser mochitest scaffold; requires a working
+     *   `tabbrowser`. Prefer this for interactive chrome/widget coverage
+     *   (including on macOS).
+     * - `mochikit` — opt-in MochiKit test at
+     *   `engine/toolkit/content/tests/widgets/test_<tag>.html` that loads
+     *   the component via `chrome://global/`. Use when the top-level chrome
+     *   document lacks a `tabbrowser`; on macOS the toolkit mochitest-chrome
+     *   flavor can be unreliable (long idle timeout).
      * - `xpcshell` — equivalent to setting `--xpcshell`; headless, storage-only.
      */
     testStyle?: 'mochikit' | 'browser-chrome' | 'xpcshell';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.19.5",
+  "version": "0.19.6",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",