@hominis/fireforge 0.15.2 → 0.15.4

package/CHANGELOG.md

@@ -36,12 +36,41 @@
 
 - New `furnace create --xpcshell` flag scaffolds an xpcshell test harness alongside (or instead of) the browser-chrome mochitest that `--with-tests` already produces. xpcshell runs headless without a `tabbrowser`, so storage-layer / observer-driven / module-loading code on forks that do not mount the upstream browser chrome (no `openLinkIn` → `URILoadingHelper`) can be covered without the harness complaining about a missing tab strip. Writes `test_<name>_module_loads.js` and an `xpcshell.toml` manifest into `engine/browser/base/content/test/<binary-name>-xpcshell/<component-name>/`. Registration in `XPCSHELL_TESTS_MANIFESTS` is left to the operator — the moz.build that should own the entry depends on where the component lives.
 
+### 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.
+- 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.
+
+### Lint
+
+- `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.
+
+### Furnace create
+
+- New `--test-style <mochikit|browser-chrome|xpcshell>` option for `furnace create --with-tests`. `mochikit` (the new default when `--with-tests` is set alone) scaffolds a `chrome://mochikit/...` test under `engine/toolkit/content/tests/widgets/test_<tag>.html` that loads the component module directly and smoke-asserts `customElements.whenDefined(tag)`. Runs today against forks whose top-level chrome document lacks a `tabbrowser` (the class of bug that forced `--xpcshell` for storage-layer code) because the harness doesn't traverse `URILoadingHelper.openLinkIn`. `browser-chrome` is the former default and requires a working tabbrowser; `xpcshell` is equivalent to `--xpcshell`. Backwards-compat: `--xpcshell` alone still works; conflicting flag combinations are rejected up-front.
+
+### Run / signals
+
+- `fireforge run` (and every other command that never registers a furnace mutation) no longer prints the alarming `Received SIGTERM; rolling back in-flight furnace mutations…` line when the CLI receives SIGINT or SIGTERM. The global signal handler now gates the rollback banner on the presence of at least one live mutation in the registry — plain launches exit silently with code 130/143 as they always did. A new regression test asserts `warn` is not called when no operations are registered.
+
 ### Internal
 
 - Extracted `furnace-apply-ftl.ts`, `furnace-config-tokens.ts`, and `create-templates.ts` to keep apply / config / scaffolding files under the per-file LOC budget after the new features landed. `parseStringArray` is now exported from `furnace-config.ts` for cross-module reuse.
 - 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.
