@gtkx/config 1.6.0 → 2.0.0-beta.10

package/dist/vite-plugin.js.map

@@ -1 +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,kBAAkB,EAAE,+BAA+B,EAAE,MAAM,cAAc,CAAC;AAQ3G,MAAM,gBAAgB,GAAG,CAAC,EAAU,EAAiB,EAAE,CACnD,EAAE,KAAK,sBAAsB,CAAC,CAAC,CAAC,+BAA+B,CAAC,CAAC,CAAC,IAAI,CAAC;AAE3E,MAAM,iBAAiB,GAAG,KAAK,EAC3B,EAAU,EACV,UAAwB,EACxB,KAAkB,EACS,EAAE;IAC7B,IAAI,EAAE,KAAK,+BAA+B,EAAE,CAAC;QACzC,OAAO,SAAS,CAAC;IACrB,CAAC;IAED,OAAO,kBAAkB,CAAC,MAAM,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;AACrF,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,kBAAkB,GAAG,CAAC,OAO3B,EAAU,EAAE;IACT,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,kBAAkB,EAAE,CAAC;IAC9D,MAAM,KAAK,GAAgB,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;IAE/C,OAAO;QACH,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,MAAM,CAAC,MAAkB;YACrB,KAAK,CAAC,IAAI,GAAG,MAAM,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,CAAC;YAEvC,OAAO,OAAO,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC;QACpC,CAAC;QACD,SAAS,EAAE,CAAC,EAAU,EAAE,EAAE,CAAC,gBAAgB,CAAC,EAAE,CAAC;QAC/C,IAAI,EAAE,CAAC,EAAU,EAAE,EAAE,CAAC,iBAAiB,CAAC,EAAE,EAAE,UAAU,EAAE,KAAK,CAAC;KACjE,CAAC;AACN,CAAC,CAAC;AAEF,eAAe,kBAAkB,CAAC","sourcesContent":["import type { Plugin, UserConfig } from \"vite\";\nimport { type ConfigLoader, createConfigLoader } from \"./loader.ts\";\nimport { GTKX_CONFIG_VIRTUAL_ID, renderConfigModule, RESOLVED_GTKX_CONFIG_VIRTUAL_ID } from \"./virtual.ts\";\n\n/** State the plugin carries from Vite's `config` hook to the virtual module it serves. */\ntype PluginState = {\n    /** Project root taken from Vite's `config` hook, undefined when the user config leaves it unset. */\n    root: string | undefined;\n};\n\nconst resolveVirtualId = (id: string): string | null =>\n    id === GTKX_CONFIG_VIRTUAL_ID ? RESOLVED_GTKX_CONFIG_VIRTUAL_ID : null;\n\nconst loadVirtualModule = async (\n    id: string,\n    loadConfig: ConfigLoader,\n    state: PluginState,\n): Promise<string | undefined> => {\n    if (id !== RESOLVED_GTKX_CONFIG_VIRTUAL_ID) {\n        return undefined;\n    }\n\n    return renderConfigModule(await loadConfig.resolve(state.root ?? process.cwd()));\n};\n\n/**\n * Creates a Vite plugin serving `virtual:gtkx-config`, the module carrying the project's resolved\n * `gtkx.config.ts`.\n */\nconst createConfigPlugin = (options: {\n    /** Name the plugin is registered under in Vite. */\n    name: string;\n    /** Loader the configuration is resolved through, defaulting to a fresh caching loader. */\n    loadConfig?: ConfigLoader;\n    /** Extra Vite configuration contributed from the plugin's `config` hook, given the user's own configuration. */\n    config?: (config: UserConfig) => Omit<UserConfig, \"plugins\">;\n}): Plugin => {\n    const loadConfig = options.loadConfig ?? createConfigLoader();\n    const state: PluginState = { root: undefined };\n\n    return {\n        name: options.name,\n        config(config: UserConfig) {\n            state.root = config.root ?? state.root;\n\n            return options.config?.(config);\n        },\n        resolveId: (id: string) => resolveVirtualId(id),\n        load: (id: string) => loadVirtualModule(id, loadConfig, state),\n    };\n};\n\nexport default createConfigPlugin;\n"]}
+{"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,kBAAkB,EAAE,+BAA+B,EAAE,MAAM,cAAc,CAAC;AAC3G,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAQjD,MAAM,aAAa,GAAG,IAAI,MAAM,CAAC,IAAI,sBAAsB,GAAG,CAAC,CAAC;AAChE,MAAM,sBAAsB,GAAG,IAAI,MAAM,CAAC,IAAI,+BAA+B,GAAG,CAAC,CAAC;AAElF,MAAM,gBAAgB,GAAG,CAAC,EAAU,EAAiB,EAAE,CACnD,EAAE,KAAK,sBAAsB,CAAC,CAAC,CAAC,+BAA+B,CAAC,CAAC,CAAC,IAAI,CAAC;AAE3E,MAAM,iBAAiB,GAAG,KAAK,EAC3B,EAAU,EACV,UAAwB,EACxB,KAAkB,EACS,EAAE;IAC7B,IAAI,EAAE,KAAK,+BAA+B,EAAE,CAAC;QACzC,OAAO,SAAS,CAAC;IACrB,CAAC;IAED,OAAO,kBAAkB,CAAC,MAAM,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;AACpE,CAAC,CAAC;AAEF;;;GAGG;AACH,MAAM,kBAAkB,GAAG,CAAC,OAO3B,EAAU,EAAE;IACT,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,kBAAkB,EAAE,CAAC;IAC9D,MAAM,KAAK,GAAgB,EAAE,IAAI,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC;IAEnD,OAAO;QACH,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,MAAM,CAAC,MAAkB;YACrB,KAAK,CAAC,IAAI,GAAG,eAAe,CAAC,MAAM,CAAC,CAAC;YAErC,OAAO,OAAO,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,CAAC;QACpC,CAAC;QACD,SAAS,EAAE;YACP,MAAM,EAAE,EAAE,EAAE,EAAE,aAAa,EAAE;YAC7B,OAAO,EAAE,CAAC,EAAU,EAAE,EAAE,CAAC,gBAAgB,CAAC,EAAE,CAAC;SAChD;QACD,IAAI,EAAE;YACF,MAAM,EAAE,EAAE,EAAE,EAAE,sBAAsB,EAAE;YACtC,OAAO,EAAE,CAAC,EAAU,EAAE,EAAE,CAAC,iBAAiB,CAAC,EAAE,EAAE,UAAU,EAAE,KAAK,CAAC;SACpE;KACJ,CAAC;AACN,CAAC,CAAC;AAEF,eAAe,kBAAkB,CAAC","sourcesContent":["import type { Plugin, UserConfig } from \"vite\";\nimport { type ConfigLoader, createConfigLoader } from \"./loader.ts\";\nimport { GTKX_CONFIG_VIRTUAL_ID, renderConfigModule, RESOLVED_GTKX_CONFIG_VIRTUAL_ID } from \"./virtual.ts\";\nimport { viteProjectRoot } from \"./vite-root.ts\";\n\n/** State the plugin carries from Vite's `config` hook to the virtual module it serves. */\ntype PluginState = {\n    /** Project root taken from Vite's `config` hook, falling back to the working directory. */\n    root: string;\n};\n\nconst VIRTUAL_ID_RE = new RegExp(`^${GTKX_CONFIG_VIRTUAL_ID}$`);\nconst RESOLVED_VIRTUAL_ID_RE = new RegExp(`^${RESOLVED_GTKX_CONFIG_VIRTUAL_ID}$`);\n\nconst resolveVirtualId = (id: string): string | null =>\n    id === GTKX_CONFIG_VIRTUAL_ID ? RESOLVED_GTKX_CONFIG_VIRTUAL_ID : null;\n\nconst loadVirtualModule = async (\n    id: string,\n    loadConfig: ConfigLoader,\n    state: PluginState,\n): Promise<string | undefined> => {\n    if (id !== RESOLVED_GTKX_CONFIG_VIRTUAL_ID) {\n        return undefined;\n    }\n\n    return renderConfigModule(await loadConfig.resolve(state.root));\n};\n\n/**\n * Creates a Vite plugin serving `virtual:gtkx-config`, the module carrying the project's resolved\n * `gtkx.config.ts`.\n */\nconst createConfigPlugin = (options: {\n    /** Name the plugin is registered under in Vite. */\n    name: string;\n    /** Loader the configuration is resolved through, defaulting to a fresh caching loader. */\n    loadConfig?: ConfigLoader;\n    /** Extra Vite configuration contributed from the plugin's `config` hook, given the user's own configuration. */\n    config?: (config: UserConfig) => Omit<UserConfig, \"plugins\">;\n}): Plugin => {\n    const loadConfig = options.loadConfig ?? createConfigLoader();\n    const state: PluginState = { root: process.cwd() };\n\n    return {\n        name: options.name,\n        config(config: UserConfig) {\n            state.root = viteProjectRoot(config);\n\n            return options.config?.(config);\n        },\n        resolveId: {\n            filter: { id: VIRTUAL_ID_RE },\n            handler: (id: string) => resolveVirtualId(id),\n        },\n        load: {\n            filter: { id: RESOLVED_VIRTUAL_ID_RE },\n            handler: (id: string) => loadVirtualModule(id, loadConfig, state),\n        },\n    };\n};\n\nexport default createConfigPlugin;\n"]}

