@hominis/fireforge 0.46.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,12 +77,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 +93,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 +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.
  */
@@ -159,7 +159,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

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

@@ -12,7 +12,7 @@
  */
 import { findBlockCloseIndex, stripBlockCommentsInLines } from './token-dark-mode.js';
 /**
- * ONE attribute selector fragment: `[data-private]` (boolean attribute) or
+ * 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
@@ -26,15 +26,15 @@ import { findBlockCloseIndex, stripBlockCommentsInLines } from './token-dark-mod
 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
+ * 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.
+ * 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
@@ -67,12 +67,12 @@ function normalizeAttributeFragment(group) {
  * 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.
@@ -93,7 +93,7 @@ export function validateVariantSelector(raw) {
     if (value === '')
         return reject;
     const parts = rootAttributeSelector(`:root${value} {`);
-    // The parse must have consumed the WHOLE fragment: anything it declined to
+    // 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}`)
@@ -138,19 +138,19 @@ function canonicalSelector(selector) {
  * (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 `]`
+ * 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
+ * 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, which is precisely the half-finished
- * themed edit `THEME_ATTRIBUTE_VARIANTS` exists to prevent.
+ * 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[');
@@ -177,14 +177,14 @@ function rootAttributeSelector(line) {
  * 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
+ * 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
+    // 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}`);
@@ -193,10 +193,10 @@ function findVariantBlock(lines, variant) {
         const selector = rootAttributeSelector(line);
         if (selector === undefined || canonicalSelector(selector.attributes) !== want)
             continue;
-        // An UNqualified request still matches a qualified block: that is the
+        // An unqualified request still matches a qualified block: that is the
         // 0.44.2 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.
+        // a qualifier, though, means it, so it must match.
         if (wantQualifier !== '' && canonicalSelector(selector.qualifier) !== wantQualifier)
             continue;
         let openLine = /\{/.test(line) ? i : -1;
@@ -240,7 +240,7 @@ function findVariantBlockInsertionPoint(lines) {
 /**
  * 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 function variantBlockExists(lines, variant) {
@@ -250,13 +250,13 @@ export function variantBlockExists(lines, variant) {
  * 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"]`
@@ -275,8 +275,8 @@ export function variantBlockHasToken(lines, variant, tokenName) {
  * 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
@@ -288,11 +288,11 @@ 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
+    // 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
+    // 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