@hominis/fireforge 0.44.4 → 0.46.0

package/dist/src/core/test-stall-triage.js

@@ -38,33 +38,51 @@ const NO_OUTPUT_STALL_CONTROL_STEP = 'First, run a known-good control test. If t
  *    its manifest from `server.js` on 8888, and a survivor of an
  *    interrupted run keeps the port. Its probe is exact, and the preflight
  *    in `mochitest-server-port.ts` now refuses it before a run starts.
- *  - (3) is a single downstream report (one consumer, 3/3 reproduce and 3/3
- *    restore on one variable) whose MECHANISM was never root-caused. It is
- *    stated as the correlation it is. An earlier revision asserted "stalls
- *    first paint" as fact; that was a causal story written on top of the
- *    correlation, and a doubtful one — a failed image load in Gecko fires
- *    `error` and does not gate the document load event, and the harness's
- *    browser-ready handshake does not wait on image decode. Do not restore
- *    a mechanism claim here without a root cause to cite.
+ *  - (3) is now MECHANICAL and root-caused, replacing the correlation an
+ *    earlier revision recorded. A `chrome://` (or `resource://`) URL that
+ *    resolves to nothing reaches `CheckForBrokenChromeURL`
+ *    (netwerk/base/nsNetUtil.cpp), which outside automation only
+ *    `printf_stderr`s `Missing chrome or resource URL: <uri>` — but under
+ *    `xpc::IsInAutomation()` the same condition is
+ *    `MOZ_CRASH_UNSAFE_PRINTF("Missing chrome or resource URLs: %s")`. A
+ *    downstream reproduction symbolicated the faulting frame as
+ *    `CheckForBrokenChromeURL`, which is the established diagnosis the bar
+ *    in `mach-error-hints.ts` asks for. The discredited "stalls first
+ *    paint" story an even earlier revision asserted must not come back: a
+ *    failed image load in Gecko fires `error` and does not gate the
+ *    document load event.
  *
