@hominis/fireforge 0.9.0

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

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Removal of custom element registrations from customElements.js.
+ * Supports three removal strategies: standalone callback, single-line array, multi-line array.
+ */
+import { join } from 'node:path';
+import { pathExists, readText, writeText } from '../utils/fs.js';
+import { CUSTOM_ELEMENTS_JS } from './furnace-constants.js';
+/**
+ * Removes a custom element registration from customElements.js.
+ *
+ * This operation is idempotent — if the tag is not registered or the file does
+ * not exist, nothing happens.
+ *
+ * @param engineDir - Path to the Firefox engine source root
+ * @param tagName - Custom element tag name to remove
+ */
+export async function removeCustomElementRegistration(engineDir, tagName) {
+    const filePath = join(engineDir, CUSTOM_ELEMENTS_JS);
+    if (!(await pathExists(filePath))) {
+        return;
+    }
+    let content = await readText(filePath);
+    const lines = content.split('\n');
+    // Strategy 1: Remove standalone callback block (setElementCreationCallback("tagName" …))
+    const callbackLine = lines.findIndex((l) => l.includes(`setElementCreationCallback("${tagName}"`));
+    if (callbackLine !== -1) {
+        let endLine = callbackLine;
+        for (let i = callbackLine + 1; i < lines.length; i++) {
+            const line = lines[i];
+            if (line === undefined)
+                continue;
+            if (/^\s*\}\);/.test(line)) {
+                endLine = i;
+                break;
+            }
+        }
+        let startLine = callbackLine;
+        const precedingLine = lines[startLine - 1];
+        if (startLine > 0 && precedingLine !== undefined && precedingLine.trim() === '') {
+            startLine--;
+        }
+        lines.splice(startLine, endLine - startLine + 1);
+        content = lines.join('\n');
+        await writeText(filePath, content);
+        return;
+    }
+    // Strategy 2: Remove single-line array entry  ["tagName", "..."],
+    const singleLineIdx = lines.findIndex((l) => new RegExp(`^\\s*\\["${tagName}",\\s*"[^"]*"\\],?\\s*$`).test(l));
+    if (singleLineIdx !== -1) {
+        lines.splice(singleLineIdx, 1);
+        content = lines.join('\n');
+        await writeText(filePath, content);
+        return;
+    }
+    // Strategy 3: Remove multi-line array entry where "tagName", is on its own line
+    const multiLineTagIdx = lines.findIndex((l) => new RegExp(`^\\s*"${tagName}",\\s*$`).test(l));
+    if (multiLineTagIdx !== -1) {
+        // Scan backwards from the tag line to find the opening [ (bounded to 20 lines)
+        let startLine = multiLineTagIdx;
+        const scanLimit = Math.max(0, multiLineTagIdx - 20);
+        for (let i = multiLineTagIdx - 1; i >= scanLimit; i--) {
+            const line = lines[i];
+            if (line !== undefined && /^\s*\[$/.test(line)) {
+                startLine = i;
+                break;
+            }
+        }
+        const openIndent = (lines[startLine] ?? '').match(/^(\s*)/)?.[1]?.length ?? 0;
+        // Scan forwards from the tag line to find the closing ],
+        let endLine = multiLineTagIdx;
+        for (let i = multiLineTagIdx + 1; i < lines.length; i++) {
+            const line = lines[i];
+            if (line !== undefined && /^\s*\],?\s*$/.test(line)) {
+                const closeIndent = line.match(/^(\s*)/)?.[1]?.length ?? 0;
+                if (closeIndent === openIndent) {
+                    endLine = i;
+                    break;
+                }
+            }
+        }
+        lines.splice(startLine, endLine - startLine + 1);
+        content = lines.join('\n');
+        await writeText(filePath, content);
+        return;
+    }
+    // Tag not found in any form — idempotent no-op
+}
+//# sourceMappingURL=furnace-registration-remove.js.map

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

