From 54b32a8f72ffa080aebb063713dc3c497480db9c Mon Sep 17 00:00:00 2001
From: Ashraf Masarwa <asmasarw@redhat.com>
Date: Tue, 2 Jun 2026 11:44:45 +0300
Subject: [PATCH 1/2] Enhance Validations and add Code-Highlighter

---
 .../form-validation-enhancements.md           |   5 +
 workspaces/dcm/plugins/dcm/package.json       |   2 +
 .../CatalogItemInstancesTabContent.tsx        |   2 +-
 .../components/InstanceFormFields.tsx         |  41 +-
 .../instanceFormTypes.ts                      |  89 +++-
 .../catalog-items/CatalogItemsTabContent.tsx  |   2 +-
 .../catalog-items/catalogItemFormTypes.ts     | 116 ++++-
 .../components/CatalogItemFormFields.tsx      | 423 ++++++++++++------
 .../policies/components/PolicyFormFields.tsx  |  25 +-
 .../pages/policies/policyFormTypes.test.ts    |  55 ++-
 .../dcm/src/pages/policies/policyFormTypes.ts |  30 +-
 workspaces/dcm/yarn.lock                      |  11 +
 12 files changed, 648 insertions(+), 153 deletions(-)
 create mode 100644 workspaces/dcm/.changeset/form-validation-enhancements.md

diff --git a/workspaces/dcm/.changeset/form-validation-enhancements.md b/workspaces/dcm/.changeset/form-validation-enhancements.md
new file mode 100644
index 0000000000..679dbb2dab
--- /dev/null
+++ b/workspaces/dcm/.changeset/form-validation-enhancements.md
@@ -0,0 +1,5 @@
+---
+'@red-hat-developer-hub/backstage-plugin-dcm': patch
+---
+
+Catalog Item: validate duplicate paths, block adding empty field rows, live-validate JSON in schema modal, surface invalid default_value / validation_schema inline. Policy: add structural Rego validation (package declaration + selected_provider reference) and monospace font to the code editor. Catalog Instance: enforce required/min/max constraints from validation_schema on user-value fields and enable submit-button gating.
diff --git a/workspaces/dcm/plugins/dcm/package.json b/workspaces/dcm/plugins/dcm/package.json
index 0343a9d24b..c578068932 100644
--- a/workspaces/dcm/plugins/dcm/package.json
+++ b/workspaces/dcm/plugins/dcm/package.json
@@ -43,6 +43,7 @@
     "@material-ui/lab": "4.0.0-alpha.61",
     "@red-hat-developer-hub/backstage-plugin-dcm-common": "workspace:^",
     "js-yaml": "^4.1.1",
+    "react-syntax-highlighter": "^15.4.5",
     "react-use": "^17.2.4",
     "yup": "^1.7.1"
   },
@@ -60,6 +61,7 @@
     "@testing-library/react": "^14.0.0",
     "@testing-library/user-event": "^14.0.0",
     "@types/js-yaml": "^4.0.9",
+    "@types/react-syntax-highlighter": "^15",
     "msw": "^1.0.0",
     "react": "^16.13.1 || ^17.0.0 || ^18.0.0",
     "react-dom": "^16.13.1 || ^17.0.0 || ^18.0.0",
diff --git a/workspaces/dcm/plugins/dcm/src/pages/catalog-item-instances/CatalogItemInstancesTabContent.tsx b/workspaces/dcm/plugins/dcm/src/pages/catalog-item-instances/CatalogItemInstancesTabContent.tsx
index bfd969a492..3cde73fe04 100644
--- a/workspaces/dcm/plugins/dcm/src/pages/catalog-item-instances/CatalogItemInstancesTabContent.tsx
+++ b/workspaces/dcm/plugins/dcm/src/pages/catalog-item-instances/CatalogItemInstancesTabContent.tsx
@@ -292,7 +292,7 @@ export function CatalogItemInstancesTabContent() {
             onCancel={crud.handleCloseCreate}
             submitLabel="Create"
             submitting={crud.createSubmitting}
-            disabled={false}
+            disabled={!isInstanceFormValid(crud.createForm)}
           />
         }
       >
