typescript-to-gdscript 0.1.0

package/dist/typings/scenes.d.ts

@@ -0,0 +1,96 @@
+import { ProjectCache } from '../cache/index.ts';
+import { parseAutoloads, findSceneFiles, resolveSignalHandlers, collectAllSignalHandlers, type SignalHandlerInfo, type ScriptClassInfo, type AutoloadEntry } from './scene-utils.ts';
+export { parseAutoloads, resolveSignalHandlers, collectAllSignalHandlers, findSceneFiles };
+export type { SignalHandlerInfo, ScriptClassInfo, AutoloadEntry };
+export interface GenerateTypingsOptions {
+    /** Root directory of the project (base for res:// paths) */
+    rootDir: string;
+    /** TypeScript source directory */
+    tsDir: string;
+    /** GDScript output directory */
+    gdDir: string;
+    /** TS source files to scan for class declarations */
+    files: string[];
+    /** Output directory for per-file .d.ts typings */
+    outputDir: string;
+    /** @deprecated Use outputDir instead */
+    outputPath?: string;
+    /** Directory containing .tscn scene files */
+    scenesDir: string;
+    /** Path to tsconfig.json */
+    tsConfigPath?: string;
+    /** Glob patterns for files/folders to ignore */
+    ignore?: string[];
+    /** Path to project.godot file (for autoload singleton detection) */
+    projectFile?: string;
+    /** Path to godot-class-registry.json (for typed signal handler generation) */
+    registryPath?: string;
+    /** Optional cache instance for skipping unchanged typings */
+    cache?: ProjectCache;
+    /** Optional debug logger (e.g. for --debug CLI flag) */
+    onDebug?: (message: string) => void;
+    /** Absolute path to Godot engine typings (for /// reference in _index.d.ts) */
+    godotTypingsDir?: string;
+    /**
+     * When true, non-anonymous classes are emitted into `declare global`
+     * so consumers can use them without an explicit `import`. When false
+     * (the project default), the same classes are emitted as module-scoped
+     * declarations and consumers must import them — matching the
+     * anonymous-class pattern. Addons override this to true unconditionally.
+     */
+    generateGlobalClassTypes?: boolean;
+}
+/**
+ * Generates per-file .d.ts typings in outputDir:
+ * - Per-scene .tscn.d.ts files (scene tree interfaces, GodotResources, parent entries)
+ * - Per-script .gd.d.ts files (module augmentation, global class, GodotScripts)
+ * - Per-resource .d.ts files (GodotResources entries)
+ * - _index.d.ts (empty global interfaces, autoload singletons)
+ * Returns list of written file paths.
+ */
+export declare function generateTypings(options: GenerateTypingsOptions): string[];
+export interface GenerateFileTypingsOptions {
+    rootDir: string;
+    tsDir: string;
+    outputDir: string;
+    tsConfigPath?: string;
+    scenesDir?: string;
+    ignore?: string[];
+    projectFile?: string;
+    /** Optional cache instance for skipping unchanged typings */
+    cache?: ProjectCache;
+    /** Absolute path to Godot engine typings (for /// reference in _index.d.ts) */
+    godotTypingsDir?: string;
+    /** See `GenerateTypingsOptions.generateGlobalClassTypes`. */
+    generateGlobalClassTypes?: boolean;
+}
+/**
+ * Regenerate typings for specific changed files (incremental).
+ * Handles .ts, .tscn, .tres/.res, and project.godot files.
+ * All TS files must be passed for the TS program to resolve cross-references.
+ */
+export declare function generateFileTypings(changedFiles: string[], allTsFiles: string[], options: GenerateFileTypingsOptions): string[];
+export interface GenerateAddonTypingsOptions {
+    rootDir: string;
+    outputDir: string;
+    ignore?: string[];
+    registryPath?: string;
+    /** Optional cache instance for skipping unchanged addon files */
+    cache?: ProjectCache;
+    /** Optional debug logger (e.g. for --debug CLI flag) */
+    onDebug?: (message: string) => void;
+    /**
+     * Path to the project's tsconfig.json. Forwarded to the nullable helper so
+     * its TS program can resolve Godot typings — otherwise references to
+     * `Node`, `Resource`, etc. collapse to `any` and Phase C's TS2322 signal
+     * never fires for Godot-class returns in addon code.
+     */
+    tsConfigPath?: string;
+}
+/**
+ * Generate typings for GDScript addon files.
+ * Converts addon .gd -> .ts, writes to outputDir/addons/ preserving structure,
+ * then generates .gd.d.ts scene typings for each addon script.
+ */
+export declare function generateAddonTypings(options: GenerateAddonTypingsOptions): string[];
+//# sourceMappingURL=scenes.d.ts.map