@@ -0,0 +1,20 @@
+/**
+ * Shared validation for furnace custom element registration placement.
+ * Used after both AST and legacy code paths to avoid duplicating logic.
+ */
+/** Regex for valid custom element tag names. */
+export declare const CUSTOM_ELEMENT_TAG_PATTERN: RegExp;
+/**
+ * Validates that a tag name conforms to custom element naming requirements.
+ * @throws FurnaceError if the tag name is invalid
+ */
+export declare function validateTagName(tagName: string): void;
+/**
+ * Validates that a registration entry landed in the correct block
+ * (Pattern A = loadSubScript, Pattern B = DOMContentLoaded/importESModule).
+ *
+ * @param result - The full file content after insertion
+ * @param tagName - The tag that was inserted
+ * @param isESModule - Whether the module uses ESM (Pattern B) or not (Pattern A)
+ */
+export declare function validateRegistrationPlacement(result: string, tagName: string, isESModule: boolean): void;

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

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Shared validation for furnace custom element registration placement.
+ * Used after both AST and legacy code paths to avoid duplicating logic.
+ */
+import { FurnaceError } from '../errors/furnace.js';
+/** Regex for valid custom element tag names. */
+export const CUSTOM_ELEMENT_TAG_PATTERN = /^[a-z][a-z0-9]*-[a-z0-9-]*$/;
+/**
+ * Validates that a tag name conforms to custom element naming requirements.
+ * @throws FurnaceError if the tag name is invalid
+ */
+export function validateTagName(tagName) {
+    if (!CUSTOM_ELEMENT_TAG_PATTERN.test(tagName)) {
+        throw new FurnaceError(`Invalid tag name "${tagName}": must contain a hyphen and match /^[a-z][a-z0-9]*-[a-z0-9-]*$/`, tagName);
+    }
+}
+/**
+ * Validates that a registration entry landed in the correct block
+ * (Pattern A = loadSubScript, Pattern B = DOMContentLoaded/importESModule).
+ *
+ * @param result - The full file content after insertion
+ * @param tagName - The tag that was inserted
+ * @param isESModule - Whether the module uses ESM (Pattern B) or not (Pattern A)
+ */
+export function validateRegistrationPlacement(result, tagName, isESModule) {
+    const dclPattern = /document\.addEventListener\(\s*["']DOMContentLoaded["']/;
+    const insertedPos = result.lastIndexOf(`"${tagName}"`);
+    if (insertedPos === -1)
+        return;
+    const contentBeforeTag = result.slice(0, insertedPos);
+    const hasDCLBefore = dclPattern.test(contentBeforeTag);
+    if (isESModule && !hasDCLBefore) {
+        throw new FurnaceError(`${tagName} was registered in the loadSubScript block (Pattern A) instead of the DOMContentLoaded/importESModule block (Pattern B). This will cause the component to fail at runtime. The customElements.js file structure may have changed upstream — manual intervention required.`, tagName);
+    }
+    if (!isESModule && hasDCLBefore) {
+        throw new FurnaceError(`${tagName} was registered in the DOMContentLoaded/importESModule block (Pattern B) instead of the loadSubScript block (Pattern A). This will cause the component to fail at runtime. The customElements.js file structure may have changed upstream — manual intervention required.`, tagName);
+    }
+}
+//# sourceMappingURL=furnace-registration-validate.js.map

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

@@ -0,0 +1,29 @@
+export { CUSTOM_ELEMENTS_JS, JAR_MN } from './furnace-constants.js';
+export { addCustomElementRegistration, removeCustomElementRegistration, } from './furnace-registration-ast.js';
+/**
+ * Adds jar.mn entries that map chrome:// URIs to on-disk paths for a
+ * component's files.
+ *
+ * Entry format (3-space indent, spaces not tabs):
+ * ```
+ *    content/global/elements/{file}  (widgets/{tagName}/{file})
+ * ```
+ *
+ * New entries are inserted in alphabetical order relative to existing
+ * `content/global/elements/` entries. The operation is idempotent.
+ *
+ * @param engineDir - Path to the Firefox engine source root
+ * @param tagName - Custom element tag name
+ * @param files - Filenames to register (e.g. ["moz-widget.mjs", "moz-widget.css"])
+ */
+export declare function addJarMnEntries(engineDir: string, tagName: string, files: string[]): Promise<void>;
+/**
+ * Removes all jar.mn entries for a given tag name.
+ *
+ * This operation is idempotent — if no entries exist or the file is missing,
+ * nothing happens.
+ *
+ * @param engineDir - Path to the Firefox engine source root
+ * @param tagName - Custom element tag name whose entries should be removed
+ */
+export declare function removeJarMnEntries(engineDir: string, tagName: string): Promise<void>;

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

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { join } from 'node:path';
+import { FurnaceError } from '../errors/furnace.js';
+import { pathExists, readText, writeText } from '../utils/fs.js';
+// Re-export everything from the AST module so existing imports keep working
+export { CUSTOM_ELEMENTS_JS, JAR_MN } from './furnace-constants.js';
+export { addCustomElementRegistration, removeCustomElementRegistration, } from './furnace-registration-ast.js';
+import { JAR_MN } from './furnace-constants.js';
+/**
+ * Adds jar.mn entries that map chrome:// URIs to on-disk paths for a
+ * component's files.
+ *
+ * Entry format (3-space indent, spaces not tabs):
+ * ```
+ *    content/global/elements/{file}  (widgets/{tagName}/{file})
+ * ```
+ *
+ * New entries are inserted in alphabetical order relative to existing
+ * `content/global/elements/` entries. The operation is idempotent.
+ *
+ * @param engineDir - Path to the Firefox engine source root
+ * @param tagName - Custom element tag name
+ * @param files - Filenames to register (e.g. ["moz-widget.mjs", "moz-widget.css"])
+ */
+export async function addJarMnEntries(engineDir, tagName, files) {
+    const filePath = join(engineDir, JAR_MN);
+    if (!(await pathExists(filePath))) {
+        throw new FurnaceError('jar.mn not found in engine', tagName);
+    }
+    let content = await readText(filePath);
+    const lines = content.split('\n');
+    // Filter to files not already registered
+    const newFiles = files.filter((f) => !content.includes(`content/global/elements/${f}`));
+    if (newFiles.length === 0)
+        return;
+    // Build new entry lines
+    const newEntries = newFiles.map((f) => `   content/global/elements/${f}  (widgets/${tagName}/${f})`);
+    // Find insertion point among existing content/global/elements/ lines
+    const elementLinePattern = /^\s+content\/global\/elements\/([^.]+)\./;
+    let insertIndex = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === undefined)
+            continue;
+        const match = elementLinePattern.exec(line);
+        if (match) {
+            const existingTag = match[1] ?? '';
+            if (existingTag > tagName) {
+                insertIndex = i;
+                break;
+            }
+            // Track last element entry line as fallback (insert after it)
+            insertIndex = i + 1;
+        }
+    }
+    if (insertIndex === -1) {
+        // Fallback: find last content/global/ line
+        for (let i = lines.length - 1; i >= 0; i--) {
+            const line = lines[i];
+            if (line !== undefined && /^\s+content\/global\//.test(line)) {
+                insertIndex = i + 1;
+                break;
+            }
+        }
+    }
+    if (insertIndex === -1) {
+        throw new FurnaceError('Could not find insertion point in jar.mn for element entries', tagName);
+    }
+    lines.splice(insertIndex, 0, ...newEntries);
+    content = lines.join('\n');
+    await writeText(filePath, content);
+}
+/**
+ * Removes all jar.mn entries for a given tag name.
+ *
+ * This operation is idempotent — if no entries exist or the file is missing,
+ * nothing happens.
+ *
+ * @param engineDir - Path to the Firefox engine source root
+ * @param tagName - Custom element tag name whose entries should be removed
+ */
+export async function removeJarMnEntries(engineDir, tagName) {
+    const filePath = join(engineDir, JAR_MN);
+    if (!(await pathExists(filePath))) {
+        return;
+    }
+    let content = await readText(filePath);
+    const lines = content.split('\n');
+    const pattern = `content/global/elements/${tagName}.`;
+    const filtered = lines.filter((line) => !line.includes(pattern));
+    if (filtered.length === lines.length)
+        return;
+    content = filtered.join('\n');
+    await writeText(filePath, content);
+}
+//# sourceMappingURL=furnace-registration.js.map

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

