@hominis/fireforge 0.36.0 → 0.37.0

package/dist/src/commands/test.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join, resolve } from 'node:path';
-import { readBuildBaseline } from '../core/build-baseline.js';
+import { readBuildBaseline, writeBuildBaseline } from '../core/build-baseline.js';
 import { prepareBuildEnvironment } from '../core/build-prepare.js';
 import { getProjectPaths, loadConfig } from '../core/config.js';
 import { assertEngineGenerationUnchanged, snapshotEngineGeneration, } from '../core/engine-session-lock.js';
@@ -10,12 +10,13 @@ import { formatMarionettePreflightLine, reportMarionettePreflight, runMarionette
 import { buildHarnessCrashMessage } from '../core/test-harness-crash.js';
 import { createPostRebuildFailureContext } from '../core/test-harness-output.js';
 import { analyzeTestPathScopes, formatScopeNotice, } from '../core/test-path-scope.js';
-import { checkStaleBuildForTest, formatStaleBuildWarning } from '../core/test-stale-check.js';
+import { checkStaleBuildForTest, findUncoveredRequestPaths, formatStaleBuildWarning, formatTestCoverageRefusal, } from '../core/test-stale-check.js';
 import { findNearestXpcshellManifest } from '../core/xpcshell-appdir.js';
 import { GeneralError } from '../errors/base.js';
 import { AmbiguousBuildArtifactsError, BuildError } from '../errors/build.js';
+import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
-import { info, intro, outro, spinner, success, warn } from '../utils/logger.js';
+import { info, intro, outro, spinner, success, verbose, warn } from '../utils/logger.js';
 import { stripEnginePrefix } from '../utils/paths.js';
 import { diagnoseShardOutcome, finalizeSingleRunOutcome } from './test-diagnose.js';
 import { assertPathlessTestMode, assertTestModeCombinations, canaryTimeoutSeconds, reportCanaryOutcome, resolveCanaryPath, } from './test-modes.js';
@@ -103,7 +104,7 @@ async function resolveLaunchablePathForTests(engineDir, binaryName, objDir) {
     }
     return bundleCheck.expectedPath;
 }
-async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries) {
+async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries, testPackagingCoverage) {
     await withBuildLock(projectRoot, async () => {
         // Pass the previous baseline exactly like `fireforge build` does, so
         // auto-configure runs under the same conditions on both paths. The
@@ -128,6 +129,19 @@ async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries
         });
         if (result.exitCode === 0) {
             s.stop('Build complete');
+            // Same record, same failure tolerance as `fireforge build` /
+            // `build --ui` (build.ts): a green pre-test build refreshes the
+            // stale-build baseline so a later plain `fireforge test` over the
+            // same files — in any invocation shape — is not refused. A failed
+            // write never fails the run. The coverage claim is scoped to the
+            // requested test paths, since a file-scoped `test --build` only
+            // guarantees packaging for those manifests.
+            try {
+                await writeBuildBaseline(projectRoot, paths.engine, projectConfig.binaryName, testPackagingCoverage);
+            }
+            catch (baselineError) {
+                verbose(`Could not persist build baseline: ${toError(baselineError).message}`);
+            }
             return;
         }
         s.error('Pre-test build failed');
@@ -136,6 +150,51 @@ async function runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries
             : 'Pre-test build failed', 'mach build faster');
     });
 }
