codex-configurator 0.2.5 → 0.2.7

package/README.md

@@ -39,7 +39,7 @@ npm start
 - `↑` `↓` : move selection
 - `PgUp` `PgDn`: move one page up/down
 - `Home` `End`: jump to first/last item
-- `Enter`: open selected table; for mixed scalar/object settings, choose a preset first (object presets open nested settings); for boolean settings, toggle directly; for string settings, open inline input; for other preset values, open picker
+- `Enter`: open selected table; for mixed scalar/object settings, choose a preset first (object presets open nested settings); for boolean settings, toggle directly; for string and numeric scalar settings, open inline input; for other preset values, open picker
 - `Del`: unset selected value or remove selected custom `<id>` entry from `config.toml`
 - `←` / `Backspace`: move up one level (to parent table)
 - `:`: enter command mode
@@ -49,7 +49,7 @@ npm start
 - `:help`: toggle quick help overlay
 - `:quit` (or `:q`): quit
 
-The right-hand pane shows what each setting means, plus a picker when a value has preset options.
+The right-hand pane shows what each setting means, the current configured value for plain scalar settings, and a picker when a value has preset options.
 Deprecated settings are marked with a `[!]` warning marker; only that marker is highlighted.
 Model picker entries are curated presets maintained by this project.
 In select lists, `[default]` marks the default option.
@@ -120,6 +120,8 @@ You can override either command with:
 - `CODEX_CONFIGURATOR_CODEX_BIN=<command-or-path>`
 - `CODEX_CONFIGURATOR_NPM_BIN=<command-or-path>`
 
+The status bar shows `Using Codex v<version>` only after Codex version detection completes. During startup schema sync it shows `Checking schema`, and after that it shows `Checking Codex version` until the Codex check finishes. When needed, it shows Codex update state as `Update available` or `Version check unavailable`; if there is no warning badge, assume Codex is up to date. The schema-progress state is kept visible for at least `1.2s` so it is observable even on very fast connections. The Codex version check starts only after schema sync completes.
+
 ## Self-update behavior
 
 On startup, the app checks the npm registry for the latest `codex-configurator` version.
@@ -132,7 +134,17 @@ This uses the `npm` command from `PATH` (or `CODEX_CONFIGURATOR_NPM_BIN` if set)
 ## Upstream reference
 
 - Canonical config schema: https://developers.openai.com/codex/config-schema.json
-- The local menu reads directly from `src/reference/config-schema.json`, which is downloaded from the canonical schema.
+- Runtime behavior:
+  - App starts with bundled fallback schema from `src/reference/config-schema.json`.
+  - App then checks for updates on startup in the background.
+  - If a valid cached schema exists, it is loaded immediately.
+  - If upstream has a newer valid schema, it is applied immediately and cached for future launches.
+  - If the check fails, the app silently continues with the already-active schema.
+- Runtime cache location: `<codex-dir>/codex-configurator-cache/`
+  - Default codex dir: `~/.codex`
+  - Cached files:
+    - `config-schema.json`
+    - `config-schema.meta.json`
 - To refresh the reference snapshot after a new stable Codex release:
   - `npm run sync:reference`
 - Snapshot currently synced against Codex stable reference updates published on 2026-02-25.

package/index.js

@@ -20,11 +20,13 @@ import {
 	writeConfig,
 } from './src/configParser.js';
 import { getConfigOptions, getConfigVariantMeta } from './src/configHelp.js';
-import {
-	getReferenceOptionForPath,
-	getReferenceCustomIdPlaceholder,
-} from './src/configReference.js';
+import { getReferenceCustomIdPlaceholder } from './src/configReference.js';
 import { normalizeCustomPathId } from './src/customPathId.js';
