@hominis/fireforge 0.44.2 → 0.44.4

package/CHANGELOG.md

@@ -86,6 +86,8 @@
 - **`token add --variant` required a flag that described nothing, rejected its companion, and reported a no-op as success.** Three separate frictions, all in the variant path. `--category` was an unconditional `requiredOption` that had to name a REAL category even under `--variant`, where the declaration is routed into a `:root<selector>` block and never into a category section — the requirement existed so the argument would not be "silently discarded", a fair goal whose effect was a mandatory argument saying nothing about where the token lands. It is now optional there (still validated when supplied, so a typo is not accepted just because the flag is inert), and its absence on a BASE declaration is refused with the REASON stated rather than commander's bare "required option not specified".
   `--create-category` is still rejected with `--variant` — the two really are incompatible — but the working create-then-variant order (author the category with the base token, then add each variant) was discoverable only by failing twice. It is now in both the error and `--variant`'s help text.
   And a token already present in the target variant block was skipped with a bare `{ added: false }`, so a re-run intending to CHANGE a value exited 0 having changed nothing, while the base path had been reporting the category and line for the same situation all along. The variant path now returns the location too, and the skip reads `already exists in :root[…] (line N), unchanged` — the block being the location, since a variant declaration has no category to name.
+- **The CC0 public-domain dedication Mozilla puts on its test files was not a recognized license header.** `containsUpstreamLicenseText` knew MPL, Apache, MIT, GPL and a bare SPDX tag; nothing knew `Any copyright is dedicated to the Public Domain. http://creativecommons.org/publicdomain/zero/1.0/`. A modified upstream test whose notice was UNCHANGED therefore warned `modified-file-missing-header`, and the downstream workaround — two identifier-only edits, an `SPDX-License-Identifier: CC0-1.0` line above each untouched notice on patch 905 — was editing Mozilla's notice to satisfy FireForge's recognizer. Worse than filed: `hasThirdPartyPermissiveBanner` did not know it either, so a NEW file copied from the upstream test tree was neither "acceptable" nor "vendored", and `export -y` would have prepended the PROJECT's license header onto code Mozilla dedicated to the public domain — precisely the mislicensing the vendored carve-out (0.38.0) exists to prevent.
+  Both predicates now recognize the dedication in every spelling the tree carries — the prose, the `creativecommons.org/publicdomain/zero/1.0/` URL with either scheme, and the `CC0-1.0` SPDX identifier — through one shared matcher, so the two cannot drift. Deliberately narrow, with the negative controls pinned: a different Creative Commons license (`licenses/by/4.0/`, `CC-BY-4.0`), a made-up `publicdomain/zero/2.0/`, a bare "public domain" mention, and a dedication below the scanned head are all still refused.
 
 ### Security
 
@@ -108,6 +110,10 @@
 ### Performance
 
 - **`getAllDiff` spawned one `git hash-object` per untracked file, uncapped.** Its sibling `getDiffForFilesAgainstHead` was reshaped into classify → one batched hash → render for exactly this reason; this path kept the per-file form, and it is the only path behind `tree create`, `tree list`, `tree remove --all`, `lint` and `export-all` — against a Firefox tree where "untracked" can mean a very large number of files. Now batched. Everything observable is deliberately unchanged (renames, `ls-files` ordering, tracked-block-first emission, the `'\n'` empty sentinel) because this output is SHA-256'd into every tree fingerprint and written verbatim into `.patch` files; a new real-git test pins those bytes, which nothing did before.
