@hominis/fireforge 0.49.2 → 0.51.0

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

@@ -17,7 +17,8 @@ import { topologicalSortCustom } from './furnace-graph-utils.js';
 import { resolveFurnaceMarkerComment } from './furnace-marker.js';
 import { recordFurnaceRollbackFailure } from './furnace-operation.js';
 import { assertFurnaceEngineDirReady } from './furnace-precondition.js';
-import { addJarMnEntries, removeCustomElementRegistration, removeJarMnEntries, } from './furnace-registration.js';
+import { addJarMnEntries, removeCustomElementRegistration } from './furnace-registration.js';
+import { removeJarMnFileEntries } from './furnace-registration-jar-inplace.js';
 import { createRollbackJournal, restoreRollbackJournalOrThrow, snapshotFile, } from './furnace-rollback.js';
 import { blockingStepErrors, hasBlockingStepErrors } from './furnace-step-errors.js';
 import { runPostApplyConsistencyChecks } from './furnace-validate-registration.js';
@@ -39,6 +40,16 @@ function addMissingComponentError(result, name, directoryPath) {
         error: `Component directory not found: ${directoryPath}`,
     });
 }
+/**
+ * The skip both batch loops record when a component's source is unchanged
+ * since the last recorded apply and its engine copy still matches. `reason`
+ * keeps its long-standing text for API consumers; `kind` lets summaries
+ * name it.
+ */
+const ALREADY_CURRENT_SKIP = {
+    reason: 'No changes since last apply',
+    kind: 'already-current',
+};
 async function applyOverrideBatch(ctx) {
     const { config, furnacePaths, state, engineDir, ftlDir, dryRun } = ctx;
     const { result, allActions, newChecksums, rollbackJournal, componentName } = ctx;
@@ -66,7 +77,7 @@ async function applyOverrideBatch(ctx) {
                 const cachedEngine = extractComponentChecksums(state.engineChecksums, 'override', name);
                 const drifted = await hasOverrideEngineDrift({ engineDir, componentDir, ftlDir }, overrideConfig, cachedEngine);
                 if (!drifted) {
-                    result.skipped.push({ name, reason: 'No changes since last apply' });
+                    result.skipped.push({ name, ...ALREADY_CURRENT_SKIP });
                     recordComponentChecksums(newChecksums, previous, 'override', name);
                     continue;
                 }
@@ -122,8 +133,8 @@ async function applyOverrideBatch(ctx) {
 /**
  * After undeploying deleted files, the in-engine jar.mn and
  * customElements.js still carry entries for the removed files. Re-sync them
- * by removing all of `name`'s jar.mn entries and re-adding only those that
- * still exist in the workspace. If the .mjs itself was deleted, also drop
+ * by removing only the deleted files' jar.mn lines in place and adding any
+ * live file that has none. If the .mjs itself was deleted, also drop
  * the customElements.js registration. Snapshots are taken under the same
  * journal so the undo path is symmetric with apply.
  */
@@ -134,18 +145,17 @@ async function reconcileCustomRegistrationAfterUndeploy(args) {
     const deletedRegistrationFiles = deletedFiles.filter((f) => f.endsWith('.mjs') || f.endsWith('.css'));
     if (deletedRegistrationFiles.length === 0)
         return;
-    // jar.mn re-sync. addJarMnEntries is idempotent on duplicates but does not
-    // drop stale entries, so we need a remove-then-add cycle. The journal
-    // snapshot before each mutation gives us a clean rollback target.
+    // jar.mn re-sync: drop only the deleted files' lines, so the rest of the
+    // widget's block keeps its order and the owning patch carries no reorder
+    // hunks. addJarMnEntries is idempotent, so the add pass inserts only a
+    // live file that has no line yet. The journal snapshot before the
+    // mutation gives us a clean rollback target.
     if (rollbackJournal) {
         await snapshotFile(rollbackJournal, join(engineDir, JAR_MN));
     }
-    await removeJarMnEntries(engineDir, name);
+    await removeJarMnFileEntries(engineDir, name, deletedRegistrationFiles);
     const liveJarFiles = Object.keys(currentChecksums).filter((f) => f.endsWith('.mjs') || f.endsWith('.css'));
     if (liveJarFiles.length > 0) {
-        // applyCustomComponent has already added live entries, and the remove
-        // above dropped them too, so re-add now to leave jar.mn in the correct
-        // state.
         await addJarMnEntries(engineDir, name, liveJarFiles);
     }
     filesAffected.push(JAR_MN);
@@ -226,7 +236,7 @@ async function applyCustomBatch(ctx, root, markerComment) {
                 // re-apply even though the workspace is unchanged.
                 const drifted = await hasCustomEngineDrift({ root, name, componentDir, ftlDir }, customConfig);
                 if (!drifted) {
-                    result.skipped.push({ name, reason: 'No changes since last apply' });
+                    result.skipped.push({ name, ...ALREADY_CURRENT_SKIP });
                     recordComponentChecksums(newChecksums, previous, 'custom', name);
                     continue;
                 }

package/dist/src/core/furnace-composed-source.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The Furnace-composed form of a component source, and the questions that
+ * need it.
+ *
+ * `furnace apply` does not copy every source verbatim: a stylesheet with
+ * `@fireforge-include` directives is deployed with each fragment body from
+ * `components/shared/` inlined between the directive and its
+ * `@fireforge-end-include` marker. Anything that compares a deployed engine
+ * file with its source has to compare against that composed form, or a
+ * freshly deployed widget reads as a large difference it is not:
+ *
+ *  - the unexported-drift belt (`build`/`test --refuse-unexported-drift`),
+ *    which must not refuse to overwrite a deployed file with the very bytes
+ *    it already holds;
+ *  - `furnace diff`, which must show what the next apply would change.
+ */
+import type { FurnaceConfig } from '../types/furnace.js';
+/**
+ * Composes one component source into the bytes apply deploys: a stylesheet
+ * carrying include directives is fragment-expanded, anything else is
+ * returned as is.
+ *
+ * @param content - Workspace source content
+ * @param fileName - Source file name (only `.css` is ever expanded)
+ * @param sharedDir - Absolute path of `components/shared/`
+ * @returns The composed content
+ * @throws FurnaceError when an included fragment is missing or nested
+ */
+export declare function composeComponentSource(content: string, fileName: string, sharedDir: string): Promise<string>;
+/** The workspace source apply deploys to one engine path. */
+export interface FurnaceDeployedSource {
+    type: 'custom' | 'override';
+    component: string;
+    /** Source file name inside the component directory. */
+    fileName: string;
+    /** Absolute path of the workspace source. */
+    sourcePath: string;
+}
+/**
+ * Maps every engine-relative path `furnace apply` writes to the workspace
+ * source it writes there: custom `.mjs`/`.css` into `targetPath`, a custom
+ * component's own `.ftl` into the Fluent tree (never for `sharedFtl`), and
+ * each override copy candidate onto its engine target.
+ *
+ * @param root - Project root
+ * @param config - Loaded furnace.json
+ * @returns Engine-relative path (POSIX) → deployed source
+ */
+export declare function mapDeployedComponentSources(root: string, config: FurnaceConfig): Promise<Map<string, FurnaceDeployedSource>>;
+/**
+ * Why a deployed engine file is safe to overwrite from its component
+ * source even though no patch body or baseline explains it:
+ *
+ * - `composed-source`: it already equals the Furnace-composed current
+ *   source, so the overwrite writes the same bytes;
+ * - `fragment-refresh`: it differs from the composed source only inside
+ *   Furnace-generated fragment expansions (a fragment changed since it was
+ *   deployed), so the overwrite only refreshes generated text;
+ * - `previous-deploy`: it is exactly the content Furnace's last recorded
+ *   apply deployed (the source has moved on since), so the overwrite loses
+ *   nothing that was not already a component source.
+ */
+export type DeployedSourceMatch = 'composed-source' | 'fragment-refresh' | 'previous-deploy';
+/**
+ * For each engine-relative path, decides whether its current engine content
+ * is a Furnace deployment of its component source (see
+ * {@link DeployedSourceMatch}). Paths with no component source, an
+ * unreadable engine copy, or content explained by none of the matches are
+ * absent from the result.
+ *
+ * @param root - Project root
+ * @param engineDir - Absolute engine directory
+ * @param files - Engine-relative paths to classify
+ * @returns Engine-relative path → match, for the matching paths only
+ */
+export declare function matchDeployedComponentFiles(root: string, engineDir: string, files: readonly string[]): Promise<Map<string, DeployedSourceMatch>>;

package/dist/src/core/furnace-composed-source.js

@@ -0,0 +1,167 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The Furnace-composed form of a component source, and the questions that
+ * need it.
+ *
+ * `furnace apply` does not copy every source verbatim: a stylesheet with
+ * `@fireforge-include` directives is deployed with each fragment body from
+ * `components/shared/` inlined between the directive and its
+ * `@fireforge-end-include` marker. Anything that compares a deployed engine
+ * file with its source has to compare against that composed form, or a
+ * freshly deployed widget reads as a large difference it is not:
+ *
+ *  - the unexported-drift belt (`build`/`test --refuse-unexported-drift`),
+ *    which must not refuse to overwrite a deployed file with the very bytes
+ *    it already holds;
+ *  - `furnace diff`, which must show what the next apply would change.
+ */
+import { readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+import { pathExists, readText } from '../utils/fs.js';
+import { sha256Hex } from '../utils/hash.js';
+import { normalizePathSlashes } from '../utils/paths.js';
+import { isOverrideCopyCandidate } from './furnace-apply-helpers.js';
+import { extractComponentChecksums, normalizeForChecksum } from './furnace-checksum-utils.js';
+import { furnaceConfigExists, getFurnacePaths, loadFurnaceConfig, loadFurnaceState, } from './furnace-config.js';
+import { resolveFtlDir } from './furnace-constants.js';
+import { expandCssFragments, listFragmentIncludes, stripExpandedFragments, } from './furnace-css-fragments.js';
+import { isRegularFile } from './furnace-dir-entry.js';
+/**
+ * Composes one component source into the bytes apply deploys: a stylesheet
+ * carrying include directives is fragment-expanded, anything else is
+ * returned as is.
+ *
+ * @param content - Workspace source content
+ * @param fileName - Source file name (only `.css` is ever expanded)
+ * @param sharedDir - Absolute path of `components/shared/`
+ * @returns The composed content
+ * @throws FurnaceError when an included fragment is missing or nested
+ */
+export async function composeComponentSource(content, fileName, sharedDir) {
+    if (!fileName.endsWith('.css') || listFragmentIncludes(content).length === 0)
+        return content;
+    return (await expandCssFragments(content, sharedDir)).expanded;
+}
+/**
+ * Maps every engine-relative path `furnace apply` writes to the workspace
+ * source it writes there: custom `.mjs`/`.css` into `targetPath`, a custom
+ * component's own `.ftl` into the Fluent tree (never for `sharedFtl`), and
+ * each override copy candidate onto its engine target.
+ *
+ * @param root - Project root
+ * @param config - Loaded furnace.json
+ * @returns Engine-relative path (POSIX) → deployed source
+ */
+export async function mapDeployedComponentSources(root, config) {
+    const furnacePaths = getFurnacePaths(root);
+    const ftlDir = resolveFtlDir(config.ftlBasePath);
+    const sources = new Map();
+    for (const [component, custom] of Object.entries(config.custom)) {
+        const componentDir = join(furnacePaths.customDir, component);
+        for (const fileName of await listSourceFiles(componentDir)) {
+            let engineRel;
+            if (fileName.endsWith('.mjs') || fileName.endsWith('.css')) {
+                engineRel = normalizePathSlashes(join(custom.targetPath, fileName));
+            }
+            else if (fileName === `${component}.ftl` && custom.localized && !custom.sharedFtl) {
+                engineRel = normalizePathSlashes(join(ftlDir, fileName));
+            }
+            if (engineRel === undefined)
+                continue;
+            sources.set(engineRel, {
+                type: 'custom',
+                component,
+                fileName,
+                sourcePath: join(componentDir, fileName),
+            });
+        }
+    }
+    for (const [component, override] of Object.entries(config.overrides)) {
+        const componentDir = join(furnacePaths.overridesDir, component);
+        for (const fileName of await listSourceFiles(componentDir)) {
+            if (!isOverrideCopyCandidate(fileName, override.type))
+                continue;
+            // Same target rule as `getOverrideEngineTargetPath`, engine-relative.
+            const base = fileName.endsWith('.ftl') ? ftlDir : override.basePath;
+            sources.set(normalizePathSlashes(join(base, fileName)), {
+                type: 'override',
+                component,
+                fileName,
+                sourcePath: join(componentDir, fileName),
+            });
+        }
+    }
+    return sources;
+}
+async function listSourceFiles(componentDir) {
+    if (!(await pathExists(componentDir)))
+        return [];
+    const entries = await readdir(componentDir, { withFileTypes: true, encoding: 'utf8' });
+    return entries.filter((entry) => isRegularFile(entry)).map((entry) => entry.name);
+}
+/**
+ * Classifies one deployed engine file against its component source.
+ *
+ * @returns The match, or undefined when the engine copy is explained by
+ *   none of them (a real, unrecorded engine edit)
+ */
+async function matchDeployedSource(engineContent, source, sharedDir, appliedChecksums) {
+    const sourceContent = await readText(source.sourcePath);
+    const engine = normalizeForChecksum(engineContent);
+    let composed;
+    try {
+        composed = await composeComponentSource(sourceContent, source.fileName, sharedDir);
+    }
+    catch {
+        // A missing fragment: no composed form exists. The other two
+        // comparisons below still apply.
+    }
+    if (composed !== undefined && normalizeForChecksum(composed) === engine) {
+        return 'composed-source';
+    }
+    const strippedEngine = stripExpandedFragments(engine);
+    if (listFragmentIncludes(sourceContent).length > 0 &&
+        strippedEngine === stripExpandedFragments(normalizeForChecksum(sourceContent))) {
+        return 'fragment-refresh';
+    }
+    const recorded = extractComponentChecksums(appliedChecksums, source.type, source.component)[source.fileName];
+    // Apply records the checksum of the (unexpanded) source it deployed, so
+    // an engine copy with its expansions collapsed hashes to that value
+    // exactly when it is that deployment.
+    if (recorded !== undefined && sha256Hex(strippedEngine) === recorded) {
+        return 'previous-deploy';
+    }
+    return undefined;
+}
+/**
+ * For each engine-relative path, decides whether its current engine content
+ * is a Furnace deployment of its component source (see
+ * {@link DeployedSourceMatch}). Paths with no component source, an
+ * unreadable engine copy, or content explained by none of the matches are
+ * absent from the result.
+ *
+ * @param root - Project root
+ * @param engineDir - Absolute engine directory
+ * @param files - Engine-relative paths to classify
+ * @returns Engine-relative path → match, for the matching paths only
+ */
+export async function matchDeployedComponentFiles(root, engineDir, files) {
+    const matches = new Map();
+    if (files.length === 0 || !(await furnaceConfigExists(root)))
+        return matches;
+    const sources = await mapDeployedComponentSources(root, await loadFurnaceConfig(root));
+    const { sharedDir } = getFurnacePaths(root);
+    const { appliedChecksums } = await loadFurnaceState(root);
+    for (const file of files) {
+        const source = sources.get(file);
+        if (source === undefined)
+            continue;
+        const enginePath = join(engineDir, file);
+        if (!(await pathExists(enginePath)))
+            continue;
+        const match = await matchDeployedSource(await readText(enginePath), source, sharedDir, appliedChecksums);
+        if (match !== undefined)
+            matches.set(file, match);
+    }
+    return matches;
+}

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

@@ -0,0 +1,16 @@
+import { type FurnaceOptInCheck, type FurnaceValidationException } from '../types/furnace.js';
+/**
+ * Parses `validationExceptions[]`: `{ component, check, tag?, reason }`
+ * objects, no other keys, every field a non-empty string, and no two
+ * entries for the same component, check and tag.
+ */
+export declare function parseValidationExceptions(raw: unknown): FurnaceValidationException[];
+/**
+ * Parses `tokenSiblingSheets`: an object from a sheet glob to a non-empty
+ * list of partner paths or globs.
+ */
+export declare function parseTokenSiblingSheets(raw: unknown): Record<string, string[]>;
+/** Parses `minComponents`: a positive integer. */
+export declare function parseMinComponents(raw: unknown): number;
+/** Parses `optInChecks[]`: names from {@link FURNACE_OPT_IN_CHECKS}. */
+export declare function parseOptInChecks(raw: unknown): FurnaceOptInCheck[];

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

@@ -0,0 +1,102 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Validators for the `furnace validate` and `token lint` policy fields of
+ * furnace.json: `validationExceptions[]`, `optInChecks[]`, `minComponents`
+ * and `tokenSiblingSheets`.
+ *
+ * Strict on purpose, like `buildAudit.unpackaged`: every exception is a
+ * standing suppression of a finding, so a malformed one must fail at load
+ * rather than quietly suppress nothing (or everything).
+ */
+import { FurnaceError } from '../errors/furnace.js';
+import { FURNACE_OPT_IN_CHECKS, } from '../types/furnace.js';
+import { isArray, isObject, isString } from '../utils/validation.js';
+const EXCEPTION_KEYS = new Set(['component', 'check', 'tag', 'reason']);
+function requireNonEmptyString(entry, key, field) {
+    const value = entry[key];
+    if (!isString(value) || value.trim().length === 0) {
+        throw new FurnaceError(`Furnace config: "${field}.${key}" must be a non-empty string`);
+    }
+    return value;
+}
+/**
+ * Parses `validationExceptions[]`: `{ component, check, tag?, reason }`
+ * objects, no other keys, every field a non-empty string, and no two
+ * entries for the same component, check and tag.
+ */
+export function parseValidationExceptions(raw) {
+    if (!isArray(raw)) {
+        throw new FurnaceError('Furnace config: "validationExceptions" must be an array');
+    }
+    const seen = new Set();
+    return raw.map((entry, index) => {
+        const field = `validationExceptions[${String(index)}]`;
+        if (!isObject(entry)) {
+            throw new FurnaceError(`Furnace config: "${field}" must be an object with "component", "check" and "reason"`);
+        }
+        for (const key of Object.keys(entry)) {
+            if (!EXCEPTION_KEYS.has(key)) {
+                throw new FurnaceError(`Furnace config: "${field}" has unknown key "${key}"`);
+            }
+        }
+        const exception = {
+            component: requireNonEmptyString(entry, 'component', field),
+            check: requireNonEmptyString(entry, 'check', field),
+            reason: requireNonEmptyString(entry, 'reason', field),
+        };
+        if (entry['tag'] !== undefined)
+            exception.tag = requireNonEmptyString(entry, 'tag', field);
+        const identity = `${exception.component}\u0000${exception.check}\u0000${exception.tag ?? ''}`;
+        if (seen.has(identity)) {
+            const on = exception.tag !== undefined ? ` on <${exception.tag}>` : '';
+            throw new FurnaceError(`Furnace config: "${field}" repeats the exception for ${exception.component} [${exception.check}]${on}`);
+        }
+        seen.add(identity);
+        return exception;
+    });
+}
+function isOptInCheck(value) {
+    return FURNACE_OPT_IN_CHECKS.includes(value);
+}
+/**
+ * Parses `tokenSiblingSheets`: an object from a sheet glob to a non-empty
+ * list of partner paths or globs.
+ */
+export function parseTokenSiblingSheets(raw) {
+    if (!isObject(raw)) {
+        throw new FurnaceError('Furnace config: "tokenSiblingSheets" must be an object');
+    }
+    const out = {};
+    for (const [pattern, partners] of Object.entries(raw)) {
+        const valid = isArray(partners) &&
+            partners.length > 0 &&
+            partners.every((partner) => isString(partner) && partner.trim() !== '');
+        if (pattern.includes('..') || !valid || partners.some((p) => String(p).includes('..'))) {
+            throw new FurnaceError(`Furnace config: "tokenSiblingSheets.${pattern}" must be a non-empty list of engine-relative paths or globs (no "..")`);
+        }
+        out[pattern] = partners;
+    }
+    return out;
+}
+/** Parses `minComponents`: a positive integer. */
+export function parseMinComponents(raw) {
+    if (typeof raw !== 'number' || !Number.isInteger(raw) || raw < 1) {
+        throw new FurnaceError('Furnace config: "minComponents" must be a positive integer');
+    }
+    return raw;
+}
+/** Parses `optInChecks[]`: names from {@link FURNACE_OPT_IN_CHECKS}. */
+export function parseOptInChecks(raw) {
+    if (!isArray(raw)) {
+        throw new FurnaceError('Furnace config: "optInChecks" must be an array');
+    }
+    const checks = [];
+    for (const value of raw) {
+        if (!isString(value) || !isOptInCheck(value)) {
+            throw new FurnaceError(`Furnace config: "optInChecks" entry ${JSON.stringify(value)} is not an opt-in check. Valid: ${FURNACE_OPT_IN_CHECKS.join(', ')}`);
+        }
+        if (!checks.includes(value))
+            checks.push(value);
+    }
+    return checks;
+}

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

@@ -8,6 +8,7 @@
 import { FurnaceError } from '../errors/furnace.js';
 import { isJsonObject, isString } from '../utils/validation.js';
 import { parseStringArray } from './furnace-config-array-utils.js';
+import { parseMinComponents, parseOptInChecks, parseTokenSiblingSheets, parseValidationExceptions, } from './furnace-config-validate-exceptions.js';
 /**
  * Validates an override component config object.
  * @param data - Raw data to validate
@@ -93,6 +94,9 @@ export function applyOptionalFurnaceFields(migrated, config) {
     if (migrated['platformPrefixes'] !== undefined) {
         config.platformPrefixes = parseStringArray(migrated['platformPrefixes'], 'platformPrefixes');
     }
+    if (migrated['tokenSiblingSheets'] !== undefined) {
+        config.tokenSiblingSheets = parseTokenSiblingSheets(migrated['tokenSiblingSheets']);
+    }
     if (migrated['runtimeVariables'] !== undefined) {
         config.runtimeVariables = parseStringArray(migrated['runtimeVariables'], 'runtimeVariables');
     }
@@ -129,4 +133,14 @@ export function applyOptionalFurnaceFields(migrated, config) {
         }
         config.scanPaths = paths;
     }
+    // `furnace validate` policy: reviewed exceptions and opt-in checks.
+    if (migrated['validationExceptions'] !== undefined) {
+        config.validationExceptions = parseValidationExceptions(migrated['validationExceptions']);
+    }
+    if (migrated['optInChecks'] !== undefined) {
+        config.optInChecks = parseOptInChecks(migrated['optInChecks']);
+    }
+    if (migrated['minComponents'] !== undefined) {
+        config.minComponents = parseMinComponents(migrated['minComponents']);
+    }
 }

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

@@ -35,6 +35,16 @@ export declare function listFragmentIncludes(css: string): string[];
  * against its workspace source and to re-expand idempotently.
  */
 export declare function stripExpandedFragments(css: string): string;
+/**
+ * Marks the lines of a stylesheet that belong to a fenced fragment
+ * expansion: the directive, the inlined body and the end marker. Index `i`
+ * is line `i + 1` of `css`. Fences are found exactly as
+ * {@link stripExpandedFragments} finds them, so a bare directive or an
+ * unterminated fence marks nothing. The patch-size metric reads this
+ * off a file's post-image, because a hunk can start inside a span and
+ * carry no directive of its own.
+ */
+export declare function expandedFragmentLineMask(css: string): boolean[];
 /**
  * Expands every `@fireforge-include` directive in `css` with the current
  * content of its fragment file from `sharedDir`, fencing each expansion

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

@@ -78,6 +78,32 @@ export function stripExpandedFragments(css) {
     }
     return out.join('\n');
 }
+/**
+ * Marks the lines of a stylesheet that belong to a fenced fragment
+ * expansion: the directive, the inlined body and the end marker. Index `i`
+ * is line `i + 1` of `css`. Fences are found exactly as
+ * {@link stripExpandedFragments} finds them, so a bare directive or an
+ * unterminated fence marks nothing. The patch-size metric reads this
+ * off a file's post-image, because a hunk can start inside a span and
+ * carry no directive of its own.
+ */
+export function expandedFragmentLineMask(css) {
+    const lines = css.split('\n');
+    const mask = lines.map(() => false);
+    for (let i = 0; i < lines.length; i++) {
+        const inc = INCLUDE_PATTERN.exec(lines[i] ?? '');
+        if (!inc?.[1])
+            continue;
+        for (let j = i + 1; j < lines.length; j++) {
+            if (END_INCLUDE_PATTERN.exec(lines[j] ?? '')?.[1] !== inc[1])
+                continue;
+            mask.fill(true, i, j + 1);
+            i = j;
+            break;
+        }
+    }
+    return mask;
+}
 /**
  * Expands every `@fireforge-include` directive in `css` with the current
  * content of its fragment file from `sharedDir`, fencing each expansion

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

@@ -63,9 +63,9 @@ export interface RunFurnaceMutationOptions {
      * never passed: `furnace deploy --wait-lock 1800` waited 1800 s for the
      * engine session lock and then met `.fireforge/furnace.lock` with a fixed
      * 30 s, which is the worst shape a budget can have: it pays the whole
-     * wait and still refuses. When absent, {@link sessionWaitLockMs} supplies
-     * the session-wide budget so the twelve furnace mutators that declare no
-     * flag are covered too.
+     * wait and still refuses. Every furnace leaf that takes this lock threads
+     * its `--wait-lock` here. When absent, {@link sessionWaitLockMs} supplies
+     * the session-wide budget (`FIREFORGE_WAIT_LOCK`).
      */
     lockTimeoutMs?: number;
     /**

package/dist/src/core/furnace-registration-jar-inplace.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Removes the lines registering `files` for `tagName`, leaving every other
+ * line of the block where it is. Returns how many lines were removed.
+ */
+export declare function removeJarMnFileEntries(engineDir: string, tagName: string, files: readonly string[]): Promise<number>;
+/**
+ * Rewrites `oldTag`'s lines in place as `newTag`'s. A line whose renamed
+ * file is in `liveFiles` keeps its position and layout; one whose file is
+ * gone is dropped. Returns the renamed files that already had a line; the
+ * caller's `addJarMnEntries` pass then inserts only the rest.
+ */
+export declare function renameJarMnEntriesInPlace(engineDir: string, oldTag: string, newTag: string, liveFiles: readonly string[], renameFile: (file: string) => string): Promise<string[]>;

package/dist/src/core/furnace-registration-jar-inplace.js

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * In-place edits to a widget's `toolkit/content/jar.mn` block.
+ *
+ * Undeploying one file and renaming a component used to drop every line of
+ * the widget and re-add the live ones, which re-sorted the whole block and
+ * left the owning patch carrying reorder hunks. These helpers touch only
+ * the lines that change: a deleted file's line goes, a renamed component's
+ * lines are rewritten where they stand, and anything still missing is left
+ * for `addJarMnEntries` to insert.
+ */
+import { join } from 'node:path';
+import { pathExists, readText, writeText } from '../utils/fs.js';
+import { escapeRegex } from '../utils/regex.js';
+import { JAR_MN } from './furnace-constants.js';
+/**
+ * The file a widget jar.mn line registers: the `(widgets/<tag>/<file>)`
+ * source mapping, or the legacy `content/global/elements/<tag>.<ext>`
+ * target written before the mapping existed. Undefined when the line is
+ * not one of this tag's.
+ */
+function registeredFile(line, tagName) {
+    const tag = escapeRegex(tagName);
+    const source = new RegExp(`\\(widgets/${tag}/([^)]+)\\)`).exec(line);
+    if (source)
+        return source[1];
+    const legacy = new RegExp(`content/global/elements/(${tag}\\.[^\\s]+)`).exec(line);
+    return legacy?.[1];
+}
+/**
+ * Removes the lines registering `files` for `tagName`, leaving every other
+ * line of the block where it is. Returns how many lines were removed.
+ */
+export async function removeJarMnFileEntries(engineDir, tagName, files) {
+    const filePath = join(engineDir, JAR_MN);
+    if (files.length === 0 || !(await pathExists(filePath)))
+        return 0;
+    const doomed = new Set(files);
+    const lines = (await readText(filePath)).split('\n');
+    const kept = lines.filter((line) => {
+        const file = registeredFile(line, tagName);
+        return file === undefined || !doomed.has(file);
+    });
+    const removed = lines.length - kept.length;
+    if (removed > 0)
+        await writeText(filePath, kept.join('\n'));
+    return removed;
+}
+/**
+ * Rewrites `oldTag`'s lines in place as `newTag`'s. A line whose renamed
+ * file is in `liveFiles` keeps its position and layout; one whose file is
+ * gone is dropped. Returns the renamed files that already had a line; the
+ * caller's `addJarMnEntries` pass then inserts only the rest.
+ */
+export async function renameJarMnEntriesInPlace(engineDir, oldTag, newTag, liveFiles, renameFile) {
+    const filePath = join(engineDir, JAR_MN);
+    if (!(await pathExists(filePath)))
+        return [];
+    const live = new Set(liveFiles);
+    const covered = [];
+    const out = [];
+    for (const line of (await readText(filePath)).split('\n')) {
+        const file = registeredFile(line, oldTag);
+        if (file === undefined) {
+            out.push(line);
+            continue;
+        }
+        const renamed = renameFile(file);
+        if (!live.has(renamed) || covered.includes(renamed))
+            continue;
+        // Textual substitution keeps the indent, column spacing and any
+        // trailing comment the line carried.
+        out.push(line
+            .replace(`content/global/elements/${file}`, `content/global/elements/${renamed}`)
+            .replace(`(widgets/${oldTag}/${file})`, `(widgets/${newTag}/${renamed})`));
+        covered.push(renamed);
+    }
+    await writeText(filePath, out.join('\n'));
+    return covered;
+}