@hominis/fireforge 0.38.0 → 0.40.0

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

@@ -0,0 +1,264 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Category banner and token-declaration helpers for the tokens CSS file
+ * (FORGE G3). 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.
+ */
+import { join } from 'node:path';
+import { GeneralError } from '../errors/base.js';
+import { pathExists, readText } from '../utils/fs.js';
+import { escapeRegex } from '../utils/regex.js';
+function singleLineBannerPattern(category) {
+    return new RegExp(`\\/\\*\\s*=+\\s*${escapeRegex(category)}\\s*=+\\s*\\*\\/`);
+}
+function multiLineBlockNameMatches(blockLine, category) {
+    return blockLine.replace(/^\s*\*\s*/, '').trim() === category;
+}
+/**
+ * True when `lines` contain a category header (single-line or multi-line
+ * banner shape) whose name EQUALS `category`. Shared by the pre-add
+ * assertion, the banner creation path, and the section finder so all
+ * agree on what "exists" means.
+ */
+export function categoryHeaderExists(lines, category) {
+    const singleLinePattern = singleLineBannerPattern(category);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (singleLinePattern.test(line)) {
+            return true;
+        }
+        if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
+            for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
+                const blockLine = lines[j] ?? '';
+                if (multiLineBlockNameMatches(blockLine, category)) {
+                    return true;
+                }
+                if (/\*\//.test(blockLine))
+                    break;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Scans a tokens CSS file for category header comments and returns the
+ * category names in document order. Used to enrich the "category not
+ * found" error body with concrete alternatives the operator can copy.
+ *
+ * Mirrors the shapes `findCategorySection` recognises:
+ * - Single-line: `/* = Foo = *\/`
+ * - Multi-line: `/* =====` opening, `Foo` on any of the next ~5 lines,
+ *   closing `*\/`.
+ *
+ * This helper exists as a pure inspector; it never throws on malformed
+ * headers and silently skips shapes it cannot parse.
+ */
+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);
+            continue;
+        }
+        if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
+            for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
+                const blockLine = lines[j] ?? '';
+                if (/\*\//.test(blockLine))
+                    break;
+                const trimmed = blockLine.replace(/^\s*\*\s*/, '').trim();
+                if (trimmed.length === 0)
+                    continue;
+                if (/^=+$/.test(trimmed))
+                    continue;
+                categories.add(trimmed);
+                break;
+            }
+        }
+    }
+    return [...categories];
+}
+/**
+ * Asserts the category banner exists (or that creation was requested).
+ * Throws a GeneralError naming the available categories and the
+ * `--create-category` remedy otherwise.
+ */
+export async function assertTokenCategoryExists(engineDir, tokensCssPath, category, createCategory = false) {
+    const filePath = join(engineDir, tokensCssPath);
+    if (!(await pathExists(filePath))) {
+        throw new GeneralError(`Token CSS file not found: ${tokensCssPath}`);
+    }
+    const content = await readText(filePath);
+    const lines = content.split('\n');
+    if (categoryHeaderExists(lines, category))
+        return;
+    // The write path declares the banner in the same edit as the token
+    // insertion, so a missing category is fine when creation was requested.
+    if (createCategory)
+        return;
+    const discoveredCategories = discoverCategoryHeaders(lines);
+    const available = discoveredCategories.length > 0
+        ? `Available categories in the file: ${discoveredCategories.map((name) => `"${name}"`).join(', ')}.`
+        : 'The file currently has no category headers.';
+    throw new GeneralError(`Category "${category}" not found in ${tokensCssPath}.\n\n` +
+        `${available}\n\n` +
+        'Categories are declared by comment headers. Single-line shape: /* = My Category = */. ' +
+        'Multi-line shape: /* =============\\n * My Category\\n * ============= */.\n\n' +
+        'Re-run with --create-category to declare the banner and insert the token in one step.');
+}
+/**
+ * Splices a new single-line category banner ("= Name =" comment shape, the
+ * same format `discoverCategoryHeaders` recognises) just before the closing
+ * brace of the `:root` block, making the new category the last section.
+ * Mutates `lines` in place.
+ */
+export function declareCategoryBanner(lines, category, tokensCssPath) {
+    const bounds = findBaseRootBounds(lines);
+    if (bounds === null) {
+        throw new GeneralError(`Cannot create category "${category}": no :root block found in ${tokensCssPath}. ` +
+            'Run "fireforge furnace init --force" to re-scaffold the tokens CSS file.');
+    }
+    if (bounds.close === -1) {
+        throw new GeneralError(`Cannot create category "${category}": the :root block in ${tokensCssPath} never closes.`);
+    }
+    lines.splice(bounds.close, 0, '', `  /* = ${category} = */`);
+}
+/** Locates and bounds the named category section. Throws when absent. */
+export function findCategorySection(lines, category, tokensCssPath) {
+    const singleLinePattern = singleLineBannerPattern(category);
+    let categoryLine = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        // Check single-line format: /* = Category = */
+        if (singleLinePattern.test(line)) {
+            categoryLine = i;
+            break;
+        }
+        // Check multi-line format: line opens a block comment with === but does NOT close it
+        if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
+            for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
+                const blockLine = lines[j] ?? '';
+                if (multiLineBlockNameMatches(blockLine, category)) {
+                    categoryLine = i;
+                    break;
+                }
+                if (/\*\//.test(blockLine))
+                    break;
+            }
+            if (categoryLine !== -1)
+                break;
+        }
+    }
+    if (categoryLine === -1) {
+        const discoveredCategories = discoverCategoryHeaders(lines);
+        const available = discoveredCategories.length > 0
+            ? `Available categories in the file: ${discoveredCategories.map((name) => `"${name}"`).join(', ')}.`
+            : 'The file currently has no category headers.';
+        throw new GeneralError(`Category "${category}" not found in ${tokensCssPath}.\n\n` +
+            `${available}\n\n` +
+            'Add a header by hand inside the :root block (format: "/* = My Category = */") or re-run "fireforge furnace init --force" to re-seed the default categories.');
+    }
+    // Find the end of this category section (next section header or closing })
+    // Skip past the current header block first
+    let scanStart = categoryLine + 1;
+    for (let i = categoryLine + 1; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (/^\s*\/\*\s*=/.test(line) || /^\s*\*\s*=/.test(line) || /^\s*\*\//.test(line)) {
+            scanStart = i + 1;
+            continue;
+        }
+        break;
+    }
+    let sectionEnd = lines.length;
+    for (let i = scanStart; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (/\/\*\s*=.*=\s*\*\//.test(line) ||
+            (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) ||
+            /^\s*\}/.test(line)) {
+            sectionEnd = i;
+            break;
+        }
+    }
+    return { categoryLine, sectionEnd };
+}
+/** 0-based open/close line indices of the base `:root {` block. */
+function findBaseRootBounds(lines) {
+    let open = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (/:root\s*\{/.test(lines[i] ?? '')) {
+            open = i;
+            break;
+        }
+    }
+    if (open === -1)
+        return null;
+    for (let i = open + 1; i < lines.length; i++) {
+        if (/^\s*\}/.test(lines[i] ?? '')) {
+            return { open, close: i };
+        }
+    }
+    return { open, close: -1 };
+}
+/** Masks block-comment content per line so declarations inside comments never match. */
+function maskCommentLines(lines) {
+    const masked = lines.join('\n').replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '));
+    return masked.split('\n');
+}
+/**
+ * Finds an existing declaration of `tokenName` inside the base `:root`
+ * block. Dark `@media` and `:root[variant]` companion blocks are
+ * deliberately excluded — they mirror the base declaration, they do not
+ * own the token. Comment content never matches, and the name match is
+ * exact (`--foo-bar` does not match `--x-foo-bar`).
+ */
+export function findTokenDeclarationInRoot(lines, tokenName) {
+    const bounds = findBaseRootBounds(lines);
+    if (bounds === null || bounds.close === -1)
+        return undefined;
+    const masked = maskCommentLines(lines);
+    const declPattern = new RegExp(`^\\s*${escapeRegex(tokenName)}\\s*:`);
+    for (let i = bounds.open + 1; i < bounds.close; i++) {
+        if (!declPattern.test(masked[i] ?? ''))
+            continue;
+        const category = findSectionNameAbove(lines, i);
+        return category === undefined ? { line: i + 1 } : { line: i + 1, category };
+    }
+    return undefined;
+}
+/** Nearest category banner name above `lineIndex`, if any. */
+function findSectionNameAbove(lines, lineIndex) {
+    const singleLinePattern = /\/\*\s*=+\s*(.+?)\s*=+\s*\*\//;
+    for (let i = lineIndex - 1; i >= 0; i--) {
+        const line = lines[i] ?? '';
+        const singleMatch = singleLinePattern.exec(line);
+        if (singleMatch?.[1]) {
+            const extracted = singleMatch[1].trim();
+            if (extracted.length > 0 && !/^=+$/.test(extracted))
+                return extracted;
+            continue;
+        }
+        if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
+            for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
+                const blockLine = lines[j] ?? '';
+                if (/\*\//.test(blockLine))
+                    break;
+                const trimmed = blockLine.replace(/^\s*\*\s*/, '').trim();
+                if (trimmed.length === 0 || /^=+$/.test(trimmed))
+                    continue;
+                return trimmed;
+            }
+        }
+    }
+    return undefined;
+}

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

