@ts-for-gir/generator-typescript 4.0.0-beta.40 → 4.0.0-beta.41

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ts-for-gir/generator-typescript",
-  "version": "4.0.0-beta.40",
+  "version": "4.0.0-beta.41",
   "description": "TypeScript type definition generator for ts-for-gir",
   "main": "src/index.ts",
   "module": "src/index.ts",
@@ -31,17 +31,18 @@
     "generator"
   ],
   "devDependencies": {
+    "@ts-for-gir/tsconfig": "^4.0.0-beta.41",
     "@types/ejs": "^3.1.5",
-    "@types/node": "^24.11.0",
+    "@types/node": "^24.12.0",
     "@types/xml2js": "^0.4.14",
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@gi.ts/parser": "^4.0.0-beta.40",
-    "@ts-for-gir/generator-base": "^4.0.0-beta.40",
-    "@ts-for-gir/lib": "^4.0.0-beta.40",
-    "@ts-for-gir/templates": "^4.0.0-beta.40",
-    "ejs": "^4.0.1",
+    "@gi.ts/parser": "^4.0.0-beta.41",
+    "@ts-for-gir/generator-base": "^4.0.0-beta.41",
+    "@ts-for-gir/lib": "^4.0.0-beta.41",
+    "@ts-for-gir/templates": "^4.0.0-beta.41",
+    "ejs": "^5.0.1",
     "xml2js": "^0.6.2"
   }
 }

package/src/generators/index.ts

@@ -0,0 +1,2 @@
+export { ModuleExporter } from "./module-exporter.ts";
+export { SignalGenerator } from "./signal-generator.ts";

package/src/generators/module-exporter.ts

@@ -0,0 +1,88 @@
+import type { DependencyManager, GirModule, NSRegistry, OptionsGeneration, Reporter } from "@ts-for-gir/lib";
+import type { ModuleGenerator } from "../module-generator.ts";
+import { NpmPackage } from "../npm-package.ts";
+import type { TemplateProcessor } from "../template-processor.ts";
+
+/** Handles exporting generated modules to files. */
+export class ModuleExporter {
+	constructor(private readonly core: ModuleGenerator) {}
+
+	private get config(): OptionsGeneration {
+		return this.core.config;
+	}
+
+	private get log(): Reporter {
+		return this.core.log;
+	}
+
+	private get moduleTemplateProcessor(): TemplateProcessor {
+		return this.core.moduleTemplateProcessor;
+	}
+
+	private get dependencyManager(): DependencyManager {
+		return this.core.dependencyManager;
+	}
+
+	/** Export a template file to outdir or log its content. */
+	private async exportTemplate(template: string, target: string): Promise<void> {
+		if (this.config.outdir) {
+			await this.moduleTemplateProcessor.create(template, this.config.outdir, target);
+		} else {
+			const { append, prepend } = await this.moduleTemplateProcessor.load(template);
+			this.log.log(append + prepend);
+		}
+	}
+
+	async exportModuleTS(): Promise<void> {
+		const girModule = this.core.girNamespace;
+		const template = "module.d.ts";
+		const explicitTemplate = `${girModule.importName}.d.ts`;
+		const output = await this.core.generateModule(girModule);
+
+		if (!output) {
+			this.log.error("Failed to generate gir module");
+			return;
+		}
+
+		if (await this.moduleTemplateProcessor.exists(explicitTemplate)) {
+			const { append: appendExplicit, prepend: prependExplicit } =
+				await this.moduleTemplateProcessor.load(explicitTemplate);
+			output.unshift(prependExplicit);
+			output.push(appendExplicit);
+		}
+
+		const { append, prepend } = await this.moduleTemplateProcessor.load(template);
+		output.unshift(prepend);
+		output.push(append);
+
+		if (this.config.outdir) {
+			await this.moduleTemplateProcessor.write(output.join("\n"), this.config.outdir, explicitTemplate);
+		} else {
+			this.log.log(output.join("\n"));
+		}
+	}
+
+	async exportModule(registry: NSRegistry, girModule: GirModule): Promise<void> {
+		await this.exportModuleTS();
+
+		if (this.config.package) {
+			const name = girModule.importName;
+			await this.exportTemplate("module.js", `${name}.js`);
+			await this.exportTemplate("index.d.ts", "index.d.ts");
+			await this.exportTemplate("index.js", "index.js");
+			await this.exportTemplate("module-ambient.d.ts", `${name}-ambient.d.ts`);
+			await this.exportTemplate("module-ambient.js", `${name}-ambient.js`);
+			await this.exportTemplate("module-import.d.ts", `${name}-import.d.ts`);
+			await this.exportTemplate("module-import.js", `${name}-import.js`);
+
+			const pkg = new NpmPackage(
+				this.config,
+				this.dependencyManager,
+				registry,
+				girModule,
+				girModule.transitiveDependencies,
+			);
+			await pkg.exportNPMPackage();
+		}
+	}
+}

package/src/generators/signal-generator.ts

