@hominis/fireforge 0.45.0 → 0.46.1

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

@@ -3,8 +3,8 @@
  * Dark-mode insertion helpers for the tokens CSS scaffold.
  *
  * `fireforge token add --mode override --dark-value ...` must land the dark
- * declaration INSIDE the nested `:root { }` of the
- * `@media (prefers-color-scheme: dark)` block; landing after that block has
+ * declaration inside the nested `:root { }` of the
+ * `@media (prefers-color-scheme: dark)` block. Landing after that block has
  * closed produces a declaration outside any rule. The helpers here scan the
  * comment-stripped source lines to find the *inner* `:root` block's closing
  * `}` and return a line index the caller can splice into. When the inner
@@ -38,8 +38,8 @@ function rootOpensBraceOnLine(line) {
  * into the original array at the same index.
  *
  * We blank the comment body with spaces (rather than removing it) so
- * any downstream consumer that indexes by column — or derives an
- * insertion index as a line number in the original array — still
+ * any downstream consumer that indexes by column (or derives an
+ * insertion index as a line number in the original array) still
  * agrees on line numbers.
  */
 export function stripBlockCommentsInLines(lines) {
@@ -77,29 +77,23 @@ export function stripBlockCommentsInLines(lines) {
 /**
  * Finds the closing `}` line of the nested `:root { ... }` block inside
  * a `@media (prefers-color-scheme: dark)` block. Returns `-1` when the
- * media block exists but the nested `:root` block is missing; returns
+ * media block exists but the nested `:root` block is missing. Returns
  * `null` when the `@media` block itself is absent.
  *
  * Runs the scan over a comment-stripped mirror of the source lines so
  * braces inside CSS comments (`/* before { after *\/`) do not offset
- * the depth counter. The scan is deliberately line-indexed so callers
+ * the depth counter. The scan is line-indexed so callers
  * can splice into the original `lines` array at the returned index.
  */
 export function findDarkRootInsertionIndex(lines) {
     const stripped = stripBlockCommentsInLines(lines);
-    let darkMediaLine = -1;
-    for (let i = 0; i < stripped.length; i++) {
-        if (/prefers-color-scheme:\s*dark/.test(stripped[i] ?? '')) {
-            darkMediaLine = i;
-            break;
-        }
-    }
+    const darkMediaLine = stripped.findIndex((line) => /prefers-color-scheme:\s*dark/.test(line));
     if (darkMediaLine === -1)
         return null;
     // Walk the comment-stripped lines after the @media header and find
     // the first `:root {` opener inside the block. The opening brace of
     // the selector may live on the same line as the selector name or on
-    // the following line; either shape is tolerated.
+    // the following line. Either shape is tolerated.
     let rootOpenLine = -1;
     for (let i = darkMediaLine; i < stripped.length; i++) {
         const line = stripped[i] ?? '';
@@ -127,14 +121,14 @@ export function findDarkRootInsertionIndex(lines) {
     }
     if (rootOpenLine === -1)
         return -1;
-    // Depth-count starting from the `:root` opener; see findBlockCloseIndex.
+    // Depth-count starting from the `:root` opener. See findBlockCloseIndex.
     return findBlockCloseIndex(stripped, rootOpenLine);
 }
 /**
  * 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
+ * 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.
  */
@@ -165,20 +159,14 @@ export function findBlockCloseIndex(stripped, startLine) {
 /**
  * Finds the closing `}` of the outermost
  * `@media (prefers-color-scheme: dark)` block. Used as the fallback
- * landing site when the scaffold has no nested `:root { }` — the
+ * landing site when the scaffold has no nested `:root { }`. The
  * insertion helper uses this index to splice a brand-new `:root`
  * wrapper containing the dark declaration, rather than dropping the
  * value.
  */
 export function findDarkMediaCloseIndex(lines) {
     const stripped = stripBlockCommentsInLines(lines);
-    let darkMediaLine = -1;
-    for (let i = 0; i < stripped.length; i++) {
-        if (/prefers-color-scheme:\s*dark/.test(stripped[i] ?? '')) {
-            darkMediaLine = i;
-            break;
-        }
-    }
+    const darkMediaLine = stripped.findIndex((line) => /prefers-color-scheme:\s*dark/.test(line));
     if (darkMediaLine === -1)
         return -1;
     return findBlockCloseIndex(stripped, darkMediaLine);

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

@@ -6,7 +6,7 @@
 /**
  * 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.
+ * `token-manager.ts`. `AddTokenOptions` is structurally compatible.
  */
 export interface TokenDocInput {
     tokenName: string;

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

@@ -0,0 +1,56 @@
+/** One token declaration inside the base `:root` block. */
+export interface TokenInventoryEntry {
+    /** Custom-property name, including the leading `--`. */
+    name: string;
+    /** 1-based line number in the tokens CSS file. */
+    line: number;
+    /** Declared value, trimmed, without the trailing `;`. */
+    value: string;
+}
+/**
+ * Tokens grouped under the banner that precedes them, in file order.
+ * `category` is null for declarations that sit above the first banner.
+ * That is a real state in a hand-edited file, and one the report must show
+ * rather than silently drop.
+ */
+export interface TokenCategoryInventory {
+    category: string | null;
+    tokens: TokenInventoryEntry[];
+}
+/** One block that declares a given token, with the value it declares. */
+export interface TokenBlockValue {
+    /**
+     * Selector trail of the declaring block, outermost first, joined with
+     * ` > `. For example `:root` or
+     * `@media (prefers-color-scheme: dark) > :root`.
+     */
+    block: string;
+    value: string;
+    /** 1-based line number of the declaration. */
+    line: number;
+}
+/**
+ * Collects every base-`:root` token declaration grouped by the category
+ * banner above it, in document order.
+ *
+ * Only the base block is walked: the dark `@media` and `:root[variant]`
+ * companions mirror declarations rather than owning them, so listing them
+ * would report the same token two or three times under no category at all.
+ *
+ * @param lines - Tokens CSS split into lines
+ * @returns Categories in file order, each with its tokens in file order
+ */
+export declare function collectTokenInventory(lines: string[]): TokenCategoryInventory[];
+/**
+ * Every declaration of `tokenName`, in every block of the file, labelled by
+ * the selector trail of the block that declares it.
+ *
+ * Not restricted to the base `:root`: the question `token show`
+ * answers is "what does this token resolve to", and a token whose dark
+ * override differs from its base value is the case worth seeing.
+ *
+ * @param lines - Tokens CSS split into lines
+ * @param tokenName - Custom-property name including the leading `--`
+ * @returns Declarations in file order
+ */
+export declare function collectTokenBlockValues(lines: string[], tokenName: string): TokenBlockValue[];

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

@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Read-only inventory of the tokens CSS file: which categories exist, which
+ * tokens each declares, and what a single token resolves to in every theme
+ * block that mentions it.
+ *
+ * `token add` requires `--category` and, until now, nothing reported the
+ * categories a project actually has, so the only way to name one correctly
+ * was to hand-parse a neighbouring `= Category =` banner out of the file.
+ * This module is that report. It reuses the banner and
+ * `:root`-bounds primitives from `token-category.ts` rather than parsing
+ * tokens CSS a second way: two readers that disagree on what a banner is
+ * would put `token list` and `token add` in different sections of the same
+ * file.
+ */
+import { categoryBannerNameAt, findBaseRootBounds, maskCommentLines } from './token-category.js';
+/** Matches a custom-property declaration and captures its name and value. */
+const DECLARATION_PATTERN = /^\s*(--[A-Za-z0-9_-]+)\s*:\s*([^;]*);?/;
+/**
+ * Collects every base-`:root` token declaration grouped by the category
+ * banner above it, in document order.
+ *
+ * Only the base block is walked: the dark `@media` and `:root[variant]`
+ * companions mirror declarations rather than owning them, so listing them
+ * would report the same token two or three times under no category at all.
+ *
+ * @param lines - Tokens CSS split into lines
+ * @returns Categories in file order, each with its tokens in file order
+ */
+export function collectTokenInventory(lines) {
+    const bounds = findBaseRootBounds(lines);
+    if (bounds === undefined || bounds.close === -1)
+        return [];
+    const masked = maskCommentLines(lines);
+    const groups = [];
+    let current;
+    for (let i = bounds.open + 1; i < bounds.close; i++) {
+        // Banners are read from the raw lines: `maskCommentLines` blanks comment
+        // bodies, which is exactly what a banner is.
+        const banner = categoryBannerNameAt(lines, i);
+        if (banner !== undefined) {
+            current = { category: banner, tokens: [] };
+            groups.push(current);
+            continue;
+        }
+        const match = DECLARATION_PATTERN.exec(masked[i] ?? '');
+        if (!match?.[1])
+            continue;
+        if (current === undefined) {
+            current = { category: null, tokens: [] };
+            groups.push(current);
+        }
+        current.tokens.push({ name: match[1], line: i + 1, value: (match[2] ?? '').trim() });
+    }
+    // A banner with no declarations under it is still a category `token add
+    // --category` accepts, so empty groups are kept.
+    return groups;
+}
+/**
+ * Every declaration of `tokenName`, in every block of the file, labelled by
+ * the selector trail of the block that declares it.
+ *
+ * Not restricted to the base `:root`: the question `token show`
+ * answers is "what does this token resolve to", and a token whose dark
+ * override differs from its base value is the case worth seeing.
+ *
+ * @param lines - Tokens CSS split into lines
+ * @param tokenName - Custom-property name including the leading `--`
+ * @returns Declarations in file order
+ */
+export function collectTokenBlockValues(lines, tokenName) {
+    const masked = maskCommentLines(lines);
+    const trail = [];
+    const found = [];
+    for (let i = 0; i < masked.length; i++) {
+        const line = masked[i] ?? '';
+        const match = DECLARATION_PATTERN.exec(line);
+        if (match?.[1] === tokenName) {
+            found.push({
+                block: trail.length > 0 ? trail.join(' > ') : '(file scope)',
+                value: (match[2] ?? '').trim(),
+                line: i + 1,
+            });
+        }
+        // Brace tracking after the declaration test, so a one-line block cannot
+        // swallow the declaration it opens on. Selector text is whatever
+        // precedes the `{`. An empty selector (a continuation line) still
+        // needs a stack entry or the closing `}` pops the wrong one.
+        for (const char of line) {
+            if (char === '{') {
+                trail.push(selectorBefore(line, trail.length));
+            }
+            else if (char === '}') {
+                trail.pop();
+            }
+        }
+    }
+    return found;
+}
+/**
+ * Selector text introducing the `depth`-th open brace on `line`. Falls back
+ * to a positional label so the trail stays well-formed on a minified or
+ * continuation line that opens a block with no visible selector.
+ */
+function selectorBefore(line, depth) {
+    const open = line.indexOf('{');
+    const text = open === -1 ? '' : line.slice(0, open).trim();
+    return text.length > 0 ? text : `(block ${String(depth + 1)})`;
+}

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

@@ -10,7 +10,7 @@ export declare const TOKEN_MODES: readonly ["auto", "static", "override"];
 /** Dark mode behaviour for a token. */
 export type TokenMode = (typeof TOKEN_MODES)[number];
 /** Narrows an arbitrary string to a {@link TokenMode}. */
-export declare const isTokenMode: (value: string) => value is "override" | "auto" | "static";
+export declare const isTokenMode: (value: string) => value is "auto" | "override" | "static";
 /**
  * Options for adding a token.
  */
@@ -21,7 +21,7 @@ export interface AddTokenOptions {
     value: string;
     /**
      * Token category matching section headers in the CSS file. Required for a
-     * base declaration; ignored — and no longer required — under
+     * base declaration. Ignored, and no longer required, under
      * {@link AddTokenOptions.variant}, which routes into a `:root<selector>`
      * block and never touches a category section.
      */
@@ -41,7 +41,7 @@ export interface AddTokenOptions {
      * `[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.
+     * overrides are CSS-only. The base token already owns its docs row.
      */
     variant?: string | undefined;
 }
@@ -62,7 +62,7 @@ export interface AddTokenResult {
     /** Whether a new category banner was declared by this add. */
     categoryCreated?: boolean;
     /**
-     * When the add skipped because the token already lives in the TARGET
+     * 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.
      */

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

@@ -60,7 +60,7 @@ async function validateTokenPrefix(root, options) {
     catch (error) {
         if (error instanceof InvalidArgumentError)
             throw error;
-        // FurnaceError means furnace.json doesn't exist yet — skip silently.
+        // FurnaceError means furnace.json doesn't exist yet, so skip silently.
         // Other errors (parse errors, permission errors) deserve a warning.
         if (!(error instanceof FurnaceError)) {
             const message = toError(error).message;
@@ -109,12 +109,12 @@ function normalizeVariantOption(options) {
  * Narrows {@link AddTokenOptions.category} for the base-declaration path,
  * which cannot proceed without one.
  *
- * `--category` used to be unconditionally required, INCLUDING under
+ * `--category` used to be unconditionally required, including under
  * `--variant`, where the declaration is routed into a `:root<selector>`
  * block and the category names nothing about where the token lands. The
- * requirement existed so the argument would not be silently discarded —
+ * requirement existed so the argument would not be silently discarded,
  * a fair goal that produced a mandatory argument describing nothing. Under
- * a variant it is now optional; everywhere else this states the reason
+ * a variant it is now optional. Everywhere else this states the reason
  * rather than leaving commander to print a bare "required option not
  * specified".
  *
@@ -136,14 +136,14 @@ async function assertTokensCssExists(engineDir, tokensCssPath) {
     }
 }
 /**
- * Routes a declaration into the top-level `:root<variant>` block — creating
+ * 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.
  *
- * A skip carries the LOCATION of the existing declaration, mirroring
+ * A skip carries the location of the existing declaration, mirroring
  * {@link evaluateBaseTokenIdempotency}. The bare `{ added: false }` it used
- * to return told the caller nothing, so a re-run intending to CHANGE a
- * value exited 0 having changed nothing and said only "already exists" —
+ * to return told the caller nothing, so a re-run intending to change a
+ * value exited 0 having changed nothing and said only "already exists",
  * while the base path had reported the category and line for the same
  * situation all along.
  */
@@ -161,9 +161,9 @@ async function addVariantTokenToCSS(engineDir, options, tokensCssPath, variant)
 }
 /**
  * Evaluates base-`:root` idempotency for one add: a token already declared
- * in the TARGET category skips; a token declared anywhere else in the base
- * block refuses loud. A whole-file substring check instead skips silently —
- * discarding `--create-category` — and exits 0.
+ * in the target category skips. A token declared anywhere else in the base
+ * block refuses loud. A whole-file substring check instead skips silently,
+ * discarding `--create-category`, and exits 0.
  */
 function evaluateBaseTokenIdempotency(lines, options, tokensCssPath) {
     const existing = findTokenDeclarationInRoot(lines, options.tokenName);
@@ -177,7 +177,7 @@ function evaluateBaseTokenIdempotency(lines, options, tokensCssPath) {
         ? '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}). ` +
+        `(${tokensCssPath}:${existing.line}${sectionSuffix}). ` +
         `A token belongs to exactly one category — ${remedy}.`);
 }
 /**
@@ -192,7 +192,7 @@ export async function validateTokenAdd(root, options) {
     await validateTokenPrefix(root, options);
     validateDarkValue(options);
     // Variant mode targets a `:root<attr>` block, not a category section, so
-    // no category is consulted — and none is required. When one IS passed it
+    // no category is consulted, and none is required. When one is passed it
     // is still checked, so a typo'd category is not silently accepted just
     // because the flag happens to be inert here.
     if (normalizeVariantOption(options) !== undefined) {
@@ -274,7 +274,7 @@ export async function addToken(root, options) {
     }
     // --- Documentation ---
     // Only the base path reaches here (variant declarations returned above),
-    // so a category is guaranteed — `requireCategory` already ran inside
+    // so a category is guaranteed. `requireCategory` already ran inside
     // `addTokenToCSS`. Re-narrowing rather than asserting keeps the docs
     // input's required `category` honest.
     const docsResult = await addTokenToDocs(engineDir, { ...options, category: requireCategory(options) }, getModeAnnotation(options.mode, options.value));
@@ -302,8 +302,8 @@ const THEME_ATTRIBUTE_VARIANTS = [
 /**
  * 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.
+ * that do not exist are left alone (scaffolded files have none, so behavior
+ * is unchanged there). Idempotent per block. Returns the selectors written.
  */
 function insertThemeAttributeOverrides(lines, options) {
     if (options.mode !== 'override' || !options.darkValue)
@@ -317,8 +317,8 @@ function insertThemeAttributeOverrides(lines, options) {
         const value = pick === 'dark' ? options.darkValue : options.value;
         insertVariantDeclaration(lines, variant, `  ${options.tokenName}: ${value};`);
         written.push(`:root${variant}`);
-        // A qualified block is matched — skipping it is the worse failure, and
-        // the one that shipped — but the qualifier narrows where the token
+        // A qualified block is matched. Skipping it is the worse failure, and
+        // the one that shipped, but the qualifier narrows where the token
         // applies, so say which selector was written through rather than
         // letting the operator meet the narrowing as a theme bug later.
         const qualifier = variantBlockQualifier(lines, variant);
@@ -338,7 +338,7 @@ function insertDarkModeOverride(lines, options) {
         return; // No @media block at all.
     const darkEntry = `    ${options.tokenName}: ${options.darkValue};`;
     if (insertionIndex === -1) {
-        // @media block exists but has no nested :root { } — the scaffold
+        // @media block exists but has no nested :root { }, so the scaffold
         // drifted. Warn and fall back to appending a fresh nested :root
         // block right before the @media block's closing brace so the
         // generated CSS still parses, rather than dropping the dark value
@@ -361,8 +361,8 @@ async function addTokenToCSS(engineDir, options, tokensCssPath) {
     await assertTokenCategoryExists(engineDir, tokensCssPath, category, options.createCategory === true);
     const content = await readText(filePath);
     const lines = content.split('\n');
-    // Per-category idempotency: a declaration in the TARGET
-    // category skips; a declaration elsewhere in the base :root block
+    // Per-category idempotency: 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);
@@ -375,7 +375,7 @@ async function addTokenToCSS(engineDir, options, tokensCssPath) {
     }
     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
+    // token insertion. The file is written exactly once, so a failure
     // between "banner declared" and "token inserted" cannot occur.
     let categoryCreated = false;
     if (options.createCategory === true && !categoryHeaderExists(lines, category)) {

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

@@ -13,13 +13,13 @@
 import type { ProjectLicense } from '../types/config.js';
 /**
  * The set of categories seeded by the default scaffold. `token add
- * --category <name>` accepts any of these without further setup; an
+ * --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 (Colors — Canvas, Spacing, …) so operators coming from
- * upstream don't have to relearn a fork-specific taxonomy.
+ * token files (the color and spacing categories listed below) so operators
+ * coming from upstream don't have to relearn a fork-specific taxonomy.
  */
 export declare const DEFAULT_TOKEN_CATEGORIES: readonly string[];
 /**
@@ -29,7 +29,7 @@ export declare const DEFAULT_TOKEN_CATEGORIES: readonly string[];
  *
  * @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`
+ * @param license - Project license, piped through `getLicenseHeader`
  *   so the scaffold is SPDX-marked and survives `fireforge lint`'s
  *   license-header checks without operator intervention.
  */

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

@@ -14,13 +14,13 @@
 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
+ * --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 (Colors — Canvas, Spacing, …) so operators coming from
- * upstream don't have to relearn a fork-specific taxonomy.
+ * 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',
@@ -35,7 +35,7 @@ export const DEFAULT_TOKEN_CATEGORIES = [
  *
  * @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`
+ * @param license - Project license, piped through `getLicenseHeader`
  *   so the scaffold is SPDX-marked and survives `fireforge lint`'s
  *   license-header checks without operator intervention.
  */

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

@@ -12,7 +12,7 @@
 import type { TokenDeclarationLocation } from './token-category.js';
 /**
  * Outcome of {@link validateVariantSelector}. `ok: true` carries the
- * normalized (quoted) selector fragment; `ok: false` carries a
+ * normalized (quoted) selector fragment. `ok: false` carries a
  * human-readable reason suitable for throwing as an `InvalidArgumentError`.
  */
 export type VariantValidation = {
@@ -27,12 +27,12 @@ export type VariantValidation = {
  * 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. That is the point: 0.44.2 widened
+ * Structure is decided by {@link rootAttributeSelector}, the matcher's own
+ * parse, rather than by a second regex. 0.44.2 widened
  * the matcher to consume consecutive `[…]` groups and stop at a pseudo-class
  * tail, and the validator did not move with it, so
  * `:root[data-skin="humanist"]:not([data-private])` was a block the tool
- * could FIND but would not let you NAME. Running both halves off one parse
+ * could find but would not let you name. Running both halves off one parse
  * is what stops them drifting apart again. Character-level safety stays a
  * separate, per-group check, because the matcher finds bracket boundaries
  * and validates no characters at all.
@@ -43,7 +43,7 @@ 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
+ * 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;
@@ -51,13 +51,13 @@ export declare function variantBlockExists(lines: string[], variant: string): bo
  * 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 semantically 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 — 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.
+ * 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"]`
@@ -72,8 +72,8 @@ export declare function variantBlockHasToken(lines: string[], variant: string, t
  * 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
+ * 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