@hominis/fireforge 0.13.2 → 0.15.1

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

@@ -69,7 +69,7 @@ export async function addJarMnEntries(engineDir, tagName, files) {
     // check so that "moz-card.css" does not match "moz-card-group.css".
     const newFiles = files.filter((f) => !new RegExp(`content/global/elements/${escapeForRegex(f)}(?:\\s|$)`, 'm').test(content));
     if (newFiles.length === 0)
-        return;
+        return 0;
     // Build new entry lines using the indent detected from existing entries.
     const indent = detectJarMnIndent(lines);
     const newEntries = newFiles.map((f) => `${indent}content/global/elements/${f}  (widgets/${tagName}/${f})`);
@@ -111,6 +111,103 @@ export async function addJarMnEntries(engineDir, tagName, files) {
     lines.splice(insertIndex, 0, ...newEntries);
     content = lines.join('\n');
     await writeText(filePath, content);
+    return newFiles.length;
+}
+/**
+ * Adds a locale jar.mn entry mapping `<chromeSubPath>/<tagName>.ftl` to the
+ * on-disk `.ftl` that `furnace apply` just copied under the FTL tree. Without
+ * this entry the chrome URI passed to `window.MozXULElement.insertFTLIfNeeded`
+ * does not resolve at runtime, so the generated `--localized` component
+ * silently ships broken l10n.
+ *
+ * Degrades gracefully — if the locale jar.mn (e.g. `toolkit/locales/jar.mn`)
+ * does not exist, returns 0 rather than throwing, so a custom fork without a
+ * standard locales package can still apply a localized component.
+ *
+ * The written entry mirrors the Mozilla convention for toolkit widgets:
+ *
+ *   locale/@AB_CD@/<chromeSubPath>/<tagName>.ftl (%<chromeSubPath>/<tagName>.ftl)
+ *
+ * @param engineDir - Path to the Firefox engine source root
+ * @param jarMnRelPath - Engine-relative path to the locale jar.mn
+ * @param tagName - Custom element tag name (base of the `.ftl` file)
+ * @param chromeSubPath - Chrome sub-path (e.g. `toolkit/global`)
+ * @returns Number of entries inserted (0 when already present, or jar.mn missing)
+ */
+export async function addLocaleFtlJarMnEntry(engineDir, jarMnRelPath, tagName, chromeSubPath) {
+    const filePath = join(engineDir, jarMnRelPath);
+    if (!(await pathExists(filePath))) {
+        return 0;
+    }
+    const content = await readText(filePath);
+    const lines = content.split('\n');
+    const ftlFile = `${tagName}.ftl`;
+    const escapedTag = escapeForRegex(tagName);
+    const escapedChrome = escapeForRegex(chromeSubPath);
+    const presencePattern = new RegExp(`locale\\/(?:@AB_CD@|[a-zA-Z-]+)\\/${escapedChrome}\\/${escapedTag}\\.ftl`, 'm');
+    if (presencePattern.test(content)) {
+        return 0;
+    }
+    const indent = detectLocaleJarMnIndent(lines, chromeSubPath);
+    const newEntry = `${indent}locale/@AB_CD@/${chromeSubPath}/${ftlFile} (%${chromeSubPath}/${ftlFile})`;
+    const sectionPattern = new RegExp(`^(\\s+)locale\\/(?:@AB_CD@|[a-zA-Z-]+)\\/${escapedChrome}\\/([^.\\s]+)\\.ftl`);
+    let insertIndex = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === undefined)
+            continue;
+        const match = sectionPattern.exec(line);
+        if (match) {
+            const existingTag = match[2] ?? '';
+            if (existingTag > tagName) {
+                insertIndex = i;
+                break;
+            }
+            insertIndex = i + 1;
+        }
+    }
+    if (insertIndex === -1) {
+        // No existing entries under this chrome sub-path. Fall back to end-of-file
+        // placement so the operator can reorder manually if desired.
+        insertIndex = lines.length;
+    }
+    lines.splice(insertIndex, 0, newEntry);
+    await writeText(filePath, lines.join('\n'));
+    return 1;
+}
+/** Detects locale jar.mn indentation by sampling an existing matching entry. */
+function detectLocaleJarMnIndent(lines, chromeSubPath) {
+    const escapedChrome = escapeForRegex(chromeSubPath);
+    const pattern = new RegExp(`^(\\s+)locale\\/(?:@AB_CD@|[a-zA-Z-]+)\\/${escapedChrome}\\/`);
+    for (const line of lines) {
+        const match = pattern.exec(line);
+        if (match?.[1])
+            return match[1];
+    }
+    // Fall back to detecting any existing `locale/...` indent before giving up.
+    for (const line of lines) {
+        const match = /^(\s+)locale\//.exec(line);
+        if (match?.[1])
+            return match[1];
+    }
+    return '  ';
+}
+/**
+ * Removes a locale jar.mn entry previously written by `addLocaleFtlJarMnEntry`.
+ * Idempotent — if the entry is absent or the file is missing, nothing happens.
+ */
+export async function removeLocaleFtlJarMnEntry(engineDir, jarMnRelPath, tagName, chromeSubPath) {
+    const filePath = join(engineDir, jarMnRelPath);
+    if (!(await pathExists(filePath))) {
+        return;
+    }
+    const content = await readText(filePath);
+    const lines = content.split('\n');
+    const pattern = new RegExp(`locale\\/(?:@AB_CD@|[a-zA-Z-]+)\\/${escapeForRegex(chromeSubPath)}\\/${escapeForRegex(tagName)}\\.ftl`);
+    const filtered = lines.filter((line) => !pattern.test(line));
+    if (filtered.length === lines.length)
+        return;
+    await writeText(filePath, filtered.join('\n'));
 }
 /**
  * Removes all jar.mn entries for a given tag name.

package/dist/src/core/furnace-staleness.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Furnace staleness advisory — shared between `fireforge run` and
+ * `fireforge watch`. Both commands launch the built browser without
+ * first running `furnace apply`, so this helper surfaces a warning when
+ * component files have drifted from the last-applied checksums and the
+ * user is about to run with stale engine state.
+ *
+ * The check is advisory only: errors (broken furnace config, partial
+ * state, transient filesystem failure) must never block the caller.
+ */
+/**
+ * Emits a warning when any tracked override or custom component has
+ * changed on disk since the last apply. Safe to call from any build-time
+ * command that does not auto-apply — a failure inside the probe is
+ * downgraded to a verbose log and the caller continues.
+ */
+export declare function warnIfFurnaceStale(projectRoot: string): Promise<void>;

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

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Furnace staleness advisory — shared between `fireforge run` and
+ * `fireforge watch`. Both commands launch the built browser without
+ * first running `furnace apply`, so this helper surfaces a warning when
+ * component files have drifted from the last-applied checksums and the
+ * user is about to run with stale engine state.
+ *
+ * The check is advisory only: errors (broken furnace config, partial
+ * state, transient filesystem failure) must never block the caller.
+ */
+import { pathExists } from '../utils/fs.js';
+import { verbose, warn } from '../utils/logger.js';
+import { extractComponentChecksums, hasComponentChanged } from './furnace-apply-helpers.js';
+import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceState, } from './furnace-config.js';
+/**
+ * Emits a warning when any tracked override or custom component has
+ * changed on disk since the last apply. Safe to call from any build-time
+ * command that does not auto-apply — a failure inside the probe is
+ * downgraded to a verbose log and the caller continues.
+ */
+export async function warnIfFurnaceStale(projectRoot) {
+    try {
+        if (!(await furnaceConfigExists(projectRoot)))
+            return;
+        const config = await loadFurnaceConfig(projectRoot);
+        const state = await loadFurnaceState(projectRoot);
+        const furnacePaths = getFurnacePaths(projectRoot);
+        if (!state.appliedChecksums)
+            return;
+        const stale = [];
+        for (const name of Object.keys(config.overrides)) {
+            const dir = `${furnacePaths.overridesDir}/${name}`;
+            if (!(await pathExists(dir)))
+                continue;
+            const prev = extractComponentChecksums(state.appliedChecksums, 'override', name);
+            if (await hasComponentChanged(dir, prev))
+                stale.push(name);
+        }
+        for (const name of Object.keys(config.custom)) {
+            const dir = `${furnacePaths.customDir}/${name}`;
+            if (!(await pathExists(dir)))
+                continue;
+            const prev = extractComponentChecksums(state.appliedChecksums, 'custom', name);
+            if (await hasComponentChanged(dir, prev))
+                stale.push(name);
+        }
+        if (stale.length > 0) {
+            warn(`Furnace component${stale.length === 1 ? '' : 's'} modified since last apply: ${stale.join(', ')}. ` +
+                'Run "fireforge furnace apply" (or "fireforge build" which auto-applies) to update the engine.');
+        }
+    }
+    catch {
+        // Non-fatal: a broken furnace config should not block the caller.
+        verbose('Furnace staleness check skipped due to an error.');
+    }
+}
+//# sourceMappingURL=furnace-staleness.js.map

