@hominis/fireforge 0.15.7 → 0.15.9

package/CHANGELOG.md

@@ -2,6 +2,50 @@
 
 ## 0.15.0
 
+### Re-export — opt-in `--stamp` and per-patch `lintIgnore`
+
+- New `fireforge re-export --stamp` stamps `sourceEsrVersion` on every successfully re-exported patch to the current `firefox.version` from `fireforge.json`. Previously `re-export` only ever refreshed patch bodies and `filesAffected`; version stamping was exclusive to `rebase`'s `stampPatchVersions` call (plus `doctor --repair-patches-manifest`). An operator asked to "re-export targeting a new ESR" had no in-surface signal that the command could not deliver the version half of that request, and had to route through the full rebase flow (which requires a Firefox source re-download) purely to update a version string. `--stamp` closes that gap for the case where the re-export cleanly refreshes every selected patch — a partial run (any skipped or failed patch) refuses to stamp and the success line notes the refusal, so a torn "some bodies refreshed at old version, some at new" state is not representable. The command description and `--help` text now explicitly call out that `re-export` does NOT change `sourceEsrVersion` by default.
+- New optional `lintIgnore: string[]` field on each patch entry in `patches.json` lists lint check IDs to suppress for that patch specifically. Surgical alternative to `--skip-lint` (which downgrades _every_ error to a warning) for the class of patch that is advisory-noisy by nature — cohesive branding bundles, localised-resource packs, auto-generated manifests — where a rule like `large-patch-lines` is not actionable. Threaded through `lintExportedPatch` as an optional `ignoreChecks` filter, honoured by `re-export`, `re-export --files`, and `lint --per-patch`. The file-level `fireforge-ignore:` comment markers for `raw-color-value` and `forward-import` are unchanged; `lintIgnore` fills the gap at the patch level where no per-line marker can exist (the `.patch` body is regenerated on every export). Unknown check IDs are a no-op so the metadata documents the _intent_ to suppress even if the rule is renamed later.
+- Motivating case: re-exporting a 22-patch queue onto 140.9.0esr after `download --force` failed on `001-branding-branding-assets` with `ERROR [large-patch-lines] (patch): Patch is 15665 lines (hard limit: 3000)` — a 57-file branding bundle that genuinely cannot be split. The only escape was `--skip-lint` (downgrades 22 patches' worth of errors) or the full `rebase` flow (already-wasted Firefox download). With `lintIgnore: ["large-patch-lines", "large-patch-files"]` on that one patch, `re-export --all --scan --stamp` now completes in one call.
+
+### Lint — `--per-patch` scope and aggregate-mode hint
+
+- New `fireforge lint --per-patch` scopes the lint diff to each patch's own `filesAffected` in turn rather than the aggregate `git diff HEAD` across every applied patch. Motivating case: running `fireforge lint` (no args) after `fireforge import` / `fireforge rebase` has just applied a 22-patch queue produces an aggregate diff of every patch summed, which means the patch-size advisory rules (`large-patch-lines`, `large-patch-files`) fire against the sum — e.g. `Patch is 37529 lines`, `Patch affects 126 files` — with `Lint failed` and a non-zero exit code on a repo that is actually in a good state. The aggregate framing reads as a task-specific regression when it is really an artefact of aggregation. `--per-patch` restates the scope so each patch lints as its own isolated diff, honours the patch's own `lintIgnore` entries, and runs the cross-patch rules (`duplicate-new-file-creation`, `forward-import`) once over the whole queue so queue-level findings are not lost by the rescoping. Mutually exclusive with explicit file paths (the two scope contracts are different).
+- Aggregate-mode runs that would otherwise surface a `large-patch-lines` / `large-patch-files` error against a multi-patch queue now print a one-line `NOTE: aggregate diff across all applied patches. Use 'fireforge lint --per-patch' to lint each patch individually; patch-size rules fire against the sum in aggregate mode.` ahead of the failure message, so the operator reaches the per-patch escape hatch without having to read the help text first. The note fires only when the patches directory has at least two entries AND the rule that fired is a patch-size rule — a single-patch queue or a non-size rule behaves identically to before.
+- Per-patch output namespaces every issue with its owning patch filename (`ERROR [relative-import] 001-ui-test.patch :: browser/base/content/a.ts: …`) so triage can attribute findings without cross-referencing patches.json. The passing summary reports how many patches were actually linted (patches with no files on disk or an empty projected diff are silently skipped — they are not a finding).
+
+### Test — xpcshell appdir auto-injection
+
+- `fireforge test` now auto-injects `--app-path=<absolute>` into mach test invocations whose nearest `xpcshell.toml` sets `firefox-appdir = "browser"` on a rebranded fork (appname != `firefox`). Without this, every `resource:///modules/<name>.sys.mjs` import inside the harness throws because the upstream xpcshell harness reads the appdir override under the appname-keyed manifest field (`<appname>-appdir`) — the literal `firefox-appdir = "browser"` directive is silently ignored when `appname` is anything other than `firefox`, so `appPath` falls back to `xrePath` (one level above the real app root). The resolver lives in the new `src/core/xpcshell-appdir.ts`: it walks each test path to the nearest `xpcshell.toml`, reads `mozinfo.json` for the active appname, prefers any `<appname>-appdir` already in the manifest (so an operator who already migrated is not overridden), and otherwise probes `<objDir>/dist/bin/<value>` and `<objDir>/dist/<bundle>.app/Contents/Resources/<value>` for the absolute target. Operator overrides via `--mach-arg=--app-path=…` always win and the resolver is skipped silently when one is detected. Mismatches across multiple test paths (different manifests resolving to different app dirs) and unresolvable manifest values (no candidate under `dist/`) are surfaced as warnings rather than guessed at, so triage can reach the underlying cause instead of debugging a wrong path.
+- The `xpcshell appdir` diagnostic that fires when the injection did not prevent the symptom now branches its "Likely triggers" copy on whether the auto-injection ran. When it ran and the failure persists, the message says so and points at packing or layout mismatches; when it did not run (no manifest found, or appname=`firefox`), the original appname-key explanation is preserved. Adds a fourth troubleshooting option — adding `<appname>-appdir = "browser"` alongside `firefox-appdir = "browser"` in the manifest — so operators can adopt the durable fix instead of relying on injection on every run.
+- `fireforge test` was previously diagnostic-only for this class of failure: it detected the symptom and surfaced a hint suggesting `--mach-arg` overrides. The hint remains as a fallback for cases the resolver cannot fix, but no manual flag is needed for the common case.
+
+### Run — `--smoke-exit` for unattended chrome smoke checks
+
+- New `fireforge run --smoke-exit <seconds>` launches the real built browser with the dev profile, streams the merged console line-by-line, sends `SIGTERM` to the entire child process group at the deadline, and exits non-zero when any `JavaScript error:` / `console.error:` / `[JavaScript Error]` / `###!!! [Parent]` line surfaces inside the smoke window without matching the operator-supplied allowlist. Closes the headless-vs-real-chrome gap that previously forced agents to choose between `fireforge run` (no exit hook, hangs on a human) and `fireforge run --headless` (does not load `browser.xhtml`/`<custom>.xhtml`, so chrome-window constructor errors stay invisible). The motivating case was `TypeError: lazy.HominisEvents.HOMINIS_TOPICS is undefined` thrown from a chrome-document constructor on every window-open, which `--headless` never observed because the main document was never instantiated.
+- Allowlist surface lives in the new `src/core/smoke-patterns.ts`: regex error patterns (`SMOKE_ERROR_PATTERNS`) anchored on the start of each line so embedded mentions of the same prefix inside descriptive prose do not trip the scanner, plus `compileAllowlistFromFile` and `compileAllowlistFromStrings` for `--console-allow-file <path>` and repeatable `--console-allow <regex>` inputs respectively. Allowlisted hits still count toward the summary so operators can see how many lines were suppressed; only unallowed errors drive the exit code. A blank or `#`-prefixed line in an allowlist file is skipped, and a malformed regex throws fast at CLI parse time rather than silently matching nothing.
+- New `--capture-console <file>` mirrors the captured stream to a file path so post-exit inspection has the raw log without re-running. Mirroring is inline with line dispatch and the file is fsync'd on close.
+- Smoke-run exit codes are wired distinctly from `BUILD_ERROR`: `SMOKE_EXIT_FAILURE = 12` (unallowed console errors observed inside the window), `SMOKE_LAUNCH_FAILURE = 13` (browser exited non-clean before the window elapsed — crashes before console wiring, missing profile, etc.). CI pipelines can route these distinctly from compile/config failures and from the existing FireForge exit codes. Carried by the new `SmokeRunError` in `src/errors/run.ts` so the throw site signals both the message and the exit code in one type. The `runMachSmoke()` wrapper in `src/core/mach.ts` handles the deadline-driven SIGTERM/SIGKILL escalation (default 10 s grace between SIGTERM and SIGKILL because Firefox's `AsyncShutdown` and `profileBeforeChange` blockers can take ~5–10 s to flush in-memory state; a shorter grace risks corrupting the dev profile mid-quit). POSIX-only — process-group semantics do not map cleanly onto Windows, so the flag is rejected up-front there. A smoke window shorter than 30 s also surfaces a one-line warning recommending a longer interval, since cold-start time alone can consume that budget on a debug build.
+
+### Furnace create — `--shared-ftl` for feature-scoped Fluent bundles
+
+- `furnace create <tag> --localized --shared-ftl <chrome-uri>` now scaffolds a component that participates in a pre-existing feature-scoped `.ftl` bundle (e.g. `browser/hominis-dock.ftl`) instead of getting its own per-component stub. Without the flag, every `--localized` create produced a `<tag>.ftl` under `components/custom/<tag>/` plus an `insertFTLIfNeeded("toolkit/global/<tag>.ftl")` call in the `.mjs`; on a feature like a dock with eight components sharing one bundle, this stranded seven empty per-component stubs in the workspace and required hand-editing every `.mjs` to point `insertFTLIfNeeded` at the shared file (and accepting that the seven empty stubs would still get packaged into `Resources/localization/en-US/toolkit/global/`). The flag short-circuits all of that: the `.mjs` is generated with the shared path baked in via `generateMjsContent`, the per-component `.ftl` is not written, and the `furnace.json` `custom` entry carries a new `sharedFtl` field so subsequent runs (and validators) know the component participates in a shared bundle.
+- `--shared-ftl` implies `--localized`; combining `--no-localized` with `--shared-ftl` is rejected fast-fail with an actionable message rather than letting the cross-field check inside the config parser surface the same error later. The interactive features prompt is suppressed when `--shared-ftl` is set so the operator is not asked to flip a flag we are about to enforce.
+- `furnace apply` and `furnace remove` honour `sharedFtl` symmetrically: apply does NOT copy a per-component `.ftl` into the FTL tree nor add a locale `jar.mn` entry (the shared file is registered by whoever owns the feature bundle), and remove early-returns from `removeCustomFtlJarMnEntry` so dropping our component's reference does not orphan every other participant in the shared bundle. The dry-run path mirrors apply, so a `--dry-run` plan accurately previews the actual file set.
+- `furnace validate`'s `missing-ftl` structural check is skipped for `sharedFtl` components — there is no per-component `<tag>.ftl` to require. The remaining error message also points at `sharedFtl` as the third option ("Create the file, set localized: false in furnace.json, or switch to sharedFtl") so an operator who hits the warning sees the structured way out alongside the existing two.
+- The `sharedFtl` value is validated in one place (`src/core/shared-ftl.ts`) by both the CLI flag path and the `furnace.json` parser, so the two entry points cannot drift. Backticks, backslashes, and `${` are rejected because the value is interpolated verbatim into the generated `.mjs` template literal — without that check, an unsafe input would either close the template or open an executable expression. `--no-localized + --shared-ftl` and `--shared-ftl=""` (empty after trim) are rejected with structured reasons. The custom-component schema parser was extracted from `furnace-config.ts` into `src/core/furnace-config-custom.ts` to keep the main config module under the per-file LOC budget as the schema continues to gain opt-in fields (`composes`, `keyboardCovered`, `sharedFtl`).
+
+### Furnace validate — `no-keyboard-handler` composition awareness
+
+- `no-keyboard-handler` no longer warns when `@click` sits on a custom-element host whose `composes` entry names a native-interactive child (e.g. `moz-button`, `moz-toggle`, `moz-checkbox`, `moz-radio`, `moz-menulist`). The wrapper's `@click` handler catches keyboard activation transitively — `<moz-button>` itself dispatches `click` on Enter/Space via the platform — so a duplicate `@keydown`/`@keypress` handler on the wrapper would either no-op or double-fire alongside the child's built-in keyboard path. Previously a `hominis-pin-section` rendering a row of `<hominis-dock-button @click=…>` instances flagged `[no-keyboard-handler] Interactive element has @click but no keyboard event handler` on every validate, even though the entire row was fully keyboard-accessible.
+- New optional `keyboardCovered: true` field on a custom component's `furnace.json` entry forces the same skip when the wrapped inner element is hand-authored (e.g. a vendored `<button>`) or is a non-stock `moz-*` widget that does not appear in `composes`. Operator-asserted: setting this to `true` does not re-check the component, so it can be used to silence a genuine finding. The check's docstring calls out the preferred path of adding the wrapped tag to `composes` when that field applies, since `composes` carries semantic value beyond a11y.
+- Unchanged: synthetic interactive markup (`<div @click>`) and bare `<a>` without an `href` attribute still fire the warning. Those are the real keyboard-a11y hazards the rule was written for; the new branches are narrowly scoped to the composition cases that previously trained authors to ignore validator output.
+
+### Test — diagnostics for harness failure modes
+
+- `fireforge test` now detects the `MochitestDesktop.http3Server` AttributeError that crashes the mochitest cleanup path and rewrites it as an actionable hint: branding registration is the lazy-init chain that initialises `http3Server`, so the AttributeError at teardown is almost always a downstream symptom of `chrome://branding` not registering correctly in the fork. The hint enumerates the three concrete checks (branding listed in `browser/branding/moz.build`, `chrome://branding/locale/brand.properties` resolves at runtime, `BROWSER_CHROME_MANIFESTS` registers the chrome.manifest) so operators do not chase the AttributeError as if it were the root cause. Surfaces as a `GeneralError` so the operator sees the diagnostic instead of the generic `BuildError("Tests failed")`. The crash itself remains an upstream Firefox harness bug — FireForge can only diagnose it.
+- New `fireforge test --mach-arg <arg>` (repeatable) forwards a single argument verbatim to `mach test`, after FireForge-managed flags. Escape valve for upstream xpcshell/mochitest flags FireForge does not model directly. Used by the xpcshell appdir hint as the operator's escape valve when auto-injection is the wrong fix; also useful for `--keep-going`, `--verbose`, or `--debugger` while iterating on a flaky test.
+
 ### Furnace create
 
 - `furnace create` now accepts `--dry-run` so operators can preview the planned file set, test scaffold, and `furnace.json` mutation without touching the workspace. Previously the only way to preview a create was `fireforge furnace create --help` followed by running the real command and inspecting the result after the fact — a workflow that stranded a component directory, a furnace.json entry, and (with `--with-tests`) test sources under `engine/` behind every aborted preview. The dry-run path runs every validation the real command would run (name shape, name conflicts, engine pre-existence, `--compose` target existence + cycle detection, prefix warning) BEFORE emitting the plan, so a preview that fails matches a real run that would fail. A new `src/commands/furnace/create-dry-run.ts` owns the plan formatter and the success-note formatter so the two renderings stay in lock-step when the scaffolded layout changes.

package/README.md

@@ -44,7 +44,7 @@ mkdir mybrowser && cd mybrowser
 npm init -y
 npm install --save-dev @hominis/fireforge
 
-npx fireforge setup              # interactive project init
+npx fireforge setup               # interactive project init
 npx fireforge download            # fetch Firefox source (~1 GB)
 npx fireforge bootstrap           # install build deps (may need sudo)
 npx fireforge import              # apply your patches (if any exist)
@@ -56,22 +56,24 @@ Your project now has `fireforge.json`, an `engine/` directory with Firefox sourc
 
 ### Workflow Overview
 
-```bash
-# 1. Make changes inside engine/
-#    Edit browser/base/content/browser.js, add CSS, create new modules...
+1. Make changes inside the `engine/` directory.
+2. Export your changes as a patch:
 
-# 2. Export your changes as a patch
-npx fireforge export browser/base/content/browser.js \
-  --name "custom-toolbar" --category ui
+```bash
+npx fireforge export browser/base/content/browser.js --name "custom-toolbar" --category ui
+```
 
-# 3. Your patch is now in patches/001-ui-custom-toolbar.patch
-#    with metadata tracked in patches/patches.json
+3. Your patch is now in `patches/`.
+4. Reset and import to verify everything applies cleanly:
 
-# 4. Later, reset and replay to verify everything applies cleanly
+```bash
 npx fireforge reset --yes
 npx fireforge import              # --dry-run to preview without applying
+```
+
+5. When Mozilla releases a new version, update fireforge.json, re-download and rebase:
 
-# 5. When Firefox releases a new ESR, update fireforge.json, re-download and rebase
+```bash
 npx fireforge download --force
 npx fireforge rebase
 ```
@@ -136,6 +138,13 @@ fireforge export browser/base/content/browser.js --before 005-ui-sidebar.patch -
 
 # Restrict a re-export to a specific file subset
 fireforge re-export --files browser/base/content/browser.js 002-ui-toolbar
+
+# Refresh every patch AND stamp sourceEsrVersion from fireforge.json onto each
+# one. Only stamps when every selected patch refreshes cleanly — partial
+# runs refuse to stamp. Use when you re-exported after a manual Firefox
+# bump that did not go through `rebase`. By default `re-export` refreshes
+# patch bodies and filesAffected but does NOT change sourceEsrVersion.
+fireforge re-export --all --scan --stamp
 ```
 
 ### Rebasing on top of a new Firefox version
@@ -173,12 +182,15 @@ This re-exports the fixed patch and continues applying the remaining stack.
       "description": "Replaces default Firefox branding with custom logo",
       "createdAt": "2025-01-15T10:30:00Z",
       "sourceEsrVersion": "140.9.0esr",
-      "filesAffected": ["browser/branding/official/logo.png"]
+      "filesAffected": ["browser/branding/official/logo.png"],
+      "lintIgnore": ["large-patch-lines", "large-patch-files"]
     }
   ]
 }
 ```
 
+The optional `lintIgnore` field lists lint check IDs to suppress for that patch specifically. Useful for the class of patch that is advisory-noisy by nature — a cohesive branding bundle, a localised-resource pack, an auto-generated manifest — where `--skip-lint` is too blunt and a per-line marker cannot exist (the `.patch` body is regenerated on every export). Threaded through `export`, `re-export`, `re-export --files`, and `lint --per-patch`. Unknown check IDs are a no-op.
+
 If the manifest drifts after an interrupted export or manual edits, `fireforge import` will stop rather then silently applying a stale stack. Use `fireforge doctor --repair-patches-manifest` to rebuild it from disk. Because the rebuild is deterministic, the result will always be consistent with what is actually on the filesystem.
 
 </details>
@@ -188,6 +200,8 @@ If the manifest drifts after an interrupted export or manual edits, `fireforge i
 
 `fireforge lint` runs automatically during export, export-all and re-export. Use `--skip-lint` to downgrade errors to warnings. Errors block the export; warnings are printed but do not block.
 
