@hominis/fireforge 0.55.0 → 0.60.0

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

@@ -1,260 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Removal of custom element registrations from customElements.js.
- *
- * Uses the same AST parser as the add path (`furnace-registration-ast.ts`) to
- * locate and delete registration entries. A line-by-line scan with a bounded
- * bracket match only works against Firefox's stock formatting and fails
- * silently on a hand-reformatted customElements.js. AST-based bracket
- * matching does not depend on the file's formatting.
- *
- * 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 falling 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, or an
- *         array declared by name and iterated with `for (... of NAME)`:
- *           ["tag", "chrome://..."]
- *   Both are deleted together with any trailing comma and newline so the
- *   resulting file is still valid JavaScript.
- */
-import { join } from 'node:path';
-import MagicString from 'magic-string';
-import { pathExists, readText, writeText } from '../utils/fs.js';
-import { asEstree, parseScript, walkAST } from './ast-utils.js';
-import { CUSTOM_ELEMENTS_JS } from './furnace-constants.js';
-/**
- * Expands `[start, end)` to consume a trailing comma and any whitespace up
- * to (and including) the next newline. This keeps the surrounding file
- * layout stable: deleting a list entry should not leave a dangling comma
- * behind, and deleting an expression statement should not leave a blank
- * line where the statement stood.
- */
-function expandRemovalRange(content, start, end) {
-    let expandedEnd = end;
-    // Walk past horizontal whitespace so a trailing comma is reachable even
-    // when the source has `[...]  ,` or similar.
-    while (expandedEnd < content.length &&
-        (content[expandedEnd] === ' ' || content[expandedEnd] === '\t')) {
-        expandedEnd++;
-    }
-    if (content[expandedEnd] === ',') {
-        expandedEnd++;
-    }
-    else if (content[expandedEnd] === ';') {
-        expandedEnd++;
-    }
-    // Consume a trailing inline comment up to end-of-line so we do not leave
-    // the comment marooned on its own line. A leading inline comment is left
-    // alone, because it may belong to the next entry.
-    while (expandedEnd < content.length &&
-        (content[expandedEnd] === ' ' || content[expandedEnd] === '\t')) {
-        expandedEnd++;
-    }
-    if (content[expandedEnd] === '/' && content[expandedEnd + 1] === '/') {
-        while (expandedEnd < content.length && content[expandedEnd] !== '\n') {
-            expandedEnd++;
-        }
-    }
-    if (content[expandedEnd] === '\n') {
-        expandedEnd++;
-    }
-    // Also consume leading whitespace on the line the removal starts on, so
-    // indentation does not survive as a blank-looking line.
-    let expandedStart = start;
-    while (expandedStart > 0) {
-        const prev = content[expandedStart - 1];
-        if (prev === ' ' || prev === '\t') {
-            expandedStart--;
-            continue;
-        }
-        break;
-    }
-    // If the removal now starts at the beginning of a line and the preceding
-    // line is blank, consume that blank line as well. This matches the older
-    // line-based implementation's "eat one leading blank" behaviour so that
-    // removing a callback block from between two blank-line-separated
-    // sections does not leave a doubled-up gap behind.
-    if (expandedStart > 0 &&
-        content[expandedStart - 1] === '\n' &&
-        expandedStart >= 2 &&
-        content[expandedStart - 2] === '\n') {
-        expandedStart--;
-    }
-    return { start: expandedStart, end: expandedEnd };
-}
-/**
- * Returns true if `node` represents a `[tag, module]` entry inside a
- * registration array, i.e. an `ArrayExpression` whose first element is a
- * string literal equal to `tagName`. Callers still have to verify the
- * parent is the outer registration array so we do not accidentally delete
- * an arbitrary user-owned `["moz-card", ...]` literal elsewhere in the file.
- */
-function isEntryArrayFor(node, tagName) {
-    if (!node || node.type !== 'ArrayExpression')
-        return false;
-    const [first] = node.elements;
-    if (!first || first.type !== 'Literal')
-        return false;
-    const literal = first;
-    return literal.value === tagName;
-}
-/**
- * Returns true if `call` is `customElements.setElementCreationCallback(tagName, ...)`
- * (optionally prefixed with `lazy.` or similar member chain). We only match
- * the property name rather than the full callee chain so unusual-but-valid
- * receivers (`lazy.customElements…`, `this.customElements…`) still count.
- */
-function isStandaloneCallbackCallFor(call, tagName) {
-    if (call.callee.type !== 'MemberExpression')
-        return false;
-    const prop = call.callee.property;
-    if (prop.type !== 'Identifier' || prop.name !== 'setElementCreationCallback')
-        return false;
-    const [tagArg] = call.arguments;
-    if (!tagArg || tagArg.type !== 'Literal')
-        return false;
-    return tagArg.value === tagName;
-}
-/**
- * Names of the identifiers used as the right-hand side of a `for (... of X)`
- * loop. A registration list declared as `const ELEMENTS = [...]` and
- * iterated by name is a registration array just like an inline literal: the
- * add path (`addCustomElementRegistration`) has always written into
- * it, so the remove and rename paths must find entries there too or a
- * rename leaves the old entry behind.
- */
-function collectForOfIdentifiers(ast) {
-    const names = new Set();
-    walkAST(ast, {
-        enter(node) {
-            if (node.type !== 'ForOfStatement')
-                return;
-            const right = asEstree(node).right;
-            if (right.type === 'Identifier')
-                names.add(right.name);
-        },
-    });
-    return names;
-}
-/** True when `parent`/`grandparent` make an array a registration list. */
-function isRegistrationList(parent, grandparent, forOfIdentifiers) {
-    if (parent?.type !== 'ArrayExpression' || !grandparent)
-        return false;
-    if (grandparent.type === 'ForOfStatement')
-        return true;
-    if (grandparent.type !== 'VariableDeclarator')
-        return false;
-    const id = asEstree(grandparent).id;
-    return id.type === 'Identifier' && forOfIdentifiers.has(id.name);
-}
-/**
- * Walks the AST and returns the source range of every registration of
- * `tagName`: each `[tag, module]` entry of a registration list, and each
- * statement enclosing a `setElementCreationCallback(tag, ...)` call.
- * Ancestor tracking lets us tell an "entry" array from a random
- * `["moz-foo", ...]` literal (only direct children of a registration list
- * are entries). Shared by removal and the in-place rename.
- *
- * @param ast - Parsed customElements.js
- * @param tagName - Tag whose registrations to find
- * @returns Unexpanded `[start, end)` ranges, in source order
- */
-export function findRegistrationRanges(ast, tagName) {
-    const ranges = [];
-    const ancestors = [];
-    const forOfIdentifiers = collectForOfIdentifiers(ast);
-    walkAST(ast, {
-        enter(node) {
-            // Entry array: [tag, module] inside a registration list, either the
-            // for-of array literal itself or an array declared by name and
-            // iterated by a for-of loop.
-            if (node.type === 'ArrayExpression' && isEntryArrayFor(node, tagName)) {
-                const parent = ancestors[ancestors.length - 1];
-                const grandparent = ancestors[ancestors.length - 2];
-                if (isRegistrationList(parent, grandparent, forOfIdentifiers)) {
-                    ranges.push({ start: node.start, end: node.end });
-                }
-            }
-            // Standalone call: customElements.setElementCreationCallback(tag, …)
-            if (node.type === 'CallExpression') {
-                const call = asEstree(node);
-                if (isStandaloneCallbackCallFor(call, tagName)) {
-                    // Find the enclosing statement so we can delete `call(...);` as
-                    // a unit, not just the call expression body.
-                    let enclosing = null;
-                    for (let i = ancestors.length - 1; i >= 0; i--) {
-                        const ancestor = ancestors[i];
-                        if (!ancestor)
-                            continue;
-                        if (ancestor.type === 'ExpressionStatement' ||
-                            ancestor.type === 'VariableDeclaration') {
-                            enclosing = asEstree(ancestor);
-                            break;
-                        }
-                    }
-                    const target = enclosing ?? call;
-                    ranges.push({ start: target.start, end: target.end });
-                }
-            }
-            ancestors.push(node);
-        },
-        leave() {
-            ancestors.pop();
-        },
-    });
-    return ranges;
-}
-/**
- * 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. 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
- */
-export async function removeCustomElementRegistration(engineDir, tagName) {
-    const filePath = join(engineDir, CUSTOM_ELEMENTS_JS);
-    if (!(await pathExists(filePath))) {
-        return;
-    }
-    const content = await readText(filePath);
-    // Cheap pre-check: if the tag literal never appears in the file there is
-    // nothing to remove and we avoid the cost of parsing a large file on the
-    // hot path of a no-op remove.
-    if (!content.includes(`"${tagName}"`) && !content.includes(`'${tagName}'`)) {
-        return;
-    }
-    let ast;
-    try {
-        ast = parseScript(content);
-    }
-    catch {
-        // An unparsable customElements.js is left untouched on purpose: this
-        // function only removes registrations, and editing a file it cannot parse
-        // risks corrupting it. The caller's regex fallback handles the retry.
-        return;
-    }
-    const ranges = findRegistrationRanges(ast, tagName).map((range) => expandRemovalRange(content, range.start, range.end));
-    if (ranges.length === 0) {
-        return;
-    }
-    // Apply all removals in a single MagicString pass. MagicString tracks
-    // original offsets so the ranges do not need to be sorted or reversed.
-    const ms = new MagicString(content);
-    for (const range of ranges) {
-        ms.remove(range.start, range.end);
-    }
-    const next = ms.toString();
-    if (next !== content) {
-        await writeText(filePath, next);
-    }
-}

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

