@hominis/fireforge 0.9.0

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

@@ -0,0 +1,99 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Test manifest registration in browser/base/moz.build.
+ */
+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';
+/**
+ * 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) => {
+        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 };
+}
+/**
+ * Registers a test manifest (browser.toml) in browser/base/moz.build.
+ *
+ * Entry format:
+ *     "content/test/{dir}/browser.toml",
+ */
+export async function registerTestManifest(engineDir, testDir, dryRun = false) {
+    const manifest = 'browser/base/moz.build';
+    const manifestPath = join(engineDir, manifest);
+    if (!(await pathExists(manifestPath))) {
+        throw new GeneralError(`Manifest not found: ${manifest}`);
+    }
+    const entry = `    "content/test/${testDir}/browser.toml",`.replace(/\\/g, '/');
+    const content = await readText(manifestPath);
+    // Idempotency check
+    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);
+    if (!dryRun) {
+        await writeText(manifestPath, value.result);
+    }
+    return { manifest, entry, previousEntry: value.previousEntry, skipped: false };
+}
+/**
+ * Deregisters a test manifest (browser.toml) from browser/base/moz.build.
+ * @param engineDir - Path to the engine directory
+ * @param testDir - Test directory name (e.g. 'mybrowser')
+ * @returns Whether the entry was removed
+ */
+export async function deregisterTestManifest(engineDir, testDir) {
+    const manifest = 'browser/base/moz.build';
+    const manifestPath = join(engineDir, manifest);
+    if (!(await pathExists(manifestPath))) {
+        return false;
+    }
+    const content = await readText(manifestPath);
+    const entryPattern = `content/test/${testDir}/browser.toml`;
+    if (!content.includes(entryPattern)) {
+        return false;
+    }
+    // Remove the line containing the entry (including trailing newline)
+    const lines = content.split('\n');
+    const filtered = lines.filter((line) => !line.includes(entryPattern));
+    await writeText(manifestPath, filtered.join('\n'));
+    return true;
+}
+//# sourceMappingURL=register-test-manifest.js.map

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

@@ -0,0 +1,4 @@
+/** Runs an operation while holding the sidecar lock for a FireForge state file. */
+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>;

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

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { rename } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { pathExists } from '../utils/fs.js';
+import { createSiblingLockPath, withFileLock } from './file-lock.js';
+/** Runs an operation while holding the sidecar lock for a FireForge state file. */
+export async function withStateFileLock(statePath, operation) {
+    return withFileLock(createSiblingLockPath(statePath, '.fireforge-state.lock'), operation, {
+        onTimeoutMessage: `Timed out waiting to update FireForge state at ${statePath}. ` +
+            'If no other fireforge process is running, remove the stale lock directory and retry.',
+        onStaleLockMessage: (ageMs) => `Removing stale FireForge state lock for ${basename(statePath)} ` +
+            `(age: ${Math.round(ageMs / 1000)}s). A previous fireforge process may have crashed.`,
+    });
+}
+/** Renames a state file out of the way while preserving it for later inspection. */
+export async function quarantineStateFile(statePath, reason = 'corrupt') {
+    if (!(await pathExists(statePath))) {
+        return undefined;
+    }
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const quarantinedPath = `${statePath}.${reason}-${timestamp}`;
+    await rename(statePath, quarantinedPath);
+    return basename(quarantinedPath);
+}
+//# sourceMappingURL=state-file.js.map

package/dist/src/core/token-coverage.d.ts

@@ -0,0 +1,12 @@
+import type { TokenCoverageReport } from '../types/commands/index.js';
+/**
+ * Measures design token coverage across CSS files.
+ *
+ * Counts var(--{prefix}*) usages, allowlisted vars, unknown vars, and raw
+ * color values. Reuses the same regex patterns as patch-lint.ts.
+ *
+ * @param repoDir - Absolute path to the engine (repository) directory
+ * @param cssFiles - File paths (relative to repoDir) to scan
+ * @returns Aggregate and per-file coverage report
+ */
+export declare function measureTokenCoverage(repoDir: string, cssFiles: string[], projectRoot?: string): Promise<TokenCoverageReport>;

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

