@hominis/fireforge 0.43.1 → 0.44.1

package/dist/src/commands/furnace/chrome-doc-templates.js

@@ -99,23 +99,25 @@ export function generateChromeDocXhtml(name, withTitlebar, license) {
 `;
 }
 /**
- * browser.xhtml-like scaffold for the document that ships as the fork's
- * MAIN BROWSER WINDOW (0.34.0 field report): the generic dialog-shaped
- * `<window>` scaffold was wrong for the `tokenHostDocuments[0]` /
- * BROWSER_CHROME_URL target — platform C++ reads the root element BEFORE
- * any script runs, and expects the `browser.xhtml` shape:
+ * browser.xhtml-like scaffold for the document that ships as the fork's MAIN
+ * BROWSER WINDOW.
+ *
+ * The generic dialog-shaped `<window>` scaffold is wrong for the
+ * `tokenHostDocuments[0]` / BROWSER_CHROME_URL target: platform C++ reads
+ * the root element BEFORE any script runs, and expects the `browser.xhtml`
+ * shape:
  *
  * - `<html id="main-window">` root (not `<window id="<name>-window">`) —
  *   upstream code from nsXULWindow sizing to session restore looks up
  *   `main-window` by id;
  * - `windowtype="navigator:browser"`, `chromehidden=""` and the geometry
  *   `persist` allowlist declared as ROOT ATTRIBUTES so the platform's
- *   pre-script pass (window tracking, XULStore geometry, chrome flags)
- *   sees them;
+ *   pre-script pass (window tracking, XULStore geometry, chrome flags) sees
+ *   them;
  * - the same head/bootstrap wiring (customElements.js, per-doc subscript,
  *   CSS + Fluent links) and `data-furnace-chrome-doc` sentinel as the
- *   generic scaffold, so jar.mn registration and the platform-module
- *   guard pattern are unchanged.
+ *   generic scaffold, so jar.mn registration and the platform-module guard
+ *   pattern are unchanged.
  */
 export function generateBrowserWindowXhtml(name, license) {
     return `<?xml version="1.0"?>
@@ -278,14 +280,13 @@ export function jarMnEntriesForChromeDoc(name) {
 /**
  * jar.inc.mn entry that registers the scoped CSS under `content/browser/`.
  *
- * The source path is `../shared/<name>-chrome.css` because `jar.inc.mn`
- * is included from each theme-specific manifest (`browser/themes/osx/jar.mn`,
- * `browser/themes/linux/jar.mn`, `browser/themes/windows/jar.mn`), and every
- * existing entry in those manifests resolves paths relative to the including
- * manifest's directory. A bare `(shared/…)` path produced
- * `obj-.../browser/themes/osx/shared/<name>-chrome.css` which does not exist;
- * `(../shared/…)` matches the upstream pattern and resolves under
- * `browser/themes/shared/`.
+ * The source path is `../shared/<name>-chrome.css` because `jar.inc.mn` is
+ * included from each theme-specific manifest (`browser/themes/osx/jar.mn`,
+ * `.../linux/`, `.../windows/`), and every existing entry in those manifests
+ * resolves paths relative to the INCLUDING manifest's directory. A bare
+ * `(shared/…)` path resolves to
+ * `obj-.../browser/themes/osx/shared/<name>-chrome.css`, which does not
+ * exist.
  */
 export function jarIncMnEntryForChromeDoc(name) {
     return `    content/browser/${name}-chrome.css           (../shared/${name}-chrome.css)`;
@@ -293,12 +294,11 @@ export function jarIncMnEntryForChromeDoc(name) {
 /**
  * locales/jar.mn entry that registers the `.ftl` under the browser locale
  * bundle. The source path is resolved by mach-locale-jar relative to the
- * per-locale root (e.g. `engine/browser/locales/en-US/`), and the FTL
- * file is scaffolded at `browser/${name}.ftl` under that root — the `%`
- * prefix means "per-locale content" and the `browser/` subdirectory
- * matches the subdir the scaffolder writes into. Before this fix the
- * entry emitted `(%${name}.ftl)`, which pointed at `en-US/${name}.ftl`
- * and broke the first post-scaffold `fireforge build` with
+ * per-locale root (e.g. `engine/browser/locales/en-US/`), and the FTL file
+ * is scaffolded at `browser/${name}.ftl` under that root — the `%` prefix
+ * means "per-locale content" and the `browser/` subdirectory matches where
+ * the scaffolder writes. A bare `(%${name}.ftl)` points at
+ * `en-US/${name}.ftl` and breaks the first post-scaffold build with
  * "jar.mn: Cannot find ${name}.ftl".
  */
 export function localeJarMnEntryForChromeDoc(name) {

package/dist/src/commands/furnace/chrome-doc-tests.js

@@ -3,30 +3,29 @@
  * Packaging-verification test templates for
  * `fireforge furnace chrome-doc create --with-tests`.
  *
- * Motivation: an operator who scaffolds a top-level chrome document wants
- * to know "did the file actually land in the packaged bundle?" before
- * relying on it at runtime. Both natural test harnesses have gaps for
- * this question:
+ * An operator who scaffolds a top-level chrome document wants to know "did
+ * the file actually land in the packaged bundle?" before relying on it at
+ * runtime. Both natural test harnesses have gaps for that question:
  *
  *   - xpcshell's `chrome://browser/*` URI registration lags what the real
  *     browser loads even with `firefox-appdir = "browser"` set, so
- *     `NetUtil.asyncFetch("chrome://browser/content/<name>.xhtml")` can
- *     fail with `NS_ERROR_FILE_NOT_FOUND` against a file that IS
- *     correctly packaged (the motivating case).
+ *     `NetUtil.asyncFetch("chrome://browser/content/<name>.xhtml")` can fail
+ *     with `NS_ERROR_FILE_NOT_FOUND` against a file that IS correctly
+ *     packaged.
  *   - Browser-chrome mochitests require a `tabbrowser`, which a
  *     fork-authored chrome doc that replaces `browser.xhtml` deliberately
- *     does not carry (the URILoadingHelper crash path).
+ *     does not carry.
  *
  * This scaffold threads the needle by probing the filesystem directly:
- * `Services.dirsvc.get("XCurProcD", Ci.nsIFile)` returns the current
- * process directory (the browser app dir when `firefox-appdir = "browser"`),
- * and the packaged chrome layout for a jar.mn entry
- * `content/browser/<name>.xhtml` is stable across platforms at
- * `<AppDir>/chrome/browser/content/browser/<name>.xhtml` on an unpacked
- * tree (the default for `mach build` without `MOZ_CHROME_MULTILOCALE`
- * / omnijar). A tree that packs omni.ja would need a different probe;
- * the scaffold notes that out-of-scope case explicitly rather than
- * silently producing a test that fails on packed builds.
+ * `Services.dirsvc.get("XCurProcD", Ci.nsIFile)` returns the current process
+ * directory (the browser app dir when `firefox-appdir = "browser"`), and the
+ * packaged chrome layout for a jar.mn entry `content/browser/<name>.xhtml`
+ * is stable across platforms at
+ * `<AppDir>/chrome/browser/content/browser/<name>.xhtml` on an unpacked tree
+ * (the default for `mach build` without `MOZ_CHROME_MULTILOCALE` / omnijar).
+ * A tree that packs omni.ja would need a different probe; the scaffold notes
+ * that out-of-scope case explicitly rather than silently producing a test
+ * that fails on packed builds.
  */
 /**
  * Returns the canonical xpcshell test basename for a chrome doc packaging
@@ -70,17 +69,16 @@ add_task(async function test_${taskSuffix}_files_packaged() {
   const appDir = Services.dirsvc.get("XCurProcD", Ci.nsIFile);
 
   // Probes a pair of candidate layouts for the same packaged file:
-  //   1) \`<AppDir>/chrome/browser/…\` — the unpacked layout when
-  //      XCurProcD honours \`firefox-appdir = "browser"\` and resolves
-  //      into \`dist/bin/browser/\`.
-  //   2) \`<AppDir>/browser/chrome/browser/…\` — the macOS .app bundle
-  //      layout and some ESR configurations, where XCurProcD sits one
-  //      level above \`browser/\` even when the appdir directive is set.
+  //   1) \`<AppDir>/chrome/browser/…\` — the unpacked layout when XCurProcD
+  //      honours \`firefox-appdir = "browser"\` and resolves into
+  //      \`dist/bin/browser/\`.
+  //   2) \`<AppDir>/browser/chrome/browser/…\` — the macOS .app bundle layout
+  //      and some ESR configurations, where XCurProcD sits one level above
+  //      \`browser/\` even when the appdir directive is set.
   // If either path exists the file is packaged; the assertion only fails
   // when BOTH layouts miss, which is the actual stale-build / missing
-  // jar.mn entry case. Before this dual probe, the eval on macOS
-  // consistently failed against layout (2) even though the file was
-  // packaged correctly.
+  // jar.mn entry case. A single-layout probe fails on macOS against layout
+  // (2) even though the file is packaged correctly.
   function probeEither(primary, fallback, description) {
     const primaryFile = appDir.clone();
     for (const segment of primary) {
@@ -121,9 +119,8 @@ add_task(async function test_${taskSuffix}_files_packaged() {
   // \`content/browser/<name>-chrome.css\` (see \`chromeDocJarIncMnCssEntry\`
   // in \`src/commands/furnace/chrome-doc-templates.ts\`), so the packaged
   // file lands under \`chrome/browser/content/browser/\`, not under
-  // \`skin/classic/browser/\`. The 2026-04-21 eval's first
-  // \`fireforge test --build\` against a scaffolded chrome-doc reported
-  // a false failure because the probe was looking at the skin layout.
+  // \`skin/classic/browser/\`. Probing the skin layout reports a false
+  // failure on the first \`fireforge test --build\` after a scaffold.
   probeEither(
     ["chrome", "browser", "content", "browser", "${name}-chrome.css"],
     ["browser", "chrome", "browser", "content", "browser", "${name}-chrome.css"],

package/dist/src/commands/furnace/chrome-doc.d.ts

@@ -2,18 +2,18 @@
  * `fireforge furnace chrome-doc create <name>` — scaffolds a top-level
  * chrome document (xhtml + js + css + ftl + jar.mn registrations).
  *
- * Motivation: `furnace create` covers custom elements under
- * `toolkit/content/widgets/`, but top-level chrome documents (the
- * `mybrowser.xhtml`-class entry points a fork adds alongside or instead
- * of `browser.xhtml`) are today hand-authored with error-prone jar.mn +
- * jar.inc.mn + locales/jar.mn glue. The `*` preprocessor flag, the
- * macOS titlebar-button carve-out, the startup-topic observer, and the
- * Fluent linkage each have silent-break failure modes.
+ * `furnace create` covers custom elements under `toolkit/content/widgets/`,
+ * but top-level chrome documents — the `mybrowser.xhtml`-class entry points
+ * a fork adds alongside or instead of `browser.xhtml` — are otherwise
+ * hand-authored with error-prone jar.mn + jar.inc.mn + locales/jar.mn glue.
+ * The `*` preprocessor flag, the macOS titlebar-button carve-out, the
+ * startup-topic observer, and the Fluent linkage each have silent-break
+ * failure modes.
  *
- * This command writes the four source files and appends three jar.mn
- * entries under a rollback journal identical in shape to `furnace create`.
- * A SIGINT mid-scaffold restores every touched file; a successful run
- * leaves the tree ready for `fireforge build`.
+ * This command writes the four source files and appends three jar.mn entries
+ * under a rollback journal identical in shape to `furnace create`. A SIGINT
+ * mid-scaffold restores every touched file; a successful run leaves the tree
+ * ready for `fireforge build`.
  */
 /** Options for `furnace chrome-doc create`. */
 export interface FurnaceChromeDocCreateOptions {
@@ -27,12 +27,11 @@ export interface FurnaceChromeDocCreateOptions {
     /**
      * Scaffold an xpcshell packaging-verification test alongside the chrome
      * document. The generated test probes `XCurProcD/chrome/browser/...` on
-     * disk rather than going through `chrome://` URI resolution — that
-     * bypasses xpcshell's limited browser-chrome manifest set (the
-     * motivating failure mode where `NetUtil.asyncFetch` returns
-     * `NS_ERROR_FILE_NOT_FOUND` against a file that IS packaged).
-     * Registration in `XPCSHELL_TESTS_MANIFESTS` is left to the operator
-     * because the owning moz.build depends on the fork's layout.
+     * disk rather than going through `chrome://` URI resolution, which
+     * bypasses xpcshell's limited browser-chrome manifest set — where
+     * `NetUtil.asyncFetch` returns `NS_ERROR_FILE_NOT_FOUND` against a file
+     * that IS packaged. Registration in `XPCSHELL_TESTS_MANIFESTS` is left to
+     * the operator because the owning moz.build depends on the fork's layout.
      */
     withTests?: boolean;
     /** Print the scaffold plan without writing files. */

package/dist/src/commands/furnace/chrome-doc.js

@@ -3,29 +3,29 @@
  * `fireforge furnace chrome-doc create <name>` — scaffolds a top-level
  * chrome document (xhtml + js + css + ftl + jar.mn registrations).
  *
- * Motivation: `furnace create` covers custom elements under
- * `toolkit/content/widgets/`, but top-level chrome documents (the
- * `mybrowser.xhtml`-class entry points a fork adds alongside or instead
- * of `browser.xhtml`) are today hand-authored with error-prone jar.mn +
- * jar.inc.mn + locales/jar.mn glue. The `*` preprocessor flag, the
- * macOS titlebar-button carve-out, the startup-topic observer, and the
- * Fluent linkage each have silent-break failure modes.
+ * `furnace create` covers custom elements under `toolkit/content/widgets/`,
+ * but top-level chrome documents — the `mybrowser.xhtml`-class entry points
+ * a fork adds alongside or instead of `browser.xhtml` — are otherwise
+ * hand-authored with error-prone jar.mn + jar.inc.mn + locales/jar.mn glue.
+ * The `*` preprocessor flag, the macOS titlebar-button carve-out, the
+ * startup-topic observer, and the Fluent linkage each have silent-break
+ * failure modes.
  *
- * This command writes the four source files and appends three jar.mn
- * entries under a rollback journal identical in shape to `furnace create`.
- * A SIGINT mid-scaffold restores every touched file; a successful run
- * leaves the tree ready for `fireforge build`.
+ * This command writes the four source files and appends three jar.mn entries
+ * under a rollback journal identical in shape to `furnace create`. A SIGINT
+ * mid-scaffold restores every touched file; a successful run leaves the tree
+ * ready for `fireforge build`.
  */
 import { join } from 'node:path';
 import { loadConfig } from '../../core/config.js';
 import { furnaceConfigExists, loadFurnaceConfig } from '../../core/furnace-config.js';
-import { recordFurnaceRollbackFailure, runFurnaceMutation, } from '../../core/furnace-operation.js';
-import { createRollbackJournal, recordCreatedDir, restoreRollbackJournalOrThrow, snapshotFile, } from '../../core/furnace-rollback.js';
+import { completeJournalRollback, runFurnaceMutation, } from '../../core/furnace-operation.js';
+import { assertFurnaceEngineReady } from '../../core/furnace-precondition.js';
+import { createRollbackJournal, recordCreatedDir, snapshotFile, } from '../../core/furnace-rollback.js';
 import { DEFAULT_LICENSE, getLicenseHeader } from '../../core/license-headers.js';
 import { InvalidArgumentError } from '../../errors/base.js';
 import { FurnaceError } from '../../errors/furnace.js';
-import { toError } from '../../utils/errors.js';
-import { pathExists, readText, writeText } from '../../utils/fs.js';
+import { ensureDir, pathExists, readText, writeText } from '../../utils/fs.js';
 import { intro, note, outro, warn } from '../../utils/logger.js';
 import { generateBrowserWindowXhtml, generateChromeDocCss, generateChromeDocFtl, generateChromeDocJs, generateChromeDocXhtml, jarIncMnEntryForChromeDoc, jarMnEntriesForChromeDoc, localeJarMnEntryForChromeDoc, localesFtlWildcardCapturesScaffoldedName, } from './chrome-doc-templates.js';
 import { chromeDocPackagingTestFileName, generateChromeDocPackagingManifest, generateChromeDocPackagingTest, } from './chrome-doc-tests.js';
@@ -189,7 +189,6 @@ async function performChromeDocMutations(args) {
         for (const dir of [contentDir, sharedThemeDir, localeDir]) {
             if (!(await pathExists(dir))) {
                 recordCreatedDir(journal, dir);
-                const { ensureDir } = await import('../../utils/fs.js');
                 await ensureDir(dir);
             }
         }
@@ -230,9 +229,9 @@ async function performChromeDocMutations(args) {
         // wildcard already pick up the scaffolded FTL automatically — appending
         // a per-file `locale/...` entry on top is at best dead weight and at
         // worst a build error when the fork has dropped the `% locale browser`
-        // registration the per-file entry depends on. The wildcard predicate
-        // is intentionally narrow: only `%browser/`-rooted globs that end in
-        // `*.ftl` count as a capture.
+        // registration the per-file entry depends on. The wildcard predicate is
+        // intentionally narrow: only `%browser/`-rooted globs ending in `*.ftl`
+        // count as a capture.
         if (await pathExists(localeJarMnPath)) {
             const existingLocaleJar = await readText(localeJarMnPath);
             if (localesFtlWildcardCapturesScaffoldedName(existingLocaleJar)) {
@@ -256,7 +255,6 @@ async function performChromeDocMutations(args) {
         if (args.withTests) {
             const testParentDir = `${args.binaryName}-xpcshell`;
             const testDir = join(args.engineDir, 'browser/base/content/test', testParentDir, args.name);
-            const { ensureDir } = await import('../../utils/fs.js');
             if (!(await pathExists(testDir))) {
                 recordCreatedDir(journal, testDir);
             }
@@ -274,20 +272,12 @@ async function performChromeDocMutations(args) {
         }
     }
     catch (error) {
-        // This body owns its rollback end to end, so tell the lifecycle wrapper
-        // not to restore the same journal again on the way out.
-        args.operationContext.markRolledBack();
-        try {
-            await restoreRollbackJournalOrThrow(journal, `Failed to scaffold chrome-doc "${args.name}"`);
-        }
-        catch (rollbackError) {
-            // Matches the seven sibling mutation sites: when the rollback itself
-            // fails the engine is in an unknown state, so leave a breadcrumb for
-            // `doctor --repair-furnace` and let the rollback error win.
-            await recordFurnaceRollbackFailure(args.projectRoot, 'chrome-doc-rollback', `chrome-doc "${args.name}": ${toError(rollbackError).message}`);
-            throw rollbackError;
-        }
-        throw error;
+        return await completeJournalRollback(args.operationContext, journal, error, {
+            projectRoot: args.projectRoot,
+            operation: 'chrome-doc-rollback',
+            failureMessage: `Failed to scaffold chrome-doc "${args.name}"`,
+            subject: `chrome-doc "${args.name}"`,
+        });
     }
     return written;
 }
@@ -303,18 +293,18 @@ export async function furnaceChromeDocCreateCommand(projectRoot, name, options =
     const forgeConfig = await loadConfig(projectRoot);
     const license = forgeConfig.license ?? DEFAULT_LICENSE;
     const engineDir = join(projectRoot, 'engine');
-    if (!(await pathExists(engineDir))) {
-        throw new FurnaceError('Engine directory not found. Run "fireforge download" first to scaffold a chrome-doc.');
-    }
+    await assertFurnaceEngineReady(projectRoot, {
+        engineMissingSuffix: ' to scaffold a chrome-doc.',
+    });
     const browserWindow = options.browserWindow ?? false;
     // The browser-window skeleton always carries its own titlebar markup and
     // chrome attributes; --no-titlebar only applies to the generic scaffold.
     const withTitlebar = browserWindow ? true : (options.titlebar ?? true);
     const withTests = options.withTests ?? false;
-    // Hint: when the scaffolded document is the configured token-host
-    // document (the fork's main browser window), the generic dialog-shaped
-    // scaffold is almost certainly wrong (0.34.0 field report: correct
-    // jar.mn registrations, wrong document body).
+    // Hint: when the scaffolded document is the configured token-host document
+    // (the fork's main browser window), the generic dialog-shaped scaffold is
+    // almost certainly wrong — correct jar.mn registrations, wrong document
+    // body.
     if (!browserWindow && (await furnaceConfigExists(projectRoot))) {
         try {
             const furnaceConfig = await loadFurnaceConfig(projectRoot);

package/dist/src/commands/furnace/create-browser-test.d.ts

@@ -1,9 +1,9 @@
 /**
  * Browser-chrome test scaffolding for `furnace create --with-tests`,
- * including the 0.34.0 `--test-dir` redirect and collision safety
- * (existing manifests are appended to; head.js and test implementations
- * are never overwritten). Split out of `create.ts` to keep that command
- * file within the per-file line budget.
+ * including the `--test-dir` redirect and collision safety (existing
+ * manifests are appended to; head.js and test implementations are never
+ * overwritten). Split out of `create.ts` to keep that command file within
+ * the per-file line budget.
  */
 import { type RollbackJournal } from '../../core/furnace-rollback.js';
 import type { ProjectLicense } from '../../types/config.js';

package/dist/src/commands/furnace/create-browser-test.js

@@ -1,15 +1,15 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
  * Browser-chrome test scaffolding for `furnace create --with-tests`,
- * including the 0.34.0 `--test-dir` redirect and collision safety
- * (existing manifests are appended to; head.js and test implementations
- * are never overwritten). Split out of `create.ts` to keep that command
- * file within the per-file line budget.
+ * including the `--test-dir` redirect and collision safety (existing
+ * manifests are appended to; head.js and test implementations are never
+ * overwritten). Split out of `create.ts` to keep that command file within
+ * the per-file line budget.
  */
 import { join } from 'node:path';
 import { recordCreatedDir, snapshotFile, } from '../../core/furnace-rollback.js';
 import { getLicenseHeader } from '../../core/license-headers.js';
-import { registerTestManifest } from '../../core/manifest-register.js';
+import { registerTestManifest } from '../../core/moz-manifest-register.js';
 import { InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
 import { ensureDir, pathExists, readText, writeText } from '../../utils/fs.js';
@@ -74,9 +74,9 @@ export async function scaffoldTestFiles(componentName, license, forgeConfig, pat
         : strippedName;
     const underscored = withoutBinaryPrefix.replace(/-/g, '_');
     const testFileName = `browser_${binaryName}_${underscored}.js`;
-    // --test-dir redirects the scaffold (0.34.0 field report: the hardcoded
-    // .../test/<binaryName>/ target collided with a test suite owned by a
-    // different patch). The manifest-registration name is the path below
+    // --test-dir redirects the scaffold: the hardcoded
+    // `.../test/<binaryName>/` target can collide with a test suite owned by a
+    // different patch. The manifest-registration name is the path below
     // browser/base/content/test/ (nested manifests are supported).
     const testDirRel = testDirOverride ?? `${TEST_SCAFFOLD_ROOT}${binaryName}`;
     const testDirName = testDirRel.slice(TEST_SCAFFOLD_ROOT.length);

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

@@ -2,13 +2,12 @@
  * MochiKit (chrome://mochikit) test-harness scaffolder for
  * `fireforge furnace create --test-style=mochikit`.
  *
- * Motivation: browser-chrome mochitests require a `tabbrowser` to exist in
- * the top-level chrome document. Forks with a bespoke chrome document
- * (e.g. `mybrowser.xhtml`) that deliberately omits tabbrowser cannot run
- * browser-chrome tests today. MochiKit tests load the component module
- * directly via `chrome://global/` and assert against `customElements`, so
- * they work against any fork that registers the upstream toolkit test
- * manifest tree — including those without a tabbrowser.
+ * Browser-chrome mochitests require a `tabbrowser` in the top-level chrome
+ * document, so forks with a bespoke chrome document that deliberately omits
+ * one cannot run them. MochiKit tests load the component module directly via
+ * `chrome://global/` and assert against `customElements`, so they work
+ * against any fork that registers the upstream toolkit test manifest tree —
+ * including those without a tabbrowser.
  */
 import { type RollbackJournal } from '../../core/furnace-rollback.js';
 import type { ProjectLicense } from '../../types/config.js';

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

@@ -3,13 +3,12 @@
  * MochiKit (chrome://mochikit) test-harness scaffolder for
  * `fireforge furnace create --test-style=mochikit`.
  *
- * Motivation: browser-chrome mochitests require a `tabbrowser` to exist in
- * the top-level chrome document. Forks with a bespoke chrome document
- * (e.g. `mybrowser.xhtml`) that deliberately omits tabbrowser cannot run
- * browser-chrome tests today. MochiKit tests load the component module
- * directly via `chrome://global/` and assert against `customElements`, so
- * they work against any fork that registers the upstream toolkit test
- * manifest tree — including those without a tabbrowser.
+ * Browser-chrome mochitests require a `tabbrowser` in the top-level chrome
+ * document, so forks with a bespoke chrome document that deliberately omits
+ * one cannot run them. MochiKit tests load the component module directly via
+ * `chrome://global/` and assert against `customElements`, so they work
+ * against any fork that registers the upstream toolkit test manifest tree —
+ * including those without a tabbrowser.
  */
 import { join } from 'node:path';
 import { recordCreatedDir, snapshotFile, } from '../../core/furnace-rollback.js';
@@ -41,8 +40,8 @@ export async function scaffoldMochikitTestFiles(componentName, license, paths, j
     const testFileName = mochikitTestFileName(componentName);
     const testFilePath = join(testDir, testFileName);
     if (await pathExists(testFilePath)) {
-        // Never clobber an existing test implementation (0.34.0 collision
-        // safety, matching the browser-chrome and xpcshell scaffolds).
+        // Never clobber an existing test implementation, matching the
+        // browser-chrome and xpcshell scaffolds.
         warn(`toolkit/content/tests/widgets/${testFileName} already exists — keeping the existing file.`);
     }
     else {

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

@@ -4,20 +4,19 @@
  * budget.
  */
 /**
- * Asserts that the just-written furnace.json contains the expected
- * custom component entry. The eval run's finding #9 observed a
- * scenario where `furnace create --allow-prefix-mismatch` reported
- * success and wrote the component files, but the subsequent
- * `furnace status` found `custom: {}` in furnace.json — an invariant
- * violation with no clear smoking gun in the code path. Local repros
- * do not trigger it, so the defensive readback is the safest recovery
- * contract we can offer: if the new entry is not visible on the next
- * load, throw a `FurnaceError` so the rollback journal restores the
- * pre-command state and the operator sees the failure instead of a
- * phantom success.
+ * Asserts that the just-written furnace.json contains the expected custom
+ * component entry.
+ *
+ * A `furnace create` that reports success and writes the component files
+ * while the next `furnace status` finds `custom: {}` is an invariant
+ * violation with no obvious smoking gun in the code path. This defensive
+ * readback is the recovery contract: if the new entry is not visible on the
+ * next load, throw a `FurnaceError` so the rollback journal restores the
+ * pre-command state and the operator sees the failure instead of a phantom
+ * success.
  *
  * @param projectRoot - Root of the FireForge project
- * @param componentName - Custom-element tag name that must be present
- *   in `config.custom` after the write. Throws when absent.
+ * @param componentName - Custom-element tag name that must be present in
+ *   `config.custom` after the write. Throws when absent.
  */
 export declare function assertCustomEntryPersisted(projectRoot: string, componentName: string): Promise<void>;

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

@@ -7,21 +7,20 @@
 import { loadFurnaceConfig } from '../../core/furnace-config.js';
 import { FurnaceError } from '../../errors/furnace.js';
 /**
- * Asserts that the just-written furnace.json contains the expected
- * custom component entry. The eval run's finding #9 observed a
- * scenario where `furnace create --allow-prefix-mismatch` reported
- * success and wrote the component files, but the subsequent
- * `furnace status` found `custom: {}` in furnace.json — an invariant
- * violation with no clear smoking gun in the code path. Local repros
- * do not trigger it, so the defensive readback is the safest recovery
- * contract we can offer: if the new entry is not visible on the next
- * load, throw a `FurnaceError` so the rollback journal restores the
- * pre-command state and the operator sees the failure instead of a
- * phantom success.
+ * Asserts that the just-written furnace.json contains the expected custom
+ * component entry.
+ *
+ * A `furnace create` that reports success and writes the component files
+ * while the next `furnace status` finds `custom: {}` is an invariant
+ * violation with no obvious smoking gun in the code path. This defensive
+ * readback is the recovery contract: if the new entry is not visible on the
+ * next load, throw a `FurnaceError` so the rollback journal restores the
+ * pre-command state and the operator sees the failure instead of a phantom
+ * success.
  *
  * @param projectRoot - Root of the FireForge project
- * @param componentName - Custom-element tag name that must be present
- *   in `config.custom` after the write. Throws when absent.
+ * @param componentName - Custom-element tag name that must be present in
+ *   `config.custom` after the write. Throws when absent.
  */
 export async function assertCustomEntryPersisted(projectRoot, componentName) {
     const persisted = await loadFurnaceConfig(projectRoot);

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

@@ -36,19 +36,18 @@ export declare function xpcshellTestFileName(name: string): string;
  * xpcshell cannot execute a component module that imports
  * `chrome://global/content/vendor/lit.all.mjs` — the Lit bundle touches
  * `window` at module-load time and the xpcshell harness has no `window`
- * global. Before 0.16.0 the scaffold called `ChromeUtils.importESModule`
- * on the component's MJS, which reliably failed with
- * `ReferenceError: window is not defined` for every Lit-based fork
- * component. FireForge's diagnostics then misrouted the failure to the
- * "stale build artifacts" branch, sending operators on a rebuild loop
- * that couldn't fix a runtime-environment incompatibility.
+ * global. A scaffold that calls `ChromeUtils.importESModule` on the
+ * component's MJS therefore fails with `ReferenceError: window is not
+ * defined` for every Lit-based fork component, and FireForge's diagnostics
+ * misroute that to the "stale build artifacts" branch, sending operators on
+ * a rebuild loop that cannot fix a runtime-environment incompatibility.
  *
- * The rewrite here mirrors the chrome-doc packaging test: XCurProcD is
+ * This template mirrors the chrome-doc packaging test instead: XCurProcD is
  * probed at a pair of candidate layouts (dist/bin/browser and the macOS
- * .app-bundle / ESR layout) to confirm the `.mjs` and `.css` files
- * landed where jar.mn promised. That's the assertion xpcshell CAN make.
- * Functional tests that need DOM/shadow-root/keyboard behaviour belong
- * in a browser-chrome mochitest — scaffolded via
+ * .app-bundle / ESR layout) to confirm the `.mjs` and `.css` files landed
+ * where jar.mn promised. That is the assertion xpcshell CAN make. Functional
+ * tests that need DOM/shadow-root/keyboard behaviour belong in a
+ * browser-chrome mochitest — scaffolded via
  * `fireforge furnace create --test-style browser-chrome`.
  */
 export declare function generateXpcshellTestContent(name: string, header: string): string;
@@ -67,26 +66,21 @@ export declare function mochikitTestFileName(name: string): string;
  * MochiKit tests load the component module directly via the global chrome
  * URI and assert that `customElements.get(<tag>)` returns a constructor.
  * They run on forks whose top-level chrome document lacks a `tabbrowser`
- * (the class of bug that forces `--xpcshell` for storage code) because
- * they do not traverse `URILoadingHelper.openLinkIn`.
+ * because they do not traverse `URILoadingHelper.openLinkIn`.
  *
- * The scaffold here is a smoke test — the component is defined and the
- * constructor is a function. Real UI assertions (render output, l10n
- * wiring, keyboard interactions) are intentionally left out because they
- * depend on the component's shape; operators can extend the test using
- * the same SimpleTest APIs upstream toolkit widgets (moz-button, etc.)
- * rely on.
+ * The scaffold is a smoke test — the component is defined and the
+ * constructor is a function. Real UI assertions (render output, l10n wiring,
+ * keyboard interactions) are left out because they depend on the
+ * component's shape; operators can extend the test using the same SimpleTest
+ * APIs upstream toolkit widgets rely on.
  *
  * The template deliberately omits `SimpleTest.waitForExplicitFinish()`.
- * `add_task` owns the test lifecycle: when every queued task resolves,
- * the task harness calls `SimpleTest.finish()` on its own. Combining
- * `waitForExplicitFinish()` with `add_task` *and* no explicit
- * `SimpleTest.finish()` inside the task body makes the harness wait
- * forever, which the 2026-04-21 eval run tripped into as an indefinite
- * hang on a `fireforge test --headless` against a scaffolded widget
- * test. Leaving `waitForExplicitFinish()` out matches the convention
- * upstream toolkit widget tests use (see `test_moz-button.html` and
- * siblings under `toolkit/content/tests/widgets/`).
+ * `add_task` owns the test lifecycle: when every queued task resolves, the
+ * task harness calls `SimpleTest.finish()` itself. Combining
+ * `waitForExplicitFinish()` with `add_task` and no explicit
+ * `SimpleTest.finish()` in the task body makes the harness wait forever —
+ * an indefinite hang on `fireforge test --headless`. Omitting it matches the
+ * convention upstream toolkit widget tests use.
  */
 export declare function generateMochikitTestContent(name: string): string;
 /**