@hominis/fireforge 0.30.1 → 0.32.0

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

@@ -1,16 +1,8 @@
 import type { FurnaceConfig, FurnaceState } from '../types/furnace.js';
 import { detectComposesCycles } from './furnace-graph-utils.js';
 export { detectComposesCycles };
-/** Name of the furnace configuration file */
-export declare const FURNACE_CONFIG_FILENAME = "furnace.json";
-/** Name of the furnace state file */
-export declare const FURNACE_STATE_FILENAME = "furnace-state.json";
-/** Name of the components directory */
-export declare const COMPONENTS_DIR = "components";
-/** Name of the overrides subdirectory */
-export declare const OVERRIDES_DIR = "overrides";
-/** Name of the custom subdirectory */
-export declare const CUSTOM_DIR = "custom";
+/** Directory name for shared CSS fragments within components/ */
+export declare const SHARED_FRAGMENTS_DIR = "shared";
 /**
  * Paths for furnace-related files and directories.
  */
@@ -23,6 +15,8 @@ interface FurnacePaths {
     overridesDir: string;
     /** Path to components/custom directory */
     customDir: string;
+    /** Path to components/shared directory (CSS fragments) */
+    sharedDir: string;
     /** Path to .fireforge/furnace-state.json */
     furnaceState: string;
 }
@@ -38,22 +32,6 @@ export declare function getFurnacePaths(root: string): FurnacePaths;
  * @returns True if furnace.json exists
  */
 export declare function furnaceConfigExists(root: string): Promise<boolean>;
-/**
- * Migrates a furnace config from an older schema version to the current one.
- * Returns the data unchanged if it is already at the current version.
- *
- * When a future version 2 is introduced, add a `case 1:` that transforms
- * v1 data into v2 shape and falls through to validation. The pattern is:
- *
- * ```
- * case 1:
- *   data = migrateV1ToV2(data);
- *   // fallthrough
- * case 2:
- *   break;
- * ```
- */
-export declare function migrateFurnaceConfig(data: Record<string, unknown>): Record<string, unknown>;
 /**
  * Validates a raw config object and returns a typed FurnaceConfig.
  * @param data - Raw data to validate
@@ -61,12 +39,6 @@ export declare function migrateFurnaceConfig(data: Record<string, unknown>): Rec
  * @throws Error if validation fails
  */
 export declare function validateFurnaceConfig(data: unknown): FurnaceConfig;
-/**
- * Validates a parsed furnace state object and returns a typed FurnaceState.
- * @param data - Parsed JSON state data
- * @returns Validated FurnaceState
- */
-export declare function validateFurnaceState(data: unknown): FurnaceState;
 /**
  * Loads and validates the furnace.json configuration.
  * @param root - Root directory of the project

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

@@ -10,20 +10,23 @@ import { parseStringArray } from './furnace-config-array-utils.js';
 import { parseCustomConfig } from './furnace-config-custom.js';
 import { orderFurnaceConfigForWrite } from './furnace-config-order.js';
 import { validateRuntimeVariables, validateTokenHostDocuments } from './furnace-config-tokens.js';
+import { applyOptionalFurnaceFields, parseNamedComponentMap, parseOverrideConfig, parseStockList, } from './furnace-config-validate.js';
 import { resolveFtlDir } from './furnace-constants.js';
 import { detectComposesCycles, validateComposesReferences } from './furnace-graph-utils.js';
 import { quarantineStateFile, withStateFileLock } from './state-file.js';
 export { detectComposesCycles };
 /** Name of the furnace configuration file */
-export const FURNACE_CONFIG_FILENAME = 'furnace.json';
+const FURNACE_CONFIG_FILENAME = 'furnace.json';
 /** Name of the furnace state file */
-export const FURNACE_STATE_FILENAME = 'furnace-state.json';
+const FURNACE_STATE_FILENAME = 'furnace-state.json';
 /** Name of the components directory */
-export const COMPONENTS_DIR = 'components';
+const COMPONENTS_DIR = 'components';
 /** Name of the overrides subdirectory */
