@hominis/fireforge 0.15.3 → 0.15.5

package/CHANGELOG.md

@@ -38,7 +38,11 @@
 
 ### Build audit
 
-- `fireforge build` now runs a warn-only post-build dist-tree audit after a successful mach build. The audit diffs engine-relative paths touched since the last successful build (stored as `.fireforge/last-build.json`) against the dist bundle, and warns per file that is packageable-by-convention (`.js`/`.mjs`/`.css`/`.ftl`/`.xhtml`/`app/profile/…`) but has no matching artifact, or whose dist mtime is older than the source. Surfaces the class of bug where a new pref file or widget is edited but never registered in `moz.build` / `jar.mn` / `package-manifest.in` — the 2026-04-18 `hominis.js` pref-file incident is the motivating case. The audit is warn-only and never fails a successful build.
+- `fireforge build` now runs a warn-only post-build dist-tree audit after a successful mach build. The audit diffs engine-relative paths touched since the last successful build (stored as `.fireforge/last-build.json`) against the dist bundle, and warns per file that is packageable-by-convention (`.js`/`.mjs`/`.css`/`.ftl`/`.xhtml`/`app/profile/…`) but has no matching artifact, or whose dist mtime is older than the source. Surfaces the class of bug where a new pref file or widget is edited but never registered in `moz.build` / `jar.mn` / `package-manifest.in`.
+- Build-system inputs (`jar.mn`, `moz.build`, `moz.configure`, `Makefile.in`, `mozbuild.in`) are now excluded from the audit's "must appear in dist/" check. They are consumed by the build to produce chrome registrations / make targets but never themselves ship, so every edit produced a guaranteed false positive — and worse, when an unrelated upstream `moz.build` coincidentally existed elsewhere in the bundle (e.g. `<App>.app/Contents/moz.build`) the audit reported "source is newer than packaged artifact" against two completely unrelated files. The exclusion list lives next to `PACKAGEABLE_EXTENSIONS` in `src/core/build-audit.ts`.
+- Same-basename collisions in `dist/` are now disambiguated by trailing-segment overlap: a branding override at `engine/browser/branding/<name>/content/aboutDialog.css` (which ships at `chrome/<area>/content/branding/aboutDialog.css`) no longer gets matched against the unrelated upstream `chrome/<area>/content/browser/aboutDialog.css`. The scorer rewards candidates whose path contains meaningful intermediate segments from the source (e.g. the `branding` segment) so re-rooted artifacts win over coincidentally-named ones. Generic segments like `content` / `chrome` / `bin` do not count toward the bonus to avoid breaking ties on noise.
+- Test sources (anything under `/test(s)/`, plus `browser_*.js` / `test_*.js` / `xpcshell.toml` / `browser.ini`) are now resolved against the `_tests/` tree under the active `obj-*` directory instead of `dist/`. Mochitest and xpcshell harnesses copy registered tests under `_tests/testing/...`, never into the packaged bundle, so the previous dist-only walk false-flagged every registered test as "missing packaged artifact". Misses still warn — but they now point at `_tests/`, directing the operator to `BROWSER_CHROME_MANIFESTS` / `XPCSHELL_TESTS_MANIFESTS` instead of `package-manifest.in`.
+- Files inside an `if CONFIG[…]:` block in their owning `moz.build` are now skipped on hosts where the gate evaluates off (Windows-only stubinstaller CSS on a macOS build, Darwin-only artwork on Linux, etc.). The detection walks up from the source file to the closest `moz.build`, scans for the basename inside a Python-style indented `if CONFIG[…]:` block, and matches the gate against the host platform via `getPlatform()`. Negation expressions (`!= "WINNT"`, `not CONFIG[…]`) are conservatively NOT treated as single-OS gates, so we never wrongly suppress a warning for a file that should ship on the current host. Lives in the new `src/core/build-audit-platform.ts`.
 - Ends every build with a `Packaged: N updated, M stale, K missing, S skipped` summary so operators can distinguish a fast-because-incremental build from a fast-because-silently-skipped one without a post-build `find`.
 - `fireforge build` auto-runs `mach configure` before the mach build step when any `moz.build`, `moz.configure`, or `Makefile.in` changed since the last successful build. Prevents the stale-backend trap where an incremental build skips work against a recursive-make backend that no longer matches the source tree. Emits a `Backend config changed; running mach configure first...` banner so the extra step is visible, and continues the build even if configure exits non-zero.
 - Mach build failures with known-cryptic mozbuild errors now print actionable hints. First entry in the table: `mozbuild.preprocessor.Preprocessor.Error: no preprocessor directives found` prints `Use JS_PREFERENCE_FILES instead, or add at least one #filter / #expand directive to the file.` The hint table lives in `src/core/mach-error-hints.ts` and is extensible — new cryptic errors we diagnose get one-line hints added without touching the build wrapper.
@@ -47,6 +51,11 @@
 
 - `fireforge lint --since <git-rev>` tags each lint issue as `[introduced]` (file touched in the diff since `<git-rev>`) or `[cumulative]` (pre-existing patch-state drift). Output gains the tag prefix and the summary line splits counts (e.g. `Lint: 2 introduced error(s), 0 introduced warning(s); 5 cumulative error(s), 1 cumulative warning(s)`). Exit code semantics are unchanged — an introduced OR cumulative error still fails lint — but triage of "is the diff I just produced clean?" no longer requires mentally subtracting pre-existing noise from every report. Without `--since` the output is unchanged.
 
+### Fork chrome-doc assumptions
+
+- `fireforge doctor`'s `Furnace engine paths` check now reads `furnace.json.tokenHostDocuments` instead of hardcoding `browser/base/content/browser.xhtml`. Forks that replaced the stock chrome document were emitting a permanent "browser.xhtml missing" warning every doctor run; reusing the same field the `missing-token-link` validator already consumes means a fork configures chrome-doc paths once and both checks agree. Defaults to `['browser/base/content/browser.xhtml']` when unset — behaviour is unchanged for forks that ship the stock chrome document.
+- `fireforge wire --dom` no longer hardcodes `browser/base/content/browser.xhtml` as the target chrome document. The target now resolves in this order: explicit `--target <path>` flag → first entry of `furnace.json.tokenHostDocuments` → upstream `browser/base/content/browser.xhtml`. Forks that replaced browser.xhtml were getting a cryptic "could not find insertion point in browser.xhtml" error that read like a FireForge bug; the resolved path now propagates into the dry-run plan, the success message, and the insertion-failure error so the actual target is surfaced. When the resolved target does not exist on disk, wire fails up-front with a pointer to `tokenHostDocuments` / `--target` rather than blowing up in the AST pass. The `addDomFragment` core now computes the `#include` directive relative to the target's own directory instead of a hardcoded `browser/base/content/`, so a target that lives elsewhere in the engine tree gets a correctly resolved include path.
+
 ### Furnace chrome-doc
 
 - New `furnace chrome-doc create <name>` subcommand scaffolds a top-level chrome document (xhtml + js + css + ftl) plus the three jar.mn registrations (`browser/base/jar.mn`, `browser/themes/shared/jar.inc.mn`, `browser/locales/jar.mn`). Default emits titlebar-buttonbox markup and a `windowtype="navigator:browser"` shell; `--no-titlebar` produces a frameless overlay with the macOS `.titlebar-button { display: none }` carve-out. Mirrors the workflow for custom elements (`furnace create`) so hand-authoring mistakes — the `*` preprocessor flag, the startup-topic observer, the platform titlebar inheritance — are eliminated. All writes go through a rollback journal under the signal-handler pathway: a Ctrl+C mid-scaffold restores every touched file.
@@ -65,7 +74,9 @@
 - New `src/core/marionette-preflight.ts` owns the `--doctor` probe and its teardown semantics.
 - Test mocks for `furnace-registration.js` now cover the new `addLocaleFtlJarMnEntry` / `removeLocaleFtlJarMnEntry` exports; `config.js` mocks in apply-batch tests now cover `loadConfig` because the apply path reads `markerComment` from fireforge.json.
 - Repo-wide scrub of fork-example mentions (`hominis.xhtml`, `HOMINIS` marker-comment examples, fixture tag names) in favour of a generic `mybrowser` / `MYBROWSER` placeholder. FireForge reads as fork-agnostic in docs and fixtures; the npm identity (`@hominis/fireforge`) is unchanged. Closes a v0.15.0 slip-through (one `@hominis/fireforge` reference remained in `src/core/furnace-operation.ts` as a generic example alongside the npm-identity occurrences; the code example is now fork-neutral).
