@hominis/fireforge 0.15.6 → 0.15.8

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

@@ -0,0 +1,120 @@
+// SPDX-License-Identifier: EUPL-1.2
+/*
+ * Packaging-verification test templates for
+ * `fireforge furnace chrome-doc create --with-tests`.
+ *
+ * Motivation: an operator who scaffolds a top-level chrome document wants
+ * to know "did the file actually land in the packaged bundle?" before
+ * relying on it at runtime. Both natural test harnesses have gaps for
+ * this question:
+ *
+ *   - xpcshell's `chrome://browser/*` URI registration lags what the real
+ *     browser loads even with `firefox-appdir = "browser"` set, so
+ *     `NetUtil.asyncFetch("chrome://browser/content/<name>.xhtml")` can
+ *     fail with `NS_ERROR_FILE_NOT_FOUND` against a file that IS
+ *     correctly packaged (the motivating case).
+ *   - Browser-chrome mochitests require a `tabbrowser`, which a
+ *     fork-authored chrome doc that replaces `browser.xhtml` deliberately
+ *     does not carry (the URILoadingHelper crash path).
+ *
+ * This scaffold threads the needle by probing the filesystem directly:
+ * `Services.dirsvc.get("XCurProcD", Ci.nsIFile)` returns the current
+ * process directory (the browser app dir when `firefox-appdir = "browser"`),
+ * and the packaged chrome layout for a jar.mn entry
+ * `content/browser/<name>.xhtml` is stable across platforms at
+ * `<AppDir>/chrome/browser/content/browser/<name>.xhtml` on an unpacked
+ * tree (the default for `mach build` without `MOZ_CHROME_MULTILOCALE`
+ * / omnijar). A tree that packs omni.ja would need a different probe;
+ * the scaffold notes that out-of-scope case explicitly rather than
+ * silently producing a test that fails on packed builds.
+ */
+/**
+ * Returns the canonical xpcshell test basename for a chrome doc packaging
+ * check (`test_<name>_packaging.js`). Hyphens in `<name>` are preserved —
+ * xpcshell permits them in file basenames even though the derived task
+ * function names replace them with underscores.
+ */
+export function chromeDocPackagingTestFileName(name) {
+    return `test_${name}_packaging.js`;
+}
+/**
+ * Emits an xpcshell test that verifies the scaffolded chrome doc's
+ * `.xhtml`, `-chrome.css`, and `.ftl` are all present under the packaged
+ * app directory. Each assertion carries the exact probed path in its
+ * failure message so an operator reading a red CI run knows which
+ * jar.mn entry or build step dropped the file.
+ */
+export function generateChromeDocPackagingTest(name, header) {
+    const taskSuffix = name.replace(/-/g, '_');
+    return `${header}
+
+"use strict";
+
+// Packaging verification for the "${name}" chrome document.
+//
+// Scope: reads the packaged tree under XCurProcD (the browser app dir
+// when firefox-appdir = "browser") and asserts that the three
+// scaffolded files landed where the jar.mn / jar.inc.mn / locales/jar.mn
+// entries promised. Does NOT go through chrome:// URI resolution —
+// xpcshell's chrome manifest set lags the real browser's even with
+// firefox-appdir = "browser", so NetUtil.asyncFetch on
+// chrome://browser/content/${name}.xhtml can fail with
+// NS_ERROR_FILE_NOT_FOUND against a file that IS packaged.
+//
+// Out of scope: builds that pack omni.ja (MOZ_CHROME_MULTILOCALE, some
+// release configs). The probe below 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);
+
+  function probe(segments, description) {
+    const file = appDir.clone();
+    for (const segment of segments) {
+      file.append(segment);
+    }
+    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.",
+    );
+  }
+
+  probe(
+    ["chrome", "browser", "content", "browser", "${name}.xhtml"],
+    "${name}.xhtml",
+  );
+  probe(
+    ["chrome", "browser", "skin", "classic", "browser", "${name}-chrome.css"],
+    "${name}-chrome.css",
+  );
+});
+`;
+}
+/**
+ * Emits the `xpcshell.toml` manifest for the packaging test directory.
+ * Sets `firefox-appdir = "browser"` so XCurProcD resolves to the browser
+ * subdir rather than the generic gecko runtime dir — without that, the
+ * path probe walks the wrong tree on every fork whose app directory is
+ * not the default.
+ */
+export function generateChromeDocPackagingManifest(name, header) {
+    return `${header}
+
+[DEFAULT]
+head = ""
+firefox-appdir = "browser"
+
+["${chromeDocPackagingTestFileName(name)}"]
+`;
+}
+//# sourceMappingURL=chrome-doc-tests.js.map

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