@@ -0,0 +1,254 @@
+import {
+	BinaryType,
+	BooleanType,
+	FilterBehavior,
+	filterConflicts,
+	type GirModule,
+	generateIndent,
+	type IntrospectedBaseClass,
+	IntrospectedClass,
+	IntrospectedClassFunction,
+	IntrospectedInterface,
+	type IntrospectedRecord,
+	mergeDescs,
+	NumberType,
+	type OptionsGeneration,
+	VoidType,
+} from "@ts-for-gir/lib";
+import type { ModuleGenerator } from "../module-generator.ts";
+
+const SIGNAL_JSDOC = "/** @signal */";
+
+/** Handles generation of GObject signal-related TypeScript definitions. */
+export class SignalGenerator {
+	constructor(private readonly core: ModuleGenerator) {}
+
+	private get namespace(): GirModule {
+		return this.core.girNamespace;
+	}
+
+	private get config(): OptionsGeneration {
+		return this.core.config;
+	}
+
+	/**
+	 * Generate SignalSignatures interface for type-safe signal handling.
+	 *
+	 * Creates a comprehensive mapping of signal names to their callback types,
+	 * enabling TypeScript to provide proper type checking and IntelliSense for
+	 * GObject signals using the centralized getAllSignals() method from the model.
+	 */
+	generateClassSignalInterfaces(girClass: IntrospectedClass, indentCount = 0): string[] {
+		const def: string[] = [];
+		const indent = generateIndent(indentCount);
+
+		def.push(`${indent}// Signal signatures`);
+		def.push(`${indent}interface SignalSignatures`);
+
+		const parentSignatures: string[] = [];
+
+		// Inherit signal signatures from parent class
+		const parentResolution = girClass.resolveParents().extends();
+		if (parentResolution && parentResolution.node instanceof IntrospectedClass) {
+			const parentClass = parentResolution.node as IntrospectedClass;
+			const parentTypeIdentifier = parentResolution.identifier
+				.resolveIdentifier(this.namespace, this.config)
+				?.print(this.namespace, this.config);
+
+			const hasSignalMethods = parentClass.signals?.length > 0;
+			const isNotTemplateWorkaround = !(
+				this.namespace.namespace === "Gimp" && ["ParamObject", "ParamItem", "ParamArray"].includes(parentClass.name)
+			);
+
+			if (parentTypeIdentifier && (hasSignalMethods || isNotTemplateWorkaround)) {
+				parentSignatures.push(`${parentTypeIdentifier}.SignalSignatures`);
+			}
+		}
+
+		// Inherit signal signatures from implemented interfaces
+		const interfaceSignatures = girClass
+			.resolveParents()
+			.implements()
+			.filter((iface) => iface.node instanceof IntrospectedInterface)
+			.filter((iface) => {
+				const node = iface.node as unknown as { signals?: unknown[] };
+				return node.signals && node.signals.length > 0;
+			})
+			.map((iface) => {
+				const interfaceTypeIdentifier = iface.identifier
+					.resolveIdentifier(this.namespace, this.config)
+					?.print(this.namespace, this.config);
+				return interfaceTypeIdentifier ? `${interfaceTypeIdentifier}.SignalSignatures` : null;
+			})
+			.filter((sig): sig is string => !!sig);
+
+		parentSignatures.push(...interfaceSignatures);
+
+		if (parentSignatures.length > 0) {
+			def.push(` extends ${parentSignatures.join(", ")} {`);
+		} else {
+			const isGObjectObject = girClass.name === "Object" && girClass.namespace.namespace === "GObject";
+
+			if (isGObjectObject) {
+				def.push(" {");
+			} else {
+				const gobjectNamespace = this.namespace.assertInstalledImport("GObject");
+				const gobjectObjectClass = gobjectNamespace.assertClass("Object");
+				const gobjectRef = gobjectObjectClass
+					.getType()
+					.resolveIdentifier(this.namespace, this.config)
+					?.print(this.namespace, this.config);
+
+				const fallbackRef = gobjectRef ? `${gobjectRef}.SignalSignatures` : "GObject.Object.SignalSignatures";
+				def.push(` extends ${fallbackRef} {`);
+			}
+		}
+
+		const allSignals = girClass.getAllSignals();
+
+		allSignals.forEach((signalInfo) => {
+			const signalKey = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(signalInfo.name) ? signalInfo.name : `"${signalInfo.name}"`;
+
+			let cbType: string;
+
+			if (signalInfo.isNotifySignal) {
+				const gobjectRef = this.namespace.namespace === "GObject" ? "" : "GObject.";
+				cbType = `(pspec: ${gobjectRef}ParamSpec) => void`;
+			} else if (signalInfo.signal) {
+				const paramTypes = signalInfo.signal.parameters
+					.map((p, idx) => `arg${idx}: ${this.core.generateType(p.type)}`)
+					.join(", ");
+
+				let returnType = signalInfo.signal.return_type;
+				if (signalInfo.signal.return_type.equals(BooleanType)) {
+					returnType = new BinaryType(BooleanType, VoidType);
+				}
+				const returnTypeStr = this.core.generateType(returnType);
+
+				cbType = `(${paramTypes}) => ${returnTypeStr}`;
+			} else {
+				const paramTypes = signalInfo.parameterTypes?.map((type, idx) => `arg${idx}: ${type}`) || [];
+				const returnTypeStr = signalInfo.returnType || "void";
+				cbType = `(${paramTypes.join(", ")}) => ${returnTypeStr}`;
+			}
+
+			// Add signal doc comment with @signal tag and signal-specific modifier tags
+			if (!signalInfo.isNotifySignal && signalInfo.signal) {
+				const signalTags = [
+					{ tagName: "signal", paramName: "", text: "" },
+					...this.namespace.getTsDocMetadataTags(signalInfo.signal.metadata),
+				];
+				if (signalInfo.signal.detailed) signalTags.push({ tagName: "detailed", paramName: "", text: "" });
+				if (signalInfo.signal.action) signalTags.push({ tagName: "action", paramName: "", text: "" });
+				if (signalInfo.signal.when)
+					signalTags.push({ tagName: `run-${signalInfo.signal.when}`, paramName: "", text: "" });
+				const comment = this.core.addGirDocComment(signalInfo.signal.doc, signalTags, indentCount + 1);
+				if (comment.length) {
+					def.push(...comment);
+				} else {
+					def.push(`${indent}    /** @signal */`);
+				}
+			} else if (!signalInfo.isNotifySignal) {
+				def.push(`${indent}    /** @signal */`);
+			}
+			def.push(`${indent}    ${signalKey}: ${cbType};`);
+		});
+
+		def.push(`${indent}}`);
+		def.push("");
+
+		return def;
+	}
+
+	/**
+	 * Generate signal methods section with header comment
+	 */
+	generateClassSignals(girClass: IntrospectedClass): string[] {
+		return mergeDescs(this.generateSignalMethods(girClass), "Signals", 1);
+	}
+
+	/**
+	 * Generate the $signals property for type-safe signal access
+	 */
+	generateClassSignalsProperty(girClass: IntrospectedClass | IntrospectedRecord, indentCount = 1): string[] {
+		const isGObjectObject = girClass.name === "Object" && girClass.namespace.namespace === "GObject";
+		const hasGObjectParent =
+			isGObjectObject ||
+			girClass.someParent((p: IntrospectedBaseClass) => p.namespace.namespace === "GObject" && p.name === "Object");
+
+		if (!hasGObjectParent) return [];
+
+		const indent = generateIndent(indentCount);
+		return [
+			"",
+			`${indent}/**`,
+			`${indent} * Compile-time signal type information.`,
+			`${indent} *`,
+			`${indent} * This instance property is generated only for TypeScript type checking.`,
+			`${indent} * It is not defined at runtime and should not be accessed in JS code.`,
+			`${indent} * @internal`,
+			`${indent} */`,
+			`${indent}$signals: ${girClass.name}.SignalSignatures;`,
+			"",
+		];
+	}
+
+	/**
+	 * Generate type-safe connect/connect_after/emit signal methods
+	 */
+	private generateSignalMethods(girClass: IntrospectedClass): string[] {
+		const signalFunctions = [
+			new IntrospectedClassFunction({
+				name: "connect",
+				parent: girClass,
+				parameters: [],
+				return_type: NumberType,
+			}),
+			new IntrospectedClassFunction({
+				name: "connect_after",
+				parent: girClass,
+				parameters: [],
+				return_type: NumberType,
+			}),
+			new IntrospectedClassFunction({
+				name: "emit",
+				parent: girClass,
+				parameters: [],
+				return_type: VoidType,
+			}),
+		];
+
+		const filteredFunctions = filterConflicts(girClass.namespace, girClass, signalFunctions, FilterBehavior.DELETE);
+		const allowedNames = new Set(filteredFunctions.map((f) => f.name));
+
+		const gobjectRef = this.namespace.namespace === "GObject" ? "" : "GObject.";
+
+		const methods: string[] = [];
+
+		if (allowedNames.has("connect")) {
+			methods.push(
+				SIGNAL_JSDOC,
+				`connect<K extends keyof ${girClass.name}.SignalSignatures>(signal: K, callback: ${gobjectRef}SignalCallback<this, ${girClass.name}.SignalSignatures[K]>): number;`,
+				"connect(signal: string, callback: (...args: any[]) => any): number;",
+			);
+		}
+
+		if (allowedNames.has("connect_after")) {
+			methods.push(
+				SIGNAL_JSDOC,
+				`connect_after<K extends keyof ${girClass.name}.SignalSignatures>(signal: K, callback: ${gobjectRef}SignalCallback<this, ${girClass.name}.SignalSignatures[K]>): number;`,
+				"connect_after(signal: string, callback: (...args: any[]) => any): number;",
+			);
+		}
+
+		if (allowedNames.has("emit")) {
+			methods.push(
+				SIGNAL_JSDOC,
+				`emit<K extends keyof ${girClass.name}.SignalSignatures>(signal: K, ...args: ${gobjectRef}GjsParameters<${girClass.name}.SignalSignatures[K]> extends [any, ...infer Q] ? Q : never): void;`,
+				"emit(signal: string, ...args: any[]): void;",
+			);
+		}
+
+		return methods;
+	}
+}