package/dist/typings/scenes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenes.d.ts","sourceRoot":"","sources":["../../src/typings/scenes.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AASjD,OAAO,EAML,cAAc,EACd,cAAc,EAId,qBAAqB,EACrB,wBAAwB,EAExB,KAAK,iBAAiB,EACtB,KAAK,eAAe,EACpB,KAAK,aAAa,EACnB,MAAM,kBAAkB,CAAC;AAI1B,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,wBAAwB,EAAE,cAAc,EAAE,CAAC;AAC3F,YAAY,EAAE,iBAAiB,EAAE,eAAe,EAAE,aAAa,EAAE,CAAC;AAIlE,MAAM,WAAW,sBAAsB;IACrC,4DAA4D;IAC5D,OAAO,EAAE,MAAM,CAAC;IAChB,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,gCAAgC;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,kDAAkD;IAClD,SAAS,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,SAAS,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,oEAAoE;IACpE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8EAA8E;IAC9E,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,wDAAwD;IACxD,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC,+EAA+E;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;;OAMG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,MAAM,EAAE,CAgKzE;AAID,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,+EAA+E;IAC/E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,6DAA6D;IAC7D,wBAAwB,CAAC,EAAE,OAAO,CAAC;CACpC;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,YAAY,EAAE,MAAM,EAAE,EACtB,UAAU,EAAE,MAAM,EAAE,EACpB,OAAO,EAAE,0BAA0B,GAClC,MAAM,EAAE,CA4HV;AAID,MAAM,WAAW,2BAA2B;IAC1C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,EAAE,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,iEAAiE;IACjE,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB,wDAAwD;IACxD,OAAO,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACpC;;;;;OAKG;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,MAAM,EAAE,CAyHnF"}

package/dist/typings/scenes.js

