@hominis/fireforge 0.54.0 → 0.60.0

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

@@ -1,73 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Scaffolds the default tokens CSS file consumed by `fireforge token add`.
- *
- * Without it, `fireforge furnace init` writes `furnace.json` but not the
- * tokens CSS, and every project's first `fireforge token add` hits
- * `Token CSS file not found: browser/themes/shared/<binaryName>-tokens.css`.
- * Init calls into this module to write a canonical `:root { … }` shell with
- * a seed set of category headers that `assertTokenCategoryExists`
- * recognises, and registers the tokens CSS path in
- * `patchLint.rawColorAllowlist` so the first token that is an actual color
- * value does not instantly fail `fireforge lint`.
- */
-import { getLicenseHeader } from './license-headers.js';
-/**
- * The set of categories seeded by the default scaffold. `token add
- * --category <name>` accepts any of these without further setup. An
- * operator who needs another category only has to add a matching
- * `/* = My Category = *\/` header inside the `:root` block by hand.
- *
- * The names intentionally mirror the vocabulary used in Firefox's own
- * token files (the color and spacing categories listed below) so operators
- * coming from upstream don't have to relearn a fork-specific taxonomy.
- */
-export const DEFAULT_TOKEN_CATEGORIES = [
-    'Colors — General',
-    'Colors — Canvas',
-    'Colors — Experiment',
-    'Spacing',
-];
-/**
- * Generates the default tokens CSS body. Extracted from the init
- * command so tests can assert on the generated shape without running
- * the interactive scaffold flow.
- *
- * @param binaryName - `fireforge.json` `binaryName` used in the
- *   rendered file banner so operators can identify the fork on-sight.
- * @param license - Project license, piped through `getLicenseHeader`
- *   so the scaffold is SPDX-marked and survives `fireforge lint`'s
- *   license-header checks without operator intervention.
- */
-export function generateDefaultTokensCss(binaryName, license) {
-    const header = getLicenseHeader(license, 'css');
-    const categoryBlocks = DEFAULT_TOKEN_CATEGORIES.map((category) => `  /* = ${category} = */\n  /* (add design tokens for "${category}" here; use \`fireforge token add --category "${category}" …\`) */`).join('\n\n');
-    return `${header}
-
-/*
- * Design tokens for ${binaryName}.
- *
- * Scaffolded by \`fireforge furnace init\`. Add new tokens with
- * \`fireforge token add --category '<name>' -- <token-name> <value>\`
- * — the command appends into the matching \`/* = <name> = *\\/\` block
- * below and keeps the per-category ordering stable.
- *
- * Raw color literals inside this file are expected — the whole point
- * of the tokens layer is that every other CSS file consumes \`var(…)\`
- * instead of literal colors. \`fireforge furnace init\` adds this
- * file's path to \`patchLint.rawColorAllowlist\` in fireforge.json so
- * \`fireforge lint\` stops flagging the literals here.
- */
-
-:root {
-${categoryBlocks}
-}
-
-@media (prefers-color-scheme: dark) {
-  :root {
-    /* Dark-mode overrides land here. Use \`fireforge token add --mode override --dark-value <v>\`
-       to have a token's dark value placed inside this block. */
-  }
-}
-`;
-}

package/dist/src/core/token-sibling-sheets.d.ts

