@hominis/fireforge 0.15.3 → 0.15.4

package/CHANGELOG.md

@@ -47,6 +47,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.

package/README.md

@@ -429,7 +429,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/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.4",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",