@hominis/fireforge 0.15.1 → 0.15.3

package/dist/src/core/build-baseline.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Persists a marker describing the state of the engine tree at the time of
+ * the last successful `fireforge build`. Two downstream consumers share this
+ * marker:
+ *
+ *   - `build-audit`: after a build succeeds, compare engine files touched
+ *     since the baseline against the dist bundle to flag silent
+ *     packaging drops (e.g. a pref file never registered in moz.build).
+ *   - `build-prepare`: before a build starts, detect whether any
+ *     `moz.build` / `moz.configure` / `Makefile.in` changed since the
+ *     baseline and run `mach configure` before the build step so the
+ *     recursive-make backend isn't stale.
+ *
+ * The marker lives under `.fireforge/last-build.json`. It is written only
+ * on successful build completion; a failed build does not update it, so a
+ * subsequent run still audits against the last known-good tree.
+ */
+/** Shape of the on-disk baseline marker. */
+export interface BuildBaseline {
+    /** SHA of engine HEAD at the time the build succeeded. */
+    engineHeadSha: string;
+    /**
+     * ISO-8601 timestamp of when the baseline was recorded. Informational —
+     * downstream code keys off `engineHeadSha` for diffs, but the timestamp
+     * helps operators reason about stale markers.
+     */
+    builtAt: string;
+    /**
+     * The binaryName used at build time. Captured so the dist-tree audit
+     * can resolve the expected bundle root under obj-star/dist/ even when
+     * the project has since been renamed.
+     */
+    binaryName: string;
+}
+/** Name of the last-build marker file under `.fireforge/`. */
+export declare const BUILD_BASELINE_FILENAME = "last-build.json";
+/**
+ * Resolves the on-disk path of the build baseline marker.
+ * @param projectRoot - Root directory of the project
+ * @returns Absolute path of the marker file
+ */
+export declare function getBuildBaselinePath(projectRoot: string): string;
+/**
+ * Reads the last-build baseline if present. Returns undefined when no
+ * previous successful build has been recorded — callers must tolerate that
+ * path (first build, cleaned workspace).
+ * @param projectRoot - Root directory of the project
+ */
+export declare function readBuildBaseline(projectRoot: string): Promise<BuildBaseline | undefined>;
+/**
+ * Records a successful build by writing a fresh baseline marker. Captures
+ * engine HEAD SHA (or an empty string when the engine has no HEAD yet) and
+ * the current binaryName. Caller is responsible for only invoking this
+ * after the build exit code was zero.
+ * @param projectRoot - Root directory of the project
+ * @param engineDir - Path to the engine directory
+ * @param binaryName - Current `binaryName` from fireforge.json
+ */
+export declare function writeBuildBaseline(projectRoot: string, engineDir: string, binaryName: string): Promise<void>;

