@hominis/fireforge 0.31.0 → 0.33.0

package/dist/src/core/patch-lint.js

@@ -1,13 +1,11 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { dirname, join } from 'node:path';
-import { toError } from '../utils/errors.js';
 import { pathExists, readText } from '../utils/fs.js';
-import { verbose } from '../utils/logger.js';
-import { hasRawCssColors, stripJsComments } from '../utils/regex.js';
-import { loadFurnaceConfig } from './furnace-config.js';
+import { stripJsComments } from '../utils/regex.js';
 import { containsUpstreamLicenseText, getLicenseHeader, hasAnyLicenseHeader, hasAnyLicenseHeaderAnyStyle, } from './license-headers.js';
 import { invokePatchLintCheckJs } from './patch-lint-checkjs.js';
 import { lintChromeScriptJsDocForFile } from './patch-lint-chrome-jsdoc.js';
+import { lintPatchedCss } from './patch-lint-css.js';
 import { detectNewFilesInDiff, extractAddedLinesPerFile } from './patch-lint-diff.js';
 import { AGGREGATE_PATCH_FILE } from './patch-lint-diff-tag.js';
 import { hasRelativeImport } from './patch-lint-imports.js';
@@ -25,6 +23,10 @@ import { resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs } from './patch
 // public surface from `patch-lint-reexports.ts` so callers continue to
 // import from a single module.
 export * from './patch-lint-reexports.js';
+// The CSS rule bodies live in `patch-lint-css.ts` (same per-file-budget
+// split as the other rule families); re-export the imported binding so
+// callers and tests keep importing `lintPatchedCss` from this module.
+export { lintPatchedCss };
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -205,158 +207,6 @@ export function commentStyleForFile(file) {
         return 'js';
     return null;
 }
