@hominis/fireforge 0.43.0 → 0.44.0

package/dist/src/core/register-browser-content.js

@@ -5,83 +5,18 @@
 import { join } from 'node:path';
 import { GeneralError } from '../errors/base.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
-import { escapeRegex } from '../utils/regex.js';
-import { findAlphabeticalPosition, findAlphabeticalTokenPosition } from './manifest-helpers.js';
-import { tokenizeJarMn } from './manifest-tokenizers.js';
-import { withParserFallback } from './parser-fallback.js';
+import { insertJarMnEntry } from './moz-manifest-helpers.js';
 /**
  * Tokenizer-based implementation for browser content registration.
  */
 function registerBrowserContentTokenized(content, fileName, entry, after) {
-    const lines = content.split('\n');
-    const tokens = tokenizeJarMn(lines);
-    let afterFallback = false;
-    let insertIndex;
-    let previousEntry;
-    if (after) {
-        const afterPattern = new RegExp(`(?:^|/)${escapeRegex(after)}(?:\\s|\\)|$)`);
-        const afterToken = tokens.find((t) => afterPattern.test(t.raw));
-        if (afterToken) {
-            insertIndex = afterToken.lineIndex + 1;
-            previousEntry = afterToken.raw.trim();
-        }
-        else {
-            afterFallback = true;
-            ({ insertIndex, previousEntry } = findAlphabeticalTokenPosition(tokens, /content\/browser\/([^\s]+)/, fileName));
-        }
-    }
-    else {
-        ({ insertIndex, previousEntry } = findAlphabeticalTokenPosition(tokens, /content\/browser\/([^\s]+)/, fileName));
-    }
-    if (insertIndex === -1) {
-        throw new GeneralError('Could not find content/browser/ section in browser/base/jar.mn');
-    }
-    lines.splice(insertIndex, 0, entry);
-    return { result: lines.join('\n'), previousEntry, afterFallback };
-}
-/**
- * Legacy line-based implementation preserved as fallback.
- */
-function legacyRegisterBrowserContent(content, fileName, entry, after) {
-    const lines = content.split('\n');
-    let afterFallback = false;
-    const extractKey = (line) => {
-        const match = /content\/browser\/([^\s]+)/.exec(line);
-        return match?.[1];
-    };
-    let sectionStart = -1;
-    let sectionEnd = lines.length;
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
-        if (line === undefined)
-            continue;
-        if (/^\s+content\/browser\//.test(line)) {
-            if (sectionStart === -1)
-                sectionStart = i;
-            sectionEnd = i + 1;
-        }
-    }
-    if (sectionStart === -1) {
-        throw new GeneralError('Could not find content/browser/ section in browser/base/jar.mn');
-    }
-    let insertIndex;
-    let previousEntry;
-    if (after) {
-        const afterLineIdx = lines.findIndex((l) => l.includes(after));
-        if (afterLineIdx !== -1) {
-            insertIndex = afterLineIdx + 1;
-            previousEntry = lines[afterLineIdx]?.trim();
-        }
-        else {
-            afterFallback = true;
-            ({ insertIndex, previousEntry } = findAlphabeticalPosition(lines, sectionStart, sectionEnd, fileName, extractKey));
-        }
-    }
-    else {
-        ({ insertIndex, previousEntry } = findAlphabeticalPosition(lines, sectionStart, sectionEnd, fileName, extractKey));
-    }
-    lines.splice(insertIndex, 0, entry);
-    return { result: lines.join('\n'), previousEntry, afterFallback };
+    const { result, previousEntry, afterFallback } = insertJarMnEntry(content, entry, {
+        sortPattern: /content\/browser\/([^\s]+)/,
+        sortKey: fileName,
+        missingSectionMessage: 'Could not find content/browser/ section in browser/base/jar.mn',
+        after,
+    });
+    return { result, previousEntry, afterFallback };
 }
 /**
  * Registers a JS/content file in browser/base/jar.mn.
@@ -102,7 +37,7 @@ export async function registerBrowserContent(engineDir, fileName, after, sourceP
     if (content.includes(`content/browser/${fileName}`)) {
         return { manifest, entry, skipped: true };
     }
-    const { value } = withParserFallback(() => registerBrowserContentTokenized(content, fileName, entry, after), () => legacyRegisterBrowserContent(content, fileName, entry, after), manifest);
+    const value = registerBrowserContentTokenized(content, fileName, entry, after);
     if (!dryRun) {
         await writeText(manifestPath, value.result);
     }

package/dist/src/core/{register-test-manifest.js → register-browser-test.js}

@@ -5,51 +5,16 @@
 import { join } from 'node:path';
 import { GeneralError } from '../errors/base.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
-import { findAlphabeticalMozBuildPosition, findAlphabeticalPosition } from './manifest-helpers.js';
-import { tokenizeMozBuildList } from './manifest-tokenizers.js';
-import { withParserFallback } from './parser-fallback.js';
+import { insertMozBuildListEntry } from './moz-manifest-helpers.js';
 /**
  * Tokenizer-based implementation for test manifest registration.
  */
 function registerTestManifestTokenized(content, testDir, entry) {
-    const lines = content.split('\n');
-    const listResult = tokenizeMozBuildList(lines, /BROWSER_CHROME_MANIFESTS/);
-    if (!listResult) {
-        throw new GeneralError('Could not find BROWSER_CHROME_MANIFESTS in browser/base/moz.build');
-    }
-    const { insertIndex, previousEntry } = findAlphabeticalMozBuildPosition(listResult.tokens, `content/test/${testDir}/browser.toml`);
-    lines.splice(insertIndex, 0, entry);
-    return { result: lines.join('\n'), previousEntry };
-}
-/**
- * Legacy line-based implementation preserved as fallback.
- */
-function legacyRegisterTestManifest(content, testDir, entry) {
-    const lines = content.split('\n');
-    const extractKey = (line) => {
-        // Nested manifests (`content/test/a/b/browser.toml`) are supported —
-        // capture the whole directory chain, not just one segment.
-        const match = /"content\/test\/(.+)\/browser\.toml"/.exec(line);
-        return match?.[1];
-    };
-    let sectionStart = -1;
-    let sectionEnd = lines.length;
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
-        if (line === undefined)
-            continue;
-        if (/^\s+"content\/test\/.*browser\.toml"/.test(line)) {
-            if (sectionStart === -1)
-                sectionStart = i;
-            sectionEnd = i + 1;
-        }
-    }
-    if (sectionStart === -1) {
-        throw new GeneralError('Could not find test manifest section in browser/base/moz.build');
-    }
-    const { insertIndex, previousEntry } = findAlphabeticalPosition(lines, sectionStart, sectionEnd, testDir, extractKey);
-    lines.splice(insertIndex, 0, entry);
-    return { result: lines.join('\n'), previousEntry };
+    return insertMozBuildListEntry(content, entry, {
+        listPattern: /BROWSER_CHROME_MANIFESTS/,
+        sortKey: `content/test/${testDir}/browser.toml`,
+        missingListMessage: 'Could not find BROWSER_CHROME_MANIFESTS in browser/base/moz.build',
+    });
 }
 /**
  * Registers a test manifest (browser.toml) in browser/base/moz.build.
@@ -69,7 +34,7 @@ export async function registerTestManifest(engineDir, testDir, dryRun = false) {
     if (content.includes(`content/test/${testDir}/browser.toml`)) {
         return { manifest, entry, skipped: true };
     }
-    const { value } = withParserFallback(() => registerTestManifestTokenized(content, testDir, entry), () => legacyRegisterTestManifest(content, testDir, entry), manifest);
+    const value = registerTestManifestTokenized(content, testDir, entry);
     if (!dryRun) {
         await writeText(manifestPath, value.result);
     }

package/dist/src/core/register-module.js

@@ -5,50 +5,17 @@
 import { join } from 'node:path';
 import { GeneralError } from '../errors/base.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
-import { findAlphabeticalMozBuildPosition, findAlphabeticalPosition } from './manifest-helpers.js';
-import { tokenizeMozBuildList } from './manifest-tokenizers.js';
-import { withParserFallback } from './parser-fallback.js';
+import { insertMozBuildListEntry } from './moz-manifest-helpers.js';
 import { scaffoldModuleMozBuild } from './register-scaffold.js';
 /**
  * Tokenizer-based implementation for module registration.
  */
 function registerFireForgeModuleTokenized(content, fileName, entry) {
-    const lines = content.split('\n');
-    const listResult = tokenizeMozBuildList(lines, /EXTRA_JS_MODULES/);
-    if (!listResult) {
-        throw new GeneralError('Could not find EXTRA_JS_MODULES in moz.build');
-    }
-    const { insertIndex, previousEntry } = findAlphabeticalMozBuildPosition(listResult.tokens, fileName);
-    lines.splice(insertIndex, 0, entry);
-    return { result: lines.join('\n'), previousEntry };
-}
-/**
- * Legacy line-based implementation preserved as fallback.
- */
-function legacyRegisterFireForgeModule(content, fileName, entry, moduleDir) {
-    const lines = content.split('\n');
-    const extractKey = (line) => {
-        const match = /^\s+"([^"]+\.sys\.mjs)"/.exec(line);
-        return match?.[1];
-    };
-    let sectionStart = -1;
-    let sectionEnd = lines.length;
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
-        if (line === undefined)
-            continue;
-        if (/^\s+"[^"]+\.sys\.mjs"/.test(line)) {
-            if (sectionStart === -1)
-                sectionStart = i;
-            sectionEnd = i + 1;
-        }
-    }
-    if (sectionStart === -1) {
-        throw new GeneralError(`Could not find module list section in ${moduleDir}/moz.build`);
-    }
-    const { insertIndex, previousEntry } = findAlphabeticalPosition(lines, sectionStart, sectionEnd, fileName, extractKey);
-    lines.splice(insertIndex, 0, entry);
-    return { result: lines.join('\n'), previousEntry };
+    return insertMozBuildListEntry(content, entry, {
+        listPattern: /EXTRA_JS_MODULES/,
+        sortKey: fileName,
+        missingListMessage: 'Could not find EXTRA_JS_MODULES in moz.build',
+    });
 }
 /**
  * Registers a module in browser/modules/{binaryName}/moz.build.
@@ -61,9 +28,9 @@ export async function registerFireForgeModule(engineDir, fileName, moduleDir, dr
     const manifestPath = join(engineDir, manifest);
     if (!(await pathExists(manifestPath))) {
         if (createManifest) {
-            // 0.34.0 field report: registering a module under a directory with
-            // no moz.build failed with "Manifest not found". Scaffold the
-            // directory manifest and wire the parent DIRS chain.
+            // Registering a module under a directory with no moz.build otherwise
+            // fails with "Manifest not found". Scaffold the directory manifest and
+            // wire the parent DIRS chain.
             const scaffoldActions = await scaffoldModuleMozBuild(engineDir, moduleDir, fileName, dryRun);
             return {
                 manifest,
@@ -80,7 +47,7 @@ export async function registerFireForgeModule(engineDir, fileName, moduleDir, dr
     if (content.includes(`"${fileName}"`)) {
         return { manifest, entry, skipped: true };
     }
-    const { value } = withParserFallback(() => registerFireForgeModuleTokenized(content, fileName, entry), () => legacyRegisterFireForgeModule(content, fileName, entry, moduleDir), manifest);
+    const value = registerFireForgeModuleTokenized(content, fileName, entry);
     if (!dryRun) {
         await writeText(manifestPath, value.result);
     }

package/dist/src/core/register-scaffold.d.ts

@@ -1,13 +1,13 @@
 /**
- * Manifest scaffolding for `fireforge register --create-manifest`
- * (0.34.0 field report): registering a module under a directory with no
- * moz.build used to fail with "Manifest not found" because `register`
- * only inserts into EXISTING manifests. This module owns the two
- * scaffolding primitives:
+ * Manifest scaffolding for `fireforge register --create-manifest`.
  *
- *  - creating a directory `moz.build` (license header + the requested
- *    list directive) and wiring the parent chain's `DIRS` entries up to
- *    the nearest existing moz.build;
+ * `register` only inserts into EXISTING manifests, so registering a module
+ * under a directory with no moz.build fails with "Manifest not found". This
+ * module owns the two scaffolding primitives:
+ *
+ *  - creating a directory `moz.build` (license header + the requested list
+ *    directive) and wiring the parent chain's `DIRS` entries up to the
+ *    nearest existing moz.build;
  *  - wiring an `XPCSHELL_TESTS_MANIFESTS` entry for a (possibly freshly
  *    created) `xpcshell.toml` into the nearest existing moz.build.
  *

package/dist/src/core/register-scaffold.js

@@ -1,14 +1,14 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Manifest scaffolding for `fireforge register --create-manifest`
- * (0.34.0 field report): registering a module under a directory with no
- * moz.build used to fail with "Manifest not found" because `register`
- * only inserts into EXISTING manifests. This module owns the two
- * scaffolding primitives:
+ * Manifest scaffolding for `fireforge register --create-manifest`.
  *
- *  - creating a directory `moz.build` (license header + the requested
- *    list directive) and wiring the parent chain's `DIRS` entries up to
- *    the nearest existing moz.build;
+ * `register` only inserts into EXISTING manifests, so registering a module
+ * under a directory with no moz.build fails with "Manifest not found". This
+ * module owns the two scaffolding primitives:
+ *
+ *  - creating a directory `moz.build` (license header + the requested list
+ *    directive) and wiring the parent chain's `DIRS` entries up to the
+ *    nearest existing moz.build;
  *  - wiring an `XPCSHELL_TESTS_MANIFESTS` entry for a (possibly freshly
  *    created) `xpcshell.toml` into the nearest existing moz.build.
  *
@@ -20,8 +20,8 @@ import { dirname, join } from 'node:path';
 import { GeneralError } from '../errors/base.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
 import { getLicenseHeader } from './license-headers.js';
-import { findAlphabeticalMozBuildPosition } from './manifest-helpers.js';
-import { tokenizeMozBuildList } from './manifest-tokenizers.js';
+import { findAlphabeticalMozBuildPosition } from './moz-manifest-helpers.js';
+import { tokenizeMozBuildList } from './moz-manifest-tokenizers.js';
 /**
  * moz.build files use Firefox's canonical MPL-2.0 hash-comment header
  * regardless of the fork's own project license — they live in the engine

package/dist/src/core/register-shared-css.d.ts

@@ -3,19 +3,16 @@
  */
 import type { RegisterResult } from './register-result.js';
 /**
- * Measures the column at which the `(source)` parenthesis opens in
- * adjacent `skin/classic/browser/<x>.css (...)` entries inside an
- * existing jar.inc.mn body, and returns the maximum so a newly inserted
- * entry can align its source column to match.
+ * Measures the column at which the `(source)` parenthesis opens in adjacent
+ * `skin/classic/browser/<x>.css (...)` entries inside an existing
+ * jar.inc.mn body, and returns the maximum so a newly inserted entry can
+ * align its source column to match.
  *
- * 2026-04-26 eval Finding 3: pre-fix `registerSharedCSS` always emitted
- * a four-space gap between the target path and the parenthesis,
- * regardless of how the rest of the file was aligned. Adjacent Firefox
- * entries are typically padded to a wider column, so a freshly
- * registered file landed at the wrong column and produced avoidable
- * formatting churn. Returns `undefined` when no existing entries
- * provide an alignment signal — callers fall back to the four-space
- * default in that case.
+ * A fixed four-space gap regardless of the surrounding alignment lands a
+ * freshly registered file at the wrong column and produces avoidable
+ * formatting churn, since adjacent Firefox entries are typically padded to a
+ * wider column. Returns `undefined` when no existing entries provide an
+ * alignment signal — callers fall back to the four-space default.
  */
 export declare function measureSourceColumn(content: string): number | undefined;
 /**

package/dist/src/core/register-shared-css.js

@@ -5,101 +5,31 @@
 import { basename, join } from 'node:path';
 import { GeneralError } from '../errors/base.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
-import { escapeRegex } from '../utils/regex.js';
-import { findAlphabeticalPosition, findAlphabeticalTokenPosition } from './manifest-helpers.js';
-import { tokenizeJarMn } from './manifest-tokenizers.js';
-import { withParserFallback } from './parser-fallback.js';
+import { insertJarMnEntry } from './moz-manifest-helpers.js';
 /**
  * Tokenizer-based implementation for shared CSS registration.
  */
 function registerSharedCSSTokenized(content, name, entry, after) {
-    const lines = content.split('\n');
-    const tokens = tokenizeJarMn(lines);
-    let afterFallback = false;
-    let insertIndex;
-    let previousEntry;
-    if (after) {
-        const afterPattern = new RegExp(`(?:^|/)${escapeRegex(after)}(?:\\s|\\)|$)`);
-        const afterToken = tokens.find((t) => afterPattern.test(t.raw));
-        if (afterToken) {
-            insertIndex = afterToken.lineIndex + 1;
-            previousEntry = afterToken.raw.trim();
-        }
-        else {
-            afterFallback = true;
-            ({ insertIndex, previousEntry } = findAlphabeticalTokenPosition(tokens, /skin\/classic\/browser\/([^.]+)\.css/, name));
-        }
-    }
-    else {
-        ({ insertIndex, previousEntry } = findAlphabeticalTokenPosition(tokens, /skin\/classic\/browser\/([^.]+)\.css/, name));
-    }
-    if (insertIndex === -1) {
-        throw new GeneralError('Could not find skin/classic/browser/ section in jar.inc.mn');
-    }
-    lines.splice(insertIndex, 0, entry);
-    return { result: lines.join('\n'), insertIndex, previousEntry, afterFallback };
-}
-/**
- * Legacy line-based implementation preserved as fallback.
- */
-function legacyRegisterSharedCSS(content, name, entry, after) {
-    const lines = content.split('\n');
-    let afterFallback = false;
-    const extractKey = (line) => {
-        const match = /skin\/classic\/browser\/([^.]+)\.css/.exec(line);
-        return match?.[1];
-    };
-    let insertIndex;
-    let previousEntry;
-    // Find skin/classic/browser/ section boundaries
-    let sectionStart = -1;
-    let sectionEnd = lines.length;
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
-        if (line === undefined)
-            continue;
-        if (/skin\/classic\/browser\//.test(line)) {
-            if (sectionStart === -1)
-                sectionStart = i;
-            sectionEnd = i + 1;
-        }
-    }
-    if (sectionStart === -1) {
-        throw new GeneralError('Could not find skin/classic/browser/ section in jar.inc.mn');
-    }
-    if (after) {
-        const afterLineIdx = lines.findIndex((l) => l.includes(after));
-        if (afterLineIdx !== -1) {
-            insertIndex = afterLineIdx + 1;
-            previousEntry = lines[afterLineIdx]?.trim();
-        }
-        else {
-            afterFallback = true;
-            ({ insertIndex, previousEntry } = findAlphabeticalPosition(lines, sectionStart, sectionEnd, name, extractKey));
-        }
-    }
-    else {
-        ({ insertIndex, previousEntry } = findAlphabeticalPosition(lines, sectionStart, sectionEnd, name, extractKey));
-    }
-    lines.splice(insertIndex, 0, entry);
-    return { result: lines.join('\n'), previousEntry, afterFallback };
+    return insertJarMnEntry(content, entry, {
+        sortPattern: /skin\/classic\/browser\/([^.]+)\.css/,
+        sortKey: name,
+        missingSectionMessage: 'Could not find skin/classic/browser/ section in jar.inc.mn',
+        after,
+    });
 }
 /** Minimum gap between the target path and the source parenthesis. */
 const MIN_SOURCE_GAP = 4;
 /**
- * Measures the column at which the `(source)` parenthesis opens in
- * adjacent `skin/classic/browser/<x>.css (...)` entries inside an
- * existing jar.inc.mn body, and returns the maximum so a newly inserted
- * entry can align its source column to match.
+ * Measures the column at which the `(source)` parenthesis opens in adjacent
+ * `skin/classic/browser/<x>.css (...)` entries inside an existing
+ * jar.inc.mn body, and returns the maximum so a newly inserted entry can
+ * align its source column to match.
  *
- * 2026-04-26 eval Finding 3: pre-fix `registerSharedCSS` always emitted
- * a four-space gap between the target path and the parenthesis,
- * regardless of how the rest of the file was aligned. Adjacent Firefox
- * entries are typically padded to a wider column, so a freshly
- * registered file landed at the wrong column and produced avoidable
- * formatting churn. Returns `undefined` when no existing entries
- * provide an alignment signal — callers fall back to the four-space
- * default in that case.
+ * A fixed four-space gap regardless of the surrounding alignment lands a
+ * freshly registered file at the wrong column and produces avoidable
+ * formatting churn, since adjacent Firefox entries are typically padded to a
+ * wider column. Returns `undefined` when no existing entries provide an
+ * alignment signal — callers fall back to the four-space default.
  */
 export function measureSourceColumn(content) {
     const lines = content.split('\n');
@@ -167,7 +97,7 @@ export async function registerSharedCSS(engineDir, fileName, after, dryRun = fal
         content.includes(`content/browser/${name}.css`)) {
         return { manifest, entry, skipped: true };
     }
-    const { value } = withParserFallback(() => registerSharedCSSTokenized(content, name, entry, after), () => legacyRegisterSharedCSS(content, name, entry, after), manifest);
+    const value = registerSharedCSSTokenized(content, name, entry, after);
     if (!dryRun) {
         await writeText(manifestPath, value.result);
     }

package/dist/src/core/register-xpcshell-test.d.ts

@@ -1,11 +1,10 @@
 /**
- * xpcshell test-file registration (0.34.0 field report): xpcshell test
- * files (e.g. `<module-dir>/test/unit/test_*.js`) were rejected by
- * `fireforge register` as "Unknown file pattern". This writer inserts the
- * `["test_*.js"]` section into the directory's `xpcshell.toml`
- * (alphabetically, idempotently) and — with `--create-manifest` — creates
- * the manifest and wires `XPCSHELL_TESTS_MANIFESTS` into the nearest
- * moz.build.
+ * xpcshell test-file registration. Without it, xpcshell test files (e.g.
+ * `<module-dir>/test/unit/test_*.js`) are rejected by `fireforge register`
+ * as "Unknown file pattern". This writer inserts the `["test_*.js"]` section
+ * into the directory's `xpcshell.toml` (alphabetically, idempotently) and —
+ * with `--create-manifest` — creates the manifest and wires
+ * `XPCSHELL_TESTS_MANIFESTS` into the nearest moz.build.
  */
 import type { RegisterResult } from './register-result.js';
 /**

package/dist/src/core/register-xpcshell-test.js

@@ -1,17 +1,16 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * xpcshell test-file registration (0.34.0 field report): xpcshell test
- * files (e.g. `<module-dir>/test/unit/test_*.js`) were rejected by
- * `fireforge register` as "Unknown file pattern". This writer inserts the
- * `["test_*.js"]` section into the directory's `xpcshell.toml`
- * (alphabetically, idempotently) and — with `--create-manifest` — creates
- * the manifest and wires `XPCSHELL_TESTS_MANIFESTS` into the nearest
- * moz.build.
+ * xpcshell test-file registration. Without it, xpcshell test files (e.g.
+ * `<module-dir>/test/unit/test_*.js`) are rejected by `fireforge register`
+ * as "Unknown file pattern". This writer inserts the `["test_*.js"]` section
+ * into the directory's `xpcshell.toml` (alphabetically, idempotently) and —
+ * with `--create-manifest` — creates the manifest and wires
+ * `XPCSHELL_TESTS_MANIFESTS` into the nearest moz.build.
  */
 import { join } from 'node:path';
 import { GeneralError } from '../errors/base.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
-import { mozbuildSortCompare } from './manifest-helpers.js';
+import { mozbuildSortCompare } from './moz-manifest-helpers.js';
 import { ensureXpcshellManifestWiring } from './register-scaffold.js';
 function manifestMissingError(manifestRel) {
     return new GeneralError(`Manifest not found: ${manifestRel}. ` +

package/dist/src/core/shared-ftl.js

@@ -8,11 +8,19 @@
  * template generator assume the value is safe to interpolate verbatim.
  */
 /**
- * Characters that must not appear in `sharedFtl`:
- *  - Backticks close the MJS template literal the scaffold writes.
+ * Characters that must not appear in `sharedFtl`.
+ *
+ * A POLICY rule about what a sensible FTL path looks like, not the safety
+ * boundary for the generated `.mjs`: the scaffold escapes the value at its
+ * sink with `JSON.stringify` (`commands/furnace/create-templates.ts`), which
+ * is what actually makes interpolation safe and what covers the two inputs
+ * this rule never catches — a `"` and a raw newline.
+ *
+ * Kept because each remains a real sign of a malformed path:
  *  - `\` is a path-escape we do not want to interpret.
- *  - `${` opens a template expression and turns the FTL path into
- *    executable code.
+ *  - Backticks and `${` are inert in the current double-quoted sink, but a
+ *    template-literal sink is one refactor away and they are not valid in a
+ *    chrome:// FTL path regardless.
  */
 const UNSAFE_CHARS = /[`\\]|\$\{/;
 /**

package/dist/src/core/state-file.d.ts

@@ -2,3 +2,48 @@
 export declare function withStateFileLock<T>(statePath: string, operation: () => Promise<T>): Promise<T>;
 /** Renames a state file out of the way while preserving it for later inspection. */
 export declare function quarantineStateFile(statePath: string, reason?: string): Promise<string | undefined>;
+/**
+ * Outcome of a version check on a persisted FireForge document.
+ *
+ * The distinction that matters is `newer` vs `corrupt`. A document written
+ * by a NEWER FireForge is not damaged — the operator simply needs to upgrade
+ * — but a check that collapses the two offers destructive remedies. The
+ * sharpest case is the tree marker, whose `schemaVersion` check inside a
+ * boolean type guard makes a `schemaVersion: 2` marker read as "missing or
+ * mistypes a required field"; `tree-guard.ts` is default-deny on corrupt, so
+ * a newer FireForge would lock the operator out of every mutating command
+ * inside that tree.
+ *
+ * `furnace.json` is the pattern the rest should follow: it refuses a newer
+ * version by name and tells the operator to upgrade (`migrateFurnaceConfig`
+ * in `furnace-config.ts`).
+ */
+export type DocumentVersionCheck = {
+    kind: 'current';
+} | {
+    kind: 'older';
+    found: number;
+} | {
+    kind: 'newer';
+    found: number;
+} | {
+    kind: 'malformed';
+};
+/**
+ * Classifies a persisted document's `version`/`schemaVersion` field.
+ *
+ * @param raw - The parsed document
+ * @param field - Version field name, e.g. `schemaVersion`
+ * @param supported - Version this build writes and understands
+ * @returns Whether the document is current, older, newer, or malformed
+ */
+export declare function checkDocumentVersion(raw: unknown, field: string, supported: number): DocumentVersionCheck;
+/**
+ * The refusal shown for a document this build is too old to read.
+ *
+ * @param label - Operator-facing document name, e.g. `tree marker`
+ * @param found - Version found on disk
+ * @param supported - Version this build understands
+ * @returns A message naming both versions and the remedy
+ */
+export declare function describeNewerDocument(label: string, found: number, supported: number): string;

package/dist/src/core/state-file.js

@@ -22,3 +22,37 @@ export async function quarantineStateFile(statePath, reason = 'corrupt') {
     await rename(statePath, quarantinedPath);
     return basename(quarantinedPath);
 }
+/**
+ * Classifies a persisted document's `version`/`schemaVersion` field.
+ *
+ * @param raw - The parsed document
+ * @param field - Version field name, e.g. `schemaVersion`
+ * @param supported - Version this build writes and understands
+ * @returns Whether the document is current, older, newer, or malformed
+ */
+export function checkDocumentVersion(raw, field, supported) {
+    if (typeof raw !== 'object' || raw === null)
+        return { kind: 'malformed' };
+    const found = raw[field];
+    if (typeof found !== 'number' || !Number.isInteger(found) || found < 1) {
+        return { kind: 'malformed' };
+    }
+    if (found > supported)
+        return { kind: 'newer', found };
+    if (found < supported)
+        return { kind: 'older', found };
+    return { kind: 'current' };
+}
+/**
+ * The refusal shown for a document this build is too old to read.
+ *
+ * @param label - Operator-facing document name, e.g. `tree marker`
+ * @param found - Version found on disk
+ * @param supported - Version this build understands
+ * @returns A message naming both versions and the remedy
+ */
+export function describeNewerDocument(label, found, supported) {
+    return (`the ${label} was written by a newer FireForge (schema version ${found}; ` +
+        `this build understands ${supported}). Upgrade FireForge to read it — the file is ` +
+        'not damaged, so do not delete it.');
+}