package/dist/src/core/build-baseline.js

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Persists a marker describing the state of the engine tree at the time of
+ * the last successful `fireforge build`. Two downstream consumers share this
+ * marker:
+ *
+ *   - `build-audit`: after a build succeeds, compare engine files touched
+ *     since the baseline against the dist bundle to flag silent
+ *     packaging drops (e.g. a pref file never registered in moz.build).
+ *   - `build-prepare`: before a build starts, detect whether any
+ *     `moz.build` / `moz.configure` / `Makefile.in` changed since the
+ *     baseline and run `mach configure` before the build step so the
+ *     recursive-make backend isn't stale.
+ *
+ * The marker lives under `.fireforge/last-build.json`. It is written only
+ * on successful build completion; a failed build does not update it, so a
+ * subsequent run still audits against the last known-good tree.
+ */
+import { join } from 'node:path';
+import { pathExists, readJson, writeJson } from '../utils/fs.js';
+import { FIREFORGE_DIR } from './config-paths.js';
+import { getHead, isMissingHeadError } from './git.js';
+/** Name of the last-build marker file under `.fireforge/`. */
+export const BUILD_BASELINE_FILENAME = 'last-build.json';
+/**
+ * Resolves the on-disk path of the build baseline marker.
+ * @param projectRoot - Root directory of the project
+ * @returns Absolute path of the marker file
+ */
+export function getBuildBaselinePath(projectRoot) {
+    return join(projectRoot, FIREFORGE_DIR, BUILD_BASELINE_FILENAME);
+}
+/**
+ * Reads the last-build baseline if present. Returns undefined when no
+ * previous successful build has been recorded — callers must tolerate that
+ * path (first build, cleaned workspace).
+ * @param projectRoot - Root directory of the project
+ */
+export async function readBuildBaseline(projectRoot) {
+    const path = getBuildBaselinePath(projectRoot);
+    if (!(await pathExists(path))) {
+        return undefined;
+    }
+    try {
+        return await readJson(path);
+    }
+    catch {
+        // A corrupt marker is equivalent to no marker — the audit/auto-configure
+        // will treat it as "first build" rather than block on the inconsistency.
+        return undefined;
+    }
+}
+/**
+ * Records a successful build by writing a fresh baseline marker. Captures
+ * engine HEAD SHA (or an empty string when the engine has no HEAD yet) and
+ * the current binaryName. Caller is responsible for only invoking this
+ * after the build exit code was zero.
+ * @param projectRoot - Root directory of the project
+ * @param engineDir - Path to the engine directory
+ * @param binaryName - Current `binaryName` from fireforge.json
+ */
+export async function writeBuildBaseline(projectRoot, engineDir, binaryName) {
+    let engineHeadSha = '';
+    try {
+        engineHeadSha = await getHead(engineDir);
+    }
+    catch (error) {
+        // Engine may be an unborn branch (freshly cloned + reset, or mid-import)
+        // — record an empty SHA and let downstream fall back to "no prior state"
+        // behavior. Any other git failure is bubbled up; we don't want to
+        // silently write a garbage marker.
+        if (!isMissingHeadError(error)) {
+            throw error;
+        }
+    }
+    const baseline = {
+        engineHeadSha,
+        builtAt: new Date().toISOString(),
+        binaryName,
+    };
+    await writeJson(getBuildBaselinePath(projectRoot), baseline);
+}
+//# sourceMappingURL=build-baseline.js.map

package/dist/src/core/build-prepare.d.ts

@@ -3,13 +3,32 @@
  * story cleanup, branding setup, Furnace component application, and mozconfig generation.
  */
 import type { FireForgeConfig, ProjectPaths } from '../types/config.js';
+import type { BuildBaseline } from './build-baseline.js';
 /**
  * Result of the build preparation phase.
  */
 export interface BuildPreparation {
     /** Number of Furnace components applied (0 if none or no furnace.json) */
     furnaceApplied: number;
+    /** True when `mach configure` was auto-run to refresh a stale backend. */
+    reconfigured: boolean;
 }
+/** Options for {@link prepareBuildEnvironment}. */
+export interface PrepareBuildOptions {
+    /**
+     * Previous successful-build baseline, used to detect `moz.build` /
+     * `moz.configure` / `Makefile.in` changes that require a fresh
+     * `mach configure` before the build. When undefined, the auto-configure
+     * step is skipped — there's no reference point for what "changed since"
+     * means.
+     */
+    previousBaseline?: BuildBaseline | undefined;
+}
+/**
+ * Returns true when the file path matches a pattern that forces
+ * `mach configure` to regenerate the backend. Exported for testing.
+ */
+export declare function isBackendInvalidatingFile(path: string): boolean;
 /**
  * Runs the shared pre-flight steps for build and package commands:
  * 1. Cleans Furnace stories from engine (prevents leaking into production)
@@ -22,4 +41,4 @@ export interface BuildPreparation {
  * @param config - Loaded FireForge configuration
  * @returns Preparation results
  */
-export declare function prepareBuildEnvironment(projectRoot: string, paths: ProjectPaths, config: FireForgeConfig): Promise<BuildPreparation>;
+export declare function prepareBuildEnvironment(projectRoot: string, paths: ProjectPaths, config: FireForgeConfig, options?: PrepareBuildOptions): Promise<BuildPreparation>;

