@gtkx/config 0.21.0 → 1.0.0-rc.1

package/dist/virtual.js

@@ -1,20 +1,8 @@
 export const GTKX_CONFIG_VIRTUAL_ID = "virtual:gtkx-config";
 export const RESOLVED_GTKX_CONFIG_VIRTUAL_ID = `\0${GTKX_CONFIG_VIRTUAL_ID}`;
 const METADATA_SPECIFIER = "@gtkx/jsx/metadata";
-const serializeConfigValue = (value) => (value === undefined ? "undefined" : JSON.stringify(value));
-export const serializeGtkxConfig = (config) => ({
-    libraries: config.libraries,
-    girPath: config.girPath,
-    applicationId: config.applicationId,
-    containerProps: config.containerProps,
-    arrayProps: config.arrayProps,
-    objectProps: config.objectProps,
-    virtualProps: config.virtualProps,
-    elementMap: config.elementMap,
-    reactCompiler: config.reactCompiler,
-});
-export const renderGtkxConfigModule = (config) => [
+export const renderConfigModule = (config) => [
     `export * from ${JSON.stringify(METADATA_SPECIFIER)};`,
-    ...Object.entries(serializeGtkxConfig(config)).map(([key, value]) => `export const ${key} = ${serializeConfigValue(value)};`),
+    `export const applicationId = ${JSON.stringify(config.applicationId)};`,
 ].join("\n");
 //# sourceMappingURL=virtual.js.map

package/dist/virtual.js.map

@@ -1 +1 @@
-{"version":3,"file":"virtual.js","sourceRoot":"","sources":["../src/virtual.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,sBAAsB,GAAG,qBAAqB,CAAC;AAE5D,MAAM,CAAC,MAAM,+BAA+B,GAAW,KAAK,sBAAsB,EAAE,CAAC;AAErF,MAAM,kBAAkB,GAAG,oBAAoB,CAAC;AAehD,MAAM,oBAAoB,GAAG,CAAC,KAAc,EAAU,EAAE,CAAC,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;AAErH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,MAA0B,EAAwB,EAAE,CAAC,CAAC;IACtF,SAAS,EAAE,MAAM,CAAC,SAAS;IAC3B,OAAO,EAAE,MAAM,CAAC,OAAO;IACvB,aAAa,EAAE,MAAM,CAAC,aAAa;IACnC,cAAc,EAAE,MAAM,CAAC,cAAc;IACrC,UAAU,EAAE,MAAM,CAAC,UAAU;IAC7B,WAAW,EAAE,MAAM,CAAC,WAAW;IAC/B,YAAY,EAAE,MAAM,CAAC,YAAY;IACjC,UAAU,EAAE,MAAM,CAAC,UAAU;IAC7B,aAAa,EAAE,MAAM,CAAC,aAAa;CACtC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAC,MAA0B,EAAU,EAAE,CACzE;IACI,iBAAiB,IAAI,CAAC,SAAS,CAAC,kBAAkB,CAAC,GAAG;IACtD,GAAG,MAAM,CAAC,OAAO,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAC9C,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,gBAAgB,GAAG,MAAM,oBAAoB,CAAC,KAAK,CAAC,GAAG,CAC5E;CACJ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC"}
+{"version":3,"file":"virtual.js","sourceRoot":"","sources":["../src/virtual.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,sBAAsB,GAAG,qBAAqB,CAAC;AAE5D,MAAM,CAAC,MAAM,+BAA+B,GAAW,KAAK,sBAAsB,EAAE,CAAC;AAErF,MAAM,kBAAkB,GAAG,oBAAoB,CAAC;AAEhD,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,MAAsB,EAAU,EAAE,CACjE;IACI,iBAAiB,IAAI,CAAC,SAAS,CAAC,kBAAkB,CAAC,GAAG;IACtD,gCAAgC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,aAAa,CAAC,GAAG;CAC1E,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC","sourcesContent":["import type { ResolvedConfig } from \"./config.js\";\n\nexport const GTKX_CONFIG_VIRTUAL_ID = \"virtual:gtkx-config\";\n\nexport const RESOLVED_GTKX_CONFIG_VIRTUAL_ID: string = `\\0${GTKX_CONFIG_VIRTUAL_ID}`;\n\nconst METADATA_SPECIFIER = \"@gtkx/jsx/metadata\";\n\nexport const renderConfigModule = (config: ResolvedConfig): string =>\n    [\n        `export * from ${JSON.stringify(METADATA_SPECIFIER)};`,\n        `export const applicationId = ${JSON.stringify(config.applicationId)};`,\n    ].join(\"\\n\");\n"]}

package/dist/vite-plugin.d.ts

@@ -0,0 +1,16 @@
+import type { Plugin, UserConfig } from "vite";
+import { type ConfigLoader } from "./loader.js";
+/**
+ * Creates the Vite plugin that resolves and serves the `virtual:gtkx-config`
+ * module, exposing the JSX metadata and the resolved application ID from the
+ * project's configuration.
+ * @param options Plugin name, an optional custom {@link ConfigLoader}, and an
+ * optional hook returning extra Vite user config.
+ */
+declare const createConfigPlugin: (options: {
+    name: string;
+    loadConfig?: ConfigLoader;
+    config?: () => Omit<UserConfig, "plugins">;
+}) => Plugin;
+export default createConfigPlugin;
+//# sourceMappingURL=vite-plugin.d.ts.map

package/dist/vite-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-plugin.d.ts","sourceRoot":"","sources":["../src/vite-plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,MAAM,CAAC;AAC/C,OAAO,EAAE,KAAK,YAAY,EAAsB,MAAM,aAAa,CAAC;AAGpE;;;;;;GAMG;AACH,QAAA,MAAM,kBAAkB,YAAa;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,CAAC,EAAE,YAAY,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;CAC9C,KAAG,MAmBH,CAAC;eAEa,kBAAkB"}

package/dist/vite-plugin.js

@@ -0,0 +1,32 @@
+import { createConfigLoader } from "./loader.js";
+import { GTKX_CONFIG_VIRTUAL_ID, RESOLVED_GTKX_CONFIG_VIRTUAL_ID, renderConfigModule } from "./virtual.js";
+/**
+ * Creates the Vite plugin that resolves and serves the `virtual:gtkx-config`
+ * module, exposing the JSX metadata and the resolved application ID from the
+ * project's configuration.
+ * @param options Plugin name, an optional custom {@link ConfigLoader}, and an
+ * optional hook returning extra Vite user config.
+ */
+const createConfigPlugin = (options) => {
+    const loadConfig = options.loadConfig ?? createConfigLoader();
+    let root;
+    return {
+        name: options.name,
+        config(config) {
+            root = config.root ?? root;
+            return options.config?.();
+        },
+        resolveId(id) {
+            if (id === GTKX_CONFIG_VIRTUAL_ID)
+                return RESOLVED_GTKX_CONFIG_VIRTUAL_ID;
+            return undefined;
+        },
+        async load(id) {
+            if (id !== RESOLVED_GTKX_CONFIG_VIRTUAL_ID)
+                return undefined;
+            return renderConfigModule(await loadConfig(root ?? process.cwd()));
+        },
+    };
+};
+export default createConfigPlugin;
+//# sourceMappingURL=vite-plugin.js.map

package/dist/vite-plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-plugin.js","sourceRoot":"","sources":["../src/vite-plugin.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,sBAAsB,EAAE,+BAA+B,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAE3G;;;;;;GAMG;AACH,MAAM,kBAAkB,GAAG,CAAC,OAI3B,EAAU,EAAE;IACT,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,kBAAkB,EAAE,CAAC;IAC9D,IAAI,IAAwB,CAAC;IAE7B,OAAO;QACH,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,MAAM,CAAC,MAAkB;YACrB,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC;YAC3B,OAAO,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QAC9B,CAAC;QACD,SAAS,CAAC,EAAU;YAChB,IAAI,EAAE,KAAK,sBAAsB;gBAAE,OAAO,+BAA+B,CAAC;YAC1E,OAAO,SAAS,CAAC;QACrB,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAU;YACjB,IAAI,EAAE,KAAK,+BAA+B;gBAAE,OAAO,SAAS,CAAC;YAC7D,OAAO,kBAAkB,CAAC,MAAM,UAAU,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACvE,CAAC;KACJ,CAAC;AACN,CAAC,CAAC;AAEF,eAAe,kBAAkB,CAAC","sourcesContent":["import type { Plugin, UserConfig } from \"vite\";\nimport { type ConfigLoader, createConfigLoader } from \"./loader.js\";\nimport { GTKX_CONFIG_VIRTUAL_ID, RESOLVED_GTKX_CONFIG_VIRTUAL_ID, renderConfigModule } from \"./virtual.js\";\n\n/**\n * Creates the Vite plugin that resolves and serves the `virtual:gtkx-config`\n * module, exposing the JSX metadata and the resolved application ID from the\n * project's configuration.\n * @param options Plugin name, an optional custom {@link ConfigLoader}, and an\n * optional hook returning extra Vite user config.\n */\nconst createConfigPlugin = (options: {\n    name: string;\n    loadConfig?: ConfigLoader;\n    config?: () => Omit<UserConfig, \"plugins\">;\n}): Plugin => {\n    const loadConfig = options.loadConfig ?? createConfigLoader();\n    let root: string | undefined;\n\n    return {\n        name: options.name,\n        config(config: UserConfig) {\n            root = config.root ?? root;\n            return options.config?.();\n        },\n        resolveId(id: string) {\n            if (id === GTKX_CONFIG_VIRTUAL_ID) return RESOLVED_GTKX_CONFIG_VIRTUAL_ID;\n            return undefined;\n        },\n        async load(id: string) {\n            if (id !== RESOLVED_GTKX_CONFIG_VIRTUAL_ID) return undefined;\n            return renderConfigModule(await loadConfig(root ?? process.cwd()));\n        },\n    };\n};\n\nexport default createConfigPlugin;\n"]}

package/env.d.ts

@@ -1,26 +1,8 @@
 declare module "virtual:gtkx-config" {
-    export const SIGNALS: import("@gtkx/config").PerElementPropRows<string>;
+    export const SIGNALS: Record<string, Record<string, string>>;
     export const CONSTRUCT_ONLY_PROPS: Record<string, Set<string>>;
     export const CONSTRUCT_PROPS: Record<string, Set<string>>;
-    export const DEFAULT_PROPS: import("@gtkx/config").PerElementPropRows<unknown>;
-    export const ELEMENT_MAP: import("@gtkx/config").ElementMapRule[];
-    export const ARRAY_PROPS: import("@gtkx/config").PerElementPropRows<import("@gtkx/config").ArrayPropRow>;
-    export const OBJECT_PROPS: import("@gtkx/config").PerElementPropRows<import("@gtkx/config").ObjectPropRow>;
-    export const VIRTUAL_PROPS: import("@gtkx/config").PerElementPropRows<import("@gtkx/config").VirtualPropRow>;
-    export const PROP_RULES: Record<string, import("@gtkx/config").PropRule[]>;
-    export const TOP_LEVEL_TYPES: string[];
-    export const DEFAULT_BLOCKABLE_TYPES: string[];
-    export const META_OBJECT_ADD_METHODS: Record<string, import("@gtkx/config").AddMethodRule[]>;
-    export const PAGE_META_SETTERS: import("@gtkx/config").PageMetaSetter[];
-    export const CONTAINER_PROPS: import("@gtkx/config").PerElementPropRows<import("@gtkx/config").ContainerPropRow>;
-    export const ATTACH_SHAPES: import("@gtkx/config").AttachShapeTable;
-    export const libraries: import("@gtkx/config").ResolvedGtkxConfig["libraries"];
-    export const girPath: import("@gtkx/config").ResolvedGtkxConfig["girPath"];
-    export const applicationId: import("@gtkx/config").ResolvedGtkxConfig["applicationId"];
-    export const containerProps: import("@gtkx/config").ResolvedGtkxConfig["containerProps"];
-    export const arrayProps: import("@gtkx/config").ResolvedGtkxConfig["arrayProps"];
-    export const objectProps: import("@gtkx/config").ResolvedGtkxConfig["objectProps"];
-    export const virtualProps: import("@gtkx/config").ResolvedGtkxConfig["virtualProps"];
-    export const elementMap: import("@gtkx/config").ResolvedGtkxConfig["elementMap"];
-    export const reactCompiler: import("@gtkx/config").ResolvedGtkxConfig["reactCompiler"];
+    export const DEFAULT_PROPS: Record<string, Record<string, unknown>>;
+    export const ELEMENT_PROPS: Record<string, import("@gtkx/config").ElementProp[]>;
+    export const applicationId: import("@gtkx/config").ResolvedConfig["applicationId"];
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@gtkx/config",
-  "version": "0.21.0",
-  "description": "gtkx.config.ts schema, validation, and loader shared by the GTKX toolchain",
+  "version": "1.0.0-rc.1",
+  "description": "gtkx.config.ts schema, loader, and the element-prop mapping language shared across the GTKX toolchain",
   "keywords": [
     "gtkx",
     "gtk",
@@ -18,7 +18,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/gtkx-org/gtkx.git",
+    "url": "git+https://github.com/gtkx-org/gtkx.git",
     "directory": "packages/config"
   },
   "license": "MPL-2.0",
@@ -27,12 +27,19 @@
   "exports": {
     "./package.json": "./package.json",
     ".": {
-      "source": "./src/index.ts",
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
     "./env": {
       "types": "./env.d.ts"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "default": "./dist/internal.js"
+    },
+    "./vite-plugin": {
+      "types": "./dist/vite-plugin.d.ts",
+      "default": "./dist/vite-plugin.js"
     }
   },
   "sideEffects": false,
@@ -41,12 +48,18 @@
     "src",
     "env.d.ts"
   ],
+  "engines": {
+    "node": ">=24"
+  },
   "dependencies": {
     "c12": "^3.3.4",
-    "vite": "^8.0.16",
-    "@gtkx/utils": "0.21.0"
+    "defu": "^6.1.7",
+    "vite": "^8.1.4",
+    "zod": "^4.4.3"
   },
   "scripts": {
-    "build": "tsc -b"
+    "build": "tsc -b tsconfig.lib.json",
+    "typecheck": "tsc -b --emitDeclarationOnly",
+    "release": "tsx ../../scripts/release-package.ts"
   }
 }

package/src/config.ts

@@ -1,191 +1,181 @@
-import { isValidApplicationId } from "@gtkx/utils";
-import {
-    type ArrayPropRow,
-    type ContainerPropRow,
-    type ElementMapRule,
-    type ObjectPropRow,
-    type PerElementPropRows,
-    type UserTableRows,
-    type VirtualPropRow,
-    validateArrayPropRows,
-    validateContainerPropRows,
-    validateElementMap,
-    validateObjectPropRows,
-    validateVirtualPropRows,
-} from "./table-schema.js";
+import { createDefineConfig, type DefineConfig } from "c12";
+import { defu } from "defu";
+import { z } from "zod";
+import { configError, elementPropsSchema, isRecord, rawIssue } from "./element-props.js";
 
 export const LIBRARIES_WILDCARD = "*";
 
-export const GIR_NAMESPACE_PATTERN: RegExp = /^[A-Za-z][A-Za-z0-9]*-\d+(?:\.\d+)*$/;
+export const GIR_LIBRARY_PATTERN: RegExp = /^[A-Za-z][A-Za-z0-9]*-\d+(?:\.\d+)*$/;
 
-export type GtkxConfig = UserTableRows & {
-    libraries?: typeof LIBRARIES_WILDCARD | string[];
+const APPLICATION_ID_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]*(\.[A-Za-z_][A-Za-z0-9_-]*)+$/;
+const APPLICATION_ID_MAX_LENGTH = 255;
 
-    girPath?: string[];
+export const isValidApplicationId = (applicationId: string): boolean => {
+    if (applicationId.length === 0 || applicationId.length > APPLICATION_ID_MAX_LENGTH) {
+        return false;
+    }
+    return APPLICATION_ID_PATTERN.test(applicationId);
+};
 
-    applicationId?: string;
+const COMPILATION_MODES = ["infer", "syntax", "annotation", "all"] as const;
 
-    reactCompiler?: boolean | ReactCompilerOptions;
-};
+const PANIC_THRESHOLDS = ["none", "critical_errors", "all_errors"] as const;
 
