@hominis/fireforge 0.46.0 → 0.46.2

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

@@ -2,8 +2,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
@@ -19,28 +19,36 @@
  * 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.
+ *
+ * Spans are copied with `indexOf` + `slice` rather than appended one
+ * character at a time. The per-character form allocated a rope link per
+ * character of every line in `tokens.css`, which on a long line cost far
+ * more than the scan it feeds: blanking a 1.6 MB line took ~39 ms against
+ * ~0.07 ms here, and the GC that pressure provoked grew faster than the
+ * input did — enough to make the scanners' linearity test read as
+ * super-linear on a loaded runner.
  */
 export declare function stripBlockCommentsInLines(lines: string[]): string[];
 /**
  * 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 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
+ * 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.
  */
@@ -48,7 +56,7 @@ export declare function findBlockCloseIndex(stripped: string[], startLine: numbe
 /**
  * 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.

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,36 +38,49 @@ 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.
+ *
+ * Spans are copied with `indexOf` + `slice` rather than appended one
+ * character at a time. The per-character form allocated a rope link per
+ * character of every line in `tokens.css`, which on a long line cost far
+ * more than the scan it feeds: blanking a 1.6 MB line took ~39 ms against
+ * ~0.07 ms here, and the GC that pressure provoked grew faster than the
+ * input did — enough to make the scanners' linearity test read as
+ * super-linear on a loaded runner.
  */
 export function stripBlockCommentsInLines(lines) {
     const out = [];
     let inBlockComment = false;
     for (const original of lines) {
+        // A line with no comment to enter or leave is already its own mirror.
+        if (!inBlockComment && !original.includes('/*')) {
+            out.push(original);
+            continue;
+        }
         let line = '';
-        for (let i = 0; i < original.length; i++) {
+        let i = 0;
+        while (i < original.length) {
             if (inBlockComment) {
-                if (original[i] === '*' && original[i + 1] === '/') {
-                    line += '  ';
-                    i += 1;
-                    inBlockComment = false;
-                }
-                else {
-                    line += ' ';
+                const end = original.indexOf('*/', i);
+                if (end === -1) {
+                    line += ' '.repeat(original.length - i);
+                    break;
                 }
-            }
-            else if (original[i] === '/' && original[i + 1] === '*') {
-                line += '  ';
-                i += 1;
-                inBlockComment = true;
+                line += ' '.repeat(end + 2 - i);
+                i = end + 2;
+                inBlockComment = false;
             }
             else {
-                // `original[i]` is provably defined here (the bounds check is
-                // the loop condition), but TS narrows it to `string | undefined`.
-                // Default to empty string so the concat stays well-typed.
-                line += original[i] ?? '';
+                const start = original.indexOf('/*', i);
+                if (start === -1) {
+                    line += original.slice(i);
+                    break;
+                }
+                line += `${original.slice(i, start)}  `;
+                i = start + 2;
+                inBlockComment = true;
             }
         }
         out.push(line);
@@ -77,12 +90,12 @@ 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) {
@@ -93,7 +106,7 @@ export function findDarkRootInsertionIndex(lines) {
     // 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] ?? '';
@@ -121,14 +134,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.
  */
@@ -159,7 +172,7 @@ 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.

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

@@ -9,9 +9,9 @@ export interface TokenInventoryEntry {
 }
 /**
  * Tokens grouped under the banner that precedes them, in file order.
- * `category` is null for declarations that sit above the first banner —
- * a real state in a hand-edited file, and one the report must show rather
- * than silently drop.
+ * `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;
@@ -21,7 +21,7 @@ export interface TokenCategoryInventory {
 export interface TokenBlockValue {
     /**
      * Selector trail of the declaring block, outermost first, joined with
-     * ` > ` — for example `:root` or
+     * ` > `. For example `:root` or
      * `@media (prefers-color-scheme: dark) > :root`.
      */
     block: string;
@@ -45,9 +45,9 @@ export declare function collectTokenInventory(lines: string[]): TokenCategoryInv
  * Every declaration of `tokenName`, in every block of the file, labelled by
  * the selector trail of the block that declares it.
  *
- * Deliberately not restricted to the base `:root`: the question `token show`
+ * 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 precisely the case worth seeing.
+ * 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 `--`

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

@@ -5,9 +5,9 @@
  * 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
+ * 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 deliberately reuses the banner and
+ * 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
@@ -35,7 +35,7 @@ export function collectTokenInventory(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
+        // 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) {
@@ -60,9 +60,9 @@ export function collectTokenInventory(lines) {
  * Every declaration of `tokenName`, in every block of the file, labelled by
  * the selector trail of the block that declares it.
  *
- * Deliberately not restricted to the base `:root`: the question `token show`
+ * 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 precisely the case worth seeing.
+ * 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 `--`
@@ -84,8 +84,8 @@ export function collectTokenBlockValues(lines, tokenName) {
         }
         // 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.
+        // 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));

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

@@ -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);
@@ -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