-export const OVERRIDES_DIR = 'overrides';
+const OVERRIDES_DIR = 'overrides';
 /** Name of the custom subdirectory */
-export const CUSTOM_DIR = 'custom';
+const CUSTOM_DIR = 'custom';
+/** Directory name for shared CSS fragments within components/ */
+export const SHARED_FRAGMENTS_DIR = 'shared';
 /**
  * Gets all furnace-related paths based on a root directory.
  * @param root - Root directory of the project
@@ -36,6 +39,7 @@ export function getFurnacePaths(root) {
         componentsDir,
         overridesDir: join(componentsDir, OVERRIDES_DIR),
         customDir: join(componentsDir, CUSTOM_DIR),
+        sharedDir: join(componentsDir, SHARED_FRAGMENTS_DIR),
         furnaceState: join(root, FIREFORGE_DIR, FURNACE_STATE_FILENAME),
     };
 }
@@ -48,36 +52,6 @@ export async function furnaceConfigExists(root) {
     const paths = getFurnacePaths(root);
     return pathExists(paths.furnaceConfig);
 }
-/**
- * Validates an override component config object.
- * @param data - Raw data to validate
- * @param name - Component name for error messages
- */
-function parseOverrideConfig(data, name) {
-    const validTypes = ['css-only', 'full'];
-    if (!isString(data['type']) || !validTypes.includes(data['type'])) {
-        throw new FurnaceError(`Furnace config: override "${name}.type" must be one of: ${validTypes.join(', ')}`);
-    }
-    if (!isString(data['description'])) {
-        throw new FurnaceError(`Furnace config: override "${name}.description" must be a string`);
-    }
-    if (!isString(data['basePath'])) {
-        throw new FurnaceError(`Furnace config: override "${name}.basePath" must be a string`);
-    }
-    if (data['basePath'].includes('..')) {
-        throw new FurnaceError(`Furnace config: override "${name}.basePath" must not contain ".." (path traversal)`);
-    }
-    if (!isString(data['baseVersion'])) {
-        throw new FurnaceError(`Furnace config: override "${name}.baseVersion" must be a string`);
-    }
-    return {
-        type: data['type'] === 'css-only' ? 'css-only' : 'full',
-        description: data['description'],
-        basePath: data['basePath'],
-        baseVersion: data['baseVersion'],
-        ...(isString(data['baseCommit']) ? { baseCommit: data['baseCommit'] } : {}),
-    };
-}
 /** The current (and only) config schema version. */
 const CURRENT_CONFIG_VERSION = 1;
 /**
@@ -95,7 +69,7 @@ const CURRENT_CONFIG_VERSION = 1;
  *   break;
  * ```
  */