@@ -0,0 +1,74 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
+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';
+/**
+ * Measures design token coverage across CSS files.
+ *
+ * Counts var(--{prefix}*) usages, allowlisted vars, unknown vars, and raw
+ * color values. Reuses the same regex patterns as patch-lint.ts.
+ *
+ * @param repoDir - Absolute path to the engine (repository) directory
+ * @param cssFiles - File paths (relative to repoDir) to scan
+ * @returns Aggregate and per-file coverage report
+ */
+export async function measureTokenCoverage(repoDir, cssFiles, projectRoot) {
+    // Load furnace config gracefully
+    let tokenPrefix;
+    let tokenAllowlist;
+    try {
+        const root = projectRoot ?? join(repoDir, '..');
+        const config = await loadFurnaceConfig(root);
+        if (config.tokenPrefix) {
+            tokenPrefix = config.tokenPrefix;
+            tokenAllowlist = new Set(config.tokenAllowlist ?? []);
+        }
+    }
+    catch (error) {
+        verbose(`Proceeding without furnace token metadata because furnace.json could not be loaded: ${toError(error).message}`);
+    }
+    const entries = [];
+    for (const file of cssFiles) {
+        const filePath = join(repoDir, file);
+        if (!(await pathExists(filePath)))
+            continue;
+        const rawCss = await readText(filePath);
+        // Strip block comments before scanning
+        const css = rawCss.replace(/\/\*[\s\S]*?\*\//g, '');
+        // Count raw color values
+        const rawColors = countRawCssColors(css);
+        // Count custom property usages by category
+        let tokenUsages = 0;
+        let allowlisted = 0;
+        let unknownVars = 0;
+        const varPattern = /var\(\s*(--[\w-]+)/g;
+        let match;
+        while ((match = varPattern.exec(css)) !== null) {
+            const prop = match[1];
+            if (!prop)
+                continue;
+            if (tokenPrefix && prop.startsWith(tokenPrefix)) {
+                tokenUsages++;
+            }
+            else if (tokenAllowlist?.has(prop)) {
+                allowlisted++;
+            }
+            else {
+                unknownVars++;
+            }
+        }
+        entries.push({ file, tokenUsages, allowlisted, unknownVars, rawColors });
+    }
+    return {
+        filesScanned: entries.length,
+        tokenUsages: entries.reduce((s, e) => s + e.tokenUsages, 0),
+        allowlistedUsages: entries.reduce((s, e) => s + e.allowlisted, 0),
+        unknownVarUsages: entries.reduce((s, e) => s + e.unknownVars, 0),
+        rawColorCount: entries.reduce((s, e) => s + e.rawColors, 0),
+        files: entries,
+    };
+}
+//# sourceMappingURL=token-coverage.js.map

package/dist/src/core/token-manager.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Dark mode behavior for a token.
+ */
+export type TokenMode = 'auto' | 'static' | 'override';
+/**
+ * Options for adding a token.
+ */
+export interface AddTokenOptions {
+    /** Full token name including prefix (e.g., "--mybrowser-widget-dot-size") */
+    tokenName: string;
+    /** CSS value (e.g., "1px", "var(--space-small)", "light-dark(#fff, #000)") */
+    value: string;
+    /** Token category matching section headers in the CSS file */
+    category: string;
+    /** Dark mode behavior */
+    mode: TokenMode;
+    /** Comment description for the CSS file */
+    description?: string | undefined;
+    /** Dark mode value (required if mode is "override") */
+    darkValue?: string | undefined;
+    /** Dry run mode */
+    dryRun?: boolean | undefined;
+}
+/**
+ * Result of adding a token.
+ */
+export interface AddTokenResult {
+    /** Whether the token was added to CSS */
+    cssAdded: boolean;
+    /** Whether the token was added to the docs table */
+    docsAdded: boolean;
+    /** Whether it was added to the unmapped table */
+    unmappedAdded: boolean;
+    /** Whether the count table was updated */
+    countUpdated: boolean;
+    /** Whether the operation was skipped (already exists) */
+    skipped: boolean;
+}
+/** Returns the token CSS path relative to engine root for a given binary name. */
+export declare function getTokensCssPath(binaryName: string): string;
+/**
+ * Validates token-add inputs without mutating files.
+ *
+ * @param root - Project root directory
+ * @param options - Token options
+ */
+export declare function validateTokenAdd(root: string, options: AddTokenOptions): Promise<void>;
+/**
+ * Adds a design token to the CSS file and documentation.
+ *
+ * @param root - Project root directory
+ * @param options - Token options
+ * @returns Result of the operation
+ */
+export declare function addToken(root: string, options: AddTokenOptions): Promise<AddTokenResult>;

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

@@ -0,0 +1,387 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { join } from 'node:path';
+import { GeneralError, InvalidArgumentError } from '../errors/base.js';
+import { FurnaceError } from '../errors/furnace.js';
+import { toError } from '../utils/errors.js';
+import { pathExists, readText, writeText } from '../utils/fs.js';
+import { warn } from '../utils/logger.js';
+import { escapeRegex } from '../utils/regex.js';
+import { validateTokenName } from '../utils/validation.js';
+import { getProjectPaths, loadConfig } from './config.js';
+import { loadFurnaceConfig } from './furnace-config.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`;
+}
+const TOKENS_DOC = 'docs/design/SRC_TOKENS.md';
+/**
+ * Determines the mode annotation string for the CSS comment.
+ */
+function getModeAnnotation(mode, value) {
+    if (mode === 'override')
+        return 'override';
+    if (mode === 'auto') {
+        if (value.includes('light-dark('))
+            return 'auto (light-dark)';
+        return 'auto';
+    }
+    // static
+    if (value.startsWith('var(--'))
+        return 'static';
+    return 'static, fork-specific';
+}
+async function resolveTokenAddContext(root) {
+    const { engine: engineDir } = getProjectPaths(root);
+    const forgeConfig = await loadConfig(root);
+    return {
+        engineDir,
+        tokensCssPath: getTokensCssPath(forgeConfig.binaryName),
+    };
+}
+async function validateTokenPrefix(root, options) {
+    try {
+        const config = await loadFurnaceConfig(root);
+        if (config.tokenPrefix && !options.tokenName.startsWith(config.tokenPrefix)) {
+            throw new InvalidArgumentError(`Token name "${options.tokenName}" does not match the configured prefix "${config.tokenPrefix}".`, 'tokenName');
+        }
+    }
+    catch (error) {
+        if (error instanceof InvalidArgumentError)
+            throw error;
+        // FurnaceError means furnace.json doesn't exist yet — skip silently.
+        // Other errors (parse errors, permission errors) deserve a warning.
+        if (!(error instanceof FurnaceError)) {
+            const message = toError(error).message;
+            warn(`Skipping token prefix validation: ${message}`);
+        }
+    }
+}
+function validateTokenNameSyntax(tokenName) {
+    const error = validateTokenName(tokenName);
+    if (error) {
+        throw new InvalidArgumentError(error, 'tokenName');
+    }
+}
+function validateDarkValue(options) {
+    if (options.mode === 'override' && !options.darkValue) {
+        throw new InvalidArgumentError('Override mode requires --dark-value to be specified.', 'darkValue');
+    }
+}
+async function assertTokenCategoryExists(engineDir, tokensCssPath, category) {
+    const filePath = join(engineDir, tokensCssPath);
+    if (!(await pathExists(filePath))) {
+        throw new GeneralError(`Token CSS file not found: ${tokensCssPath}`);
+    }
+    const content = await readText(filePath);
+    const lines = content.split('\n');
+    const escapedCategory = escapeRegex(category);
+    const singleLinePattern = new RegExp(`\\/\\*\\s*=.*${escapedCategory}.*=\\s*\\*\\/`);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (singleLinePattern.test(line)) {
+            return;
+        }
+        if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
+            for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
+                const blockLine = lines[j] ?? '';
+                if (new RegExp(escapedCategory).test(blockLine)) {
+                    return;
+                }
+                if (/\*\//.test(blockLine))
+                    break;
+            }
+        }
+    }
+    throw new GeneralError(`Category "${category}" not found in ${tokensCssPath}. ` +
+        'Available categories are defined by /* =... category ...= */ comment headers.');
+}
+/**
+ * Validates token-add inputs without mutating files.
+ *
+ * @param root - Project root directory
+ * @param options - Token options
+ */
+export async function validateTokenAdd(root, options) {
+    const { engineDir, tokensCssPath } = await resolveTokenAddContext(root);
+    validateTokenNameSyntax(options.tokenName);
+    await validateTokenPrefix(root, options);
+    validateDarkValue(options);
+    await assertTokenCategoryExists(engineDir, tokensCssPath, options.category);
+}
+/**
+ * Adds a design token to the CSS file and documentation.
+ *
+ * @param root - Project root directory
+ * @param options - Token options
+ * @returns Result of the operation
+ */
+export async function addToken(root, options) {
+    const { engineDir, tokensCssPath } = await resolveTokenAddContext(root);
+    validateTokenNameSyntax(options.tokenName);
+    await validateTokenPrefix(root, options);
+    validateDarkValue(options);
+    if (options.dryRun) {
+        await validateTokenAdd(root, options);
+        const filePath = join(engineDir, tokensCssPath);
+        const content = await readText(filePath);
+        const stripped = content.replace(/\/\*[\s\S]*?\*\//g, '');
+        const skipped = stripped.includes(options.tokenName + ':');
+        return {
+            cssAdded: !skipped,
+            docsAdded: !skipped,
+            unmappedAdded: !skipped && !options.value.startsWith('var('),
+            countUpdated: !skipped,
+            skipped,
+        };
+    }
+    // --- CSS file ---
+    const cssAdded = await addTokenToCSS(engineDir, options, tokensCssPath);
+    if (!cssAdded) {
+        return {
+            cssAdded: false,
+            docsAdded: false,
+            unmappedAdded: false,
+            countUpdated: false,
+            skipped: true,
+        };
+    }
+    // --- Documentation ---
+    const docsResult = await addTokenToDocs(engineDir, options);
+    return {
+        cssAdded,
+        docsAdded: docsResult.docsAdded,
+        unmappedAdded: docsResult.unmappedAdded,
+        countUpdated: docsResult.countUpdated,
+        skipped: false,
+    };
+}
+function findCategorySection(lines, category, tokensCssPath) {
+    const escapedCategory = escapeRegex(category);
+    const singleLinePattern = new RegExp(`\\/\\*\\s*=.*${escapedCategory}.*=\\s*\\*\\/`);
+    let categoryLine = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        // Check single-line format: /* = Category = */
+        if (singleLinePattern.test(line)) {
+            categoryLine = i;
+            break;
+        }
+        // Check multi-line format: line opens a block comment with === but does NOT close it
+        // e.g., "/* ================================================================"
+        // (NOT "/* ================================================= */" which closes on the same line)
+        if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
+            // Look ahead within the comment block (up to 5 lines) for the category text
+            for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
+                const blockLine = lines[j] ?? '';
+                if (new RegExp(escapedCategory).test(blockLine)) {
+                    categoryLine = i;
+                    break;
+                }
+                // Stop if we've exited the comment block
+                if (/\*\//.test(blockLine))
+                    break;
+            }
+            if (categoryLine !== -1)
+                break;
+        }
+    }
+    if (categoryLine === -1) {
+        throw new GeneralError(`Category "${category}" not found in ${tokensCssPath}. ` +
+            'Available categories are defined by /* =... category ...= */ comment headers.');
+    }
+    // Find the end of this category section (next section header or closing })
+    // Handles both single-line (/* =...= */) and multi-line (/* ===...) section delimiters
+    // Skip past the current header block first
+    let scanStart = categoryLine + 1;
+    for (let i = categoryLine + 1; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        // Skip lines that are part of the current header comment block
+        if (/^\s*\/\*\s*=/.test(line) || /^\s*\*\s*=/.test(line) || /^\s*\*\//.test(line)) {
+            scanStart = i + 1;
+            continue;
+        }
+        break;
+    }
+    let sectionEnd = lines.length;
+    for (let i = scanStart; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (/\/\*\s*=.*=\s*\*\//.test(line) ||
+            (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) ||
+            /^\s*\}/.test(line)) {
+            sectionEnd = i;
+            break;
+        }
+    }
+    return { categoryLine, sectionEnd };
+}
+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)
+        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);
+}
+/**
+ * Adds a token declaration to the CSS file in the correct category section.
+ */
+async function addTokenToCSS(engineDir, options, tokensCssPath) {
+    const filePath = join(engineDir, tokensCssPath);
+    await assertTokenCategoryExists(engineDir, tokensCssPath, options.category);
+    let content = await readText(filePath);
+    // Idempotency check — strip CSS block comments so we don't match inside them
+    const stripped = content.replace(/\/\*[\s\S]*?\*\//g, '');
+    if (stripped.includes(options.tokenName + ':')) {
+        return false;
+    }
+    const lines = content.split('\n');
+    const annotation = getModeAnnotation(options.mode, options.value);
+    const { categoryLine, sectionEnd } = findCategorySection(lines, options.category, tokensCssPath);
+    // Build the insertion lines
+    const insertLines = [];
+    if (options.description) {
+        insertLines.push(`  /* ${options.description} */`);
+    }
+    insertLines.push(`  ${options.tokenName}: ${options.value}; /* ${annotation} */`);
+    // Insert before the section end (before next header or closing brace)
+    // Find last non-blank line in the section to insert after it
+    let insertIndex = sectionEnd;
+    for (let i = sectionEnd - 1; i > categoryLine; i--) {
+        if ((lines[i] ?? '').trim()) {
+            insertIndex = i + 1;
+            break;
+        }
+    }
+    lines.splice(insertIndex, 0, ...insertLines);
+    insertDarkModeOverride(lines, options);
+    content = lines.join('\n');
+    await writeText(filePath, content);
+    return true;
+}
+/**
+ * Adds a token to the documentation markdown file.
+ */
+async function addTokenToDocs(engineDir, options) {
+    const filePath = join(engineDir, '..', TOKENS_DOC);
+    if (!(await pathExists(filePath))) {
+        // Docs file is optional
+        return { docsAdded: false, unmappedAdded: false, countUpdated: false };
+    }
+    let content = await readText(filePath);
+    const lines = content.split('\n');
+    let docsAdded = false;
+    let unmappedAdded = false;
+    let countUpdated = false;
+    const annotation = getModeAnnotation(options.mode, options.value);
+    const isLiteral = !options.value.startsWith('var(');
+    // Find the category group in the token table
+    // Look for a row containing the category name, then find the last row in that group
+    let categoryRowStart = -1;
+    let lastRowInCategory = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        // Table rows start with |
+        if (line.startsWith('|') && line.includes(options.category)) {
+            categoryRowStart = i;
+            lastRowInCategory = i;
+        }
+        else if (categoryRowStart !== -1 &&
+            line.startsWith('|') &&
+            !line.startsWith('|--') &&
+            !line.startsWith('| Token')) {
+            // Check if this row still belongs to the same category (no category cell or empty category)
+            const cells = line.split('|').map((c) => c.trim());
+            // If the first data cell (after leading empty) is empty, it belongs to same category
+            if (cells[1] === '' || !cells[1]) {
+                lastRowInCategory = i;
+            }
+            else {
+                break;
+            }
+        }
+        else if (categoryRowStart !== -1 && !line.startsWith('|')) {
+            break;
+        }
+    }
+    if (lastRowInCategory !== -1) {
+        // Insert a new row after the last row in this category
+        const mapsTo = isLiteral ? '—' : options.value.replace(/var\(([^)]+)\)/, '$1');
+        const newRow = `| | \`${options.tokenName}\` | \`${options.value}\` | ${mapsTo} | ${annotation} |`;
+        lines.splice(lastRowInCategory + 1, 0, newRow);
+        docsAdded = true;
+    }
+    // If the value is a literal (not a var() reference), add to unmapped table
+    if (isLiteral) {
+        let unmappedTableStart = -1;
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i] ?? '';
+            if (/not yet mapped/i.test(line) || /unmapped/i.test(line)) {
+                unmappedTableStart = i;
+                break;
+            }
+        }
+        if (unmappedTableStart !== -1) {
+            // Find the last row of the unmapped table
+            let lastUnmappedRow = unmappedTableStart;
+            for (let i = unmappedTableStart + 1; i < lines.length; i++) {
+                const line = lines[i] ?? '';
+                if (line.startsWith('|') && !line.startsWith('|--') && !line.startsWith('| Token')) {
+                    lastUnmappedRow = i;
+                }
+                else if (!line.startsWith('|')) {
+                    break;
+                }
+            }
+            const unmappedRow = `| \`${options.tokenName}\` | \`${options.value}\` | ${options.description ?? ''} |`;
+            lines.splice(lastUnmappedRow + 1, 0, unmappedRow);
+            unmappedAdded = true;
+        }
+    }
+    // Update dark/light mode behavior count table
+    const modeCountPattern = new RegExp(`\\|\\s*${options.mode}\\s*\\|\\s*(\\d+)\\s*\\|`);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        const match = modeCountPattern.exec(line);
+        if (match) {
+            const oldCount = parseInt(match[1] ?? '0', 10);
+            lines[i] = line.replace(modeCountPattern, `| ${options.mode} | ${oldCount + 1} |`);
+            countUpdated = true;
+            break;
+        }
+    }
+    content = lines.join('\n');
+    await writeText(filePath, content);
+    return { docsAdded, unmappedAdded, countUpdated };
+}
+//# sourceMappingURL=token-manager.js.map

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

@@ -0,0 +1,21 @@
+/**
+ * browser-init.js — destroy expression in onUnload()/uninit().
+ */
+/**
+ * AST-based implementation: finds onUnload()/uninit() method body and
+ * inserts the destroy block at the top (LIFO ordering).
+ */
+export declare function addDestroyAST(content: string, expression: string): string;
+/**
+ * Legacy regex/line-based implementation preserved as fallback.
+ */
+export declare function legacyAddDestroy(content: string, expression: string): string;
+/**
+ * Adds a destroy expression to the top of onUnload() or uninit() in
+ * browser-init.js (LIFO ordering — newest first).
+ *
+ * @param engineDir - Engine source root
+ * @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>;