@hominis/fireforge 0.32.0 → 0.33.0

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

@@ -3,6 +3,6 @@
  * Public re-exports for {@link ./patch-lint.ts}. Split out so the
  * orchestrator stays within the ESLint `max-lines` budget.
  */
-export { buildPatchQueueContext, collectNewFileCreatorsByPath, extractImportSpecifiers, extractImportSpecifiersWithLines, findForwardImportIgnoreLines, FORWARD_IMPORT_IGNORE_MARKER, isForwardImportableFile, lintPatchQueue, lintPatchQueueDuplicateCreations, lintPatchQueueForwardImports, } from './patch-lint-cross.js';
+export { buildPatchQueueContext, collectForwardImportEdges, collectNewFileCreatorsByPath, extractImportSpecifiers, extractImportSpecifiersWithLines, findForwardImportIgnoreLines, FORWARD_IMPORT_IGNORE_MARKER, isForwardImportableFile, lintPatchQueue, lintPatchQueueDuplicateCreations, lintPatchQueueForwardImports, } from './patch-lint-cross.js';
 export { buildModifiedFileAdditionsFromDiff, detectNewFilesInDiff } from './patch-lint-diff.js';
 //# sourceMappingURL=patch-lint-reexports.js.map

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/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.

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

@@ -9,13 +9,13 @@ import { escapeRegex } from '../utils/regex.js';
 import { validateTokenName } from '../utils/validation.js';
 import { getProjectPaths, loadConfig } from './config.js';
 import { loadFurnaceConfig } from './furnace-config.js';
-import { findTableAfterHeading, findTableByColumns, insertRow, rewriteTableRows, updateCellByKey, } from './markdown-table.js';
 import { findDarkMediaCloseIndex, findDarkRootInsertionIndex } from './token-dark-mode.js';
+import { addTokenToDocs } from './token-docs.js';
+import { insertVariantDeclaration, validateVariantSelector, variantBlockHasToken, } from './token-variant.js';
 /** Returns the token CSS path relative to engine root for a given binary name. */
 export function getTokensCssPath(binaryName) {
     return `browser/themes/shared/${binaryName}-tokens.css`;
 }
-const TOKENS_DOC = 'docs/design/SRC_TOKENS.md';
 /**
  * Determines the mode annotation string for the CSS comment.
  */
@@ -69,6 +69,49 @@ function validateDarkValue(options) {
         throw new InvalidArgumentError('Override mode requires --dark-value to be specified.', 'darkValue');
     }
 }
