@hominis/fireforge 0.13.2 → 0.15.1

package/dist/src/core/furnace-apply-ftl.js

@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `.ftl` apply/undeploy helpers for custom components. Extracted from
+ * `furnace-apply-helpers.ts` so the main helper module stays under the
+ * per-file LOC budget.
+ *
+ * Every helper here degrades gracefully: if the locale jar.mn is missing or
+ * the FTL tree is non-standard, apply logs a `stepError` rather than
+ * aborting the whole command. Missing jar.mn on a fork without a locale
+ * package should not block a working `.mjs`/`.css` from shipping.
+ */
+import { join, relative } from 'node:path';
+import { toError } from '../utils/errors.js';
+import { copyFile, pathExists } from '../utils/fs.js';
+import { resolveFtlChromeSubPath, resolveFtlLocaleJarMnPath } from './furnace-constants.js';
+import { addLocaleFtlJarMnEntry, removeLocaleFtlJarMnEntry } from './furnace-registration.js';
+import { snapshotFile } from './furnace-rollback.js';
+/**
+ * Copies a component's `.ftl` into the FTL tree and registers the chrome URI
+ * in the locale jar.mn.
+ *
+ * Failure modes (missing jar.mn, regex write error) are captured as
+ * stepErrors rather than thrown — a well-formed `.mjs`/`.css` must never be
+ * blocked by a broken locale path.
+ */
+export async function applyCustomFtlFile(engineDir, name, componentDir, ftlDir, affectedPaths, stepErrors, rollbackJournal) {
+    const ftlFile = `${name}.ftl`;
+    const ftlSrc = join(componentDir, ftlFile);
+    if (!(await pathExists(ftlSrc)))
+        return;
+    const ftlDest = join(engineDir, ftlDir, ftlFile);
+    if (rollbackJournal) {
+        await snapshotFile(rollbackJournal, ftlDest);
+    }
+    await copyFile(ftlSrc, ftlDest);
+    affectedPaths.push(relative(engineDir, ftlDest));
+    const chromeSubPath = resolveFtlChromeSubPath(ftlDir);
+    const localeJarRel = resolveFtlLocaleJarMnPath(ftlDir);
+    if (chromeSubPath === undefined || localeJarRel === undefined)
+        return;
+    const localeJarAbs = join(engineDir, localeJarRel);
+    if (!(await pathExists(localeJarAbs))) {
+        stepErrors.push({
+            step: 'locale jar.mn registration',
+            error: `Locale jar.mn not found at ${localeJarRel}; component "${name}" ships without a chrome URI for ${ftlFile}. Add the file manually or set furnace.json "ftlBasePath" to a tree that owns a jar.mn.`,
+        });
+        return;
+    }
+    try {
+        if (rollbackJournal) {
+            await snapshotFile(rollbackJournal, localeJarAbs);
+        }
+        const inserted = await addLocaleFtlJarMnEntry(engineDir, localeJarRel, name, chromeSubPath);
+        if (inserted > 0) {
+            affectedPaths.push(localeJarRel);
+        }
+    }
+    catch (error) {
+        stepErrors.push({
+            step: 'locale jar.mn registration',
+            error: toError(error).message,
+        });
+    }
+}
+/**
+ * Returns a dry-run action for registering a locale jar.mn entry for the
+ * `.ftl` that `applyCustomFtlFile` would write. `undefined` when the FTL
+ * tree does not expose a locale jar.mn we can confidently name.
+ */
+export function describeLocaleFtlJarMnRegistration(name, ftlDir, ftlFile) {
+    const chromeSubPath = resolveFtlChromeSubPath(ftlDir);
+    const localeJarRel = resolveFtlLocaleJarMnPath(ftlDir);
+    if (chromeSubPath === undefined || localeJarRel === undefined)
+        return undefined;
+    return {
+        component: name,
+        action: 'register-jar',
+        description: `Register ${chromeSubPath}/${ftlFile} in ${localeJarRel}`,
+    };
+}
+/**
+ * Drops the locale jar.mn entry for `fileName` when it's a `.ftl` whose
+ * source workspace file has been deleted. Idempotent — absent entries are a
+ * no-op.
+ */
+export async function removeCustomFtlJarMnEntry(engineDir, fileName, ftlDir, rollbackJournal) {
+    if (!fileName.endsWith('.ftl'))
+        return;
+    const tagName = fileName.slice(0, -'.ftl'.length);
+    const chromeSubPath = resolveFtlChromeSubPath(ftlDir);
+    const localeJarRel = resolveFtlLocaleJarMnPath(ftlDir);
+    if (chromeSubPath === undefined || localeJarRel === undefined)
+        return;
+    const localeJarAbs = join(engineDir, localeJarRel);
+    if (!(await pathExists(localeJarAbs)))
+        return;
+    if (rollbackJournal) {
+        await snapshotFile(rollbackJournal, localeJarAbs);
+    }
+    await removeLocaleFtlJarMnEntry(engineDir, localeJarRel, tagName, chromeSubPath);
+}
+//# sourceMappingURL=furnace-apply-ftl.js.map

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