package/dist/vite-root.d.ts

@@ -0,0 +1,9 @@
+type RootConfig = {
+    root?: string | undefined;
+    test?: {
+        root?: string | undefined;
+    } | undefined;
+};
+declare const viteProjectRoot: (config: RootConfig) => string;
+export { viteProjectRoot };
+//# sourceMappingURL=vite-root.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vite-root.d.ts","sourceRoot":"","sources":["../src/vite-root.ts"],"names":[],"mappings":"AAAA,KAAK,UAAU,GAAG;IACd,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAC1B,IAAI,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,GAAG,SAAS,CAAC;CACpD,CAAC;AAEF,QAAA,MAAM,eAAe,GAAI,QAAQ,UAAU,KAAG,MAA2D,CAAC;AAE1G,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/vite-root.js

@@ -0,0 +1,3 @@
+const viteProjectRoot = (config) => config.test?.root ?? config.root ?? process.cwd();
+export { viteProjectRoot };
+//# sourceMappingURL=vite-root.js.map

package/dist/vite-root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite-root.js","sourceRoot":"","sources":["../src/vite-root.ts"],"names":[],"mappings":"AAKA,MAAM,eAAe,GAAG,CAAC,MAAkB,EAAU,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,IAAI,MAAM,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,EAAE,CAAC;AAE1G,OAAO,EAAE,eAAe,EAAE,CAAC","sourcesContent":["type RootConfig = {\n    root?: string | undefined;\n    test?: { root?: string | undefined } | undefined;\n};\n\nconst viteProjectRoot = (config: RootConfig): string => config.test?.root ?? config.root ?? process.cwd();\n\nexport { viteProjectRoot };\n"]}

