@hominis/fireforge 0.44.0 → 0.44.2

package/dist/src/core/run-log.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Per-run output logs under `.fireforge/logs/`.
+ *
+ * A run's diagnosis used to exist in exactly one place: the terminal. Piping
+ * through `tail`/`grep` — the ergonomic default when output is long — keeps
+ * the summary and discards the `TEST-UNEXPECTED-FAIL` lines that say WHAT
+ * broke, and it launders the exit code besides. The operator rule ("never
+ * pipe a run") was written down three times downstream and broken after each
+ * writing, which is the tell that it is not an operator problem: the tool is
+ * the only party that can make the log survive the mistake.
+ *
+ * So `test` and `build` write their own complete copy as they stream, and the
+ * `FIREFORGE-VERDICT:` line names the path. A piped, truncated, or
+ * backgrounded run then still leaves a re-readable artifact.
+ *
+ * Everything here is BEST-EFFORT by construction. A log is a diagnostic aid;
+ * a run must never fail because one could not be opened, written, or pruned.
+ * Every entry point swallows its errors and degrades to "no log", which is
+ * exactly the behaviour that existed before this module.
+ */
+/** A run log sink. `write` never throws. */
+export interface RunLog {
+    /** Absolute path to the log file. */
+    path: string;
+    /** Appends raw output. Silently drops on any stream error. */
+    write: (chunk: string) => void;
+    /** Flushes and closes. Resolves even when the stream already failed. */
+    close: () => Promise<void>;
+}
+/** `.fireforge/logs` under `projectRoot`. */
+export declare function getRunLogDir(projectRoot: string): string;
+/**
+ * Opens `.fireforge/logs/<command>-<timestamp>.log` for a run, pruning older
+ * logs of the same kind first.
+ *
+ * @param projectRoot - Project root directory
+ * @param command - Command kind, e.g. `test` or `build`
+ * @param now - Clock injection point for deterministic tests
+ * @returns The sink, or undefined when no log could be opened
+ */
+export declare function openRunLog(projectRoot: string, command: string, now?: Date): Promise<RunLog | undefined>;
+/** Installs (or clears, with `undefined`) the run log for this process. */
+export declare function setActiveRunLog(log: RunLog | undefined): void;
+/** Absolute path of the active run log, or undefined when none is open. */
+export declare function getActiveRunLogPath(): string | undefined;
+/** Appends to the active run log. A no-op when none is open. */
+export declare function writeToActiveRunLog(chunk: string): void;
+/** Closes and clears the active run log. Resolves even when none is open. */
+export declare function closeActiveRunLog(): Promise<void>;
+/**
+ * A writable that forwards to `base` AND to the active run log.
+ *
+ * Used by the stdio-inheriting capture path, whose collectors take a mirror
+ * stream rather than per-chunk callbacks — so the tee reuses the mirror the
+ * exec layer already supports instead of growing a second hook.
+ *
+ * @param base - The stream to forward to (normally `process.stdout`)
+ * @returns A writable teeing into `base` and the run log
+ */
+export declare function teeToRunLog(base: NodeJS.WritableStream): NodeJS.WritableStream;

package/dist/src/core/run-log.js

@@ -0,0 +1,183 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Per-run output logs under `.fireforge/logs/`.
+ *
+ * A run's diagnosis used to exist in exactly one place: the terminal. Piping
+ * through `tail`/`grep` — the ergonomic default when output is long — keeps
+ * the summary and discards the `TEST-UNEXPECTED-FAIL` lines that say WHAT
+ * broke, and it launders the exit code besides. The operator rule ("never
+ * pipe a run") was written down three times downstream and broken after each
+ * writing, which is the tell that it is not an operator problem: the tool is
+ * the only party that can make the log survive the mistake.
+ *
+ * So `test` and `build` write their own complete copy as they stream, and the
+ * `FIREFORGE-VERDICT:` line names the path. A piped, truncated, or
+ * backgrounded run then still leaves a re-readable artifact.
+ *
+ * Everything here is BEST-EFFORT by construction. A log is a diagnostic aid;
+ * a run must never fail because one could not be opened, written, or pruned.
+ * Every entry point swallows its errors and degrades to "no log", which is
+ * exactly the behaviour that existed before this module.
+ */
+import { createWriteStream } from 'node:fs';
+import { mkdir, readdir, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { Writable } from 'node:stream';
+import { verbose } from '../utils/logger.js';
+import { FIREFORGE_DIR } from './config-paths.js';
+/** Directory under `.fireforge/` holding run logs. */
+const LOGS_DIRNAME = 'logs';
+/**
+ * How many logs to keep per command kind. Retention is per-kind so a busy
+ * `test` loop cannot evict every `build` log, which is the pair an operator
+ * most often needs to read together.
+ */
+const RETAINED_LOGS_PER_COMMAND = 20;
+/** `.fireforge/logs` under `projectRoot`. */
+export function getRunLogDir(projectRoot) {
+    return join(projectRoot, FIREFORGE_DIR, LOGS_DIRNAME);
+}
+/**
+ * A filesystem-safe, sortable timestamp: `2026-08-28T14-32-05-123Z`.
+ *
+ * Colons are not portable in filenames (Windows rejects them outright), so
+ * the ISO form is punctuated with dashes only. Lexical order still equals
+ * chronological order, which is what the pruning below relies on.
+ */
+function logTimestamp(now) {
+    return now.toISOString().replace(/[:.]/g, '-');
+}
+/**
+ * Makes room for one new log by deleting the oldest, so that at most
+ * {@link RETAINED_LOGS_PER_COMMAND} logs for `command` exist once the new
+ * one is created. Pruning runs BEFORE the file is opened — hence the
+ * `- 1`, without which the directory settles at N + 1.
+ *
+ * Best-effort: a failure here must not stop the run that is about to be
+ * logged.
+ */
+async function pruneRunLogs(dir, command) {
+    const keep = RETAINED_LOGS_PER_COMMAND - 1;
+    try {
+        const entries = await readdir(dir);
+        const mine = entries.filter((name) => name.startsWith(`${command}-`) && name.endsWith('.log'));
+        if (mine.length <= keep)
+            return;
+        // Names embed a lexically-sortable timestamp, so sorting is ordering by
+        // age without stat-ing every file.
+        const stale = mine.sort().slice(0, mine.length - keep);
+        await Promise.all(stale.map(async (name) => {
+            try {
+                await unlink(join(dir, name));
+            }
+            catch {
+                // A concurrent run may have pruned it already.
+            }
+        }));
+    }
+    catch (error) {
+        verbose(`Run-log pruning skipped: ${String(error)}`);
+    }
+}
+/**
+ * Opens `.fireforge/logs/<command>-<timestamp>.log` for a run, pruning older
+ * logs of the same kind first.
+ *
+ * @param projectRoot - Project root directory
+ * @param command - Command kind, e.g. `test` or `build`
+ * @param now - Clock injection point for deterministic tests
+ * @returns The sink, or undefined when no log could be opened
+ */
+export async function openRunLog(projectRoot, command, now = new Date()) {
+    const dir = getRunLogDir(projectRoot);
+    let stream;
+    const path = join(dir, `${command}-${logTimestamp(now)}.log`);
+    try {
+        await mkdir(dir, { recursive: true });
+        await pruneRunLogs(dir, command);
+        stream = createWriteStream(path, { flags: 'a' });
+    }
+    catch (error) {
+        verbose(`Run log unavailable (${path}): ${String(error)}`);
+        return undefined;
+    }
+    // A stream error after open (disk full, a removed directory) must not
+    // become an unhandled 'error' event and kill the run the log exists to
+    // describe. Latch it and drop every later write.
+    let broken = false;
+    stream.on('error', (error) => {
+        broken = true;
+        verbose(`Run log write failed (${path}): ${error.message}`);
+    });
+    return {
+        path,
+        write: (chunk) => {
+            if (broken)
+                return;
+            try {
+                stream.write(chunk);
+            }
+            catch {
+                broken = true;
+            }
+        },
+        close: async () => {
+            await new Promise((resolve) => {
+                stream.end(() => {
+                    resolve();
+                });
+            });
+        },
+    };
+}
+/**
+ * The run log for the command currently executing, if any.
+ *
+ * Module state rather than a threaded parameter, for the same reason
+ * `test-verdict.ts` keeps its emitted-once flag here: the sink has to be
+ * reachable from `mach.ts`'s stream callbacks, which sit five frames below
+ * the command that opened it, behind dispatch signatures that exist to
+ * describe TESTS rather than logging. Threading it would have touched every
+ * dispatcher, the retry wrapper and the shard loop to deliver one pointer.
+ *
+ * One command runs per process, so a single slot is the whole lifetime.
+ */
+let activeRunLog;
+/** Installs (or clears, with `undefined`) the run log for this process. */
+export function setActiveRunLog(log) {
+    activeRunLog = log;
+}
+/** Absolute path of the active run log, or undefined when none is open. */
+export function getActiveRunLogPath() {
+    return activeRunLog?.path;
+}
+/** Appends to the active run log. A no-op when none is open. */
+export function writeToActiveRunLog(chunk) {
+    activeRunLog?.write(chunk);
+}
+/** Closes and clears the active run log. Resolves even when none is open. */
+export async function closeActiveRunLog() {
+    const log = activeRunLog;
+    activeRunLog = undefined;
+    await log?.close();
+}
+/**
+ * A writable that forwards to `base` AND to the active run log.
+ *
+ * Used by the stdio-inheriting capture path, whose collectors take a mirror
+ * stream rather than per-chunk callbacks — so the tee reuses the mirror the
+ * exec layer already supports instead of growing a second hook.
+ *
+ * @param base - The stream to forward to (normally `process.stdout`)
+ * @returns A writable teeing into `base` and the run log
+ */
+export function teeToRunLog(base) {
+    return new Writable({
+        write(chunk, _encoding, callback) {
+            const text = typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+            base.write(text);
+            writeToActiveRunLog(text);
+            callback();
+        },
+    });
+}

package/dist/src/core/test-harness-output.d.ts

@@ -8,7 +8,30 @@ export interface PostRebuildFailureContext {
     requestedPaths: readonly string[];
     firstFailureLine?: string;
 }
-/** Finds the first high-signal failure line from captured mach test output. */
+/**
+ * Finds the first high-signal failure line from captured mach test output.
+ *
+ * Selection is FIRST-MATCHING-LINE, not first-matching-pattern, so the bare
+ * `AttributeError:` arm above has exactly the same standing as
+ * `TEST-UNEXPECTED-FAIL` — whichever appears earlier in the text wins. That
+ * is how a run whose real defect was an export shard's file-count assertion
+ * got diagnosed as the recognized mozsystemmonitor teardown crash: the
+ * information was present and the SELECTION was wrong, which is the
+ * expensive kind of wrong, because the named cause is a real, documented,
+ * unrelated upstream defect and therefore reads as an answer.
+ *
+ * So a capture carrying the recognized teardown incident gets two passes:
+ * candidates excluding its `AttributeError` header first, and only if that
+ * finds nothing does the full set apply. The narrowness the rest of the
+ * codebase maintains is preserved exactly — the exclusion is gated on
+ * `hasKnownTeardownNoise` for the WHOLE capture, so it requires both the
+ * closed attribute allowlist and a `resourcemonitor.py` frame. A novel
+ * attribute, or a traceback from anywhere else, stays a real failure and is
+ * still eligible to be reported.
+ *
+ * @param output - Raw captured stdout/stderr from the run
+ * @returns The chosen failure line, or the first non-empty line
+ */
 export declare function findFirstUsefulFailureLine(output: string): string | undefined;
 /** Starts a post-rebuild context block for a focused test failure. */
 export declare function createPostRebuildFailureContext(rebuildCommand: string, requestedPaths: readonly string[]): PostRebuildFailureContext;

package/dist/src/core/test-harness-output.js

@@ -1,4 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
+import { hasKnownTeardownNoise, isKnownTeardownNoiseLine } from './mach-known-noise-filter.js';
 function getNonEmptyOutputLines(output) {
     return output
         .split(/\r?\n/)
@@ -8,23 +9,53 @@ function getNonEmptyOutputLines(output) {
 function findFirstMatchingLine(lines, patterns) {
     return lines.find((line) => patterns.some((pattern) => pattern.test(line)));
 }
-/** Finds the first high-signal failure line from captured mach test output. */
+const FAILURE_LINE_PATTERNS = [
+    /\bTEST-UNEXPECTED-[A-Z-]+\b/,
+    /\bPROCESS-CRASH\b/i,
+    /\bTIMEOUT\b/i,
+    /timed out/i,
+    /HominisBrowserUnavailableError/i,
+    /Marionette.*(?:session|startup|start).*fail/i,
+    /(?:failed|unable) to (?:start|create|open).*Marionette/i,
+    /SessionNotCreatedException/i,
+    /Browser process exited during spawn/i,
+    /Failed to load (?:resource|chrome):\/\//i,
+    /\b(?:Error|Exception|TypeError|ReferenceError|SyntaxError):\s+/,
+    /AttributeError:\s+/,
+];
+/**
+ * Finds the first high-signal failure line from captured mach test output.
+ *
+ * Selection is FIRST-MATCHING-LINE, not first-matching-pattern, so the bare
+ * `AttributeError:` arm above has exactly the same standing as
+ * `TEST-UNEXPECTED-FAIL` — whichever appears earlier in the text wins. That
+ * is how a run whose real defect was an export shard's file-count assertion
+ * got diagnosed as the recognized mozsystemmonitor teardown crash: the
+ * information was present and the SELECTION was wrong, which is the
+ * expensive kind of wrong, because the named cause is a real, documented,
+ * unrelated upstream defect and therefore reads as an answer.
+ *
+ * So a capture carrying the recognized teardown incident gets two passes:
+ * candidates excluding its `AttributeError` header first, and only if that
+ * finds nothing does the full set apply. The narrowness the rest of the
+ * codebase maintains is preserved exactly — the exclusion is gated on
+ * `hasKnownTeardownNoise` for the WHOLE capture, so it requires both the
+ * closed attribute allowlist and a `resourcemonitor.py` frame. A novel
+ * attribute, or a traceback from anywhere else, stays a real failure and is
+ * still eligible to be reported.
+ *
+ * @param output - Raw captured stdout/stderr from the run
+ * @returns The chosen failure line, or the first non-empty line
+ */
 export function findFirstUsefulFailureLine(output) {
     const lines = getNonEmptyOutputLines(output);
-    const matched = findFirstMatchingLine(lines, [
-        /\bTEST-UNEXPECTED-[A-Z-]+\b/,
-        /\bPROCESS-CRASH\b/i,
-        /\bTIMEOUT\b/i,
-        /timed out/i,
-        /HominisBrowserUnavailableError/i,
-        /Marionette.*(?:session|startup|start).*fail/i,
-        /(?:failed|unable) to (?:start|create|open).*Marionette/i,
-        /SessionNotCreatedException/i,
-        /Browser process exited during spawn/i,
-        /Failed to load (?:resource|chrome):\/\//i,
-        /\b(?:Error|Exception|TypeError|ReferenceError|SyntaxError):\s+/,
-        /AttributeError:\s+/,
-    ]);
+    if (hasKnownTeardownNoise(output)) {
+        const withoutNoise = lines.filter((line) => !isKnownTeardownNoiseLine(line));
+        const preferred = findFirstMatchingLine(withoutNoise, FAILURE_LINE_PATTERNS);
+        if (preferred !== undefined)
+            return preferred;
+    }
+    const matched = findFirstMatchingLine(lines, FAILURE_LINE_PATTERNS);
     return matched ?? lines[0];
 }
 /** Starts a post-rebuild context block for a focused test failure. */

package/dist/src/core/test-xpcshell-retry.d.ts

@@ -4,11 +4,11 @@ export interface XpcshellRetryClassification {
     nonXpcshell: readonly string[];
 }
 /** Dispatches a (possibly suite-specific) mach test run, mirroring `testWithOutput`. */
-export type TestDispatch = (engineDir: string, testPaths: string[], args: string[], env?: Record<string, string>) => Promise<MachCommandResult>;
+export type TestDispatch = (engineDir: string, testPaths: string[], args: string[], env?: Record<string, string>, fullOutput?: boolean) => Promise<MachCommandResult>;
 /**
  * Removes a stale xpcshell install symlink and retries the focused mach test
  * once. The retry uses the same `dispatch` (suite-specific or generic) the
  * caller is already running on, so an xpcshell-suite run repairs and re-runs
  * via `mach xpcshell-test` rather than falling back to the generic command.
  */
-export declare function retryAfterXpcshellSymlinkRepair(engineDir: string, objDir: string | undefined, result: MachCommandResult, classification: XpcshellRetryClassification, normalizedPaths: string[], extraArgs: string[], env?: Record<string, string>, dispatch?: TestDispatch): Promise<MachCommandResult>;
+export declare function retryAfterXpcshellSymlinkRepair(engineDir: string, objDir: string | undefined, result: MachCommandResult, classification: XpcshellRetryClassification, normalizedPaths: string[], extraArgs: string[], env?: Record<string, string>, dispatch?: TestDispatch, fullOutput?: boolean): Promise<MachCommandResult>;

package/dist/src/core/test-xpcshell-retry.js

@@ -7,12 +7,17 @@ import { tryRepairStaleXpcshellTestSymlink } from './test-stale-symlink.js';
  * caller is already running on, so an xpcshell-suite run repairs and re-runs
  * via `mach xpcshell-test` rather than falling back to the generic command.
  */
-export async function retryAfterXpcshellSymlinkRepair(engineDir, objDir, result, classification, normalizedPaths, extraArgs, env, dispatch = testWithOutput) {
+export async function retryAfterXpcshellSymlinkRepair(engineDir, objDir, result, classification, normalizedPaths, extraArgs, env, dispatch = testWithOutput, fullOutput) {
     if (result.exitCode !== 0 &&
         classification.xpcshell.length > 0 &&
         classification.nonXpcshell.length === 0) {
         const repaired = await tryRepairStaleXpcshellTestSymlink(engineDir, objDir, `${result.stdout}\n${result.stderr}`);
         if (repaired) {
+            // The repaired re-run is the same logical invocation, so it keeps
+            // the verbosity the run was started with.
+            if (fullOutput === true) {
+                return dispatch(engineDir, normalizedPaths, extraArgs, env, true);
+            }
             return env
                 ? dispatch(engineDir, normalizedPaths, extraArgs, env)
                 : dispatch(engineDir, normalizedPaths, extraArgs);

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

@@ -19,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
@@ -60,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)) {
@@ -181,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-dark-mode.js

@@ -12,6 +12,24 @@
  * 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
@@ -85,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.js

@@ -44,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

@@ -19,8 +19,13 @@ export interface AddTokenOptions {
     tokenName: string;
     /** CSS value (e.g., "1px", "var(--space-small)", "light-dark(#fff, #000)") */
     value: string;
-    /** Token category matching section headers in the CSS file */
-    category: string;
+    /**
+     * Token category matching section headers in the CSS file. Required for a
+     * base declaration; ignored — and no longer required — under
+     * {@link AddTokenOptions.variant}, which routes into a `:root<selector>`
+     * block and never touches a category section.
+     */
+    category?: string | undefined;
     /** Dark mode behavior */
     mode: TokenMode;
     /** Comment description for the CSS file */