@@ -1,3 +1,4 @@
+import { type TokenDeclarationLocation } from './token-category.js';
 /**
  * Dark mode behavior for a token.
  */
@@ -47,6 +48,12 @@ export interface AddTokenResult {
     skipped: boolean;
     /** Whether a new category banner was declared by this add. */
     categoryCreated?: boolean;
+    /**
+     * When the add skipped because the token already lives in the TARGET
+     * category, names where the existing base-`:root` declaration sits so
+     * the skip message can point at it (FORGE G3).
+     */
+    skippedExisting?: TokenDeclarationLocation;
 }
 /** Returns the token CSS path relative to engine root for a given binary name. */
 export declare function getTokensCssPath(binaryName: string): string;

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

@@ -4,14 +4,14 @@ import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
-import { warn } from '../utils/logger.js';
-import { escapeRegex } from '../utils/regex.js';
+import { info, warn } from '../utils/logger.js';
 import { validateTokenName } from '../utils/validation.js';
 import { getProjectPaths, loadConfig } from './config.js';
 import { loadFurnaceConfig } from './furnace-config.js';
+import { assertTokenCategoryExists, categoryHeaderExists, declareCategoryBanner, findCategorySection, findTokenDeclarationInRoot, } from './token-category.js';
 import { findDarkMediaCloseIndex, findDarkRootInsertionIndex } from './token-dark-mode.js';
 import { addTokenToDocs } from './token-docs.js';