-- New modules landed under coverage-gate protection: `src/core/mach-error-hints.ts`, `src/core/build-audit.ts`, `src/core/build-baseline.ts`, `src/core/patch-lint-diff-tag.ts`, `src/commands/furnace/chrome-doc.ts`, `src/commands/furnace/chrome-doc-templates.ts`, `src/commands/furnace/create-mochikit.ts`. Per-module thresholds added to `scripts/check-coverage-thresholds.mjs`.
+- Second pass on the same scrub: residual `hominis.xhtml` test fixtures in `wire.test.ts`, `browser-wire.test.ts`, and `doctor.test.ts` are now `mybrowser-shell.xhtml`; the `hominis.js` reference in the build-audit changelog motivating-case description is now generic. Tests retain a distinct override-target (`mybrowser.xhtml`) to preserve the configured-vs-overridden semantic of the wire `--target` precedence test.
+- New modules landed under coverage-gate protection: `src/core/mach-error-hints.ts`, `src/core/build-audit.ts`, `src/core/build-audit-resolve.ts`, `src/core/build-audit-platform.ts`, `src/core/build-baseline.ts`, `src/core/patch-lint-diff-tag.ts`, `src/commands/furnace/chrome-doc.ts`, `src/commands/furnace/chrome-doc-templates.ts`, `src/commands/furnace/create-mochikit.ts`. Per-module thresholds added to `scripts/check-coverage-thresholds.mjs`.
+- Path resolution and Python-style moz.build gate detection extracted from `build-audit.ts` into the new `build-audit-resolve.ts` (basename collisions, `_tests/` routing, trailing-segment scoring) and `build-audit-platform.ts` (`if CONFIG[…]:` gate parser keyed on host platform). Keeps the orchestrator under the per-file LOC budget after the false-positive fixes landed.
 
 ## 0.14.0
 

package/README.md

@@ -398,6 +398,13 @@ The summary line splits counts — e.g. `Lint: 2 introduced error(s), 0 introduc
 
 `fireforge build` is a transactional step: after a successful mach build it audits the dist bundle against engine-relative paths touched since the last successful build, and warns per file that is packageable-by-convention (`.js`/`.mjs`/`.css`/`.ftl`/`.xhtml`/`app/profile/…`) but has no matching artifact or whose dist mtime is older than the source. Ends every build with a `Packaged: N updated, M stale, K missing, S skipped` summary. The audit is warn-only — it never fails a build that mach reported green.
 
+The audit applies four routing rules to suppress false positives that previously trained operators to ignore its warnings:
+
+- **Build inputs are excluded.** `jar.mn`, `moz.build`, `moz.configure`, `Makefile.in`, and `mozbuild.in` are consumed by the build to produce chrome registrations / make targets but never themselves ship. They are skipped before the dist lookup, so editing them no longer fires a "missing packaged artifact" warning.
+- **Same-basename collisions in `dist/` are disambiguated by trailing-segment overlap.** A branding override at `engine/browser/branding/<name>/content/aboutDialog.css` ships at `chrome/<area>/content/branding/aboutDialog.css`. A naive basename match would tie that against the unrelated upstream `chrome/<area>/content/browser/aboutDialog.css`; the audit now scores candidates by trailing path-segment match plus a small bonus for non-generic source segments (`branding`, the branding directory name) appearing in the candidate path, so re-rooted artifacts win over coincidentally-named ones.
+- **Test sources are looked up under `_tests/`, not `dist/`.** Anything under `/test(s)/` directories, plus `browser_*.js` / `test_*.js` / `xpcshell.toml` / `browser.ini`, is resolved against the `_tests/` tree under the active `obj-*` directory. Mochitest and xpcshell harnesses copy registered tests there, never into the packaged bundle. Misses still warn — but they point at `_tests/`, directing the operator to `BROWSER_CHROME_MANIFESTS` / `XPCSHELL_TESTS_MANIFESTS` instead of `package-manifest.in`.
+- **Files inside an `if CONFIG[…]:` block in their owning `moz.build` are skipped on hosts where the gate is off.** Windows-only stubinstaller CSS on a macOS build, Darwin-only artwork on Linux, etc. The detection walks up to the closest `moz.build`, scans for the basename inside a Python-style indented `if CONFIG[…]:` block, and matches the gate against the host platform. Negation expressions are conservatively NOT treated as single-OS gates so a warning is never wrongly suppressed for a file that should ship on the current host.
+
 The build also auto-runs `mach configure` before the mach build step when any `moz.build`, `moz.configure`, or `Makefile.in` changed since the last successful build. Prevents incremental builds from silently skipping work against a stale recursive-make backend. Emits a `Backend config changed; running mach configure first...` banner when it fires.
 
 Mach build failures with known-cryptic mozbuild errors now print actionable hints. Example: a `JS_PREFERENCE_PP_FILES` entry with no `#filter` / `#expand` directives now prints `Hint: ...use JS_PREFERENCE_FILES instead, or add at least one #filter / #expand directive to the file.` alongside the raw mach traceback.
@@ -429,7 +436,7 @@ Mach build failures with known-cryptic mozbuild errors now print actionable hint
 
 **`markerComment`** (optional). Appended as a `  // <marker>:` suffix to every line FireForge writes into upstream Firefox source files (starting with `customElements.js`). Keeps fork modifications discoverable and makes re-apply idempotent without hand-tagging entries after each `furnace apply`. Reject list: empty strings, leading/trailing whitespace, newlines, `*/` (would close an enclosing block comment), control characters.
 
-**`furnace.json.tokenHostDocuments`** (optional). List of chrome XHTML documents the `missing-token-link` validator scans for the tokens CSS link. Forks with a second chrome host (e.g. `mybrowser.xhtml` alongside `browser.xhtml`) should list every document that may own the link — the rule fires only when NONE of them link the tokens CSS. Defaults to `["browser/base/content/browser.xhtml"]` when omitted.
+**`furnace.json.tokenHostDocuments`** (optional). List of chrome XHTML documents the `missing-token-link` validator scans for the tokens CSS link. Forks with a second chrome host (e.g. `mybrowser.xhtml` alongside `browser.xhtml`) should list every document that may own the link — the rule fires only when NONE of them link the tokens CSS. Defaults to `["browser/base/content/browser.xhtml"]` when omitted. `fireforge doctor`'s engine-paths probe reads the same field when confirming the chrome document exists on disk, and `fireforge wire --dom` uses the first entry as the default target for its `#include` directive (override per-invocation with `--target <path>`). Forks that fully replaced `browser.xhtml` with a custom top-level chrome document configure this field once and both checks agree.
 
 ### `furnace create --localized` for `MozLitElement`
 

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

