@hominis/fireforge 0.14.0 → 0.15.2

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,17 @@
+/**
+ * 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;
+/**
+ * Validates a `runtimeVariables` raw value. Each entry must start with `--`
+ * (it is a CSS custom property name). Throws `FurnaceError` on violation;
+ * does nothing for `undefined` (field is optional).
+ */
+export declare function validateRuntimeVariables(raw: unknown): void;

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

@@ -0,0 +1,43 @@
+// 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 "..")`);
+        }
+    }
+}
+/**
+ * Validates a `runtimeVariables` raw value. Each entry must start with `--`
+ * (it is a CSS custom property name). Throws `FurnaceError` on violation;
+ * does nothing for `undefined` (field is optional).
+ */
+export function validateRuntimeVariables(raw) {
+    if (raw === undefined)
+        return;
+    const vars = parseStringArray(raw, 'runtimeVariables');
+    for (const name of vars) {
+        if (!name.startsWith('--')) {
+            throw new FurnaceError(`Furnace config: "runtimeVariables" entries must start with "--" (got ${JSON.stringify(name)})`);
+        }
+    }
+}
+//# 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 { validateRuntimeVariables, 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,12 @@ export function validateFurnaceConfig(data) {
     if (migrated['tokenAllowlist'] !== undefined) {
         parseStringArray(migrated['tokenAllowlist'], 'tokenAllowlist');
     }
+    // Validate optional runtimeVariables — CSS runtime state channels
+    // (e.g. `--cam-x`) that are exempt from `token-prefix-violation`.
+    validateRuntimeVariables(migrated['runtimeVariables']);
+    // 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) {
@@ -232,12 +239,18 @@ export function validateFurnaceConfig(data) {
         overrides,
         custom,
     };
-    if (migrated['tokenPrefix'] !== undefined) {
+    if (migrated['tokenPrefix'] !== undefined)
         config.tokenPrefix = migrated['tokenPrefix'];
-    }
     if (migrated['tokenAllowlist'] !== undefined) {
         config.tokenAllowlist = parseStringArray(migrated['tokenAllowlist'], 'tokenAllowlist');
     }
+    if (migrated['runtimeVariables'] !== undefined) {
+        config.runtimeVariables = parseStringArray(migrated['runtimeVariables'], 'runtimeVariables');
+    }
+    if (migrated['tokenHostDocuments'] !== undefined) {
+        const docs = parseStringArray(migrated['tokenHostDocuments'], 'tokenHostDocuments');
+        config.tokenHostDocuments = docs;
+    }
     // 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. `"MYBROWSER"`
+     * produces `  // MYBROWSER:` 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 `// MYBROWSER:`)
+ * 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

@@ -35,6 +35,33 @@ export { addCustomElementRegistration, removeCustomElementRegistration, validate
  * @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>;
+/**
+ * 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.
  *

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

@@ -113,6 +113,102 @@ export async function addJarMnEntries(engineDir, tagName, files) {
     await writeText(filePath, content);
     return newFiles.length;
 }
+/**
+ * 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 async function addLocaleFtlJarMnEntry(engineDir, jarMnRelPath, tagName, chromeSubPath) {
+    const filePath = join(engineDir, jarMnRelPath);
+    if (!(await pathExists(filePath))) {
+        return 0;
+    }
+    const content = await readText(filePath);
+    const lines = content.split('\n');
+    const ftlFile = `${tagName}.ftl`;
+    const escapedTag = escapeForRegex(tagName);
+    const escapedChrome = escapeForRegex(chromeSubPath);
+    const presencePattern = new RegExp(`locale\\/(?:@AB_CD@|[a-zA-Z-]+)\\/${escapedChrome}\\/${escapedTag}\\.ftl`, 'm');
+    if (presencePattern.test(content)) {
+        return 0;
+    }
+    const indent = detectLocaleJarMnIndent(lines, chromeSubPath);
+    const newEntry = `${indent}locale/@AB_CD@/${chromeSubPath}/${ftlFile} (%${chromeSubPath}/${ftlFile})`;
+    const sectionPattern = new RegExp(`^(\\s+)locale\\/(?:@AB_CD@|[a-zA-Z-]+)\\/${escapedChrome}\\/([^.\\s]+)\\.ftl`);
+    let insertIndex = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === undefined)
+            continue;
+        const match = sectionPattern.exec(line);
+        if (match) {
+            const existingTag = match[2] ?? '';
+            if (existingTag > tagName) {
+                insertIndex = i;
+                break;
+            }
+            insertIndex = i + 1;
+        }
+    }
+    if (insertIndex === -1) {
+        // No existing entries under this chrome sub-path. Fall back to end-of-file
+        // placement so the operator can reorder manually if desired.
+        insertIndex = lines.length;
+    }
+    lines.splice(insertIndex, 0, newEntry);
+    await writeText(filePath, lines.join('\n'));
+    return 1;
+}
+/** Detects locale jar.mn indentation by sampling an existing matching entry. */
+function detectLocaleJarMnIndent(lines, chromeSubPath) {
+    const escapedChrome = escapeForRegex(chromeSubPath);
+    const pattern = new RegExp(`^(\\s+)locale\\/(?:@AB_CD@|[a-zA-Z-]+)\\/${escapedChrome}\\/`);
+    for (const line of lines) {
+        const match = pattern.exec(line);
+        if (match?.[1])
+            return match[1];
+    }
+    // Fall back to detecting any existing `locale/...` indent before giving up.
+    for (const line of lines) {
+        const match = /^(\s+)locale\//.exec(line);
+        if (match?.[1])
+            return match[1];
+    }
+    return '  ';
+}
+/**
+ * Removes a locale jar.mn entry previously written by `addLocaleFtlJarMnEntry`.
+ * Idempotent — if the entry is absent or the file is missing, nothing happens.
+ */
+export async function removeLocaleFtlJarMnEntry(engineDir, jarMnRelPath, tagName, chromeSubPath) {
+    const filePath = join(engineDir, jarMnRelPath);
+    if (!(await pathExists(filePath))) {
+        return;
+    }
+    const content = await readText(filePath);
+    const lines = content.split('\n');
+    const pattern = new RegExp(`locale\\/(?:@AB_CD@|[a-zA-Z-]+)\\/${escapeForRegex(chromeSubPath)}\\/${escapeForRegex(tagName)}\\.ftl`);
+    const filtered = lines.filter((line) => !pattern.test(line));
+    if (filtered.length === lines.length)
+        return;
+    await writeText(filePath, filtered.join('\n'));
+}
 /**
  * Removes all jar.mn entries for a given tag name.
  *