@hominis/fireforge 0.43.1 → 0.44.1

package/dist/src/core/test-stale-check.js

@@ -4,24 +4,23 @@
  *
  * Without this preflight, an operator who edits engine chrome / packaged
  * resources (`jar.mn` entries, `.xhtml`/`.mjs`/`.css` under chrome trees,
- * pref files) and then runs `fireforge test <path>` only discovers the
- * build is stale AFTER xpcshell / mach test starts and errors out with
- * `NS_ERROR_FILE_NOT_FOUND` against a `chrome://browser/content/…` URI
- * — which reads as a test bug, not a rebuild prompt. The motivating case
- * was scaffolding a new top-level chrome document + BrowserGlue-style
- * xpcshell test: the test file existed, the manifests were registered,
- * but `dist/` still held the pre-edit bundle and chrome URIs resolved
- * to nothing.
+ * pref files) and then runs `fireforge test <path>` only discovers the build
+ * is stale AFTER xpcshell / mach test starts and errors out with
+ * `NS_ERROR_FILE_NOT_FOUND` against a `chrome://browser/content/…` URI —
+ * which reads as a test bug, not a rebuild prompt. Scaffolding a new
+ * top-level chrome document plus an xpcshell test is the canonical case: the
+ * test file exists, the manifests are registered, but `dist/` still holds
+ * the pre-edit bundle and chrome URIs resolve to nothing.
  *
  * This preflight diffs engine HEAD (or workdir) against the last-build
  * baseline (`.fireforge/last-build.json`), filters to paths that imply
  * packaging, and returns a compact summary. `fireforge test` prints a
- * warning up-front so the operator sees "you edited X, Y, Z since the
- * last build — rerun with `--build` to refresh" BEFORE mach test
- * launches. Detection stays advisory (warn-only) because a fork that
- * rebuilds out-of-band (a separate `./mach build` invocation, an IDE
- * plugin, etc.) can legitimately have a fresh `dist/` with no
- * FireForge-recorded baseline update.
+ * warning up-front so the operator sees "you edited X, Y, Z since the last
+ * build — rerun with `--build` to refresh" BEFORE mach test launches.
+ * Detection stays advisory (warn-only) because a fork that rebuilds
+ * out-of-band (a separate `./mach build` invocation, an IDE plugin) can
+ * legitimately have a fresh `dist/` with no FireForge-recorded baseline
+ * update.
  */
 import { toError } from '../utils/errors.js';
 import { verbose, warn } from '../utils/logger.js';