diff --git a/workspaces/dcm/plugins/dcm/src/pages/catalog-item-instances/components/InstanceFormFields.tsx b/workspaces/dcm/plugins/dcm/src/pages/catalog-item-instances/components/InstanceFormFields.tsx
index 61349cd219..1c84b67b21 100644
--- a/workspaces/dcm/plugins/dcm/src/pages/catalog-item-instances/components/InstanceFormFields.tsx
+++ b/workspaces/dcm/plugins/dcm/src/pages/catalog-item-instances/components/InstanceFormFields.tsx
@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { useMemo } from 'react';
+import { useMemo, useState } from 'react';
 import {
   Box,
   Divider,
@@ -43,6 +43,7 @@ import {
   buildUserValueRows,
   InstanceForm,
   validateInstanceForm,
+  validateUserValues,
 } from '../instanceFormTypes';
 import type { UserValueRow } from '../instanceFormTypes';
 
@@ -59,6 +60,7 @@ export type InstanceFormFieldsProps = Readonly<{
 
 function fieldHelperText(row: UserValueRow): string {
   const parts: string[] = [`path: ${row.path}`];
+  if (row.required) parts.push('required');
   if (row.schemaType) parts.push(`type: ${row.schemaType}`);
   if (row.schemaMin !== undefined) parts.push(`min: ${row.schemaMin}`);
   if (row.schemaMax !== undefined) parts.push(`max: ${row.schemaMax}`);
@@ -74,6 +76,13 @@ export function InstanceFormFields({
 }: InstanceFormFieldsProps) {
   const classes = useStyles();
   const errors = useMemo(() => validateInstanceForm(form), [form]);
+  const userValueErrors = useMemo(
+    () => validateUserValues(form.user_values),
+    [form.user_values],
+  );
+  const [userValuesTouched, setUserValuesTouched] = useState<
+    Record<number, boolean>
+  >({});
   const selectedItem = catalogItems.find(ci => ci.uid === form.catalog_item_id);
 
   const handleCatalogItemChange = (id: string) => {
@@ -84,6 +93,7 @@ export function InstanceFormFields({
       user_values: buildUserValueRows(item),
     }));
     setTouched(prev => ({ ...prev, catalog_item_id: true }));
+    setUserValuesTouched({});
   };
 
   const setUserValue = (index: number, value: string) =>
@@ -93,6 +103,9 @@ export function InstanceFormFields({
       return { ...prev, user_values: updated };
     });
 
+  const touchUserValue = (index: number) =>
+    setUserValuesTouched(prev => ({ ...prev, [index]: true }));
+
   return (
     <Box display="flex" flexDirection="column" gridGap={16}>
       <TextField
@@ -189,7 +202,12 @@ export function InstanceFormFields({
             </Typography>
           </Typography>
           {form.user_values.map((row, i) => {
-            const helperText = fieldHelperText(row);
+            const isTouched = Boolean(userValuesTouched[i]);
+            const fieldError = isTouched ? userValueErrors[i] : undefined;
+            const label = row.required
+              ? `${row.displayName} *`
+              : row.displayName;
+            const helperText = fieldError ?? fieldHelperText(row);
 
             /* Enum field → Select */
             if (row.enumValues && row.enumValues.length > 0) {
@@ -199,12 +217,17 @@ export function InstanceFormFields({
                   variant="outlined"
                   size="small"
                   fullWidth
+                  error={Boolean(fieldError)}
                 >
-                  <InputLabel shrink>{row.displayName}</InputLabel>
+                  <InputLabel shrink>{label}</InputLabel>
                   <Select
                     value={row.value}
-                    onChange={e => setUserValue(i, e.target.value as string)}
-                    input={<OutlinedInput notched label={row.displayName} />}
+                    onChange={e => {
+                      setUserValue(i, e.target.value as string);
+                      touchUserValue(i);
+                    }}
+                    onBlur={() => touchUserValue(i)}
+                    input={<OutlinedInput notched label={label} />}
                   >
                     {row.enumValues.map(v => (
                       <MenuItem key={v} value={v}>
@@ -222,10 +245,12 @@ export function InstanceFormFields({
               return (
                 <TextField
                   key={row.path}
-                  label={row.displayName}
+                  label={label}
                   helperText={helperText}
+                  error={Boolean(fieldError)}
                   value={row.value}
                   onChange={e => setUserValue(i, e.target.value)}
+                  onBlur={() => touchUserValue(i)}
                   fullWidth
                   variant="outlined"
                   size="small"
@@ -243,10 +268,12 @@ export function InstanceFormFields({
             return (
               <TextField
                 key={row.path}
-                label={row.displayName}
+                label={label}
                 helperText={helperText}
+                error={Boolean(fieldError)}
                 value={row.value}
                 onChange={e => setUserValue(i, e.target.value)}
+                onBlur={() => touchUserValue(i)}
                 fullWidth
                 variant="outlined"
                 size="small"
diff --git a/workspaces/dcm/plugins/dcm/src/pages/catalog-item-instances/instanceFormTypes.ts b/workspaces/dcm/plugins/dcm/src/pages/catalog-item-instances/instanceFormTypes.ts
index b9d9335381..2834a3cf9d 100644
--- a/workspaces/dcm/plugins/dcm/src/pages/catalog-item-instances/instanceFormTypes.ts
+++ b/workspaces/dcm/plugins/dcm/src/pages/catalog-item-instances/instanceFormTypes.ts
@@ -40,6 +40,8 @@ export type UserValueRow = {
   schemaMin?: number;
   /** Inclusive upper bound (from validation_schema.maximum). */
   schemaMax?: number;
+  /** Whether the field must be filled (from validation_schema.required). */
+  required?: boolean;
 };
 
 export type InstanceForm = {
@@ -66,12 +68,14 @@ const instanceSchema = yup.object({
     ),
 });
 
-export const { validate: validateInstanceForm, isValid: isInstanceFormValid } =
-  createYupValidator<InstanceForm>(instanceSchema, f => ({
-    display_name: f.display_name,
-    catalog_item_id: f.catalog_item_id,
-    api_version: f.api_version,
-  }));
+export const {
+  validate: validateInstanceForm,
+  isValid: isInstanceScalarValid,
+} = createYupValidator<InstanceForm>(instanceSchema, f => ({
+  display_name: f.display_name,
+  catalog_item_id: f.catalog_item_id,
+  api_version: f.api_version,
+}));
 
 export function emptyInstanceForm(): InstanceForm {
   return {
@@ -94,10 +98,25 @@ function defaultToString(val: unknown): string {
   }
 }
 
+function pickNumericBound(
+  obj: Record<string, unknown>,
+  primaryKey: string,
+  fallbackKey: string,
+): number | undefined {
+  const primary = obj[primaryKey];
+  if (typeof primary === 'number') return primary;
+  const fallback = obj[fallbackKey];
+  if (typeof fallback === 'number') return fallback;
+  return undefined;
+}
+
 /** Extract typed schema metadata from a {@link FieldConfiguration}. */
 function extractSchemaInfo(
   field: FieldConfiguration,
-): Pick<UserValueRow, 'schemaType' | 'enumValues' | 'schemaMin' | 'schemaMax'> {
+): Pick<
+  UserValueRow,
+  'schemaType' | 'enumValues' | 'schemaMin' | 'schemaMax' | 'required'
+> {
   const schema = field.validation_schema ?? {};
   const schemaType = typeof schema.type === 'string' ? schema.type : undefined;
   const enumValues =
@@ -105,11 +124,57 @@ function extractSchemaInfo(
     schema.enum.every(v => typeof v === 'string' || typeof v === 'number')
       ? (schema.enum as (string | number)[]).map(String)
       : undefined;
-  const schemaMin =
-    typeof schema.minimum === 'number' ? schema.minimum : undefined;
-  const schemaMax =
-    typeof schema.maximum === 'number' ? schema.maximum : undefined;
-  return { schemaType, enumValues, schemaMin, schemaMax };
+  const schemaMin = pickNumericBound(schema, 'minimum', 'min');
+  const schemaMax = pickNumericBound(schema, 'maximum', 'max');
+  const required = schema.required === true;
+  return { schemaType, enumValues, schemaMin, schemaMax, required };
+}
+
+/**
+ * Validates user-value rows against their schema constraints.
+ * Returns a record keyed by row index; only rows with errors are included.
+ */
+export function validateUserValues(
+  rows: UserValueRow[],
+): Record<number, string> {
+  const errors: Record<number, string> = {};
+
+  rows.forEach((row, i) => {
+    const v = row.value.trim();
+
+    if (row.required && v === '') {
+      errors[i] = 'This field is required';
+      return;
+    }
+
+    if (
+      v !== '' &&
+      (row.schemaType === 'integer' || row.schemaType === 'number')
+    ) {
+      const n = Number(v);
+      if (Number.isNaN(n)) {
+        errors[i] = 'Must be a valid number';
+        return;
+      }
+      if (row.schemaMin !== undefined && n < row.schemaMin) {
+        errors[i] = `Must be at least ${row.schemaMin}`;
+        return;
+      }
+      if (row.schemaMax !== undefined && n > row.schemaMax) {
+        errors[i] = `Must be at most ${row.schemaMax}`;
+        return;
+      }
+    }
+  });
+
+  return errors;
+}
+
+export function isInstanceFormValid(f: InstanceForm): boolean {
+  return (
+    isInstanceScalarValid(f) &&
+    Object.keys(validateUserValues(f.user_values)).length === 0
+  );
 }
 
 /** Build UserValueRows from the selected catalog item's editable fields. */
diff --git a/workspaces/dcm/plugins/dcm/src/pages/catalog-items/CatalogItemsTabContent.tsx b/workspaces/dcm/plugins/dcm/src/pages/catalog-items/CatalogItemsTabContent.tsx
index 7d27b76903..4a94485b01 100644
--- a/workspaces/dcm/plugins/dcm/src/pages/catalog-items/CatalogItemsTabContent.tsx
+++ b/workspaces/dcm/plugins/dcm/src/pages/catalog-items/CatalogItemsTabContent.tsx
@@ -248,7 +248,7 @@ export function CatalogItemsTabContent() {
     <Drawer
       anchor="right"
       open={open}
-      onClose={submitting ? undefined : onClose}
+      onClose={submitting || Boolean(error) ? undefined : onClose}
     >
       <Box className={classes.drawer}>
         <Box className={classes.drawerHeader}>
diff --git a/workspaces/dcm/plugins/dcm/src/pages/catalog-items/catalogItemFormTypes.ts b/workspaces/dcm/plugins/dcm/src/pages/catalog-items/catalogItemFormTypes.ts
index da6ee7055b..1a6e2fbea7 100644
--- a/workspaces/dcm/plugins/dcm/src/pages/catalog-items/catalogItemFormTypes.ts
+++ b/workspaces/dcm/plugins/dcm/src/pages/catalog-items/catalogItemFormTypes.ts
@@ -71,8 +71,122 @@ export function hasValidFields(f: CatalogItemForm): boolean {
   return f.fields.some(row => row.path.trim() !== '');
 }
 
+/** Per-row validation errors for a {@link FieldRow}. */
+export type FieldRowErrors = {
+  path?: string;
+  default_value?: string;
+  validation_schema?: string;
+};
+
+/** Returns true if a string looks like intended JSON (and should therefore be valid JSON). */
+function looksLikeJson(s: string): boolean {
+  return s.startsWith('{') || s.startsWith('[') || s.startsWith('"');
+}
+
+/**
+ * Validates all field rows for:
+ * - Duplicate paths (only non-empty paths are checked)
+ * - `default_value` that looks like JSON but fails to parse
+ * - `validation_schema` that is non-empty but not a valid JSON object
+ *
+ * Returns a record keyed by row index; only rows with errors are included.
+ */
+
+function pickNumericBound(
+  obj: Record<string, unknown>,
+  primaryKey: string,
+  fallbackKey: string,
+): number | undefined {
+  const primary = obj[primaryKey];
+  if (typeof primary === 'number') return primary;
+  const fallback = obj[fallbackKey];
+  if (typeof fallback === 'number') return fallback;
+  return undefined;
+}
+
+export function validateFieldRows(
+  fields: FieldRow[],
+): Record<number, FieldRowErrors> {
+  const result: Record<number, FieldRowErrors> = {};
+  const seenPaths = new Map<string, number>();
+
+  fields.forEach((row, i) => {
+    const rowErrors: FieldRowErrors = {};
+    const trimmedPath = row.path.trim();
+
+    if (trimmedPath !== '') {
+      if (seenPaths.has(trimmedPath)) {
+        rowErrors.path = 'Duplicate path — paths must be unique';
+      } else {
+        seenPaths.set(trimmedPath, i);
+      }
+    }
+
+    const defaultTrimmed = row.default_value.trim();
+    if (defaultTrimmed && looksLikeJson(defaultTrimmed)) {
+      try {
+        JSON.parse(defaultTrimmed);
+      } catch {
+        rowErrors.default_value =
+          'Invalid JSON — fix the syntax or use a plain string value';
+      }
+    }
+
+    const schemaTrimmed = row.validation_schema.trim();
+    let schemaMin: number | undefined;
+    let schemaMax: number | undefined;
+    if (schemaTrimmed) {
+      try {
+        const parsed = JSON.parse(schemaTrimmed);
+        if (
+          typeof parsed !== 'object' ||
+          parsed === null ||
+          Array.isArray(parsed)
+        ) {
+          rowErrors.validation_schema =
+            'Must be a JSON object — e.g. {"type":"integer"}';
+        } else {
+          schemaMin = pickNumericBound(parsed, 'minimum', 'min');
+          schemaMax = pickNumericBound(parsed, 'maximum', 'max');
+          if (
+            schemaMin !== undefined &&
+            schemaMax !== undefined &&
+            schemaMin > schemaMax
+          ) {
+            rowErrors.validation_schema = `minimum (${schemaMin}) must not exceed maximum (${schemaMax})`;
+          }
+        }
+      } catch {
+        rowErrors.validation_schema = 'Invalid JSON syntax';
+      }
+    }
+
+    const defaultNum = Number(defaultTrimmed);
+    if (
+      !rowErrors.default_value &&
+      !rowErrors.validation_schema &&
+      defaultTrimmed &&
+      Number.isFinite(defaultNum)
+    ) {
+      if (schemaMin !== undefined && defaultNum < schemaMin) {
+        rowErrors.default_value = `Default value (${defaultNum}) is below the schema minimum (${schemaMin})`;
+      } else if (schemaMax !== undefined && defaultNum > schemaMax) {
+        rowErrors.default_value = `Default value (${defaultNum}) exceeds the schema maximum (${schemaMax})`;
+      }
+    }
+
+    if (Object.keys(rowErrors).length > 0) {
+      result[i] = rowErrors;
+    }
+  });
+
+  return result;
+}
+
 export function isCatalogItemFormValid(f: CatalogItemForm): boolean {
-  return Object.keys(validateScalar(f)).length === 0 && hasValidFields(f);
+  if (Object.keys(validateScalar(f)).length !== 0) return false;
+  if (!hasValidFields(f)) return false;
+  return Object.keys(validateFieldRows(f.fields)).length === 0;
 }
 
 export function emptyFieldRow(): FieldRow {
diff --git a/workspaces/dcm/plugins/dcm/src/pages/catalog-items/components/CatalogItemFormFields.tsx b/workspaces/dcm/plugins/dcm/src/pages/catalog-items/components/CatalogItemFormFields.tsx
index e610059ee6..14ab1ad9e7 100644
--- a/workspaces/dcm/plugins/dcm/src/pages/catalog-items/components/CatalogItemFormFields.tsx
+++ b/workspaces/dcm/plugins/dcm/src/pages/catalog-items/components/CatalogItemFormFields.tsx
@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import { useRef, useMemo, useState } from 'react';
+import { useRef, useMemo, useState, useCallback } from 'react';
 import {
   Box,
   Button,
@@ -43,6 +43,11 @@ import DeleteIcon from '@material-ui/icons/Delete';
 import PublishIcon from '@material-ui/icons/Publish';
 import { makeStyles } from '@material-ui/core/styles';
 import { load as loadYaml } from 'js-yaml';
+import { Light as SyntaxHighlighter } from 'react-syntax-highlighter';
+import json from 'react-syntax-highlighter/dist/esm/languages/hljs/json';
+import docco from 'react-syntax-highlighter/dist/esm/styles/hljs/docco';
+
+SyntaxHighlighter.registerLanguage('json', json);
 
 const useStyles = makeStyles(theme => ({
   fieldRow: {
@@ -70,45 +75,152 @@ const useSchemaEditorStyles = makeStyles(theme => ({
   dialogContent: {
     paddingTop: theme.spacing(1),
   },
-  monoInput: {
-    fontFamily: 'monospace',
-    fontSize: 12,
+  editorWrapper: {
+    position: 'relative' as const,
+    border: `1px solid ${theme.palette.divider}`,
+    borderRadius: theme.shape.borderRadius,
+    overflow: 'hidden',
+    '&:focus-within': {
+      borderColor: theme.palette.primary.main,
+      boxShadow: `0 0 0 1px ${theme.palette.primary.main}`,
+    },
+  },
+  editorWrapperError: {
+    borderColor: theme.palette.error.main,
+    '&:focus-within': {
+      borderColor: theme.palette.error.main,
+      boxShadow: `0 0 0 1px ${theme.palette.error.main}`,
+    },
+  },
+  editorTextarea: {
+    position: 'absolute' as const,
+    top: 0,
+    left: 0,
+    width: '100%',
+    height: '100%',
+    margin: 0,
+    padding: '12px',
+    border: 'none',
+    outline: 'none',
+    resize: 'none' as const,
+    background: 'transparent',
+    color: 'transparent',
+    caretColor: theme.palette.text.primary,
+    fontFamily:
+      '"SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace',
+    fontSize: 13,
+    lineHeight: '1.45',
+    whiteSpace: 'pre' as const,
+    overflowWrap: 'normal' as const,
+    overflow: 'auto',
+    zIndex: 1,
+    WebkitTextFillColor: 'transparent',
+  },
+  editorHighlight: {
+    margin: 0,
+    padding: '12px !important',
+    minHeight: 280,
+    fontFamily:
+      '"SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace !important',
+    fontSize: '13px !important',
+    lineHeight: '1.45 !important',
+    whiteSpace: 'pre' as const,
+    overflowWrap: 'normal' as const,
+    overflow: 'auto',
+    background: `${theme.palette.background.paper} !important`,
+  },
+  editorHelperText: {
+    marginTop: theme.spacing(0.5),
+    display: 'block',
   },
 }));
 
 type SchemaButtonProps = Readonly<{
   value: string;
   onChange: (v: string) => void;
+  /** Error on the stored value (e.g. from import or duplicate detection). */
+  fieldError?: string;
 }>;
 
-function SchemaButton({ value, onChange }: SchemaButtonProps) {
+function validateSchemaJson(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) return '';
+  try {
+    const parsed = JSON.parse(trimmed);
+    if (
+      typeof parsed !== 'object' ||
+      parsed === null ||
+      Array.isArray(parsed)
+    ) {
+      return 'Must be a JSON object, not an array or primitive';
+    }
+    return '';
+  } catch {
+    return 'Invalid JSON syntax';
+  }
+}
+
+function prettyPrintIfValid(raw: string): string {
+  try {
+    return JSON.stringify(JSON.parse(raw), null, 2);
+  } catch {
+    return raw;
+  }
+}
+
+function SchemaButton({ value, onChange, fieldError }: SchemaButtonProps) {
   const classes = useSchemaEditorStyles();
   const [open, setOpen] = useState(false);
   const [draft, setDraft] = useState('');
-  const [parseError, setParseError] = useState('');
+  const textareaRef = useRef<HTMLTextAreaElement>(null);
+  const highlightRef = useRef<HTMLDivElement>(null);
+
+  const jsonError = useMemo(() => validateSchemaJson(draft), [draft]);
+  const applyDisabled = draft.trim() !== '' && Boolean(jsonError);
+  const hasError = Boolean(draft.trim() && jsonError);
 
   const handleOpen = () => {
-    setDraft(value);
-    setParseError('');
+    setDraft(value ? prettyPrintIfValid(value) : '');
     setOpen(true);
   };
 
-  const handleApply = () => {
-    const trimmed = draft.trim();
-    if (trimmed) {
-      try {
-        JSON.parse(trimmed);
-      } catch {
-        setParseError('Invalid JSON — fix the syntax before applying.');
-        return;
-      }
-    }
-    onChange(trimmed);
+  const handleApply = useCallback(() => {
+    if (applyDisabled) return;
+    onChange(draft.trim());
     setOpen(false);
-  };
+  }, [applyDisabled, draft, onChange]);
 
   const handleClose = () => setOpen(false);
 
+  const syncScroll = () => {
+    if (textareaRef.current && highlightRef.current) {
+      highlightRef.current.scrollTop = textareaRef.current.scrollTop;
+      highlightRef.current.scrollLeft = textareaRef.current.scrollLeft;
+    }
+  };
+
+  const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    if (e.key !== 'Enter') return;
+    const afterEnter = `${draft}\n`;
+    const formatted = prettyPrintIfValid(afterEnter);
+    if (formatted !== afterEnter) {
+      e.preventDefault();
+      setDraft(formatted);
+    }
+  };
+
+  const handlePaste = (e: React.ClipboardEvent<HTMLTextAreaElement>) => {
+    const pasted = e.clipboardData.getData('text');
+    const { selectionStart: start, selectionEnd: end } = e.currentTarget;
+    const afterPaste =
+      draft.slice(0, start ?? 0) + pasted + draft.slice(end ?? 0);
+    const formatted = prettyPrintIfValid(afterPaste);
+    if (formatted !== afterPaste) {
+      e.preventDefault();
+      setDraft(formatted);
+    }
+  };
+
   return (
     <>
       <Box display="flex" flexDirection="column">
@@ -125,37 +237,66 @@ function SchemaButton({ value, onChange }: SchemaButtonProps) {
             variant="outlined"
             startIcon={<CodeIcon fontSize="small" />}
             onClick={handleOpen}
-            color="primary"
+            color={fieldError ? 'secondary' : 'primary'}
           >
-            View JSON
+            {value ? 'Edit JSON' : 'Add JSON'}
           </Button>
         </Box>
+        {fieldError && (
+          <Typography variant="caption" color="error">
+            {fieldError}
+          </Typography>
+        )}
       </Box>
 
       <Dialog open={open} onClose={handleClose} maxWidth="sm" fullWidth>
         <DialogTitle>Validation schema</DialogTitle>
         <DialogContent className={classes.dialogContent}>
-          <TextField
-            value={draft}
-            onChange={e => {
-              setDraft(e.target.value);
-              setParseError('');
-            }}
-            error={Boolean(parseError)}
-            helperText={
-              parseError ||
-              'JSON Schema object — e.g. {"type":"integer","minimum":0}'
-            }
-            fullWidth
-            multiline
-            minRows={14}
-            variant="outlined"
-            inputProps={{ className: classes.monoInput }}
-          />
+          <Box
+            className={`${classes.editorWrapper} ${
+              hasError ? classes.editorWrapperError : ''
+            }`}
+          >
+            <div ref={highlightRef} style={{ overflow: 'hidden' }}>
+              <SyntaxHighlighter
+                language="json"
+                style={docco}
+                className={classes.editorHighlight}
+              >
+                {draft || ' '}
+              </SyntaxHighlighter>
+            </div>
+            <textarea
+              ref={textareaRef}
+              className={classes.editorTextarea}
+              value={draft}
+              onChange={e => setDraft(e.target.value)}
+              onScroll={syncScroll}
+              onKeyDown={handleKeyDown}
+              onPaste={handlePaste}
+              spellCheck={false}
+              autoCapitalize="off"
+              autoCorrect="off"
+              placeholder='{"type":"integer","minimum":0}'
+            />
+          </Box>
+          <Typography
+            variant="caption"
+            color={hasError ? 'error' : 'textSecondary'}
+            className={classes.editorHelperText}
+          >
+            {(draft.trim() && jsonError) ||
+              'JSON Schema object — e.g. {"type":"integer","minimum":0}'}
+          </Typography>
         </DialogContent>
         <DialogActions>
           <Button onClick={handleClose}>Cancel</Button>
-          <Button onClick={handleApply} color="primary" variant="contained">
+          <Button
+            onClick={handleApply}
+            color="primary"
+            variant="contained"
+            disabled={applyDisabled}
+          >
             Apply
           </Button>
         </DialogActions>
@@ -169,8 +310,9 @@ import {
   emptyFieldRow,
   hasValidFields,
   validateCatalogItemForm,
+  validateFieldRows,
 } from '../catalogItemFormTypes';
-import type { FieldRow } from '../catalogItemFormTypes';
+import type { FieldRow, FieldRowErrors } from '../catalogItemFormTypes';
 
 type ScalarFields = Omit<CatalogItemForm, 'fields'>;
 type TouchedMap = Partial<Record<keyof ScalarFields, boolean>>;
@@ -204,6 +346,10 @@ export function CatalogItemFormFields({
 }: CatalogItemFormFieldsProps) {
   const classes = useStyles();
   const errors = useMemo(() => validateCatalogItemForm(form), [form]);
+  const fieldRowErrors = useMemo(
+    () => validateFieldRows(form.fields),
+    [form.fields],
+  );
   const fileInputRef = useRef<HTMLInputElement>(null);
   const [importError, setImportError] = useState('');
 
@@ -225,8 +371,13 @@ export function CatalogItemFormFields({
       return { ...prev, fields: updated };
     });
 
-  const addField = () =>
+  const canAddField =
+    form.fields.length === 0 || form.fields.at(-1)!.path.trim() !== '';
+
+  const addField = () => {
+    if (!canAddField) return;
     setForm(prev => ({ ...prev, fields: [...prev.fields, emptyFieldRow()] }));
+  };
 
   const removeField = (index: number) =>
     setForm(prev => {
@@ -364,14 +515,25 @@ export function CatalogItemFormFields({
             (at least one required)
           </Typography>
         </Typography>
-        <Button
-          size="small"
-          startIcon={<AddIcon />}
-          onClick={addField}
-          color="primary"
+        <Tooltip
+          title={
+            canAddField
+              ? ''
+              : 'Fill in the path of the last field before adding a new one'
+          }
         >
-          Add field
-        </Button>
+          <Box component="span" display="inline-block">
+            <Button
+              size="small"
+              startIcon={<AddIcon />}
+              onClick={addField}
+              color="primary"
+              disabled={!canAddField}
+            >
+              Add field
+            </Button>
+          </Box>
+        </Tooltip>
       </Box>
 
       {showFieldsError && (
@@ -380,88 +542,97 @@ export function CatalogItemFormFields({
         </Typography>
       )}
 
-      {form.fields.map((row, i) => (
-        <Box
-          key={row.id}
-          display="flex"
-          flexDirection="column"
-          gridGap={8}
-          className={classes.fieldRow}
-        >
-          {/* Primary row: path, display name, editable toggle, delete */}
-          <Box display="flex" alignItems="flex-start" gridGap={8}>
-            <Box flex={2}>
-              <TextField
-                label="Path *"
-                helperText="e.g. config.replicas"
-                value={row.path}
-                onChange={e => setField(i, 'path', e.target.value)}
-                fullWidth
-                variant="outlined"
-                size="small"
-              />
-            </Box>
-            <Box flex={2}>
-              <TextField
-                label="Display name"
-                value={row.display_name}
-                onChange={e => setField(i, 'display_name', e.target.value)}
-                fullWidth
-                variant="outlined"
+      {form.fields.map((row, i) => {
+        const rowErrors: FieldRowErrors = fieldRowErrors[i] ?? {};
+        return (
+          <Box
+            key={row.id}
+            display="flex"
+            flexDirection="column"
+            gridGap={8}
+            className={classes.fieldRow}
+          >
+            {/* Primary row: path, display name, editable toggle, delete */}
+            <Box display="flex" alignItems="flex-start" gridGap={8}>
+              <Box flex={2}>
+                <TextField
+                  label="Path *"
+                  helperText={rowErrors.path ?? 'e.g. config.replicas'}
+                  error={Boolean(rowErrors.path)}
+                  value={row.path}
+                  onChange={e => setField(i, 'path', e.target.value)}
+                  fullWidth
+                  variant="outlined"
+                  size="small"
+                />
+              </Box>
+              <Box flex={2}>
+                <TextField
+                  label="Display name"
+                  value={row.display_name}
+                  onChange={e => setField(i, 'display_name', e.target.value)}
+                  fullWidth
+                  variant="outlined"
+                  size="small"
+                />
+              </Box>
+              <Box
+                display="flex"
+                alignItems="center"
+                className={classes.fieldRowSwitch}
+              >
+                <FormControlLabel
+                  control={
+                    <Switch
+                      size="small"
+                      checked={row.editable}
+                      onChange={e => setField(i, 'editable', e.target.checked)}
+                      color="primary"
+                    />
+                  }
+                  label={<Typography variant="caption">Editable</Typography>}
+                />
+              </Box>
+              <IconButton
                 size="small"
-              />
-            </Box>
-            <Box
-              display="flex"
-              alignItems="center"
-              className={classes.fieldRowSwitch}
-            >
-              <FormControlLabel
-                control={
-                  <Switch
-                    size="small"
-                    checked={row.editable}
-                    onChange={e => setField(i, 'editable', e.target.checked)}
-                    color="primary"
-                  />
-                }
-                label={<Typography variant="caption">Editable</Typography>}
-              />
+                aria-label="Remove field"
+                onClick={() => removeField(i)}
+                className={classes.fieldRowDelete}
+              >
+                <DeleteIcon fontSize="small" />
+              </IconButton>
             </Box>
-            <IconButton
-              size="small"
-              aria-label="Remove field"
-              onClick={() => removeField(i)}
-              className={classes.fieldRowDelete}
-            >
-              <DeleteIcon fontSize="small" />
-            </IconButton>
-          </Box>
 
-          {/* Secondary row: default value and validation schema */}
-          <Box display="flex" alignItems="flex-start" gridGap={8}>
-            <Box flex={1}>
-              <TextField
-                label="Default value"
-                helperText='Any JSON value — e.g. 42, "hello", true, [1,2]'
-                value={row.default_value}
-                onChange={e => setField(i, 'default_value', e.target.value)}
-                fullWidth
-                variant="outlined"
-                size="small"
-                multiline
-                minRows={2}
-              />
-            </Box>
-            <Box flex={1} paddingTop={0.5}>
-              <SchemaButton
-                value={row.validation_schema}
-                onChange={v => setField(i, 'validation_schema', v)}
-              />
+            {/* Secondary row: default value and validation schema */}
+            <Box display="flex" alignItems="flex-start" gridGap={8}>
+              <Box flex={1}>
+                <TextField
+                  label="Default value"
+                  helperText={
+                    rowErrors.default_value ??
+                    'Any JSON value — e.g. 42, "hello", true, [1,2]'
+                  }
+                  error={Boolean(rowErrors.default_value)}
+                  value={row.default_value}
+                  onChange={e => setField(i, 'default_value', e.target.value)}
+                  fullWidth
+                  variant="outlined"
+                  size="small"
+                  multiline
+                  minRows={2}
+                />
+              </Box>
+              <Box flex={1} paddingTop={0.5}>
+                <SchemaButton
+                  value={row.validation_schema}
+                  onChange={v => setField(i, 'validation_schema', v)}
+                  fieldError={rowErrors.validation_schema}
+                />
+              </Box>
             </Box>
           </Box>
-        </Box>
-      ))}
+        );
+      })}
     </Box>
   );
 }
diff --git a/workspaces/dcm/plugins/dcm/src/pages/policies/components/PolicyFormFields.tsx b/workspaces/dcm/plugins/dcm/src/pages/policies/components/PolicyFormFields.tsx
index ee6394aded..305b802660 100644
--- a/workspaces/dcm/plugins/dcm/src/pages/policies/components/PolicyFormFields.tsx
+++ b/workspaces/dcm/plugins/dcm/src/pages/policies/components/PolicyFormFields.tsx
@@ -25,8 +25,20 @@ import {
   Switch,
   TextField,
 } from '@material-ui/core';
+import { makeStyles } from '@material-ui/core/styles';
 import type { PolicyType } from '@red-hat-developer-hub/backstage-plugin-dcm-common';
-import { PolicyForm, validatePolicyForm } from '../policyFormTypes';
+import {
+  PolicyForm,
+  validatePolicyForm,
+  validateRegoCode,
+} from '../policyFormTypes';
+
+const useStyles = makeStyles(() => ({
+  regoInput: {
+    fontFamily: 'monospace',
+    fontSize: 13,
+  },
+}));
 
 type TouchedMap = Partial<Record<keyof PolicyForm, boolean>>;
 
@@ -43,6 +55,7 @@ export function PolicyFormFields({
   touched,
   setTouched,
 }: PolicyFormFieldsProps) {
+  const classes = useStyles();
   const errors = validatePolicyForm(form);
 
   const touch = (field: keyof PolicyForm) =>
@@ -51,6 +64,11 @@ export function PolicyFormFields({
   const err = (field: keyof PolicyForm) =>
     touched[field] ? errors[field] : undefined;
 
+  // Rego structural errors are computed directly — not through Yup — to
+  // avoid a Yup v1 quirk where custom .test() results are dropped from
+  // err.inner when the total number of schema errors is exactly one.
+  const regoErr = validateRegoCode(form.rego_code);
+
   return (
     <Box display="flex" flexDirection="column" gridGap={16}>
       <TextField
@@ -129,10 +147,10 @@ export function PolicyFormFields({
       <TextField
         label="Rego code *"
         helperText={
-          err('rego_code') ??
+          regoErr ??
           'OPA Rego evaluated by the Placement Manager. Must assign selected_provider to the name of a registered provider.'
         }
-        error={Boolean(err('rego_code'))}
+        error={Boolean(regoErr)}
         value={form.rego_code}
         onChange={e =>
           setForm(prev => ({ ...prev, rego_code: e.target.value }))
@@ -145,6 +163,7 @@ export function PolicyFormFields({
         placeholder={
           'package dcm.placement\n\n# Replace "my-provider-name" with the name of a registered provider.\n# The Placement Manager requires selected_provider to be set.\nselected_provider := "my-provider-name"'
         }
+        inputProps={{ className: classes.regoInput }}
       />
 
       <FormControlLabel
diff --git a/workspaces/dcm/plugins/dcm/src/pages/policies/policyFormTypes.test.ts b/workspaces/dcm/plugins/dcm/src/pages/policies/policyFormTypes.test.ts
index 0ab933ccb4..17d133b9e3 100644
--- a/workspaces/dcm/plugins/dcm/src/pages/policies/policyFormTypes.test.ts
+++ b/workspaces/dcm/plugins/dcm/src/pages/policies/policyFormTypes.test.ts
@@ -20,6 +20,7 @@ import {
   isPolicyFormValid,
   policyToForm,
   validatePolicyForm,
+  validateRegoCode,
 } from './policyFormTypes';
 
 describe('validatePolicyForm', () => {
@@ -71,11 +72,63 @@ describe('isPolicyFormValid', () => {
         description: '',
         policy_type: 'GLOBAL',
         priority: '500',
-        rego_code: 'package dcm',
+        rego_code: 'package dcm.placement\nselected_provider := "p1"',
         enabled: true,
       }),
     ).toBe(true);
   });
+
+  it('returns false when rego_code has no package declaration', () => {
+    expect(
+      isPolicyFormValid({
+        display_name: 'My Policy',
+        description: '',
+        policy_type: 'GLOBAL',
+        priority: '500',
+        rego_code: 'selected_provider := "p1"',
+        enabled: true,
+      }),
+    ).toBe(false);
+  });
+
+  it('returns false when rego_code has no selected_provider', () => {
+    expect(
+      isPolicyFormValid({
+        display_name: 'My Policy',
+        description: '',
+        policy_type: 'GLOBAL',
+        priority: '500',
+        rego_code: 'package dcm.placement',
+        enabled: true,
+      }),
+    ).toBe(false);
+  });
+});
+
+describe('validateRegoCode', () => {
+  it('returns undefined for empty string', () => {
+    expect(validateRegoCode('')).toBeUndefined();
+  });
+
+  it('returns undefined for valid Rego', () => {
+    expect(
+      validateRegoCode('package dcm.placement\nselected_provider := "p1"'),
+    ).toBeUndefined();
+  });
+
+  it('flags missing package declaration', () => {
+    expect(validateRegoCode('selected_provider := "p1"')).toMatch(/package/);
+  });
+
+  it('flags missing selected_provider', () => {
+    expect(validateRegoCode('package dcm.placement')).toMatch(
+      /selected_provider/,
+    );
+  });
+
+  it('flags Jinja-style non-Rego input', () => {
+    expect(validateRegoCode('{{ THIS IS A VALID REGO }}')).toMatch(/package/);
+  });
 });
 
 describe('policyToForm / formToPolicy round-trip', () => {
diff --git a/workspaces/dcm/plugins/dcm/src/pages/policies/policyFormTypes.ts b/workspaces/dcm/plugins/dcm/src/pages/policies/policyFormTypes.ts
index 1682c2fd82..b501b54aa7 100644
--- a/workspaces/dcm/plugins/dcm/src/pages/policies/policyFormTypes.ts
+++ b/workspaces/dcm/plugins/dcm/src/pages/policies/policyFormTypes.ts
@@ -52,12 +52,40 @@ const policySchema = yup.object({
     .min(1, 'Rego code cannot be empty'),
 });
 
-export const { validate: validatePolicyForm, isValid: isPolicyFormValid } =
+const { validate: validatePolicyFormScalar, isValid: isPolicyScalarValid } =
   createYupValidator<PolicyForm>(policySchema, f => ({
     ...f,
     priority: f.priority === '' ? undefined : Number(f.priority),
   }));
 
+export { validatePolicyFormScalar as validatePolicyForm };
+
+/**
+ * Validates structural Rego requirements independently of Yup.
+ * Returns an error string when the code is non-empty but violates a rule,
+ * or undefined when the code is valid (or empty — empty is caught by Yup).
+ */
+const REGO_PACKAGE_RE = /^package\s+\S+/;
+
+export function validateRegoCode(value: string): string | undefined {
+  const trimmed = value.trim();
+  if (!trimmed) return undefined;
+  const hasPackage = trimmed
+    .split('\n')
+    .some(line => REGO_PACKAGE_RE.test(line.trimStart()));
+  if (!hasPackage) {
+    return 'Must contain a package declaration — e.g. "package dcm.placement"';
+  }
+  if (!/\bselected_provider\b/.test(trimmed)) {
+    return 'Must reference selected_provider — e.g. selected_provider := "my-provider"';
+  }
+  return undefined;
+}
+
+export function isPolicyFormValid(f: PolicyForm): boolean {
+  return isPolicyScalarValid(f) && validateRegoCode(f.rego_code) === undefined;
+}
+
 export function emptyPolicyForm(): PolicyForm {
   return {
     display_name: '',
diff --git a/workspaces/dcm/yarn.lock b/workspaces/dcm/yarn.lock
index 58528b4ce2..12973e5c1a 100644
--- a/workspaces/dcm/yarn.lock
+++ b/workspaces/dcm/yarn.lock
@@ -11615,11 +11615,13 @@ __metadata:
     "@testing-library/react": "npm:^14.0.0"
     "@testing-library/user-event": "npm:^14.0.0"
     "@types/js-yaml": "npm:^4.0.9"
+    "@types/react-syntax-highlighter": "npm:^15"
     js-yaml: "npm:^4.1.1"
     msw: "npm:^1.0.0"
     react: "npm:^16.13.1 || ^17.0.0 || ^18.0.0"
     react-dom: "npm:^16.13.1 || ^17.0.0 || ^18.0.0"
     react-router-dom: "npm:^6.0.0"
+    react-syntax-highlighter: "npm:^15.4.5"
     react-use: "npm:^17.2.4"
     yup: "npm:^1.7.1"
   peerDependencies:
@@ -14905,6 +14907,15 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/react-syntax-highlighter@npm:^15":
+  version: 15.5.13
+  resolution: "@types/react-syntax-highlighter@npm:15.5.13"
+  dependencies:
+    "@types/react": "npm:*"
+  checksum: 10/0cc47785326aea5effac9ee68c263abc6448c63b6a084eec3084fd13c08da93addfdc3102ff919cbe420aa71fbded9bf041cc2c51fe625c6ee0751e8a131bd38
+  languageName: node
+  linkType: hard
+
 "@types/react-transition-group@npm:^4.2.0, @types/react-transition-group@npm:^4.4.10":
   version: 4.4.12
   resolution: "@types/react-transition-group@npm:4.4.12"

From f2729e3c44bb9628048082337e6580be87fb7433 Mon Sep 17 00:00:00 2001
From: Ashraf Masarwa <asmasarw@redhat.com>
Date: Thu, 4 Jun 2026 13:20:01 +0300
Subject: [PATCH 2/2] Add Shared Schema

---
 .../instanceFormTypes.ts                      | 13 +-------
 .../catalog-items/catalogItemFormTypes.ts     | 13 +-------
 .../dcm/plugins/dcm/src/utils/schemaUtils.ts  | 32 +++++++++++++++++++
 3 files changed, 34 insertions(+), 24 deletions(-)
 create mode 100644 workspaces/dcm/plugins/dcm/src/utils/schemaUtils.ts

diff --git a/workspaces/dcm/plugins/dcm/src/pages/catalog-item-instances/instanceFormTypes.ts b/workspaces/dcm/plugins/dcm/src/pages/catalog-item-instances/instanceFormTypes.ts
index 2834a3cf9d..96f2f22e18 100644
--- a/workspaces/dcm/plugins/dcm/src/pages/catalog-item-instances/instanceFormTypes.ts
+++ b/workspaces/dcm/plugins/dcm/src/pages/catalog-item-instances/instanceFormTypes.ts
@@ -22,6 +22,7 @@ import type {
   UserValue,
 } from '@red-hat-developer-hub/backstage-plugin-dcm-common';
 import { createYupValidator } from '../../utils/createYupValidator';
+import { pickNumericBound } from '../../utils/schemaUtils';
 
 /** One user-supplied field value, with string value for form binding. */
 export type UserValueRow = {
@@ -98,18 +99,6 @@ function defaultToString(val: unknown): string {
   }
 }
 
-function pickNumericBound(
-  obj: Record<string, unknown>,
-  primaryKey: string,
-  fallbackKey: string,
-): number | undefined {
-  const primary = obj[primaryKey];
-  if (typeof primary === 'number') return primary;
-  const fallback = obj[fallbackKey];
-  if (typeof fallback === 'number') return fallback;
-  return undefined;
-}
-
 /** Extract typed schema metadata from a {@link FieldConfiguration}. */
 function extractSchemaInfo(
   field: FieldConfiguration,
diff --git a/workspaces/dcm/plugins/dcm/src/pages/catalog-items/catalogItemFormTypes.ts b/workspaces/dcm/plugins/dcm/src/pages/catalog-items/catalogItemFormTypes.ts
index 1a6e2fbea7..2442a382c8 100644
--- a/workspaces/dcm/plugins/dcm/src/pages/catalog-items/catalogItemFormTypes.ts
+++ b/workspaces/dcm/plugins/dcm/src/pages/catalog-items/catalogItemFormTypes.ts
@@ -20,6 +20,7 @@ import type {
   FieldConfiguration,
 } from '@red-hat-developer-hub/backstage-plugin-dcm-common';
 import { createYupValidator } from '../../utils/createYupValidator';
+import { pickNumericBound } from '../../utils/schemaUtils';
 
 export type FieldRow = {
   /** Stable client-side identifier used as React list key. Never sent to the API. */
@@ -92,18 +93,6 @@ function looksLikeJson(s: string): boolean {
  * Returns a record keyed by row index; only rows with errors are included.
  */
 
-function pickNumericBound(
-  obj: Record<string, unknown>,
-  primaryKey: string,
-  fallbackKey: string,
-): number | undefined {
-  const primary = obj[primaryKey];
-  if (typeof primary === 'number') return primary;
-  const fallback = obj[fallbackKey];
-  if (typeof fallback === 'number') return fallback;
-  return undefined;
-}
-
 export function validateFieldRows(
   fields: FieldRow[],
 ): Record<number, FieldRowErrors> {
diff --git a/workspaces/dcm/plugins/dcm/src/utils/schemaUtils.ts b/workspaces/dcm/plugins/dcm/src/utils/schemaUtils.ts
new file mode 100644
index 0000000000..1e404ab61c
--- /dev/null
+++ b/workspaces/dcm/plugins/dcm/src/utils/schemaUtils.ts
@@ -0,0 +1,32 @@
+/*
+ * Copyright Red Hat, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/**
+ * Reads a numeric value from `obj[primaryKey]`; falls back to
+ * `obj[fallbackKey]` if the primary is absent or not a number.
+ * Returns `undefined` if neither key holds a number.
+ */
+export function pickNumericBound(
+  obj: Record<string, unknown>,
+  primaryKey: string,
+  fallbackKey: string,
+): number | undefined {
+  const primary = obj[primaryKey];
+  if (typeof primary === 'number') return primary;
+  const fallback = obj[fallbackKey];
+  if (typeof fallback === 'number') return fallback;
+  return undefined;
+}