@@ -319,12 +319,19 @@ const furnaceEnginePathsCheck = {
     dependsOn: ['Furnace configuration'],
     skipIf: (ctx) => !ctx.furnaceConfigExists || !ctx.furnaceConfig || !ctx.engineExists,
     run: async (ctx) => {
+        // Forks that replace browser.xhtml with a custom top-level chrome
+        // document enumerate their chrome docs in furnace.json.tokenHostDocuments.
+        // Reuse the same field for the engine-path probe so those forks stop
+        // seeing a permanent "browser.xhtml missing" warning.
+        const hostDocs = ctx.furnaceConfig?.tokenHostDocuments && ctx.furnaceConfig.tokenHostDocuments.length > 0
+            ? ctx.furnaceConfig.tokenHostDocuments
+            : ['browser/base/content/browser.xhtml'];
         const expectedPaths = [
             CUSTOM_ELEMENTS_JS,
             JAR_MN,
             'toolkit/content/widgets',
             resolveFtlDir(ctx.furnaceConfig?.ftlBasePath),
-            'browser/base/content/browser.xhtml',
+            ...hostDocs,
         ];
         const missing = [];
         for (const relative of expectedPaths) {

package/dist/src/commands/wire.js

@@ -2,7 +2,9 @@
 import { join, relative } from 'node:path';
 import { DEFAULT_BROWSER_SUBSCRIPT_DIR, wireSubscript } from '../core/browser-wire.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
+import { furnaceConfigExists as checkFurnaceConfigExists, loadFurnaceConfig, } from '../core/furnace-config.js';
 import { consumeParserFallbackEvents } from '../core/parser-fallback.js';
+import { DEFAULT_DOM_TARGET } from '../core/wire-dom-fragment.js';
 import { InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
@@ -10,7 +12,7 @@ import { info, intro, outro, success, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
 import { isContainedRelativePath, isPathInsideRoot, toRootRelativePath } from '../utils/paths.js';
 const BROWSER_BASE_DIR = 'browser/base';
-function printWireDryRun(engineDir, name, subscriptDir, domFilePath, options) {
+function printWireDryRun(engineDir, name, subscriptDir, domFilePath, domTargetPath, options) {
     info('[dry-run] Would wire subscript:');
     info(`  source: ${subscriptDir}/${name}.js`);
     info(`  browser-main.js: loadSubScript("chrome://browser/content/${name}.js")`);
@@ -22,12 +24,45 @@ function printWireDryRun(engineDir, name, subscriptDir, domFilePath, options) {
     }
     if (domFilePath) {
         const includePath = relative(join(engineDir, subscriptDir), join(engineDir, domFilePath)).replace(/\\/g, '/');
-        info(`  browser.xhtml: #include ${includePath}`);
+        info(`  ${domTargetPath}: #include ${includePath}`);
     }
     const relPath = relative(join(engineDir, BROWSER_BASE_DIR), join(engineDir, subscriptDir)).replace(/\\/g, '/');
     info(`  jar.mn: content/browser/${name}.js (${relPath}/${name}.js)`);
     outro('Dry run complete');
 }
+/**
+ * Resolves the chrome document the `#include` directive is inserted into.
+ *
+ * Preference order:
+ *   1. `--target <path>` CLI flag (explicit caller intent)
+ *   2. First entry of `furnace.json.tokenHostDocuments` (fork-configured
+ *      chrome doc list; already consumed by the missing-token-link
+ *      validator and the doctor check)
+ *   3. `browser/base/content/browser.xhtml` (upstream default)
+ *
+ * Step 2 is silent — a missing / invalid furnace.json falls through to the
+ * upstream default rather than surfacing a warning, because forks that don't
+ * use furnace shouldn't have to configure anything.
+ */
+async function resolveDomTargetPath(projectRoot, explicit) {
+    if (explicit !== undefined) {
+        return explicit;
+    }
+    if (await checkFurnaceConfigExists(projectRoot)) {
+        try {
+            const furnaceConfig = await loadFurnaceConfig(projectRoot);
+            const first = furnaceConfig.tokenHostDocuments?.[0];
+            if (first !== undefined && first.length > 0) {
+                return first;
+            }
+        }
+        catch {
+            // Fall through to default — a broken furnace.json should not block
+            // the wire command. The doctor surfaces that issue separately.
+        }
+    }
+    return DEFAULT_DOM_TARGET;
+}
 /**
  * Validates a subscript name supplied on the command line. Subscripts are
  * resolved into filenames under the subscript directory and registered in
@@ -90,6 +125,21 @@ export async function wireCommand(projectRoot, name, options = {}) {
         }
         domFilePath = toRootRelativePath(paths.engine, options.dom);
     }
+    // Resolve the chrome document the `#include` directive will land in.
+    // Only consulted when `--dom` is supplied — we still resolve it here so
+    // the dry-run plan can print the target accurately.
+    if (options.target !== undefined && !isContainedRelativePath(options.target)) {
+        throw new InvalidArgumentError(`Target chrome document must stay within engine/: ${options.target}`, 'target');
+    }
+    const domTargetPath = await resolveDomTargetPath(projectRoot, options.target);
+    if (domFilePath) {
+        const paths = getProjectPaths(projectRoot);
+        if (!options.dryRun && !(await pathExists(join(paths.engine, domTargetPath)))) {
+            throw new InvalidArgumentError(`Chrome document not found in engine: ${domTargetPath}\n` +
+                'Set "tokenHostDocuments" in furnace.json (first entry is used by wire) ' +
+                'or pass --target <path>.', 'target');
+        }
+    }
     // Verify the subscript file exists in engine/ (skip for dry-run)
     if (!options.dryRun) {
         const paths = getProjectPaths(projectRoot);
@@ -100,13 +150,14 @@ export async function wireCommand(projectRoot, name, options = {}) {
         }
     }
     if (options.dryRun) {
-        printWireDryRun(getProjectPaths(projectRoot).engine, name, subscriptDir, domFilePath, options);
+        printWireDryRun(getProjectPaths(projectRoot).engine, name, subscriptDir, domFilePath, domTargetPath, options);
         return;
     }
     const result = await wireSubscript(projectRoot, name, {
         ...(options.init !== undefined ? { init: options.init } : {}),
         ...(options.destroy !== undefined ? { destroy: options.destroy } : {}),
         ...(domFilePath !== undefined ? { domFilePath } : {}),
+        ...(domFilePath !== undefined && domTargetPath !== DEFAULT_DOM_TARGET ? { domTargetPath } : {}),
         ...(options.after !== undefined ? { after: options.after } : {}),
         ...(subscriptDir !== DEFAULT_BROWSER_SUBSCRIPT_DIR ? { subscriptDir } : {}),
         dryRun: false,
@@ -140,10 +191,10 @@ export async function wireCommand(projectRoot, name, options = {}) {
     }
     if (domFilePath) {
         if (result.domInserted) {
-            success(`Inserted #include directive into browser.xhtml`);
+            success(`Inserted #include directive into ${domTargetPath}`);
         }
         else {
-            info(`#include directive already present in browser.xhtml (skipped)`);
+            info(`#include directive already present in ${domTargetPath} (skipped)`);
         }
     }
     if (result.jarMnResult.skipped) {
@@ -161,10 +212,12 @@ export function registerWire(program, { getProjectRoot, withErrorHandling }) {
         .description('Wire a chrome subscript into the browser')
         .option('--init <expression>', 'Init expression for browser-init.js onLoad()')
         .option('--destroy <expression>', 'Destroy expression for browser-init.js onUnload()')
-        .option('--dom <file>', 'XHTML fragment file to insert into browser.xhtml')
+        .option('--dom <file>', 'XHTML fragment file to insert into the chrome document')
         .option('--dry-run', 'Show what would be changed without writing')
         .option('--after <name>', 'Insert init block after the block for this name')
         .option('--subscript-dir <dir>', 'Subscript directory relative to engine/ (default: browser/base/content)')
+        .option('--target <path>', 'Chrome document to insert --dom into, relative to engine/ ' +
+        '(default: first entry of furnace.json tokenHostDocuments, else browser/base/content/browser.xhtml)')
         .action(withErrorHandling(async (name, options) => {
         await wireCommand(getProjectRoot(), name, pickDefined(options));
     }));

package/dist/src/core/browser-wire.d.ts

@@ -22,6 +22,14 @@ export interface WireOptions {
     destroy?: string | undefined;
     /** Path to `.inc.xhtml` file relative to engine root */
     domFilePath?: string | undefined;
+    /**
+     * Top-level chrome document the DOM fragment's `#include` directive is
+     * inserted into, relative to engine/. Defaults to
+     * `browser/base/content/browser.xhtml`. Forks that replace browser.xhtml
+     * with a custom chrome document (e.g. `mybrowser.xhtml`) pass the
+     * replacement path here.
+     */
+    domTargetPath?: string | undefined;
     /** Dry run — don't write any files */
     dryRun?: boolean | undefined;
     /** Insert init block after the block containing this name */

package/dist/src/core/browser-wire.js

@@ -48,10 +48,10 @@ export async function wireSubscript(root, name, options = {}) {
     if (options.destroy) {
         destroyAdded = await addDestroyToBrowserInit(engineDir, options.destroy);
     }
-    // 4. Add #include directive to browser.xhtml (if provided)
+    // 4. Add #include directive to the top-level chrome document (if provided)
     let domInserted = false;
     if (options.domFilePath) {
-        domInserted = await addDomFragment(engineDir, toRootRelativePath(engineDir, options.domFilePath));
+        domInserted = await addDomFragment(engineDir, toRootRelativePath(engineDir, options.domFilePath), options.domTargetPath);
     }
     // 5. Register in jar.mn
     const jarMnResult = await registerBrowserContent(engineDir, `${name}.js`, undefined, jarMnSourcePath);

package/dist/src/core/build-audit-platform.d.ts

@@ -0,0 +1,36 @@
+/** Outcome of a moz.build platform-gate lookup for a single source file. */
+export interface PlatformGateResult {
+    /** True when the file is gated off on the current host. */
+    gatedOff: boolean;
+    /**
+     * The gate expression that excluded the file, if any. Surfaced in
+     * verbose output so an operator can confirm the audit's reasoning.
+     */
+    gateExpression?: string;
+}
+/**
+ * Scans a moz.build file for a basename match inside a conditional
+ * block, returning the gate expression when one encloses the match.
+ *
+ * The scanner uses indentation to track block scope (Python-style):
+ * an `if CONFIG[…]:` line opens a scope at indent N+1, and dedenting
+ * back to indent N closes it. A basename match inside that scope
+ * inherits the gate expression.
+ *
+ * @param content moz.build file content
+ * @param basename Basename of the source file we are auditing
+ * @returns The enclosing gate expression, or undefined if none
+ */
+export declare function findEnclosingGate(content: string, basename: string): string | undefined;
+/**
+ * Determines whether the given source file is gated off on the current
+ * host by an enclosing `if CONFIG[...]:` block in its owning moz.build.
+ * Returns `gatedOff: false` and no expression when no gate is found —
+ * the file is not platform-restricted, so the caller should audit it
+ * normally.
+ *
+ * @param engineDir Absolute path to the engine root
+ * @param sourcePath Engine-relative POSIX path of the source file
+ * @returns Detection result
+ */
+export declare function detectPlatformGate(engineDir: string, sourcePath: string): Promise<PlatformGateResult>;

package/dist/src/core/build-audit-platform.js

@@ -0,0 +1,170 @@
+// SPDX-License-Identifier: EUPL-1.2
+/*
+ * Platform-gate detection for the post-build dist-tree audit.
+ *
+ * `moz.build` files commonly wrap entries in conditional blocks like
+ * `if CONFIG["MAKENSISU"]:` (Windows-only stubinstaller) or
+ * `if CONFIG["OS_TARGET"] == "Darwin":` (macOS-only artwork). On a host
+ * that does not match the gate, the wrapped files are never processed
+ * by the build, so they cannot appear under `dist/`. Without this
+ * detection, the audit fires a "missing packaged artifact" warning for
+ * every gated file on every off-platform build — pure noise.
+ *
+ * The detection is intentionally lightweight: we walk up from the
+ * source file looking for the closest `moz.build`, scan it for an
+ * occurrence of the source basename inside an `if CONFIG[...]:` block,
+ * and check whether the gate expression matches the host platform.
+ *
+ * This is best-effort. False negatives (we miss a gate and warn anyway)
+ * are tolerable — the audit is warn-only. False positives (we wrongly
+ * skip a gated file that should ship on this host) are not, so the
+ * detection errs toward NOT skipping when uncertain.
+ */
+import { dirname, join } from 'node:path';
+import { pathExists, readText } from '../utils/fs.js';
+import { getPlatform } from '../utils/platform.js';
+/**
+ * Tokens that uniquely identify a Windows-only `if CONFIG[...]:` block.
+ * `MAKENSISU` is the Windows stubinstaller compiler; `OS_TARGET ==
+ * "WINNT"` and `MOZ_WIDGET_TOOLKIT == "windows"` are the conventional
+ * platform discriminators.
+ */
+const WINDOWS_ONLY_GATE_TOKENS = ['MAKENSISU', '"WINNT"', "'WINNT'", '"windows"', "'windows'"];
+/** Tokens that mark a macOS-only `if CONFIG[...]:` block. */
+const DARWIN_ONLY_GATE_TOKENS = ['"Darwin"', "'Darwin'", '"cocoa"', "'cocoa'"];
+/** Tokens that mark a Linux-only `if CONFIG[...]:` block. */
+const LINUX_ONLY_GATE_TOKENS = ['"Linux"', "'Linux'", '"gtk"', "'gtk'"];
+/**
+ * Returns true when the platform-gate expression includes one of the
+ * tokens characteristic of a single OS that is not the current host.
+ */
+function isGateOffHost(expression, host) {
+    const matchesWindows = WINDOWS_ONLY_GATE_TOKENS.some((t) => expression.includes(t));
+    const matchesDarwin = DARWIN_ONLY_GATE_TOKENS.some((t) => expression.includes(t));
+    const matchesLinux = LINUX_ONLY_GATE_TOKENS.some((t) => expression.includes(t));
+    // Negation gates (`!= "WINNT"`, `not CONFIG["MAKENSISU"]`) flip the
+    // semantics. Keep this conservative — if we cannot confidently parse
+    // a negation, return false so we don't wrongly suppress a warning.
+    const negated = /\bnot\b|!=/.test(expression);
+    if (negated)
+        return false;
+    if (matchesWindows && host !== 'win32')
+        return true;
+    if (matchesDarwin && host !== 'darwin')
+        return true;
+    if (matchesLinux && host !== 'linux')
+        return true;
+    return false;
+}
+/**
+ * Walks from a starting directory up to (but not above) the engine root,
+ * yielding the first `moz.build` encountered. Returns undefined when no
+ * ancestor has one — typically only for files that live above any
+ * moz.build entry point, which would not be packageable anyway.
+ */
+async function findOwningMozBuild(engineDir, sourceDir) {
+    let current = sourceDir;
+    const root = engineDir.replace(/\/+$/, '');
+    while (current.startsWith(root)) {
+        const candidate = join(current, 'moz.build');
+        if (await pathExists(candidate))
+            return candidate;
+        const parent = dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return undefined;
+}
+/**
+ * Matches a `basename` appearing at the tail of a quoted path literal
+ * on a single moz.build line. Catches both the bare entry
+ * `"installing_page.css"` and the path-prefixed entry
+ * `"stubinstaller/installing_page.css"`.
+ */
+function matchesQuotedBasename(line, basename) {
+    const escaped = basename.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return new RegExp(`["'](?:[^"']*\\/)?${escaped}["']`).test(line);
+}
+/**
+ * Scans a moz.build file for a basename match inside a conditional
+ * block, returning the gate expression when one encloses the match.
+ *
+ * The scanner uses indentation to track block scope (Python-style):
+ * an `if CONFIG[…]:` line opens a scope at indent N+1, and dedenting
+ * back to indent N closes it. A basename match inside that scope
+ * inherits the gate expression.
+ *
+ * @param content moz.build file content
+ * @param basename Basename of the source file we are auditing
+ * @returns The enclosing gate expression, or undefined if none
+ */
+export function findEnclosingGate(content, basename) {
+    const lines = content.split('\n');
+    const stack = [];
+    for (const line of lines) {
+        if (line.trim() === '')
+            continue;
+        const indent = (/^(\s*)/.exec(line)?.[1] ?? '').length;
+        while (stack.length > 0) {
+            const top = stack[stack.length - 1];
+            if (top && indent <= top.indent) {
+                stack.pop();
+                continue;
+            }
+            break;
+        }
+        const ifMatch = /^\s*if\s+(.+?):\s*(?:#.*)?$/.exec(line);
+        if (ifMatch?.[1]) {
+            stack.push({ indent, expression: ifMatch[1] });
+            continue;
+        }
+        if (matchesQuotedBasename(line, basename)) {
+            const top = stack[stack.length - 1];
+            if (top)
+                return top.expression;
+            return undefined;
+        }
+    }
+    return undefined;
+}
+/**
+ * Determines whether the given source file is gated off on the current
+ * host by an enclosing `if CONFIG[...]:` block in its owning moz.build.
+ * Returns `gatedOff: false` and no expression when no gate is found —
+ * the file is not platform-restricted, so the caller should audit it
+ * normally.
+ *
+ * @param engineDir Absolute path to the engine root
+ * @param sourcePath Engine-relative POSIX path of the source file
+ * @returns Detection result
+ */
+export async function detectPlatformGate(engineDir, sourcePath) {
+    const sourceDir = dirname(join(engineDir, sourcePath));
+    const mozBuild = await findOwningMozBuild(engineDir, sourceDir);
+    if (!mozBuild)
+        return { gatedOff: false };
+    let content;
+    try {
+        content = await readText(mozBuild);
+    }
+    catch {
+        return { gatedOff: false };
+    }
+    const sourceBasename = sourcePath.split('/').pop() ?? '';
+    const expression = findEnclosingGate(content, sourceBasename);
+    if (!expression)
+        return { gatedOff: false };
+    let host;
+    try {
+        host = getPlatform();
+    }
+    catch {
+        return { gatedOff: false };
+    }
+    if (isGateOffHost(expression, host)) {
+        return { gatedOff: true, gateExpression: expression };
+    }
+    return { gatedOff: false, gateExpression: expression };
+}
+//# sourceMappingURL=build-audit-platform.js.map

package/dist/src/core/build-audit-resolve.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Heuristic test for "this looks like a packaged-test source file" — the
+ * audit routes such paths to `_tests/` instead of `dist/`. Matches
+ * mochitest / xpcshell / browser-chrome conventions: any source under a
+ * `/test/` or `/tests/` directory, or with a `browser_` / `test_` prefix
+ * on a `.js`/`.toml` basename. Test manifests (`*.toml`, `*.list`,
+ * `*.ini`) under those directories also qualify.
+ *
+ * @param sourcePath Engine-relative POSIX path
+ * @returns True when the file belongs to the test tree, not the bundle
+ */
+export declare function isTestPath(sourcePath: string): boolean;
+/**
+ * Counts how many trailing segments two paths share. Used to score
+ * candidate dist artifacts against a source path so that
+ * `branding/<name>/content/aboutDialog.css` prefers a candidate at
+ * `…/content/branding/aboutDialog.css` over one at
+ * `…/content/browser/aboutDialog.css`.
+ *
+ * @param a First path
+ * @param b Second path
+ * @returns Count of matching trailing segments (basename always counts as 1)
+ */
+export declare function countTrailingSegmentMatches(a: string, b: string): number;
+/**
+ * Computes a score for `candidatePath` relative to `sourcePath`. Higher
+ * scores win. Score = trailing-segment match count, with a bonus when
+ * the candidate's path contains a meaningful intermediate segment from
+ * the source (e.g. `branding`, the branding dir name itself, etc.).
+ *
+ * The bonus exists because Firefox packaging often re-roots files: a
+ * source `branding/<name>/content/aboutDialog.css` lands at
+ * `chrome/browser/content/branding/aboutDialog.css` — only the basename
+ * trails-match, but the `branding` segment moved into the middle of
+ * the candidate path. Without the bonus, that candidate would tie with
+ * the unrelated `chrome/browser/content/browser/aboutDialog.css` and
+ * the audit would pick whichever the directory walk hit first.
+ *
+ * @param sourcePath Engine-relative POSIX path
+ * @param candidatePath Absolute path under the dist tree
+ * @returns Numeric score; higher means better match
+ */
+export declare function scoreCandidate(sourcePath: string, candidatePath: string): number;
+/**
+ * Walks a tree under `root` and returns every file whose basename equals
+ * `name`. Skips dotfile / hidden directories so the symlinked
+ * `.mozbuild` cache (a full upstream copy) does not dominate the scan
+ * on macOS.
+ *
+ * @param root Tree root to search
+ * @param name Basename to match
+ * @param maxDepth Optional traversal cap (default 12)
+ * @returns All matching absolute paths
+ */
+export declare function findAllByBasename(root: string, name: string, maxDepth?: number): Promise<string[]>;
+/**
+ * Resolves the best-matching artifact for a source path under one or
+ * more search roots. Returns the highest-scoring candidate by trailing
+ * segment overlap; ties go to the first-found path (deterministic via
+ * the directory-walk order). Returns undefined when no candidate exists.
+ *
+ * @param sourcePath Engine-relative POSIX source path
+ * @param searchRoots Absolute roots to scan (e.g. dist/, _tests/)
+ * @returns Best-matching artifact path, or undefined
+ */
+export declare function resolveBestArtifact(sourcePath: string, searchRoots: readonly string[]): Promise<string | undefined>;

package/dist/src/core/build-audit-resolve.js

@@ -0,0 +1,209 @@
+// SPDX-License-Identifier: EUPL-1.2
+/*
+ * Path-resolution helpers for the post-build dist-tree audit.
+ *
+ * Resolves the expected on-disk artifact location for a given engine
+ * source path. The previous implementation matched purely by basename and
+ * suffered three classes of false positive:
+ *
+ *   1. A branding override (e.g. `engine/browser/branding/<name>/content/aboutDialog.css`)
+ *      shipped at `chrome/browser/content/branding/aboutDialog.css` would
+ *      get matched against the unrelated upstream
+ *      `chrome/browser/content/browser/aboutDialog.css`.
+ *   2. Test files (`browser_*.js`, `test_*.js`) live under `_tests/`, not
+ *      `dist/`, so every registered test was reported as missing.
+ *   3. Build inputs (`jar.mn`, `moz.build`, `Makefile.in`, `moz.configure`)
+ *      never appear under `dist/` — they are consumed, not packaged.
+ *
+ * The helpers below address (1) by ranking same-basename candidates by
+ * how many trailing path segments they share with the source, and (2) by
+ * routing test paths to a separate `_tests/`-aware resolver.
+ *
+ * (3) is handled in `build-audit.ts` via `isPackageablePath`.
+ */
+import { readdir } from 'node:fs/promises';
+import { basename, join } from 'node:path';
+import { pathExists } from '../utils/fs.js';
+/** Maximum directory depth to traverse when scanning a tree root. */
+const MAX_SCAN_DEPTH = 12;
+/**
+ * Heuristic test for "this looks like a packaged-test source file" — the
+ * audit routes such paths to `_tests/` instead of `dist/`. Matches
+ * mochitest / xpcshell / browser-chrome conventions: any source under a
+ * `/test/` or `/tests/` directory, or with a `browser_` / `test_` prefix
+ * on a `.js`/`.toml` basename. Test manifests (`*.toml`, `*.list`,
+ * `*.ini`) under those directories also qualify.
+ *
+ * @param sourcePath Engine-relative POSIX path
+ * @returns True when the file belongs to the test tree, not the bundle
+ */
+export function isTestPath(sourcePath) {
+    if (sourcePath.includes('/test/') || sourcePath.includes('/tests/')) {
+        return true;
+    }
+    const name = basename(sourcePath);
+    if (/^browser_.+\.(js|toml|ini)$/.test(name))
+        return true;
+    if (/^test_.+\.(js|toml|ini)$/.test(name))
+        return true;
+    return false;
+}
+/**
+ * Splits a POSIX path into segments, dropping empties.
+ * @param path POSIX-separated path
+ */
+function pathSegments(path) {
+    return path.split('/').filter(Boolean);
+}
+/**
+ * Counts how many trailing segments two paths share. Used to score
+ * candidate dist artifacts against a source path so that
+ * `branding/<name>/content/aboutDialog.css` prefers a candidate at
+ * `…/content/branding/aboutDialog.css` over one at
+ * `…/content/browser/aboutDialog.css`.
+ *
+ * @param a First path
+ * @param b Second path
+ * @returns Count of matching trailing segments (basename always counts as 1)
+ */
+export function countTrailingSegmentMatches(a, b) {
+    const aSegs = pathSegments(a);
+    const bSegs = pathSegments(b);
+    let matches = 0;
+    while (matches < aSegs.length &&
+        matches < bSegs.length &&
+        aSegs[aSegs.length - 1 - matches] === bSegs[bSegs.length - 1 - matches]) {
+        matches += 1;
+    }
+    return matches;
+}
+/**
+ * Computes a score for `candidatePath` relative to `sourcePath`. Higher
+ * scores win. Score = trailing-segment match count, with a bonus when
+ * the candidate's path contains a meaningful intermediate segment from
+ * the source (e.g. `branding`, the branding dir name itself, etc.).
+ *
+ * The bonus exists because Firefox packaging often re-roots files: a
+ * source `branding/<name>/content/aboutDialog.css` lands at
+ * `chrome/browser/content/branding/aboutDialog.css` — only the basename
+ * trails-match, but the `branding` segment moved into the middle of
+ * the candidate path. Without the bonus, that candidate would tie with
+ * the unrelated `chrome/browser/content/browser/aboutDialog.css` and
+ * the audit would pick whichever the directory walk hit first.
+ *
+ * @param sourcePath Engine-relative POSIX path
+ * @param candidatePath Absolute path under the dist tree
+ * @returns Numeric score; higher means better match
+ */
+export function scoreCandidate(sourcePath, candidatePath) {
+    const trailing = countTrailingSegmentMatches(sourcePath, candidatePath);
+    const sourceSegs = pathSegments(sourcePath);
+    const candSegs = pathSegments(candidatePath);
+    // Look for source segments that appear anywhere in the candidate path
+    // but are not part of the trailing match. Each unique mid-path hit on
+    // a meaningful (>2-char, not generic like 'content'/'chrome'/'bin')
+    // segment adds 1 to the score.
+    const generic = new Set([
+        'content',
+        'chrome',
+        'bin',
+        'browser',
+        'toolkit',
+        'modules',
+        'base',
+        'app',
+        'profile',
+        'shared',
+        'themes',
+    ]);
+    const trailingSet = new Set(sourceSegs.slice(sourceSegs.length - trailing));
+    let bonus = 0;
+    for (const seg of sourceSegs) {
+        if (seg.length <= 2)
+            continue;
+        if (generic.has(seg))
+            continue;
+        if (trailingSet.has(seg))
+            continue;
+        if (candSegs.includes(seg))
+            bonus += 1;
+    }
+    return trailing * 10 + bonus;
+}
+/**
+ * Walks a tree under `root` and returns every file whose basename equals
+ * `name`. Skips dotfile / hidden directories so the symlinked
+ * `.mozbuild` cache (a full upstream copy) does not dominate the scan
+ * on macOS.
+ *
+ * @param root Tree root to search
+ * @param name Basename to match
+ * @param maxDepth Optional traversal cap (default 12)
+ * @returns All matching absolute paths
+ */
+export async function findAllByBasename(root, name, maxDepth = MAX_SCAN_DEPTH) {
+    const results = [];
+    if (!(await pathExists(root)))
+        return results;
+    const stack = [{ dir: root, depth: 0 }];
+    while (stack.length > 0) {
+        const entry = stack.pop();
+        if (!entry)
+            break;
+        if (entry.depth > maxDepth)
+            continue;
+        let children;
+        try {
+            children = await readdir(entry.dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const child of children) {
+            const fullPath = join(entry.dir, child.name);
+            if (child.isDirectory()) {
+                if (child.name.startsWith('.'))
+                    continue;
+                stack.push({ dir: fullPath, depth: entry.depth + 1 });
+                continue;
+            }
+            if (child.name === name) {
+                results.push(fullPath);
+            }
+        }
+    }
+    return results;
+}
+/**
+ * Resolves the best-matching artifact for a source path under one or
+ * more search roots. Returns the highest-scoring candidate by trailing
+ * segment overlap; ties go to the first-found path (deterministic via
+ * the directory-walk order). Returns undefined when no candidate exists.
+ *
+ * @param sourcePath Engine-relative POSIX source path
+ * @param searchRoots Absolute roots to scan (e.g. dist/, _tests/)
+ * @returns Best-matching artifact path, or undefined
+ */
+export async function resolveBestArtifact(sourcePath, searchRoots) {
+    const name = basename(sourcePath);
+    const allCandidates = [];
+    for (const root of searchRoots) {
+        const found = await findAllByBasename(root, name);
+        allCandidates.push(...found);
+    }
+    if (allCandidates.length === 0)
+        return undefined;
+    if (allCandidates.length === 1)
+        return allCandidates[0];
+    let bestScore = -1;
+    let best;
+    for (const candidate of allCandidates) {
+        const score = scoreCandidate(sourcePath, candidate);
+        if (score > bestScore) {
+            bestScore = score;
+            best = candidate;
+        }
+    }
+    return best;
+}
+//# sourceMappingURL=build-audit-resolve.js.map

package/dist/src/core/build-audit.d.ts

@@ -28,7 +28,10 @@ export interface AuditSummary {
 }
 /**
  * Decides whether a source path should be packaged. Returns true for paths
- * whose extension or directory fragment matches a known-packaged pattern.
+ * whose extension or directory fragment matches a known-packaged pattern,
+ * after excluding build inputs (`jar.mn`, `moz.build`, etc.) which are
+ * consumed by the build but never themselves packaged.
+ *
  * @param sourcePath Engine-relative POSIX path (for example browser/app/profile/pref.js).
  * @returns True when the path implies packaging.
  */

package/dist/src/core/build-audit.js

@@ -19,12 +19,27 @@
  *   - False positives are acceptable at this stage: fork-specific packaging
  *     tricks FireForge doesn't know about will surface as warnings an
  *     operator can investigate. The audit never fails the build.
+ *
+ * Routing rules:
+ *   - Build inputs (jar.mn, moz.build, Makefile.in, moz.configure) are
+ *     skipped; they are consumed, not packaged.
+ *   - Test sources (anything under /test(s)/, browser_*.js, test_*.js)
+ *     are looked up under _tests/, not dist/ — that's where mach copies
+ *     them.
+ *   - Files inside an `if CONFIG[...]:` block in moz.build that gates
+ *     off on the current host are skipped (Windows stubinstaller CSS on
+ *     a macOS build, etc.).
+ *   - Same-basename collisions in dist/ are disambiguated by trailing-
+ *     segment overlap so a branding override does not get matched
+ *     against an unrelated upstream file with the same basename.
  */
 import { stat } from 'node:fs/promises';
 import { basename, join } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info, verbose, warn } from '../utils/logger.js';
+import { detectPlatformGate } from './build-audit-platform.js';
+import { isTestPath, resolveBestArtifact } from './build-audit-resolve.js';
 import { hasChanges, isMissingHeadError } from './git.js';
 import { git } from './git-base.js';
 import { getUntrackedFiles } from './git-status.js';
@@ -44,48 +59,29 @@ const PACKAGEABLE_EXTENSIONS = [
 const PACKAGEABLE_PATH_FRAGMENTS = ['/app/profile/', '/chrome/', '/locales/'];
 /** Directories that are build artifacts, not source — never audited. */
 const IGNORE_PATH_FRAGMENTS = ['obj-', 'node_modules/', '.git/', '.cargo/', '.mozbuild/'];
-/*
- * Finds the first file with the given basename anywhere under the dist
- * bundle. Scans the darwin Contents/Resources layout and the linux/win
- * top-level layout with a depth-limited traversal so deeply-nested
- * node_modules in the dist copy do not dominate the audit wall clock.
+/**
+ * Basenames that are build-system inputs, not packaged artifacts.
+ * `jar.mn` is consumed to produce chrome registrations; `moz.build` /
+ * `moz.configure` / `Makefile.in` feed the build backend; none of them
+ * ship in the bundle. Auditing them produced a guaranteed false
+ * positive on every edit (nothing under dist/ ever has these names),
+ * and a worse failure mode when an unrelated upstream `moz.build`
+ * coincidentally exists at e.g. `MyBrowser.app/Contents/moz.build` and
+ * gets matched as a "stale artifact" of an entirely different file.
  */
-async function findArtifactByBasename(distRoot, name, maxDepth = 10) {
-    const { readdir } = await import('node:fs/promises');
-    const stack = [{ dir: distRoot, depth: 0 }];
-    while (stack.length > 0) {
-        const entry = stack.pop();
-        if (!entry)
-            break;
-        if (entry.depth > maxDepth)
-            continue;
-        let children;
-        try {
-            children = await readdir(entry.dir, { withFileTypes: true });
-        }
-        catch {
-            continue;
-        }
-        for (const child of children) {
-            const fullPath = join(entry.dir, child.name);
-            if (child.isDirectory()) {
-                // Skip the symlinked mozbuild cache tree which contains full copies
-                // and would dominate the scan on macOS.
-                if (child.name.startsWith('.'))
-                    continue;
-                stack.push({ dir: fullPath, depth: entry.depth + 1 });
-                continue;
-            }
-            if (child.name === name) {
-                return fullPath;
-            }
-        }
-    }
-    return undefined;
-}
+const BUILD_INPUT_BASENAMES = new Set([
+    'jar.mn',
+    'moz.build',
+    'moz.configure',
+    'Makefile.in',
+    'mozbuild.in',
+]);
 /**
  * Decides whether a source path should be packaged. Returns true for paths
- * whose extension or directory fragment matches a known-packaged pattern.
+ * whose extension or directory fragment matches a known-packaged pattern,
+ * after excluding build inputs (`jar.mn`, `moz.build`, etc.) which are
+ * consumed by the build but never themselves packaged.
+ *
  * @param sourcePath Engine-relative POSIX path (for example browser/app/profile/pref.js).
  * @returns True when the path implies packaging.
  */
@@ -94,6 +90,8 @@ export function isPackageablePath(sourcePath) {
         if (sourcePath.includes(fragment))
             return false;
     }
+    if (BUILD_INPUT_BASENAMES.has(basename(sourcePath)))
+        return false;
     for (const ext of PACKAGEABLE_EXTENSIONS) {
         if (sourcePath.endsWith(ext))
             return true;
@@ -169,6 +167,97 @@ async function resolveDistRoot(engineDir) {
     }
     return undefined;
 }
+/**
+ * Resolves the `_tests/` tree under the active obj-* directory, used as
+ * a secondary search root for sources that look like packaged tests.
+ * Returns undefined when no obj dir exists yet.
+ */
+async function resolveTestsRoot(engineDir) {
+    const { readdir } = await import('node:fs/promises');
+    let entries;
+    try {
+        entries = await readdir(engineDir);
+    }
+    catch {
+        return undefined;
+    }
+    const objDirs = entries.filter((e) => e.startsWith('obj-'));
+    for (const objDir of objDirs) {
+        const testsPath = join(engineDir, objDir, '_tests');
+        if (await pathExists(testsPath)) {
+            return testsPath;
+        }
+    }
+    return undefined;
+}
+/**
+ * Resolves the search roots an individual source path should be looked
+ * up under. Test-shaped paths get `_tests/`; everything else gets `dist/`.
+ */
+function searchRootsFor(source, distRoot, testsRoot) {
+    if (isTestPath(source)) {
+        return testsRoot ? [testsRoot] : [];
+    }
+    return [distRoot];
+}
+/**
+ * Audits one engine source path and returns its entry. Pure orchestration
+ * helper kept separate so `auditBuildArtifacts` stays under the per-function
+ * line budget.
+ */
+async function auditSinglePath(source, ctx) {
+    if (!isPackageablePath(source)) {
+        return { source, artifact: undefined, status: 'skipped' };
+    }
+    const gate = await detectPlatformGate(ctx.engineDir, source);
+    if (gate.gatedOff) {
+        verbose(`Audit: skipping engine/${source} — gated off by moz.build "${gate.gateExpression ?? '?'}".`);
+        return { source, artifact: undefined, status: 'skipped' };
+    }
+    const sourcePath = join(ctx.engineDir, source);
+    let sourceMtime;
+    try {
+        const sourceStat = await stat(sourcePath);
+        sourceMtime = sourceStat.mtimeMs;
+    }
+    catch {
+        // Deletion that didn't propagate — distinct class of bug, not audited yet.
+        return { source, artifact: undefined, status: 'skipped' };
+    }
+    const roots = searchRootsFor(source, ctx.distRoot, ctx.testsRoot);
+    const artifact = await resolveBestArtifact(source, roots);
+    if (!artifact) {
+        const where = isTestPath(source) ? '_tests/' : 'dist/';
+        return {
+            source,
+            artifact: undefined,
+            status: 'missing',
+            warning: `Audit: engine/${source} was touched but no packaged artifact with basename "${basename(source)}" was found under ${where}. Missing moz.build / jar.mn / package-manifest.in registration?`,
+        };
+    }
+    let artifactMtime;
+    try {
+        const artifactStat = await stat(artifact);
+        artifactMtime = artifactStat.mtimeMs;
+    }
+    catch {
+        return {
+            source,
+            artifact,
+            status: 'missing',
+            warning: `Audit: engine/${source} has no readable packaged artifact at ${artifact} (disappeared during audit).`,
+        };
+    }
+    if (artifactMtime + 1 < sourceMtime) {
+        return {
+            source,
+            artifact,
+            status: 'stale',
+            warning: `Audit: engine/${source} is newer than its packaged artifact ${artifact}. Build reported success but the file's path may not flow through packaging — check moz.build / jar.mn entries.`,
+        };
+    }
+    return { source, artifact, status: 'updated' };
+}
 /**
  * Runs the post-build audit. Emits per-file warnings for missing or
  * stale artifacts and a summary info line at the end. Always returns
@@ -193,57 +282,22 @@ export async function auditBuildArtifacts(projectRoot, engineDir, baseline) {
         verbose('Audit skipped: no dist tree found under obj-*/dist/.');
         return summary;
     }
+    const testsRoot = await resolveTestsRoot(engineDir);
     const changed = await collectChangedFiles(engineDir, baseline);
     if (changed.length === 0) {
         return summary;
     }
+    const ctx = { engineDir, distRoot, testsRoot };
     for (const source of changed) {
-        if (!isPackageablePath(source)) {
-            summary.skipped += 1;
-            summary.entries.push({ source, artifact: undefined, status: 'skipped' });
-            continue;
-        }
-        const sourcePath = join(engineDir, source);
-        let sourceMtime;
-        try {
-            const sourceStat = await stat(sourcePath);
-            sourceMtime = sourceStat.mtimeMs;
-        }
-        catch {
-            // File was deleted since the diff was computed. Skip — a deletion
-            // that didn't propagate to the dist tree is a distinct class of bug
-            // we don't audit yet.
-            summary.skipped += 1;
-            summary.entries.push({ source, artifact: undefined, status: 'skipped' });
-            continue;
-        }
-        const artifact = await findArtifactByBasename(distRoot, basename(source));
-        if (!artifact) {
-            summary.missing += 1;
-            summary.entries.push({ source, artifact: undefined, status: 'missing' });
-            warn(`Audit: engine/${source} was touched but no packaged artifact with basename "${basename(source)}" was found under ${distRoot}. Missing moz.build / jar.mn / package-manifest.in registration?`);
-            continue;
-        }
-        let artifactMtime;
-        try {
-            const artifactStat = await stat(artifact);
-            artifactMtime = artifactStat.mtimeMs;
-        }
-        catch {
-            // Disappeared after the directory scan; treat as missing.
-            summary.missing += 1;
-            summary.entries.push({ source, artifact, status: 'missing' });
-            warn(`Audit: engine/${source} has no readable packaged artifact at ${artifact} (disappeared during audit).`);
-            continue;
-        }
-        if (artifactMtime + 1 < sourceMtime) {
-            summary.stale += 1;
-            summary.entries.push({ source, artifact, status: 'stale' });
-            warn(`Audit: engine/${source} is newer than its packaged artifact ${artifact}. Build reported success but the file's path may not flow through packaging — check moz.build / jar.mn entries.`);
-            continue;
-        }
-        summary.updated += 1;
-        summary.entries.push({ source, artifact, status: 'updated' });
+        const result = await auditSinglePath(source, ctx);
+        summary[result.status] += 1;
+        summary.entries.push({
+            source: result.source,
+            artifact: result.artifact,
+            status: result.status,
+        });
+        if (result.warning)
+            warn(result.warning);
     }
     info(`Packaged: ${summary.updated} updated, ${summary.stale} stale, ${summary.missing} missing, ${summary.skipped} skipped`);
     return summary;

package/dist/src/core/wire-dom-fragment.d.ts

@@ -1,6 +1,13 @@
 /**
- * browser.xhtml — DOM fragment insertion.
+ * Top-level chrome document — DOM fragment insertion.
+ *
+ * Default target is `browser/base/content/browser.xhtml`. Forks that replace
+ * browser.xhtml with a custom top-level chrome document pass the replacement
+ * path in via `targetPath`; the insertion logic is shape-agnostic (looks for
+ * `#include browser-sets.inc`, then falls back to `<html:body>`), so any
+ * browser.xhtml-shaped xhtml works.
  */
+export declare const DEFAULT_DOM_TARGET = "browser/base/content/browser.xhtml";
 /**
  * Tokenizer-based implementation for DOM fragment insertion.
  */
@@ -10,14 +17,19 @@ export declare function addDomFragmentTokenized(content: string, includeDirectiv
  */
 export declare function legacyAddDomFragment(content: string, includeDirective: string): string;
 /**
- * Inserts a `#include` directive for an `.inc.xhtml` file into browser.xhtml,
- * before `#include browser-sets.inc`.
+ * Inserts a `#include` directive for an `.inc.xhtml` file into the top-level
+ * chrome document (default: `browser/base/content/browser.xhtml`), before
+ * `#include browser-sets.inc`.
  *
  * If the file's content was previously inlined (detected by root element id=),
  * the inlined block is automatically replaced with the `#include` directive.
  *
  * @param engineDir - Engine source root
  * @param domFilePath - Path to the `.inc.xhtml` file relative to engine root
+ * @param targetPath - Chrome document to insert into, relative to engine
+ *   root. Defaults to {@link DEFAULT_DOM_TARGET}. Forks that replace
+ *   browser.xhtml with a custom top-level chrome document pass the
+ *   replacement path here.
  * @returns true if inserted, false if already present
  */
-export declare function addDomFragment(engineDir: string, domFilePath: string): Promise<boolean>;
+export declare function addDomFragment(engineDir: string, domFilePath: string, targetPath?: string): Promise<boolean>;

package/dist/src/core/wire-dom-fragment.js

@@ -1,15 +1,21 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * browser.xhtml — DOM fragment insertion.
+ * Top-level chrome document — DOM fragment insertion.
+ *
+ * Default target is `browser/base/content/browser.xhtml`. Forks that replace
+ * browser.xhtml with a custom top-level chrome document pass the replacement
+ * path in via `targetPath`; the insertion logic is shape-agnostic (looks for
+ * `#include browser-sets.inc`, then falls back to `<html:body>`), so any
+ * browser.xhtml-shaped xhtml works.
  */
-import { join, relative } from 'node:path';
+import { dirname, join, relative } from 'node:path';
 import { GeneralError } from '../errors/base.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
 import { toRootRelativePath } from '../utils/paths.js';
 import { escapeRegex } from '../utils/regex.js';
 import { withParserFallback } from './parser-fallback.js';
 import { tokenizeXhtml } from './wire-utils.js';
-const BROWSER_XHTML = 'browser/base/content/browser.xhtml';
+export const DEFAULT_DOM_TARGET = 'browser/base/content/browser.xhtml';
 /**
  * Tokenizer-based implementation for DOM fragment insertion.
  */
@@ -36,7 +42,7 @@ export function addDomFragmentTokenized(content, includeDirective) {
         }
     }
     if (insertIndex === -1) {
-        throw new GeneralError('Could not find insertion point in browser.xhtml');
+        throw new GeneralError('Could not find insertion point in chrome document');
     }
     lines.splice(insertIndex, 0, includeDirective);
     return lines.join('\n');
@@ -64,32 +70,41 @@ export function legacyAddDomFragment(content, includeDirective) {
         }
     }
     if (insertIndex === -1) {
-        throw new GeneralError('Could not find insertion point in browser.xhtml');
+        throw new GeneralError('Could not find insertion point in chrome document');
     }
     lines.splice(insertIndex, 0, includeDirective);
     return lines.join('\n');
 }
 /**
- * Inserts a `#include` directive for an `.inc.xhtml` file into browser.xhtml,
- * before `#include browser-sets.inc`.
+ * Inserts a `#include` directive for an `.inc.xhtml` file into the top-level
+ * chrome document (default: `browser/base/content/browser.xhtml`), before
+ * `#include browser-sets.inc`.
  *
  * If the file's content was previously inlined (detected by root element id=),
  * the inlined block is automatically replaced with the `#include` directive.
  *
  * @param engineDir - Engine source root
  * @param domFilePath - Path to the `.inc.xhtml` file relative to engine root
+ * @param targetPath - Chrome document to insert into, relative to engine
+ *   root. Defaults to {@link DEFAULT_DOM_TARGET}. Forks that replace
+ *   browser.xhtml with a custom top-level chrome document pass the
+ *   replacement path here.
  * @returns true if inserted, false if already present
  */
-export async function addDomFragment(engineDir, domFilePath) {
-    const browserXhtmlPath = join(engineDir, BROWSER_XHTML);
+export async function addDomFragment(engineDir, domFilePath, targetPath = DEFAULT_DOM_TARGET) {
+    const targetAbsPath = join(engineDir, targetPath);
     const safeDomFilePath = toRootRelativePath(engineDir, domFilePath);
-    if (!(await pathExists(browserXhtmlPath))) {
-        throw new GeneralError(`${BROWSER_XHTML} not found in engine`);
+    if (!(await pathExists(targetAbsPath))) {
+        throw new GeneralError(`${targetPath} not found in engine`);
     }
-    // Compute include path relative to browser/base/content/ (where browser.xhtml lives)
-    const includePath = relative('browser/base/content', safeDomFilePath).replace(/\\/g, '/');
+    // Compute include path relative to the target's directory — the `#include`
+    // directive is resolved by the preprocessor relative to the file that
+    // contains it, so this must track the chrome doc's location, not a
+    // hardcoded `browser/base/content/`.
+    const targetDir = dirname(targetPath);
+    const includePath = relative(targetDir, safeDomFilePath).replace(/\\/g, '/');
     const includeDirective = `#include ${includePath}`;
-    let content = await readText(browserXhtmlPath);
+    let content = await readText(targetAbsPath);
     // Idempotency: check if the #include directive already exists (line-anchored to avoid substring matches)
     if (new RegExp(`^${escapeRegex(includeDirective)}$`, 'm').test(content)) {
         return false;
@@ -116,14 +131,14 @@ export async function addDomFragment(engineDir, domFilePath) {
                 }
                 lines.splice(startIdx, endIdx - startIdx, includeDirective);
                 content = lines.join('\n');
-                await writeText(browserXhtmlPath, content);
+                await writeText(targetAbsPath, content);
                 return true;
             }
         }
     }
     // Normal insertion
-    const { value } = withParserFallback(() => addDomFragmentTokenized(content, includeDirective), () => legacyAddDomFragment(content, includeDirective), BROWSER_XHTML);
-    await writeText(browserXhtmlPath, value);
+    const { value } = withParserFallback(() => addDomFragmentTokenized(content, includeDirective), () => legacyAddDomFragment(content, includeDirective), targetPath);
+    await writeText(targetAbsPath, value);
     return true;
 }
 //# sourceMappingURL=wire-dom-fragment.js.map

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

@@ -309,6 +309,13 @@ export interface WireOptions {
     dryRun?: boolean;
     after?: string;
     subscriptDir?: string;
+    /**
+     * Chrome document the DOM fragment's `#include` is inserted into, relative
+     * to engine/. Defaults to the first entry of
+     * `furnace.json.tokenHostDocuments` when set, otherwise
+     * `browser/base/content/browser.xhtml`.
+     */
+    target?: string;
 }
 /**
  * Options for the register command.

package/package.json

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