@hominis/fireforge 0.49.2 → 0.51.0

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

@@ -0,0 +1,53 @@
+/**
+ * `fireforge token lint`: structural checks over the design-token system.
+ *
+ * - `token-lockstep`: a themed override block (the dark `@media` mirror, a
+ *   `:root[variant]` block) declares only tokens the base `:root` declares.
+ *   An override with no base is a token that exists only in one theme, so
+ *   every other theme resolves it to nothing.
+ * - `token-undeclared`: a `var(--<prefix>…)` reference in the tokens CSS or
+ *   in a CSS file the patch queue touches names a token no block of the
+ *   tokens CSS declares. Same-file declarations, declarations of a sheet
+ *   that loads beside it (see `token-sibling-sheets.ts`), `furnace.json`
+ *   `tokenAllowlist` and `runtimeVariables` are exempt, matching the
+ *   `token-prefix-violation` rule's notion of a runtime channel. A
+ *   reference with a fallback (`var(--x, 0)`) is optional by construction
+ *   (a host hook, a channel set from JS) and is not reported.
+ *
+ * Built on `token-category.ts`'s base-block and comment-mask primitives, so
+ * this report and `token add` agree on which block is the base.
+ */
+/** One `token lint` finding. */
+export interface TokenLintFinding {
+    check: 'token-lockstep' | 'token-undeclared';
+    /** Engine-relative file. */
+    file: string;
+    /** 1-based line. */
+    line: number;
+    /** The custom property at fault. */
+    token: string;
+    message: string;
+}
+/** Every custom property the tokens CSS declares, in any block. */
+export declare function collectDeclaredTokenNames(lines: string[]): Set<string>;
+/**
+ * Themed override declarations of `tokenPrefix` tokens that the base
+ * `:root` block does not declare.
+ *
+ * @param lines - Tokens CSS split into lines
+ * @param tokensCssPath - Engine-relative path, for the findings
+ * @param tokenPrefix - Only tokens with this prefix are held to lockstep;
+ *   a themed block may still override platform properties
+ */
+export declare function lintTokenLockstep(lines: string[], tokensCssPath: string, tokenPrefix: string): TokenLintFinding[];
+/**
+ * `var(--<prefix>…)` references naming a token the tokens CSS never
+ * declares.
+ *
+ * @param file - Engine-relative path, for the findings
+ * @param css - The file's content
+ * @param tokenPrefix - Only references with this prefix are checked
+ * @param declared - {@link collectDeclaredTokenNames} of the tokens CSS
+ * @param exempt - `tokenAllowlist` and `runtimeVariables` names
+ */
+export declare function lintUndeclaredTokenReferences(file: string, css: string, tokenPrefix: string, declared: ReadonlySet<string>, exempt: ReadonlySet<string>): TokenLintFinding[];

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