@@ -0,0 +1,20 @@
+interface FileSnapshot {
+    existed: boolean;
+    content?: Uint8Array;
+    mode?: number;
+}
+export interface RollbackJournal {
+    files: Map<string, FileSnapshot>;
+    createdDirs: Set<string>;
+}
+/** Creates an empty rollback journal for tracking touched files and created directories. */
+export declare function createRollbackJournal(): RollbackJournal;
+/** Records a directory that should be removed if the operation later rolls back. */
+export declare function recordCreatedDir(journal: RollbackJournal, dirPath: string): void;
+/** Snapshots a file once so rollback can restore its previous contents or absence. */
+export declare function snapshotFile(journal: RollbackJournal, filePath: string): Promise<void>;
+/** Restores all snapshotted files and removes directories created during the operation. */
+export declare function restoreRollbackJournal(journal: RollbackJournal): Promise<void>;
+/** Restores a rollback journal and wraps rollback failures in a FurnaceError. */
+export declare function restoreRollbackJournalOrThrow(journal: RollbackJournal, context: string): Promise<void>;
+export {};

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

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { chmod, mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { FurnaceError } from '../errors/furnace.js';
+import { toError } from '../utils/errors.js';
+import { pathExists } from '../utils/fs.js';
+/** Creates an empty rollback journal for tracking touched files and created directories. */
+export function createRollbackJournal() {
+    return {
+        files: new Map(),
+        createdDirs: new Set(),
+    };
+}
+/** Records a directory that should be removed if the operation later rolls back. */
+export function recordCreatedDir(journal, dirPath) {
+    journal.createdDirs.add(dirPath);
+}
+/** Snapshots a file once so rollback can restore its previous contents or absence. */
+export async function snapshotFile(journal, filePath) {
+    if (journal.files.has(filePath)) {
+        return;
+    }
+    if (!(await pathExists(filePath))) {
+        journal.files.set(filePath, { existed: false });
+        return;
+    }
+    const [content, fileStat] = await Promise.all([readFile(filePath), stat(filePath)]);
+    journal.files.set(filePath, {
+        existed: true,
+        content,
+        mode: fileStat.mode,
+    });
+}
+async function restoreFile(filePath, snapshot) {
+    if (!snapshot.existed) {
+        await rm(filePath, { force: true });
+        return;
+    }
+    await mkdir(dirname(filePath), { recursive: true });
+    await writeFile(filePath, snapshot.content ?? new Uint8Array());
+    if (snapshot.mode !== undefined) {
+        await chmod(filePath, snapshot.mode);
+    }
+}
+/** Restores all snapshotted files and removes directories created during the operation. */
+export async function restoreRollbackJournal(journal) {
+    const fileEntries = [...journal.files.entries()].sort(([left], [right]) => right.length - left.length);
+    for (const [filePath, snapshot] of fileEntries) {
+        await restoreFile(filePath, snapshot);
+    }
+    const createdDirs = [...journal.createdDirs].sort((left, right) => right.length - left.length);
+    for (const dirPath of createdDirs) {
+        await rm(dirPath, { recursive: true, force: true });
+    }
+}
+/** Restores a rollback journal and wraps rollback failures in a FurnaceError. */
+export async function restoreRollbackJournalOrThrow(journal, context) {
+    try {
+        await restoreRollbackJournal(journal);
+    }
+    catch (error) {
+        const message = toError(error).message;
+        throw new FurnaceError(`${context}; automatic rollback failed: ${message}`);
+    }
+}
+//# sourceMappingURL=furnace-rollback.js.map

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

@@ -0,0 +1,40 @@
+import type { ScannedComponent } from '../types/furnace.js';
+/**
+ * Parses customElements.js to extract tag-to-module mappings.
+ *
+ * Looks for registration patterns like:
+ * ```
+ * lazy.customElements.setElementCreationCallback("moz-button", () => {
+ *   import("chrome://global/content/elements/moz-button.mjs");
+ * });
+ * ```
+ *
+ * @param engineDir - Path to the Firefox engine source root
+ * @returns Map of tagName to module path
+ */
+export declare function scanCustomElementsRegistrations(engineDir: string): Promise<Map<string, string>>;
+/**
+ * Scans the widgets directory to discover all MozLitElement custom elements.
+ *
+ * Each subdirectory starting with `moz-` that contains a `.mjs` file is
+ * considered a component. For each component, checks whether it has associated
+ * CSS, Fluent localization, and customElements.js registration.
+ *
+ * @param engineDir - Path to the Firefox engine source root
+ * @returns Array of discovered components
+ */
+export declare function scanWidgetsDirectory(engineDir: string): Promise<ScannedComponent[]>;
+/**
+ * Gets detailed information about a single component by tag name.
+ * @param engineDir - Path to the Firefox engine source root
+ * @param tagName - Component tag name (e.g., "moz-button")
+ * @returns Component details, or null if not found in the source tree
+ */
+export declare function getComponentDetails(engineDir: string, tagName: string): Promise<ScannedComponent | null>;
+/**
+ * Checks whether a component directory exists in the engine source tree.
+ * @param engineDir - Path to the Firefox engine source root
+ * @param tagName - Component tag name (e.g., "moz-button")
+ * @returns True if the component directory exists
+ */
+export declare function isComponentInEngine(engineDir: string, tagName: string): Promise<boolean>;

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

@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pathExists, readText } from '../utils/fs.js';
+import { CUSTOM_ELEMENTS_JS } from './furnace-constants.js';
+/** Path to the widgets directory within the engine source tree */
+const WIDGETS_DIR = 'toolkit/content/widgets';
+/** Path to the Fluent localization directory for toolkit global components */
+const FTL_DIR = 'toolkit/locales/en-US/toolkit/global';
+/**
+ * Parses customElements.js to extract tag-to-module mappings.
+ *
+ * Looks for registration patterns like:
+ * ```
+ * lazy.customElements.setElementCreationCallback("moz-button", () => {
+ *   import("chrome://global/content/elements/moz-button.mjs");
+ * });
+ * ```
+ *
+ * @param engineDir - Path to the Firefox engine source root
+ * @returns Map of tagName to module path
+ */
+export async function scanCustomElementsRegistrations(engineDir) {
+    const registrations = new Map();
+    const filePath = join(engineDir, CUSTOM_ELEMENTS_JS);
+    if (!(await pathExists(filePath))) {
+        return registrations;
+    }
+    const content = await readText(filePath);
+    const lines = content.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line === undefined)
+            continue;
+        const callbackMatch = /setElementCreationCallback\(\s*"([^"]+)"/.exec(line);
+        if (!callbackMatch?.[1])
+            continue;
+        const tagName = callbackMatch[1];
+        let modulePath = '';
+        // Search the following lines for an import() statement
+        const searchEnd = Math.min(i + 5, lines.length);
+        for (let j = i + 1; j < searchEnd; j++) {
+            const importLine = lines[j];
+            if (importLine === undefined)
+                continue;
+            const importMatch = /import\(\s*"([^"]+)"/.exec(importLine);
+            if (importMatch?.[1]) {
+                modulePath = importMatch[1];
+                break;
+            }
+        }
+        if (!modulePath) {
+            // No module path found in the lookahead lines; skip this entry
+            continue;
+        }
+        registrations.set(tagName, modulePath);
+    }
+    return registrations;
+}
+/**
+ * Scans the widgets directory to discover all MozLitElement custom elements.
+ *
+ * Each subdirectory starting with `moz-` that contains a `.mjs` file is
+ * considered a component. For each component, checks whether it has associated
+ * CSS, Fluent localization, and customElements.js registration.
+ *
+ * @param engineDir - Path to the Firefox engine source root
+ * @returns Array of discovered components
+ */
+export async function scanWidgetsDirectory(engineDir) {
+    const widgetsPath = join(engineDir, WIDGETS_DIR);
+    if (!(await pathExists(widgetsPath))) {
+        return [];
+    }
+    const entries = await readdir(widgetsPath, { withFileTypes: true });
+    const registrations = await scanCustomElementsRegistrations(engineDir);
+    const components = [];
+    for (const entry of entries) {
+        if (!entry.isDirectory() || !entry.name.startsWith('moz-')) {
+            continue;
+        }
+        const tagName = entry.name;
+        const componentDir = join(widgetsPath, tagName);
+        const componentEntries = await readdir(componentDir, { withFileTypes: true });
+        // Only include directories that contain a .mjs file
+        const hasMjs = componentEntries.some((e) => e.isFile() && e.name.endsWith('.mjs'));
+        if (!hasMjs) {
+            continue;
+        }
+        const hasCSS = componentEntries.some((e) => e.isFile() && e.name.endsWith('.css'));
+        const ftlPath = join(engineDir, FTL_DIR, `${tagName}.ftl`);
+        const hasFTL = await pathExists(ftlPath);
+        const isRegistered = registrations.has(tagName);
+        components.push({
+            tagName,
+            sourcePath: join(WIDGETS_DIR, tagName),
+            hasCSS,
+            hasFTL,
+            isRegistered,
+        });
+    }
+    return components;
+}
+/**
+ * Gets detailed information about a single component by tag name.
+ * @param engineDir - Path to the Firefox engine source root
+ * @param tagName - Component tag name (e.g., "moz-button")
+ * @returns Component details, or null if not found in the source tree
+ */
+export async function getComponentDetails(engineDir, tagName) {
+    const componentDir = join(engineDir, WIDGETS_DIR, tagName);
+    if (!(await pathExists(componentDir))) {
+        return null;
+    }
+    const entries = await readdir(componentDir, { withFileTypes: true });
+    const hasMjs = entries.some((e) => e.isFile() && e.name.endsWith('.mjs'));
+    if (!hasMjs) {
+        return null;
+    }
+    const hasCSS = entries.some((e) => e.isFile() && e.name.endsWith('.css'));
+    const ftlPath = join(engineDir, FTL_DIR, `${tagName}.ftl`);
+    const hasFTL = await pathExists(ftlPath);
+    const registrations = await scanCustomElementsRegistrations(engineDir);
+    const isRegistered = registrations.has(tagName);
+    return {
+        tagName,
+        sourcePath: join(WIDGETS_DIR, tagName),
+        hasCSS,
+        hasFTL,
+        isRegistered,
+    };
+}
+/**
+ * Checks whether a component directory exists in the engine source tree.
+ * @param engineDir - Path to the Firefox engine source root
+ * @param tagName - Component tag name (e.g., "moz-button")
+ * @returns True if the component directory exists
+ */
+export async function isComponentInEngine(engineDir, tagName) {
+    const componentDir = join(engineDir, WIDGETS_DIR, tagName);
+    return pathExists(componentDir);
+}
+//# sourceMappingURL=furnace-scanner.js.map

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