+- 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`.
 
 ## 0.14.0
 

package/README.md

@@ -293,6 +293,7 @@ There are three component types:
 fireforge furnace scan                             # discover components in the engine
 fireforge furnace override moz-button -t css-only  # fork with CSS-only restyle
 fireforge furnace create moz-my-widget             # scaffold a new component
+fireforge furnace chrome-doc create mybrowser      # scaffold a top-level chrome document
 fireforge furnace deploy                           # apply to engine/ + validate
 fireforge furnace status                           # workspace vs engine drift
 fireforge furnace diff moz-button                  # unified diff against baseline
@@ -300,6 +301,39 @@ fireforge furnace diff moz-button                  # unified diff against baseli
 
 `furnace deploy` validates components before applying. As always, errors block, warnings are advisory. `fireforge build` and `fireforge test --build` run apply automatically — when apply wrote files during a build, the build prints a `Furnace: source → engine sync wrote N component(s) …` banner naming every component that was synced, so it is obvious whether engine/ was freshly updated. Use `fireforge doctor --repair-furnace` if the engine gets out of sync.
 
+### Scaffolding top-level chrome documents
+
+Custom elements live under `toolkit/content/widgets`, but a fork's top-level chrome document (`browser.xhtml` equivalents like `mybrowser.xhtml`, `about:*` panels, onboarding flows) lives at `browser/base/content/` and needs jar.mn, jar.inc.mn, and locales/jar.mn entries to reach the packaged bundle. `furnace chrome-doc create <name>` handles that boilerplate:
+
+```bash
+fireforge furnace chrome-doc create mybrowser              # full chrome (titlebar + windowtype)
+fireforge furnace chrome-doc create overlay --no-titlebar  # frameless overlay
+```
+
+The command writes:
+
+- `engine/browser/base/content/<name>.xhtml` — XHTML shell, optional titlebar-buttonbox, Fluent `<link>`.
+- `engine/browser/base/content/<name>.js` — startup-topic observer fired on first idle.
+- `engine/browser/themes/shared/<name>-chrome.css` — scoped CSS; emits the macOS `.titlebar-button { display: none }` carve-out under `--no-titlebar`.
+- `engine/browser/locales/en-US/browser/<name>.ftl` — Fluent stub keyed on `<name>-window-title`.
+- Appends the corresponding `jar.mn` / `jar.inc.mn` / `locales/jar.mn` entries.
+
+Writes are transactional: a SIGINT mid-scaffold rolls back every touched file. Requires an existing engine — run `fireforge download` first.
+
+### Picking a test harness for `furnace create`
+
+`furnace create --with-tests` defaults to a MochiKit test at `engine/toolkit/content/tests/widgets/test_<tag>.html`. MochiKit tests load the component module via `chrome://global/` and don't need a `tabbrowser`, so they run against any fork — including bespoke chrome documents (`mybrowser.xhtml`-class) that deliberately omit the upstream browser chrome.
+
+Three styles are available via `--test-style`:
+
+| Style            | When to use                                                                                                                                                                                                         |
+| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `mochikit`       | Default. Pure-UI custom elements. Runs today against non-tabbrowser chrome. Emits `test_<tag>.html` under `toolkit/content/tests/widgets/`.                                                                         |
+| `browser-chrome` | Element talks to the browser window (open URLs, manipulate tabs). Requires a working `tabbrowser` in the chrome document. Emits the `browser_<bin>_<tag>.js` scaffold and registers it in `browser/base/moz.build`. |
+| `xpcshell`       | Storage-layer, observer-driven, or ESM-loading code. Headless, no tabbrowser. Emits `test_<name>_module_loads.js` + `xpcshell.toml` (registration in `XPCSHELL_TESTS_MANIFESTS` is left to the operator).           |
+
+`--xpcshell` is preserved as an alias for `--test-style=xpcshell`; conflicting flag combinations (`--xpcshell --test-style=mochikit`) are rejected.
+
 ## Additional Commands
 
 The commands below cover project configuration, patch queue management, build packaging and development utilities. Run `fireforge <command> --help` for full option details.
@@ -348,6 +382,26 @@ fireforge watch
 fireforge token --name "--my-color" --value "light-dark(#fff, #000)"
 ```
 
+### Diff-scoped lint (`lint --since`)
+
+`fireforge lint --since <git-rev>` tags each issue as `[introduced]` or `[cumulative]` based on whether its file changed since `<git-rev>`:
+
+```bash
+fireforge lint --since HEAD~1            # just the current commit
+fireforge lint --since main              # everything since main
+fireforge lint --since abc1234           # since a specific SHA
+```
+
+The summary line splits counts — e.g. `Lint: 2 introduced error(s), 0 introduced warning(s); 5 cumulative error(s), 1 cumulative warning(s)` — so triage of "did my diff introduce any of these?" is a one-glance check on a large patch series. Exit code still fails on any error (introduced or cumulative); the flag is purely a display / audit tool. Without `--since`, output is unchanged.
+
+### Post-build audit and auto-configure
+
+`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 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.
+
 ## Configuration
 
 `fireforge.json` at your project root:
