@gtkx/codegen 0.21.0

package/src/react/props.ts

@@ -0,0 +1,307 @@
+import { toCamelCase, toIdentifier, toPascalCase } from "@gtkx/utils";
+import type { GirClass } from "../gir/class.js";
+import type { GirNamespace } from "../gir/namespace.js";
+import { type GirParameter, isInoutParameter, isOutParameter } from "../gir/parameter.js";
+import type { GirProperty } from "../gir/property.js";
+import { resolveQualifiedClass, splitQualifiedName } from "../gir/qualified-name.js";
+import { qualifyTypeRef } from "../gir/qualify.js";
+import type { GirRepository } from "../gir/repository.js";
+import type { GirSignal } from "../gir/signal.js";
+import type { GirTypeRef, NamedTypeRef } from "../gir/type-ref.js";
+import { renderBaseTypeFor, type TsTypeTarget } from "../writers/ts-type.js";
+import { isScalarRef } from "../writers/value.js";
+import { signalHandlerName } from "./widgets.js";
+
+/**
+ * Rendered prop entries for a single widget's Props interface, together
+ * with imports the writer must request to keep type references valid.
+ */
+export type WidgetPropsEntries = {
+    /** Rendered prop lines, indented one level inside the interface body. */
+    readonly propLines: readonly string[];
+    /** Cross-namespace imports the writer must add to the surrounding module. */
+    readonly imports: ReadonlyMap<string, string>;
+};
+
+/**
+ * Options for {@link buildWidgetPropsEntries}.
+ */
+export type WidgetPropsOptions = {
+    /** The full GIR repository. */
+    readonly repository: GirRepository;
+    /** The widget class whose props bag is being built. */
+    readonly klass: GirClass;
+    /** Property names that should be widened to `ReactNode` slot children. */
+    readonly slotPropNames?: ReadonlySet<string>;
+    /** Returns `true` when `candidate` already has its own widget Props interface. */
+    readonly isWidgetAncestor?: (candidate: GirClass) => boolean;
+};
+
+type SignalRenderOptions = {
+    readonly repository: GirRepository;
+    readonly signal: GirSignal;
+    readonly imports: Map<string, string>;
+    readonly selfType: string;
+    readonly owningNamespace: string;
+};
+
+type ParentRef = { readonly klass: GirClass; readonly namespaceName: string };
+
+/**
+ * Builds a typed prop bag for one widget intrinsic.
+ *
+ * Combines the widget's own properties + signal handlers with those declared
+ * by its directly-implemented interfaces and by every non-widget ancestor up
+ * to the first widget parent (whose props are inherited via `extends`).
+ * Property types are written as TypeScript surface types resolved against the
+ * loaded GIR repository.
+ *
+ * @param options - {@link WidgetPropsOptions}
+ */
+export const buildWidgetPropsEntries = (options: WidgetPropsOptions): WidgetPropsEntries => {
+    const { repository, klass, slotPropNames = new Set<string>(), isWidgetAncestor = () => false } = options;
+    const imports = new Map<string, string>();
+    const propEntries: string[] = [];
+    const seen = new Set<string>();
+
+    const ownerName = klass.glibTypeName ?? klass.cType ?? klass.name;
+    const selfNamespace = currentNamespaceKey(repository, klass);
+    const selfTypeName = resolveSelfTypeName(klass, selfNamespace, imports);
+
+    const acceptProperty = (property: GirProperty, owningNamespace: string): void => {
+        const jsName = toIdentifier(toCamelCase(property.name));
+        if (seen.has(jsName)) return;
+        seen.add(jsName);
+        if (isPropOverridden(ownerName, jsName)) return;
+        if (slotPropNames.has(jsName)) {
+            propEntries.push(`${jsName}?: ReactNode | null;`);
+            return;
+        }
+        const qualified = qualifyTypeRef(property.type, owningNamespace);
+        const tsType = renderReactPropType(repository, qualified, true, imports);
+        propEntries.push(`${jsName}?: ${tsType} | null;`);
+    };
+
+    const acceptSignal = (signal: GirSignal, owningNamespace: string): void => {
+        const handlerName = signalHandlerName(signal.name);
+        if (seen.has(handlerName)) return;
+        seen.add(handlerName);
+        if (isSignalOverridden(ownerName, handlerName)) return;
+        const signature = renderSignalHandler({
+            repository,
+            signal,
+            imports,
+            selfType: selfTypeName,
+            owningNamespace,
+        });
+        propEntries.push(`${handlerName}?: ${signature};`);
+    };
+
+    visitClassAndAncestors({ repository, klass, selfNamespace, isWidgetAncestor }, acceptProperty, acceptSignal);
+
+    return { propLines: propEntries, imports };
+};
+
+const resolveSelfTypeName = (klass: GirClass, selfNamespace: string, imports: Map<string, string>): string => {
+    if (selfNamespace === "?") return toPascalCase(klass.name);
+    imports.set(selfNamespace, selfNamespace);
+    return `${selfNamespace}.${toPascalCase(klass.name)}`;
+};
+
+type WalkContext = {
+    readonly repository: GirRepository;
+    readonly klass: GirClass;
+    readonly selfNamespace: string;
+    readonly isWidgetAncestor: (candidate: GirClass) => boolean;
+};
+
+const visitClassAndAncestors = (
+    walk: WalkContext,
+    acceptProperty: (property: GirProperty, owningNamespace: string) => void,
+    acceptSignal: (signal: GirSignal, owningNamespace: string) => void,
+): void => {
+    const visit = (current: GirClass, owningNamespace: string): void => {
+        for (const property of current.properties) acceptProperty(property, owningNamespace);
+        for (const signal of current.signals) acceptSignal(signal, owningNamespace);
+        for (const implementsName of current.implements) {
+            const resolved = resolveInterface(walk.repository, current, implementsName);
+            if (resolved === undefined) continue;
+            for (const property of resolved.value.properties) acceptProperty(property, resolved.namespace.name);
+            for (const signal of resolved.value.signals) acceptSignal(signal, resolved.namespace.name);
+        }
+    };
+
+    visit(walk.klass, walk.selfNamespace);
+    const visited = new Set<string>([`${walk.selfNamespace}.${walk.klass.name}`]);
+    let parentRef = resolveParent(walk.repository, walk.klass, walk.selfNamespace);
+    while (parentRef !== undefined && !walk.isWidgetAncestor(parentRef.klass)) {
+        const key = `${parentRef.namespaceName}.${parentRef.klass.name}`;
+        if (visited.has(key)) break;
+        visited.add(key);
+        visit(parentRef.klass, parentRef.namespaceName);
+        parentRef = resolveParent(walk.repository, parentRef.klass, parentRef.namespaceName);
+    }
+};
+
+const resolveParent = (repository: GirRepository, klass: GirClass, defaultNamespace: string): ParentRef | undefined => {
+    if (klass.parent === undefined) return undefined;
+    return resolveQualifiedClass(repository, klass.parent, defaultNamespace);
+};
+
+const currentNamespaceKey = (repository: GirRepository, klass: GirClass): string => {
+    for (const namespace of repository.namespaces.values()) {
+        if (namespace.classes.includes(klass) || namespace.interfaces.includes(klass)) {
+            return namespace.name;
+        }
+    }
+    return "?";
+};
+
+const resolveInterface = (
+    repository: GirRepository,
+    declaringClass: GirClass,
+    implementsName: string,
+): { readonly namespace: GirNamespace; readonly value: GirClass } | undefined => {
+    const { namespaceName, typeName } = splitQualifiedName(
+        implementsName,
+        currentNamespaceKey(repository, declaringClass),
+    );
+    const resolved = repository.resolveNamed(namespaceName, typeName);
+    if (resolved === undefined) return undefined;
+    if (resolved.kind !== "interface") return undefined;
+    return { namespace: resolved.namespace, value: resolved.value };
+};
+
+/**
+ * Per-widget prop names that the React package re-types in a hand-written
+ * `declare module` augmentation. Skipping them in the generated bag
+ * prevents TS2717 "subsequent property declarations must have the same
+ * type" when the augmentation widens the GIR property to a declarative
+ * React shape (e.g. an array of child-props instead of a raw GObject
+ * model).
+ *
+ * Entries are matched against the widget's GLib type name (e.g.
+ * `"AdwToggleGroup"`); values are the JS prop names to skip.
+ */
+const PROP_OVERRIDES_BY_WIDGET: Readonly<Record<string, ReadonlySet<string>>> = {
+    AdwToggleGroup: new Set(["toggles"]),
+    AdwAlertDialog: new Set(["responses"]),
+    GtkColumnView: new Set(["columns"]),
+    GtkScale: new Set(["marks"]),
+};
+
+const isPropOverridden = (ownerName: string, propName: string): boolean => {
+    const overrides = PROP_OVERRIDES_BY_WIDGET[ownerName];
+    return overrides?.has(propName) ?? false;
+};
+
+/**
+ * Per-widget signal-handler names whose generated emission is skipped so
+ * a hand-written `declare module` augmentation can supply a refined
+ * signature without triggering TS2717.
+ */
+const SIGNAL_OVERRIDES_BY_WIDGET: Readonly<Record<string, ReadonlySet<string>>> = {
+    GtkRange: new Set(["onValueChanged"]),
+    GtkScale: new Set(["onValueChanged"]),
+    GtkScaleButton: new Set(["onValueChanged"]),
+    GtkSpinButton: new Set(["onValueChanged"]),
+    AdwSpinRow: new Set(["onValueChanged"]),
+    AdwSwitchRow: new Set(["onActivated"]),
+};
+
+const isSignalOverridden = (ownerName: string, handlerName: string): boolean => {
+    const overrides = SIGNAL_OVERRIDES_BY_WIDGET[ownerName];
+    return overrides?.has(handlerName) ?? false;
+};
+
+const renderSignalHandler = (options: SignalRenderOptions): string => {
+    const { repository, signal, imports, selfType, owningNamespace } = options;
+    const visible = signal.parameters.filter((parameter) => !parameter.isVarargs);
+    const params = visible
+        .filter((parameter) => !isOutParameter(parameter))
+        .map((parameter, index) => {
+            const name = parameter.name.length === 0 ? `arg${index + 1}` : toIdentifier(toCamelCase(parameter.name));
+            const qualified = qualifyTypeRef(parameter.type, owningNamespace);
+            const baseType = renderReactPropType(repository, qualified, false, imports);
+            return `${name}: ${baseType}`;
+        });
+    params.push(`self: ${selfType}`);
+    return `(${params.join(", ")}) => ${renderSignalReturnType(options, visible)}`;
+};
+
+/**
+ * Computes a signal handler's return type.
+ *
+ * Pure out-parameters (`direction="out"`, not caller-allocated) are surfaced
+ * through the return value as a tuple `[primary, ...outs]`, mirroring the
+ * convention {@link renderMethodReturnType} produces for methods: a value return
+ * with no outs stays scalar (with `| void` so handlers may opt out); a void
+ * return with a single out unwraps to that out's type; otherwise the primary
+ * (when present) leads a tuple of the out types.
+ *
+ * @param options - The signal render options
+ * @param visible - The signal's non-varargs parameters
+ */
+const renderSignalReturnType = (options: SignalRenderOptions, visible: readonly GirParameter[]): string => {
+    const { repository, signal, imports, owningNamespace } = options;
+    const qualifiedReturn = qualifyTypeRef(signal.returnValue.type, owningNamespace);
+    const baseReturn = renderReactPropType(repository, qualifiedReturn, signal.returnValue.nullable, imports);
+    const outTypes = visible
+        .filter(
+            (parameter) =>
+                isOutParameter(parameter) ||
+                (isInoutParameter(parameter) && isScalarRef(repository, owningNamespace, parameter.type)),
+        )
+        .map((parameter) =>
+            renderReactPropType(repository, qualifyTypeRef(parameter.type, owningNamespace), false, imports),
+        );
+    if (outTypes.length === 0) {
+        return baseReturn === "void" ? "void" : `${baseReturn} | void`;
+    }
+    if (baseReturn !== "void") {
+        return `[${baseReturn}, ${outTypes.join(", ")}]`;
+    }
+    const [single, ...rest] = outTypes;
+    if (rest.length === 0 && single !== undefined) return single;
+    return `[${outTypes.join(", ")}]`;
+};
+
+const reactTarget = (repository: GirRepository, imports: Map<string, string>): TsTypeTarget => ({
+    containerStyle: "record",
+    callbackType: "(...args: unknown[]) => unknown",
+    byteArrayAsNumber: false,
+    renderNamed: (ref) => namedTsType(repository, ref, imports),
+});
+
+const renderReactPropType = (
+    repository: GirRepository,
+    ref: GirTypeRef | undefined,
+    isNullable: boolean,
+    imports: Map<string, string>,
+): string => {
+    const base = renderBaseTypeFor(reactTarget(repository, imports), ref);
+    return isNullable ? `${base} | null` : base;
+};
+
+const namedTsType = (repository: GirRepository, ref: NamedTypeRef, imports: Map<string, string>): string => {
+    const namespaceName = ref.namespaceName;
+    if (namespaceName === undefined) {
+        return ref.typeName;
+    }
+    const resolved = repository.resolveNamed(namespaceName, ref.typeName);
+    if (resolved === undefined) {
+        imports.set(namespaceName, namespaceName);
+        return `${namespaceName}.${ref.typeName}`;
+    }
+    if (resolved.kind === "callback") return "(...args: unknown[]) => unknown";
+    if (resolved.kind === "alias") {
+        if (resolved.target === undefined) return "number";
+        return namedTsType(
+            repository,
+            { kind: "named", namespaceName: resolved.namespace.name, typeName: resolved.target, cType: undefined },
+            imports,
+        );
+    }
+    imports.set(namespaceName, namespaceName);
+    return `${namespaceName}.${ref.typeName}`;
+};