@@ -24,6 +24,17 @@ export interface FurnaceChromeDocCreateOptions {
      * `--no-titlebar`.
      */
     titlebar?: boolean;
+    /**
+     * Scaffold an xpcshell packaging-verification test alongside the chrome
+     * document. The generated test probes `XCurProcD/chrome/browser/...` on
+     * disk rather than going through `chrome://` URI resolution — that
+     * bypasses xpcshell's limited browser-chrome manifest set (the
+     * motivating failure mode where `NetUtil.asyncFetch` returns
+     * `NS_ERROR_FILE_NOT_FOUND` against a file that IS packaged).
+     * Registration in `XPCSHELL_TESTS_MANIFESTS` is left to the operator
+     * because the owning moz.build depends on the fork's layout.
+     */
+    withTests?: boolean;
 }
 /**
  * Runs `furnace chrome-doc create <name>`.

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

@@ -26,6 +26,7 @@ import { FurnaceError } from '../../errors/furnace.js';
 import { pathExists, readText, writeText } from '../../utils/fs.js';
 import { intro, note, outro } from '../../utils/logger.js';
 import { generateChromeDocCss, generateChromeDocFtl, generateChromeDocJs, generateChromeDocXhtml, jarIncMnEntryForChromeDoc, jarMnEntriesForChromeDoc, localeJarMnEntryForChromeDoc, } from './chrome-doc-templates.js';
+import { chromeDocPackagingTestFileName, generateChromeDocPackagingManifest, generateChromeDocPackagingTest, } from './chrome-doc-tests.js';
 /** Chrome-doc name shape: lowercase ASCII, optional hyphens, no leading digit. */
 const CHROME_DOC_NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 /**
@@ -123,6 +124,28 @@ async function performChromeDocMutations(args) {
         const localeJarMnPath = join(args.engineDir, 'browser/locales/jar.mn');
         await appendJarEntryIfAbsent(localeJarMnPath, localeJarMnEntryForChromeDoc(args.name), journal);
         written.push('browser/locales/jar.mn');
+        // --with-tests scaffolds an xpcshell packaging verification. All writes
+        // go through the same rollback journal so a SIGINT here restores the
+        // source files and jar.mn edits above alongside the test scaffold.
+        if (args.withTests) {
+            const testParentDir = `${args.binaryName}-xpcshell`;
+            const testDir = join(args.engineDir, 'browser/base/content/test', testParentDir, args.name);
+            const { ensureDir } = await import('../../utils/fs.js');
+            if (!(await pathExists(testDir))) {
+                recordCreatedDir(journal, testDir);
+            }
+            await ensureDir(testDir);
+            const hashHeader = getLicenseHeader(args.license, 'hash');
+            const testFileName = chromeDocPackagingTestFileName(args.name);
+            const testFilePath = join(testDir, testFileName);
+            await snapshotFile(journal, testFilePath);
+            await writeText(testFilePath, generateChromeDocPackagingTest(args.name, jsHeader));
+            written.push(`browser/base/content/test/${testParentDir}/${args.name}/${testFileName}`);
+            const manifestPath = join(testDir, 'xpcshell.toml');
+            await snapshotFile(journal, manifestPath);
+            await writeText(manifestPath, generateChromeDocPackagingManifest(args.name, hashHeader));
+            written.push(`browser/base/content/test/${testParentDir}/${args.name}/xpcshell.toml`);
+        }
     }
     catch (error) {
         await restoreRollbackJournalOrThrow(journal, `Failed to scaffold chrome-doc "${args.name}"`);
@@ -146,22 +169,32 @@ export async function furnaceChromeDocCreateCommand(projectRoot, name, options =
         throw new FurnaceError('Engine directory not found. Run "fireforge download" first to scaffold a chrome-doc.');
     }
     const withTitlebar = options.titlebar ?? true;
+    const withTests = options.withTests ?? false;
     const written = await runFurnaceMutation(projectRoot, 'chrome-doc-rollback', (ctx) => performChromeDocMutations({
         name,
         license,
         engineDir,
         withTitlebar,
+        withTests,
+        binaryName: forgeConfig.binaryName,
         operationContext: ctx,
     }));
+    const nextSteps = [
+        `  1. Edit engine/browser/base/content/${name}.xhtml and fill in the body.`,
+        `  2. Localize strings in engine/browser/locales/en-US/browser/${name}.ftl.`,
+        `  3. Run "fireforge build" to validate packaging (post-build audit will flag`,
+        '     any entry whose file does not land in the dist bundle).',
+    ];
+    if (withTests) {
+        nextSteps.push(`  4. Register the xpcshell test directory in the nearest moz.build under`, `     XPCSHELL_TESTS_MANIFESTS, then run "fireforge test browser/base/content/test/${forgeConfig.binaryName}-xpcshell/${name}/xpcshell.toml".`);
+    }
+    nextSteps.push('', 'Platform-module compatibility: this chrome document carries the', `  data-furnace-chrome-doc="${name}" sentinel on its root element. Upstream`, '  platform modules (DevToolsStartup, PageActions, SessionStore, …) observe', '  "browser-delayed-startup-finished" and walk INTO the window assuming the', '  browser.xhtml DOM; use the sentinel attribute as a guard in fork-side', '  patches to those modules. See README "Platform module compatibility".');
     note([
         `Chrome document "${name}" scaffolded:`,
         ...written.map((f) => `  engine/${f}`),
         '',
         'Next steps:',
-        `  1. Edit engine/browser/base/content/${name}.xhtml and fill in the body.`,
-        `  2. Localize strings in engine/browser/locales/en-US/browser/${name}.ftl.`,
-        `  3. Run "fireforge build" to validate packaging (post-build audit will flag`,
-        '     any entry whose file does not land in the dist bundle).',
+        ...nextSteps,
     ].join('\n'), name);
     outro('Chrome document created');
 }

package/dist/src/commands/furnace/create-dry-run.d.ts

@@ -0,0 +1,38 @@
+import type { ResolvedTestStyle } from './create.js';
+export interface DryRunPlanInput {
+    componentName: string;
+    localized: boolean;
+    register: boolean;
+    composes: string[] | undefined;
+    /**
+     * Feature-scoped Fluent bundle the component participates in (the same
+     * value that will be written to `furnace.json`'s `sharedFtl`). When set,
+     * the component's own `.ftl` is NOT scaffolded and the plan preview
+     * reflects that. Omit the key for the default per-component scaffold.
+     */
+    sharedFtl?: string;
+    testStyle: ResolvedTestStyle;
+    description: string;
+    binaryName: string;
+}
+/**
+ * Builds the success-note body printed after `furnace create` has applied
+ * its mutations. Lives beside the dry-run formatter so the two renderings
+ * stay in lock-step when the scaffolded layout changes.
+ */
+export declare function formatSuccessNote(args: {
+    componentName: string;
+    files: string[];
+    testFiles: string[];
+    testStyle: ResolvedTestStyle;
+    binaryName: string;
+}): string;
+/**
+ * Builds the planned component + test file list for a dry-run preview.
+ *
+ * Mirrors the order `writeComponentFiles` and the test-style scaffolders
+ * would produce so the dry-run output matches what a real run prints on
+ * success. The component directory path is rendered relative to
+ * `components/custom/` to match the wording of the real success note.
+ */
+export declare function formatDryRunPlan(args: DryRunPlanInput): string;