@@ -375,7 +429,7 @@ fireforge token --name "--my-color" --value "light-dark(#fff, #000)"
 
 **`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/build.js

@@ -1,11 +1,14 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { InvalidArgumentError as CommanderInvalidArgumentError } from 'commander';
 import { validateBrandOverride } from '../core/brand-validation.js';
+import { auditBuildArtifacts } from '../core/build-audit.js';
+import { readBuildBaseline, writeBuildBaseline } from '../core/build-baseline.js';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { build, buildArtifactMismatchMessage, buildUI, hasBuildArtifacts } from '../core/mach.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
+import { toError } from '../utils/errors.js';
 import { checkDiskSpace, pathExists } from '../utils/fs.js';
 import { error, info, intro, outro, verbose, warn } from '../utils/logger.js';
 import { pickDefined } from '../utils/options.js';
@@ -60,8 +63,13 @@ export async function buildCommand(projectRoot, options) {
         // Future: Load brand-specific config from fireforge.json brands section
         info(`Brand: ${options.brand}`);
     }
-    // Shared pre-flight: branding, Furnace, mozconfig
-    await prepareBuildEnvironment(projectRoot, paths, config);
+    // Read the previous build baseline BEFORE prepareBuildEnvironment so the
+    // auto-configure step there can detect moz.build-family changes since the
+    // last successful build. The post-build audit below reuses the same
+    // baseline to diff engine changes against dist artifacts.
+    const previousBaseline = await readBuildBaseline(projectRoot);
+    // Shared pre-flight: branding, Furnace, mozconfig, auto-configure
+    await prepareBuildEnvironment(projectRoot, paths, config, { previousBaseline });
     const jobs = resolveJobCount(options, config.build?.jobs);
     // Run build
     info(`Starting ${buildType.toLowerCase()} build...`);
@@ -90,6 +98,25 @@ export async function buildCommand(projectRoot, options) {
         error(`Build failed after ${timeStr}`);
         throw new BuildError(`Build failed with exit code ${exitCode}`, options.ui ? 'mach build faster' : 'mach build');
     }
+    // Warn-only post-build audit: surfaces silent packaging drops (files
+    // edited in engine/ but never registered for packaging) against the
+    // previous-build baseline. Never fails the build; the worst case is a
+    // warning an operator chooses to investigate.
+    try {
+        await auditBuildArtifacts(projectRoot, paths.engine, previousBaseline);
+    }
+    catch (auditError) {
+        verbose(`Audit skipped: ${toError(auditError).message}`);
+    }
+    // Record a fresh baseline only on clean success so the next run audits
+    // against this build's HEAD. A failed build keeps the prior baseline so
+    // the next attempt still catches long-standing packaging drops.
+    try {
+        await writeBuildBaseline(projectRoot, paths.engine, config.binaryName);
+    }
+    catch (baselineError) {
+        verbose(`Could not persist build baseline: ${toError(baselineError).message}`);
+    }
     outro(`Build completed in ${timeStr}!`);
 }
 /** Registers the build command on the CLI program. */

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/furnace/chrome-doc-templates.d.ts

@@ -0,0 +1,49 @@
+/**
+ * File-content templates for `fireforge furnace chrome-doc create`.
+ * Extracted so the command entrypoint stays under the per-file LOC budget
+ * and each template can be exercised in isolation.
+ *
+ * The templates here mirror the shape of top-level chrome documents in
+ * upstream Firefox (browser.xhtml, privatebrowsing/aboutPrivateBrowsing.html,
+ * etc.) minus the fork-specific wiring. A fork author fills in the body.
+ */
+/**
+ * XHTML shell for a top-level chrome document.
+ *
+ * The emitted document:
+ * - Declares `windowtype="navigator:browser"` when `withTitlebar` is true
+ *   so chrome-wide stylesheets that target the browser window still apply.
+ * - Emits a titlebar-buttonbox placeholder when `withTitlebar` is true so
+ *   platform-native window controls render.
+ * - Links the per-document CSS at `chrome://browser/content/<name>-chrome.css`
+ *   and the Fluent bundle `browser/<name>.ftl`.
+ */
+export declare function generateChromeDocXhtml(name: string, withTitlebar: boolean, license: string): string;
+/**
+ * ESM bootstrap script for the chrome document.
+ *
+ * The generated script fires a startup observer topic on the first idle
+ * callback so other chrome code can wait on the document being ready.
+ * Mirrors the pattern FireForge-built forks use to coordinate per-window
+ * init across multiple top-level documents.
+ */
+export declare function generateChromeDocJs(name: string, licenseHeader: string): string;
+/**
+ * Scoped CSS for a chrome document. When `withTitlebar` is false the
+ * macOS `.titlebar-button { display: none }` carve-out is emitted so
+ * frameless overlay-style documents don't inherit the platform window
+ * controls that `global.css` applies by default.
+ */
+export declare function generateChromeDocCss(name: string, withTitlebar: boolean, licenseHeader: string): string;
+/** Fluent stub — one placeholder message keyed to the window title. */
+export declare function generateChromeDocFtl(name: string, licenseHeader: string): string;
+/**
+ * Single-line jar.mn entry that registers an xhtml + js pair under
+ * `content/browser/`. Emits the `*` preprocessor flag so both files flow
+ * through `#filter substitution` for FireForge brand-name substitution.
+ */
+export declare function jarMnEntriesForChromeDoc(name: string): string[];
+/** jar.inc.mn entry that registers the scoped CSS under `content/browser/`. */
+export declare function jarIncMnEntryForChromeDoc(name: string): string;
+/** locales/jar.mn entry that registers the `.ftl` under the browser locale bundle. */
+export declare function localeJarMnEntryForChromeDoc(name: string): string;

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