package/src/react/slot-props.ts

@@ -0,0 +1,57 @@
+/**
+ * Built-in widget-typed properties that should be exposed as JSX child
+ * slots (typed as `ReactNode`) rather than as raw widget refs.
+ *
+ * The keys are JSX element names (i.e. GLib type names such as
+ * `"AdwWindow"`, `"GtkHeaderBar"`); the values are the camelCase property
+ * names that should be promoted. User-supplied `slotProps` from
+ * `gtkx.config.ts` merge into this map.
+ */
+const BUILT_IN_SLOT_PROPS: Readonly<Record<string, readonly string[]>> = Object.freeze({
+    GtkWindow: ["titlebar"],
+    AdwWindow: ["content"],
+    AdwApplicationWindow: ["content"],
+    AdwAlertDialog: ["extraChild"],
+    AdwBottomSheet: ["bottomBar", "content", "sheet"],
+    GtkCenterBox: ["centerWidget", "endWidget", "startWidget"],
+    GtkExpander: ["labelWidget"],
+    AdwFlap: ["content", "flap", "separator"],
+    GtkFrame: ["labelWidget"],
+    GtkHeaderBar: ["titleWidget"],
+    AdwHeaderBar: ["titleWidget"],
+    GtkMenuButton: ["popover"],
+    AdwMessageDialog: ["extraChild"],
+    AdwNavigationSplitView: ["content", "sidebar"],
+    AdwOverlaySplitView: ["content", "sidebar"],
+    GtkPaned: ["endChild", "startChild"],
+    AdwPreferencesGroup: ["headerSuffix"],
+    AdwPreferencesPage: ["banner"],
+    AdwSplitButton: ["popover"],
+    AdwTabBar: ["endActionWidget", "startActionWidget"],
+    AdwToolbarView: ["content"],
+});
+
+/**
+ * Merges built-in slot props with the user-supplied `slotProps` map.
+ *
+ * Per JSX element name, the resulting list is the union of both sources
+ * with duplicates removed and a stable alphabetical sort.
+ *
+ * @param userSlotProps - The user-provided `slotProps` map, or `undefined`
+ */
+export const mergeSlotProps = (
+    userSlotProps: Readonly<Record<string, readonly string[]>> | undefined,
+): Readonly<Record<string, readonly string[]>> => {
+    const result: Record<string, string[]> = {};
+    for (const [key, values] of Object.entries(BUILT_IN_SLOT_PROPS)) {
+        result[key] = [...values];
+    }
+    if (userSlotProps !== undefined) {
+        for (const [key, values] of Object.entries(userSlotProps)) {
+            const merged = new Set<string>(result[key] ?? []);
+            for (const value of values) merged.add(value);
+            result[key] = [...merged].sort((a, b) => a.localeCompare(b));
+        }
+    }
+    return result;
+};

