@hominis/fireforge 0.46.0 → 0.46.2

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

@@ -17,7 +17,7 @@ export { removeCustomElementRegistration } from './furnace-registration-remove.j
  *   `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.
@@ -42,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.
  *
@@ -59,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
@@ -83,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

@@ -46,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.
@@ -122,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.
  *
@@ -183,7 +183,7 @@ function detectLocaleJarMnIndent(lines, chromeSubPath) {
 }
 /**
  * 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);
@@ -201,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
@@ -214,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.
@@ -232,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-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) {

package/dist/src/core/furnace-state-persist.d.ts

@@ -4,25 +4,25 @@
  * There are exactly two sanctioned ways checksums land in
  * furnace-state.json:
  *
- *  1. The BATCH path inside `applyAllComponents` (persistState: true), which
- *     replaces `appliedChecksums` wholesale — correct only when the run
- *     covered every component.
- *  2. The per-component MERGE in this module, which rewrites only the
+ *  1. The batch path inside `applyAllComponents` (persistState: true), which
+ *     replaces `appliedChecksums` wholesale. That is correct only when the
+ *     run covered every component.
+ *  2. The per-component merge in this module, which rewrites only the
  *     `<type>/<name>/…` keys of the component that was applied.
  *
- * Every targeted (named) apply/deploy MUST use path 2 with
+ * Every targeted (named) apply/deploy must use path 2 with
  * `persistState: false`. Routing a named run through the batch path wipes
  * every other component's checksum state: the batch loops filter to the
  * named component, so the wholesale replace persists a state file containing
  * only that component. Downstream, `diffDeletedFiles` and
  * `findOrphanedEngineFiles` both key on `appliedChecksums`, so the wiped
- * components' stale engine files become undetectable by apply AND by
+ * components' stale engine files become undetectable by apply and by
  * `furnace validate`.
  */
 import { type ApplyAllComponentsResult } from './furnace-apply.js';
 import { type FurnacePaths } from './furnace-config.js';
 /**
- * Counts applied entries that carry at least one BLOCKING step error
+ * Counts applied entries that carry at least one blocking step error
  * (advisory step errors are warnings and never fail a run).
  */
 export declare function getStepFailureCount(result: ApplyAllComponentsResult): number;
@@ -33,7 +33,7 @@ export declare function getStepFailureCount(result: ApplyAllComponentsResult): n
  * Named runs are atomic: if any apply step fails, the rollback journal
  * restores the engine to its pre-run state and this helper returns `false`
  * so state is not touched. The conditions must stay in lock-step with the
- * rollback trigger in `applyAllComponents` — both read step errors, so a
+ * rollback trigger in `applyAllComponents`: both read step errors, so a
  * future refactor cannot drift them apart and accidentally persist partial
  * state.
  */
@@ -43,7 +43,7 @@ export declare function shouldPersistSingleComponentState(result: ApplyAllCompon
  *
  * Guards against future refactors that might reorder or misroute the
  * applied[] array: a named run persists state under a single component
- * name, so the first applied entry MUST be that component. Persisting a
+ * name, so the first applied entry must be that component. Persisting a
  * different component's checksums would cause the next status/apply run to
  * mis-report health for both components involved.
  *
@@ -55,7 +55,7 @@ export declare function getPersistableAppliedEntry(commandLabel: string, name: s
 };
 /**
  * Persists checksum state for a successfully applied named component by
- * MERGING its `<type>/<name>/…` keys into the existing state — never
+ * merging its `<type>/<name>/…` keys into the existing state rather than
  * replacing the whole map.
  *
  * @param projectRoot - Root directory of the project

package/dist/src/core/furnace-state-persist.js

@@ -5,19 +5,19 @@
  * There are exactly two sanctioned ways checksums land in
  * furnace-state.json:
  *
- *  1. The BATCH path inside `applyAllComponents` (persistState: true), which
- *     replaces `appliedChecksums` wholesale — correct only when the run
- *     covered every component.
- *  2. The per-component MERGE in this module, which rewrites only the
+ *  1. The batch path inside `applyAllComponents` (persistState: true), which
+ *     replaces `appliedChecksums` wholesale. That is correct only when the
+ *     run covered every component.
+ *  2. The per-component merge in this module, which rewrites only the
  *     `<type>/<name>/…` keys of the component that was applied.
  *
- * Every targeted (named) apply/deploy MUST use path 2 with
+ * Every targeted (named) apply/deploy must use path 2 with
  * `persistState: false`. Routing a named run through the batch path wipes
  * every other component's checksum state: the batch loops filter to the
  * named component, so the wholesale replace persists a state file containing
  * only that component. Downstream, `diffDeletedFiles` and
  * `findOrphanedEngineFiles` both key on `appliedChecksums`, so the wiped
- * components' stale engine files become undetectable by apply AND by
+ * components' stale engine files become undetectable by apply and by
  * `furnace validate`.
  */
 import { join } from 'node:path';
@@ -26,7 +26,7 @@ import { computeComponentChecksums, prefixChecksums, } from './furnace-apply.js'
 import { updateFurnaceState } from './furnace-config.js';
 import { countEntriesWithBlockingStepErrors } from './furnace-step-errors.js';
 /**
- * Counts applied entries that carry at least one BLOCKING step error
+ * Counts applied entries that carry at least one blocking step error
  * (advisory step errors are warnings and never fail a run).
  */
 export function getStepFailureCount(result) {
@@ -39,7 +39,7 @@ export function getStepFailureCount(result) {
  * Named runs are atomic: if any apply step fails, the rollback journal
  * restores the engine to its pre-run state and this helper returns `false`
  * so state is not touched. The conditions must stay in lock-step with the
- * rollback trigger in `applyAllComponents` — both read step errors, so a
+ * rollback trigger in `applyAllComponents`: both read step errors, so a
  * future refactor cannot drift them apart and accidentally persist partial
  * state.
  */
@@ -57,7 +57,7 @@ export function shouldPersistSingleComponentState(result, isDryRun) {
  *
  * Guards against future refactors that might reorder or misroute the
  * applied[] array: a named run persists state under a single component
- * name, so the first applied entry MUST be that component. Persisting a
+ * name, so the first applied entry must be that component. Persisting a
  * different component's checksums would cause the next status/apply run to
  * mis-report health for both components involved.
  *
@@ -87,7 +87,7 @@ export function getPersistableAppliedEntry(commandLabel, name, appliedEntry) {
 }
 /**
  * Persists checksum state for a successfully applied named component by
- * MERGING its `<type>/<name>/…` keys into the existing state — never
+ * merging its `<type>/<name>/…` keys into the existing state rather than
  * replacing the whole map.
  *
  * @param projectRoot - Root directory of the project

package/dist/src/core/furnace-step-errors.d.ts

@@ -1,12 +1,12 @@
 /**
  * Shared predicates over {@link StepError} lists.
  *
- * Step errors come in two severities: BLOCKING (the default — the apply is
- * considered failed, triggers rollback and a non-zero exit) and ADVISORY
- * (`advisory: true` — reported as a warning, never blocks; used by the
- * `.ftl` helpers whose contract is graceful degradation). Every gate that
- * decides rollback/failure must count only blocking errors; every reporter
- * should still surface advisory ones. This module is a leaf (types-only
+ * Step errors come in two severities: blocking (the default: the apply is
+ * considered failed, triggers rollback and a non-zero exit) and advisory
+ * (`advisory: true`, which is reported as a warning, never blocks, and is
+ * used by the `.ftl` helpers whose contract is graceful degradation). Every
+ * gate that decides rollback/failure must count only blocking errors, and
+ * every reporter should still surface advisory ones. This module is a leaf (types-only
  * imports) so both `furnace-apply.ts` and its callers can share the
  * predicates without import cycles.
  */

package/dist/src/core/furnace-step-errors.js

@@ -2,12 +2,12 @@
 /**
  * Shared predicates over {@link StepError} lists.
  *
- * Step errors come in two severities: BLOCKING (the default — the apply is
- * considered failed, triggers rollback and a non-zero exit) and ADVISORY
- * (`advisory: true` — reported as a warning, never blocks; used by the
- * `.ftl` helpers whose contract is graceful degradation). Every gate that
- * decides rollback/failure must count only blocking errors; every reporter
- * should still surface advisory ones. This module is a leaf (types-only
+ * Step errors come in two severities: blocking (the default: the apply is
+ * considered failed, triggers rollback and a non-zero exit) and advisory
+ * (`advisory: true`, which is reported as a warning, never blocks, and is
+ * used by the `.ftl` helpers whose contract is graceful degradation). Every
+ * gate that decides rollback/failure must count only blocking errors, and
+ * every reporter should still surface advisory ones. This module is a leaf (types-only
  * imports) so both `furnace-apply.ts` and its callers can share the
  * predicates without import cycles.
  */

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

@@ -81,7 +81,7 @@ function hasPositiveTabindex(content) {
  * Collects `[start, end)` spans of `<label>…</label>` elements whose content
  * includes actual label text. Labels cannot nest per HTML, so the non-greedy
  * inner match is sound. A span qualifies only when the inner content minus
- * tags still contains non-whitespace — an empty or tag-only wrapper provides
+ * tags still contains non-whitespace. An empty or tag-only wrapper provides
  * no accessible name. A `${…}` Lit binding counts as label text: dynamic
  * (usually localized) text is a legitimate accessible name.
  */
@@ -132,12 +132,12 @@ function hasTemplateKeyboardHandler(content) {
 }
 /**
  * Native HTML elements that dispatch `click` on Enter and Space via the
- * platform. Attaching `@click` to these is NOT a keyboard-a11y bug because
- * the browser already handles the keyboard activation path — a duplicate
+ * platform. Attaching `@click` to these is not a keyboard-a11y bug, because
+ * the browser already handles the keyboard activation path. A duplicate
  * `@keydown`/`@keypress` handler would usually double-fire the action.
  *
- * `<a>` is accepted only when an `href` attribute is present; bare `<a>` is
- * non-interactive and is treated as synthetic.
+ * `<a>` is accepted only when an `href` attribute is present. A bare `<a>`
+ * is non-interactive and is treated as synthetic.
  */
 const NATIVE_CLICK_INTERACTIVE_TAGS = new Set([
     'button',
@@ -178,7 +178,7 @@ function isKeyboardCoveredByComposition(customConfig) {
  * *synthetic* interactive element (e.g. `<div @click>`), which lacks native
  * keyboard activation and therefore needs an explicit key handler for
  * Enter/Space. Returns false when every `@click` handler sits on a native
- * interactive element — those already fire `click` on keyboard activation.
+ * interactive element. Those already fire `click` on keyboard activation.
  */
 function hasTemplateClickOnSyntheticInteractive(content) {
     const pattern = /@click\s*=\s*\$\{/g;
@@ -219,7 +219,7 @@ function isClickOnSyntheticInteractive(content, clickIndex) {
         return true;
     const tagName = tagMatch[1].toLowerCase();
     if (tagName === 'a') {
-        // Bare <a> (no href) is non-interactive; require a keyboard handler.
+        // Bare <a> (no href) is non-interactive, so require a keyboard handler.
         // Look forward from the tag open for the closing `>` and scan the
         // attribute text in between for an href attribute.
         const tagEnd = content.indexOf('>', tagOpenIndex);
@@ -236,20 +236,20 @@ const SYMBOL_ONLY_ASCII = '+-*=<>|/\\^~@#&!?%';
  * Reports whether `text` is decoration (arrows, maths, emoji, bare
  * punctuation) rather than user-facing prose that needs localizing.
  *
- * The letter/number/mark test comes first and is script-agnostic — a rule
+ * The letter/number/mark test comes first and is script-agnostic. A rule
  * keyed on `code > 0xff` would classify every code point above U+00FF as a
  * symbol, exempting all CJK, Cyrillic, Greek, Arabic, Hebrew, Devanagari and
- * Thai text from a **localization** validator.
+ * Thai text from a localization validator.
  *
- * Combining marks are deliberately NOT counted as text: the check is an
+ * Combining marks are not counted as text: the check is an
  * `every()`, so a script's base letters already disqualify the string, and
  * treating marks as text would flag emoji carrying a variation selector
- * (U+FE0F is category Mn — `⚙️` is U+2699 + U+FE0F).
+ * (U+FE0F is category Mn, and `⚙️` is U+2699 + U+FE0F).
  *
- * High code points that are not letters — emoji, arrows, CJK punctuation —
+ * High code points that are not letters (emoji, arrows, CJK punctuation)
  * stay exempt, which is the rule's intent.
  *
- * A handful of emoji are ALSO Unicode letters, and the letter test alone
+ * A handful of emoji are also Unicode letters, and the letter test alone
  * gets them wrong: U+2139 (`ℹ`, the base of the common `ℹ️`) is category Ll,
  * so `\p{L}` would classify an info badge as prose needing localization.
  * Non-ASCII code points carrying `Emoji` are therefore read as symbols
@@ -335,7 +335,7 @@ function hasFlaggedTextInLitTemplates(content) {
     return false;
 }
 function hasFlaggedTextInDomAssignment(content) {
-    // `<expr>.textContent = "abc"` and `<expr>.innerHTML = "abc"` — these are
+    // `<expr>.textContent = "abc"` and `<expr>.innerHTML = "abc"`: these are
     // user-visible render paths. Template-literal RHS is excluded (usually
     // dynamic), matching the `${` guard used elsewhere in this helper.
     const assignPattern = /\.(?:textContent|innerHTML)\s*=\s*(["'])((?:\\.|(?!\1).)*)\1/g;

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

@@ -170,7 +170,7 @@ function hasCustomElementDefineCall(mjsContent) {
 /**
  * Detects whether the module's `customElements.define(...)` call includes a
  * literal `extends:` option (third argument). That shape is the marker for
- * a customized built-in element — the class extends a specific
+ * a customized built-in element: the class extends a specific
  * `HTMLxxxElement` rather than the autonomous `MozLitElement` path.
  *
  * Firefox's own widgets use this pattern for toolkit anchors (e.g.
@@ -193,24 +193,24 @@ function hasCustomElementExtendsOption(mjsContent) {
  *
  * Two shapes are accepted:
  *
- * 1. Autonomous custom element: `class X extends MozLitElement` — the
+ * 1. Autonomous custom element: `class X extends MozLitElement`, the
  *    default FireForge pattern for fork-authored components and most
  *    toolkit widgets.
  * 2. Customized built-in: `class X extends HTML<Something>Element` paired
  *    with a `customElements.define(..., ..., { extends: "<tagname>" })`
  *    call. Firefox's `moz-support-link`, `moz-button-group` tabbing
- *    widgets, and a handful of other toolkit components use this form;
+ *    widgets, and a handful of other toolkit components use this form.
  *    `furnace override` of those components writes the original source
  *    verbatim and the validator must not reject them.
  *
- * A class that extends a plain `HTMLElement` WITHOUT a `extends:` option
- * is still rejected — that's the legitimate `not-moz-lit-element` case
+ * A class that extends a plain `HTMLElement` without an `extends:` option
+ * is still rejected. That is the legitimate `not-moz-lit-element` case
  * the rule was originally designed to catch.
  */
 function classExtendsMozLitElement(mjsContent) {
     const hasClassDeclaration = /class\s+\w+\s+extends\s+/.test(mjsContent);
     if (!hasClassDeclaration) {
-        // No class declaration — skip this check since the component may use a
+        // No class declaration, so skip this check since the component may use a
         // different pattern (e.g. function-based). Other validators will catch
         // structural issues.
         return true;
@@ -218,8 +218,8 @@ function classExtendsMozLitElement(mjsContent) {
     if (/class\s+\w+\s+extends\s+MozLitElement\b/.test(mjsContent)) {
         return true;
     }
-    // Customized built-in: extend a specific HTMLxxxElement AND the define
-    // call carries an `extends:` option. Both halves are required — a class
+    // Customized built-in: extend a specific HTMLxxxElement and the define
+    // call carries an `extends:` option. Both halves are required: a class
     // that extends `HTMLAnchorElement` without the matching define option is
     // almost certainly an author mistake, and a define call with `extends:`
     // without a matching class is unreachable.
@@ -243,7 +243,7 @@ function collectCssVariableReferences(cssContent) {
     return referencedVariables;
 }
 /**
- * Collects CSS custom property *declarations* — names appearing on the
+ * Collects CSS custom property *declarations*, i.e. names appearing on the
  * left-hand side of a `--name:` declaration. Used to auto-exempt
  * component-local runtime variables from the token-prefix check: if the
  * component both declares and consumes a variable in its own CSS file, it

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

@@ -44,10 +44,10 @@ export declare function withRegistrationValidationCache<T>(body: () => Promise<T
  *
  * Scan set is the union of (a) the configured `tokenHostDocuments` (or
  * the upstream default when unset) and (b) any `browser/base/content/*.xhtml`
- * document that references `tagName` — the auto-detection path catches
+ * document that references `tagName`. The auto-detection path catches
  * forks that mount components from a replacement chrome document without
  * having configured `tokenHostDocuments`. The warning fires only when
- * NONE of the documents in the final scan set link the tokens CSS.
+ * none of the documents in the final scan set link the tokens CSS.
  */
 export declare function validateTokenLink(componentDir: string, tagName: string, root: string, tokenPrefix?: string, tokenHostDocuments?: string[]): Promise<ValidationIssue[]>;
 /**