package/dist/src/core/furnace-validate-accessibility.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
-import { containsHardcodedTemplateText, createIssue, hasAriaRole, hasDelegatesFocusEnabled, hasGenericInteractiveElement, hasPositiveTabindex, hasTemplateClickHandler, hasTemplateKeyboardHandler, hasUnlabelledFormInput, } from './furnace-validate-helpers.js';
+import { containsHardcodedTemplateText, createIssue, hasAriaRole, hasDelegatesFocusEnabled, hasGenericInteractiveElement, hasPositiveTabindex, hasTemplateClickHandler, hasTemplateClickOnSyntheticInteractive, hasTemplateKeyboardHandler, hasUnlabelledFormInput, } from './furnace-validate-helpers.js';
 /**
  * Validates accessibility patterns in a component's .mjs file.
  * Checks for ARIA roles, keyboard handlers, l10n, and focus delegation.
@@ -17,7 +17,13 @@ export async function validateAccessibility(componentDir, tagName) {
     }
     const hasClick = hasTemplateClickHandler(content);
     const hasKeyboardHandler = hasTemplateKeyboardHandler(content);
-    if (hasClick && !hasKeyboardHandler) {
+    // Native interactive elements (<button>, <a href>, form controls,
+    // moz-button/moz-toggle/etc.) dispatch click on Enter/Space via the
+    // platform, so a duplicate keyboard handler would usually double-fire.
+    // Only flag synthetic markup (e.g. `<div @click>`) where the activation
+    // path has to be wired manually.
+    const hasClickOnSynthetic = hasTemplateClickOnSyntheticInteractive(content);
+    if (hasClickOnSynthetic && !hasKeyboardHandler) {
         issues.push(createIssue(tagName, 'warning', 'no-keyboard-handler', 'Interactive element has @click but no keyboard event handler (@keydown/@keypress/@keyup).'));
     }
     if (containsHardcodedTemplateText(content)) {

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

@@ -13,6 +13,14 @@ export declare function hasUnlabelledFormInput(content: string): boolean;
 export declare function hasTemplateClickHandler(content: string): boolean;
 /** Detects Lit-style template keyboard handlers. */
 export declare function hasTemplateKeyboardHandler(content: string): boolean;