@@ -0,0 +1,151 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * File-content templates for `fireforge furnace chrome-doc create`.
+ * Extracted so the command entrypoint stays under the per-file LOC budget
+ * and each template can be exercised in isolation.
+ *
+ * The templates here mirror the shape of top-level chrome documents in
+ * upstream Firefox (browser.xhtml, privatebrowsing/aboutPrivateBrowsing.html,
+ * etc.) minus the fork-specific wiring. A fork author fills in the body.
+ */
+/**
+ * XHTML shell for a top-level chrome document.
+ *
+ * The emitted document:
+ * - Declares `windowtype="navigator:browser"` when `withTitlebar` is true
+ *   so chrome-wide stylesheets that target the browser window still apply.
+ * - Emits a titlebar-buttonbox placeholder when `withTitlebar` is true so
+ *   platform-native window controls render.
+ * - Links the per-document CSS at `chrome://browser/content/<name>-chrome.css`
+ *   and the Fluent bundle `browser/<name>.ftl`.
+ */
+export function generateChromeDocXhtml(name, withTitlebar, license) {
+    const windowAttr = withTitlebar ? ' windowtype="navigator:browser"' : '';
+    const titlebarMarkup = withTitlebar
+        ? `
+    <hbox class="titlebar-buttonbox-container">
+      <hbox class="titlebar-buttonbox"></hbox>
+    </hbox>`
+        : '';
+    return `<?xml version="1.0"?>
+<!-- SPDX-License-Identifier: ${license} -->
+<!DOCTYPE window>
+<window
+    xmlns="http://www.w3.org/1999/xhtml"
+    xmlns:xul="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
+    id="${name}-window"${windowAttr}
+    data-l10n-id="${name}-window-title"
+    role="application">
+  <head>
+    <meta charset="utf-8" />
+    <title data-l10n-id="${name}-window-title"></title>
+    <link rel="localization" href="browser/${name}.ftl" />
+    <link rel="stylesheet" href="chrome://global/skin/global.css" />
+    <link rel="stylesheet" href="chrome://browser/content/${name}-chrome.css" />
+    <script src="chrome://browser/content/${name}.js"></script>
+  </head>
+  <body>${titlebarMarkup}
+    <main id="${name}-main"></main>
+  </body>
+</window>
+`;
+}
+/**
+ * ESM bootstrap script for the chrome document.
+ *
+ * The generated script fires a startup observer topic on the first idle
+ * callback so other chrome code can wait on the document being ready.
+ * Mirrors the pattern FireForge-built forks use to coordinate per-window
+ * init across multiple top-level documents.
+ */
+export function generateChromeDocJs(name, licenseHeader) {
+    const topic = `${name}-startup`;
+    return `${licenseHeader}
+
+"use strict";
+
+// Fire a startup topic on first idle so subscribers can defer their own
+// init until this document is ready. Observers see the document element as
+// the subject; use \`aSubject instanceof Ci.nsIDOMWindow\` if you need the
+// containing window instead.
+window.addEventListener(
+  "DOMContentLoaded",
+  () => {
+    window.requestIdleCallback?.(() => {
+      try {
+        Services.obs.notifyObservers(document.documentElement, "${topic}");
+      } catch (error) {
+        // Observer notifications should never block document init — log
+        // but don't throw so a missing observer service (headless / test
+        // harness) still leaves the document usable.
+        console.error("Failed to fire ${topic} observer:", error);
+      }
+    });
+  },
+  { once: true }
+);
+`;
+}
+/**
+ * Scoped CSS for a chrome document. When `withTitlebar` is false the
+ * macOS `.titlebar-button { display: none }` carve-out is emitted so
+ * frameless overlay-style documents don't inherit the platform window
+ * controls that `global.css` applies by default.
+ */
+export function generateChromeDocCss(name, withTitlebar, licenseHeader) {
+    const titlebarOverrides = withTitlebar
+        ? ''
+        : `
+
+/* Frameless overlay — suppress the platform titlebar buttons that
+   global.css inherits on macOS. Without this carve-out the traffic-light
+   controls render even though the document has no titlebar-buttonbox. */
+:root[windowtype="navigator:browser"] .titlebar-button {
+  display: none;
+}
+`;
+    return `${licenseHeader}
+
+:root {
+  --${name}-padding: 16px;
+}
+
+#${name}-window {
+  display: flex;
+  flex-direction: column;
+  min-height: 100vh;
+}
+
+#${name}-main {
+  flex: 1;
+  padding: var(--${name}-padding);
+}${titlebarOverrides}
+`;
+}
+/** Fluent stub — one placeholder message keyed to the window title. */
+export function generateChromeDocFtl(name, licenseHeader) {
+    return `${licenseHeader}
+
+${name}-window-title = ${name}
+`;
+}
+/**
+ * Single-line jar.mn entry that registers an xhtml + js pair under
+ * `content/browser/`. Emits the `*` preprocessor flag so both files flow
+ * through `#filter substitution` for FireForge brand-name substitution.
+ */
+export function jarMnEntriesForChromeDoc(name) {
+    return [
+        `*   content/browser/${name}.xhtml                (content/${name}.xhtml)`,
+        `    content/browser/${name}.js                   (content/${name}.js)`,
+    ];
+}
+/** jar.inc.mn entry that registers the scoped CSS under `content/browser/`. */
+export function jarIncMnEntryForChromeDoc(name) {
+    return `    content/browser/${name}-chrome.css           (shared/${name}-chrome.css)`;
+}
+/** locales/jar.mn entry that registers the `.ftl` under the browser locale bundle. */
+export function localeJarMnEntryForChromeDoc(name) {
+    return `    locale/browser/${name}.ftl                    (%${name}.ftl)`;
+}
+//# sourceMappingURL=chrome-doc-templates.js.map

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

