@hominis/fireforge 0.10.1 → 0.11.1

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

@@ -0,0 +1,220 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { join } from 'node:path';
+import { FurnaceError } from '../errors/furnace.js';
+import { toError } from '../utils/errors.js';
+import { warn } from '../utils/logger.js';
+import { FIREFORGE_DIR } from './config-paths.js';
+import { withFileLock } from './file-lock.js';
+import { loadFurnaceState, updateFurnaceState } from './furnace-config.js';
+import { restoreRollbackJournal } from './furnace-rollback.js';
+/** Sidecar lock filename used to serialize concurrent furnace mutations. */
+const FURNACE_LOCK_FILENAME = 'furnace.lock';
+const activeOperations = new Map();
+let nextOperationToken = 1;
+let signalRollbackInFlight = false;
+/**
+ * Returns true while a signal-driven rollback is in progress. The bin entry
+ * point uses this as a re-entrancy guard so a user mashing Ctrl+C cannot
+ * trigger a second rollback that races the first. Exposed for the bin shim
+ * (and the test suite); production callers should not need it.
+ */
+export function isSignalRollbackInFlight() {
+    return signalRollbackInFlight;
+}
+/**
+ * Rolls back every in-flight furnace operation and writes a pendingRepair
+ * marker for each. The bin entry point installs SIGINT/SIGTERM handlers that
+ * call this and then exit; calling it directly from inside the library would
+ * violate the "process.exit only in bin" invariant. The function is also
+ * exposed under this name so the test suite can exercise the teardown path
+ * without going through `process.emit` / `process.exit`.
+ */
+/** Maximum time (ms) the signal-driven rollback may take per operation. */
+const SIGNAL_ROLLBACK_TIMEOUT_MS = 15_000;
+/** Races a promise against a deadline, rejecting with a timeout error if the deadline expires. */
+function withTimeout(promise, ms, label) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`${label} timed out after ${ms}ms`));
+        }, ms);
+        promise.then((value) => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (error) => {
+            clearTimeout(timer);
+            reject(error instanceof Error ? error : new Error(String(error)));
+        });
+    });
+}
+/**
+ * Rolls back every in-flight furnace operation and writes a pendingRepair
+ * marker for each. Each cleanup callback and journal restore is bounded by a
+ * timeout so a stuck I/O operation cannot hang the process indefinitely.
+ */
+export async function rollbackActiveOperationsForSignal(signal) {
+    signalRollbackInFlight = true;
+    warn(`Received ${signal}; rolling back in-flight furnace mutations…`);
+    // Snapshot the active operations so we don't race with `runFurnaceMutation`
+    // clearing slots during normal completion.
+    const snapshot = [...activeOperations.values()];
+    for (const op of snapshot) {
+        // If the body completed successfully and is in its finally-block cleanup
+        // (deleting the token), skip rollback — the mutation committed cleanly.
+        if (op.completed)
+            continue;
+        const cleanupErrors = [];
+        // Run extra cleanup callbacks first (e.g. preview's cleanStories), so the
+        // engine is in its tidiest possible shape before the journal restore
+        // writes the original file contents back over the top.
+        for (const cleanup of op.cleanups) {
+            try {
+                await withTimeout(cleanup(), SIGNAL_ROLLBACK_TIMEOUT_MS, 'Cleanup callback');
+            }
+            catch (error) {
+                cleanupErrors.push(toError(error).message);
+            }
+        }
+        if (!op.journal) {
+            // The body had not yet handed us a journal — nothing to roll back. We
+            // still write a marker because the body may have started mutating the
+            // engine before reaching the registerJournal call.
+            const cleanupSuffix = cleanupErrors.length > 0 ? `; cleanup errors: ${cleanupErrors.join('; ')}` : '';
+            await persistPendingRepair(op.root, op.kind, `interrupted by ${signal} before any state was captured${cleanupSuffix}`).catch((error) => {
+                warn(`Could not persist pending-repair marker: ${toError(error).message}`);
+            });
+            continue;
+        }
+        let rollbackError;
+        try {
+            await withTimeout(restoreRollbackJournal(op.journal), SIGNAL_ROLLBACK_TIMEOUT_MS, 'Rollback journal restore');
+        }
+        catch (error) {
+            rollbackError = toError(error).message;
+        }
+        // A clean signal-driven rollback is not itself a repairable problem:
+        // preview/apply/deploy/remove were interrupted, but the engine was restored
+        // successfully and the next `doctor` run should remain green. Persist a
+        // pending-repair marker only when rollback was incomplete or uncertain.
+        if (rollbackError || cleanupErrors.length > 0) {
+            const reasonParts = [`interrupted by ${signal}`];
+            if (rollbackError) {
+                reasonParts.push(`automatic rollback failed: ${rollbackError}`);
+            }
+            else {
+                reasonParts.push('automatic rollback succeeded');
+            }
+            if (cleanupErrors.length > 0) {
+                reasonParts.push(`cleanup errors: ${cleanupErrors.join('; ')}`);
+            }
+            await persistPendingRepair(op.root, op.kind, reasonParts.join('; ')).catch((error) => {
+                warn(`Could not persist pending-repair marker: ${toError(error).message}`);
+            });
+        }
+    }
+}
+async function persistPendingRepair(root, operation, reason) {
+    await updateFurnaceState(root, (state) => ({
+        ...state,
+        pendingRepair: {
+            operation,
+            timestamp: new Date().toISOString(),
+            reason,
+        },
+    }));
+}
+/**
+ * Resolves the path of the lock directory used to serialize furnace mutations
+ * for a given project root. Exposed for tests; production callers should not
+ * touch this directly.
+ */
+export function getFurnaceLockPath(root) {
+    return join(root, FIREFORGE_DIR, FURNACE_LOCK_FILENAME);
+}
+/**
+ * Runs a furnace-mutating body under the apply-wide lock and registers it
+ * with the process-wide SIGINT/SIGTERM rollback pathway. The lock prevents
+ * two `furnace apply`/`deploy`/`create`/etc. runs from racing on the engine
+ * working copy; the CLI entrypoint's global signal handlers consult this
+ * registry and invoke rollback (writing a `pendingRepair` marker when needed)
+ * if the user hits Ctrl+C mid-run.
+ *
+ * Dry-run callers should pass `options.dryRun = true` so the wrapper skips
+ * the lock entirely (concurrent dry-runs are safe and shouldn't block each
+ * other).
+ *
+ * The body receives a {@link FurnaceOperationContext}; it must call
+ * `ctx.registerJournal(journal)` once it has constructed its rollback journal.
+ * Bodies that don't manage a journal directly (e.g. apply, which delegates to
+ * `applyAllComponents`) can pass an internal callback through.
+ */
+export async function runFurnaceMutation(root, kind, body, options = {}) {
+    if (options.dryRun) {
+        // Dry-run: no lock, no signal handler, no journal registration. The body
+        // is still given a no-op context so callers can use the same shape.
+        return body({
+            registerJournal: () => undefined,
+            registerCleanup: () => undefined,
+        });
+    }
+    // Pre-flight: refuse to mutate when a previous operation left the engine in
+    // a partially-rolled-back state. The user must run `fireforge doctor
+    // --repair-furnace` to reconcile before any new mutations can proceed.
+    if (!options.skipPendingRepairCheck) {
+        const state = await loadFurnaceState(root);
+        if (state.pendingRepair) {
+            throw new FurnaceError(`A previous "${state.pendingRepair.operation}" left the engine in an inconsistent state ` +
+                `(${state.pendingRepair.reason}). Run "fireforge doctor --repair-furnace" to reconcile ` +
+                'before running further furnace mutations.');
+        }
+    }
+    const token = nextOperationToken++;
+    const operation = { root, kind, cleanups: [] };
+    const lockPath = getFurnaceLockPath(root);
+    const lockOptions = {
+        ...(options.lockTimeoutMs !== undefined ? { timeoutMs: options.lockTimeoutMs } : {}),
+        onTimeoutMessage: `Timed out waiting for the furnace lock at ${lockPath}. ` +
+            'Another fireforge furnace command may be running. ' +
+            'If no other process is running, remove the stale lock directory and retry.',
+        onStaleLockMessage: (ageMs) => `Removing stale furnace lock (age: ${Math.round(ageMs / 1000)}s). ` +
+            'A previous fireforge process may have crashed.',
+    };
+    return withFileLock(lockPath, async () => {
+        activeOperations.set(token, operation);
+        try {
+            return await body({
+                registerJournal: (journal) => {
+                    operation.journal = journal;
+                },
+                registerCleanup: (cleanup) => {
+                    operation.cleanups.push(cleanup);
+                },
+            });
+        }
+        finally {
+            operation.completed = true;
+            activeOperations.delete(token);
+        }
+    }, lockOptions);
+}
+/**
+ * Persists an `apply-rollback` (or other operation-kind) `pendingRepair`
+ * marker on behalf of a caller that detected a rollback failure outside the
+ * signal-handler path (e.g. apply's own catch-around-restore). Exposed so
+ * `furnace-apply.ts` can write the marker without taking on a dependency on
+ * the lifecycle wrapper's internals.
+ */
+export async function recordFurnaceRollbackFailure(root, operation, reason) {
+    await persistPendingRepair(root, operation, reason);
+}
+/**
+ * Test-only helper: tears down the module-scoped state. Vitest workers may
+ * reuse the module across tests, so the test suite must call this between
+ * cases that exercise the signal pathway. Not exported from the package
+ * entry point.
+ */
+export function __resetFurnaceOperationStateForTests() {
+    activeOperations.clear();
+    nextOperationToken = 1;
+    signalRollbackInFlight = false;
+}
+//# sourceMappingURL=furnace-operation.js.map

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