-export function migrateFurnaceConfig(data) {
+function migrateFurnaceConfig(data) {
     const version = data['version'];
     if (typeof version !== 'number' || !Number.isInteger(version) || version < 1) {
         throw new FurnaceError(`Furnace config: "version" must be a positive integer (got ${JSON.stringify(version)}). ` +
@@ -141,45 +115,9 @@ export function validateFurnaceConfig(data) {
     // Validate optional tokenHostDocuments — list of chrome XHTMLs that the
     // `missing-token-link` validator scans for the tokens CSS link.
     validateTokenHostDocuments(migrated['tokenHostDocuments']);
-    const stock = parseStringArray(migrated['stock'], 'stock');
-    const stockSet = new Set();
-    for (const name of stock) {
-        if (!/^[a-z][a-z0-9-]*$/.test(name)) {
-            throw new FurnaceError(`Furnace config: stock entry "${name}" must match /^[a-z][a-z0-9-]*$/ (lowercase, no path separators)`);
-        }
-        if (stockSet.has(name)) {
-            throw new FurnaceError(`Furnace config: duplicate stock entry "${name}"`);
-        }
-        stockSet.add(name);
-    }
-    // Validate overrides
-    if (!isObject(migrated['overrides'])) {
-        throw new FurnaceError('Furnace config: "overrides" must be an object');
-    }
-    const overrides = {};
-    for (const [name, value] of Object.entries(migrated['overrides'])) {
-        if (!/^[a-z][a-z0-9-]*$/.test(name)) {
-            throw new FurnaceError(`Furnace config: override name "${name}" must match /^[a-z][a-z0-9-]*$/ (lowercase, no path separators)`);
-        }
-        if (!isObject(value)) {
-            throw new FurnaceError(`Furnace config: override "${name}" must be an object`);
-        }
-        overrides[name] = parseOverrideConfig(value, name);
-    }
-    // Validate custom
-    if (!isObject(migrated['custom'])) {
-        throw new FurnaceError('Furnace config: "custom" must be an object');
-    }
-    const custom = {};
-    for (const [name, value] of Object.entries(migrated['custom'])) {
-        if (!/^[a-z][a-z0-9-]*$/.test(name)) {
-            throw new FurnaceError(`Furnace config: custom name "${name}" must match /^[a-z][a-z0-9-]*$/ (lowercase, no path separators)`);
-        }
-        if (!isObject(value)) {
-            throw new FurnaceError(`Furnace config: custom "${name}" must be an object`);
-        }
-        custom[name] = parseCustomConfig(value, name);
-    }
+    const stock = parseStockList(migrated['stock']);
+    const overrides = parseNamedComponentMap(migrated['overrides'], 'override', 'overrides', parseOverrideConfig);
+    const custom = parseNamedComponentMap(migrated['custom'], 'custom', 'custom', parseCustomConfig);
     // Detect circular composes references among custom components.
     detectComposesCycles(custom);
     // Validate that every composes reference points to a known component.
@@ -191,41 +129,7 @@ export function validateFurnaceConfig(data) {
         overrides,
         custom,
     };
-    if (migrated['tokenPrefix'] !== undefined)
-        config.tokenPrefix = migrated['tokenPrefix'];
-    if (migrated['tokenAllowlist'] !== undefined) {
-        config.tokenAllowlist = parseStringArray(migrated['tokenAllowlist'], 'tokenAllowlist');
-    }
-    if (migrated['platformPrefixes'] !== undefined) {
-        config.platformPrefixes = parseStringArray(migrated['platformPrefixes'], 'platformPrefixes');
-    }
-    if (migrated['runtimeVariables'] !== undefined) {
-        config.runtimeVariables = parseStringArray(migrated['runtimeVariables'], 'runtimeVariables');
-    }
-    if (migrated['tokenHostDocuments'] !== undefined) {
-        const docs = parseStringArray(migrated['tokenHostDocuments'], 'tokenHostDocuments');
-        config.tokenHostDocuments = docs;
-    }
-    // Validate optional ftlBasePath
-    if (migrated['ftlBasePath'] !== undefined) {
-        if (!isString(migrated['ftlBasePath'])) {
-            throw new FurnaceError('Furnace config: "ftlBasePath" must be a string if provided');
-        }
-        if (migrated['ftlBasePath'].includes('..')) {
-            throw new FurnaceError('Furnace config: "ftlBasePath" must not contain ".." (path traversal)');
-        }
-        config.ftlBasePath = migrated['ftlBasePath'];
-    }
-    // Validate optional scanPaths
-    if (migrated['scanPaths'] !== undefined) {
-        const paths = parseStringArray(migrated['scanPaths'], 'scanPaths');
-        for (const p of paths) {
-            if (p.includes('..')) {
-                throw new FurnaceError('Furnace config: "scanPaths" entries must not contain ".." (path traversal)');
-            }
-        }
-        config.scanPaths = paths;
-    }
+    applyOptionalFurnaceFields(migrated, config);
     return config;
 }
 /**
@@ -233,7 +137,7 @@ export function validateFurnaceConfig(data) {
  * @param data - Parsed JSON state data
  * @returns Validated FurnaceState
  */
-export function validateFurnaceState(data) {
+function validateFurnaceState(data) {
     const result = sanitizeFurnaceState(data);
     if (result.issues.length > 0) {
         throw new FurnaceError(`Invalid furnace state: ${result.issues.join('; ')}`);

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

@@ -4,22 +4,12 @@ export declare const CUSTOM_ELEMENTS_JS = "toolkit/content/customElements.js";
 export declare const JAR_MN = "toolkit/content/jar.mn";
 /** Default Fluent localization directory for toolkit global components, relative to engine root */
 export declare const FTL_DIR = "toolkit/locales/en-US/toolkit/global";
-/**
- * Suffix for the per-binary xpcshell scaffold parent directory. Components
- * created with `furnace create --with-tests --xpcshell` land at
- * `browser/base/content/test/<binaryName>${XPCSHELL_TEST_DIR_SUFFIX}/<component>/`.
- * Centralised so `create` / `remove` / `rename` / `validate` all agree on
- * the path template (2026-04-24 eval Finding 5).
- */
-export declare const XPCSHELL_TEST_DIR_SUFFIX = "-xpcshell";
 /**
  * Returns the engine-relative directory that holds xpcshell scaffolds for
  * a given binary. Matches the form `create-xpcshell.ts` writes and the
  * path `remove.ts` / `rename.ts` / `validate.ts` must clean up.
  */
 export declare function xpcshellTestParentDir(binaryName: string): string;
-/** File extensions that constitute a Furnace component's source files. */
-export declare const COMPONENT_FILE_EXTENSIONS: readonly [".mjs", ".css", ".ftl"];
 /** Returns true when `fileName` has one of the standard component file extensions. */
 export declare function isComponentSourceFile(fileName: string): boolean;
 /**

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

@@ -12,7 +12,7 @@ export const FTL_DIR = 'toolkit/locales/en-US/toolkit/global';
  * Centralised so `create` / `remove` / `rename` / `validate` all agree on
  * the path template (2026-04-24 eval Finding 5).
  */
-export const XPCSHELL_TEST_DIR_SUFFIX = '-xpcshell';
+const XPCSHELL_TEST_DIR_SUFFIX = '-xpcshell';
 /**
  * Returns the engine-relative directory that holds xpcshell scaffolds for
  * a given binary. Matches the form `create-xpcshell.ts` writes and the
@@ -22,7 +22,7 @@ export function xpcshellTestParentDir(binaryName) {
     return `browser/base/content/test/${binaryName}${XPCSHELL_TEST_DIR_SUFFIX}`;
 }
 /** File extensions that constitute a Furnace component's source files. */
-export const COMPONENT_FILE_EXTENSIONS = ['.mjs', '.css', '.ftl'];
+const COMPONENT_FILE_EXTENSIONS = ['.mjs', '.css', '.ftl'];
 /** Returns true when `fileName` has one of the standard component file extensions. */
 export function isComponentSourceFile(fileName) {
     return COMPONENT_FILE_EXTENSIONS.some((ext) => fileName.endsWith(ext));

package/dist/src/core/furnace-css-fragments.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared CSS fragments for Furnace widgets (field report D2).
+ *
+ * Shadow-DOM isolation forces each widget stylesheet to carry its own copy
+ * of genuinely shared CSS (keyframes, resets). Hand-syncing those copies
+ * drifts. Instead, a workspace stylesheet declares an include directive
+ * (a CSS block comment on its own line):
+ *
+ *     @fireforge-include shared-anims.css
+ *
+ * naming a fragment file in `components/shared/`. `furnace deploy` expands
+ * the fragment into the *deployed* copy only — the workspace source stays
+ * DRY — fencing the expansion between the directive line and a matching
+ * `@fireforge-end-include` marker so re-deploys can refresh it idempotently.
+ *
+ * Drift contract: the apply fast-path and `furnace validate` compare the
+ * *expanded* workspace source against the engine copy, so editing a
+ * fragment surfaces as ordinary component drift and the next deploy
+ * refreshes every consuming widget.
+ */
+import type { ValidationIssue } from '../types/furnace.js';
+export { SHARED_FRAGMENTS_DIR } from './furnace-config.js';
+/** Returns the fragment names referenced by `@fireforge-include` directives. */
+export declare function listFragmentIncludes(css: string): string[];
+/**
+ * Collapses fenced fragment expansions back to their bare directives.
+ * Inverse of {@link expandCssFragments}; used to compare a deployed file
+ * against its workspace source and to re-expand idempotently.
+ */
+export declare function stripExpandedFragments(css: string): string;
+/**
+ * Expands every `@fireforge-include` directive in `css` with the current
+ * content of its fragment file from `sharedDir`, fencing each expansion
+ * with an end marker. Existing expansions are stripped first, so the
+ * operation is idempotent and refreshes stale content.
+ *
+ * @param css - Stylesheet source (workspace or previously expanded)
+ * @param sharedDir - Absolute path to the shared fragments directory
+ * @returns Expanded stylesheet and the fragment names it consumed
+ * @throws FurnaceError when a fragment is missing or itself contains an
+ *   include directive (nesting is not supported)
+ */
+export declare function expandCssFragments(css: string, sharedDir: string): Promise<{
+    expanded: string;
+    includes: string[];
+}>;
+/**
+ * Extracts the fenced expansion bodies of a previously expanded stylesheet,
+ * keyed by fragment name. Used by validate to compare a deployed expansion
+ * against the current fragment source without re-deploying.
+ */
+export declare function extractExpandedFragmentBodies(css: string): Map<string, string>;
+/**
+ * Deploys one component file: CSS sources carrying include directives are
+ * written as their fragment-expanded form; everything else is a plain
+ * copy. Extracted here so `applyCustomComponent` stays inside the
+ * per-file line budget.
+ *
+ * @returns True when fragment expansion was applied
+ */
+export declare function deployFileWithFragments(src: string, dest: string, sharedDir: string): Promise<boolean>;
+/**
+ * Builds the dry-run description suffix for a component file copy,
+ * naming the fragments an expansion would inline. Empty for plain copies.
+ */
+export declare function describeFragmentExpansion(src: string): Promise<string>;
+/**
+ * Validates fragment usage for one custom component: every directive must
+ * name an existing fragment (`missing-fragment`, error), and a deployed
+ * stylesheet's fenced expansion must match the current fragment source
+ * (`stale-fragment-expansion`, warning → redeploy refreshes it).
+ *
+ * @param componentDir - Workspace directory of the component
+ * @param tagName - Component tag name for issue attribution
+ * @param sharedDir - Shared fragments directory
+ * @param engineTargetDir - Deployed directory in the engine (optional —
+ *   pre-deploy validation skips the staleness check)
+ */
+export declare function validateCssFragments(componentDir: string, tagName: string, sharedDir: string, engineTargetDir?: string): Promise<ValidationIssue[]>;

package/dist/src/core/furnace-css-fragments.js

@@ -0,0 +1,243 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Shared CSS fragments for Furnace widgets (field report D2).
+ *
+ * Shadow-DOM isolation forces each widget stylesheet to carry its own copy
+ * of genuinely shared CSS (keyframes, resets). Hand-syncing those copies
+ * drifts. Instead, a workspace stylesheet declares an include directive
+ * (a CSS block comment on its own line):
+ *
+ *     @fireforge-include shared-anims.css
+ *
+ * naming a fragment file in `components/shared/`. `furnace deploy` expands
+ * the fragment into the *deployed* copy only — the workspace source stays
+ * DRY — fencing the expansion between the directive line and a matching
+ * `@fireforge-end-include` marker so re-deploys can refresh it idempotently.
+ *
+ * Drift contract: the apply fast-path and `furnace validate` compare the
+ * *expanded* workspace source against the engine copy, so editing a
+ * fragment surfaces as ordinary component drift and the next deploy
+ * refreshes every consuming widget.
+ */
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { FurnaceError } from '../errors/furnace.js';
+import { copyFile, pathExists, readText, writeText } from '../utils/fs.js';
+export { SHARED_FRAGMENTS_DIR } from './furnace-config.js';
+// Local copy of the directory name for message text — importing the
+// binding for value use keeps a single source of truth.
+import { SHARED_FRAGMENTS_DIR } from './furnace-config.js';
+const INCLUDE_PATTERN = /^\s*\/\*\s*@fireforge-include\s+([\w./-]+)\s*\*\/\s*$/;
+const END_INCLUDE_PATTERN = /^\s*\/\*\s*@fireforge-end-include\s+([\w./-]+)\s*\*\/\s*$/;
+/** Returns the fragment names referenced by `@fireforge-include` directives. */
+export function listFragmentIncludes(css) {
+    const names = [];
+    for (const line of css.split('\n')) {
+        const m = INCLUDE_PATTERN.exec(line);
+        if (m?.[1] && !names.includes(m[1]))
+            names.push(m[1]);
+    }
+    return names;
+}
+/**
+ * Collapses fenced fragment expansions back to their bare directives.
+ * Inverse of {@link expandCssFragments}; used to compare a deployed file
+ * against its workspace source and to re-expand idempotently.
+ */
+export function stripExpandedFragments(css) {
+    const lines = css.split('\n');
+    const out = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        out.push(line);
+        const inc = INCLUDE_PATTERN.exec(line);
+        if (!inc?.[1])
+            continue;
+        // A bare directive (workspace file) has no fence to strip. Only skip
+        // the expansion body when a matching end marker actually follows —
+        // otherwise an unterminated fence would silently eat the rest of the
+        // file.
+        let endIndex = -1;
+        for (let j = i + 1; j < lines.length; j++) {
+            if (END_INCLUDE_PATTERN.exec(lines[j] ?? '')?.[1] === inc[1]) {
+                endIndex = j;
+                break;
+            }
+        }
+        if (endIndex !== -1)
+            i = endIndex;
+    }
+    return out.join('\n');
+}
+/**
+ * Expands every `@fireforge-include` directive in `css` with the current
+ * content of its fragment file from `sharedDir`, fencing each expansion
+ * with an end marker. Existing expansions are stripped first, so the
+ * operation is idempotent and refreshes stale content.
+ *
+ * @param css - Stylesheet source (workspace or previously expanded)
+ * @param sharedDir - Absolute path to the shared fragments directory
+ * @returns Expanded stylesheet and the fragment names it consumed
+ * @throws FurnaceError when a fragment is missing or itself contains an
+ *   include directive (nesting is not supported)
+ */
+export async function expandCssFragments(css, sharedDir) {
+    const stripped = stripExpandedFragments(css);
+    const includes = listFragmentIncludes(stripped);
+    if (includes.length === 0)
+        return { expanded: stripped, includes };
+    const fragments = new Map();
+    for (const name of includes) {
+        const fragmentPath = join(sharedDir, name);
+        if (!(await pathExists(fragmentPath))) {
+            throw new FurnaceError(`CSS fragment "${name}" not found in components/${SHARED_FRAGMENTS_DIR}/. ` +
+                'Create the fragment file or remove the @fireforge-include directive.');
+        }
+        const content = await readText(fragmentPath);
+        if (listFragmentIncludes(content).length > 0) {
+            throw new FurnaceError(`CSS fragment "${name}" contains an @fireforge-include directive of its own; ` +
+                'nested fragment includes are not supported.');
+        }
+        fragments.set(name, content.replace(/\n$/, ''));
+    }
+    const out = [];
+    for (const line of stripped.split('\n')) {
+        out.push(line);
+        const inc = INCLUDE_PATTERN.exec(line);
+        if (inc?.[1]) {
+            out.push(fragments.get(inc[1]) ?? '');
+            out.push(`/* @fireforge-end-include ${inc[1]} */`);
+        }
+    }
+    return { expanded: out.join('\n'), includes };
+}
+/**
+ * Extracts the fenced expansion bodies of a previously expanded stylesheet,
+ * keyed by fragment name. Used by validate to compare a deployed expansion
+ * against the current fragment source without re-deploying.
+ */
+export function extractExpandedFragmentBodies(css) {
+    const bodies = new Map();
+    const lines = css.split('\n');
+    let current = null;
+    let buffer = [];
+    for (const line of lines) {
+        if (current !== null) {
+            if (END_INCLUDE_PATTERN.exec(line)?.[1] === current) {
+                bodies.set(current, buffer.join('\n'));
+                current = null;
+                buffer = [];
+                continue;
+            }
+            buffer.push(line);
+            continue;
+        }
+        const inc = INCLUDE_PATTERN.exec(line);
+        if (inc?.[1]) {
+            current = inc[1];
+        }
+    }
+    return bodies;
+}
+/**
+ * Deploys one component file: CSS sources carrying include directives are
+ * written as their fragment-expanded form; everything else is a plain
+ * copy. Extracted here so `applyCustomComponent` stays inside the
+ * per-file line budget.
+ *
+ * @returns True when fragment expansion was applied
+ */
+export async function deployFileWithFragments(src, dest, sharedDir) {
+    if (src.endsWith('.css')) {
+        const content = await readText(src);
+        if (listFragmentIncludes(content).length > 0) {
+            const { expanded } = await expandCssFragments(content, sharedDir);
+            await writeText(dest, expanded);
+            return true;
+        }
+    }
+    await copyFile(src, dest);
+    return false;
+}
+/**
+ * Builds the dry-run description suffix for a component file copy,
+ * naming the fragments an expansion would inline. Empty for plain copies.
+ */
+export async function describeFragmentExpansion(src) {
+    if (!src.endsWith('.css'))
+        return '';
+    const includes = listFragmentIncludes(await readText(src));
+    if (includes.length === 0)
+        return '';
+    return ` (expanding fragment${includes.length === 1 ? '' : 's'}: ${includes.join(', ')})`;
+}
+/**
+ * Validates fragment usage for one custom component: every directive must
+ * name an existing fragment (`missing-fragment`, error), and a deployed
+ * stylesheet's fenced expansion must match the current fragment source
+ * (`stale-fragment-expansion`, warning → redeploy refreshes it).
+ *
+ * @param componentDir - Workspace directory of the component
+ * @param tagName - Component tag name for issue attribution
+ * @param sharedDir - Shared fragments directory
+ * @param engineTargetDir - Deployed directory in the engine (optional —
+ *   pre-deploy validation skips the staleness check)
+ */
+export async function validateCssFragments(componentDir, tagName, sharedDir, engineTargetDir) {
+    const issues = [];
+    if (!(await pathExists(componentDir)))
+        return issues;
+    // Graceful degradation like the other validators: an unreadable
+    // component directory must not cascade into a validation crash.
+    let entries;
+    try {
+        entries = await readdir(componentDir);
+    }
+    catch {
+        return issues;
+    }
+    for (const fileName of entries) {
+        if (!fileName.endsWith('.css'))
+            continue;
+        const source = await readText(join(componentDir, fileName));
+        const includes = listFragmentIncludes(source);
+        if (includes.length === 0)
+            continue;
+        let deployedBodies = null;
+        if (engineTargetDir) {
+            const destPath = join(engineTargetDir, fileName);
+            if (await pathExists(destPath)) {
+                deployedBodies = extractExpandedFragmentBodies(await readText(destPath));
+            }
+        }
+        for (const include of includes) {
+            const fragmentPath = join(sharedDir, include);
+            if (!(await pathExists(fragmentPath))) {
+                issues.push({
+                    component: tagName,
+                    severity: 'error',
+                    check: 'missing-fragment',
+                    message: `${fileName} includes CSS fragment "${include}", but components/${SHARED_FRAGMENTS_DIR}/${include} does not exist. ` +
+                        'Create the fragment or remove the @fireforge-include directive.',
+                });
+                continue;
+            }
+            if (deployedBodies === null)
+                continue;
+            const fragmentContent = (await readText(fragmentPath)).replace(/\n$/, '');
+            const deployed = deployedBodies.get(include);
+            if (deployed === undefined || deployed !== fragmentContent) {
+                issues.push({
+                    component: tagName,
+                    severity: 'warning',
+                    check: 'stale-fragment-expansion',
+                    message: deployed === undefined
+                        ? `Deployed ${fileName} has no expansion for fragment "${include}". Run "fireforge furnace deploy ${tagName}".`
+                        : `Deployed ${fileName} carries a stale expansion of fragment "${include}" — the fragment source changed since the last deploy. Run "fireforge furnace deploy ${tagName}".`,
+                });
+            }
+        }
+    }
+    return issues;
+}
+//# sourceMappingURL=furnace-css-fragments.js.map

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

@@ -0,0 +1,63 @@
+/**
+ * Maintains `compilerOptions.paths` entries in a consumer-owned jsconfig
+ * so typed cross-module imports of multi-file Furnace components work
+ * (field report D3).
+ *
+ * When a main widget imports a sibling helper via its deployed chrome URL
+ * (`chrome://global/content/elements/<helper>.mjs`), a wildcard module
+ * shim swallows the import: value imports degrade to `any` and
+ * `import(...).SomeType` typedefs fail with TS2694. The fix is a `paths`
+ * mapping from the chrome URL to the real workspace source. Furnace
+ * already owns the jar.mn side of that mapping, so it can maintain the
+ * jsconfig side automatically on every deploy.
+ *
+ * Ownership contract: only entries whose key starts with
+ * `chrome://global/content/elements/` AND whose mapped path resolves into
+ * the Furnace custom-components workspace are managed (added, updated,
+ * pruned). Everything else in the jsconfig — including hand-written
+ * `paths` entries pointing elsewhere — is preserved verbatim. No
+ * `baseUrl` is required or written: relative `paths` resolve against the
+ * config file's directory.
+ */
+import type { FurnaceConfig } from '../types/furnace.js';
+/** Result summary of a jsconfig paths sync. */
+export interface JsconfigSyncResult {
+    /** Keys newly added to compilerOptions.paths. */
+    added: string[];
+    /** Managed keys whose mapped path changed. */
+    updated: string[];
+    /** Managed keys removed because their component/file is gone. */
+    pruned: string[];
+    /** True when the file was (or would be) rewritten. */
+    changed: boolean;
+}
+/**
+ * Reconciles the managed `compilerOptions.paths` entries of the configured
+ * jsconfig against the current Furnace workspace. Idempotent; writes only
+ * when something actually changes; dry-run returns the diff without
+ * writing.
+ *
+ * The consumer owns the jsconfig file: a missing file is an error with
+ * guidance rather than a silent scaffold, and JSONC (comments/trailing
+ * commas) is unsupported for the managed file — `readJson` is a strict
+ * JSON parser, so the error message says so explicitly.
+ *
+ * @param root - Project root directory
+ * @param config - Loaded Furnace configuration (must carry `typecheckJsconfig`)
+ * @param options - `dryRun` skips the write but still reports the diff
+ */
+export declare function syncFurnaceJsconfigPaths(root: string, config: FurnaceConfig, options?: {
+    dryRun?: boolean;
+}): Promise<JsconfigSyncResult>;
+/**
+ * Computes jsconfig `paths` drift for `furnace validate`: managed entries
+ * that are missing or stale relative to the current workspace. Read-only —
+ * delegates to {@link syncFurnaceJsconfigPaths} in dry-run mode.
+ */
+export declare function findJsconfigPathsDrift(root: string, config: FurnaceConfig): Promise<JsconfigSyncResult>;
+/**
+ * Runs the jsconfig paths sync after a successful deploy/sync and reports
+ * the diff. No-op when `typecheckJsconfig` is unset. Shared by
+ * `furnace deploy` and `furnace sync` so both report identically.
+ */
+export declare function reportJsconfigPathsSync(root: string, config: FurnaceConfig, dryRun: boolean): Promise<void>;