@@ -0,0 +1,34 @@
+/**
+ * `fireforge furnace chrome-doc create <name>` — scaffolds a top-level
+ * chrome document (xhtml + js + css + ftl + jar.mn registrations).
+ *
+ * Motivation: `furnace create` covers custom elements under
+ * `toolkit/content/widgets/`, but top-level chrome documents (the
+ * `mybrowser.xhtml`-class entry points a fork adds alongside or instead
+ * of `browser.xhtml`) are today hand-authored with error-prone jar.mn +
+ * jar.inc.mn + locales/jar.mn glue. The `*` preprocessor flag, the
+ * macOS titlebar-button carve-out, the startup-topic observer, and the
+ * Fluent linkage each have silent-break failure modes.
+ *
+ * This command writes the four source files and appends three jar.mn
+ * entries under a rollback journal identical in shape to `furnace create`.
+ * A SIGINT mid-scaffold restores every touched file; a successful run
+ * leaves the tree ready for `fireforge build`.
+ */
+/** Options for `furnace chrome-doc create`. */
+export interface FurnaceChromeDocCreateOptions {
+    /**
+     * Emit the titlebar-buttonbox markup and leave platform window controls
+     * visible. Defaults to `true` because the common case is a full chrome
+     * document (not a frameless overlay). Frameless callers pass
+     * `--no-titlebar`.
+     */
+    titlebar?: boolean;
+}
+/**
+ * Runs `furnace chrome-doc create <name>`.
+ * @param projectRoot Root directory of the project.
+ * @param name Chrome-doc name (e.g. `mybrowser`, `aboutonboarding`).
+ * @param options CLI-provided options.
+ */
+export declare function furnaceChromeDocCreateCommand(projectRoot: string, name: string, options?: FurnaceChromeDocCreateOptions): Promise<void>;

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