package/dist/src/commands/furnace/create-dry-run.js

@@ -0,0 +1,100 @@
+// SPDX-License-Identifier: EUPL-1.2
+/*
+ * Dry-run plan formatter for `furnace create`.
+ *
+ * Lives outside `create.ts` so the authoring command stays under the
+ * per-file LOC budget. The formatter is pure — all inputs are already
+ * resolved by the command's validation phase — so it can be exercised
+ * independently of the mutation plumbing.
+ */
+/**
+ * Builds the test-section fragment of the dry-run plan for a given
+ * harness choice. Kept separate from the top-level formatter so the
+ * switch over `testStyle` does not push the caller over the per-function
+ * complexity budget.
+ */
+function formatTestSection(args) {
+    const { testStyle, componentName, binaryName } = args;
+    if (testStyle === 'none')
+        return '';
+    const strippedName = componentName.startsWith('moz-') ? componentName.slice(4) : componentName;
+    const withoutBinaryPrefix = strippedName.startsWith(binaryName + '-')
+        ? strippedName.slice(binaryName.length + 1)
+        : strippedName;
+    const underscored = withoutBinaryPrefix.replace(/-/g, '_');
+    if (testStyle === 'browser-chrome') {
+        const testRoot = `engine/browser/base/content/test/${binaryName}/`;
+        return (`\n\nWould create test files in ${testRoot}:\n` +
+            `  browser.toml\n  head.js\n  browser_${binaryName}_${underscored}.js` +
+            `\n\nWould register ${binaryName}/browser.toml in engine/browser/base/moz.build`);
+    }
+    if (testStyle === 'xpcshell') {
+        const testRoot = `engine/browser/base/content/test/${binaryName}-xpcshell/${componentName}/`;
+        return `\n\nWould create xpcshell test files in ${testRoot}`;
+    }
+    // testStyle === 'mochikit' (last remaining branch in ResolvedTestStyle).
+    const testRoot = 'engine/toolkit/content/tests/widgets/';
+    return `\n\nWould create mochikit test file in ${testRoot}`;
+}
+/**
+ * Builds the success-note body printed after `furnace create` has applied
+ * its mutations. Lives beside the dry-run formatter so the two renderings
+ * stay in lock-step when the scaffolded layout changes.
+ */
+export function formatSuccessNote(args) {
+    const { componentName, files, testFiles, testStyle, binaryName } = args;
+    let note = `Files created in components/custom/${componentName}/:\n` +
+        files.map((f) => `  ${f}`).join('\n');
+    if (testFiles.length > 0) {
+        let testRoot;
+        if (testStyle === 'xpcshell') {
+            testRoot = `engine/browser/base/content/test/${binaryName}-xpcshell/${componentName}/`;
+        }
+        else if (testStyle === 'mochikit') {
+            testRoot = 'engine/toolkit/content/tests/widgets/';
+        }
+        else {
+            testRoot = `engine/browser/base/content/test/${binaryName}/`;
+        }
+        note += `\n\nTest files in ${testRoot}:\n` + testFiles.map((f) => `  ${f}`).join('\n');
+    }
+    note +=
+        '\n\n' +
+            'Next steps:\n' +
+            `  1. Edit component files in components/custom/${componentName}/\n` +
+            '  2. Run "fireforge furnace preview" to see it\n' +
+            '  3. Run "fireforge build" to apply and build';
+    return note;
+}
+/**
+ * Builds the planned component + test file list for a dry-run preview.
+ *
+ * Mirrors the order `writeComponentFiles` and the test-style scaffolders
+ * would produce so the dry-run output matches what a real run prints on
+ * success. The component directory path is rendered relative to
+ * `components/custom/` to match the wording of the real success note.
+ */
+export function formatDryRunPlan(args) {
+    const { componentName, localized, register, composes, sharedFtl, testStyle, description, binaryName, } = args;
+    const componentFiles = [`${componentName}.mjs`, `${componentName}.css`];
+    // A per-component .ftl is scaffolded only when the component does NOT
+    // opt into a shared feature-scoped bundle. Mirrors writeComponentFiles.
+    if (localized && !sharedFtl)
+        componentFiles.push(`${componentName}.ftl`);
+    let plan = `Would create files in components/custom/${componentName}/:\n` +
+        componentFiles.map((f) => `  ${f}`).join('\n');
+    plan += formatTestSection({ testStyle, componentName, binaryName });
+    plan += `\n\nWould add custom entry to furnace.json:`;
+    plan += `\n  name: ${componentName}`;
+    plan += `\n  description: ${description || '(empty)'}`;
+    plan += `\n  register: ${register}`;
+    plan += `\n  localized: ${localized}`;
+    if (composes && composes.length > 0) {
+        plan += `\n  composes: ${composes.join(', ')}`;
+    }
+    if (sharedFtl) {
+        plan += `\n  sharedFtl: ${sharedFtl}`;
+    }
+    return plan;
+}
+//# sourceMappingURL=create-dry-run.js.map

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