package/dist/src/core/build-prepare.js

@@ -4,14 +4,72 @@
  * story cleanup, branding setup, Furnace component application, and mozconfig generation.
  */
 import { FurnaceError } from '../errors/furnace.js';
+import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
-import { spinner, warn } from '../utils/logger.js';
+import { info, spinner, verbose, warn } from '../utils/logger.js';
 import { isBrandingSetup, setupBranding } from './branding.js';
 import { applyAllComponents } from './furnace-apply.js';
 import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceState, } from './furnace-config.js';
 import { runFurnaceMutation } from './furnace-operation.js';
 import { cleanStories } from './furnace-stories.js';
-import { generateMozconfig } from './mach.js';
+import { hasChanges, isMissingHeadError } from './git.js';
+import { git } from './git-base.js';
+import { getUntrackedFiles } from './git-status.js';
+import { generateMozconfig, runMach } from './mach.js';
+/** Path fragments of files whose edits invalidate the recursive-make backend. */
+const BACKEND_INVALIDATING_SUFFIXES = ['moz.build', 'moz.configure', 'Makefile.in'];
+/**
+ * Returns true when the file path matches a pattern that forces
+ * `mach configure` to regenerate the backend. Exported for testing.
+ */
+export function isBackendInvalidatingFile(path) {
+    for (const suffix of BACKEND_INVALIDATING_SUFFIXES) {
+        if (path === suffix || path.endsWith(`/${suffix}`))
+            return true;
+    }
+    return false;
+}
+/**
+ * Collects engine-relative paths of files changed since the baseline's HEAD
+ * SHA plus any workdir modifications. Defensive — git failures surface as
+ * verbose lines and return the files collected so far. An empty result
+ * means "no drift we can prove" rather than "no drift occurred".
+ */
+async function collectBackendRelevantChanges(engineDir, baseline) {
+    const collected = new Set();
+    if (baseline.engineHeadSha) {
+        try {
+            const diff = await git(['diff', '--name-only', `${baseline.engineHeadSha}..HEAD`], engineDir);
+            for (const line of diff.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed)
+                    collected.add(trimmed);
+            }
+        }
+        catch (error) {
+            if (!isMissingHeadError(error)) {
+                verbose(`Auto-configure: could not diff engine against baseline — ${toError(error).message}`);
+            }
+        }
+    }
+    try {
+        if (await hasChanges(engineDir)) {
+            const worktreeDiff = await git(['diff', '--name-only', 'HEAD'], engineDir);
+            for (const line of worktreeDiff.split('\n')) {
+                const trimmed = line.trim();
+                if (trimmed)
+                    collected.add(trimmed);
+            }
+            for (const file of await getUntrackedFiles(engineDir)) {
+                collected.add(file);
+            }
+        }
+    }
+    catch (error) {
+        verbose(`Auto-configure: could not enumerate workdir changes — ${toError(error).message}`);
+    }
+    return [...collected];
+}
 /**
  * Runs the shared pre-flight steps for build and package commands:
  * 1. Cleans Furnace stories from engine (prevents leaking into production)
@@ -24,7 +82,7 @@ import { generateMozconfig } from './mach.js';
  * @param config - Loaded FireForge configuration
  * @returns Preparation results
  */
-export async function prepareBuildEnvironment(projectRoot, paths, config) {
+export async function prepareBuildEnvironment(projectRoot, paths, config, options = {}) {
     // Block the build if Furnace has an unresolved repair marker. This prevents
     // building against an engine that may be in an inconsistent state after a
     // failed rollback.
@@ -36,6 +94,33 @@ export async function prepareBuildEnvironment(projectRoot, paths, config) {
                 'Run "fireforge doctor --repair-furnace" to reconcile engine state before building.');
         }
     }