+/**
+ * Stale-build preflight — when `--build` was NOT requested, detect
+ * packageable engine edits since the last successful build and fail
+ * UP-FRONT unless the operator explicitly accepts the stale package risk.
+ *
+ * Packaging COVERAGE is checked first, on EVERY non-`--build` run and
+ * regardless of staleness or `--allow-stale-build`: a runtime packaged by
+ * a file-scoped `test --build` can lack support fixtures for OTHER
+ * manifests even when nothing changed since — dispatching such a run
+ * hangs on missing fixtures rather than failing, so the flag (which only
+ * accepts stale CONTENT) must not be the trigger. Field incident: a
+ * three-file scoped rebuild left `file_tiles_audio.html` unpackaged and a
+ * later run over different files timed out twice at 45s waiting on
+ * `DOMAudioPlaybackStarted`.
+ *
+ * Exception: a path-less `test --doctor` stops at the Marionette health
+ * check (`runDoctorPreflight` returns 'stop' when no test paths were
+ * given) and never dispatches a test, so it needs no packaging coverage —
+ * treating it as a full-suite request would refuse a probe that touches
+ * no fixtures. The stale-content refusal still applies to it unchanged.
+ */
+async function enforceStaleBuildGate(projectRoot, engineDir, options, normalizedPaths) {
+    const stale = await checkStaleBuildForTest(projectRoot, engineDir);
+    const dispatchesNoTests = options.doctor === true && normalizedPaths.length === 0;
+    if (!dispatchesNoTests) {
+        const recordedCoverage = stale.baseline?.testPackagingCoverage;
+        const uncovered = findUncoveredRequestPaths(recordedCoverage, normalizedPaths);
+        if (uncovered.length > 0) {
+            throw new GeneralError(formatTestCoverageRefusal(uncovered, Array.isArray(recordedCoverage) ? recordedCoverage : []));
+        }
+    }
+    const staleMessage = stale.stale
+        ? `${formatStaleBuildWarning(stale)}\n\n` +
+            'Run `fireforge test --build` to refresh the packaged runtime first, or pass ' +
+            '`--allow-stale-build` if you intentionally rebuilt out-of-band and accept the risk.'
+        : undefined;
+    if (staleMessage !== undefined) {
+        if (options.allowStaleBuild === true) {
+            warn(staleMessage);
+        }
+        else {
+            throw new GeneralError(staleMessage);
+        }
+    }
+}
 function logTestSelection(scopes) {
     if (scopes.length > 0) {
         const labels = scopes.map((scope) => scope.isDirectory && scope.testFileCount > 0
@@ -297,28 +356,23 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
     // during spawn (exit code 1, signal none). stderr tail: (empty)`.
     const launchablePath = await resolveLaunchablePathForTests(paths.engine, projectConfig.binaryName, buildCheck.objDir);
     const harnessRetries = options.harnessRetries ?? DEFAULT_HARNESS_RETRIES;
+    // Normalized engine-relative request paths, hoisted above the build/stale
+    // gate: the pre-test build records them as the packaging-coverage claim,
+    // and the --allow-stale-build path checks the request against the
+    // recorded coverage. (Existence is still asserted later, after the gate —
+    // stale/coverage refusals keep precedence over missing-path errors.)
+    const requestedPaths = canaryPath !== undefined ? [canaryPath] : testPaths;
+    const normalizedPaths = requestedPaths.map((p) => stripEnginePrefix(p).trim());
     // Run incremental build if requested
     if (options.build) {
-        await runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries);
+        // A path-less `test --build` runs (and packages for) the full suite;
+        // a scoped invocation only vouches for the requested paths.
+        const coverage = normalizedPaths.length === 0 ? 'full' : normalizedPaths;
+        await runPreTestBuild(projectRoot, paths, projectConfig, harnessRetries, coverage);
         info('');
     }
     else {
-        // Stale-build preflight — when --build was NOT requested, detect
-        // packageable engine edits since the last successful `fireforge build`
-        // and fail UP-FRONT unless the operator explicitly accepts the stale
-        // package risk.
-        const stale = await checkStaleBuildForTest(projectRoot, paths.engine);
-        if (stale.stale) {
-            const message = `${formatStaleBuildWarning(stale)}\n\n` +
-                'Run `fireforge test --build` to refresh the packaged runtime first, or pass ' +
-                '`--allow-stale-build` if you intentionally rebuilt out-of-band and accept the risk.';
-            if (options.allowStaleBuild === true) {
-                warn(message);
-            }
-            else {
-                throw new GeneralError(message);
-            }
-        }
+        await enforceStaleBuildGate(projectRoot, paths.engine, options, normalizedPaths);
     }
     // Resolve the effective Marionette port. Operator precedence:
     //   1. `--marionette-port` (first-class option, parsed at the CLI layer)
@@ -355,8 +409,6 @@ export async function testCommand(projectRoot, testPaths, options = {}) {
         if (doctorOutcome === 'stop')
             return;
     }
-    const requestedPaths = canaryPath !== undefined ? [canaryPath] : testPaths;
-    const normalizedPaths = requestedPaths.map((p) => stripEnginePrefix(p).trim());
     await assertTestPathsExist(paths.engine, normalizedPaths);
     const classification = await classifyTestHarnesses(paths.engine, normalizedPaths);
     if (classification.xpcshell.length > 0 && classification.nonXpcshell.length > 0) {

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

@@ -35,4 +35,28 @@ export interface BuildBaseline {
      * was recorded.
      */
     packageableFingerprints?: Record<string, string>;
+    /**
+     * What the packaged test runtime produced by the recorded build covers.
+     *
+     * - `'full'`: the build packaged the full test set — written by
+     *   `fireforge build` / `build --ui` and by a path-less
+     *   `fireforge test --build` (full-suite run).
+     * - `string[]`: engine-relative POSIX request paths of the file/directory-
+     *   scoped `fireforge test --build` invocation that produced the runtime.
+     *   A directory entry covers everything beneath it. Support fixtures for
+     *   manifests outside this list may be missing from `obj-*`/`_tests/`, so
+     *   an `--allow-stale-build` run over uncovered paths is refused rather
+     *   than dispatched into a hang.
+     *
+     * Missing on baselines written before 0.37.0 — only `fireforge build`
+     * wrote baselines then, so "full" is the honest historical value and the
+     * stale-check treats an absent field as full coverage.
+     *
+     * The record is project-scoped, which is also per-obj-dir: multi-objdir
+     * checkouts are refused up-front (`AmbiguousBuildArtifactsError`), so at
+     * most one obj dir exists per project.
+     */
+    testPackagingCoverage?: TestPackagingCoverage;
 }
+/** Coverage claim of the packaged test runtime. See {@link BuildBaseline.testPackagingCoverage}. */
+export type TestPackagingCoverage = 'full' | string[];

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

@@ -15,7 +15,7 @@
  * on successful build completion; a failed build does not update it, so a
  * subsequent run still audits against the last known-good tree.
  */
-import type { BuildBaseline } from './build-baseline-types.js';
+import type { BuildBaseline, TestPackagingCoverage } from './build-baseline-types.js';
 /** Name of the last-build marker file under `.fireforge/`. */
 export declare const BUILD_BASELINE_FILENAME = "last-build.json";
 /**
@@ -39,5 +39,8 @@ export declare function readBuildBaseline(projectRoot: string): Promise<BuildBas
  * @param projectRoot - Root directory of the project
  * @param engineDir - Path to the engine directory
  * @param binaryName - Current `binaryName` from fireforge.json
+ * @param testPackagingCoverage - Coverage claim of the packaged test
+ *   runtime this build produced (`'full'`, or the scoped request paths of
+ *   a `test --build` invocation). Omitted → field left off the marker.
  */
-export declare function writeBuildBaseline(projectRoot: string, engineDir: string, binaryName: string): Promise<void>;
+export declare function writeBuildBaseline(projectRoot: string, engineDir: string, binaryName: string, testPackagingCoverage?: TestPackagingCoverage): Promise<void>;

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

@@ -65,8 +65,11 @@ export async function readBuildBaseline(projectRoot) {
  * @param projectRoot - Root directory of the project
  * @param engineDir - Path to the engine directory
  * @param binaryName - Current `binaryName` from fireforge.json
+ * @param testPackagingCoverage - Coverage claim of the packaged test
+ *   runtime this build produced (`'full'`, or the scoped request paths of
+ *   a `test --build` invocation). Omitted → field left off the marker.
  */
-export async function writeBuildBaseline(projectRoot, engineDir, binaryName) {
+export async function writeBuildBaseline(projectRoot, engineDir, binaryName, testPackagingCoverage) {
     let engineHeadSha = '';
     try {
         engineHeadSha = await getHead(engineDir);
@@ -86,6 +89,7 @@ export async function writeBuildBaseline(projectRoot, engineDir, binaryName) {
         builtAt: new Date().toISOString(),
         binaryName,
         ...(packageableFingerprints !== undefined ? { packageableFingerprints } : {}),
+        ...(testPackagingCoverage !== undefined ? { testPackagingCoverage } : {}),
     };
     await writeJson(getBuildBaselinePath(projectRoot), baseline);
 }

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

@@ -35,6 +35,13 @@ export function parseCustomConfig(data, name) {
     if (!isBoolean(data['localized'])) {
         throw new FurnaceError(`Furnace config: custom "${name}.localized" must be a boolean`);
     }
+    if (data['kind'] !== undefined && data['kind'] !== 'element' && data['kind'] !== 'library') {
+        throw new FurnaceError(`Furnace config: custom "${name}.kind" must be "element" or "library" when set`);
+    }
+    if (data['kind'] === 'library' && data['register']) {
+        throw new FurnaceError(`Furnace config: custom "${name}" has kind "library" but register: true — ` +
+            'a library exports no custom element; set register: false');
+    }
     if (data['composes'] !== undefined) {
         parseStringArray(data['composes'], `${name}.composes`);
     }
@@ -58,6 +65,9 @@ export function parseCustomConfig(data, name) {
             ? { composes: parseStringArray(data['composes'], `${name}.composes`) }
             : {}),
         ...(data['keyboardCovered'] === true ? { keyboardCovered: true } : {}),
+        // Explicit `kind: "element"` is the default; normalize it away so the
+        // stored config carries the field only when it changes behavior.
+        ...(data['kind'] === 'library' ? { kind: 'library' } : {}),
         ...(sharedFtl !== undefined ? { sharedFtl } : {}),
     };
 }

package/dist/src/core/furnace-stale-export.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Stale-furnace-source gate for `fireforge patch export` / `re-export`.
+ *
+ * Exports capture the DEPLOYED engine copies of furnace-managed files, not
+ * the `components/` sources. Editing a component source and re-exporting
+ * its owning patch WITHOUT an intervening `furnace deploy`/`apply` silently
+ * exports the stale deployed copy — per-patch lint then flags the old line
+ * count and the patch body lags the source. This gate detects that
+ * sequence by comparing component source directories against the checksums
+ * recorded at the last apply (`FurnaceState.appliedChecksums`) — the same
+ * signal `warnIfFurnaceStale` uses for run/watch — and refuses the export
+ * unless the operator passes `--allow-stale-furnace`.
+ *
+ * Checksum-based on purpose: git checkouts and `furnace refresh` churn
+ * mtimes without content changes, so an mtime comparison would misfire.
+ *
+ * Probe failures (broken furnace config, missing state) degrade to a
+ * verbose log and an empty result — a broken furnace setup must never
+ * block non-furnace patch work.
+ */
+/** One furnace component whose source drifted from its deployed copy. */
+export interface StaleFurnaceComponent {
+    /** Component name (furnace.json key). */
+    name: string;
+    /** Component flavor — resolves the source directory root. */
+    type: 'custom' | 'override';
+    /** Engine-relative deployed prefix (`/`-terminated) the component owns. */
+    prefix: string;
+}
+/**
+ * Returns the furnace components whose deployed engine copies the given
+ * files fall under AND whose `components/` sources have changed since the
+ * last apply. Empty when furnace is not configured, never applied, or the
+ * probe fails.
+ *
+ * Files are attributed per component: the custom `targetPath` / override
+ * `basePath` prefixes, plus — for a localized non-sharedFtl custom
+ * component — its exact deployed `<ftlDir>/<name>.ftl` file (the shared
+ * FTL dir as a whole stays unclaimed; sibling files there belong to other
+ * components). `sharedFtl` bundles are NOT furnace-deployed (apply only
+ * prunes a dangling per-widget jar.mn line), so they have no deployed copy
+ * to go stale and get no candidate by design. The storybook stories prefix
+ * is likewise skipped.
+ *
+ * @param projectRoot - Project root directory
+ * @param files - Engine-relative paths the export will capture
+ */
+export declare function findStaleFurnaceComponentsForFiles(projectRoot: string, files: readonly string[]): Promise<StaleFurnaceComponent[]>;
+/**
+ * Gate helper for export/re-export: refuses (or, with `allow`, warns) when
+ * any exported file belongs to a furnace component whose source changed
+ * since the last apply — the export would capture the stale deployed copy.
+ *
+ * @param projectRoot - Project root directory
+ * @param files - Engine-relative paths the export will capture
+ * @param allow - True when the operator passed `--allow-stale-furnace`
+ * @param command - Which command runs the gate (message wording only)
+ */
+export declare function enforceFreshFurnaceSources(projectRoot: string, files: readonly string[], allow: boolean, command: 'export' | 're-export'): Promise<void>;

package/dist/src/core/furnace-stale-export.js

@@ -0,0 +1,123 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Stale-furnace-source gate for `fireforge patch export` / `re-export`.
+ *
+ * Exports capture the DEPLOYED engine copies of furnace-managed files, not
+ * the `components/` sources. Editing a component source and re-exporting
+ * its owning patch WITHOUT an intervening `furnace deploy`/`apply` silently
+ * exports the stale deployed copy — per-patch lint then flags the old line
+ * count and the patch body lags the source. This gate detects that
+ * sequence by comparing component source directories against the checksums
+ * recorded at the last apply (`FurnaceState.appliedChecksums`) — the same
+ * signal `warnIfFurnaceStale` uses for run/watch — and refuses the export
+ * unless the operator passes `--allow-stale-furnace`.
+ *
+ * Checksum-based on purpose: git checkouts and `furnace refresh` churn
+ * mtimes without content changes, so an mtime comparison would misfire.
+ *
+ * Probe failures (broken furnace config, missing state) degrade to a
+ * verbose log and an empty result — a broken furnace setup must never
+ * block non-furnace patch work.
+ */
+import { GeneralError } from '../errors/base.js';
+import { pathExists } from '../utils/fs.js';
+import { verbose, warn } from '../utils/logger.js';
+import { extractComponentChecksums, hasComponentChanged } from './furnace-apply-helpers.js';
+import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceState, } from './furnace-config.js';
+import { resolveFtlDir } from './furnace-constants.js';
+/**
+ * Returns the furnace components whose deployed engine copies the given
+ * files fall under AND whose `components/` sources have changed since the
+ * last apply. Empty when furnace is not configured, never applied, or the
+ * probe fails.
+ *
+ * Files are attributed per component: the custom `targetPath` / override
+ * `basePath` prefixes, plus — for a localized non-sharedFtl custom
+ * component — its exact deployed `<ftlDir>/<name>.ftl` file (the shared
+ * FTL dir as a whole stays unclaimed; sibling files there belong to other
+ * components). `sharedFtl` bundles are NOT furnace-deployed (apply only
+ * prunes a dangling per-widget jar.mn line), so they have no deployed copy
+ * to go stale and get no candidate by design. The storybook stories prefix
+ * is likewise skipped.
+ *
+ * @param projectRoot - Project root directory
+ * @param files - Engine-relative paths the export will capture
+ */
+export async function findStaleFurnaceComponentsForFiles(projectRoot, files) {
+    try {
+        if (files.length === 0)
+            return [];
+        if (!(await furnaceConfigExists(projectRoot)))
+            return [];
+        const config = await loadFurnaceConfig(projectRoot);
+        const state = await loadFurnaceState(projectRoot);
+        if (!state.appliedChecksums)
+            return [];
+        const furnacePaths = getFurnacePaths(projectRoot);
+        const ftlDir = resolveFtlDir(config.ftlBasePath);
+        const ftlPrefix = ftlDir.endsWith('/') ? ftlDir : `${ftlDir}/`;
+        const candidates = [
+            ...Object.entries(config.overrides).map(([name, cfg]) => ({
+                name,
+                type: 'override',
+                prefix: cfg.basePath.endsWith('/') ? cfg.basePath : `${cfg.basePath}/`,
+                exactFiles: [],
+            })),
+            ...Object.entries(config.custom).map(([name, cfg]) => ({
+                name,
+                type: 'custom',
+                prefix: cfg.targetPath.endsWith('/') ? cfg.targetPath : `${cfg.targetPath}/`,
+                // A localized non-sharedFtl component also owns exactly one
+                // deployed file in the shared FTL dir (applyCustomFtlFile copies
+                // `<name>.ftl` there). sharedFtl bundles are not furnace-deployed.
+                exactFiles: cfg.localized && cfg.sharedFtl === undefined ? [`${ftlPrefix}${name}.ftl`] : [],
+            })),
+        ];
+        const stale = [];
+        for (const candidate of candidates) {
+            if (!files.some((file) => file.startsWith(candidate.prefix) || candidate.exactFiles.includes(file)))
+                continue;
+            const sourceRoot = candidate.type === 'override' ? furnacePaths.overridesDir : furnacePaths.customDir;
+            const sourceDir = `${sourceRoot}/${candidate.name}`;
+            if (!(await pathExists(sourceDir)))
+                continue;
+            const previous = extractComponentChecksums(state.appliedChecksums, candidate.type, candidate.name);
+            if (await hasComponentChanged(sourceDir, previous)) {
+                stale.push({ name: candidate.name, type: candidate.type, prefix: candidate.prefix });
+            }
+        }
+        return stale;
+    }
+    catch (error) {
+        verbose(`Stale-furnace export gate skipped due to an error: ${error instanceof Error ? error.message : String(error)}`);
+        return [];
+    }
+}
+/**
+ * Gate helper for export/re-export: refuses (or, with `allow`, warns) when
+ * any exported file belongs to a furnace component whose source changed
+ * since the last apply — the export would capture the stale deployed copy.
+ *
+ * @param projectRoot - Project root directory
+ * @param files - Engine-relative paths the export will capture
+ * @param allow - True when the operator passed `--allow-stale-furnace`
+ * @param command - Which command runs the gate (message wording only)
+ */
+export async function enforceFreshFurnaceSources(projectRoot, files, allow, command) {
+    const stale = await findStaleFurnaceComponentsForFiles(projectRoot, files);
+    if (stale.length === 0)
+        return;
+    const list = stale
+        .map((component) => `${component.name} (components/${component.type === 'custom' ? 'custom' : 'overrides'}/${component.name}/ → ${component.prefix})`)
+        .join(', ');
+    const message = `Component source${stale.length === 1 ? '' : 's'} changed since the last furnace apply: ${list}. ` +
+        `The deployed engine cop${stale.length === 1 ? 'y is' : 'ies are'} stale, so this ${command} would ` +
+        'capture the OLD component content into the patch. Run "fireforge furnace deploy" (or ' +
+        '"fireforge furnace apply") first so the export captures the current source, or pass ' +
+        '--allow-stale-furnace to export the deployed copy anyway.';
+    if (allow) {
+        warn(message);
+        return;
+    }
+    throw new GeneralError(message);
+}

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

@@ -3,7 +3,7 @@ import { join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
 import { hasRawCssColors } from '../utils/regex.js';
 import { classExtendsMozLitElement, collectCssVariableDeclarations, collectCssVariableReferences, createIssue, getTokenPrefixContext, hasCustomElementDefineCall, hasRelativeModuleImport, stripCssBlockComments, } from './furnace-validate-helpers.js';
-async function validateMjsCompatibility(mjsPath, tagName) {
+async function validateMjsCompatibility(mjsPath, tagName, isLibrary) {
     if (!(await pathExists(mjsPath)))
         return [];
     const mjsContent = await readText(mjsPath);
@@ -11,6 +11,12 @@ async function validateMjsCompatibility(mjsPath, tagName) {
     if (hasRelativeModuleImport(mjsContent)) {
         issues.push(createIssue(tagName, 'error', 'relative-import', 'Imports must use chrome:// URIs, not relative paths.'));
     }
+    // A library component (kind: "library") deliberately defines no element:
+    // it exports a base class + helpers for other components to extend, so
+    // the define/extends requirements do not apply.
+    if (isLibrary) {
+        return issues;
+    }
     if (!hasCustomElementDefineCall(mjsContent)) {
         issues.push(createIssue(tagName, 'error', 'no-custom-element-define', 'Missing customElements.define() call. Component will not be registered.'));
     }
@@ -124,7 +130,8 @@ export async function validateCompatibility(componentDir, tagName, type, config,
     const issues = [];
     const mjsPath = join(componentDir, `${tagName}.mjs`);
     const cssPath = join(componentDir, `${tagName}.css`);
-    const mjsIssues = await validateMjsCompatibility(mjsPath, tagName);
+    const isLibrary = type === 'custom' && config?.custom[tagName]?.kind === 'library';
+    const mjsIssues = await validateMjsCompatibility(mjsPath, tagName, isLibrary);
     issues.push(...mjsIssues);
     const cssIssues = await validateCssCompatibility(cssPath, tagName, type, config, root);
     issues.push(...cssIssues);

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

@@ -37,8 +37,9 @@ export async function validateStructure(componentDir, tagName, type, customConfi
             message: `Required file ${tagName}.mjs not found.`,
         });
     }
-    // .css should exist
-    if (!(await pathExists(cssPath))) {
+    // .css should exist — except for library components (base class + helpers,
+    // no element of their own), which render nothing and need no stylesheet.
+    if (!(await pathExists(cssPath)) && customConfig?.kind !== 'library') {
         issues.push({
             component: tagName,
             severity: 'warning',

package/dist/src/core/mach-known-noise-filter.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Terminal-echo filter for the KNOWN upstream mozsystemmonitor teardown
+ * traceback (0.37.0 item 8).
+ *
+ * Every headless test run against the 153-beta engine ends with an
+ * `AttributeError: 'SystemResourceMonitor' object has no attribute
+ * 'stop_time'` traceback at harness teardown — upstream noise that sits
+ * exactly where a reader looks for the failure summary. 0.36.0 already made
+ * real failure lines beat this traceback in CLASSIFICATION; this filter
+ * closes the PRESENTATION gap by collapsing the echoed traceback to one
+ * labeled line.
+ *
+ * Scope is deliberately narrow:
+ *   - Only the terminal ECHO is filtered. The captured stdout/stderr strings
+ *     stay raw — the classifier (`test-harness-crash.ts`) depends on the
+ *     raw traceback for its green-summary override and secondary-noise
+ *     detection.
+ *   - Only the exact documented incident is collapsed, and every condition
+ *     must hold: an `AttributeError` on `SystemResourceMonitor` naming one
+ *     of the two known attributes (`stop_time`, `poll_interval` — the
+ *     0.34.0 guard family), AND a `mozsystemmonitor/resourcemonitor.py`
+ *     stack frame, AND a previously-seen SUITE_END shutdown marker (shared
+ *     across the run's stdout/stderr filter instances — the marker usually
+ *     lands on stdout while the traceback lands on stderr). A novel
+ *     attribute, a novel exception type in resourcemonitor.py, or a
+ *     pre-shutdown occurrence is echoed verbatim, always.
+ *   - The hold buffer is bounded; on overflow the block is flushed verbatim
+ *     and the filter returns to pass-through, so output is never lost.
+ */
+/**
+ * Shared across the stdout and stderr filter instances of ONE mach run:
+ * SUITE_END typically arrives on stdout while the teardown traceback lands
+ * on stderr, so the shutdown-seen flag must be visible to both. The two
+ * pipes are independent, so a traceback can theoretically beat the marker
+ * through — the block then prints verbatim, the correct failure direction.
+ */
+export interface TeardownNoiseContext {
+    shutdownSeen: boolean;
+}
+/** Fresh per-run context — hand the same instance to both stream filters. */
+export declare function createTeardownNoiseContext(): TeardownNoiseContext;
+/** One line replaces the whole recognized traceback block in the echo. */
+export declare const KNOWN_TEARDOWN_NOISE_ANNOTATION: string;
+/** Chunk-safe, line-buffered echo filter. See module doc. */
+export interface KnownTeardownNoiseFilter {
+    /** Feed a raw chunk; returns the text to echo now (possibly empty). */
+    transform(chunk: string): string;
+    /** Flush any buffered residue verbatim (call after the stream closes). */
+    flush(): string;
+}
+/**
+ * Creates a stateful filter for one output stream. Complete lines outside a
+ * traceback pass straight through (only the trailing partial line is held
+ * back); a `Traceback (most recent call last)` header switches to hold mode
+ * until the block ends, then either the one-line annotation (recognized
+ * signature after a seen shutdown marker) or the verbatim block (anything
+ * else) is emitted. Pass the run's shared {@link TeardownNoiseContext} so
+ * both stream filters see the same shutdown flag.
+ */
+export declare function createKnownTeardownNoiseFilter(context?: TeardownNoiseContext): KnownTeardownNoiseFilter;