@hominis/fireforge 0.9.0

package/dist/src/core/wire-destroy.js

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * browser-init.js — destroy expression in onUnload()/uninit().
+ */
+import { join } from 'node:path';
+import MagicString from 'magic-string';
+import { GeneralError } from '../errors/base.js';
+import { BuildError } from '../errors/build.js';
+import { pathExists, readText, writeText } from '../utils/fs.js';
+import { escapeRegex } from '../utils/regex.js';
+import { detectIndent, parseScript } from './ast-utils.js';
+import { withParserFallback } from './parser-fallback.js';
+import { extractNameFromExpression, findMethodBody, findMethodBraceIndex, validateWireName, } from './wire-utils.js';
+const BROWSER_INIT_JS = 'browser/base/content/browser-init.js';
+/**
+ * AST-based implementation: finds onUnload()/uninit() method body and
+ * inserts the destroy block at the top (LIFO ordering).
+ */
+export function addDestroyAST(content, expression) {
+    const name = extractNameFromExpression(expression);
+    const ast = parseScript(content);
+    const ms = new MagicString(content);
+    const body = findMethodBody(ast, ['onUnload', 'uninit']);
+    if (!body) {
+        throw new BuildError('Could not find onUnload/uninit method body via AST');
+    }
+    // Insert at top of method body (LIFO ordering)
+    const firstStmt = body.body[0];
+    let insertPos;
+    let indent;
+    if (firstStmt) {
+        insertPos = firstStmt.start;
+        indent = detectIndent(content, firstStmt.start);
+    }
+    else {
+        // Empty method body — insert after opening {
+        insertPos = body.start + 1;
+        indent = '    ';
+    }
+    const block = [
+        `${indent}// ${name} destroy`,
+        `${indent}try {`,
+        `${indent}  if (typeof ${name} !== "undefined") {`,
+        `${indent}    ${expression};`,
+        `${indent}  }`,
+        `${indent}} catch (e) {`,
+        `${indent}  console.error("${name} destroy failed:", e);`,
+        `${indent}}`,
+    ].join('\n');
+    ms.appendRight(insertPos, block + '\n');
+    return ms.toString();
+}
+/**
+ * Legacy regex/line-based implementation preserved as fallback.
+ */
+export function legacyAddDestroy(content, expression) {
+    const name = extractNameFromExpression(expression);
+    const lines = content.split('\n');
+    const destroyRegex = /\b(?:async\s+)?(onUnload|uninit)\s*[(:]/;
+    const found = findMethodBraceIndex(lines, destroyRegex);
+    if (!found) {
+        throw new GeneralError('Could not find "onUnload" or "uninit" method in browser-init.js.\n' +
+            'FireForge was looking for a signature matching: \\b(?:async\\s+)?(onUnload|uninit)\\s*[(:]');
+    }
+    const insertIndex = found.braceIndex + 1;
+    const block = [
+        `    // ${name} destroy`,
+        `    try {`,
+        `      if (typeof ${name} !== "undefined") {`,
+        `        ${expression};`,
+        `      }`,
+        `    } catch (e) {`,
+        `      console.error("${name} destroy failed:", e);`,
+        `    }`,
+    ];
+    lines.splice(insertIndex, 0, ...block);
+    return lines.join('\n');
+}
+/**
+ * Adds a destroy expression to the top of onUnload() or uninit() in
+ * browser-init.js (LIFO ordering — newest first).
+ *
+ * @param engineDir - Engine source root
+ * @param expression - The destroy expression (e.g., "MyComponent.destroy()")
+ * @returns true if added, false if already present
+ */
+export async function addDestroyToBrowserInit(engineDir, expression) {
+    validateWireName(expression, 'destroy expression');
+    const filePath = join(engineDir, BROWSER_INIT_JS);
+    if (!(await pathExists(filePath))) {
+        throw new GeneralError(`${BROWSER_INIT_JS} not found in engine`);
+    }
+    const content = await readText(filePath);
+    // Idempotency check — use word-boundary regex to avoid substring false positives
+    const destroyPattern = new RegExp(`(?:^|\\W)${escapeRegex(expression)}\\s*;?\\s*$`, 'm');
+    if (destroyPattern.test(content)) {
+        return false;
+    }
+    const { value } = withParserFallback(() => addDestroyAST(content, expression), () => legacyAddDestroy(content, expression), BROWSER_INIT_JS);
+    await writeText(filePath, value);
+    return true;
+}
+//# sourceMappingURL=wire-destroy.js.map

package/dist/src/core/wire-dom-fragment.d.ts

@@ -0,0 +1,23 @@
+/**
+ * browser.xhtml — DOM fragment insertion.
+ */
+/**
+ * Tokenizer-based implementation for DOM fragment insertion.
+ */
+export declare function addDomFragmentTokenized(content: string, includeDirective: string): string;
+/**
+ * Legacy line-based implementation preserved as fallback.
+ */
+export declare function legacyAddDomFragment(content: string, includeDirective: string): string;
+/**
+ * Inserts a `#include` directive for an `.inc.xhtml` file into browser.xhtml,
+ * before `#include browser-sets.inc`.
+ *
+ * If the file's content was previously inlined (detected by root element id=),
+ * the inlined block is automatically replaced with the `#include` directive.
+ *
+ * @param engineDir - Engine source root
+ * @param domFilePath - Path to the `.inc.xhtml` file relative to engine root
+ * @returns true if inserted, false if already present
+ */
+export declare function addDomFragment(engineDir: string, domFilePath: string): Promise<boolean>;

package/dist/src/core/wire-dom-fragment.js

@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * browser.xhtml — DOM fragment insertion.
+ */
+import { join, relative } from 'node:path';
+import { GeneralError } from '../errors/base.js';
+import { pathExists, readText, writeText } from '../utils/fs.js';
+import { toRootRelativePath } from '../utils/paths.js';
+import { escapeRegex } from '../utils/regex.js';
+import { withParserFallback } from './parser-fallback.js';
+import { tokenizeXhtml } from './wire-utils.js';
+const BROWSER_XHTML = 'browser/base/content/browser.xhtml';
+/**
+ * Tokenizer-based implementation for DOM fragment insertion.
+ */
+export function addDomFragmentTokenized(content, includeDirective) {
+    const lines = content.split('\n');
+    const tokens = tokenizeXhtml(lines);
+    // Find the #include browser-sets.inc token
+    let insertIndex = -1;
+    for (let i = 0; i < tokens.length; i++) {
+        const token = tokens[i];
+        if (token && token.type === 'macro' && token.raw.includes('browser-sets.inc')) {
+            insertIndex = i;
+            break;
+        }
+    }
+    if (insertIndex === -1) {
+        // Fallback: after <html:body>
+        for (let i = 0; i < tokens.length; i++) {
+            const token = tokens[i];
+            if (token && token.type === 'xml' && /<html:body/.test(token.raw)) {
+                insertIndex = i + 1;
+                break;
+            }
+        }
+    }
+    if (insertIndex === -1) {
+        throw new GeneralError('Could not find insertion point in browser.xhtml');
+    }
+    lines.splice(insertIndex, 0, includeDirective);
+    return lines.join('\n');
+}
+/**
+ * Legacy line-based implementation preserved as fallback.
+ */
+export function legacyAddDomFragment(content, includeDirective) {
+    const lines = content.split('\n');
+    let insertIndex = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (/browser-sets\.inc/.test(line)) {
+            insertIndex = i;
+            break;
+        }
+    }
+    if (insertIndex === -1) {
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i] ?? '';
+            if (/<html:body/.test(line)) {
+                insertIndex = i + 1;
+                break;
+            }
+        }
+    }
+    if (insertIndex === -1) {
+        throw new GeneralError('Could not find insertion point in browser.xhtml');
+    }
+    lines.splice(insertIndex, 0, includeDirective);
+    return lines.join('\n');
+}
+/**
+ * Inserts a `#include` directive for an `.inc.xhtml` file into browser.xhtml,
+ * before `#include browser-sets.inc`.
+ *
+ * If the file's content was previously inlined (detected by root element id=),
+ * the inlined block is automatically replaced with the `#include` directive.
+ *
+ * @param engineDir - Engine source root
+ * @param domFilePath - Path to the `.inc.xhtml` file relative to engine root
+ * @returns true if inserted, false if already present
+ */
+export async function addDomFragment(engineDir, domFilePath) {
+    const browserXhtmlPath = join(engineDir, BROWSER_XHTML);
+    const safeDomFilePath = toRootRelativePath(engineDir, domFilePath);
+    if (!(await pathExists(browserXhtmlPath))) {
+        throw new GeneralError(`${BROWSER_XHTML} not found in engine`);
+    }
+    // Compute include path relative to browser/base/content/ (where browser.xhtml lives)
+    const includePath = relative('browser/base/content', safeDomFilePath).replace(/\\/g, '/');
+    const includeDirective = `#include ${includePath}`;
+    let content = await readText(browserXhtmlPath);
+    // Idempotency: check if the #include directive already exists (line-anchored to avoid substring matches)
+    if (new RegExp(`^${escapeRegex(includeDirective)}$`, 'm').test(content)) {
+        return false;
+    }
+    // Migration: check if inlined content from this file exists (by id= match)
+    // and replace it with the #include directive
+    const domFileFullPath = join(engineDir, safeDomFilePath);
+    if (await pathExists(domFileFullPath)) {
+        const domContent = await readText(domFileFullPath);
+        const idMatch = /id\s*=\s*["']([^"']+)["']/.exec(domContent);
+        if (idMatch && content.includes(`id="${idMatch[1]}"`)) {
+            const lines = content.split('\n');
+            const rootId = idMatch[1];
+            const startIdx = lines.findIndex((l) => l.includes(`id="${rootId}"`));
+            if (startIdx !== -1) {
+                let endIdx = startIdx;
+                for (let i = startIdx; i < lines.length; i++) {
+                    const line = lines[i] ?? '';
+                    if (i > startIdx && (/^#include\s/.test(line.trim()) || line.trim() === '')) {
+                        endIdx = i;
+                        break;
+                    }
+                    endIdx = i + 1;
+                }
+                lines.splice(startIdx, endIdx - startIdx, includeDirective);
+                content = lines.join('\n');
+                await writeText(browserXhtmlPath, content);
+                return true;
+            }
+        }
+    }
+    // Normal insertion
+    const { value } = withParserFallback(() => addDomFragmentTokenized(content, includeDirective), () => legacyAddDomFragment(content, includeDirective), BROWSER_XHTML);
+    await writeText(browserXhtmlPath, value);
+    return true;
+}
+//# sourceMappingURL=wire-dom-fragment.js.map

package/dist/src/core/wire-init.d.ts

@@ -0,0 +1,23 @@
+/**
+ * browser-init.js — init expression in onLoad().
+ */
+/**
+ * AST-based implementation: finds onLoad() method body, locates existing
+ * fireforge init blocks (TryStatements containing typeof guards), and inserts
+ * after the correct position.
+ */
+export declare function addInitAST(content: string, expression: string, after?: string): string;
+/**
+ * Legacy regex/line-based implementation preserved as fallback.
+ */
+export declare function legacyAddInit(content: string, expression: string, after?: string): string;
+/**
+ * Adds an init expression as the first statement(s) in gBrowserInit.onLoad()
+ * in browser-init.js, after any previously-wired fireforge init blocks.
+ *
+ * @param engineDir - Engine source root
+ * @param expression - The init expression (e.g., "MyComponent.init()")
+ * @param after - Optional name to insert after (e.g., "MyComponent" to insert after its block)
+ * @returns true if added, false if already present
+ */
+export declare function addInitToBrowserInit(engineDir: string, expression: string, after?: string): Promise<boolean>;

package/dist/src/core/wire-init.js

@@ -0,0 +1,201 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * browser-init.js — init expression in onLoad().
+ */
+import { join } from 'node:path';
+import MagicString from 'magic-string';
+import { GeneralError } from '../errors/base.js';
+import { BuildError } from '../errors/build.js';
+import { pathExists, readText, writeText } from '../utils/fs.js';
+import { escapeRegex } from '../utils/regex.js';
+import { detectIndent, getNodeSource, parseScript } from './ast-utils.js';
+import { withParserFallback } from './parser-fallback.js';
+import { extractNameFromExpression, findInsertionAfterFireforgeBlocks, findMethodBody, findMethodBraceIndex, validateWireName, walkToTryBlockEnd, } from './wire-utils.js';
+const BROWSER_INIT_JS = 'browser/base/content/browser-init.js';
+/**
+ * AST-based implementation: finds onLoad() method body, locates existing
+ * fireforge init blocks (TryStatements containing typeof guards), and inserts
+ * after the correct position.
+ */
+export function addInitAST(content, expression, after) {
+    const name = extractNameFromExpression(expression);
+    const ast = parseScript(content);
+    const ms = new MagicString(content);
+    const body = findMethodBody(ast, 'onLoad');
+    if (!body) {
+        throw new BuildError('Could not find onLoad method body via AST');
+    }
+    // Collect fireforge try-catch blocks (those containing typeof guards)
+    const fireforgeBlocks = [];
+    for (const stmt of body.body) {
+        if (stmt.type === 'TryStatement') {
+            const tryNode = stmt;
+            const src = getNodeSource(content, tryNode);
+            if (/typeof\s+\w+\s*!==\s*"undefined"/.test(src)) {
+                fireforgeBlocks.push(tryNode);
+            }
+        }
+    }
+    let insertPos;
+    let indent;
+    if (after) {
+        // Find the specific fireforge block containing the --after target
+        const targetBlock = fireforgeBlocks.find((block) => {
+            const src = getNodeSource(content, block);
+            return src.includes(`typeof ${after}`) || src.includes(`${after}.init(`);
+        });
+        if (targetBlock) {
+            insertPos = targetBlock.end;
+            indent = detectIndent(content, targetBlock.start);
+        }
+        else {
+            // --after target not found: fall through to default (after last fireforge block)
+            if (fireforgeBlocks.length > 0) {
+                const lastBlock = fireforgeBlocks[fireforgeBlocks.length - 1];
+                if (!lastBlock)
+                    throw new GeneralError('Unexpected empty fireforgeBlocks array');
+                insertPos = lastBlock.end;
+                indent = detectIndent(content, lastBlock.start);
+            }
+            else {
+                // No fireforge blocks, insert at top of method body
+                const firstStmt = body.body[0];
+                if (firstStmt) {
+                    insertPos = firstStmt.start;
+                    indent = detectIndent(content, insertPos);
+                }
+                else {
+                    insertPos = body.start + 1;
+                    indent = '    ';
+                }
+            }
+        }
+    }
+    else {
+        // Default: insert after the last consecutive fireforge block at the start
+        if (fireforgeBlocks.length > 0) {
+            const lastBlock = fireforgeBlocks[fireforgeBlocks.length - 1];
+            if (!lastBlock)
+                throw new GeneralError('Unexpected empty fireforgeBlocks array');
+            insertPos = lastBlock.end;
+            indent = detectIndent(content, lastBlock.start);
+        }
+        else {
+            const firstStmt = body.body[0];
+            if (firstStmt) {
+                insertPos = firstStmt.start;
+                indent = detectIndent(content, insertPos);
+            }
+            else {
+                insertPos = body.start + 1;
+                indent = '    ';
+            }
+        }
+    }
+    const block = [
+        `${indent}// ${name} init — must be first, before Firefox subsystem`,
+        `${indent}// inits that reference native UI elements we hide.`,
+        `${indent}try {`,
+        `${indent}  if (typeof ${name} !== "undefined") {`,
+        `${indent}    ${expression};`,
+        `${indent}  }`,
+        `${indent}} catch (e) {`,
+        `${indent}  console.error("${name} init failed:", e);`,
+        `${indent}}`,
+    ].join('\n');
+    ms.appendRight(insertPos, '\n' + block + '\n');
+    return ms.toString();
+}
+/**
+ * Legacy regex/line-based implementation preserved as fallback.
+ */
+export function legacyAddInit(content, expression, after) {
+    const name = extractNameFromExpression(expression);
+    const lines = content.split('\n');
+    const onLoadRegex = /\b(?:async\s+)?onLoad\s*[(:]/;
+    const found = findMethodBraceIndex(lines, onLoadRegex);
+    if (!found) {
+        throw new GeneralError('Could not find "onLoad" method in browser-init.js.\n' +
+            'FireForge was looking for a signature matching: \\b(?:async\\s+)?onLoad\\s*[(:]');
+    }
+    const { braceIndex } = found;
+    let insertIndex = braceIndex + 1;
+    if (after) {
+        // Try to find the specific --after target block
+        let located = false;
+        for (let i = braceIndex + 1; i < lines.length; i++) {
+            const line = lines[i] ?? '';
+            if (line.includes(`typeof ${after}`) || line.includes(`${after}.init(`)) {
+                // Walk backward to find the enclosing try, including a preceding comment
+                let tryStart = i;
+                for (let k = i - 1; k > braceIndex; k--) {
+                    if (/\btry\s*\{/.test(lines[k] ?? '')) {
+                        tryStart = k;
+                        break;
+                    }
+                    if (/\/\//.test(lines[k] ?? '') && /\btry\s*\{/.test(lines[k + 1] ?? '')) {
+                        tryStart = k;
+                        break;
+                    }
+                }
+                insertIndex = walkToTryBlockEnd(lines, tryStart);
+                located = true;
+                break;
+            }
+        }
+        // If --after target not found, fall through to default fireforge block scan
+        if (!located) {
+            insertIndex = findInsertionAfterFireforgeBlocks(lines, braceIndex + 1, braceIndex);
+        }
+    }
+    else {
+        insertIndex = findInsertionAfterFireforgeBlocks(lines, braceIndex + 1, braceIndex);
+    }
+    // Detect indent from surrounding code instead of hardcoding
+    const refLine = lines
+        .slice(0, insertIndex)
+        .reverse()
+        .find((l) => l.trim());
+    const baseIndent = refLine?.match(/^(\s*)/)?.[1] ?? '    ';
+    const inner = baseIndent + '  ';
+    const inner2 = inner + '  ';
+    const block = [
+        `${baseIndent}// ${name} init — must be first, before Firefox subsystem`,
+        `${baseIndent}// inits that reference native UI elements we hide.`,
+        `${baseIndent}try {`,
+        `${inner}if (typeof ${name} !== "undefined") {`,
+        `${inner2}${expression};`,
+        `${inner}}`,
+        `${baseIndent}} catch (e) {`,
+        `${inner}console.error("${name} init failed:", e);`,
+        `${baseIndent}}`,
+    ];
+    lines.splice(insertIndex, 0, ...block);
+    return lines.join('\n');
+}
+/**
+ * Adds an init expression as the first statement(s) in gBrowserInit.onLoad()
+ * in browser-init.js, after any previously-wired fireforge init blocks.
+ *
+ * @param engineDir - Engine source root
+ * @param expression - The init expression (e.g., "MyComponent.init()")
+ * @param after - Optional name to insert after (e.g., "MyComponent" to insert after its block)
+ * @returns true if added, false if already present
+ */
+export async function addInitToBrowserInit(engineDir, expression, after) {
+    validateWireName(expression, 'init expression');
+    const filePath = join(engineDir, BROWSER_INIT_JS);
+    if (!(await pathExists(filePath))) {
+        throw new GeneralError(`${BROWSER_INIT_JS} not found in engine`);
+    }
+    const content = await readText(filePath);
+    // Idempotency check — use word-boundary regex to avoid substring false positives
+    const initPattern = new RegExp(`(?:^|\\W)${escapeRegex(expression)}\\s*;?\\s*$`, 'm');
+    if (initPattern.test(content)) {
+        return false;
+    }
+    const { value } = withParserFallback(() => addInitAST(content, expression, after), () => legacyAddInit(content, expression, after), BROWSER_INIT_JS);
+    await writeText(filePath, value);
+    return true;
+}
+//# sourceMappingURL=wire-init.js.map

package/dist/src/core/wire-subscript.d.ts

@@ -0,0 +1,20 @@
+/**
+ * browser-main.js — loadSubScript registration.
+ */
+/**
+ * AST-based implementation: finds the last try/catch containing
+ * `loadSubScript` and inserts a new try/catch block after it.
+ */
+export declare function addSubscriptAST(content: string, name: string): string;
+/**
+ * Legacy regex/line-based implementation preserved as fallback.
+ */
+export declare function legacyAddSubscript(content: string, name: string): string;
+/**
+ * Adds a loadSubScript entry to browser-main.js with try/catch error handling.
+ *
+ * @param engineDir - Engine source root
+ * @param name - Subscript name (without .js extension)
+ * @returns true if added, false if already present
+ */
+export declare function addSubscriptToBrowserMain(engineDir: string, name: string): Promise<boolean>;

package/dist/src/core/wire-subscript.js

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * browser-main.js — loadSubScript registration.
+ */
+import { join } from 'node:path';
+import MagicString from 'magic-string';
+import { GeneralError } from '../errors/base.js';
+import { BuildError } from '../errors/build.js';
+import { pathExists, readText, writeText } from '../utils/fs.js';
+import { detectIndent, getNodeSource, parseScript, walkAST, } from './ast-utils.js';
+import { withParserFallback } from './parser-fallback.js';
+import { findNearestTryLine, validateWireName, walkToTryBlockEnd } from './wire-utils.js';
+const BROWSER_MAIN_JS = 'browser/base/content/browser-main.js';
+/**
+ * AST-based implementation: finds the last try/catch containing
+ * `loadSubScript` and inserts a new try/catch block after it.
+ */
+export function addSubscriptAST(content, name) {
+    const ast = parseScript(content);
+    const ms = new MagicString(content);
+    // Collect all TryStatements containing loadSubScript
+    const tryNodes = [];
+    walkAST(ast, {
+        enter(node) {
+            if (node.type === 'TryStatement') {
+                const n = node;
+                const src = getNodeSource(content, n);
+                if (src.includes('loadSubScript')) {
+                    tryNodes.push(n);
+                }
+            }
+        },
+    });
+    let insertPos;
+    let indent;
+    if (tryNodes.length > 0) {
+        const lastTry = tryNodes[tryNodes.length - 1];
+        if (!lastTry)
+            throw new GeneralError('Unexpected empty tryNodes array');
+        insertPos = lastTry.end;
+        indent = detectIndent(content, lastTry.start);
+    }
+    else {
+        // No existing loadSubScript — insert before last standalone closing brace
+        // Use line-based search to avoid matching braces inside strings/comments
+        const allLines = content.split('\n');
+        let lastBrace = -1;
+        for (let i = allLines.length - 1; i >= 0; i--) {
+            if (allLines[i]?.trim() === '}') {
+                lastBrace = allLines.slice(0, i).join('\n').length + 1;
+                break;
+            }
+        }
+        if (lastBrace === -1) {
+            throw new BuildError('Could not find closing brace in browser-main.js');
+        }
+        insertPos = lastBrace;
+        indent = detectIndent(content, lastBrace);
+    }
+    const block = [
+        `${indent}try {`,
+        `${indent}  Services.scriptloader.loadSubScript("chrome://browser/content/${name}.js", this);`,
+        `${indent}} catch (e) {`,
+        `${indent}  console.error("Failed to load ${name}.js:", e);`,
+        `${indent}}`,
+    ].join('\n');
+    ms.appendRight(insertPos, '\n' + block + '\n');
+    return ms.toString();
+}
+/**
+ * Legacy regex/line-based implementation preserved as fallback.
+ */
+export function legacyAddSubscript(content, name) {
+    const lines = content.split('\n');
+    let lastSubScriptLine = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (/loadSubScript/.test(lines[i] ?? '')) {
+            lastSubScriptLine = i;
+        }
+    }
+    let insertIndex;
+    if (lastSubScriptLine !== -1) {
+        const tryStart = findNearestTryLine(lines, lastSubScriptLine - 1, -1);
+        insertIndex = tryStart !== -1 ? walkToTryBlockEnd(lines, tryStart) : lastSubScriptLine + 1;
+    }
+    else {
+        insertIndex = lines.length;
+        for (let i = lines.length - 1; i >= 0; i--) {
+            if (lines[i]?.trim() === '}') {
+                insertIndex = i;
+                break;
+            }
+        }
+    }
+    // Detect indent from surrounding code instead of hardcoding
+    const refLine = lines
+        .slice(0, insertIndex)
+        .reverse()
+        .find((l) => l.trim());
+    const ind = refLine?.match(/^(\s*)/)?.[1] ?? '  ';
+    const inner = ind + '  ';
+    const block = [
+        `${ind}try {`,
+        `${inner}Services.scriptloader.loadSubScript("chrome://browser/content/${name}.js", this);`,
+        `${ind}} catch (e) {`,
+        `${inner}console.error("Failed to load ${name}.js:", e);`,
+        `${ind}}`,
+    ];
+    lines.splice(insertIndex, 0, ...block);
+    return lines.join('\n');
+}
+/**
+ * Adds a loadSubScript entry to browser-main.js with try/catch error handling.
+ *
+ * @param engineDir - Engine source root
+ * @param name - Subscript name (without .js extension)
+ * @returns true if added, false if already present
+ */
+export async function addSubscriptToBrowserMain(engineDir, name) {
+    validateWireName(name, 'subscript name');
+    const filePath = join(engineDir, BROWSER_MAIN_JS);
+    if (!(await pathExists(filePath))) {
+        throw new GeneralError(`${BROWSER_MAIN_JS} not found in engine`);
+    }
+    const content = await readText(filePath);
+    // Idempotency check — include closing quote to avoid substring false positives
+    if (content.includes(`content/${name}.js"`)) {
+        return false;
+    }
+    const { value } = withParserFallback(() => addSubscriptAST(content, name), () => legacyAddSubscript(content, name), BROWSER_MAIN_JS);
+    await writeText(filePath, value);
+    return true;
+}
+//# sourceMappingURL=wire-subscript.js.map

package/dist/src/core/wire-targets.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Wire targets barrel — re-exports all wiring target modules.
+ */
+export { addDestroyAST, addDestroyToBrowserInit, legacyAddDestroy } from './wire-destroy.js';
+export { addDomFragment, addDomFragmentTokenized, legacyAddDomFragment, } from './wire-dom-fragment.js';
+export { addInitAST, addInitToBrowserInit, legacyAddInit } from './wire-init.js';
+export { addSubscriptAST, addSubscriptToBrowserMain, legacyAddSubscript, } from './wire-subscript.js';

package/dist/src/core/wire-targets.js

@@ -0,0 +1,9 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Wire targets barrel — re-exports all wiring target modules.
+ */
+export { addDestroyAST, addDestroyToBrowserInit, legacyAddDestroy } from './wire-destroy.js';
+export { addDomFragment, addDomFragmentTokenized, legacyAddDomFragment, } from './wire-dom-fragment.js';
+export { addInitAST, addInitToBrowserInit, legacyAddInit } from './wire-init.js';
+export { addSubscriptAST, addSubscriptToBrowserMain, legacyAddSubscript, } from './wire-subscript.js';
+//# sourceMappingURL=wire-targets.js.map