+    // Auto-configure: if any backend-invalidating file (moz.build, moz.configure,
+    // Makefile.in) changed since the last successful build, run `mach configure`
+    // before the build step. Prevents incremental builds from silently skipping
+    // work against a stale recursive-make backend.
+    let reconfigured = false;
+    if (options.previousBaseline) {
+        const changed = await collectBackendRelevantChanges(paths.engine, options.previousBaseline);
+        const invalidating = changed.filter(isBackendInvalidatingFile);
+        if (invalidating.length > 0) {
+            info(`Backend config changed; running mach configure first... (${invalidating.length} file${invalidating.length === 1 ? '' : 's'} touched)`);
+            const configureSpinner = spinner('Running mach configure...');
+            try {
+                const exitCode = await runMach(['configure'], paths.engine);
+                if (exitCode !== 0) {
+                    configureSpinner.error('mach configure exited non-zero; continuing with build anyway');
+                }
+                else {
+                    configureSpinner.stop('Backend regenerated');
+                    reconfigured = true;
+                }
+            }
+            catch (error) {
+                configureSpinner.error('mach configure failed; continuing with build anyway');
+                verbose(`Auto-configure error: ${toError(error).message}`);
+            }
+        }
+    }
     // Clean stories before build to ensure they don't leak into production binary
     await cleanStories(paths.engine);
     // Set up custom branding directory and patch moz.configure
@@ -95,7 +180,12 @@ export async function prepareBuildEnvironment(projectRoot, paths, config) {
                 throw new FurnaceError(`${totalApplyFailures} component${totalApplyFailures === 1 ? '' : 's'} failed to apply cleanly`);
             }
             if (furnaceApplied > 0) {
+                const appliedNames = result.applied.map((entry) => entry.name).join(', ');
                 furnaceSpinner.stop(`Applied ${furnaceApplied} component${furnaceApplied === 1 ? '' : 's'}`);
+                // Loud banner: the build operator needs to see that engine/ was
+                // updated before this build, otherwise a silent re-apply is
+                // indistinguishable from a build that shipped stale components.
+                info(`Furnace: source → engine sync wrote ${furnaceApplied} component${furnaceApplied === 1 ? '' : 's'} before build (${appliedNames}). engine/ now matches components/.`);
             }
             else {
                 furnaceSpinner.stop('Components up to date');
@@ -112,6 +202,6 @@ export async function prepareBuildEnvironment(projectRoot, paths, config) {
         mozconfigSpinner.error('Failed to generate mozconfig');
         throw error;
     }
-    return { furnaceApplied };
+    return { furnaceApplied, reconfigured };
 }
 //# sourceMappingURL=build-prepare.js.map

package/dist/src/core/furnace-apply-helpers.d.ts

@@ -94,7 +94,7 @@ export declare function hasCustomEngineDrift(root: string, name: string, compone
 export interface CustomApplyOptions {
     /**
      * Trailing project marker appended to inserted `customElements.js` entries
-     * (e.g. `"HOMINIS"` emits `  // HOMINIS:` on each line). Mirrors the
+     * (e.g. `"MYBROWSER"` emits `  // MYBROWSER:` on each line). Mirrors the
      * `markerComment` field in fireforge.json.
      */
     markerComment?: string;

package/dist/src/core/furnace-config-tokens.d.ts

@@ -9,3 +9,9 @@
  * violation; does nothing for `undefined` (field is optional).
  */
 export declare function validateTokenHostDocuments(raw: unknown): void;
+/**
+ * Validates a `runtimeVariables` raw value. Each entry must start with `--`
+ * (it is a CSS custom property name). Throws `FurnaceError` on violation;
+ * does nothing for `undefined` (field is optional).
+ */
+export declare function validateRuntimeVariables(raw: unknown): void;

package/dist/src/core/furnace-config-tokens.js

@@ -25,4 +25,19 @@ export function validateTokenHostDocuments(raw) {
         }
     }
 }