+By default, a standalone `fireforge lint` (no arguments) lints the **aggregate** `git diff HEAD` — i.e. every applied patch summed. On a repo where `fireforge import` or `fireforge rebase` has just applied the full queue, the patch-size rules (`large-patch-lines`, `large-patch-files`) fire against the sum, which reads as "my queue is broken" when it is really an artefact of aggregation. Use `fireforge lint --per-patch` to rescope the diff to each patch's own `filesAffected`, honouring the patch's own `lintIgnore`. Cross-patch rules (`duplicate-new-file-creation`, `forward-import`) still run once over the whole queue either way. Pass explicit file paths to narrow the scope further; the three modes (aggregate, file-scoped, per-patch) are mutually exclusive.
+
 | Check                          | Scope                                                                     | Severity                 |
 | ------------------------------ | ------------------------------------------------------------------------- | ------------------------ |
 | `missing-license-header`       | New files (JS/CSS/FTL)                                                    | error                    |
@@ -536,6 +550,83 @@ The two flags can be combined — `--with-tests --xpcshell` writes both harnesse
 
 `fireforge test <path>` (without `--build`) now runs a preflight that diffs engine HEAD and the workdir against the last successful `fireforge build` (recorded at `.fireforge/last-build.json`). When packageable engine files have changed since that baseline, the command prints a single up-front warning naming the paths and pointing at `fireforge test --build`. This catches the class of failure where a newly scaffolded chrome resource or pref file is registered correctly but `obj-*/dist/` still holds the pre-edit bundle, so the test reads stale packaged artifacts and errors out with a cryptic `NS_ERROR_FILE_NOT_FOUND` inside xpcshell / mach test. The preflight is warn-only — a fork that rebuilt out-of-band (direct `./mach build`, IDE plugin, separate CI stage) is not blocked. Passing `--build` skips the preflight because the rebuild just refreshed the bundle.
 