-import { insertVariantDeclaration, validateVariantSelector, variantBlockHasToken, } from './token-variant.js';
+import { insertVariantDeclaration, validateVariantSelector, variantBlockExists, 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`;
@@ -83,6 +83,10 @@ function normalizeVariantOption(options) {
         throw new InvalidArgumentError('Cannot combine --variant with --mode override; author the variant declaration with ' +
             '--mode auto/static instead.', 'variant');
     }
+    if (options.createCategory === true) {
+        throw new InvalidArgumentError('--create-category cannot be combined with --variant; variant declarations are routed ' +
+            'into a :root<selector> block, not a category section.', 'variant');
+    }
     const result = validateVariantSelector(options.variant);
     if (!result.ok) {
         throw new InvalidArgumentError(`--variant ${result.reason}.`, 'variant');
@@ -113,95 +117,26 @@ async function addVariantTokenToCSS(engineDir, options, tokensCssPath, variant)
     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
- * in-memory banner creation path so both agree on what "exists" means.
+ * Evaluates base-`:root` idempotency for one add (FORGE G3): a token
+ * already declared in the TARGET category skips; a token declared
+ * anywhere else in the base block refuses loud — the pre-0.40.0
+ * whole-file substring check silently skipped (and discarded
+ * `--create-category`) in that case, exit 0.
  */
-function categoryHeaderExists(lines, category) {
-    const escapedCategory = escapeRegex(category);
-    const singleLinePattern = new RegExp(`\\/\\*\\s*=.*${escapedCategory}.*=\\s*\\*\\/`);
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        if (singleLinePattern.test(line)) {
-            return true;
-        }
-        if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
-            for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
-                const blockLine = lines[j] ?? '';
-                if (new RegExp(escapedCategory).test(blockLine)) {
-                    return true;
-                }
-                if (/\*\//.test(blockLine))
-                    break;
-            }
-        }
+function evaluateBaseTokenIdempotency(lines, options, tokensCssPath) {
+    const existing = findTokenDeclarationInRoot(lines, options.tokenName);
+    if (!existing)
+        return { skipped: false };
+    if (existing.category === options.category) {
+        return { skipped: true, existing };
     }
-    return false;
-}
-async function assertTokenCategoryExists(engineDir, tokensCssPath, category, createCategory = false) {
-    const filePath = join(engineDir, tokensCssPath);
-    if (!(await pathExists(filePath))) {
-        throw new GeneralError(`Token CSS file not found: ${tokensCssPath}`);
-    }
-    const content = await readText(filePath);
-    const lines = content.split('\n');
-    if (categoryHeaderExists(lines, category))
-        return;
-    // The write path declares the banner in the same edit as the token
-    // insertion, so a missing category is fine when creation was requested.
-    if (createCategory)
-        return;
-    const discoveredCategories = discoverCategoryHeaders(lines);
-    const available = discoveredCategories.length > 0
-        ? `Available categories in the file: ${discoveredCategories.map((name) => `"${name}"`).join(', ')}.`
-        : 'The file currently has no category headers.';
-    throw new GeneralError(`Category "${category}" not found in ${tokensCssPath}.\n\n` +
-        `${available}\n\n` +
-        'Categories are declared by comment headers. Single-line shape: /* = My Category = */. ' +
-        'Multi-line shape: /* =============\\n * My Category\\n * ============= */.\n\n' +
-        'Re-run with --create-category to declare the banner and insert the token in one step.');
-}
-/**
- * Scans a tokens CSS file for category header comments and returns the
- * category names in document order. Used to enrich the "category not
- * found" error body with concrete alternatives the operator can copy.
- *
- * Mirrors the shapes `findCategorySection` already recognises:
- * - Single-line: `/* = Foo = *\/`
- * - Multi-line: `/* =====` opening, `Foo` on any of the next ~5 lines,
- *   closing `*\/`.
- *
- * This helper exists as a pure inspector; it never throws on malformed
- * headers and silently skips shapes it cannot parse.
- */
-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);
-            continue;
-        }
-        if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
-            for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
-                const blockLine = lines[j] ?? '';
-                if (/\*\//.test(blockLine))
-                    break;
-                const trimmed = blockLine.replace(/^\s*\*\s*/, '').trim();
-                if (trimmed.length === 0)
-                    continue;
-                if (/^=+$/.test(trimmed))
-                    continue;
-                categories.add(trimmed);
-                break;
-            }
-        }
-    }
-    return [...categories];
+    const sectionSuffix = existing.category === undefined ? '' : `, section "${existing.category}"`;
+    const remedy = existing.category === undefined
+        ? 'remove the stray declaration first'
+        : `pass --category "${existing.category}" to target the existing declaration, or remove it first`;
+    throw new GeneralError(`Token "${options.tokenName}" is already declared outside category "${options.category}" ` +
+        `(${tokensCssPath}:${String(existing.line)}${sectionSuffix}). ` +
+        `A token belongs to exactly one category — ${remedy}.`);
 }
 /**
  * Validates token-add inputs without mutating files.
@@ -214,10 +149,11 @@ 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.
+    // Variant mode targets a `:root<attr>` block, not a category section —
+    // but the required --category must still name a REAL category rather
+    // than being silently discarded (FORGE G3 bypass 2).
     if (normalizeVariantOption(options) !== undefined) {
-        await assertTokensCssExists(engineDir, tokensCssPath);
+        await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, false);
         return;
     }
     await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, options.createCategory === true);
@@ -249,14 +185,14 @@ export async function addToken(root, options) {
                 skipped,
             };
         }
-        const stripped = content.replace(/\/\*[\s\S]*?\*\//g, '');
-        const skipped = stripped.includes(options.tokenName + ':');
+        const { skipped, existing } = evaluateBaseTokenIdempotency(content.split('\n'), options, tokensCssPath);
         return {
             cssAdded: !skipped,
             docsAdded: !skipped,
             unmappedAdded: !skipped && !options.value.startsWith('var('),
             countUpdated: !skipped,
             skipped,
+            ...(existing !== undefined ? { skippedExisting: existing } : {}),
         };
     }
     // Variant overrides are CSS-only: route the declaration into the
@@ -264,6 +200,9 @@ export async function addToken(root, options) {
     // 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) {
+        // The required --category must name a real category even though the
+        // declaration routes into the variant block (FORGE G3 bypass 2).
+        await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, false);
         const { added } = await addVariantTokenToCSS(engineDir, options, tokensCssPath, normalizedVariant);
         return {
             cssAdded: added,
@@ -274,7 +213,7 @@ export async function addToken(root, options) {
         };
     }
     // --- CSS file ---
-    const { added: cssAdded, categoryCreated } = await addTokenToCSS(engineDir, options, tokensCssPath);
+    const { added: cssAdded, categoryCreated, existing, } = await addTokenToCSS(engineDir, options, tokensCssPath);
     if (!cssAdded) {
         return {
             cssAdded: false,
@@ -282,6 +221,7 @@ export async function addToken(root, options) {
             unmappedAdded: false,
             countUpdated: false,
             skipped: true,
+            ...(existing !== undefined ? { skippedExisting: existing } : {}),
         };
     }
     // --- Documentation ---
@@ -296,98 +236,37 @@ export async function addToken(root, options) {
     };
 }
 /**
- * Splices a new single-line category banner ("= Name =" comment shape, the
- * same format `discoverCategoryHeaders` recognises) just before the closing
- * brace of the `:root` block, making the new category the last section.
- * Mutates `lines` in place.
+ * Explicit theme-attribute selectors the override path keeps in sync with
+ * the `@media (prefers-color-scheme: dark)` block. Consumer scaffolds that
+ * pair the media query with `:root[data-theme="dark"]` /
+ * `:root[data-theme="light"]` blocks (viewer-toggle theming) require every
+ * themed list to declare identical token sets, so an override add that only
+ * wrote the media block was a guaranteed half-finished edit (FORGE F8).
  */