package/src/module-generator.ts

@@ -4,7 +4,6 @@ import {
 	addInfoComment,
 	addTSDocCommentLines,
 	BinaryType,
-	BooleanType,
 	ClassStructTypeIdentifier,
 	ConflictType,
 	DependencyManager,
@@ -13,6 +12,7 @@ import {
 	filterConflicts,
 	filterFunctionConflict,
 	type Generic,
+	type GirDocContext,
 	type GirEnumMember,
 	type GirModule,
 	generateIndent,
@@ -41,10 +41,8 @@ import {
 	IntrospectedStaticClassFunction,
 	IntrospectedVirtualClassFunction,
 	isInvalid,
-	mergeDescs,
 	NativeType,
 	type NSRegistry,
-	NumberType,
 	type OptionsGeneration,
 	printGirDocComment,
 	promisifyFunctions,
@@ -57,11 +55,11 @@ import {
 	type TsDocTag,
 	TypeConflict,
 	type TypeExpression,
+	transformGirDocTagTextWithContext,
 	transformGirDocText,
-	VoidType,
 } from "@ts-for-gir/lib";
+import { ModuleExporter, SignalGenerator } from "./generators/index.ts";
 // import { PackageDataParser } from './package-data-parser.ts'
-import { NpmPackage } from "./npm-package.ts";
 import { override as overrideGLib } from "./overrides/glib.ts";
 import { override as overrideGObject } from "./overrides/gobject.ts";
 import { TemplateProcessor } from "./template-processor.ts";
@@ -80,6 +78,33 @@ export enum ModuleGeneratorFormat {
 	Inline = "inline",
 }
 
+/**
+ * Base URLs for gi-docgen content pages per namespace.
+ * Version-specific keys (e.g. "Gtk-4.0") take priority over plain namespace keys.
+ */
+const DOC_BASE_URLS = new Map<string, string>([
+	// GNOME core (docs.gtk.org)
+	["GLib", "https://docs.gtk.org/glib/"],
+	["GObject", "https://docs.gtk.org/gobject/"],
+	["Gio", "https://docs.gtk.org/gio/"],
+	["GdkPixbuf", "https://docs.gtk.org/gdk-pixbuf/"],
+	["Pango", "https://docs.gtk.org/Pango/"],
+	["PangoCairo", "https://docs.gtk.org/PangoCairo/"],
+	// GTK 4
+	["Gtk-4.0", "https://docs.gtk.org/gtk4/"],
+	["Gdk-4.0", "https://docs.gtk.org/gdk4/"],
+	["Gsk-4.0", "https://docs.gtk.org/gsk4/"],
+	["GdkWayland-4.0", "https://docs.gtk.org/gdk4-wayland/"],
+	["GdkX11-4.0", "https://docs.gtk.org/gdk4-x11/"],
+	// GTK 3
+	["Gtk-3.0", "https://docs.gtk.org/gtk3/"],
+	["Gdk-3.0", "https://docs.gtk.org/gdk3/"],
+	// Libadwaita
+	["Adw-1", "https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/"],
+	// GtkSourceView
+	["GtkSource-5", "https://gnome.pages.gitlab.gnome.org/gtksourceview/gtksourceview5/"],
+]);
+
 export class ModuleGenerator extends FormatGenerator<string[]> {
 	log: Reporter;
 	dependencyManager: DependencyManager;
@@ -88,6 +113,14 @@ export class ModuleGenerator extends FormatGenerator<string[]> {
 	config: OptionsGeneration;
 	moduleTemplateProcessor: TemplateProcessor;
 
+	readonly signalGenerator: SignalGenerator;
+	readonly moduleExporter: ModuleExporter;
+
+	/** Public accessor for the protected namespace from FormatGenerator */
+	get girNamespace() {
+		return this.namespace;
+	}
+
 	/**
 	 * @param _config The config to use without the override config
 	 */
@@ -124,6 +157,82 @@ export class ModuleGenerator extends FormatGenerator<string[]> {
 			girModule.transitiveDependencies,
 			this.config,
 		);
+
+		this.signalGenerator = new SignalGenerator(this);
+		this.moduleExporter = new ModuleExporter(this);
+		this._docContext = this.buildDocContext();
+	}
+
+	private readonly _docContext: GirDocContext;
+
+	/**
+	 * Build a GirDocContext that resolves C identifiers to TypeScript paths
+	 * by searching the current namespace and all its dependencies.
+	 */
+	private buildDocContext(): GirDocContext {
+		const ns = this.namespace;
+
+		// Collect all available namespaces (current + dependencies)
+		const allNamespaces: GirModule[] = [ns];
+		for (const dep of ns.allDependencies) {
+			const imported = ns.getInstalledImport(dep.namespace);
+			if (imported) allNamespaces.push(imported);
+		}
+
+		// Resolve base URL for gi-docgen content pages
+		const docBaseUrl = DOC_BASE_URLS.get(`${ns.namespace}-${ns.version}`) ?? DOC_BASE_URLS.get(ns.namespace);
+
+		// Pre-merge enum constants for O(1) lookup
+		const constantMap = new Map<string, string>();
+		for (const mod of allNamespaces) {
+			for (const [cId, result] of mod.enum_constants) {
+				if (!constantMap.has(cId)) {
+					constantMap.set(cId, `${mod.namespace}.${result[0]}.${result[1]}`);
+				}
+			}
+		}
+
+		// Type resolution cache — populated lazily on first miss
+		const typeCache = new Map<string, string | null>();
+
+		return {
+			docBaseUrl,
+			resolveType(cTypeName: string): string | null {
+				const cached = typeCache.get(cTypeName);
+				if (cached !== undefined) return cached;
+
+				let result: string | null = null;
+				// Strategy 1: _resolve_names lookup
+				for (const mod of allNamespaces) {
+					const member = mod.getMemberWithoutOverrides(cTypeName);
+					if (member && "name" in member) {
+						result = `${mod.namespace}.${member.name}`;
+						break;
+					}
+				}
+				// Strategy 2: C prefix stripping
+				if (!result) {
+					for (const mod of allNamespaces) {
+						for (const prefix of mod.c_prefixes) {
+							if (cTypeName.startsWith(prefix) && cTypeName.length > prefix.length) {
+								const girName = cTypeName.slice(prefix.length);
+								if (mod.hasSymbol(girName)) {
+									result = `${mod.namespace}.${girName}`;
+									break;
+								}
+							}
+						}
+						if (result) break;
+					}
+				}
+
+				typeCache.set(cTypeName, result);
+				return result;
+			},
+			resolveConstant(cIdentifier: string): string | null {
+				return constantMap.get(cIdentifier) ?? null;
+			},
+		};
 	}
 
 	/**
@@ -311,14 +420,22 @@ export class ModuleGenerator extends FormatGenerator<string[]> {
 	}
 
 	generateSignal(node: IntrospectedSignal, type: IntrospectedSignalType = IntrospectedSignalType.CONNECT): string[] {
+		let fn: IntrospectedClassFunction;
 		switch (type) {
 			case IntrospectedSignalType.CONNECT:
-				return node.asConnect(false).asString(this);
+				fn = node.asConnect(false);
+				break;
 			case IntrospectedSignalType.CONNECT_AFTER:
-				return node.asConnect(true).asString(this);
+				fn = node.asConnect(true);
+				break;
 			case IntrospectedSignalType.EMIT:
-				return node.asEmit().asString(this);
+				fn = node.asEmit();
+				break;
 		}
+		fn.doc = node.doc;
+		fn.metadata = node.metadata;
+		fn.signalOrigin = node.name;
+		return fn.asString(this);
 	}
 
 	generateStaticClassFunction(node: IntrospectedStaticClassFunction): string[] {
@@ -340,7 +457,11 @@ export class ModuleGenerator extends FormatGenerator<string[]> {
 	generateProperty(tsProp: IntrospectedProperty, construct?: boolean, indentCount = 0) {
 		const desc: string[] = [];
 
-		desc.push(...this.addGirDocComment(tsProp.doc, [], indentCount));
+		const propTags = [...this.namespace.getTsDocMetadataTags(tsProp.metadata)];
+		if (tsProp.constructOnly) propTags.push({ tagName: "construct-only", paramName: "", text: "" });
+		else if (tsProp.readable && !tsProp.writable) propTags.push({ tagName: "read-only", paramName: "", text: "" });
+		else if (tsProp.writable && !tsProp.readable) propTags.push({ tagName: "write-only", paramName: "", text: "" });
+		desc.push(...this.addGirDocComment(tsProp.doc, propTags, indentCount));
 
 		const indent = generateIndent(indentCount);
 		const name = generateMemberName(tsProp);
@@ -421,7 +542,7 @@ export class ModuleGenerator extends FormatGenerator<string[]> {
 		const desc: string[] = [];
 		const isStatic = tsProp.isStatic;
 
-		desc.push(...this.addGirDocComment(tsProp.doc, [], indentCount));
+		desc.push(...this.addGirDocComment(tsProp.doc, this.namespace.getTsDocMetadataTags(tsProp.metadata), indentCount));
 
 		const indent = generateIndent(indentCount);
 		const name = generateMemberName(tsProp);
@@ -532,9 +653,9 @@ export class ModuleGenerator extends FormatGenerator<string[]> {
 			return desc;
 		}
 
-		const text = tsDoc ? transformGirDocText(tsDoc) : null;
+		const text = tsDoc ? transformGirDocText(tsDoc, this._docContext) : null;
 
-		if (text) {
+		if (text || tags.length) {
 			desc.push(`${indent}/**`);
 
 			if (text) {
@@ -547,10 +668,13 @@ export class ModuleGenerator extends FormatGenerator<string[]> {
 			}
 
 			for (const tag of tags) {
+				const tagText = tag.text ? transformGirDocTagTextWithContext(tag.text, this._docContext) : "";
 				if (tag.paramName) {
-					desc.push(`${indent} * @${tag.tagName} ${tag.paramName} ${tag.text}`);
+					desc.push(`${indent} * @${tag.tagName} ${tag.paramName} ${tagText}`);
+				} else if (tagText) {
+					desc.push(`${indent} * @${tag.tagName} ${tagText}`);
 				} else {
-					desc.push(`${indent} * @${tag.tagName} ${tag.text}`);
+					desc.push(`${indent} * @${tag.tagName}`);
 				}
 			}
 			desc.push(`${indent} */`);
@@ -558,6 +682,29 @@ export class ModuleGenerator extends FormatGenerator<string[]> {
 		return desc;
 	}
 
+	private getGirTypeTags(
+		obj: IntrospectedClass | IntrospectedRecord | IntrospectedInterface | IntrospectedCallback | IntrospectedAlias,
+	): TsDocTag[] {
+		let girType: string;
+
+		if (obj instanceof IntrospectedRecord) {
+			if (obj.structFor) girType = "Class Struct";
+			else if (obj.isForeign()) girType = "Foreign Struct";
+			else girType = "Struct";
+		} else if (obj instanceof IntrospectedInterface) {
+			girType = "Interface";
+		} else if (obj instanceof IntrospectedClass) {
+			girType = "Class";
+		} else if (obj instanceof IntrospectedCallback) {
+			girType = "Callback";
+		} else {
+			// IntrospectedAlias
+			girType = "Alias";
+		}
+
+		return [{ tagName: "gir-type", paramName: "", text: girType }];
+	}
+
 	/**
 	 * Adds an info comment, is used for debugging the generated types
 	 * @param comment
@@ -693,17 +840,23 @@ export class ModuleGenerator extends FormatGenerator<string[]> {
 
 		const { parameters: inParams } = tsFunction;
 
-		if (tsFunction.doc)
-			def.push(
-				...this.addGirDocComment(
-					tsFunction.doc,
-					[
-						...this.namespace.getTsDocInParamTags(tsFunction.parameters),
-						...this.namespace.getTsDocReturnTags(tsFunction),
-					],
-					indentCount,
-				),
-			);
+		def.push(
+			...this.addGirDocComment(
+				tsFunction.doc,
+				[
+					...this.namespace.getTsDocInParamTags(tsFunction.parameters),
+					...this.namespace.getTsDocReturnTags(tsFunction),
+					...this.namespace.getTsDocMetadataTags(tsFunction.metadata),
+					...(tsFunction instanceof IntrospectedVirtualClassFunction
+						? [{ tagName: "virtual", paramName: "", text: "" } as const]
+						: []),
+					...("signalOrigin" in tsFunction && tsFunction.signalOrigin
+						? [{ tagName: "signal", paramName: "", text: "" } as const]
+						: []),
+				],
+				indentCount,
+			),
+		);
 
 		const warning = tsFunction.getWarning();
 		if (warning) def.push(warning);
@@ -775,7 +928,11 @@ export class ModuleGenerator extends FormatGenerator<string[]> {
 	) {
 		const def: string[] = [];
 
-		def.push(...this.addGirDocComment(tsCallback.doc, [], indentCount));
+		const callbackTags =
+			tsCallback instanceof IntrospectedCallback && !(tsCallback instanceof IntrospectedClassCallback)
+				? [...this.getGirTypeTags(tsCallback), ...this.namespace.getTsDocMetadataTags(tsCallback.metadata)]
+				: this.namespace.getTsDocMetadataTags(tsCallback.metadata);
+		def.push(...this.addGirDocComment(tsCallback.doc, callbackTags, indentCount));
 
 		const indent = generateIndent(indentCount);
 		const indentBody = generateIndent(indentCount + 1);
@@ -835,6 +992,8 @@ export class ModuleGenerator extends FormatGenerator<string[]> {
 		}
 
 		if (girEnum.isRegistered) {
+			const nsTags = [{ tagName: "gir-type", paramName: "", text: girEnum.flags ? "Flags" : "Enum" } as const];
+			desc.push(...this.addGirDocComment(null, nsTags, indentCount));
 			desc.push(`export namespace ${name} {`);
 			const gtypeNamespace = namespace.namespace === "GObject" ? "" : "GObject.";
 			desc.push(`    export const $gtype: ${gtypeNamespace}GType<${name}>;`);
@@ -842,7 +1001,11 @@ export class ModuleGenerator extends FormatGenerator<string[]> {
 			desc.push("");
 		}
 
-		desc.push(...this.addGirDocComment(girEnum.doc, [], indentCount));
+		const enumTags = [
+			{ tagName: "gir-type", paramName: "", text: girEnum.flags ? "Flags" : "Enum" } as const,
+			...this.namespace.getTsDocMetadataTags(girEnum.metadata),
+		];
+		desc.push(...this.addGirDocComment(girEnum.doc, enumTags, indentCount));
 		desc.push(this.generateExport("enum", name, "{", indentCount));
 		if (girEnum.members) {
 			for (const girEnumMember of girEnum.members.values()) {
@@ -875,7 +1038,9 @@ export class ModuleGenerator extends FormatGenerator<string[]> {
 	generateConst(tsConst: IntrospectedConstant, indentCount = 0) {
 		const desc: string[] = [];
 
-		desc.push(...this.addGirDocComment(tsConst.doc, [], indentCount));
+		desc.push(
+			...this.addGirDocComment(tsConst.doc, this.namespace.getTsDocMetadataTags(tsConst.metadata), indentCount),
+		);
 
 		const indent = generateIndent(indentCount);
 		const exp = !this.config.noNamespace ? "" : "export ";
@@ -892,6 +1057,14 @@ export class ModuleGenerator extends FormatGenerator<string[]> {
 
 		const desc: string[] = [];
 
+		desc.push(
+			...this.addGirDocComment(
+				girAlias.doc,
+				[...this.getGirTypeTags(girAlias), ...this.namespace.getTsDocMetadataTags(girAlias.metadata)],
+				indentCount,
+			),
+		);
+
 		const indent = generateIndent(indentCount);
 
 		const genericList = girAlias.generics
@@ -1000,33 +1173,6 @@ export class ModuleGenerator extends FormatGenerator<string[]> {
 		return def;
 	}
 
-	generateClassSignalsProperty(girClass: IntrospectedClass | IntrospectedRecord, indentCount = 1) {
-		const def: string[] = [];
-
-		// Add instance $signals property for type-safe signal access (compile-time only)
-		const isGObjectObject = girClass.name === "Object" && girClass.namespace.namespace === "GObject";
-		const hasGObjectParent =
-			isGObjectObject ||
-			girClass.someParent((p: IntrospectedBaseClass) => p.namespace.namespace === "GObject" && p.name === "Object");
-
-		if (hasGObjectParent) {
-			def.push(
-				"",
-				`${generateIndent(indentCount)}/**`,
-				`${generateIndent(indentCount)} * Compile-time signal type information.`,
-				`${generateIndent(indentCount)} *`,
-				`${generateIndent(indentCount)} * This instance property is generated only for TypeScript type checking.`,
-				`${generateIndent(indentCount)} * It is not defined at runtime and should not be accessed in JS code.`,
-				`${generateIndent(indentCount)} * @internal`,
-				`${generateIndent(indentCount)} */`,
-				`${generateIndent(indentCount)}$signals: ${girClass.name}.SignalSignatures;`,
-				"",
-			);
-		}
-
-		return def;
-	}
-
 	generateClassMemberFields(girClass: IntrospectedClass | IntrospectedRecord | IntrospectedInterface, indentCount = 1) {
 		const def: string[] = [];
 
@@ -1272,219 +1418,6 @@ export class ModuleGenerator extends FormatGenerator<string[]> {
 		return `${method.name}(${params}):${returnType}`;
 	}
 
-	generateClassSignalInterfaces(girClass: IntrospectedClass, indentCount = 0) {
-		const def: string[] = [];
-		const _tsSignals = girClass.signals;
-
-		// No separate callback interfaces generated. All callback types are inlined directly in SignalSignatures.
-
-		// Always generate SignalSignatures interface for proper inheritance
-		def.push(...this.generateSignalSignatures(girClass, indentCount));
-
-		return def;
-	}
-
-	/**
-	 * Generate SignalSignatures interface for type-safe signal handling
-	 *
-	 * This creates a comprehensive mapping of signal names to their callback types,
-	 * enabling TypeScript to provide proper type checking and IntelliSense for
-	 * GObject signals using the centralized getAllSignals() method from the model.
-	 */
-	generateSignalSignatures(girClass: IntrospectedClass, indentCount = 0): string[] {
-		const def: string[] = [];
-		const indent = generateIndent(indentCount);
-
-		// Generate SignalSignatures interface to maintain type inheritance chain
-		def.push(`${indent}// Signal signatures`);
-		def.push(`${indent}interface SignalSignatures`);
-
-		// Build inheritance chain for signal signatures
-		const parentSignatures: string[] = [];
-
-		// Inherit signal signatures from parent class
-		const parentResolution = girClass.resolveParents().extends();
-		if (parentResolution && parentResolution.node instanceof IntrospectedClass) {
-			const parentClass = parentResolution.node as IntrospectedClass;
-			const parentTypeIdentifier = parentResolution.identifier
-				.resolveIdentifier(this.namespace, this.config)
-				?.print(this.namespace, this.config);
-
-			// Include parent signals unless it's a template workaround class
-			const hasSignalMethods = parentClass.signals?.length > 0;
-			const isNotTemplateWorkaround = !(
-				this.namespace.namespace === "Gimp" && ["ParamObject", "ParamItem", "ParamArray"].includes(parentClass.name)
-			);
-
-			if (parentTypeIdentifier && (hasSignalMethods || isNotTemplateWorkaround)) {
-				parentSignatures.push(`${parentTypeIdentifier}.SignalSignatures`);
-			}
-		}
-
-		// Inherit signal signatures from implemented interfaces
-		const interfaceSignatures = girClass
-			.resolveParents()
-			.implements()
-			.filter((iface) => iface.node instanceof IntrospectedInterface)
-			.filter((iface) => {
-				// Only include interfaces that actually define signals
-				const node = iface.node as unknown as { signals?: unknown[] };
-				return node.signals && node.signals.length > 0;
-			})
-			.map((iface) => {
-				const interfaceTypeIdentifier = iface.identifier
-					.resolveIdentifier(this.namespace, this.config)
-					?.print(this.namespace, this.config);
-				return interfaceTypeIdentifier ? `${interfaceTypeIdentifier}.SignalSignatures` : null;
-			})
-			.filter((sig): sig is string => !!sig);
-
-		parentSignatures.push(...interfaceSignatures);
-
-		// Apply inheritance or fallback to base GObject signals
-		if (parentSignatures.length > 0) {
-			def.push(` extends ${parentSignatures.join(", ")} {`);
-		} else {
-			// Handle root GObject.Object class to avoid circular references
-			const isGObjectObject = girClass.name === "Object" && girClass.namespace.namespace === "GObject";
-
-			if (isGObjectObject) {
-				def.push(" {");
-			} else {
-				// All other classes inherit from GObject.Object's signal signatures as fallback
-				const gobjectNamespace = this.namespace.assertInstalledImport("GObject");
-				const gobjectObjectClass = gobjectNamespace.assertClass("Object");
-				const gobjectRef = gobjectObjectClass
-					.getType()
-					.resolveIdentifier(this.namespace, this.config)
-					?.print(this.namespace, this.config);
-
-				const fallbackRef = gobjectRef ? `${gobjectRef}.SignalSignatures` : "GObject.Object.SignalSignatures";
-				def.push(` extends ${fallbackRef} {`);
-			}
-		}
-
-		// Use the centralized getAllSignals method from the model
-		const allSignals = girClass.getAllSignals();
-
-		allSignals.forEach((signalInfo) => {
-			// Ensure valid TypeScript property names by quoting invalid identifiers
-			const signalKey = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/.test(signalInfo.name) ? signalInfo.name : `"${signalInfo.name}"`;
-
-			let cbType: string;
-
-			if (signalInfo.isNotifySignal) {
-				// Property notification signals have a standard signature
-				const gobjectRef = this.namespace.namespace === "GObject" ? "" : "GObject.";
-				cbType = `(pspec: ${gobjectRef}ParamSpec) => void`;
-			} else if (signalInfo.signal) {
-				// Regular signals - use the signal's parameters and return type
-				const paramTypes = signalInfo.signal.parameters
-					.map((p, idx) => `arg${idx}: ${this.generateType(p.type)}`)
-					.join(", ");
-
-				// For boolean return types, allow boolean | void for flexibility
-				let returnType = signalInfo.signal.return_type;
-				if (signalInfo.signal.return_type.equals(BooleanType)) {
-					returnType = new BinaryType(BooleanType, VoidType);
-				}
-				const returnTypeStr = this.generateType(returnType);
-
-				cbType = `(${paramTypes}) => ${returnTypeStr}`;
-			} else {
-				// Fallback for custom signal types
-				const paramTypes = signalInfo.parameterTypes?.map((type, idx) => `arg${idx}: ${type}`) || [];
-				const returnTypeStr = signalInfo.returnType || "void";
-				cbType = `(${paramTypes.join(", ")}) => ${returnTypeStr}`;
-			}
-
-			def.push(`${indent}    ${signalKey}: ${cbType};`);
-		});
-
-		def.push(`${indent}}`);
-		def.push("");
-
-		return def;
-	}
-
-	generateSignals(girClass: IntrospectedClass) {
-		// Create IntrospectedClassFunction instances for the signal methods
-		// These represent the GObject signal methods that we want to generate
-		const signalFunctions = [
-			new IntrospectedClassFunction({
-				name: "connect",
-				parent: girClass,
-				parameters: [],
-				return_type: NumberType,
-			}),
-			new IntrospectedClassFunction({
-				name: "connect_after",
-				parent: girClass,
-				parameters: [],
-				return_type: NumberType,
-			}),
-			new IntrospectedClassFunction({
-				name: "emit",
-				parent: girClass,
-				parameters: [],
-				return_type: VoidType,
-			}),
-		];
-
-		// Filter out signal methods that conflict with existing methods in the class or parent classes
-		// For example, if a class already has a connect() method (like Camel.Service), we don't generate
-		// the signal connect() method to avoid conflicts
-		const filteredFunctions = filterConflicts(girClass.namespace, girClass, signalFunctions, FilterBehavior.DELETE);
-
-		// Get the names of methods that should be kept (non-conflicting)
-		const allowedNames = new Set(filteredFunctions.map((f) => f.name));
-
-		const gobjectRef = this.namespace.namespace === "GObject" ? "" : "GObject.";
-
-		// Generate only the non-conflicting type-safe signal methods
-		const methods: string[] = [];
-
-		if (allowedNames.has("connect")) {
-			methods.push(
-				// Type-safe overload for known signals
-				`connect<K extends keyof ${girClass.name}.SignalSignatures>(signal: K, callback: ${gobjectRef}SignalCallback<this, ${girClass.name}.SignalSignatures[K]>): number;`,
-				// Fallback overload for dynamic signals
-				"connect(signal: string, callback: (...args: any[]) => any): number;",
-			);
-		}
-
-		if (allowedNames.has("connect_after")) {
-			methods.push(
-				// Type-safe overload for known signals
-				`connect_after<K extends keyof ${girClass.name}.SignalSignatures>(signal: K, callback: ${gobjectRef}SignalCallback<this, ${girClass.name}.SignalSignatures[K]>): number;`,
-				// Fallback overload for dynamic signals
-				"connect_after(signal: string, callback: (...args: any[]) => any): number;",
-			);
-		}
-
-		if (allowedNames.has("emit")) {
-			// Fix: Use a conditional type to extract parameters from the signal signature
-			methods.push(
-				// Type-safe overload for known signals
-				`emit<K extends keyof ${girClass.name}.SignalSignatures>(signal: K, ...args: ${gobjectRef}GjsParameters<${girClass.name}.SignalSignatures[K]> extends [any, ...infer Q] ? Q : never): void;`,
-				// Fallback overload for dynamic signals
-				"emit(signal: string, ...args: any[]): void;",
-			);
-		}
-
-		return methods;
-	}
-
-	generateClassSignals(girClass: IntrospectedClass) {
-		const def: string[] = [];
-
-		const signalDescs = this.generateSignals(girClass);
-
-		def.push(...mergeDescs(signalDescs, "Signals", 1));
-
-		return def;
-	}
-
 	generateClassNamespaces(girClass: IntrospectedClass | IntrospectedRecord | IntrospectedInterface, indentCount = 0) {
 		const def: string[] = [];
 		const bodyDef: string[] = [];
@@ -1495,7 +1428,7 @@ export class ModuleGenerator extends FormatGenerator<string[]> {
 
 		if (girClass instanceof IntrospectedClass) {
 			// Signal interfaces
-			bodyDef.push(...this.generateClassSignalInterfaces(girClass, indentCount + 1));
+			bodyDef.push(...this.signalGenerator.generateClassSignalInterfaces(girClass, indentCount + 1));
 		}
 
 		if (girClass instanceof IntrospectedInterface) {
@@ -1580,6 +1513,18 @@ export class ModuleGenerator extends FormatGenerator<string[]> {
 
 		const ext = implementationNames.length ? ` extends ${implementationNames.join(", ")}` : "";
 		const interfaceHead = `${girClass.name}${genericParameters}${ext}`;
+
+		// Add @gir-type doc comment for interfaces (classes/records handle this in generateClass)
+		if (girClass instanceof IntrospectedInterface) {
+			def.push(
+				...this.addGirDocComment(
+					girClass.doc,
+					[...this.getGirTypeTags(girClass), ...this.namespace.getTsDocMetadataTags(girClass.metadata)],
+					0,
+				),
+			);
+		}
+
 		def.push(this.generateExport("interface", interfaceHead, "{"));
 
 		if (girClass.__ts__indexSignature) {
@@ -1745,7 +1690,13 @@ export class ModuleGenerator extends FormatGenerator<string[]> {
 
 		def.push(...this.generateClassNamespaces(girClass));
 
-		def.push(...this.addGirDocComment(girClass.doc, [], 0));
+		def.push(
+			...this.addGirDocComment(
+				girClass.doc,
+				[...this.getGirTypeTags(girClass), ...this.namespace.getTsDocMetadataTags(girClass.metadata)],
+				0,
+			),
+		);
 
 		const genericParameters = this.generateGenericParameters(girClass.generics);
 		const ext = this.extends(girClass);
@@ -1774,7 +1725,7 @@ export class ModuleGenerator extends FormatGenerator<string[]> {
 			def.push(...this.generateClassProperties(girClass));
 
 			// $signals property (instance property for type-safe signal access)
-			def.push(...this.generateClassSignalsProperty(girClass));
+			def.push(...this.signalGenerator.generateClassSignalsProperty(girClass));
 
 			// Static and member Fields
 			def.push(...this.generateClassFields(girClass));
@@ -1784,7 +1735,7 @@ export class ModuleGenerator extends FormatGenerator<string[]> {
 
 			if (girClass instanceof IntrospectedClass) {
 				// Signals
-				def.push(...this.generateClassSignals(girClass));
+				def.push(...this.signalGenerator.generateClassSignals(girClass));
 			}
 
 			// Static Methods
@@ -1797,27 +1748,45 @@ export class ModuleGenerator extends FormatGenerator<string[]> {
 			def.push(...this.generateClassMethods(girClass));
 
 			if (girClass instanceof IntrospectedClass) {
-				const implementedProperties = girClass.implementedProperties().map((prop) => prop.copy({ parent: girClass }));
-				const implementedMethods = girClass
-					.implementedMethods(implementedProperties)
-					.map((method) => method.copy({ parent: girClass }));
-
-				const generatedImplementedProperties = filterConflicts(
-					girClass.namespace,
-					girClass,
-					implementedProperties,
-				).flatMap((m) => m.asString(this));
-
-				if (generatedImplementedProperties.length > 0)
-					def.push("\n// Inherited properties", ...generatedImplementedProperties);
-
-				const filteredImplMethods = promisifyIfEnabled(
-					this.options,
-					filterFunctionConflict(girClass.namespace, girClass, implementedMethods, []),
-				);
-				const generatedImplementedMethods = filteredImplMethods.flatMap((m) => m.asString(this));
+				const rawProperties = girClass.implementedProperties();
+				const rawMethods = girClass.implementedMethods(rawProperties);
+				const selfName = `${girClass.namespace.namespace}.${girClass.name}`;
+
+				// Group inherited properties by source interface
+				const propsBySource = groupBySource(rawProperties);
+				for (const [source, props] of propsBySource) {
+					const copied = props.map((p) => p.copy({ parent: girClass }));
+					for (const m of filterConflicts(girClass.namespace, girClass, copied)) {
+						const memberLines = m.asString(this);
+						if (memberLines.length > 0) {
+							// Only tag as inherited if source is a different class
+							if (source !== selfName) {
+								injectInheritedTags(memberLines, source);
+							}
+							def.push(...memberLines);
+						}
+					}
+				}
 
-				if (generatedImplementedMethods.length > 0) def.push("\n// Inherited methods", ...generatedImplementedMethods);
+				// Group inherited methods by source interface
+				const methodsBySource = groupBySource(rawMethods);
+				for (const [source, methods] of methodsBySource) {
+					const copied = methods.map((m) => m.copy({ parent: girClass }));
+					const filtered = promisifyIfEnabled(
+						this.options,
+						filterFunctionConflict(girClass.namespace, girClass, copied, []),
+					);
+					for (const m of filtered) {
+						const memberLines = m.asString(this);
+						if (memberLines.length > 0) {
+							// Only tag as inherited if source is a different class
+							if (source !== selfName) {
+								injectInheritedTags(memberLines, source);
+							}
+							def.push(...memberLines);
+						}
+					}
+				}
 			}
 			// END BODY
 
@@ -1901,126 +1870,6 @@ export class ModuleGenerator extends FormatGenerator<string[]> {
 		}
 	}
 
-	async exportModuleIndexJS(): Promise<void> {
-		const template = "index.js";
-		const target = "index.js";
-
-		if (this.config.outdir) {
-			await this.moduleTemplateProcessor.create(template, this.config.outdir, target);
-		} else {
-			const { append, prepend } = await this.moduleTemplateProcessor.load(template);
-			this.log.log(append + prepend);
-		}
-	}
-
-	async exportModuleIndexTS(): Promise<void> {
-		const template = "index.d.ts";
-		const target = "index.d.ts";
-
-		if (this.config.outdir) {
-			await this.moduleTemplateProcessor.create(template, this.config.outdir, target);
-		} else {
-			const { append, prepend } = await this.moduleTemplateProcessor.load(template);
-			this.log.log(append + prepend);
-		}
-	}
-
-	async exportModuleJS(girModule: GirModule): Promise<void> {
-		const template = "module.js";
-		const target = `${girModule.importName}.js`;
-
-		if (this.config.outdir) {
-			await this.moduleTemplateProcessor.create(template, this.config.outdir, target);
-		} else {
-			const { append, prepend } = await this.moduleTemplateProcessor.load(template);
-			this.log.log(append + prepend);
-		}
-	}
-
-	async exportModuleAmbientTS(girModule: GirModule): Promise<void> {
-		const template = "module-ambient.d.ts";
-		const target = `${girModule.importName}-ambient.d.ts`;
-
-		if (this.config.outdir) {
-			await this.moduleTemplateProcessor.create(template, this.config.outdir, target);
-		} else {
-			const { append, prepend } = await this.moduleTemplateProcessor.load(template);
-			this.log.log(append + prepend);
-		}
-	}
-
-	protected async exportModuleAmbientJS(girModule: GirModule): Promise<void> {
-		const template = "module-ambient.js";
-		const target = `${girModule.importName}-ambient.js`;
-
-		if (this.config.outdir) {
-			await this.moduleTemplateProcessor.create(template, this.config.outdir, target);
-		} else {
-			const { append, prepend } = await this.moduleTemplateProcessor.load(template);
-			this.log.log(append + prepend);
-		}
-	}
-
-	protected async exportModuleImportTS(girModule: GirModule): Promise<void> {
-		const template = "module-import.d.ts";
-		const target = `${girModule.importName}-import.d.ts`;
-
-		if (this.config.outdir) {
-			await this.moduleTemplateProcessor.create(template, this.config.outdir, target);
-		} else {
-			const { append, prepend } = await this.moduleTemplateProcessor.load(template);
-			this.log.log(append + prepend);
-		}
-	}
-
-	protected async exportModuleImportJS(girModule: GirModule): Promise<void> {
-		const template = "module-import.js";
-		const target = `${girModule.importName}-import.js`;
-
-		if (this.config.outdir) {
-			await this.moduleTemplateProcessor.create(template, this.config.outdir, target);
-		} else {
-			const { append, prepend } = await this.moduleTemplateProcessor.load(template);
-			this.log.log(append + prepend);
-		}
-	}
-
-	async exportModuleTS(): Promise<void> {
-		const { namespace: girModule } = this;
-		const template = "module.d.ts";
-		const explicitTemplate = `${girModule.importName}.d.ts`;
-		const target = explicitTemplate;
-		const output = await this.generateModule(girModule);
-
-		if (!output) {
-			this.log.error("Failed to generate gir module");
-			return;
-		}
-
-		// Output is always an array now
-		const outputArray = output;
-
-		// Extra interfaces if a template with the module name  (e.g. '../templates/gobject-2-0.d.ts') is found
-		// E.g. used for GObject-2.0 to help define GObject classes in js;
-		// these aren't part of gi.
-		if (await this.moduleTemplateProcessor.exists(explicitTemplate)) {
-			const { append: appendExplicit, prepend: prependExplicit } =
-				await this.moduleTemplateProcessor.load(explicitTemplate);
-			outputArray.unshift(prependExplicit);
-			outputArray.push(appendExplicit);
-		}
-
-		const { append, prepend } = await this.moduleTemplateProcessor.load(template);
-		outputArray.unshift(prepend);
-		outputArray.push(append);
-
-		if (this.config.outdir) {
-			await this.moduleTemplateProcessor.write(outputArray.join("\n"), this.config.outdir, target);
-		} else {
-			this.log.log(outputArray.join("\n"));
-		}
-	}
-
 	async generateModule(girModule: GirModule): Promise<string[]> {
 		const out: string[] = [];
 
@@ -2153,32 +2002,45 @@ export class ModuleGenerator extends FormatGenerator<string[]> {
 		const result = await this.generateNamespace(girModule);
 		return result.join("\n");
 	}
+}
 
-	async exportModule(_registry: NSRegistry, girModule: GirModule) {
-		// Used for package.json and local ambient mode
-		await this.exportModuleTS();
-
-		if (this.config.package) {
-			await this.exportModuleJS(girModule);
-
-			await this.exportModuleIndexTS();
-			await this.exportModuleIndexJS();
-
-			await this.exportModuleAmbientTS(girModule);
-			await this.exportModuleAmbientJS(girModule);
-
-			await this.exportModuleImportTS(girModule);
-			await this.exportModuleImportJS(girModule);
+/**
+ * Groups items by their source interface/class name (e.g. "Gtk.Accessible").
+ * Must be called BEFORE copy({ parent: ... }) so the original parent is preserved.
+ */
+function groupBySource<T extends { parent: { namespace: { namespace: string }; name: string } }>(
+	items: T[],
+): Map<string, T[]> {
+	const groups = new Map<string, T[]>();
+	for (const item of items) {
+		const source = `${item.parent.namespace.namespace}.${item.parent.name}`;
+		const list = groups.get(source);
+		if (list) list.push(item);
+		else groups.set(source, [item]);
+	}
+	return groups;
+}
 
-			const pkg = new NpmPackage(
-				this.config,
-				this.dependencyManager,
-				_registry,
-				girModule,
-				girModule.transitiveDependencies,
-			);
-			await pkg.exportNPMPackage();
-		}
+/**
+ * Injects a `@category` TSDoc tag into generated member strings.
+ * Places the member in a subcategory "Inherited from X" within its kind group,
+ * so inherited members appear grouped after own members.
+ */
+function injectInheritedTags(lines: string[], source: string): void {
+	const category = `Inherited from ${source}`;
+	// Search backwards — `*/` is typically on the last or second-to-last line
+	let closingIdx = -1;
+	for (let i = lines.length - 1; i >= 0; i--) {
+		if (lines[i].trimEnd().endsWith("*/")) {
+			closingIdx = i;
+			break;
+		}
+	}
+	if (closingIdx >= 0) {
+		const indent = lines[closingIdx].match(/^(\s*)/)?.[1] ?? "";
+		lines.splice(closingIdx, 0, `${indent} * @category ${category}`);
+	} else {
+		lines.unshift(`/** @category ${category} */`);
 	}
 }
 

package/src/type-definition-generator.ts

@@ -84,6 +84,9 @@ export class TypeDefinitionGenerator implements Generator {
 			await templateProcessor.create("gjs/console.d.ts", config.outdir, "console.d.ts");
 			await templateProcessor.create("gjs/console.js", config.outdir, "console.js");
 
+			await templateProcessor.create("gjs/gi.d.ts", config.outdir, "gi.d.ts");
+			await templateProcessor.create("gjs/gi.js", config.outdir, "gi.js");
+
 			// Import ambient types
 			await templateProcessor.create("gjs/gjs-ambient.d.ts", config.outdir, "gjs-ambient.d.ts");
 			await templateProcessor.create("gjs/gjs-ambient.js", config.outdir, "gjs-ambient.js");
@@ -114,6 +117,9 @@ export class TypeDefinitionGenerator implements Generator {
 				"console.d.ts",
 			);
 
+			const giContent = await templateProcessor.load("gjs/gi.d.ts");
+			await templateProcessor.write(`${giContent.prepend}\n${giContent.append}`, config.outdir, "gi.d.ts");
+
 			// Additional DOM types supported by GJS
 			const domContent = await templateProcessor.load("gjs/dom.d.ts");
 			await templateProcessor.write(`${domContent.prepend}\n${domContent.append}`, config.outdir, "dom.d.ts");
@@ -144,7 +150,7 @@ export class TypeDefinitionGenerator implements Generator {
 
 	public async generate(module: GirModule) {
 		const moduleGenerator = new ModuleGenerator(module, this.config, this.registry);
-		await moduleGenerator.exportModule(this.registry, module);
+		await moduleGenerator.moduleExporter.exportModule(this.registry, module);
 	}
 
 	public async start() {