@hominis/fireforge 0.16.2 → 0.16.5

package/dist/src/commands/export-shared.js

@@ -4,6 +4,7 @@ import { confirm, select, text } from '@clack/prompts';
 import { addLicenseHeaderToFile, getLicenseHeader } from '../core/license-headers.js';
 import { findAllPatchesForFiles } from '../core/patch-export.js';
 import { commentStyleForFile, detectNewFilesInDiff, lintExportedPatch, } from '../core/patch-lint.js';
+import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { pathExists, readText } from '../utils/fs.js';
 import { cancel, info, isCancel, warn } from '../utils/logger.js';
@@ -222,4 +223,79 @@ export async function autoFixLicenseHeaders(engineDir, diffContent, config, isIn
     }
     return true;
 }
+/**
+ * Maps every file in `filesAffected` to the existing patches that already
+ * claim ownership of it, excluding the caller's own patch (when `newFilename`
+ * is provided) and any patches that the caller intends to fully supersede.
+ *
+ * Returns an empty map when no overlap exists. Used by the overlap gate in
+ * `export` and `export-all` to refuse a default-mode export that would
+ * silently create cross-patch ownership conflicts — the same class of
+ * conflict `verify` immediately fails with.
+ */
+export function findPartialOwnershipOverlap(manifest, filesAffected, excludeFilenames) {
+    const overlap = new Map();
+    const targetSet = new Set(filesAffected);
+    for (const patch of manifest.patches) {
+        if (excludeFilenames.has(patch.filename))
+            continue;
+        for (const file of patch.filesAffected) {
+            if (!targetSet.has(file))
+                continue;
+            const owners = overlap.get(file) ?? [];
+            owners.push(patch.filename);
+            overlap.set(file, owners);
+        }
+    }
+    return overlap;
+}
+/**
+ * Gate that refuses the default export path when the new patch would
+ * silently claim files that are already tracked by other non-superseded
+ * patches. `findAllPatchesForFiles` already catches the full-coverage
+ * supersede case — this helper fills the gap for partial overlap, which
+ * was the eval finding #12 scenario (two patches both claiming
+ * `browser/themes/shared/jar.inc.mn` after a second export with
+ * `--before`).
+ *
+ * Proceeds silently when there is no overlap, or when the caller passed
+ * `--allow-overlap`. In interactive mode the caller is prompted to
+ * acknowledge the overlap (the proper fix path is `re-export --files` to
+ * repartition ownership, so the prompt surfaces that pointer). In
+ * non-interactive mode the function throws — better to fail fast than
+ * let the queue fall out of sync with verify.
+ */
+export async function guardOwnershipOverlap(args) {
+    const { patchesDir, filesAffected, supersedingFilenames, allowOverlap, isInteractive, s } = args;
+    if (allowOverlap)
+        return true;
+    const manifest = await loadPatchesManifest(patchesDir);
+    if (!manifest)
+        return true;
+    const overlap = findPartialOwnershipOverlap(manifest, filesAffected, supersedingFilenames);
+    if (overlap.size === 0)
+        return true;
+    s.stop();
+    const entries = [...overlap.entries()].sort(([a], [b]) => a.localeCompare(b));
+    warn(`This export would create cross-patch ownership overlap on ${String(entries.length)} file${entries.length === 1 ? '' : 's'}:`);
+    for (const [file, owners] of entries) {
+        warn(`  - ${file} already claimed by: ${owners.join(', ')}`);
+    }
+    warn('The queue would fail `fireforge verify` immediately after this export. ' +
+        'To repartition ownership safely, run `fireforge re-export --files <paths> <existing-patch>` ' +
+        'on the overlapping patches first, then re-run the export.');
+    if (!isInteractive) {
+        throw new GeneralError('Refusing to export a queue with cross-patch ownership overlap in non-interactive mode. ' +
+            'Pass --allow-overlap to acknowledge the conflict, or repartition ownership via `fireforge re-export --files`.');
+    }
+    const confirmed = await confirm({
+        message: 'Proceed with overlapping ownership? This will leave the queue in a verify-failing state.',
+        initialValue: false,
+    });
+    if (isCancel(confirmed) || !confirmed) {
+        cancel('Export cancelled');
+        return false;
+    }
+    return true;
+}
 //# sourceMappingURL=export-shared.js.map

package/dist/src/commands/export.js

