@hominis/fireforge 0.15.1 → 0.15.2

package/CHANGELOG.md

@@ -5,7 +5,7 @@
 ### Furnace registration
 
 - `furnace apply` idempotency check is marker-comment-tolerant. Previously the single-line substring match (`content.includes('["tag",')`) missed multi-line entries, and the standalone-line regex anchored on `\s*$`, which did not allow trailing `// <marker>:` comments an operator may have appended to a previously-written entry. A duplicate tag was then inserted on every re-apply, and the second `setElementCreationCallback` invocation threw `NotSupportedError: Operation is not supported` at every window-load. The idempotency check now matches on tag-name column 0 (both single- and multi-line array shapes) and tolerates trailing `//` comments on the line.
-- New optional fireforge.json field `markerComment` (e.g. `"HOMINIS"`) is appended as a `  // HOMINIS:` suffix to every line FireForge writes into `customElements.js`. Keeps fork modifications discoverable and re-applies idempotent without hand-tagging after each apply. The field is threaded through `applyCustomComponent` and `furnace deploy`, not just `furnace create`.
+- New optional fireforge.json field `markerComment` (e.g. `"MYBROWSER"`) is appended as a `  // MYBROWSER:` suffix to every line FireForge writes into `customElements.js`. Keeps fork modifications discoverable and re-applies idempotent without hand-tagging after each apply. The field is threaded through `applyCustomComponent` and `furnace deploy`, not just `furnace create`.
 - `addCustomElementRegistration` and its regex fallback both accept the new marker as an optional parameter; the AST idempotency check and the regex-fallback idempotency check share a single helper (`isTagAlreadyRegistered`).
 
 ### Furnace `--localized`
@@ -17,19 +17,31 @@
 
 ### Furnace validate
 
-- `missing-token-link` now reads `tokenHostDocuments` from furnace.json and scans every configured chrome document for the tokens CSS link. Warning fires only when NONE of them link the tokens CSS; the warning enumerates the documents it actually checked. Previously the check was hardcoded to `browser/base/content/browser.xhtml`, which false-positived on forks that mount components in a different chrome document (e.g. `hominis.xhtml`). Defaults to `["browser/base/content/browser.xhtml"]` when omitted — behaviour is unchanged for projects that never set the field.
+- `missing-token-link` now reads `tokenHostDocuments` from furnace.json and scans every configured chrome document for the tokens CSS link. Warning fires only when NONE of them link the tokens CSS; the warning enumerates the documents it actually checked. Previously the check was hardcoded to `browser/base/content/browser.xhtml`, which false-positived on forks that mount components in a different chrome document (e.g. `mybrowser.xhtml`). Defaults to `["browser/base/content/browser.xhtml"]` when omitted — behaviour is unchanged for projects that never set the field.
 - `no-keyboard-handler` no longer warns when `@click` sits on a native interactive element (`<button>`, `<a href>`, `<input>`, `<select>`, `<textarea>`, `<summary>`, `<details>`, or the Firefox `moz-button`/`moz-toggle`/`moz-checkbox`/`moz-radio`/`moz-menulist` widgets). Those elements dispatch `click` on Enter and Space via the platform, so a duplicate `@keydown`/`@keypress` handler would double-fire. The rule still fires for synthetic interactive markup (e.g. `<div @click>`) and for bare `<a>` without an `href` attribute, which are the real keyboard-a11y hazards.