package/package.json

@@ -1,11 +1,13 @@
 {
   "name": "@gtkx/config",
-  "version": "1.6.0",
-  "description": "Config schema, loader, and element-prop mapping for the GTK toolchain.",
+  "version": "2.0.0-beta.10",
+  "description": "Configuration and element-prop mapping for Adwaita-first GTKX apps.",
   "keywords": [
     "gtkx",
     "gtk",
     "gtk4",
+    "adwaita",
+    "gnome",
     "react",
     "typescript",
     "config",
@@ -28,14 +30,20 @@
     "./package.json": "./package.json",
     ".": {
       "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": null,
       "default": "./dist/index.js"
     },
     "./internal": {
       "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js",
+      "require": null,
       "default": "./dist/internal.js"
     },
     "./vite-plugin": {
       "types": "./dist/vite-plugin.d.ts",
+      "import": "./dist/vite-plugin.js",
+      "require": null,
       "default": "./dist/vite-plugin.js"
     }
   },
@@ -55,14 +63,15 @@
     }
   },
   "engines": {
-    "node": ">=24"
+    "node": ">=26.7.0"
   },
   "dependencies": {
+    "@gtkx/utils": "2.0.0-beta.10",
     "c12": "^3.3.4",
     "defu": "^6.1.7",
+    "jiti": "^2.7.0",
     "vite": "^8.2.2",
-    "zod": "^4.4.3",
-    "@gtkx/utils": "1.6.0"
+    "zod": "^4.5.4"
   },
   "scripts": {
     "release": "tsx ../../scripts/release-package.ts"

package/src/config-dependencies.ts

@@ -0,0 +1,114 @@
+import { createJiti, type Jiti, type TransformOptions, type TransformResult } from "jiti";
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createRequire, registerHooks } from "node:module";
+import { extname, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+type CaptureState = { cacheKey: string; dependencies: Set<string>; transformer: Jiti };
+type CapturedConfig<T> = { dependencies: string[]; value: T };
+
+const captureStorage: AsyncLocalStorage<CaptureState> = new AsyncLocalStorage();
+const dependenciesByValue: WeakMap<object, string[]> = new WeakMap();
+const CACHE_BUSTED_EXTENSIONS: ReadonlySet<string> = new Set([".cjs", ".js", ".json", ".mjs"]);
+
+const isTrackedPath = (path: string): boolean => !path.includes(`${sep}node_modules${sep}`);
+
+const addPath = (path: string): void => {
+    if (isTrackedPath(path)) {
+        captureStorage.getStore()?.dependencies.add(path);
+    }
+};
+
+const addUrl = (url: string): void => {
+    if (url.startsWith("file:")) {
+        addPath(fileURLToPath(url));
+    }
+};
+
+const cacheBustedUrl = (url: string): string => {
+    if (!url.startsWith("file:")) {
+        return url;
+    }
+
+    const path = fileURLToPath(url);
+
+    if (!isTrackedPath(path) || !CACHE_BUSTED_EXTENSIONS.has(extname(path))) {
+        return url;
+    }
+
+    const parsed = new URL(url);
+    parsed.searchParams.set("gtkx-config-load", captureStorage.getStore()?.cacheKey ?? "uncaptured");
+
+    return parsed.href;
+};
+
+const registerResolutionHook = (): ReturnType<typeof registerHooks> =>
+    registerHooks({
+        resolve(specifier, context, nextResolve) {
+            const result = nextResolve(specifier, context);
+            addUrl(result.url);
+
+            return { ...result, url: cacheBustedUrl(result.url) };
+        },
+    });
+
+const clearNativeModuleCache = (dependencies: Iterable<string>): void => {
+    const cache = createRequire(import.meta.url).cache;
+
+    for (const path of dependencies) {
+        Reflect.deleteProperty(cache, path);
+    }
+};
+
+const transformConfigModule = (options: TransformOptions): TransformResult => {
+    const state = captureStorage.getStore();
+
+    if (state === undefined) {
+        throw new Error("Configuration transformation started outside a dependency capture");
+    }
+
+    if (options.filename !== undefined) {
+        addPath(options.filename);
+    }
+
+    return { code: state.transformer.transform(options) };
+};
+
+const setConfigDependencies = (value: object, dependencies: Iterable<string>): void => {
+    const paths = [...new Set(dependencies)];
+    dependenciesByValue.set(value, paths);
+    clearNativeModuleCache(paths);
+};
+
+const configDependenciesFor = (value: unknown): string[] =>
+    typeof value === "object" && value !== null ? dependenciesByValue.get(value) ?? [] : [];
+
+const captureConfigDependencies = async <T>(operation: () => Promise<T>): Promise<CapturedConfig<T>> => {
+    const state: CaptureState = {
+        cacheKey: process.hrtime.bigint().toString(),
+        dependencies: new Set(),
+        transformer: createJiti(import.meta.url, { fsCache: false, moduleCache: false }),
+    };
+    const hook = registerResolutionHook();
+
+    try {
+        const value = await captureStorage.run(state, operation);
+
+        return { dependencies: [...state.dependencies], value };
+    } catch (error) {
+        if (typeof error === "object" && error !== null) {
+            setConfigDependencies(error, state.dependencies);
+        }
+
+        throw error;
+    } finally {
+        hook.deregister();
+    }
+};
+
+export {
+    captureConfigDependencies,
+    configDependenciesFor,
+    setConfigDependencies,
+    transformConfigModule,
+};

package/src/config-error.ts

@@ -1,86 +1,18 @@
-import type { z } from "zod";
+import { z } from "zod";
 
-type IssuePath = (string | number)[];
-
-const CONFIG_PREFIX = "gtkx.config.ts:";
-const UNRECOGNIZED_KEY_REASON = "is not a recognized key";
+const DEFAULT_CONFIG_FILE = "gtkx.config.*";
 
 const isRecord = (value: unknown): value is Record<string, unknown> =>
     typeof value === "object" && value !== null && !Array.isArray(value);
 
-const rawIssue = (input: unknown, path: IssuePath, message: string, isStandalone = false) => ({
-    code: "custom" as const,
-    input,
-    path,
-    message,
-    continue: true as const,
-    ...(isStandalone && { params: { standalone: true } }),
-});
-
-const appendSegment = (path: string, segment: PropertyKey): string => {
-    if (typeof segment === "number") {
-        return `${path}[${String(segment)}]`;
-    }
-
-    return path === "" ? String(segment) : `${path}.${String(segment)}`;
-};
-
-const dottedPath = (segments: PropertyKey[]): string => {
-    let path = "";
-
-    for (const segment of segments) {
-        path = appendSegment(path, segment);
-    }
-
-    return path;
-};
-
-const isStandaloneIssue = (issue: z.core.$ZodIssue): boolean =>
-    "params" in issue && isRecord(issue.params) && issue.params.standalone === true;
-
-const unrecognizedKeyPath = (issue: z.core.$ZodIssue, fullPath: PropertyKey[]): string | undefined => {
-    if (issue.code === "unrecognized_keys") {
-        const [key] = issue.keys;
-
-        return dottedPath(key === undefined ? fullPath : [...fullPath, key]);
-    }
-
-    return issue.code === "invalid_key" ? dottedPath(fullPath) : undefined;
-};
-
-const keyRejectionReason = (issue: z.core.$ZodIssue): string => {
-    const nested = issue.code === "invalid_key" ? issue.issues[0] : undefined;
-
-    return nested?.code === "custom" ? nested.message : UNRECOGNIZED_KEY_REASON;
-};
-
-const formatIssue = (issue: z.core.$ZodIssue, fullPath: PropertyKey[]): string => {
-    const unrecognized = unrecognizedKeyPath(issue, fullPath);
-
-    if (unrecognized !== undefined) {
-        return `${CONFIG_PREFIX} \`${unrecognized}\` ${keyRejectionReason(issue)}`;
-    }
-
-    if (isStandaloneIssue(issue)) {
-        return `${CONFIG_PREFIX} ${issue.message}`;
-    }
-
-    const path = dottedPath(fullPath);
-
-    return path === "" ? `${CONFIG_PREFIX} ${issue.message}` : `${CONFIG_PREFIX} \`${path}\` ${issue.message}`;
-};
-
-const missingConfigFileError = (cwd: string): Error =>
-    new Error(`${CONFIG_PREFIX} no configuration file found in ${cwd}`);
-
-const configError = (error: z.ZodError): Error => {
-    const issue = error.issues[0];
+const configPrefix = (configFile: string): string => `${configFile}:`;
 
-    if (issue === undefined) {
-        return new Error(`${CONFIG_PREFIX} invalid configuration`);
-    }
+const missingConfigFileError = (cwd: string, configFile?: string): Error =>
+    new Error(configFile === undefined
+        ? `${configPrefix(DEFAULT_CONFIG_FILE)} no configuration file found in ${cwd}`
+        : `${configPrefix(configFile)} no configuration file found in ${cwd}`);
 
-    return new Error(formatIssue(issue, issue.path));
-};
+const configError = (error: z.ZodError, configFile = DEFAULT_CONFIG_FILE): Error =>
+    new Error(`${configPrefix(configFile)}\n${z.prettifyError(error)}`);
 
-export { isRecord, rawIssue, missingConfigFileError, configError };
+export { isRecord, missingConfigFileError, configError };

package/src/config.ts

@@ -2,23 +2,17 @@ import { createDefineConfig, type DefineConfig } from "c12";
 import { defu } from "defu";
 import { resolve } from "node:path";
 import { z } from "zod";
-import { configError, isRecord, rawIssue } from "./config-error.ts";
+import { configError, isRecord } from "./config-error.ts";
 import { deploySchema } from "./deploy.ts";
-import { DEPRECATION_IDS } from "./deprecations.ts";
-import { isGirLibrary, text } from "./schema-text.ts";
+import { girLibrary, text } from "./schema-text.ts";
 import { resolveUserEventSignals } from "./user-event-signals.ts";
 
-/** Accepted `reactCompiler.compilationMode` values, choosing which functions the compiler processes. */
-type ReactCompilerCompilationMode = (typeof COMPILATION_MODES)[number];
-/** Accepted `reactCompiler.panicThreshold` values, choosing which compiler diagnostics fail the build. */
-type ReactCompilerPanicThreshold = (typeof PANIC_THRESHOLDS)[number];
-
-/** Object form of the `reactCompiler` config key, forwarded as-is to `babel-plugin-react-compiler`. */
+/** Object form of the `reactCompiler` config key, forwarded to `babel-plugin-react-compiler`. */
 type ReactCompilerOptions = {
-    /** Which functions the compiler processes; left to the compiler's own default when omitted. */
-    compilationMode?: ReactCompilerCompilationMode;
-    /** Which compiler diagnostics fail the build; left to the compiler's own default when omitted. */
-    panicThreshold?: ReactCompilerPanicThreshold;
+    /** Which functions the compiler processes. */
+    compilationMode?: (typeof COMPILATION_MODES)[number];
+    /** Which compiler diagnostics fail the build. */
+    panicThreshold?: (typeof PANIC_THRESHOLDS)[number];
 };
 
 /**
@@ -33,9 +27,8 @@ type ResolvedReactCompilerOptions = ReactCompilerOptions & {
 /**
  * User-facing configuration for a GTKX project, as authored in `gtkx.config.ts`: the GIR libraries
  * to bind and where to find them, the GApplication id, per-element configuration, the React
- * Compiler, codegen, and user event signal settings, the `agents` and `mcp` blocks controlling what
- * coding agents are given, the `future` block opting into behavior that becomes the default in the
- * next major version, and the `deprecations` block silencing the warnings about flags left unset.
+ * Compiler, codegen, and user event signal settings, and the `agents` and `mcp` blocks controlling
+ * what coding agents are given.
  */
 type Config = z.infer<typeof configSchema>;
 type ModuleExport = z.infer<typeof moduleExportSchema>;
@@ -46,16 +39,6 @@ type McpSettings = {
     isReadOnly: boolean;
 };
 
-type ResolvedFuture = {
-    isByteArrayTyped: boolean;
-    isValueUnwrapped: boolean;
-    isFinishTrimmed: boolean;
-    isInoutInPlace: boolean;
-    isResourceImported: boolean;
-    isAdwaitaDefault: boolean;
-    isTreeShaken: boolean;
-};
-
 /** Configuration reduced to the values the app runtime and the build need, with paths already resolved. */
 type ResolvedConfig = {
     /** The GApplication identifier the app registers under. */
@@ -73,92 +56,35 @@ type ResolvedConfig = {
     lazyElements: string[];
 };
 
-const LIBRARIES_WILDCARD = "*";
 const APPLICATION_ID_PATTERN = /^[A-Za-z_][A-Za-z0-9_-]*(\.[A-Za-z_][A-Za-z0-9_-]*)+$/;
 const APPLICATION_ID_MAX_LENGTH = 255;
+const IMPLICIT_LIBRARIES: Set<string> = new Set(["Adw-1", "Gtk-4.0"]);
 /** Compilation modes `babel-plugin-react-compiler` accepts. */
 const COMPILATION_MODES = ["infer", "syntax", "annotation", "all"] as const;
 /** Panic thresholds `babel-plugin-react-compiler` accepts. */
 const PANIC_THRESHOLDS = ["none", "critical_errors", "all_errors"] as const;
 const REACT_COMPILER_TARGET = "19";
-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`));
+const librarySchema = girLibrary('must be of the form "Name-Version", such as "Adw-1"')
+    .refine((library) => !IMPLICIT_LIBRARIES.has(library), { error: "is bound implicitly; remove it" });
 
-        return;
-    }
-
-    for (const [index, entry] of value.entries()) {
-        ctx.issues.push(...libraryEntryIssues(value, index, entry));
-    }
-});
+const librariesSchema = z
+    .array(librarySchema, { error: "must be a non-empty string array or omitted" })
+    .min(1, { error: "must be a non-empty string array or omitted" });
 
-const applicationIdSchema = z.custom<string>().check((ctx) => {
-    const value = ctx.value;
-
-    if (typeof value !== "string" || !isValidApplicationId(value)) {
-        ctx.issues.push(
-            rawIssue(
-                value,
-                [],
-                `invalid \`applicationId\` "${value}", must satisfy g_application_id_is_valid ` +
-                '(e.g. "org.example.MyApp")',
-                true,
-            ),
-        );
-    }
-});
+const applicationIdSchema = z
+    .string({ error: "must satisfy g_application_id_is_valid" })
+    .refine((value) => isValidApplicationId(value), {
+        error: 'must satisfy g_application_id_is_valid, such as "org.example.MyApp"',
+    });
 