@@ -0,0 +1,37 @@
+import type { ComponentType, SyncResult } from '../types/furnace.js';
+/**
+ * Generates the full content of a Storybook `.stories.mjs` file for a
+ * Furnace component.
+ *
+ * @param tagName - Component tag name (e.g. "moz-button")
+ * @param displayName - Human-readable name (e.g. "Button")
+ * @param type - Component classification (stock, override, custom)
+ * @returns Complete story file content
+ */
+export declare function generateStoryContent(tagName: string, displayName: string, type: ComponentType, licenseHeader?: string, modulePath?: string): string;
+/**
+ * Returns the path to the Storybook stories directory in the engine.
+ *
+ * @param engineDir - Path to the Firefox engine source root
+ * @returns Absolute path to `browser/components/storybook/stories/`
+ */
+export declare function getStoriesDir(engineDir: string): string;
+/**
+ * Synchronises Storybook story files for all Furnace-managed components.
+ *
+ * - Stock components: story created only if not already present.
+ * - Override components: story always regenerated.
+ * - Custom components: story always regenerated.
+ * - Stale story files (for components no longer in furnace.json) are removed.
+ *
+ * @param root - Root directory of the project
+ * @returns Summary of created, updated, and removed story files
+ */
+export declare function syncStories(root: string): Promise<SyncResult>;
+/**
+ * Removes the entire `stories/furnace/` directory from the engine.
+ *
+ * @param engineDir - Path to the Firefox engine source root
+ * @returns Number of files that were removed
+ */
+export declare function cleanStories(engineDir: string): Promise<number>;