@hominis/fireforge 0.15.2 → 0.15.4

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

@@ -4,14 +4,72 @@
  * story cleanup, branding setup, Furnace component application, and mozconfig generation.
  */
 import { FurnaceError } from '../errors/furnace.js';
+import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
-import { info, spinner, warn } from '../utils/logger.js';
+import { info, spinner, verbose, warn } from '../utils/logger.js';
 import { isBrandingSetup, setupBranding } from './branding.js';
 import { applyAllComponents } from './furnace-apply.js';
 import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceState, } from './furnace-config.js';
 import { runFurnaceMutation } from './furnace-operation.js';
 import { cleanStories } from './furnace-stories.js';
-import { generateMozconfig } from './mach.js';
+import { hasChanges, isMissingHeadError } from './git.js';
+import { git } from './git-base.js';
+import { getUntrackedFiles } from './git-status.js';
+import { generateMozconfig, runMach } from './mach.js';
+/** Path fragments of files whose edits invalidate the recursive-make backend. */
+const BACKEND_INVALIDATING_SUFFIXES = ['moz.build', 'moz.configure', 'Makefile.in'];
+/**
+ * Returns true when the file path matches a pattern that forces
+ * `mach configure` to regenerate the backend. Exported for testing.
+ */
+export function isBackendInvalidatingFile(path) {
+    for (const suffix of BACKEND_INVALIDATING_SUFFIXES) {
+        if (path === suffix || path.endsWith(`/${suffix}`))
+            return true;
+    }
+    return false;
+}
+/**
+ * Collects engine-relative paths of files changed since the baseline's HEAD
+ * SHA plus any workdir modifications. Defensive — git failures surface as
+ * verbose lines and return the files collected so far. An empty result
+ * means "no drift we can prove" rather than "no drift occurred".
+ */
+async function collectBackendRelevantChanges(engineDir, baseline) {
+    const collected = new Set();
+    if (baseline.engineHeadSha) {
+        try {
+            const diff = await git(['diff', '--name-only', `${baseline.engineHeadSha}..HEAD`], engineDir);
+            for (const line of diff.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed)
+                    collected.add(trimmed);
+            }
+        }
+        catch (error) {
+            if (!isMissingHeadError(error)) {
+                verbose(`Auto-configure: could not diff engine against baseline — ${toError(error).message}`);
+            }
+        }
+    }
+    try {
+        if (await hasChanges(engineDir)) {
+            const worktreeDiff = await git(['diff', '--name-only', 'HEAD'], engineDir);
+            for (const line of worktreeDiff.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed)
+                    collected.add(trimmed);
+            }
+            for (const file of await getUntrackedFiles(engineDir)) {
+                collected.add(file);
+            }
+        }
+    }
+    catch (error) {
+        verbose(`Auto-configure: could not enumerate workdir changes — ${toError(error).message}`);
+    }
+    return [...collected];
+}
 /**
  * Runs the shared pre-flight steps for build and package commands:
  * 1. Cleans Furnace stories from engine (prevents leaking into production)
@@ -24,7 +82,7 @@ import { generateMozconfig } from './mach.js';
  * @param config - Loaded FireForge configuration
  * @returns Preparation results
  */
-export async function prepareBuildEnvironment(projectRoot, paths, config) {
+export async function prepareBuildEnvironment(projectRoot, paths, config, options = {}) {
     // Block the build if Furnace has an unresolved repair marker. This prevents
     // building against an engine that may be in an inconsistent state after a
     // failed rollback.
@@ -36,6 +94,33 @@ export async function prepareBuildEnvironment(projectRoot, paths, config) {
                 'Run "fireforge doctor --repair-furnace" to reconcile engine state before building.');
         }
     }
+    // Auto-configure: if any backend-invalidating file (moz.build, moz.configure,
+    // Makefile.in) changed since the last successful build, run `mach configure`
+    // before the build step. Prevents incremental builds from silently skipping
+    // work against a stale recursive-make backend.
+    let reconfigured = false;
+    if (options.previousBaseline) {
+        const changed = await collectBackendRelevantChanges(paths.engine, options.previousBaseline);
+        const invalidating = changed.filter(isBackendInvalidatingFile);
+        if (invalidating.length > 0) {
+            info(`Backend config changed; running mach configure first... (${invalidating.length} file${invalidating.length === 1 ? '' : 's'} touched)`);
+            const configureSpinner = spinner('Running mach configure...');
+            try {
+                const exitCode = await runMach(['configure'], paths.engine);
+                if (exitCode !== 0) {
+                    configureSpinner.error('mach configure exited non-zero; continuing with build anyway');
+                }
+                else {
+                    configureSpinner.stop('Backend regenerated');
+                    reconfigured = true;
+                }
+            }
+            catch (error) {
+                configureSpinner.error('mach configure failed; continuing with build anyway');
+                verbose(`Auto-configure error: ${toError(error).message}`);
+            }
+        }
+    }
     // Clean stories before build to ensure they don't leak into production binary
     await cleanStories(paths.engine);
     // Set up custom branding directory and patch moz.configure