+### xpcshell appdir auto-injection on rebranded forks
+
+`fireforge test` auto-resolves and injects `--app-path=<absolute>` into the underlying `mach test` invocation when the nearest `xpcshell.toml` sets `firefox-appdir = "browser"` and the active build's `appname` is anything other than `firefox`. Without this, every `resource:///modules/<name>.sys.mjs` import inside the harness throws `Failed to load resource:///modules/…` because the upstream xpcshell harness reads the appdir override under the appname-keyed manifest field (`<appname>-appdir`) — the literal `firefox-appdir = "browser"` directive is silently ignored on rebranded forks, `appPath` falls back to `xrePath`, and `resource:///` resolves one level above the real app root. The resolver walks each test path to its nearest manifest, reads `mozinfo.json` for the active appname, prefers any `<appname>-appdir` already in the manifest, and otherwise probes `<objDir>/dist/bin/<value>` and `<objDir>/dist/<bundle>.app/Contents/Resources/<value>` for the absolute target. Operator overrides via `--mach-arg=--app-path=…` always win and skip the resolver silently. Mismatches across multiple test paths and unresolvable manifest values surface as warnings rather than guesses, so triage reaches the underlying cause.
+
+The durable fix is to add `<appname>-appdir = "browser"` alongside `firefox-appdir = "browser"` in the manifest — the harness then reads the appname-keyed value directly without auto-injection. The xpcshell appdir hint that fires when the symptom persists despite injection lists this option first.
+
+### Smoke-run mode (`fireforge run --smoke-exit`)
+
+`fireforge run --smoke-exit <seconds>` launches the real built browser, streams the merged console line-by-line, sends `SIGTERM` to the entire child process group at the deadline, and exits non-zero when any `JavaScript error:` / `console.error:` / `[JavaScript Error]` / `###!!! [Parent]` line surfaces inside the smoke window without matching an allowlist. Closes the headless-vs-real-chrome gap that previously forced agents to choose between `fireforge run` (no exit hook, hangs on a human) and `--headless` (does not load the chrome document, so chrome-window constructor errors stay invisible).
+
+```bash
+# Launch, wait 60s, exit 0 unless an unallowed error fired
+fireforge run --smoke-exit 60
+
+# Same, but ignore a known async-shutdown blocker we've already triaged
+fireforge run --smoke-exit 60 --console-allow 'AsyncShutdown blocker timed out'
+
+# Allowlist file (one regex per line, # comments and blanks skipped) + capture
+fireforge run --smoke-exit 60 --console-allow-file scripts/smoke-allow.txt --capture-console smoke.log
+```
+
+Exit codes are wired distinct from `BUILD_ERROR`:
+
+| Code | Meaning                                                                |
+| ---- | ---------------------------------------------------------------------- |
+| 0    | Smoke window elapsed cleanly (or only allowlisted errors fired).       |
+| 12   | One or more unallowed console errors fired inside the window.          |
+| 13   | Browser exited non-clean before the window elapsed (launch-side fail). |
+
+POSIX only — process-group semantics do not map cleanly onto Windows. A smoke window shorter than 30 s warns up-front because cold-start time alone can consume that budget on a debug build; `--capture-console <file>` mirrors the captured stream so post-exit inspection has the raw log without re-running.
+
+### Furnace `--shared-ftl` for feature-scoped Fluent bundles
+
+A feature with multiple components (e.g. an eight-component dock) typically wants one shared `.ftl` per feature rather than eight per-component stubs. `furnace create <tag> --localized --shared-ftl <chrome-uri>` participates in an existing feature-scoped bundle:
+
+```bash
+fireforge furnace create hominis-dock-button --localized --shared-ftl browser/hominis-dock.ftl
+```
+
+The generated `.mjs` calls `insertFTLIfNeeded("browser/hominis-dock.ftl")` instead of the per-component path. No `<tag>.ftl` stub is written. The `furnace.json` `custom` entry carries a new `sharedFtl` field so apply, validate, and remove all honour the participation:
+
+- `furnace apply` does not copy a per-component `.ftl` into the FTL tree nor add a locale `jar.mn` entry — the shared file is registered by whoever owns the feature bundle.
+- `furnace remove` early-returns from the locale `jar.mn` cleanup, so dropping our component's reference does not orphan the bundle for every other participant.
+- `furnace validate`'s `missing-ftl` structural check is skipped — there is no per-component `.ftl` to require.
+
+`--shared-ftl` implies `--localized`. `--no-localized + --shared-ftl` is rejected fast-fail. The value is interpolated verbatim into the generated template literal, so backticks, backslashes, and `${` are rejected at parse time. Setting `sharedFtl` does not auto-migrate previous per-component FTL state — flipping an existing component leaves the prior per-component entry in the engine tree and locale `jar.mn` until cleaned up explicitly.
+
+### Furnace `keyboardCovered` for composed-button wrappers
+
+`furnace validate`'s `no-keyboard-handler` rule is automatically suppressed when `@click` sits on a custom-element host whose `composes` lists a native-interactive child (e.g. `moz-button`, `moz-toggle`). The wrapper's click handler catches keyboard activation transitively because the inner element dispatches `click` on Enter/Space via the platform; a duplicate `@keydown` on the wrapper would either no-op or double-fire alongside the child's built-in path.
+
+When the wrapped inner element is hand-authored or is a non-stock `moz-*` widget that does not appear in `composes`, the explicit `keyboardCovered: true` field on the component's `furnace.json` entry forces the same skip:
+
+```json
+"hominis-dock-button": {
+  "description": "Dock button wrapper",
+  "targetPath": "components/custom/hominis-dock-button",
+  "register": true,
+  "localized": false,
+  "composes": ["moz-button"],
+  "keyboardCovered": true
+}
+```
+
+`keyboardCovered` is operator-asserted — it does not re-check the component, so it can be used to silence a genuine finding. Prefer adding the wrapped tag to `composes` when that field applies (it carries semantic value beyond a11y).
+
+### Test escape valves
+
+`fireforge test --mach-arg <arg>` (repeatable) forwards a single argument verbatim to `mach test` after FireForge-managed flags. Escape valve for upstream xpcshell/mochitest options FireForge does not model directly:
+
+```bash
+fireforge test browser/base/content/test/foo --mach-arg=--keep-going --mach-arg=--verbose
+fireforge test browser/components/tests/unit/test_x.js --mach-arg=--app-path=/abs/override
+```
+
+Operator overrides for `--app-path` always win over the auto-injection described above.
+
 ## Roadmap
 
 Planned but not yet implemented:

package/dist/src/commands/export-shared.d.ts

@@ -11,8 +11,13 @@ import type { SpinnerHandle } from '../utils/logger.js';
  * @param config - Project configuration
  * @param skipLint - If true, downgrade errors to warnings
  * @param patchQueueCtx - Optional cross-patch context for ownership resolution
+ * @param ignoreChecks - Optional per-patch set of `check` IDs to suppress
+ *   (threaded from `PatchMetadata.lintIgnore`). Surgical alternative to
+ *   `--skip-lint` when exactly one advisory rule does not apply to a
+ *   specific patch — e.g. `large-patch-lines` on a cohesive branding
+ *   bundle that genuinely cannot be split.
  */
-export declare function runPatchLint(engineDir: string, filesAffected: string[], diffContent: string, config: FireForgeConfig, skipLint?: boolean, patchQueueCtx?: import('../core/patch-lint-cross.js').PatchQueueContext): Promise<void>;
+export declare function runPatchLint(engineDir: string, filesAffected: string[], diffContent: string, config: FireForgeConfig, skipLint?: boolean, patchQueueCtx?: import('../core/patch-lint-cross.js').PatchQueueContext, ignoreChecks?: ReadonlySet<string>): Promise<void>;
 /**
  * Resolves patch metadata interactively or from flags, with shared validation.
  * @param options - Export command options

package/dist/src/commands/export-shared.js

@@ -18,9 +18,14 @@ import { isValidPatchCategory, PATCH_CATEGORIES, validatePatchName } from '../ut
  * @param config - Project configuration
  * @param skipLint - If true, downgrade errors to warnings
  * @param patchQueueCtx - Optional cross-patch context for ownership resolution
+ * @param ignoreChecks - Optional per-patch set of `check` IDs to suppress
+ *   (threaded from `PatchMetadata.lintIgnore`). Surgical alternative to
+ *   `--skip-lint` when exactly one advisory rule does not apply to a
+ *   specific patch — e.g. `large-patch-lines` on a cohesive branding
+ *   bundle that genuinely cannot be split.
  */