@@ -1,26 +0,0 @@
-/**
- * In-place rename of a custom element registration in customElements.js.
- *
- * Removing the old entry and adding a new one would, on a registration
- * list the remove path cannot see, leave the old entry beside the new one,
- * and the new entry would lack the project marker every sibling line
- * carries (`// <MARKER>:`), so the next lint would flag it as an unmarked
- * engine edit. Rewriting the tag and module
- * literals inside the existing entry keeps the entry's position, layout and
- * trailing marker comments exactly as they were.
- */
-/**
- * Renames `oldTag`'s registration in customElements.js in place.
- *
- * Returns false, writing nothing, when the file is missing or unparsable,
- * holds no registration for `oldTag`, or already registers `newTag` (an
- * in-place rewrite would then register it twice); the caller then falls
- * back to remove-and-add, whose add is idempotent. Never parses with a line-based heuristic: an unparsable
- * file is a doctor problem, not something a rename edits around.
- *
- * @param engineDir - Path to the Firefox engine source root
- * @param oldTag - Tag being renamed away from
- * @param newTag - Tag being renamed to
- * @returns True when at least one registration was rewritten
- */
-export declare function renameCustomElementRegistration(engineDir: string, oldTag: string, newTag: string): Promise<boolean>;

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

@@ -1,77 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * In-place rename of a custom element registration in customElements.js.
- *
- * Removing the old entry and adding a new one would, on a registration
- * list the remove path cannot see, leave the old entry beside the new one,
- * and the new entry would lack the project marker every sibling line
- * carries (`// <MARKER>:`), so the next lint would flag it as an unmarked
- * engine edit. Rewriting the tag and module
- * literals inside the existing entry keeps the entry's position, layout and
- * trailing marker comments exactly as they were.
- */
-import { join } from 'node:path';
-import MagicString from 'magic-string';
-import { pathExists, readText, writeText } from '../utils/fs.js';
-import { escapeRegex } from '../utils/regex.js';
-import { parseScript } from './ast-utils.js';
-import { CUSTOM_ELEMENTS_JS } from './furnace-constants.js';
-import { isTagAlreadyRegistered } from './furnace-registration-ast.js';
-import { findRegistrationRanges } from './furnace-registration-remove.js';
-/**
- * Rewrites the old tag's literals inside one registration's source: the
- * quoted tag itself and the module file name in its chrome:// URI.
- * Everything else in the range (indentation, line breaks, comments between
- * elements) is left byte-for-byte.
- */
-function renameRegistrationSource(source, oldTag, newTag) {
-    const escaped = escapeRegex(oldTag);
-    return source
-        .replace(new RegExp(`(["'])${escaped}\\1`, 'g'), `$1${newTag}$1`)
-        .replace(new RegExp(`/${escaped}(\\.m?js["'])`, 'g'), `/${newTag}$1`);
-}
-/**
- * Renames `oldTag`'s registration in customElements.js in place.
- *
- * Returns false, writing nothing, when the file is missing or unparsable,
- * holds no registration for `oldTag`, or already registers `newTag` (an
- * in-place rewrite would then register it twice); the caller then falls
- * back to remove-and-add, whose add is idempotent. Never parses with a line-based heuristic: an unparsable
- * file is a doctor problem, not something a rename edits around.
- *
- * @param engineDir - Path to the Firefox engine source root
- * @param oldTag - Tag being renamed away from
- * @param newTag - Tag being renamed to
- * @returns True when at least one registration was rewritten
- */
-export async function renameCustomElementRegistration(engineDir, oldTag, newTag) {
-    const filePath = join(engineDir, CUSTOM_ELEMENTS_JS);
-    if (!(await pathExists(filePath)))
-        return false;
-    const content = await readText(filePath);
-    if (!content.includes(`"${oldTag}"`) && !content.includes(`'${oldTag}'`))
-        return false;
-    if (isTagAlreadyRegistered(content, newTag))
-        return false;
-    let ranges;
-    try {
-        ranges = findRegistrationRanges(parseScript(content), oldTag);
-    }
-    catch {
-        return false;
-    }
-    if (ranges.length === 0)
-        return false;
-    const ms = new MagicString(content);
-    for (const range of ranges) {
-        const source = content.slice(range.start, range.end);
-        const renamed = renameRegistrationSource(source, oldTag, newTag);
-        if (renamed !== source)
-            ms.overwrite(range.start, range.end, renamed);
-    }
-    const next = ms.toString();
-    if (next === content)
-        return false;
-    await writeText(filePath, next);
-    return true;
-}

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

