@hominis/fireforge 0.15.1 → 0.15.3

package/CHANGELOG.md

@@ -5,7 +5,7 @@
 ### Furnace registration
 
 - `furnace apply` idempotency check is marker-comment-tolerant. Previously the single-line substring match (`content.includes('["tag",')`) missed multi-line entries, and the standalone-line regex anchored on `\s*$`, which did not allow trailing `// <marker>:` comments an operator may have appended to a previously-written entry. A duplicate tag was then inserted on every re-apply, and the second `setElementCreationCallback` invocation threw `NotSupportedError: Operation is not supported` at every window-load. The idempotency check now matches on tag-name column 0 (both single- and multi-line array shapes) and tolerates trailing `//` comments on the line.
-- New optional fireforge.json field `markerComment` (e.g. `"HOMINIS"`) is appended as a `  // HOMINIS:` suffix to every line FireForge writes into `customElements.js`. Keeps fork modifications discoverable and re-applies idempotent without hand-tagging after each apply. The field is threaded through `applyCustomComponent` and `furnace deploy`, not just `furnace create`.
+- New optional fireforge.json field `markerComment` (e.g. `"MYBROWSER"`) is appended as a `  // MYBROWSER:` suffix to every line FireForge writes into `customElements.js`. Keeps fork modifications discoverable and re-applies idempotent without hand-tagging after each apply. The field is threaded through `applyCustomComponent` and `furnace deploy`, not just `furnace create`.
 - `addCustomElementRegistration` and its regex fallback both accept the new marker as an optional parameter; the AST idempotency check and the regex-fallback idempotency check share a single helper (`isTagAlreadyRegistered`).
 
 ### Furnace `--localized`
@@ -17,19 +17,55 @@
 
 ### Furnace validate
 
-- `missing-token-link` now reads `tokenHostDocuments` from furnace.json and scans every configured chrome document for the tokens CSS link. Warning fires only when NONE of them link the tokens CSS; the warning enumerates the documents it actually checked. Previously the check was hardcoded to `browser/base/content/browser.xhtml`, which false-positived on forks that mount components in a different chrome document (e.g. `hominis.xhtml`). Defaults to `["browser/base/content/browser.xhtml"]` when omitted — behaviour is unchanged for projects that never set the field.
+- `missing-token-link` now reads `tokenHostDocuments` from furnace.json and scans every configured chrome document for the tokens CSS link. Warning fires only when NONE of them link the tokens CSS; the warning enumerates the documents it actually checked. Previously the check was hardcoded to `browser/base/content/browser.xhtml`, which false-positived on forks that mount components in a different chrome document (e.g. `mybrowser.xhtml`). Defaults to `["browser/base/content/browser.xhtml"]` when omitted — behaviour is unchanged for projects that never set the field.
 - `no-keyboard-handler` no longer warns when `@click` sits on a native interactive element (`<button>`, `<a href>`, `<input>`, `<select>`, `<textarea>`, `<summary>`, `<details>`, or the Firefox `moz-button`/`moz-toggle`/`moz-checkbox`/`moz-radio`/`moz-menulist` widgets). Those elements dispatch `click` on Enter and Space via the platform, so a duplicate `@keydown`/`@keypress` handler would double-fire. The rule still fires for synthetic interactive markup (e.g. `<div @click>`) and for bare `<a>` without an `href` attribute, which are the real keyboard-a11y hazards.