@@ -51,17 +50,16 @@ export async function checkStaleBuildForTest(projectRoot, engineDir) {
     let packageable = changed.filter((path) => isPackageablePath(path)).sort();
     // Content-hash comparison: when the baseline carries a fingerprint set,
     // fold each candidate path through a live re-hash and drop paths whose
-    // current content matches the baseline. Pre-0.16.0 baselines have no
-    // `packageableFingerprints` field; those fall through and the
-    // path-only comparison behaves as before (every workdir-dirty
-    // packageable path is reported as stale). The concrete motivating
-    // case: a project with imported patches + Furnace-applied components
-    // always has a persistent workdir diff against HEAD. Before the
-    // fingerprint layer, `git diff --name-only HEAD` returned that diff
-    // on every build, so the stale check fired immediately after a
-    // successful build even though nothing had actually changed. The
-    // fingerprints capture "these files had this content when the build
-    // ran"; a path stays stale only when its live hash diverges.
+    // current content matches the baseline. Baselines without
+    // `packageableFingerprints` fall through to the path-only comparison,
+    // where every workdir-dirty packageable path reports as stale.
+    //
+    // This matters because a project with imported patches plus
+    // Furnace-applied components always has a persistent workdir diff against
+    // HEAD, so `git diff --name-only HEAD` returns that diff on every build
+    // and the stale check fires immediately after a successful one. The
+    // fingerprints capture "these files had this content when the build ran";
+    // a path stays stale only when its live hash diverges.
     const fingerprints = baseline.packageableFingerprints;
     if (fingerprints) {
         const staleAfterHashCheck = [];
@@ -105,16 +103,16 @@ export const FULL_SUITE_REQUEST = '(entire suite)';
  * packaging does NOT cover — the runs that would dispatch against missing
  * `_tests/` support fixtures and hang rather than fail.
  *
- * Coverage semantics: `undefined` (pre-0.37.0 baseline) and `'full'` cover
- * everything. A scoped list covers a request path when the request equals a
- * covered entry, sits beneath a covered directory entry, or shares a
- * manifest granule with a covered entry ({@link toManifestGranule} — a
- * scoped `test --build` packages the whole manifest directory, so a
- * same-manifest sibling of a covered file is packaged too). Both sides are
- * normalized to forward slashes so Windows-style CLI input cannot defeat
- * the prefix rule (baseline paths are POSIX by convention). A request with
- * no paths is a full-suite run and is never covered by a scoped list — the
- * {@link FULL_SUITE_REQUEST} sentinel is returned so the refusal can name it.
+ * Coverage semantics: an absent claim and `'full'` cover everything. A
+ * scoped list covers a request path when the request equals a covered entry,
+ * sits beneath a covered directory entry, or shares a manifest granule with
+ * a covered entry ({@link toManifestGranule} — a scoped `test --build`
+ * packages the whole manifest directory, so a same-manifest sibling of a
+ * covered file is packaged too). Both sides are normalized to forward
+ * slashes so Windows-style CLI input cannot defeat the prefix rule (baseline
+ * paths are POSIX by convention). A request with no paths is a full-suite
+ * run and is never covered by a scoped list — the {@link FULL_SUITE_REQUEST}
+ * sentinel is returned so the refusal can name it.
  */
 export function findUncoveredRequestPaths(coverage, requestedPaths) {
     if (coverage === undefined || coverage === 'full') {
@@ -167,8 +165,17 @@ export function formatTestCoverageRefusal(uncovered, coverage) {
         return head.join(', ') + (truncated > 0 ? `, … (+${truncated} more)` : '');
     };
     const rebuildTargets = uncovered.filter((p) => p !== FULL_SUITE_REQUEST);
+    // Name --extend-coverage here or it is undiscoverable: a scoped build
+    // REPLACES the claim, so under several concurrent sessions a peer's build
+    // for an unrelated path erases coverage you legitimately still hold, and
+    // the union that fixes it is a flag the operator has no reason to know
+    // exists at the moment they need it. The anchor conditions are stated
+    // because they are what decides whether it will work.
+    const extendHint = rebuildTargets.length > 0
+        ? ` Add --extend-coverage to that rebuild to UNION the new paths onto the recorded claim instead of replacing it — it holds while engine HEAD and engine/mozconfig are unchanged since the recorded build.`
+        : '';
     const rebuildHint = rebuildTargets.length > 0
-        ? `Rerun "fireforge test --build ${rebuildTargets.slice(0, STALE_PATHS_LIMIT).join(' ')}" to package them, or run "fireforge build" for full coverage.`
+        ? `Rerun "fireforge test --build ${rebuildTargets.slice(0, STALE_PATHS_LIMIT).join(' ')}" to package them, or run "fireforge build" for full coverage.${extendHint}`
         : 'Run "fireforge build" (or a path-less "fireforge test --build") for full coverage first.';
     return (`The packaged test runtime was produced by a scoped "fireforge test --build" covering only: ${cap(coverage)}.\n` +
         `The requested run needs ${cap(uncovered)}, which that packaging does not cover — support ` +
@@ -180,17 +187,17 @@ export function formatTestCoverageRefusal(uncovered, coverage) {
  * Probes whether any `components.conf` changed since the last FULL
  * `fireforge build` — i.e. since the compiled StaticComponents table was
  * last regenerated. `components.conf` entries bake into compiled code; a
- * scoped `test --build` packages the file but the child process resolves
- * the OLD table and fails with `NS_ERROR_MALFORMED_URI` that reads as a
- * test bug.
+ * scoped `test --build` packages the file but the child process resolves the
+ * OLD table and fails with `NS_ERROR_MALFORMED_URI` that reads as a test
+ * bug.
  *
  * The diff anchors to the baseline's `staticComponentsBaseline` (the last
- * full build's engine HEAD SHA), NOT the baseline's own `engineHeadSha`
+ * full build's engine HEAD SHA), NOT the baseline's own `engineHeadSha`,
  * which a scoped `test --build` advances. Dirty candidates are hash-checked
  * against the anchor's fingerprints so only genuine content divergence
- * counts. No baseline / no anchor (pre-0.38.0 marker) → fresh. Never
- * throws — the probes it composes degrade to verbose lines and empty
- * results on git failure, matching {@link checkStaleBuildForTest}.
+ * counts. No baseline or no anchor means fresh. Never throws — the probes it
+ * composes degrade to verbose lines and empty results on git failure,
+ * matching {@link checkStaleBuildForTest}.
  */
 export async function checkStaticComponentsStale(engineDir, baseline) {
     const anchor = baseline?.staticComponentsBaseline;

package/dist/src/core/test-stall-triage.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Operator-facing triage for the `timed out … with no output` / `Ran 0
+ * checks` stall — the shape where the harness dies before ANY test output.
+ *
+ * Split out of `test-harness-crash.ts`, which CLASSIFIES runs; this module
+ * only renders advice about one already-classified shape. Keeping the two
+ * apart matters because the census below carries claims of unequal
+ * evidential strength, and the rules for editing it are not the rules for
+ * editing a classifier: a pattern in the classifier is either matched by
+ * the output or not, while a cause in the census is an assertion about the
+ * world that an operator will act on.
+ *
+ * Everything here is pure — the platform and the probed display state are
+ * injected, so unit tests need no mocking.
+ */
+import type { DisplaySleepState } from './display-state.js';
+import type { HarnessCrashSignature } from './test-harness-signature.js';
+/**
+ * Optional hint appended to the harness-crash message when a HEADED run on
+ * macOS died at the no-output timeout.
+ *
+ * When `displayState` names a MEASURED display state, the hint states it as
+ * fact rather than as one of three possibilities — that is the point of
+ * probing: an operator staring at a bare test failure should not have to
+ * rediscover that their machine dimmed. `caffeinate` is described accurately
+ * (it prevents sleep; it cannot wake an already-sleeping display), so
+ * operators are not sent to a command that could not have helped them.
+ *
+ * Pure — the platform and the probed state are injected so unit tests need
+ * no mocking.
+ *
+ * @param signature - The recognized crash shape
+ * @param context - Run mode, platform, and the probed display state
+ * @returns The hint text, or undefined when the shape does not apply
+ */
+export declare function headedNoOutputTimeoutHint(signature: HarnessCrashSignature, context: {
+    headless: boolean;
+    platform: string;
+    displayState?: DisplaySleepState;
+}): string | undefined;
+/**
+ * Verdict-line note for a headed no-output stall whose display was
+ * measured asleep. Returned as the parenthetical the verdict line carries,
+ * so the one greppable line an automated consumer reads already names the
+ * environmental cause instead of a bare `FAIL reason=crash`.
+ */
+export declare function headedDisplayAsleepVerdictNote(signature: HarnessCrashSignature, context: {
+    headless: boolean;
+    platform: string;
+    displayState: DisplaySleepState;
+}): string | undefined;

package/dist/src/core/test-stall-triage.js

@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Operator-facing triage for the `timed out … with no output` / `Ran 0
+ * checks` stall — the shape where the harness dies before ANY test output.
+ *
+ * Split out of `test-harness-crash.ts`, which CLASSIFIES runs; this module
+ * only renders advice about one already-classified shape. Keeping the two
+ * apart matters because the census below carries claims of unequal
+ * evidential strength, and the rules for editing it are not the rules for
+ * editing a classifier: a pattern in the classifier is either matched by
+ * the output or not, while a cause in the census is an assertion about the
+ * world that an operator will act on.
+ *
+ * Everything here is pure — the platform and the probed display state are
+ * injected, so unit tests need no mocking.
+ */
+/**
+ * First step for the `timed out … with no output` / `Ran 0 checks`
+ * signature, printed ABOVE the cause list. Running a known-good control
+ * separates "this test" from "this build" and is the correct opening move
+ * for EVERY cause below — it is not specific to any one of them, so
+ * attaching it to a single entry made reaching that entry informationally
+ * empty.
+ */
+const NO_OUTPUT_STALL_CONTROL_STEP = 'First, run a known-good control test. If the control stalls too, the cause is not the test ' +
+    'under investigation, and the list below applies to the build or the host.';
+/**
+ * Recorded causes of the `timed out … with no output` / `Ran 0 checks`
+ * signature, each paired with the probe that DISCRIMINATES it from the
+ * others. Printed verbatim under the hint.
+ *
+ * Evidence per entry is deliberately unequal, and the text says so:
+ *
+ *  - (1) is MEASURED — `probeDisplaySleepState` reads the display's power
+ *    state, so the hint states it as fact rather than as a possibility.
+ *  - (2) is discriminated by `--headless`.
+ *  - (4) is MECHANICAL and was root-caused downstream: the harness serves
+ *    its manifest from `server.js` on 8888, and a survivor of an
+ *    interrupted run keeps the port. Its probe is exact, and the preflight
+ *    in `mochitest-server-port.ts` now refuses it before a run starts.
+ *  - (3) is a single downstream report (one consumer, 3/3 reproduce and 3/3
+ *    restore on one variable) whose MECHANISM was never root-caused. It is
+ *    stated as the correlation it is. An earlier revision asserted "stalls
+ *    first paint" as fact; that was a causal story written on top of the
+ *    correlation, and a doubtful one — a failed image load in Gecko fires
+ *    `error` and does not gate the document load event, and the harness's
+ *    browser-ready handshake does not wait on image decode. Do not restore
+ *    a mechanism claim here without a root cause to cite.
+ *
+ * Detection (a named signature, as with the module-resolution SIGSEGV) is
+ * not specified for (3) because no log line is known to key on. The bar for
+ * adding one is the bar `mach-error-hints.ts` states: an established
+ * diagnosis, never a plausible guess.
+ */
+const NO_OUTPUT_STALL_TRIAGE = [
+    '  1. A sleeping or locked display on an unattended HEADED run (macOS). The browser never ' +
+        'paints and never reaches its first test.',
+    '  2. A headless SWGL compositor failure — re-run with --headless to separate this from (1): ' +
+        'if --headless passes, the stall was display/compositor-side, not product-side.',
+    '  3. Product-side startup: the browser never reaches the state the harness waits for. One ' +
+        'downstream report correlates this stall with a broken `chrome://` image URI on the ' +
+        'startup page (reproduced and un-reproduced on that one variable); the mechanism was ' +
+        'never root-caused, so treat it as a lead, not an explanation. Discriminate with ' +
+        '"fireforge run --smoke-exit 60 --headless --capture-console <file>", which launches the ' +
+        'same browser OUTSIDE the test harness: a clean window with no unallowed console errors ' +
+        'means product-side startup is healthy and the stall is harness- or test-side; a hang, a ' +
+        'non-zero exit, or console errors in <file> put it in the startup document.',
+    '  4. A stale mochitest httpd holding the harness server port (127.0.0.1:8888). A fresh ' +
+        "browser connects to THAT server, which cannot serve this run's manifest, so the run " +
+        'stalls before TEST_START. Probe with "lsof -nP -iTCP:8888": any listener that is not ' +
+        "this run's own is the cause. FireForge now refuses this at preflight, so it should " +
+        'reach a stall only on a host where the port could not be probed.',
+];
+/**
+ * Optional hint appended to the harness-crash message when a HEADED run on
+ * macOS died at the no-output timeout.
+ *
+ * When `displayState` names a MEASURED display state, the hint states it as
+ * fact rather than as one of three possibilities — that is the point of
+ * probing: an operator staring at a bare test failure should not have to
+ * rediscover that their machine dimmed. `caffeinate` is described accurately
+ * (it prevents sleep; it cannot wake an already-sleeping display), so
+ * operators are not sent to a command that could not have helped them.
+ *
+ * Pure — the platform and the probed state are injected so unit tests need
+ * no mocking.
+ *
+ * @param signature - The recognized crash shape
+ * @param context - Run mode, platform, and the probed display state
+ * @returns The hint text, or undefined when the shape does not apply
+ */
+export function headedNoOutputTimeoutHint(signature, context) {
+    if (context.platform !== 'darwin' || context.headless)
+        return undefined;
+    if (!signature.reason.includes('no-output timeout'))
+        return undefined;
+    const lead = context.displayState === 'asleep'
+        ? 'Hint: this was a HEADED run on macOS and the display was MEASURED ASLEEP ' +
+            '(IODisplayWrangler below its awake power state). A headed browser on a sleeping ' +
+            'display never paints and never starts a test, so this stall is environmental — not a ' +
+            'product or test failure.'
+        : context.displayState === 'awake'
+            ? 'Hint: this was a HEADED run on macOS that died at the no-output timeout. The display ' +
+                'was measured AWAKE, so the sleeping-display cause below is ruled out for this run.'
+            : 'Hint: this was a HEADED run on macOS that died at the no-output timeout. The display ' +
+                'state could not be measured, so all three causes below remain open.';
+    const remedy = 'Note that `caffeinate -disu` PREVENTS sleep; it cannot WAKE a display that is already ' +
+        'asleep. Wake the display (or run on an attended machine), or pass --headless.';
+    return (`${lead}\n\n${NO_OUTPUT_STALL_CONTROL_STEP}\n\n` +
+        `Known causes of this exact signature:\n${NO_OUTPUT_STALL_TRIAGE.join('\n')}\n\n${remedy}`);
+}
+/**
+ * Verdict-line note for a headed no-output stall whose display was
+ * measured asleep. Returned as the parenthetical the verdict line carries,
+ * so the one greppable line an automated consumer reads already names the
+ * environmental cause instead of a bare `FAIL reason=crash`.
+ */
+export function headedDisplayAsleepVerdictNote(signature, context) {
+    if (context.platform !== 'darwin' || context.headless)
+        return undefined;
+    if (context.displayState !== 'asleep')
+        return undefined;
+    if (!signature.reason.includes('no-output timeout'))
+        return undefined;
+    return 'headed run stalled with the display asleep';
+}

package/dist/src/core/token-category.js

@@ -1,15 +1,13 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Category banner and token-declaration helpers for the tokens CSS file
- *. Split out of `token-manager.ts` to stay inside the per-file
- * line budget.
+ * Category banner and token-declaration helpers for the tokens CSS file.
+ * Split out of `token-manager.ts` to stay inside the per-file line budget.
  *
  * Banner matching is EXACT: the text between the `=` runs (single-line
  * shape) or on the block line (multi-line shape) must equal the category
- * after trimming. The pre-0.40.0 substring match let a TOC comment or a
- * longer banner (`Colors — Canvas` for `Colors`) satisfy the lookup, so
- * `token add` wrote into the wrong section — or no-oped for 19
- * consecutive calls — with exit 0.
+ * after trimming. A substring match lets a TOC comment or a longer banner
+ * (`Colors — Canvas` for `Colors`) satisfy the lookup, so `token add` writes
+ * into the wrong section — or no-ops — with exit 0.
  */
 import { join } from 'node:path';
 import { GeneralError } from '../errors/base.js';
@@ -21,6 +19,63 @@ function singleLineBannerPattern(category) {
 function multiLineBlockNameMatches(blockLine, category) {
     return blockLine.replace(/^\s*\*\s*/, '').trim() === category;
 }
+/**
+ * Body of the first `/* … *\/` comment on `line`, or `null` when the line
+ * carries no closed block comment.
+ *
+ * Deliberately index arithmetic rather than a regex: every regex spelling of
+ * "banner comment" this module used to carry was super-linear on a line that
+ * repeats the opening shape (CodeQL `js/polynomial-redos`), and `tokens.css`
+ * is a file FireForge reads out of a consumer's engine tree, so a
+ * pathological line needs no attacker to arrive.
+ */
+function blockCommentBody(line) {
+    const open = line.indexOf('/*');
+    if (open === -1)
+        return null;
+    const close = line.indexOf('*/', open + 2);
+    if (close === -1)
+        return null;
+    return line.slice(open + 2, close);
+}
+/**
+ * True when `line` carries a single-line banner comment — a closed block
+ * comment whose body both opens and closes with `=`. Recognises the decorative
+ * all-`=` rule as well as a named `= Foo =` banner, which is what the section
+ * scan wants: either shape ends the preceding section.
+ */
+function isSingleLineBannerLine(line) {
+    const body = blockCommentBody(line)?.trim();
+    return body !== undefined && body.length >= 2 && body.startsWith('=') && body.endsWith('=');
+}
+/**
+ * Name declared by a single-line banner (`/* = Foo = *\/` → `Foo`), or `null`
+ * when the line is not a named banner. The `=` runs on both sides are
+ * required; a decorative all-`=` rule carries no name and yields `null`.
+ */
+function singleLineBannerName(line) {
+    const body = blockCommentBody(line);
+    if (body === null)
+        return null;
+    let start = 0;
+    let end = body.length;
+    while (start < end && /\s/.test(body[start] ?? ''))
+        start++;
+    const leadingEqStart = start;
+    while (start < end && body[start] === '=')
+        start++;
+    if (start === leadingEqStart)
+        return null;
+    while (end > start && /\s/.test(body[end - 1] ?? ''))
+        end--;
+    const trailingEqEnd = end;
+    while (end > start && body[end - 1] === '=')
+        end--;
+    if (end === trailingEqEnd)
+        return null;
+    const name = body.slice(start, end).trim();
+    return name.length > 0 ? name : null;
+}
 /**
  * True when `lines` contain a category header (single-line or multi-line
  * banner shape) whose name EQUALS `category`. Shared by the pre-add
@@ -62,14 +117,11 @@ export function categoryHeaderExists(lines, category) {
  */
 function discoverCategoryHeaders(lines) {
     const categories = new Set();
-    const singleLinePattern = /\/\*\s*=+\s*(.+?)\s*=+\s*\*\//;
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i] ?? '';
-        const singleMatch = singleLinePattern.exec(line);
-        if (singleMatch?.[1]) {
-            const extracted = singleMatch[1].trim();
-            if (extracted.length > 0)
-                categories.add(extracted);
+        const extracted = singleLineBannerName(line);
+        if (extracted !== null) {
+            categories.add(extracted);
             continue;
         }
         if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
@@ -183,7 +235,7 @@ export function findCategorySection(lines, category, tokensCssPath) {
     let sectionEnd = lines.length;
     for (let i = scanStart; i < lines.length; i++) {
         const line = lines[i] ?? '';
-        if (/\/\*\s*=.*=\s*\*\//.test(line) ||
+        if (isSingleLineBannerLine(line) ||
             (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) ||
             /^\s*\}/.test(line)) {
             sectionEnd = i;

package/dist/src/core/token-coverage.js

@@ -7,17 +7,17 @@ import { countRawCssColors } from '../utils/regex.js';
 import { loadFurnaceConfig } from './furnace-config.js';
 /**
  * Default platform prefixes treated as allowlisted upstream vars. Any
- * `var(--moz-*)` usage in a fork's CSS is a Firefox platform variable
- * that the fork does not own and should not be counted as an unknown.
- * 2026-04-21 eval (Finding #5): a `furnace override moz-button -t
- * css-only` + one fork token produced 1% coverage because the 84
- * upstream `--moz-*` vars in the copied baseline counted as unknown.
+ * `var(--moz-*)` usage in a fork's CSS is a Firefox platform variable the
+ * fork does not own and must not count as an unknown — otherwise a
+ * `furnace override moz-button -t css-only` plus one fork token reports 1%
+ * coverage, because the ~84 upstream `--moz-*` vars in the copied baseline
+ * all count against it.
  *
  * Forks that want to opt out can override this via
- * `furnace.json.platformPrefixes = []`; forks that want more can
- * extend it (e.g. `['--moz-', '--in-content-']`). The config is
- * additive — nothing is removed from the defaults unless the operator
- * explicitly writes a shorter list.
+ * `furnace.json.platformPrefixes = []`; forks that want more can extend it
+ * (e.g. `['--moz-', '--in-content-']`). The config is additive — nothing is
+ * removed from the defaults unless the operator explicitly writes a shorter
+ * list.
  */
 const DEFAULT_PLATFORM_PREFIXES = ['--moz-'];
 /**

package/dist/src/core/token-dark-mode.d.ts

@@ -1,17 +1,15 @@
 /**
  * Dark-mode insertion helpers for the tokens CSS scaffold.
  *
- * The 2026-04-21 eval reproduced a bug where `fireforge token add
- * --mode override --dark-value ...` landed the dark declaration
- * AFTER the nested `:root { }` inside the
- * `@media (prefers-color-scheme: dark)` block had already closed,
- * producing a declaration outside any rule block. The helpers here
- * scan the comment-stripped source lines to find the *inner* `:root`
- * block's closing `}` and return a line index the caller can splice
- * into. When the inner `:root` is missing (a scaffold that drifted
- * from the default), the fallback helper returns the outer `@media`
- * block's close so the caller can materialise a fresh `:root` wrapper
- * rather than dropping the dark value.
+ * `fireforge token add --mode override --dark-value ...` must land the dark
+ * declaration INSIDE the nested `:root { }` of the
+ * `@media (prefers-color-scheme: dark)` block; landing after that block has
+ * closed produces a declaration outside any rule. The helpers here scan the
+ * comment-stripped source lines to find the *inner* `:root` block's closing
+ * `}` and return a line index the caller can splice into. When the inner
+ * `:root` is missing (a scaffold that drifted from the default), the
+ * fallback helper returns the outer `@media` block's close so the caller can
+ * materialise a fresh `:root` wrapper rather than dropping the dark value.
  */
 /**
  * Strips the content of `/* ... *\/` block comments from an array of

package/dist/src/core/token-dark-mode.js

@@ -2,18 +2,34 @@
 /**
  * Dark-mode insertion helpers for the tokens CSS scaffold.
  *
- * The 2026-04-21 eval reproduced a bug where `fireforge token add
- * --mode override --dark-value ...` landed the dark declaration
- * AFTER the nested `:root { }` inside the
- * `@media (prefers-color-scheme: dark)` block had already closed,
- * producing a declaration outside any rule block. The helpers here
- * scan the comment-stripped source lines to find the *inner* `:root`
- * block's closing `}` and return a line index the caller can splice
- * into. When the inner `:root` is missing (a scaffold that drifted
- * from the default), the fallback helper returns the outer `@media`
- * block's close so the caller can materialise a fresh `:root` wrapper
- * rather than dropping the dark value.
+ * `fireforge token add --mode override --dark-value ...` must land the dark
+ * declaration INSIDE the nested `:root { }` of the
+ * `@media (prefers-color-scheme: dark)` block; landing after that block has
+ * closed produces a declaration outside any rule. The helpers here scan the
+ * comment-stripped source lines to find the *inner* `:root` block's closing
+ * `}` and return a line index the caller can splice into. When the inner
+ * `:root` is missing (a scaffold that drifted from the default), the
+ * fallback helper returns the outer `@media` block's close so the caller can
+ * materialise a fresh `:root` wrapper rather than dropping the dark value.
  */
+/**
+ * True when `line` carries a `:root` selector whose opening brace is on the
+ * same line, with no intervening brace of either kind.
+ *
+ * Index arithmetic rather than `/:root[^{}]*\{/`: that pattern restarts at
+ * every `:root` in the line, which is quadratic on a line repeating the
+ * selector (CodeQL `js/polynomial-redos`). `tokens.css` comes from a
+ * consumer's engine tree, so such a line needs no attacker to arrive.
+ */
+function rootOpensBraceOnLine(line) {
+    const brace = line.indexOf('{');
+    if (brace === -1)
+        return false;
+    const root = line.lastIndexOf(':root', brace - ':root'.length);
+    if (root === -1 || root + ':root'.length > brace)
+        return false;
+    return !line.slice(root + ':root'.length, brace).includes('}');
+}
 /**
  * Strips the content of `/* ... *\/` block comments from an array of
  * CSS source lines while preserving each line's length. Indexed scans
@@ -87,9 +103,9 @@ export function findDarkRootInsertionIndex(lines) {
     let rootOpenLine = -1;
     for (let i = darkMediaLine; i < stripped.length; i++) {
         const line = stripped[i] ?? '';
-        if (/(^|[\s,{])\s*:root\b/.test(line)) {
+        if (/(?:^|[\s,{]):root\b/.test(line)) {
             // Brace on the same line?
-            if (/:root[^{}]*\{/.test(line)) {
+            if (rootOpensBraceOnLine(line)) {
                 rootOpenLine = i;
                 break;
             }

package/dist/src/core/token-docs.d.ts

@@ -21,6 +21,8 @@ export interface TokenDocInput {
  * against a freshly parsed view of the document so that splice indices
  * stay valid as rewrites are layered.
  *
+ * @param engineDir - Absolute path to the engine checkout
+ * @param options - Token name, category and description to document
  * @param annotation - The mode annotation string the caller already computed
  *   (kept here as a parameter so this module needs no dependency on
  *   token-manager's `getModeAnnotation`).

package/dist/src/core/token-docs.js

@@ -26,6 +26,8 @@ function stripInlineCode(cell) {
  * against a freshly parsed view of the document so that splice indices
  * stay valid as rewrites are layered.
  *
+ * @param engineDir - Absolute path to the engine checkout
+ * @param options - Token name, category and description to document
  * @param annotation - The mode annotation string the caller already computed
  *   (kept here as a parameter so this module needs no dependency on
  *   token-manager's `getModeAnnotation`).
@@ -42,7 +44,7 @@ export async function addTokenToDocs(engineDir, options, annotation) {
     let unmappedAdded = false;
     let countUpdated = false;
     const isLiteral = !options.value.startsWith('var(');
-    const mapsTo = isLiteral ? '—' : options.value.replace(/var\(([^)]+)\)/, '$1');
+    const mapsTo = isLiteral ? '—' : options.value.replace(/^var\(([^)]+)\)/, '$1');
     const tokenCell = `\`${options.tokenName}\``;
     const valueCell = `\`${options.value}\``;
     // --- Main token table: Category | Token | Value | Maps to | Mode ---

package/dist/src/core/token-manager.d.ts

@@ -1,8 +1,16 @@
 import { type TokenDeclarationLocation } from './token-category.js';
 /**
- * Dark mode behavior for a token.
+ * Dark mode behaviour for a token.
+ *
+ * Derived from {@link TOKEN_MODES} so the runtime allowlist and the type
+ * cannot drift: adding a member here without updating the list (or the
+ * reverse) is no longer possible, because there is only one list.
  */
-export type TokenMode = 'auto' | 'static' | 'override';
+export declare const TOKEN_MODES: readonly ["auto", "static", "override"];
+/** Dark mode behaviour for a token. */
+export type TokenMode = (typeof TOKEN_MODES)[number];
+/** Narrows an arbitrary string to a {@link TokenMode}. */
+export declare const isTokenMode: (value: string) => value is "override" | "auto" | "static";
 /**
  * Options for adding a token.
  */