@@ -1,46 +0,0 @@
-/**
- * Which stylesheets load together, so `token lint` can resolve a token one
- * sheet references against the declarations of the sheets beside it.
- *
- * A widget sheet may read a token its host document's other sheet
- * declares; judged alone it looks undeclared. Two sources say which sheets
- * share a document:
- *
- * - links the queue's documents make: `<link rel="stylesheet">` (and
- *   `<html:link>`) and `<?xml-stylesheet?>` in markup and Lit templates,
- *   and CSS `@import`. A `chrome://` URL resolves through the jar.mn lines
- *   the queue adds; a relative URL resolves beside the document, and only
- *   to a sheet the queue touches.
- * - `furnace.json#tokenSiblingSheets`: `{ "<glob>": ["<path or glob>"] }`,
- *   for pairings no link in the queue shows (an upstream host document).
- *
- * Sheets linked from one document are siblings of each other; an
- * `@import` makes the importing and the imported sheet siblings.
- */
-/** The stylesheet URLs one document or sheet loads, in order. */
-export declare function collectStylesheetUrls(file: string, content: string): string[];
-/**
- * Resolves a stylesheet URL to an engine-relative path, or undefined.
- *
- * @param url - The URL as written
- * @param from - Engine-relative path of the document or sheet holding it
- * @param jarTargets - jar target (`content/<pkg>/<path>`) → packaged source
- * @param knownSheets - Sheets a relative URL may resolve to
- */
-export declare function resolveStylesheetUrl(url: string, from: string, jarTargets: ReadonlyMap<string, string>, knownSheets: ReadonlySet<string>): string | undefined;
-/** Inputs of {@link buildSiblingSheetMap}. */
-export interface SiblingSheetInputs {
-    /** Documents and sheets to read links from: engine-relative path and content. */
-    documents: Iterable<readonly [string, string]>;
-    /** jar target → packaged source, from the queue's jar.mn lines. */
-    jarTargets: ReadonlyMap<string, string>;
-    /** The sheets `token lint` judges. */
-    sheets: readonly string[];
-    /** `furnace.json#tokenSiblingSheets`. */
-    explicit?: Readonly<Record<string, readonly string[]>> | undefined;
-}
-/**
- * Maps each sheet to the other sheets that load beside it. A sheet with no
- * siblings is absent.
- */
-export declare function buildSiblingSheetMap(inputs: SiblingSheetInputs): Map<string, Set<string>>;

package/dist/src/core/token-sibling-sheets.js