-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 compilationMode = value.compilationMode;
-
-    if (!isValidReactCompilerOption(compilationMode, COMPILATION_MODE_SET)) {
-        ctx.issues.push(
-            rawIssue(
-                value,
-                [],
-                `invalid \`reactCompiler.compilationMode\` "${String(compilationMode)}", ` +
-                `must be one of ${COMPILATION_MODES.join(", ")}`,
-                true,
-            ),
-        );
-    }
-
-    const panicThreshold = value.panicThreshold;
-
-    if (!isValidReactCompilerOption(panicThreshold, PANIC_THRESHOLD_SET)) {
-        ctx.issues.push(
-            rawIssue(
-                value,
-                [],
-                `invalid \`reactCompiler.panicThreshold\` "${String(panicThreshold)}", ` +
-                `must be one of ${PANIC_THRESHOLDS.join(", ")}`,
-                true,
-            ),
-        );
-    }
-});
+const reactCompilerSchema = z.union([
+    z.boolean(),
+    z.object({
+        compilationMode: z.enum(COMPILATION_MODES).optional(),
+        panicThreshold: z.enum(PANIC_THRESHOLDS).optional(),
+    }),
+]);
 
 const userEventSignalsSchema = z.record(
     z.string(),
@@ -215,30 +141,28 @@ const mcpSchema = z.object({
     readOnly: z.boolean({ error: "must be a boolean" }).optional(),
 });
 
-const futureSchema = z.object({
-    v2ByteArrays: z.boolean({ error: "must be a boolean" }).optional(),
-    v2ValueReturns: z.boolean({ error: "must be a boolean" }).optional(),
-    v2FinishResults: z.boolean({ error: "must be a boolean" }).optional(),
-    v2InoutReturns: z.boolean({ error: "must be a boolean" }).optional(),
-    v2ResourceImports: z.boolean({ error: "must be a boolean" }).optional(),
-    v2DefaultLibraries: z.boolean({ error: "must be a boolean" }).optional(),
-    v2TreeShaking: z.boolean({ error: "must be a boolean" }).optional(),
-});
-
-const FUTURE_KEYS: Set<string> = new Set(Object.keys(futureSchema.shape));
-const DEPRECATION_ID_ERROR = `must be one of ${DEPRECATION_IDS.join(", ")}`;
+const graduatedFutureSchema = z
+    .object({
+        v2ByteArrays: z.literal(true, { error: "can only be true; remove the flag" }).optional(),
+        v2ValueReturns: z.literal(true, { error: "can only be true; remove the flag" }).optional(),
+        v2FinishResults: z.literal(true, { error: "can only be true; remove the flag" }).optional(),
+        v2InoutReturns: z.literal(true, { error: "can only be true; remove the flag" }).optional(),
+        v2ResourceImports: z.literal(true, { error: "can only be true; remove the flag" }).optional(),
+        v2DefaultLibraries: z.literal(true, { error: "can only be true; remove the flag" }).optional(),
+        v2TreeShaking: z.literal(true, { error: "can only be true; remove the flag" }).optional(),
+    })
+    .strict();
 
 const deprecationsSchema = z.object({
     silence: z
-        .array(z.enum(DEPRECATION_IDS, { error: DEPRECATION_ID_ERROR }), {
-            error: "must be an array of deprecation ids",
+        .array(z.never({ error: "does not name a current deprecation" }), {
+            error: "must be an array of current deprecation ids",
         })
         .optional(),
 });
 
 /** Schema every `gtkx.config.ts` is validated against, and the source of the {@link Config} type. */
 const configSchema = z.object({
-    future: futureSchema.optional(),
     libraries: librariesSchema.optional(),
     girPath: z.array(z.string(), { error: "must be an array of strings if provided" }).optional(),
     applicationId: applicationIdSchema,
@@ -258,34 +182,10 @@ const configSchema = z.object({
  * autocompletion and type checking.
  */
 const defineConfig: DefineConfig<Config> = createDefineConfig<Config>();
+const validationSchema = configSchema.extend({ future: graduatedFutureSchema.optional() });
 
-const libraryEntryIssues = (value: unknown[], index: number, entry: unknown): ReturnType<typeof rawIssue>[] => {
-    if (typeof entry === "string" && isGirLibrary(entry)) {
-        return [];
-    }
-
-    if (entry === LIBRARIES_WILDCARD) {
-        const message =
-            `to generate every library, set \`libraries: "${LIBRARIES_WILDCARD}"\` as a bare string, ` +
-            "not an array entry";
-
-        return [rawIssue(value, [index], message, true)];
-    }
-
-    const message =
-        `invalid library identifier "${String(entry)}", must be of the form "Name-Version" ` +
-        '(e.g. "Gtk-4.0")';
-
-    return [rawIssue(value, [index], message, true)];
-};
-
-const isValidApplicationId = (applicationId: string): boolean => {
-    if (applicationId.length === 0 || applicationId.length > APPLICATION_ID_MAX_LENGTH) {
-        return false;
-    }
-
-    return APPLICATION_ID_PATTERN.test(applicationId);
-};
+const isValidApplicationId = (applicationId: string): boolean =>
+    applicationId.length <= APPLICATION_ID_MAX_LENGTH && APPLICATION_ID_PATTERN.test(applicationId);
 
 const resolveReactCompilerOptions = (setting: Config["reactCompiler"]): ResolvedReactCompilerOptions | null => {
     if (setting === false) {
@@ -294,20 +194,29 @@ const resolveReactCompilerOptions = (setting: Config["reactCompiler"]): Resolved
 
     const overrides = setting === undefined || setting === true ? {} : setting;
 
-    return { ...overrides, target: REACT_COMPILER_TARGET };
+    return {
+        ...(overrides.compilationMode !== undefined && { compilationMode: overrides.compilationMode }),
+        ...(overrides.panicThreshold !== undefined && { panicThreshold: overrides.panicThreshold }),
+        target: REACT_COMPILER_TARGET,
+    };
 };
 
-const isValidReactCompilerOption = (value: unknown, allowed: Set<string>): boolean =>
-    value === undefined || (typeof value === "string" && allowed.has(value));
-
-const validateConfig = (config: Config): void => {
-    const result = configSchema.safeParse(config);
+const validateConfig = (config: unknown, configFile?: string): void => {
+    const result = validationSchema.safeParse(config);
 
     if (!result.success) {
-        throw configError(result.error);
+        throw configError(result.error, configFile);
     }
 };
 
+const graduatedFutureKeys = (config: unknown): string[] => {
+    if (!isRecord(config) || !isRecord(config.future)) {
+        return [];
+    }
+
+    return Object.keys(config.future).toSorted((first, second) => first.localeCompare(second));
+};
+
 /**
  * Deep-merges a configuration over a base. `override` wins over `base` on conflicting scalar and object keys, while
  * arrays are concatenated with the `override` entries first.
@@ -356,19 +265,6 @@ const resolveMcpSettings = (config: Config): McpSettings => ({
     isReadOnly: config.mcp?.readOnly === true,
 });
 
-const resolveFuture = (future: Config["future"]): ResolvedFuture => ({
-    isByteArrayTyped: future?.v2ByteArrays === true,
-    isValueUnwrapped: future?.v2ValueReturns === true,
-    isFinishTrimmed: future?.v2FinishResults === true,
-    isInoutInPlace: future?.v2InoutReturns === true,
-    isResourceImported: future?.v2ResourceImports === true,
-    isAdwaitaDefault: future?.v2DefaultLibraries === true,
-    isTreeShaken: future?.v2TreeShaking === true,
-});
-
-const unknownFutureKeys = (future: Config["future"]): string[] =>
-    Object.keys(future ?? {}).filter((key) => !FUTURE_KEYS.has(key));
-
 const resolveConfig = (config: Config, root?: string): ResolvedConfig => ({
     applicationId: config.applicationId,
     reactCompiler: resolveReactCompilerOptions(config.reactCompiler),
@@ -383,6 +279,7 @@ export {
     isAgentReferenceEnabled,
     isAgentRulesEnabled,
     isValidApplicationId,
+    graduatedFutureKeys,
     validateConfig,
     mergeConfig,
     resolveLazyElements,
@@ -391,11 +288,8 @@ export {
     resolveMcpSettings,
     resolveOmittedProps,
     resolveConfig,
-    resolveFuture,
-    unknownFutureKeys,
     type McpSettings,
     type ResolvedReactCompilerOptions,
     type Config,
     type ResolvedConfig,
-    type ResolvedFuture,
 };