@@ -0,0 +1,24 @@
+/**
+ * Feature-flag resolution for `furnace create`. Extracted from
+ * `create.ts` so the authoring command stays under the per-file LOC
+ * budget — the flag resolver has grown with each new opt-in (`--xpcshell`,
+ * `--test-style`, `--shared-ftl`).
+ */
+import type { FurnaceCreateOptions } from '../../types/commands/index.js';
+/**
+ * Resolves the localized and registration feature flags for a new component.
+ *
+ * `--shared-ftl` implies `localized` and short-circuits the interactive
+ * prompt so the operator is not asked to flip a flag we are about to
+ * enforce. `--no-localized` combined with `--shared-ftl` is rejected
+ * fast-fail; the cross-field check in furnace-config would catch it
+ * too, but later and without a clear command-line message.
+ *
+ * @param isInteractive - Whether interactive prompts are available
+ * @param options - CLI-provided feature flags
+ * @returns Final feature selections, or null when creation is cancelled
+ */
+export declare function resolveCreateFeatures(isInteractive: boolean, options: FurnaceCreateOptions): Promise<{
+    localized: boolean;
+    register: boolean;
+} | null>;

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

@@ -0,0 +1,56 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Feature-flag resolution for `furnace create`. Extracted from
+ * `create.ts` so the authoring command stays under the per-file LOC
+ * budget — the flag resolver has grown with each new opt-in (`--xpcshell`,
+ * `--test-style`, `--shared-ftl`).
+ */
+import { multiselect } from '@clack/prompts';
+import { InvalidArgumentError } from '../../errors/base.js';
+import { cancel, isCancel } from '../../utils/logger.js';
+/**
+ * Resolves the localized and registration feature flags for a new component.
+ *
+ * `--shared-ftl` implies `localized` and short-circuits the interactive
+ * prompt so the operator is not asked to flip a flag we are about to
+ * enforce. `--no-localized` combined with `--shared-ftl` is rejected
+ * fast-fail; the cross-field check in furnace-config would catch it
+ * too, but later and without a clear command-line message.
+ *
+ * @param isInteractive - Whether interactive prompts are available
+ * @param options - CLI-provided feature flags
+ * @returns Final feature selections, or null when creation is cancelled
+ */
+export async function resolveCreateFeatures(isInteractive, options) {
+    let localized = options.localized ?? false;
+    let register = options.register ?? true;
+    if (options.sharedFtl !== undefined) {
+        if (options.localized === false) {
+            throw new InvalidArgumentError('--shared-ftl requires localization. Remove --no-localized or drop --shared-ftl.', 'sharedFtl');
+        }
+        localized = true;
+    }
+    const featuresPromptSuppressed = options.sharedFtl !== undefined;
+    if (isInteractive &&
+        options.localized === undefined &&
+        options.register === undefined &&
+        !featuresPromptSuppressed) {
+        const features = await multiselect({
+            message: 'Component features:',
+            options: [
+                { value: 'localized', label: 'Fluent localization (data-l10n-id)' },
+                { value: 'register', label: 'Register in customElements.js' },
+            ],
+            initialValues: ['register'],
+        });
+        if (isCancel(features)) {
+            cancel('Create cancelled');
+            return null;
+        }
+        const selected = features;
+        localized = selected.includes('localized');
+        register = selected.includes('register');
+    }
+    return { localized, register };
+}
+//# sourceMappingURL=create-features.js.map

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