+- `token-prefix-violation` stops flagging component-owned runtime CSS custom properties. Previously every `var(--foo)` that did not match `tokenPrefix` was rejected as a design-token escape, even when the property was a per-frame state channel (`--cam-x`, `--tile-z`) both written and read by the component. Two relaxations ship together: (a) a new optional `runtimeVariables: string[]` field in `furnace.json` explicitly allowlists cross-component runtime channels (e.g. set in JS, read in the child's CSS); (b) variables that are both declared (`--foo: value;`) and consumed (`var(--foo)`) inside the same CSS file are auto-exempted — no config entry required. The same relaxations apply to the patch-stack lint. The violation message now calls out `runtimeVariables` as the third escape hatch alongside `tokenPrefix` and `tokenAllowlist`.
+- `hardcoded-text` narrowed from a bare `>…<` scan to three context-aware probes: text inside Lit `` html`…` `` template literals, string literals assigned via `.textContent = "…"` / `.innerHTML = "…"`, and XUL-attribute values set via `setAttribute("label"|"title"|"tooltiptext", "…")`. Previously the rule also matched JS comparisons (`if (x > 0 && y < 100)`), long diagnostic strings (`console.error("…")`), and identifier literals passed to `querySelector`, producing noise that trained authors to ignore validator warnings. The file-wide `// furnace-ignore: hardcoded-text` escape hatch is preserved.
 
 ### Run / test
 
 - `fireforge run`, `fireforge watch`, `fireforge build`, and every other `mach` invocation launched with inherited stdio now forward parent `SIGINT`/`SIGTERM` to the child as `SIGTERM` and wait ~1.5 s before escalating to `SIGKILL`. A second Ctrl-C during the grace window escalates immediately (matches the usual "hit Ctrl-C twice to force-quit" UX). Previously the parent could exit before Gecko's `AsyncShutdown` / `profileBeforeChange` blockers finished flushing in-memory state, losing the last few seconds of edits. The grace window is configurable via a new `shutdownGraceMs` option on `execInherit` / `execInheritCapture`.
 - New `fireforge test --doctor` runs a short marionette handshake preflight before (optionally) invoking `mach test`. Spawns the built browser headless, opens a TCP socket to `127.0.0.1:2828`, waits for the handshake bytes, and reports PASS/FAIL with the tail of stderr on FAIL. When `--doctor` is supplied with no test paths, it exits after the preflight — a sub-minute way to tell "marionette wedged" apart from "test failed to discover" when `mach test` hangs for the full 360 s marionette timeout. When supplied with test paths, a FAIL preflight short-circuits before `mach test` runs.
+- `fireforge test --doctor` is now a cascade of six layered probes (engine-present → mach-available → python-available → profile-creatable → browser-spawns → marionette-handshake) with tight per-layer budgets. Previously the single 30 s socket poll gave the same generic "socket did not respond" diagnostic whether mach was missing, Python was unavailable, `/tmp` was not writable, or the browser binary crashed at startup — so operators had no lead on where to start debugging. Each layer now short-circuits with a `[layer N/6: <name>]`-prefixed detail message so the first broken layer is surfaced immediately, and a crashing browser is caught by a short settle window at layer 5 instead of wasting the full budget waiting for bytes that never come.
+
+### Furnace build
+
+- `fireforge build` already auto-applies Furnace components (via `prepareBuildEnvironment`) before the mach build step, but the behaviour was undocumented and silent — operators who edited `components/custom/` and then ran `fireforge build` could not distinguish "auto-apply wrote files" from "nothing changed". A loud `Furnace: source → engine sync wrote N component(s) before build (...)` banner now fires whenever apply wrote files, naming every component that was synced. The `fireforge build --help` description and help footer now call out that apply runs before the build step.
+
+### Furnace create
+
+- New `furnace create --xpcshell` flag scaffolds an xpcshell test harness alongside (or instead of) the browser-chrome mochitest that `--with-tests` already produces. xpcshell runs headless without a `tabbrowser`, so storage-layer / observer-driven / module-loading code on forks that do not mount the upstream browser chrome (no `openLinkIn` → `URILoadingHelper`) can be covered without the harness complaining about a missing tab strip. Writes `test_<name>_module_loads.js` and an `xpcshell.toml` manifest into `engine/browser/base/content/test/<binary-name>-xpcshell/<component-name>/`. Registration in `XPCSHELL_TESTS_MANIFESTS` is left to the operator — the moz.build that should own the entry depends on where the component lives.
 
 ### Internal
 
 - Extracted `furnace-apply-ftl.ts`, `furnace-config-tokens.ts`, and `create-templates.ts` to keep apply / config / scaffolding files under the per-file LOC budget after the new features landed. `parseStringArray` is now exported from `furnace-config.ts` for cross-module reuse.
 - New `src/core/marionette-preflight.ts` owns the `--doctor` probe and its teardown semantics.
 - Test mocks for `furnace-registration.js` now cover the new `addLocaleFtlJarMnEntry` / `removeLocaleFtlJarMnEntry` exports; `config.js` mocks in apply-batch tests now cover `loadConfig` because the apply path reads `markerComment` from fireforge.json.
+- Repo-wide scrub of fork-example mentions (`hominis.xhtml`, `HOMINIS` marker-comment examples, fixture tag names) in favour of a generic `mybrowser` / `MYBROWSER` placeholder. FireForge reads as fork-agnostic in docs and fixtures; the npm identity (`@hominis/fireforge`) is unchanged.
 
 ## 0.14.0
 
@@ -249,7 +261,7 @@
 ### General improvements
 
 - getPackageRoot up to this point expected hardcoded `@hominis/fireforge`, was changed to just the package name for potential forks and more flexibility when changing project name.
-- Some test generators were derived from early Hominis Browser fork additions, the references to Hominis have been replaced with generic naming.
+- Some test generators were derived from an early downstream fork; the fork-specific names have been replaced with generic naming so the templates apply to any Firefox fork.
 
 ### Build and Git reliability
 

package/README.md

@@ -298,7 +298,7 @@ fireforge furnace status                           # workspace vs engine drift
 fireforge furnace diff moz-button                  # unified diff against baseline
 ```
 
-`furnace deploy` validates components before applying. As always, errors block, warnings are advisory. `fireforge build` and `fireforge test --build` run apply automatically. Use `fireforge doctor --repair-furnace` if the engine gets out of sync.
+`furnace deploy` validates components before applying. As always, errors block, warnings are advisory. `fireforge build` and `fireforge test --build` run apply automatically — when apply wrote files during a build, the build prints a `Furnace: source → engine sync wrote N component(s) …` banner naming every component that was synced, so it is obvious whether engine/ was freshly updated. Use `fireforge doctor --repair-furnace` if the engine gets out of sync.
 
 ## Additional Commands
 
@@ -367,7 +367,7 @@ fireforge token --name "--my-color" --value "light-dark(#fff, #000)"
   "wire": { "subscriptDir": "browser/components/mybrowser" },
   "patchLint": {
     "checkJs": true,
-    "rawColorAllowlist": ["hominis-tokens.css"]
+    "rawColorAllowlist": ["mybrowser-tokens.css"]
   },
   "markerComment": "MYBROWSER"
 }
@@ -375,7 +375,7 @@ fireforge token --name "--my-color" --value "light-dark(#fff, #000)"
 
 **`markerComment`** (optional). Appended as a `  // <marker>:` suffix to every line FireForge writes into upstream Firefox source files (starting with `customElements.js`). Keeps fork modifications discoverable and makes re-apply idempotent without hand-tagging entries after each `furnace apply`. Reject list: empty strings, leading/trailing whitespace, newlines, `*/` (would close an enclosing block comment), control characters.
 
-**`furnace.json.tokenHostDocuments`** (optional). List of chrome XHTML documents the `missing-token-link` validator scans for the tokens CSS link. Forks with a second chrome host (e.g. `hominis.xhtml` alongside `browser.xhtml`) should list every document that may own the link — the rule fires only when NONE of them link the tokens CSS. Defaults to `["browser/base/content/browser.xhtml"]` when omitted.
+**`furnace.json.tokenHostDocuments`** (optional). List of chrome XHTML documents the `missing-token-link` validator scans for the tokens CSS link. Forks with a second chrome host (e.g. `mybrowser.xhtml` alongside `browser.xhtml`) should list every document that may own the link — the rule fires only when NONE of them link the tokens CSS. Defaults to `["browser/base/content/browser.xhtml"]` when omitted.
 
 ### `furnace create --localized` for `MozLitElement`
 
@@ -391,6 +391,25 @@ fireforge test --doctor browser/base/content/test/foo/browser_bar.js
 
 Spawns the built browser headless, waits for a marionette handshake on `127.0.0.1:2828`, and reports PASS/FAIL with the tail of the browser's stderr on FAIL. Distinguishes "marionette wedged" (socket silent) from "mach test discovery failed" — both otherwise surface as a silent 360-second hang followed by `Passed: 0, Failed: 0`. Useful as a prefix on routine `fireforge test` invocations when marionette has been flaky.
 
+The probe is a cascade of six layered checks — engine-present → mach-available → python-available → profile-creatable → browser-spawns → marionette-handshake. Each failure is tagged `[layer N/6: <name>]` so the first broken layer is surfaced immediately instead of the whole cascade blocking on the final socket poll. When the browser binary crashes at startup (missing dylib, wrong CPU arch, corrupt profile) the cascade fails at layer 5 within the settle window, not after the full socket timeout.
+
+### Runtime CSS variables in Furnace
+
+Design tokens imported from the fork's palette are enforced by `tokenPrefix`, but some components write and read CSS custom properties as runtime state channels (`--cam-x` per frame, `--tile-z` from a hit-test observer). Two escape hatches exist:
+
+- **Auto-exempt** — a variable that is both declared (`--foo: 0;`) and consumed (`var(--foo)`) inside the same component's CSS file is recognised as a component-local runtime channel. No config entry required.
+- **`furnace.json.runtimeVariables`** — explicit allowlist for names that are _written_ in JS and _read_ in a different file's CSS (cross-component runtime channels that the CSS-only auto-exempt cannot see). Entries must start with `--`.
+
+Both rules compose with the existing `tokenPrefix` / `tokenAllowlist` checks and apply to both component validation and patch-stack lint.
+
+### Test harness options
+
+`fireforge furnace create --with-tests` scaffolds a **browser-chrome mochitest**. Use this when the component renders UI that depends on the tab strip (`openLinkIn` → `URILoadingHelper`, `gBrowser`, etc.).
+
+`fireforge furnace create --xpcshell` scaffolds an **xpcshell test harness** instead. Use this when the component's code path is storage-only, observer-driven, or module-loading logic that does not touch a `tabbrowser`. xpcshell runs headless without browser chrome, so forks without an upstream tab strip can still cover these paths. The scaffolder writes `test_<name>_module_loads.js` + `xpcshell.toml` into `engine/browser/base/content/test/<binary-name>-xpcshell/<component-name>/` and prints a note: registration in `XPCSHELL_TESTS_MANIFESTS` is the operator's call (the moz.build that should own the entry depends on where the component actually lives).
+
+The two flags can be combined — `--with-tests --xpcshell` writes both harnesses.
+
 ## Roadmap
 
 Planned but not yet implemented:

package/dist/src/commands/build.js

@@ -96,10 +96,21 @@ export async function buildCommand(projectRoot, options) {
 export function registerBuild(program, { getProjectRoot, withErrorHandling }) {
     program
         .command('build')
-        .description('Build the browser')
+        .description('Build the browser (auto-applies Furnace components first)')
         .option('--ui', 'Fast UI-only rebuild')
         .option('-j, --jobs <n>', 'Number of parallel jobs', parseJobCount)
         .option('--brand <name>', 'Build specific brand')
+        .addHelpText('after', [
+        '',
+        'Furnace apply runs automatically before the build step, so edits in',
+        'components/custom/ and components/overrides/ are propagated to the',
+        'engine/ tree every time. The command prints a banner listing the',
+        'components synced during the current invocation.',
+        '',
+        'If you want to preview the engine state without triggering a build,',
+        'run `fireforge furnace apply` directly. For source-change-driven',
+        'rebuild loops during development, use `fireforge watch`.',
+    ].join('\n'))
         .action(withErrorHandling(async (options) => {
         await buildCommand(getProjectRoot(), pickDefined(options));
     }));

package/dist/src/commands/furnace/create-templates.d.ts

@@ -24,3 +24,24 @@ export declare function generateMjsContent(name: string, className: string, desc
 export declare function generateCssContent(header: string): string;
 /** Generates the .ftl file content for a custom component. */
 export declare function generateFtlContent(name: string, header: string): string;
+/** Returns the canonical xpcshell test file basename for a component. */
+export declare function xpcshellTestFileName(name: string): string;
+/**
+ * Generates an xpcshell test file for a custom component.
+ *
+ * xpcshell tests run headless without a `tabbrowser`, so they suit
+ * storage/observer/module-loading code in forks that do not mount the
+ * upstream browser chrome (and therefore lack `openLinkIn` →
+ * `URILoadingHelper`). The scaffold imports the component module via
+ * `ChromeUtils.importESModule` and asserts the module resolves — enough
+ * to catch registration regressions without touching DOM rendering paths
+ * that xpcshell cannot execute.
+ */
+export declare function generateXpcshellTestContent(name: string, header: string): string;
+/**
+ * Generates an `xpcshell.toml` manifest for a custom component's test
+ * directory. Kept minimal — adding prefs, head.js, and support-files is
+ * left to the operator because those decisions depend on what the
+ * component actually touches (Services.storage, observer topics, etc.).
+ */
+export declare function generateXpcshellManifestContent(name: string, header: string): string;

package/dist/src/commands/furnace/create-templates.js

@@ -83,4 +83,53 @@ export function generateFtlContent(name, header) {
 ## Strings for the ${name} component
 `;
 }
+/** Returns the canonical xpcshell test file basename for a component. */
+export function xpcshellTestFileName(name) {
+    return `test_${name.replace(/-/g, '_')}_module_loads.js`;
+}
+/**
+ * Generates an xpcshell test file for a custom component.
+ *
+ * xpcshell tests run headless without a `tabbrowser`, so they suit
+ * storage/observer/module-loading code in forks that do not mount the
+ * upstream browser chrome (and therefore lack `openLinkIn` →
+ * `URILoadingHelper`). The scaffold imports the component module via
+ * `ChromeUtils.importESModule` and asserts the module resolves — enough
+ * to catch registration regressions without touching DOM rendering paths
+ * that xpcshell cannot execute.
+ */
+export function generateXpcshellTestContent(name, header) {
+    return `${header}
+
+"use strict";
+
+add_task(async function test_${name.replace(/-/g, '_')}_module_loads() {
+  // Module-load smoke check: resolves the ESM at its registered chrome URI.
+  // Replace or extend with storage-layer assertions as the component grows
+  // (Services.storage, observer topics, JSONFile, etc. are all available
+  // here without a tabbrowser).
+  const moduleUri = "chrome://global/content/elements/${name}.mjs";
+  const module = await ChromeUtils.importESModule(moduleUri);
+  Assert.ok(
+    module,
+    "${name}.mjs should load under xpcshell (storage-layer code path).",
+  );
+});
+`;
+}
+/**
+ * Generates an `xpcshell.toml` manifest for a custom component's test
+ * directory. Kept minimal — adding prefs, head.js, and support-files is
+ * left to the operator because those decisions depend on what the
+ * component actually touches (Services.storage, observer topics, etc.).
+ */
+export function generateXpcshellManifestContent(name, header) {
+    return `${header}
+
+[DEFAULT]
+head = ""
+
+["${xpcshellTestFileName(name)}"]
+`;
+}
 //# sourceMappingURL=create-templates.js.map

package/dist/src/commands/furnace/create-xpcshell.d.ts

@@ -0,0 +1,27 @@
+/**
+ * xpcshell test-harness scaffolder for `fireforge furnace create --xpcshell`.
+ * Extracted from `create.ts` so the command entrypoint stays under the
+ * per-file LOC budget and the scaffolder is unit-testable in isolation.
+ */
+import { type RollbackJournal } from '../../core/furnace-rollback.js';
+import type { ProjectLicense } from '../../types/config.js';
+/**
+ * Scaffolds an xpcshell test harness for a newly created custom component.
+ *
+ * xpcshell is the appropriate harness for storage-layer code on forks
+ * without a `tabbrowser` (no `openLinkIn` → `URILoadingHelper`). Browser
+ * chrome mochitests require tabbrowser; xpcshell does not, so storage,
+ * observers, and ESM-loading logic can be covered headless.
+ *
+ * Writes `test_<name>_module_loads.js` and an `xpcshell.toml` manifest
+ * into `engine/browser/base/content/test/<binary-name>-xpcshell/
+ * <component-name>/`. moz.build registration is intentionally left to the
+ * operator — wiring an `XPCSHELL_TESTS_MANIFESTS` entry requires a
+ * deliberate choice about which moz.build should own it, and an
+ * auto-insertion that guessed wrong would be worse than a note.
+ */
+export declare function scaffoldXpcshellTestFiles(componentName: string, license: ProjectLicense, forgeConfig: {
+    binaryName: string;
+}, paths: {
+    engine: string;
+}, journal?: RollbackJournal): Promise<string[]>;

package/dist/src/commands/furnace/create-xpcshell.js

@@ -0,0 +1,53 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * xpcshell test-harness scaffolder for `fireforge furnace create --xpcshell`.
+ * Extracted from `create.ts` so the command entrypoint stays under the
+ * per-file LOC budget and the scaffolder is unit-testable in isolation.
+ */
+import { join } from 'node:path';
+import { recordCreatedDir, snapshotFile, } from '../../core/furnace-rollback.js';
+import { getLicenseHeader } from '../../core/license-headers.js';
+import { ensureDir, pathExists, writeText } from '../../utils/fs.js';
+import { warn } from '../../utils/logger.js';
+import { generateXpcshellManifestContent, generateXpcshellTestContent, xpcshellTestFileName, } from './create-templates.js';
+/**
+ * Scaffolds an xpcshell test harness for a newly created custom component.
+ *
+ * xpcshell is the appropriate harness for storage-layer code on forks
+ * without a `tabbrowser` (no `openLinkIn` → `URILoadingHelper`). Browser
+ * chrome mochitests require tabbrowser; xpcshell does not, so storage,
+ * observers, and ESM-loading logic can be covered headless.
+ *
+ * Writes `test_<name>_module_loads.js` and an `xpcshell.toml` manifest
+ * into `engine/browser/base/content/test/<binary-name>-xpcshell/
+ * <component-name>/`. moz.build registration is intentionally left to the
+ * operator — wiring an `XPCSHELL_TESTS_MANIFESTS` entry requires a
+ * deliberate choice about which moz.build should own it, and an
+ * auto-insertion that guessed wrong would be worse than a note.
+ */
+export async function scaffoldXpcshellTestFiles(componentName, license, forgeConfig, paths, journal) {
+    const parentDirName = `${forgeConfig.binaryName}-xpcshell`;
+    const testDir = join(paths.engine, 'browser/base/content/test', parentDirName, componentName);
+    if (journal && !(await pathExists(testDir))) {
+        recordCreatedDir(journal, testDir);
+    }
+    await ensureDir(testDir);
+    const jsHeader = getLicenseHeader(license, 'js');
+    const hashHeader = getLicenseHeader(license, 'hash');
+    const testFiles = [];
+    const testFileName = xpcshellTestFileName(componentName);
+    const testFilePath = join(testDir, testFileName);
+    if (journal)
+        await snapshotFile(journal, testFilePath);
+    await writeText(testFilePath, generateXpcshellTestContent(componentName, jsHeader));
+    testFiles.push(testFileName);
+    const manifestPath = join(testDir, 'xpcshell.toml');
+    if (journal)
+        await snapshotFile(journal, manifestPath);
+    await writeText(manifestPath, generateXpcshellManifestContent(componentName, hashHeader));
+    testFiles.push('xpcshell.toml');
+    warn(`xpcshell scaffold written under browser/base/content/test/${parentDirName}/${componentName}/. ` +
+        'Add the directory to XPCSHELL_TESTS_MANIFESTS in the nearest moz.build to run it via "fireforge test".');
+    return testFiles;
+}
+//# sourceMappingURL=create-xpcshell.js.map

package/dist/src/commands/furnace/create.js

@@ -16,6 +16,7 @@ import { toError } from '../../utils/errors.js';
 import { ensureDir, pathExists, readText, writeText } from '../../utils/fs.js';
 import { cancel, intro, isCancel, note, outro, success, warn } from '../../utils/logger.js';
 import { generateCssContent, generateFtlContent, generateMjsContent } from './create-templates.js';
+import { scaffoldXpcshellTestFiles } from './create-xpcshell.js';
 async function loadAuthoringFurnaceConfig(projectRoot) {
     if (await furnaceConfigExists(projectRoot)) {
         return loadFurnaceConfig(projectRoot);
@@ -262,6 +263,10 @@ async function performCreateMutations(args) {
             const scafFiles = await scaffoldTestFiles(args.componentName, args.license, args.forgeConfig, args.paths, journal);
             testFiles.push(...scafFiles);
         }
+        if (args.xpcshellTests) {
+            const xpcshellFiles = await scaffoldXpcshellTestFiles(args.componentName, args.license, args.forgeConfig, args.paths, journal);
+            testFiles.push(...xpcshellFiles);
+        }
     }
     catch (error) {
         try {
@@ -396,12 +401,14 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
     }
     const { localized, register } = featureSelection;
     // --with-tests writes files under engine/browser/base/content/test/ and
-    // registers them in moz.build. Guard against a missing engine now rather
-    // than letting scaffoldTestFiles fabricate a partial engine tree with
-    // ensureDir.
+    // registers them in moz.build. --xpcshell is the equivalent for forks
+    // without a tabbrowser (storage-layer code). Guard against a missing
+    // engine now rather than letting the scaffolders fabricate a partial
+    // engine tree with ensureDir.
     const withTests = options.withTests ?? false;
-    if (withTests && !(await pathExists(paths.engine))) {
-        throw new FurnaceError('Engine directory not found. Run "fireforge download" first to use --with-tests.', componentName);
+    const xpcshellTests = options.xpcshell ?? false;
+    if ((withTests || xpcshellTests) && !(await pathExists(paths.engine))) {
+        throw new FurnaceError('Engine directory not found. Run "fireforge download" first to use --with-tests or --xpcshell.', componentName);
     }
     // --- Generate component files ---
     const className = tagNameToClassName(componentName);
@@ -438,6 +445,7 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
         paths,
         license,
         withTests,
+        xpcshellTests,
         ftlChromeSubPath,
         operationContext: ctx,
     }));
@@ -445,9 +453,10 @@ export async function furnaceCreateCommand(projectRoot, name, options = {}) {
     let noteParts = `Files created in components/custom/${componentName}/:\n` +
         files.map((f) => `  ${f}`).join('\n');
     if (testFiles.length > 0) {
-        noteParts +=
-            `\n\nTest files in engine/browser/base/content/test/${forgeConfig.binaryName}/:\n` +
-                testFiles.map((f) => `  ${f}`).join('\n');
+        const testRoot = xpcshellTests
+            ? `engine/browser/base/content/test/${forgeConfig.binaryName}-xpcshell/${componentName}/`
+            : `engine/browser/base/content/test/${forgeConfig.binaryName}/`;
+        noteParts += `\n\nTest files in ${testRoot}:\n` + testFiles.map((f) => `  ${f}`).join('\n');
     }
     noteParts +=
         '\n\n' +

package/dist/src/commands/furnace/index.js

@@ -72,6 +72,7 @@ function registerFurnaceInfoCommands(furnace, context) {
         .option('--localized', 'Include Fluent l10n support')
         .option('--no-register', 'Skip customElements.js registration')
         .option('--with-tests', 'Scaffold Mochitest directory and register in moz.build')
+        .option('--xpcshell', 'Scaffold an xpcshell test harness (for storage-layer code on forks without tabbrowser)')
         .option('--compose <tags>', 'Record stock tags composed internally (metadata only, comma-separated)', (val) => val.split(',').map((s) => s.trim()))
         .action(withErrorHandling(async (name, options) => {
         await furnaceCreateCommand(getProjectRoot(), name, options);

package/dist/src/commands/setup.d.ts

@@ -8,4 +8,4 @@ import type { SetupOptions } from '../types/commands/index.js';
  */
 export declare function setupCommand(projectRoot: string, options?: SetupOptions): Promise<void>;
 /** Registers the setup command on the CLI program. */
-export declare function registerSetup(program: Command, { getProjectRoot, withErrorHandling }: CommandContext): void;
+export declare function registerSetup(program: Command, { withErrorHandling }: CommandContext): void;

package/dist/src/commands/setup.js

@@ -1,4 +1,5 @@
 // SPDX-License-Identifier: EUPL-1.2
+import { resolve } from 'node:path';
 import { confirm } from '@clack/prompts';
 import { Option } from 'commander';
 import { configExists } from '../core/config.js';
@@ -57,7 +58,7 @@ export async function setupCommand(projectRoot, options = {}) {
     }
 }
 /** Registers the setup command on the CLI program. */
-export function registerSetup(program, { getProjectRoot, withErrorHandling }) {
+export function registerSetup(program, { withErrorHandling }) {
     program
         .command('setup')
         .description('Initialize a new FireForge project')
@@ -88,7 +89,7 @@ export function registerSetup(program, { getProjectRoot, withErrorHandling }) {
                 setupOptions.license = parsedLicense;
             }
         }
-        await setupCommand(getProjectRoot(), setupOptions);
+        await setupCommand(resolve(process.cwd()), setupOptions);
     }));
 }
 //# sourceMappingURL=setup.js.map

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

@@ -5,7 +5,7 @@
  */
 import { FurnaceError } from '../errors/furnace.js';
 import { pathExists } from '../utils/fs.js';
-import { spinner, warn } from '../utils/logger.js';
+import { info, spinner, 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';
@@ -95,7 +95,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');

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-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>;
 }>;

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

@@ -148,28 +148,88 @@ function isWithinLocalizedElement(content, matchIndex) {
     const tagContent = contentBefore.slice(lastTagOpen, matchIndex + 1);
     return /data-l10n-id\s*=/.test(tagContent);
 }
-/** 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 function containsHardcodedTemplateText(content) {
     if (/furnace-ignore:\s*hardcoded-text/.test(content)) {
         return false;
     }
-    const textPattern = />([^<$\s][^<$]*)</g;
-    let textMatch;
-    while ((textMatch = textPattern.exec(content)) !== null) {
-        const text = textMatch[1]?.trim() ?? '';
-        if (/\$\{/.test(text)) {
-            continue;
-        }
-        if (Array.from(text).length <= 1) {
-            continue;
-        }
-        if (isSymbolOnlyText(text)) {
-            continue;
-        }
-        if (isWithinLocalizedElement(content, textMatch.index)) {
-            continue;
+    return (hasFlaggedTextInLitTemplates(content) ||
+        hasFlaggedTextInDomAssignment(content) ||
+        hasFlaggedTextInXulAttribute(content));
+}
+function isFlaggableText(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return false;
+    if (/\$\{/.test(trimmed))
+        return false;
+    if (Array.from(trimmed).length <= 1)
+        return false;
+    if (isSymbolOnlyText(trimmed))
+        return false;
+    return true;
+}
+function hasFlaggedTextInLitTemplates(content) {
+    // Match `html\`…\`` regions, anchored on a non-identifier char before `html`
+    // so substrings like `otherhtml` do not spuriously open a template.
+    const htmlPattern = /(?:^|[^a-zA-Z0-9_$])html`([\s\S]*?)`/g;
+    let litMatch;
+    while ((litMatch = htmlPattern.exec(content)) !== null) {
+        const region = litMatch[1] ?? '';
+        const textPattern = />([^<$\s][^<$]*)</g;
+        let textMatch;
+        while ((textMatch = textPattern.exec(region)) !== null) {
+            const text = textMatch[1] ?? '';
+            if (!isFlaggableText(text))
+                continue;
+            if (isWithinLocalizedElement(region, textMatch.index))
+                continue;
+            return true;
         }
-        return true;
+    }
+    return false;
+}
+function hasFlaggedTextInDomAssignment(content) {
+    // `<expr>.textContent = "abc"` and `<expr>.innerHTML = "abc"` — these are
+    // user-visible render paths. Template-literal RHS is excluded (usually
+    // dynamic), matching the `${` guard used elsewhere in this helper.
+    const assignPattern = /\.(?:textContent|innerHTML)\s*=\s*(["'])((?:\\.|(?!\1).)*)\1/g;
+    let match;
+    while ((match = assignPattern.exec(content)) !== null) {
+        const text = match[2] ?? '';
+        if (isFlaggableText(text))
+            return true;
+    }
+    return false;
+}
+function hasFlaggedTextInXulAttribute(content) {
+    // Assignments like `node.setAttribute("label", "Save")` or JS-built XUL
+    // attributes `label="…"` / `title="…"` / `tooltiptext="…"` in template
+    // literals outside Lit blocks. Covers DOM built via createXULElement.
+    const setAttrPattern = /setAttribute\s*\(\s*["'](?:label|title|tooltiptext)["']\s*,\s*(["'])((?:\\.|(?!\1).)*)\1/g;
+    let setAttrMatch;
+    while ((setAttrMatch = setAttrPattern.exec(content)) !== null) {
+        const text = setAttrMatch[2] ?? '';
+        if (isFlaggableText(text))
+            return true;
     }
     return false;
 }
@@ -214,6 +274,27 @@ export function collectCssVariableReferences(cssContent) {
     }
     return referencedVariables;
 }
+/**
+ * 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 function collectCssVariableDeclarations(cssContent) {
+    const declared = new Set();
+    const pattern = /(?:^|[{;,\s])(--[\w-]+)\s*:/g;
+    let match;
+    while ((match = pattern.exec(cssContent)) !== null) {
+        const name = match[1];
+        if (name)
+            declared.add(name);
+    }
+    return declared;
+}
 async function collectInheritedOverrideVariables(tagName, config, root) {
     const inheritedVariables = new Set();
     const basePath = config.overrides[tagName]?.basePath;
@@ -234,12 +315,14 @@ async function collectInheritedOverrideVariables(tagName, config, root) {
 /** Builds token-validation context from the config allowlist and inherited override CSS. */
 export async function getTokenPrefixContext(tagName, type, config, root) {
     const allowlist = new Set(config.tokenAllowlist ?? []);
+    const runtimeVariables = new Set(config.runtimeVariables ?? []);
     if (type !== 'override' || !root) {
-        return { allowlist, inheritedOverrideVars: new Set() };
+        return { allowlist, inheritedOverrideVars: new Set(), runtimeVariables };
     }
     return {
         allowlist,
         inheritedOverrideVars: await collectInheritedOverrideVariables(tagName, config, root),
+        runtimeVariables,
     };
 }
 //# sourceMappingURL=furnace-validate-helpers.js.map

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

@@ -35,7 +35,7 @@ export declare function validateJarMnEntries(root: string, config: FurnaceConfig
  * linked in at least one chrome host document. Without the link, tokens
  * silently resolve to nothing at runtime.
  *
- * Forks with multiple chrome host documents (e.g. `hominis.xhtml` beside
+ * Forks with multiple chrome host documents (e.g. `mybrowser.xhtml` beside
  * `browser.xhtml`) can enumerate them via `tokenHostDocuments` in
  * furnace.json; the warning fires only when NONE of the configured
  * documents link the tokens CSS.

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

@@ -216,7 +216,7 @@ const DEFAULT_TOKEN_HOST_DOCUMENTS = ['browser/base/content/browser.xhtml'];
  * linked in at least one chrome host document. Without the link, tokens
  * silently resolve to nothing at runtime.
  *
- * Forks with multiple chrome host documents (e.g. `hominis.xhtml` beside
+ * Forks with multiple chrome host documents (e.g. `mybrowser.xhtml` beside
  * `browser.xhtml`) can enumerate them via `tokenHostDocuments` in
  * furnace.json; the warning fires only when NONE of the configured
  * documents link the tokens CSS.

package/dist/src/core/marionette-preflight.d.ts

@@ -6,18 +6,17 @@
  * to discover"; this helper surfaces the failure in under a minute with a
  * clear PASS/FAIL line and the tail of the browser's stderr.
  *
- * The probe is intentionally narrow — it does not replace mach test or try
- * to execute anything via marionette. It spawns `mach run --marionette
- * --headless` (plus a throwaway profile) and waits for the marionette server
- * to accept a TCP connection on the conventional port. Any byte read from
- * the socket proves a handshake payload is being produced.
+ * The probe is a cascade of layered checks (engine → mach → python →
+ * profile → spawn → handshake). Each layer has a tight per-attempt budget
+ * so a broken earlier layer fails fast with a specific diagnosis rather
+ * than blocking on the final socket poll for the full overall budget.
  */
 import { spawn } from 'node:child_process';
 import net from 'node:net';
 export interface MarionettePreflightResult {
     ok: boolean;
     durationMs: number;
-    /** Human-readable summary. */
+    /** Human-readable summary. On FAIL, prefixed with `[layer N/6: <name>]`. */
     detail: string;
 }
 export interface MarionettePreflightOptions {
@@ -25,13 +24,21 @@ export interface MarionettePreflightOptions {
     timeoutMs?: number;
     /** Overrides marionette TCP port — primarily used in tests. */
     port?: number;
+    /**
+     * Grace window after spawn() before the browser is considered "running
+     * OK." Catches immediate crashes (missing dylib, wrong CPU arch, corrupt
+     * profile) at the spawn layer rather than the handshake layer. Default:
+     * {@link SPAWN_SETTLE_MS}. Tests may set this to 0 to skip the settle.
+     */
+    spawnSettleMs?: number;
     /** Test seam: spawn and socket connect factories. */
     spawner?: typeof spawn;
     connect?: typeof net.createConnection;
 }
 /**
  * Runs the marionette preflight. Returns PASS on first byte read from the
- * marionette socket within the budget; FAIL otherwise. Always tears down the
+ * marionette socket within the budget; FAIL otherwise, with a diagnostic
+ * identifying which layer of the cascade broke. Always tears down the
  * spawned browser before returning.
  */
 export declare function runMarionettePreflight(engineDir: string, options?: MarionettePreflightOptions): Promise<MarionettePreflightResult>;

package/dist/src/core/marionette-preflight.js

@@ -7,11 +7,10 @@
  * to discover"; this helper surfaces the failure in under a minute with a
  * clear PASS/FAIL line and the tail of the browser's stderr.
  *
- * The probe is intentionally narrow — it does not replace mach test or try
- * to execute anything via marionette. It spawns `mach run --marionette
- * --headless` (plus a throwaway profile) and waits for the marionette server
- * to accept a TCP connection on the conventional port. Any byte read from
- * the socket proves a handshake payload is being produced.
+ * The probe is a cascade of layered checks (engine → mach → python →
+ * profile → spawn → handshake). Each layer has a tight per-attempt budget
+ * so a broken earlier layer fails fast with a specific diagnosis rather
+ * than blocking on the final socket poll for the full overall budget.
  */
 import { spawn } from 'node:child_process';
 import { mkdtemp, rm } from 'node:fs/promises';
@@ -28,60 +27,112 @@ const MARIONETTE_PORT = 2828;
 const DEFAULT_PREFLIGHT_TIMEOUT_MS = 30_000;
 /** Per-attempt socket connect timeout. Polling continues until the overall budget expires. */
 const SOCKET_ATTEMPT_TIMEOUT_MS = 2_000;
+/**
+ * Grace window after spawn() returns before we accept the child as
+ * "spawned OK". A browser binary that exits immediately (missing dylib,
+ * wrong CPU arch, corrupt profile) must be caught here — not 30 seconds
+ * later at the socket layer.
+ */
+const SPAWN_SETTLE_MS = 750;
 /** Tail of stderr preserved for FAIL diagnostics. */
 const STDERR_TAIL_LIMIT = 8 * 1024;
+/**
+ * Layer names, ordered by the probe sequence. Surfaced in `detail` so the
+ * operator sees which layer failed without having to guess.
+ */
+const LAYER_NAMES = [
+    'engine-present',
+    'mach-available',
+    'python-available',
+    'profile-creatable',
+    'browser-spawns',
+    'marionette-handshake',
+];
+function layerTag(name) {
+    const index = LAYER_NAMES.indexOf(name) + 1;
+    return `[layer ${index}/${LAYER_NAMES.length}: ${name}]`;
+}
 /**
  * Runs the marionette preflight. Returns PASS on first byte read from the
- * marionette socket within the budget; FAIL otherwise. Always tears down the
+ * marionette socket within the budget; FAIL otherwise, with a diagnostic
+ * identifying which layer of the cascade broke. Always tears down the
  * spawned browser before returning.
  */
 export async function runMarionettePreflight(engineDir, options = {}) {
     const timeoutMs = options.timeoutMs ?? DEFAULT_PREFLIGHT_TIMEOUT_MS;
+    const spawnSettleMs = options.spawnSettleMs ?? SPAWN_SETTLE_MS;
     const port = options.port ?? MARIONETTE_PORT;
     const spawnerFn = options.spawner ?? spawn;
     const connectFn = options.connect ?? net.createConnection;
     const startedAt = Date.now();
     const elapsed = () => Date.now() - startedAt;
+    // Layer 1: engine directory exists.
     if (!(await pathExists(engineDir))) {
-        return {
-            ok: false,
-            durationMs: elapsed(),
-            detail: 'Engine directory not found — run "fireforge download" first.',
-        };
+        return fail('engine-present', 'Engine directory not found — run "fireforge download" first.', elapsed());
     }
+    // Layer 2: mach binary resolves in the engine.
     try {
         await ensureMach(engineDir);
     }
     catch (error) {
-        return {
-            ok: false,
-            durationMs: elapsed(),
-            detail: `mach not available in engine: ${error.message}`,
-        };
+        return fail('mach-available', `mach not available in engine: ${error.message}`, elapsed());
+    }
+    // Layer 3: Python that mach requires is discoverable.
+    let python;
+    try {
+        python = await getPython(engineDir);
+    }
+    catch (error) {
+        return fail('python-available', `Python interpreter required by mach is not available: ${error.message}`, elapsed());
+    }
+    // Layer 4: throwaway browser profile directory is creatable.
+    let profileDir;
+    try {
+        profileDir = await mkdtemp(join(tmpdir(), 'fireforge-marionette-'));
+    }
+    catch (error) {
+        return fail('profile-creatable', `Could not create a throwaway browser profile in ${tmpdir()}: ${error.message}`, elapsed());
     }
-    const python = await getPython(engineDir);
-    const profileDir = await mkdtemp(join(tmpdir(), 'fireforge-marionette-'));
     let child;
     let stderrTail = '';
     try {
-        child = spawnerFn(python, [
-            join(engineDir, 'mach'),
-            'run',
-            '--marionette',
-            '--headless',
-            '--no-remote',
-            '-profile',
-            profileDir,
-        ], {
-            cwd: engineDir,
-            env: { ...process.env, MOZ_HEADLESS: '1' },
-            stdio: ['ignore', 'ignore', 'pipe'],
-        });
+        // Layer 5: browser spawns and does not crash within the settle window.
+        try {
+            child = spawnerFn(python, [
+                join(engineDir, 'mach'),
+                'run',
+                '--marionette',
+                '--headless',
+                '--no-remote',
+                '-profile',
+                profileDir,
+            ], {
+                cwd: engineDir,
+                env: { ...process.env, MOZ_HEADLESS: '1' },
+                stdio: ['ignore', 'ignore', 'pipe'],
+            });
+        }
+        catch (error) {
+            return fail('browser-spawns', `Could not spawn mach run: ${error.message}`, elapsed());
+        }
+        const spawnedChild = child;
         child.stderr?.on('data', (data) => {
             const chunk = data.toString();
             stderrTail = (stderrTail + chunk).slice(-STDERR_TAIL_LIMIT);
         });
-        const spawnedChild = child;
+        // Short settle window — catches "binary exits immediately" failures
+        // (missing dylib, wrong CPU arch, corrupt profile) before the socket
+        // poll swallows the full overall budget waiting for bytes that will
+        // never come.
+        const settleDeadline = Math.min(spawnSettleMs, Math.max(0, timeoutMs - elapsed()));
+        if (settleDeadline > 0) {
+            await delay(settleDeadline);
+        }
+        if (hasChildExited(spawnedChild)) {
+            return fail('browser-spawns', `Browser process exited during spawn (exit code ${String(spawnedChild.exitCode)}, signal ${spawnedChild.signalCode ?? 'none'}). ` +
+                `stderr tail: ${stderrTail.trim().slice(-2_000) || '(empty)'}`, elapsed());
+        }
+        // Layer 6: marionette handshake within the remaining budget.
         const socketResult = await waitForMarionetteSocket(port, connectFn, () => {
             return elapsed() < timeoutMs && !hasChildExited(spawnedChild);
         });
@@ -95,19 +146,11 @@ export async function runMarionettePreflight(engineDir, options = {}) {
         // Child may have exited before the socket was ever ready — surface that
         // distinctly from "socket never answered" so the operator has a lead.
         if (hasChildExited(spawnedChild)) {
-            return {
-                ok: false,
-                durationMs: elapsed(),
-                detail: `Browser process exited before marionette handshake (exit code ${String(spawnedChild.exitCode)}, signal ${spawnedChild.signalCode ?? 'none'}). ` +
-                    `stderr tail: ${stderrTail.trim().slice(-2_000) || '(empty)'}`,
-            };
+            return fail('marionette-handshake', `Browser process exited before marionette handshake (exit code ${String(spawnedChild.exitCode)}, signal ${spawnedChild.signalCode ?? 'none'}). ` +
+                `stderr tail: ${stderrTail.trim().slice(-2_000) || '(empty)'}`, elapsed());
         }
-        return {
-            ok: false,
-            durationMs: elapsed(),
-            detail: `Marionette socket on 127.0.0.1:${port} did not respond within ${timeoutMs}ms. ` +
-                `stderr tail: ${stderrTail.trim().slice(-2_000) || '(empty)'}`,
-        };
+        return fail('marionette-handshake', `Marionette socket on 127.0.0.1:${port} did not respond within ${timeoutMs}ms. ` +
+            `stderr tail: ${stderrTail.trim().slice(-2_000) || '(empty)'}`, elapsed());
     }
     finally {
         if (child && !hasChildExited(child)) {
@@ -137,6 +180,13 @@ export async function runMarionettePreflight(engineDir, options = {}) {
         }
     }
 }
+function fail(layer, message, durationMs) {
+    return {
+        ok: false,
+        durationMs,
+        detail: `${layerTag(layer)} ${message}`,
+    };
+}
 /** Returns true when the child process has exited (normal or signaled). */
 function hasChildExited(child) {
     return child.exitCode !== null || child.signalCode !== null;

package/dist/src/core/patch-lint-cross.d.ts

@@ -91,7 +91,7 @@ export declare function collectNewFileCreatorsByPath(ctx: PatchQueueContext): Ma
 /**
  * Cross-patch lint rule: the same path is newly created (`--- /dev/null →
  * +++ b/path`) by more than one patch. This is the failure mode that
- * motivated the rule — Hominis landed three patches each trying to create
+ * motivated the rule — a fork landed three patches each trying to create
  * the same file, and the error surfaced only when import rolled back
  * mid-apply.
  *

package/dist/src/core/patch-lint-cross.js

@@ -114,7 +114,7 @@ export function collectNewFileCreatorsByPath(ctx) {
 /**
  * Cross-patch lint rule: the same path is newly created (`--- /dev/null →
  * +++ b/path`) by more than one patch. This is the failure mode that
- * motivated the rule — Hominis landed three patches each trying to create
+ * motivated the rule — a fork landed three patches each trying to create
  * the same file, and the error surfaced only when import rolled back
  * mid-apply.
  *

package/dist/src/core/patch-lint.js

@@ -110,12 +110,14 @@ export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config
     // Load furnace config gracefully — skip token-prefix check if unavailable
     let tokenPrefix;
     let tokenAllowlist;
+    let runtimeVariables;
     try {
         const root = join(repoDir, '..');
         const furnaceConfig = await loadFurnaceConfig(root);
         if (furnaceConfig.tokenPrefix) {
             tokenPrefix = furnaceConfig.tokenPrefix;
             tokenAllowlist = new Set(furnaceConfig.tokenAllowlist ?? []);
+            runtimeVariables = new Set(furnaceConfig.runtimeVariables ?? []);
         }
     }
     catch (error) {
@@ -154,20 +156,38 @@ export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config
                 });
             }
         }
-        // Check for non-tokenized custom properties
+        // Check for non-tokenized custom properties. A variable that is both
+        // declared and consumed inside the same file is auto-exempted as a
+        // runtime state channel (see furnace.json → runtimeVariables).
         if (tokenPrefix) {
+            const declarationPattern = /(?:^|[{;,\s])(--[\w-]+)\s*:/g;
+            const localDeclarations = new Set();
+            let declMatch;
+            while ((declMatch = declarationPattern.exec(cssContent)) !== null) {
+                const name = declMatch[1];
+                if (name)
+                    localDeclarations.add(name);
+            }
             const varPattern = /var\(\s*(--[\w-]+)/g;
             let match;
             while ((match = varPattern.exec(cssContent)) !== null) {
                 const prop = match[1];
-                if (prop && !prop.startsWith(tokenPrefix) && !tokenAllowlist?.has(prop)) {
-                    issues.push({
-                        file,
-                        check: 'token-prefix-violation',
-                        message: `CSS references var(${prop}) which does not match the required token prefix "${tokenPrefix}". Use a design token or add to tokenAllowlist.`,
-                        severity: 'error',
-                    });
-                }
+                if (!prop)
+                    continue;
+                if (prop.startsWith(tokenPrefix))
+                    continue;
+                if (tokenAllowlist?.has(prop))
+                    continue;
+                if (runtimeVariables?.has(prop))
+                    continue;
+                if (localDeclarations.has(prop))
+                    continue;
+                issues.push({
+                    file,
+                    check: 'token-prefix-violation',
+                    message: `CSS references var(${prop}) which does not match the required token prefix "${tokenPrefix}". Use a design token, add to tokenAllowlist, or (for runtime state channels) list the variable in runtimeVariables.`,
+                    severity: 'error',
+                });
             }
         }
     }

package/dist/src/types/commands/options.d.ts

@@ -271,6 +271,16 @@ export interface FurnaceCreateOptions {
     register?: boolean;
     /** Scaffold Mochitest directory and register in moz.build */
     withTests?: boolean;
+    /**
+     * Scaffold an xpcshell test harness (headless, no tabbrowser) instead of
+     * browser-chrome. Required for forks without a `tabbrowser` (storage-only
+     * code, observer-driven modules). Implies `withTests` when set. Writes an
+     * `xpcshell.toml` + `test_<name>.js` under
+     * `engine/browser/base/content/test/<binary-name>-xpcshell/` and leaves
+     * moz.build registration to the operator (add the directory to
+     * `XPCSHELL_TESTS_MANIFESTS`).
+     */
+    xpcshell?: boolean;
     /** Stock component tag names composed internally by this component */
     compose?: string[];
 }

package/dist/src/types/config.d.ts

@@ -47,7 +47,7 @@ export interface FireForgeConfig {
     /**
      * Project marker prefix appended to lines FireForge writes into
      * upstream Firefox source files (e.g. the `customElements.js` tag list).
-     * `"HOMINIS"` emits a trailing `  // HOMINIS:` on each inserted line.
+     * `"MYBROWSER"` emits a trailing `  // MYBROWSER:` on each inserted line.
      * Keeps modifications discoverable and re-applies idempotent.
      */
     markerComment?: string;

package/dist/src/types/furnace.d.ts

@@ -63,10 +63,21 @@ export interface FurnaceConfig {
     tokenPrefix?: string;
     /** Custom properties allowed even though they don't match tokenPrefix (e.g. ["--background-color-box"]) */
     tokenAllowlist?: string[];
+    /**
+     * Custom properties used as runtime state channels — written and read by the
+     * component itself (e.g. per-frame camera/tile positions) rather than
+     * consumed as design tokens. Listed names are exempt from the
+     * `token-prefix-violation` check even when they do not match `tokenPrefix`
+     * and are not in `tokenAllowlist`. Use this for cross-component runtime
+     * variables (e.g. set in JS, read in CSS of a child). Component-local
+     * variables that are both declared and consumed inside the same component's
+     * own CSS file are auto-exempted and do not need an entry here.
+     */
+    runtimeVariables?: string[];
     /**
      * Chrome documents scanned by the `missing-token-link` validator to confirm
      * the tokens CSS file is `<link>`ed. Forks with multiple chrome host
-     * documents (e.g. `hominis.xhtml` beside the stock `browser.xhtml`) should
+     * documents (e.g. `mybrowser.xhtml` beside the stock `browser.xhtml`) should
      * list every document that may own the link. When omitted, defaults to
      * `['browser/base/content/browser.xhtml']` — the upstream Firefox path.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.15.1",
+  "version": "0.15.2",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",