+/**
+ * Returns true when `content` has at least one `@click=${...}` handler on a
+ * *synthetic* interactive element (e.g. `<div @click>`), which lacks native
+ * keyboard activation and therefore needs an explicit key handler for
+ * Enter/Space. Returns false when every `@click` handler sits on a native
+ * interactive element — those already fire `click` on keyboard activation.
+ */
+export declare function hasTemplateClickOnSyntheticInteractive(content: string): boolean;
 /** Detects hardcoded user-visible template text that should usually be localized. */
 export declare function containsHardcodedTemplateText(content: string): boolean;
 /** Detects whether a component opts into shadow-root focus delegation. */

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

@@ -52,6 +52,87 @@ export function hasTemplateClickHandler(content) {
 export function hasTemplateKeyboardHandler(content) {
     return /@key(down|press|up)\s*=\s*\$\{/.test(content);
 }
+/**
+ * Native HTML elements that dispatch `click` on Enter and Space via the
+ * platform. Attaching `@click` to these is NOT a keyboard-a11y bug because
+ * the browser already handles the keyboard activation path — a duplicate
+ * `@keydown`/`@keypress` handler would usually double-fire the action.
+ *
+ * `<a>` is accepted only when an `href` attribute is present; bare `<a>` is
+ * non-interactive and is treated as synthetic.
+ */
+const NATIVE_CLICK_INTERACTIVE_TAGS = new Set([
+    'button',
+    'input',
+    'select',
+    'textarea',
+    'summary',
+    'details',
+    // Mozilla widgets that extend the native pattern and keep Enter/Space activation.
+    'moz-button',
+    'moz-toggle',
+    'moz-checkbox',
+    'moz-radio',
+    'moz-radio-group',
+    'moz-menulist',
+]);
+/**
+ * Returns true when `content` has at least one `@click=${...}` handler on a
+ * *synthetic* interactive element (e.g. `<div @click>`), which lacks native
+ * keyboard activation and therefore needs an explicit key handler for
+ * Enter/Space. Returns false when every `@click` handler sits on a native
+ * interactive element — those already fire `click` on keyboard activation.
+ */
+export function hasTemplateClickOnSyntheticInteractive(content) {
+    const pattern = /@click\s*=\s*\$\{/g;
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+        if (isClickOnSyntheticInteractive(content, match.index)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Given the offset of an `@click=${...}` occurrence, walks backwards to find
+ * the opening `<tag` that owns it and decides whether that tag is a native
+ * interactive element (no warning needed) or a synthetic one (warning needed).
+ */
+function isClickOnSyntheticInteractive(content, clickIndex) {
+    // Find the nearest preceding `<` that starts a tag (skip `</` closers).
+    let i = clickIndex - 1;
+    let tagOpenIndex = -1;
+    while (i >= 0) {
+        if (content[i] === '<' && content[i + 1] !== '/') {
+            tagOpenIndex = i;
+            break;
+        }
+        // A `>` before an unclosed `<` means we're outside the attribute list,
+        // which shouldn't happen for a well-formed template but we defensively
+        // treat it as synthetic to preserve the prior-behaviour warning.
+        if (content[i] === '>') {
+            return true;
+        }
+        i--;
+    }
+    if (tagOpenIndex < 0)
+        return true;
+    const tagMatch = /^<([a-zA-Z][a-zA-Z0-9-]*)/.exec(content.slice(tagOpenIndex));
+    if (!tagMatch?.[1])
+        return true;
+    const tagName = tagMatch[1].toLowerCase();
+    if (tagName === 'a') {
+        // Bare <a> (no href) is non-interactive; require a keyboard handler.
+        // Look forward from the tag open for the closing `>` and scan the
+        // attribute text in between for an href attribute.
+        const tagEnd = content.indexOf('>', tagOpenIndex);
+        if (tagEnd < 0)
+            return true;
+        const attrs = content.slice(tagOpenIndex, tagEnd);
+        return !/\shref\s*=/.test(attrs);
+    }
+    return !NATIVE_CLICK_INTERACTIVE_TAGS.has(tagName);
+}
 function isSymbolOnlyText(text) {
     return Array.from(text).every((character) => {
         const code = character.codePointAt(0) ?? 0;

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

@@ -32,9 +32,15 @@ export declare function checkRegistrationConsistency(root: string, name: string,
 export declare function validateJarMnEntries(root: string, config: FurnaceConfig): Promise<ValidationIssue[]>;
 /**
  * Validates that components using design tokens have the tokens CSS
- * linked in browser.xhtml. Without the link, tokens silently resolve to nothing.
+ * linked in at least one chrome host document. Without the link, tokens
+ * silently resolve to nothing at runtime.
+ *
+ * Forks with multiple chrome host documents (e.g. `hominis.xhtml` beside
+ * `browser.xhtml`) can enumerate them via `tokenHostDocuments` in
+ * furnace.json; the warning fires only when NONE of the configured
+ * documents link the tokens CSS.
  */
-export declare function validateTokenLink(componentDir: string, tagName: string, root: string, tokenPrefix?: string): Promise<ValidationIssue[]>;
+export declare function validateTokenLink(componentDir: string, tagName: string, root: string, tokenPrefix?: string, tokenHostDocuments?: string[]): Promise<ValidationIssue[]>;
 /**
  * Post-apply registration consistency check for custom components.
  *

package/dist/src/core/furnace-validate-registration.js

@@ -206,11 +206,22 @@ export async function validateJarMnEntries(root, config) {
     }
     return issues;
 }
+/**
+ * Default chrome host document scanned by `validateTokenLink` when
+ * `tokenHostDocuments` is not configured in furnace.json.
+ */
+const DEFAULT_TOKEN_HOST_DOCUMENTS = ['browser/base/content/browser.xhtml'];
 /**
  * Validates that components using design tokens have the tokens CSS
- * linked in browser.xhtml. Without the link, tokens silently resolve to nothing.
+ * linked in at least one chrome host document. Without the link, tokens
+ * silently resolve to nothing at runtime.
+ *
+ * Forks with multiple chrome host documents (e.g. `hominis.xhtml` beside
+ * `browser.xhtml`) can enumerate them via `tokenHostDocuments` in
+ * furnace.json; the warning fires only when NONE of the configured
+ * documents link the tokens CSS.
  */
-export async function validateTokenLink(componentDir, tagName, root, tokenPrefix) {
+export async function validateTokenLink(componentDir, tagName, root, tokenPrefix, tokenHostDocuments) {
     const issues = [];
     const cssPath = join(componentDir, `${tagName}.css`);
     if (!(await pathExists(cssPath)))
@@ -221,11 +232,10 @@ export async function validateTokenLink(componentDir, tagName, root, tokenPrefix
     // Check if the component CSS references any tokens with the configured prefix
     if (!cssContent.includes(tokenPrefix))
         return issues;
-    // Check if browser.xhtml links the token CSS file
     const { engine: engineDir } = getProjectPaths(root);
-    const browserXhtmlPath = join(engineDir, 'browser/base/content/browser.xhtml');
-    if (!(await pathExists(browserXhtmlPath)))
-        return issues;
+    const hostDocuments = tokenHostDocuments && tokenHostDocuments.length > 0
+        ? tokenHostDocuments
+        : DEFAULT_TOKEN_HOST_DOCUMENTS;
     let tokensCssFile;
     try {
         const forgeConfig = await loadConfig(root);
@@ -237,13 +247,28 @@ export async function validateTokenLink(componentDir, tagName, root, tokenPrefix
         warn(`Could not resolve token CSS link target for ${tagName} during validation: ${reason}`);
         return issues;
     }
-    const xhtmlContent = await readText(browserXhtmlPath);
-    if (!xhtmlContent.includes(tokensCssFile)) {
+    const checkedDocuments = [];
+    let anyLinks = false;
+    for (const relDocPath of hostDocuments) {
+        const absPath = join(engineDir, relDocPath);
+        if (!(await pathExists(absPath)))
+            continue;
+        checkedDocuments.push(relDocPath);
+        const xhtmlContent = await readText(absPath);
+        if (xhtmlContent.includes(tokensCssFile)) {
+            anyLinks = true;
+            break;
+        }
+    }
+    if (checkedDocuments.length === 0)
+        return issues;
+    if (!anyLinks) {
+        const docsList = checkedDocuments.join(', ');
         issues.push({
             component: tagName,
             severity: 'warning',
             check: 'missing-token-link',
-            message: `Component uses ${tokenPrefix}* tokens but browser.xhtml does not link ${tokensCssFile}. Tokens will silently resolve to nothing.`,
+            message: `Component uses ${tokenPrefix}* tokens but none of the configured chrome host documents (${docsList}) link ${tokensCssFile}. Tokens will silently resolve to nothing. Configure additional hosts via furnace.json "tokenHostDocuments" if needed.`,
         });
     }
     return issues;

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

@@ -46,9 +46,9 @@ export async function validateComponent(componentDir, tagName, type, config, roo
         const forgeConfig = await loadConfig(root);
         issues.push(...buildOverrideVersionDriftIssues(config, forgeConfig.firefox.version, tagName));
     }
-    // Check for missing token link in browser.xhtml
+    // Check for missing token link across configured chrome host documents.
     if (root) {
-        issues.push(...(await validateTokenLink(componentDir, tagName, root, config?.tokenPrefix)));
+        issues.push(...(await validateTokenLink(componentDir, tagName, root, config?.tokenPrefix, config?.tokenHostDocuments)));
     }
     // When root is provided and this is a custom component with registration,
     // also run registration pattern and jar.mn validation for this component.

package/dist/src/core/marionette-preflight.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Marionette handshake preflight for `fireforge test --doctor`.
+ *
+ * Answers a single question before tests run: "does marionette come up?" A
+ * silent 360-second mach-test hang is indistinguishable from "tests failed
+ * to discover"; this helper surfaces the failure in under a minute with a
+ * clear PASS/FAIL line and the tail of the browser's stderr.
+ *
+ * The probe is intentionally narrow — it does not replace mach test or try
+ * to execute anything via marionette. It spawns `mach run --marionette
+ * --headless` (plus a throwaway profile) and waits for the marionette server
+ * to accept a TCP connection on the conventional port. Any byte read from
+ * the socket proves a handshake payload is being produced.
+ */
+import { spawn } from 'node:child_process';
+import net from 'node:net';
+export interface MarionettePreflightResult {
+    ok: boolean;
+    durationMs: number;
+    /** Human-readable summary. */
+    detail: string;
+}
+export interface MarionettePreflightOptions {
+    /** Total budget in ms. Defaults to 30 seconds. */
+    timeoutMs?: number;
+    /** Overrides marionette TCP port — primarily used in tests. */
+    port?: number;
+    /** Test seam: spawn and socket connect factories. */
+    spawner?: typeof spawn;
+    connect?: typeof net.createConnection;
+}
+/**
+ * Runs the marionette preflight. Returns PASS on first byte read from the
+ * marionette socket within the budget; FAIL otherwise. Always tears down the
+ * spawned browser before returning.
+ */
+export declare function runMarionettePreflight(engineDir: string, options?: MarionettePreflightOptions): Promise<MarionettePreflightResult>;
+/** Renders a PASS/FAIL banner to the CLI using the shared logger helpers. */
+export declare function reportMarionettePreflight(result: MarionettePreflightResult): void;

package/dist/src/core/marionette-preflight.js

@@ -0,0 +1,210 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Marionette handshake preflight for `fireforge test --doctor`.
+ *
+ * Answers a single question before tests run: "does marionette come up?" A
+ * silent 360-second mach-test hang is indistinguishable from "tests failed
+ * to discover"; this helper surfaces the failure in under a minute with a
+ * clear PASS/FAIL line and the tail of the browser's stderr.
+ *
+ * The probe is intentionally narrow — it does not replace mach test or try
+ * to execute anything via marionette. It spawns `mach run --marionette
+ * --headless` (plus a throwaway profile) and waits for the marionette server
+ * to accept a TCP connection on the conventional port. Any byte read from
+ * the socket proves a handshake payload is being produced.
+ */
+import { spawn } from 'node:child_process';
+import { mkdtemp, rm } from 'node:fs/promises';
+import net from 'node:net';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { pathExists } from '../utils/fs.js';
+import { info, warn } from '../utils/logger.js';
+import { ensureMach } from './mach.js';
+import { getPython } from './mach-python.js';
+/** Marionette's default TCP port when the browser is launched with `--marionette`. */
+const MARIONETTE_PORT = 2828;
+/** Overall budget for the preflight (browser boot + socket handshake). */
+const DEFAULT_PREFLIGHT_TIMEOUT_MS = 30_000;
+/** Per-attempt socket connect timeout. Polling continues until the overall budget expires. */
+const SOCKET_ATTEMPT_TIMEOUT_MS = 2_000;
+/** Tail of stderr preserved for FAIL diagnostics. */
+const STDERR_TAIL_LIMIT = 8 * 1024;
+/**
+ * Runs the marionette preflight. Returns PASS on first byte read from the
+ * marionette socket within the budget; FAIL otherwise. Always tears down the
+ * spawned browser before returning.
+ */
+export async function runMarionettePreflight(engineDir, options = {}) {
+    const timeoutMs = options.timeoutMs ?? DEFAULT_PREFLIGHT_TIMEOUT_MS;
+    const port = options.port ?? MARIONETTE_PORT;
+    const spawnerFn = options.spawner ?? spawn;
+    const connectFn = options.connect ?? net.createConnection;
+    const startedAt = Date.now();
+    const elapsed = () => Date.now() - startedAt;
+    if (!(await pathExists(engineDir))) {
+        return {
+            ok: false,
+            durationMs: elapsed(),
+            detail: 'Engine directory not found — run "fireforge download" first.',
+        };
+    }
+    try {
+        await ensureMach(engineDir);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            durationMs: elapsed(),
+            detail: `mach not available in engine: ${error.message}`,
+        };
+    }
+    const python = await getPython(engineDir);
+    const profileDir = await mkdtemp(join(tmpdir(), 'fireforge-marionette-'));
+    let child;
+    let stderrTail = '';
+    try {
+        child = spawnerFn(python, [
+            join(engineDir, 'mach'),
+            'run',
+            '--marionette',
+            '--headless',
+            '--no-remote',
+            '-profile',
+            profileDir,
+        ], {
+            cwd: engineDir,
+            env: { ...process.env, MOZ_HEADLESS: '1' },
+            stdio: ['ignore', 'ignore', 'pipe'],
+        });
+        child.stderr?.on('data', (data) => {
+            const chunk = data.toString();
+            stderrTail = (stderrTail + chunk).slice(-STDERR_TAIL_LIMIT);
+        });
+        const spawnedChild = child;
+        const socketResult = await waitForMarionetteSocket(port, connectFn, () => {
+            return elapsed() < timeoutMs && !hasChildExited(spawnedChild);
+        });
+        if (socketResult.ok) {
+            return {
+                ok: true,
+                durationMs: elapsed(),
+                detail: `Marionette handshake received on 127.0.0.1:${port} in ${Date.now() - startedAt}ms.`,
+            };
+        }
+        // Child may have exited before the socket was ever ready — surface that
+        // distinctly from "socket never answered" so the operator has a lead.
+        if (hasChildExited(spawnedChild)) {
+            return {
+                ok: false,
+                durationMs: elapsed(),
+                detail: `Browser process exited before marionette handshake (exit code ${String(spawnedChild.exitCode)}, signal ${spawnedChild.signalCode ?? 'none'}). ` +
+                    `stderr tail: ${stderrTail.trim().slice(-2_000) || '(empty)'}`,
+            };
+        }
+        return {
+            ok: false,
+            durationMs: elapsed(),
+            detail: `Marionette socket on 127.0.0.1:${port} did not respond within ${timeoutMs}ms. ` +
+                `stderr tail: ${stderrTail.trim().slice(-2_000) || '(empty)'}`,
+        };
+    }
+    finally {
+        if (child && !hasChildExited(child)) {
+            try {
+                child.kill('SIGTERM');
+            }
+            catch {
+                // Already exited — nothing to do.
+            }
+            // Small escalation: if the child doesn't honour SIGTERM quickly, SIGKILL
+            // so we don't leave a ghost mach process around after a failed probe.
+            await delay(500);
+            if (!hasChildExited(child)) {
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch {
+                    // Already gone.
+                }
+            }
+        }
+        try {
+            await rm(profileDir, { recursive: true, force: true });
+        }
+        catch (error) {
+            warn(`Could not clean up marionette preflight profile: ${error.message}`);
+        }
+    }
+}
+/** Returns true when the child process has exited (normal or signaled). */
+function hasChildExited(child) {
+    return child.exitCode !== null || child.signalCode !== null;
+}
+async function waitForMarionetteSocket(port, connectFn, keepTrying) {
+    while (keepTrying()) {
+        const result = await attemptMarionetteConnect(port, connectFn);
+        if (result.ok) {
+            return { ok: true };
+        }
+        await delay(400);
+    }
+    return { ok: false };
+}
+function attemptMarionetteConnect(port, connectFn) {
+    return new Promise((resolve) => {
+        const socket = connectFn({ host: '127.0.0.1', port });
+        let settled = false;
+        const finish = (ok) => {
+            if (settled)
+                return;
+            settled = true;
+            try {
+                socket.destroy();
+            }
+            catch {
+                // Ignore — already closed.
+            }
+            resolve({ ok });
+        };
+        const attemptTimer = setTimeout(() => {
+            finish(false);
+        }, SOCKET_ATTEMPT_TIMEOUT_MS);
+        attemptTimer.unref();
+        socket.once('connect', () => {
+            // Connect alone is insufficient — the marionette server performs a
+            // handshake send as soon as the socket opens, so wait for at least one
+            // byte to confirm the server is actually speaking marionette.
+            const readTimer = setTimeout(() => {
+                finish(false);
+            }, SOCKET_ATTEMPT_TIMEOUT_MS);
+            readTimer.unref();
+            socket.once('data', () => {
+                clearTimeout(readTimer);
+                finish(true);
+            });
+        });
+        socket.once('error', () => {
+            finish(false);
+        });
+        socket.once('close', () => {
+            finish(false);
+        });
+    });
+}
+function delay(ms) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        timer.unref();
+    });
+}
+/** Renders a PASS/FAIL banner to the CLI using the shared logger helpers. */
+export function reportMarionettePreflight(result) {
+    if (result.ok) {
+        info(`Marionette preflight: PASS (${result.durationMs}ms) — ${result.detail}`);
+    }
+    else {
+        warn(`Marionette preflight: FAIL (${result.durationMs}ms) — ${result.detail}`);
+    }
+}
+//# sourceMappingURL=marionette-preflight.js.map