package/src/react/widgets.ts

@@ -0,0 +1,185 @@
+import { toCamelCase, toIdentifier, toUpperFirst } from "@gtkx/utils";
+import type { GirClass } from "../gir/class.js";
+import type { GirNamespace } from "../gir/namespace.js";
+import { splitQualifiedName } from "../gir/qualified-name.js";
+import type { GirRepository } from "../gir/repository.js";
+
+/**
+ * Maps a kebab-case signal name to its `on`-prefixed camelCase handler prop
+ * name (e.g. `value-changed` → `onValueChanged`).
+ *
+ * @param signalName - The GIR signal name
+ */
+export const signalHandlerName = (signalName: string): string =>
+    `on${toUpperFirst(toIdentifier(toCamelCase(signalName)))}`;
+
+/** A class qualified by its declaring namespace and the GLib type name it exposes. */
+export type WidgetCandidate = {
+    readonly glibName: string;
+    readonly klass: GirClass;
+    readonly namespace: GirNamespace;
+};
+
+/**
+ * Iterates every `(class, namespace, glibName)` triple in the repository whose
+ * `glib:type-name` (or C type fallback) is defined.
+ *
+ * The order follows GIR file order within a namespace and `namespaces` map
+ * iteration order between namespaces; callers that need stable output should
+ * sort the result themselves.
+ *
+ * @param repository - The repository to walk
+ */
+export function* iterateClassesWithGlibName(repository: GirRepository): IterableIterator<WidgetCandidate> {
+    for (const namespace of repository.namespaces.values()) {
+        for (const klass of namespace.classes) {
+            const glibName = klass.glibTypeName ?? klass.cType;
+            if (glibName === undefined) continue;
+            yield { glibName, klass, namespace };
+        }
+    }
+}
+
+const resolveParentClass = (
+    repository: GirRepository,
+    parent: string,
+    namespace: GirNamespace,
+): { readonly klass: GirClass; readonly namespace: GirNamespace } | undefined => {
+    const { namespaceName, typeName } = splitQualifiedName(parent, namespace.name);
+    const resolved = repository.resolveNamed(namespaceName, typeName);
+    if (resolved === undefined || (resolved.kind !== "class" && resolved.kind !== "interface")) return undefined;
+    return { klass: resolved.value, namespace: resolved.namespace };
+};
+
+/** A resolved interface qualified by the namespace that declares it. */
+export type ResolvedQualifiedInterface = { readonly klass: GirClass; readonly namespace: GirNamespace };
+
+/**
+ * Resolves every interface a class implements, including the transitive
+ * prerequisite interfaces of those interfaces, nearest first.
+ *
+ * Interfaces never appear in the GObject type-parent chain, so the React
+ * runtime cannot reach an interface's signals or properties by walking a
+ * widget's ancestors. Each implementing class must therefore carry its
+ * interfaces' metadata directly. Prerequisite interfaces (e.g. a
+ * `Gtk.SelectionModel`'s `Gio.ListModel`) are folded in transitively; class
+ * prerequisites are ignored because their metadata is reachable through the
+ * type-parent chain.
+ *
+ * @param klass - The class whose interfaces to resolve
+ * @param namespace - The namespace the class lives in
+ * @param repository - The repository for cross-namespace lookups
+ */
+export const implementedInterfaces = (
+    klass: GirClass,
+    namespace: GirNamespace,
+    repository: GirRepository,
+): readonly ResolvedQualifiedInterface[] => {
+    const result: ResolvedQualifiedInterface[] = [];
+    const visited = new Set<string>();
+    const visit = (names: readonly string[], fromNamespace: GirNamespace): void => {
+        for (const name of names) {
+            const { namespaceName, typeName } = splitQualifiedName(name, fromNamespace.name);
+            const resolved = repository.resolveNamed(namespaceName, typeName);
+            if (resolved === undefined || resolved.kind !== "interface") continue;
+            const key = `${resolved.namespace.name}.${resolved.value.name}`;
+            if (visited.has(key)) continue;
+            visited.add(key);
+            result.push({ klass: resolved.value, namespace: resolved.namespace });
+            visit(resolved.value.prerequisites, resolved.namespace);
+        }
+    };
+    visit(klass.implements, namespace);
+    return result;
+};
+
+/**
+ * Returns the GLib type names of a class and every ancestor it descends from,
+ * nearest first. Used to let a subclass inherit slot-prop declarations made on
+ * its ancestors.
+ *
+ * @param klass - The class to start from
+ * @param namespace - The namespace the class lives in
+ * @param repository - The repository for cross-namespace parent lookups
+ */
+export const ancestorGlibNames = (
+    klass: GirClass,
+    namespace: GirNamespace,
+    repository: GirRepository,
+): readonly string[] => {
+    const names: string[] = [];
+    let currentClass: GirClass | undefined = klass;
+    let currentNamespace: GirNamespace | undefined = namespace;
+    while (currentClass !== undefined && currentNamespace !== undefined) {
+        const glibName = currentClass.glibTypeName ?? currentClass.cType;
+        if (glibName !== undefined) names.push(glibName);
+        if (currentClass.parent === undefined) break;
+        const next = resolveParentClass(repository, currentClass.parent, currentNamespace);
+        if (next === undefined) break;
+        currentClass = next.klass;
+        currentNamespace = next.namespace;
+    }
+    return names;
+};
+
+const descendsFrom = (
+    klass: GirClass,
+    namespace: GirNamespace,
+    repository: GirRepository,
+    matches: (glibName: string) => boolean,
+): boolean => {
+    let currentClass: GirClass | undefined = klass;
+    let currentNamespace: GirNamespace | undefined = namespace;
+    while (currentClass !== undefined && currentNamespace !== undefined) {
+        const glibName = currentClass.glibTypeName ?? currentClass.cType ?? "";
+        if (matches(glibName)) return true;
+        if (currentClass.parent === undefined) return false;
+        const next = resolveParentClass(repository, currentClass.parent, currentNamespace);
+        if (next === undefined) return false;
+        currentClass = next.klass;
+        currentNamespace = next.namespace;
+    }
+    return false;
+};
+
+/**
+ * Decides whether a `<class>` is a "widget" for the React reconciler — a
+ * descendant (direct or transitive) of `GtkWidget`.
+ *
+ * Walks the parent chain across namespaces. Returns `false` if any
+ * ancestor cannot be resolved (which is preferable to silently treating
+ * an unknown type as a widget).
+ *
+ * @param klass - The class to inspect
+ * @param namespace - The namespace the class lives in
+ * @param repository - The repository for cross-namespace parent lookups
+ */
+export const isWidgetClass = (klass: GirClass, namespace: GirNamespace, repository: GirRepository): boolean =>
+    descendsFrom(klass, namespace, repository, (glibName) => glibName === "GtkWidget");
+
+const AUXILIARY_BASE_TYPES: ReadonlySet<string> = new Set(["GtkEventController", "GtkGesture", "GtkLayoutManager"]);
+
+/**
+ * Decides whether a `<class>` is a non-widget React reconciler node — an event
+ * controller, gesture, or layout manager (direct or transitive descendant of
+ * `GtkEventController`, `GtkGesture`, or `GtkLayoutManager`). These are JSX
+ * elements that need the same prop/signal metadata as widgets.
+ *
+ * @param klass - The class to inspect
+ * @param namespace - The namespace the class lives in
+ * @param repository - The repository for cross-namespace parent lookups
+ */
+const isAuxiliaryReactType = (klass: GirClass, namespace: GirNamespace, repository: GirRepository): boolean =>
+    descendsFrom(klass, namespace, repository, (glibName) => AUXILIARY_BASE_TYPES.has(glibName));
+
+/**
+ * Decides whether a `<class>` is any React reconciler node — a widget or one
+ * of the auxiliary node kinds. This is the set of classes that need generated
+ * prop, signal, and construct-only metadata.
+ *
+ * @param klass - The class to inspect
+ * @param namespace - The namespace the class lives in
+ * @param repository - The repository for cross-namespace parent lookups
+ */
+export const isReactNodeClass = (klass: GirClass, namespace: GirNamespace, repository: GirRepository): boolean =>
+    isWidgetClass(klass, namespace, repository) || isAuxiliaryReactType(klass, namespace, repository);

