@hominis/fireforge 0.46.0 → 0.46.2

package/dist/src/commands/export-shared.js

@@ -20,7 +20,7 @@ import { describePatchNameProblem, normalizePatchDisplayName, PATCH_CATEGORIES,
 export async function runPatchLint(options) {
     const { engineDir, filesAffected, diffContent, config, skipLint, patchQueueCtx, ignoreChecks, patchTier, } = options;
     // Compute the tier decision independently of the lint pipeline so it can
-    // be surfaced even when the rule body emitted no issues — a branding patch
+    // be surfaced even when the rule body emitted no issues. A branding patch
     // under the soft threshold still benefits from operators knowing which
     // tier governed the run. The same helper is reused inside `lintPatchSize`,
     // so the surfaced tier and the tier that actually drove the thresholds
@@ -100,8 +100,8 @@ export function reportPatchLintOutcome(issues, skipLint) {
  */
 export async function promptExportPatchMetadata(options, isInteractive, commandName, config) {
     const categories = config !== undefined ? getPatchPolicyCategories(config) : [...PATCH_CATEGORIES];
-    // A filename-shaped `--name foo.patch` must not die on the dot rule —
-    // strip the extension before validation so the one-step flow works for
+    // A filename-shaped `--name foo.patch` must not die on the dot rule, so
+    // strip the extension before validation and the one-step flow works for
     // both name shapes.
     let patchName = options.name?.trim().replace(/\.patch$/i, '');
     if (patchName) {
@@ -158,7 +158,7 @@ export async function promptExportPatchMetadata(options, isInteractive, commandN
             description = descResult;
         }
     }
-    // The filename slug pipeline strips redundant category prefixes; the
+    // The filename slug pipeline strips redundant category prefixes. The
     // manifest display name must agree, or every `export --name ui-foo`
     // needs a follow-up `patch rename` to satisfy bare-slug naming policy.
     const normalized = normalizePatchDisplayName(patchName, category);
@@ -208,14 +208,14 @@ export async function confirmSupersedePatches(patchesDir, filesAffected, superse
  * Detects new files missing license headers and offers to add them.
  *
  * In interactive mode the user is prompted before any files are modified. In
- * non-interactive mode the function is a no-op — the existing lint error
+ * non-interactive mode the function is a no-op. The existing lint error
  * blocks the export instead.
  *
  * @param engineDir - Absolute path to engine directory
  * @param diffContent - Current unified diff
  * @param config - Project configuration
  * @param isInteractive - Whether interactive prompts are available
- * @param dryRun - When true, only REPORT missing headers, never prompt or
+ * @param dryRun - When true, only report missing headers, never prompt or
  *   write. Dry-run must stay read-only: without this flag an interactive
  *   `export --dry-run` prompts (default Yes), writes license headers into
  *   engine/ files, and then closes with "no changes made".
@@ -293,7 +293,7 @@ export async function autoFixLicenseHeaders(engineDir, diffContent, config, isIn
  *
  * Returns an empty map when no overlap exists. Used by the overlap gate in
  * `export` and `export-all` to refuse a default-mode export that would
- * silently create cross-patch ownership conflicts — the same class of
+ * silently create cross-patch ownership conflicts, the same class of
  * conflict `verify` immediately fails with.
  */
 export function findPartialOwnershipOverlap(manifest, filesAffected, excludeFilenames) {
@@ -315,16 +315,16 @@ export function findPartialOwnershipOverlap(manifest, filesAffected, excludeFile
 /**
  * Gate that refuses the default export path when the new patch would
  * silently claim files already tracked by other non-superseded patches.
- * `findAllPatchesForFiles` catches the full-coverage supersede case; this
- * fills the gap for PARTIAL overlap — two patches both claiming e.g.
+ * `findAllPatchesForFiles` catches the full-coverage supersede case. This
+ * fills the gap for partial overlap: two patches both claiming e.g.
  * `browser/themes/shared/jar.inc.mn` after a second export with `--before`.
  *
  * Proceeds silently when there is no overlap, or when the caller passed
  * `--allow-overlap`. In interactive mode the caller is prompted to
  * acknowledge the overlap (the proper fix path is `re-export --files` to
  * repartition ownership, so the prompt surfaces that pointer). In
- * non-interactive mode it throws — better to fail fast than let the queue
- * fall out of sync with verify.
+ * non-interactive mode it throws, since failing fast beats letting the
+ * queue fall out of sync with verify.
  */
 export async function guardOwnershipOverlap(args) {
     const { patchesDir, filesAffected, supersedingFilenames, allowOverlap, isInteractive, s } = args;
@@ -364,7 +364,7 @@ export async function guardOwnershipOverlap(args) {
  * order: the supersede confirmation, then the cross-patch ownership overlap
  * guard. The overlap guard receives the filenames of the patches the export
  * would fully supersede so it does not flag a file claimed by a patch that
- * is about to be removed. Catching only FULL-coverage supersedes leaves a
+ * is about to be removed. Catching only full-coverage supersedes leaves a
  * second export targeting a shared file creating a queue where two patches
  * both claim it and `verify` fails immediately.
  *
@@ -375,7 +375,7 @@ export async function guardOwnershipOverlap(args) {
  * @param args.allowOverlap - The command's `--allow-overlap` flag
  * @param args.isInteractive - Whether prompting the operator is possible
  * @param args.s - Active spinner, stopped before any prompt
- * @returns `true` when both gates passed; `false` when the operator declined
+ * @returns `true` when both gates passed, `false` when the operator declined
  *   (the caller returns without committing)
  */
 export async function runSupersedeAndOverlapGates(args) {

package/dist/src/commands/export.js

@@ -88,11 +88,11 @@ async function collectExportFiles(paths, files) {
     return { files: [...collectedFiles].sort(), fromDirectory };
 }
 /**
- * Auto-excludes directory-derived files already owned by OTHER patches.
+ * Auto-excludes directory-derived files already owned by other patches.
  *
  * A directory export otherwise plans files owned by earlier patches into the
  * new patch, and the duplicate-new-file-creation refusal surfaces only at
- * placement lint, suggesting `--force-unsafe` — the wrong tool for "leave
+ * placement lint, suggesting `--force-unsafe`, the wrong tool for "leave
  * that file with its owner". Explicitly named files are never excluded (the
  * overlap gates still confront the operator with those). Prints one notice
  * per exclusion.
@@ -217,7 +217,7 @@ async function prepareExport(projectRoot, files, options) {
     }
     const config = await loadConfig(projectRoot);
     const isInteractive = stdioIsInteractive();
-    // Auto-fix missing license headers on new files (interactive only;
+    // Auto-fix missing license headers on new files (interactive only, and
     // report-only under --dry-run so the preview never mutates engine/)
     const headersAdded = await autoFixLicenseHeaders(paths.engine, diff, config, isInteractive, options.dryRun ?? false);
     if (headersAdded) {
@@ -269,7 +269,7 @@ export async function exportCommand(projectRoot, files, options) {
             patchTier: options.tier,
         });
         // Resolve placement (if any flag was given). Placement is mutually
-        // exclusive with supersede — the semantics overlap confusingly.
+        // exclusive with supersede, because the semantics overlap confusingly.
         let placementPlan = null;
         if (placementFlagCount > 0) {
             const gated = await gatePlacementPlan({

package/dist/src/commands/furnace/apply.js

@@ -29,7 +29,7 @@ async function snapshotWatchedChecksums(watchDirs) {
             }
         }
         catch {
-            // Directory may have been removed between iterations — ignore.
+            // Directory may have been removed between iterations, so ignore.
         }
     }
     return combined;
@@ -46,7 +46,7 @@ function checksumMapsEqual(a, b) {
 /**
  * Builds a watch-loop apply-failure message tailored to the error class so
  * transient filesystem errors (EACCES, ENOSPC, lock timeout) look different
- * from genuine apply-level failures; the previous generic "Apply failed: ..."
+ * from genuine apply-level failures. The previous generic "Apply failed: ..."
  * collapsed all causes into one string and made diagnosis difficult.
  */
 function classifyWatchApplyError(err) {
@@ -74,8 +74,8 @@ function classifyWatchApplyError(err) {
 }
 async function runWatchLoop(projectRoot) {
     const furnacePaths = getFurnacePaths(projectRoot);
-    // Both categories are eligible targets. The set is fixed; only existence
-    // varies over time — a component dir created AFTER watch started (the user
+    // Both categories are eligible targets. The set is fixed. Only existence
+    // varies over time: a component dir created after watch started (the user
     // running `furnace create` in another terminal) must be picked up without
     // restarting watch. A one-shot `pathExists` check at startup captures only
     // the dirs that existed then, leaving any later creation invisible.
@@ -115,8 +115,8 @@ async function runWatchLoop(projectRoot) {
             // for changes that are already reflected in the engine.
             lastChecksums = await snapshotWatchedChecksums(watchDirs);
         }
-        // Another change arrived while we were applying — run again so the edit
-        // is not silently absorbed into the post-apply checksum bump.
+        // Another change arrived while we were applying, so run again and the
+        // edit is not silently absorbed into the post-apply checksum bump.
         if (pendingChange) {
             pendingChange = false;
             await runApplyCycle();
@@ -124,7 +124,7 @@ async function runWatchLoop(projectRoot) {
     };
     const triggerApply = () => {
         if (applyInFlight) {
-            // An apply is already running; record the change so runApplyCycle
+            // An apply is already running. Record the change so runApplyCycle
             // re-runs after it completes. Do not schedule a new debounce: the
             // in-flight apply will observe this flag when it finishes.
             pendingChange = true;
@@ -136,7 +136,7 @@ async function runWatchLoop(projectRoot) {
             debounceTimer = null;
             if (applyInFlight) {
                 // Race with a change that started its own apply between the debounce
-                // scheduling and the timer firing. Record the pending change; the
+                // scheduling and the timer firing. Record the pending change. The
                 // in-flight apply will pick it up.
                 pendingChange = true;
                 return;
@@ -188,7 +188,7 @@ async function runWatchLoop(projectRoot) {
         }
         return added;
     };
-    // Register signal-driven cleanup BEFORE creating watchers so there is no
+    // Register signal-driven cleanup before creating watchers so there is no
     // race window where a SIGINT could arrive after watchers exist but before
     // cleanup handlers are registered.
     const cleanup = () => {
@@ -229,7 +229,7 @@ async function runWatchLoop(projectRoot) {
                 }
             }
             catch {
-                // Best effort — errors here are transient filesystem issues.
+                // Best effort: errors here are transient filesystem issues.
             }
         })();
     }, WATCH_POLL_INTERVAL_MS);
@@ -277,14 +277,14 @@ export async function furnaceApplyCommand(projectRoot, name, options = {}) {
     }
     const applySpinner = dryRun ? undefined : spinner('Applying components to engine...');
     const result = await runFurnaceMutation(projectRoot, 'apply-rollback', async (ctx) => {
-        // `persistState: false` for a NAMED apply is load-bearing: the batch
-        // persist path replaces `appliedChecksums` wholesale with only this
-        // run's entries, and the batch loops filter to the named component —
-        // so routing a named apply through it persists a state file containing
-        // ONLY that component, wiping every other component's checksums.
+        // `persistState: false` for a named apply matters: the batch persist
+        // path replaces `appliedChecksums` wholesale with only this run's
+        // entries, and the batch loops filter to the named component, so
+        // routing a named apply through it persists a state file containing
+        // only that component and wipes every other component's checksums.
         // Orphan detection and deleted-file undeploy both key on that state,
         // so the wiped components' stale engine files become invisible to
-        // apply AND to `furnace validate`. Named apply merges per-component
+        // apply and to `furnace validate`. Named apply merges per-component
         // state below, exactly like `furnace deploy <name>`.
         const applyResult = await applyAllComponents(projectRoot, dryRun, {
             operationContext: ctx,

package/dist/src/commands/furnace/chrome-doc-remove.d.ts

@@ -1,5 +1,5 @@
 /**
- * `fireforge furnace chrome-doc remove <name>` — removes the files and
+ * `fireforge furnace chrome-doc remove <name>` removes the files and
  * registrations created by `furnace chrome-doc create`.
  */
 /** Options for `furnace chrome-doc remove`. */

package/dist/src/commands/furnace/chrome-doc-remove.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `fireforge furnace chrome-doc remove <name>` — removes the files and
+ * `fireforge furnace chrome-doc remove <name>` removes the files and
  * registrations created by `furnace chrome-doc create`.
  */
 import { readdir } from 'node:fs/promises';

package/dist/src/commands/furnace/chrome-doc-templates.d.ts

@@ -41,21 +41,21 @@
  */
 export declare function generateChromeDocXhtml(name: string, withTitlebar: boolean, license: string): string;
 /**
- * browser.xhtml-like scaffold for the document that ships as the fork's MAIN
- * BROWSER WINDOW.
+ * browser.xhtml-like scaffold for the document that ships as the fork's main
+ * browser window.
  *
  * The generic dialog-shaped `<window>` scaffold is wrong for the
  * `tokenHostDocuments[0]` / BROWSER_CHROME_URL target: platform C++ reads
- * the root element BEFORE any script runs, and expects the `browser.xhtml`
+ * the root element before any script runs, and expects the `browser.xhtml`
  * shape:
  *
- * - `<html id="main-window">` root (not `<window id="<name>-window">`) —
+ * - `<html id="main-window">` root (not `<window id="<name>-window">`):
  *   upstream code from nsXULWindow sizing to session restore looks up
- *   `main-window` by id;
+ *   `main-window` by id.
  * - `windowtype="navigator:browser"`, `chromehidden=""` and the geometry
- *   `persist` allowlist declared as ROOT ATTRIBUTES so the platform's
+ *   `persist` allowlist declared as root attributes so the platform's
  *   pre-script pass (window tracking, XULStore geometry, chrome flags) sees
- *   them;
+ *   them.
  * - the same head/bootstrap wiring (customElements.js, per-doc subscript,
  *   CSS + Fluent links) and `data-furnace-chrome-doc` sentinel as the
  *   generic scaffold, so jar.mn registration and the platform-module guard
@@ -89,7 +89,7 @@ export declare function generateChromeDocJs(name: string, licenseHeader: string)
  * the platform window controls that `global.css` applies by default.
  */
 export declare function generateChromeDocCss(name: string, withTitlebar: boolean, licenseHeader: string): string;
-/** Fluent stub — one placeholder message keyed to the window title. */
+/** Fluent stub with one placeholder message keyed to the window title. */
 export declare function generateChromeDocFtl(name: string, licenseHeader: string): string;
 /**
  * Single-line jar.mn entry that registers an xhtml + js pair under
@@ -110,7 +110,7 @@ export declare function jarMnEntriesForChromeDoc(name: string): string[];
  * The source path is `../shared/<name>-chrome.css` because `jar.inc.mn` is
  * included from each theme-specific manifest (`browser/themes/osx/jar.mn`,
  * `.../linux/`, `.../windows/`), and every existing entry in those manifests
- * resolves paths relative to the INCLUDING manifest's directory. A bare
+ * resolves paths relative to the including manifest's directory. A bare
  * `(shared/…)` path resolves to
  * `obj-.../browser/themes/osx/shared/<name>-chrome.css`, which does not
  * exist.
@@ -120,7 +120,7 @@ export declare function jarIncMnEntryForChromeDoc(name: string): string;
  * locales/jar.mn entry that registers the `.ftl` under the browser locale
  * bundle. The source path is resolved by mach-locale-jar relative to the
  * per-locale root (e.g. `engine/browser/locales/en-US/`), and the FTL file
- * is scaffolded at `browser/${name}.ftl` under that root — the `%` prefix
+ * is scaffolded at `browser/${name}.ftl` under that root. The `%` prefix
  * means "per-locale content" and the `browser/` subdirectory matches where
  * the scaffolder writes. A bare `(%${name}.ftl)` points at
  * `en-US/${name}.ftl` and breaks the first post-scaffold build with
@@ -132,11 +132,11 @@ export declare function localeJarMnEntryForChromeDoc(name: string): string;
  * wildcard rooted at `%browser/` whose pattern would already pick up a
  * scaffolded `browser/<name>.ftl` file. Recognises:
  *
- *   - `(%browser/**\/*.ftl)` — recursive (the upstream shape).
- *   - `(%browser/*.ftl)` — flat.
+ *   - `(%browser/**\/*.ftl)`: recursive (the upstream shape).
+ *   - `(%browser/*.ftl)`: flat.
  *
  * Forks that have migrated entirely to `[localization]` wildcards typically
- * keep no per-file `locale/...` entries for FTL at all; appending one
+ * keep no per-file `locale/...` entries for FTL at all. Appending one
  * there is dead weight at best, and an outright build break when the fork
  * has also dropped the `% locale browser …` registration. The chrome-doc
  * scaffolder consults this predicate before its locales/jar.mn append and
@@ -146,7 +146,7 @@ export declare function localeJarMnEntryForChromeDoc(name: string): string;
  * Conservative by design: only wildcards rooted at `%browser/` count, and
  * a `(%browser/foo.ftl)`-style explicit reference (no `*`) is not treated
  * as a capture. A fork with a narrower wildcard (e.g. `(%browser/about/*.ftl)`)
- * is correctly NOT captured by this predicate, because that wildcard would
+ * is correctly not captured by this predicate, because that wildcard would
  * not pick up the top-level `browser/<name>.ftl` the scaffold writes.
  */
 export declare function localesFtlWildcardCapturesScaffoldedName(jarMnContents: string): boolean;

package/dist/src/commands/furnace/chrome-doc-templates.js

@@ -12,7 +12,7 @@
  * Sentinel attribute emitted on every `furnace chrome-doc create`-scaffolded
  * root element. Platform modules (`DevToolsStartup`, `PageActions`,
  * `SessionStore`, `DownloadsButton`, …) that observe
- * `browser-delayed-startup-finished` and walk INTO the window assume the
+ * `browser-delayed-startup-finished` and walk into the window assume the
  * `browser.xhtml` DOM and throw on anything else. A fork-authored patch
  * to such a module can use `hasAttribute(...)` against this sentinel as
  * a cheap, fork-neutral guard to skip the walk on a custom chrome doc.
@@ -54,8 +54,8 @@ const FURNACE_CHROME_DOC_SENTINEL = 'data-furnace-chrome-doc';
  *   the README "Platform module compatibility" section for the pattern.
  */
 export function generateChromeDocXhtml(name, withTitlebar, license) {
-    // navigator:browser minimum set. Carrying every attribute together —
-    // not just `windowtype` — lets a fork that uses the scaffold output
+    // navigator:browser minimum set. Carrying every attribute together, not
+    // just `windowtype`, lets a fork that uses the scaffold output
     // verbatim launch as a real main window: `customtitlebar` opts into the
     // platform-native title bar handling that pairs with the buttonbox
     // markup below, the explicit width/height avoid the OS-minimum first
@@ -99,21 +99,21 @@ export function generateChromeDocXhtml(name, withTitlebar, license) {
 `;
 }
 /**
- * browser.xhtml-like scaffold for the document that ships as the fork's MAIN
- * BROWSER WINDOW.
+ * browser.xhtml-like scaffold for the document that ships as the fork's main
+ * browser window.
  *
  * The generic dialog-shaped `<window>` scaffold is wrong for the
  * `tokenHostDocuments[0]` / BROWSER_CHROME_URL target: platform C++ reads
- * the root element BEFORE any script runs, and expects the `browser.xhtml`
+ * the root element before any script runs, and expects the `browser.xhtml`
  * shape:
  *
- * - `<html id="main-window">` root (not `<window id="<name>-window">`) —
+ * - `<html id="main-window">` root (not `<window id="<name>-window">`):
  *   upstream code from nsXULWindow sizing to session restore looks up
- *   `main-window` by id;
+ *   `main-window` by id.
  * - `windowtype="navigator:browser"`, `chromehidden=""` and the geometry
- *   `persist` allowlist declared as ROOT ATTRIBUTES so the platform's
+ *   `persist` allowlist declared as root attributes so the platform's
  *   pre-script pass (window tracking, XULStore geometry, chrome flags) sees
- *   them;
+ *   them.
  * - the same head/bootstrap wiring (customElements.js, per-doc subscript,
  *   CSS + Fluent links) and `data-furnace-chrome-doc` sentinel as the
  *   generic scaffold, so jar.mn registration and the platform-module guard
@@ -252,7 +252,7 @@ export function generateChromeDocCss(name, withTitlebar, licenseHeader) {
 }${titlebarOverrides}
 `;
 }
-/** Fluent stub — one placeholder message keyed to the window title. */
+/** Fluent stub with one placeholder message keyed to the window title. */
 export function generateChromeDocFtl(name, licenseHeader) {
     return `${licenseHeader}
 
@@ -283,7 +283,7 @@ export function jarMnEntriesForChromeDoc(name) {
  * The source path is `../shared/<name>-chrome.css` because `jar.inc.mn` is
  * included from each theme-specific manifest (`browser/themes/osx/jar.mn`,
  * `.../linux/`, `.../windows/`), and every existing entry in those manifests
- * resolves paths relative to the INCLUDING manifest's directory. A bare
+ * resolves paths relative to the including manifest's directory. A bare
  * `(shared/…)` path resolves to
  * `obj-.../browser/themes/osx/shared/<name>-chrome.css`, which does not
  * exist.
@@ -295,7 +295,7 @@ export function jarIncMnEntryForChromeDoc(name) {
  * locales/jar.mn entry that registers the `.ftl` under the browser locale
  * bundle. The source path is resolved by mach-locale-jar relative to the
  * per-locale root (e.g. `engine/browser/locales/en-US/`), and the FTL file
- * is scaffolded at `browser/${name}.ftl` under that root — the `%` prefix
+ * is scaffolded at `browser/${name}.ftl` under that root. The `%` prefix
  * means "per-locale content" and the `browser/` subdirectory matches where
  * the scaffolder writes. A bare `(%${name}.ftl)` points at
  * `en-US/${name}.ftl` and breaks the first post-scaffold build with
@@ -309,11 +309,11 @@ export function localeJarMnEntryForChromeDoc(name) {
  * wildcard rooted at `%browser/` whose pattern would already pick up a
  * scaffolded `browser/<name>.ftl` file. Recognises:
  *
- *   - `(%browser/**\/*.ftl)` — recursive (the upstream shape).
- *   - `(%browser/*.ftl)` — flat.
+ *   - `(%browser/**\/*.ftl)`: recursive (the upstream shape).
+ *   - `(%browser/*.ftl)`: flat.
  *
  * Forks that have migrated entirely to `[localization]` wildcards typically
- * keep no per-file `locale/...` entries for FTL at all; appending one
+ * keep no per-file `locale/...` entries for FTL at all. Appending one
  * there is dead weight at best, and an outright build break when the fork
  * has also dropped the `% locale browser …` registration. The chrome-doc
  * scaffolder consults this predicate before its locales/jar.mn append and
@@ -323,7 +323,7 @@ export function localeJarMnEntryForChromeDoc(name) {
  * Conservative by design: only wildcards rooted at `%browser/` count, and
  * a `(%browser/foo.ftl)`-style explicit reference (no `*`) is not treated
  * as a capture. A fork with a narrower wildcard (e.g. `(%browser/about/*.ftl)`)
- * is correctly NOT captured by this predicate, because that wildcard would
+ * is correctly not captured by this predicate, because that wildcard would
  * not pick up the top-level `browser/<name>.ftl` the scaffold writes.
  */
 export function localesFtlWildcardCapturesScaffoldedName(jarMnContents) {

package/dist/src/commands/furnace/chrome-doc-tests.d.ts

@@ -1,6 +1,6 @@
 /**
  * Returns the canonical xpcshell test basename for a chrome doc packaging
- * check (`test_<name>_packaging.js`). Hyphens in `<name>` are preserved —
+ * check (`test_<name>_packaging.js`). Hyphens in `<name>` are preserved:
  * xpcshell permits them in file basenames even though the derived task
  * function names replace them with underscores.
  */
@@ -16,7 +16,7 @@ export declare function generateChromeDocPackagingTest(name: string, header: str
 /**
  * Emits the `xpcshell.toml` manifest for the packaging test directory.
  * Sets `firefox-appdir = "browser"` so XCurProcD resolves to the browser
- * subdir rather than the generic gecko runtime dir — without that, the
+ * subdir rather than the generic gecko runtime dir. Without that, the
  * path probe walks the wrong tree on every fork whose app directory is
  * not the default.
  */

package/dist/src/commands/furnace/chrome-doc-tests.js

@@ -10,7 +10,7 @@
  *   - xpcshell's `chrome://browser/*` URI registration lags what the real
  *     browser loads even with `firefox-appdir = "browser"` set, so
  *     `NetUtil.asyncFetch("chrome://browser/content/<name>.xhtml")` can fail
- *     with `NS_ERROR_FILE_NOT_FOUND` against a file that IS correctly
+ *     with `NS_ERROR_FILE_NOT_FOUND` against a file that is correctly
  *     packaged.
  *   - Browser-chrome mochitests require a `tabbrowser`, which a
  *     fork-authored chrome doc that replaces `browser.xhtml` deliberately
@@ -23,13 +23,13 @@
  * is stable across platforms at
  * `<AppDir>/chrome/browser/content/browser/<name>.xhtml` on an unpacked tree
  * (the default for `mach build` without `MOZ_CHROME_MULTILOCALE` / omnijar).
- * A tree that packs omni.ja would need a different probe; the scaffold notes
+ * A tree that packs omni.ja would need a different probe. The scaffold notes
  * that out-of-scope case explicitly rather than silently producing a test
  * that fails on packed builds.
  */
 /**
  * Returns the canonical xpcshell test basename for a chrome doc packaging
- * check (`test_<name>_packaging.js`). Hyphens in `<name>` are preserved —
+ * check (`test_<name>_packaging.js`). Hyphens in `<name>` are preserved:
  * xpcshell permits them in file basenames even though the derived task
  * function names replace them with underscores.
  */
@@ -132,7 +132,7 @@ add_task(async function test_${taskSuffix}_files_packaged() {
 /**
  * Emits the `xpcshell.toml` manifest for the packaging test directory.
  * Sets `firefox-appdir = "browser"` so XCurProcD resolves to the browser
- * subdir rather than the generic gecko runtime dir — without that, the
+ * subdir rather than the generic gecko runtime dir. Without that, the
  * path probe walks the wrong tree on every fork whose app directory is
  * not the default.
  */

package/dist/src/commands/furnace/chrome-doc.d.ts

@@ -1,10 +1,10 @@
 /**
- * `fireforge furnace chrome-doc create <name>` — scaffolds a top-level
+ * `fireforge furnace chrome-doc create <name>` scaffolds a top-level
  * chrome document (xhtml + js + css + ftl + jar.mn registrations).
  *
  * `furnace create` covers custom elements under `toolkit/content/widgets/`,
- * but top-level chrome documents — the `mybrowser.xhtml`-class entry points
- * a fork adds alongside or instead of `browser.xhtml` — are otherwise
+ * but top-level chrome documents (the `mybrowser.xhtml`-class entry points
+ * a fork adds alongside or instead of `browser.xhtml`) are otherwise
  * hand-authored with error-prone jar.mn + jar.inc.mn + locales/jar.mn glue.
  * The `*` preprocessor flag, the macOS titlebar-button carve-out, the
  * startup-topic observer, and the Fluent linkage each have silent-break
@@ -12,7 +12,7 @@
  *
  * This command writes the four source files and appends three jar.mn entries
  * under a rollback journal identical in shape to `furnace create`. A SIGINT
- * mid-scaffold restores every touched file; a successful run leaves the tree
+ * mid-scaffold restores every touched file. A successful run leaves the tree
  * ready for `fireforge build`.
  */
 /** Options for `furnace chrome-doc create`. */
@@ -28,16 +28,16 @@ export interface FurnaceChromeDocCreateOptions {
      * Scaffold an xpcshell packaging-verification test alongside the chrome
      * document. The generated test probes `XCurProcD/chrome/browser/...` on
      * disk rather than going through `chrome://` URI resolution, which
-     * bypasses xpcshell's limited browser-chrome manifest set — where
+     * bypasses xpcshell's limited browser-chrome manifest set, where
      * `NetUtil.asyncFetch` returns `NS_ERROR_FILE_NOT_FOUND` against a file
-     * that IS packaged. Registration in `XPCSHELL_TESTS_MANIFESTS` is left to
+     * that is packaged. Registration in `XPCSHELL_TESTS_MANIFESTS` is left to
      * the operator because the owning moz.build depends on the fork's layout.
      */
     withTests?: boolean;
     /** Print the scaffold plan without writing files. */
     dryRun?: boolean;
     /**
-     * Emit the browser.xhtml-like MAIN-WINDOW skeleton (`<html
+     * Emit the browser.xhtml-like main-window skeleton (`<html
      * id="main-window">` with the `windowtype`/`chromehidden`/`persist`
      * root attributes platform C++ reads before scripts run) instead of
      * the generic dialog-shaped `<window>` document. Use for the document
@@ -49,7 +49,7 @@ export interface FurnaceChromeDocCreateOptions {
 }
 /**
  * Validates a chrome-doc name. Lowercase ASCII, optional hyphens, no
- * leading digit — the name is used verbatim in CSS selectors, jar.mn
+ * leading digit. The name is used verbatim in CSS selectors, jar.mn
  * entries, FTL keys, and file basenames, so anything outside that
  * character set would break at least one downstream consumer.
  * @param name Chrome-doc name (file basename without extension).

package/dist/src/commands/furnace/chrome-doc.js

@@ -1,11 +1,11 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * `fireforge furnace chrome-doc create <name>` — scaffolds a top-level
+ * `fireforge furnace chrome-doc create <name>` scaffolds a top-level
  * chrome document (xhtml + js + css + ftl + jar.mn registrations).
  *
  * `furnace create` covers custom elements under `toolkit/content/widgets/`,
- * but top-level chrome documents — the `mybrowser.xhtml`-class entry points
- * a fork adds alongside or instead of `browser.xhtml` — are otherwise
+ * but top-level chrome documents (the `mybrowser.xhtml`-class entry points
+ * a fork adds alongside or instead of `browser.xhtml`) are otherwise
  * hand-authored with error-prone jar.mn + jar.inc.mn + locales/jar.mn glue.
  * The `*` preprocessor flag, the macOS titlebar-button carve-out, the
  * startup-topic observer, and the Fluent linkage each have silent-break
@@ -13,7 +13,7 @@
  *
  * This command writes the four source files and appends three jar.mn entries
  * under a rollback journal identical in shape to `furnace create`. A SIGINT
- * mid-scaffold restores every touched file; a successful run leaves the tree
+ * mid-scaffold restores every touched file. A successful run leaves the tree
  * ready for `fireforge build`.
  */
 import { join } from 'node:path';
@@ -33,7 +33,7 @@ import { chromeDocPackagingTestFileName, generateChromeDocPackagingManifest, gen
 const CHROME_DOC_NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 /**
  * Validates a chrome-doc name. Lowercase ASCII, optional hyphens, no
- * leading digit — the name is used verbatim in CSS selectors, jar.mn
+ * leading digit. The name is used verbatim in CSS selectors, jar.mn
  * entries, FTL keys, and file basenames, so anything outside that
  * character set would break at least one downstream consumer.
  * @param name Chrome-doc name (file basename without extension).
@@ -154,8 +154,8 @@ function renderChromeDocCreateDryRun(name, plan) {
  */
 async function appendJarEntryIfAbsent(filePath, entry, journal) {
     if (!(await pathExists(filePath))) {
-        // Target jar.mn doesn't exist in this tree layout. We do NOT create it
-        // — a fork that moved the jar file needs the operator to choose a
+        // Target jar.mn doesn't exist in this tree layout. We do not create it:
+        // a fork that moved the jar file needs the operator to choose a
         // placement. The command surfaces this as a FurnaceError so the user
         // can investigate rather than silently writing to a non-canonical path.
         throw new FurnaceError(`Required jar file ${filePath} does not exist; cannot register chrome-doc entry. Check that the fork's engine layout matches the expected browser/ and locales/ tree.`);
@@ -177,7 +177,7 @@ async function performChromeDocMutations(args) {
     const journal = createRollbackJournal();
     args.operationContext.registerJournal(journal);
     // XHTML uses an inline XML comment since getLicenseHeader has no XML
-    // style — the SPDX convention is a single-line comment at the top.
+    // style. The SPDX convention is a single-line comment at the top.
     const jsHeader = getLicenseHeader(args.license, 'js');
     const cssHeader = getLicenseHeader(args.license, 'css');
     const ftlHeader = getLicenseHeader(args.license, 'hash');
@@ -213,7 +213,7 @@ async function performChromeDocMutations(args) {
         await snapshotFile(journal, ftlPath);
         await writeText(ftlPath, generateChromeDocFtl(args.name, ftlHeader));
         written.push(`browser/locales/en-US/browser/${args.name}.ftl`);
-        // jar.mn registrations — XHTML + JS go through the `*` preprocessor
+        // jar.mn registrations: XHTML + JS go through the `*` preprocessor
         // for brand substitution, CSS goes through jar.inc.mn, FTL through
         // the locale jar.
         const jarMnPath = join(args.engineDir, 'browser/base/jar.mn');
@@ -226,12 +226,12 @@ async function performChromeDocMutations(args) {
         written.push('browser/themes/shared/jar.inc.mn');
         const localeJarMnPath = join(args.engineDir, 'browser/locales/jar.mn');
         // Forks that have migrated to a `[localization] (%browser/**/*.ftl)`
-        // wildcard already pick up the scaffolded FTL automatically — appending
-        // a per-file `locale/...` entry on top is at best dead weight and at
-        // worst a build error when the fork has dropped the `% locale browser`
-        // registration the per-file entry depends on. The wildcard predicate is
-        // intentionally narrow: only `%browser/`-rooted globs ending in `*.ftl`
-        // count as a capture.
+        // wildcard already pick up the scaffolded FTL automatically, so
+        // appending a per-file `locale/...` entry on top is at best dead weight
+        // and at worst a build error when the fork has dropped the
+        // `% locale browser` registration the per-file entry depends on. The
+        // wildcard predicate is narrow on purpose: only `%browser/`-rooted globs
+        // ending in `*.ftl` count as a capture.
         if (await pathExists(localeJarMnPath)) {
             const existingLocaleJar = await readText(localeJarMnPath);
             if (localesFtlWildcardCapturesScaffoldedName(existingLocaleJar)) {
@@ -298,12 +298,12 @@ export async function furnaceChromeDocCreateCommand(projectRoot, name, options =
     });
     const browserWindow = options.browserWindow ?? false;
     // The browser-window skeleton always carries its own titlebar markup and
-    // chrome attributes; --no-titlebar only applies to the generic scaffold.
+    // chrome attributes. --no-titlebar only applies to the generic scaffold.
     const withTitlebar = browserWindow ? true : (options.titlebar ?? true);
     const withTests = options.withTests ?? false;
     // Hint: when the scaffolded document is the configured token-host document
     // (the fork's main browser window), the generic dialog-shaped scaffold is
-    // almost certainly wrong — correct jar.mn registrations, wrong document
+    // almost certainly wrong: correct jar.mn registrations, wrong document
     // body.
     if (!browserWindow && (await furnaceConfigExists(projectRoot))) {
         try {
@@ -317,7 +317,7 @@ export async function furnaceChromeDocCreateCommand(projectRoot, name, options =
             }
         }
         catch {
-            // A broken furnace.json must not block chrome-doc scaffolding; the
+            // A broken furnace.json must not block chrome-doc scaffolding. The
             // hint is best-effort.
         }
     }

package/dist/src/commands/furnace/create-browser-test.d.ts

@@ -1,7 +1,7 @@
 /**
  * Browser-chrome test scaffolding for `furnace create --with-tests`,
  * including the `--test-dir` redirect and collision safety (existing
- * manifests are appended to; head.js and test implementations are never
+ * manifests are appended to, and head.js and test implementations are never
  * overwritten). Split out of `create.ts` to keep that command file within
  * the per-file line budget.
  */