@@ -0,0 +1,20 @@
+export interface RefreshFileResult {
+    fileName: string;
+    status: 'merged' | 'conflict' | 'unchanged' | 'new-file';
+    conflictMarkers?: number;
+}
+export interface RefreshResult {
+    files: RefreshFileResult[];
+    newBaseVersion: string;
+}
+/**
+ * Refreshes a single override file against the current engine HEAD.
+ *
+ * @param engineDir - Path to the engine git repository
+ * @param overridePath - Path to the current override file in the workspace
+ * @param engineRelPath - Engine-relative path for git show
+ * @param baseCommit - The git ref at which the override was originally created
+ * @param fileName - Display name for the file
+ * @returns Merge result with the updated content written to the override file
+ */
+export declare function refreshOverrideFile(engineDir: string, overridePath: string, engineRelPath: string, baseCommit: string, fileName: string, dryRun?: boolean, strategy?: 'ours' | 'theirs'): Promise<RefreshFileResult>;

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

@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Three-way merge logic for refreshing overrides against a newer Firefox baseline.
+ *
+ * When Firefox moves forward and an override's `baseVersion` drifts, the user
+ * needs a way to incorporate upstream changes into their override workspace
+ * without losing local modifications. This module uses `git merge-file` to
+ * perform a three-way merge between the old baseline, the current override,
+ * and the new upstream content.
+ */
+import { randomUUID } from 'node:crypto';
+import { unlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { FurnaceError } from '../errors/furnace.js';
+import { readText, writeText } from '../utils/fs.js';
+import { exec } from '../utils/process.js';
+import { ensureGit } from './git-base.js';
+import { getFileContentAtRef } from './git-file-ops.js';
+/**
+ * Performs a three-way merge on a single file.
+ *
+ * Uses `git merge-file` with:
+ *   - base: the original Firefox content at the override's recorded baseCommit
+ *   - ours: the current override workspace content (local modifications)
+ *   - theirs: the current Firefox content at HEAD
+ *
+ * @returns The merged content and the number of conflict markers (0 = clean merge)
+ */
+async function threeWayMergeFile(base, ours, theirs, label, strategy) {
+    await ensureGit();
+    // Write all three versions to temp files for git merge-file.
+    // Use crypto.randomUUID() for unique, unpredictable temp file names.
+    const id = randomUUID();
+    const tempBase = join(tmpdir(), `fireforge-merge-base-${id}`);
+    const tempOurs = join(tmpdir(), `fireforge-merge-ours-${id}`);
+    const tempTheirs = join(tmpdir(), `fireforge-merge-theirs-${id}`);
+    try {
+        await writeText(tempBase, base);
+        await writeText(tempOurs, ours);
+        await writeText(tempTheirs, theirs);
+        // git merge-file writes the result to the first file (ours) in-place.
+        // Exit code 0 = clean merge, >0 = number of conflicts, <0 = error.
+        const mergeArgs = [
+            'merge-file',
+            ...(strategy ? [`--${strategy}`] : []),
+            '-L',
+            label.ours,
+            '-L',
+            label.base,
+            '-L',
+            label.theirs,
+            tempOurs,
+            tempBase,
+            tempTheirs,
+        ];
+        const result = await exec('git', mergeArgs);
+        const merged = await readText(tempOurs);
+        const conflicts = result.exitCode > 0 ? result.exitCode : 0;
+        if (result.exitCode < 0) {
+            throw new FurnaceError(`git merge-file failed: ${result.stderr}`);
+        }
+        return { merged, conflicts };
+    }
+    finally {
+        // Clean up temp files (best-effort)
+        await Promise.allSettled([unlink(tempBase), unlink(tempOurs), unlink(tempTheirs)]);
+    }
+}
+/**
+ * Refreshes a single override file against the current engine HEAD.
+ *
+ * @param engineDir - Path to the engine git repository
+ * @param overridePath - Path to the current override file in the workspace
+ * @param engineRelPath - Engine-relative path for git show
+ * @param baseCommit - The git ref at which the override was originally created
+ * @param fileName - Display name for the file
+ * @returns Merge result with the updated content written to the override file
+ */
+export async function refreshOverrideFile(engineDir, overridePath, engineRelPath, baseCommit, fileName, dryRun, strategy) {
+    // Read the three versions
+    const oursContent = await readText(overridePath);
+    const baseContent = await getFileContentAtRef(engineDir, engineRelPath, baseCommit);
+    if (baseContent === null) {
+        // File didn't exist at baseCommit — this is a new file introduced by the override
+        return { fileName, status: 'new-file' };
+    }
+    const theirsContent = await getFileContentAtRef(engineDir, engineRelPath, 'HEAD');
+    if (theirsContent === null) {
+        // File was removed upstream — no merge needed, keep the override as-is
+        return { fileName, status: 'unchanged' };
+    }
+    // If upstream hasn't changed, nothing to merge
+    if (baseContent === theirsContent) {
+        return { fileName, status: 'unchanged' };
+    }
+    // If our override matches the base (no local changes), just take theirs
+    if (oursContent === baseContent) {
+        if (!dryRun) {
+            await writeText(overridePath, theirsContent);
+        }
+        return { fileName, status: 'merged' };
+    }
+    // Three-way merge
+    const { merged, conflicts } = await threeWayMergeFile(baseContent, oursContent, theirsContent, {
+        ours: `components/overrides/${fileName} (your changes)`,
+        base: `Firefox ${baseCommit.slice(0, 8)} (original)`,
+        theirs: `Firefox HEAD (upstream)`,
+    }, strategy);
+    if (!dryRun) {
+        await writeText(overridePath, merged);
+    }
+    if (conflicts > 0) {
+        return { fileName, status: 'conflict', conflictMarkers: conflicts };
+    }
+    return { fileName, status: 'merged' };
+}
+//# sourceMappingURL=furnace-refresh.js.map

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

@@ -22,3 +22,8 @@ export { CUSTOM_ELEMENTS_JS, JAR_MN } from './furnace-constants.js';
  * @param modulePath - chrome:// URI for the module
  */
 export declare function addCustomElementRegistration(engineDir: string, tagName: string, modulePath: string): Promise<void>;
+/**
+ * Validates that a custom element registration *would* succeed without
+ * writing anything. Used by dry-run to surface registration errors early.
+ */
+export declare function validateCustomElementRegistration(engineDir: string, tagName: string, modulePath: string): Promise<void>;

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

@@ -8,6 +8,7 @@ import MagicString from 'magic-string';
 import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
+import { verbose, warn } from '../utils/logger.js';
 import { detectIndent, getNodeSource, parseScript, walkAST, } from './ast-utils.js';
 import { CUSTOM_ELEMENTS_JS } from './furnace-constants.js';
 import { validateRegistrationPlacement, validateTagName } from './furnace-registration-validate.js';
@@ -171,6 +172,60 @@ function addRegistrationAST(content, tagName, modulePath, isESModule) {
     }
     return ms.toString();
 }