-export type ReactCompilerCompilationMode = "infer" | "syntax" | "annotation" | "all";
+type ReactCompilerCompilationMode = (typeof COMPILATION_MODES)[number];
 
-export type ReactCompilerPanicThreshold = "none" | "critical_errors" | "all_errors";
+type ReactCompilerPanicThreshold = (typeof PANIC_THRESHOLDS)[number];
 
-export type ReactCompilerOptions = {
+type ReactCompilerOptions = {
     compilationMode?: ReactCompilerCompilationMode;
     panicThreshold?: ReactCompilerPanicThreshold;
 };
 
+/**
+ * React Compiler options resolved for the build, with the compilation target
+ * fixed to React 19.
+ */
 export type ResolvedReactCompilerOptions = ReactCompilerOptions & {
     target: "19";
 };
 
 const REACT_COMPILER_TARGET = "19";
 
-export const resolveReactCompilerOptions = (
-    setting: GtkxConfig["reactCompiler"],
-): ResolvedReactCompilerOptions | null => {
+export const resolveReactCompilerOptions = (setting: Config["reactCompiler"]): ResolvedReactCompilerOptions | null => {
     if (setting === false) return null;
     const overrides = setting === undefined || setting === true ? {} : setting;
     return { ...overrides, target: REACT_COMPILER_TARGET };
 };
 
-const validateLibraryEntry = (library: unknown): void => {
-    if (typeof library === "string" && GIR_NAMESPACE_PATTERN.test(library)) {
+const COMPILATION_MODE_SET: Set<string> = new Set(COMPILATION_MODES);
+
+const PANIC_THRESHOLD_SET: Set<string> = new Set(PANIC_THRESHOLDS);
+
+const librariesSchema = z.custom<typeof LIBRARIES_WILDCARD | string[]>().check((ctx) => {
+    const value = ctx.value;
+    if (value === LIBRARIES_WILDCARD) return;
+    if (!Array.isArray(value) || value.length === 0) {
+        ctx.issues.push(rawIssue(value, [], `must be "${LIBRARIES_WILDCARD}", a non-empty string array, or omitted`));
         return;
     }
-    if (library === LIBRARIES_WILDCARD) {
-        throw new Error(
-            'gtkx.config.ts: to generate every library, set `libraries: "*"` as a bare string, not an array entry',
+    value.forEach((entry, index) => {
+        if (typeof entry === "string" && GIR_LIBRARY_PATTERN.test(entry)) return;
+        if (entry === LIBRARIES_WILDCARD) {
+            ctx.issues.push(
+                rawIssue(
+                    value,
+                    [index],
+                    `to generate every library, set \`libraries: "${LIBRARIES_WILDCARD}"\` as a bare string, not an array entry`,
+                    true,
+                ),
+            );
+            return;
+        }
+        ctx.issues.push(
+            rawIssue(
+                value,
+                [index],
+                `invalid library identifier "${String(entry)}", must be of the form "Name-Version" (e.g. "Gtk-4.0")`,
+                true,
+            ),
         );
-    }
-    throw new Error(
-        `gtkx.config.ts: invalid library identifier "${String(library)}" — must be of the form "Name-Version" (e.g. "Gtk-4.0")`,
-    );
-};
+    });
+});
 
-const validateLibraries = (libraries: GtkxConfig["libraries"]): void => {
-    if (libraries === undefined || libraries === LIBRARIES_WILDCARD) {
-        return;
-    }
-    if (!Array.isArray(libraries) || libraries.length === 0) {
-        throw new Error('gtkx.config.ts: `libraries` must be "*", a non-empty string array, or omitted');
-    }
-    for (const library of libraries) {
-        validateLibraryEntry(library);
+const applicationIdSchema = z.custom<string>().check((ctx) => {
+    const value = ctx.value;
+    if (typeof value !== "string" || !isValidApplicationId(value)) {
+        ctx.issues.push(
+            rawIssue(
+                value,
+                [],
+                `invalid \`applicationId\` "${String(value)}", must satisfy g_application_id_is_valid (e.g. "org.example.MyApp")`,
+                true,
+            ),
+        );
     }
-};
+});
 
-const validateGirPath = (girPath: GtkxConfig["girPath"]): void => {
-    if (girPath !== undefined && !Array.isArray(girPath)) {
-        throw new Error("gtkx.config.ts: `girPath` must be an array of strings if provided");
+const reactCompilerSchema = z.custom<boolean | ReactCompilerOptions>().check((ctx) => {
+    const value = ctx.value;
+    if (typeof value === "boolean") return;
+    if (!isRecord(value)) {
+        ctx.issues.push(rawIssue(value, [], "must be a boolean or an options object"));
+        return;
     }
-};
-
-const validateApplicationId = (applicationId: GtkxConfig["applicationId"]): void => {
-    if (applicationId === undefined) return;
-    if (typeof applicationId !== "string" || !isValidApplicationId(applicationId)) {
-        throw new Error(
-            `gtkx.config.ts: invalid \`applicationId\` "${String(applicationId)}" — ` +
-                `must satisfy g_application_id_is_valid (e.g. "org.example.MyApp")`,
+    const compilationMode = value.compilationMode;
+    if (
+        compilationMode !== undefined &&
+        !(typeof compilationMode === "string" && COMPILATION_MODE_SET.has(compilationMode))
+    ) {
+        ctx.issues.push(
+            rawIssue(
+                value,
+                [],
+                `invalid \`reactCompiler.compilationMode\` "${String(compilationMode)}", must be one of ${COMPILATION_MODES.join(", ")}`,
+                true,
+            ),
         );
     }
-};
-
-const REACT_COMPILER_COMPILATION_MODES: ReactCompilerCompilationMode[] = ["infer", "syntax", "annotation", "all"];
-
-const REACT_COMPILER_PANIC_THRESHOLDS: ReactCompilerPanicThreshold[] = ["none", "critical_errors", "all_errors"];
-
-const validateReactCompilerEnum = <T extends string>(value: T | undefined, allowed: T[], field: string): void => {
-    if (value !== undefined && !allowed.includes(value)) {
-        throw new Error(
-            `gtkx.config.ts: invalid \`reactCompiler.${field}\` "${String(value)}" — must be one of ${allowed.join(", ")}`,
+    const panicThreshold = value.panicThreshold;
+    if (
+        panicThreshold !== undefined &&
+        !(typeof panicThreshold === "string" && PANIC_THRESHOLD_SET.has(panicThreshold))
+    ) {
+        ctx.issues.push(
+            rawIssue(
+                value,
+                [],
+                `invalid \`reactCompiler.panicThreshold\` "${String(panicThreshold)}", must be one of ${PANIC_THRESHOLDS.join(", ")}`,
+                true,
+            ),
         );
     }
-};
-
-const validateReactCompiler = (reactCompiler: GtkxConfig["reactCompiler"]): void => {
-    if (reactCompiler === undefined || typeof reactCompiler === "boolean") return;
-    if (typeof reactCompiler !== "object" || reactCompiler === null || Array.isArray(reactCompiler)) {
-        throw new Error("gtkx.config.ts: `reactCompiler` must be a boolean or an options object");
-    }
-    validateReactCompilerEnum(reactCompiler.compilationMode, REACT_COMPILER_COMPILATION_MODES, "compilationMode");
-    validateReactCompilerEnum(reactCompiler.panicThreshold, REACT_COMPILER_PANIC_THRESHOLDS, "panicThreshold");
-};
-
-export const validateGtkxConfig = (config: GtkxConfig): void => {
-    validateLibraries(config.libraries);
-    validateGirPath(config.girPath);
-    validateApplicationId(config.applicationId);
-    validateContainerPropRows(config.containerProps);
-    validateArrayPropRows(config.arrayProps);
-    validateObjectPropRows(config.objectProps);
-    validateVirtualPropRows(config.virtualProps);
-    validateElementMap(config.elementMap);
-    validateReactCompiler(config.reactCompiler);
-};
-
-export type GtkxConfigEnv = {
-    mode?: string;
-};
-
-export type GtkxConfigFn = (env: GtkxConfigEnv) => GtkxConfig;
-
-export type GtkxConfigFnPromise = (env: GtkxConfigEnv) => Promise<GtkxConfig>;
-
-export type GtkxConfigExport = GtkxConfig | Promise<GtkxConfig> | GtkxConfigFn | GtkxConfigFnPromise;
+});
 
-export function defineConfig(config: GtkxConfig): GtkxConfig;
-export function defineConfig(config: Promise<GtkxConfig>): Promise<GtkxConfig>;
-export function defineConfig(config: GtkxConfigFn): GtkxConfigFn;
-export function defineConfig(config: GtkxConfigFnPromise): GtkxConfigFnPromise;
-export function defineConfig(config: GtkxConfigExport): GtkxConfigExport;
-export function defineConfig(config: GtkxConfigExport): GtkxConfigExport {
-    return config;
-}
+const configSchema = z.object({
+    libraries: librariesSchema.optional(),
+    girPath: z.array(z.string(), { error: "must be an array of strings if provided" }).optional(),
+    applicationId: applicationIdSchema,
+    elementProps: elementPropsSchema.optional(),
+    reactCompiler: reactCompilerSchema.optional(),
+    codegen: z.boolean({ error: "must be a boolean" }).optional(),
+});
 
-const isMergeableObject = (value: unknown): value is Record<string, unknown> =>
-    typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * User-facing configuration for a GTKX project, as authored in `gtkx.config.ts`:
+ * the GIR libraries to bind, extra `.gir` search paths, the GApplication id,
+ * custom element prop mappings, and the React Compiler and codegen settings.
+ */
+export type Config = z.infer<typeof configSchema>;
 
-const mergeConfigValue = (base: unknown, override: unknown): unknown => {
-    if (override === undefined) return base;
-    if (base === undefined) return override;
-    if (Array.isArray(base) && Array.isArray(override)) return [...base, ...override];
-    if (isMergeableObject(base) && isMergeableObject(override)) {
-        const merged: Record<string, unknown> = { ...base };
-        for (const key of Object.keys(override)) {
-            merged[key] = mergeConfigValue(base[key], override[key]);
-        }
-        return merged;
-    }
-    return override;
+export const validateConfig = (config: Config): void => {
+    const result = configSchema.safeParse(config);
+    if (!result.success) throw configError(result.error);
 };
 
-export const mergeConfig = (base: GtkxConfig, override: GtkxConfig): GtkxConfig =>
-    mergeConfigValue(base, override) as GtkxConfig;
-
-export type ResolvedGtkxConfig = {
-    libraries: typeof LIBRARIES_WILDCARD | string[];
-    girPath: string[];
-    applicationId: string | undefined;
-    containerProps: PerElementPropRows<ContainerPropRow>;
-    arrayProps: PerElementPropRows<ArrayPropRow>;
-    objectProps: PerElementPropRows<ObjectPropRow>;
-    virtualProps: PerElementPropRows<VirtualPropRow>;
-    elementMap: ElementMapRule[];
+/**
+ * Identity helper that returns the given configuration typed as {@link Config},
+ * enabling editor autocompletion and type checking in `gtkx.config.ts`.
+ */
+export const defineConfig: DefineConfig<Config> = createDefineConfig<Config>();
+
+/**
+ * Deep-merges two configurations, with `override` taking precedence over `base`.
+ * @param base The lower-priority configuration.
+ * @param override The higher-priority configuration whose values win on conflict.
+ */
+export const mergeConfig = (base: Config, override: Config): Config => defu(override, base);
+
+/**
+ * Configuration reduced to the values needed at runtime: the GApplication
+ * identifier and the resolved React Compiler options (`null` when disabled).
+ */
+export type ResolvedConfig = {
+    applicationId: string;
     reactCompiler: ResolvedReactCompilerOptions | null;
 };
 
-export const resolveGtkxConfig = (config: GtkxConfig): ResolvedGtkxConfig => ({
-    libraries: config.libraries ?? [],
-    girPath: config.girPath ?? [],
+export const resolveConfig = (config: Config): ResolvedConfig => ({
     applicationId: config.applicationId,
-    containerProps: config.containerProps ?? {},
-    arrayProps: config.arrayProps ?? {},
-    objectProps: config.objectProps ?? {},
-    virtualProps: config.virtualProps ?? {},
-    elementMap: config.elementMap ?? [],
     reactCompiler: resolveReactCompilerOptions(config.reactCompiler),
 });
-