@@ -0,0 +1,368 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'fs';
+import { join, relative, extname, dirname, resolve } from 'path';
+import { createTsProgram } from "../parser/typescript/index.js";
+import { resolveRegistry } from "../config/index.js";
+import { convertGdToTs } from "../converter/gd-to-ts/index.js";
+import { runTsHelpers } from "../converter/gd-to-ts/ts-helpers.js";
+import { findAddonGdFiles } from "../cli/helpers.js";
+import { ProjectCache } from "../cache/index.js";
+import { parseScene } from "./scene-parser.js";
+import { generateSceneTypingContent, generateScriptTypingContent, generateIndexTypingContent, resolveConnections, } from "./content-generators.js";
+import { absPathToResPath, sceneResPathToOutputFile, scriptResPathToOutputFile, computeTsImport, scanTsFilesForClasses, parseAutoloads, findSceneFiles, findAssetFiles, parseGdResourceType, ASSET_EXTENSION_MAP, resolveSignalHandlers, collectAllSignalHandlers, } from "./scene-utils.js";
+// ─── Re-exports (public API — other files import from scenes.ts) ───
+export { parseAutoloads, resolveSignalHandlers, collectAllSignalHandlers, findSceneFiles };
+/**
+ * Generates per-file .d.ts typings in outputDir:
+ * - Per-scene .tscn.d.ts files (scene tree interfaces, GodotResources, parent entries)
+ * - Per-script .gd.d.ts files (module augmentation, global class, GodotScripts)
+ * - Per-resource .d.ts files (GodotResources entries)
+ * - _index.d.ts (empty global interfaces, autoload singletons)
+ * Returns list of written file paths.
+ */
+export function generateTypings(options) {
+    const { rootDir, tsDir, outputDir, scenesDir, ignore = [], cache, onDebug } = options;
+    // Default false — matches `ResolvedConfig.converterOptions` default.
+    const generateGlobal = options.generateGlobalClassTypes ?? false;
+    const writtenFiles = [];
+    const typingSources = []; // Track all sources for cleanStale
+    let written = 0;
+    let skipped = 0;
+    mkdirSync(outputDir, { recursive: true });
+    // 1. Scan TS files for class declarations
+    const program = createTsProgram({
+        rootDir: tsDir,
+        files: options.files,
+        tsConfigPath: options.tsConfigPath,
+    });
+    // Map: script res:// path -> class info including enums and inner classes
+    const scriptClassMap = new Map();
+    let registry;
+    try {
+        registry = resolveRegistry({ registryPath: options.registryPath });
+    }
+    catch { /* optional */ }
+    scanTsFilesForClasses(program, options.files, tsDir, scriptClassMap, registry);
+    // 2. Find and process all .tscn files
+    const sceneFiles = findSceneFiles(scenesDir, rootDir, ignore);
+    for (const sceneFile of sceneFiles) {
+        typingSources.push(sceneFile);
+        const actualResPath = absPathToResPath(sceneFile, rootDir);
+        const outputFile = sceneResPathToOutputFile(actualResPath);
+        const outputPath = resolve(outputDir, outputFile);
+        // Cache check: skip typing generation if scene file and .d.ts are unchanged
+        if (cache?.isTypingsFresh(sceneFile, outputPath)) {
+            skipped++;
+            writtenFiles.push(outputPath);
+            continue;
+        }
+        const sceneData = parseScene(sceneFile);
+        if (!sceneData)
+            continue;
+        // Collect unique name nodes from the parsed data
+        const uniqueNames = new Set();
+        for (const script of sceneData.scripts) {
+            for (const child of script.children) {
+                if (child.path.startsWith('%')) {
+                    uniqueNames.add(child.path.slice(1));
+                }
+            }
+        }
+        const connections = resolveConnections(actualResPath, sceneData);
+        const content = generateSceneTypingContent(actualResPath, sceneData, uniqueNames, connections);
+        mkdirSync(dirname(outputPath), { recursive: true });
+        writeFileSync(outputPath, content);
+        writtenFiles.push(outputPath);
+        written++;
+        cache?.updateTypings(sceneFile, outputPath);
+    }
+    // 3. Generate .gd.d.ts for each script
+    for (const [scriptResPath, classInfo] of scriptClassMap) {
+        typingSources.push(classInfo.tsAbsPath);
+        const outputFile = scriptResPathToOutputFile(scriptResPath);
+        const outputPath = resolve(outputDir, outputFile);
+        // Cache check: skip if TS source and .d.ts are unchanged
+        if (cache?.isTypingsFresh(classInfo.tsAbsPath, outputPath)) {
+            skipped++;
+            writtenFiles.push(outputPath);
+            continue;
+        }
+        const tsImportPath = computeTsImport(outputDir, outputFile, classInfo.tsAbsPath);
+        // `declare module "<path>"` matches the user's TS module specifier
+        // exactly. Under `moduleResolution: "classic"` (project default),
+        // user code writes `import "./foo"` (no extension) — so the
+        // augmentation target needs to be the same bare form.
+        const tsModulePath = tsImportPath;
+        const content = generateScriptTypingContent(scriptResPath, classInfo.className, classInfo.isAnonymous, tsImportPath, tsModulePath, classInfo.enums, classInfo.innerClasses, classInfo.extendsNode, generateGlobal);
+        mkdirSync(dirname(outputPath), { recursive: true });
+        writeFileSync(outputPath, content);
+        writtenFiles.push(outputPath);
+        written++;
+        cache?.updateTypings(classInfo.tsAbsPath, outputPath);
+    }
+    if (onDebug) {
+        if (skipped > 0)
+            onDebug(`Typings: wrote ${written}, skipped ${skipped} unchanged`);
+        else
+            onDebug(`Typings: wrote ${written} file(s)`);
+    }
+    // 4. Generate bundled _resources.d.ts for all asset files
+    const assetFiles = findAssetFiles(rootDir, rootDir, ignore);
+    const resourceEntries = [];
+    for (const assetFile of assetFiles) {
+        const resPath = absPathToResPath(assetFile, rootDir);
+        const ext = extname(assetFile).toLowerCase();
+        // Skip .tscn files (handled by scene generator) and .gd files (handled by script generator)
+        if (ext === '.tscn' || ext === '.gd')
+            continue;
+        let godotType;
+        if (ext === '.tres' || ext === '.res') {
+            godotType = parseGdResourceType(assetFile) ?? ASSET_EXTENSION_MAP[ext] ?? 'Resource';
+        }
+        else {
+            godotType = ASSET_EXTENSION_MAP[ext] ?? 'Resource';
+        }
+        resourceEntries.push({ resPath, godotType });
+    }
+    if (resourceEntries.length > 0) {
+        const resLines = [];
+        resLines.push('// AUTO-GENERATED — do not edit manually.\n');
+        resLines.push('declare global {');
+        resLines.push('  interface GodotResources {');
+        for (const { resPath, godotType } of resourceEntries) {
+            resLines.push(`    "${resPath}": ${godotType};`);
+        }
+        resLines.push('  }');
+        resLines.push('}\n');
+        resLines.push('export {}');
+        const resourcesPath = resolve(outputDir, '_resources.d.ts');
+        writeFileSync(resourcesPath, resLines.join('\n'));
+        writtenFiles.push(resourcesPath);
+    }
+    // 5. Generate _index.d.ts
+    const projectFile = options.projectFile ?? join(rootDir, 'project.godot');
+    const autoloads = existsSync(projectFile) ? parseAutoloads(projectFile) : [];
+    const indexContent = generateIndexTypingContent(autoloads, outputDir, options.godotTypingsDir);
+    const indexPath = resolve(outputDir, '_index.d.ts');
+    writeFileSync(indexPath, indexContent);
+    writtenFiles.push(indexPath);
+    // Clean stale typings entries and save cache
+    if (cache) {
+        const currentTypingSources = new Set(typingSources.map(f => f.replace(/\\/g, '/')));
+        cache.cleanStale(undefined, undefined, currentTypingSources);
+        cache.save();
+    }
+    return writtenFiles;
+}
+/**
+ * Regenerate typings for specific changed files (incremental).
+ * Handles .ts, .tscn, .tres/.res, and project.godot files.
+ * All TS files must be passed for the TS program to resolve cross-references.
+ */
+export function generateFileTypings(changedFiles, allTsFiles, options) {
+    const { rootDir, tsDir, outputDir, ignore = [], cache } = options;
+    const writtenFiles = [];
+    mkdirSync(outputDir, { recursive: true });
+    const changedTs = changedFiles.filter(f => f.endsWith('.ts') && !f.endsWith('.d.ts'));
+    const changedScenes = changedFiles.filter(f => f.endsWith('.tscn'));
+    const changedResources = changedFiles.filter(f => f.endsWith('.tres') || f.endsWith('.res') ||
+        f.endsWith('.png') || f.endsWith('.jpg') || f.endsWith('.ogg') ||
+        f.endsWith('.wav') || f.endsWith('.mp3') || f.endsWith('.gdshader') ||
+        f.endsWith('.theme'));
+    const changedProject = changedFiles.filter(f => f.endsWith('project.godot'));
+    // Regenerate .gd.d.ts for changed .ts files
+    if (changedTs.length > 0) {
+        // Need full TS program for type resolution, but only generate typings for changed files
+        const program = createTsProgram({
+            rootDir: tsDir,
+            files: allTsFiles,
+            tsConfigPath: options.tsConfigPath,
+        });
+        const scriptClassMap = new Map();
+        let fileRegistry;
+        try {
+            fileRegistry = resolveRegistry();
+        }
+        catch { /* optional */ }
+        scanTsFilesForClasses(program, changedTs, tsDir, scriptClassMap, fileRegistry);
+        for (const [scriptResPath, classInfo] of scriptClassMap) {
+            const outputFile = scriptResPathToOutputFile(scriptResPath);
+            const tsImportPath = computeTsImport(outputDir, outputFile, classInfo.tsAbsPath);
+            const tsModulePath = tsImportPath;
+            const content = generateScriptTypingContent(scriptResPath, classInfo.className, classInfo.isAnonymous, tsImportPath, tsModulePath, classInfo.enums, classInfo.innerClasses, classInfo.extendsNode, options.generateGlobalClassTypes ?? false);
+            const outputPath = resolve(outputDir, outputFile);
+            mkdirSync(dirname(outputPath), { recursive: true });
+            writeFileSync(outputPath, content);
+            writtenFiles.push(outputPath);
+            cache?.updateTypings(classInfo.tsAbsPath, outputPath);
+        }
+    }
+    // Regenerate .tscn.d.ts for changed .tscn files
+    for (const sceneFile of changedScenes) {
+        const sceneData = parseScene(sceneFile);
+        if (!sceneData)
+            continue;
+        const actualResPath = absPathToResPath(sceneFile, rootDir);
+        const uniqueNames = new Set();
+        for (const script of sceneData.scripts) {
+            for (const child of script.children) {
+                if (child.path.startsWith('%')) {
+                    uniqueNames.add(child.path.slice(1));
+                }
+            }
+        }
+        const content = generateSceneTypingContent(actualResPath, sceneData, uniqueNames);
+        const outputFile = sceneResPathToOutputFile(actualResPath);
+        const outputPath = resolve(outputDir, outputFile);
+        mkdirSync(dirname(outputPath), { recursive: true });
+        writeFileSync(outputPath, content);
+        writtenFiles.push(outputPath);
+        cache?.updateTypings(sceneFile, outputPath);
+    }
+    // Regenerate _resources.d.ts if any resource/asset changed
+    if (changedResources.length > 0) {
+        const assetFiles = findAssetFiles(rootDir, rootDir, ignore);
+        const resourceEntries = [];
+        for (const assetFile of assetFiles) {
+            const resPath = absPathToResPath(assetFile, rootDir);
+            const ext = extname(assetFile).toLowerCase();
+            if (ext === '.tscn' || ext === '.gd')
+                continue;
+            let godotType;
+            if (ext === '.tres' || ext === '.res') {
+                godotType = parseGdResourceType(assetFile) ?? ASSET_EXTENSION_MAP[ext] ?? 'Resource';
+            }
+            else {
+                godotType = ASSET_EXTENSION_MAP[ext] ?? 'Resource';
+            }
+            resourceEntries.push({ resPath, godotType });
+        }
+        if (resourceEntries.length > 0) {
+            const resLines = [];
+            resLines.push('// AUTO-GENERATED — do not edit manually.\n');
+            resLines.push('declare global {');
+            resLines.push('  interface GodotResources {');
+            for (const { resPath, godotType } of resourceEntries) {
+                resLines.push(`    "${resPath}": ${godotType};`);
+            }
+            resLines.push('  }');
+            resLines.push('}\n');
+            resLines.push('export {}');
+            const resourcesPath = resolve(outputDir, '_resources.d.ts');
+            writeFileSync(resourcesPath, resLines.join('\n'));
+            writtenFiles.push(resourcesPath);
+        }
+    }
+    // Regenerate _index.d.ts if project.godot changed
+    if (changedProject.length > 0) {
+        const projectFile = options.projectFile ?? join(rootDir, 'project.godot');
+        const autoloads = existsSync(projectFile) ? parseAutoloads(projectFile) : [];
+        const indexContent = generateIndexTypingContent(autoloads, outputDir, options.godotTypingsDir);
+        const indexPath = resolve(outputDir, '_index.d.ts');
+        writeFileSync(indexPath, indexContent);
+        writtenFiles.push(indexPath);
+    }
+    cache?.save();
+    return writtenFiles;
+}
+/**
+ * Generate typings for GDScript addon files.
+ * Converts addon .gd -> .ts, writes to outputDir/addons/ preserving structure,
+ * then generates .gd.d.ts scene typings for each addon script.
+ */
+export function generateAddonTypings(options) {
+    const { rootDir, outputDir, cache, onDebug } = options;
+    const ignore = options.ignore ?? [];
+    const writtenFiles = [];
+    const addonGdFiles = findAddonGdFiles(rootDir, ignore);
+    if (addonGdFiles.length === 0)
+        return writtenFiles;
+    // Cache check: if ALL addon files are fresh, skip the entire pipeline.
+    // (Changing one addon can affect type resolution for others, so it's all-or-nothing.)
+    if (cache) {
+        const allFresh = addonGdFiles.every(gdPath => {
+            const relPath = relative(rootDir, gdPath).replace(/\\/g, '/');
+            const tsPath = resolve(outputDir, relPath.replace(/\.gd$/, '.ts'));
+            const dtsPath = resolve(outputDir, scriptResPathToOutputFile('res://' + relPath));
+            return cache.isAddonFresh(gdPath, tsPath, dtsPath);
+        });
+        if (allFresh) {
+            onDebug?.(`Addon typings: skipped ${addonGdFiles.length} unchanged file(s)`);
+            return writtenFiles;
+        }
+    }
+    const registry = resolveRegistry({ registryPath: options.registryPath });
+    const addonSources = addonGdFiles.map(f => ({
+        source: readFileSync(f, 'utf-8'),
+        filePath: f,
+    }));
+    // Pass 1: Convert all addon .gd -> .ts, write to outputDir.
+    // Addon .ts files start without `@ts-nocheck` so the nullable helper's
+    // type checker can see the annotations. The header is prepended after
+    // the helper pass finishes.
+    const addonTsPaths = [];
+    for (const { source, filePath } of addonSources) {
+        const result = convertGdToTs({ source, filePath, registry, projectSources: addonSources, isAddon: true });
+        const relPath = relative(rootDir, filePath).replace(/\\/g, '/');
+        const outputTsPath = resolve(outputDir, relPath.replace(/\.gd$/, '.ts'));
+        mkdirSync(dirname(outputTsPath), { recursive: true });
+        writeFileSync(outputTsPath, result.code);
+        writtenFiles.push(outputTsPath);
+        addonTsPaths.push(outputTsPath);
+    }
+    // Pass 1b: Run the nullable helper in addon mode. Phase B widens reference-
+    // typed field/local annotations; Phase C widens function returns only when
+    // TS2322 proves null flows through; Phase D narrows parameters back to
+    // strict when the body uses them as non-null. Addon consumers see signatures
+    // matching the addon's actual null behaviour.
+    if (addonTsPaths.length > 0) {
+        runTsHelpers({
+            files: addonTsPaths,
+            rootDir: outputDir,
+            tsConfigPath: options.tsConfigPath,
+            registry,
+            addonMode: true,
+        });
+    }
+    // Prepend the `@ts-nocheck` header now that helper mutations are done.
+    for (const p of addonTsPaths) {
+        const body = readFileSync(p, 'utf-8');
+        writeFileSync(p, '// @ts-nocheck — auto-generated from GDScript addon\n' + body);
+    }
+    // Pass 2: Create TS program from addon .ts files, scan for classes
+    const scriptClassMap = new Map();
+    const addonProgram = createTsProgram({ rootDir: outputDir, files: addonTsPaths });
+    scanTsFilesForClasses(addonProgram, addonTsPaths, outputDir, scriptClassMap, registry, true);
+    // Pass 3: Generate .gd.d.ts for each addon script. Addons always opt
+    // into `declare global` so their classes are usable in the consuming
+    // project without explicit imports — that's the contract addons rely
+    // on, regardless of the project's `generateGlobalClassTypes` setting.
+    for (const [scriptResPath, classInfo] of scriptClassMap) {
+        const outputFile = scriptResPathToOutputFile(scriptResPath);
+        const tsImportPath = computeTsImport(outputDir, outputFile, classInfo.tsAbsPath);
+        const tsModulePath = tsImportPath;
+        const content = generateScriptTypingContent(scriptResPath, classInfo.className, classInfo.isAnonymous, tsImportPath, tsModulePath, classInfo.enums, classInfo.innerClasses, classInfo.extendsNode, true);
+        const outputPath = resolve(outputDir, outputFile);
+        mkdirSync(dirname(outputPath), { recursive: true });
+        writeFileSync(outputPath, content);
+        writtenFiles.push(outputPath);
+    }
+    // Update addon cache entries after full pipeline
+    if (cache) {
+        for (const gdPath of addonGdFiles) {
+            const relPath = relative(rootDir, gdPath).replace(/\\/g, '/');
+            const tsPath = resolve(outputDir, relPath.replace(/\.gd$/, '.ts'));
+            const resPath = 'res://' + relPath;
+            const dtsFile = scriptResPathToOutputFile(resPath);
+            const dtsPath = resolve(outputDir, dtsFile);
+            if (existsSync(tsPath) && existsSync(dtsPath)) {
+                cache.updateAddon(gdPath, tsPath, dtsPath);
+            }
+        }
+        const currentAddonFiles = new Set(addonGdFiles.map(f => f.replace(/\\/g, '/')));
+        cache.cleanStale(undefined, currentAddonFiles);
+        cache.save();
+    }
+    onDebug?.(`Addon typings: wrote ${writtenFiles.length} file(s)`);
+    return writtenFiles;
+}
+//# sourceMappingURL=scenes.js.map