@@ -90,8 +90,17 @@ export declare function hasOverrideEngineDrift(engineDir: string, componentDir:
  * the validate command.
  */
 export declare function hasCustomEngineDrift(root: string, name: string, componentDir: string, config: CustomComponentConfig, ftlDir: string): Promise<boolean>;
+/** Extra knobs threaded into `applyCustomComponent` from the project config. */
+export interface CustomApplyOptions {
+    /**
+     * Trailing project marker appended to inserted `customElements.js` entries
+     * (e.g. `"HOMINIS"` emits `  // HOMINIS:` on each line). Mirrors the
+     * `markerComment` field in fireforge.json.
+     */
+    markerComment?: string;
+}
 /** Applies a custom component into the engine tree and captures registration step errors. */
-export declare function applyCustomComponent(engineDir: string, name: string, componentDir: string, config: CustomComponentConfig, ftlDir: string, dryRun?: boolean, rollbackJournal?: RollbackJournal): Promise<{
+export declare function applyCustomComponent(engineDir: string, name: string, componentDir: string, config: CustomComponentConfig, ftlDir: string, dryRun?: boolean, rollbackJournal?: RollbackJournal, applyOptions?: CustomApplyOptions): Promise<{
     affectedPaths: string[];
     stepErrors: StepError[];
     actions?: DryRunAction[];

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

@@ -6,6 +6,7 @@ import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
 import { copyFile, ensureDir, pathExists, readText, removeFile } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
+import { applyCustomFtlFile, describeLocaleFtlJarMnRegistration, removeCustomFtlJarMnEntry, } from './furnace-apply-ftl.js';
 import { CUSTOM_ELEMENTS_JS, JAR_MN } from './furnace-constants.js';
 import { addCustomElementRegistration, addJarMnEntries, validateCustomElementRegistration, validateJarMnEntries, } from './furnace-registration.js';
 import { recordCreatedDir, snapshotFile } from './furnace-rollback.js';
@@ -138,6 +139,10 @@ export async function undeployCustomFiles(engineDir, config, deletedFiles, ftlDi
             await removeFile(enginePath);
             removed.push(relative(engineDir, enginePath));
         }
+        // When an `.ftl` is deleted from the workspace, the corresponding locale
+        // jar.mn entry must also be dropped — otherwise the chrome URI points at
+        // a missing file and runtime Fluent resolution breaks silently.
+        await removeCustomFtlJarMnEntry(engineDir, fileName, ftlDir, rollbackJournal);
     }
     return removed;
 }
@@ -312,6 +317,10 @@ async function buildCustomDryRunActions(name, componentDir, engineDir, config, t
                 target: join(engineDir, ftlDir, ftlFile),
                 description: `Copy ${ftlFile} to ${ftlDir}`,
             });