-export async function runPatchLint(engineDir, filesAffected, diffContent, config, skipLint, patchQueueCtx) {
-    const issues = await lintExportedPatch(engineDir, filesAffected, diffContent, config, patchQueueCtx);
+export async function runPatchLint(engineDir, filesAffected, diffContent, config, skipLint, patchQueueCtx, ignoreChecks) {
+    const issues = await lintExportedPatch(engineDir, filesAffected, diffContent, config, patchQueueCtx, ignoreChecks);
     if (issues.length === 0)
         return;
     const errors = issues.filter((i) => i.severity === 'error');

package/dist/src/commands/furnace/create-dry-run.d.ts

@@ -4,6 +4,13 @@ export interface DryRunPlanInput {
     localized: boolean;
     register: boolean;
     composes: string[] | undefined;
+    /**
+     * Feature-scoped Fluent bundle the component participates in (the same
+     * value that will be written to `furnace.json`'s `sharedFtl`). When set,
+     * the component's own `.ftl` is NOT scaffolded and the plan preview
+     * reflects that. Omit the key for the default per-component scaffold.
+     */
+    sharedFtl?: string;
     testStyle: ResolvedTestStyle;
     description: string;
     binaryName: string;

package/dist/src/commands/furnace/create-dry-run.js

@@ -75,9 +75,11 @@ export function formatSuccessNote(args) {
  * `components/custom/` to match the wording of the real success note.
  */
 export function formatDryRunPlan(args) {
-    const { componentName, localized, register, composes, testStyle, description, binaryName } = args;
+    const { componentName, localized, register, composes, sharedFtl, testStyle, description, binaryName, } = args;
     const componentFiles = [`${componentName}.mjs`, `${componentName}.css`];
-    if (localized)
+    // A per-component .ftl is scaffolded only when the component does NOT
+    // opt into a shared feature-scoped bundle. Mirrors writeComponentFiles.
+    if (localized && !sharedFtl)
         componentFiles.push(`${componentName}.ftl`);
     let plan = `Would create files in components/custom/${componentName}/:\n` +
         componentFiles.map((f) => `  ${f}`).join('\n');
@@ -90,6 +92,9 @@ export function formatDryRunPlan(args) {
     if (composes && composes.length > 0) {
         plan += `\n  composes: ${composes.join(', ')}`;
     }
+    if (sharedFtl) {
+        plan += `\n  sharedFtl: ${sharedFtl}`;
+    }
     return plan;
 }
 //# sourceMappingURL=create-dry-run.js.map

package/dist/src/commands/furnace/create-features.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Feature-flag resolution for `furnace create`. Extracted from
+ * `create.ts` so the authoring command stays under the per-file LOC
+ * budget — the flag resolver has grown with each new opt-in (`--xpcshell`,
+ * `--test-style`, `--shared-ftl`).
+ */
+import type { FurnaceCreateOptions } from '../../types/commands/index.js';
+/**
+ * Resolves the localized and registration feature flags for a new component.
+ *
+ * `--shared-ftl` implies `localized` and short-circuits the interactive
+ * prompt so the operator is not asked to flip a flag we are about to
+ * enforce. `--no-localized` combined with `--shared-ftl` is rejected
+ * fast-fail; the cross-field check in furnace-config would catch it
+ * too, but later and without a clear command-line message.
+ *
+ * @param isInteractive - Whether interactive prompts are available
+ * @param options - CLI-provided feature flags
+ * @returns Final feature selections, or null when creation is cancelled
+ */
+export declare function resolveCreateFeatures(isInteractive: boolean, options: FurnaceCreateOptions): Promise<{
+    localized: boolean;
+    register: boolean;
+} | null>;

package/dist/src/commands/furnace/create-features.js

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Feature-flag resolution for `furnace create`. Extracted from
+ * `create.ts` so the authoring command stays under the per-file LOC
+ * budget — the flag resolver has grown with each new opt-in (`--xpcshell`,
+ * `--test-style`, `--shared-ftl`).
+ */
+import { multiselect } from '@clack/prompts';
+import { InvalidArgumentError } from '../../errors/base.js';
+import { cancel, isCancel } from '../../utils/logger.js';
+/**
+ * Resolves the localized and registration feature flags for a new component.
+ *
+ * `--shared-ftl` implies `localized` and short-circuits the interactive
+ * prompt so the operator is not asked to flip a flag we are about to
+ * enforce. `--no-localized` combined with `--shared-ftl` is rejected
+ * fast-fail; the cross-field check in furnace-config would catch it
+ * too, but later and without a clear command-line message.
+ *
+ * @param isInteractive - Whether interactive prompts are available
+ * @param options - CLI-provided feature flags
+ * @returns Final feature selections, or null when creation is cancelled
+ */
+export async function resolveCreateFeatures(isInteractive, options) {
+    let localized = options.localized ?? false;
+    let register = options.register ?? true;
+    if (options.sharedFtl !== undefined) {
+        if (options.localized === false) {
+            throw new InvalidArgumentError('--shared-ftl requires localization. Remove --no-localized or drop --shared-ftl.', 'sharedFtl');
+        }
+        localized = true;
+    }
+    const featuresPromptSuppressed = options.sharedFtl !== undefined;
+    if (isInteractive &&
+        options.localized === undefined &&
+        options.register === undefined &&
+        !featuresPromptSuppressed) {
+        const features = await multiselect({
+            message: 'Component features:',
+            options: [
+                { value: 'localized', label: 'Fluent localization (data-l10n-id)' },
+                { value: 'register', label: 'Register in customElements.js' },
+            ],
+            initialValues: ['register'],
+        });
+        if (isCancel(features)) {
+            cancel('Create cancelled');
+            return null;
+        }
+        const selected = features;
+        localized = selected.includes('localized');
+        register = selected.includes('register');
+    }
+    return { localized, register };
+}
+//# sourceMappingURL=create-features.js.map

package/dist/src/commands/furnace/create-templates.d.ts

@@ -14,12 +14,16 @@
  * per-instance shadow-DOM Fluent attachment via `l10n.connectRoot`. We mirror
  * that pattern here so `--localized` produces functional code.
  *
- * The FTL path mirrors the locale jar.mn entry that `furnace apply` writes:
- * `<ftlChromeSubPath>/<name>.ftl`. For the default `toolkit/global` tree this
- * yields `toolkit/global/<name>.ftl`, which matches the URI upstream toolkit
- * widgets ship.
+ * Path resolution precedence (when `localized` is true):
+ *   1. `sharedFtl` — used verbatim. The caller has resolved it from
+ *      `--shared-ftl` / `furnace.json`; this template does no rewriting.
+ *      Use this when the component participates in a feature-scoped
+ *      bundle that another component owns.
+ *   2. `<ftlChromeSubPath>/<name>.ftl` — the default per-component path,
+ *      matching the locale jar.mn entry that `furnace apply` writes.
+ *   3. `<name>.ftl` — fallback when no chrome sub-path was resolvable.
  */
-export declare function generateMjsContent(name: string, className: string, description: string, localized: boolean, header: string, ftlChromeSubPath: string | undefined): string;
+export declare function generateMjsContent(name: string, className: string, description: string, localized: boolean, header: string, ftlChromeSubPath: string | undefined, sharedFtl: string | undefined): string;
 /** Generates the .css file content for a custom component. */
 export declare function generateCssContent(header: string): string;
 /** Generates the .ftl file content for a custom component. */

package/dist/src/commands/furnace/create-templates.js

@@ -15,13 +15,21 @@
  * per-instance shadow-DOM Fluent attachment via `l10n.connectRoot`. We mirror
  * that pattern here so `--localized` produces functional code.
  *
- * The FTL path mirrors the locale jar.mn entry that `furnace apply` writes:
- * `<ftlChromeSubPath>/<name>.ftl`. For the default `toolkit/global` tree this
- * yields `toolkit/global/<name>.ftl`, which matches the URI upstream toolkit
- * widgets ship.
+ * Path resolution precedence (when `localized` is true):
+ *   1. `sharedFtl` — used verbatim. The caller has resolved it from
+ *      `--shared-ftl` / `furnace.json`; this template does no rewriting.
+ *      Use this when the component participates in a feature-scoped
+ *      bundle that another component owns.
+ *   2. `<ftlChromeSubPath>/<name>.ftl` — the default per-component path,
+ *      matching the locale jar.mn entry that `furnace apply` writes.
+ *   3. `<name>.ftl` — fallback when no chrome sub-path was resolvable.
  */
-export function generateMjsContent(name, className, description, localized, header, ftlChromeSubPath) {
-    const ftlPath = ftlChromeSubPath !== undefined ? `${ftlChromeSubPath}/${name}.ftl` : `${name}.ftl`;
+export function generateMjsContent(name, className, description, localized, header, ftlChromeSubPath, sharedFtl) {
+    const ftlPath = sharedFtl !== undefined
+        ? sharedFtl
+        : ftlChromeSubPath !== undefined
+            ? `${ftlChromeSubPath}/${name}.ftl`
+            : `${name}.ftl`;
     const ftlModulePreamble = localized
         ? `
 window.MozXULElement?.insertFTLIfNeeded("${ftlPath}");

package/dist/src/commands/furnace/create.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
-import { multiselect, text } from '@clack/prompts';
+import { text } from '@clack/prompts';
 import { getProjectPaths, loadConfig } from '../../core/config.js';
 import { createDefaultFurnaceConfig, detectComposesCycles, furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, writeFurnaceConfig, } from '../../core/furnace-config.js';
 import { resolveFtlChromeSubPath, tagNameToClassName } from '../../core/furnace-constants.js';
@@ -10,12 +10,14 @@ import { createRollbackJournal, recordCreatedDir, restoreRollbackJournalOrThrow,
 import { isComponentInEngine } from '../../core/furnace-scanner.js';
 import { DEFAULT_LICENSE, getLicenseHeader } from '../../core/license-headers.js';
 import { registerTestManifest } from '../../core/manifest-register.js';
+import { validateSharedFtl } from '../../core/shared-ftl.js';
 import { InvalidArgumentError } from '../../errors/base.js';
 import { FurnaceError } from '../../errors/furnace.js';
 import { toError } from '../../utils/errors.js';
 import { ensureDir, pathExists, readText, writeText } from '../../utils/fs.js';
 import { cancel, intro, isCancel, note, outro, success, warn } from '../../utils/logger.js';
 import { formatDryRunPlan, formatSuccessNote } from './create-dry-run.js';
+import { resolveCreateFeatures } from './create-features.js';
 import { scaffoldMochikitTestFiles } from './create-mochikit.js';
 import { generateCssContent, generateFtlContent, generateMjsContent } from './create-templates.js';
 import { scaffoldXpcshellTestFiles } from './create-xpcshell.js';
@@ -158,40 +160,6 @@ add_task(async function test_${underscored}_defined() {
     }
     return testFiles;
 }
-/**
- * Resolves the localized and registration feature flags for a new component.
- * @param isInteractive - Whether interactive prompts are available
- * @param options - CLI-provided feature flags
- * @returns Final feature selections, or null when creation is cancelled
- */
-async function resolveCreateFeatures(isInteractive, options) {
-    let localized = options.localized ?? false;
-    let register = options.register ?? true;
-    if (isInteractive && options.localized === undefined && options.register === undefined) {
-        const features = await multiselect({
-            message: 'Component features:',
-            options: [
-                {
-                    value: 'localized',
-                    label: 'Fluent localization (data-l10n-id)',
-                },
-                {
-                    value: 'register',
-                    label: 'Register in customElements.js',
-                },
-            ],
-            initialValues: ['register'],
-        });
-        if (isCancel(features)) {
-            cancel('Create cancelled');
-            return null;
-        }
-        const selected = features;
-        localized = selected.includes('localized');
-        register = selected.includes('register');
-    }
-    return { localized, register };
-}
 /**
  * Writes the scaffolded component source files to disk.
  * @param componentDir - Destination component directory
@@ -203,20 +171,25 @@ async function resolveCreateFeatures(isInteractive, options) {
  * @param journal - Optional rollback journal that snapshots files before writes
  * @returns Relative filenames written for the component
  */
-async function writeComponentFiles(componentDir, componentName, className, description, localized, license, ftlChromeSubPath, journal) {
+async function writeComponentFiles(componentDir, componentName, className, description, localized, license, ftlChromeSubPath, sharedFtl, journal) {
     await ensureDir(componentDir);
     const files = [`${componentName}.mjs`, `${componentName}.css`];
     const mjsPath = join(componentDir, `${componentName}.mjs`);
     if (journal)
         await snapshotFile(journal, mjsPath);
-    const mjsContent = generateMjsContent(componentName, className, description, localized, getLicenseHeader(license, 'js'), ftlChromeSubPath);
+    const mjsContent = generateMjsContent(componentName, className, description, localized, getLicenseHeader(license, 'js'), ftlChromeSubPath, sharedFtl);
     await writeText(mjsPath, mjsContent);
     const cssPath = join(componentDir, `${componentName}.css`);
     if (journal)
         await snapshotFile(journal, cssPath);
     const cssContent = generateCssContent(getLicenseHeader(license, 'css'));
     await writeText(cssPath, cssContent);
-    if (localized) {
+    // Skip the per-component .ftl stub when the component participates in a
+    // pre-existing feature-scoped bundle. The shared bundle is owned
+    // elsewhere; dropping a stub here would clutter the workspace with
+    // empty files that never get packaged (furnace apply also skips copying
+    // them in this mode).
+    if (localized && !sharedFtl) {
         const ftlPath = join(componentDir, `${componentName}.ftl`);
         if (journal)
             await snapshotFile(journal, ftlPath);
@@ -277,7 +250,7 @@ async function performCreateMutations(args) {
         // so signal-driven rollback can clean it up even if writeComponentFiles
         // is interrupted mid-ensureDir.
         recordCreatedDir(journal, args.componentDir);
-        files = await writeComponentFiles(args.componentDir, args.componentName, args.className, args.description, args.localized, args.license, args.ftlChromeSubPath, journal);
+        files = await writeComponentFiles(args.componentDir, args.componentName, args.className, args.description, args.localized, args.license, args.ftlChromeSubPath, args.sharedFtl, journal);
         const customEntry = {
             description: args.description,
             targetPath: `toolkit/content/widgets/${args.componentName}`,
@@ -287,6 +260,9 @@ async function performCreateMutations(args) {
         if (args.composes && args.composes.length > 0) {
             customEntry.composes = args.composes;
         }
+        if (args.sharedFtl) {
+            customEntry.sharedFtl = args.sharedFtl;
+        }
         args.config.custom[args.componentName] = customEntry;
         await snapshotFile(journal, args.furnacePaths.furnaceConfig);
         await writeFurnaceConfig(args.projectRoot, args.config);
@@ -455,6 +431,21 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
     // does not strand component files behind.
     const composes = options.compose;
     validateComposesTargets(config, componentName, composes);
+    // --- Normalize and validate --shared-ftl ahead of any writes. Shares the
+    // structural rules with furnace-config.ts so the command and the on-disk
+    // schema cannot diverge. Pass the resolved `localized` rather than a
+    // `true` literal so the validator's cross-field check stays anchored to
+    // the real feature selection — `resolveCreateFeatures` promotes localized
+    // upstream, but hard-coding `true` here would hide a regression if that
+    // promotion ever moved or dropped.
+    let sharedFtl;
+    if (options.sharedFtl !== undefined) {
+        const result = validateSharedFtl(options.sharedFtl, { localized });
+        if (!result.ok) {
+            throw new InvalidArgumentError(`--shared-ftl ${result.reason}.`, 'sharedFtl');
+        }
+        sharedFtl = result.value;
+    }
     // Dry-run exits here — every validation that does not need a write has
     // already run, so the plan we render reflects exactly what the real
     // command would do. The mutation phase and its rollback journal are
@@ -465,6 +456,9 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
             localized,
             register,
             composes,
+            // Spread rather than assign so the key is absent when sharedFtl is
+            // undefined — the DryRunPlanInput type uses strict-optional shape.
+            ...(sharedFtl !== undefined ? { sharedFtl } : {}),
             testStyle,
             description,
             binaryName: forgeConfig.binaryName,
@@ -490,6 +484,7 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
         localized,
         register,
         composes,
+        sharedFtl,
         componentDir,
         furnacePaths,
         config,

package/dist/src/commands/furnace/index.js

@@ -81,6 +81,7 @@ function registerFurnaceInfoCommands(furnace, context) {
         return value;
     })
         .option('--compose <tags>', 'Record stock tags composed internally (metadata only, comma-separated)', (val) => val.split(',').map((s) => s.trim()))
+        .option('--shared-ftl <path>', 'Participate in an existing feature-scoped .ftl at this path (e.g. "browser/hominis-dock.ftl"); skips the per-component .ftl scaffold (implies --localized)')
         .option('--dry-run', 'Show the planned file set and furnace.json changes without writing')
         .action(withErrorHandling(async (name, options) => {
         await furnaceCreateCommand(getProjectRoot(), name, options);