package/dist/typings/scenes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scenes.js","sourceRoot":"","sources":["../../src/typings/scenes.ts"],"names":[],"mappings":"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"}

package/dist/typings/type-mapping.d.ts

@@ -0,0 +1,76 @@
+import type { GodotClassXml } from './godot-registry.ts';
+/**
+ * Context passed explicitly through type-mapping functions.
+ * Built once per typings generation run by `generateGodotDocsTypings()`.
+ * Replaces the previous module-level singleton state.
+ */
+export interface TypeContext {
+    /** Set of known Godot class names (excludes `@`-prefixed pseudo-classes). */
+    knownClasses: Set<string>;
+    /**
+     * Fundamental value types constructed as function calls in GDScript (not `new`).
+     * Derived set — classes with a copy constructor (single parameter of own type).
+     */
+    valueTypes: Set<string>;
+    /**
+     * Per-class set of member names whose types should stay non-nullable even
+     * though they would normally be nullable reference types.
+     * Loaded from `non-nullable.json` files in override directories.
+     */
+    nonNullableMembers: Map<string, Set<string>>;
+    /**
+     * Map of Godot type name → types that can be implicitly converted to it.
+     * Used to widen method parameter types (e.g. `Vector2` also accepts `Vector2i`).
+     */
+    variantParamConverts: Map<string, string[]>;
+}
+/** Construct an empty context (used during early bootstrap before all fields are populated). */
+export declare function emptyTypeContext(): TypeContext;
+/** TS primitive types — widening between two primitives is excluded (too noisy). */
+export declare const TS_PRIMITIVE_TYPES: Set<string>;
+/** TS type names that are always non-nullable (primitives, void, unknown). */
+export declare const NON_NULLABLE_TS_TYPES: Set<string>;
+/** Names that conflict with TS/JS built-in globals and need prefixing */
+export declare const CLASS_NAME_CONFLICTS: Map<string, string>;
+/**
+ * GDScript classes emitted as TS interfaces (replacing standard TS built-in types).
+ * Maps GD class name → TS interface name. These are generated from Godot docs
+ * instead of being hardcoded in globals.d.ts.
+ */
+export declare const INTERFACE_CLASSES: Map<string, string>;
+export declare function sanitizeClassName(name: string): string;
+/**
+ * Maps a Godot type string to a TypeScript type string.
+ */
+export declare function godotTypeToTs(type: string, ctx: TypeContext): string;
+/**
+ * Returns true when a Godot type should be made nullable (`T | null`) in
+ * generated declarations.  Reference types (Node, Resource, Material, etc.)
+ * are nullable; value/variant types, primitives, enums and arrays are not.
+ */
+export declare function isNullableGodotType(gdType: string, ctx: TypeContext): boolean;
+/**
+ * Widen a Godot type for use as a method parameter by including all types
+ * that can be variant-converted to it.
+ * Returns the TS type string, potentially as a union (e.g. `Vector2 | Vector2i`).
+ */
+export declare function widenParamType(gdType: string, ctx: TypeContext): string;
+/**
+ * Derive value types from parsed XML class data.
+ * A class is a value type if it has a constructor with a single parameter of
+ * its own type (e.g. `Vector2(from: Vector2)`).
+ */
+export declare function deriveValueTypes(classes: Map<string, GodotClassXml>, ctx: TypeContext): Set<string>;
+/**
+ * Derive variant conversion map from parsed XML class data.
+ * For each class with single-parameter "from" constructors, records which types
+ * can be converted to this class.
+ */
+export declare function deriveVariantParamConverts(classes: Map<string, GodotClassXml>): Map<string, string[]>;
+/**
+ * Load `non-nullable.json` from each override directory and merge.
+ * Later directories override earlier ones (user > defaults).
+ * Returns a map of ClassName → Set of member names that should be non-nullable.
+ */
+export declare function loadNonNullableOverrides(overrideDirs: string[]): Map<string, Set<string>>;
+//# sourceMappingURL=type-mapping.d.ts.map

package/dist/typings/type-mapping.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"type-mapping.d.ts","sourceRoot":"","sources":["../../src/typings/type-mapping.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIzD;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,6EAA6E;IAC7E,YAAY,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC1B;;;OAGG;IACH,UAAU,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACxB;;;;OAIG;IACH,kBAAkB,EAAE,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IAC7C;;;OAGG;IACH,oBAAoB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;CAC7C;AAED,gGAAgG;AAChG,wBAAgB,gBAAgB,IAAI,WAAW,CAO9C;AAID,oFAAoF;AACpF,eAAO,MAAM,kBAAkB,aAAoE,CAAC;AAEpG,8EAA8E;AAC9E,eAAO,MAAM,qBAAqB,aAEhC,CAAC;AAEH,yEAAyE;AACzE,eAAO,MAAM,oBAAoB,qBAE/B,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,qBAK5B,CAAC;AAEH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEtD;AAID;;GAEG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,MAAM,CA0EpE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAoB7E;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,EAAE,WAAW,GAAG,MAAM,CAevE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,EACnC,GAAG,EAAE,WAAW,GACf,GAAG,CAAC,MAAM,CAAC,CAeb;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,aAAa,CAAC,GAClC,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAevB;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,GAAG,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC,CAYzF"}