+- `token-prefix-violation` stops flagging component-owned runtime CSS custom properties. Previously every `var(--foo)` that did not match `tokenPrefix` was rejected as a design-token escape, even when the property was a per-frame state channel (`--cam-x`, `--tile-z`) both written and read by the component. Two relaxations ship together: (a) a new optional `runtimeVariables: string[]` field in `furnace.json` explicitly allowlists cross-component runtime channels (e.g. set in JS, read in the child's CSS); (b) variables that are both declared (`--foo: value;`) and consumed (`var(--foo)`) inside the same CSS file are auto-exempted — no config entry required. The same relaxations apply to the patch-stack lint. The violation message now calls out `runtimeVariables` as the third escape hatch alongside `tokenPrefix` and `tokenAllowlist`.
+- `hardcoded-text` narrowed from a bare `>…<` scan to three context-aware probes: text inside Lit `` html`…` `` template literals, string literals assigned via `.textContent = "…"` / `.innerHTML = "…"`, and XUL-attribute values set via `setAttribute("label"|"title"|"tooltiptext", "…")`. Previously the rule also matched JS comparisons (`if (x > 0 && y < 100)`), long diagnostic strings (`console.error("…")`), and identifier literals passed to `querySelector`, producing noise that trained authors to ignore validator warnings. The file-wide `// furnace-ignore: hardcoded-text` escape hatch is preserved.
 
 ### Run / test
 
 - `fireforge run`, `fireforge watch`, `fireforge build`, and every other `mach` invocation launched with inherited stdio now forward parent `SIGINT`/`SIGTERM` to the child as `SIGTERM` and wait ~1.5 s before escalating to `SIGKILL`. A second Ctrl-C during the grace window escalates immediately (matches the usual "hit Ctrl-C twice to force-quit" UX). Previously the parent could exit before Gecko's `AsyncShutdown` / `profileBeforeChange` blockers finished flushing in-memory state, losing the last few seconds of edits. The grace window is configurable via a new `shutdownGraceMs` option on `execInherit` / `execInheritCapture`.
 - New `fireforge test --doctor` runs a short marionette handshake preflight before (optionally) invoking `mach test`. Spawns the built browser headless, opens a TCP socket to `127.0.0.1:2828`, waits for the handshake bytes, and reports PASS/FAIL with the tail of stderr on FAIL. When `--doctor` is supplied with no test paths, it exits after the preflight — a sub-minute way to tell "marionette wedged" apart from "test failed to discover" when `mach test` hangs for the full 360 s marionette timeout. When supplied with test paths, a FAIL preflight short-circuits before `mach test` runs.
+- `fireforge test --doctor` is now a cascade of six layered probes (engine-present → mach-available → python-available → profile-creatable → browser-spawns → marionette-handshake) with tight per-layer budgets. Previously the single 30 s socket poll gave the same generic "socket did not respond" diagnostic whether mach was missing, Python was unavailable, `/tmp` was not writable, or the browser binary crashed at startup — so operators had no lead on where to start debugging. Each layer now short-circuits with a `[layer N/6: <name>]`-prefixed detail message so the first broken layer is surfaced immediately, and a crashing browser is caught by a short settle window at layer 5 instead of wasting the full budget waiting for bytes that never come.
+
+### Furnace build
+
+- `fireforge build` already auto-applies Furnace components (via `prepareBuildEnvironment`) before the mach build step, but the behaviour was undocumented and silent — operators who edited `components/custom/` and then ran `fireforge build` could not distinguish "auto-apply wrote files" from "nothing changed". A loud `Furnace: source → engine sync wrote N component(s) before build (...)` banner now fires whenever apply wrote files, naming every component that was synced. The `fireforge build --help` description and help footer now call out that apply runs before the build step.
+
+### Furnace create
+
+- 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.
+
+### 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. 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
 
@@ -249,7 +285,7 @@
 ### General improvements
 
 - getPackageRoot up to this point expected hardcoded `@hominis/fireforge`, was changed to just the package name for potential forks and more flexibility when changing project name.
-- Some test generators were derived from early Hominis Browser fork additions, the references to Hominis have been replaced with generic naming.
+- Some test generators were derived from an early downstream fork; the fork-specific names have been replaced with generic naming so the templates apply to any Firefox fork.
 
 ### Build and Git reliability
 

package/README.md

@@ -293,12 +293,46 @@ 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
 ```
 
-`furnace deploy` validates components before applying. As always, errors block, warnings are advisory. `fireforge build` and `fireforge test --build` run apply automatically. Use `fireforge doctor --repair-furnace` if the engine gets out of sync.
+`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
 
@@ -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:
@@ -367,7 +421,7 @@ fireforge token --name "--my-color" --value "light-dark(#fff, #000)"
   "wire": { "subscriptDir": "browser/components/mybrowser" },
   "patchLint": {
     "checkJs": true,
-    "rawColorAllowlist": ["hominis-tokens.css"]
+    "rawColorAllowlist": ["mybrowser-tokens.css"]
   },
   "markerComment": "MYBROWSER"
 }