@@ -14,12 +14,16 @@
  * per-instance shadow-DOM Fluent attachment via `l10n.connectRoot`. We mirror
  * that pattern here so `--localized` produces functional code.
  *
- * The FTL path mirrors the locale jar.mn entry that `furnace apply` writes:
- * `<ftlChromeSubPath>/<name>.ftl`. For the default `toolkit/global` tree this
- * yields `toolkit/global/<name>.ftl`, which matches the URI upstream toolkit
- * widgets ship.
+ * Path resolution precedence (when `localized` is true):
+ *   1. `sharedFtl` — used verbatim. The caller has resolved it from
+ *      `--shared-ftl` / `furnace.json`; this template does no rewriting.
+ *      Use this when the component participates in a feature-scoped
+ *      bundle that another component owns.
+ *   2. `<ftlChromeSubPath>/<name>.ftl` — the default per-component path,
+ *      matching the locale jar.mn entry that `furnace apply` writes.
+ *   3. `<name>.ftl` — fallback when no chrome sub-path was resolvable.
  */
-export declare function generateMjsContent(name: string, className: string, description: string, localized: boolean, header: string, ftlChromeSubPath: string | undefined): string;
+export declare function generateMjsContent(name: string, className: string, description: string, localized: boolean, header: string, ftlChromeSubPath: string | undefined, sharedFtl: string | undefined): string;
 /** Generates the .css file content for a custom component. */
 export declare function generateCssContent(header: string): string;
 /** Generates the .ftl file content for a custom component. */

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