@@ -1,53 +0,0 @@
-/**
- * Shared validation for furnace custom element registration placement.
- * Shared by the AST registration editor and the registration validator to
- * avoid duplicating logic.
- */
-/**
- * Regex for valid custom element tag names. A valid name is lowercase, starts
- * with a letter, and contains one or more hyphen-separated groups where each
- * group is a non-empty alphanumeric run. Consecutive hyphens and trailing
- * hyphens are both rejected. Kept in sync with the HTML custom element spec
- * requirement that a name contain at least one hyphen.
- *
- * A single shared constant is used by every furnace authoring path
- * (`furnace create`, `furnace override`, and the AST registration helper) so
- * that a name accepted by one command cannot be rejected by another.
- */
-export declare const CUSTOM_ELEMENT_TAG_PATTERN: RegExp;
-/** Human-readable description of the tag-name rules, for CLI error messages. */
-export declare const CUSTOM_ELEMENT_TAG_RULES = "must be lowercase, start with a letter, and use hyphens to separate non-empty alphanumeric groups (e.g., \"my-widget\")";
-/**
- * Validates that a tag name conforms to custom element naming requirements.
- * @throws FurnaceError if the tag name is invalid
- */
-export declare function validateTagName(tagName: string): void;
-/**
- * Returns why `tagName` is invalid, or `undefined` when it is fine.
- *
- * The message-returning half of {@link validateTagName}, for callers that
- * must not throw, specifically clack `validate` callbacks, which expect a
- * returned string and re-prompt on it. Passing the throwing form to one
- * makes an invalid tag name escape clack's validation loop as a
- * `FurnaceError`, killing the prompt instead of showing the rule inline.
- *
- * @param tagName - Candidate custom element tag name
- * @returns The rule violation, or undefined when the name is valid
- */
-export declare function describeTagNameProblem(tagName: string): string | undefined;
-/**
- * Validates that a registration entry landed in the correct block
- * (Pattern A = loadSubScript, Pattern B = DOMContentLoaded/importESModule).
- *
- * @param result - The full file content after insertion
- * @param tagName - The tag that was inserted
- * @param isESModule - Whether the module uses ESM (Pattern B) or not (Pattern A)
- */
-export declare function validateRegistrationPlacement(result: string, tagName: string, isESModule: boolean): void;
-/**
- * Returns whether a tag appears in the correct customElements.js placement.
- * ESM entries may either appear textually inside/after DOMContentLoaded or
- * inside an array declared before DOMContentLoaded and consumed by a for-of
- * loop inside the listener, as Firefox 152 Beta does for acornElements.
- */
-export declare function isTagInCorrectCustomElementsPlacement(content: string, tagName: string, isESModule: boolean): boolean;

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

