@hominis/fireforge 0.15.7 → 0.15.9

package/dist/src/commands/run.js

@@ -1,14 +1,36 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { readdir } from 'node:fs/promises';
+import { createWriteStream } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { getProjectPaths } from '../core/config.js';
 import { warnIfFurnaceStale } from '../core/furnace-staleness.js';
-import { buildArtifactMismatchMessage, hasBuildArtifacts, run } from '../core/mach.js';
-import { GeneralError } from '../errors/base.js';
+import { buildArtifactMismatchMessage, hasBuildArtifacts, run, runMachSmoke, } from '../core/mach.js';
+import { compileAllowlistFromFile, compileAllowlistFromStrings, matchesAllowlist, matchesSmokeError, } from '../core/smoke-patterns.js';
+import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
+import { ExitCode } from '../errors/codes.js';
+import { SmokeRunError } from '../errors/run.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, removeDir, removeFile } from '../utils/fs.js';
-import { info, intro, verbose } from '../utils/logger.js';
+import { info, intro, verbose, warn } from '../utils/logger.js';
+import { pickDefined } from '../utils/options.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 const SMOKE_EXIT_FAILURE = ExitCode.SMOKE_EXIT_FAILURE;
+/**
+ * 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 const SMOKE_LAUNCH_FAILURE = ExitCode.SMOKE_LAUNCH_FAILURE;
+/** Recommendation surfaced when the smoke window is shorter than a typical cold start. */
+const SMOKE_COLD_START_THRESHOLD_MS = 30_000;
+/** Maximum number of unallowed error lines to surface in the terminal summary. */
+const SMOKE_UNALLOWED_PREVIEW_MAX = 10;
 /**
  * Cleans the dev profile to prevent stale-state startup failures.
  *
@@ -50,7 +72,7 @@ async function cleanDevProfile(engineDir) {
  * Runs the run command to launch the built browser.
  * @param projectRoot - Root directory of the project
  */