@@ -117,6 +202,6 @@ export async function prepareBuildEnvironment(projectRoot, paths, config) {
         mozconfigSpinner.error('Failed to generate mozconfig');
         throw error;
     }
-    return { furnaceApplied };
+    return { furnaceApplied, reconfigured };
 }
 //# sourceMappingURL=build-prepare.js.map

package/dist/src/core/furnace-operation.d.ts

@@ -4,7 +4,8 @@ import { type RollbackJournal } from './furnace-rollback.js';
  * The signal names the lifecycle wrapper knows how to react to. Spelled out
  * as a literal union (rather than `NodeJS.Signals`) so the public type
  * surface does not depend on the NodeJS global namespace — consumers of
- * `@hominis/fireforge` may compile against tsconfigs that omit `@types/node`.
+ * FireForge's published scoped npm package may compile against tsconfigs
+ * that omit `@types/node`.
  */
 export type FurnaceShutdownSignal = 'SIGINT' | 'SIGTERM';
 /**

package/dist/src/core/furnace-operation.js

@@ -52,16 +52,22 @@ function withTimeout(promise, ms, label) {
  * timeout so a stuck I/O operation cannot hang the process indefinitely.
  */
 export async function rollbackActiveOperationsForSignal(signal) {
+    // Snapshot the active operations so we don't race with `runFurnaceMutation`
+    // clearing slots during normal completion. Filter completed bodies so a
+    // body sitting in its finally-block cleanup window is not counted as live
+    // work — this would mis-trigger the rollback banner for plain `fireforge
+    // run` (which never registers a mutation but can receive SIGTERM).
+    const snapshot = [...activeOperations.values()].filter((op) => !op.completed);
+    if (snapshot.length === 0) {
+        // Nothing to roll back. Stay silent so commands that never mutated (run,
+        // watch, test, doctor) don't print an alarming "rolling back mutations"
+        // line on Ctrl+C / SIGTERM. Leave `signalRollbackInFlight` false so a
+        // subsequent registrant can still trigger the full path.
+        return;
+    }
     signalRollbackInFlight = true;
     warn(`Received ${signal}; rolling back in-flight furnace mutations…`);
-    // Snapshot the active operations so we don't race with `runFurnaceMutation`
-    // clearing slots during normal completion.
-    const snapshot = [...activeOperations.values()];
     for (const op of snapshot) {
-        // If the body completed successfully and is in its finally-block cleanup
-        // (deleting the token), skip rollback — the mutation committed cleanly.
-        if (op.completed)
-            continue;
         const cleanupErrors = [];
         // Run extra cleanup callbacks first (e.g. preview's cleanStories), so the
         // engine is in its tidiest possible shape before the journal restore

package/dist/src/core/mach-error-hints.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Pattern-based translator for cryptic mozbuild / mach errors.
+ *
+ * Each entry maps a stderr regex to an actionable hint. The goal is not to
+ * parse every mach failure — it's to convert the handful of errors whose
+ * message is non-obvious into a one-line "here's what to change". New
+ * entries should only be added when a concrete diagnosis of the cryptic
+ * output has been established; low-confidence hints would train operators
+ * to ignore the translator.
+ */
+/** A single translator entry. */
+export interface MachErrorHint {
+    /** Pattern to search within the captured mach stderr. */
+    pattern: RegExp;
+    /** Actionable, one-line hint to surface alongside the raw mach output. */
+    hint: string;
+}
+/**
+ * Registered hint patterns. Order-sensitive: the first match wins per
+ * pattern, but multiple distinct patterns may fire for the same stderr.
+ */
+export declare const MACH_ERROR_HINTS: MachErrorHint[];
+/**
+ * Scans captured stderr for known mach errors and returns matching hints.
+ * Pure function — safe to call on any string; never throws.
+ * @param stderr Captured mach stderr.
+ * @returns Ordered, de-duplicated list of hint strings. Empty when nothing matches.
+ */
+export declare function explainMachError(stderr: string): string[];

package/dist/src/core/mach-error-hints.js

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Pattern-based translator for cryptic mozbuild / mach errors.
+ *
+ * Each entry maps a stderr regex to an actionable hint. The goal is not to
+ * parse every mach failure — it's to convert the handful of errors whose
+ * message is non-obvious into a one-line "here's what to change". New
+ * entries should only be added when a concrete diagnosis of the cryptic
+ * output has been established; low-confidence hints would train operators
+ * to ignore the translator.
+ */
+/**
+ * Registered hint patterns. Order-sensitive: the first match wins per
+ * pattern, but multiple distinct patterns may fire for the same stderr.
+ */
+export const MACH_ERROR_HINTS = [
+    {
+        pattern: /mozbuild\.preprocessor\.Preprocessor\.Error[\s\S]*?no preprocessor directives found/,
+        hint: 'A file registered under JS_PREFERENCE_PP_FILES contains no preprocessor directives. ' +
+            'Use JS_PREFERENCE_FILES instead, or add at least one #filter / #expand directive to the file.',
+    },
+];
+/**
+ * Scans captured stderr for known mach errors and returns matching hints.
+ * Pure function — safe to call on any string; never throws.
+ * @param stderr Captured mach stderr.
+ * @returns Ordered, de-duplicated list of hint strings. Empty when nothing matches.
+ */
+export function explainMachError(stderr) {
+    if (!stderr) {
+        return [];
+    }
+    const hits = [];
+    const seen = new Set();
+    for (const { pattern, hint } of MACH_ERROR_HINTS) {
+        if (pattern.test(stderr) && !seen.has(hint)) {
+            seen.add(hint);
+            hits.push(hint);
+        }
+    }
+    return hits;
+}
+//# sourceMappingURL=mach-error-hints.js.map

package/dist/src/core/mach.d.ts

@@ -57,14 +57,17 @@ export declare function bootstrap(engineDir: string): Promise<number>;
  */
 export declare function bootstrapWithOutput(engineDir: string): Promise<MachCommandResult>;
 /**
- * Runs a full mach build.
+ * Runs a full mach build. On a non-zero exit, any matched error hints are
+ * surfaced on top of the raw mach output so operators get an actionable
+ * nudge alongside the cryptic mozbuild traceback.
  * @param engineDir - Path to the engine directory
  * @param jobs - Number of parallel jobs (optional)
  * @returns Exit code
  */
 export declare function build(engineDir: string, jobs?: number): Promise<number>;
 /**
- * Runs a fast UI-only build.
+ * Runs a fast UI-only build. On a non-zero exit, any matched error hints are
+ * surfaced on top of the raw mach output.
  * @param engineDir - Path to the engine directory
  * @returns Exit code
  */

package/dist/src/core/mach.js

@@ -2,7 +2,9 @@
 import { join } from 'node:path';
 import { MachNotFoundError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
+import { warn } from '../utils/logger.js';
 import { exec, execInherit, execInheritCapture, execStream } from '../utils/process.js';
+import { explainMachError } from './mach-error-hints.js';
 import { getPython } from './mach-python.js';
 // Re-export sub-modules so existing `from './mach.js'` imports keep working.
 export { buildArtifactMismatchMessage, hasBuildArtifacts, } from './mach-build-artifacts.js';
@@ -109,7 +111,23 @@ export async function bootstrapWithOutput(engineDir) {
     return runMachInheritCapture(['bootstrap', '--application-choice', 'browser'], engineDir);
 }
 /**
- * Runs a full mach build.
+ * Prints any matched {@link MachErrorHint} hints for the captured stderr.
+ * No-op when nothing matches. Always called before a non-zero exit propagates
+ * so the hint sits immediately below the raw mach error in the operator's
+ * terminal.
+ */
+function surfaceMachErrorHints(stderr) {
+    const hints = explainMachError(stderr);
+    if (hints.length === 0)
+        return;
+    for (const hint of hints) {
+        warn(`Hint: ${hint}`);
+    }
+}
+/**
+ * Runs a full mach build. On a non-zero exit, any matched error hints are
+ * surfaced on top of the raw mach output so operators get an actionable
+ * nudge alongside the cryptic mozbuild traceback.
  * @param engineDir - Path to the engine directory
  * @param jobs - Number of parallel jobs (optional)
  * @returns Exit code
@@ -119,15 +137,24 @@ export async function build(engineDir, jobs) {
     if (jobs !== undefined) {
         args.push('-j', String(jobs));
     }
-    return runMach(args, engineDir, { inherit: true });
+    const result = await runMachInheritCapture(args, engineDir);
+    if (result.exitCode !== 0) {
+        surfaceMachErrorHints(result.stderr);
+    }
+    return result.exitCode;
 }
 /**
- * Runs a fast UI-only build.
+ * Runs a fast UI-only build. On a non-zero exit, any matched error hints are
+ * surfaced on top of the raw mach output.
  * @param engineDir - Path to the engine directory
  * @returns Exit code
  */
 export async function buildUI(engineDir) {
-    return runMach(['build', 'faster'], engineDir, { inherit: true });
+    const result = await runMachInheritCapture(['build', 'faster'], engineDir);
+    if (result.exitCode !== 0) {
+        surfaceMachErrorHints(result.stderr);
+    }
+    return result.exitCode;
 }
 /**
  * Runs the built browser.

package/dist/src/core/patch-lint-diff-tag.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Diff-scoping for `fireforge lint`.
+ *
+ * Pre-existing patch-state errors and errors introduced by the current task
+ * print identically today, so triaging "is the diff I just produced clean?"
+ * requires mentally subtracting the pre-existing noise. This module
+ * classifies each lint issue as either `introduced` (the file was touched
+ * since the user-supplied git revision) or `cumulative` (pre-existing
+ * drift), without changing what the underlying rules emit.
+ */
+import type { PatchLintIssue } from '../types/commands/index.js';
+/**
+ * Collects engine-relative paths that changed between `rev` and `HEAD`,
+ * plus any workdir modifications and untracked files. An empty set means
+ * "no diff we can prove" — downstream treats every issue as `cumulative`
+ * in that case (operator ran `lint --since HEAD` with no pending work).
+ * @param engineDir Path to the engine git repository.
+ * @param rev Git revision to diff against (e.g. `HEAD`, a branch, a SHA).
+ */
+export declare function collectDiffFilePaths(engineDir: string, rev: string): Promise<Set<string>>;
+/**
+ * Annotates a list of lint issues with `introduced` / `cumulative` tags
+ * based on whether the issue's file is part of the supplied diff set.
+ * Mutates each issue in place AND returns the list for chaining.
+ *
+ * Issues with no file (`issue.file === ''`) — e.g. cross-patch rules that
+ * describe queue-wide state — are always `cumulative` under `--since`
+ * because they describe drift accumulated across many commits, not a
+ * single current-task edit.
+ * @param issues Issues returned by the lint orchestrator.
+ * @param diffFiles File paths touched since the user's revision.
+ */
+export declare function tagLintIssues(issues: PatchLintIssue[], diffFiles: Set<string>): PatchLintIssue[];

package/dist/src/core/patch-lint-diff-tag.js

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Diff-scoping for `fireforge lint`.
+ *
+ * Pre-existing patch-state errors and errors introduced by the current task
+ * print identically today, so triaging "is the diff I just produced clean?"
+ * requires mentally subtracting the pre-existing noise. This module
+ * classifies each lint issue as either `introduced` (the file was touched
+ * since the user-supplied git revision) or `cumulative` (pre-existing
+ * drift), without changing what the underlying rules emit.
+ */
+import { toError } from '../utils/errors.js';
+import { verbose } from '../utils/logger.js';
+import { isMissingHeadError } from './git.js';
+import { git } from './git-base.js';
+import { getUntrackedFiles } from './git-status.js';
+/**
+ * Collects engine-relative paths that changed between `rev` and `HEAD`,
+ * plus any workdir modifications and untracked files. An empty set means
+ * "no diff we can prove" — downstream treats every issue as `cumulative`
+ * in that case (operator ran `lint --since HEAD` with no pending work).
+ * @param engineDir Path to the engine git repository.
+ * @param rev Git revision to diff against (e.g. `HEAD`, a branch, a SHA).
+ */
+export async function collectDiffFilePaths(engineDir, rev) {
+    const files = new Set();
+    try {
+        const commitDiff = await git(['diff', '--name-only', `${rev}...HEAD`], engineDir);
+        for (const line of commitDiff.split('\n')) {
+            const trimmed = line.trim();
+            if (trimmed)
+                files.add(trimmed);
+        }
+    }
+    catch (error) {
+        if (!isMissingHeadError(error)) {
+            verbose(`lint --since: could not diff against ${rev} — ${toError(error).message}`);
+        }
+    }
+    try {
+        const worktreeDiff = await git(['diff', '--name-only', 'HEAD'], engineDir);
+        for (const line of worktreeDiff.split('\n')) {
+            const trimmed = line.trim();
+            if (trimmed)
+                files.add(trimmed);
+        }
+    }
+    catch (error) {
+        verbose(`lint --since: could not enumerate workdir diff — ${toError(error).message}`);
+    }
+    try {
+        for (const file of await getUntrackedFiles(engineDir)) {
+            files.add(file);
+        }
+    }
+    catch (error) {
+        verbose(`lint --since: could not list untracked files — ${toError(error).message}`);
+    }
+    return files;
+}
+/**
+ * Annotates a list of lint issues with `introduced` / `cumulative` tags
+ * based on whether the issue's file is part of the supplied diff set.
+ * Mutates each issue in place AND returns the list for chaining.
+ *
+ * Issues with no file (`issue.file === ''`) — e.g. cross-patch rules that
+ * describe queue-wide state — are always `cumulative` under `--since`
+ * because they describe drift accumulated across many commits, not a
+ * single current-task edit.
+ * @param issues Issues returned by the lint orchestrator.
+ * @param diffFiles File paths touched since the user's revision.
+ */
+export function tagLintIssues(issues, diffFiles) {
+    for (const issue of issues) {
+        if (!issue.file) {
+            issue.tag = 'cumulative';
+            continue;
+        }
+        issue.tag = diffFiles.has(issue.file) ? 'introduced' : 'cumulative';
+    }
+    return issues;
+}
+//# sourceMappingURL=patch-lint-diff-tag.js.map

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

@@ -281,6 +281,21 @@ export interface FurnaceCreateOptions {
      * `XPCSHELL_TESTS_MANIFESTS`).
      */
     xpcshell?: boolean;
+    /**
+     * Test harness style to scaffold when `--with-tests` is set.
+     *
+     * - `mochikit` (default when `--with-tests` is set alone) — a MochiKit
+     *   test at `engine/toolkit/content/tests/widgets/test_<tag>.html` that
+     *   loads the component module directly via `chrome://global/` and
+     *   asserts against `customElements`. Runs today on forks whose
+     *   top-level chrome document (e.g. `mybrowser.xhtml`) lacks a
+     *   `tabbrowser`, because it doesn't go through `URILoadingHelper`.
+     * - `browser-chrome` — today's browser-mochitest scaffold, requires a
+     *   working tabbrowser. Use for components that talk to the browser
+     *   window or open URLs.
+     * - `xpcshell` — equivalent to setting `--xpcshell`; headless, storage-only.
+     */
+    testStyle?: 'mochikit' | 'browser-chrome' | 'xpcshell';
     /** Stock component tag names composed internally by this component */
     compose?: string[];
 }
@@ -294,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/dist/src/types/commands/patches.d.ts

@@ -96,4 +96,13 @@ export interface PatchLintIssue {
     message: string;
     /** Severity: errors block export, warnings are advisory, notices are informational (not counted) */
     severity: 'error' | 'warning' | 'notice';
+    /**
+     * Diff-scoping tag populated by `lint --since <rev>`. Absent when the
+     * caller did not request diff-scoping.
+     *
+     * - `introduced` — the issue's file was touched in the diff since `<rev>`.
+     * - `cumulative` — the issue is pre-existing patch-state drift not
+     *   introduced by the current task.
+     */
+    tag?: 'introduced' | 'cumulative';
 }

package/dist/src/types/furnace.d.ts

@@ -106,7 +106,7 @@ export interface FurnaceConfig {
  * state before clearing authoring markers. The string is surfaced in doctor's
  * failure message verbatim, so new entries should be self-explanatory.
  */
-export type FurnacePendingRepairOperation = 'preview-teardown' | 'apply-rollback' | 'deploy-rollback' | 'remove-rollback' | 'create-rollback' | 'override-rollback' | 'scan-rollback' | 'rename-rollback' | 'refresh-rollback';
+export type FurnacePendingRepairOperation = 'preview-teardown' | 'apply-rollback' | 'deploy-rollback' | 'remove-rollback' | 'create-rollback' | 'override-rollback' | 'scan-rollback' | 'rename-rollback' | 'refresh-rollback' | 'chrome-doc-rollback';
 /**
  * Marker persisted into `.fireforge/furnace-state.json` when a furnace
  * mutation failed to roll back cleanly. Its presence tells the next

package/package.json

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