@@ -0,0 +1,168 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge furnace chrome-doc create <name>` — scaffolds a top-level
+ * chrome document (xhtml + js + css + ftl + jar.mn registrations).
+ *
+ * Motivation: `furnace create` covers custom elements under
+ * `toolkit/content/widgets/`, but top-level chrome documents (the
+ * `mybrowser.xhtml`-class entry points a fork adds alongside or instead
+ * of `browser.xhtml`) are today hand-authored with error-prone jar.mn +
+ * jar.inc.mn + locales/jar.mn glue. The `*` preprocessor flag, the
+ * macOS titlebar-button carve-out, the startup-topic observer, and the
+ * Fluent linkage each have silent-break failure modes.
+ *
+ * This command writes the four source files and appends three jar.mn
+ * entries under a rollback journal identical in shape to `furnace create`.
+ * A SIGINT mid-scaffold restores every touched file; a successful run
+ * leaves the tree ready for `fireforge build`.
+ */
+import { join } from 'node:path';
+import { loadConfig } from '../../core/config.js';
+import { runFurnaceMutation } from '../../core/furnace-operation.js';
+import { createRollbackJournal, recordCreatedDir, restoreRollbackJournalOrThrow, snapshotFile, } from '../../core/furnace-rollback.js';
+import { DEFAULT_LICENSE, getLicenseHeader } from '../../core/license-headers.js';
+import { InvalidArgumentError } from '../../errors/base.js';
+import { FurnaceError } from '../../errors/furnace.js';
+import { pathExists, readText, writeText } from '../../utils/fs.js';
+import { intro, note, outro } from '../../utils/logger.js';
+import { generateChromeDocCss, generateChromeDocFtl, generateChromeDocJs, generateChromeDocXhtml, jarIncMnEntryForChromeDoc, jarMnEntriesForChromeDoc, localeJarMnEntryForChromeDoc, } from './chrome-doc-templates.js';
+/** Chrome-doc name shape: lowercase ASCII, optional hyphens, no leading digit. */
+const CHROME_DOC_NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+/**
+ * Validates a chrome-doc name. Lowercase ASCII, optional hyphens, no
+ * leading digit — the name is used verbatim in CSS selectors, jar.mn
+ * entries, FTL keys, and file basenames, so anything outside that
+ * character set would break at least one downstream consumer.
+ * @param name Chrome-doc name (file basename without extension).
+ * @throws InvalidArgumentError when the name is unusable.
+ */
+function validateChromeDocName(name) {
+    if (!name.trim()) {
+        throw new InvalidArgumentError('Chrome-doc name is required', 'name');
+    }
+    if (!CHROME_DOC_NAME_PATTERN.test(name)) {
+        throw new InvalidArgumentError('Chrome-doc name must be lowercase ASCII, may contain hyphens, and must not start with a digit (e.g. mybrowser, about-onboarding).', 'name');
+    }
+}
+/**
+ * Appends a line to a jar.mn-style file when that exact line is not
+ * already present. Captures the pre-write contents in the journal so a
+ * mid-run interruption restores the file to its original state.
+ */
+async function appendJarEntryIfAbsent(filePath, entry, journal) {
+    if (!(await pathExists(filePath))) {
+        // Target jar.mn doesn't exist in this tree layout. We do NOT create it
+        // — a fork that moved the jar file needs the operator to choose a
+        // placement. The command surfaces this as a FurnaceError so the user
+        // can investigate rather than silently writing to a non-canonical path.
+        throw new FurnaceError(`Required jar file ${filePath} does not exist; cannot register chrome-doc entry. Check that the fork's engine layout matches the expected browser/ and locales/ tree.`);
+    }
+    const existing = await readText(filePath);
+    if (existing.includes(entry)) {
+        return;
+    }
+    await snapshotFile(journal, filePath);
+    const withEntry = existing.trimEnd() + '\n' + entry + '\n';
+    await writeText(filePath, withEntry);
+}
+/**
+ * Writes the xhtml/js/css/ftl source files plus the three jar.mn
+ * registrations under a rollback journal. Any interruption leaves the
+ * tree in its pre-command state.
+ */
+async function performChromeDocMutations(args) {
+    const journal = createRollbackJournal();
+    args.operationContext.registerJournal(journal);
+    // XHTML uses an inline XML comment since getLicenseHeader has no XML
+    // style — the SPDX convention is a single-line comment at the top.
+    const jsHeader = getLicenseHeader(args.license, 'js');
+    const cssHeader = getLicenseHeader(args.license, 'css');
+    const ftlHeader = getLicenseHeader(args.license, 'hash');
+    const written = [];
+    try {
+        const contentDir = join(args.engineDir, 'browser/base/content');
+        const sharedThemeDir = join(args.engineDir, 'browser/themes/shared');
+        const localeDir = join(args.engineDir, 'browser/locales/en-US/browser');
+        for (const dir of [contentDir, sharedThemeDir, localeDir]) {
+            if (!(await pathExists(dir))) {
+                recordCreatedDir(journal, dir);
+                const { ensureDir } = await import('../../utils/fs.js');
+                await ensureDir(dir);
+            }
+        }
+        const xhtmlPath = join(contentDir, `${args.name}.xhtml`);
+        if (await pathExists(xhtmlPath)) {
+            throw new FurnaceError(`${args.name}.xhtml already exists at ${xhtmlPath}. Remove it or choose a different name.`);
+        }
+        await snapshotFile(journal, xhtmlPath);
+        await writeText(xhtmlPath, generateChromeDocXhtml(args.name, args.withTitlebar, args.license));
+        written.push(`browser/base/content/${args.name}.xhtml`);
+        const jsPath = join(contentDir, `${args.name}.js`);
+        await snapshotFile(journal, jsPath);
+        await writeText(jsPath, generateChromeDocJs(args.name, jsHeader));
+        written.push(`browser/base/content/${args.name}.js`);
+        const cssPath = join(sharedThemeDir, `${args.name}-chrome.css`);
+        await snapshotFile(journal, cssPath);
+        await writeText(cssPath, generateChromeDocCss(args.name, args.withTitlebar, cssHeader));
+        written.push(`browser/themes/shared/${args.name}-chrome.css`);
+        const ftlPath = join(localeDir, `${args.name}.ftl`);
+        await snapshotFile(journal, ftlPath);
+        await writeText(ftlPath, generateChromeDocFtl(args.name, ftlHeader));
+        written.push(`browser/locales/en-US/browser/${args.name}.ftl`);
+        // jar.mn registrations — XHTML + JS go through the `*` preprocessor
+        // for brand substitution, CSS goes through jar.inc.mn, FTL through
+        // the locale jar.
+        const jarMnPath = join(args.engineDir, 'browser/base/jar.mn');
+        for (const entry of jarMnEntriesForChromeDoc(args.name)) {
+            await appendJarEntryIfAbsent(jarMnPath, entry, journal);
+        }
+        written.push('browser/base/jar.mn');
+        const jarIncMnPath = join(args.engineDir, 'browser/themes/shared/jar.inc.mn');
+        await appendJarEntryIfAbsent(jarIncMnPath, jarIncMnEntryForChromeDoc(args.name), journal);
+        written.push('browser/themes/shared/jar.inc.mn');
+        const localeJarMnPath = join(args.engineDir, 'browser/locales/jar.mn');
+        await appendJarEntryIfAbsent(localeJarMnPath, localeJarMnEntryForChromeDoc(args.name), journal);
+        written.push('browser/locales/jar.mn');
+    }
+    catch (error) {
+        await restoreRollbackJournalOrThrow(journal, `Failed to scaffold chrome-doc "${args.name}"`);
+        throw error;
+    }
+    return written;
+}
+/**
+ * Runs `furnace chrome-doc create <name>`.
+ * @param projectRoot Root directory of the project.
+ * @param name Chrome-doc name (e.g. `mybrowser`, `aboutonboarding`).
+ * @param options CLI-provided options.
+ */
+export async function furnaceChromeDocCreateCommand(projectRoot, name, options = {}) {
+    intro('Furnace chrome-doc create');
+    validateChromeDocName(name);
+    const forgeConfig = await loadConfig(projectRoot);
+    const license = forgeConfig.license ?? DEFAULT_LICENSE;
+    const engineDir = join(projectRoot, 'engine');
+    if (!(await pathExists(engineDir))) {
+        throw new FurnaceError('Engine directory not found. Run "fireforge download" first to scaffold a chrome-doc.');
+    }
+    const withTitlebar = options.titlebar ?? true;
+    const written = await runFurnaceMutation(projectRoot, 'chrome-doc-rollback', (ctx) => performChromeDocMutations({
+        name,
+        license,
+        engineDir,
+        withTitlebar,
+        operationContext: ctx,
+    }));
+    note([
+        `Chrome document "${name}" scaffolded:`,
+        ...written.map((f) => `  engine/${f}`),
+        '',
+        'Next steps:',
+        `  1. Edit engine/browser/base/content/${name}.xhtml and fill in the body.`,
+        `  2. Localize strings in engine/browser/locales/en-US/browser/${name}.ftl.`,
+        `  3. Run "fireforge build" to validate packaging (post-build audit will flag`,
+        '     any entry whose file does not land in the dist bundle).',
+    ].join('\n'), name);
+    outro('Chrome document created');
+}
+//# sourceMappingURL=chrome-doc.js.map