+- **A dirty `jar.mn` escalated EVERY `test --build` to a full `mach build`, and a dirty `moz.build` re-ran `mach configure` every time — including immediately after the full build that had consumed exactly that content.** A downstream session measured it: 15:00 for the first full build, 14:03 for the next `test --build` because "`jar.mn` changed relative to its own successful-build record", and 17 s for the CSS-only fix that followed. Two of those three builds were the same work twice.
+  The cause is what "changed" meant. `collectChangedEnginePaths` unions the baseline-to-HEAD diff with every WORKTREE modification, and a fork's worktree is permanently dirty — imported patches plus Furnace-applied components are a standing diff against HEAD — so a patch-touched `jar.mn` was "changed" on every run for as long as the patch existed. The baseline already solved this for packageable files (`packageableFingerprints`, 0.40.0) and for `components.conf` (the static-components anchor), and both consumers compare content, not dirtiness; the build inputs were the one family with no fingerprint, because `isPackageablePath` excludes them by design and nothing else recorded them.
+  `last-build.json` now carries `buildInputFingerprints` — a content hash per dirty `jar.mn` / `moz.build` / `moz.configure` / `Makefile.in` / `mozbuild.in` — and `build-prepare` drops any input whose live hash still matches before deciding either escalation. The two halves refresh on different rules, and the difference is load-bearing: backend inputs are refreshed on every successful write, because every baseline-writing path ran the auto-configure preflight against the previous record first; `jar.mn` entries are refreshed only by a FULL build and carried forward verbatim on a `faster` one, because `fireforge build --ui` is a `mach build faster` that never escalates, and recording a `jar.mn` no full build has installed would silence the next escalation. `build --ui` therefore now says which kind of build it was (`writeBuildBaseline`'s new `buildKind`), and passes the previous baseline it was already holding. An unreadable file, a missing entry, or a marker written before the field existed all count as changed — "cannot prove unchanged" never becomes "unchanged". The stale-build preflight's hash loop became the shared `dropPathsMatchingFingerprints` so both consumers compare the same way.
+  **On the escalation itself** — the downstream ask was a scoped install-manifest refresh for jar-only registrations, or a reason full compilation is necessary. Read against mozbuild: every `mach build`, `faster` included, first runs `backend_out_of_date` and regenerates the backend through `config.status` when any `backend.*Backend.in` dependency is newer, and `jar.mn` files are such dependencies; the FasterMake backend consumes `JARManifest` objects for `dist/bin` targets into its own install manifests. So for an entry added to an EXISTING `jar.mn` under `dist/bin` — the Furnace widget case — a `faster` build likely installs the destination, and the 0.41.0 rule ("full build for new `jar.mn` registrations") looks over-broad. It is NOT relaxed here: the rule came from an observed failure whose specifics were not recorded, and the claim needs a real objdir to prove, which a source reading is not. The seam is already available to prove it with: `fireforge build --ui` never escalates, so a jar-only registration followed by `build --ui`, a check that `obj-*/faster/install_dist_bin` names the new destination and the file landed under `dist/bin`, then a plain `fireforge test`, is the experiment; two clean runs of it make narrowing the escalation (to new `jar.mn` files and non-`dist/bin` targets) a safe change. Recorded in `docs/testing.md` so the next reader inherits the analysis rather than the guess. Also recorded, not fixed: `build --ui` ignores `fullBuildRequired` and `package` runs `prepareBuildEnvironment` with no baseline at all, so neither auto-configures nor escalates.
 
 ### Drift collapsed
 
@@ -149,6 +155,9 @@
 - **`fireforge test --doctor` printed the same preflight line three times** on a terminal: a 2026-04-24 fix added an emission for non-TTY capture without removing the two it superseded. The raw writes are gated on non-TTY, which is where the capture requirement applies; the clack framing stays for terminals.
 - **All seven** `--wait-lock` commands that take the patch-directory lock now honour it: `patch tier`, `patch lint-ignore`, `patch staged-dependency`, `export-all`, `resolve`, `doctor` and `rebase`. Each routes through a different lock entry point, so the budget is threaded through `updatePatchMetadata`, `mutatePatchMetadata`, `commitExportedPatch`, `updatePatchAndMetadata`, `rebuildPatchesManifest` and the rebase patch loop.
 - `status --json` outside a project wrote a clack-styled block to **stdout** and exited 2, because the config error is raised before the command body engages machine mode. The boundary now engages it from the flag, so stdout carries exactly one JSON envelope and the human guidance goes to stderr — rule 3 of `docs/machine-output.md`, which was aspirational until now. A payload that already owns stdout (`status --json --fail-on`) suppresses the envelope, so the "exactly one document" half of the contract holds too.
+- **`--variant` refused selectors the matcher had just learned to find.** 0.44.2 widened `rootAttributeSelector` to consume consecutive `[…]` groups and to stop at a pseudo-class tail, so `:root[data-skin="humanist"][data-theme="dark"]` and `:root[data-theme="light"]:not([data-private])` became blocks FireForge can locate and write through. The CLI validator did not move with it: its own regex still accepted exactly one `[attr]` fragment, so `token add --variant '[data-skin=humanist]:not([data-private])'` was refused as "must be a single attribute selector" — a block the tool can FIND was one it would not let you NAME, and the private-exclusion selectors the widening exists for are precisely that shape. Downstream the values were maintained by hand in the allowlisted block instead.
+  The validator now runs the MATCHER'S parse and requires it to consume the whole fragment, rather than carrying a second grammar that can drift from the first again. Character safety stays a separate check, because that parse finds bracket boundaries and validates no characters at all — it is applied one bracket group at a time rather than as a repeated pattern, which is the shape that backtracks (`js/polynomial-redos`), and a linearity test pins that alongside the matcher's own. Normalization to `="value"` now covers every fragment in a run and the `:not(…)` argument, not just a trailing one.
+  `findVariantBlock` had to move with it: it compared a request against a block's ATTRIBUTE run only, so a variant carrying its own qualifier would have matched nothing and spliced a fresh duplicate block on every add. Request and candidate go through the same parse and are compared tail-to-tail. An UNqualified request still matches a qualified block — that is the 0.44.2 behaviour `variantBlockQualifier` exists to report out loud, since silently skipping the block is the worse failure — but a request that names a qualifier means it.
 - `tree list --json` gained the failure envelope `status --json` already emitted, so a scripted consumer no longer gets a parseable refusal from one and a bare non-zero exit from the other. The contract is written down in `docs/machine-output.md`.
 
 ### More correctness
@@ -158,6 +167,7 @@
 - `RebasePatchEntry` became a discriminated union on `status`, so a status flip can no longer strand the previous status's payload — which `rebase --continue` did, persisting `{ status: 'resolved', error, conflictingFiles }` to the session file. The on-disk validator is deliberately NOT tightened to match: the session file carries no schema version, so a stricter validator would refuse a 0.43.x file mid-rebase, where the only remedies discard the operator's conflict resolution. Entries are normalized on read instead, and two tests pin that an older session still loads.
 - **A `patches.json` from a newer FireForge was reported as malformed.** `patches.json version must be 1` sent the operator looking for damage in a file that only needed a newer build to read it, and the manifest had no migration hook at all. It now refuses by name — naming the found and supported schema versions and telling the operator not to delete the file — while a version below 1 or non-integer keeps the plain malformed message, because that one really is malformed.
 - The three JSDoc walkers in `patch-lint-jsdoc.ts` return their issues instead of pushing into an out-param, matching the ~30 other patch-lint entry points. The new `jsdoc/check-param-names` rule immediately caught the stale `@param issues` the change left behind — which is the point of enabling it.
+- **`furnace create --test-dir` was honoured by the scaffolder and ignored by everything that told the operator where the files went.** `create.ts` resolved the override once and passed it to the scaffolders, but `formatDryRunPlan` and `formatSuccessNote` received only `binaryName` and recomputed the DEFAULT from it — so `--dry-run` planned `test/hominis/` plus `hominis/browser.toml` in `moz.build` for a command that would write to `test/hominis-tiles/`, and the success note after the real run named `hominis/` while the files sat in `hominis-tiles/`. The one message an operator gets as confirmation was the one thing that could not be trusted. Both formatters now take the resolved directory, and the default lives in one place: `resolveBrowserChromeTestDir` / `resolveXpcshellTestDir` in `furnace-constants.ts`, called by the scaffolders AND the formatters, so the two cannot disagree again. The moz.build registration line follows the override too (it is the path below `browser/base/content/test/`, which under `--test-dir` is not the binary name), and a test scaffolds for real and asserts the printed directory is the one on disk — default and overridden, browser-chrome and xpcshell.
 
 ### Windows
 
@@ -180,6 +190,8 @@ On the test side: path expectations and mock keys are rendered through a new `na
 - **`test.test.ts` was 2,943 lines under one `describe`.** What made it unsplittable was its own 190-line `vi.mock` header: any split either duplicated the header into each new file or did not happen. The header moved to `test-command-mocks.ts` as one factory per mocked module, called from inside each file's own `vi.mock` callback — hoisting is unaffected and every suite still gets fresh `vi.fn()`s rather than shared call history. The file is now six, largest 952 lines, split on the seams the tests already formed: discovery and failure rewriting, staleness and packaging coverage, xpcshell/mochitest hints, Marionette forwarding, harness resilience, verdict contract.
   The split exposed a real test-isolation bug: `keeps the Marionette preflight for xpcshell-only --doctor runs` had never set a preflight result, and passed only because an `it` roughly 1,000 lines earlier had left one on the shared mock with `mockResolvedValue`. It sets its own now. Coverage of `src/commands/test.ts` is byte-identical before and after the split (95.12 / 94.28 / 100 / 86.23), which is the check that the mock rewiring did not quietly stop exercising anything.
 - Five rollback tests moved from asserting a module-level spy to asserting the persisted pending-repair marker. The spy stopped working when the sequence moved into `completeJournalRollback` (its call to the recorder is intra-module), and the outcome is the better assertion anyway.
+- **Fourteen verdict assertions passed only because writing to a filesystem root fails.** The command suites pass `/project` as the project root and assert the `FIREFORGE-VERDICT:` line by exact string — which holds only while no run log is open, since the line carries an open log's path as a ` log=<path>` key. On POSIX `mkdir('/project/.fireforge/logs')` fails at the root, the best-effort open degrades to "no log", and the assertions passed for a reason none of them stated. On Windows the same path resolves against the CURRENT DRIVE, the mkdir succeeds, and all fourteen failed — while the run also created real `C:\project\.fireforge\logs` directories on the runner. `createRunLogMock()` joins the two factories in `module-mocks.ts` and the five suites state the precondition instead of inheriting it from a permission error. Because mocking the module away removes the suffix's only coverage, `test-verdict.test.ts` gains the opposite assertion: with a log open, the path rides the line, once, as the run's last stdout write.
+- **A lock-wait test decided its result on a `readdir`.** `a wait whose queue position keeps improving > survives a drain longer than its budget` runs on real timers and a real filesystem, and gave each probe about 20 ms of slack inside a 100 ms budget; it also retired its simulated queue with un-awaited `rm` calls, so a retirement could land after the probe meant to observe it and a release could leave `mkdir` seeing `EEXIST` past the intended free. On a Windows runner the second probe missed the deadline, no extension was ever granted, and the wait expired still three from the head — the exact refusal the test exists to prove does NOT happen. The retirement and release are synchronous now (the callback returns `void` and cannot await), and the constants are scaled to ~100 ms of slack per probe while keeping the two invariants that fix them: the budget must span two probes, and the drain must outlast the budget or the sibling test would acquire instead of expiring. No production change — `withFileLock` checking its deadline before probing is correct, since a wait must not extend itself on a probe taken after it expired.
 - `git-readonly-index.test.ts` carried a latent racy-clean flake: it edited `const b = 2;` to `const b = 3;` — the same byte length, within the same second as the index entry — without invalidating the stat cache, so git could report the file unmodified. Its sibling test already guarded for this.
 
 ### Documentation
@@ -187,6 +199,7 @@ On the test side: path expectations and mock keys are rendered through a new `na
 - **README.md had become the reference manual.** Its "Regular Workflow" section had grown into fourteen paragraphs of flag semantics — scan manifests, shard behaviour, packaging-coverage anchors, tree CoW, shim configuration — read by nobody starting out and found by nobody looking for a specific rule, because prose in a getting-started page has no index. The reference material moves to `docs/`, split by the thing a reader is actually doing: `patch-workflow.md`, `testing.md`, `furnace.md`, `verification-trees.md`, `configuration.md`, plus `docs/README.md` as the index. README keeps installation, the loop's shape, rebasing, Furnace's premise, the roadmap and the licence — the parts that are project statement rather than manual — and links out for the rest.
 - **`docs/run-logs.md`** states the `.fireforge/logs/` contract that previously existed only as a table cell in `machine-output.md`: raw bytes rather than the echo filter's form, opened before any preflight, retained 20 deep per command kind, best-effort throughout, and the tee sitting at the two mach capture funnels rather than at the commands.
 - Two documents had gone stale against the code. `machine-output.md`'s surface table omitted `status --raw`, which engages the same stdout discipline through the same argv check in `cli.ts` — a machine surface to which rules 3 and 4 apply and rules 1 and 2 do not — and omitted `build`'s direct log announcement, which exists precisely because `build` prints no verdict line to carry a `log=` key. `lifecycle-invariants.md` still described `--wait-lock` as the engine-session lock's budget alone, which stopped being true when the budget was threaded into the furnace lock as well; both lock rows now state the resolution order (`lockTimeoutMs` → `FIREFORGE_WAIT_LOCK` → the 30 s default) and which mutators each covers.
+- **The package did not ship the `docs/` tree its own README links to.** The `files` allowlist was `dist/`, `templates/` and the three root markdown files, so `node_modules/@hominis/fireforge/docs` did not exist and all eleven relative `docs/…` links dead-ended for a consumer — against a doctrine that names the INSTALLED package as the authority, precisely so an agent never has to leave its repo to answer a tool question. The links resolved on GitHub and on the registry page, which rewrites them, which is why nothing caught it. `docs/` is now published (~100 KB of markdown against a package that already ships `dist/`), and `wrapper-smoke.test.ts` asserts the tree is both packed and present after install, the way it already did for `templates/` — so a future `files` edit that drops it fails the gate rather than the reader.
 - `FIREFORGE_WAIT_LOCK` and the three other environment variables FireForge reads were documented only in help text and JSDoc. They are tabulated in `configuration.md` with their defaults and their behaviour on a malformed value.
 
 ## 0.43.0

package/dist/build-info.json

@@ -1,9 +1,9 @@
 {
   "schemaVersion": 1,
-  "version": "0.44.2",
-  "commit": "d653751d6c8a1be154647943dc346e81cc62b390",
-  "shortCommit": "d653751d6c8a",
+  "version": "0.44.4",
+  "commit": "b8742ddc056124f81624d9c13d182d0b0c57c86c",
+  "shortCommit": "b8742ddc0561",
   "dirty": false,
   "dirtyHash": null,
-  "buildTime": "2026-08-28T13:39:36.337Z"
+  "buildTime": "2026-08-28T23:48:06.918Z"
 }

package/dist/src/commands/build.js

@@ -342,13 +342,18 @@ async function runBuildCommandBody(projectRoot, options) {
     // Record a fresh baseline only on clean success so the next run audits
     // against this build's HEAD. A failed build keeps the prior baseline so
     // the next attempt still catches long-standing packaging drops.
-    await recordFullBuildBaseline(projectRoot, paths.engine, config.binaryName, options.ui === true);
+    await recordFullBuildBaseline(projectRoot, paths.engine, config.binaryName, options.ui === true, previousBaseline);
     outro(`Build completed in ${timeStr}!`);
 }
-/** Persists the full-coverage baseline; a failed write never fails the build. */
-async function recordFullBuildBaseline(projectRoot, engineDir, binaryName, ui) {
+/**
+ * Persists the full-coverage baseline; a failed write never fails the build.
+ * `--ui` is a `mach build faster`, so it is recorded as such: its `jar.mn`
+ * fingerprints are carried forward from the previous baseline rather than
+ * refreshed, which is why that baseline is threaded through.
+ */
+async function recordFullBuildBaseline(projectRoot, engineDir, binaryName, ui, previousBaseline) {
     try {
-        await writeBuildBaseline(projectRoot, engineDir, binaryName, 'full', undefined, ui ? 'fireforge build --ui' : 'fireforge build');
+        await writeBuildBaseline(projectRoot, engineDir, binaryName, 'full', previousBaseline, ui ? 'fireforge build --ui' : 'fireforge build', 'auto', ui ? 'faster' : 'full');
     }
     catch (baselineError) {
         verbose(`Could not persist build baseline: ${toError(baselineError).message}`);

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

@@ -14,6 +14,15 @@ import type { ResolvedTestStyle } from '../../types/furnace.js';
  * tree, so a redirect makes no sense there.
  */
 export declare function resolveValidatedTestDir(rawTestDir: string | undefined, testStyle: ResolvedTestStyle): string | undefined;
+/**
+ * Scaffolds browser mochitest files for a newly created custom component.
+ * @param componentName - Custom element tag name
+ * @param license - Project license used for generated headers
+ * @param forgeConfig - Project config fields needed for test naming
+ * @param paths - Resolved project paths used to place test files
+ * @param journal - Optional rollback journal that snapshots files before writes
+ * @returns Relative test filenames created or updated for the component
+ */
 /**
  * Normalizes and validates a `--test-dir` override: engine-relative,
  * under `browser/base/content/test/` (so manifest registration keeps

package/dist/src/commands/furnace/create-browser-test.js

@@ -7,6 +7,7 @@
  * the per-file line budget.
  */
 import { join } from 'node:path';
+import { BROWSER_TEST_SCAFFOLD_ROOT, resolveBrowserChromeTestDir, } from '../../core/furnace-constants.js';
 import { recordCreatedDir, snapshotFile, } from '../../core/furnace-rollback.js';
 import { getLicenseHeader } from '../../core/license-headers.js';
 import { registerTestManifest } from '../../core/moz-manifest-register.js';
@@ -40,7 +41,6 @@ export function resolveValidatedTestDir(rawTestDir, testStyle) {
  * @param journal - Optional rollback journal that snapshots files before writes
  * @returns Relative test filenames created or updated for the component
  */
-const TEST_SCAFFOLD_ROOT = 'browser/base/content/test/';
 /**
  * Normalizes and validates a `--test-dir` override: engine-relative,
  * under `browser/base/content/test/` (so manifest registration keeps
@@ -48,9 +48,9 @@ const TEST_SCAFFOLD_ROOT = 'browser/base/content/test/';
  */
 export function resolveTestDirOverride(raw) {
     const normalized = stripEnginePrefix(raw).replace(/\/+$/, '');
-    if (!normalized.startsWith(TEST_SCAFFOLD_ROOT) ||
-        normalized === TEST_SCAFFOLD_ROOT.slice(0, -1)) {
-        throw new InvalidArgumentError(`--test-dir must be an engine-relative directory under ${TEST_SCAFFOLD_ROOT} (got "${raw}").`, 'testDir');
+    if (!normalized.startsWith(BROWSER_TEST_SCAFFOLD_ROOT) ||
+        normalized === BROWSER_TEST_SCAFFOLD_ROOT.slice(0, -1)) {
+        throw new InvalidArgumentError(`--test-dir must be an engine-relative directory under ${BROWSER_TEST_SCAFFOLD_ROOT} (got "${raw}").`, 'testDir');
     }
     return normalized;
 }
@@ -78,8 +78,8 @@ export async function scaffoldTestFiles(componentName, license, forgeConfig, pat
     // `.../test/<binaryName>/` target can collide with a test suite owned by a
     // different patch. The manifest-registration name is the path below
     // browser/base/content/test/ (nested manifests are supported).
-    const testDirRel = testDirOverride ?? `${TEST_SCAFFOLD_ROOT}${binaryName}`;
-    const testDirName = testDirRel.slice(TEST_SCAFFOLD_ROOT.length);
+    const testDirRel = resolveBrowserChromeTestDir(binaryName, testDirOverride);
+    const testDirName = testDirRel.slice(BROWSER_TEST_SCAFFOLD_ROOT.length);
     const testDir = join(paths.engine, testDirRel);
     if (journal && !(await pathExists(testDir))) {
         recordCreatedDir(journal, testDir);

package/dist/src/commands/furnace/create-dry-run.d.ts

@@ -15,6 +15,14 @@ export interface DryRunPlanInput {
     testStyle: ResolvedTestStyle;
     description: string;
     binaryName: string;
+    /**
+     * Resolved `--test-dir` override (engine-relative, already validated by
+     * `resolveValidatedTestDir`). Omit for the default `<binaryName>`-derived
+     * scaffold directory. The formatters MUST receive the same value the
+     * scaffolders get — the plan used to recompute the default from
+     * `binaryName` and named a directory the real run never wrote to.
+     */
+    testDir?: string;
 }
 /**
  * Builds the success-note body printed after `furnace create` has applied
@@ -27,6 +35,8 @@ export declare function formatSuccessNote(args: {
     testFiles: string[];
     testStyle: ResolvedTestStyle;
     binaryName: string;
+    /** Resolved `--test-dir` override; see {@link DryRunPlanInput.testDir}. */
+    testDir?: string | undefined;
 }): string;
 /**
  * Builds the planned component + test file list for a dry-run preview.

package/dist/src/commands/furnace/create-dry-run.js

@@ -7,6 +7,7 @@
  * resolved by the command's validation phase — so it can be exercised
  * independently of the mutation plumbing.
  */
+import { BROWSER_TEST_SCAFFOLD_ROOT, resolveBrowserChromeTestDir, resolveXpcshellTestDir, } from '../../core/furnace-constants.js';
 /**
  * Builds the test-section fragment of the dry-run plan for a given
  * harness choice. Kept separate from the top-level formatter so the
@@ -14,7 +15,7 @@
  * complexity budget.
  */
 function formatTestSection(args) {
-    const { testStyle, componentName, binaryName } = args;
+    const { testStyle, componentName, binaryName, testDir } = args;
     if (testStyle === 'none')
         return '';
     const strippedName = componentName.startsWith('moz-') ? componentName.slice(4) : componentName;
@@ -23,14 +24,18 @@ function formatTestSection(args) {
         : strippedName;
     const underscored = withoutBinaryPrefix.replace(/-/g, '_');
     if (testStyle === 'browser-chrome') {
-        const testRoot = `engine/browser/base/content/test/${binaryName}/`;
-        return (`\n\nWould create test files in ${testRoot}:\n` +
+        // Same resolver as scaffoldTestFiles: the registration name is the
+        // path below browser/base/content/test/, which under --test-dir is
+        // NOT the binary name.
+        const testDirRel = resolveBrowserChromeTestDir(binaryName, testDir);
+        const manifestName = testDirRel.slice(BROWSER_TEST_SCAFFOLD_ROOT.length);
+        return (`\n\nWould create test files in engine/${testDirRel}/:\n` +
             `  browser.toml\n  head.js\n  browser_${binaryName}_${underscored}.js` +
-            `\n\nWould register ${binaryName}/browser.toml in engine/browser/base/moz.build`);
+            `\n\nWould register ${manifestName}/browser.toml in engine/browser/base/moz.build`);
     }
     if (testStyle === 'xpcshell') {
-        const testRoot = `engine/browser/base/content/test/${binaryName}-xpcshell/${componentName}/`;
-        return `\n\nWould create xpcshell test files in ${testRoot}`;
+        const testDirRel = resolveXpcshellTestDir(binaryName, componentName, testDir);
+        return `\n\nWould create xpcshell test files in engine/${testDirRel}/`;
     }
     // testStyle === 'mochikit' (last remaining branch in ResolvedTestStyle).
     const testRoot = 'engine/toolkit/content/tests/widgets/';
@@ -42,19 +47,19 @@ function formatTestSection(args) {
  * stay in lock-step when the scaffolded layout changes.
  */
 export function formatSuccessNote(args) {
-    const { componentName, files, testFiles, testStyle, binaryName } = args;
+    const { componentName, files, testFiles, testStyle, binaryName, testDir } = args;
     let note = `Files created in components/custom/${componentName}/:\n` +
         files.map((f) => `  ${f}`).join('\n');
     if (testFiles.length > 0) {
         let testRoot;
         if (testStyle === 'xpcshell') {
-            testRoot = `engine/browser/base/content/test/${binaryName}-xpcshell/${componentName}/`;
+            testRoot = `engine/${resolveXpcshellTestDir(binaryName, componentName, testDir)}/`;
         }
         else if (testStyle === 'mochikit') {
             testRoot = 'engine/toolkit/content/tests/widgets/';
         }
         else {
-            testRoot = `engine/browser/base/content/test/${binaryName}/`;
+            testRoot = `engine/${resolveBrowserChromeTestDir(binaryName, testDir)}/`;
         }
         note += `\n\nTest files in ${testRoot}:\n` + testFiles.map((f) => `  ${f}`).join('\n');
     }
@@ -75,7 +80,7 @@ export function formatSuccessNote(args) {
  * `components/custom/` to match the wording of the real success note.
  */
 export function formatDryRunPlan(args) {
-    const { componentName, localized, register, composes, stockAdditions, sharedFtl, testStyle, description, binaryName, } = args;
+    const { componentName, localized, register, composes, stockAdditions, sharedFtl, testStyle, description, binaryName, testDir, } = args;
     const componentFiles = [`${componentName}.mjs`, `${componentName}.css`];
     // A per-component .ftl is scaffolded only when the component does NOT
     // opt into a shared feature-scoped bundle. Mirrors writeComponentFiles.
@@ -83,7 +88,7 @@ export function formatDryRunPlan(args) {
         componentFiles.push(`${componentName}.ftl`);
     let plan = `Would create files in components/custom/${componentName}/:\n` +
         componentFiles.map((f) => `  ${f}`).join('\n');
-    plan += formatTestSection({ testStyle, componentName, binaryName });
+    plan += formatTestSection({ testStyle, componentName, binaryName, testDir });
     plan += `\n\nWould add custom entry to furnace.json:`;
     plan += `\n  name: ${componentName}`;
     plan += `\n  description: ${description || '(empty)'}`;

package/dist/src/commands/furnace/create-xpcshell.js

@@ -5,7 +5,7 @@
  * per-file LOC budget and the scaffolder is unit-testable in isolation.
  */
 import { join } from 'node:path';
-import { xpcshellTestParentDir } from '../../core/furnace-constants.js';
+import { resolveXpcshellTestDir, xpcshellTestParentDir } from '../../core/furnace-constants.js';
 import { recordCreatedDir, snapshotFile, } from '../../core/furnace-rollback.js';
 import { getLicenseHeader } from '../../core/license-headers.js';
 import { ensureDir, pathExists, readText, writeText } from '../../utils/fs.js';
@@ -31,7 +31,7 @@ export async function scaffoldXpcshellTestFiles(componentName, license, forgeCon
     const parentDirName = parentRelDir.split('/').slice(-1)[0] ?? `${forgeConfig.binaryName}-xpcshell`;
     // --test-dir names the FINAL directory (no per-component segment is
     // appended) so the operator controls the exact scaffold target.
-    const testDirRel = testDirOverride ?? `${parentRelDir}/${componentName}`;
+    const testDirRel = resolveXpcshellTestDir(forgeConfig.binaryName, componentName, testDirOverride);
     const testDir = join(paths.engine, testDirRel);
     if (journal && !(await pathExists(testDir))) {
         recordCreatedDir(journal, testDir);

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

@@ -356,6 +356,10 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
             testStyle,
             description,
             binaryName: forgeConfig.binaryName,
+            // The plan must name the directory the scaffolder will actually use:
+            // an omitted override here is how the printed path came to disagree
+            // with the files a real run wrote.
+            ...(testDir !== undefined ? { testDir } : {}),
         });
         note(plan, componentName);
         outro('Dry run complete (no files modified)');
@@ -391,6 +395,7 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
         testFiles,
         testStyle,
         binaryName: forgeConfig.binaryName,
+        ...(testDir !== undefined ? { testDir } : {}),
     }), componentName);
     outro('Component created');
 }

package/dist/src/commands/test-build-phase.js

@@ -84,7 +84,7 @@ async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries
                     ? 'refresh'
                     : extend !== undefined
                         ? 'carry-forward'
-                        : 'auto');
+                        : 'auto', buildKind);
             }
             catch (baselineError) {
                 verbose(`Could not persist build baseline: ${toError(baselineError).message}`);

package/dist/src/commands/token.js

@@ -180,7 +180,9 @@ export function registerToken(program, { getProjectRoot, withErrorHandling }) {
         .option('--description <desc>', 'Comment description for the CSS file')
         .option('--dark-value <val>', 'Dark mode value (required if mode is "override")')
         .option('--variant <selector>', 'Attribute selector fragment routing the declaration into a `:root<selector>` block ' +
-        "(e.g. '[data-skin=precision]' or '[data-private]'); creates or updates the block. " +
+        "(e.g. '[data-skin=precision]', '[data-private]', a run such as " +
+        "'[data-skin=precision][data-theme=dark]', or one with a pseudo-class tail such as " +
+        "'[data-skin=precision]:not([data-private])'); creates or updates the block. " +
         'CSS-only — cannot be combined with --mode override or --create-category. To author ' +
         'a new category and its variants, add the BASE token first (with --create-category), ' +
         'then add each variant with --variant.')

package/dist/src/core/build-audit.d.ts

@@ -1,4 +1,24 @@
 import type { BuildBaseline } from './build-baseline-types.js';
+/**
+ * True for the build-input manifests the build consumes but never packages
+ * (`jar.mn`, `moz.build`, `moz.configure`, `Makefile.in`, `mozbuild.in`).
+ * Excluded from the packaging audit and from `packageableFingerprints`;
+ * fingerprinted separately as `buildInputFingerprints` so `build-prepare`
+ * can tell "dirty against HEAD" from "changed since the last successful
+ * build".
+ *
+ * @param sourcePath Engine-relative POSIX path.
+ */
+export declare function isBuildInputPath(sourcePath: string): boolean;
+/**
+ * True for a chrome packaging manifest (`jar.mn`). Its install-manifest
+ * destinations are the one build input whose change escalates a pre-test
+ * `mach build faster` to a full build, and whose fingerprint is therefore
+ * refreshed only by a full build.
+ *
+ * @param sourcePath Engine-relative POSIX path.
+ */
+export declare function isJarManifestPath(sourcePath: string): boolean;
 /** Result of a single artifact lookup. */
 export interface AuditEntry {
     /** Engine-relative source file path (POSIX separators). */

package/dist/src/core/build-audit.js

@@ -74,6 +74,30 @@ const BUILD_INPUT_BASENAMES = new Set([
     'Makefile.in',
     'mozbuild.in',
 ]);
+/**
+ * True for the build-input manifests the build consumes but never packages
+ * (`jar.mn`, `moz.build`, `moz.configure`, `Makefile.in`, `mozbuild.in`).
+ * Excluded from the packaging audit and from `packageableFingerprints`;
+ * fingerprinted separately as `buildInputFingerprints` so `build-prepare`
+ * can tell "dirty against HEAD" from "changed since the last successful
+ * build".
+ *
+ * @param sourcePath Engine-relative POSIX path.
+ */
+export function isBuildInputPath(sourcePath) {
+    return BUILD_INPUT_BASENAMES.has(basename(sourcePath));
+}
+/**
+ * True for a chrome packaging manifest (`jar.mn`). Its install-manifest
+ * destinations are the one build input whose change escalates a pre-test
+ * `mach build faster` to a full build, and whose fingerprint is therefore
+ * refreshed only by a full build.
+ *
+ * @param sourcePath Engine-relative POSIX path.
+ */
+export function isJarManifestPath(sourcePath) {
+    return sourcePath === 'jar.mn' || sourcePath.endsWith('/jar.mn');
+}
 /**
  * Decides whether a source path should be packaged. Returns true for paths
  * whose extension or directory fragment matches a known-packaged pattern,
@@ -88,7 +112,7 @@ export function isPackageablePath(sourcePath) {
         if (sourcePath.includes(fragment))
             return false;
     }
-    if (BUILD_INPUT_BASENAMES.has(basename(sourcePath)))
+    if (isBuildInputPath(sourcePath))
         return false;
     // `.inc.xhtml` fragments are consumed via `#include` from a registered
     // chrome document and resolved at packaging time — they never ship as a

package/dist/src/core/build-baseline-types.d.ts

@@ -35,6 +35,34 @@ export interface BuildBaseline {
      * a tracked deletion.
      */
     packageableFingerprints?: Record<string, string>;
+    /**
+     * Content hash per build-input manifest (`jar.mn`, `moz.build`,
+     * `moz.configure`, `Makefile.in`, `mozbuild.in`) that was dirty
+     * (modified-against-HEAD or untracked) when the recorded build succeeded.
+     * Same key/value shape as {@link BuildBaseline.packageableFingerprints}.
+     *
+     * Consumed by `build-prepare`: a dirty build input whose live hash still
+     * matches its entry was already consumed by the recorded build, so it
+     * neither re-runs `mach configure` nor escalates a pre-test build to a
+     * full `mach build`. Without this the persistent worktree diff every
+     * fork carries (imported patches + Furnace-applied components) made a
+     * patch-touched `jar.mn` "changed" on EVERY run, and each `test --build`
+     * after a full build paid the full build again.
+     *
+     * Refresh rules, per entry kind:
+     * - backend inputs (`moz.build` & co) are refreshed on every successful
+     *   write — every baseline-writing path ran the auto-configure preflight
+     *   against the previous baseline, so a changed one was reconfigured;
+     * - `jar.mn` entries are refreshed only by a FULL build and carried
+     *   forward verbatim from the previous record on a `faster` write, since
+     *   `fireforge build --ui` never escalates and recording a `jar.mn` no
+     *   full build has installed would hide the next escalation.
+     *
+     * Absent on baselines written before the field existed; `build-prepare`
+     * then falls back to the path-only comparison (every dirty build input
+     * counts as changed).
+     */
+    buildInputFingerprints?: Record<string, string>;
     /**
      * What the packaged test runtime produced by the recorded build covers.
      *

package/dist/src/core/build-baseline.d.ts

@@ -16,6 +16,15 @@
  * subsequent run still audits against the last known-good tree.
  */
 import { type BuildBaseline, type TestPackagingCoverage } from './build-baseline-types.js';
+/**
+ * Which mach build produced the baseline being written. Decides whether
+ * the `jar.mn` half of {@link BuildBaseline.buildInputFingerprints} is
+ * refreshed (`'full'`) or carried forward from the previous record
+ * (`'faster'`). `fireforge build --ui` and a non-escalated `test --build`
+ * are `'faster'`; `fireforge build` and an escalated `test --build` are
+ * `'full'`.
+ */
+export type BaselineBuildKind = 'full' | 'faster';
 /** Name of the last-build marker file under `.fireforge/`. */
 export declare const BUILD_BASELINE_FILENAME = "last-build.json";
 /**
@@ -56,5 +65,11 @@ export declare function readBuildBaseline(projectRoot: string): Promise<BuildBas
  *   keeps the previous anchor: needed by `--extend-coverage`, whose union
  *   can EVALUATE to `'full'` while the build that produced it was still a
  *   scoped `mach build faster` that did not rebake the compiled table.
+ * @param buildKind - Which mach build produced this baseline (default
+ *   `'full'`). A `'faster'` write carries the previous record's `jar.mn`
+ *   fingerprints forward instead of refreshing them — see
+ *   {@link BuildBaseline.buildInputFingerprints}. Every caller that ran
+ *   `mach build faster` MUST say so, or the next pre-test build skips an
+ *   escalation no full build has honoured.
  */
-export declare function writeBuildBaseline(projectRoot: string, engineDir: string, binaryName: string, testPackagingCoverage?: TestPackagingCoverage, previousBaseline?: BuildBaseline, recordedBy?: string, staticComponentsHandling?: 'auto' | 'refresh' | 'carry-forward'): Promise<void>;
+export declare function writeBuildBaseline(projectRoot: string, engineDir: string, binaryName: string, testPackagingCoverage?: TestPackagingCoverage, previousBaseline?: BuildBaseline, recordedBy?: string, staticComponentsHandling?: 'auto' | 'refresh' | 'carry-forward', buildKind?: BaselineBuildKind): Promise<void>;

package/dist/src/core/build-baseline.js

@@ -23,7 +23,7 @@ import { mapWithConcurrency } from '../utils/concurrency.js';
 import { getNodeErrorCode, toError } from '../utils/errors.js';
 import { pathExists, readJson, writeJson } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
-import { isPackageablePath, isXpcomManifestPath } from './build-audit.js';
+import { isBuildInputPath, isJarManifestPath, isPackageablePath, isXpcomManifestPath, } from './build-audit.js';
 import { DELETED_FILE_FINGERPRINT, } from './build-baseline-types.js';
 import { FIREFORGE_DIR } from './config-paths.js';
 import { hashEngineFile } from './coverage-extend.js';
@@ -90,8 +90,14 @@ export async function readBuildBaseline(projectRoot) {
  *   keeps the previous anchor: needed by `--extend-coverage`, whose union
  *   can EVALUATE to `'full'` while the build that produced it was still a
  *   scoped `mach build faster` that did not rebake the compiled table.
+ * @param buildKind - Which mach build produced this baseline (default
+ *   `'full'`). A `'faster'` write carries the previous record's `jar.mn`
+ *   fingerprints forward instead of refreshing them — see
+ *   {@link BuildBaseline.buildInputFingerprints}. Every caller that ran
+ *   `mach build faster` MUST say so, or the next pre-test build skips an
+ *   escalation no full build has honoured.
  */
-export async function writeBuildBaseline(projectRoot, engineDir, binaryName, testPackagingCoverage, previousBaseline, recordedBy, staticComponentsHandling = 'auto') {
+export async function writeBuildBaseline(projectRoot, engineDir, binaryName, testPackagingCoverage, previousBaseline, recordedBy, staticComponentsHandling = 'auto', buildKind = 'full') {
     let engineHeadSha = '';
     try {
         engineHeadSha = await getHead(engineDir);
@@ -106,6 +112,7 @@ export async function writeBuildBaseline(projectRoot, engineDir, binaryName, tes
         }
     }
     const packageableFingerprints = await collectPackageableFingerprints(engineDir);
+    const buildInputFingerprints = await collectBuildInputFingerprints(engineDir, previousBaseline, buildKind);
     // A full-coverage write (and the legacy no-claim `fireforge build` shape)
     // just recompiled the StaticComponents table, so it anchors the table to
     // the current engine state. A scoped write did not — carry the previous
@@ -121,6 +128,7 @@ export async function writeBuildBaseline(projectRoot, engineDir, binaryName, tes
         builtAt: new Date().toISOString(),
         binaryName,
         ...(packageableFingerprints !== undefined ? { packageableFingerprints } : {}),
+        ...(buildInputFingerprints !== undefined ? { buildInputFingerprints } : {}),
         ...(testPackagingCoverage !== undefined ? { testPackagingCoverage } : {}),
         ...(mozconfigHash !== undefined ? { mozconfigHash } : {}),
         ...(staticComponentsBaseline !== undefined ? { staticComponentsBaseline } : {}),
@@ -143,6 +151,34 @@ export async function writeBuildBaseline(projectRoot, engineDir, binaryName, tes
 async function collectPackageableFingerprints(engineDir) {
     return collectDirtyFingerprints(engineDir, isPackageablePath, 'packageable fingerprint');
 }
+/**
+ * Content fingerprints of the dirty build-input manifests
+ * ({@link isBuildInputPath}) this build consumed. Backend inputs
+ * (`moz.build` & co) are always taken from the live tree: the
+ * auto-configure preflight reconfigured against them before this build
+ * ran. `jar.mn` entries are taken from the live tree only after a FULL
+ * build; a `faster` write carries the previous record's `jar.mn` entries
+ * forward verbatim, because `mach build faster` is exactly the build the
+ * `jar.mn` escalation exists to bypass, and recording a `jar.mn` it did
+ * not install would silence the next escalation. Returns `undefined` on
+ * probe failure so the field is omitted rather than written as `{}`.
+ */
+async function collectBuildInputFingerprints(engineDir, previousBaseline, buildKind) {
+    const live = await collectDirtyFingerprints(engineDir, isBuildInputPath, 'build-input fingerprint');
+    if (live === undefined || buildKind === 'full') {
+        return live;
+    }
+    const fingerprints = {};
+    for (const [path, hash] of Object.entries(live)) {
+        if (!isJarManifestPath(path))
+            fingerprints[path] = hash;
+    }
+    for (const [path, hash] of Object.entries(previousBaseline?.buildInputFingerprints ?? {})) {
+        if (isJarManifestPath(path))
+            fingerprints[path] = hash;
+    }
+    return fingerprints;
+}
 /**
  * Anchor for the compiled StaticComponents table: the engine HEAD SHA of
  * this (full) build plus content fingerprints of the `components.conf`

package/dist/src/core/build-prepare.js

@@ -11,8 +11,9 @@ import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { info, notice, spinner, verbose, warn } from '../utils/logger.js';
 import { isBrandingSetup, setupBranding } from './branding.js';
+import { isBuildInputPath, isJarManifestPath } from './build-audit.js';
 import { findUnexportedDriftAtRisk, formatUnexportedDriftWarning, } from './build-overwrite-guard.js';
-import { collectChangedEnginePaths } from './engine-changes.js';
+import { collectChangedEnginePaths, dropPathsMatchingFingerprints } from './engine-changes.js';
 import { applyAllComponents } from './furnace-apply.js';
 import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceState, } from './furnace-config.js';
 import { runFurnaceMutation } from './furnace-operation.js';
@@ -24,7 +25,35 @@ import { explainMachError } from './mach-error-hints.js';
 const BACKEND_INVALIDATING_SUFFIXES = ['moz.build', 'moz.configure', 'Makefile.in'];
 /** Packaging manifests whose graph/destination directories need a full build. */
 export function requiresFullBuildForIncrementalTest(path) {
-    return path === 'jar.mn' || path.endsWith('/jar.mn');
+    return isJarManifestPath(path);
+}
+/**
+ * Build-input manifests changed since the last SUCCESSFUL build — not
+ * merely dirty against HEAD. `collectChangedEnginePaths` unions the
+ * baseline-to-HEAD diff with every worktree modification, and a fork's
+ * worktree is permanently dirty (imported patches, Furnace-applied
+ * components), so on its own it reports a patch-touched `jar.mn` or
+ * `moz.build` as changed on every run: `mach configure` re-ran and the
+ * pre-test build escalated to a full `mach build` after each full build
+ * that had already consumed exactly this content. The baseline's
+ * `buildInputFingerprints` say what the last successful build saw;
+ * anything byte-identical to that is dropped here. A baseline without the
+ * field (written before it existed) keeps every dirty input, which is the
+ * old behaviour.
+ *
+ * @param engineDir - Path to the engine directory
+ * @param baseline - Last successful build's baseline
+ * @returns Engine-relative build-input paths that still need acting on
+ */
+async function collectChangedBuildInputs(engineDir, baseline) {
+    const changed = await collectChangedEnginePaths(engineDir, baseline, 'Auto-configure');
+    const dirtyInputs = changed.filter(isBuildInputPath);
+    const stillChanged = await dropPathsMatchingFingerprints(engineDir, dirtyInputs, baseline.buildInputFingerprints);
+    const unchangedSinceBuild = dirtyInputs.filter((path) => !stillChanged.includes(path));
+    if (unchangedSinceBuild.length > 0) {
+        verbose(`Auto-configure: ${unchangedSinceBuild.length} dirty build input(s) byte-identical to the last successful build, not treated as changed: ${unchangedSinceBuild.join(', ')}`);
+    }
+    return stillChanged;
 }
 /**
  * Extracts the tail of captured `mach configure` output so the underlying
@@ -149,7 +178,7 @@ export async function prepareBuildEnvironment(projectRoot, paths, config, option
     let reconfigured = false;
     let fullBuildRequired = false;
     if (options.previousBaseline) {
-        const changed = await collectChangedEnginePaths(paths.engine, options.previousBaseline, 'Auto-configure');
+        const changed = await collectChangedBuildInputs(paths.engine, options.previousBaseline);
         const invalidating = changed.filter(isBackendInvalidatingFile);
         fullBuildRequired = changed.some(requiresFullBuildForIncrementalTest);
         if (invalidating.length > 0) {