@hominis/fireforge 0.16.5 → 0.18.0

package/dist/src/core/status-classify.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Status classifier: partitions engine file changes into
+ * patch-backed / unmanaged / branding / furnace / conflict buckets.
+ *
+ * Extracted from `src/commands/status.ts` so that command file stays
+ * under the per-file line budget as the number of buckets grows.
+ */
+/**
+ * Classification buckets for engine file changes:
+ * - `patch-backed`: content matches the expected post-patch state —
+ *   normal after `fireforge import`.
+ * - `unmanaged`: edits not explained by any patch or tool — local
+ *   drift to export or discard.
+ * - `branding`: files under tool-managed branding paths, written by
+ *   FireForge's branding pipeline.
+ * - `furnace`: files under Furnace-managed component prefixes.
+ * - `conflict`: the file is claimed by two or more patches in
+ *   `patches.json`. The human `--ownership` mode already surfaces
+ *   this bucket as `CONFLICT`; the classification is carried through
+ *   the JSON pipeline so machine consumers can detect the same
+ *   ownership breakage the human output shows. Before 0.16.0,
+ *   cross-patch conflicts silently rolled into the `unmanaged` bucket
+ *   in `--json`, which misled scripts built on top of the JSON view
+ *   into treating the file as routine local drift.
+ */
+export type FileClassification = 'patch-backed' | 'unmanaged' | 'branding' | 'furnace' | 'conflict';
+export interface StatusFile {
+    status: string;
+    file: string;
+}
+export interface ClassifiedFile extends StatusFile {
+    classification: FileClassification;
+    /**
+     * Names of patch files that claim this path in `patches.json`.
+     * Populated only when `classification === 'conflict'` — single-claim
+     * patch-backed entries don't need to expose their owner because the
+     * single claim is fully captured by the classification itself.
+     */
+    claimedBy?: string[];
+}
+/**
+ * Classifies files into patch-backed, unmanaged, branding, furnace, or
+ * conflict buckets.
+ *
+ * Tracks patch ownership as a `Map<file, patchFilename[]>` rather than
+ * a plain `Set<file>` so the classifier can surface cross-patch
+ * ownership conflicts the same way the human `--ownership` mode does.
+ * The 2026-04-21 eval's `status --json` run reported
+ * `classification: "unmanaged"` on two files (`browser/base/jar.mn`,
+ * `browser/themes/shared/jar.inc.mn`) that `--ownership` correctly
+ * flagged as `CONFLICT`; the JSON output was effectively lying to
+ * machine consumers about the nature of the drift.
+ */
+export declare function classifyFiles(files: StatusFile[], engineDir: string, patchesDir: string, binaryName: string, furnacePrefixes: Set<string>): Promise<ClassifiedFile[]>;

