@hominis/fireforge 0.33.0 → 0.34.1

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 0.34.0
+
+- Reworked the macOS resource-monitor (psutil) crash mitigation to an **in-process guard FireForge owns on its mach dispatches**: a `fireforge_mach_guard.pth` + module pair is installed directly into every discovered mach virtualenv site-packages (objdir `_virtualenvs` and the `~/.mozbuild` state dir) before each dispatch, because mach's venv re-exec drops `PYTHONPATH` and the 0.33.0 `sitecustomize.py` route never loaded (the env-var shim is retained only for the pre-venv bootstrap phase). The guard now covers the whole crash family: `psutil.virtual_memory`/`swap_memory`/`cpu_percent`/`cpu_times`/`disk_io_counters` are wrapped module-wide (which also covers the direct `psutil.virtual_memory()` call in `mozbuild.base._run_make`), and `SystemResourceMonitor` **construction** is guarded via an import hook that pre-populates `poll_interval` and degrades a partially-constructed monitor to a no-op — so the `AttributeError: ... poll_interval` variant can no longer escape a polling-only patch.
+- Routed every mach build dispatch — plain `fireforge build`, `build --ui` (`mach build faster`), and the pre-test build step of `fireforge test --build` — through one protected path (`runProtectedMachBuild`) with a **uniform recognized-crash retry budget** (default 2 retries, matching `--harness-retries`; the pre-test step forwards the operator's `--harness-retries` value). Each retry spawns a fresh mach process AND re-installs the guard (re-discovering venvs), so a venv materialized by a crashed first attempt is guarded on the next one instead of every retry dying on the same wedged state. Non-crash build failures are never retried; exhausted budgets surface the crash shape and evidence line above the regular diagnostics. The suite-specific test dispatches (`mach test` / `xpcshell-test` / `mochitest`) install the same guard.
+- Investigated the field incident where a failed pre-test build was followed by a ~64-minute full rebuild: FireForge's protected path performs **no configure/clobber beyond what `mach build faster` itself does** (retries never re-run `prepareBuildEnvironment`/`mach configure`; there is no fallback-to-full-build in FireForge). The pre-test build now also passes the previous build baseline into `prepareBuildEnvironment` exactly like `fireforge build` does, so auto-configure runs under identical conditions on both paths instead of diverging.
+- Fixed the degraded-psutil fallback crashing mozsystemmonitor on the fallback itself (downstream report: `TypeError: '_DegradedReading' object is not subscriptable` from `_build_meta`'s `psutil.virtual_memory()[0]`, aborting `mach mochitest` at startup with zero `TEST-START` lines, and `_collect failed: '_DegradedReading' object is not iterable`). The guard's degraded reading is now a **real duck type of psutil's namedtuple results**: each wrapped function degrades to a zeroed instance of psutil's own result namedtuple (`svmem`/`sswap`/`scputimes`/`sdiskio`, resolved via `getattr` without touching the failing syscall), falling back to an extended `_DegradedReading` that supports subscripting, iteration, `len()`, `_fields` (svmem field order), and `_asdict()`. `cpu_percent` degrades to a plain `0.0` float (callers do arithmetic on it), and `disk_io_counters` deliberately degrades to a zeroed struct rather than `None`. Runtime-verified by new python3-executed regression tests covering a mozsystemmonitor-style `_build_meta`/`_collect` sequence against a degraded host.
+- Taught the harness-crash classifier the two `_DegradedReading` crash signatures (`object is not subscriptable` / `object is not iterable`), so a startup abort with zero `TEST-START` lines from this family classifies as crash-not-failure and retries; the `_collect failed: '_DegradedReading' ...` evidence line is exempted from the noise-stripping that otherwise drops `_collect failed` degradation chatter, while a completed green summary still vetoes the classification.
+- Fixed the sharded/retry crash classifier marking fully green runs as `CRASH (N attempts)`: a completed green embedded summary (a `TEST_START`/`TEST-START` execution signal, `Unexpected results: 0`, and `SUITE_END`) now **vetoes** signature-based crash classification for that attempt, and resource-monitor degradation lines (`UserWarning: psutil failed to run: ...`, `_collect failed: ...`, FireForge's own degradation notice) plus mach's caught telemetry tracebacks are stripped from crash evidence entirely. Exit codes follow the corrected verdict: a run whose every shard is green exits 0, and a non-sharded (`--no-shard`) run whose embedded summary completed green exits 0 even when mach's own exit code went non-zero on harness noise (a note explains the override) — parsing embedded summaries by hand is no longer necessary. Runs with a non-zero unexpected count or real `TEST-UNEXPECTED-*` lines still fail, and the post-green shutdown re-entry shape still classifies as a crash.
+- Fixed `fireforge test <directory>` dispatching xpcshell-only directories to the mochitest runner ("could not find any mochitests under the following test path(s)"): the manifest walk now starts at the directory itself, so a directory whose own manifest is an `xpcshell.toml` dispatches to `mach xpcshell-test` just like an explicit `test_*.js` path.
+- Added `fireforge register --create-manifest`: registering a module under a directory with no `moz.build` now scaffolds the directory manifest (MPL-header + `EXTRA_JS_MODULES.<namespace>` list) and wires the parent `DIRS` chain up to the nearest existing moz.build (creating intermediates); without the flag the "Manifest not found" error names it. Also added an **xpcshell test-file pattern** (`**/test_*.js` outside `browser/base/content/test/`) that inserts the `["test_*.js"]` section into the directory's `xpcshell.toml` in mozbuild sort order — or creates the manifest and wires `XPCSHELL_TESTS_MANIFESTS` with `--create-manifest` — and extended the browser-chrome manifest rule to fork-owned `browser.toml` manifests at **arbitrary depth** under `browser/base/content/test/` (previously one level only).
+- Improved export ergonomics three ways: (1) `re-export <patch> --files` now accepts the `export`-style space-separated path shape — path-shaped extra positionals are folded into the file list with a notice, and the "operates on exactly one target patch" error explains both accepted forms (the dry-run "removed files (N; become unmanaged)" preview is unchanged); (2) directory exports auto-exclude files already owned by other patches, printing a per-file `Excluding <file> ... (owned by <patch>)` notice and a `re-export --files` pointer instead of hitting the duplicate-new-file-creation refusal at placement lint (whose message now recommends an explicit file list rather than `--force-unsafe`; explicitly named files are never auto-excluded); (3) `export --name 203-ui-foo --category ui` no longer produces `203-ui-203-ui-foo.patch` — a leading `NNN-<category>-` prefix matching the selected category is stripped from the name before the filename builders prepend order and category.
+- Fixed `furnace deploy` leaving a stale toolkit `jar.mn` line after a component helper file rename (every build then failed at packaging with "File ... not found"): entry removal now keys on the `(widgets/<tag>/...)` source-mapping segment so ALL of a component's lines are removed regardless of basename, and the remove-then-re-add reconciliation therefore prunes renamed/removed helpers. `furnace validate` gained a `stale-jar-registration` error for registration lines pointing at files that no longer exist (`--fix` prunes them), and `doctor` gained a "Furnace jar.mn registrations" check (`--repair-furnace` prunes) — both previously reported success while the stale line survived.
+- Added `furnace scan --track`, which persists every discovered untracked component into the `stock` section of furnace.json non-interactively (same locked, rollback-journaled write path as the interactive confirm flow). Scan's help and its non-interactive output now state that scan is report-only by default and where the inventory is consumed, ending the report-persist-nothing-explain-nothing behavior.
+- Added `furnace chrome-doc create --browser-window`, a browser.xhtml-like scaffold for the document that ships as the fork's main browser window: `<html id="main-window">` root with the `windowtype="navigator:browser"`/`chromehidden`/geometry-`persist` attributes platform C++ reads before scripts run, while keeping the generic scaffold's bootstrap wiring, sentinel, and (already-correct) jar.mn registrations. When the target document matches a configured `tokenHostDocuments` entry and the flag was not passed, create warns that the browser-window variant is probably intended.
+- Added `furnace create --test-dir <dir>` to redirect the `--with-tests` scaffold (browser-chrome and xpcshell styles) to any engine-relative directory under `browser/base/content/test/` — nested manifests register correctly — and made all test scaffolds collision-safe: existing `browser.toml`/`xpcshell.toml`/`chrome.toml` manifests are appended to (with a shared-manifest notice) instead of scaffolded over, and existing `head.js`/test implementation files are never overwritten.
+
 ## 0.33.0
 
 - Fixed `furnace deploy`/`apply` to prune a dangling per-widget locale `jar.mn` entry for a `localized: true` widget that uses the `sharedFtl` browser-bundle convention. A stale `locale/@AB_CD@/toolkit/global/<name>.ftl` line (written by an older FireForge) pointed at a `.ftl` that never exists, so `mach build` failed hard (`Cannot find toolkit/global/<name>.ftl`) and blocked every build; apply now drops that per-widget line idempotently while leaving the shared bundle's own line untouched.

package/dist/src/commands/build.js

@@ -6,6 +6,7 @@ import { readBuildBaseline, writeBuildBaseline } from '../core/build-baseline.js
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { attemptMozinfoRewrite, build, buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, hasRunnableBundle, runMach, withBuildLock, } from '../core/mach.js';
+import { buildHarnessCrashMessage } from '../core/test-harness-crash.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { toError } from '../utils/errors.js';
@@ -260,7 +261,14 @@ export async function buildCommand(projectRoot, options) {
     if (result.exitCode !== 0) {
         error(`Build failed after ${timeStr}`);
         const machCommand = options.ui ? 'mach build faster' : 'mach build';
-        throw new BuildError(buildFailureDiagnostics(result, paths.engine, buildCheck.objDir, machCommand), machCommand);
+        // When the protected dispatch exhausted its recognized-crash retry
+        // budget, lead with the environmental-crash explanation so the
+        // operator does not read a resource-monitor traceback as a build
+        // regression.
+        const crashPreamble = result.crashSignature
+            ? `${buildHarnessCrashMessage(result.crashSignature, result.attempts, machCommand)}\n\n`
+            : '';
+        throw new BuildError(crashPreamble + buildFailureDiagnostics(result, paths.engine, buildCheck.objDir, machCommand), machCommand);
     }
     // Tool-managed branding edits that land on `browser/moz.configure`
     // before the build cause mach's post-build guard to print one of two

package/dist/src/commands/doctor-furnace-jar.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `doctor` check for stale furnace jar.mn registrations (0.34.0 field
+ * report): a component-file rename left the old toolkit jar.mn line
+ * pointing at the deleted file, every build failed at packaging, and
+ * `doctor --repair-furnace` reported success without pruning. Split out
+ * of `doctor-furnace.ts` to keep that file within the line budget.
+ */
+import type { DoctorCheckDefinition } from './doctor-check-core.js';
+/**
+ * "Furnace jar.mn registrations" check: detect widget registration lines
+ * pointing at component files that no longer exist in the workspace
+ * (typically left by a rename under an older FireForge). These break
+ * `mach build` at packaging; `--repair-furnace` prunes them (0.34.0 field
+ * report: doctor --repair-furnace reported success without pruning).
+ */
+export declare const furnaceStaleJarRegistrationCheck: DoctorCheckDefinition;

package/dist/src/commands/doctor-furnace-jar.js

@@ -0,0 +1,47 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `doctor` check for stale furnace jar.mn registrations (0.34.0 field
+ * report): a component-file rename left the old toolkit jar.mn line
+ * pointing at the deleted file, every build failed at packaging, and
+ * `doctor --repair-furnace` reported success without pruning. Split out
+ * of `doctor-furnace.ts` to keep that file within the line budget.
+ */
+import { getFurnacePaths } from '../core/furnace-config.js';
+import { findStaleJarMnEntries, pruneStaleJarMnEntries } from '../core/furnace-registration.js';
+import { toError } from '../utils/errors.js';
+import { failure, ok, warning } from './doctor-check-core.js';
+/**
+ * "Furnace jar.mn registrations" check: detect widget registration lines
+ * pointing at component files that no longer exist in the workspace
+ * (typically left by a rename under an older FireForge). These break
+ * `mach build` at packaging; `--repair-furnace` prunes them (0.34.0 field
+ * report: doctor --repair-furnace reported success without pruning).
+ */
+export const furnaceStaleJarRegistrationCheck = {
+    name: 'Furnace jar.mn registrations',
+    dependsOn: ['Furnace configuration'],
+    skipIf: (ctx) => !ctx.furnaceConfigExists || !ctx.furnaceConfig || !ctx.engineExists,
+    run: async (ctx) => {
+        const config = ctx.furnaceConfig;
+        if (!config)
+            return [];
+        const furnacePaths = getFurnacePaths(ctx.projectRoot);
+        const managedTags = Object.keys(config.custom);
+        const stale = await findStaleJarMnEntries(ctx.paths.engine, furnacePaths.customDir, managedTags);
+        if (stale.length === 0) {
+            return ok('Furnace jar.mn registrations');
+        }
+        const staleList = stale.map((entry) => `${entry.tagName}/${entry.fileName}`).join(', ');
+        if (!ctx.options.repairFurnace) {
+            return warning('Furnace jar.mn registrations', `jar.mn carries ${stale.length} registration line${stale.length === 1 ? '' : 's'} pointing at removed component file${stale.length === 1 ? '' : 's'} (${staleList}). mach build will fail at packaging ("File ... not found").`, 'Run "fireforge doctor --repair-furnace" (or "fireforge furnace validate --fix") to prune the stale lines.');
+        }
+        try {
+            const pruned = await pruneStaleJarMnEntries(ctx.paths.engine, furnacePaths.customDir, managedTags);
+            return warning('Furnace jar.mn registrations', `Pruned ${pruned.length} stale jar.mn registration line${pruned.length === 1 ? '' : 's'} (${staleList}).`);
+        }
+        catch (err) {
+            return failure('Furnace jar.mn registrations', `Could not prune stale jar.mn lines: ${toError(err).message}`, 'Remove the stale lines from toolkit/content/jar.mn manually and retry.');
+        }
+    },
+};
+//# sourceMappingURL=doctor-furnace-jar.js.map

package/dist/src/commands/doctor-furnace.js

@@ -10,6 +10,7 @@ import { validateAllComponents } from '../core/furnace-validate.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { failure, ok, warning } from './doctor-check-core.js';
+import { furnaceStaleJarRegistrationCheck } from './doctor-furnace-jar.js';
 import { furnaceManifestSyncCheck } from './doctor-furnace-manifest-sync.js';
 const ENGINE_REPAIRABLE_OPERATIONS = [
     'preview-teardown',
@@ -503,6 +504,7 @@ const furnaceStaleLockCheck = {
 export const FURNACE_DOCTOR_CHECKS = [
     furnaceConfigurationCheck,
     furnaceStateConsistencyCheck,
+    furnaceStaleJarRegistrationCheck,
     furnaceEnginePathsCheck,
     furnaceStorybookCheck,
     furnaceStaleLockCheck,

package/dist/src/commands/export-flow.js

@@ -227,7 +227,10 @@ export async function commitPlacementExport(input) {
         }
         const conflicts = await projectPlacementForLint(input.patchesDir, currentPlan, input.diff);
         if (conflicts && input.unsafeOverride !== true) {
-            throw new InvalidArgumentError(`Refusing to run export: ${conflicts.reason}. Pass --force-unsafe to override.`, '--force-unsafe');
+            throw new InvalidArgumentError(`Refusing to run export: ${conflicts.reason}. ` +
+                'If the conflict names files owned by another patch (e.g. duplicate-new-file-creation), ' +
+                're-run the export with an explicit file list that leaves those files with their owner — ' +
+                'do NOT bypass with --force-unsafe. Pass --force-unsafe only for a reviewed placement conflict.', '--force-unsafe');
         }
         const originalManifest = await loadPatchesManifest(input.patchesDir);
         if (originalManifest !== null) {

package/dist/src/commands/export-placement-gate.js

@@ -98,7 +98,10 @@ export async function gatePlacementPlan(args) {
     }
     else if (conflicts && options.forceUnsafe !== true) {
         s.stop();
-        throw new InvalidArgumentError(`Refusing to run export: ${conflicts.reason}. Pass --force-unsafe to override.`, '--force-unsafe');
+        throw new InvalidArgumentError(`Refusing to run export: ${conflicts.reason}. ` +
+            'If the conflict names files owned by another patch (e.g. duplicate-new-file-creation), ' +
+            're-run the export with an explicit file list that leaves those files with their owner — ' +
+            'do NOT bypass with --force-unsafe. Pass --force-unsafe only for a reviewed placement conflict.', '--force-unsafe');
     }
     return placementPlan;
 }

package/dist/src/commands/export.js

@@ -12,6 +12,7 @@ import { getModifiedFilesInDir, getUntrackedFiles, getUntrackedFilesInDir, } fro
 import { extractAffectedFiles } from '../core/patch-apply.js';
 import { commitExportedPatch } from '../core/patch-export.js';
 import { buildPatchQueueContext } from '../core/patch-lint.js';
+import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { buildPatchSourceMetadata } from '../core/patch-source-metadata.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
@@ -25,6 +26,7 @@ import { gatePlacementPlan, patchMetadataExtras } from './export-placement-gate.
 import { autoFixLicenseHeaders, promptExportPatchMetadata, runPatchLint, runSupersedeAndOverlapGates, } from './export-shared.js';
 async function collectExportFiles(paths, files) {
     const collectedFiles = new Set();
+    const fromDirectory = new Set();
     let fileStatuses;
     let untrackedFiles;
     // Accept both repo-root-relative (`engine/browser/...`) and engine-relative
@@ -49,10 +51,14 @@ async function collectExportFiles(paths, files) {
             const dirPath = inputPath.endsWith('/') ? inputPath.slice(0, -1) : inputPath;
             const modifiedFiles = await getModifiedFilesInDir(paths.engine, dirPath);
             const dirUntrackedFiles = await getUntrackedFilesInDir(paths.engine, dirPath);
-            for (const f of modifiedFiles)
+            for (const f of modifiedFiles) {
                 collectedFiles.add(f);
-            for (const f of dirUntrackedFiles)
+                fromDirectory.add(f);
+            }
+            for (const f of dirUntrackedFiles) {
                 collectedFiles.add(f);
+                fromDirectory.add(f);
+            }
         }
         else {
             if (inputPath.endsWith('/')) {
@@ -72,9 +78,53 @@ async function collectExportFiles(paths, files) {
                 }
             }
             collectedFiles.add(inputPath);
+            // A file named explicitly always stays in the export set, even if a
+            // directory argument also swept it up.
+            fromDirectory.delete(inputPath);
         }
     }
-    return [...collectedFiles].sort();
+    return { files: [...collectedFiles].sort(), fromDirectory };
+}
+/**
+ * Auto-excludes directory-derived files already owned by OTHER patches
+ * (0.34.0 field report): a directory export used to plan files owned by
+ * earlier patches into the new patch, and the duplicate-new-file-creation
+ * refusal surfaced only at placement lint, suggesting --force-unsafe —
+ * the wrong tool for "leave that file with its owner". Explicitly named
+ * files are never excluded (the overlap gates still confront the operator
+ * with those). Prints one notice per exclusion.
+ */
+async function excludeFilesOwnedByOtherPatches(patchesDir, collected) {
+    if (collected.fromDirectory.size === 0)
+        return collected.files;
+    const manifest = await loadPatchesManifest(patchesDir);
+    if (!manifest)
+        return collected.files;
+    const owners = new Map();
+    for (const patch of manifest.patches) {
+        for (const file of patch.filesAffected) {
+            if (!owners.has(file))
+                owners.set(file, patch.filename);
+        }
+    }
+    const kept = [];
+    let excludedCount = 0;
+    for (const file of collected.files) {
+        const owner = collected.fromDirectory.has(file) ? owners.get(file) : undefined;
+        if (owner !== undefined) {
+            info(`Excluding ${file} from the directory export (owned by ${owner})`);
+            excludedCount += 1;
+        }
+        else {
+            kept.push(file);
+        }
+    }
+    if (excludedCount > 0) {
+        info(`Excluded ${excludedCount} file${excludedCount === 1 ? '' : 's'} owned by other patches. ` +
+            'Use "fireforge re-export <patch> --files ..." to update the owning patch, or name the ' +
+            'file explicitly in this export to move it deliberately.');
+    }
+    return kept;
 }
 async function generatePatchDiff(engineDir, allFiles) {
     const diffs = [];
@@ -125,7 +175,9 @@ async function prepareExport(projectRoot, files, options) {
     if (!(await isGitRepository(paths.engine))) {
         throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
     }
-    let allFiles = await collectExportFiles(paths, files);
+    const collected = await collectExportFiles(paths, files);
+    let allFiles = await excludeFilesOwnedByOtherPatches(paths.patches, collected);
+    const ownershipExclusions = collected.files.length - allFiles.length;
     // Filter out furnace-managed files when --exclude-furnace is set
     if (options.excludeFurnace) {
         const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
@@ -140,6 +192,11 @@ async function prepareExport(projectRoot, files, options) {
     }
     if (allFiles.length === 0) {
         const pathList = files.join(', ');
+        if (ownershipExclusions > 0) {
+            throw new GeneralError(`Every changed file under "${pathList}" is already owned by another patch ` +
+                '(see the exclusions above).\n\n' +
+                'Use "fireforge re-export <patch> --files ..." to refresh the owning patch instead.');
+        }
         throw new GeneralError(`Paths "${pathList}" have no changes to export.\n\n` +
             'Run "fireforge status" to see modified files.');
     }

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

@@ -40,6 +40,26 @@
  *   the README "Platform module compatibility" section for the pattern.
  */
 export declare function generateChromeDocXhtml(name: string, withTitlebar: boolean, license: string): string;
+/**
+ * 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:
+ *
+ * - `<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;
+ * - 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.
+ */
+export declare function generateBrowserWindowXhtml(name: string, license: string): string;
 /**
  * ESM bootstrap script for the chrome document.
  *

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

@@ -98,6 +98,58 @@ export function generateChromeDocXhtml(name, withTitlebar, license) {
 </window>
 `;
 }
+/**
+ * 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:
+ *
+ * - `<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;
+ * - 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.
+ */
+export function generateBrowserWindowXhtml(name, license) {
+    return `<?xml version="1.0"?>
+<!-- SPDX-License-Identifier: ${license} -->
+<html
+    xmlns="http://www.w3.org/1999/xhtml"
+    xmlns:xul="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
+    id="main-window"
+    windowtype="navigator:browser"
+    customtitlebar="true"
+    chromehidden=""
+    width="1024"
+    height="640"
+    persist="screenX screenY width height sizemode"
+    ${FURNACE_CHROME_DOC_SENTINEL}="${name}"
+    role="application">
+  <head>
+    <meta charset="utf-8" />
+    <title data-l10n-id="${name}-window-title"></title>
+    <link rel="localization" href="browser/${name}.ftl" />
+    <link rel="stylesheet" href="chrome://global/skin/global.css" />
+    <link rel="stylesheet" href="chrome://browser/content/${name}-chrome.css" />
+    <script src="chrome://global/content/customElements.js"></script>
+    <script src="chrome://browser/content/${name}.js"></script>
+  </head>
+  <body>
+    <hbox class="titlebar-buttonbox-container">
+      <hbox class="titlebar-buttonbox"></hbox>
+    </hbox>
+    <main id="${name}-main"></main>
+  </body>
+</html>
+`;
+}
 /**
  * ESM bootstrap script for the chrome document.
  *

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

@@ -37,6 +37,16 @@ export interface FurnaceChromeDocCreateOptions {
     withTests?: boolean;
     /** Print the scaffold plan without writing files. */
     dryRun?: boolean;
+    /**
+     * Emit the browser.xhtml-like MAIN-WINDOW skeleton (`<html
+     * id="main-window">` with the `windowtype`/`chromehidden`/`persist`
+     * root attributes platform C++ reads before scripts run) instead of
+     * the generic dialog-shaped `<window>` document. Use for the document
+     * configured as the fork's main browser window
+     * (`tokenHostDocuments[0]` / the BROWSER_CHROME_URL target). Implies
+     * the titlebar markup.
+     */
+    browserWindow?: boolean;
 }
 /**
  * Validates a chrome-doc name. Lowercase ASCII, optional hyphens, no

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

@@ -18,14 +18,15 @@
  */
 import { join } from 'node:path';
 import { loadConfig } from '../../core/config.js';
+import { furnaceConfigExists, loadFurnaceConfig } from '../../core/furnace-config.js';
 import { runFurnaceMutation } from '../../core/furnace-operation.js';
 import { createRollbackJournal, recordCreatedDir, restoreRollbackJournalOrThrow, 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 { pathExists, readText, writeText } from '../../utils/fs.js';
-import { intro, note, outro } from '../../utils/logger.js';
-import { generateChromeDocCss, generateChromeDocFtl, generateChromeDocJs, generateChromeDocXhtml, jarIncMnEntryForChromeDoc, jarMnEntriesForChromeDoc, localeJarMnEntryForChromeDoc, localesFtlWildcardCapturesScaffoldedName, } from './chrome-doc-templates.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';
 /** Chrome-doc name shape: lowercase ASCII, optional hyphens, no leading digit. */
 const CHROME_DOC_NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
@@ -196,7 +197,9 @@ async function performChromeDocMutations(args) {
             throw new FurnaceError(`${args.name}.xhtml already exists at ${xhtmlPath}. Remove it or choose a different name.`);
         }
         await snapshotFile(journal, xhtmlPath);
-        await writeText(xhtmlPath, generateChromeDocXhtml(args.name, args.withTitlebar, args.license));
+        await writeText(xhtmlPath, args.browserWindow
+            ? generateBrowserWindowXhtml(args.name, args.license)
+            : generateChromeDocXhtml(args.name, args.withTitlebar, args.license));
         written.push(`browser/base/content/${args.name}.xhtml`);
         const jsPath = join(contentDir, `${args.name}.js`);
         await snapshotFile(journal, jsPath);
@@ -290,8 +293,31 @@ export async function furnaceChromeDocCreateCommand(projectRoot, name, options =
     if (!(await pathExists(engineDir))) {
         throw new FurnaceError('Engine directory not found. Run "fireforge download" first to scaffold a chrome-doc.');
     }
-    const withTitlebar = options.titlebar ?? true;
+    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).
+    if (!browserWindow && (await furnaceConfigExists(projectRoot))) {
+        try {
+            const furnaceConfig = await loadFurnaceConfig(projectRoot);
+            const targetDocPath = `browser/base/content/${name}.xhtml`;
+            if (furnaceConfig.tokenHostDocuments?.includes(targetDocPath)) {
+                warn(`${targetDocPath} is a configured token-host document (the fork's main browser window). ` +
+                    'The default scaffold emits a generic dialog-shaped <window> document; you probably ' +
+                    'want "fireforge furnace chrome-doc create --browser-window" for the ' +
+                    '<html id="main-window"> skeleton platform C++ expects.');
+            }
+        }
+        catch {
+            // A broken furnace.json must not block chrome-doc scaffolding; the
+            // hint is best-effort.
+        }
+    }
     const plan = await buildChromeDocPlan({
         engineDir,
         name,
@@ -310,6 +336,7 @@ export async function furnaceChromeDocCreateCommand(projectRoot, name, options =
         engineDir,
         withTitlebar,
         withTests,
+        browserWindow,
         binaryName: forgeConfig.binaryName,
         operationContext: ctx,
     }));

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

@@ -0,0 +1,30 @@
+/**
+ * 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.
+ */
+import { type RollbackJournal } from '../../core/furnace-rollback.js';
+import type { ProjectLicense } from '../../types/config.js';
+import type { ResolvedTestStyle } from '../../types/furnace.js';
+/**
+ * Validates the `--test-dir` option against the resolved test style before
+ * any writes. Mochikit lives in the upstream toolkit/content/tests/widgets
+ * tree, so a redirect makes no sense there.
+ */
+export declare function resolveValidatedTestDir(rawTestDir: string | undefined, testStyle: ResolvedTestStyle): string | undefined;
+/**
+ * Normalizes and validates a `--test-dir` override: engine-relative,
+ * under `browser/base/content/test/` (so manifest registration keeps
+ * working). Returns the normalized engine-relative directory.
+ */
+export declare function resolveTestDirOverride(raw: string): string;
+/**
+ *
+ */
+export declare function scaffoldTestFiles(componentName: string, license: ProjectLicense, forgeConfig: {
+    binaryName: string;
+}, paths: {
+    engine: string;
+}, journal?: RollbackJournal, testDirOverride?: string): Promise<string[]>;