+/**
+ * Validates a `runtimeVariables` raw value. Each entry must start with `--`
+ * (it is a CSS custom property name). Throws `FurnaceError` on violation;
+ * does nothing for `undefined` (field is optional).
+ */
+export function validateRuntimeVariables(raw) {
+    if (raw === undefined)
+        return;
+    const vars = parseStringArray(raw, 'runtimeVariables');
+    for (const name of vars) {
+        if (!name.startsWith('--')) {
+            throw new FurnaceError(`Furnace config: "runtimeVariables" entries must start with "--" (got ${JSON.stringify(name)})`);
+        }
+    }
+}
 //# sourceMappingURL=furnace-config-tokens.js.map

package/dist/src/core/furnace-config.js

@@ -7,7 +7,7 @@ import { warn } from '../utils/logger.js';
 import { isExplicitAbsolutePath } from '../utils/paths.js';
 import { isArray, isBoolean, isObject, isString } from '../utils/validation.js';
 import { FIREFORGE_DIR } from './config.js';
-import { validateTokenHostDocuments } from './furnace-config-tokens.js';
+import { validateRuntimeVariables, validateTokenHostDocuments } from './furnace-config-tokens.js';
 import { resolveFtlDir } from './furnace-constants.js';
 import { detectComposesCycles, validateComposesReferences } from './furnace-graph-utils.js';
 import { quarantineStateFile, withStateFileLock } from './state-file.js';