@@ -15,13 +15,21 @@
  * per-instance shadow-DOM Fluent attachment via `l10n.connectRoot`. We mirror
  * that pattern here so `--localized` produces functional code.
  *
- * The FTL path mirrors the locale jar.mn entry that `furnace apply` writes:
- * `<ftlChromeSubPath>/<name>.ftl`. For the default `toolkit/global` tree this
- * yields `toolkit/global/<name>.ftl`, which matches the URI upstream toolkit
- * widgets ship.
+ * Path resolution precedence (when `localized` is true):
+ *   1. `sharedFtl` — used verbatim. The caller has resolved it from
+ *      `--shared-ftl` / `furnace.json`; this template does no rewriting.
+ *      Use this when the component participates in a feature-scoped
+ *      bundle that another component owns.
+ *   2. `<ftlChromeSubPath>/<name>.ftl` — the default per-component path,
+ *      matching the locale jar.mn entry that `furnace apply` writes.
+ *   3. `<name>.ftl` — fallback when no chrome sub-path was resolvable.
  */
-export function generateMjsContent(name, className, description, localized, header, ftlChromeSubPath) {
-    const ftlPath = ftlChromeSubPath !== undefined ? `${ftlChromeSubPath}/${name}.ftl` : `${name}.ftl`;
+export function generateMjsContent(name, className, description, localized, header, ftlChromeSubPath, sharedFtl) {
+    const ftlPath = sharedFtl !== undefined
+        ? sharedFtl
+        : ftlChromeSubPath !== undefined
+            ? `${ftlChromeSubPath}/${name}.ftl`
+            : `${name}.ftl`;
     const ftlModulePreamble = localized
         ? `
 window.MozXULElement?.insertFTLIfNeeded("${ftlPath}");
@@ -103,6 +111,20 @@ export function generateXpcshellTestContent(name, 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.
+//
+//   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