@hominis/fireforge 0.45.0 → 0.46.1

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

@@ -12,7 +12,7 @@
  *
  * Matches any of:
  *   1. `setElementCreationCallback("tag"` / `setElementCreationCallback('tag'`
- *   2. Single-line array entry: `["tag", "..."]` — column 0 only, comments allowed after
+ *   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
  */
 export declare function isTagAlreadyRegistered(content: string, tagName: string): boolean;
@@ -28,7 +28,6 @@ export interface RegistrationWriteOptions {
      */
     markerComment?: string;
 }
-export { removeCustomElementRegistration } from './furnace-registration-remove.js';
 /**
  * Adds a custom element registration entry to customElements.js.
  *
@@ -39,7 +38,7 @@ export { removeCustomElementRegistration } from './furnace-registration-remove.j
  * ```
  *
  * New entries are inserted in alphabetical order relative to existing entries.
- * This operation is idempotent — if the tag is already registered the file is
+ * This operation is idempotent: if the tag is already registered the file is
  * left unchanged.
  *
  * @param engineDir - Path to the Firefox engine source root

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

@@ -23,7 +23,7 @@ import { validateRegistrationPlacement, validateTagName } from './furnace-regist
  *
  * Matches any of:
  *   1. `setElementCreationCallback("tag"` / `setElementCreationCallback('tag'`
- *   2. Single-line array entry: `["tag", "..."]` — column 0 only, comments allowed after
+ *   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
  */
 export function isTagAlreadyRegistered(content, tagName) {
@@ -46,9 +46,6 @@ function formatMarkerSuffix(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
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -237,8 +234,8 @@ function addRegistrationAST(content, tagName, modulePath, isESModule, markerComm
  * fails. Finds the last existing `["tag", "path"],` line in the appropriate
  * block and inserts the new entry after it in alphabetical order.
  *
- * This is intentionally less precise than the AST approach — it does not
- * validate indentation or multi-line format — but it is robust against
+ * This is intentionally less precise than the AST approach (it does not
+ * validate indentation or multi-line format), but it is robust against
  * upstream syntax changes that break the parser.
  */
 function addRegistrationRegexFallback(content, tagName, modulePath, isESModule, markerComment) {
@@ -300,7 +297,7 @@ function hasRecognizableRegistrationLoop(content) {
  * ```
  *
  * New entries are inserted in alphabetical order relative to existing entries.
- * This operation is idempotent — if the tag is already registered the file is
+ * This operation is idempotent: if the tag is already registered the file is
  * left unchanged.
  *
  * @param engineDir - Path to the Firefox engine source root
@@ -315,13 +312,13 @@ export async function addCustomElementRegistration(engineDir, tagName, modulePat
     const content = await readText(filePath);
     // 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
+    // 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.
+    // Validate upfront. Tag name errors must not fall through to the regex fallback.
     validateTagName(tagName);
     const isESModule = modulePath.endsWith('.mjs');
     // Cheap pre-flight: the AST walker assumes the file contains at least one
@@ -329,7 +326,7 @@ export async function addCustomElementRegistration(engineDir, tagName, modulePat
     // right-hand side, and (for ESM tags) at least one such loop inside a
     // `document.addEventListener("DOMContentLoaded", ...)` block. If either
     // assumption is violated the AST path errors with a confusing
-    // "Could not find DOMContentLoaded block" message — fail fast here with
+    // "Could not find DOMContentLoaded block" message, so fail fast here with
     // actionable guidance instead.
     if (!hasRecognizableRegistrationLoop(content)) {
         throw new FurnaceError(`${CUSTOM_ELEMENTS_JS} does not contain a recognizable registration loop; refusing to mutate. ` +
@@ -345,7 +342,7 @@ export async function addCustomElementRegistration(engineDir, tagName, modulePat
     }
     catch (error) {
         if (error instanceof FurnaceError) {
-            // AST structural errors (missing DOMContentLoaded block, etc.) — try regex fallback
+            // AST structural errors (missing DOMContentLoaded block, etc.): try regex fallback
             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 {
@@ -399,7 +396,7 @@ export async function validateCustomElementRegistration(engineDir, tagName, modu
         addRegistrationAST(content, tagName, modulePath, isESModule);
     }
     catch {
-        // Validation only — if AST fails, try regex to see if the entry could be placed
+        // Validation only: if AST fails, try regex to see if the entry could be placed
         addRegistrationRegexFallback(content, tagName, modulePath, isESModule);
     }
 }

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

@@ -4,8 +4,8 @@
  * Uses the same AST parser as the add path (`furnace-registration-ast.ts`) to
  * locate and delete registration entries. A line-by-line scan with a bounded
  * bracket match only works against Firefox's stock formatting and fails
- * silently on a hand-reformatted customElements.js; AST-based bracket
- * matching is format-agnostic by construction.
+ * silently on a hand-reformatted customElements.js. AST-based bracket
+ * matching does not depend on the file's formatting.
  *
  * Contract:
  * - Idempotent: if the tag is not registered, the file is left unchanged.
@@ -23,10 +23,10 @@
 /**
  * Removes a custom element registration from customElements.js.
  *
- * This operation is idempotent — if the tag is not registered or the file
+ * This operation is idempotent: if the tag is not registered or the file
  * does not exist, nothing happens. If the file exists but cannot be parsed,
  * the file is left unchanged rather than fall back to a line-based
- * heuristic; a corrupted customElements.js is a doctor problem, not
+ * heuristic. A corrupted customElements.js is a doctor problem, not
  * something `furnace remove` should "helpfully" edit around.
  *
  * @param engineDir - Path to the Firefox engine source root

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

@@ -5,8 +5,8 @@
  * Uses the same AST parser as the add path (`furnace-registration-ast.ts`) to
  * locate and delete registration entries. A line-by-line scan with a bounded
  * bracket match only works against Firefox's stock formatting and fails
- * silently on a hand-reformatted customElements.js; AST-based bracket
- * matching is format-agnostic by construction.
+ * silently on a hand-reformatted customElements.js. AST-based bracket
+ * matching does not depend on the file's formatting.
  *
  * Contract:
  * - Idempotent: if the tag is not registered, the file is left unchanged.
@@ -49,7 +49,7 @@ function expandRemovalRange(content, start, end) {
     }
     // Consume a trailing inline comment up to end-of-line so we do not leave
     // the comment marooned on its own line. A leading inline comment is left
-    // alone — it may belong to the next entry.
+    // alone, because it may belong to the next entry.
     while (expandedEnd < content.length &&
         (content[expandedEnd] === ' ' || content[expandedEnd] === '\t')) {
         expandedEnd++;
@@ -88,7 +88,7 @@ function expandRemovalRange(content, start, end) {
 }
 /**
  * Returns true if `node` represents a `[tag, module]` entry inside a
- * registration array — i.e. an `ArrayExpression` whose first element is a
+ * registration array, i.e. an `ArrayExpression` whose first element is a
  * string literal equal to `tagName`. Callers still have to verify the
  * parent is the outer registration array so we do not accidentally delete
  * an arbitrary user-owned `["moz-card", ...]` literal elsewhere in the file.
@@ -176,10 +176,10 @@ function collectRemovalRanges(ast, content, tagName) {
 /**
  * Removes a custom element registration from customElements.js.
  *
- * This operation is idempotent — if the tag is not registered or the file
+ * This operation is idempotent: if the tag is not registered or the file
  * does not exist, nothing happens. If the file exists but cannot be parsed,
  * the file is left unchanged rather than fall back to a line-based
- * heuristic; a corrupted customElements.js is a doctor problem, not
+ * heuristic. A corrupted customElements.js is a doctor problem, not
  * something `furnace remove` should "helpfully" edit around.
  *
  * @param engineDir - Path to the Firefox engine source root

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

@@ -25,8 +25,8 @@ export declare function validateTagName(tagName: string): void;
  * Returns why `tagName` is invalid, or `undefined` when it is fine.
  *
  * The message-returning half of {@link validateTagName}, for callers that
- * must not throw — specifically clack `validate` callbacks, which expect a
- * returned string and re-prompt on it. Passing the THROWING form to one
+ * must not throw, specifically clack `validate` callbacks, which expect a
+ * returned string and re-prompt on it. Passing the throwing form to one
  * makes an invalid tag name escape clack's validation loop as a
  * `FurnaceError`, killing the prompt instead of showing the rule inline.
  *

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

@@ -33,8 +33,8 @@ export function validateTagName(tagName) {
  * Returns why `tagName` is invalid, or `undefined` when it is fine.
  *
  * The message-returning half of {@link validateTagName}, for callers that
- * must not throw — specifically clack `validate` callbacks, which expect a
- * returned string and re-prompt on it. Passing the THROWING form to one
+ * must not throw, specifically clack `validate` callbacks, which expect a
+ * returned string and re-prompt on it. Passing the throwing form to one
  * makes an invalid tag name escape clack's validation loop as a
  * `FurnaceError`, killing the prompt instead of showing the rule inline.
  *

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

@@ -1,4 +1,5 @@
-export { addCustomElementRegistration, removeCustomElementRegistration, validateCustomElementRegistration, } from './furnace-registration-ast.js';
+export { addCustomElementRegistration, validateCustomElementRegistration, } from './furnace-registration-ast.js';
+export { removeCustomElementRegistration } from './furnace-registration-remove.js';
 /**
  * Adds jar.mn entries that map chrome:// URIs to on-disk paths for a
  * component's files.
@@ -16,7 +17,7 @@ export { addCustomElementRegistration, removeCustomElementRegistration, validate
  *   `content/global/elements/` line. Falls back to 3 spaces when no
  *   reference line exists.
  * - **Insertion point**: identified by existing lines matching the regex
- *   `^\s+content\/global\/elements\/([^.]+)\.` — new entries are inserted
+ *   `^\s+content\/global\/elements\/([^.]+)\.`. New entries are inserted
  *   in alphabetical order relative to these.
  * - **Fallback**: if no `content/global/elements/` line exists (empty
  *   project), looks for any `content/global/` line and inserts after it.
@@ -41,7 +42,7 @@ export declare function addJarMnEntries(engineDir: string, tagName: string, file
  * 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`)
+ * 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.
  *
@@ -58,13 +59,13 @@ export declare function addJarMnEntries(engineDir: string, tagName: string, file
 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.
+ * 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.
  *
- * This operation is idempotent — if no entries exist or the file is missing,
+ * This operation is idempotent: if no entries exist or the file is missing,
  * nothing happens.
  *
  * @param engineDir - Path to the Firefox engine source root
@@ -82,7 +83,7 @@ export interface StaleJarMnEntry {
 }
 /**
  * Scans jar.mn for widget registration lines `(widgets/<tag>/<file>)` whose
- * workspace source file no longer exists — a renamed component helper
+ * workspace source file no longer exists. A renamed component helper
  * otherwise leaves the old line pointing at a deleted file and every build
  * fails at packaging. Only tags in `managedTags` (furnace-managed custom
  * components) are inspected, so upstream lines are never touched.

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

@@ -2,22 +2,31 @@
 import { join } from 'node:path';
 import { FurnaceError } from '../errors/furnace.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
+/**
+ * Returns the leading whitespace of the first line matching `pattern`, whose
+ * first capture group must be that indentation. `undefined` when no line
+ * matches, so callers can chain progressively looser patterns before falling
+ * back to a convention default.
+ */
+function detectIndent(lines, pattern) {
+    for (const line of lines) {
+        const match = pattern.exec(line);
+        if (match?.[1])
+            return match[1];
+    }
+    return undefined;
+}
 /**
  * Detects the indentation used by existing `content/global/elements/` lines
  * in jar.mn. Falls back to 3 spaces (the historical Firefox convention) when
  * no reference line is found.
  */
 function detectJarMnIndent(lines) {
-    for (const line of lines) {
-        const match = /^(\s+)content\/global\/elements\//.exec(line);
-        if (match?.[1]) {
-            return match[1];
-        }
-    }
-    return '   ';
+    return detectIndent(lines, /^(\s+)content\/global\/elements\//) ?? '   ';
 }
 // Re-export everything from the AST module so existing imports keep working
-export { addCustomElementRegistration, removeCustomElementRegistration, validateCustomElementRegistration, } from './furnace-registration-ast.js';
+export { addCustomElementRegistration, validateCustomElementRegistration, } from './furnace-registration-ast.js';
+export { removeCustomElementRegistration } from './furnace-registration-remove.js';
 import { escapeRegex } from '../utils/regex.js';
 import { JAR_MN } from './furnace-constants.js';
 /**
@@ -37,7 +46,7 @@ import { JAR_MN } from './furnace-constants.js';
  *   `content/global/elements/` line. Falls back to 3 spaces when no
  *   reference line exists.
  * - **Insertion point**: identified by existing lines matching the regex
- *   `^\s+content\/global\/elements\/([^.]+)\.` — new entries are inserted
+ *   `^\s+content\/global\/elements\/([^.]+)\.`. New entries are inserted
  *   in alphabetical order relative to these.
  * - **Fallback**: if no `content/global/elements/` line exists (empty
  *   project), looks for any `content/global/` line and inserts after it.
@@ -72,10 +81,7 @@ export async function addJarMnEntries(engineDir, tagName, files) {
     // 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;
+    for (const [i, line] of lines.entries()) {
         const match = elementLinePattern.exec(line);
         if (match) {
             const existingTag = match[1] ?? '';
@@ -116,7 +122,7 @@ export async function addJarMnEntries(engineDir, tagName, files) {
  * 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`)
+ * 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.
  *
@@ -148,10 +154,7 @@ export async function addLocaleFtlJarMnEntry(engineDir, jarMnRelPath, tagName, c
     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;
+    for (const [i, line] of lines.entries()) {
         const match = sectionPattern.exec(line);
         if (match) {
             const existingTag = match[2] ?? '';
@@ -174,23 +177,13 @@ export async function addLocaleFtlJarMnEntry(engineDir, jarMnRelPath, tagName, c
 /** Detects locale jar.mn indentation by sampling an existing matching entry. */
 function detectLocaleJarMnIndent(lines, chromeSubPath) {
     const escapedChrome = escapeRegex(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 '  ';
+    const exact = new RegExp(`^(\\s+)locale\\/(?:@AB_CD@|[a-zA-Z-]+)\\/${escapedChrome}\\/`);
+    // Fall back to any existing `locale/...` indent before giving up.
+    return detectIndent(lines, exact) ?? detectIndent(lines, /^(\s+)locale\//) ?? '  ';
 }
 /**
  * Removes a locale jar.mn entry previously written by `addLocaleFtlJarMnEntry`.
- * Idempotent — if the entry is absent or the file is missing, nothing happens.
+ * 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);
@@ -208,7 +201,7 @@ export async function removeLocaleFtlJarMnEntry(engineDir, jarMnRelPath, tagName
 /**
  * Removes all jar.mn entries for a given tag name.
  *
- * This operation is idempotent — if no entries exist or the file is missing,
+ * This operation is idempotent: if no entries exist or the file is missing,
  * nothing happens.
  *
  * @param engineDir - Path to the Firefox engine source root
@@ -221,9 +214,9 @@ export async function removeJarMnEntries(engineDir, tagName) {
     }
     let content = await readText(filePath);
     const lines = content.split('\n');
-    // Match by the SOURCE MAPPING segment `(widgets/<tagName>/...)` so every
+    // Match by the source mapping segment `(widgets/<tagName>/...)` so every
     // line the component registered is removed regardless of the target
-    // basename — a helper `.mjs` whose name does not start with the tag (e.g.
+    // basename. A helper `.mjs` whose name does not start with the tag (e.g.
     // a renamed `foo-utils.mjs`) otherwise survives the remove pass and leaves
     // a stale registration that breaks packaging. The legacy target-path match
     // is kept as an OR for lines written before the source mapping existed.
@@ -239,7 +232,7 @@ export async function removeJarMnEntries(engineDir, tagName) {
 const WIDGET_SOURCE_MAPPING_PATTERN = /\(widgets\/([^/)]+)\/([^)]+)\)/;
 /**
  * Scans jar.mn for widget registration lines `(widgets/<tag>/<file>)` whose
- * workspace source file no longer exists — a renamed component helper
+ * workspace source file no longer exists. A renamed component helper
  * otherwise leaves the old line pointing at a deleted file and every build
  * fails at packaging. Only tags in `managedTags` (furnace-managed custom
  * components) are inspected, so upstream lines are never touched.

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

@@ -16,7 +16,7 @@ export declare function recordCreatedDir(journal: RollbackJournal, dirPath: stri
 /**
  * Recursively snapshots every file under a directory tree so a later rollback
  * can restore deleted files. Skips symlinks to avoid following them out of the
- * tree. The directory itself is not recorded as "created" — callers that
+ * tree. The directory itself is not recorded as "created", so callers that
  * intend to delete and restore the directory should record it explicitly.
  *
  * Safe to call on a missing path: it returns without recording anything.

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

@@ -20,7 +20,7 @@ export function recordCreatedDir(journal, dirPath) {
 /**
  * Recursively snapshots every file under a directory tree so a later rollback
  * can restore deleted files. Skips symlinks to avoid following them out of the
- * tree. The directory itself is not recorded as "created" — callers that
+ * tree. The directory itself is not recorded as "created", so callers that
  * intend to delete and restore the directory should record it explicitly.
  *
  * Safe to call on a missing path: it returns without recording anything.
@@ -49,9 +49,9 @@ export async function snapshotFile(journal, filePath) {
     // Journal keys are the paths rollback will later write back to, and the
     // restore runs from whatever cwd the process happens to be in by then. A
     // relative key would therefore restore somewhere other than where the
-    // snapshot was taken — silently, and only on the failure path where nobody
-    // is watching. Every caller composes an absolute path already; this keeps
-    // it that way.
+    // snapshot was taken, silently, and only on the failure path where nobody
+    // is watching. Every caller composes an absolute path already, and this
+    // keeps it that way.
     assert(isAbsolute(filePath), () => `snapshot path is absolute (got "${filePath}")`);
     if (journal.files.has(filePath)) {
         return;
@@ -149,7 +149,7 @@ export async function restoreRollbackJournal(journal) {
     // Directory removal is only safe once every file is back where it belongs:
     // a created directory may hold a restored file, and removing it recursively
     // would undo the restore we just performed. The throw above is what
-    // normally enforces this; the assertion names it so a future early-return
+    // normally enforces this. The assertion names it so a future early-return
     // or error-swallowing edit cannot quietly reach the rm loop with failures
     // outstanding.
     assert(errors.length === 0, 'all journal files restored before created directories are removed');

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

@@ -1,9 +1,9 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { createHash } from 'node:crypto';
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText } from '../utils/fs.js';
+import { sha256Hex } from '../utils/hash.js';
 import { verbose, warn } from '../utils/logger.js';
 import { asEstree, getNodeSource, parseScript, walkAST } from './ast-utils.js';
 import { CUSTOM_ELEMENTS_JS, FTL_DIR, WIDGETS_DIR } from './furnace-constants.js';
@@ -48,7 +48,7 @@ export async function scanCustomElementsRegistrations(engineDir) {
         return registrations;
     }
     const content = await readText(filePath);
-    const contentHash = createHash('sha256').update(content).digest('hex');
+    const contentHash = sha256Hex(content);
     // Return cached result if file hasn't changed since last parse.
     if (registrationCache && registrationCache.hash === contentHash) {
         return new Map(registrationCache.registrations);
@@ -121,10 +121,7 @@ export async function scanCustomElementsRegistrations(engineDir) {
             'Results may be incomplete — run "fireforge furnace validate" to verify registration consistency.');
         verbose(`Scanner regex fallback activated due to parse error: ${reason}`);
         const lines = content.split('\n');
-        for (let i = 0; i < lines.length; i++) {
-            const line = lines[i];
-            if (line === undefined)
-                continue;
+        for (const [i, line] of lines.entries()) {
             const callbackMatch = /setElementCreationCallback\(\s*"([^"]+)"/.exec(line);
             if (!callbackMatch?.[1])
                 continue;

package/dist/src/core/furnace-stale-export.d.ts

@@ -1,46 +1,46 @@
 /**
  * Stale-furnace-source gate for `fireforge patch export` / `re-export`.
  *
- * Exports capture the DEPLOYED engine copies of furnace-managed files, not
+ * Exports capture the deployed engine copies of furnace-managed files, not
  * the `components/` sources. Editing a component source and re-exporting its
- * owning patch WITHOUT an intervening `furnace deploy`/`apply` silently
- * exports the stale deployed copy — per-patch lint then flags the old line
+ * owning patch without an intervening `furnace deploy`/`apply` silently
+ * exports the stale deployed copy: per-patch lint then flags the old line
  * count and the patch body lags the source. This gate detects that sequence
  * by comparing component source directories against the checksums recorded
- * at the last apply (`FurnaceState.appliedChecksums`) — the same signal
- * `warnIfFurnaceStale` uses for run/watch — and refuses the export unless
+ * at the last apply (`FurnaceState.appliedChecksums`), the same signal
+ * `warnIfFurnaceStale` uses for run/watch, and refuses the export unless
  * the operator passes `--allow-stale-furnace`.
  *
  * Checksum-based on purpose: git checkouts and `furnace refresh` churn
  * mtimes without content changes, so an mtime comparison would misfire.
  *
  * Probe failures (broken furnace config, missing state) degrade to a verbose
- * log and an empty result — a broken furnace setup must never block
+ * log and an empty result. A broken furnace setup must never block
  * non-furnace patch work.
  */
 /** One furnace component whose source drifted from its deployed copy. */
 export interface StaleFurnaceComponent {
     /** Component name (furnace.json key). */
     name: string;
-    /** Component flavor — resolves the source directory root. */
+    /** Component flavor, which resolves the source directory root. */
     type: 'custom' | 'override';
     /** Engine-relative deployed prefix (`/`-terminated) the component owns. */
     prefix: string;
 }
 /**
  * Returns the furnace components whose deployed engine copies the given
- * files fall under AND whose `components/` sources have changed since the
+ * files fall under and whose `components/` sources have changed since the
  * last apply. Empty when furnace is not configured, never applied, or the
  * probe fails.
  *
  * Files are attributed per component: the custom `targetPath` / override
- * `basePath` prefixes, plus — for a localized non-sharedFtl custom
- * component — its exact deployed `<ftlDir>/<name>.ftl` file (the shared
- * FTL dir as a whole stays unclaimed; sibling files there belong to other
- * components). `sharedFtl` bundles are NOT furnace-deployed (apply only
- * prunes a dangling per-widget jar.mn line), so they have no deployed copy
- * to go stale and get no candidate by design. The storybook stories prefix
- * is likewise skipped.
+ * `basePath` prefixes, plus, for a localized non-sharedFtl custom
+ * component, its exact deployed `<ftlDir>/<name>.ftl` file (the shared
+ * FTL dir as a whole stays unclaimed, because sibling files there belong
+ * to other components). `sharedFtl` bundles are not furnace-deployed (apply
+ * only prunes a dangling per-widget jar.mn line), so they have no deployed
+ * copy to go stale and get no candidate by design. The storybook stories
+ * prefix is likewise skipped.
  *
  * @param projectRoot - Project root directory
  * @param files - Engine-relative paths the export will capture
@@ -49,7 +49,8 @@ export declare function findStaleFurnaceComponentsForFiles(projectRoot: string,
 /**
  * Gate helper for export/re-export: refuses (or, with `allow`, warns) when
  * any exported file belongs to a furnace component whose source changed
- * since the last apply — the export would capture the stale deployed copy.
+ * since the last apply, where the export would capture the stale deployed
+ * copy.
  *
  * @param projectRoot - Project root directory
  * @param files - Engine-relative paths the export will capture

package/dist/src/core/furnace-stale-export.js

@@ -2,21 +2,21 @@
 /**
  * Stale-furnace-source gate for `fireforge patch export` / `re-export`.
  *
- * Exports capture the DEPLOYED engine copies of furnace-managed files, not
+ * Exports capture the deployed engine copies of furnace-managed files, not
  * the `components/` sources. Editing a component source and re-exporting its
- * owning patch WITHOUT an intervening `furnace deploy`/`apply` silently
- * exports the stale deployed copy — per-patch lint then flags the old line
+ * owning patch without an intervening `furnace deploy`/`apply` silently
+ * exports the stale deployed copy: per-patch lint then flags the old line
  * count and the patch body lags the source. This gate detects that sequence
  * by comparing component source directories against the checksums recorded
- * at the last apply (`FurnaceState.appliedChecksums`) — the same signal
- * `warnIfFurnaceStale` uses for run/watch — and refuses the export unless
+ * at the last apply (`FurnaceState.appliedChecksums`), the same signal
+ * `warnIfFurnaceStale` uses for run/watch, and refuses the export unless
  * the operator passes `--allow-stale-furnace`.
  *
  * Checksum-based on purpose: git checkouts and `furnace refresh` churn
  * mtimes without content changes, so an mtime comparison would misfire.
  *
  * Probe failures (broken furnace config, missing state) degrade to a verbose
- * log and an empty result — a broken furnace setup must never block
+ * log and an empty result. A broken furnace setup must never block
  * non-furnace patch work.
  */
 import { GeneralError } from '../errors/base.js';
@@ -28,18 +28,18 @@ import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceSta
 import { resolveFtlDir } from './furnace-constants.js';
 /**
  * Returns the furnace components whose deployed engine copies the given
- * files fall under AND whose `components/` sources have changed since the
+ * files fall under and whose `components/` sources have changed since the
  * last apply. Empty when furnace is not configured, never applied, or the
  * probe fails.
  *
  * Files are attributed per component: the custom `targetPath` / override
- * `basePath` prefixes, plus — for a localized non-sharedFtl custom
- * component — its exact deployed `<ftlDir>/<name>.ftl` file (the shared
- * FTL dir as a whole stays unclaimed; sibling files there belong to other
- * components). `sharedFtl` bundles are NOT furnace-deployed (apply only
- * prunes a dangling per-widget jar.mn line), so they have no deployed copy
- * to go stale and get no candidate by design. The storybook stories prefix
- * is likewise skipped.
+ * `basePath` prefixes, plus, for a localized non-sharedFtl custom
+ * component, its exact deployed `<ftlDir>/<name>.ftl` file (the shared
+ * FTL dir as a whole stays unclaimed, because sibling files there belong
+ * to other components). `sharedFtl` bundles are not furnace-deployed (apply
+ * only prunes a dangling per-widget jar.mn line), so they have no deployed
+ * copy to go stale and get no candidate by design. The storybook stories
+ * prefix is likewise skipped.
  *
  * @param projectRoot - Project root directory
  * @param files - Engine-relative paths the export will capture
@@ -97,7 +97,8 @@ export async function findStaleFurnaceComponentsForFiles(projectRoot, files) {
 /**
  * Gate helper for export/re-export: refuses (or, with `allow`, warns) when
  * any exported file belongs to a furnace component whose source changed
- * since the last apply — the export would capture the stale deployed copy.
+ * since the last apply, where the export would capture the stale deployed
+ * copy.
  *
  * @param projectRoot - Project root directory
  * @param files - Engine-relative paths the export will capture

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

@@ -1,5 +1,5 @@
 /**
- * Furnace staleness advisory — shared between `fireforge run` and
+ * Furnace staleness advisory, shared between `fireforge run` and
  * `fireforge watch`. Both commands launch the built browser without
  * first running `furnace apply`, so this helper surfaces a warning when
  * component files have drifted from the last-applied checksums and the
@@ -11,7 +11,7 @@
 /**
  * Emits a warning when any tracked override or custom component has
  * changed on disk since the last apply. Safe to call from any build-time
- * command that does not auto-apply — a failure inside the probe is
+ * command that does not auto-apply. A failure inside the probe is
  * downgraded to a verbose log and the caller continues.
  */
 export declare function warnIfFurnaceStale(projectRoot: string): Promise<void>;

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

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Furnace staleness advisory — shared between `fireforge run` and
+ * Furnace staleness advisory, shared between `fireforge run` and
  * `fireforge watch`. Both commands launch the built browser without
  * first running `furnace apply`, so this helper surfaces a warning when
  * component files have drifted from the last-applied checksums and the
@@ -16,7 +16,7 @@ import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceSta
 /**
  * Emits a warning when any tracked override or custom component has
  * changed on disk since the last apply. Safe to call from any build-time
- * command that does not auto-apply — a failure inside the probe is
+ * command that does not auto-apply. A failure inside the probe is
  * downgraded to a verbose log and the caller continues.
  */
 export async function warnIfFurnaceStale(projectRoot) {