+/**
+ * Regex-based fallback for inserting a registration entry when the AST parser
+ * fails. Finds the last existing `["tag", "path"],` line in the appropriate
+ * block and inserts the new entry after it in alphabetical order.
+ *
+ * This is intentionally less precise than the AST approach — it does not
+ * validate indentation or multi-line format — but it is robust against
+ * upstream syntax changes that break the parser.
+ */
+function addRegistrationRegexFallback(content, tagName, modulePath, isESModule) {
+    // Find all registration entries: ["tag", "path"],
+    const entryPattern = /^(\s*)\["([^"]+)",\s*"[^"]+"\],?\s*$/gm;
+    let lastMatch = null;
+    let insertAfterMatch = null;
+    const allMatches = [];
+    let match;
+    // For ESM modules, only consider entries inside a DOMContentLoaded block.
+    // For non-ESM, consider entries outside DOMContentLoaded.
+    const dclStart = content.search(/document\.addEventListener\s*\(\s*["']DOMContentLoaded["']/);
+    const dclBlockStart = dclStart >= 0 ? content.indexOf('{', dclStart) : -1;
+    while ((match = entryPattern.exec(content)) !== null) {
+        const isInDCL = dclBlockStart >= 0 && match.index > dclBlockStart;
+        if (isESModule ? isInDCL : !isInDCL) {
+            allMatches.push(match);
+        }
+    }
+    // Find alphabetical insertion point
+    for (const m of allMatches) {
+        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- capture group [2] always present when regex matches
+        const existingTag = m[2];
+        if (existingTag < tagName) {
+            insertAfterMatch = m;
+        }
+        lastMatch = m;
+    }
+    // If we found no entries in the target block, give up
+    if (!lastMatch) {
+        throw new FurnaceError(`Regex fallback could not find any registration entries in the ${isESModule ? 'DOMContentLoaded' : 'non-DOMContentLoaded'} block of ${CUSTOM_ELEMENTS_JS}.`, tagName);
+    }
+    const indent = lastMatch[1] ?? '    ';
+    const newEntry = `${indent}["${tagName}", "${modulePath}"],`;
+    if (insertAfterMatch) {
+        // Insert after the last entry that sorts before tagName
+        const insertPos = insertAfterMatch.index + insertAfterMatch[0].length;
+        return content.slice(0, insertPos) + '\n' + newEntry + content.slice(insertPos);
+    }
+    // Insert before the first entry (tagName sorts before all existing)
+    const firstMatch = allMatches[0];
+    if (!firstMatch) {
+        throw new FurnaceError(`Regex fallback found no entries in the target block of ${CUSTOM_ELEMENTS_JS}.`, tagName);
+    }
+    const insertPos = firstMatch.index;
+    return content.slice(0, insertPos) + newEntry + '\n' + content.slice(insertPos);
+}
 /**
  * Adds a custom element registration entry to customElements.js.
  *
@@ -195,24 +250,99 @@ export async function addCustomElementRegistration(engineDir, tagName, modulePat
     }
     const content = await readText(filePath);
     // Idempotency: already registered (standalone block or array entry).
+    // Check both double-quote and single-quote variants — upstream Firefox
+    // sources may use either style.
     if (content.includes(`setElementCreationCallback("${tagName}"`) ||
+        content.includes(`setElementCreationCallback('${tagName}'`) ||
         content.includes(`["${tagName}",`) ||
-        new RegExp(`^\\s*"${tagName}",\\s*$`, 'm').test(content)) {
+        content.includes(`['${tagName}',`) ||
+        new RegExp(`^\\s*["']${tagName}["'],\\s*$`, 'm').test(content)) {
         return;
     }
+    // Validate upfront — tag name errors must not fall through to the regex fallback.
+    validateTagName(tagName);
     const isESModule = modulePath.endsWith('.mjs');
+    // Cheap pre-flight: the AST walker assumes the file contains at least one
+    // destructuring `for (... of [...])` loop with an array literal on the
+    // right-hand side, and (for ESM tags) at least one such loop inside a
+    // `document.addEventListener("DOMContentLoaded", ...)` block. If either
+    // assumption is violated the AST path errors with a confusing
+    // "Could not find DOMContentLoaded block" message — fail fast here with
+    // actionable guidance instead.
+    if (!/for\s*\(\s*(?:let|const|var)\s*\[/.test(content)) {
+        throw new FurnaceError(`${CUSTOM_ELEMENTS_JS} does not contain a recognizable registration loop; refusing to mutate. ` +
+            'Run "fireforge reset --force" to restore the engine, or inspect the file manually.', tagName);
+    }
+    if (isESModule && !/document\.addEventListener\s*\(\s*["']DOMContentLoaded["']/.test(content)) {
+        throw new FurnaceError(`${CUSTOM_ELEMENTS_JS} has no DOMContentLoaded block; cannot register ESM element ${tagName}. ` +
+            'The file may be corrupt — run "fireforge reset --force" to restore.', tagName);
+    }
     let nextContent;
     try {
         nextContent = addRegistrationAST(content, tagName, modulePath, isESModule);
     }
     catch (error) {
         if (error instanceof FurnaceError) {
-            throw error;
+            // AST structural errors (missing DOMContentLoaded block, etc.) — try regex fallback
+            warn(`AST-based registration failed for ${tagName}: ${error.message}. ` +
+                'Falling back to regex-based insertion. Please report this so the AST parser can be updated.');
+            try {
+                nextContent = addRegistrationRegexFallback(content, tagName, modulePath, isESModule);
+                verbose(`Regex fallback succeeded for ${tagName}. The registration may be less precise than the AST approach.`);
+            }
+            catch {
+                // If regex fallback also fails, throw the original AST error
+                throw error;
+            }
+        }
+        else {
+            const parserError = toError(error);
+            warn(`AST parser threw an unexpected error for ${tagName}: ${parserError.message}. ` +
+                'Falling back to regex-based insertion.');
+            try {
+                nextContent = addRegistrationRegexFallback(content, tagName, modulePath, isESModule);
+                verbose(`Regex fallback succeeded for ${tagName}. The registration may be less precise than the AST approach.`);
+            }
+            catch {
+                throw new FurnaceError(`Failed to update ${CUSTOM_ELEMENTS_JS} using both AST and regex fallback: ${parserError.message}`, tagName, parserError);
+            }
         }
-        const parserError = toError(error);
-        throw new FurnaceError(`Failed to update ${CUSTOM_ELEMENTS_JS} using AST registration parsing: ${parserError.message}`, tagName, parserError);
     }
     validateRegistrationPlacement(nextContent, tagName, isESModule);
     await writeText(filePath, nextContent);
 }
+/**
+ * Validates that a custom element registration *would* succeed without
+ * writing anything. Used by dry-run to surface registration errors early.
+ */
+export async function validateCustomElementRegistration(engineDir, tagName, modulePath) {
+    const filePath = join(engineDir, CUSTOM_ELEMENTS_JS);
+    if (!(await pathExists(filePath))) {
+        throw new FurnaceError('customElements.js not found in engine', tagName);
+    }
+    const content = await readText(filePath);
+    if (content.includes(`setElementCreationCallback("${tagName}"`) ||
+        content.includes(`setElementCreationCallback('${tagName}'`) ||
+        content.includes(`["${tagName}",`) ||
+        content.includes(`['${tagName}',`) ||
+        new RegExp(`^\\s*["']${tagName}["'],\\s*$`, 'm').test(content)) {
+        return;
+    }
+    const isESModule = modulePath.endsWith('.mjs');
+    if (!/for\s*\(\s*(?:let|const|var)\s*\[/.test(content)) {
+        throw new FurnaceError(`${CUSTOM_ELEMENTS_JS} does not contain a recognizable registration loop; refusing to mutate. ` +
+            'Run "fireforge reset --force" to restore the engine, or inspect the file manually.', tagName);
+    }
+    if (isESModule && !/document\.addEventListener\s*\(\s*["']DOMContentLoaded["']/.test(content)) {
+        throw new FurnaceError(`${CUSTOM_ELEMENTS_JS} has no DOMContentLoaded block; cannot register ESM element ${tagName}. ` +
+            'The file may be corrupt — run "fireforge reset --force" to restore.', tagName);
+    }
+    try {
+        addRegistrationAST(content, tagName, modulePath, isESModule);
+    }
+    catch {
+        // Validation only — if AST fails, try regex to see if the entry could be placed
+        addRegistrationRegexFallback(content, tagName, modulePath, isESModule);
+    }
+}
 //# sourceMappingURL=furnace-registration-ast.js.map

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

@@ -1,12 +1,34 @@
 /**
  * Removal of custom element registrations from customElements.js.
- * Supports three removal strategies: standalone callback, single-line array, multi-line array.
+ *
+ * Uses the same AST parser as the add path (`furnace-registration-ast.ts`) to
+ * locate and delete registration entries. The earlier implementation walked
+ * the file line-by-line with a 20-line scan bound for bracket matching, which
+ * only worked against Firefox's stock formatting and silently failed on any
+ * hand-reformatted customElements.js. AST-based bracket matching is format-
+ * agnostic by construction.
+ *
+ * Contract:
+ * - Idempotent: if the tag is not registered, the file is left unchanged.
+ * - Non-destructive on parse failure: if customElements.js cannot be parsed,
+ *   the file is left untouched rather than fall through to a line-based
+ *   heuristic that could delete the wrong range.
+ * - Two registration shapes are recognised:
+ *     (A) Standalone statement:
+ *           customElements.setElementCreationCallback("tag", ...);
+ *     (B) Entry inside a `for (... of [ ... ])` registration array:
+ *           ["tag", "chrome://..."]
+ *   Both are deleted together with any trailing comma and newline so the
+ *   resulting file is still valid JavaScript.
  */
 /**
  * Removes a custom element registration from customElements.js.
  *
- * This operation is idempotent — if the tag is not registered or the file does
- * not exist, nothing happens.
+ * This operation is idempotent — if the tag is not registered or the file
+ * does not exist, nothing happens. If the file exists but cannot be parsed,
+ * the file is left unchanged rather than fall back to a line-based
+ * heuristic; a corrupted customElements.js is a doctor problem, not
+ * something `furnace remove` should "helpfully" edit around.
  *
  * @param engineDir - Path to the Firefox engine source root
  * @param tagName - Custom element tag name to remove