package/dist/src/core/status-classify.js

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Status classifier: partitions engine file changes into
+ * patch-backed / unmanaged / branding / furnace / conflict buckets.
+ *
+ * Extracted from `src/commands/status.ts` so that command file stays
+ * under the per-file line budget as the number of buckets grows.
+ */
+import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
+import { readText } from '../utils/fs.js';
+import { verbose } from '../utils/logger.js';
+import { isBrandingManagedPath } from './branding.js';
+import { computePatchedContent } from './patch-apply.js';
+import { loadPatchesManifest } from './patch-manifest.js';
+function getPrimaryStatusCode(status) {
+    if (status.includes('?'))
+        return '?';
+    if (status.includes('!'))
+        return '!';
+    for (const code of status) {
+        if (code !== ' ') {
+            return code;
+        }
+    }
+    return status;
+}
+/**
+ * Classifies files into patch-backed, unmanaged, branding, furnace, or
+ * conflict buckets.
+ *
+ * Tracks patch ownership as a `Map<file, patchFilename[]>` rather than
+ * a plain `Set<file>` so the classifier can surface cross-patch
+ * ownership conflicts the same way the human `--ownership` mode does.
+ * The 2026-04-21 eval's `status --json` run reported
+ * `classification: "unmanaged"` on two files (`browser/base/jar.mn`,
+ * `browser/themes/shared/jar.inc.mn`) that `--ownership` correctly
+ * flagged as `CONFLICT`; the JSON output was effectively lying to
+ * machine consumers about the nature of the drift.
+ */
+export async function classifyFiles(files, engineDir, patchesDir, binaryName, furnacePrefixes) {
+    const manifest = await loadPatchesManifest(patchesDir);
+    // Build a multimap from file path → list of claiming patch
+    // filenames so we can detect cross-patch ownership conflicts. The
+    // previous `Set<string>` captured only whether a path was claimed,
+    // not by whom, and collapsed multi-owner files into the single-owner
+    // branch where the expected-vs-actual content comparison then routed
+    // them into `unmanaged` when the content didn't match either owner's
+    // expectation.
+    const patchClaims = new Map();
+    if (manifest) {
+        for (const patch of manifest.patches) {
+            for (const f of patch.filesAffected) {
+                const owners = patchClaims.get(f);
+                if (owners) {
+                    owners.push(patch.filename);
+                }
+                else {
+                    patchClaims.set(f, [patch.filename]);
+                }
+            }
+        }
+    }
+    const results = [];
+    for (const entry of files) {
+        // Branding check first
+        if (isBrandingManagedPath(entry.file, binaryName)) {
+            results.push({ ...entry, classification: 'branding' });
+            continue;
+        }
+        // Furnace-managed component paths
+        if (furnacePrefixes.size > 0) {
+            let isFurnace = false;
+            for (const prefix of furnacePrefixes) {
+                if (entry.file.startsWith(prefix)) {
+                    isFurnace = true;
+                    break;
+                }
+            }
+            if (isFurnace) {
+                results.push({ ...entry, classification: 'furnace' });
+                continue;
+            }
+        }
+        const owners = patchClaims.get(entry.file);
+        // Multiple patches claim this file — surface the cross-patch
+        // ownership conflict regardless of whether the current content
+        // matches any single claim. `--ownership` reports the same state
+        // as `CONFLICT`; `--json` must agree so machine consumers of the
+        // two views see the same truth.
+        if (owners && owners.length >= 2) {
+            results.push({
+                ...entry,
+                classification: 'conflict',
+                claimedBy: [...owners],
+            });
+            continue;
+        }
+        // Not in any patch → unmanaged
+        if (!owners) {
+            results.push({ ...entry, classification: 'unmanaged' });
+            continue;
+        }
+        // File is claimed by exactly one patch — compare content.
+        const primaryCode = getPrimaryStatusCode(entry.status);
+        if (primaryCode === 'D') {
+            // Deleted file: patch-backed only if patch expects deletion
+            const expected = await computePatchedContent(patchesDir, engineDir, entry.file);
+            results.push({
+                ...entry,
+                classification: expected === null ? 'patch-backed' : 'unmanaged',
+            });
+            continue;
+        }
+        // File exists on disk — compare actual vs expected
+        try {
+            const [expected, actual] = await Promise.all([
+                computePatchedContent(patchesDir, engineDir, entry.file),
+                readText(join(engineDir, entry.file)),
+            ]);
+            results.push({
+                ...entry,
+                classification: actual === expected ? 'patch-backed' : 'unmanaged',
+            });
+        }
+        catch (error) {
+            verbose(`Treating ${entry.file} as unmanaged because patch-backed classification failed: ${toError(error).message}`);
+            // If we can't read the file, treat as unmanaged
+            results.push({ ...entry, classification: 'unmanaged' });
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=status-classify.js.map

package/dist/src/core/token-coverage.js

@@ -5,6 +5,21 @@ import { pathExists, readText } from '../utils/fs.js';
 import { verbose } from '../utils/logger.js';
 import { countRawCssColors } from '../utils/regex.js';
 import { loadFurnaceConfig } from './furnace-config.js';
+/**
+ * Default platform prefixes treated as allowlisted upstream vars. Any
+ * `var(--moz-*)` usage in a fork's CSS is a Firefox platform variable
+ * that the fork does not own and should not be counted as an unknown.
+ * 2026-04-21 eval (Finding #5): a `furnace override moz-button -t
+ * css-only` + one fork token produced 1% coverage because the 84
+ * upstream `--moz-*` vars in the copied baseline counted as unknown.
+ *
+ * Forks that want to opt out can override this via
+ * `furnace.json.platformPrefixes = []`; forks that want more can
+ * extend it (e.g. `['--moz-', '--in-content-']`). The config is
+ * additive — nothing is removed from the defaults unless the operator
+ * explicitly writes a shorter list.
+ */
+const DEFAULT_PLATFORM_PREFIXES = ['--moz-'];
 /**
  * Measures design token coverage across CSS files.
  *
@@ -19,6 +34,7 @@ export async function measureTokenCoverage(repoDir, cssFiles, projectRoot) {
     // Load furnace config gracefully
     let tokenPrefix;
     let tokenAllowlist;
+    let platformPrefixes = DEFAULT_PLATFORM_PREFIXES;
     try {
         const root = projectRoot ?? join(repoDir, '..');
         const config = await loadFurnaceConfig(root);
@@ -26,6 +42,9 @@ export async function measureTokenCoverage(repoDir, cssFiles, projectRoot) {
             tokenPrefix = config.tokenPrefix;
             tokenAllowlist = new Set(config.tokenAllowlist ?? []);
         }
+        if (config.platformPrefixes !== undefined) {
+            platformPrefixes = config.platformPrefixes;
+        }
     }
     catch (error) {
         verbose(`Proceeding without furnace token metadata because furnace.json could not be loaded: ${toError(error).message}`);
@@ -56,6 +75,11 @@ export async function measureTokenCoverage(repoDir, cssFiles, projectRoot) {
             else if (tokenAllowlist?.has(prop)) {
                 allowlisted++;
             }
+            else if (platformPrefixes.some((prefix) => prop.startsWith(prefix))) {
+                // Platform vars (upstream `--moz-*`) are counted as allowlisted
+                // so they don't drag the fork-owned coverage percentage down.
+                allowlisted++;
+            }
             else {
                 unknownVars++;
             }

package/dist/src/core/token-dark-mode.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Dark-mode insertion helpers for the tokens CSS scaffold.
+ *
+ * The 2026-04-21 eval reproduced a bug where `fireforge token add
+ * --mode override --dark-value ...` landed the dark declaration
+ * AFTER the nested `:root { }` inside the
+ * `@media (prefers-color-scheme: dark)` block had already closed,
+ * producing a declaration outside any rule block. The helpers here
+ * scan the comment-stripped source lines to find the *inner* `:root`
+ * block's closing `}` and return a line index the caller can splice
+ * into. When the inner `:root` is missing (a scaffold that drifted
+ * from the default), the fallback helper returns the outer `@media`
+ * block's close so the caller can materialise a fresh `:root` wrapper
+ * rather than dropping the dark value.
+ */
+/**
+ * Strips the content of `/* ... *\/` block comments from an array of
+ * CSS source lines while preserving each line's length. Indexed scans
+ * over the returned mirror line up with the original, so callers that
+ * compute an insertion index against the stripped array can splice
+ * into the original array at the same index.
+ *
+ * We blank the comment body with spaces (rather than removing it) so
+ * any downstream consumer that indexes by column — or derives an
+ * insertion index as a line number in the original array — still
+ * agrees on line numbers.
+ */
+export declare function stripBlockCommentsInLines(lines: string[]): string[];
+/**
+ * Finds the closing `}` line of the nested `:root { ... }` block inside
+ * a `@media (prefers-color-scheme: dark)` block. Returns `-1` when the
+ * media block exists but the nested `:root` block is missing; returns
+ * `null` when the `@media` block itself is absent.
+ *
+ * Runs the scan over a comment-stripped mirror of the source lines so
+ * braces inside CSS comments (`/* before { after *\/`) do not offset
+ * the depth counter. The scan is deliberately line-indexed so callers
+ * can splice into the original `lines` array at the returned index.
+ */
+export declare function findDarkRootInsertionIndex(lines: string[]): number | null;
+/**
+ * Finds the closing `}` of the outermost
+ * `@media (prefers-color-scheme: dark)` block. Used as the fallback
+ * landing site when the scaffold has no nested `:root { }` — the
+ * insertion helper uses this index to splice a brand-new `:root`
+ * wrapper containing the dark declaration, rather than dropping the
+ * value.
+ */
+export declare function findDarkMediaCloseIndex(lines: string[]): number;

package/dist/src/core/token-dark-mode.js

@@ -0,0 +1,182 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Dark-mode insertion helpers for the tokens CSS scaffold.
+ *
+ * The 2026-04-21 eval reproduced a bug where `fireforge token add
+ * --mode override --dark-value ...` landed the dark declaration
+ * AFTER the nested `:root { }` inside the
+ * `@media (prefers-color-scheme: dark)` block had already closed,
+ * producing a declaration outside any rule block. The helpers here
+ * scan the comment-stripped source lines to find the *inner* `:root`
+ * block's closing `}` and return a line index the caller can splice
+ * into. When the inner `:root` is missing (a scaffold that drifted
+ * from the default), the fallback helper returns the outer `@media`
+ * block's close so the caller can materialise a fresh `:root` wrapper
+ * rather than dropping the dark value.
+ */
+/**
+ * Strips the content of `/* ... *\/` block comments from an array of
+ * CSS source lines while preserving each line's length. Indexed scans
+ * over the returned mirror line up with the original, so callers that
+ * compute an insertion index against the stripped array can splice
+ * into the original array at the same index.
+ *
+ * We blank the comment body with spaces (rather than removing it) so
+ * any downstream consumer that indexes by column — or derives an
+ * insertion index as a line number in the original array — still
+ * agrees on line numbers.
+ */
+export function stripBlockCommentsInLines(lines) {
+    const out = [];
+    let inBlockComment = false;
+    for (const original of lines) {
+        let line = '';
+        for (let i = 0; i < original.length; i++) {
+            if (inBlockComment) {
+                if (original[i] === '*' && original[i + 1] === '/') {
+                    line += '  ';
+                    i += 1;
+                    inBlockComment = false;
+                }
+                else {
+                    line += ' ';
+                }
+            }
+            else if (original[i] === '/' && original[i + 1] === '*') {
+                line += '  ';
+                i += 1;
+                inBlockComment = true;
+            }
+            else {
+                // `original[i]` is provably defined here (the bounds check is
+                // the loop condition), but TS narrows it to `string | undefined`.
+                // Default to empty string so the concat stays well-typed.
+                line += original[i] ?? '';
+            }
+        }
+        out.push(line);
+    }
+    return out;
+}
+/**
+ * Finds the closing `}` line of the nested `:root { ... }` block inside
+ * a `@media (prefers-color-scheme: dark)` block. Returns `-1` when the
+ * media block exists but the nested `:root` block is missing; returns
+ * `null` when the `@media` block itself is absent.
+ *
+ * Runs the scan over a comment-stripped mirror of the source lines so
+ * braces inside CSS comments (`/* before { after *\/`) do not offset
+ * the depth counter. The scan is deliberately line-indexed so callers
+ * can splice into the original `lines` array at the returned index.
+ */
+export function findDarkRootInsertionIndex(lines) {
+    const stripped = stripBlockCommentsInLines(lines);
+    let darkMediaLine = -1;
+    for (let i = 0; i < stripped.length; i++) {
+        if (/prefers-color-scheme:\s*dark/.test(stripped[i] ?? '')) {
+            darkMediaLine = i;
+            break;
+        }
+    }
+    if (darkMediaLine === -1)
+        return null;
+    // Walk the comment-stripped lines after the @media header and find
+    // the first `:root {` opener inside the block. The opening brace of
+    // the selector may live on the same line as the selector name or on
+    // the following line; either shape is tolerated.
+    let rootOpenLine = -1;
+    for (let i = darkMediaLine; i < stripped.length; i++) {
+        const line = stripped[i] ?? '';
+        if (/(^|[\s,{])\s*:root\b/.test(line)) {
+            // Brace on the same line?
+            if (/:root[^{}]*\{/.test(line)) {
+                rootOpenLine = i;
+                break;
+            }
+            // Otherwise scan forward for the opening brace, stopping at the
+            // first `}` or second selector that would mean the `:root`
+            // declaration never opened a block.
+            for (let j = i + 1; j < stripped.length; j++) {
+                const next = stripped[j] ?? '';
+                if (/\{/.test(next)) {
+                    rootOpenLine = j;
+                    break;
+                }
+                if (/[};]/.test(next))
+                    break;
+            }
+            if (rootOpenLine !== -1)
+                break;
+        }
+    }
+    if (rootOpenLine === -1)
+        return -1;
+    // Depth-count starting from the `:root` opener. The first `{`
+    // encountered sets the entry depth to the initial counter value; the
+    // closing brace that returns to that depth terminates the block.
+    let depth = 0;
+    let entryDepth = 0;
+    let enteredBlock = false;
+    for (let i = rootOpenLine; i < stripped.length; i++) {
+        const line = stripped[i] ?? '';
+        for (const ch of line) {
+            if (ch === '{') {
+                depth++;
+                if (!enteredBlock) {
+                    entryDepth = depth - 1;
+                    enteredBlock = true;
+                }
+            }
+            else if (ch === '}') {
+                depth--;
+            }
+        }
+        if (enteredBlock && depth === entryDepth) {
+            return i;
+        }
+    }
+    return -1;
+}
+/**
+ * Finds the closing `}` of the outermost
+ * `@media (prefers-color-scheme: dark)` block. Used as the fallback
+ * landing site when the scaffold has no nested `:root { }` — the
+ * insertion helper uses this index to splice a brand-new `:root`
+ * wrapper containing the dark declaration, rather than dropping the
+ * value.
+ */
+export function findDarkMediaCloseIndex(lines) {
+    const stripped = stripBlockCommentsInLines(lines);
+    let darkMediaLine = -1;
+    for (let i = 0; i < stripped.length; i++) {
+        if (/prefers-color-scheme:\s*dark/.test(stripped[i] ?? '')) {
+            darkMediaLine = i;
+            break;
+        }
+    }
+    if (darkMediaLine === -1)
+        return -1;
+    let depth = 0;
+    let entryDepth = 0;
+    let enteredBlock = false;
+    for (let i = darkMediaLine; i < stripped.length; i++) {
+        const line = stripped[i] ?? '';
+        for (const ch of line) {
+            if (ch === '{') {
+                depth++;
+                if (!enteredBlock) {
+                    entryDepth = depth - 1;
+                    enteredBlock = true;
+                }
+            }
+            else if (ch === '}') {
+                depth--;
+            }
+        }
+        if (enteredBlock && depth === entryDepth) {
+            return i;
+        }
+    }
+    return -1;
+}
+//# sourceMappingURL=token-dark-mode.js.map

package/dist/src/core/token-manager.js

@@ -10,6 +10,7 @@ import { validateTokenName } from '../utils/validation.js';
 import { getProjectPaths, loadConfig } from './config.js';
 import { loadFurnaceConfig } from './furnace-config.js';
 import { findTableAfterHeading, findTableByColumns, insertRow, rewriteTableRows, updateCellByKey, } from './markdown-table.js';
+import { findDarkMediaCloseIndex, findDarkRootInsertionIndex } from './token-dark-mode.js';
 /** Returns the token CSS path relative to engine root for a given binary name. */
 export function getTokensCssPath(binaryName) {
     return `browser/themes/shared/${binaryName}-tokens.css`;
@@ -271,41 +272,24 @@ function findCategorySection(lines, category, tokensCssPath) {
 function insertDarkModeOverride(lines, options) {
     if (options.mode !== 'override' || !options.darkValue)
         return;
-    let darkMediaLine = -1;
-    for (let i = 0; i < lines.length; i++) {
-        if (/prefers-color-scheme:\s*dark/.test(lines[i] ?? '')) {
-            darkMediaLine = i;
-            break;
-        }
-    }
-    if (darkMediaLine === -1)
+    const insertionIndex = findDarkRootInsertionIndex(lines);
+    if (insertionIndex === null)
+        return; // No @media block at all.
+    const darkEntry = `    ${options.tokenName}: ${options.darkValue};`;
+    if (insertionIndex === -1) {
+        // @media block exists but has no nested :root { } — the scaffold
+        // drifted. Warn and fall back to appending a fresh nested :root
+        // block right before the @media block's closing brace so the
+        // generated CSS still parses, rather than dropping the dark value
+        // on the floor or producing a declaration outside any rule.
+        warn(`Dark-mode override block for "${options.tokenName}" could not find a nested ":root { }" inside @media (prefers-color-scheme: dark). Appending a fresh ":root { }" block — review the tokens CSS scaffold.`);
+        const outerCloseIndex = findDarkMediaCloseIndex(lines);
+        if (outerCloseIndex === -1)
+            return;
+        lines.splice(outerCloseIndex, 0, '  :root {', darkEntry, '  }');
         return;
-    // Find the closing } of the @media block
-    let darkBlockEnd = lines.length;
-    let depth = 0;
-    let entryDepth = 0;
-    let enteredBlock = false;
-    for (let i = darkMediaLine; i < lines.length; i++) {
-        const line = lines[i] ?? '';
-        for (const ch of line) {
-            if (ch === '{') {
-                depth++;
-                if (!enteredBlock) {
-                    entryDepth = depth - 1;
-                    enteredBlock = true;
-                }
-            }
-            if (ch === '}')
-                depth--;
-        }
-        if (enteredBlock && depth === entryDepth) {
-            darkBlockEnd = i;
-            break;
-        }
     }
-    // Insert the dark value before the closing }
-    const darkEntry = `    ${options.tokenName}: ${options.darkValue};`;
-    lines.splice(darkBlockEnd, 0, darkEntry);
+    lines.splice(insertionIndex, 0, darkEntry);
 }
 /**
  * Adds a token declaration to the CSS file in the correct category section.

package/dist/src/core/wire-destroy.d.ts

@@ -4,12 +4,16 @@
 /**
  * AST-based implementation: finds onUnload()/uninit() method body and
  * inserts the destroy block at the top (LIFO ordering).
+ *
+ * `marker` is prefixed to the generated comment so wire-generated
+ * edits carry the patch-lint `// <MARKER>:` signature
+ * `lintModificationComments` looks for (eval 1 Finding #9).
  */
-export declare function addDestroyAST(content: string, expression: string): string;
+export declare function addDestroyAST(content: string, expression: string, marker?: string): string;
 /**
  * Legacy regex/line-based implementation preserved as fallback.
  */
-export declare function legacyAddDestroy(content: string, expression: string): string;
+export declare function legacyAddDestroy(content: string, expression: string, marker?: string): string;
 /**
  * Adds a destroy expression to the top of onUnload() or uninit() in
  * browser-init.js (LIFO ordering — newest first).
@@ -18,4 +22,4 @@ export declare function legacyAddDestroy(content: string, expression: string): s
  * @param expression - The destroy expression (e.g., "MyComponent.destroy()")
  * @returns true if added, false if already present
  */
-export declare function addDestroyToBrowserInit(engineDir: string, expression: string): Promise<boolean>;
+export declare function addDestroyToBrowserInit(engineDir: string, expression: string, marker?: string): Promise<boolean>;

package/dist/src/core/wire-destroy.js

@@ -12,11 +12,16 @@ import { detectIndent, parseScript } from './ast-utils.js';
 import { withParserFallback } from './parser-fallback.js';
 import { assertBraceBalancePreserved, coerceToCall, extractNameFromExpression, findMethodBody, findMethodBraceIndex, validateWireName, } from './wire-utils.js';
 const BROWSER_INIT_JS = 'browser/base/content/browser-init.js';
+const DEFAULT_MARKER = 'FIREFORGE:';
 /**
  * AST-based implementation: finds onUnload()/uninit() method body and
  * inserts the destroy block at the top (LIFO ordering).
+ *
+ * `marker` is prefixed to the generated comment so wire-generated
+ * edits carry the patch-lint `// <MARKER>:` signature
+ * `lintModificationComments` looks for (eval 1 Finding #9).
  */
-export function addDestroyAST(content, expression) {
+export function addDestroyAST(content, expression, marker = DEFAULT_MARKER) {
     const name = extractNameFromExpression(expression);
     // See wire-init.ts for the rationale: the template interpolates the
     // expression verbatim, so a bare `Foo.bar` compiled to `Foo.bar;`
@@ -44,7 +49,7 @@ export function addDestroyAST(content, expression) {
         indent = '    ';
     }
     const block = [
-        `${indent}// ${name} destroy`,
+        `${indent}// ${marker} wire-destroy ${name}`,
         `${indent}try {`,
         `${indent}  if (typeof ${name} !== "undefined") {`,
         `${indent}    ${callExpression};`,
@@ -59,7 +64,7 @@ export function addDestroyAST(content, expression) {
 /**
  * Legacy regex/line-based implementation preserved as fallback.
  */
-export function legacyAddDestroy(content, expression) {
+export function legacyAddDestroy(content, expression, marker = DEFAULT_MARKER) {
     const name = extractNameFromExpression(expression);
     // Match the AST path on the call-coercion contract so fallback vs AST
     // emits identical blocks (see wire-init.ts).
@@ -73,7 +78,7 @@ export function legacyAddDestroy(content, expression) {
     }
     const insertIndex = found.braceIndex + 1;
     const block = [
-        `    // ${name} destroy`,
+        `    // ${marker} wire-destroy ${name}`,
         `    try {`,
         `      if (typeof ${name} !== "undefined") {`,
         `        ${callExpression};`,
@@ -93,7 +98,7 @@ export function legacyAddDestroy(content, expression) {
  * @param expression - The destroy expression (e.g., "MyComponent.destroy()")
  * @returns true if added, false if already present
  */
-export async function addDestroyToBrowserInit(engineDir, expression) {
+export async function addDestroyToBrowserInit(engineDir, expression, marker = DEFAULT_MARKER) {
     validateWireName(expression, 'destroy expression');
     const filePath = join(engineDir, BROWSER_INIT_JS);
     if (!(await pathExists(filePath))) {
@@ -109,7 +114,7 @@ export async function addDestroyToBrowserInit(engineDir, expression) {
     if (destroyPattern.test(content)) {
         return false;
     }
-    const { value, usedFallback } = withParserFallback(() => addDestroyAST(content, expression), () => legacyAddDestroy(content, expression), BROWSER_INIT_JS);
+    const { value, usedFallback } = withParserFallback(() => addDestroyAST(content, expression, marker), () => legacyAddDestroy(content, expression, marker), BROWSER_INIT_JS);
     if (usedFallback) {
         assertBraceBalancePreserved(content, value, BROWSER_INIT_JS);
     }

package/dist/src/core/wire-dom-fragment.d.ts

@@ -16,6 +16,23 @@ export declare function addDomFragmentTokenized(content: string, includeDirectiv
  * Legacy line-based implementation preserved as fallback.
  */
 export declare function legacyAddDomFragment(content: string, includeDirective: string): string;
+/**
+ * Dry-run precheck for `addDomFragment`. Reads the resolved chrome
+ * document and verifies it either already contains the `#include`
+ * directive (the idempotent-skip case) OR offers a locatable insertion
+ * point via {@link addDomFragmentTokenized} / {@link legacyAddDomFragment}.
+ * Throws the same `Could not find insertion point in chrome document`
+ * error the real run would throw when neither condition holds.
+ *
+ * Motivating case (2026-04-21 eval, Finding #12): `fireforge wire ...
+ * --dry-run` previewed a plausible mutation plan against
+ * `tokenHostDocuments[0]`, then `fireforge wire ...` without
+ * `--dry-run` threw `Could not find insertion point in chrome document`
+ * on the same arguments. The real run had always called the insertion
+ * helpers; dry-run did not. This helper runs the same check in the
+ * preview pass so plan and execution disagree less.
+ */
+export declare function probeDomFragmentInsertionPoint(engineDir: string, domFilePath: string, targetPath?: string): Promise<void>;
 /**
  * Inserts a `#include` directive for an `.inc.xhtml` file into the top-level
  * chrome document (default: `browser/base/content/browser.xhtml`), before