@@ -183,6 +183,9 @@ export function validateFurnaceConfig(data) {
     if (migrated['tokenAllowlist'] !== undefined) {
         parseStringArray(migrated['tokenAllowlist'], 'tokenAllowlist');
     }
+    // Validate optional runtimeVariables — CSS runtime state channels
+    // (e.g. `--cam-x`) that are exempt from `token-prefix-violation`.
+    validateRuntimeVariables(migrated['runtimeVariables']);
     // Validate optional tokenHostDocuments — list of chrome XHTMLs that the
     // `missing-token-link` validator scans for the tokens CSS link.
     validateTokenHostDocuments(migrated['tokenHostDocuments']);
@@ -236,14 +239,17 @@ export function validateFurnaceConfig(data) {
         overrides,
         custom,
     };
-    if (migrated['tokenPrefix'] !== undefined) {
+    if (migrated['tokenPrefix'] !== undefined)
         config.tokenPrefix = migrated['tokenPrefix'];
-    }
     if (migrated['tokenAllowlist'] !== undefined) {
         config.tokenAllowlist = parseStringArray(migrated['tokenAllowlist'], 'tokenAllowlist');
     }
+    if (migrated['runtimeVariables'] !== undefined) {
+        config.runtimeVariables = parseStringArray(migrated['runtimeVariables'], 'runtimeVariables');
+    }
     if (migrated['tokenHostDocuments'] !== undefined) {
-        config.tokenHostDocuments = parseStringArray(migrated['tokenHostDocuments'], 'tokenHostDocuments');
+        const docs = parseStringArray(migrated['tokenHostDocuments'], 'tokenHostDocuments');
+        config.tokenHostDocuments = docs;
     }
     // Validate optional ftlBasePath
     if (migrated['ftlBasePath'] !== undefined) {

package/dist/src/core/furnace-operation.d.ts

@@ -4,7 +4,8 @@ import { type RollbackJournal } from './furnace-rollback.js';
  * The signal names the lifecycle wrapper knows how to react to. Spelled out
  * as a literal union (rather than `NodeJS.Signals`) so the public type
  * surface does not depend on the NodeJS global namespace — consumers of
- * `@hominis/fireforge` may compile against tsconfigs that omit `@types/node`.
+ * FireForge's published scoped npm package may compile against tsconfigs
+ * that omit `@types/node`.
  */
 export type FurnaceShutdownSignal = 'SIGINT' | 'SIGTERM';
 /**

package/dist/src/core/furnace-operation.js

@@ -52,16 +52,22 @@ function withTimeout(promise, ms, label) {
  * timeout so a stuck I/O operation cannot hang the process indefinitely.
  */
 export async function rollbackActiveOperationsForSignal(signal) {
+    // Snapshot the active operations so we don't race with `runFurnaceMutation`
+    // clearing slots during normal completion. Filter completed bodies so a
+    // body sitting in its finally-block cleanup window is not counted as live
+    // work — this would mis-trigger the rollback banner for plain `fireforge
+    // run` (which never registers a mutation but can receive SIGTERM).
+    const snapshot = [...activeOperations.values()].filter((op) => !op.completed);
+    if (snapshot.length === 0) {
+        // Nothing to roll back. Stay silent so commands that never mutated (run,
+        // watch, test, doctor) don't print an alarming "rolling back mutations"
+        // line on Ctrl+C / SIGTERM. Leave `signalRollbackInFlight` false so a
+        // subsequent registrant can still trigger the full path.
+        return;
+    }
     signalRollbackInFlight = true;
     warn(`Received ${signal}; rolling back in-flight furnace mutations…`);
-    // Snapshot the active operations so we don't race with `runFurnaceMutation`
-    // clearing slots during normal completion.
-    const snapshot = [...activeOperations.values()];
     for (const op of snapshot) {
-        // If the body completed successfully and is in its finally-block cleanup
-        // (deleting the token), skip rollback — the mutation committed cleanly.
-        if (op.completed)
-            continue;
         const cleanupErrors = [];
         // Run extra cleanup callbacks first (e.g. preview's cleanStories), so the
         // engine is in its tidiest possible shape before the journal restore

package/dist/src/core/furnace-registration-ast.d.ts

@@ -8,8 +8,8 @@
  */
 export interface RegistrationWriteOptions {
     /**
-     * Trailing project marker appended to every inserted line (e.g. `"HOMINIS"`
-     * produces `  // HOMINIS:` at end-of-line). Keeps modifications discoverable
+     * Trailing project marker appended to every inserted line (e.g. `"MYBROWSER"`
+     * produces `  // MYBROWSER:` at end-of-line). Keeps modifications discoverable
      * without requiring the operator to hand-tag them post-apply.
      */
     markerComment?: string;

package/dist/src/core/furnace-registration-ast.js

@@ -16,7 +16,7 @@ import { validateRegistrationPlacement, validateTagName } from './furnace-regist
 /**
  * Returns true when `content` already contains a registration for `tagName`.
  *
- * Tolerates trailing line comments (e.g. a project marker like `// HOMINIS:`)
+ * Tolerates trailing line comments (e.g. a project marker like `// MYBROWSER:`)
  * that an operator may have appended to entries written by a previous apply.
  * Without this, a re-apply would insert a duplicate entry, and the second
  * `setElementCreationCallback` at window-load would throw `NotSupportedError`.

package/dist/src/core/furnace-validate-compatibility.js

@@ -2,7 +2,7 @@
 import { join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
 import { hasRawCssColors } from '../utils/regex.js';
-import { classExtendsMozLitElement, collectCssVariableReferences, createIssue, getTokenPrefixContext, hasCustomElementDefineCall, hasRelativeModuleImport, stripCssBlockComments, } from './furnace-validate-helpers.js';
+import { classExtendsMozLitElement, collectCssVariableDeclarations, collectCssVariableReferences, createIssue, getTokenPrefixContext, hasCustomElementDefineCall, hasRelativeModuleImport, stripCssBlockComments, } from './furnace-validate-helpers.js';
 async function validateMjsCompatibility(mjsPath, tagName) {
     if (!(await pathExists(mjsPath)))
         return [];
@@ -29,13 +29,24 @@ async function validateCssCompatibility(cssPath, tagName, type, config, root) {
         issues.push(createIssue(tagName, 'error', 'raw-color-value', 'Raw color value found. Use CSS custom properties (var(--...)) for design token consistency.'));
     }
     if (config?.tokenPrefix) {
-        const { allowlist, inheritedOverrideVars } = await getTokenPrefixContext(tagName, type, config, root);
+        const { allowlist, inheritedOverrideVars, runtimeVariables } = await getTokenPrefixContext(tagName, type, config, root);
+        // Auto-exempt component-local runtime channels: a CSS custom property
+        // both declared and consumed in the same file is a runtime state
+        // channel (e.g. `--cam-x`), not a design-token reference. See
+        // `runtimeVariables` in furnace.json for cross-component cases.
+        const localDeclarations = collectCssVariableDeclarations(cssContent);
         for (const prop of collectCssVariableReferences(cssContent)) {
-            if (!prop.startsWith(config.tokenPrefix) &&
-                !allowlist.has(prop) &&
-                !inheritedOverrideVars.has(prop)) {
-                issues.push(createIssue(tagName, 'error', 'token-prefix-violation', `CSS references var(${prop}) which does not match the required token prefix "${config.tokenPrefix}". Use a design token or add to tokenAllowlist.`));
-            }
+            if (prop.startsWith(config.tokenPrefix))
+                continue;
+            if (allowlist.has(prop))
+                continue;
+            if (inheritedOverrideVars.has(prop))
+                continue;
+            if (runtimeVariables.has(prop))
+                continue;
+            if (localDeclarations.has(prop))
+                continue;
+            issues.push(createIssue(tagName, 'error', 'token-prefix-violation', `CSS references var(${prop}) which does not match the required token prefix "${config.tokenPrefix}". Use a design token, add to tokenAllowlist, or (for runtime state channels) list the variable in runtimeVariables.`));
         }
     }
     // Flag excessive !important usage

package/dist/src/core/furnace-validate-helpers.d.ts

@@ -21,7 +21,25 @@ export declare function hasTemplateKeyboardHandler(content: string): boolean;
  * interactive element — those already fire `click` on keyboard activation.
  */
 export declare function hasTemplateClickOnSyntheticInteractive(content: string): boolean;
-/** Detects hardcoded user-visible template text that should usually be localized. */
+/**
+ * Detects hardcoded user-visible template text that should usually be
+ * localized.
+ *
+ * Scoped to three positive contexts rather than scanning the whole file,
+ * because a bare `>…<` regex catches JS comparisons (`if (x > 0 && y <
+ * 100)`), diagnostic strings (`console.error("Failed <id> lookup")`), and
+ * identifier literals that are never shown to a user. Only matches that
+ * actually enter a UI render path count:
+ *
+ *   1. Content inside a Lit `` html`…` `` tagged template literal.
+ *   2. The string literal on the RHS of `.textContent = "…"` or
+ *      `.innerHTML = "…"`.
+ *   3. The string literal assigned to an XUL-widget `label=`,
+ *      `title=`, or `tooltiptext=` attribute when constructing DOM in JS.
+ *
+ * A file-wide `// furnace-ignore: hardcoded-text` comment suppresses all
+ * findings (matches the pre-existing escape hatch).
+ */
 export declare function containsHardcodedTemplateText(content: string): boolean;
 /** Detects whether a component opts into shadow-root focus delegation. */
 export declare function hasDelegatesFocusEnabled(content: string): boolean;
@@ -35,8 +53,20 @@ export declare function hasCustomElementDefineCall(mjsContent: string): boolean;
 export declare function classExtendsMozLitElement(mjsContent: string): boolean;
 /** Collects CSS custom property references used via var(--token-name). */
 export declare function collectCssVariableReferences(cssContent: string): string[];
+/**
+ * Collects CSS custom property *declarations* — names appearing on the
+ * left-hand side of a `--name:` declaration. Used to auto-exempt
+ * component-local runtime variables from the token-prefix check: if the
+ * component both declares and consumes a variable in its own CSS file, it
+ * is a local runtime channel, not a design-token reference.
+ *
+ * The anchor `(?:^|[{;,\s])` rules out `var(--name)` occurrences (which are
+ * always preceded by `(`), so references are not mistaken for declarations.
+ */
+export declare function collectCssVariableDeclarations(cssContent: string): Set<string>;
 /** Builds token-validation context from the config allowlist and inherited override CSS. */
 export declare function getTokenPrefixContext(tagName: string, type: ComponentType, config: FurnaceConfig, root: string | undefined): Promise<{
     allowlist: Set<string>;
     inheritedOverrideVars: Set<string>;
+    runtimeVariables: Set<string>;
 }>;