-/**
- * Loads the furnace token-prefix lint inputs gracefully — returns
- * undefined (skipping the token-prefix check) when furnace.json cannot
- * be loaded or no tokenPrefix is configured.
- */
-async function loadCssTokenContext(repoDir) {
-    try {
-        const root = join(repoDir, '..');
-        const furnaceConfig = await loadFurnaceConfig(root);
-        if (furnaceConfig.tokenPrefix) {
-            return {
-                tokenPrefix: furnaceConfig.tokenPrefix,
-                tokenAllowlist: new Set(furnaceConfig.tokenAllowlist ?? []),
-                runtimeVariables: new Set(furnaceConfig.runtimeVariables ?? []),
-            };
-        }
-    }
-    catch (error) {
-        verbose(`Skipping furnace token-prefix lint hints because furnace.json could not be loaded: ${toError(error).message}`);
-    }
-    return undefined;
-}
-/**
- * Raw-color check for one patched CSS file, scoped to introduced lines
- * when diff context is available. Pushes onto `issues`.
- */
-function checkRawColorValues(file, rawCss, addedLinesByFile, config, issues) {
-    // Check only introduced raw color values when diff context is available.
-    // Skip files on the raw-color allowlist (exact path or basename match) and
-    // auto-exempt files under `browser/branding/` — those are the fork's
-    // visual identity assets (app-about dialogs, installer pages, branded
-    // CSS copied from Firefox's `unofficial` template) and belong to the
-    // design-decision layer the design-token system does not govern.
-    // Without this auto-exemption, every first-time setup's copied CSS
-    // failed `raw-color-value` with no actionable fix other than manually
-    // listing each path in `rawColorAllowlist`.
-    const allowlist = config?.patchLint?.rawColorAllowlist;
-    const isAllowlisted = allowlist?.some((entry) => file === entry || file.endsWith('/' + entry));
-    const isBranding = file.startsWith('browser/branding/');
-    if (!isAllowlisted && !isBranding) {
-        // Strip lines with inline fireforge-ignore: raw-color-value suppression.
-        // Check against rawCss (before comment stripping) so the CSS comment marker is still present.
-        const sourceForSuppression = addedLinesByFile
-            ? (addedLinesByFile.get(file) ?? []).join('\n')
-            : rawCss;
-        const suppressedContent = sourceForSuppression
-            .split('\n')
-            .filter((line) => !line.includes('fireforge-ignore: raw-color-value'))
-            .join('\n')
-            .replace(/\/\*[\s\S]*?\*\//g, '');
-        if (hasRawCssColors(suppressedContent)) {
-            issues.push({
-                file,
-                check: 'raw-color-value',
-                message: 'Raw color value found. Use CSS custom properties (var(--...)) for design token consistency.',
-                severity: 'error',
-            });
-        }
-    }
-}
-/**
- * Token-prefix check for one patched CSS file: flags `var(--x)` references
- * that match neither the configured prefix, the allowlist, the runtime
- * variables, nor a same-file declaration. Pushes onto `issues`.
- */
-function checkTokenPrefixViolations(file, cssContent, addedLinesByFile, tokenContext, issues) {
-    // Check for non-tokenized custom properties. A variable that is both
-    // declared and consumed inside the same file is auto-exempted as a
-    // runtime state channel (see furnace.json → runtimeVariables).
-    //
-    // When diff context is available, scope the `var(...)` scan to
-    // added/modified lines only. `cssContent` (full-file) is still the
-    // source of `localDeclarations` so vars declared anywhere in the file
-    // are recognised as same-file refs regardless of where the consuming
-    // `var(...)` appears. Before this scoping change, a small edit to a
-    // Furnace override of a stock component (e.g. moz-card) produced a
-    // `token-prefix-violation` for every stock `var(--moz-card-*)` the
-    // upstream file already carried, because the scanner saw the full
-    // applied file and flagged each inherited reference as if the fork
-    // had introduced it.
-    if (tokenContext) {
-        const declarationPattern = /(?:^|[{;,\s])(--[\w-]+)\s*:/g;
-        const localDeclarations = new Set();
-        let declMatch;
-        while ((declMatch = declarationPattern.exec(cssContent)) !== null) {
-            const name = declMatch[1];
-            if (name)
-                localDeclarations.add(name);
-        }
-        const prefixScanSource = addedLinesByFile
-            ? (addedLinesByFile.get(file) ?? []).join('\n').replace(/\/\*[\s\S]*?\*\//g, '')
-            : cssContent;
-        if (prefixScanSource.length > 0) {
-            const varPattern = /var\(\s*(--[\w-]+)/g;
-            const flaggedProps = new Set();
-            let match;
-            while ((match = varPattern.exec(prefixScanSource)) !== null) {
-                const prop = match[1];
-                if (!prop)
-                    continue;
-                if (prop.startsWith(tokenContext.tokenPrefix))
-                    continue;
-                if (tokenContext.tokenAllowlist.has(prop))
-                    continue;
-                if (tokenContext.runtimeVariables.has(prop))
-                    continue;
-                if (localDeclarations.has(prop))
-                    continue;
-                // De-duplicate per (file, prop) pair so the same introduced var
-                // used five times in the added hunk doesn't produce five
-                // identical issue entries.
-                if (flaggedProps.has(prop))
-                    continue;
-                flaggedProps.add(prop);
-                issues.push({
-                    file,
-                    check: 'token-prefix-violation',
-                    message: `CSS references var(${prop}) which does not match the required token prefix "${tokenContext.tokenPrefix}". Use a design token, add to tokenAllowlist, or (for runtime state channels) list the variable in runtimeVariables.`,
-                    severity: 'error',
-                });
-            }
-        }
-    }
-}
-/**
- * Lints patched CSS files for introduced raw color values and non-tokenized
- * custom properties.
- *
- * @param repoDir - Absolute path to the engine (repository) directory
- * @param affectedFiles - File paths (relative to repoDir) affected by the patch
- * @param diffContent - Optional unified diff used to scope raw color checks to introduced lines
- * @returns Array of lint issues found
- */
-export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config) {
-    const cssFiles = affectedFiles.filter((f) => f.endsWith('.css'));
-    if (cssFiles.length === 0)
-        return [];
-    const tokenContext = await loadCssTokenContext(repoDir);
-    const issues = [];
-    const addedLinesByFile = diffContent ? extractAddedLinesPerFile(diffContent) : undefined;
-    for (const file of cssFiles) {
-        const filePath = join(repoDir, file);
-        if (!(await pathExists(filePath)))
-            continue;
-        const rawCss = await readText(filePath);
-        // Strip block comments before scanning
-        const cssContent = rawCss.replace(/\/\*[\s\S]*?\*\//g, '');
-        checkRawColorValues(file, rawCss, addedLinesByFile, config, issues);
-        checkTokenPrefixViolations(file, cssContent, addedLinesByFile, tokenContext, issues);
-    }
-    return issues;
-}
 // ---------------------------------------------------------------------------
 // License header lint
 // ---------------------------------------------------------------------------
@@ -695,9 +545,6 @@ export async function lintModifiedFileHeaders(repoDir, affectedFiles, newFiles)
     }
     return issues;
 }
-// ---------------------------------------------------------------------------
-// Orchestrator
-// ---------------------------------------------------------------------------
 /**
  * Runs all patch lint checks and returns combined issues.
  *
@@ -717,9 +564,11 @@ export async function lintModifiedFileHeaders(repoDir, affectedFiles, newFiles)
  *   per-patch manifest context (re-export, per-patch lint) should
  *   pass this; aggregate-mode callers without a specific patch
  *   context skip it and fall through to auto-detection.
+ * @param options - Optional behaviour switches; see
+ *   {@link LintExportedPatchOptions}.
  * @returns Array of all lint issues found
  */
-export async function lintExportedPatch(repoDir, affectedFiles, diffContent, config, patchQueueCtx, ignoreChecks, patchTier) {
+export async function lintExportedPatch(repoDir, affectedFiles, diffContent, config, patchQueueCtx, ignoreChecks, patchTier, options) {
     const newFiles = detectNewFilesInDiff(diffContent);
     const { textLines: lineCount } = countNonBinaryDiffLines(diffContent);
     const patchOwnedFiles = resolvePatchOwnedSysMjs(newFiles, patchQueueCtx);
@@ -731,7 +580,9 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
         lintModifiedFileHeaders(repoDir, affectedFiles, newFiles),
     ]);
     const modCommentIssues = lintModificationComments(diffContent, config);
-    const sizeIssues = lintPatchSize(affectedFiles, lineCount, patchTier);
+    const sizeIssues = options?.skipPatchSize
+        ? []
+        : lintPatchSize(affectedFiles, lineCount, patchTier);
     const issues = [
         ...sizeIssues,
         ...cssIssues,
@@ -740,8 +591,13 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
         ...jsIssues,
         ...modCommentIssues,
     ];
-    if (config.patchLint?.checkJs) {
-        issues.push(...(await invokePatchLintCheckJs(repoDir, patchOwnedFiles, config.patchLint, dirname(repoDir))));
+    if (options?.precomputedCheckJs) {
+        // Per-patch lint built one queue-wide program and already attributed
+        // this patch's findings — append them instead of rebuilding the program.
+        issues.push(...options.precomputedCheckJs);
+    }
+    else if (config.patchLint?.checkJs) {
+        issues.push(...(await invokePatchLintCheckJs(repoDir, patchOwnedFiles, config.patchLint, dirname(repoDir), options?.checkJsReportScope)));
     }
     // Filter out ignored checks last so every rule still runs (keeps the
     // implementation uniform) but suppressed rules do not surface. We do not

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

@@ -44,9 +44,12 @@ export declare function detectHarnessCrashSignature(output: string): HarnessCras
  * 1. A recognized crash signature wins regardless of exit code (the
  *    shutdown re-entry shape exits non-zero on an otherwise green run;
  *    the hang shape can even exit zero with a `Passed: 0` summary).
- * 2. No `TEST-START` with explicit paths requested means no test ran —
- *    `no-tests`, even when the exit code is zero. Summary lines are not
- *    trusted as evidence of execution.
+ * 2. No execution signal with explicit paths requested means no test ran —
+ *    `no-tests`, even when the exit code is zero. The execution signal is
+ *    a `TEST-START` line (generic `mach test` / browser-chrome dispatch)
+ *    OR the suite-specific xpcshell result-summary block (the xpcshell
+ *    dispatch prints no `TEST-START`). Bare `Passed:`/`Failed:` summary
+ *    lines are still not trusted as evidence of execution.
  * 3. Exit code zero with tests started is a pass; anything else is a
  *    test failure for the regular diagnosis chain.
  */

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

@@ -23,6 +23,20 @@
  * of reporting phantom test failures (or phantom passes).
  */
 const TEST_START_PATTERN = /\bTEST-START\b/;
+/**
+ * Execution signals emitted by the suite-specific xpcshell dispatch
+ * (`mach xpcshell-test`), which does NOT print `TEST-START` lines the way
+ * the generic `mach test` / browser-chrome dispatch does. A passing
+ * single-file xpcshell run prints a result-summary block instead
+ * (`TEST_END: Test PASS`, `Ran 16 checks`, `Unexpected results: 0`), so
+ * keying execution purely on `TEST-START` mis-reads a green xpcshell run as
+ * "no tests started" (field report: a single-file xpcshell pass exited 1).
+ *
+ * These markers are xpcshell-specific on purpose: the bare
+ * `Passed: 0` / `Failed: 0` summary that the no-output hang shape prints is
+ * deliberately NOT matched here — that case must still read as `no-tests`.
+ */
+const XPCSHELL_RESULT_SUMMARY_PATTERN = /\bTEST_END\b|\bRan \d+ checks?\b|\bResult summary:/i;
 const UNEXPECTED_LINE_PATTERN = /^.*\bTEST-UNEXPECTED-[A-Z-]+\b.*$/gm;
 const SHUTDOWN_REENTRY_PATTERN = /Application shut down \(without crashing\) in the middle of a test/i;
 const FOCUS_STALL_PATTERN = /must wait for focus/i;
@@ -49,6 +63,16 @@ function findLine(output, patterns) {
     }
     return undefined;
 }
+/**
+ * True when the captured output carries the suite-specific xpcshell
+ * result-summary block, which proves tests executed even though the
+ * xpcshell dispatch emits no `TEST-START` line. Used alongside
+ * `TEST_START_PATTERN` so a green single-file xpcshell run is not
+ * mis-classified as `no-tests`. Exported for direct unit testing.
+ */
+function hasXpcshellResultSummary(output) {
+    return XPCSHELL_RESULT_SUMMARY_PATTERN.test(output);
+}
 /** Unexpected-failure lines that are NOT the shutdown re-entry artifact. */
 function realUnexpectedFailureLines(output) {
     const matches = output.match(UNEXPECTED_LINE_PATTERN) ?? [];
@@ -95,9 +119,12 @@ export function detectHarnessCrashSignature(output) {
  * 1. A recognized crash signature wins regardless of exit code (the
  *    shutdown re-entry shape exits non-zero on an otherwise green run;
  *    the hang shape can even exit zero with a `Passed: 0` summary).
- * 2. No `TEST-START` with explicit paths requested means no test ran —
- *    `no-tests`, even when the exit code is zero. Summary lines are not
- *    trusted as evidence of execution.
+ * 2. No execution signal with explicit paths requested means no test ran —
+ *    `no-tests`, even when the exit code is zero. The execution signal is
+ *    a `TEST-START` line (generic `mach test` / browser-chrome dispatch)
+ *    OR the suite-specific xpcshell result-summary block (the xpcshell
+ *    dispatch prints no `TEST-START`). Bare `Passed:`/`Failed:` summary
+ *    lines are still not trusted as evidence of execution.
  * 3. Exit code zero with tests started is a pass; anything else is a
  *    test failure for the regular diagnosis chain.
  */
@@ -106,7 +133,8 @@ export function classifyHarnessRun(exitCode, output, requestedPaths) {
     if (signature) {
         return { kind: 'harness-crash', signature };
     }
-    if (!TEST_START_PATTERN.test(output) && requestedPaths.length > 0) {
+    const ranTests = TEST_START_PATTERN.test(output) || hasXpcshellResultSummary(output);
+    if (!ranTests && requestedPaths.length > 0) {
         return { kind: 'no-tests' };
     }
     return exitCode === 0 ? { kind: 'tests-ran-ok' } : { kind: 'test-failures' };

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

@@ -3,5 +3,12 @@ export interface XpcshellRetryClassification {
     xpcshell: readonly string[];
     nonXpcshell: readonly string[];
 }
-/** Removes a stale xpcshell install symlink and retries the focused mach test once. */
-export declare function retryAfterXpcshellSymlinkRepair(engineDir: string, objDir: string | undefined, result: MachCommandResult, classification: XpcshellRetryClassification, normalizedPaths: string[], extraArgs: string[], env?: Record<string, string>): Promise<MachCommandResult>;
+/** 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>;
+/**
+ * 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>;

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

@@ -1,16 +1,21 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { testWithOutput } from './mach.js';
 import { tryRepairStaleXpcshellTestSymlink } from './test-stale-symlink.js';
-/** Removes a stale xpcshell install symlink and retries the focused mach test once. */
-export async function retryAfterXpcshellSymlinkRepair(engineDir, objDir, result, classification, normalizedPaths, extraArgs, env) {
+/**
+ * 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 async function retryAfterXpcshellSymlinkRepair(engineDir, objDir, result, classification, normalizedPaths, extraArgs, env, dispatch = testWithOutput) {
     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) {
             return env
-                ? testWithOutput(engineDir, normalizedPaths, extraArgs, env)
-                : testWithOutput(engineDir, normalizedPaths, extraArgs);
+                ? dispatch(engineDir, normalizedPaths, extraArgs, env)
+                : dispatch(engineDir, normalizedPaths, extraArgs);
         }
     }
     return result;

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

@@ -38,6 +38,15 @@ export declare function stripBlockCommentsInLines(lines: string[]): string[];
  * can splice into the original `lines` array at the returned index.
  */
 export declare function findDarkRootInsertionIndex(lines: string[]): number | null;
+/**
+ * Depth-counts braces from `startLine` (whose lines must already have
+ * block comments stripped), returning the index of the line on which the
+ * block opened there returns to its entry depth — i.e. the line carrying
+ * the block's closing `}` — or -1 when the block never closes. The first
+ * `{` encountered sets the entry depth, so the scan may start on the
+ * selector/at-rule line itself rather than on the opener.
+ */
+export declare function findBlockCloseIndex(stripped: string[], startLine: number): number;
 /**
  * Finds the closing `}` of the outermost
  * `@media (prefers-color-scheme: dark)` block. Used as the fallback

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

@@ -122,7 +122,7 @@ export function findDarkRootInsertionIndex(lines) {
  * `{` encountered sets the entry depth, so the scan may start on the
  * selector/at-rule line itself rather than on the opener.
  */
-function findBlockCloseIndex(stripped, startLine) {
+export function findBlockCloseIndex(stripped, startLine) {
     let depth = 0;
     let entryDepth = 0;
     let enteredBlock = false;

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

@@ -0,0 +1,32 @@
+/**
+ * Documentation-table updates for `fireforge token add`. Extracted from
+ * `token-manager.ts` so the CSS-mutation path and the Markdown-table path
+ * each stay within the per-file line budget. Consumed only by token-manager.
+ */
+/**
+ * Minimal token shape the docs updater needs. Declared locally (rather than
+ * importing `AddTokenOptions`) so this module has no edge back to
+ * `token-manager.ts` — `AddTokenOptions` is structurally compatible.
+ */
+export interface TokenDocInput {
+    tokenName: string;
+    value: string;
+    category: string;
+    mode: string;
+    description?: string | undefined;
+}
+/**
+ * Adds a token row to the main token table, the unmapped table (for
+ * literal values), and bumps the mode count table. Each sub-update runs
+ * against a freshly parsed view of the document so that splice indices
+ * stay valid as rewrites are layered.
+ *
+ * @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`).
+ */
+export declare function addTokenToDocs(engineDir: string, options: TokenDocInput, annotation: string): Promise<{
+    docsAdded: boolean;
+    unmappedAdded: boolean;
+    countUpdated: boolean;
+}>;

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

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Documentation-table updates for `fireforge token add`. Extracted from
+ * `token-manager.ts` so the CSS-mutation path and the Markdown-table path
+ * each stay within the per-file line budget. Consumed only by token-manager.
+ */
+import { join } from 'node:path';
+import { pathExists, readText, writeText } from '../utils/fs.js';
+import { findTableAfterHeading, findTableByColumns, insertRow, rewriteTableRows, updateCellByKey, } from './markdown-table.js';
+const TOKENS_DOC = 'docs/design/SRC_TOKENS.md';
+/**
+ * Strips surrounding backticks from a cell, if present. Token cells are
+ * usually wrapped in inline code fences (`` `--foo` ``) and the parser
+ * returns them verbatim.
+ */
+function stripInlineCode(cell) {
+    const trimmed = cell.trim();
+    if (trimmed.startsWith('`') && trimmed.endsWith('`') && trimmed.length >= 2) {
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+/**
+ * Adds a token row to the main token table, the unmapped table (for
+ * literal values), and bumps the mode count table. Each sub-update runs
+ * against a freshly parsed view of the document so that splice indices
+ * stay valid as rewrites are layered.
+ *
+ * @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`).
+ */
+export async function addTokenToDocs(engineDir, options, annotation) {
+    const filePath = join(engineDir, '..', TOKENS_DOC);
+    if (!(await pathExists(filePath))) {
+        // Docs file is optional
+        return { docsAdded: false, unmappedAdded: false, countUpdated: false };
+    }
+    const originalContent = await readText(filePath);
+    let lines = originalContent.split('\n');
+    let docsAdded = false;
+    let unmappedAdded = false;
+    let countUpdated = false;
+    const isLiteral = !options.value.startsWith('var(');
+    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 ---
+    const mainTable = findTableByColumns(lines, ['Category', 'Token', 'Value', 'Mode']);
+    if (mainTable) {
+        // The doc convention allows the Category cell to be blank on
+        // continuation rows that belong to the previous category. Group rows
+        // by carrying the last non-empty Category value forward.
+        let lastGroupRowIndex = -1;
+        let currentCategory = '';
+        for (let i = 0; i < mainTable.rows.length; i++) {
+            const row = mainTable.rows[i];
+            if (!row)
+                continue;
+            const cell = row[0]?.trim() ?? '';
+            if (cell) {
+                currentCategory = cell;
+            }
+            if (currentCategory === options.category) {
+                lastGroupRowIndex = i;
+            }
+        }
+        if (lastGroupRowIndex !== -1) {
+            insertRow(mainTable, ['', tokenCell, valueCell, mapsTo, annotation], lastGroupRowIndex + 1);
+            lines = rewriteTableRows(lines, mainTable);
+            docsAdded = true;
+        }
+    }
+    // --- Unmapped table: populated for literal (non-var()) values only ---
+    if (isLiteral) {
+        const unmappedTable = findTableAfterHeading(lines, /not yet mapped|unmapped/i);
+        if (unmappedTable) {
+            insertRow(unmappedTable, [tokenCell, valueCell, options.description ?? ''], unmappedTable.rows.length);
+            lines = rewriteTableRows(lines, unmappedTable);
+            unmappedAdded = true;
+        }
+    }
+    // --- Mode behavior count table: Mode | Count ---
+    const modeTable = findTableByColumns(lines, ['Mode', 'Count']);
+    if (modeTable) {
+        const modeIndex = modeTable.headers.indexOf('Mode');
+        const countIndex = modeTable.headers.indexOf('Count');
+        const existing = modeTable.rows.find((row) => stripInlineCode(row[modeIndex] ?? '') === options.mode);
+        if (existing) {
+            const oldCount = parseInt(existing[countIndex] ?? '0', 10);
+            const updated = updateCellByKey(modeTable, 'Mode', existing[modeIndex] ?? options.mode, 'Count', String((Number.isNaN(oldCount) ? 0 : oldCount) + 1));
+            if (updated) {
+                lines = rewriteTableRows(lines, modeTable);
+                countUpdated = true;
+            }
+        }
+    }
+    await writeText(filePath, lines.join('\n'));
+    return { docsAdded, unmappedAdded, countUpdated };
+}
+//# sourceMappingURL=token-docs.js.map

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

@@ -22,6 +22,14 @@ export interface AddTokenOptions {
     dryRun?: boolean | undefined;
     /** Declare the category banner in the tokens CSS when it does not exist yet. */
     createCategory?: boolean | undefined;
+    /**
+     * Attribute selector fragment (e.g. `[data-skin="precision"]` or
+     * `[data-private]`) that routes the declaration into a top-level
+     * `:root<variant>` block instead of the base `:root` / category section.
+     * The block is created if absent and appended to if present. Variant
+     * overrides are CSS-only — the base token already owns its docs row.
+     */
+    variant?: string | undefined;
 }
 /**
  * Result of adding a token.