-function declareCategoryBanner(lines, category, tokensCssPath) {
-    let rootOpen = -1;
-    for (let i = 0; i < lines.length; i++) {
-        if (/:root\s*\{/.test(lines[i] ?? '')) {
-            rootOpen = i;
-            break;
-        }
-    }
-    if (rootOpen === -1) {
-        throw new GeneralError(`Cannot create category "${category}": no :root block found in ${tokensCssPath}. ` +
-            'Run "fireforge furnace init --force" to re-scaffold the tokens CSS file.');
-    }
-    let rootClose = -1;
-    for (let i = rootOpen + 1; i < lines.length; i++) {
-        if (/^\s*\}/.test(lines[i] ?? '')) {
-            rootClose = i;
-            break;
-        }
-    }
-    if (rootClose === -1) {
-        throw new GeneralError(`Cannot create category "${category}": the :root block in ${tokensCssPath} never closes.`);
-    }
-    lines.splice(rootClose, 0, '', `  /* = ${category} = */`);
-}
-function findCategorySection(lines, category, tokensCssPath) {
-    const escapedCategory = escapeRegex(category);
-    const singleLinePattern = new RegExp(`\\/\\*\\s*=.*${escapedCategory}.*=\\s*\\*\\/`);
-    let categoryLine = -1;
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        // Check single-line format: /* = Category = */
-        if (singleLinePattern.test(line)) {
-            categoryLine = i;
-            break;
-        }
-        // Check multi-line format: line opens a block comment with === but does NOT close it
-        // e.g., "/* ================================================================"
-        // (NOT "/* ================================================= */" which closes on the same line)
-        if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
-            // Look ahead within the comment block (up to 5 lines) for the category text
-            for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
-                const blockLine = lines[j] ?? '';
-                if (new RegExp(escapedCategory).test(blockLine)) {
-                    categoryLine = i;
-                    break;
-                }
-                // Stop if we've exited the comment block
-                if (/\*\//.test(blockLine))
-                    break;
-            }
-            if (categoryLine !== -1)
-                break;
-        }
-    }
-    if (categoryLine === -1) {
-        const discoveredCategories = discoverCategoryHeaders(lines);
-        const available = discoveredCategories.length > 0
-            ? `Available categories in the file: ${discoveredCategories.map((name) => `"${name}"`).join(', ')}.`
-            : 'The file currently has no category headers.';
-        throw new GeneralError(`Category "${category}" not found in ${tokensCssPath}.\n\n` +
-            `${available}\n\n` +
-            'Add a header by hand inside the :root block (format: "/* = My Category = */") or re-run "fireforge furnace init --force" to re-seed the default categories.');
-    }
-    // Find the end of this category section (next section header or closing })
-    // Handles both single-line (/* =...= */) and multi-line (/* ===...) section delimiters
-    // Skip past the current header block first
-    let scanStart = categoryLine + 1;
-    for (let i = categoryLine + 1; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        // Skip lines that are part of the current header comment block
-        if (/^\s*\/\*\s*=/.test(line) || /^\s*\*\s*=/.test(line) || /^\s*\*\//.test(line)) {
-            scanStart = i + 1;
+const THEME_ATTRIBUTE_VARIANTS = [
+    { variant: '[data-theme="dark"]', pick: 'dark' },
+    { variant: '[data-theme="light"]', pick: 'light' },
+];
+/**
+ * Mirrors an override's light/dark values into existing top-level
+ * `:root[data-theme="dark"]` / `:root[data-theme="light"]` blocks. Blocks
+ * that do not exist are left alone (scaffolded files have none; behavior is
+ * unchanged there). Idempotent per block. Returns the selectors written.
+ */
+function insertThemeAttributeOverrides(lines, options) {
+    if (options.mode !== 'override' || !options.darkValue)
+        return [];
+    const written = [];
+    for (const { variant, pick } of THEME_ATTRIBUTE_VARIANTS) {
+        if (!variantBlockExists(lines, variant))
             continue;
-        }
-        break;
-    }
-    let sectionEnd = lines.length;
-    for (let i = scanStart; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        if (/\/\*\s*=.*=\s*\*\//.test(line) ||
-            (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) ||
-            /^\s*\}/.test(line)) {
-            sectionEnd = i;
-            break;
-        }
+        if (variantBlockHasToken(lines, variant, options.tokenName))
+            continue;
+        const value = pick === 'dark' ? options.darkValue : options.value;
+        insertVariantDeclaration(lines, variant, `  ${options.tokenName}: ${value};`);
+        written.push(`:root${variant}`);
     }
-    return { categoryLine, sectionEnd };
+    return written;
 }
 function insertDarkModeOverride(lines, options) {
     if (options.mode !== 'override' || !options.darkValue)
@@ -417,13 +296,20 @@ function insertDarkModeOverride(lines, options) {
 async function addTokenToCSS(engineDir, options, tokensCssPath) {
     const filePath = join(engineDir, tokensCssPath);
     await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, options.createCategory === true);
-    let content = await readText(filePath);
-    // Idempotency check — strip CSS block comments so we don't match inside them
-    const stripped = content.replace(/\/\*[\s\S]*?\*\//g, '');
-    if (stripped.includes(options.tokenName + ':')) {
-        return { added: false, categoryCreated: false };
-    }
+    const content = await readText(filePath);
     const lines = content.split('\n');
+    // Per-category idempotency (FORGE G3): a declaration in the TARGET
+    // category skips; a declaration elsewhere in the base :root block
+    // throws instead of silently skipping (and silently discarding
+    // --create-category).
+    const idempotency = evaluateBaseTokenIdempotency(lines, options, tokensCssPath);
+    if (idempotency.skipped) {
+        return {
+            added: false,
+            categoryCreated: false,
+            ...(idempotency.existing !== undefined ? { existing: idempotency.existing } : {}),
+        };
+    }
     const annotation = getModeAnnotation(options.mode, options.value);
     // Declare a missing category banner in the same in-memory edit as the
     // token insertion — the file is written exactly once, so a failure
@@ -451,7 +337,10 @@ async function addTokenToCSS(engineDir, options, tokensCssPath) {
     }
     lines.splice(insertIndex, 0, ...insertLines);
     insertDarkModeOverride(lines, options);
-    content = lines.join('\n');
-    await writeText(filePath, content);
+    const themeBlocksWritten = insertThemeAttributeOverrides(lines, options);
+    if (themeBlocksWritten.length > 0) {
+        info(`Override also written to ${themeBlocksWritten.join(' and ')}.`);
+    }
+    await writeText(filePath, lines.join('\n'));
     return { added: true, categoryCreated };
 }

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

@@ -29,6 +29,13 @@ export type VariantValidation = {
  * @param raw - Raw `--variant` value from the CLI / programmatic caller.
  */
 export declare function validateVariantSelector(raw: unknown): VariantValidation;
+/**
+ * True when a top-level `:root<variant>` block exists in `lines`. Used by
+ * the override path to write theme-attribute blocks only when the scaffold
+ * already declares them — `insertVariantDeclaration` would otherwise create
+ * the block, which is only wanted for the explicit `--variant` flow.
+ */
+export declare function variantBlockExists(lines: string[], variant: string): boolean;
 /** True when the `:root<variant>` block already declares `tokenName`. */
 export declare function variantBlockHasToken(lines: string[], variant: string, tokenName: string): boolean;
 /**