@@ -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. `hominis.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.
 
 ### `furnace create --localized` for `MozLitElement`
 
@@ -391,6 +445,25 @@ fireforge test --doctor browser/base/content/test/foo/browser_bar.js
 
 Spawns the built browser headless, waits for a marionette handshake on `127.0.0.1:2828`, and reports PASS/FAIL with the tail of the browser's stderr on FAIL. Distinguishes "marionette wedged" (socket silent) from "mach test discovery failed" — both otherwise surface as a silent 360-second hang followed by `Passed: 0, Failed: 0`. Useful as a prefix on routine `fireforge test` invocations when marionette has been flaky.
 
+The probe is a cascade of six layered checks — engine-present → mach-available → python-available → profile-creatable → browser-spawns → marionette-handshake. Each failure is tagged `[layer N/6: <name>]` so the first broken layer is surfaced immediately instead of the whole cascade blocking on the final socket poll. When the browser binary crashes at startup (missing dylib, wrong CPU arch, corrupt profile) the cascade fails at layer 5 within the settle window, not after the full socket timeout.
+
+### Runtime CSS variables in Furnace
+
+Design tokens imported from the fork's palette are enforced by `tokenPrefix`, but some components write and read CSS custom properties as runtime state channels (`--cam-x` per frame, `--tile-z` from a hit-test observer). Two escape hatches exist:
+
+- **Auto-exempt** — a variable that is both declared (`--foo: 0;`) and consumed (`var(--foo)`) inside the same component's CSS file is recognised as a component-local runtime channel. No config entry required.
+- **`furnace.json.runtimeVariables`** — explicit allowlist for names that are _written_ in JS and _read_ in a different file's CSS (cross-component runtime channels that the CSS-only auto-exempt cannot see). Entries must start with `--`.
+
+Both rules compose with the existing `tokenPrefix` / `tokenAllowlist` checks and apply to both component validation and patch-stack lint.
+
+### Test harness options
+
+`fireforge furnace create --with-tests` scaffolds a **browser-chrome mochitest**. Use this when the component renders UI that depends on the tab strip (`openLinkIn` → `URILoadingHelper`, `gBrowser`, etc.).
+
+`fireforge furnace create --xpcshell` scaffolds an **xpcshell test harness** instead. Use this when the component's code path is storage-only, observer-driven, or module-loading logic that does not touch a `tabbrowser`. xpcshell runs headless without browser chrome, so forks without an upstream tab strip can still cover these paths. The scaffolder writes `test_<name>_module_loads.js` + `xpcshell.toml` into `engine/browser/base/content/test/<binary-name>-xpcshell/<component-name>/` and prints a note: registration in `XPCSHELL_TESTS_MANIFESTS` is the operator's call (the moz.build that should own the entry depends on where the component actually lives).
+
+The two flags can be combined — `--with-tests --xpcshell` writes both harnesses.
+
 ## Roadmap
 
 Planned but not yet implemented:

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,16 +98,46 @@ 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. */
 export function registerBuild(program, { getProjectRoot, withErrorHandling }) {
     program
         .command('build')
-        .description('Build the browser')
+        .description('Build the browser (auto-applies Furnace components first)')
         .option('--ui', 'Fast UI-only rebuild')
         .option('-j, --jobs <n>', 'Number of parallel jobs', parseJobCount)
         .option('--brand <name>', 'Build specific brand')
+        .addHelpText('after', [
+        '',
+        'Furnace apply runs automatically before the build step, so edits in',
+        'components/custom/ and components/overrides/ are propagated to the',
+        'engine/ tree every time. The command prints a banner listing the',
+        'components synced during the current invocation.',
+        '',
+        'If you want to preview the engine state without triggering a build,',
+        'run `fireforge furnace apply` directly. For source-change-driven',
+        'rebuild loops during development, use `fireforge watch`.',
+    ].join('\n'))
         .action(withErrorHandling(async (options) => {
         await buildCommand(getProjectRoot(), pickDefined(options));
     }));

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>;