@hominis/fireforge 0.15.7 → 0.15.8

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 ## 0.15.0
 
+### 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,25 @@ Your project now has `fireforge.json`, an `engine/` directory with Firefox sourc
 
 ### Workflow Overview
 
+1. Make changes inside the `engine/` directory.
+2. Export your changes as a patch:
+
 ```bash
-# 1. Make changes inside engine/
-#    Edit browser/base/content/browser.js, add CSS, create new modules...
+npx fireforge export browser/base/content/browser.js --name "custom-toolbar" --category ui
+```
 
-# 2. Export your changes as a patch
-npx fireforge export browser/base/content/browser.js \
-  --name "custom-toolbar" --category ui
+3. Your patch is now in `patches/`.
 
-# 3. Your patch is now in patches/001-ui-custom-toolbar.patch
-#    with metadata tracked in patches/patches.json
+# 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
 ```
@@ -536,6 +539,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/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);

package/dist/src/commands/run.d.ts

@@ -1,9 +1,23 @@
 import { Command } from 'commander';
 import type { CommandContext } from '../types/cli.js';
+import type { RunOptions } from '../types/commands/index.js';
+/**
+ * Exit code returned by smoke-run mode when the captured console stream
+ * produced one or more error lines that did NOT match the operator's
+ * allowlist.
+ */
+export declare const SMOKE_EXIT_FAILURE: 12;
+/**
+ * Exit code returned by smoke-run mode when the browser itself exited
+ * with a non-clean status before the smoke window elapsed — i.e. a
+ * launch-side failure we could NOT observe as a console error line
+ * (crash before console wiring, missing profile, etc.).
+ */
+export declare const SMOKE_LAUNCH_FAILURE: 13;
 /**
  * Runs the run command to launch the built browser.
  * @param projectRoot - Root directory of the project
  */
-export declare function runCommand(projectRoot: string): Promise<void>;
+export declare function runCommand(projectRoot: string, options?: RunOptions): Promise<void>;
 /** Registers the run command on the CLI program. */
 export declare function registerRun(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;