@@ -1,110 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Shared validation for furnace custom element registration placement.
- * Shared by the AST registration editor and the registration validator to
- * avoid duplicating logic.
- */
-import { FurnaceError } from '../errors/furnace.js';
-import { escapeRegex, stripJsComments } from '../utils/regex.js';
-/**
- * Regex for valid custom element tag names. A valid name is lowercase, starts
- * with a letter, and contains one or more hyphen-separated groups where each
- * group is a non-empty alphanumeric run. Consecutive hyphens and trailing
- * hyphens are both rejected. Kept in sync with the HTML custom element spec
- * requirement that a name contain at least one hyphen.
- *
- * A single shared constant is used by every furnace authoring path
- * (`furnace create`, `furnace override`, and the AST registration helper) so
- * that a name accepted by one command cannot be rejected by another.
- */
-export const CUSTOM_ELEMENT_TAG_PATTERN = /^[a-z][a-z0-9]*(-[a-z0-9]+)+$/;
-/** Human-readable description of the tag-name rules, for CLI error messages. */
-export const CUSTOM_ELEMENT_TAG_RULES = 'must be lowercase, start with a letter, and use hyphens to separate non-empty alphanumeric groups (e.g., "my-widget")';
-/**
- * Validates that a tag name conforms to custom element naming requirements.
- * @throws FurnaceError if the tag name is invalid
- */
-export function validateTagName(tagName) {
-    const problem = describeTagNameProblem(tagName);
-    if (problem !== undefined) {
-        throw new FurnaceError(problem, tagName);
-    }
-}
-/**
- * Returns why `tagName` is invalid, or `undefined` when it is fine.
- *
- * The message-returning half of {@link validateTagName}, for callers that
- * must not throw, specifically clack `validate` callbacks, which expect a
- * returned string and re-prompt on it. Passing the throwing form to one
- * makes an invalid tag name escape clack's validation loop as a
- * `FurnaceError`, killing the prompt instead of showing the rule inline.
- *
- * @param tagName - Candidate custom element tag name
- * @returns The rule violation, or undefined when the name is valid
- */
-export function describeTagNameProblem(tagName) {
-    if (!CUSTOM_ELEMENT_TAG_PATTERN.test(tagName)) {
-        return `Invalid tag name "${tagName}": ${CUSTOM_ELEMENT_TAG_RULES}`;
-    }
-    return undefined;
-}
-/**
- * Validates that a registration entry landed in the correct block
- * (Pattern A = loadSubScript, Pattern B = DOMContentLoaded/importESModule).
- *
- * @param result - The full file content after insertion
- * @param tagName - The tag that was inserted
- * @param isESModule - Whether the module uses ESM (Pattern B) or not (Pattern A)
- */
-export function validateRegistrationPlacement(result, tagName, isESModule) {
-    const insertedPos = result.lastIndexOf(`"${tagName}"`);
-    if (insertedPos === -1)
-        return;
-    if (!isTagInCorrectCustomElementsPlacement(result, tagName, isESModule)) {
-        if (!isESModule) {
-            throw new FurnaceError(`${tagName} was registered in the DOMContentLoaded/importESModule block (Pattern B) instead of the loadSubScript block (Pattern A). This will cause the component to fail at runtime. The customElements.js file structure may have changed upstream — manual intervention required.`, tagName);
-        }
-        throw new FurnaceError(`${tagName} was registered in the loadSubScript block (Pattern A) instead of the DOMContentLoaded/importESModule block (Pattern B). This will cause the component to fail at runtime. The customElements.js file structure may have changed upstream — manual intervention required.`, tagName);
-    }
-}
-/**
- * Returns whether a tag appears in the correct customElements.js placement.
- * ESM entries may either appear textually inside/after DOMContentLoaded or
- * inside an array declared before DOMContentLoaded and consumed by a for-of
- * loop inside the listener, as Firefox 152 Beta does for acornElements.
- */
-export function isTagInCorrectCustomElementsPlacement(content, tagName, isESModule) {
-    const stripped = stripJsComments(content);
-    const tagPattern = new RegExp(`["']${escapeRegex(tagName)}["']`);
-    const dclMatch = /document\.addEventListener\(\s*["']DOMContentLoaded["']/.exec(stripped);
-    if (!dclMatch) {
-        return !isESModule && tagPattern.test(stripped);
-    }
-    const beforeDcl = stripped.slice(0, dclMatch.index);
-    const afterDcl = stripped.slice(dclMatch.index);
-    const tagBeforeDcl = tagPattern.test(beforeDcl);
-    const tagAfterDcl = tagPattern.test(afterDcl);
-    if (!isESModule) {
-        return tagBeforeDcl && !tagAfterDcl;
-    }
-    return (tagAfterDcl || isTagInArrayConsumedInsideDOMContentLoaded(stripped, dclMatch.index, tagName));
-}
-function isTagInArrayConsumedInsideDOMContentLoaded(content, domContentLoadedIdx, tagName) {
-    const beforeDcl = content.slice(0, domContentLoadedIdx);
-    const afterDcl = content.slice(domContentLoadedIdx);
-    const consumedArrays = new Set();
-    const forOfPattern = /for\s*\(\s*(?:let|const|var)\s*\[[^)]*\]\s+of\s+([A-Za-z_$][\w$]*)\s*\)/g;
-    let match;
-    while ((match = forOfPattern.exec(afterDcl)) !== null) {
-        if (match[1])
-            consumedArrays.add(match[1]);
-    }
-    for (const arrayName of consumedArrays) {
-        const declarationPattern = new RegExp(`(?:const|let|var)\\s+${escapeRegex(arrayName)}\\s*=\\s*\\[([\\s\\S]*?)\\];`);
-        const declaration = declarationPattern.exec(beforeDcl);
-        if (declaration?.[1] && new RegExp(`["']${escapeRegex(tagName)}["']`).test(declaration[1])) {
-            return true;
-        }
-    }
-    return false;
-}

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

@@ -1,112 +0,0 @@
-export { addCustomElementRegistration, validateCustomElementRegistration, } from './furnace-registration-ast.js';
-export { removeCustomElementRegistration } from './furnace-registration-remove.js';
-export { renameCustomElementRegistration } from './furnace-registration-rename.js';
-/**
- * Adds jar.mn entries that map chrome:// URIs to on-disk paths for a
- * component's files.
- *
- * ## Assumed jar.mn format
- *
- * Firefox's `toolkit/content/jar.mn` uses a stable format that has not
- * changed in the custom-element era (Firefox 90+). The entry format is:
- *
- * ```
- *    content/global/elements/{file}  (widgets/{tagName}/{file})
- * ```
- *
- * - **Indent**: detected dynamically from the nearest existing
- *   `content/global/elements/` line. Falls back to 3 spaces when no
- *   reference line exists.
- * - **Insertion point**: identified by existing lines matching the regex
- *   `^\s+content\/global\/elements\/([^.]+)\.`. New entries are inserted
- *   in alphabetical order relative to these.
- * - **Fallback**: if no `content/global/elements/` line exists (empty
- *   project), looks for any `content/global/` line and inserts after it.
- * - **Idempotency**: entries already present anywhere in the file (an exact
- *   target match on `content/global/elements/{file}`, or a source match on
- *   `(widgets/{tagName}/{file})`) are skipped, including hand-written ones.
- *
- * If Firefox upstream changes the jar.mn section ordering or switches to a
- * different resource registration mechanism, the preflight validation in
- * `validateJarMnInsertionForFiles` will catch the format mismatch before any writes
- * occur.
- *
- * @param engineDir - Path to the Firefox engine source root
- * @param tagName - Custom element tag name
- * @param files - Filenames to register (e.g. ["moz-widget.mjs", "moz-widget.css"])
- */
-export declare function addJarMnEntries(engineDir: string, tagName: string, files: string[]): Promise<number>;
-/**
- * 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 declare function addLocaleFtlJarMnEntry(engineDir: string, jarMnRelPath: string, tagName: string, chromeSubPath: string): Promise<number>;
-/**
- * True when the locale jar.mn carries a per-widget line for `tagName`.
- * False when the jar.mn is missing. Used by `furnace rename --dry-run` to
- * say whether a rename would re-point a line or leave the jar alone.
- */
-export declare function hasLocaleFtlJarMnEntry(engineDir: string, jarMnRelPath: string, tagName: string, chromeSubPath: string): Promise<boolean>;
-/**
- * Removes a locale jar.mn entry previously written by `addLocaleFtlJarMnEntry`.
- * Idempotent: if the entry is absent or the file is missing, nothing happens.
- *
- * @returns True when a line was removed, so a rename re-points only an
- *   entry that existed instead of inventing one
- */
-export declare function removeLocaleFtlJarMnEntry(engineDir: string, jarMnRelPath: string, tagName: string, chromeSubPath: string): Promise<boolean>;
-/**
- * Removes all jar.mn entries for a given tag name.
- *
- * This operation is idempotent: if no entries exist or the file is missing,
- * nothing happens.
- *
- * @param engineDir - Path to the Firefox engine source root
- * @param tagName - Custom element tag name whose entries should be removed
- */
-export declare function removeJarMnEntries(engineDir: string, tagName: string): Promise<void>;
-/** A jar.mn widget registration line whose source file no longer exists. */
-export interface StaleJarMnEntry {
-    /** Component tag name from the `(widgets/<tag>/<file>)` source mapping. */
-    tagName: string;
-    /** File name from the source mapping. */
-    fileName: string;
-    /** The full (trimmed) jar.mn line. */
-    line: string;
-}
-/**
- * Scans jar.mn for widget registration lines `(widgets/<tag>/<file>)` whose
- * workspace source file no longer exists. A renamed component helper
- * otherwise leaves the old line pointing at a deleted file and every build
- * fails at packaging. Only tags in `managedTags` (furnace-managed custom
- * components) are inspected, so upstream lines are never touched.
- */
-export declare function findStaleJarMnEntries(engineDir: string, customDir: string, managedTags: readonly string[]): Promise<StaleJarMnEntry[]>;
-/**
- * Removes every stale widget registration line found by
- * {@link findStaleJarMnEntries}. Returns the removed entries. Used by
- * `furnace validate --fix` and `doctor --repair-furnace`.
- */
-export declare function pruneStaleJarMnEntries(engineDir: string, customDir: string, managedTags: readonly string[]): Promise<StaleJarMnEntry[]>;
-/**
- * Validates that jar.mn entries *could* be added without writing anything.
- * Used by dry-run to surface structural problems early.
- */
-export declare function validateJarMnInsertionForFiles(engineDir: string, tagName: string, files: string[]): Promise<void>;