@gtkx/codegen 1.0.0-rc.2 → 1.0.0-rc.4

package/src/gir/libraries.ts

@@ -1,14 +1,24 @@
-import type { Config } from "@gtkx/config";
-import { GIR_LIBRARY_PATTERN, LIBRARIES_WILDCARD } from "@gtkx/config/internal";
 import { sortStrings } from "@gtkx/utils";
 import { readdirSync } from "node:fs";
 
 type GirNamespace = { name: string; version: string; identifier: string };
+/** A `libraries` config value: an explicit list, `"*"` for everything installed, or absent for the default. */
+type LibrarySelection = typeof LIBRARIES_WILDCARD | string[] | undefined;
 
+/** The `libraries` value that stands for every GIR library installed on the search path. */
+const LIBRARIES_WILDCARD = "*";
+const GIR_LIBRARY_PATTERN = /^[A-Za-z][A-Za-z0-9]*-\d+(?:\.\d+)*$/;
 const DEFAULT_LIBRARIES: string[] = ["Gtk-4.0"];
 const GIR_FILE_SUFFIX = ".gir";
 
-const resolveLibraries = (libraries: Config["libraries"], girPath: string[]): string[] => {
+/**
+ * Expands a `libraries` config value into the GIR identifiers to generate from: `"Gtk-4.0"` alone when
+ * nothing is configured, everything installed for `"*"`, and otherwise the given list with `"Gtk-4.0"`
+ * prepended unless it already names a Gtk version.
+ *
+ * @throws If `"*"` matched no `.gir` file anywhere on the GIR path.
+ */
+const resolveLibraries = (libraries: LibrarySelection, girPath: string[]): string[] => {
     if (libraries === undefined) {
         return [...DEFAULT_LIBRARIES];
     }
@@ -73,6 +83,10 @@ const collectDirNamespaces = (highestByName: Map<string, GirNamespace>, dir: str
     }
 };
 
+/**
+ * Every GIR library installed on the search path, as sorted `Name-Version` identifiers. A namespace found
+ * in more than one version contributes only its highest, and unreadable directories are skipped.
+ */
 const discoverGirNamespaces = (girPath: string[]): string[] => {
     const highestByName: Map<string, GirNamespace> = new Map();
 
@@ -99,4 +113,4 @@ const compareVersions = (a: string, b: string): number => {
     return 0;
 };
 
-export { resolveLibraries, discoverGirNamespaces };
+export { resolveLibraries, discoverGirNamespaces, type LibrarySelection };

package/src/gir/parameter.ts

@@ -53,10 +53,6 @@ const SCOPES: Set<CallbackScope> = new Set(["call", "notified", "async", "foreve
 const transferOwnership = (node: RawNode): ParameterTransfer =>
     parseEnumAttr(attr(node, "transfer-ownership"), TRANSFERS, "none", "transfer-ownership");
 
-// `allow-none` is the legacy spelling of two different attributes: on an in-parameter it means the
-// value may be NULL (`nullable`), but on an out-parameter it means the caller may pass a NULL
-// location (`optional`). Folding it into `nullable` for an out-parameter would claim the returned
-// value can be null for the 494 out-parameters across the installed GIRs that only say `allow-none`.
 const isInDirection = (node: RawNode): boolean =>
     parseEnumAttr(attr(node, "direction"), DIRECTIONS, "in", "direction") === "in";
 

package/src/gir/size.ts

@@ -59,9 +59,6 @@ const pushPlainField = (state: StructLayoutState, slots: FieldSlot[], field: Fie
     state.bitCursor = (byteOffset + field.layout.size) * 8;
 };
 
-// SysV AMD64 places a bit-field at the current bit offset whenever it still fits inside a storage
-// unit of its declared type aligned to that type's alignment, so the unit the cursor already sits in
-// may have room even though the cursor is not on a unit boundary.
 const pushBitfield = (input: {
     state: StructLayoutState;
     slots: FieldSlot[];

package/src/gir/type-id.ts

@@ -12,7 +12,7 @@ type CArrayType = {
     elementCType: string | undefined;
     lengthParameterIndex: number | undefined;
     fixedSize: number | undefined;
-    zeroTerminated: boolean;
+    isZeroTerminated: boolean;
 };
 
 type ListType = {
@@ -46,10 +46,8 @@ const LIST_FLAVOR_BY_NAME = {
     "GLib.ByteArray": "gbytearray",
 } as const;
 
-// An array with no length parameter, no fixed size and an explicit `zero-terminated="0"` carries no
-// way to recover its length, so it is a bare pointer rather than something that can be walked.
 const hasUnknownArrayLength = (ref: CArrayType): boolean =>
-    !ref.zeroTerminated && ref.lengthParameterIndex === undefined && ref.fixedSize === undefined;
+    !ref.isZeroTerminated && ref.lengthParameterIndex === undefined && ref.fixedSize === undefined;
 
 export {
     hasUnknownArrayLength,

package/src/gir/type-ref.ts

@@ -90,7 +90,7 @@ const arrayTypeRefFromNode = (arrayNode: RawNode, context: ParseContext): TypeId
         elementCType: elementNode === undefined ? undefined : attr(elementNode, "c:type"),
         lengthParameterIndex: intAttr(arrayNode, "length"),
         fixedSize: intAttr(arrayNode, "fixed-size"),
-        zeroTerminated: isAttrTrue(arrayNode, "zero-terminated", true),
+        isZeroTerminated: isAttrTrue(arrayNode, "zero-terminated", true),
     };
 
     return context.addContainer(carray);

package/src/index.ts

@@ -1,3 +1,4 @@
+/** @public */
 export {
     API_SYMBOL_KINDS,
     type ApiLookupResult,
@@ -7,22 +8,24 @@ export {
     type ApiSearchOptions,
     type ApiSymbol,
     type ApiSymbolKind,
+    type ApiSymbolQuery,
     loadApiReference,
 } from "./docs/api-reference.js";
-export {
-    type DocsElementLink,
-    type DocsNamespace,
-    type DocsOptions,
-    type DocsResult,
-    writeDocs,
-} from "./docs/pipeline.js";
+/** @public */
 export { resolveGirPath } from "./gir/gir-path.js";
-export { discoverGirNamespaces, resolveLibraries } from "./gir/libraries.js";
-export {
-    type BuiltinElement,
-    type BuiltinElements,
-    type ModuleExport,
-    readBuiltinElements,
-} from "./react/element-config.js";
-export { runCodegen } from "./runner.js";
+/** @public */
+export { discoverGirNamespaces, type LibrarySelection, resolveLibraries } from "./gir/libraries.js";
+/** @public */
+export { type BuiltinElements, type ModuleExport, readBuiltinElements } from "./react/element-config.js";
+/** @public */
+export { type CodegenRunnerOptions, type CodegenRunnerResult, runCodegen } from "./runner.js";
+/** @public */
 export type { ElementProps } from "./store/jsx/element-prop-imports.js";
+/** @public */
+export { type GeneratedElement, readGeneratedElements } from "./store/jsx/generated-elements.js";
+/** @public */
+export { mergeOmittedProps, type OmittedProps } from "./store/jsx/omitted-props.js";
+/** @public */
+export { type ResolvedStore, resolveStore } from "./store/resolve-store.js";
+/** @public */
+export type { StoreOptions } from "./store/store-fs.js";

package/src/internal.ts

@@ -0,0 +1,2 @@
+export { writeDocs } from "./docs/pipeline.js";
+export { runGlCodegen } from "./runner.js";

package/src/jsx.ts

@@ -1,4 +1,5 @@
 import type { Library } from "./gir/library.js";
+import type { StoreOptions } from "./store/store-fs.js";
 import {
     computeJsxFingerprint,
     FINGERPRINT_FILENAME,
@@ -6,65 +7,69 @@ import {
     jsxStoreFreshness,
 } from "./fingerprint.js";
 import { type ModuleExport, readBuiltinElements } from "./react/element-config.js";
-import { type JsxStoreOptions, writeJsxStore } from "./store/jsx-store.js";
+import { writeJsxStore } from "./store/jsx-store.js";
+import { ELEMENTS_FILENAME, renderGeneratedElements } from "./store/jsx/generated-elements.js";
+import { mergeOmittedProps, type OmittedProps } from "./store/jsx/omitted-props.js";
 import { generateJsxFiles } from "./store/jsx/pipeline.js";
 
 type RunJsxCodegenOptions = {
     getLibrary: () => Library;
-    jsx: JsxStoreOptions;
+    jsx: StoreOptions;
     giStoreDir: string;
     reactSubexports: string[];
     userComponents: Record<string, ModuleExport>;
     userLazyElements: string[];
     userProps: Record<string, ModuleExport>;
-    giRegenerated: boolean;
-    force: boolean;
+    userOmittedProps: OmittedProps;
+    isGiRegenerated: boolean;
+    isForced: boolean;
 };
 
 type RunJsxCodegenResult = {
-    regenerated: boolean;
+    isRegenerated: boolean;
     intrinsicElementCount: number;
 };
 
-/**
- * Generates the `@gtkx/jsx` store, reading the framework's built-in element config from the freshly
- * linked `@gtkx/react` and layering the project's own element config over it. This is the react-importing
- * half of codegen: it must run only after the gi store has been written and linked.
- */
 const runJsxCodegen = async (options: RunJsxCodegenOptions): Promise<RunJsxCodegenResult> => {
     const builtin = await readBuiltinElements(options.reactSubexports, options.giStoreDir);
     const components = { ...builtin.components, ...options.userComponents };
     const lazyElements = [...builtin.lazyElements, ...options.userLazyElements];
     const props = { ...builtin.props, ...options.userProps };
+    const omittedProps = mergeOmittedProps(builtin.omittedProps, options.userOmittedProps);
 
     const fingerprintInput: JsxFingerprintInput = {
         reactVersion: options.jsx.version,
         components,
         lazyElements,
         props,
+        omittedProps,
     };
 
-    if (!options.force && !options.giRegenerated) {
-        const { fresh, intrinsicElementCount } = jsxStoreFreshness(options.jsx.storeDir, fingerprintInput);
+    if (!options.isForced && !options.isGiRegenerated) {
+        const { isFresh, intrinsicElementCount } = jsxStoreFreshness(options.jsx.storeDir, fingerprintInput);
 
-        if (fresh) {
-            return { regenerated: false, intrinsicElementCount };
+        if (isFresh) {
+            return { isRegenerated: false, intrinsicElementCount };
         }
     }
 
-    const { namespaces, metadata, intrinsicElementCount } = generateJsxFiles(options.getLibrary(), {
+    const { namespaces, metadata, intrinsicElementCount, elements } = generateJsxFiles(options.getLibrary(), {
         reactSubexports: options.reactSubexports,
         components,
         lazyElements,
         props,
+        omittedProps,
     });
 
-    writeJsxStore(options.jsx, namespaces, metadata, {
-        relativePath: FINGERPRINT_FILENAME,
-        content: `${JSON.stringify(computeJsxFingerprint(fingerprintInput, intrinsicElementCount), null, 2)}\n`,
-    });
+    writeJsxStore(options.jsx, namespaces, metadata, [
+        {
+            relativePath: FINGERPRINT_FILENAME,
+            content: `${JSON.stringify(computeJsxFingerprint(fingerprintInput, intrinsicElementCount), null, 2)}\n`,
+        },
+        { relativePath: ELEMENTS_FILENAME, content: renderGeneratedElements(elements) },
+    ]);
 
-    return { regenerated: true, intrinsicElementCount };
+    return { isRegenerated: true, intrinsicElementCount };
 };
 
-export { runJsxCodegen, type RunJsxCodegenOptions, type RunJsxCodegenResult };
+export { runJsxCodegen };

package/src/khronos/args.ts

@@ -52,7 +52,7 @@ type BuildArgOptions = {
 const OUT_PLAN_KINDS: Set<string> = new Set(["ref-out", "ref-array-out", "ref-fixed-out", "string-out"]);
 
 const scalarAliasOrGroup = (scalar: GlScalar, group: string | undefined): string =>
-    group !== undefined && scalar.groupBearing === true ? group : scalar.tsAlias;
+    group !== undefined && scalar.isGroupBearing === true ? group : scalar.tsAlias;
 
 const paramIndexByName = (command: GlCommand, name: string): number => {
     const index = command.params.findIndex((param) => param.name === name);

package/src/khronos/pipeline.ts

@@ -143,7 +143,7 @@ const mergeGroupAlias = (aliases: Map<string, string>, scalar: GlScalar, group:
         return;
     }
 
-    if (scalar.groupBearing !== true) {
+    if (scalar.isGroupBearing !== true) {
         return;
     }
 

package/src/khronos/plan.ts

@@ -5,13 +5,13 @@ type GlScalar = {
     descriptor: string;
     tsAlias: string;
     viewType?: string;
-    groupBearing?: boolean;
+    isGroupBearing?: boolean;
 };
 
 type ParsedCType = {
     base: string;
     pointers: number;
-    constData: boolean;
+    isConstData: boolean;
 };
 
 type ParamPlan =
@@ -61,10 +61,10 @@ type CommandPlan =
 type ParamOutcome = { plan: ParamPlan } | { reason: GlExclusionReason };
 
 const GL_SCALARS: Map<string, GlScalar> = new Map([
-    ["GLenum", { descriptor: tScalar("uint32"), tsAlias: "GLenum", viewType: "Uint32Array", groupBearing: true }],
+    ["GLenum", { descriptor: tScalar("uint32"), tsAlias: "GLenum", viewType: "Uint32Array", isGroupBearing: true }],
     [
         "GLbitfield",
-        { descriptor: tScalar("uint32"), tsAlias: "GLbitfield", viewType: "Uint32Array", groupBearing: true },
+        { descriptor: tScalar("uint32"), tsAlias: "GLbitfield", viewType: "Uint32Array", isGroupBearing: true },
     ],
     ["GLuint", { descriptor: tScalar("uint32"), tsAlias: "GLuint", viewType: "Uint32Array" }],
     ["GLint", { descriptor: tScalar("int32"), tsAlias: "GLint", viewType: "Int32Array" }],
@@ -96,7 +96,7 @@ const parseCType = (cType: string): ParsedCType => {
         .filter((token) => token.length > 0 && token !== "const" && token !== "struct")
         .join(" ");
 
-    return { base, pointers, constData: isConstData };
+    return { base, pointers, isConstData };
 };
 
 const isCompsize = (len: string): boolean => len.includes("COMPSIZE(");
@@ -158,11 +158,11 @@ const charStringOutLen = (command: GlCommand, param: GlParam, parsed: ParsedCTyp
 };
 
 const planCharParam = (command: GlCommand, param: GlParam, parsed: ParsedCType): ParamOutcome => {
-    if (parsed.pointers === 1 && parsed.constData) {
+    if (parsed.pointers === 1 && parsed.isConstData) {
         return { plan: { kind: "string-in" } };
     }
 
-    if (parsed.pointers === 2 && parsed.constData) {
+    if (parsed.pointers === 2 && parsed.isConstData) {
         return { plan: { kind: "string-array-in" } };
     }
 
@@ -191,7 +191,7 @@ const planScalarParam = (
         return { plan: { kind: "scalar", scalar } };
     }
 
-    if (parsed.pointers === 1 && parsed.constData) {
+    if (parsed.pointers === 1 && parsed.isConstData) {
         return { plan: { kind: "array-in", scalar } };
     }
 

package/src/react/element-config.ts

@@ -1,14 +1,19 @@
-import type { ModuleExport } from "@gtkx/react/config";
+import type { ModuleExport } from "@gtkx/react/internal";
 import { readdirSync } from "node:fs";
+import type { OmittedProps } from "../store/jsx/omitted-props.js";
 
-/** The codegen-relevant subset of a React element config; behaviors are ignored at codegen time. */
-type BuiltinElement = { component?: ModuleExport; lazy?: boolean; props?: ModuleExport };
+type BuiltinElement = { component?: ModuleExport; isLazy?: boolean; props?: ModuleExport; omittedProps?: string[] };
 
 /** The framework's built-in element config, split into the maps codegen consumes. */
 type BuiltinElements = {
+    /** Component wrappers keyed by GLib type name; an element without one inherits its nearest ancestor's. */
     components: Record<string, ModuleExport>;
+    /** GLib type names with no GObject of their own, exported as elements that drop their construct-only props. */
     lazyElements: string[];
+    /** Base props interfaces the generated element props extend, keyed by GLib type name. */
     props: Record<string, ModuleExport>;
+    /** Props left out of the generated element props, keyed by GLib type name. */
+    omittedProps: OmittedProps;
 };
 
 const CONFIG_ENTRYPOINT = "config";
@@ -27,10 +32,6 @@ const presentNamespaceDirs = (giStoreDir: string): Set<string> => {
     return dirs;
 };
 
-/**
- * The clean, reconciler-free `@gtkx/react` config entrypoints to import: the base `config` entry plus
- * each namespace's `<ns>/config` entry whose GIR namespace is present in the gi store.
- */
 const configEntrypoints = (reactSubexports: string[], present: Set<string>): string[] =>
     reactSubexports.filter((sub) => {
         if (sub === CONFIG_ENTRYPOINT) {
@@ -59,26 +60,34 @@ const applyBuiltinElement = (target: BuiltinElements, type: string, config: Buil
         target.props[type] = config.props;
     }
 
-    if (config.lazy === true) {
+    if (config.omittedProps !== undefined) {
+        target.omittedProps[type] = [...(target.omittedProps[type] ?? []), ...config.omittedProps];
+    }
+
+    if (config.isLazy === true) {
         target.lazyElements.push(type);
     }
 };
 
-/**
- * Reads the framework's built-in element config by importing the freshly linked `@gtkx/react` config
- * entrypoints. These are reconciler-free, so importing them resolves `@gtkx/gi` but never `virtual:gtkx-config`;
- * it must run only after the gi store has been linked.
- */
 const collectBuiltinElements = (target: BuiltinElements, elements: Record<string, BuiltinElement>): void => {
     for (const [type, config] of Object.entries(elements)) {
         applyBuiltinElement(target, type, config);
     }
 };
 
+/**
+ * Reads the framework's built-in element config by importing the `config` entrypoints of the installed
+ * `@gtkx/react`, skipping the per-namespace ones whose namespace the gi store does not carry. Those
+ * entrypoints are reconciler-free, so importing them resolves `@gtkx/gi` but never `virtual:gtkx-config`,
+ * which means this must run only after the gi store has been written and linked.
+ *
+ * @param reactSubexports Subexport names of the installed `@gtkx/react`, as `resolveStore` reports them.
+ * @param giStoreDir The gi store directory, whose subdirectories name the generated namespaces.
+ */
 const readBuiltinElements = async (reactSubexports: string[], giStoreDir: string): Promise<BuiltinElements> => {
     const present = presentNamespaceDirs(giStoreDir);
     const entrypoints = configEntrypoints(reactSubexports, present);
-    const result: BuiltinElements = { components: {}, lazyElements: [], props: {} };
+    const result: BuiltinElements = { components: {}, lazyElements: [], props: {}, omittedProps: {} };
 
     for (const entrypoint of entrypoints) {
         collectBuiltinElements(result, await importBuiltinElements(entrypoint));
@@ -87,5 +96,5 @@ const readBuiltinElements = async (reactSubexports: string[], giStoreDir: string
     return result;
 };
 
-export { type ModuleExport } from "@gtkx/react/config";
-export { readBuiltinElements, type BuiltinElement, type BuiltinElements };
+export type { ModuleExport } from "@gtkx/react/internal";
+export { readBuiltinElements, type BuiltinElements };

package/src/runner.ts

@@ -1,14 +1,20 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-import type { GiStoreOptions } from "./store/gi-store.js";
-import type { JsxStoreOptions } from "./store/jsx-store.js";
+import type { OmittedProps } from "./store/jsx/omitted-props.js";
+import type { StoreOptions } from "./store/store-fs.js";
 import { checkModules } from "./compile.js";
 import { isGiStoreFresh } from "./fingerprint.js";
 import { runGiCodegen } from "./gi.js";
 import { Library } from "./gir/library.js";
 import { generateGlModules, type GlGenerationReport } from "./khronos/pipeline.js";
 
-type ModuleExport = { module: string; export: string };
+/** A named export in a module, referenced as plain data (the module is never imported at runtime). */
+type ModuleExport = {
+    /** Specifier the export is imported from. */
+    module: string;
+    /** Identifier the module exports it under. */
+    export: string;
+};
 
 type GlCodegenOptions = {
     registryPath: string;
@@ -17,57 +23,71 @@ type GlCodegenOptions = {
     resolveFrom: string;
 };
 
+/** What to generate and where to write it. */
 type CodegenRunnerOptions = {
-    libraries?: string[];
-    girPath?: string[];
-    gi?: GiStoreOptions;
-    jsx?: JsxStoreOptions | undefined;
+    /** GIR library identifiers such as `"Gtk-4.0"`; a `"*"` selection must be expanded before it gets here. */
+    libraries: string[];
+    /** Directories to search for `.gir` files. */
+    girPath: string[];
+    /** Where to write and link the `@gtkx/gi` store. */
+    gi: StoreOptions;
+    /** Where to write and link the `@gtkx/jsx` store; omit to generate the gi store alone. */
+    jsx?: StoreOptions | undefined;
+    /** Subexport names of the installed `@gtkx/react`, whose element config shapes the jsx store. */
     reactSubexports?: string[];
+    /** Component wrappers the project layers over the built-ins, keyed by GLib type name. */
     userComponents?: Record<string, ModuleExport>;
+    /** GLib type names whose GObject their parent container creates, added to the framework's own. */
     userLazyElements?: string[];
+    /** Base props interfaces the project's elements extend, keyed by GLib type name. */
     userProps?: Record<string, ModuleExport>;
-    gl?: GlCodegenOptions;
-    force?: boolean;
+    /** Props the project drops from the generated element props, keyed by GLib type name. */
+    userOmittedProps?: OmittedProps;
+    /** Regenerates both stores even when their fingerprints are fresh. */
+    isForced?: boolean;
 };
 
+/** What a `runCodegen` run produced. */
 type CodegenRunnerResult = {
-    regenerated: boolean;
+    /** Whether either store was rewritten; false means both were already fresh. */
+    isRegenerated: boolean;
+    /** How many namespaces the gi store was written with, zero when it was already fresh. */
     namespaces: number;
+    /** How many JSX elements the jsx store binds, zero when no jsx store was requested. */
     intrinsicElements: number;
+    /** Wall-clock duration of the run, in milliseconds. */
     duration: number;
-    gl?: GlGenerationReport | undefined;
 };
 
 type StoreResult = {
-    regenerated: boolean;
+    isRegenerated: boolean;
     namespaces: number;
     intrinsicElements: number;
 };
 
 /**
- * Runs the `@gtkx` code generators, producing the `@gtkx/gi`, `@gtkx/jsx`, and `@gtkx/gl` bindings from the
- * configured GObject-introspection libraries and OpenGL registry. The gi store is regenerated only when its
- * fingerprint is stale unless `options.force` is set, then the jsx store is regenerated when the gi store or
- * the React element config changed; the OpenGL modules are regenerated whenever `options.gl` is provided.
+ * Writes and links a project's `@gtkx/gi` and `@gtkx/jsx` stores from the given GObject-Introspection
+ * libraries. The gi store is rewritten only when its GIR inputs changed, and the jsx store only when the gi
+ * store or the React element config changed, unless `options.isForced` is set. Pass the spread of
+ * `resolveStore(projectRoot)` for everything but `libraries` and `girPath`.
  *
- * @param options - What to generate and where to write it.
+ * @param options What to generate and where to write it.
  * @returns A summary of what was regenerated and how long the run took.
+ * @throws If `girPath` is empty, which would otherwise generate nothing and report success.
  */
 const runCodegen = async (options: CodegenRunnerOptions): Promise<CodegenRunnerResult> => {
     const start = Date.now();
-    const gl = options.gl === undefined ? undefined : emitGlModules(options.gl);
     const store = await emitStores(options);
 
     return {
-        regenerated: store.regenerated,
+        isRegenerated: store.isRegenerated,
         namespaces: store.namespaces,
         intrinsicElements: store.intrinsicElements,
         duration: Date.now() - start,
-        gl,
     };
 };
 
-const emitGlModules = (options: GlCodegenOptions): GlGenerationReport => {
+const runGlCodegen = (options: GlCodegenOptions): GlGenerationReport => {
     const { files, report } = generateGlModules({
         registryPath: options.registryPath,
         overrideExports: options.overrideExports,
@@ -95,22 +115,24 @@ const jsxUserOptions = (
     userComponents: Record<string, ModuleExport>;
     userLazyElements: string[];
     userProps: Record<string, ModuleExport>;
+    userOmittedProps: OmittedProps;
 } => ({
     reactSubexports: options.reactSubexports ?? [],
     userComponents: options.userComponents ?? {},
     userLazyElements: options.userLazyElements ?? [],
     userProps: options.userProps ?? {},
+    userOmittedProps: options.userOmittedProps ?? {},
 });
 
 const emitJsxStore = async (input: {
     options: CodegenRunnerOptions;
-    jsx: JsxStoreOptions;
-    gi: GiStoreOptions;
+    jsx: StoreOptions;
+    gi: StoreOptions;
     loadLibrary: () => Library;
-    giRegenerated: boolean;
+    isGiRegenerated: boolean;
     namespaces: number;
 }): Promise<StoreResult> => {
-    const { options, jsx, gi, loadLibrary, giRegenerated, namespaces } = input;
+    const { options, jsx, gi, loadLibrary, isGiRegenerated, namespaces } = input;
     const { runJsxCodegen } = await import("./jsx.js");
 
     const jsxResult = await runJsxCodegen({
@@ -118,12 +140,12 @@ const emitJsxStore = async (input: {
         jsx,
         giStoreDir: gi.storeDir,
         ...jsxUserOptions(options),
-        giRegenerated,
-        force: options.force === true,
+        isGiRegenerated,
+        isForced: options.isForced === true,
     });
 
     return {
-        regenerated: giRegenerated || jsxResult.regenerated,
+        isRegenerated: isGiRegenerated || jsxResult.isRegenerated,
         namespaces,
         intrinsicElements: jsxResult.intrinsicElementCount,
     };
@@ -131,32 +153,35 @@ const emitJsxStore = async (input: {
 
 const emitStoresWithConfig = async (config: {
     options: CodegenRunnerOptions;
-    gi: GiStoreOptions;
-    jsx: JsxStoreOptions | undefined;
+    gi: StoreOptions;
+    jsx: StoreOptions | undefined;
     libraries: string[];
     girPath: string[];
 }): Promise<StoreResult> => {
     const { options, gi, jsx, libraries, girPath } = config;
     let library: Library | undefined;
     const loadLibrary = (): Library => (library ??= Library.load(libraries, girPath));
-    const isGiRegenerated = options.force === true || !isGiStoreFresh(gi.storeDir, libraries, girPath);
-    const namespaces = isGiRegenerated ? runGiCodegen(loadLibrary(), gi, libraries, girPath) : 0;
+    const isGiRegenerated = options.isForced === true || !isGiStoreFresh(gi.storeDir, libraries, girPath);
+
+    const namespaces = isGiRegenerated
+        ? runGiCodegen(loadLibrary(), { gi, libraries, girPath })
+        : 0;
 
     if (jsx === undefined) {
-        return { regenerated: isGiRegenerated, namespaces, intrinsicElements: 0 };
+        return { isRegenerated: isGiRegenerated, namespaces, intrinsicElements: 0 };
     }
 
-    return emitJsxStore({ options, jsx, gi, loadLibrary, giRegenerated: isGiRegenerated, namespaces });
+    return emitJsxStore({ options, jsx, gi, loadLibrary, isGiRegenerated, namespaces });
 };
 
 const emitStores = async (options: CodegenRunnerOptions): Promise<StoreResult> => {
     const { gi, jsx, libraries, girPath } = options;
 
-    if (gi === undefined || libraries === undefined || girPath === undefined) {
-        return { regenerated: false, namespaces: 0, intrinsicElements: 0 };
+    if (girPath.length === 0) {
+        throw new Error("codegen needs at least one GIR search path; pass the result of resolveGirPath");
     }
 
     return emitStoresWithConfig({ options, gi, jsx, libraries, girPath });
 };
 
-export { runCodegen, type GlCodegenOptions, type CodegenRunnerOptions, type CodegenRunnerResult };
+export { runCodegen, runGlCodegen, type CodegenRunnerOptions, type CodegenRunnerResult };

package/src/store/compile-store.ts

@@ -6,8 +6,7 @@ type CompileStoreParams = {
     storeDir: string;
     files: SourceModule[];
     packageName: string;
-    /** Declare `virtual:gtkx-config` for the typecheck, needed when it follows imports into `@gtkx/react` source. */
-    configEnv?: boolean;
+    requiresEnvReference?: boolean;
 };
 
 const EMIT_OPTIONS = {
@@ -32,14 +31,14 @@ const writeEnvReference = (storeDir: string): (() => void) => {
 const compileStore = (params: CompileStoreParams): void => {
     const fileNames = params.files.map((file) => file.fileName);
 
-    const removeEnvReference = params.configEnv === true
+    const removeEnvReference = params.requiresEnvReference === true
         ? writeEnvReference(params.storeDir)
         : (): void => undefined;
 
     try {
         compileProject({
             projectDir: params.storeDir,
-            fileNames: params.configEnv === true ? [ENV_REFERENCE_FILE, ...fileNames] : fileNames,
+            fileNames: params.requiresEnvReference === true ? [ENV_REFERENCE_FILE, ...fileNames] : fileNames,
             compilerOptions: EMIT_OPTIONS,
             label: `the generated ${params.packageName} store`,
         });