package/src/runner.ts

@@ -0,0 +1,89 @@
+import { generateNamespaceModule } from "./ffi/pipeline.js";
+import { computeFingerprint } from "./fingerprint.js";
+import { type GiNamespaceInput, type GiStoreOptions, writeGiStore } from "./gi-store.js";
+import { loadGirRepository } from "./gir/repository.js";
+import { type JsxStoreOptions, writeJsxStore } from "./jsx-store.js";
+import { generateReactFiles } from "./react/pipeline.js";
+
+/**
+ * Options for {@link CodegenRunner}.
+ */
+export type CodegenRunnerOptions = {
+    /** Resolved `Name-Version` namespace identifiers to generate. */
+    readonly libraries: readonly string[];
+    /** Directories searched for `.gir` files. */
+    readonly girPath: readonly string[];
+    /** Optional user slot-prop overrides keyed by JSX element name. */
+    readonly slotProps?: Readonly<Record<string, readonly string[]>>;
+    /** Target for the injected `@gtkx/gi` bindings package. */
+    readonly gi: GiStoreOptions;
+    /** Target for the injected `@gtkx/react-jsx` unit; React is skipped when omitted. */
+    readonly jsx?: JsxStoreOptions;
+};
+
+/**
+ * Result returned from {@link CodegenRunner.run}.
+ */
+export type CodegenRunnerResult = {
+    /** Number of FFI namespaces produced. */
+    readonly namespaces: number;
+    /** Number of widget intrinsics emitted into `jsx.ts`. */
+    readonly widgets: number;
+    /** Wall-clock duration in milliseconds. */
+    readonly duration: number;
+};
+
+/**
+ * Single-entry orchestrator for the GTKX codegen.
+ *
+ * Loads the GIR repository, runs the FFI pipeline per namespace, runs the
+ * React pipeline once, and materializes the self-contained `@gtkx/gi` (and
+ * optional `@gtkx/react-jsx`) packages into the project's `node_modules`.
+ *
+ * @example
+ * ```ts
+ * import { CodegenRunner } from "@gtkx/codegen";
+ *
+ * await new CodegenRunner({
+ *     libraries: ["Gtk-4.0", "Adw-1"],
+ *     girPath: ["/usr/share/gir-1.0"],
+ *     gi: { storeDir, linkDir, realFfiDir, realNativeDir, version },
+ * }).run();
+ * ```
+ */
+export class CodegenRunner {
+    constructor(private readonly options: CodegenRunnerOptions) {}
+
+    /**
+     * Executes the full codegen pipeline and materializes the output packages.
+     */
+    async run(): Promise<CodegenRunnerResult> {
+        const start = Date.now();
+        const repository = loadGirRepository(this.options.libraries, this.options.girPath);
+
+        const namespaces: GiNamespaceInput[] = [];
+        for (const namespace of repository.namespaces.values()) {
+            const { source } = generateNamespaceModule(namespace, repository);
+            namespaces.push({ directory: namespace.name.toLowerCase(), rawSource: source });
+        }
+        const libraries = [...this.options.libraries];
+        writeGiStore(this.options.gi, namespaces, {
+            value: computeFingerprint(repository.girFiles, libraries),
+            girFiles: repository.girFiles,
+            libraries,
+        });
+
+        let widgetCount = 0;
+        if (this.options.jsx !== undefined) {
+            const reactPipeline = generateReactFiles(repository, this.options.slotProps);
+            writeJsxStore(this.options.jsx, reactPipeline.files);
+            widgetCount = reactPipeline.widgetCount;
+        }
+
+        return {
+            namespaces: repository.namespaces.size,
+            widgets: widgetCount,
+            duration: Date.now() - start,
+        };
+    }
+}