+            const localeAction = describeLocaleFtlJarMnRegistration(name, ftlDir, ftlFile);
+            if (localeAction) {
+                actions.push(localeAction);
+            }
         }
     }
     if (config.register) {
@@ -353,7 +362,7 @@ async function buildCustomDryRunActions(name, componentDir, engineDir, config, t
     return { actions, stepErrors };
 }
 /** Applies a custom component into the engine tree and captures registration step errors. */
-export async function applyCustomComponent(engineDir, name, componentDir, config, ftlDir, dryRun = false, rollbackJournal) {
+export async function applyCustomComponent(engineDir, name, componentDir, config, ftlDir, dryRun = false, rollbackJournal, applyOptions = {}) {
     if (!/^[a-z][a-z0-9-]*$/.test(name)) {
         throw new FurnaceError(`Invalid component name "${name}": must match /^[a-z][a-z0-9-]*$/`);
     }
@@ -394,16 +403,7 @@ export async function applyCustomComponent(engineDir, name, componentDir, config
         copiedFileNames.push(entry.name);
     }));
     if (config.localized) {
-        const ftlFile = `${name}.ftl`;
-        const ftlSrc = join(componentDir, ftlFile);
-        if (await pathExists(ftlSrc)) {
-            const ftlDest = join(engineDir, ftlDir, ftlFile);
-            if (rollbackJournal) {
-                await snapshotFile(rollbackJournal, ftlDest);
-            }
-            await copyFile(ftlSrc, ftlDest);
-            affectedPaths.push(relative(engineDir, ftlDest));
-        }
+        await applyCustomFtlFile(engineDir, name, componentDir, ftlDir, affectedPaths, stepErrors, rollbackJournal);
     }
     if (config.register) {
         try {
@@ -411,7 +411,11 @@ export async function applyCustomComponent(engineDir, name, componentDir, config
             if (rollbackJournal) {
                 await snapshotFile(rollbackJournal, join(engineDir, CUSTOM_ELEMENTS_JS));
             }
-            await addCustomElementRegistration(engineDir, name, modulePath);
+            await addCustomElementRegistration(engineDir, name, modulePath, {
+                ...(applyOptions.markerComment !== undefined
+                    ? { markerComment: applyOptions.markerComment }
+                    : {}),
+            });
             affectedPaths.push(CUSTOM_ELEMENTS_JS);
         }
         catch (error) {

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

@@ -4,7 +4,7 @@ import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info } from '../utils/logger.js';
-import { getProjectPaths } from './config.js';
+import { getProjectPaths, loadConfig } from './config.js';
 import { applyCustomComponent, applyOverrideComponent, computeComponentChecksums, diffDeletedFiles, extractComponentChecksums, getOverrideEngineTargetPath, hasComponentChanged, hasCustomEngineDrift, hasOverrideEngineDrift, prefixChecksums, undeployCustomFiles, undeployOverrideFiles, } from './furnace-apply-helpers.js';
 import { getFurnacePaths, loadFurnaceConfig, loadFurnaceState, updateFurnaceState, } from './furnace-config.js';
 import { CUSTOM_ELEMENTS_JS, JAR_MN, resolveFtlDir } from './furnace-constants.js';
@@ -161,7 +161,7 @@ async function reconcileCustomRegistrationAfterUndeploy(engineDir, name, config,
         filesAffected.push(CUSTOM_ELEMENTS_JS);
     }
 }
-async function applyCustomBatch(root, config, furnacePaths, state, engineDir, ftlDir, dryRun, result, allActions, newChecksums, rollbackJournal, componentName) {
+async function applyCustomBatch(root, config, furnacePaths, state, engineDir, ftlDir, dryRun, result, allActions, newChecksums, rollbackJournal, componentName, markerComment) {
     const allKnown = new Set([
         ...config.stock,
         ...Object.keys(config.overrides),
@@ -246,7 +246,7 @@ async function applyCustomBatch(root, config, furnacePaths, state, engineDir, ft
                 const removed = await undeployCustomFiles(engineDir, customConfig, deletedFiles, ftlDir, rollbackJournal);
                 filesAffectedTotal.push(...removed);
             }
-            const { affectedPaths: filesAffected, stepErrors, actions, } = await applyCustomComponent(engineDir, name, componentDir, customConfig, ftlDir, dryRun, rollbackJournal);
+            const { affectedPaths: filesAffected, stepErrors, actions, } = await applyCustomComponent(engineDir, name, componentDir, customConfig, ftlDir, dryRun, rollbackJournal, markerComment !== undefined ? { markerComment } : {});
             if (dryRun && actions) {
                 allActions.push(...actions);
             }
@@ -304,6 +304,9 @@ export async function applyAllComponents(root, dryRun = false, options) {
     const { engine: engineDir } = getProjectPaths(root);
     const furnacePaths = getFurnacePaths(root);
     const ftlDir = resolveFtlDir(config.ftlBasePath);
+    const markerComment = await loadConfig(root)
+        .then((forgeConfig) => forgeConfig.markerComment)
+        .catch(() => undefined);
     if (!(await pathExists(engineDir))) {
         throw new FurnaceError('Engine directory not found. Run "fireforge download" first.');
     }
@@ -328,7 +331,7 @@ export async function applyAllComponents(root, dryRun = false, options) {
         }
     }
     await applyOverrideBatch(config, furnacePaths, state, engineDir, ftlDir, dryRun, result, allActions, newChecksums, rollbackJournal, componentName);
-    await applyCustomBatch(root, config, furnacePaths, state, engineDir, ftlDir, dryRun, result, allActions, newChecksums, rollbackJournal, componentName);
+    await applyCustomBatch(root, config, furnacePaths, state, engineDir, ftlDir, dryRun, result, allActions, newChecksums, rollbackJournal, componentName, markerComment);
     // Check for any partial failures (step errors on applied components).
     const hasStepErrors = result.applied.some((entry) => 'stepErrors' in entry && entry.stepErrors.length > 0);
     // Orphaned components are implicitly cleaned up: newChecksums only

package/dist/src/core/furnace-config-tokens.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Small validation helpers for furnace.json token-related fields. Extracted
+ * from `furnace-config.ts` so the main config module stays under the per-file
+ * LOC budget.
+ */
+/**
+ * Validates a `tokenHostDocuments` raw value. Each entry must be a non-empty
+ * relative path contained in the engine tree. Throws `FurnaceError` on
+ * violation; does nothing for `undefined` (field is optional).
+ */
+export declare function validateTokenHostDocuments(raw: unknown): void;

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

@@ -0,0 +1,28 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Small validation helpers for furnace.json token-related fields. Extracted
+ * from `furnace-config.ts` so the main config module stays under the per-file
+ * LOC budget.
+ */
+import { FurnaceError } from '../errors/furnace.js';
+import { isContainedRelativePath } from '../utils/paths.js';
+import { parseStringArray } from './furnace-config.js';
+/**
+ * Validates a `tokenHostDocuments` raw value. Each entry must be a non-empty
+ * relative path contained in the engine tree. Throws `FurnaceError` on
+ * violation; does nothing for `undefined` (field is optional).
+ */
+export function validateTokenHostDocuments(raw) {
+    if (raw === undefined)
+        return;
+    const docs = parseStringArray(raw, 'tokenHostDocuments');
+    for (const doc of docs) {
+        if (doc.trim() === '') {
+            throw new FurnaceError('Furnace config: "tokenHostDocuments" entries must be non-empty strings');
+        }
+        if (!isContainedRelativePath(doc)) {
+            throw new FurnaceError(`Furnace config: "tokenHostDocuments" entry "${doc}" must stay within the engine tree (no absolute paths, no "..")`);
+        }
+    }
+}
+//# sourceMappingURL=furnace-config-tokens.js.map

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

@@ -38,6 +38,12 @@ export declare function getFurnacePaths(root: string): FurnacePaths;
  * @returns True if furnace.json exists
  */
 export declare function furnaceConfigExists(root: string): Promise<boolean>;
+/**
+ * Validates an override component config object.
+ * @param data - Raw data to validate
+ * @param name - Component name for error messages
+ */
+export declare function parseStringArray(value: unknown, fieldName: string): string[];
 /**
  * Migrates a furnace config from an older schema version to the current one.
  * Returns the data unchanged if it is already at the current version.

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

@@ -7,6 +7,7 @@ import { warn } from '../utils/logger.js';
 import { isExplicitAbsolutePath } from '../utils/paths.js';
 import { isArray, isBoolean, isObject, isString } from '../utils/validation.js';
 import { FIREFORGE_DIR } from './config.js';
+import { validateTokenHostDocuments } from './furnace-config-tokens.js';
 import { resolveFtlDir } from './furnace-constants.js';
 import { detectComposesCycles, validateComposesReferences } from './furnace-graph-utils.js';
 import { quarantineStateFile, withStateFileLock } from './state-file.js';
@@ -50,7 +51,7 @@ export async function furnaceConfigExists(root) {
  * @param data - Raw data to validate
  * @param name - Component name for error messages
  */
-function parseStringArray(value, fieldName) {
+export function parseStringArray(value, fieldName) {
     if (!isArray(value)) {
         throw new FurnaceError(`Furnace config: "${fieldName}" must be an array`);
     }
@@ -182,6 +183,9 @@ export function validateFurnaceConfig(data) {
     if (migrated['tokenAllowlist'] !== undefined) {
         parseStringArray(migrated['tokenAllowlist'], 'tokenAllowlist');
     }
+    // Validate optional tokenHostDocuments — list of chrome XHTMLs that the
+    // `missing-token-link` validator scans for the tokens CSS link.
+    validateTokenHostDocuments(migrated['tokenHostDocuments']);
     const stock = parseStringArray(migrated['stock'], 'stock');
     const stockSet = new Set();
     for (const name of stock) {
@@ -238,6 +242,9 @@ export function validateFurnaceConfig(data) {
     if (migrated['tokenAllowlist'] !== undefined) {
         config.tokenAllowlist = parseStringArray(migrated['tokenAllowlist'], 'tokenAllowlist');
     }
+    if (migrated['tokenHostDocuments'] !== undefined) {
+        config.tokenHostDocuments = parseStringArray(migrated['tokenHostDocuments'], 'tokenHostDocuments');
+    }
     // Validate optional ftlBasePath
     if (migrated['ftlBasePath'] !== undefined) {
         if (!isString(migrated['ftlBasePath'])) {

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

@@ -13,6 +13,26 @@ export declare function isComponentSourceFile(fileName: string): boolean;
  * `furnace.json` over the built-in default.
  */
 export declare function resolveFtlDir(configuredPath?: string): string;
+/**
+ * Resolves the chrome sub-path that `document.l10n` / `insertFTLIfNeeded`
+ * expects for a given `ftlBasePath`. Strips the mandatory `locales/<LOCALE>/`
+ * segment. For the default `toolkit/locales/en-US/toolkit/global` this yields
+ * `toolkit/global`.
+ *
+ * Returns `undefined` when no `locales/<LOCALE>/` segment is present. Callers
+ * must treat that as "cannot confidently locate the locale jar.mn entry" and
+ * degrade gracefully rather than inventing a path.
+ */
+export declare function resolveFtlChromeSubPath(ftlBasePath?: string): string | undefined;
+/**
+ * Returns the engine-relative locale jar.mn that owns the FTL tree for a
+ * given `ftlBasePath`. For the default toolkit tree this yields
+ * `toolkit/locales/jar.mn`.
+ *
+ * Returns `undefined` when the path does not contain a `locales/` segment —
+ * callers must treat that as "cannot locate" and degrade gracefully.
+ */
+export declare function resolveFtlLocaleJarMnPath(ftlBasePath?: string): string | undefined;
 /**
  * Converts a kebab-case tag name to PascalCase class name.
  * e.g. "moz-sidebar-panel" → "MozSidebarPanel"

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

@@ -18,6 +18,38 @@ export function isComponentSourceFile(fileName) {
 export function resolveFtlDir(configuredPath) {
     return configuredPath ?? FTL_DIR;
 }
+/**
+ * Resolves the chrome sub-path that `document.l10n` / `insertFTLIfNeeded`
+ * expects for a given `ftlBasePath`. Strips the mandatory `locales/<LOCALE>/`
+ * segment. For the default `toolkit/locales/en-US/toolkit/global` this yields
+ * `toolkit/global`.
+ *
+ * Returns `undefined` when no `locales/<LOCALE>/` segment is present. Callers
+ * must treat that as "cannot confidently locate the locale jar.mn entry" and
+ * degrade gracefully rather than inventing a path.
+ */
+export function resolveFtlChromeSubPath(ftlBasePath) {
+    const path = (ftlBasePath ?? FTL_DIR).replace(/\\/g, '/');
+    const match = /^(.*?)\/locales\/[^/]+\/(.+?)\/?$/.exec(path);
+    if (!match?.[2])
+        return undefined;
+    return match[2];
+}
+/**
+ * Returns the engine-relative locale jar.mn that owns the FTL tree for a
+ * given `ftlBasePath`. For the default toolkit tree this yields
+ * `toolkit/locales/jar.mn`.
+ *
+ * Returns `undefined` when the path does not contain a `locales/` segment —
+ * callers must treat that as "cannot locate" and degrade gracefully.
+ */
+export function resolveFtlLocaleJarMnPath(ftlBasePath) {
+    const path = (ftlBasePath ?? FTL_DIR).replace(/\\/g, '/');
+    const match = /^(.*?)\/locales\/[^/]+\//.exec(path);
+    if (!match?.[1])
+        return undefined;
+    return `${match[1]}/locales/jar.mn`;
+}
 /**
  * Converts a kebab-case tag name to PascalCase class name.
  * e.g. "moz-sidebar-panel" → "MozSidebarPanel"

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

@@ -2,6 +2,18 @@
  * AST-based custom element registration updates for customElements.js.
  * Removal logic is in furnace-registration-remove.ts.
  */
+/**
+ * Options that shape the lines `addCustomElementRegistration` writes into
+ * `customElements.js`. Kept optional so existing call sites keep working.
+ */
+export interface RegistrationWriteOptions {
+    /**
+     * Trailing project marker appended to every inserted line (e.g. `"HOMINIS"`
+     * produces `  // HOMINIS:` at end-of-line). Keeps modifications discoverable
+     * without requiring the operator to hand-tag them post-apply.
+     */
+    markerComment?: string;
+}
 export { removeCustomElementRegistration } from './furnace-registration-remove.js';
 export { CUSTOM_ELEMENTS_JS, JAR_MN } from './furnace-constants.js';
 /**
@@ -21,7 +33,7 @@ export { CUSTOM_ELEMENTS_JS, JAR_MN } from './furnace-constants.js';
  * @param tagName - Custom element tag name
  * @param modulePath - chrome:// URI for the module
  */
-export declare function addCustomElementRegistration(engineDir: string, tagName: string, modulePath: string): Promise<void>;
+export declare function addCustomElementRegistration(engineDir: string, tagName: string, modulePath: string, options?: RegistrationWriteOptions): Promise<void>;
 /**
  * Validates that a custom element registration *would* succeed without
  * writing anything. Used by dry-run to surface registration errors early.

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

@@ -9,9 +9,43 @@ 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 { escapeRegex } from '../utils/regex.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';
+/**
+ * Returns true when `content` already contains a registration for `tagName`.
+ *
+ * Tolerates trailing line comments (e.g. a project marker like `// HOMINIS:`)
+ * that an operator may have appended to entries written by a previous apply.
+ * Without this, a re-apply would insert a duplicate entry, and the second
+ * `setElementCreationCallback` at window-load would throw `NotSupportedError`.
+ *
+ * Matches any of:
+ *   1. `setElementCreationCallback("tag"` / `setElementCreationCallback('tag'`
+ *   2. Single-line array entry: `["tag", "..."]` — column 0 only, comments allowed after
+ *   3. Multi-line array entry: `"tag",` on its own line, optional trailing `//` comment
+ */
+function isTagAlreadyRegistered(content, tagName) {
+    const escaped = escapeRegex(tagName);
+    if (content.includes(`setElementCreationCallback("${tagName}"`) ||
+        content.includes(`setElementCreationCallback('${tagName}'`)) {
+        return true;
+    }
+    if (new RegExp(`^\\s*\\[\\s*["']${escaped}["']\\s*,`, 'm').test(content)) {
+        return true;
+    }
+    if (new RegExp(`^\\s*["']${escaped}["']\\s*,\\s*(?:\\/\\/.*)?$`, 'm').test(content)) {
+        return true;
+    }
+    return false;
+}
+/** Validates a markerComment value and returns the formatted suffix (with leading spaces). */
+function formatMarkerSuffix(markerComment) {
+    if (!markerComment)
+        return '';
+    return `  // ${markerComment}:`;
+}
 // Re-export from split modules so existing import sites continue working
 export { removeCustomElementRegistration } from './furnace-registration-remove.js';
 // Re-export constants so existing import sites continue working
@@ -62,23 +96,27 @@ function selectRegistrationTarget(targets, isESModule, tagName) {
     }
     throw new FurnaceError(`${tagName} would land in the DOMContentLoaded/importESModule block (Pattern B) instead of the loadSubScript block (Pattern A) — no non-DOMContentLoaded registration array found in customElements.js. The file structure may have changed upstream — manual intervention required.`, tagName);
 }
-function buildRegistrationEntry(referenceEntry, tagName, modulePath) {
+function buildRegistrationEntry(referenceEntry, tagName, modulePath, markerComment) {
+    const marker = formatMarkerSuffix(markerComment);
     if (!referenceEntry) {
-        return `    ["${tagName}", "${modulePath}"],`;
+        return `    ["${tagName}", "${modulePath}"],${marker}`;
     }
     if (referenceEntry.isMultiLine) {
         const indent = referenceEntry.indent;
         const inner = referenceEntry.innerIndent ?? indent + '  ';
-        return `${indent}[\n${inner}"${tagName}",\n${inner}"${modulePath}",\n${indent}],`;
+        return (`${indent}[${marker}\n` +
+            `${inner}"${tagName}",${marker}\n` +
+            `${inner}"${modulePath}",${marker}\n` +
+            `${indent}],${marker}`);
     }
-    return `${referenceEntry.indent}["${tagName}", "${modulePath}"],`;
+    return `${referenceEntry.indent}["${tagName}", "${modulePath}"],${marker}`;
 }
 /**
  * AST-based implementation: parses customElements.js, walks to find the
  * target ForOfStatement array, and inserts the new entry at the correct
  * alphabetical position using magic-string.
  */
-function addRegistrationAST(content, tagName, modulePath, isESModule) {
+function addRegistrationAST(content, tagName, modulePath, isESModule, markerComment) {
     validateTagName(tagName);
     const ast = parseScript(content);
     const ancestors = [];
@@ -141,7 +179,7 @@ function addRegistrationAST(content, tagName, modulePath, isESModule) {
         referenceEntry = entry;
     }
     // Build new entry string matching detected format
-    const newEntry = buildRegistrationEntry(referenceEntry, tagName, modulePath);
+    const newEntry = buildRegistrationEntry(referenceEntry, tagName, modulePath, markerComment);
     const ms = new MagicString(content);
     // Helper: find the start-of-line position for a given offset
     function lineStart(pos) {
@@ -181,7 +219,7 @@ function addRegistrationAST(content, tagName, modulePath, isESModule) {
  * validate indentation or multi-line format — but it is robust against
  * upstream syntax changes that break the parser.
  */
-function addRegistrationRegexFallback(content, tagName, modulePath, isESModule) {
+function addRegistrationRegexFallback(content, tagName, modulePath, isESModule, markerComment) {
     // Find all registration entries: ["tag", "path"],
     const entryPattern = /^(\s*)\["([^"]+)",\s*"[^"]+"\],?\s*$/gm;
     let lastMatch = null;
@@ -212,7 +250,8 @@ function addRegistrationRegexFallback(content, tagName, modulePath, isESModule)
         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}"],`;
+    const marker = formatMarkerSuffix(markerComment);
+    const newEntry = `${indent}["${tagName}", "${modulePath}"],${marker}`;
     if (insertAfterMatch) {
         // Insert after the last entry that sorts before tagName
         const insertPos = insertAfterMatch.index + insertAfterMatch[0].length;
@@ -243,20 +282,18 @@ function addRegistrationRegexFallback(content, tagName, modulePath, isESModule)
  * @param tagName - Custom element tag name
  * @param modulePath - chrome:// URI for the module
  */
-export async function addCustomElementRegistration(engineDir, tagName, modulePath) {
+export async function addCustomElementRegistration(engineDir, tagName, modulePath, options = {}) {
     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);
-    // 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}",`) ||
-        content.includes(`['${tagName}',`) ||
-        new RegExp(`^\\s*["']${tagName}["'],\\s*$`, 'm').test(content)) {
+    // Idempotency: check column-0 of each array entry rather than a literal
+    // substring match. A previous apply may have written this entry with
+    // trailing marker comments (see `options.markerComment`); matching on the
+    // full line would then miss it and insert a duplicate on re-apply, which
+    // throws NotSupportedError at every window-load.
+    if (isTagAlreadyRegistered(content, tagName)) {
         return;
     }
     // Validate upfront — tag name errors must not fall through to the regex fallback.
@@ -279,7 +316,7 @@ export async function addCustomElementRegistration(engineDir, tagName, modulePat
     }
     let nextContent;
     try {
-        nextContent = addRegistrationAST(content, tagName, modulePath, isESModule);
+        nextContent = addRegistrationAST(content, tagName, modulePath, isESModule, options.markerComment);
     }
     catch (error) {
         if (error instanceof FurnaceError) {
@@ -287,7 +324,7 @@ export async function addCustomElementRegistration(engineDir, tagName, modulePat
             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);
+                nextContent = addRegistrationRegexFallback(content, tagName, modulePath, isESModule, options.markerComment);
                 verbose(`Regex fallback succeeded for ${tagName}. The registration may be less precise than the AST approach.`);
             }
             catch {
@@ -300,7 +337,7 @@ export async function addCustomElementRegistration(engineDir, tagName, modulePat
             warn(`AST parser threw an unexpected error for ${tagName}: ${parserError.message}. ` +
                 'Falling back to regex-based insertion.');
             try {
-                nextContent = addRegistrationRegexFallback(content, tagName, modulePath, isESModule);
+                nextContent = addRegistrationRegexFallback(content, tagName, modulePath, isESModule, options.markerComment);
                 verbose(`Regex fallback succeeded for ${tagName}. The registration may be less precise than the AST approach.`);
             }
             catch {
@@ -321,11 +358,7 @@ export async function validateCustomElementRegistration(engineDir, tagName, modu
         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)) {
+    if (isTagAlreadyRegistered(content, tagName)) {
         return;
     }
     const isESModule = modulePath.endsWith('.mjs');

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

@@ -34,7 +34,34 @@ export { addCustomElementRegistration, removeCustomElementRegistration, validate
  * @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<void>;
+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>;
+/**
+ * Removes a locale jar.mn entry previously written by `addLocaleFtlJarMnEntry`.
+ * Idempotent — if the entry is absent or the file is missing, nothing happens.
+ */
+export declare function removeLocaleFtlJarMnEntry(engineDir: string, jarMnRelPath: string, tagName: string, chromeSubPath: string): Promise<void>;
 /**
  * Removes all jar.mn entries for a given tag name.
  *