@hominis/fireforge 0.36.0 → 0.38.0

package/dist/src/core/build-baseline-types.d.ts

@@ -35,4 +35,62 @@ export interface BuildBaseline {
      * was recorded.
      */
     packageableFingerprints?: Record<string, string>;
+    /**
+     * What the packaged test runtime produced by the recorded build covers.
+     *
+     * - `'full'`: the build packaged the full test set — written by
+     *   `fireforge build` / `build --ui` and by a path-less
+     *   `fireforge test --build` (full-suite run).
+     * - `string[]`: engine-relative POSIX request paths of the file/directory-
+     *   scoped `fireforge test --build` invocation that produced the runtime.
+     *   A directory entry covers everything beneath it. Support fixtures for
+     *   manifests outside this list may be missing from `obj-*`/`_tests/`, so
+     *   an `--allow-stale-build` run over uncovered paths is refused rather
+     *   than dispatched into a hang.
+     *
+     * Missing on baselines written before 0.37.0 — only `fireforge build`
+     * wrote baselines then, so "full" is the honest historical value and the
+     * stale-check treats an absent field as full coverage.
+     *
+     * The record is project-scoped, which is also per-obj-dir: multi-objdir
+     * checkouts are refused up-front (`AmbiguousBuildArtifactsError`), so at
+     * most one obj dir exists per project.
+     *
+     * Union/"shared coverage" across successive scoped builds was evaluated
+     * and rejected as unsound — every baseline write refreshes
+     * `packageableFingerprints` for ALL dirty packageable paths, so a union
+     * would whitewash an earlier scope's edited fixtures while
+     * `obj-*`/`_tests/` still holds its stale staging; coverage therefore
+     * REPLACES.
+     */
+    testPackagingCoverage?: TestPackagingCoverage;
+    /**
+     * Anchor for the compiled StaticComponents table: the engine HEAD SHA of
+     * the last FULL-coverage build plus content fingerprints of the
+     * `components.conf` manifests that were dirty at that moment. Written
+     * fresh only on FULL-coverage baseline writes (`fireforge build`,
+     * `build --ui`, path-less `test --build`); a scoped `test --build`
+     * carries the previous record forward verbatim, because `mach build
+     * faster` does not rebake `components.conf` registrations into the
+     * compiled table. Missing on pre-0.38.0 baselines — the
+     * static-components stale check degrades to "fresh" in that case.
+     */
+    staticComponentsBaseline?: StaticComponentsBaseline;
+}
+/**
+ * State of the engine at the last FULL build, as far as compiled-in XPCOM
+ * component registration is concerned. See
+ * {@link BuildBaseline.staticComponentsBaseline}.
+ */
+export interface StaticComponentsBaseline {
+    /** Engine HEAD SHA at the time of the last full build. */
+    engineHeadSha: string;
+    /**
+     * Hex-encoded SHA-256 per `components.conf` path that was dirty
+     * (modified-against-HEAD or untracked) when the full build ran. Keys are
+     * engine-relative POSIX paths.
+     */
+    fingerprints: Record<string, string>;
 }
+/** Coverage claim of the packaged test runtime. See {@link BuildBaseline.testPackagingCoverage}. */
+export type TestPackagingCoverage = 'full' | string[];

package/dist/src/core/build-baseline.d.ts

@@ -15,7 +15,7 @@
  * on successful build completion; a failed build does not update it, so a
  * subsequent run still audits against the last known-good tree.
  */
-import type { BuildBaseline } from './build-baseline-types.js';
+import type { BuildBaseline, TestPackagingCoverage } from './build-baseline-types.js';
 /** Name of the last-build marker file under `.fireforge/`. */
 export declare const BUILD_BASELINE_FILENAME = "last-build.json";
 /**
@@ -39,5 +39,13 @@ export declare function readBuildBaseline(projectRoot: string): Promise<BuildBas
  * @param projectRoot - Root directory of the project
  * @param engineDir - Path to the engine directory
  * @param binaryName - Current `binaryName` from fireforge.json
+ * @param testPackagingCoverage - Coverage claim of the packaged test
+ *   runtime this build produced (`'full'`, or the scoped request paths of
+ *   a `test --build` invocation). Omitted → field left off the marker.
+ * @param previousBaseline - The baseline this write replaces, when the
+ *   caller has it. A scoped (non-`'full'`) write carries its
+ *   `staticComponentsBaseline` forward verbatim — `mach build faster`
+ *   does not rebake `components.conf` registrations, so the last FULL
+ *   build stays the honest anchor for the compiled StaticComponents table.
  */