@@ -1,119 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Which stylesheets load together, so `token lint` can resolve a token one
- * sheet references against the declarations of the sheets beside it.
- *
- * A widget sheet may read a token its host document's other sheet
- * declares; judged alone it looks undeclared. Two sources say which sheets
- * share a document:
- *
- * - links the queue's documents make: `<link rel="stylesheet">` (and
- *   `<html:link>`) and `<?xml-stylesheet?>` in markup and Lit templates,
- *   and CSS `@import`. A `chrome://` URL resolves through the jar.mn lines
- *   the queue adds; a relative URL resolves beside the document, and only
- *   to a sheet the queue touches.
- * - `furnace.json#tokenSiblingSheets`: `{ "<glob>": ["<path or glob>"] }`,
- *   for pairings no link in the queue shows (an upstream host document).
- *
- * Sheets linked from one document are siblings of each other; an
- * `@import` makes the importing and the imported sheet siblings.
- */
-import { dirname, posix } from 'node:path';
-import { matchesAnyGlob } from '../utils/path-glob.js';
-import { normalizePathSlashes } from '../utils/paths.js';
-const LINK_TAG = /<(?:html:)?link\b[^>]*>/gi;
-const STYLESHEET_PI = /<\?xml-stylesheet\b[^?]*?href\s*=\s*["']([^"']+)["']/gi;
-const CSS_IMPORT = /@import\s+(?:url\(\s*)?["']([^"']+)["']/gi;
-/** The stylesheet URLs one document or sheet loads, in order. */
-export function collectStylesheetUrls(file, content) {
-    const urls = [];
-    if (file.endsWith('.css')) {
-        for (const match of content.matchAll(CSS_IMPORT))
-            urls.push(match[1] ?? '');
-        return urls.filter((url) => url !== '');
-    }
-    for (const match of content.matchAll(LINK_TAG)) {
-        const tag = match[0];
-        if (!/\brel\s*=\s*["']stylesheet["']/i.test(tag))
-            continue;
-        const href = /\bhref\s*=\s*["']([^"'$]+)["']/i.exec(tag)?.[1];
-        if (href !== undefined)
-            urls.push(href);
-    }
-    for (const match of content.matchAll(STYLESHEET_PI))
-        urls.push(match[1] ?? '');
-    return urls.filter((url) => url.endsWith('.css'));
-}
-/**
- * Resolves a stylesheet URL to an engine-relative path, or undefined.
- *
- * @param url - The URL as written
- * @param from - Engine-relative path of the document or sheet holding it
- * @param jarTargets - jar target (`content/<pkg>/<path>`) → packaged source
- * @param knownSheets - Sheets a relative URL may resolve to
- */
-export function resolveStylesheetUrl(url, from, jarTargets, knownSheets) {
-    const chrome = /^chrome:\/\/([\w.-]+)\/(content|skin|locale)\/(.+)$/.exec(url);
-    if (chrome !== null) {
-        const [, pkg = '', kind = '', path = ''] = chrome;
-        const candidates = kind === 'skin'
-            ? [`skin/classic/${pkg}/${path}`, `skin/${pkg}/${path}`]
-            : [`${kind}/${pkg}/${path}`];
-        for (const target of candidates) {
-            const source = jarTargets.get(target);
-            if (source !== undefined)
-                return source;
-        }
-        return undefined;
-    }
-    if (/^[a-z][\w+.-]*:/i.test(url))
-        return undefined;
-    const base = normalizePathSlashes(dirname(from));
-    const resolved = posix.normalize(posix.join(base === '.' ? '' : base, url));
-    return knownSheets.has(resolved) ? resolved : undefined;
-}
-/**
- * Maps each sheet to the other sheets that load beside it. A sheet with no
- * siblings is absent.
- */
-export function buildSiblingSheetMap(inputs) {
-    const known = new Set(inputs.sheets);
-    const siblings = new Map();
-    const link = (group) => {
-        for (const sheet of group) {
-            const set = siblings.get(sheet) ?? new Set();
-            for (const other of group)
-                if (other !== sheet)
-                    set.add(other);
-            if (set.size > 0)
-                siblings.set(sheet, set);
-        }
-    };
-    for (const [file, content] of inputs.documents) {
-        const linked = collectStylesheetUrls(file, content)
-            .map((url) => resolveStylesheetUrl(url, file, inputs.jarTargets, known))
-            .filter((sheet) => sheet !== undefined);
-        // An @import pairs the importing sheet with what it imports.
-        link(file.endsWith('.css') ? [file, ...linked] : linked);
-    }
-    for (const [pattern, partners] of Object.entries(inputs.explicit ?? {})) {
-        const owners = inputs.sheets.filter((sheet) => matchesAnyGlob(sheet, [pattern]));
-        for (const owner of owners) {
-            const set = siblings.get(owner) ?? new Set();
-            for (const partner of partners) {
-                if (/[*?]/.test(partner)) {
-                    for (const sheet of inputs.sheets) {
-                        if (sheet !== owner && matchesAnyGlob(sheet, [partner]))
-                            set.add(sheet);
-                    }
-                }
-                else if (partner !== owner) {
-                    set.add(partner);
-                }
-            }
-            if (set.size > 0)
-                siblings.set(owner, set);
-        }
-    }
-    return siblings;
-}

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

@@ -1,90 +0,0 @@
-/**
- * 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 not an
- * attribute-keyed selector such as `:root[data-skin="precision"]` or
- * `:root[data-private]`, which would otherwise have 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.
- */
-import type { TokenDeclarationLocation } from './token-category.js';
-/**
- * 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` selector fragment and normalizes any `=value`
- * form to the double-quoted `="value"` shape (Mozilla convention).
- * Boolean-attribute fragments are returned unchanged.
- *
- * Structure is decided by {@link rootAttributeSelector}, the matcher's own
- * parse, rather than by a second regex. The matcher consumes consecutive
- * `[…]` groups and stops at a pseudo-class tail, and a separate validator
- * that does not follow it leaves blocks such as
- * `:root[data-skin="humanist"]:not([data-private])` findable but
- * unnameable. Running both halves off one parse keeps them from drifting
- * apart. Character-level safety stays a
- * separate, per-group check, because the matcher finds bracket boundaries
- * and validates no characters at all.
- *
- * @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;
-/**
- * The pseudo-class qualifier on the matched `:root<variant>` block, or
- * `undefined` when no block matched. `''` for an unqualified block.
- *
- * A qualifier such as `:not([data-private])` is load-bearing: writing into
- * that block scopes the declaration to the qualified case, and that may not
- * be what the operator meant. Matching it is still the right call, since
- * silently skipping it is the worse failure and the one that shipped, but
- * the override path uses this to say out loud which selector it wrote
- * through, so the narrowing is a visible decision rather than a theme bug
- * discovered later.
- *
- * @param lines - Tokens CSS split into lines
- * @param variant - Attribute selector fragment, e.g. `[data-theme="light"]`
- * @returns The qualifier, or undefined when no block matched
- */
-export declare function variantBlockQualifier(lines: string[], variant: string): string | undefined;
-/** True when the `:root<variant>` block already declares `tokenName`. */
-export declare function variantBlockHasToken(lines: string[], variant: string, tokenName: string): boolean;
-/**
- * Locates an existing declaration of `tokenName` inside the
- * `:root<variant>` block, or `undefined` when the block has none (or does
- * not exist).
- *
- * The located form of {@link variantBlockHasToken}: the variant add path
- * reports a skip the way the base path does, naming the block and the
- * line, instead of returning a bare boolean that leaves a no-op re-run
- * indistinguishable from a write.
- *
- * @param lines - Tokens CSS split into lines
- * @param variant - Attribute selector fragment
- * @param tokenName - Full token name including prefix
- * @returns The declaration's 1-based line, or undefined
- */
-export declare function findVariantBlockDeclaration(lines: string[], variant: string, tokenName: string): TokenDeclarationLocation | undefined;
-/**
- * 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;

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

@@ -1,327 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * 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 not an
- * attribute-keyed selector such as `:root[data-skin="precision"]` or
- * `:root[data-private]`, which would otherwise have 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.
- */
-import { findBlockCloseIndex, stripBlockCommentsInLines } from './token-dark-mode.js';
-/**
- * One attribute selector fragment: `[data-private]` (boolean attribute) or
- * `[data-skin=precision]` / `[data-skin="precision"]` (attribute with
- * value). The name and value halves are restricted to identifier-safe
- * characters so the fragment can be spliced into CSS verbatim without
- * escaping concerns.
- *
- * A multi-fragment variant is checked one group at a time (see
- * {@link splitAttributeGroups}) rather than by wrapping this in a `+`: the
- * repeated form is the shape CodeQL flags as `js/polynomial-redos`, and the
- * split the matcher already performs is available for free.
- */
-const ATTRIBUTE_FRAGMENT_PATTERN = /^\[[a-zA-Z][a-zA-Z0-9_-]*(?:=(?:"[a-zA-Z0-9_-]+"|'[a-zA-Z0-9_-]+'|[a-zA-Z0-9_-]+))?\]$/;
-/**
- * A pseudo-class tail: `:not(…)`, `:hover`, and friends. The parenthesised
- * argument is captured rather than validated here. It is a fragment run of
- * its own and goes through the same per-group check.
- */
-const QUALIFIER_PATTERN = /^:[a-zA-Z][a-zA-Z0-9-]*(?:\(([^()]*)\))?$/;
-/**
- * Splits a run of consecutive attribute fragments into its groups, or
- * returns `undefined` when the run is not exactly that: a group that does
- * not open with `[`, an unclosed group, an empty run, or a group whose name
- * or value is not identifier-safe.
- *
- * @param run - The `[…][…]` text with no `:root` prefix
- * @returns The individual fragments, or undefined when the run is not valid
- */
-function splitAttributeGroups(run) {
-    const groups = [];
-    let cursor = 0;
-    while (cursor < run.length) {
-        if (run[cursor] !== '[')
-            return undefined;
-        const close = run.indexOf(']', cursor);
-        if (close === -1)
-            return undefined;
-        const group = run.slice(cursor, close + 1);
-        if (!ATTRIBUTE_FRAGMENT_PATTERN.test(group))
-            return undefined;
-        groups.push(group);
-        cursor = close + 1;
-    }
-    return groups.length > 0 ? groups : undefined;
-}
-/** Rewrites `=value` / `='value'` to the double-quoted Mozilla convention. */
-function normalizeAttributeFragment(group) {
-    return group
-        .replace(/='([a-zA-Z0-9_-]+)'\]$/, '="$1"]')
-        .replace(/=([a-zA-Z0-9_-]+)\]$/, '="$1"]');
-}
-/**
- * Validates a `--variant` selector fragment and normalizes any `=value`
- * form to the double-quoted `="value"` shape (Mozilla convention).
- * Boolean-attribute fragments are returned unchanged.
- *
- * Structure is decided by {@link rootAttributeSelector}, the matcher's own
- * parse, rather than by a second regex. The matcher consumes consecutive
- * `[…]` groups and stops at a pseudo-class tail, and a separate validator
- * that does not follow it leaves blocks such as
- * `:root[data-skin="humanist"]:not([data-private])` findable but
- * unnameable. Running both halves off one parse keeps them from drifting
- * apart. Character-level safety stays a
- * separate, per-group check, because the matcher finds bracket boundaries
- * and validates no characters at all.
- *
- * @param raw - Raw `--variant` value from the CLI / programmatic caller.
- */
-export function validateVariantSelector(raw) {
-    if (typeof raw !== 'string') {
-        return { ok: false, reason: 'must be a string when set' };
-    }
-    const reject = {
-        ok: false,
-        reason: 'must be one or more attribute selectors like [data-private], [data-skin=precision] ' +
-            'or [data-skin=precision][data-theme=dark], optionally followed by a pseudo-class ' +
-            'such as :not([data-private]) (identifier-safe attribute names and values only)',
-    };
-    const value = raw.trim();
-    if (value === '')
-        return reject;
-    const parts = rootAttributeSelector(`:root${value} {`);
-    // The parse must have consumed the whole fragment: anything it declined to
-    // read (a stray space, a trailing combinator) is text the matcher would
-    // not see either, so accepting it would author a block nothing can find.
-    if (parts === undefined || `${parts.attributes}${parts.qualifier}` !== `:root${value}`)
-        return reject;
-    const groups = splitAttributeGroups(parts.attributes.slice(':root'.length));
-    if (groups === undefined)
-        return reject;
-    let qualifier = '';
-    if (parts.qualifier !== '') {
-        const match = QUALIFIER_PATTERN.exec(parts.qualifier);
-        if (match === null)
-            return reject;
-        const inner = match[1];
-        if (inner === undefined) {
-            qualifier = parts.qualifier;
-        }
-        else {
-            const innerGroups = splitAttributeGroups(inner);
-            if (innerGroups === undefined)
-                return reject;
-            const name = parts.qualifier.slice(0, parts.qualifier.indexOf('('));
-            qualifier = `${name}(${innerGroups.map(normalizeAttributeFragment).join('')})`;
-        }
-    }
-    return { ok: true, value: `${groups.map(normalizeAttributeFragment).join('')}${qualifier}` };
-}
-/**
- * Reduces a `:root<attr>` selector to a quote- and whitespace-insensitive
- * canonical form so `[data-skin="precision"]`, `[data-skin='precision']`,
- * and `[data-skin=precision]` all compare equal when matching an existing
- * block against the requested variant.
- */
-function canonicalSelector(selector) {
-    return selector.replace(/\s+/g, '').replace(/["']/g, '');
-}
-/**
- * Splits the `:root[…]` selector on `line` into its attribute run and any
- * trailing qualifier, or `undefined` when the line carries none.
- *
- * Index arithmetic rather than `/:root\[[^{]*\]/`: `[^{]` also matches `]`,
- * so that pattern backtracks quadratically on a line repeating `:root[`
- * (CodeQL `js/polynomial-redos`). This walk is linear and allocation-free
- * per group.
- *
- * It consumes consecutive `[…]` groups and stops at the first character that
- * is not `[`. The previous implementation instead sliced to the last `]`
- * before the brace, which kept multi-attribute selectors comparing as a
- * whole (that property is preserved here, since consecutive groups are all
- * consumed) but it also swallowed a pseudo-class tail. On
- * `:root[data-theme="light"]:not([data-private]) {` the last `]` is the one
- * inside `:not(…)`, so the computed fragment was
- * `:root[data-theme="light"]:not([data-private]` and the canonical
- * comparison could never match. The unqualified
- * `:root[data-theme="dark"] { }` beside it matched fine, and that asymmetry
- * was the bug: an override add mirrored itself into the dark block and
- * silently skipped the light one, the half-finished themed edit
- * `THEME_ATTRIBUTE_VARIANTS` exists to prevent.
- */
-function rootAttributeSelector(line) {
-    const start = line.indexOf(':root[');
-    if (start === -1)
-        return undefined;
-    const brace = line.indexOf('{', start);
-    const limit = brace === -1 ? line.length : brace;
-    let cursor = start + ':root'.length;
-    let end = cursor;
-    while (cursor < limit && line[cursor] === '[') {
-        const close = line.indexOf(']', cursor);
-        if (close === -1 || close >= limit)
-            break;
-        cursor = close + 1;
-        end = cursor;
-    }
-    if (end === start + ':root'.length)
-        return undefined;
-    return { attributes: line.slice(start, end), qualifier: line.slice(end, limit).trim() };
-}
-/**
- * Finds the top-level `:root<variant>` block whose attribute selector
- * matches `variant` (compared canonically). Returns the opening-brace and
- * closing-brace line indices, or `undefined` when no such block exists.
- *
- * Scans a comment-stripped mirror of `lines` so braces inside comments do
- * not offset the depth counter. The returned indices line up with the
- * original array.
- */
-function findVariantBlock(lines, variant) {
-    const stripped = stripBlockCommentsInLines(lines);
-    // The request goes through the same parse as the candidate lines, so a
-    // variant carrying its own `:not(…)` tail is compared tail-to-tail rather
-    // than being folded into the attribute run, where it would match nothing
-    // and every add would splice a fresh duplicate block.
-    const requested = rootAttributeSelector(`:root${variant} {`);
-    const want = canonicalSelector(requested?.attributes ?? `:root${variant}`);
-    const wantQualifier = canonicalSelector(requested?.qualifier ?? '');
-    for (const [i, line] of stripped.entries()) {
-        const selector = rootAttributeSelector(line);
-        if (selector === undefined || canonicalSelector(selector.attributes) !== want)
-            continue;
-        // An unqualified request still matches a qualified block: that is the
-        // behaviour `variantBlockQualifier` exists to report, since
-        // silently skipping the block is the worse failure. A request that names
-        // a qualifier, though, means it, so it must match.
-        if (wantQualifier !== '' && canonicalSelector(selector.qualifier) !== wantQualifier)
-            continue;
-        let openLine = /\{/.test(line) ? i : -1;
-        if (openLine === -1) {
-            for (let j = i + 1; j < stripped.length; j++) {
-                const next = stripped[j] ?? '';
-                if (/\{/.test(next)) {
-                    openLine = j;
-                    break;
-                }
-                if (/[};]/.test(next))
-                    break;
-            }
-        }
-        if (openLine === -1)
-            continue;
-        const close = findBlockCloseIndex(stripped, openLine);
-        if (close === -1)
-            continue;
-        return { open: openLine, close, qualifier: selector.qualifier };
-    }
-    return undefined;
-}
-/**
- * Returns the line index at which a brand-new `:root<variant>` block should
- * be spliced: immediately after the base `:root { }` block's closing brace
- * (so attribute variants sit between the base block and any dark `@media`
- * block). Falls back to end-of-file when no base `:root` block is found.
- */
-function findVariantBlockInsertionPoint(lines) {
-    const stripped = stripBlockCommentsInLines(lines);
-    for (const [i, line] of stripped.entries()) {
-        if (/^\s*:root\s*\{/.test(line)) {
-            const close = findBlockCloseIndex(stripped, i);
-            if (close !== -1)
-                return close + 1;
-        }
-    }
-    return lines.length;
-}
-/**
- * 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 function variantBlockExists(lines, variant) {
-    return findVariantBlock(lines, variant) !== undefined;
-}
-/**
- * The pseudo-class qualifier on the matched `:root<variant>` block, or
- * `undefined` when no block matched. `''` for an unqualified block.
- *
- * A qualifier such as `:not([data-private])` is load-bearing: writing into
- * that block scopes the declaration to the qualified case, and that may not
- * be what the operator meant. Matching it is still the right call, since
- * silently skipping it is the worse failure and the one that shipped, but
- * the override path uses this to say out loud which selector it wrote
- * through, so the narrowing is a visible decision rather than a theme bug
- * discovered later.
- *
- * @param lines - Tokens CSS split into lines
- * @param variant - Attribute selector fragment, e.g. `[data-theme="light"]`
- * @returns The qualifier, or undefined when no block matched
- */
-export function variantBlockQualifier(lines, variant) {
-    return findVariantBlock(lines, variant)?.qualifier;
-}
-/** True when the `:root<variant>` block already declares `tokenName`. */
-export function variantBlockHasToken(lines, variant, tokenName) {
-    return findVariantBlockDeclaration(lines, variant, tokenName) !== undefined;
-}
-/**
- * Locates an existing declaration of `tokenName` inside the
- * `:root<variant>` block, or `undefined` when the block has none (or does
- * not exist).
- *
- * The located form of {@link variantBlockHasToken}: the variant add path
- * reports a skip the way the base path does, naming the block and the
- * line, instead of returning a bare boolean that leaves a no-op re-run
- * indistinguishable from a write.
- *
- * @param lines - Tokens CSS split into lines
- * @param variant - Attribute selector fragment
- * @param tokenName - Full token name including prefix
- * @returns The declaration's 1-based line, or undefined
- */
-export function findVariantBlockDeclaration(lines, variant, tokenName) {
-    const block = findVariantBlock(lines, variant);
-    if (!block)
-        return undefined;
-    // Comments are stripped across the whole block before scanning, matching
-    // what the boolean form always did: a `/* … */` spanning several lines
-    // must not leave its tail looking like a declaration.
-    const blockLines = lines.slice(block.open, block.close + 1);
-    // Blank the comment's characters rather than deleting it: removing a
-    // multi-line comment outright collapses its lines and shifts every line
-    // number after it, which is the one thing this function exists to report.
-    const stripped = blockLines
-        .join('\n')
-        .replace(/\/\*[\s\S]*?\*\//g, (match) => match.replace(/[^\n]/g, ' '))
-        .split('\n');
-    for (const [i, line] of stripped.entries()) {
-        if (line.includes(`${tokenName}:`))
-            return { line: block.open + i + 1 };
-    }
-    return undefined;
-}
-/**
- * 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 function insertVariantDeclaration(lines, variant, declLine) {
-    const block = findVariantBlock(lines, variant);
-    if (block) {
-        let insertIndex = block.close;
-        for (let i = block.close - 1; i > block.open; i--) {
-            if ((lines[i] ?? '').trim()) {
-                insertIndex = i + 1;
-                break;
-            }
-        }
-        lines.splice(insertIndex, 0, declLine);
-        return;
-    }
-    lines.splice(findVariantBlockInsertionPoint(lines), 0, '', `:root${variant} {`, declLine, '}');
-}