+import {
+	getReferenceScalarType,
+	getScalarEditType,
+	parseScalarDraftValue,
+} from './src/scalarEditing.js';
 import {
 	applyVariantSelection,
 	buildVariantSelectorOptions,
@@ -36,6 +38,7 @@ import {
 import {
 	APP_MODES,
 	APP_STATE_ACTION,
+	REFERENCE_SCHEMA_CHANGED_ACTION,
 	appStateReducer,
 	buildInitialAppState,
 } from './src/appState.js';
@@ -43,6 +46,7 @@ import { pathToKey, clamp, computeListViewportRows } from './src/layout.js';
 import { Header } from './src/components/Header.js';
 import { ConfigNavigator } from './src/components/ConfigNavigator.js';
 import { filterRowsByQuery } from './src/fuzzySearch.js';
+import { syncReferenceSchemaAtStartup } from './src/schemaRuntimeSync.js';
 import { executeInputCommand, getModeHint } from './src/ui/commands.js';
 import { CommandBar } from './src/ui/panes/CommandBar.js';
 import { HelpBubble } from './src/ui/panes/HelpBubble.js';
@@ -52,17 +56,6 @@ import { StatusLine } from './src/ui/panes/StatusLine.js';
 const require = createRequire(import.meta.url);
 const { version: PACKAGE_VERSION = 'unknown' } = require('./package.json');
 
-const isStringReferenceType = (type) =>
-	/^string(?:\s|$)/.test(String(type || '').trim());
-
-const isStringField = (pathSegments, value) => {
-	if (typeof value === 'string') {
-		return true;
-	}
-
-	return isStringReferenceType(getReferenceOptionForPath(pathSegments)?.type);
-};
-
 const isCustomIdTableRow = (pathSegments, row) =>
 	row?.kind === 'table' &&
 	typeof row?.pathSegment === 'string' &&
@@ -75,6 +68,7 @@ const UPDATE_MAX_BUFFER_BYTES = 10 * 1024 * 1024;
 const CODEX_BIN_ENV_VAR = 'CODEX_CONFIGURATOR_CODEX_BIN';
 const NPM_BIN_ENV_VAR = 'CODEX_CONFIGURATOR_NPM_BIN';
 const CONFIGURATOR_PACKAGE_NAME = 'codex-configurator';
+const SCHEMA_STATUS_MIN_VISIBLE_MS = 1200;
 const FILE_SWITCH_MAX_VISIBLE_ENTRIES = 6;
 const FILE_SWITCH_PANEL_BASE_ROWS = 3;
 const FILE_SWITCH_LAYOUT_EXTRA_GAP_ROWS = 1;
@@ -174,6 +168,11 @@ const runCommand = async (command, args = [], options = {}) => {
 	return result.stdout;
 };
 
+const waitForMilliseconds = (milliseconds) =>
+	new Promise((resolve) => {
+		setTimeout(resolve, Math.max(0, Number(milliseconds) || 0));
+	});
+
 const getConfiguredCommand = (environmentVariableName, fallbackCommand) => {
 	const configuredCommand = String(
 		process.env[environmentVariableName] || '',
@@ -364,7 +363,7 @@ const getCodexUpdateStatus = async () => {
 		return {
 			installed: installedLabel,
 			latest: 'unknown',
-			status: 'version check unavailable',
+			status: 'Version check unavailable',
 		};
 	}
 
@@ -380,7 +379,7 @@ const getCodexUpdateStatus = async () => {
 		return {
 			installed,
 			latest: 'unknown',
-			status: 'version check unavailable',
+			status: 'Version check unavailable',
 		};
 	}
 
@@ -389,14 +388,14 @@ const getCodexUpdateStatus = async () => {
 		return {
 			installed,
 			latest,
-			status: `update available: ${latest}`,
+			status: 'Update available',
 		};
 	}
 
 	return {
 		installed,
 		latest,
-		status: 'up to date',
+		status: 'Up to date',
 	};
 };
 
@@ -470,6 +469,8 @@ const App = () => {
 		});
 	const setStateBatch = (updates) =>
 		dispatch({ type: APP_STATE_ACTION, payload: { updates } });
+	const resetSchemaDerivedEditState = () =>
+		dispatch({ type: REFERENCE_SCHEMA_CHANGED_ACTION });
 
 	const setSnapshot = (valueOrUpdater) =>
 		setAppState('snapshot', valueOrUpdater);
@@ -517,6 +518,10 @@ const App = () => {
 		setAppState('codexVersion', valueOrUpdater);
 	const setCodexVersionStatus = (valueOrUpdater) =>
 		setAppState('codexVersionStatus', valueOrUpdater);
+	const setIsSchemaCheckInProgress = (valueOrUpdater) =>
+		setAppState('isSchemaCheckInProgress', valueOrUpdater);
+	const setSchemaCheckStatusText = (valueOrUpdater) =>
+		setAppState('schemaCheckStatusText', valueOrUpdater);
 	const {
 		snapshot,
 		snapshotByFileId,
@@ -538,6 +543,8 @@ const App = () => {
 		showHelp,
 		codexVersion,
 		codexVersionStatus,
+		isSchemaCheckInProgress,
+		schemaCheckStatusText,
 	} = state;
 	commandInputRef.current = String(commandInput || '');
 	const { exit } = useApp();
@@ -552,6 +559,10 @@ const App = () => {
 					: APP_MODES.BROWSE;
 
 	useEffect(() => {
+		if (isSchemaCheckInProgress) {
+			return undefined;
+		}
+
 		let isCancelled = false;
 
 		const loadVersionStatus = async () => {
@@ -570,9 +581,56 @@ const App = () => {
 			await ensureLatestConfiguratorVersion(commands.npmCommand);
 		};
 
+		setCodexVersionStatus('Checking Codex version');
 		loadVersionStatus();
 		ensureLatestConfigurator();
 
+		return () => {
+			isCancelled = true;
+		};
+	}, [isSchemaCheckInProgress]);
+
+	useEffect(() => {
+		let isCancelled = false;
+
+		const syncSchemaReference = async () => {
+			const checkStartedAt = Date.now();
+			const updateSchemaStatus = (status) => {
+				if (isCancelled) {
+					return;
+				}
+
+				setSchemaCheckStatusText(status);
+			};
+
+			await syncReferenceSchemaAtStartup({
+				mainConfigPath: initialMainSnapshot.path,
+				onSchemaChange: () => {
+					if (isCancelled) {
+						return;
+					}
+
+					resetSchemaDerivedEditState();
+				},
+				onStatus: updateSchemaStatus,
+			});
+
+			const elapsed = Date.now() - checkStartedAt;
+			const remainingVisibleMs = SCHEMA_STATUS_MIN_VISIBLE_MS - elapsed;
+			if (remainingVisibleMs > 0) {
+				await waitForMilliseconds(remainingVisibleMs);
+			}
+
+			if (isCancelled) {
+				return;
+			}
+
+			setSchemaCheckStatusText('');
+			setIsSchemaCheckInProgress(false);
+		};
+
+		syncSchemaReference();
+
 		return () => {
 			isCancelled = true;
 		};
@@ -822,13 +880,14 @@ const App = () => {
 		});
 	};
 
-	const beginTextEditing = (target, targetPath) => {
+	const beginScalarEditing = (target, targetPath, scalarType) => {
 		setEditError('');
 		setEditMode({
-			mode: 'text',
+			mode: 'scalar',
+			scalarType,
 			path: targetPath,
-			draftValue: typeof target.value === 'string' ? target.value : '',
-			savedValue: null,
+			draftValue:
+				typeof target.value === 'undefined' ? '' : String(target.value),
 		});
 	};
 
@@ -961,15 +1020,24 @@ const App = () => {
 		setEditError('');
 	};
 
-	const applyTextEdit = () => {
-		if (!editMode || editMode.mode !== 'text') {
+	const applyScalarEdit = () => {
+		if (!editMode || editMode.mode !== 'scalar') {
+			return;
+		}
+
+		const parsedValue = parseScalarDraftValue(
+			editMode.draftValue,
+			editMode.scalarType,
+		);
+		if (!parsedValue.ok) {
+			setEditError(parsedValue.error);
 			return;
 		}
 
 		const nextData = setValueAtPath(
 			snapshot.ok ? snapshot.data : {},
 			editMode.path,
-			editMode.draftValue,
+			parsedValue.value,
 		);
 		if (!ensureAgentConfigFile(nextData, editMode.path)) {
 			return;
@@ -1062,17 +1130,13 @@ const App = () => {
 						undefined,
 						'value',
 					) || [];
-				if (requiredOptions.length > 0) {
-					return requiredOptions[0];
-				}
+					if (requiredOptions.length > 0) {
+						return requiredOptions[0];
+					}
 
-				if (
-					isStringReferenceType(
-						getReferenceOptionForPath(requiredPath)?.type,
-					)
-				) {
-					return '';
-				}
+					if (getReferenceScalarType(requiredPath) === 'string') {
+						return '';
+					}
 
 				return {};
 			},
@@ -1273,28 +1337,28 @@ const App = () => {
 					setCommandInput,
 					getCommandInput: () => commandInputRef.current,
 					setCommandMessage,
-					setEditError,
-					beginAddIdEditing,
-					beginTextEditing,
-					beginVariantEditing,
-					beginEditing,
-					beginFileSwitchMode,
-					applyFileSwitch,
-					applyTextEdit,
-					applyAddId,
-					applyVariantEdit,
-					applyEdit,
+						setEditError,
+						beginAddIdEditing,
+						beginScalarEditing,
+						beginVariantEditing,
+						beginEditing,
+						beginFileSwitchMode,
+						applyFileSwitch,
+						applyScalarEdit,
+						applyAddId,
+						applyVariantEdit,
+						applyEdit,
 					applyBooleanToggle,
 					unsetValueAtPath,
 					openPathView,
 					reloadActiveConfig,
 					getConfigOptions: getConfigOptions,
-					getConfigVariantMeta,
-					getNodeAtPath,
-					buildRows,
-					isStringField,
-					isCustomIdTableRow,
-					resolveMixedVariantBackNavigationPath,
+						getConfigVariantMeta,
+						getNodeAtPath,
+						buildRows,
+						getScalarEditType,
+						isCustomIdTableRow,
+						resolveMixedVariantBackNavigationPath,
 					adjustScrollForSelection,
 					getSavedIndex,
 					readActiveConfigSnapshot,
@@ -1447,6 +1511,8 @@ const App = () => {
 		React.createElement(StatusLine, {
 			codexVersion,
 			codexVersionStatus,
+			isSchemaCheckInProgress,
+			schemaCheckStatusText,
 			activeConfigFile,
 			appMode,
 		}),

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "codex-configurator",
-	"version": "0.2.5",
+	"version": "0.2.7",
 	"description": "TOML-aware Ink TUI for Codex Configurator",
 	"main": "index.js",
 	"type": "module",

package/src/appState.js

@@ -1,4 +1,5 @@
 export const APP_STATE_ACTION = 'APP_STATE_ACTION';
+export const REFERENCE_SCHEMA_CHANGED_ACTION = 'REFERENCE_SCHEMA_CHANGED_ACTION';
 
 export const APP_MODES = {
   BROWSE: 'browse',
@@ -9,6 +10,14 @@ export const APP_MODES = {
 };
 
 export const appStateReducer = (state, action) => {
+  if (action.type === REFERENCE_SCHEMA_CHANGED_ACTION) {
+    return {
+      ...state,
+      editMode: null,
+      editError: '',
+    };
+  }
+
   if (action.type !== APP_STATE_ACTION) {
     return state;
   }
@@ -66,4 +75,6 @@ export const buildInitialAppState = (initialMainSnapshot, initialCatalog, initia
   showHelp: false,
   codexVersion: 'version loading...',
   codexVersionStatus: '',
+  isSchemaCheckInProgress: true,
+  schemaCheckStatusText: 'Checking schema',
 });

package/src/components/ConfigNavigator.js

@@ -10,6 +10,7 @@ import {
 import { computePaneWidths, clamp } from '../layout.js';
 import { getNodeAtPath, buildRows } from '../configParser.js';
 import { filterRowsByQuery } from '../fuzzySearch.js';
+import { getReadOnlyValuePreviewText } from '../valuePreview.js';
 import {
 	buildVariantSelectorOptions,
 	isObjectValue,
@@ -112,7 +113,7 @@ const renderArrayDetails = (rows) => {
 	);
 };
 
-const renderTextEditor = (draftValue) =>
+const renderScalarEditor = (draftValue, scalarType) =>
 	React.createElement(
 		React.Fragment,
 		null,
@@ -124,7 +125,13 @@ const renderTextEditor = (draftValue) =>
 		React.createElement(
 			Text,
 			{ color: 'gray', wrap: 'truncate-end' },
-			'Type to edit • Enter: save • Esc: cancel',
+			`Type ${
+				scalarType === 'string'
+					? 'text'
+					: scalarType === 'integer'
+						? 'integer'
+						: 'number'
+			} • Enter: save • Esc: cancel`,
 		),
 	);
 
@@ -416,6 +423,10 @@ export const ConfigNavigator = ({
 	);
 	const shouldShowReadOnlyOptions =
 		readOnlyOptions.length > 0 && !isBooleanOnlyOptions(readOnlyOptions);
+	const readOnlyValuePreviewText = getReadOnlyValuePreviewText(
+		selectedRow,
+		shouldShowReadOnlyOptions,
+	);
 
 	const editRow = rows[selected] || null;
 	const editDefaultOption =
@@ -471,8 +482,8 @@ export const ConfigNavigator = ({
 			)
 		: null;
 	const optionSelector = editMode
-		? editMode.mode === 'text'
-			? renderTextEditor(editMode.draftValue)
+		? editMode.mode === 'scalar'
+			? renderScalarEditor(editMode.draftValue, editMode.scalarType)
 			: editMode.mode === 'add-id'
 				? renderIdEditor(editMode.placeholder, editMode.draftValue)
 				: renderEditableOptions(
@@ -497,6 +508,17 @@ export const ConfigNavigator = ({
 						false,
 					),
 				)
+			: readOnlyValuePreviewText
+				? React.createElement(
+						React.Fragment,
+						null,
+						React.createElement(Text, { color: 'gray' }, ' '),
+						React.createElement(
+							Text,
+							{ color: 'white', wrap: 'truncate-end' },
+							readOnlyValuePreviewText,
+						),
+					)
 			: selectedRow?.kind === 'array'
 				? renderArrayDetails(selectedRow.value)
 				: null;

package/src/components/Header.js

@@ -26,9 +26,4 @@ export const Header = ({ packageVersion }) =>
 				`v${packageVersion || 'unknown'}`,
 			),
 		),
-		React.createElement(
-			Text,
-			{ color: 'white', dimColor: false },
-			'TUI Mode ',
-		),
 	);

package/src/configFeatures.js

@@ -35,25 +35,24 @@ const buildFeatureDefinitionFromReference = (key) => {
   };
 };
 
-const DOCUMENTED_REFERENCE_FEATURE_KEYS = getReferenceFeatureKeys();
-
-export const CONFIG_FEATURE_DEFINITIONS = DOCUMENTED_REFERENCE_FEATURE_KEYS
-  .map((key) => buildFeatureDefinitionFromReference(key))
-  .filter(Boolean);
-
-const FEATURE_DEFINITION_MAP = CONFIG_FEATURE_DEFINITIONS.reduce((acc, definition) => {
-  acc[definition.key] = definition;
-
-  return acc;
-}, {});
+const buildFeatureDefinitionMap = () =>
+  getReferenceFeatureKeys()
+    .map((key) => buildFeatureDefinitionFromReference(key))
+    .filter(Boolean)
+    .reduce((acc, definition) => {
+      acc[definition.key] = definition;
+      return acc;
+    }, {});
 
 export const getConfigFeatureKeys = () => {
-  return DOCUMENTED_REFERENCE_FEATURE_KEYS;
+  return getReferenceFeatureKeys();
 };
 
-export const getConfigFeatureDefinition = (key) => FEATURE_DEFINITION_MAP[key];
+export const getConfigFeatureDefinition = (key) =>
+  buildFeatureDefinitionMap()[String(key || '').trim()];
 
 export const getConfigFeatureDefinitionOrFallback = (key) => {
+  const normalizedKey = String(key || '').trim();
   if (!key) {
     return {
       short: `${prettifyFeatureName(String(key))}`,
@@ -64,9 +63,9 @@ export const getConfigFeatureDefinitionOrFallback = (key) => {
   }
 
   return (
-    FEATURE_DEFINITION_MAP[key] || {
-      key,
-      short: prettifyFeatureName(String(key)),
+    getConfigFeatureDefinition(normalizedKey) || {
+      key: normalizedKey,
+      short: prettifyFeatureName(normalizedKey),
       usage: 'This configured key is not in the official feature list.',
       defaultValue: false,
       isDocumented: false,

package/src/configReference.js

@@ -1,7 +1,7 @@
 import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
-const CONFIG_SCHEMA_DATA = require('./reference/config-schema.json');
+const BUNDLED_CONFIG_SCHEMA_DATA = require('./reference/config-schema.json');
 
 const ROOT_PLACEHOLDER = '<name>';
 const PLACEHOLDER_SEGMENT = /^<[^>]+>$/;
@@ -38,6 +38,8 @@ const normalizeType = (type) => String(type || '').replace(/\s+/g, ' ').trim();
 const isObject = (value) =>
   value !== null && typeof value === 'object' && !Array.isArray(value);
 
+const buildSchemaRevision = (schema) => JSON.stringify(schema);
+
 const isPrimitiveValue = (type) =>
   type === 'string' || type === 'number' || type === 'integer' || type === 'boolean';
 
@@ -966,9 +968,62 @@ const fullPathMatches = (referencePath, actualPath) =>
 const countConcreteSegments = (segments) =>
   segments.reduce((count, segment) => count + (isPlaceholderSegment(segment) ? 0 : 1), 0);
 
-const referenceOptions = buildReferenceOptions(CONFIG_SCHEMA_DATA);
+const buildFeatureKeys = (referenceOptions) => [
+  ...new Set(
+    referenceOptions
+      .filter(
+        (option) =>
+          option.keyPath.length === 2 &&
+          option.keyPath[0] === 'features' &&
+          !isPlaceholderSegment(option.keyPath[1])
+      )
+      .map((option) => option.keyPath[1])
+  ),
+].sort((left, right) => left.localeCompare(right));
+
+const prepareReferenceState = (schema) => {
+  if (!isObject(schema)) {
+    return null;
+  }
+
+  const referenceOptions = buildReferenceOptions(schema);
+  if (!Array.isArray(referenceOptions) || referenceOptions.length === 0) {
+    return null;
+  }
+
+  return {
+    schema,
+    revision: buildSchemaRevision(schema),
+    referenceOptions,
+    optionsByKey: new Map(referenceOptions.map((option) => [option.key, option])),
+    featureKeys: buildFeatureKeys(referenceOptions),
+  };
+};
+
+let activeReferenceState = prepareReferenceState(BUNDLED_CONFIG_SCHEMA_DATA);
+if (!activeReferenceState) {
+  throw new Error('Bundled config schema is invalid.');
+}
 
-const optionsByKey = new Map(referenceOptions.map((option) => [option.key, option]));
+const getReferenceState = () => activeReferenceState;
+
+export const isReferenceSchemaValid = (schema) => Boolean(prepareReferenceState(schema));
+
+export const getReferenceSchemaRevision = () => getReferenceState().revision;
+
+export const setReferenceSchema = (schema) => {
+  const nextState = prepareReferenceState(schema);
+  if (!nextState) {
+    return false;
+  }
+
+  if (activeReferenceState?.revision === nextState.revision) {
+    return true;
+  }
+
+  activeReferenceState = nextState;
+  return true;
+};
 
 const mergeDefinition = (map, definition) => {
   const existing = map.get(definition.key);
@@ -988,6 +1043,7 @@ const mergeDefinition = (map, definition) => {
 };
 
 export const getReferenceOptionForPath = (pathSegments) => {
+  const { optionsByKey, referenceOptions } = getReferenceState();
   const normalizedPath = normalizeSegments(pathSegments);
   if (normalizedPath.length === 0) {
     return null;
@@ -1016,7 +1072,7 @@ export const getReferenceOptionForPath = (pathSegments) => {
   return candidates[0];
 };
 
-const getVariantObjectPaths = (normalizedPath) => {
+const getVariantObjectPaths = (normalizedPath, referenceOptions) => {
   const depth = normalizedPath.length;
   const paths = referenceOptions
     .filter((option) => pathPrefixMatches(option.keyPath, normalizedPath))
@@ -1028,6 +1084,7 @@ const getVariantObjectPaths = (normalizedPath) => {
 };
 
 export const getReferenceVariantForPath = (pathSegments = []) => {
+  const { referenceOptions } = getReferenceState();
   const normalizedPath = normalizeSegments(pathSegments);
   if (normalizedPath.length === 0) {
     return null;
@@ -1061,11 +1118,12 @@ export const getReferenceVariantForPath = (pathSegments = []) => {
               : {},
         }))
       : [],
-    objectSchemaPaths: getVariantObjectPaths(normalizedPath),
+    objectSchemaPaths: getVariantObjectPaths(normalizedPath, referenceOptions),
   };
 };
 
 export const getReferenceTableDefinitions = (pathSegments = []) => {
+  const { referenceOptions } = getReferenceState();
   const normalizedPath = normalizeSegments(pathSegments);
   const childDefinitions = new Map();
   const depth = normalizedPath.length;
@@ -1099,22 +1157,10 @@ export const getReferenceTableDefinitions = (pathSegments = []) => {
 
 export const getReferenceRootDefinitions = () => getReferenceTableDefinitions([]);
 
-const featureKeys = [
-  ...new Set(
-    referenceOptions
-      .filter(
-        (option) =>
-          option.keyPath.length === 2 &&
-          option.keyPath[0] === 'features' &&
-          !isPlaceholderSegment(option.keyPath[1])
-      )
-      .map((option) => option.keyPath[1])
-  ),
-].sort((left, right) => left.localeCompare(right));
-
-export const getReferenceFeatureKeys = () => featureKeys;
+export const getReferenceFeatureKeys = () => [...getReferenceState().featureKeys];
 
 export const getReferenceCustomIdPlaceholder = (pathSegments = []) => {
+  const { referenceOptions } = getReferenceState();
   const normalizedPath = normalizeSegments(pathSegments);
   const depth = normalizedPath.length;
   const placeholders = new Set();
@@ -1139,6 +1185,7 @@ export const getReferenceCustomIdPlaceholder = (pathSegments = []) => {
 };
 
 export const getReferenceDescendantOptions = (pathSegments = []) => {
+  const { referenceOptions } = getReferenceState();
   const normalizedPath = normalizeSegments(pathSegments);
 
   return referenceOptions