@hominis/fireforge 0.14.0 → 0.15.2

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-compatibility.js

@@ -2,7 +2,7 @@
 import { join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
 import { hasRawCssColors } from '../utils/regex.js';
-import { classExtendsMozLitElement, collectCssVariableReferences, createIssue, getTokenPrefixContext, hasCustomElementDefineCall, hasRelativeModuleImport, stripCssBlockComments, } from './furnace-validate-helpers.js';
+import { classExtendsMozLitElement, collectCssVariableDeclarations, collectCssVariableReferences, createIssue, getTokenPrefixContext, hasCustomElementDefineCall, hasRelativeModuleImport, stripCssBlockComments, } from './furnace-validate-helpers.js';
 async function validateMjsCompatibility(mjsPath, tagName) {
     if (!(await pathExists(mjsPath)))
         return [];
@@ -29,13 +29,24 @@ async function validateCssCompatibility(cssPath, tagName, type, config, root) {
         issues.push(createIssue(tagName, 'error', 'raw-color-value', 'Raw color value found. Use CSS custom properties (var(--...)) for design token consistency.'));
     }
     if (config?.tokenPrefix) {
-        const { allowlist, inheritedOverrideVars } = await getTokenPrefixContext(tagName, type, config, root);
+        const { allowlist, inheritedOverrideVars, runtimeVariables } = await getTokenPrefixContext(tagName, type, config, root);
+        // Auto-exempt component-local runtime channels: a CSS custom property
+        // both declared and consumed in the same file is a runtime state
+        // channel (e.g. `--cam-x`), not a design-token reference. See
+        // `runtimeVariables` in furnace.json for cross-component cases.
+        const localDeclarations = collectCssVariableDeclarations(cssContent);
         for (const prop of collectCssVariableReferences(cssContent)) {
-            if (!prop.startsWith(config.tokenPrefix) &&
-                !allowlist.has(prop) &&
-                !inheritedOverrideVars.has(prop)) {
-                issues.push(createIssue(tagName, 'error', 'token-prefix-violation', `CSS references var(${prop}) which does not match the required token prefix "${config.tokenPrefix}". Use a design token or add to tokenAllowlist.`));
-            }
+            if (prop.startsWith(config.tokenPrefix))
+                continue;
+            if (allowlist.has(prop))
+                continue;
+            if (inheritedOverrideVars.has(prop))
+                continue;
+            if (runtimeVariables.has(prop))
+                continue;
+            if (localDeclarations.has(prop))
+                continue;
+            issues.push(createIssue(tagName, 'error', 'token-prefix-violation', `CSS references var(${prop}) which does not match the required token prefix "${config.tokenPrefix}". Use a design token, add to tokenAllowlist, or (for runtime state channels) list the variable in runtimeVariables.`));
         }
     }
     // Flag excessive !important usage

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

@@ -13,7 +13,33 @@ 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;
-/** Detects hardcoded user-visible template text that should usually be localized. */
+/**
+ * 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.
+ *
+ * Scoped to three positive contexts rather than scanning the whole file,
+ * because a bare `>…<` regex catches JS comparisons (`if (x > 0 && y <
+ * 100)`), diagnostic strings (`console.error("Failed <id> lookup")`), and
+ * identifier literals that are never shown to a user. Only matches that
+ * actually enter a UI render path count:
+ *
+ *   1. Content inside a Lit `` html`…` `` tagged template literal.
+ *   2. The string literal on the RHS of `.textContent = "…"` or
+ *      `.innerHTML = "…"`.
+ *   3. The string literal assigned to an XUL-widget `label=`,
+ *      `title=`, or `tooltiptext=` attribute when constructing DOM in JS.
+ *
+ * A file-wide `// furnace-ignore: hardcoded-text` comment suppresses all
+ * findings (matches the pre-existing escape hatch).
+ */
 export declare function containsHardcodedTemplateText(content: string): boolean;
 /** Detects whether a component opts into shadow-root focus delegation. */
 export declare function hasDelegatesFocusEnabled(content: string): boolean;
@@ -27,8 +53,20 @@ export declare function hasCustomElementDefineCall(mjsContent: string): boolean;
 export declare function classExtendsMozLitElement(mjsContent: string): boolean;
 /** Collects CSS custom property references used via var(--token-name). */
 export declare function collectCssVariableReferences(cssContent: string): string[];
+/**
+ * Collects CSS custom property *declarations* — names appearing on the
+ * left-hand side of a `--name:` declaration. Used to auto-exempt
+ * component-local runtime variables from the token-prefix check: if the
+ * component both declares and consumes a variable in its own CSS file, it
+ * is a local runtime channel, not a design-token reference.
+ *
+ * The anchor `(?:^|[{;,\s])` rules out `var(--name)` occurrences (which are
+ * always preceded by `(`), so references are not mistaken for declarations.
+ */
+export declare function collectCssVariableDeclarations(cssContent: string): Set<string>;
 /** Builds token-validation context from the config allowlist and inherited override CSS. */
 export declare function getTokenPrefixContext(tagName: string, type: ComponentType, config: FurnaceConfig, root: string | undefined): Promise<{
     allowlist: Set<string>;
     inheritedOverrideVars: Set<string>;
+    runtimeVariables: Set<string>;
 }>;

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;
@@ -67,28 +148,88 @@ function isWithinLocalizedElement(content, matchIndex) {
     const tagContent = contentBefore.slice(lastTagOpen, matchIndex + 1);
     return /data-l10n-id\s*=/.test(tagContent);
 }
-/** Detects hardcoded user-visible template text that should usually be localized. */
+/**
+ * Detects hardcoded user-visible template text that should usually be
+ * localized.
+ *
+ * Scoped to three positive contexts rather than scanning the whole file,
+ * because a bare `>…<` regex catches JS comparisons (`if (x > 0 && y <
+ * 100)`), diagnostic strings (`console.error("Failed <id> lookup")`), and
+ * identifier literals that are never shown to a user. Only matches that
+ * actually enter a UI render path count:
+ *
+ *   1. Content inside a Lit `` html`…` `` tagged template literal.
+ *   2. The string literal on the RHS of `.textContent = "…"` or
+ *      `.innerHTML = "…"`.
+ *   3. The string literal assigned to an XUL-widget `label=`,
+ *      `title=`, or `tooltiptext=` attribute when constructing DOM in JS.
+ *
+ * A file-wide `// furnace-ignore: hardcoded-text` comment suppresses all
+ * findings (matches the pre-existing escape hatch).
+ */
 export function containsHardcodedTemplateText(content) {
     if (/furnace-ignore:\s*hardcoded-text/.test(content)) {
         return false;
     }
-    const textPattern = />([^<$\s][^<$]*)</g;
-    let textMatch;
-    while ((textMatch = textPattern.exec(content)) !== null) {
-        const text = textMatch[1]?.trim() ?? '';
-        if (/\$\{/.test(text)) {
-            continue;
-        }
-        if (Array.from(text).length <= 1) {
-            continue;
-        }
-        if (isSymbolOnlyText(text)) {
-            continue;
-        }
-        if (isWithinLocalizedElement(content, textMatch.index)) {
-            continue;
+    return (hasFlaggedTextInLitTemplates(content) ||
+        hasFlaggedTextInDomAssignment(content) ||
+        hasFlaggedTextInXulAttribute(content));
+}
+function isFlaggableText(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return false;
+    if (/\$\{/.test(trimmed))
+        return false;
+    if (Array.from(trimmed).length <= 1)
+        return false;
+    if (isSymbolOnlyText(trimmed))
+        return false;
+    return true;
+}
+function hasFlaggedTextInLitTemplates(content) {
+    // Match `html\`…\`` regions, anchored on a non-identifier char before `html`
+    // so substrings like `otherhtml` do not spuriously open a template.
+    const htmlPattern = /(?:^|[^a-zA-Z0-9_$])html`([\s\S]*?)`/g;
+    let litMatch;
+    while ((litMatch = htmlPattern.exec(content)) !== null) {
+        const region = litMatch[1] ?? '';
+        const textPattern = />([^<$\s][^<$]*)</g;
+        let textMatch;
+        while ((textMatch = textPattern.exec(region)) !== null) {
+            const text = textMatch[1] ?? '';
+            if (!isFlaggableText(text))
+                continue;
+            if (isWithinLocalizedElement(region, textMatch.index))
+                continue;
+            return true;
         }
-        return true;
+    }
+    return false;
+}
+function hasFlaggedTextInDomAssignment(content) {
+    // `<expr>.textContent = "abc"` and `<expr>.innerHTML = "abc"` — these are
+    // user-visible render paths. Template-literal RHS is excluded (usually
+    // dynamic), matching the `${` guard used elsewhere in this helper.
+    const assignPattern = /\.(?:textContent|innerHTML)\s*=\s*(["'])((?:\\.|(?!\1).)*)\1/g;
+    let match;
+    while ((match = assignPattern.exec(content)) !== null) {
+        const text = match[2] ?? '';
+        if (isFlaggableText(text))
+            return true;
+    }
+    return false;
+}
+function hasFlaggedTextInXulAttribute(content) {
+    // Assignments like `node.setAttribute("label", "Save")` or JS-built XUL
+    // attributes `label="…"` / `title="…"` / `tooltiptext="…"` in template
+    // literals outside Lit blocks. Covers DOM built via createXULElement.
+    const setAttrPattern = /setAttribute\s*\(\s*["'](?:label|title|tooltiptext)["']\s*,\s*(["'])((?:\\.|(?!\1).)*)\1/g;
+    let setAttrMatch;
+    while ((setAttrMatch = setAttrPattern.exec(content)) !== null) {
+        const text = setAttrMatch[2] ?? '';
+        if (isFlaggableText(text))
+            return true;
     }
     return false;
 }
@@ -133,6 +274,27 @@ export function collectCssVariableReferences(cssContent) {
     }
     return referencedVariables;
 }
+/**
+ * Collects CSS custom property *declarations* — names appearing on the
+ * left-hand side of a `--name:` declaration. Used to auto-exempt
+ * component-local runtime variables from the token-prefix check: if the
+ * component both declares and consumes a variable in its own CSS file, it
+ * is a local runtime channel, not a design-token reference.
+ *
+ * The anchor `(?:^|[{;,\s])` rules out `var(--name)` occurrences (which are
+ * always preceded by `(`), so references are not mistaken for declarations.
+ */
+export function collectCssVariableDeclarations(cssContent) {
+    const declared = new Set();
+    const pattern = /(?:^|[{;,\s])(--[\w-]+)\s*:/g;
+    let match;
+    while ((match = pattern.exec(cssContent)) !== null) {
+        const name = match[1];
+        if (name)
+            declared.add(name);
+    }
+    return declared;
+}
 async function collectInheritedOverrideVariables(tagName, config, root) {
     const inheritedVariables = new Set();
     const basePath = config.overrides[tagName]?.basePath;
@@ -153,12 +315,14 @@ async function collectInheritedOverrideVariables(tagName, config, root) {
 /** Builds token-validation context from the config allowlist and inherited override CSS. */
 export async function getTokenPrefixContext(tagName, type, config, root) {
     const allowlist = new Set(config.tokenAllowlist ?? []);
+    const runtimeVariables = new Set(config.runtimeVariables ?? []);
     if (type !== 'override' || !root) {
-        return { allowlist, inheritedOverrideVars: new Set() };
+        return { allowlist, inheritedOverrideVars: new Set(), runtimeVariables };
     }
     return {
         allowlist,
         inheritedOverrideVars: await collectInheritedOverrideVariables(tagName, config, root),
+        runtimeVariables,
     };
 }
 //# sourceMappingURL=furnace-validate-helpers.js.map

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. `mybrowser.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. `mybrowser.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,46 @@
+/**
+ * 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 a cascade of layered checks (engine → mach → python →
+ * profile → spawn → handshake). Each layer has a tight per-attempt budget
+ * so a broken earlier layer fails fast with a specific diagnosis rather
+ * than blocking on the final socket poll for the full overall budget.
+ */
+import { spawn } from 'node:child_process';
+import net from 'node:net';
+export interface MarionettePreflightResult {
+    ok: boolean;
+    durationMs: number;
+    /** Human-readable summary. On FAIL, prefixed with `[layer N/6: <name>]`. */
+    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;
+    /**
+     * Grace window after spawn() before the browser is considered "running
+     * OK." Catches immediate crashes (missing dylib, wrong CPU arch, corrupt
+     * profile) at the spawn layer rather than the handshake layer. Default:
+     * {@link SPAWN_SETTLE_MS}. Tests may set this to 0 to skip the settle.
+     */
+    spawnSettleMs?: 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, with a diagnostic
+ * identifying which layer of the cascade broke. 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;