@@ -10,7 +10,7 @@ import { generateBinaryFilePatch, generateFullFilePatch } from '../core/git-diff
 import { isBinaryFile } from '../core/git-file-ops.js';
 import { getModifiedFilesInDir, getUntrackedFiles, getUntrackedFilesInDir, } from '../core/git-status.js';
 import { extractAffectedFiles } from '../core/patch-apply.js';
-import { commitExportedPatch } from '../core/patch-export.js';
+import { commitExportedPatch, findAllPatchesForFiles } from '../core/patch-export.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { ensureDir, pathExists } from '../utils/fs.js';
@@ -19,7 +19,7 @@ import { pickDefined } from '../utils/options.js';
 import { stripEnginePrefix } from '../utils/paths.js';
 import { parsePositiveIntegerFlag, PATCH_CATEGORIES } from '../utils/validation.js';
 import { commitPlacementExport, placementSummary, projectPlacementForLint, renderDryRunPreview, resolvePlacementPlan, } from './export-flow.js';
-import { autoFixLicenseHeaders, confirmSupersedePatches, promptExportPatchMetadata, runPatchLint, } from './export-shared.js';
+import { autoFixLicenseHeaders, confirmSupersedePatches, guardOwnershipOverlap, promptExportPatchMetadata, runPatchLint, } from './export-shared.js';
 async function collectExportFiles(paths, files) {
     const collectedFiles = new Set();
     let fileStatuses;
@@ -286,6 +286,26 @@ export async function exportCommand(projectRoot, files, options) {
         const shouldProceed = await confirmSupersedePatches(paths.patches, filesAffected, options.supersede, isInteractive, s);
         if (!shouldProceed)
             return;
+        // Overlap gate: pre-0.16.0 `export` only caught FULL-coverage
+        // supersedes, so a second export targeting a shared file like
+        // `browser/themes/shared/jar.inc.mn` happily created a queue where
+        // two patches both listed the same file in `filesAffected`. `verify`
+        // then failed immediately on "cross-patch filesAffected conflicts".
+        // `confirmSupersedePatches` might already have confirmed full
+        // supersedes above; pass their filenames through so we do not flag
+        // a file claimed by a patch that is about to be removed.
+        const willSupersede = await findAllPatchesForFiles(paths.patches, filesAffected);
+        const supersedingFilenames = new Set(willSupersede.map((p) => p.filename));
+        const shouldProceedPastOverlap = await guardOwnershipOverlap({
+            patchesDir: paths.patches,
+            filesAffected,
+            supersedingFilenames,
+            allowOverlap: options.allowOverlap === true,
+            isInteractive,
+            s,
+        });
+        if (!shouldProceedPastOverlap)
+            return;
         const { patchFilename, superseded } = await commitExportedPatch({
             patchesDir: paths.patches,
             category: selectedCategory,
@@ -327,6 +347,7 @@ export function registerExport(program, { getProjectRoot, withErrorHandling }) {
         .option('-y, --yes', 'Skip confirmation for placement renumbers (required for non-TTY)')
         .option('--force-unsafe', 'Bypass cross-patch lint refusal on projected placement')
         .option('--exclude-furnace', 'Exclude furnace-managed file paths from the export')
+        .option('--allow-overlap', 'Acknowledge cross-patch ownership overlap (default mode only; the resulting queue fails verify)')
         .action(withErrorHandling(async (paths, options) => {
         const { category, ...rest } = options;
         await exportCommand(getProjectRoot(), paths, {

package/dist/src/commands/furnace/chrome-doc-templates.d.ts

@@ -56,11 +56,29 @@ export declare function generateChromeDocCss(name: string, withTitlebar: boolean
 export declare function generateChromeDocFtl(name: string, licenseHeader: string): string;
 /**
  * Single-line jar.mn entry that registers an xhtml + js pair under
- * `content/browser/`. Emits the `*` preprocessor flag so both files flow
- * through `#filter substitution` for FireForge brand-name substitution.
+ * `content/browser/`.
+ *
+ * Neither emitted line carries the `*` preprocessor flag. The scaffolded
+ * XHTML and JS contain no `#filter` / `#expand` / `#include` directives,
+ * and mach's `process_install_manifest.py` fails the whole package step
+ * with "no preprocessor directives found" when a preprocessed entry has
+ * nothing for the preprocessor to do. A fork that later needs brand
+ * substitution can re-introduce `*` and add a top-of-file
+ * `#filter substitution` directive itself.
  */
 export declare function jarMnEntriesForChromeDoc(name: string): string[];
-/** jar.inc.mn entry that registers the scoped CSS under `content/browser/`. */
+/**
+ * jar.inc.mn entry that registers the scoped CSS under `content/browser/`.
+ *
+ * The source path is `../shared/<name>-chrome.css` because `jar.inc.mn`
+ * is included from each theme-specific manifest (`browser/themes/osx/jar.mn`,
+ * `browser/themes/linux/jar.mn`, `browser/themes/windows/jar.mn`), and every
+ * existing entry in those manifests resolves paths relative to the including
+ * manifest's directory. A bare `(shared/…)` path produced
+ * `obj-.../browser/themes/osx/shared/<name>-chrome.css` which does not exist;
+ * `(../shared/…)` matches the upstream pattern and resolves under
+ * `browser/themes/shared/`.
+ */
 export declare function jarIncMnEntryForChromeDoc(name: string): string;
 /**
  * locales/jar.mn entry that registers the `.ftl` under the browser locale

package/dist/src/commands/furnace/chrome-doc-templates.js

@@ -149,18 +149,36 @@ ${name}-window-title = ${name}
 }
 /**
  * Single-line jar.mn entry that registers an xhtml + js pair under
- * `content/browser/`. Emits the `*` preprocessor flag so both files flow
- * through `#filter substitution` for FireForge brand-name substitution.
+ * `content/browser/`.
+ *
+ * Neither emitted line carries the `*` preprocessor flag. The scaffolded
+ * XHTML and JS contain no `#filter` / `#expand` / `#include` directives,
+ * and mach's `process_install_manifest.py` fails the whole package step
+ * with "no preprocessor directives found" when a preprocessed entry has
+ * nothing for the preprocessor to do. A fork that later needs brand
+ * substitution can re-introduce `*` and add a top-of-file
+ * `#filter substitution` directive itself.
  */
 export function jarMnEntriesForChromeDoc(name) {
     return [
-        `*   content/browser/${name}.xhtml                (content/${name}.xhtml)`,
+        `    content/browser/${name}.xhtml                (content/${name}.xhtml)`,
         `    content/browser/${name}.js                   (content/${name}.js)`,
     ];
 }
-/** jar.inc.mn entry that registers the scoped CSS under `content/browser/`. */
+/**
+ * jar.inc.mn entry that registers the scoped CSS under `content/browser/`.
+ *
+ * The source path is `../shared/<name>-chrome.css` because `jar.inc.mn`
+ * is included from each theme-specific manifest (`browser/themes/osx/jar.mn`,
+ * `browser/themes/linux/jar.mn`, `browser/themes/windows/jar.mn`), and every
+ * existing entry in those manifests resolves paths relative to the including
+ * manifest's directory. A bare `(shared/…)` path produced
+ * `obj-.../browser/themes/osx/shared/<name>-chrome.css` which does not exist;
+ * `(../shared/…)` matches the upstream pattern and resolves under
+ * `browser/themes/shared/`.
+ */
 export function jarIncMnEntryForChromeDoc(name) {
-    return `    content/browser/${name}-chrome.css           (shared/${name}-chrome.css)`;
+    return `    content/browser/${name}-chrome.css           (../shared/${name}-chrome.css)`;
 }
 /**
  * locales/jar.mn entry that registers the `.ftl` under the browser locale

package/dist/src/commands/furnace/chrome-doc-tests.js

@@ -69,32 +69,57 @@ export function generateChromeDocPackagingTest(name, header) {
 add_task(async function test_${taskSuffix}_files_packaged() {
   const appDir = Services.dirsvc.get("XCurProcD", Ci.nsIFile);
 
-  function probe(segments, description) {
-    const file = appDir.clone();
-    for (const segment of segments) {
-      file.append(segment);
+  // Probes a pair of candidate layouts for the same packaged file:
+  //   1) \`<AppDir>/chrome/browser/…\` — the unpacked layout when
+  //      XCurProcD honours \`firefox-appdir = "browser"\` and resolves
+  //      into \`dist/bin/browser/\`.
+  //   2) \`<AppDir>/browser/chrome/browser/…\` — the macOS .app bundle
+  //      layout and some ESR configurations, where XCurProcD sits one
+  //      level above \`browser/\` even when the appdir directive is set.
+  // If either path exists the file is packaged; the assertion only fails
+  // when BOTH layouts miss, which is the actual stale-build / missing
+  // jar.mn entry case. Before this dual probe, the eval on macOS
+  // consistently failed against layout (2) even though the file was
+  // packaged correctly.
+  function probeEither(primary, fallback, description) {
+    const primaryFile = appDir.clone();
+    for (const segment of primary) {
+      primaryFile.append(segment);
     }
+    const fallbackFile = appDir.clone();
+    for (const segment of fallback) {
+      fallbackFile.append(segment);
+    }
+    const found = primaryFile.exists() ? primaryFile : fallbackFile.exists() ? fallbackFile : null;
     Assert.ok(
-      file.exists(),
-      description + " missing at " + file.path +
-        ' — run "fireforge build --ui" and retry. If the file is present under ' +
-        "obj-*/dist/ but absent from this path, the xpcshell harness is probing " +
-        "a stale build tree; the post-build audit should flag the same miss.",
-    );
-    Assert.greater(
-      file.fileSize,
-      0,
-      description + " is zero-length at " + file.path +
-        " — packaging copied an empty file, check the source template.",
+      found !== null,
+      description +
+        " missing at both " +
+        primaryFile.path +
+        " and " +
+        fallbackFile.path +
+        ' — run "fireforge build --ui" and retry. If one of those paths IS populated, the xpcshell harness is probing a stale build tree; the post-build audit should flag the same miss.',
     );
+    if (found !== null) {
+      Assert.greater(
+        found.fileSize,
+        0,
+        description +
+          " is zero-length at " +
+          found.path +
+          " — packaging copied an empty file, check the source template.",
+      );
+    }
   }
 
-  probe(
+  probeEither(
     ["chrome", "browser", "content", "browser", "${name}.xhtml"],
+    ["browser", "chrome", "browser", "content", "browser", "${name}.xhtml"],
     "${name}.xhtml",
   );
-  probe(
+  probeEither(
     ["chrome", "browser", "skin", "classic", "browser", "${name}-chrome.css"],
+    ["browser", "chrome", "browser", "skin", "classic", "browser", "${name}-chrome.css"],
     "${name}-chrome.css",
   );
 });

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

@@ -0,0 +1,23 @@
+/**
+ * Defensive read-back helper for `furnace create`. Extracted from
+ * `create.ts` so the authoring command stays under the per-file LOC
+ * budget.
+ */
+/**
+ * Asserts that the just-written furnace.json contains the expected
+ * custom component entry. The eval run's finding #9 observed a
+ * scenario where `furnace create --allow-prefix-mismatch` reported
+ * success and wrote the component files, but the subsequent
+ * `furnace status` found `custom: {}` in furnace.json — an invariant
+ * violation with no clear smoking gun in the code path. Local repros
+ * do not trigger it, so the defensive readback is the safest recovery
+ * contract we can offer: if the new entry is not visible on the next
+ * load, throw a `FurnaceError` so the rollback journal restores the
+ * pre-command state and the operator sees the failure instead of a
+ * phantom success.
+ *
+ * @param projectRoot - Root of the FireForge project
+ * @param componentName - Custom-element tag name that must be present
+ *   in `config.custom` after the write. Throws when absent.
+ */
+export declare function assertCustomEntryPersisted(projectRoot: string, componentName: string): Promise<void>;

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

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Defensive read-back helper for `furnace create`. Extracted from
+ * `create.ts` so the authoring command stays under the per-file LOC
+ * budget.
+ */
+import { loadFurnaceConfig } from '../../core/furnace-config.js';
+import { FurnaceError } from '../../errors/furnace.js';
+/**
+ * Asserts that the just-written furnace.json contains the expected
+ * custom component entry. The eval run's finding #9 observed a
+ * scenario where `furnace create --allow-prefix-mismatch` reported
+ * success and wrote the component files, but the subsequent
+ * `furnace status` found `custom: {}` in furnace.json — an invariant
+ * violation with no clear smoking gun in the code path. Local repros
+ * do not trigger it, so the defensive readback is the safest recovery
+ * contract we can offer: if the new entry is not visible on the next
+ * load, throw a `FurnaceError` so the rollback journal restores the
+ * pre-command state and the operator sees the failure instead of a
+ * phantom success.
+ *
+ * @param projectRoot - Root of the FireForge project
+ * @param componentName - Custom-element tag name that must be present
+ *   in `config.custom` after the write. Throws when absent.
+ */
+export async function assertCustomEntryPersisted(projectRoot, componentName) {
+    const persisted = await loadFurnaceConfig(projectRoot);
+    if (!(componentName in persisted.custom)) {
+        throw new FurnaceError(`Wrote furnace.json but "${componentName}" is missing from config.custom on read-back. ` +
+            'This should not happen — please report the issue. As a workaround, ' +
+            're-run the command, or add the entry to furnace.json by hand.', componentName);
+    }
+}
+//# sourceMappingURL=create-readback.js.map

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

@@ -33,13 +33,23 @@ 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.
+ * xpcshell cannot execute a component module that imports
+ * `chrome://global/content/vendor/lit.all.mjs` — the Lit bundle touches
+ * `window` at module-load time and the xpcshell harness has no `window`
+ * global. Before 0.16.0 the scaffold called `ChromeUtils.importESModule`
+ * on the component's MJS, which reliably failed with
+ * `ReferenceError: window is not defined` for every Lit-based fork
+ * component. FireForge's diagnostics then misrouted the failure to the
+ * "stale build artifacts" branch, sending operators on a rebuild loop
+ * that couldn't fix a runtime-environment incompatibility.
+ *
+ * The rewrite here mirrors the chrome-doc packaging test: XCurProcD is
+ * probed at a pair of candidate layouts (dist/bin/browser and the macOS
+ * .app-bundle / ESR layout) to confirm the `.mjs` and `.css` files
+ * landed where jar.mn promised. That's the assertion xpcshell CAN make.
+ * Functional tests that need DOM/shadow-root/keyboard behaviour belong
+ * in a browser-chrome mochitest — scaffolded via
+ * `fireforge furnace create --test-style browser-chrome`.
  */
 export declare function generateXpcshellTestContent(name: string, header: string): string;
 /**

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

@@ -93,48 +93,102 @@ export function generateFtlContent(name, header) {
 }
 /** Returns the canonical xpcshell test file basename for a component. */
 export function xpcshellTestFileName(name) {
-    return `test_${name.replace(/-/g, '_')}_module_loads.js`;
+    return `test_${name.replace(/-/g, '_')}_packaged.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.
+ * xpcshell cannot execute a component module that imports
+ * `chrome://global/content/vendor/lit.all.mjs` — the Lit bundle touches
+ * `window` at module-load time and the xpcshell harness has no `window`
+ * global. Before 0.16.0 the scaffold called `ChromeUtils.importESModule`
+ * on the component's MJS, which reliably failed with
+ * `ReferenceError: window is not defined` for every Lit-based fork
+ * component. FireForge's diagnostics then misrouted the failure to the
+ * "stale build artifacts" branch, sending operators on a rebuild loop
+ * that couldn't fix a runtime-environment incompatibility.
+ *
+ * The rewrite here mirrors the chrome-doc packaging test: XCurProcD is
+ * probed at a pair of candidate layouts (dist/bin/browser and the macOS
+ * .app-bundle / ESR layout) to confirm the `.mjs` and `.css` files
+ * landed where jar.mn promised. That's the assertion xpcshell CAN make.
+ * Functional tests that need DOM/shadow-root/keyboard behaviour belong
+ * in a browser-chrome mochitest — scaffolded via
+ * `fireforge furnace create --test-style browser-chrome`.
  */
 export function generateXpcshellTestContent(name, header) {
+    const taskSuffix = name.replace(/-/g, '_');
     return `${header}
 
 "use strict";
 
-// Chrome-URI access from xpcshell:
-//   Toolkit chrome (chrome://global/*) IS registered and resolvable from
-//   this harness — that is what the smoke assertion below uses.
+// Packaging verification for the "${name}" custom component.
+//
+// Why this is not a module-load test:
+//   ChromeUtils.importESModule("chrome://global/content/elements/${name}.mjs")
+//   pulls in \`chrome://global/content/vendor/lit.all.mjs\`, which
+//   references \`window\` during its module body — there is no \`window\`
+//   global in xpcshell, so every attempt throws
+//   \`ReferenceError: window is not defined\`. For Lit-based components,
+//   xpcshell can only verify that the files reached the packaged tree;
+//   functional UI assertions belong in a browser-chrome mochitest
+//   (see \`fireforge furnace create --test-style browser-chrome\`).
 //
-//   Browser chrome (chrome://browser/*) is NOT registered unless the
-//   xpcshell.toml sets firefox-appdir = "browser" AND the built app bundle
-//   has landed every packaged chrome manifest. Even then, the set of
-//   manifests xpcshell loads lags what the real browser loads, so
-//   NetUtil.asyncFetch("chrome://browser/content/…") can still fail with
-//   NS_ERROR_FILE_NOT_FOUND against an artifact that IS present in
-//   obj-*/dist/. Assertions that need browser chrome URIs belong in a
-//   browser-chrome mochitest (fireforge furnace create --test-style=browser-chrome),
-//   not xpcshell.
-
-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).",
+// Out of scope: builds that pack omni.ja (MOZ_CHROME_MULTILOCALE, some
+// release configs). The probe assumes an unpacked tree, which is what
+// \`mach build\` produces by default. A packed build would need to unzip
+// omni.ja to verify the same files.
+
+add_task(async function test_${taskSuffix}_files_packaged() {
+  const appDir = Services.dirsvc.get("XCurProcD", Ci.nsIFile);
+
+  // Two candidate layouts are probed per asset:
+  //   1) \`<AppDir>/chrome/global/elements/…\` — unpacked layout when
+  //      XCurProcD honours \`firefox-appdir = "browser"\` and resolves
+  //      into \`dist/bin/browser/\`.
+  //   2) \`<AppDir>/browser/chrome/global/elements/…\` — macOS .app
+  //      bundle and some ESR layouts where XCurProcD sits one level
+  //      above \`browser/\`.
+  function probeEither(primary, fallback, description) {
+    const primaryFile = appDir.clone();
+    for (const segment of primary) {
+      primaryFile.append(segment);
+    }
+    const fallbackFile = appDir.clone();
+    for (const segment of fallback) {
+      fallbackFile.append(segment);
+    }
+    const found = primaryFile.exists() ? primaryFile : fallbackFile.exists() ? fallbackFile : null;
+    Assert.ok(
+      found !== null,
+      description +
+        " missing at both " +
+        primaryFile.path +
+        " and " +
+        fallbackFile.path +
+        ' — run "fireforge build --ui" and retry. If the file IS present at one of those paths, xpcshell is probing a stale build tree.',
+    );
+    if (found !== null) {
+      Assert.greater(
+        found.fileSize,
+        0,
+        description +
+          " is zero-length at " +
+          found.path +
+          " — packaging copied an empty file, check the source template.",
+      );
+    }
+  }
+
+  probeEither(
+    ["chrome", "global", "elements", "${name}.mjs"],
+    ["browser", "chrome", "global", "elements", "${name}.mjs"],
+    "${name}.mjs",
+  );
+  probeEither(
+    ["chrome", "global", "elements", "${name}.css"],
+    ["browser", "chrome", "global", "elements", "${name}.css"],
+    "${name}.css",
   );
 });
 `;

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

@@ -13,7 +13,7 @@ import type { ProjectLicense } from '../../types/config.js';
  * 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
+ * Writes `test_<name>_packaged.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

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

@@ -18,7 +18,7 @@ import { generateXpcshellManifestContent, generateXpcshellTestContent, xpcshellT
  * 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
+ * Writes `test_<name>_packaged.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

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

@@ -19,6 +19,7 @@ import { cancel, intro, isCancel, note, outro, success, warn } from '../../utils
 import { formatDryRunPlan, formatSuccessNote } from './create-dry-run.js';
 import { resolveCreateFeatures } from './create-features.js';
 import { scaffoldMochikitTestFiles } from './create-mochikit.js';
+import { assertCustomEntryPersisted } from './create-readback.js';
 import { generateCssContent, generateFtlContent, generateMjsContent } from './create-templates.js';
 import { scaffoldXpcshellTestFiles } from './create-xpcshell.js';
 async function loadAuthoringFurnaceConfig(projectRoot) {
@@ -266,6 +267,7 @@ async function performCreateMutations(args) {
         args.config.custom[args.componentName] = customEntry;
         await snapshotFile(journal, args.furnacePaths.furnaceConfig);
         await writeFurnaceConfig(args.projectRoot, args.config);
+        await assertCustomEntryPersisted(args.projectRoot, args.componentName);
         if (args.testStyle === 'browser-chrome') {
             const scafFiles = await scaffoldTestFiles(args.componentName, args.license, args.forgeConfig, args.paths, journal);
             testFiles.push(...scafFiles);

package/dist/src/commands/furnace/preview.d.ts

@@ -1,4 +1,16 @@
 import type { FurnacePreviewOptions } from '../../types/commands/index.js';
+/**
+ * Builds a targeted Storybook failure message from captured mach output.
+ *
+ * Exported for the test suite: the heuristic has three branches (backend
+ * artifact missing, Storybook dep missing, generic) and regression
+ * testing each is easier when the classifier is addressable directly.
+ *
+ * @param output - Combined stdout and stderr from the Storybook command
+ * @param installRequested - Whether the caller requested a dependency reinstall first
+ * @returns User-facing guidance for the specific failure mode
+ */
+export declare function buildStorybookFailureMessage(output: string, installRequested: boolean): string;
 /**
  * Runs the furnace preview command to start Storybook for component preview.
  * @param projectRoot - Root directory of the project

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

@@ -72,17 +72,49 @@ function reportPreviewStagingFailures(stageResult) {
     const totalFailures = stageResult.errors.length + appliedWithStepErrorsCount;
     throw new FurnaceError(`${totalFailures} component${totalFailures === 1 ? '' : 's'} failed to stage for preview`);
 }
+/**
+ * Filenames emitted by the Firefox build backend (not by Storybook's npm
+ * package set) — their absence means `mach build` has not produced its
+ * post-configure artifacts, which is a different failure mode from a
+ * missing Storybook workspace dependency tree. The eval log for finding
+ * #11 reported `FileNotFoundError: [...] chrome-map.json` *after* a
+ * successful Storybook `npm install`, and the pre-0.16 heuristic
+ * misdiagnosed it as a dep failure and sent the operator back to
+ * `--install`. Pattern list is narrow on purpose so we only surface the
+ * backend-rebuild hint when we are confident.
+ */
+const BACKEND_ARTIFACT_PATTERNS = [
+    /chrome-map\.json/i,
+    /config\.status/i,
+    /obj-[^\s/]+\/dist\/bin\/\.lldbinit/i,
+];
 /**
  * Builds a targeted Storybook failure message from captured mach output.
+ *
+ * Exported for the test suite: the heuristic has three branches (backend
+ * artifact missing, Storybook dep missing, generic) and regression
+ * testing each is easier when the classifier is addressable directly.
+ *
  * @param output - Combined stdout and stderr from the Storybook command
  * @param installRequested - Whether the caller requested a dependency reinstall first
  * @returns User-facing guidance for the specific failure mode
  */
-function buildStorybookFailureMessage(output, installRequested) {
+export function buildStorybookFailureMessage(output, installRequested) {
     const installHint = installRequested
         ? 'Try running "python3 ./mach storybook upgrade" manually in the engine directory.'
         : 'Run "fireforge furnace preview --install" to bootstrap Storybook dependencies, or run "python3 ./mach storybook upgrade" manually in engine/.';
-    if (/(ENOENT|No such file or directory)/i.test(output) && /storybook|backend/i.test(output)) {
+    const hasFileNotFoundSignal = /(ENOENT|No such file or directory|FileNotFoundError)/i.test(output);
+    // Check backend-artifact signal first — a missing chrome-map.json looks
+    // like any other "No such file" error to a naïve regex, but the fix is
+    // to rerun `fireforge build`, not to reinstall Storybook dependencies.
+    if (hasFileNotFoundSignal && BACKEND_ARTIFACT_PATTERNS.some((p) => p.test(output))) {
+        return ('Storybook failed because the Firefox build backend artifacts are missing or stale ' +
+            '(chrome-map.json / config.status / obj-*/dist/bin/.lldbinit). ' +
+            'This is a Firefox-build completeness issue, not a Storybook dependency issue.\n\n' +
+            'Rerun "fireforge build" and let it finish, then retry "fireforge furnace preview". ' +
+            'A full rebuild regenerates the backend artifacts Storybook reads.');
+    }
+    if (hasFileNotFoundSignal && /storybook|backend/i.test(output)) {
         return ('Storybook failed because the Firefox checkout appears to be missing Storybook workspace files or backend dependencies.\n\n' +
             installHint);
     }