- * Detection (a named signature, as with the module-resolution SIGSEGV) is
- * not specified for (3) because no log line is known to key on. The bar for
- * adding one is the bar `mach-error-hints.ts` states: an established
- * diagnosis, never a plausible guess.
+ * Detection by log line is deliberately NOT specified for (3), and the
+ * reason is the mechanism itself: in the reproduction the crash landed in a
+ * CONTENT process (`plugin-container`, a child of the browser) with the
+ * crash reporter compiled out, so the harness log carried neither the crash
+ * message nor a crash line — only the no-output timeout, `Ran 0 checks`,
+ * and mochitest's "Can't trigger Breakpad, just killing process". Under
+ * automation the message is in the process that DIED, not in the log, so
+ * the census points at the two artefacts that do carry it: the OS crash
+ * report (whose faulting frame names `CheckForBrokenChromeURL`) and the
+ * out-of-automation smoke probe (which prints the non-crashing spelling
+ * and, since 0.45.0, counts it as an unallowed error so the exit code
+ * agrees with the capture).
  */
 const NO_OUTPUT_STALL_TRIAGE = [
     '  1. A sleeping or locked display on an unattended HEADED run (macOS). The browser never ' +
         'paints and never reaches its first test.',
     '  2. A headless SWGL compositor failure — re-run with --headless to separate this from (1): ' +
         'if --headless passes, the stall was display/compositor-side, not product-side.',
-    '  3. Product-side startup: the browser never reaches the state the harness waits for. One ' +
-        'downstream report correlates this stall with a broken `chrome://` image URI on the ' +
-        'startup page (reproduced and un-reproduced on that one variable); the mechanism was ' +
-        'never root-caused, so treat it as a lead, not an explanation. Discriminate with ' +
+    '  3. A broken `chrome://` or `resource://` URL reached from the startup document. Under ' +
+        'automation this is a MOZ_CRASH in whichever process opened the channel ' +
+        '(CheckForBrokenChromeURL, netwerk/base/nsNetUtil.cpp), so the browser dies before the ' +
+        'harness sees anything. Expect the log to name NOTHING: with the crash in a content ' +
+        'process and the crash reporter compiled out, the only artefacts are the OS crash report ' +
+        '(macOS: ~/Library/Logs/DiagnosticReports/plugin-container-*.ips — the faulting frame ' +
+        'reads CheckForBrokenChromeURL) and the smoke probe below. Discriminate with ' +
         '"fireforge run --smoke-exit 60 --headless --capture-console <file>", which launches the ' +
-        'same browser OUTSIDE the test harness: a clean window with no unallowed console errors ' +
-        'means product-side startup is healthy and the stall is harness- or test-side; a hang, a ' +
-        'non-zero exit, or console errors in <file> put it in the startup document.',
+        'same browser OUTSIDE automation, where the same condition only PRINTS ' +
+        '"Missing chrome or resource URL: <uri>" — a line the probe counts as an unallowed ' +
+        'error, so its exit code and its capture now agree. A clean window with no unallowed ' +
+        'console errors means product-side startup is healthy and the stall is harness- or ' +
+        'test-side.',
     '  4. A stale mochitest httpd holding the harness server port (127.0.0.1:8888). A fresh ' +
         "browser connects to THAT server, which cannot serve this run's manifest, so the run " +
         'stalls before TEST_START. Probe with "lsof -nP -iTCP:8888": any listener that is not ' +

package/dist/src/core/test-xpcshell-retry.d.ts

@@ -1,14 +1,33 @@
-import { type MachCommandResult } from './mach.js';
+import { type MachCommandResult, type MachTestSuiteKind } from './mach.js';
 export interface XpcshellRetryClassification {
     xpcshell: readonly string[];
     nonXpcshell: readonly string[];
 }
-/** Dispatches a (possibly suite-specific) mach test run, mirroring `testWithOutput`. */
-export type TestDispatch = (engineDir: string, testPaths: string[], args: string[], env?: Record<string, string>, fullOutput?: boolean) => Promise<MachCommandResult>;
+export interface XpcshellRetryOptions {
+    /** Engine checkout the run happened in. */
+    engineDir: string;
+    /** Object directory the run used, when one is configured. */
+    objDir: string | undefined;
+    /** Result of the run that may need repairing and retrying. */
+    result: MachCommandResult;
+    /** Which of the requested paths are xpcshell tests, and which are not. */
+    classification: XpcshellRetryClassification;
+    /** Test paths, normalized, as handed to mach. */
+    normalizedPaths: string[];
+    /** Extra mach arguments the run was started with. */
+    extraArgs: string[];
+    /** Environment overlay for the retried run. */
+    env?: Record<string, string> | undefined;
+    /** Mach command kind to retry with. Defaults to the generic `test`. */
+    kind?: MachTestSuiteKind | undefined;
+    /** Whether the run was started with full harness output. */
+    fullOutput?: boolean | undefined;
+}
 /**
  * Removes a stale xpcshell install symlink and retries the focused mach test
- * once. The retry uses the same `dispatch` (suite-specific or generic) the
- * caller is already running on, so an xpcshell-suite run repairs and re-runs
- * via `mach xpcshell-test` rather than falling back to the generic command.
+ * once. The retry uses the same mach command `kind` (suite-specific or
+ * generic) the caller is already running on, so an xpcshell-suite run repairs
+ * and re-runs via `mach xpcshell-test` rather than falling back to the
+ * generic command.
  */
-export declare function retryAfterXpcshellSymlinkRepair(engineDir: string, objDir: string | undefined, result: MachCommandResult, classification: XpcshellRetryClassification, normalizedPaths: string[], extraArgs: string[], env?: Record<string, string>, dispatch?: TestDispatch, fullOutput?: boolean): Promise<MachCommandResult>;
+export declare function retryAfterXpcshellSymlinkRepair(options: XpcshellRetryOptions): Promise<MachCommandResult>;

package/dist/src/core/test-xpcshell-retry.js

@@ -1,13 +1,15 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { testWithOutput } from './mach.js';
+import { runMachTestSuite } from './mach.js';
 import { tryRepairStaleXpcshellTestSymlink } from './test-stale-symlink.js';
 /**
  * Removes a stale xpcshell install symlink and retries the focused mach test
- * once. The retry uses the same `dispatch` (suite-specific or generic) the
- * caller is already running on, so an xpcshell-suite run repairs and re-runs
- * via `mach xpcshell-test` rather than falling back to the generic command.
+ * once. The retry uses the same mach command `kind` (suite-specific or
+ * generic) the caller is already running on, so an xpcshell-suite run repairs
+ * and re-runs via `mach xpcshell-test` rather than falling back to the
+ * generic command.
  */
-export async function retryAfterXpcshellSymlinkRepair(engineDir, objDir, result, classification, normalizedPaths, extraArgs, env, dispatch = testWithOutput, fullOutput) {
+export async function retryAfterXpcshellSymlinkRepair(options) {
+    const { engineDir, objDir, result, classification, normalizedPaths, extraArgs, env, kind = 'test', fullOutput, } = options;
     if (result.exitCode !== 0 &&
         classification.xpcshell.length > 0 &&
         classification.nonXpcshell.length === 0) {
@@ -15,12 +17,13 @@ export async function retryAfterXpcshellSymlinkRepair(engineDir, objDir, result,
         if (repaired) {
             // The repaired re-run is the same logical invocation, so it keeps
             // the verbosity the run was started with.
-            if (fullOutput === true) {
-                return dispatch(engineDir, normalizedPaths, extraArgs, env, true);
-            }
-            return env
-                ? dispatch(engineDir, normalizedPaths, extraArgs, env)
-                : dispatch(engineDir, normalizedPaths, extraArgs);
+            return runMachTestSuite(kind, {
+                engineDir,
+                testPaths: normalizedPaths,
+                args: extraArgs,
+                env,
+                fullOutput,
+            });
         }
     }
     return result;

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

@@ -5,6 +5,32 @@
  * agree on what "exists" means.
  */
 export declare function categoryHeaderExists(lines: string[], category: string): boolean;
+/**
+ * Scans a tokens CSS file for category header comments and returns the
+ * category names in document order. Used to enrich the "category not
+ * found" error body with concrete alternatives the operator can copy.
+ *
+ * Mirrors the shapes `findCategorySection` recognises:
+ * - Single-line: `/* = Foo = *\/`
+ * - Multi-line: `/* =====` opening, `Foo` on any of the next ~5 lines,
+ *   closing `*\/`.
+ *
+ * This helper exists as a pure inspector; it never throws on malformed
+ * headers and silently skips shapes it cannot parse.
+ */
+/**
+ * Category name declared by the banner STARTING at `index`, or `undefined`
+ * when that line opens no banner.
+ *
+ * The single reader for both banner shapes, so the inventory walk, the
+ * "available categories" error body and the section finder cannot drift on
+ * what counts as a header.
+ *
+ * @param lines - Tokens CSS split into lines
+ * @param index - 0-based line index to test
+ * @returns The declared category name, or undefined
+ */
+export declare function categoryBannerNameAt(lines: string[], index: number): string | undefined;
 /**
  * Asserts the category banner exists (or that creation was requested).
  * Throws a GeneralError naming the available categories and the
@@ -23,6 +49,13 @@ export declare function findCategorySection(lines: string[], category: string, t
     categoryLine: number;
     sectionEnd: number;
 };
+/** 0-based open/close line indices of the base `:root {` block. */
+export declare function findBaseRootBounds(lines: string[]): {
+    open: number;
+    close: number;
+} | undefined;
+/** Masks block-comment content per line so declarations inside comments never match. */
+export declare function maskCommentLines(lines: string[]): string[];
 /** Location of an existing base-`:root` token declaration. */
 export interface TokenDeclarationLocation {
     /** 1-based line number in the tokens CSS file. */

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

@@ -20,8 +20,8 @@ function multiLineBlockNameMatches(blockLine, category) {
     return blockLine.replace(/^\s*\*\s*/, '').trim() === category;
 }
 /**
- * Body of the first `/* … *\/` comment on `line`, or `null` when the line
- * carries no closed block comment.
+ * Body of the first `/* … *\/` comment on `line`, or `undefined` when the
+ * line carries no closed block comment.
  *
  * Deliberately index arithmetic rather than a regex: every regex spelling of
  * "banner comment" this module used to carry was super-linear on a line that
@@ -32,10 +32,10 @@ function multiLineBlockNameMatches(blockLine, category) {
 function blockCommentBody(line) {
     const open = line.indexOf('/*');
     if (open === -1)
-        return null;
+        return undefined;
     const close = line.indexOf('*/', open + 2);
     if (close === -1)
-        return null;
+        return undefined;
     return line.slice(open + 2, close);
 }
 /**
@@ -49,14 +49,15 @@ function isSingleLineBannerLine(line) {
     return body !== undefined && body.length >= 2 && body.startsWith('=') && body.endsWith('=');
 }
 /**
- * Name declared by a single-line banner (`/* = Foo = *\/` → `Foo`), or `null`
- * when the line is not a named banner. The `=` runs on both sides are
- * required; a decorative all-`=` rule carries no name and yields `null`.
+ * Name declared by a single-line banner (`/* = Foo = *\/` → `Foo`), or
+ * `undefined` when the line is not a named banner. The `=` runs on both sides
+ * are required; a decorative all-`=` rule carries no name and yields
+ * `undefined`.
  */
 function singleLineBannerName(line) {
     const body = blockCommentBody(line);
-    if (body === null)
-        return null;
+    if (body === undefined)
+        return undefined;
     let start = 0;
     let end = body.length;
     while (start < end && /\s/.test(body[start] ?? ''))
@@ -65,16 +66,16 @@ function singleLineBannerName(line) {
     while (start < end && body[start] === '=')
         start++;
     if (start === leadingEqStart)
-        return null;
+        return undefined;
     while (end > start && /\s/.test(body[end - 1] ?? ''))
         end--;
     const trailingEqEnd = end;
     while (end > start && body[end - 1] === '=')
         end--;
     if (end === trailingEqEnd)
-        return null;
+        return undefined;
     const name = body.slice(start, end).trim();
-    return name.length > 0 ? name : null;
+    return name.length > 0 ? name : undefined;
 }
 /**
  * True when `lines` contain a category header (single-line or multi-line
@@ -84,8 +85,7 @@ function singleLineBannerName(line) {
  */
 export function categoryHeaderExists(lines, category) {
     const singleLinePattern = singleLineBannerPattern(category);
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? '';
+    for (const [i, line] of lines.entries()) {
         if (singleLinePattern.test(line)) {
             return true;
         }
@@ -115,29 +115,44 @@ export function categoryHeaderExists(lines, category) {
  * This helper exists as a pure inspector; it never throws on malformed
  * headers and silently skips shapes it cannot parse.
  */
+/**
+ * Category name declared by the banner STARTING at `index`, or `undefined`
+ * when that line opens no banner.
+ *
+ * The single reader for both banner shapes, so the inventory walk, the
+ * "available categories" error body and the section finder cannot drift on
+ * what counts as a header.
+ *
+ * @param lines - Tokens CSS split into lines
+ * @param index - 0-based line index to test
+ * @returns The declared category name, or undefined
+ */
+export function categoryBannerNameAt(lines, index) {
+    const line = lines[index] ?? '';
+    const extracted = singleLineBannerName(line);
+    if (extracted !== undefined)
+        return extracted;
+    if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
+        for (let j = index + 1; j < Math.min(index + 6, lines.length); j++) {
+            const blockLine = lines[j] ?? '';
+            if (/\*\//.test(blockLine))
+                break;
+            const trimmed = blockLine.replace(/^\s*\*\s*/, '').trim();
+            if (trimmed.length === 0)
+                continue;
+            if (/^=+$/.test(trimmed))
+                continue;
+            return trimmed;
+        }
+    }
+    return undefined;
+}
 function discoverCategoryHeaders(lines) {
     const categories = new Set();
     for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        const extracted = singleLineBannerName(line);
-        if (extracted !== null) {
-            categories.add(extracted);
-            continue;
-        }
-        if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
-            for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
-                const blockLine = lines[j] ?? '';
-                if (/\*\//.test(blockLine))
-                    break;
-                const trimmed = blockLine.replace(/^\s*\*\s*/, '').trim();
-                if (trimmed.length === 0)
-                    continue;
-                if (/^=+$/.test(trimmed))
-                    continue;
-                categories.add(trimmed);
-                break;
-            }
-        }
+        const name = categoryBannerNameAt(lines, i);
+        if (name !== undefined)
+            categories.add(name);
     }
     return [...categories];
 }
@@ -177,7 +192,7 @@ export async function assertTokenCategoryExists(engineDir, tokensCssPath, catego
  */
 export function declareCategoryBanner(lines, category, tokensCssPath) {
     const bounds = findBaseRootBounds(lines);
-    if (bounds === null) {
+    if (bounds === undefined) {
         throw new GeneralError(`Cannot create category "${category}": no :root block found in ${tokensCssPath}. ` +
             'Run "fireforge furnace init --force" to re-scaffold the tokens CSS file.');
     }
@@ -190,8 +205,7 @@ export function declareCategoryBanner(lines, category, tokensCssPath) {
 export function findCategorySection(lines, category, tokensCssPath) {
     const singleLinePattern = singleLineBannerPattern(category);
     let categoryLine = -1;
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i] ?? '';
+    for (const [i, line] of lines.entries()) {
         // Check single-line format: /* = Category = */
         if (singleLinePattern.test(line)) {
             categoryLine = i;
@@ -245,16 +259,10 @@ export function findCategorySection(lines, category, tokensCssPath) {
     return { categoryLine, sectionEnd };
 }
 /** 0-based open/close line indices of the base `:root {` block. */
-function findBaseRootBounds(lines) {
-    let open = -1;
-    for (let i = 0; i < lines.length; i++) {
-        if (/:root\s*\{/.test(lines[i] ?? '')) {
-            open = i;
-            break;
-        }
-    }
+export function findBaseRootBounds(lines) {
+    const open = lines.findIndex((line) => /:root\s*\{/.test(line));
     if (open === -1)
-        return null;
+        return undefined;
     for (let i = open + 1; i < lines.length; i++) {
         if (/^\s*\}/.test(lines[i] ?? '')) {
             return { open, close: i };
@@ -263,7 +271,7 @@ function findBaseRootBounds(lines) {
     return { open, close: -1 };
 }
 /** Masks block-comment content per line so declarations inside comments never match. */
-function maskCommentLines(lines) {
+export function maskCommentLines(lines) {
     const masked = lines.join('\n').replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '));
     return masked.split('\n');
 }
@@ -276,7 +284,7 @@ function maskCommentLines(lines) {
  */
 export function findTokenDeclarationInRoot(lines, tokenName) {
     const bounds = findBaseRootBounds(lines);
-    if (bounds === null || bounds.close === -1)
+    if (bounds === undefined || bounds.close === -1)
         return undefined;
     const masked = maskCommentLines(lines);
     const declPattern = new RegExp(`^\\s*${escapeRegex(tokenName)}\\s*:`);

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

@@ -87,13 +87,7 @@ export function stripBlockCommentsInLines(lines) {
  */
 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
@@ -172,13 +166,7 @@ export function findBlockCloseIndex(stripped, startLine) {
  */
 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-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 —
+ * 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.
+ *
+ * Deliberately 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.
+ *
+ * @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 deliberately 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.
+ *
+ * Deliberately 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.
+ *
+ * @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.
  */

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

@@ -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}.`);
 }
 /**