-export async function runCommand(projectRoot) {
+export async function runCommand(projectRoot, options = {}) {
     intro('FireForge Run');
     const paths = getProjectPaths(projectRoot);
     // Check if engine exists
@@ -76,6 +98,10 @@ export async function runCommand(projectRoot) {
     await warnIfFurnaceStale(projectRoot);
     // Clean stale profile state to prevent silent startup failures
     await cleanDevProfile(paths.engine);
+    if (options.smokeExit !== undefined) {
+        await runSmokeExit(paths.engine, options);
+        return;
+    }
     info('Launching browser...\n');
     const exitCode = await run(paths.engine);
     // Exit-code whitelist:
@@ -89,13 +115,182 @@ export async function runCommand(projectRoot) {
         throw new BuildError(`Browser exited with code ${exitCode}`, 'mach run');
     }
 }
+/**
+ * Drives the `--smoke-exit` launch path. Runs the browser under
+ * {@link runMachSmoke}, scans the merged console stream for error-class
+ * lines against the operator-supplied allowlist, and applies the smoke
+ * exit contract. The deadline-fires-SIGTERM path is treated as a clean
+ * window iff no unallowed errors were observed.
+ */
+async function runSmokeExit(engineDir, options) {
+    // Windows lacks the POSIX process-group primitives --smoke-exit leans on to
+    // SIGTERM the whole mach → python → firefox tree. Running through anyway
+    // would only kill the top-level wrapper and orphan Firefox content
+    // processes, so reject the flag up front to match the documented contract
+    // in CHANGELOG.md / README.md.
+    if (process.platform === 'win32') {
+        throw new InvalidArgumentError('--smoke-exit is POSIX-only; process-group semantics do not map cleanly onto Windows.', 'smokeExit');
+    }
+    const smokeExit = options.smokeExit;
+    // The runCommand caller has already gated on `options.smokeExit !== undefined`,
+    // but commander can hand us `0` or negative values through the action
+    // layer if the parser in `registerRun` was bypassed (e.g. programmatic
+    // use in a test that skips the parser). Guard explicitly so the deadline
+    // timer cannot be scheduled at 0 ms and immediately kill the process.
+    if (smokeExit === undefined || smokeExit < 1 || !Number.isFinite(smokeExit)) {
+        throw new InvalidArgumentError('--smoke-exit expects a positive integer number of seconds.', 'smokeExit');
+    }
+    const smokeTimeoutMs = smokeExit * 1000;
+    if (smokeTimeoutMs < SMOKE_COLD_START_THRESHOLD_MS) {
+        // Not an error — cold starts just tend to exceed the window. Surfacing
+        // the hint here instead of failing lets agents run shorter windows
+        // intentionally (e.g. warm-cache smoke checks).
+        verbose(`Smoke window is ${String(smokeExit)}s; cold starts on slow machines often exceed 30s.`);
+    }
+    const allowlist = await buildAllowlist(options);
+    const captureStream = options.captureConsole
+        ? createWriteStream(options.captureConsole)
+        : undefined;
+    // createWriteStream opens the fd asynchronously, so ENOENT / EACCES /
+    // EISDIR / EROFS surface as an 'error' event *after* the constructor
+    // returns. Without a listener Node re-throws as uncaughtException and
+    // kills the CLI mid-smoke-run — orphaning the mach → python → firefox
+    // tree because the deadline timer never fires. Swallow the event into a
+    // warning so the smoke run still terminates cleanly; subsequent mirror
+    // writes on the errored stream are silent no-ops.
+    captureStream?.on('error', (err) => {
+        warn(`--capture-console stream error: ${err.message}`);
+    });
+    const findings = [];
+    let allowlistedHits = 0;
+    const handleLine = (stream, line) => {
+        // Mirror raw output to the terminal so operators watching the smoke
+        // run still see what the browser is printing. Stream selection on the
+        // mirror preserves stdout/stderr separation for downstream piping.
+        const sink = stream === 'stdout' ? process.stdout : process.stderr;
+        sink.write(`${line}\n`);
+        if (!matchesSmokeError(line))
+            return;
+        if (matchesAllowlist(line, allowlist)) {
+            allowlistedHits += 1;
+            return;
+        }
+        findings.push({ stream, line });
+    };
+    info(`Launching browser (smoke-exit after ${String(smokeExit)}s)...\n`);
+    const startedAt = Date.now();
+    let result;
+    try {
+        result = await runMachSmoke(['run'], engineDir, {
+            smokeTimeoutMs,
+            onStdoutLine: (line) => {
+                handleLine('stdout', line);
+            },
+            onStderrLine: (line) => {
+                handleLine('stderr', line);
+            },
+            ...(captureStream ? { mirror: { stdout: captureStream, stderr: captureStream } } : {}),
+        });
+    }
+    finally {
+        captureStream?.end();
+    }
+    const elapsedMs = Date.now() - startedAt;
+    reportSmokeSummary({
+        smokeTimeoutMs,
+        elapsedMs,
+        timedOut: result.timedOut,
+        allowlistedHits,
+        findings,
+        exitCode: result.exitCode,
+    });
+    // Exit contract (precedence: unallowed errors dominate timed-out).
+    if (findings.length > 0) {
+        throw new SmokeRunError(`Smoke run observed ${String(findings.length)} unallowed console error(s).`, SMOKE_EXIT_FAILURE);
+    }
+    if (result.timedOut) {
+        // Clean window — SIGTERM from us. Treat as success.
+        return;
+    }
+    if (result.exitCode === 0 || result.exitCode === 130 || result.exitCode === 143) {
+        return;
+    }
+    throw new SmokeRunError(`Browser exited with code ${String(result.exitCode)} before smoke-exit window elapsed.`, SMOKE_LAUNCH_FAILURE);
+}
+/**
+ * Compiles the active allowlist from `--console-allow` CLI values and
+ * the optional `--console-allow-file`. Fails fast on a bad regex —
+ * better to surface the typo at parse time than to silently let it
+ * match nothing and turn every allowed hit into a smoke failure.
+ */
+async function buildAllowlist(options) {
+    const allow = [];
+    if (options.consoleAllow && options.consoleAllow.length > 0) {
+        try {
+            allow.push(...compileAllowlistFromStrings(options.consoleAllow));
+        }
+        catch (error) {
+            throw new InvalidArgumentError(toError(error).message, 'consoleAllow');
+        }
+    }
+    if (options.consoleAllowFile) {
+        try {
+            const body = await readFile(options.consoleAllowFile, 'utf8');
+            allow.push(...compileAllowlistFromFile(body, options.consoleAllowFile));
+        }
+        catch (error) {
+            throw new InvalidArgumentError(`Failed to read --console-allow-file: ${toError(error).message}`, 'consoleAllowFile');
+        }
+    }
+    return allow;
+}
+/**
+ * Prints the human-readable summary block that follows every smoke run.
+ * Called once, right before the exit-code decision. Keeps the reporting
+ * path separate from exit-contract logic so a test can render summaries
+ * without mocking the BuildError construction.
+ */
+function reportSmokeSummary(args) {
+    const seconds = (args.elapsedMs / 1000).toFixed(1);
+    const windowSeconds = (args.smokeTimeoutMs / 1000).toFixed(0);
+    const suffix = args.timedOut ? ' (deadline fired — SIGTERM sent to process group)' : '';
+    info('');
+    info(`Smoke run complete: ${seconds}s elapsed of ${windowSeconds}s window${suffix}`);
+    info(`  Unallowed errors: ${String(args.findings.length)}`);
+    info(`  Allowlisted hits: ${String(args.allowlistedHits)}`);
+    info(`  Child exit code:  ${String(args.exitCode)}`);
+    if (args.findings.length === 0)
+        return;
+    warn('');
+    warn(`Unallowed console errors (first ${String(SMOKE_UNALLOWED_PREVIEW_MAX)}):`);
+    args.findings.slice(0, SMOKE_UNALLOWED_PREVIEW_MAX).forEach((finding, index) => {
+        warn(`  ${String(index + 1)}. [${finding.stream}] ${finding.line}`);
+    });
+    if (args.findings.length > SMOKE_UNALLOWED_PREVIEW_MAX) {
+        const remaining = args.findings.length - SMOKE_UNALLOWED_PREVIEW_MAX;
+        warn(`  …and ${String(remaining)} more.`);
+    }
+}
 /** Registers the run command on the CLI program. */
 export function registerRun(program, { getProjectRoot, withErrorHandling }) {
     program
         .command('run')
         .description('Launch the built browser')
-        .action(withErrorHandling(async () => {
-        await runCommand(getProjectRoot());
+        .option('--smoke-exit <seconds>', 'Smoke-run mode (POSIX only): launch, capture console, SIGTERM the process group after <seconds>. Exit 0 on a clean window, 12 on unallowed errors, 13 on launch failure.', (value) => {
+        const parsed = Number.parseInt(value, 10);
+        if (!Number.isFinite(parsed) || parsed < 1 || String(parsed) !== value.trim()) {
+            throw new Error(`--smoke-exit expects a positive integer number of seconds (got "${value}").`);
+        }
+        return parsed;
+    })
+        .option('--console-allow <regex>', 'Allowlist regex (repeatable). Lines that match any entry do not count toward the smoke exit code.', (value, acc) => {
+        acc.push(value);
+        return acc;
+    }, [])
+        .option('--console-allow-file <path>', 'Newline-delimited allowlist regex file. Blank lines and # comments are ignored.')
+        .option('--capture-console <file>', 'Mirror captured console output to <file> for post-exit inspection.')
+        .action(withErrorHandling(async (options) => {
+        await runCommand(getProjectRoot(), pickDefined(options));
     }));
 }
 //# sourceMappingURL=run.js.map

package/dist/src/commands/test.js

@@ -5,6 +5,7 @@ import { getProjectPaths, loadConfig } from '../core/config.js';
 import { buildArtifactMismatchMessage, buildUI, hasBuildArtifacts, testWithOutput, } from '../core/mach.js';
 import { reportMarionettePreflight, runMarionettePreflight } from '../core/marionette-preflight.js';
 import { checkStaleBuildForTest, formatStaleBuildWarning } from '../core/test-stale-check.js';
+import { operatorAlreadySetAppPath, resolveXpcshellAppdirArg, } from '../core/xpcshell-appdir.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
@@ -60,7 +61,47 @@ function hasStaleBuildArtifactsSignal(output) {
         /resource:\/\/\/modules\/distribution\.sys\.mjs/i.test(output) ||
         /browser\/branding\/[^/\s]+\/moz\.build/i.test(output));
 }
-function handleNonZeroTestExit(result, normalizedPaths) {
+// Detects the broader xpcshell symptom where every `resource:///modules/...`
+// import fails — the signature of xpcshell running with the wrong app-dir on
+// a manifest that sets `firefox-appdir = "browser"`. Checked AFTER the
+// stale-build signal (which matches the narrower `distribution.sys.mjs`
+// path) so the more specific diagnosis wins when both patterns apply.
+function hasXpcshellAppdirSignal(output) {
+    return /Failed to load resource:\/\/\/modules\//i.test(output);
+}
+function buildXpcshellAppdirMessage(injectionAttempted) {
+    const triggerLines = injectionAttempted
+        ? 'FireForge auto-injected `--app-path=<absolute>` against the resolved obj-dir before mach test ran, but the failure persists. The injected path either does not match the appdir layout your harness expects, or the harness was built against a layout FireForge cannot probe (omni.ja-packed tree, alternate `dist/` shape).\n\n'
+        : 'Likely triggers:\n' +
+            '  - The nearest xpcshell.toml sets `firefox-appdir = "browser"` but the harness reads `<appname>-appdir` instead — the literal `firefox-appdir` directive is silently ignored on rebranded forks (appname != "firefox").\n' +
+            '  - FireForge could not find an xpcshell.toml above the test path, so the auto-injection never ran.\n\n';
+    return ('xpcshell failed to load core resource:///modules/*.sys.mjs imports.\n\n' +
+        'This is the canonical symptom of xpcshell running with the wrong app directory: the runtime resolves `resource:///modules/` against the parent of the expected app root, so every `ChromeUtils.importESModule("resource:///modules/…")` throws.\n\n' +
+        triggerLines +
+        'Options:\n' +
+        '  - Add `<appname>-appdir = "browser"` alongside `firefox-appdir = "browser"` in the xpcshell.toml [DEFAULT] so the harness reads the appname-keyed value directly.\n' +
+        '  - Pass overrides through `fireforge test <path> --mach-arg="--app-path=<absolute>"` to inject the path verbatim (operator overrides always win over auto-injection).\n' +
+        '  - Remove `firefox-appdir = "browser"` from the xpcshell.toml [DEFAULT] and move browser-chrome dependencies into a browser-chrome mochitest (see `fireforge furnace create --test-style=browser-chrome`).\n' +
+        '  - If the test only touches toolkit chrome (chrome://global/*), drop the `firefox-appdir` setting entirely — toolkit chrome is registered without it.');
+}
+// Detects the `AttributeError: 'MochitestDesktop' object has no attribute
+// 'http3Server'` teardown crash. The attribute is lazy-initialized inside
+// harness code paths that presume chrome://branding resolves correctly; a
+// missing or miswired branding registration short-circuits the setup and
+// leaves the cleanup path looking up an attribute that was never assigned.
+function hasMochitestHttp3ServerSignal(output) {
+    return /'MochitestDesktop' object has no attribute 'http3Server'/.test(output);
+}
+function buildMochitestHttp3ServerMessage() {
+    return ("Mochitest raised `AttributeError: 'MochitestDesktop' object has no attribute 'http3Server'`.\n\n" +
+        'This is almost always a symptom of `chrome://branding` not registering correctly in your fork — the mochitest harness lazy-initializes `http3Server` only after branding resolves, and a missing branding registration short-circuits setup. The cleanup path then trips the AttributeError, masking the real error.\n\n' +
+        'Check that:\n' +
+        "  - Your fork's branding directory is listed in `browser/branding/moz.build` (or equivalent) and ships a `brand.properties` / `brand.ftl`.\n" +
+        '  - `chrome://branding/locale/brand.properties` resolves at runtime (try `fireforge run` and inspect the Browser Console).\n' +
+        "  - The `BROWSER_CHROME_MANIFESTS` entry for your fork's chrome.manifest is registered.\n\n" +
+        'This is an upstream Firefox harness interaction; FireForge can only diagnose it.');
+}
+function handleNonZeroTestExit(result, normalizedPaths, appdirInjectionAttempted) {
     if (result.exitCode === 0 || result.exitCode === 130)
         return;
     const combinedOutput = `${result.stdout}\n${result.stderr}`;
@@ -70,6 +111,12 @@ function handleNonZeroTestExit(result, normalizedPaths) {
     if (hasStaleBuildArtifactsSignal(combinedOutput)) {
         throw new GeneralError(buildStaleBuildMessage());
     }
+    if (hasMochitestHttp3ServerSignal(combinedOutput)) {
+        throw new GeneralError(buildMochitestHttp3ServerMessage());
+    }
+    if (hasXpcshellAppdirSignal(combinedOutput)) {
+        throw new GeneralError(buildXpcshellAppdirMessage(appdirInjectionAttempted));
+    }
     if (/invalid filename/i.test(combinedOutput) ||
         /chrome:\/\/mochitests.*not found/i.test(combinedOutput)) {
         info('Hint: The test file may not be registered in browser.toml or jar.mn.');
@@ -159,6 +206,23 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     if (options.headless) {
         extraArgs.push('--headless');
     }
+    // --mach-arg is a verbatim passthrough for upstream mach/xpcshell/mochitest
+    // flags FireForge does not model directly (see the xpcshell appdir hint
+    // above for the motivating case). Appended AFTER --headless so mach sees
+    // the FireForge-managed flags first and the escape-valve ones last, which
+    // keeps the override precedence predictable.
+    if (options.machArg && options.machArg.length > 0) {
+        extraArgs.push(...options.machArg);
+    }
+    // xpcshell appdir auto-injection — see src/core/xpcshell-appdir.ts for the
+    // full motivation. On rebranded forks (appname != "firefox") the upstream
+    // harness silently ignores `firefox-appdir = "browser"` directives in the
+    // xpcshell.toml, so every `resource:///modules/…` import throws. We probe
+    // the nearest manifest, compute the absolute appdir under obj-*/dist/, and
+    // inject `--app-path=<abs>` so the harness uses the right root. Operator
+    // overrides via `--mach-arg=--app-path=…` always win — we skip injection
+    // when the operator already passed one.
+    const appdirInjection = await maybeInjectAppdirArg(paths.engine, normalizedPaths, buildCheck.objDir, extraArgs);
     // Log what we're doing
     if (normalizedPaths.length > 0) {
         info(`Running tests: ${normalizedPaths.join(', ')}`);
@@ -174,7 +238,34 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     catch (error) {
         throw new BuildError('Test process failed to start', 'mach test', error instanceof Error ? error : undefined);
     }
-    handleNonZeroTestExit(result, normalizedPaths);
+    handleNonZeroTestExit(result, normalizedPaths, appdirInjection);
+}
+/**
+ * Resolves and (when applicable) appends an `--app-path=<abs>` arg to
+ * `extraArgs`. Returns true iff the arg was injected. The logging branches
+ * mirror the {@link XpcshellAppdirOutcome} variants so an operator can tell
+ * from the test output whether FireForge tried to help and what it found.
+ */
+async function maybeInjectAppdirArg(engineDir, normalizedPaths, objDir, extraArgs) {
+    if (!objDir)
+        return false;
+    if (operatorAlreadySetAppPath(extraArgs))
+        return false;
+    const outcome = await resolveXpcshellAppdirArg(engineDir, normalizedPaths, objDir);
+    switch (outcome.kind) {
+        case 'none':
+            return false;
+        case 'mismatch':
+            warn(`xpcshell appdir auto-injection skipped — multiple test paths resolved to different app dirs (${outcome.values.join(', ')}). Pass --mach-arg=--app-path=<abs> to disambiguate.`);
+            return false;
+        case 'unresolved':
+            warn(`xpcshell appdir auto-injection skipped — manifest at ${outcome.manifestPath} requests appdir "${outcome.relativeAppdir}" but no matching directory exists under ${objDir}/dist/. Build artifacts may be stale.`);
+            return false;
+        case 'injected':
+            extraArgs.push(`--app-path=${outcome.result.appPath}`);
+            info(`xpcshell appdir auto-injected: --app-path=${outcome.result.appPath} (from ${outcome.result.manifestPath} firefox-appdir=${outcome.result.relativeAppdir}).`);
+            return true;
+    }
 }
 /** Registers the test command on the CLI program. */
 export function registerTest(program, { getProjectRoot, withErrorHandling }) {
@@ -184,6 +275,10 @@ export function registerTest(program, { getProjectRoot, withErrorHandling }) {
         .option('--headless', 'Run tests in headless mode')
         .option('--build', 'Run incremental UI build before testing')
         .option('--doctor', 'Run a marionette handshake preflight before tests (exit 1 on FAIL). With no paths, runs the preflight only.')
+        .option('--mach-arg <arg>', 'Forward this argument verbatim to `mach test` (repeatable). Escape valve for upstream xpcshell/mochitest flags FireForge does not model.', (value, acc) => {
+        acc.push(value);
+        return acc;
+    }, [])
         .action(withErrorHandling(async (paths, options) => {
         await testCommand(getProjectRoot(), paths, pickDefined(options));
     }));

package/dist/src/core/furnace-apply-ftl.d.ts

@@ -8,7 +8,7 @@
  * aborting the whole command. Missing jar.mn on a fork without a locale
  * package should not block a working `.mjs`/`.css` from shipping.
  */
-import type { DryRunAction, StepError } from '../types/furnace.js';
+import type { CustomComponentConfig, DryRunAction, StepError } from '../types/furnace.js';
 import { type RollbackJournal } from './furnace-rollback.js';
 /**
  * Copies a component's `.ftl` into the FTL tree and registers the chrome URI
@@ -28,6 +28,8 @@ export declare function describeLocaleFtlJarMnRegistration(name: string, ftlDir:
 /**
  * Drops the locale jar.mn entry for `fileName` when it's a `.ftl` whose
  * source workspace file has been deleted. Idempotent — absent entries are a
- * no-op.
+ * no-op. Early-returns for `sharedFtl` components: the shared bundle is
+ * owned elsewhere, and dropping its jar.mn line on our component's delete
+ * would orphan every other participant.
  */
-export declare function removeCustomFtlJarMnEntry(engineDir: string, fileName: string, ftlDir: string, rollbackJournal?: RollbackJournal): Promise<void>;
+export declare function removeCustomFtlJarMnEntry(engineDir: string, fileName: string, ftlDir: string, config: CustomComponentConfig, rollbackJournal?: RollbackJournal): Promise<void>;

package/dist/src/core/furnace-apply-ftl.js

@@ -81,9 +81,13 @@ export function describeLocaleFtlJarMnRegistration(name, ftlDir, ftlFile) {
 /**
  * Drops the locale jar.mn entry for `fileName` when it's a `.ftl` whose
  * source workspace file has been deleted. Idempotent — absent entries are a
- * no-op.
+ * no-op. Early-returns for `sharedFtl` components: the shared bundle is
+ * owned elsewhere, and dropping its jar.mn line on our component's delete
+ * would orphan every other participant.
  */
-export async function removeCustomFtlJarMnEntry(engineDir, fileName, ftlDir, rollbackJournal) {
+export async function removeCustomFtlJarMnEntry(engineDir, fileName, ftlDir, config, rollbackJournal) {
+    if (config.sharedFtl)
+        return;
     if (!fileName.endsWith('.ftl'))
         return;
     const tagName = fileName.slice(0, -'.ftl'.length);

package/dist/src/core/furnace-apply-helpers.js

@@ -139,10 +139,12 @@ export async function undeployCustomFiles(engineDir, config, deletedFiles, ftlDi
             await removeFile(enginePath);
             removed.push(relative(engineDir, enginePath));
         }
-        // When an `.ftl` is deleted from the workspace, the corresponding locale
+        // When an `.ftl` is deleted from the workspace the corresponding locale
         // jar.mn entry must also be dropped — otherwise the chrome URI points at
         // a missing file and runtime Fluent resolution breaks silently.
-        await removeCustomFtlJarMnEntry(engineDir, fileName, ftlDir, rollbackJournal);
+        // `removeCustomFtlJarMnEntry` early-returns for `sharedFtl` components
+        // (the shared bundle is owned elsewhere).
+        await removeCustomFtlJarMnEntry(engineDir, fileName, ftlDir, config, rollbackJournal);
     }
     return removed;
 }
@@ -306,7 +308,12 @@ async function buildCustomDryRunActions(name, componentDir, engineDir, config, t
             description: `Copy ${entry.name} to ${config.targetPath}`,
         });
     }
-    if (config.localized) {
+    // Per-component .ftl handling is skipped when the component opts into a
+    // shared feature-scoped bundle via `sharedFtl`. The shared file is
+    // registered (and copied) by whoever owns the feature bundle, so
+    // emitting a copy-ftl / register-jar action here would duplicate (or
+    // later orphan) the entry.
+    if (config.localized && !config.sharedFtl) {
         const ftlFile = `${name}.ftl`;
         const ftlSrc = join(componentDir, ftlFile);
         if (await pathExists(ftlSrc)) {
@@ -402,7 +409,10 @@ export async function applyCustomComponent(engineDir, name, componentDir, config
         affectedPaths.push(relative(engineDir, dest));
         copiedFileNames.push(entry.name);
     }));
-    if (config.localized) {
+    // See buildCustomDryRunActions for the rationale: when `sharedFtl` is set
+    // the shared bundle is owned elsewhere and FireForge must not copy or
+    // register a per-component `.ftl` on its behalf.
+    if (config.localized && !config.sharedFtl) {
         await applyCustomFtlFile(engineDir, name, componentDir, ftlDir, affectedPaths, stepErrors, rollbackJournal);
     }
     if (config.register) {

package/dist/src/core/furnace-config-custom.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Parser for the `custom` entries in furnace.json. Extracted from
+ * `furnace-config.ts` so the main config module stays under the
+ * per-file LOC budget — the custom-component schema has grown to
+ * carry opt-in fields (`composes`, `keyboardCovered`, `sharedFtl`) that
+ * each add their own validation branch.
+ */
+import type { CustomComponentConfig } from '../types/furnace.js';
+/**
+ * Validates a custom component config object.
+ * @param data - Raw data to validate
+ * @param name - Component name for error messages
+ */
+export declare function parseCustomConfig(data: Record<string, unknown>, name: string): CustomComponentConfig;

package/dist/src/core/furnace-config-custom.js

@@ -0,0 +1,64 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Parser for the `custom` entries in furnace.json. Extracted from
+ * `furnace-config.ts` so the main config module stays under the
+ * per-file LOC budget — the custom-component schema has grown to
+ * carry opt-in fields (`composes`, `keyboardCovered`, `sharedFtl`) that
+ * each add their own validation branch.
+ */
+import { FurnaceError } from '../errors/furnace.js';
+import { isExplicitAbsolutePath } from '../utils/paths.js';
+import { isBoolean, isString } from '../utils/validation.js';
+import { parseStringArray } from './furnace-config.js';
+import { validateSharedFtl } from './shared-ftl.js';
+/**
+ * Validates a custom component config object.
+ * @param data - Raw data to validate
+ * @param name - Component name for error messages
+ */
+export function parseCustomConfig(data, name) {
+    if (!isString(data['description'])) {
+        throw new FurnaceError(`Furnace config: custom "${name}.description" must be a string`);
+    }
+    if (!isString(data['targetPath'])) {
+        throw new FurnaceError(`Furnace config: custom "${name}.targetPath" must be a string`);
+    }
+    if (data['targetPath'].includes('..') || data['targetPath'].includes('\0')) {
+        throw new FurnaceError(`Furnace config: custom "${name}.targetPath" must not contain ".." or null bytes (path traversal)`);
+    }
+    if (isExplicitAbsolutePath(data['targetPath'])) {
+        throw new FurnaceError(`Furnace config: custom "${name}.targetPath" must not be an absolute path`);
+    }
+    if (!isBoolean(data['register'])) {
+        throw new FurnaceError(`Furnace config: custom "${name}.register" must be a boolean`);
+    }
+    if (!isBoolean(data['localized'])) {
+        throw new FurnaceError(`Furnace config: custom "${name}.localized" must be a boolean`);
+    }
+    if (data['composes'] !== undefined) {
+        parseStringArray(data['composes'], `${name}.composes`);
+    }
+    if (data['keyboardCovered'] !== undefined && !isBoolean(data['keyboardCovered'])) {
+        throw new FurnaceError(`Furnace config: custom "${name}.keyboardCovered" must be a boolean when set`);
+    }
+    let sharedFtl;
+    if (data['sharedFtl'] !== undefined) {
+        const result = validateSharedFtl(data['sharedFtl'], { localized: data['localized'] });
+        if (!result.ok) {
+            throw new FurnaceError(`Furnace config: custom "${name}.sharedFtl" ${result.reason}`);
+        }
+        sharedFtl = result.value;
+    }
+    return {
+        description: data['description'],
+        targetPath: data['targetPath'],
+        register: data['register'],
+        localized: data['localized'],
+        ...(data['composes'] !== undefined
+            ? { composes: parseStringArray(data['composes'], `${name}.composes`) }
+            : {}),
+        ...(data['keyboardCovered'] === true ? { keyboardCovered: true } : {}),
+        ...(sharedFtl !== undefined ? { sharedFtl } : {}),
+    };
+}
+//# sourceMappingURL=furnace-config-custom.js.map

package/dist/src/core/furnace-config.js

@@ -4,9 +4,9 @@ import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readJson, writeJson } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
-import { isExplicitAbsolutePath } from '../utils/paths.js';
-import { isArray, isBoolean, isObject, isString } from '../utils/validation.js';
+import { isArray, isObject, isString } from '../utils/validation.js';
 import { FIREFORGE_DIR } from './config.js';
+import { parseCustomConfig } from './furnace-config-custom.js';
 import { validateRuntimeVariables, validateTokenHostDocuments } from './furnace-config-tokens.js';
 import { resolveFtlDir } from './furnace-constants.js';
 import { detectComposesCycles, validateComposesReferences } from './furnace-graph-utils.js';
@@ -89,43 +89,6 @@ function parseOverrideConfig(data, name) {
         ...(isString(data['baseCommit']) ? { baseCommit: data['baseCommit'] } : {}),
     };
 }
-/**
- * Validates a custom component config object.
- * @param data - Raw data to validate
- * @param name - Component name for error messages
- */
-function parseCustomConfig(data, name) {
-    if (!isString(data['description'])) {
-        throw new FurnaceError(`Furnace config: custom "${name}.description" must be a string`);
-    }
-    if (!isString(data['targetPath'])) {
-        throw new FurnaceError(`Furnace config: custom "${name}.targetPath" must be a string`);
-    }
-    if (data['targetPath'].includes('..') || data['targetPath'].includes('\0')) {
-        throw new FurnaceError(`Furnace config: custom "${name}.targetPath" must not contain ".." or null bytes (path traversal)`);
-    }
-    if (isExplicitAbsolutePath(data['targetPath'])) {
-        throw new FurnaceError(`Furnace config: custom "${name}.targetPath" must not be an absolute path`);
-    }
-    if (!isBoolean(data['register'])) {
-        throw new FurnaceError(`Furnace config: custom "${name}.register" must be a boolean`);
-    }
-    if (!isBoolean(data['localized'])) {
-        throw new FurnaceError(`Furnace config: custom "${name}.localized" must be a boolean`);
-    }
-    if (data['composes'] !== undefined) {
-        parseStringArray(data['composes'], `${name}.composes`);
-    }
-    return {
-        description: data['description'],
-        targetPath: data['targetPath'],
-        register: data['register'],
-        localized: data['localized'],
-        ...(data['composes'] !== undefined
-            ? { composes: parseStringArray(data['composes'], `${name}.composes`) }
-            : {}),
-    };
-}
 /** The current (and only) config schema version. */
 const CURRENT_CONFIG_VERSION = 1;
 /**

package/dist/src/core/furnace-validate-accessibility.d.ts

@@ -1,6 +1,13 @@
-import type { ValidationIssue } from '../types/furnace.js';
+import type { CustomComponentConfig, ValidationIssue } from '../types/furnace.js';
 /**
  * Validates accessibility patterns in a component's .mjs file.
  * Checks for ARIA roles, keyboard handlers, l10n, and focus delegation.
+ *
+ * @param customConfig - When the component is custom, its matching entry
+ *   from `furnace.json`. Used to skip the `no-keyboard-handler` warning
+ *   when the component declares keyboard coverage either explicitly
+ *   (`keyboardCovered: true`) or via `composes` naming a native-interactive
+ *   inner element. Optional so stock/override callers and test fixtures
+ *   without config in scope can continue to call without changes.
  */
-export declare function validateAccessibility(componentDir: string, tagName: string): Promise<ValidationIssue[]>;
+export declare function validateAccessibility(componentDir: string, tagName: string, customConfig?: CustomComponentConfig): Promise<ValidationIssue[]>;