npm - @hominis/fireforge - Versions diffs - 0.18.3 → 0.18.6 - Mend

@hominis/fireforge 0.18.3 → 0.18.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

package/README.md +10 -4
package/dist/src/commands/build.js +27 -12
package/dist/src/commands/config.js +64 -6
package/dist/src/commands/furnace/chrome-doc-templates.d.ts +59 -8
package/dist/src/commands/furnace/chrome-doc-templates.js +95 -12
package/dist/src/commands/furnace/chrome-doc.js +24 -2
package/dist/src/commands/furnace/deploy.js +10 -1
package/dist/src/commands/furnace/init.js +28 -2
package/dist/src/commands/lint.js +22 -3
package/dist/src/commands/patch/delete.js +2 -4
package/dist/src/commands/patch/lint-ignore.js +2 -4
package/dist/src/commands/patch/reorder.js +2 -4
package/dist/src/commands/patch/tier.js +2 -4
package/dist/src/commands/status.js +13 -2
package/dist/src/core/furnace-apply.js +11 -3
package/dist/src/core/furnace-marker.d.ts +16 -0
package/dist/src/core/furnace-marker.js +23 -0
package/dist/src/core/furnace-registration-ast.js +1 -3
package/dist/src/core/git.js +66 -10
package/dist/src/core/patch-identifier-suggest.d.ts +25 -0
package/dist/src/core/patch-identifier-suggest.js +108 -0
package/dist/src/core/register-shared-css.d.ts +28 -0
package/dist/src/core/register-shared-css.js +59 -1
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -358,11 +358,11 @@ fireforge furnace chrome-doc create mybrowser --with-tests # + xpcshell packagin
 The command writes:
-- `engine/browser/base/content/<name>.xhtml` — XHTML shell, optional titlebar-buttonbox, Fluent `<link>`.
+- `engine/browser/base/content/<name>.xhtml` — XHTML shell. `data-l10n-id` is bound on the leaf `<title>` only (binding it on the root `<window>` would let Fluent's first-paint translation pass overwrite the entire body subtree, the standard `data-l10n-id`-on-non-leaf failure mode). The `<head>` loads `chrome://global/content/customElements.js` ahead of the per-doc subscript so any `<moz-*>` widget the author drops into the body resolves through the toolkit registry instead of silently degrading to `HTMLUnknownElement` — matches the `webrtcIndicator.xhtml` shape upstream uses for non-`browser.xhtml` chrome documents. Under `--with-titlebar` (the default) the root carries the `navigator:browser` minimum attribute set: `windowtype="navigator:browser"`, `customtitlebar="true"`, default `width="1024"` / `height="640"`, and `persist="screenX screenY width height sizemode"` so XULStore remembers geometry across restarts; without these a fork shipping the scaffold verbatim opens at the OS intrinsic minimum size on first launch and forgets the user's window position.
 - `engine/browser/base/content/<name>.js` — startup-topic observer fired on first idle.
-- `engine/browser/themes/shared/<name>-chrome.css` — scoped CSS; emits the macOS `.titlebar-button { display: none }` carve-out under `--no-titlebar`.
+- `engine/browser/themes/shared/<name>-chrome.css` — scoped CSS. Under `--with-titlebar` the buttonbox container is a `-moz-window-dragging: drag` region and `.titlebar-buttonbox` opts into the platform-native `-moz-window-button-box` appearance so the OS renders traffic-light / minimize-maximize-close controls in their canonical positions; under `--no-titlebar` the macOS `.titlebar-button { display: none }` carve-out is emitted instead so frameless overlays don't inherit the platform window controls `global.css` applies by default.
 - `engine/browser/locales/en-US/browser/<name>.ftl` — Fluent stub keyed on `<name>-window-title`.
-- Appends the corresponding `jar.mn` / `jar.inc.mn` / `locales/jar.mn` entries.
+- Appends the corresponding `jar.mn` / `jar.inc.mn` entries. The locales/jar.mn append is suppressed when the fork's existing `engine/browser/locales/jar.mn` already carries a `[localization] (%browser/**/*.ftl)` (or `(%browser/*.ftl)`) wildcard that would already pick up the scaffolded FTL — on those forks a per-file `locale/<name>.ftl` entry would be dead weight at best and an outright build break when the fork has dropped the `% locale browser …` registration the per-file entry depends on. Forks still on the legacy registration get the per-file entry as before.
 - When `--with-tests` is set, also scaffolds an xpcshell test + `xpcshell.toml` under `engine/browser/base/content/test/<binary>-xpcshell/<name>/` that probes the packaged app directory (`Services.dirsvc.get("XCurProcD")/chrome/browser/...`) directly rather than going through `chrome://` URI resolution — see "Platform module compatibility" and the xpcshell chrome-URI note further down for why direct filesystem probing is the reliable way to verify chrome-doc packaging. Registration in `XPCSHELL_TESTS_MANIFESTS` is left to the operator because the owning moz.build depends on the fork layout.
 Writes are transactional: a SIGINT mid-scaffold rolls back every touched file. Requires an existing engine — run `fireforge download` first.
@@ -429,6 +429,8 @@ fireforge config customKey "value" --force
 Writes are serialised behind a sidecar lock — two concurrent `fireforge config` invocations against the same `fireforge.json` (for example, parallel automation steps) queue instead of racing the read-modify-write. The lock is released automatically on process exit; stale locks from a crashed earlier command are reclaimed on the next invocation via the PID-alive probe.
+Re-setting a key to its current value is a no-op: `fireforge.json` is not rewritten, key ordering is preserved, and the success log surfaces `<key> = <value> (unchanged)` instead of a fresh `Set …` line. This means automation that idempotently runs `fireforge config <key> <value>` no longer produces spurious diffs in `fireforge.json`.
 ### Patch queue management
 ```bash
@@ -476,7 +478,7 @@ fireforge token add --category 'Colors — General' --mode static -- --my-color
 fireforge token add --category 'Colors — General' --mode static my-color   '#fff'   # bare-name form
 ```
-Tokens live in the Furnace-managed tokens CSS file (`engine/browser/themes/shared/<binaryName>-tokens.css`), scaffolded by `fireforge furnace init` alongside `furnace.json`. The scaffold seeds a default set of categories (`Colors — General`, `Colors — Canvas`, `Colors — Experiment`, `Spacing`); add a category by hand as a `/* = My Category = */` comment inside the `:root { … }` block if you need another. `fireforge furnace init` also registers the tokens CSS path in `patchLint.rawColorAllowlist` so raw color literals inside it are not flagged by `fireforge lint`, and derives `tokenPrefix: --<binaryName>-` from `fireforge.json`'s `binaryName` so `fireforge token coverage` has a prefix to key off on the very first run. Projects that prefer a different prefix can override it in `furnace.json` after init.
+Tokens live in the Furnace-managed tokens CSS file (`engine/browser/themes/shared/<binaryName>-tokens.css`), scaffolded by `fireforge furnace init` alongside `furnace.json`. The scaffold seeds a default set of categories (`Colors — General`, `Colors — Canvas`, `Colors — Experiment`, `Spacing`); add a category by hand as a `/* = My Category = */` comment inside the `:root { … }` block if you need another. `fireforge furnace init` does three more things in the same step so the file is owned end-to-end by tooling: it registers the tokens CSS path in `patchLint.rawColorAllowlist` (so raw color literals inside it are not flagged by `fireforge lint`); it adds the matching `skin/classic/browser/<binaryName>-tokens.css (../shared/<binaryName>-tokens.css)` entry to `browser/themes/shared/jar.inc.mn` (so `fireforge status` does not flag the file as unmanaged or unregistered); and it derives `tokenPrefix: --<binaryName>-` from `fireforge.json`'s `binaryName` so `fireforge token coverage` has a prefix to key off on the very first run. Projects that prefer a different prefix can override it in `furnace.json` after init.
 ### Diff-scoped lint (`lint --since`)
@@ -518,6 +520,10 @@ The build also auto-runs `mach configure` before the mach build step when any `m
 Mach build failures with known-cryptic mozbuild errors now print actionable hints. Example: a `JS_PREFERENCE_PP_FILES` entry with no `#filter` / `#expand` directives now prints `Hint: ...use JS_PREFERENCE_FILES instead, or add at least one #filter / #expand directive to the file.` alongside the raw mach traceback.
+When mach prints a post-build `config.status is out of date …` or `Config object not found by mach. / Configure complete!` banner on a successful build, FireForge surfaces a one-line annotation immediately before its own `Build completed in Xm Ys!` outro explaining that the banner is a known side effect of tool-managed branding edits applied before the build and that the build does not need to be re-run. The FireForge exit code remains authoritative regardless of the mach guard text.
+The reported `Build completed in Xm Ys!` duration is wall-clock measured with `Date.now()`, so it includes any time the host spent suspended (laptop sleep, system idle) during the build. Treat it as wall-clock-with-sleep, not active CPU time, when comparing builds across machines or sessions.
 ### Relocated workspaces: `fireforge build --rewrite-mozinfo`
 When a workspace is moved to a new path (e.g. the project directory was renamed or relocated on disk), `obj-*/mozinfo.json` still records the old `topsrcdir` / `topobjdir`. The pre-flight detects the mismatch and aborts with a "delete and rebuild" instruction — correct but expensive; a fresh clean build typically runs ~20 minutes and discards ~14 GB of intact obj artefacts on a moved checkout.

package/dist/src/commands/build.js CHANGED Viewed

@@ -157,18 +157,33 @@ export async function buildCommand(projectRoot, options) {
         throw new BuildError(`Build failed with exit code ${result.exitCode}`, options.ui ? 'mach build faster' : 'mach build');
     }
     // Tool-managed branding edits that land on `browser/moz.configure`
-    // before the build cause mach's post-build guard to print
-    // "config.status is out of date … Be sure to run |mach build|" even
-    // though the build itself completed cleanly. 2026-04-21 eval finding:
-    // operators read that as "your build is stale" and either rebuilt
-    // (wasting ~10 minutes) or doubted the Fireforge "Build completed"
-    // footer. Annotate the captured output so the operator knows the
-    // warning is expected and not actionable.
-    const staleConfigurePattern = /config\.status is out of date/i;
-    if (staleConfigurePattern.test(result.stdout) || staleConfigurePattern.test(result.stderr)) {
-        info('Note: mach reported "config.status is out of date" after this build. ' +
-            'That notice is a known side effect of tool-managed branding edits applied before the build ' +
-            'and does not require a rebuild — the Fireforge exit code is authoritative.');
+    // before the build cause mach's post-build guard to print one of two
+    // banners that read like build failures even though the build
+    // completed cleanly:
+    //
+    //   1) "config.status is out of date with respect to ..."
+    //   2) "Config object not found by mach. / Configure complete! /
+    //      Be sure to run |mach build| to pick up any changes."
+    //
+    // 2026-04-21 eval covered (1); 2026-04-26 eval Finding 8 reproduced
+    // (2) on a successful build. The pre-fix pattern only matched (1),
+    // so operators on the (2) path saw mach's own "Configure complete!"
+    // and "run |mach build|" lines unexplained between mach's
+    // "Your build was successful!" and FireForge's own "Build completed
+    // in Xm Ys" outro — a contradictory tail. Both shapes now route
+    // through the same annotation, emitted BEFORE FireForge's outro so
+    // the operator's last terminal line is the explanation, not the
+    // confusing mach guard text.
+    const staleConfigurePatterns = [
+        /config\.status is out of date/i,
+        /Config object not found by mach\.[\s\S]*Configure complete!/i,
+    ];
+    const captured = `${result.stdout}\n${result.stderr}`;
+    if (staleConfigurePatterns.some((p) => p.test(captured))) {
+        info('Note: mach printed a post-build "Configure complete!" / "config.status is out of date" ' +
+            'banner. That is a known side effect of tool-managed branding edits applied before the ' +
+            'build and does not mean the build is stale or that you need to rerun mach — the FireForge ' +
+            'exit code is authoritative.');
     }
     // Warn-only post-build audit: surfaces silent packaging drops (files
     // edited in engine/ but never registered for packaging) against the

package/dist/src/commands/config.js CHANGED Viewed

@@ -66,10 +66,15 @@ function formatValue(value) {
     if (value === undefined) {
         return '(not set)';
     }
-    if (value === null || typeof value === 'object' || typeof value === 'function') {
-        return JSON.stringify(value, null, 2);
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
+        return String(value);
+    }
+    if (typeof value === 'symbol') {
+        return value.toString();
     }
-    return String(value);
+    return JSON.stringify(value, null, 2);
 }
 /**
  * Runs the config command to get or set configuration values.
@@ -111,6 +116,7 @@ export async function configCommand(projectRoot, key, value, options = {}) {
         }
         const parsedValue = parseValue(value, key);
         const keyIsKnown = SUPPORTED_CONFIG_PATHS.includes(key);
+        let unchanged;
         try {
             // Serialise the read → mutate → write round-trip behind the sidecar
             // config lock so two concurrent `fireforge config` invocations can't
@@ -122,7 +128,21 @@ export async function configCommand(projectRoot, key, value, options = {}) {
             // were never enough on their own — the lost update happens before
             // the rename, inside the read-modify step. Readers stay lock-free
             // (see `withConfigFileLock` docstring).
-            await withConfigFileLock(projectRoot, async () => {
+            unchanged = await withConfigFileLock(projectRoot, async () => {
+                // 2026-04-26 eval Finding 11: short-circuit when the new value
+                // matches the current on-disk value. Pre-fix, every set ran
+                // through `mutateConfig` + `writeConfig`, which round-trips
+                // through `JSON.stringify` and rewrites the file even when no
+                // semantic change happened — the rewrite reorders top-level
+                // keys (`license`, `markerComment`, etc.) on every harmless
+                // re-set, producing diff churn for no reason. The check uses
+                // the raw on-disk document so forced-keys round-trip the same
+                // as known keys.
+                const rawConfig = await loadRawConfigDocument(projectRoot);
+                const currentValue = getNestedValue(rawConfig, key);
+                if (deepEqual(currentValue, parsedValue)) {
+                    return true;
+                }
                 // `--force` is intended as an escape hatch for *unknown* keys; it
                 // should not also let the user write a structurally invalid value
                 // for a *known* key. Apply strict validation whenever the key is
@@ -133,7 +153,6 @@ export async function configCommand(projectRoot, key, value, options = {}) {
                     // keys (which `validateConfig` would strip) survive the round-trip.
                     // Without this, writing a second --force key would silently drop
                     // every earlier forced key from fireforge.json.
-                    const rawConfig = await loadRawConfigDocument(projectRoot);
                     const updatedConfig = mutateConfig(rawConfig, key, parsedValue, true);
                     await writeConfigDocument(projectRoot, updatedConfig);
                 }
@@ -142,15 +161,54 @@ export async function configCommand(projectRoot, key, value, options = {}) {
                     const updatedConfig = mutateConfig(config, key, parsedValue);
                     await writeConfig(projectRoot, updatedConfig);
                 }
+                return false;
             });
         }
         catch (error) {
             throw new InvalidArgumentError(`Invalid value for "${key}": ${toError(error).message}`, key);
         }
-        success(`Set ${key} = ${formatValue(parsedValue)}`);
+        if (unchanged) {
+            info(`${key} = ${formatValue(parsedValue)} (unchanged)`);
+        }
+        else {
+            success(`Set ${key} = ${formatValue(parsedValue)}`);
+        }
     }
     outro('');
 }
+/**
+ * Structural equality check covering the shapes that
+ * `fireforge config` accepts: primitives (strings, numbers, booleans),
+ * `null`, arrays of primitives, and nested objects. Used to short-circuit
+ * no-op writes (Finding 11) — when the parsed value matches the current
+ * on-disk value, skip the mutate + write step entirely.
+ */
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (a === null || b === null)
+        return a === b;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a !== 'object')
+        return false;
+    if (Array.isArray(a)) {
+        if (!Array.isArray(b))
+            return false;
+        if (a.length !== b.length)
+            return false;
+        return a.every((v, i) => deepEqual(v, b[i]));
+    }
+    if (Array.isArray(b))
+        return false;
+    const ar = a;
+    const br = b;
+    const keysA = Object.keys(ar);
+    const keysB = Object.keys(br);
+    if (keysA.length !== keysB.length)
+        return false;
+    return keysA.every((k) => deepEqual(ar[k], br[k]));
+}
 /** Registers the config command on the CLI program. */
 export function registerConfig(program, { getProjectRoot, withErrorHandling }) {
     program

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

@@ -24,12 +24,29 @@ export declare const FURNACE_CHROME_DOC_SENTINEL = "data-furnace-chrome-doc";
  * XHTML shell for a top-level chrome document.
  *
  * The emitted document:
- * - Declares `windowtype="navigator:browser"` when `withTitlebar` is true
- *   so chrome-wide stylesheets that target the browser window still apply.
- * - Emits a titlebar-buttonbox placeholder when `withTitlebar` is true so
- *   platform-native window controls render.
+ * - When `withTitlebar` is true, declares the `navigator:browser` minimum
+ *   set: `windowtype`, `customtitlebar`, default `width`/`height`, and a
+ *   `persist` allowlist for screen position + size + sizemode. Without
+ *   these, a fork-owned chrome doc that ships as the main window opens
+ *   at the OS intrinsic minimum size on first launch and forgets the
+ *   user's last-known geometry across restarts. The titlebar-buttonbox
+ *   placeholder is emitted alongside so platform-native window controls
+ *   render with the matching CSS rules from `generateChromeDocCss`.
+ * - Loads `chrome://global/content/customElements.js` in `<head>` ahead
+ *   of the per-doc subscript. Without it, every `<moz-*>` widget the
+ *   author drops into the body silently degrades to `HTMLUnknownElement`
+ *   and the upstream a11y/keyboard semantics that motivated the use of
+ *   the toolkit widget in the first place are lost. Matches the
+ *   `webrtcIndicator.xhtml` shape upstream uses for non-`browser.xhtml`
+ *   chrome documents.
  * - Links the per-document CSS at `chrome://browser/content/<name>-chrome.css`
  *   and the Fluent bundle `browser/<name>.ftl`.
+ * - Keeps `data-l10n-id` on the leaf `<title>` only. Binding the same key
+ *   on the root `<window>` would cause Fluent's first-paint translation
+ *   pass to overwrite the entire body subtree with the message's text
+ *   value (the standard `data-l10n-id`-on-non-leaf failure mode), since
+ *   the FTL stub gives `<name>-window-title` a value rather than an
+ *   attribute-only message.
  * - Carries the `data-furnace-chrome-doc="<name>"` sentinel so fork-side
  *   patches to upstream platform modules (DevToolsStartup, PageActions, …)
  *   that assume `browser.xhtml`'s DOM can guard against it cheaply. See
@@ -46,10 +63,21 @@ export declare function generateChromeDocXhtml(name: string, withTitlebar: boole
  */
 export declare function generateChromeDocJs(name: string, licenseHeader: string): string;
 /**
- * Scoped CSS for a chrome document. When `withTitlebar` is false the
- * macOS `.titlebar-button { display: none }` carve-out is emitted so
- * frameless overlay-style documents don't inherit the platform window
- * controls that `global.css` applies by default.
+ * Scoped CSS for a chrome document.
+ *
+ * When `withTitlebar` is true, the matching navigator:browser minimum
+ * CSS is emitted alongside the layout rules: the buttonbox container is
+ * a draggable region (`-moz-window-dragging: drag`) so the user can drag
+ * the window from the title bar, and the buttonbox itself opts into the
+ * platform-native window-button-box appearance so the OS renders the
+ * traffic-light / minimize-maximize-close controls in their canonical
+ * positions. Without these rules the buttonbox markup still draws but
+ * is unstyled and non-draggable, which is the failure mode a fork that
+ * ships the scaffold verbatim hits on first launch.
+ *
+ * When `withTitlebar` is false the macOS `.titlebar-button { display: none }`
+ * carve-out is emitted so frameless overlay-style documents don't inherit
+ * 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. */
@@ -92,3 +120,26 @@ export declare function jarIncMnEntryForChromeDoc(name: string): string;
  * "jar.mn: Cannot find ${name}.ftl".
  */
 export declare function localeJarMnEntryForChromeDoc(name: string): string;
+/**
+ * Returns true when `jarMnContents` already carries a `[localization]`-style
+ * 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.
+ *
+ * Forks that have migrated entirely to `[localization]` wildcards typically
+ * 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
+ * skips the per-file write when the wildcard already covers the scaffold's
+ * target path.
+ *
+ * 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
+ * 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 CHANGED Viewed

@@ -25,19 +25,49 @@ export const FURNACE_CHROME_DOC_SENTINEL = 'data-furnace-chrome-doc';
  * XHTML shell for a top-level chrome document.
  *
  * The emitted document:
- * - Declares `windowtype="navigator:browser"` when `withTitlebar` is true
- *   so chrome-wide stylesheets that target the browser window still apply.
- * - Emits a titlebar-buttonbox placeholder when `withTitlebar` is true so
- *   platform-native window controls render.
+ * - When `withTitlebar` is true, declares the `navigator:browser` minimum
+ *   set: `windowtype`, `customtitlebar`, default `width`/`height`, and a
+ *   `persist` allowlist for screen position + size + sizemode. Without
+ *   these, a fork-owned chrome doc that ships as the main window opens
+ *   at the OS intrinsic minimum size on first launch and forgets the
+ *   user's last-known geometry across restarts. The titlebar-buttonbox
+ *   placeholder is emitted alongside so platform-native window controls
+ *   render with the matching CSS rules from `generateChromeDocCss`.
+ * - Loads `chrome://global/content/customElements.js` in `<head>` ahead
+ *   of the per-doc subscript. Without it, every `<moz-*>` widget the
+ *   author drops into the body silently degrades to `HTMLUnknownElement`
+ *   and the upstream a11y/keyboard semantics that motivated the use of
+ *   the toolkit widget in the first place are lost. Matches the
+ *   `webrtcIndicator.xhtml` shape upstream uses for non-`browser.xhtml`
+ *   chrome documents.
  * - Links the per-document CSS at `chrome://browser/content/<name>-chrome.css`
  *   and the Fluent bundle `browser/<name>.ftl`.
+ * - Keeps `data-l10n-id` on the leaf `<title>` only. Binding the same key
+ *   on the root `<window>` would cause Fluent's first-paint translation
+ *   pass to overwrite the entire body subtree with the message's text
+ *   value (the standard `data-l10n-id`-on-non-leaf failure mode), since
+ *   the FTL stub gives `<name>-window-title` a value rather than an
+ *   attribute-only message.
  * - Carries the `data-furnace-chrome-doc="<name>"` sentinel so fork-side
  *   patches to upstream platform modules (DevToolsStartup, PageActions, …)
  *   that assume `browser.xhtml`'s DOM can guard against it cheaply. See
  *   the README "Platform module compatibility" section for the pattern.
  */
 export function generateChromeDocXhtml(name, withTitlebar, license) {
-    const windowAttr = withTitlebar ? ' windowtype="navigator:browser"' : '';
+    // 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
+    // launch, and `persist` lets the platform remember geometry across
+    // restarts via XULStore.
+    const navigatorBrowserAttrs = withTitlebar
+        ? ` windowtype="navigator:browser"
+    customtitlebar="true"
+    width="1024"
+    height="640"
+    persist="screenX screenY width height sizemode"`
+        : '';
     const titlebarMarkup = withTitlebar
         ? `
     <hbox class="titlebar-buttonbox-container">
@@ -50,9 +80,8 @@ export function generateChromeDocXhtml(name, withTitlebar, license) {
 <window
     xmlns="http://www.w3.org/1999/xhtml"
     xmlns:xul="http://www.mozilla.org/keymaster/gatekeeper/there.is.only.xul"
-    id="${name}-window"${windowAttr}
+    id="${name}-window"${navigatorBrowserAttrs}
     ${FURNACE_CHROME_DOC_SENTINEL}="${name}"
-    data-l10n-id="${name}-window-title"
     role="application">
   <head>
     <meta charset="utf-8" />
@@ -60,6 +89,7 @@ export function generateChromeDocXhtml(name, withTitlebar, license) {
     <link rel="localization" href="browser/${name}.ftl" />
     <link rel="stylesheet" href="chrome://global/skin/global.css" />
     <link rel="stylesheet" href="chrome://browser/content/${name}-chrome.css" />
+    <script src="chrome://global/content/customElements.js"></script>
     <script src="chrome://browser/content/${name}.js"></script>
   </head>
   <body>${titlebarMarkup}
@@ -105,14 +135,42 @@ window.addEventListener(
 `;
 }
 /**
- * Scoped CSS for a chrome document. When `withTitlebar` is false the
- * macOS `.titlebar-button { display: none }` carve-out is emitted so
- * frameless overlay-style documents don't inherit the platform window
- * controls that `global.css` applies by default.
+ * Scoped CSS for a chrome document.
+ *
+ * When `withTitlebar` is true, the matching navigator:browser minimum
+ * CSS is emitted alongside the layout rules: the buttonbox container is
+ * a draggable region (`-moz-window-dragging: drag`) so the user can drag
+ * the window from the title bar, and the buttonbox itself opts into the
+ * platform-native window-button-box appearance so the OS renders the
+ * traffic-light / minimize-maximize-close controls in their canonical
+ * positions. Without these rules the buttonbox markup still draws but
+ * is unstyled and non-draggable, which is the failure mode a fork that
+ * ships the scaffold verbatim hits on first launch.
+ *
+ * When `withTitlebar` is false the macOS `.titlebar-button { display: none }`
+ * carve-out is emitted so frameless overlay-style documents don't inherit
+ * the platform window controls that `global.css` applies by default.
  */
 export function generateChromeDocCss(name, withTitlebar, licenseHeader) {
     const titlebarOverrides = withTitlebar
-        ? ''
+        ? `
+/* navigator:browser minimum titlebar styling. Pairs with the
+   \`customtitlebar="true"\` + \`titlebar-buttonbox\` markup the XHTML
+   template emits when --with-titlebar is set. The container is the drag
+   region; the inner buttonbox opts into the platform-native traffic
+   light / minimize-maximize-close appearance via \`-moz-window-button-box\`. */
+.titlebar-buttonbox-container {
+  -moz-window-dragging: drag;
+  display: flex;
+  align-items: center;
+}
+.titlebar-buttonbox {
+  appearance: auto;
+  -moz-default-appearance: -moz-window-button-box;
+}
+`
         : `
 /* Frameless overlay — suppress the platform titlebar buttons that
@@ -194,4 +252,29 @@ export function jarIncMnEntryForChromeDoc(name) {
 export function localeJarMnEntryForChromeDoc(name) {
     return `    locale/browser/${name}.ftl                    (%browser/${name}.ftl)`;
 }
+/**
+ * Returns true when `jarMnContents` already carries a `[localization]`-style
+ * 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.
+ *
+ * Forks that have migrated entirely to `[localization]` wildcards typically
+ * 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
+ * skips the per-file write when the wildcard already covers the scaffold's
+ * target path.
+ *
+ * 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
+ * not pick up the top-level `browser/<name>.ftl` the scaffold writes.
+ */
+export function localesFtlWildcardCapturesScaffoldedName(jarMnContents) {
+    return /\(%browser\/(?:\*\*\/)?\*\.ftl\)/.test(jarMnContents);
+}
 //# sourceMappingURL=chrome-doc-templates.js.map

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

@@ -25,7 +25,7 @@ import { InvalidArgumentError } from '../../errors/base.js';
 import { FurnaceError } from '../../errors/furnace.js';
 import { pathExists, readText, writeText } from '../../utils/fs.js';
 import { intro, note, outro } from '../../utils/logger.js';
-import { generateChromeDocCss, generateChromeDocFtl, generateChromeDocJs, generateChromeDocXhtml, jarIncMnEntryForChromeDoc, jarMnEntriesForChromeDoc, localeJarMnEntryForChromeDoc, } from './chrome-doc-templates.js';
+import { generateChromeDocCss, generateChromeDocFtl, generateChromeDocJs, generateChromeDocXhtml, jarIncMnEntryForChromeDoc, jarMnEntriesForChromeDoc, localeJarMnEntryForChromeDoc, localesFtlWildcardCapturesScaffoldedName, } from './chrome-doc-templates.js';
 import { chromeDocPackagingTestFileName, generateChromeDocPackagingManifest, generateChromeDocPackagingTest, } from './chrome-doc-tests.js';
 /** Chrome-doc name shape: lowercase ASCII, optional hyphens, no leading digit. */
 const CHROME_DOC_NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
@@ -122,7 +122,29 @@ async function performChromeDocMutations(args) {
         await appendJarEntryIfAbsent(jarIncMnPath, jarIncMnEntryForChromeDoc(args.name), journal);
         written.push('browser/themes/shared/jar.inc.mn');
         const localeJarMnPath = join(args.engineDir, 'browser/locales/jar.mn');
-        await appendJarEntryIfAbsent(localeJarMnPath, localeJarMnEntryForChromeDoc(args.name), journal);
+        // 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 that end in
+        // `*.ftl` count as a capture.
+        if (await pathExists(localeJarMnPath)) {
+            const existingLocaleJar = await readText(localeJarMnPath);
+            if (localesFtlWildcardCapturesScaffoldedName(existingLocaleJar)) {
+                note(`Locale jar.mn already carries a [localization] wildcard that captures browser/${args.name}.ftl — skipping the per-file entry.`, args.name);
+            }
+            else {
+                await appendJarEntryIfAbsent(localeJarMnPath, localeJarMnEntryForChromeDoc(args.name), journal);
+            }
+        }
+        else {
+            // Preserve the existing "missing locale jar.mn" failure mode: pretend
+            // we still want to append so appendJarEntryIfAbsent surfaces the same
+            // FurnaceError it does for the other two jars. Forks that move the
+            // file deserve the same explicit complaint everywhere.
+            await appendJarEntryIfAbsent(localeJarMnPath, localeJarMnEntryForChromeDoc(args.name), journal);
+        }
         written.push('browser/locales/jar.mn');
         // --with-tests scaffolds an xpcshell packaging verification. All writes
         // go through the same rollback journal so a SIGINT here restores the

package/dist/src/commands/furnace/deploy.js CHANGED Viewed

@@ -5,6 +5,7 @@ import { applyAllComponents, applyCustomComponent, applyOverrideComponent, compu
 import { logApplyResult } from '../../core/furnace-apply-output.js';
 import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, updateFurnaceState, } from '../../core/furnace-config.js';
 import { resolveFtlDir } from '../../core/furnace-constants.js';
+import { resolveFurnaceMarkerComment } from '../../core/furnace-marker.js';
 import { recordFurnaceRollbackFailure, runFurnaceMutation, } from '../../core/furnace-operation.js';
 import { createRollbackJournal, restoreRollbackJournalOrThrow, } from '../../core/furnace-rollback.js';
 import { findOverrideBaseVersionDrift, formatOverrideBaseVersionDriftError, formatOverrideBaseVersionDriftWarning, } from '../../core/furnace-version-drift.js';
@@ -305,6 +306,14 @@ export async function furnaceDeployCommand(projectRoot, name, options = {}) {
     // the plan before deciding whether to refresh the override or acknowledge
     // the new baseline in furnace.json.
     const forgeConfig = await loadConfig(projectRoot);
+    // 2026-04-26 eval Finding 6: when `markerComment` is unset in
+    // fireforge.json, default it to `binaryName.toUpperCase()` so the
+    // furnace-emitted edits to upstream files satisfy
+    // `lintModificationComments` on the next `lint`/`export` round-trip.
+    // The lint rule keys on the same uppercased binaryName, so the
+    // implicit default is identical to what the rule expects. Threaded
+    // through `applyNamedComponent` below.
+    const resolvedMarkerComment = resolveFurnaceMarkerComment(forgeConfig);
     const driftEntries = findOverrideBaseVersionDrift(config, forgeConfig.firefox.version);
     const force = options.force ?? false;
     const scopedDrift = name ? driftEntries.filter((entry) => entry.name === name) : driftEntries;
@@ -317,7 +326,7 @@ export async function furnaceDeployCommand(projectRoot, name, options = {}) {
     // `furnace deploy` runs only contend on the actual mutation.
     const applyOutcome = await runFurnaceMutation(projectRoot, 'deploy-rollback', async (ctx) => {
         if (name) {
-            const namedApplyResult = await applyNamedComponent(name, paths.engine, furnacePaths, config, ftlDir, isDryRun, ctx, projectRoot, forgeConfig.markerComment);
+            const namedApplyResult = await applyNamedComponent(name, paths.engine, furnacePaths, config, ftlDir, isDryRun, ctx, projectRoot, resolvedMarkerComment);
             if (namedApplyResult === 'stock') {
                 return { kind: 'stock' };
             }

package/dist/src/commands/furnace/init.js CHANGED Viewed

@@ -5,6 +5,7 @@ import { text } from '@clack/prompts';
 import { getProjectPaths, loadConfig, mutateConfig, writeConfig } from '../../core/config.js';
 import { createDefaultFurnaceConfig, furnaceConfigExists, writeFurnaceConfig, } from '../../core/furnace-config.js';
 import { DEFAULT_LICENSE } from '../../core/license-headers.js';
+import { registerSharedCSS } from '../../core/register-shared-css.js';
 import { getTokensCssPath } from '../../core/token-manager.js';
 import { generateDefaultTokensCss } from '../../core/token-scaffold.js';
 import { FurnaceError } from '../../errors/furnace.js';
@@ -184,9 +185,11 @@ export async function furnaceInitCommand(projectRoot, options = {}) {
     }
     note(lines.join('\n'), 'Configuration');
     info('Next steps:\n' +
-        '  fireforge furnace scan        — discover engine components\n' +
+        '  fireforge furnace scan         — discover engine components\n' +
         '  fireforge furnace create       — create a new custom component\n' +
-        '  fireforge furnace override     — fork an existing component');
+        '  fireforge furnace override     — fork an existing component\n' +
+        '  fireforge token add            — define a token in the scaffolded tokens CSS\n' +
+        '  fireforge export <tokens.css>  — capture the tokens CSS + its registration in a patch');
     outro('Init complete');
 }
 /**
@@ -251,6 +254,29 @@ async function scaffoldTokensCss(projectRoot) {
         warn(`Could not register tokens CSS in patchLint.rawColorAllowlist: ${toError(error).message}. ` +
             `Add "${tokensCssPath}" manually under patchLint.rawColorAllowlist in fireforge.json if lint flags its contents.`);
     }
+    // 2026-04-26 eval Finding 2: register the tokens CSS in
+    // browser/themes/shared/jar.inc.mn so the file is owned end-to-end by
+    // tooling. Pre-fix, `furnace init` only scaffolded + allowlisted the
+    // file, so the very next `fireforge status` correctly flagged it as
+    // unmanaged + unregistered and `furnace deploy --dry-run` reported
+    // nothing to deploy — a documented init command turned a clean
+    // project into an unclean one. The CSS lives at the canonical
+    // `browser/themes/shared/<binaryName>-tokens.css` path that the
+    // shared-CSS rule already targets, so the tokens file gets the same
+    // `skin/classic/browser/<name>.css (../shared/<name>.css)` jar.inc.mn
+    // entry as any other shared CSS. Idempotent — running
+    // `furnace init --force` against a registered tree is a no-op.
+    try {
+        const fileBase = `${forgeConfig.binaryName}-tokens.css`;
+        const result = await registerSharedCSS(paths.engine, fileBase, undefined, false);
+        if (!result.skipped) {
+            info(`Registered ${fileBase} in browser/themes/shared/jar.inc.mn`);
+        }
+    }
+    catch (error) {
+        warn(`Could not register tokens CSS in browser/themes/shared/jar.inc.mn: ${toError(error).message}. ` +
+            `Run "fireforge register browser/themes/shared/${forgeConfig.binaryName}-tokens.css" once jar.inc.mn is reachable.`);
+    }
     return { tokensCssPath };
 }
 //# sourceMappingURL=init.js.map

package/dist/src/commands/lint.js CHANGED Viewed

@@ -348,17 +348,22 @@ async function lintPerPatch(projectRoot, paths) {
     const ctx = await buildPatchQueueContext(paths.patches);
     const issues = [];
     let linted = 0;
+    let skipped = 0;
     for (const patch of manifest.patches) {
         const existing = [];
         for (const f of patch.filesAffected) {
             if (await pathExists(join(paths.engine, f)))
                 existing.push(f);
         }
-        if (existing.length === 0)
+        if (existing.length === 0) {
+            skipped++;
             continue;
+        }
         const diff = await getDiffForFilesAgainstHead(paths.engine, existing);
-        if (!diff.trim())
+        if (!diff.trim()) {
+            skipped++;
             continue;
+        }
         const ignore = patch.lintIgnore?.length ? new Set(patch.lintIgnore) : undefined;
         const decision = resolvePatchSizeTier(existing, patch.tier);
         if (decision.tier === 'branding') {
@@ -377,7 +382,21 @@ async function lintPerPatch(projectRoot, paths) {
     // context.
     issues.push(...lintPatchQueue(ctx));
     if (issues.length === 0) {
-        success(`No lint issues found across ${linted} patch(es).`);
+        // 2026-04-26 eval Finding 7: pre-fix the success line read
+        // `No lint issues found across 0 patch(es).` whenever the queue
+        // had not been applied to the engine — every patch's
+        // `filesAffected` filtered out, so `existing` was empty and the
+        // patch was silently skipped. Operators read that as "the queue
+        // is clean" when in reality nothing was checked. Surface the
+        // skipped count and, when nothing was linted at all, point at
+        // `fireforge import` as the missing prerequisite.
+        if (linted === 0 && skipped > 0) {
+            info(`No patches in the queue have been applied to engine/. Run "fireforge import" first if you want lint findings against the staged hunks; otherwise this is expected.`);
+        }
+        const summary = skipped > 0
+            ? `No lint issues found across ${linted} patch(es) (${skipped} skipped — files not present in engine/).`
+            : `No lint issues found across ${linted} patch(es).`;
+        success(summary);
         outro('Lint passed');
         return;
     }

package/dist/src/commands/patch/delete.js CHANGED Viewed

@@ -10,6 +10,7 @@
 import { basename } from 'node:path';
 import { getProjectPaths } from '../../core/config.js';
 import { appendHistory, confirmDestructive } from '../../core/destructive.js';
+import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
 import { buildPatchQueueContext, extractImportSpecifiersWithLines, findForwardImportIgnoreLines, isForwardImportableFile, } from '../../core/patch-lint.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
 import { loadPatchesManifest, removePatchFileAndManifest, resolvePatchIdentifier, } from '../../core/patch-manifest.js';
@@ -39,10 +40,7 @@ export async function patchDeleteCommand(projectRoot, identifier, options = {})
     }
     const target = resolvePatchIdentifier(identifier, manifest.patches);
     if (!target) {
-        const available = manifest.patches
-            .map((p) => p.name && p.name !== p.filename ? `${p.filename} (name: ${p.name})` : p.filename)
-            .join(', ');
-        throw new InvalidArgumentError(`Patch "${identifier}" not found. Accepted identifiers: ordinal (e.g. 2), filename (e.g. 002-ui-foo.patch), or manifest name (e.g. ui-foo). Available: ${available}`, identifier);
+        throw new InvalidArgumentError(formatPatchNotFoundError(identifier, manifest.patches), identifier);
     }
     // Build the full queue context once so we can scan each patch's newFiles
     // without re-parsing for the dependency check below.

package/dist/src/commands/patch/lint-ignore.js CHANGED Viewed

@@ -22,6 +22,7 @@
 import { getProjectPaths } from '../../core/config.js';
 import { appendHistory } from '../../core/destructive.js';
 import { mutatePatchMetadata } from '../../core/patch-export.js';
+import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
 import { loadPatchesManifest, resolvePatchIdentifier } from '../../core/patch-manifest.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
@@ -113,10 +114,7 @@ export async function patchLintIgnoreCommand(projectRoot, identifier, options =
     }
     const target = resolvePatchIdentifier(identifier, manifest.patches);
     if (!target) {
-        const available = manifest.patches
-            .map((p) => p.name && p.name !== p.filename ? `${p.filename} (name: ${p.name})` : p.filename)
-            .join(', ');
-        throw new InvalidArgumentError(`Patch "${identifier}" not found. Accepted identifiers: ordinal (e.g. 2), filename (e.g. 002-ui-foo.patch), or manifest name (e.g. ui-foo). Available: ${available}`, identifier);
+        throw new InvalidArgumentError(formatPatchNotFoundError(identifier, manifest.patches), identifier);
     }
     if (isDryRun) {
         const existing = target.lintIgnore ?? [];

package/dist/src/commands/patch/reorder.js CHANGED Viewed

@@ -11,6 +11,7 @@
 import { Option } from 'commander';
 import { getProjectPaths } from '../../core/config.js';
 import { appendHistory, confirmDestructive, } from '../../core/destructive.js';
+import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
 import { buildPatchQueueContext, lintPatchQueue, } from '../../core/patch-lint.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
 import { loadPatchesManifest, renumberPatchesInManifest, resolvePatchIdentifier, } from '../../core/patch-manifest.js';
@@ -270,10 +271,7 @@ export async function patchReorderCommand(projectRoot, identifier, options = {})
     }
     const target = resolvePatchIdentifier(identifier, manifest.patches);
     if (!target) {
-        const available = manifest.patches
-            .map((p) => p.name && p.name !== p.filename ? `${p.filename} (name: ${p.name})` : p.filename)
-            .join(', ');
-        throw new InvalidArgumentError(`Patch "${identifier}" not found. Accepted identifiers: ordinal (e.g. 2), filename (e.g. 002-ui-foo.patch), or manifest name (e.g. ui-foo). Available: ${available}`, identifier);
+        throw new InvalidArgumentError(formatPatchNotFoundError(identifier, manifest.patches), identifier);
     }
     const { destinationOrder, anchorFilename } = resolveDestination(target, manifest.patches, options);
     const renameMap = computeRenameMap(manifest.patches, target, destinationOrder);

package/dist/src/commands/patch/tier.js CHANGED Viewed

@@ -18,6 +18,7 @@ import { Option } from 'commander';
 import { getProjectPaths } from '../../core/config.js';
 import { appendHistory } from '../../core/destructive.js';
 import { updatePatchMetadata } from '../../core/patch-export.js';
+import { formatPatchNotFoundError } from '../../core/patch-identifier-suggest.js';
 import { loadPatchesManifest, resolvePatchIdentifier } from '../../core/patch-manifest.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
@@ -56,10 +57,7 @@ export async function patchTierCommand(projectRoot, identifier, options = {}) {
     }
     const target = resolvePatchIdentifier(identifier, manifest.patches);
     if (!target) {
-        const available = manifest.patches
-            .map((p) => p.name && p.name !== p.filename ? `${p.filename} (name: ${p.name})` : p.filename)
-            .join(', ');
-        throw new InvalidArgumentError(`Patch "${identifier}" not found. Accepted identifiers: ordinal (e.g. 2), filename (e.g. 002-ui-foo.patch), or manifest name (e.g. ui-foo). Available: ${available}`, identifier);
+        throw new InvalidArgumentError(formatPatchNotFoundError(identifier, manifest.patches), identifier);
     }
     const before = target.tier;
     const after = setting ? options.tier : undefined;

package/dist/src/commands/status.js CHANGED Viewed

@@ -7,7 +7,8 @@ import { buildOwnershipTable, renderOwnershipTable } from '../core/ownership-tab
 import { buildPatchQueueContext, collectNewFileCreatorsByPath } from '../core/patch-lint.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { classifyFiles, } from '../core/status-classify.js';
-import { GeneralError } from '../errors/base.js';
+import { CommandError, GeneralError } from '../errors/base.js';
+import { ExitCode } from '../errors/codes.js';
 import { FIREFORGE_TMP_PATH_PATTERN, pathExists } from '../utils/fs.js';
 import { info, intro, outro, warn } from '../utils/logger.js';
 /**
@@ -295,9 +296,19 @@ export async function statusCommand(projectRoot, options = {}) {
     // and exit non-zero via GeneralError so the exit code still reflects the
     // failure but stdout remains valid JSON. The same guard runs for
     // ownership mode below because that path also throws on missing engine.
+    // 2026-04-26 eval Finding 1: throw `CommandError` rather than
+    // `GeneralError` after the JSON line lands on stdout. `GeneralError`
+    // is a `FireForgeError`, so the `withErrorHandling` wrapper in cli.ts
+    // calls `logError(error.userMessage)` on it, which routes the styled
+    // human banner through clack to stdout — `status --json` therefore
+    // emitted both the JSON object AND the `■ Firefox source not found …`
+    // line on stdout, breaking every script that pipes the command into
+    // a JSON parser. `CommandError` is the bin-only sentinel that
+    // `withErrorHandling` does not log: bin/fireforge.ts catches it,
+    // exits with the carried code, and stdout stays a single JSON line.
     const emitJsonError = (code, message) => {
         process.stdout.write(JSON.stringify({ error: message, code }) + '\n');
-        throw new GeneralError(message);
+        throw new CommandError(ExitCode.GENERAL_ERROR);
     };
     // Ownership mode is a flat file→patch table; sources are the manifest's
     // filesAffected, any worktree drift, and the cross-patch

package/dist/src/core/furnace-apply.js CHANGED Viewed

@@ -9,6 +9,7 @@ import { applyCustomComponent, applyOverrideComponent, computeComponentChecksums
 import { getFurnacePaths, loadFurnaceConfig, loadFurnaceState, updateFurnaceState, } from './furnace-config.js';
 import { CUSTOM_ELEMENTS_JS, JAR_MN, resolveFtlDir } from './furnace-constants.js';
 import { topologicalSortCustom } from './furnace-graph-utils.js';
+import { resolveFurnaceMarkerComment } from './furnace-marker.js';
 import { recordFurnaceRollbackFailure } from './furnace-operation.js';
 import { addJarMnEntries, removeCustomElementRegistration, removeJarMnEntries, } from './furnace-registration.js';
 import { createRollbackJournal, restoreRollbackJournalOrThrow, snapshotFile, } from './furnace-rollback.js';
@@ -304,9 +305,16 @@ export async function applyAllComponents(root, dryRun = false, options) {
     const { engine: engineDir } = getProjectPaths(root);
     const furnacePaths = getFurnacePaths(root);
     const ftlDir = resolveFtlDir(config.ftlBasePath);
-    const markerComment = await loadConfig(root)
-        .then((forgeConfig) => forgeConfig.markerComment)
-        .catch(() => undefined);
+    // 2026-04-26 eval Finding 6: when `markerComment` is unset in
+    // fireforge.json, default it to `binaryName.toUpperCase()` so the
+    // furnace-emitted edits to upstream files (e.g. customElements.js)
+    // carry a marker that satisfies `lintModificationComments` — that
+    // rule keys on `${binaryName.toUpperCase()}:` and was firing
+    // `[missing-modification-comment]` on every furnace-applied
+    // upstream edit because the implicit default was `undefined`. An
+    // explicit `markerComment` in fireforge.json still wins.
+    const forgeConfig = await loadConfig(root).catch(() => undefined);
+    const markerComment = resolveFurnaceMarkerComment(forgeConfig);
     if (!(await pathExists(engineDir))) {
         throw new FurnaceError('Engine directory not found. Run "fireforge download" first.');
     }

package/dist/src/core/furnace-marker.d.ts ADDED Viewed

@@ -0,0 +1,16 @@
+/**
+ * Marker-comment resolution shared between furnace apply and deploy.
+ *
+ * 2026-04-26 eval Finding 6: when `markerComment` is unset in
+ * fireforge.json, fall back to `binaryName.toUpperCase()` so the
+ * patch-lint rule `lintModificationComments` (which keys on
+ * `${binaryName.toUpperCase()}:`) accepts furnace-emitted edits on the
+ * next `lint`/`export` round-trip. The helper tolerates the
+ * undefined-config case (a project that hasn't run `fireforge setup`
+ * yet) and the missing-binaryName case (test fixtures that mock
+ * `loadConfig` with a partial shape).
+ */
+export declare function resolveFurnaceMarkerComment(forgeConfig: {
+    markerComment?: string;
+    binaryName?: string;
+} | undefined): string | undefined;

package/dist/src/core/furnace-marker.js ADDED Viewed

@@ -0,0 +1,23 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Marker-comment resolution shared between furnace apply and deploy.
+ *
+ * 2026-04-26 eval Finding 6: when `markerComment` is unset in
+ * fireforge.json, fall back to `binaryName.toUpperCase()` so the
+ * patch-lint rule `lintModificationComments` (which keys on
+ * `${binaryName.toUpperCase()}:`) accepts furnace-emitted edits on the
+ * next `lint`/`export` round-trip. The helper tolerates the
+ * undefined-config case (a project that hasn't run `fireforge setup`
+ * yet) and the missing-binaryName case (test fixtures that mock
+ * `loadConfig` with a partial shape).
+ */
+export function resolveFurnaceMarkerComment(forgeConfig) {
+    if (!forgeConfig)
+        return undefined;
+    if (forgeConfig.markerComment !== undefined)
+        return forgeConfig.markerComment;
+    if (forgeConfig.binaryName)
+        return forgeConfig.binaryName.toUpperCase();
+    return undefined;
+}
+//# sourceMappingURL=furnace-marker.js.map

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

@@ -70,9 +70,7 @@ function isInsideDOMContentLoaded(ancestors, content) {
             call.callee.property.type === 'Identifier' &&
             call.callee.property.name === 'addEventListener') {
             const firstArg = call.arguments[0];
-            if (firstArg &&
-                firstArg.type === 'Literal' &&
-                firstArg.value === 'DOMContentLoaded') {
+            if (firstArg && firstArg.type === 'Literal' && firstArg.value === 'DOMContentLoaded') {
                 return true;
             }
             // Check if "DOMContentLoaded" appears in the call's source (handles edge cases)

package/dist/src/core/git.js CHANGED Viewed

@@ -65,6 +65,35 @@ async function cleanupIndexLock(dir) {
         verbose('Cleaned up stale .git/index.lock after timeout');
     }
 }
+/**
+ * Returns true when {@link relativePath} is ignored by `.gitignore` (or
+ * any other exclusion mechanism git considers, e.g. `.git/info/exclude`,
+ * core.excludesFile). Used by the chunked staging fallback to skip
+ * entries that would otherwise fail `git add -- <path>` with the fatal
+ * "The following paths are ignored by one of your .gitignore files"
+ * error — a state the monolithic `git add -A` path silently handles.
+ *
+ * Implementation: `git check-ignore -q -- <path>` exits 0 when the path
+ * is ignored, 1 when it isn't, and >=128 on real failures. Treat
+ * anything other than 0/1 as "unknown" and conservatively return false
+ * so the chunk runs and any real underlying failure surfaces normally.
+ *
+ * 2026-04-26 eval Finding 4: a Firefox checkout's top-level `.vscode/`
+ * is gitignored by the source tree's own `.gitignore`. Pre-fix, the
+ * chunked `git add -- .vscode` invocation aborted the entire fallback
+ * and turned a recoverable monolithic timeout into a hard setup
+ * failure that required `fireforge download --force`.
+ */
+async function isPathIgnored(dir, relativePath) {
+    const result = await exec('git', ['check-ignore', '-q', '--', relativePath], { cwd: dir });
+    if (result.exitCode === 0)
+        return true;
+    if (result.exitCode === 1)
+        return false;
+    // Any other shape is "we don't know" — let the caller proceed and
+    // surface the real error if `git add` rejects the path.
+    return false;
+}
 /**
  * Stages every file by walking top-level directories one at a time.
  * This avoids a single monolithic `git add -A` that may time out on
@@ -98,11 +127,26 @@ async function stageAllFilesChunked(dir, options = {}) {
         }
     }
     for (const dirName of directories) {
+        if (await isPathIgnored(dir, dirName)) {
+            options.onProgress?.(`Skipping gitignored: ${dirName}/`);
+            continue;
+        }
         options.onProgress?.(`Staging directory: ${dirName}/...`);
         await runChunk(['add', '--', dirName], dirName);
     }
-    // Stage any top-level files
-    const topLevelFiles = entries.filter((e) => e.isFile()).map((e) => e.name);
+    // Stage any top-level files (excluding gitignored ones — `git add`
+    // on an explicit ignored path errors out, which would otherwise
+    // abort the chunked fallback after the monolithic path has already
+    // timed out).
+    const topLevelCandidates = entries.filter((e) => e.isFile()).map((e) => e.name);
+    const topLevelFiles = [];
+    for (const name of topLevelCandidates) {
+        if (await isPathIgnored(dir, name)) {
+            options.onProgress?.(`Skipping gitignored: ${name}`);
+            continue;
+        }
+        topLevelFiles.push(name);
+    }
     if (topLevelFiles.length > 0) {
         options.onProgress?.('Staging top-level files...');
         await runChunk(['add', '--', ...topLevelFiles], 'top-level files');
@@ -125,16 +169,23 @@ const GIT_ADD_HEARTBEAT_MS = 15_000;
 export async function stageAllFiles(dir, options = {}) {
     const timeout = options.timeout ?? GIT_ADD_TIMEOUT_MS;
     const reportProgress = options.onProgress;
-    const heartbeatStartedAt = Date.now();
-    // Periodic heartbeat so non-TTY log scrapers (CI, tail -f) AND operators
-    // watching a spinner both see that the add is still making progress
-    // rather than a dead process. Each tick reports elapsed seconds so the
-    // expected 1–3 minute window (see `download.ts`' info banner) is
-    // observable as it unfolds.
+    // 2026-04-26 eval Finding 5: the pre-fix heartbeat used a single
+    // `heartbeatStartedAt` set at function entry and reported cumulative
+    // elapsed for the whole `stageAllFiles` invocation. After a
+    // monolithic timeout, the chunked-phase ticks therefore named
+    // numbers that already included the entire monolithic budget plus
+    // any host-sleep time, with no way for an operator watching the log
+    // to tell where the monolithic attempt ended and the chunked pass
+    // began. The heartbeat now tracks a per-phase start timestamp and
+    // labels each tick with the phase, so the chunked pass reports its
+    // own elapsed window and the monolithic→chunked handoff is visible.
+    let phase = 'monolithic';
+    let phaseStartedAt = Date.now();
     const heartbeatTimer = reportProgress
         ? setInterval(() => {
-            const elapsedS = Math.round((Date.now() - heartbeatStartedAt) / 1000);
-            reportProgress(`Indexing Firefox source (still staging, ${elapsedS}s elapsed)`);
+            const elapsedS = Math.round((Date.now() - phaseStartedAt) / 1000);
+            const label = phase === 'monolithic' ? 'monolithic' : 'chunked staging';
+            reportProgress(`Indexing Firefox source (${label}, ${elapsedS}s elapsed)`);
         }, GIT_ADD_HEARTBEAT_MS)
         : null;
     heartbeatTimer?.unref();
@@ -158,6 +209,11 @@ export async function stageAllFiles(dir, options = {}) {
         }
         // The killed process may have left an index lock
         await cleanupIndexLock(dir);
+        // Reset elapsed accounting for the chunked phase so its heartbeat
+        // names a believable per-phase number rather than rolling the
+        // monolithic budget forward.
+        phase = 'chunked';
+        phaseStartedAt = Date.now();
         try {
             await stageAllFilesChunked(dir, options);
         }

package/dist/src/core/patch-identifier-suggest.d.ts ADDED Viewed

@@ -0,0 +1,25 @@
+/**
+ * Builds a concise "patch not found" error message with did-you-mean
+ * suggestions in place of the full queue enumeration.
+ *
+ * 2026-04-26 eval Finding 12: pre-fix every `patch` subcommand
+ * (`delete`, `reorder`, `tier`, `lint-ignore`) caught a missing
+ * identifier by joining every queued patch's filename and (optional)
+ * manifest name into a single comma-separated `Available: ...` tail.
+ * On a 29-patch queue the resulting line ran ~1500 characters and
+ * buried the actual error under noise that was almost never useful in
+ * CI. The new shape ranks each known identifier (ordinal,
+ * filename-with-and-without-`.patch`, manifest name) by Levenshtein
+ * distance from the operator's input, surfaces up to three suggestions
+ * close enough to be plausibly the intended target, and falls back to
+ * a count-only summary that points at `fireforge patch list` when no
+ * close match exists. The full enumeration is no longer ever inlined.
+ */
+import type { PatchMetadata } from '../types/commands/index.js';
+/**
+ * Formats the user-facing "patch not found" error message used by
+ * `patch delete`, `patch reorder`, `patch tier`, and
+ * `patch lint-ignore`. Returns a single string suitable for the
+ * `InvalidArgumentError` body — never the full queue enumeration.
+ */
+export declare function formatPatchNotFoundError(identifier: string, patches: readonly PatchMetadata[]): string;

package/dist/src/core/patch-identifier-suggest.js ADDED Viewed

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Builds a concise "patch not found" error message with did-you-mean
+ * suggestions in place of the full queue enumeration.
+ *
+ * 2026-04-26 eval Finding 12: pre-fix every `patch` subcommand
+ * (`delete`, `reorder`, `tier`, `lint-ignore`) caught a missing
+ * identifier by joining every queued patch's filename and (optional)
+ * manifest name into a single comma-separated `Available: ...` tail.
+ * On a 29-patch queue the resulting line ran ~1500 characters and
+ * buried the actual error under noise that was almost never useful in
+ * CI. The new shape ranks each known identifier (ordinal,
+ * filename-with-and-without-`.patch`, manifest name) by Levenshtein
+ * distance from the operator's input, surfaces up to three suggestions
+ * close enough to be plausibly the intended target, and falls back to
+ * a count-only summary that points at `fireforge patch list` when no
+ * close match exists. The full enumeration is no longer ever inlined.
+ */
+/** Maximum Levenshtein distance accepted as a "did you mean" suggestion. */
+const SUGGESTION_DISTANCE_THRESHOLD = 3;
+/** Maximum number of suggestions to surface in the error message. */
+const SUGGESTION_LIMIT = 3;
+/**
+ * Computes the Levenshtein edit distance between two strings. Used by
+ * `formatPatchNotFoundError` to rank candidate identifiers; the small
+ * upper bound on input lengths (filenames, ordinals, names) makes the
+ * O(m*n) implementation trivially fast.
+ */
+function levenshtein(a, b) {
+    if (a === b)
+        return 0;
+    if (a.length === 0)
+        return b.length;
+    if (b.length === 0)
+        return a.length;
+    // Allocate the row buffers up-front and fill with zero so every index in
+    // [0, b.length] is populated before any read. Using `Array.fill(0)` keeps
+    // the type as `number[]` (not `(number | undefined)[]`) so subsequent
+    // index reads compose without optional-chaining noise.
+    const prev = new Array(b.length + 1).fill(0);
+    const curr = new Array(b.length + 1).fill(0);
+    for (let j = 0; j <= b.length; j++)
+        prev[j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            const left = curr[j - 1] ?? 0;
+            const up = prev[j] ?? 0;
+            const diag = prev[j - 1] ?? 0;
+            curr[j] = Math.min(left + 1, up + 1, diag + cost);
+        }
+        for (let j = 0; j <= b.length; j++)
+            prev[j] = curr[j] ?? 0;
+    }
+    return prev[b.length] ?? 0;
+}
+/**
+ * Collects every identifier shape FireForge accepts for a queue entry:
+ *   - the ordinal (string form), e.g. `"2"`
+ *   - the filename, e.g. `"002-ui-foo.patch"`
+ *   - the filename without the `.patch` suffix, e.g. `"002-ui-foo"`
+ *   - the manifest `name` field, when distinct from the filename
+ * Returned as a flat list so the suggestion ranking can compare each
+ * candidate independently.
+ */
+function collectAcceptedIdentifiers(patches) {
+    const set = new Set();
+    for (const patch of patches) {
+        set.add(String(patch.order));
+        set.add(patch.filename);
+        if (patch.filename.endsWith('.patch')) {
+            set.add(patch.filename.slice(0, -'.patch'.length));
+        }
+        if (patch.name && patch.name !== patch.filename)
+            set.add(patch.name);
+    }
+    return Array.from(set);
+}
+/**
+ * Returns up to {@link SUGGESTION_LIMIT} accepted identifiers ordered
+ * by closest Levenshtein distance to {@link identifier}, dropping any
+ * candidate whose distance exceeds {@link SUGGESTION_DISTANCE_THRESHOLD}.
+ */
+function rankSuggestions(identifier, candidates) {
+    return candidates
+        .map((candidate) => ({ candidate, distance: levenshtein(identifier, candidate) }))
+        .filter((entry) => entry.distance <= SUGGESTION_DISTANCE_THRESHOLD)
+        .sort((a, b) => a.distance - b.distance || a.candidate.localeCompare(b.candidate))
+        .slice(0, SUGGESTION_LIMIT)
+        .map((entry) => entry.candidate);
+}
+/**
+ * Formats the user-facing "patch not found" error message used by
+ * `patch delete`, `patch reorder`, `patch tier`, and
+ * `patch lint-ignore`. Returns a single string suitable for the
+ * `InvalidArgumentError` body — never the full queue enumeration.
+ */
+export function formatPatchNotFoundError(identifier, patches) {
+    const accepted = collectAcceptedIdentifiers(patches);
+    const suggestions = rankSuggestions(identifier, accepted);
+    const lead = `Patch "${identifier}" not found. Accepted identifiers: ordinal (e.g. 2), filename (e.g. 002-ui-foo.patch), or manifest name (e.g. ui-foo).`;
+    if (suggestions.length > 0) {
+        return `${lead} Did you mean: ${suggestions.join(', ')}? (${patches.length} patches in queue — run "fireforge patch list" for the full list.)`;
+    }
+    return `${lead} No close match found among ${patches.length} patches in the queue. Run "fireforge patch list" to see them.`;
+}
+//# sourceMappingURL=patch-identifier-suggest.js.map

package/dist/src/core/register-shared-css.d.ts CHANGED Viewed

@@ -2,10 +2,38 @@
  * CSS registration in browser/themes/shared/jar.inc.mn.
  */
 import type { RegisterResult } from './manifest-register.js';
+/**
+ * Measures the column at which the `(source)` parenthesis opens in
+ * adjacent `skin/classic/browser/<x>.css (...)` entries inside an
+ * existing jar.inc.mn body, and returns the maximum so a newly inserted
+ * entry can align its source column to match.
+ *
+ * 2026-04-26 eval Finding 3: pre-fix `registerSharedCSS` always emitted
+ * a four-space gap between the target path and the parenthesis,
+ * regardless of how the rest of the file was aligned. Adjacent Firefox
+ * entries are typically padded to a wider column, so a freshly
+ * registered file landed at the wrong column and produced avoidable
+ * formatting churn. Returns `undefined` when no existing entries
+ * provide an alignment signal — callers fall back to the four-space
+ * default in that case.
+ */
+export declare function measureSourceColumn(content: string): number | undefined;
+/**
+ * Builds a `skin/classic/browser/<name>.css   (../shared/<name>.css)`
+ * line padded so the parenthesis lands at {@link sourceColumn} (when
+ * supplied) or at the default four-space gap (when {@link sourceColumn}
+ * is `undefined` or would force the parenthesis closer to the target
+ * than {@link MIN_SOURCE_GAP}).
+ */
+export declare function buildEntry(name: string, sourceColumn: number | undefined): string;
 /**
  * Registers a CSS file in browser/themes/shared/jar.inc.mn.
  *
  * Entry format:
  *   skin/classic/browser/{name}.css    (../shared/{name}.css)
+ *
+ * The gap between target and source is sized to align with adjacent
+ * entries when the manifest already uses a wider column; falls back to
+ * a four-space minimum otherwise.
  */
 export declare function registerSharedCSS(engineDir: string, fileName: string, after?: string, dryRun?: boolean): Promise<RegisterResult>;

package/dist/src/core/register-shared-css.js CHANGED Viewed

@@ -83,11 +83,68 @@ function legacyRegisterSharedCSS(content, name, entry, after) {
     lines.splice(insertIndex, 0, entry);
     return { result: lines.join('\n'), previousEntry, afterFallback };
 }
+/** Minimum gap between the target path and the source parenthesis. */
+const MIN_SOURCE_GAP = 4;
+/**
+ * Measures the column at which the `(source)` parenthesis opens in
+ * adjacent `skin/classic/browser/<x>.css (...)` entries inside an
+ * existing jar.inc.mn body, and returns the maximum so a newly inserted
+ * entry can align its source column to match.
+ *
+ * 2026-04-26 eval Finding 3: pre-fix `registerSharedCSS` always emitted
+ * a four-space gap between the target path and the parenthesis,
+ * regardless of how the rest of the file was aligned. Adjacent Firefox
+ * entries are typically padded to a wider column, so a freshly
+ * registered file landed at the wrong column and produced avoidable
+ * formatting churn. Returns `undefined` when no existing entries
+ * provide an alignment signal — callers fall back to the four-space
+ * default in that case.
+ */
+export function measureSourceColumn(content) {
+    const lines = content.split('\n');
+    let maxColumn = 0;
+    let sampled = 0;
+    // The regex guarantees `(` appears in the matched line, so the index
+    // lookup below is always >= 0. The `match` body's leading-whitespace
+    // and target-path captures are likewise guaranteed by the pattern, so
+    // we can take the literal `match[0]` (full match) length minus one to
+    // locate the `(` column without a fragile per-group lookup.
+    const lineRe = /^\s*skin\/classic\/browser\/[^\s()]+\s+\(/;
+    for (const line of lines) {
+        const match = lineRe.exec(line);
+        if (!match)
+            continue;
+        const parenIndex = match[0].length - 1;
+        if (parenIndex > maxColumn)
+            maxColumn = parenIndex;
+        sampled++;
+    }
+    return sampled > 0 ? maxColumn : undefined;
+}
+/**
+ * Builds a `skin/classic/browser/<name>.css   (../shared/<name>.css)`
+ * line padded so the parenthesis lands at {@link sourceColumn} (when
+ * supplied) or at the default four-space gap (when {@link sourceColumn}
+ * is `undefined` or would force the parenthesis closer to the target
+ * than {@link MIN_SOURCE_GAP}).
+ */
+export function buildEntry(name, sourceColumn) {
+    const indent = '  ';
+    const target = `${indent}skin/classic/browser/${name}.css`;
+    const minColumn = target.length + MIN_SOURCE_GAP;
+    const column = sourceColumn !== undefined && sourceColumn >= minColumn ? sourceColumn : minColumn;
+    const padding = ' '.repeat(column - target.length);
+    return `${target}${padding}(../shared/${name}.css)`.replace(/\\/g, '/');
+}
 /**
  * Registers a CSS file in browser/themes/shared/jar.inc.mn.
  *
  * Entry format:
  *   skin/classic/browser/{name}.css    (../shared/{name}.css)
+ *
+ * The gap between target and source is sized to align with adjacent
+ * entries when the manifest already uses a wider column; falls back to
+ * a four-space minimum otherwise.
  */
 export async function registerSharedCSS(engineDir, fileName, after, dryRun = false) {
     const manifest = 'browser/themes/shared/jar.inc.mn';
@@ -96,8 +153,9 @@ export async function registerSharedCSS(engineDir, fileName, after, dryRun = fal
         throw new GeneralError(`Manifest not found: ${manifest}`);
     }
     const name = basename(fileName, '.css');
-    const entry = `  skin/classic/browser/${name}.css    (../shared/${name}.css)`.replace(/\\/g, '/');
     const content = await readText(manifestPath);
+    const sourceColumn = measureSourceColumn(content);
+    const entry = buildEntry(name, sourceColumn);
     // Idempotency check. `furnace chrome-doc create` writes its CSS as a
     // `content/browser/<name>.css` entry rather than the canonical
     // `skin/classic/browser/<name>.css` form `register` produces; recognise

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.18.3",
+  "version": "0.18.6",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",