+/**
+ * Validates and normalizes the `--variant` attribute selector. Returns the
+ * normalized (quoted) selector when set, or `undefined` when no variant was
+ * requested. Rejects combining `--variant` with `--mode override`: an
+ * override authors a dark `@media :root` block, which variant routing
+ * bypasses, so the combination would silently drop the dark value.
+ */
+function normalizeVariantOption(options) {
+    if (options.variant === undefined)
+        return undefined;
+    if (options.mode === 'override') {
+        throw new InvalidArgumentError('Cannot combine --variant with --mode override; author the variant declaration with ' +
+            '--mode auto/static instead.', 'variant');
+    }
+    const result = validateVariantSelector(options.variant);
+    if (!result.ok) {
+        throw new InvalidArgumentError(`--variant ${result.reason}.`, 'variant');
+    }
+    return result.value;
+}
+/** Throws when the tokens CSS file is missing (variant mode skips category checks). */
+async function assertTokensCssExists(engineDir, tokensCssPath) {
+    if (!(await pathExists(join(engineDir, tokensCssPath)))) {
+        throw new GeneralError(`Token CSS file not found: ${tokensCssPath}`);
+    }
+}
+/**
+ * Routes a declaration into the top-level `:root<variant>` block — creating
+ * the block after the base `:root` block if absent, or appending to it if
+ * present. Idempotent within the block. Returns `{ added: false }` when the
+ * token already lives in that block.
+ */
+async function addVariantTokenToCSS(engineDir, options, tokensCssPath, variant) {
+    await assertTokensCssExists(engineDir, tokensCssPath);
+    const filePath = join(engineDir, tokensCssPath);
+    const lines = (await readText(filePath)).split('\n');
+    if (variantBlockHasToken(lines, variant, options.tokenName))
+        return { added: false };
+    const annotation = getModeAnnotation(options.mode, options.value);
+    insertVariantDeclaration(lines, variant, `  ${options.tokenName}: ${options.value}; /* ${annotation} */`);
+    await writeText(filePath, lines.join('\n'));
+    return { added: true };
+}
 /**
  * True when `lines` contain a category header (single-line or multi-line
  * banner shape) naming `category`. Shared by the pre-add assertion and the
@@ -171,6 +214,12 @@ export async function validateTokenAdd(root, options) {
     validateTokenNameSyntax(options.tokenName);
     await validateTokenPrefix(root, options);
     validateDarkValue(options);
+    // Variant mode targets a `:root<attr>` block, not a category section, so it
+    // only needs the tokens CSS file to exist — category checks do not apply.
+    if (normalizeVariantOption(options) !== undefined) {
+        await assertTokensCssExists(engineDir, tokensCssPath);
+        return;
+    }
     await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, options.createCategory === true);
 }
 /**
@@ -185,10 +234,21 @@ export async function addToken(root, options) {
     validateTokenNameSyntax(options.tokenName);
     await validateTokenPrefix(root, options);
     validateDarkValue(options);
+    const normalizedVariant = normalizeVariantOption(options);
     if (options.dryRun) {
         await validateTokenAdd(root, options);
         const filePath = join(engineDir, tokensCssPath);
         const content = await readText(filePath);
+        if (normalizedVariant !== undefined) {
+            const skipped = variantBlockHasToken(content.split('\n'), normalizedVariant, options.tokenName);
+            return {
+                cssAdded: !skipped,
+                docsAdded: false,
+                unmappedAdded: false,
+                countUpdated: false,
+                skipped,
+            };
+        }
         const stripped = content.replace(/\/\*[\s\S]*?\*\//g, '');
         const skipped = stripped.includes(options.tokenName + ':');
         return {
@@ -199,6 +259,20 @@ export async function addToken(root, options) {
             skipped,
         };
     }
+    // Variant overrides are CSS-only: route the declaration into the
+    // `:root<attr>` block and leave docs untouched (the base token owns its
+    // docs row). Done before the base-CSS path so an override of an existing
+    // base token is not short-circuited by the global idempotency check.
+    if (normalizedVariant !== undefined) {
+        const { added } = await addVariantTokenToCSS(engineDir, options, tokensCssPath, normalizedVariant);
+        return {
+            cssAdded: added,
+            docsAdded: false,
+            unmappedAdded: false,
+            countUpdated: false,
+            skipped: !added,
+        };
+    }
     // --- CSS file ---
     const { added: cssAdded, categoryCreated } = await addTokenToCSS(engineDir, options, tokensCssPath);
     if (!cssAdded) {
@@ -211,7 +285,7 @@ export async function addToken(root, options) {
         };
     }
     // --- Documentation ---
-    const docsResult = await addTokenToDocs(engineDir, options);
+    const docsResult = await addTokenToDocs(engineDir, options, getModeAnnotation(options.mode, options.value));
     return {
         cssAdded,
         docsAdded: docsResult.docsAdded,
@@ -381,96 +455,4 @@ async function addTokenToCSS(engineDir, options, tokensCssPath) {
     await writeText(filePath, content);
     return { added: true, categoryCreated };
 }
-/**
- * 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.
- *
- * The old implementation walked `split('\n')` by hand, detected rows by
- * literal `|`-prefix, and used a whitespace-sensitive regex to increment
- * the mode count. Switching to {@link findTableByColumns} and
- * {@link updateCellByKey} removes those formatting traps.
- */
-async function addTokenToDocs(engineDir, options) {
-    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 annotation = getModeAnnotation(options.mode, options.value);
-    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-manager.js.map

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

@@ -0,0 +1,39 @@
+/**
+ * Attribute-variant block helpers for the tokens CSS scaffold.
+ *
+ * `fireforge token add --mode` can author the base `:root { }` block and the
+ * dark `@media (prefers-color-scheme: dark)` block, but there was no way to
+ * target an attribute-keyed selector such as `:root[data-skin="precision"]`
+ * or `:root[data-private]` — forcing those override blocks to be hand-edited.
+ * These helpers locate (or compute the insertion point for) a top-level
+ * `:root<variant>` block so `token-manager.ts` can splice a declaration into
+ * it, keeping all token authoring in the CLI.
+ */
+/**
+ * Outcome of {@link validateVariantSelector}. `ok: true` carries the
+ * normalized (quoted) selector fragment; `ok: false` carries a
+ * human-readable reason suitable for throwing as an `InvalidArgumentError`.
+ */
+export type VariantValidation = {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Validates a `--variant` attribute selector fragment and normalizes any
+ * `=value` form to the double-quoted `="value"` shape (Mozilla convention).
+ * Boolean-attribute fragments are returned unchanged.
+ *
+ * @param raw - Raw `--variant` value from the CLI / programmatic caller.
+ */
+export declare function validateVariantSelector(raw: unknown): VariantValidation;
+/** True when the `:root<variant>` block already declares `tokenName`. */
+export declare function variantBlockHasToken(lines: string[], variant: string, tokenName: string): boolean;
+/**
+ * Splices `declLine` into the `:root<variant>` block, creating the block
+ * (after the base `:root` block) when absent or appending after the last
+ * non-blank line when present. Mutates `lines` in place.
+ */
+export declare function insertVariantDeclaration(lines: string[], variant: string, declLine: string): void;