-export declare function writeBuildBaseline(projectRoot: string, engineDir: string, binaryName: string): Promise<void>;
+export declare function writeBuildBaseline(projectRoot: string, engineDir: string, binaryName: string, testPackagingCoverage?: TestPackagingCoverage, previousBaseline?: BuildBaseline): Promise<void>;

package/dist/src/core/build-baseline.js

@@ -22,7 +22,7 @@ import { join } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { pathExists, readJson, writeJson } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
-import { isPackageablePath } from './build-audit.js';
+import { isPackageablePath, isXpcomManifestPath } from './build-audit.js';
 import { FIREFORGE_DIR } from './config-paths.js';
 import { getHead, hasChanges, isMissingHeadError } from './git.js';
 import { git } from './git-base.js';
@@ -65,8 +65,16 @@ export async function readBuildBaseline(projectRoot) {
  * @param projectRoot - Root directory of the project
  * @param engineDir - Path to the engine directory
  * @param binaryName - Current `binaryName` from fireforge.json
+ * @param testPackagingCoverage - Coverage claim of the packaged test
+ *   runtime this build produced (`'full'`, or the scoped request paths of
+ *   a `test --build` invocation). Omitted → field left off the marker.
+ * @param previousBaseline - The baseline this write replaces, when the
+ *   caller has it. A scoped (non-`'full'`) write carries its
+ *   `staticComponentsBaseline` forward verbatim — `mach build faster`
+ *   does not rebake `components.conf` registrations, so the last FULL
+ *   build stays the honest anchor for the compiled StaticComponents table.
  */
-export async function writeBuildBaseline(projectRoot, engineDir, binaryName) {
+export async function writeBuildBaseline(projectRoot, engineDir, binaryName, testPackagingCoverage, previousBaseline) {
     let engineHeadSha = '';
     try {
         engineHeadSha = await getHead(engineDir);
@@ -81,11 +89,20 @@ export async function writeBuildBaseline(projectRoot, engineDir, binaryName) {
         }
     }
     const packageableFingerprints = await collectPackageableFingerprints(engineDir);
+    // A full-coverage write (and the legacy no-claim `fireforge build` shape)
+    // just recompiled the StaticComponents table, so it anchors the table to
+    // the current engine state. A scoped write did not — carry the previous
+    // anchor forward verbatim.
+    const staticComponentsBaseline = testPackagingCoverage === undefined || testPackagingCoverage === 'full'
+        ? await collectStaticComponentsBaseline(engineDir, engineHeadSha)
+        : previousBaseline?.staticComponentsBaseline;
     const baseline = {
         engineHeadSha,
         builtAt: new Date().toISOString(),
         binaryName,
         ...(packageableFingerprints !== undefined ? { packageableFingerprints } : {}),
+        ...(testPackagingCoverage !== undefined ? { testPackagingCoverage } : {}),
+        ...(staticComponentsBaseline !== undefined ? { staticComponentsBaseline } : {}),
     };
     await writeJson(getBuildBaselinePath(projectRoot), baseline);
 }
@@ -103,6 +120,33 @@ export async function writeBuildBaseline(projectRoot, engineDir, binaryName) {
  * back to the pre-0.16.0 "path-only" behavior on the next test run.
  */
 async function collectPackageableFingerprints(engineDir) {
+    return collectDirtyFingerprints(engineDir, isPackageablePath, 'packageable fingerprint');
+}
+/**
+ * Anchor for the compiled StaticComponents table: the engine HEAD SHA of
+ * this (full) build plus content fingerprints of the `components.conf`
+ * manifests dirty right now — the same dirty-path probe family as
+ * {@link collectPackageableFingerprints}, filtered to XPCOM manifests.
+ * Returns `undefined` on probe failure so a broken probe omits the field
+ * (the static-components stale check then degrades to "fresh") rather than
+ * anchoring to a garbage record.
+ */
+async function collectStaticComponentsBaseline(engineDir, engineHeadSha) {
+    const fingerprints = await collectDirtyFingerprints(engineDir, isXpcomManifestPath, 'static-components fingerprint');
+    if (fingerprints === undefined) {
+        return undefined;
+    }
+    return { engineHeadSha, fingerprints };
+}
+/**
+ * Shared dirty-path fingerprint probe backing
+ * {@link collectPackageableFingerprints} and
+ * {@link collectStaticComponentsBaseline}: enumerates engine workdir
+ * modifications (tracked and untracked), keeps the paths `includePath`
+ * accepts, and hashes each. Returns `undefined` on any git failure so a
+ * broken probe never corrupts the on-disk baseline with `{}`.
+ */
+async function collectDirtyFingerprints(engineDir, includePath, contextLabel) {
     try {
         const dirtyPaths = new Set();
         if (await hasChanges(engineDir)) {
@@ -116,12 +160,12 @@ async function collectPackageableFingerprints(engineDir) {
                 dirtyPaths.add(untracked);
             }
         }
-        const packageable = [...dirtyPaths].filter(isPackageablePath);
-        if (packageable.length === 0) {
+        const included = [...dirtyPaths].filter(includePath);
+        if (included.length === 0) {
             return {};
         }
         const fingerprints = {};
-        for (const relPath of packageable) {
+        for (const relPath of included) {
             try {
                 const buffer = await readFile(join(engineDir, relPath));
                 fingerprints[relPath] = createHash('sha256').update(buffer).digest('hex');
@@ -130,13 +174,13 @@ async function collectPackageableFingerprints(engineDir) {
                 // A file that disappeared between status probe and hash is
                 // expected in concurrent scenarios; skip it without failing the
                 // whole baseline write.
-                verbose(`Build baseline: skipping fingerprint for ${relPath} — ${toError(fileError).message}`);
+                verbose(`Build baseline: skipping ${contextLabel} for ${relPath} — ${toError(fileError).message}`);
             }
         }
         return fingerprints;
     }
     catch (error) {
-        verbose(`Build baseline: packageable fingerprint probe failed — ${toError(error).message}`);
+        verbose(`Build baseline: ${contextLabel} probe failed — ${toError(error).message}`);
         return undefined;
     }
 }

package/dist/src/core/config-paths.d.ts

@@ -11,7 +11,7 @@ export declare const STATE_FILENAME = "state.json";
 /** Supported top-level fireforge.json keys backed by the current schema. */
 export declare const SUPPORTED_CONFIG_ROOT_KEYS: readonly ["name", "vendor", "appId", "binaryName", "firefox", "build", "test", "externalToolchains", "license", "wire", "patchLint", "patchPolicy", "typecheck", "markerComment"];
 /** Supported config paths that can be read or set without --force. */
-export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "firefox.sha256", "build", "build.jobs", "test", "test.canaryPath", "test.canaryTimeoutSeconds", "externalToolchains", "wire", "wire.subscriptDir", "patchLint", "patchLint.checkJs", "patchLint.checkJsStrict", "patchLint.checkJsCompilerOptions", "patchLint.checkJsExtraShim", "patchLint.rawColorAllowlist", "patchLint.jsdocClassMethods", "patchLint.testAssertionFloor", "patchLint.chromeScriptJsDoc", "patchPolicy", "typecheck", "typecheck.projects", "typecheck.extraShim", "markerComment"];
+export declare const SUPPORTED_CONFIG_PATHS: readonly ["name", "vendor", "appId", "binaryName", "license", "firefox", "firefox.version", "firefox.product", "firefox.sha256", "firefox.candidate", "build", "build.jobs", "test", "test.canaryPath", "test.canaryTimeoutSeconds", "externalToolchains", "wire", "wire.subscriptDir", "patchLint", "patchLint.checkJs", "patchLint.checkJsStrict", "patchLint.checkJsCompilerOptions", "patchLint.checkJsExtraShim", "patchLint.rawColorAllowlist", "patchLint.jsdocClassMethods", "patchLint.testAssertionFloor", "patchLint.chromeScriptJsDoc", "patchPolicy", "typecheck", "typecheck.projects", "typecheck.extraShim", "markerComment"];
 /**
  * Gets all project paths based on a root directory.
  * @param root - Root directory of the project

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

@@ -45,6 +45,7 @@ export const SUPPORTED_CONFIG_PATHS = [
     'firefox.version',
     'firefox.product',
     'firefox.sha256',
+    'firefox.candidate',
     'build',
     'build.jobs',
     'test',

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

@@ -6,7 +6,7 @@ import { ConfigError } from '../errors/config.js';
 import { verbose } from '../utils/logger.js';
 import { parseObject } from '../utils/parse.js';
 import { isContainedRelativePath, isExplicitAbsolutePath } from '../utils/paths.js';
-import { isValidAppId, isValidFirefoxVersion, isValidProjectLicense, PROJECT_LICENSES, validateFirefoxProductVersionCompatibility, } from '../utils/validation.js';
+import { isValidAppId, isValidFirefoxCandidate, isValidFirefoxVersion, isValidProjectLicense, PROJECT_LICENSES, validateFirefoxProductVersionCompatibility, } from '../utils/validation.js';
 import { SUPPORTED_CONFIG_ROOT_KEYS } from './config-paths.js';
 import { parsePatchPolicyBlock } from './config-validate-patch-policy.js';
 import { parseExternalToolchainsBlock, parseTestBlock } from './config-validate-test-toolchains.js';
@@ -81,10 +81,15 @@ function parseFirefoxBlock(rec) {
     if (firefoxSha256 !== undefined && !/^[a-f0-9]{64}$/i.test(firefoxSha256)) {
         throw new ConfigError('Config field "firefox.sha256" must be a 64-character SHA-256 hex digest');
     }
+    const firefoxCandidate = optionalConfigString(firefoxRec, 'candidate', 'firefox.candidate');
+    if (firefoxCandidate !== undefined && !isValidFirefoxCandidate(firefoxCandidate)) {
+        throw new ConfigError('Config field "firefox.candidate" must look like "buildN" (e.g. "build2")');
+    }
     return {
         version: firefoxVersion,
         product: firefoxProduct,
         ...(firefoxSha256 !== undefined ? { sha256: firefoxSha256.toLowerCase() } : {}),
+        ...(firefoxCandidate !== undefined ? { candidate: firefoxCandidate } : {}),
     };
 }
 /** Parses the optional `build` block (currently just `build.jobs`). */

package/dist/src/core/engine-session-lock.d.ts

@@ -1,7 +1,16 @@
+export interface EngineSessionLockOptions {
+    /**
+     * Wait up to this many seconds for the engine session lock instead of the
+     * legacy ~1 s fail-fast. Enables exponential poll backoff (100 ms → 2 s)
+     * and a holder-identified progress line roughly every 5 s. `undefined`
+     * preserves the historical fail-fast behavior exactly.
+     */
+    waitLockSeconds?: number | undefined;
+}
 /**
  *
  */
-export declare function withEngineSessionLock<T>(projectRoot: string, command: string, operation: () => Promise<T>): Promise<T>;
+export declare function withEngineSessionLock<T>(projectRoot: string, command: string, operation: () => Promise<T>, options?: EngineSessionLockOptions): Promise<T>;
 /**
  *
  */

package/dist/src/core/engine-session-lock.js

@@ -1,19 +1,45 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
 import { GeneralError } from '../errors/base.js';
+import { info } from '../utils/logger.js';
 import { withFileLock } from './file-lock.js';
 import { git } from './git-base.js';
 const ENGINE_SESSION_LOCK_PATH = join('.fireforge', 'engine-session.lock');
+/**
+ * Formats the periodic operator-facing waiting line printed while `--wait-lock`
+ * polls a contended engine session lock. The holder identification comes from
+ * the lock's owner-metadata lines (`command=…`, `started=…`); an unreadable
+ * owner file degrades to the anonymous form.
+ */
+function formatWaitProgressLine(waitedMs, timeoutMs, holder) {
+    const progress = `${String(Math.round(waitedMs / 1000))}s of up to ${String(Math.round(timeoutMs / 1000))}s`;
+    if (holder === undefined) {
+        return `Waiting for the FireForge engine lock — ${progress}.`;
+    }
+    const details = holder.metadata.length > 0 ? ` (${holder.metadata.join(', ')})` : '';
+    return `Waiting for the FireForge engine lock held by PID ${String(holder.pid)}${details} — ${progress}.`;
+}
 /**
  *
  */
-export async function withEngineSessionLock(projectRoot, command, operation) {
+export async function withEngineSessionLock(projectRoot, command, operation, options = {}) {
     if (process.env['FIREFORGE_ENABLE_ENGINE_SESSION_LOCK_IN_TEST'] !== '1' &&
         (process.env['NODE_ENV'] === 'test' || process.env['VITEST'] !== undefined)) {
         return operation();
     }
+    const { waitLockSeconds } = options;
     return withFileLock(join(projectRoot, ENGINE_SESSION_LOCK_PATH), operation, {
-        timeoutMs: 1000,
+        timeoutMs: waitLockSeconds !== undefined ? waitLockSeconds * 1000 : 1000,
+        ...(waitLockSeconds !== undefined
+            ? {
+                pollMs: 100,
+                pollMaxMs: 2000,
+                waitProgressMs: 5000,
+                onWaitProgress: ({ waitedMs, timeoutMs, holder }) => {
+                    info(formatWaitProgressLine(waitedMs, timeoutMs, holder));
+                },
+            }
+            : {}),
         ownerMetadata: [`command=${command}`, `started=${new Date().toISOString()}`],
         onTimeoutMessage: `Another FireForge engine-mutating command is already running. ` +
             `Wait for it to finish, then retry \`${command}\`.`,

package/dist/src/core/file-lock.d.ts

@@ -1,6 +1,23 @@
+/**
+ * Snapshot of the current lock holder handed to {@link FileLockOptions.onWaitProgress}.
+ * `metadata` carries the pid file's human-diagnostic lines (line 3 onward,
+ * e.g. `command=build`, `started=…`) written via
+ * {@link FileLockOptions.ownerMetadata}.
+ */
+export interface LockHolder {
+    pid: number;
+    alive: boolean;
+    metadata: string[];
+}
 export interface FileLockOptions {
     timeoutMs?: number;
     pollMs?: number;
+    /**
+     * When set, the poll interval doubles after every contended poll (starting
+     * from `pollMs`) up to this cap. When absent, polling stays at the fixed
+     * `pollMs` interval — zero behavior change for existing callers.
+     */
+    pollMaxMs?: number;
     staleMs?: number;
     /**
      * Interval between stale-lock probes while waiting (defaults to
@@ -8,6 +25,22 @@ export interface FileLockOptions {
      * the mid-wait reaping path without multi-second sleeps.
      */
     staleReprobeMs?: number;
+    /**
+     * Interval between {@link onWaitProgress} callbacks while the lock is
+     * contended. Progress reporting is off unless both this and
+     * `onWaitProgress` are set.
+     */
+    waitProgressMs?: number;
+    /**
+     * Invoked roughly every `waitProgressMs` while waiting for a contended
+     * lock. `holder` is `undefined` when the owner PID file is missing or
+     * unreadable.
+     */
+    onWaitProgress?: (progress: {
+        waitedMs: number;
+        timeoutMs: number;
+        holder: LockHolder | undefined;
+    }) => void;
     onTimeoutMessage?: string;
     onStaleLockMessage?: (ageMs: number) => string | undefined;
     /** Extra owner-file lines for human diagnostics; ignored by lock mechanics. */

package/dist/src/core/file-lock.js

@@ -50,7 +50,8 @@ function isProcessAlive(pid) {
     }
 }
 /**
- * Reads the owner PID (line 1) and acquisition token (line 2) from a lock
+ * Reads the owner PID (line 1), acquisition token (line 2), and diagnostic
+ * metadata (lines 3+, see {@link FileLockOptions.ownerMetadata}) from a lock
  * directory's PID file. Returns `{ present: false }` when the PID file is
  * missing or the PID does not parse as a finite integer (caller falls back
  * to the age-only staleness heuristic).
@@ -62,14 +63,15 @@ function isProcessAlive(pid) {
 async function readLockOwner(lockPath) {
     try {
         const pidContent = await readFile(join(lockPath, LOCK_PID_FILE), 'utf-8');
-        const [pidLine, tokenLine] = pidContent.split('\n');
+        const [pidLine, tokenLine, ...metadataLines] = pidContent.split('\n');
         const pid = parseInt((pidLine ?? '').trim(), 10);
         if (Number.isFinite(pid)) {
+            const metadata = metadataLines.map((line) => line.trim()).filter((line) => line.length > 0);
             const token = tokenLine?.trim();
             if (token !== undefined && token.length > 0) {
-                return { present: true, pid, token };
+                return { present: true, pid, token, metadata };
             }
-            return { present: true, pid };
+            return { present: true, pid, metadata };
         }
     }
     catch {
@@ -77,6 +79,18 @@ async function readLockOwner(lockPath) {
     }
     return { present: false };
 }
+/**
+ * Reads the contended lock's owner and reports wait progress to the caller's
+ * `onWaitProgress` callback. Failure to read the owner degrades to
+ * `holder: undefined` — progress reporting must never break the wait loop.
+ */
+async function reportWaitProgress(lockPath, waitedMs, timeoutMs, onWaitProgress) {
+    const owner = await readLockOwner(lockPath);
+    const holder = owner.present
+        ? { pid: owner.pid, alive: isProcessAlive(owner.pid), metadata: owner.metadata }
+        : undefined;
+    onWaitProgress({ waitedMs, timeoutMs, holder });
+}
 /**
  * Reaps a lock directory believed to be stale, safely against concurrent
  * reapers and a concurrent legitimate re-acquisition.
@@ -216,8 +230,11 @@ export async function withFileLock(lockPath, operation, options = {}) {
     const pollMs = options.pollMs ?? DEFAULT_LOCK_POLL_MS;
     const staleMs = options.staleMs ?? DEFAULT_STALE_LOCK_MS;
     const staleReprobeMs = options.staleReprobeMs ?? STALE_REPROBE_INTERVAL_MS;
-    const deadline = Date.now() + timeoutMs;
+    const startedAt = Date.now();
+    const deadline = startedAt + timeoutMs;
     let lastStaleProbeAt;
+    let currentPollMs = pollMs;
+    let lastProgressAt = startedAt;
     await ensureDir(dirname(lockPath));
     for (;;) {
         try {
@@ -246,7 +263,16 @@ export async function withFileLock(lockPath, operation, options = {}) {
                     : ' If no other FireForge process is running, remove the lock directory and retry.';
                 throw new Error(options.onTimeoutMessage ?? `Timed out waiting for file lock ${lockPath}.${holderHint}`, { cause: error });
             }
-            await sleep(pollMs);
+            if (options.onWaitProgress !== undefined &&
+                options.waitProgressMs !== undefined &&
+                Date.now() - lastProgressAt >= options.waitProgressMs) {
+                lastProgressAt = Date.now();
+                await reportWaitProgress(lockPath, Date.now() - startedAt, timeoutMs, options.onWaitProgress);
+            }
+            await sleep(currentPollMs);
+            if (options.pollMaxMs !== undefined) {
+                currentPollMs = Math.min(currentPollMs * 2, options.pollMaxMs);
+            }
         }
     }
     // Stamp ownership (PID + per-acquisition token) into the lock directory so

package/dist/src/core/firefox-archive.d.ts

@@ -39,6 +39,7 @@ export declare function validateArchiveMetadata(data: unknown): ArchiveMetadata;
  * Resolves archive identity for URL generation and cache storage.
  * @param version - Requested Firefox version
  * @param product - Firefox product type
+ * @param candidate - Optional release-candidate build directory (e.g. "build2")
  * @returns Resolved archive descriptor
  */
-export declare function resolveArchive(version: string, product?: FirefoxProduct): ResolvedArchive;
+export declare function resolveArchive(version: string, product?: FirefoxProduct, candidate?: string): ResolvedArchive;

package/dist/src/core/firefox-archive.js

@@ -4,15 +4,26 @@
  */
 import { ConfigError } from '../errors/config.js';
 import { parseObject } from '../utils/parse.js';
-import { isValidFirefoxProduct } from '../utils/validation.js';
+import { isValidFirefoxCandidate, isValidFirefoxProduct } from '../utils/validation.js';
 /**
  * Base URLs for Firefox source archives on archive.mozilla.org.
  */
-const FIREFOX_ARCHIVE_BASE_URL = 'https://archive.mozilla.org/pub/firefox/releases';
-const DEVEDITION_ARCHIVE_BASE_URL = 'https://archive.mozilla.org/pub/devedition/releases';
+const FIREFOX_ARCHIVE_BASE_URL = 'https://archive.mozilla.org/pub/firefox';
+const DEVEDITION_ARCHIVE_BASE_URL = 'https://archive.mozilla.org/pub/devedition';
 function getArchiveBaseUrl(product) {
     return product === 'firefox-devedition' ? DEVEDITION_ARCHIVE_BASE_URL : FIREFOX_ARCHIVE_BASE_URL;
 }
+/**
+ * Directory holding the release's artifacts: `releases/<version>/` for
+ * final releases, `candidates/<version>-candidates/<buildN>/` when a
+ * release-candidate build is requested for pre-release verification.
+ */
+function getArchiveDirUrl(product, archiveVersion, candidate) {
+    const base = getArchiveBaseUrl(product);
+    return candidate === undefined
+        ? `${base}/releases/${archiveVersion}`
+        : `${base}/candidates/${archiveVersion}-candidates/${candidate}`;
+}
 /**
  * Validates raw JSON data as ArchiveMetadata.
  * @param data - Unknown data to validate
@@ -41,13 +52,20 @@ export function validateArchiveMetadata(data) {
  * Resolves archive identity for URL generation and cache storage.
  * @param version - Requested Firefox version
  * @param product - Firefox product type
+ * @param candidate - Optional release-candidate build directory (e.g. "build2")
  * @returns Resolved archive descriptor
  */
-export function resolveArchive(version, product = 'firefox') {
+export function resolveArchive(version, product = 'firefox', candidate) {
     // Reject versions containing path traversal characters
     if (version.includes('/') || version.includes('..') || version.includes('\\')) {
         throw new ConfigError(`Invalid Firefox version "${version}": contains disallowed characters`, 'firefox.version');
     }
+    // Defense-in-depth: config validation enforces this shape already, but a
+    // caller-supplied candidate becomes both a URL path segment and part of
+    // the cache filename, so re-validate here like the version check above.
+    if (candidate !== undefined && !isValidFirefoxCandidate(candidate)) {
+        throw new ConfigError(`Invalid Firefox candidate "${candidate}": must look like "buildN" (e.g. "build2")`, 'firefox.candidate');
+    }
     // ESR status is determined solely by the product field. Config validation
     // ensures product and version are consistent, so we never need to infer
     // ESR from the version string independently.
@@ -55,18 +73,24 @@ export function resolveArchive(version, product = 'firefox') {
     const isEsr = product === 'firefox-esr';
     const archiveVersion = isEsr ? `${cleanVersion}esr` : cleanVersion;
     const safeProduct = product.replace(/[^a-z0-9-]/gi, '-');
+    const dirUrl = getArchiveDirUrl(product, archiveVersion, candidate);
+    // Candidate artifacts get a `-<candidate>` filename suffix so a build2
+    // archive can never collide with the final release artifact (same
+    // archiveVersion, potentially different bytes) in .fireforge/cache.
+    const candidateSuffix = candidate === undefined ? '' : `-${candidate}`;
+    const filename = `firefox-${safeProduct}-${archiveVersion}${candidateSuffix}.source.tar.xz`;
     return {
         requestedVersion: version,
         product,
         archiveVersion,
-        url: `${getArchiveBaseUrl(product)}/${archiveVersion}/source/firefox-${archiveVersion}.source.tar.xz`,
-        filename: `firefox-${safeProduct}-${archiveVersion}.source.tar.xz`,
-        metadataFilename: `firefox-${safeProduct}-${archiveVersion}.source.tar.xz.json`,
+        url: `${dirUrl}/source/firefox-${archiveVersion}.source.tar.xz`,
+        filename,
+        metadataFilename: `${filename}.json`,
         // Mozilla publishes one SHA256SUMS per release directory listing every
         // artifact by its release-relative path. Downloads verify against it by
         // default (fail closed on mismatch), so a compromised CDN response
         // cannot silently become the trusted git baseline.
-        checksumsUrl: `${getArchiveBaseUrl(product)}/${archiveVersion}/SHA256SUMS`,
+        checksumsUrl: `${dirUrl}/SHA256SUMS`,
         pathInChecksums: `source/firefox-${archiveVersion}.source.tar.xz`,
     };
 }

package/dist/src/core/firefox.d.ts

@@ -13,16 +13,18 @@ export { formatBytes, getFirefoxVersion } from './firefox-extract.js';
  * Gets the download URL for a Firefox source tarball.
  * @param version - Firefox version (e.g., "140.9.0esr")
  * @param product - Firefox product type
+ * @param candidate - Optional release-candidate build directory (e.g. "build2")
  * @returns Full URL to the source tarball
  */
-export declare function getDownloadUrl(version: string, product?: FirefoxProduct): string;
+export declare function getDownloadUrl(version: string, product?: FirefoxProduct, candidate?: string): string;
 /**
  * Gets the filename for a Firefox source tarball.
  * @param version - Firefox version
  * @param product - Firefox product type
+ * @param candidate - Optional release-candidate build directory (e.g. "build2")
  * @returns Tarball filename
  */
-export declare function getTarballFilename(version: string, product?: FirefoxProduct): string;
+export declare function getTarballFilename(version: string, product?: FirefoxProduct, candidate?: string): string;
 /**
  * Lifecycle phase reported by {@link downloadFirefoxSource}. The download
  * CLI command uses this to swap spinners between the bytes-on-the-wire
@@ -57,5 +59,8 @@ export declare function sweepOrphanedEngineWorkDirs(destDir: string): Promise<st
  * @param onPhase - Optional callback fired when the function transitions
  *   between phases (`'download'` → `'extract'`). Fires exactly once per
  *   phase even if the cached archive path skips the wire entirely.
+ * @param candidate - Optional release-candidate build directory (e.g.
+ *   "build2") resolving the archive under `candidates/` instead of
+ *   `releases/`.
  */
-export declare function downloadFirefoxSource(version: string, product: FirefoxProduct, destDir: string, cacheDir: string, onProgress?: ProgressCallback, onPhase?: FirefoxSourcePhaseCallback, expectedSha256?: string, onPhaseProgress?: FirefoxSourceProgressCallback): Promise<void>;
+export declare function downloadFirefoxSource(version: string, product: FirefoxProduct, destDir: string, cacheDir: string, onProgress?: ProgressCallback, onPhase?: FirefoxSourcePhaseCallback, expectedSha256?: string, onPhaseProgress?: FirefoxSourceProgressCallback, candidate?: string): Promise<void>;

package/dist/src/core/firefox.js

@@ -19,19 +19,21 @@ export { formatBytes, getFirefoxVersion } from './firefox-extract.js';
  * Gets the download URL for a Firefox source tarball.
  * @param version - Firefox version (e.g., "140.9.0esr")
  * @param product - Firefox product type
+ * @param candidate - Optional release-candidate build directory (e.g. "build2")
  * @returns Full URL to the source tarball
  */
-export function getDownloadUrl(version, product = 'firefox') {
-    return resolveArchive(version, product).url;
+export function getDownloadUrl(version, product = 'firefox', candidate) {
+    return resolveArchive(version, product, candidate).url;
 }
 /**
  * Gets the filename for a Firefox source tarball.
  * @param version - Firefox version
  * @param product - Firefox product type
+ * @param candidate - Optional release-candidate build directory (e.g. "build2")
  * @returns Tarball filename
  */
-export function getTarballFilename(version, product = 'firefox') {
-    return resolveArchive(version, product).filename;
+export function getTarballFilename(version, product = 'firefox', candidate) {
+    return resolveArchive(version, product, candidate).filename;
 }
 /**
  * Classifies an extraction failure as archive corruption (invalidate the
@@ -100,9 +102,12 @@ export async function sweepOrphanedEngineWorkDirs(destDir) {
  * @param onPhase - Optional callback fired when the function transitions
  *   between phases (`'download'` → `'extract'`). Fires exactly once per
  *   phase even if the cached archive path skips the wire entirely.
+ * @param candidate - Optional release-candidate build directory (e.g.
+ *   "build2") resolving the archive under `candidates/` instead of
+ *   `releases/`.
  */
-export async function downloadFirefoxSource(version, product, destDir, cacheDir, onProgress, onPhase, expectedSha256, onPhaseProgress) {
-    const archive = resolveArchive(version, product);
+export async function downloadFirefoxSource(version, product, destDir, cacheDir, onProgress, onPhase, expectedSha256, onPhaseProgress, candidate) {
+    const archive = resolveArchive(version, product, candidate);
     const tarballPath = join(cacheDir, archive.filename);
     // Ensure cache directory exists
     await ensureDir(cacheDir);

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

@@ -35,6 +35,13 @@ export function parseCustomConfig(data, name) {
     if (!isBoolean(data['localized'])) {
         throw new FurnaceError(`Furnace config: custom "${name}.localized" must be a boolean`);
     }
+    if (data['kind'] !== undefined && data['kind'] !== 'element' && data['kind'] !== 'library') {
+        throw new FurnaceError(`Furnace config: custom "${name}.kind" must be "element" or "library" when set`);
+    }
+    if (data['kind'] === 'library' && data['register']) {
+        throw new FurnaceError(`Furnace config: custom "${name}" has kind "library" but register: true — ` +
+            'a library exports no custom element; set register: false');
+    }
     if (data['composes'] !== undefined) {
         parseStringArray(data['composes'], `${name}.composes`);
     }
@@ -58,6 +65,9 @@ export function parseCustomConfig(data, name) {
             ? { composes: parseStringArray(data['composes'], `${name}.composes`) }
             : {}),
         ...(data['keyboardCovered'] === true ? { keyboardCovered: true } : {}),
+        // Explicit `kind: "element"` is the default; normalize it away so the
+        // stored config carries the field only when it changes behavior.
+        ...(data['kind'] === 'library' ? { kind: 'library' } : {}),
         ...(sharedFtl !== undefined ? { sharedFtl } : {}),
     };
 }