@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * `fireforge token lint`: structural checks over the design-token system.
+ *
+ * - `token-lockstep`: a themed override block (the dark `@media` mirror, a
+ *   `:root[variant]` block) declares only tokens the base `:root` declares.
+ *   An override with no base is a token that exists only in one theme, so
+ *   every other theme resolves it to nothing.
+ * - `token-undeclared`: a `var(--<prefix>…)` reference in the tokens CSS or
+ *   in a CSS file the patch queue touches names a token no block of the
+ *   tokens CSS declares. Same-file declarations, declarations of a sheet
+ *   that loads beside it (see `token-sibling-sheets.ts`), `furnace.json`
+ *   `tokenAllowlist` and `runtimeVariables` are exempt, matching the
+ *   `token-prefix-violation` rule's notion of a runtime channel. A
+ *   reference with a fallback (`var(--x, 0)`) is optional by construction
+ *   (a host hook, a channel set from JS) and is not reported.
+ *
+ * Built on `token-category.ts`'s base-block and comment-mask primitives, so
+ * this report and `token add` agree on which block is the base.
+ */
+import { findBaseRootBounds, maskCommentLines } from './token-category.js';
+const DECLARATION = /(?:^|[{;\s])(--[A-Za-z0-9_-]+)\s*:/g;
+function selectorBefore(text) {
+    const selector = text.slice(Math.max(text.lastIndexOf('}'), text.lastIndexOf(';')) + 1).trim();
+    return selector.length > 0 ? selector.replace(/\s+/g, ' ') : '(block)';
+}
+/**
+ * Every custom-property declaration in a CSS file with the selector trail
+ * of the block holding it, outermost first, joined with ` > `.
+ */
+function collectDeclarations(lines) {
+    const masked = maskCommentLines(lines);
+    const trail = [];
+    const found = [];
+    let pending = '';
+    for (const [index, line] of masked.entries()) {
+        for (const match of line.matchAll(DECLARATION)) {
+            found.push({
+                name: match[1] ?? '',
+                line: index + 1,
+                block: trail.length > 0 ? trail.join(' > ') : '(file scope)',
+            });
+        }
+        for (const char of line) {
+            if (char === '{') {
+                trail.push(selectorBefore(pending));
+                pending = '';
+            }
+            else if (char === '}') {
+                trail.pop();
+                pending = '';
+            }
+            else {
+                pending += char;
+            }
+        }
+        pending += '\n';
+    }
+    return found;
+}
+/** Every custom property the tokens CSS declares, in any block. */
+export function collectDeclaredTokenNames(lines) {
+    return new Set(collectDeclarations(lines).map((declaration) => declaration.name));
+}
+/**
+ * Themed override declarations of `tokenPrefix` tokens that the base
+ * `:root` block does not declare.
+ *
+ * @param lines - Tokens CSS split into lines
+ * @param tokensCssPath - Engine-relative path, for the findings
+ * @param tokenPrefix - Only tokens with this prefix are held to lockstep;
+ *   a themed block may still override platform properties
+ */
+export function lintTokenLockstep(lines, tokensCssPath, tokenPrefix) {
+    const bounds = findBaseRootBounds(lines);
+    if (bounds === undefined)
+        return [];
+    const close = bounds.close === -1 ? lines.length : bounds.close;
+    const declarations = collectDeclarations(lines);
+    const inBase = (line) => line - 1 >= bounds.open && line - 1 <= close;
+    const base = new Set(declarations.filter((d) => inBase(d.line)).map((d) => d.name));
+    return declarations
+        .filter((d) => !inBase(d.line) && d.name.startsWith(tokenPrefix) && !base.has(d.name))
+        .map((d) => ({
+        check: 'token-lockstep',
+        file: tokensCssPath,
+        line: d.line,
+        token: d.name,
+        message: `${d.name} is declared in ${d.block} but not in the base :root block, so every other ` +
+            'theme resolves it to nothing. Declare the base value first (fireforge token add), ' +
+            'or drop the override.',
+    }));
+}
+/**
+ * `var(--<prefix>…)` references naming a token the tokens CSS never
+ * declares.
+ *
+ * @param file - Engine-relative path, for the findings
+ * @param css - The file's content
+ * @param tokenPrefix - Only references with this prefix are checked
+ * @param declared - {@link collectDeclaredTokenNames} of the tokens CSS
+ * @param exempt - `tokenAllowlist` and `runtimeVariables` names
+ */
+export function lintUndeclaredTokenReferences(file, css, tokenPrefix, declared, exempt) {
+    const lines = css.split('\n');
+    const local = collectDeclaredTokenNames(lines);
+    const findings = [];
+    const seen = new Set();
+    for (const [index, line] of maskCommentLines(lines).entries()) {
+        for (const match of line.matchAll(/var\(\s*(--[A-Za-z0-9_-]+)\s*(,)?/g)) {
+            const name = match[1] ?? '';
+            if (match[2] !== undefined)
+                continue;
+            if (!name.startsWith(tokenPrefix) || declared.has(name) || local.has(name))
+                continue;
+            if (exempt.has(name) || seen.has(name))
+                continue;
+            seen.add(name);
+            findings.push({
+                check: 'token-undeclared',
+                file,
+                line: index + 1,
+                token: name,
+                message: `var(${name}) names a token the tokens CSS does not declare, so it resolves to ` +
+                    'nothing. Add the token, fix the name, or list a runtime channel in furnace.json ' +
+                    'runtimeVariables.',
+            });
+        }
+    }
+    return findings;
+}

package/dist/src/core/token-sibling-sheets.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Which stylesheets load together, so `token lint` can resolve a token one
+ * sheet references against the declarations of the sheets beside it.
+ *
+ * A widget sheet may read a token its host document's other sheet
+ * declares; judged alone it looks undeclared. Two sources say which sheets
+ * share a document:
+ *
+ * - links the queue's documents make: `<link rel="stylesheet">` (and
+ *   `<html:link>`) and `<?xml-stylesheet?>` in markup and Lit templates,
+ *   and CSS `@import`. A `chrome://` URL resolves through the jar.mn lines
+ *   the queue adds; a relative URL resolves beside the document, and only
+ *   to a sheet the queue touches.
+ * - `furnace.json#tokenSiblingSheets`: `{ "<glob>": ["<path or glob>"] }`,
+ *   for pairings no link in the queue shows (an upstream host document).
+ *
+ * Sheets linked from one document are siblings of each other; an
+ * `@import` makes the importing and the imported sheet siblings.
+ */
+/** The stylesheet URLs one document or sheet loads, in order. */
+export declare function collectStylesheetUrls(file: string, content: string): string[];
+/**
+ * Resolves a stylesheet URL to an engine-relative path, or undefined.
+ *
+ * @param url - The URL as written
+ * @param from - Engine-relative path of the document or sheet holding it
+ * @param jarTargets - jar target (`content/<pkg>/<path>`) → packaged source
+ * @param knownSheets - Sheets a relative URL may resolve to
+ */
+export declare function resolveStylesheetUrl(url: string, from: string, jarTargets: ReadonlyMap<string, string>, knownSheets: ReadonlySet<string>): string | undefined;
+/** Inputs of {@link buildSiblingSheetMap}. */
+export interface SiblingSheetInputs {
+    /** Documents and sheets to read links from: engine-relative path and content. */
+    documents: Iterable<readonly [string, string]>;
+    /** jar target → packaged source, from the queue's jar.mn lines. */
+    jarTargets: ReadonlyMap<string, string>;
+    /** The sheets `token lint` judges. */
+    sheets: readonly string[];
+    /** `furnace.json#tokenSiblingSheets`. */
+    explicit?: Readonly<Record<string, readonly string[]>> | undefined;
+}
+/**
+ * Maps each sheet to the other sheets that load beside it. A sheet with no
+ * siblings is absent.
+ */
+export declare function buildSiblingSheetMap(inputs: SiblingSheetInputs): Map<string, Set<string>>;

package/dist/src/core/token-sibling-sheets.js

@@ -0,0 +1,119 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Which stylesheets load together, so `token lint` can resolve a token one
+ * sheet references against the declarations of the sheets beside it.
+ *
+ * A widget sheet may read a token its host document's other sheet
+ * declares; judged alone it looks undeclared. Two sources say which sheets
+ * share a document:
+ *
+ * - links the queue's documents make: `<link rel="stylesheet">` (and
+ *   `<html:link>`) and `<?xml-stylesheet?>` in markup and Lit templates,
+ *   and CSS `@import`. A `chrome://` URL resolves through the jar.mn lines
+ *   the queue adds; a relative URL resolves beside the document, and only
+ *   to a sheet the queue touches.
+ * - `furnace.json#tokenSiblingSheets`: `{ "<glob>": ["<path or glob>"] }`,
+ *   for pairings no link in the queue shows (an upstream host document).
+ *
+ * Sheets linked from one document are siblings of each other; an
+ * `@import` makes the importing and the imported sheet siblings.
+ */
+import { dirname, posix } from 'node:path';
+import { matchesAnyGlob } from '../utils/path-glob.js';
+import { normalizePathSlashes } from '../utils/paths.js';
+const LINK_TAG = /<(?:html:)?link\b[^>]*>/gi;
+const STYLESHEET_PI = /<\?xml-stylesheet\b[^?]*?href\s*=\s*["']([^"']+)["']/gi;
+const CSS_IMPORT = /@import\s+(?:url\(\s*)?["']([^"']+)["']/gi;
+/** The stylesheet URLs one document or sheet loads, in order. */
+export function collectStylesheetUrls(file, content) {
+    const urls = [];
+    if (file.endsWith('.css')) {
+        for (const match of content.matchAll(CSS_IMPORT))
+            urls.push(match[1] ?? '');
+        return urls.filter((url) => url !== '');
+    }
+    for (const match of content.matchAll(LINK_TAG)) {
+        const tag = match[0];
+        if (!/\brel\s*=\s*["']stylesheet["']/i.test(tag))
+            continue;
+        const href = /\bhref\s*=\s*["']([^"'$]+)["']/i.exec(tag)?.[1];
+        if (href !== undefined)
+            urls.push(href);
+    }
+    for (const match of content.matchAll(STYLESHEET_PI))
+        urls.push(match[1] ?? '');
+    return urls.filter((url) => url.endsWith('.css'));
+}
+/**
+ * Resolves a stylesheet URL to an engine-relative path, or undefined.
+ *
+ * @param url - The URL as written
+ * @param from - Engine-relative path of the document or sheet holding it
+ * @param jarTargets - jar target (`content/<pkg>/<path>`) → packaged source
+ * @param knownSheets - Sheets a relative URL may resolve to
+ */
+export function resolveStylesheetUrl(url, from, jarTargets, knownSheets) {
+    const chrome = /^chrome:\/\/([\w.-]+)\/(content|skin|locale)\/(.+)$/.exec(url);
+    if (chrome !== null) {
+        const [, pkg = '', kind = '', path = ''] = chrome;
+        const candidates = kind === 'skin'
+            ? [`skin/classic/${pkg}/${path}`, `skin/${pkg}/${path}`]
+            : [`${kind}/${pkg}/${path}`];
+        for (const target of candidates) {
+            const source = jarTargets.get(target);
+            if (source !== undefined)
+                return source;
+        }
+        return undefined;
+    }
+    if (/^[a-z][\w+.-]*:/i.test(url))
+        return undefined;
+    const base = normalizePathSlashes(dirname(from));
+    const resolved = posix.normalize(posix.join(base === '.' ? '' : base, url));
+    return knownSheets.has(resolved) ? resolved : undefined;
+}
+/**
+ * Maps each sheet to the other sheets that load beside it. A sheet with no
+ * siblings is absent.
+ */
+export function buildSiblingSheetMap(inputs) {
+    const known = new Set(inputs.sheets);
+    const siblings = new Map();
+    const link = (group) => {
+        for (const sheet of group) {
+            const set = siblings.get(sheet) ?? new Set();
+            for (const other of group)
+                if (other !== sheet)
+                    set.add(other);
+            if (set.size > 0)
+                siblings.set(sheet, set);
+        }
+    };
+    for (const [file, content] of inputs.documents) {
+        const linked = collectStylesheetUrls(file, content)
+            .map((url) => resolveStylesheetUrl(url, file, inputs.jarTargets, known))
+            .filter((sheet) => sheet !== undefined);
+        // An @import pairs the importing sheet with what it imports.
+        link(file.endsWith('.css') ? [file, ...linked] : linked);
+    }
+    for (const [pattern, partners] of Object.entries(inputs.explicit ?? {})) {
+        const owners = inputs.sheets.filter((sheet) => matchesAnyGlob(sheet, [pattern]));
+        for (const owner of owners) {
+            const set = siblings.get(owner) ?? new Set();
+            for (const partner of partners) {
+                if (/[*?]/.test(partner)) {
+                    for (const sheet of inputs.sheets) {
+                        if (sheet !== owner && matchesAnyGlob(sheet, [partner]))
+                            set.add(sheet);
+                    }
+                }
+                else if (partner !== owner) {
+                    set.add(partner);
+                }
+            }
+            if (set.size > 0)
+                siblings.set(owner, set);
+        }
+    }
+    return siblings;
+}

package/dist/src/core/tree-guard.js

@@ -36,6 +36,8 @@ export const TREE_COMMAND_VERDICTS = {
     export: 'conditional',
     'export-all': 'conditional',
     're-export': 'conditional',
+    // Parks live in the primary tree's .fireforge/ and rewrite engine files.
+    park: 'refused',
     patch: 'refused',
     rebase: 'refused',
     package: 'refused',
@@ -51,6 +53,9 @@ export const TREE_COMMAND_VERDICTS = {
     lint: 'allowed',
     typecheck: 'allowed',
     verify: 'allowed',
+    // Its furnace-validate and token-coverage steps are commands a tree
+    // refuses. Run the allowed gates one by one in a tree.
+    check: 'refused',
     furnace: 'refused',
     // No nesting. `tree list` inside a tree is pointless but harmless, and
     // the subcommand check below allows only `list`.

package/dist/src/core/typecheck-shim.d.ts

@@ -24,7 +24,7 @@ export declare const SHIM_FILENAME = "__fireforge_firefox_globals.d.ts";
  * `declare var` redeclarations to the first declaration, the typed
  * consumer declaration wins over the loose fallback here.
  */
-export declare const TEST_HARNESS_SHIM = "\n// \u2500\u2500 FireForge test-harness shim (loose baseline) \u2500\u2500\ndeclare var TestUtils: any;\ndeclare var BrowserTestUtils: any;\ndeclare var SpecialPowers: any;\ndeclare var EventUtils: any;\ndeclare var SimpleTest: any;\ndeclare var Assert: any;\ndeclare var gTestPath: string;\ndeclare var content: any;\ndeclare function add_task(task: (...args: any[]) => any): any;\ndeclare function add_setup(task: (...args: any[]) => any): any;\ndeclare function ok(condition: any, message?: string): void;\ndeclare function is(actual: any, expected: any, message?: string): void;\ndeclare function isnot(actual: any, expected: any, message?: string): void;\ndeclare function todo(condition: any, message?: string): void;\ndeclare function todo_is(actual: any, expected: any, message?: string): void;\ndeclare function info(message: string): void;\ndeclare function registerCleanupFunction(callback: (...args: any[]) => any): void;\ndeclare function waitForExplicitFinish(): void;\ndeclare function finish(): void;\ndeclare function do_get_profile(): any;\ndeclare function run_test(): any;\n\n";
+export declare const TEST_HARNESS_SHIM = "\n// \u2500\u2500 FireForge test-harness shim (loose baseline) \u2500\u2500\ndeclare var TestUtils: any;\ndeclare var BrowserTestUtils: any;\ndeclare var SpecialPowers: any;\ndeclare var EventUtils: any;\ndeclare var SimpleTest: any;\ndeclare var Assert: any;\ndeclare var gTestPath: string;\ndeclare var content: any;\ndeclare function add_task(task: (...args: any[]) => any): any;\ndeclare function add_setup(task: (...args: any[]) => any): any;\ndeclare function ok(condition: any, message?: string): void;\ndeclare function is(actual: any, expected: any, message?: string): void;\ndeclare function isnot(actual: any, expected: any, message?: string): void;\ndeclare function todo(condition: any, message?: string): void;\ndeclare function todo_is(actual: any, expected: any, message?: string): void;\ndeclare function todo_isnot(actual: any, expected: any, message?: string): void;\ndeclare function info(message: string): void;\ndeclare function registerCleanupFunction(callback: (...args: any[]) => any): void;\ndeclare function waitForExplicitFinish(): void;\ndeclare function finish(): void;\ndeclare function do_get_profile(): any;\ndeclare function run_test(): any;\n\n";
 /**
  * TS diagnostic codes suppressed by both the patch-lint checkJs pass
  * and the whole-project typecheck command. Each is a known false
@@ -81,5 +81,9 @@ export interface ComposedShim {
  * @param projectRoot - Absolute project root, used to resolve the relative
  *   shim path
  * @param extraShimPath - Optional project-relative path to an extra `.d.ts`
+ * @param options - `litTypes` appends {@link LIT_TYPES_SHIM} after the
+ *   built-in shim (before the extra shim, which can still merge into it)
  */
-export declare function composeShimSource(projectRoot: string, extraShimPath: string | undefined): Promise<ComposedShim>;
+export declare function composeShimSource(projectRoot: string, extraShimPath: string | undefined, options?: {
+    litTypes?: boolean | undefined;
+}): Promise<ComposedShim>;

package/dist/src/core/typecheck-shim.js

@@ -43,7 +43,9 @@ export const SHIM_FILENAME = '__fireforge_firefox_globals.d.ts';
  * - `const lazy = {};` + `ChromeUtils.defineESModuleGetters(lazy, { ... })`
  *   populates `lazy` at runtime, so we declare it as `Record<string, any>`.
  * - `Services.obs`, `Services.prefs`, etc. are XPCOM service accessors.
- * - `Ci`, `Cc`, `Cr`, `Cu` are XPCOM component shortcuts.
+ * - `Ci`, `Cc`, `Cr`, `Cu` are XPCOM component shortcuts. `Cu` alone is
+ *   typed (`CuShim`, the members of `nsIXPCComponents_Utils`), so an
+ *   unknown `Cu.*` member is an error rather than a runtime TypeError.
  * - Browser chrome globals like `gBrowser`, `gURLBar` are common in
  *   content scripts wired via `browser.js`.
  * - Dynamic `import("resource:-…")` / `import("chrome:-…")` under patch
@@ -72,7 +74,92 @@ interface ChromeUtilsShim {
   predictRemoteTypeForURI(uri: string | object | null, options?: object): string | null;
 }
 declare var ChromeUtils: ChromeUtilsShim;
-declare var Cu: any;
+// Components.utils (js/xpconnect/idl/xpccomponents.idl, nsIXPCComponents_Utils,
+// Firefox 153). Every member is listed with loose (any) jsval parameters and
+// results, so Xray-waived and cloned objects keep their expandos, but the
+// member set is closed: a call to a member Cu does not have (Cu.now() is
+// ChromeUtils.now()) is a typecheck error instead of a runtime TypeError.
+// Extensible via interface merging, same as ChromeUtilsShim.
+interface CuShim {
+  QueryInterface(iid: any): any;
+  printStderr(message: string): void;
+  reportError(error: any, stack?: any): void;
+  readonly Sandbox: { new (principal: any, options?: any): any; (principal: any, options?: any): any };
+  evalInSandbox(
+    source: string,
+    sandbox: any,
+    version?: any,
+    filename?: string,
+    lineNo?: number,
+    enforceFilenameRestrictions?: boolean
+  ): any;
+  getUAWidgetScope(principal: any): any;
+  getSandboxMetadata(sandbox: any): any;
+  setSandboxMetadata(sandbox: any, metadata: any): void;
+  setSandboxLocaleOverride(sandbox: any, locale: string): void;
+  setSandboxTimezoneOverride(sandbox: any, timezone: string): void;
+  isESModuleLoaded(resourceURI: string): boolean;
+  importGlobalProperties(propertyList: any): void;
+  getWeakReference(obj: any): { get(): any };
+  forceGC(): void;
+  forceCC(listener?: any): void;
+  createCCLogger(): any;
+  finishCC(): void;
+  ccSlice(budget: number): void;
+  getMaxCCSliceTimeSinceClear(): number;
+  clearMaxCCTime(): void;
+  forceShrinkingGC(): void;
+  schedulePreciseGC(callback: any): void;
+  schedulePreciseShrinkingGC(callback: any): void;
+  unlinkGhostWindows(): void;
+  intentionallyLeak(): void;
+  getJSTestingFunctions(): any;
+  getFunctionSourceLocation(func: any): any;
+  callFunctionWithAsyncStack(func: any, stack: any, asyncCause: string): any;
+  getGlobalForObject(obj: any): any;
+  isProxy(obj: any): boolean;
+  exportFunction(func: any, scope: any, options?: any): any;
+  createObjectIn(scope: any, options?: any): any;
+  makeObjectPropsNormal(obj: any): void;
+  isDeadWrapper(obj: any): boolean;
+  isRemoteProxy(val: any): boolean;
+  recomputeWrappers(obj?: any): void;
+  setWantXrays(scope: any): void;
+  dispatch(runnable: any, scope?: any): void;
+  readonly isInAutomation: boolean;
+  exitIfInAutomation(): void;
+  crashIfNotInAutomation(): void;
+  setGCZeal(zeal: number): void;
+  nukeSandbox(obj: any): void;
+  blockScriptForGlobal(global: any): void;
+  unblockScriptForGlobal(global: any): void;
+  isOpaqueWrapper(obj: any): boolean;
+  isXrayWrapper(obj: any): boolean;
+  waiveXrays(val: any): any;
+  unwaiveXrays(val: any): any;
+  getClassName(obj: any, unwrap: boolean): string;
+  getIncumbentGlobal(callback?: any): any;
+  getDebugName(obj: any): string;
+  getWatchdogTimestamp(category: string): number;
+  getJSEngineTelemetryValue(): any;
+  cloneInto(value: any, scope: any, options?: any): any;
+  getWebIDLCallerPrincipal(): any;
+  getObjectPrincipal(obj: any): any;
+  getRealmLocation(obj: any): string;
+  readUTF8File(file: any): string;
+  readUTF8URI(url: any): string;
+  createSpellChecker(): any;
+  createCommandLine(args: string[], workingDir: any, state: number): any;
+  createCommandParams(): any;
+  createLoadContext(): any;
+  createPrivateLoadContext(): any;
+  createPersistentProperties(): any;
+  createDocumentEncoder(contentType: string): any;
+  createHTMLCopyEncoder(): any;
+  readonly loadedESModules: string[];
+  getModuleImportStack(location: string): string;
+}
+declare var Cu: CuShim;
 declare var Ci: any;
 declare var Cc: any;
 declare var Cr: any;
@@ -159,6 +246,7 @@ declare function is(actual: any, expected: any, message?: string): void;
 declare function isnot(actual: any, expected: any, message?: string): void;
 declare function todo(condition: any, message?: string): void;
 declare function todo_is(actual: any, expected: any, message?: string): void;
+declare function todo_isnot(actual: any, expected: any, message?: string): void;
 declare function info(message: string): void;
 declare function registerCleanupFunction(callback: (...args: any[]) => any): void;
 declare function waitForExplicitFinish(): void;
@@ -201,6 +289,117 @@ export const UNDEFINED_IDENTIFIER_CODES = new Set([
     2304, // Cannot find name '{0}'.
     2552, // Cannot find name '{0}'. Did you mean '{1}'?
 ]);
+/**
+ * Typed Lit, opt-in through `typecheck.litTypes`. Declares the two chrome
+ * modules widgets import Lit from, so they no longer fall to the
+ * `chrome:*` wildcard as `any`: `LitElement` (with `ReactiveElement`'s
+ * lifecycle) and `MozLitElement` carry closed member lists, so a misspelt
+ * member of a widget host is TS2339, as `Cu` is in the built-in shim.
+ * Template helpers and directives stay loose. A project shim can merge
+ * members into `LitElementShimMembers`; a project whose jsconfig `paths`
+ * maps these URLs to the real sources gets those instead, since a resolved
+ * file wins over an ambient module.
+ */
+const LIT_TYPES_SHIM = `
+// ── FireForge typed Lit (typecheck.litTypes) ──
+interface LitPropertyDeclarationShim {
+  type?: unknown;
+  attribute?: boolean | string;
+  reflect?: boolean;
+  state?: boolean;
+  noAccessor?: boolean;
+  converter?: unknown;
+  hasChanged?(value: unknown, oldValue: unknown): boolean;
+  fluent?: boolean;
+}
+interface LitElementShimMembers {
+  readonly renderRoot: HTMLElement | DocumentFragment;
+  readonly isUpdatePending: boolean;
+  readonly hasUpdated: boolean;
+  readonly updateComplete: Promise<boolean>;
+  renderOptions: any;
+  requestUpdate(name?: PropertyKey, oldValue?: unknown, options?: LitPropertyDeclarationShim): void;
+  addController(controller: any): void;
+  removeController(controller: any): void;
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  attributeChangedCallback(name: string, oldValue: string | null, value: string | null): void;
+  createRenderRoot(): HTMLElement | DocumentFragment;
+  enableUpdating(requestedUpdate: boolean): void;
+  scheduleUpdate(): void | Promise<unknown>;
+  performUpdate(): void;
+  getUpdateComplete(): Promise<boolean>;
+  shouldUpdate(changedProperties: Map<PropertyKey, unknown>): boolean;
+  willUpdate(changedProperties: Map<PropertyKey, unknown>): void;
+  update(changedProperties: Map<PropertyKey, unknown>): void;
+  render(): unknown;
+  firstUpdated(changedProperties: Map<PropertyKey, unknown>): void;
+  updated(changedProperties: Map<PropertyKey, unknown>): void;
+}
+declare module 'chrome://global/content/vendor/lit.all.mjs' {
+  export class ReactiveElement extends HTMLElement {
+    static properties: Record<string, LitPropertyDeclarationShim>;
+    static styles: any;
+    static shadowRootOptions: ShadowRootInit;
+    static readonly observedAttributes: string[];
+    static createProperty(name: PropertyKey, options?: LitPropertyDeclarationShim): void;
+    static addInitializer(initializer: (element: ReactiveElement) => void): void;
+  }
+  export interface ReactiveElement extends LitElementShimMembers {}
+  export class LitElement extends ReactiveElement {}
+  export const html: (strings: TemplateStringsArray, ...values: unknown[]) => any;
+  export const svg: (strings: TemplateStringsArray, ...values: unknown[]) => any;
+  export const css: (strings: TemplateStringsArray, ...values: unknown[]) => any;
+  export const nothing: any;
+  export const noChange: any;
+  export const render: any;
+  export const unsafeCSS: any;
+  export const classMap: any;
+  export const styleMap: any;
+  export const ifDefined: any;
+  export const repeat: any;
+  export const when: any;
+  export const map: any;
+  export const live: any;
+  export const ref: any;
+  export const createRef: any;
+  export const until: any;
+  export const guard: any;
+  export const choose: any;
+  export const keyed: any;
+  export const cache: any;
+  export const join: any;
+  export const range: any;
+  export const unsafeHTML: any;
+  export const unsafeSVG: any;
+  export const literal: any;
+  export const unsafeStatic: any;
+  export const staticHtml: any;
+  export const staticSvg: any;
+  export const directive: any;
+  export const Directive: any;
+  export const AsyncDirective: any;
+  export const PartType: any;
+  export const defaultConverter: any;
+  export const notEqual: any;
+  export const adoptStyles: any;
+  export const supportsAdoptingStyleSheets: boolean;
+  export const CSSResult: any;
+  export const isServer: boolean;
+}
+declare module 'chrome://global/content/lit-utils.mjs' {
+  import { LitElement } from 'chrome://global/content/vendor/lit.all.mjs';
+  export class MozLitElement extends LitElement {
+    static queries: Record<string, string | Record<string, unknown>>;
+    static fragment: unknown;
+    dispatchOnUpdateComplete(event: Event): Promise<void>;
+  }
+  export const MozBaseInputElement: any;
+  export const MozBoolInputElement: any;
+  export const SelectControlBaseElement: any;
+  export const SelectControlItemMixin: any;
+}
+`;
 /** Hint appended to reported undefined-identifier diagnostics. */
 export const UNDEFINED_IDENTIFIER_HINT = '(undefined identifier — import or declare it, add the global to the extra shim, ' +
     'or tune the "undefinedIdentifiers" setting)';
@@ -262,9 +461,11 @@ async function inlineTripleSlashReferences(source, baseDir, seen) {
  * @param projectRoot - Absolute project root, used to resolve the relative
  *   shim path
  * @param extraShimPath - Optional project-relative path to an extra `.d.ts`
+ * @param options - `litTypes` appends {@link LIT_TYPES_SHIM} after the
+ *   built-in shim (before the extra shim, which can still merge into it)
  */
-export async function composeShimSource(projectRoot, extraShimPath) {
-    const base = FIREFOX_GLOBALS_SHIM;
+export async function composeShimSource(projectRoot, extraShimPath, options = {}) {
+    const base = options.litTypes === true ? `${FIREFOX_GLOBALS_SHIM}\n${LIT_TYPES_SHIM}` : FIREFOX_GLOBALS_SHIM;
     if (!extraShimPath) {
         return { source: base, extraShimAppended: false };
     }

package/dist/src/core/typecheck.js

@@ -102,7 +102,9 @@ export async function runTypecheck(projectRoot, cfg, runOptions = {}) {
         const cached = shimCache.get(key);
         if (cached !== undefined)
             return cached;
-        const composed = await composeShimSource(projectRoot, extraShim);
+        const composed = await composeShimSource(projectRoot, extraShim, {
+            litTypes: cfg.litTypes,
+        });
         if (composed.extraShimAppended) {
             verbose(`typecheck: extra shim ${extraShim ?? ''} appended to Firefox globals shim`);
         }