@qoretechnologies/reqraft 0.10.25 → 0.10.26

package/src/components/form/engine/FormEngine.tsx

@@ -3,9 +3,9 @@ import {
   ReqoreCollection,
   ReqoreControlGroup,
   ReqoreErrorBoundary,
+  ReqoreIcon,
   ReqoreMessage,
   ReqoreP,
-  ReqorePanel,
   ReqoreSkeleton,
   ReqoreTag,
   ReqoreTagGroup,
@@ -15,19 +15,16 @@ import {
 } from '@qoretechnologies/reqore';
 import { IReqoreCollectionProps } from '@qoretechnologies/reqore/dist/components/Collection';
 import { IReqoreCollectionItemProps } from '@qoretechnologies/reqore/dist/components/Collection/item';
-import {
-  IReqorePanelAction,
-  IReqorePanelProps,
-} from '@qoretechnologies/reqore/dist/components/Panel';
+import { IReqorePanelProps } from '@qoretechnologies/reqore/dist/components/Panel';
 import { IReqoreFormTemplates } from '@qoretechnologies/reqore/dist/components/Textarea';
 import { TReqoreIntent } from '@qoretechnologies/reqore/dist/constants/theme';
-import { IReqoreIconName } from '@qoretechnologies/reqore/dist/types/icons';
 import {
   changeDarkness,
   getMainBackgroundColor,
   getReadableColor,
   percentToHexAlpha,
 } from '@qoretechnologies/reqore/dist/helpers/colors';
+import { IReqoreIconName } from '@qoretechnologies/reqore/dist/types/icons';
 import {
   IQorusFormField,
   IQorusFormFieldMessage,
@@ -41,6 +38,8 @@ import {
   TQorusFormOperatorValue,
   TQorusType,
 } from '@qoretechnologies/ts-toolkit';
+import { resolveOptionActions, TOptionActions } from './optionActions';
+import { createRendererOnlyUiTypeCheck, isRendererOnlyUiType } from './rendererTypes';
 import { cloneDeep, findKey, flatten, forEach, isEqual, isPlainObject, last } from 'lodash';
 import isArray from 'lodash/isArray';
 import map from 'lodash/map';
@@ -48,11 +47,10 @@ import reduce from 'lodash/reduce';
 import size from 'lodash/size';
 import React, { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
 import { useMeasure, useMount, useUpdateEffect } from 'react-use';
-import { createContext } from 'use-context-selector';
 import styled from 'styled-components';
+import { createContext } from 'use-context-selector';
 import { getDefaultValue, insertAtIndex, richtextToString } from '../../../helpers/common';
 import { getRequiredOptionMessage } from '../../../helpers/options';
-import { query } from '../../../utils/fetch';
 import {
   IValidationResult,
   hasAllDependenciesFullfilled,
@@ -61,6 +59,7 @@ import {
 } from '../../../helpers/validations';
 import { useQorusTypes } from '../../../hooks/useQorusTypes';
 import { useTemplates } from '../../../hooks/useTemplates';
+import { query } from '../../../utils/fetch';
 import { Description } from '../../Description';
 import { FocusedEditing } from '../../FocusedEditing';
 import { SelectFormField } from '../fields/select/Select';
@@ -72,12 +71,6 @@ import {
 } from '../fields/template/TemplateField';
 import { CompactRow } from './CompactRow';
 import { CompactRowContext, ICompactRowContext } from './compactRowContext';
-import { CompactToolbar } from './CompactToolbar';
-import {
-  CompactToolbarContext,
-  ICompactToolbarContext,
-  TCompactSort,
-} from './compactToolbarContext';
 import {
   GROUP_INDENT,
   LABEL_COL_MAX,
@@ -86,15 +79,30 @@ import {
   StyledCompactPanel,
   StyledGroupBody,
   StyledGroupHeader,
-  StyledGroupHeaderLine,
+  StyledRequiredClusterBox,
+  StyledRequiredClusterHeader,
+  StyledStatusBox,
+  StyledStatusBoxGroupLabel,
 } from './compactRowStyles';
+import { CompactToolbar } from './CompactToolbar';
+import {
+  CompactToolbarContext,
+  ICompactToolbarContext,
+  TCompactSort,
+} from './compactToolbarContext';
 import { OptionFieldMessages } from './OptionFieldMessages';
 import { OptionsHelpDialog } from './OptionsHelpDialog';
 import {
+  TReadFirstStatus,
+  getFirstAttentionOptionName,
   getOptionGroup,
   getOptionGroupLabel,
+  getReadFirstBucket,
   getReadFirstCompletion,
+  getReadFirstStatus,
   isOptionValueEmpty,
+  isFixedCompactAllowedValueOption,
+  shouldAutoCollapseCompactOption,
 } from './readFirst';
 
 // Re-export types for consumers
@@ -125,6 +133,47 @@ export interface IFormValidityData {
   invalidFields: IFormFieldValidityData[];
 }
 
+/**
+ * Resolve a field's `inherit_props` map against the current available
+ * options (plus any values inherited from an outer FormEngine scope),
+ * producing a `{ propName: siblingValue }` hash suitable for spreading
+ * onto the field's renderer.
+ *
+ * For each entry `<prop-name-on-renderer> -> <sibling-field-name>`, the
+ * sibling's current value is forwarded under the receiving prop name.
+ * Lookup order:
+ *   1. `availableOptions[siblingName]?.value` — the field's local scope.
+ *   2. `inheritedFromParent[siblingName]` — the bag threaded in by an
+ *      outer FormEngine (see the `inheritedFromParent` prop). Used when
+ *      a composite field's `arg_schema` sub-form needs to reach a value
+ *      on an ancestor scope — e.g. a service-method row's `body` picking
+ *      up `language` from the parent service form.
+ * Missing siblings emit `undefined`, which the renderer's prop type can
+ * treat as "no hint".
+ *
+ * Designed to be JSON-pure: no closures, no transformations. Renderers
+ * decide how to use the forwarded value (e.g. the consumer-injected
+ * `code-editor` renderer maps a `language: "qore"` prop to its
+ * highlighter mode).
+ *
+ * Mirrored in qorus-ide `src/components/Field/systemOptions.tsx`; keep
+ * the two in sync (see qorus-ide's `.claude/CLAUDE.md`).
+ */
+const resolveInheritProps = (
+  inheritProps: Record<string, string> | undefined,
+  availableOptions: TQorusForm | undefined,
+  inheritedFromParent?: Record<string, unknown>
+): Record<string, unknown> => {
+  if (!inheritProps) return {};
+  const out: Record<string, unknown> = {};
+  for (const propName in inheritProps) {
+    const siblingName = inheritProps[propName];
+    const localValue = (availableOptions?.[siblingName] as IQorusFormField | undefined)?.value;
+    out[propName] = localValue !== undefined ? localValue : inheritedFromParent?.[siblingName];
+  }
+  return out;
+};
+
 const NegativeColorEffect: any = {
   gradient: {
     colors: { 0: 'danger', 100: 'danger:darken:2' },
@@ -153,13 +202,6 @@ const StyledCompactWrap = styled.div<{ $flush?: boolean }>`
      engage instead of overflowing the container horizontally. */
   min-width: 0;
   max-width: 100%;
-  /* A bit of horizontal breathing room for the whole form (header + content
-     alike). Horizontal only — top padding would break the sticky toolbar's
-     flush pin (see the scroll-context note below). Dropped to flush via the
-     compactFlush prop, for embeds that own their own gutters (e.g. the
-     SchemaDefinition tab body). */
-  padding: ${({ $flush }) => ($flush ? '0' : '0 12px')};
-
   /* Own our scroll context instead of borrowing the host's. The sticky toolbar
      pins to whatever scrolls; if that scroller carries top padding (e.g. a
      ReqorePanel/ReqoreContent body), sticky \`top: 0\` resolves against its
@@ -204,12 +246,16 @@ const StyledCommitDock = styled.div<{ $bg: string; $border: string }>`
 `;
 
 export const getType = (
-  type: TQorusType | TQorusType[],
+  type?: TQorusType | TQorusType[],
   operators?: IOperatorsSchema,
   operator?: TOperatorValue
 ): TQorusType => {
   const finalType = getTypeFromOperator(operators, fixOperatorValue(operator)) || type;
-  return (isArray(finalType) ? finalType[0] : finalType) as TQorusType;
+  const resolvedType = isArray(finalType) ? finalType[0] : finalType;
+
+  // A value can be received before its server-driven option schema. Keep the
+  // renderer type-safe during that transition without guessing a concrete type.
+  return (resolvedType || 'any') as TQorusType;
 };
 
 const getTypeFromOperator = (
@@ -226,6 +272,40 @@ export const fixOperatorValue = (operator: TOperatorValue): (string | null | und
   return isArray(operator) ? operator : [operator];
 };
 
+/**
+ * The renderer-only predicate. Defaults to reqraft's built-ins; a FormEngine
+ * instance passes its own (built-ins + the `rendererOnlyUiTypes` prop) so a
+ * consumer's injected editors are recognised too. See `./rendererTypes`.
+ */
+type TRendererOnlyCheck = (type?: TQorusType | TQorusType[]) => boolean;
+
+const getOptionSchemaStorageType = (
+  option?: TQorusFormFieldSchema,
+  isRendererOnly: TRendererOnlyCheck = isRendererOnlyUiType
+): TQorusType =>
+  ((isFixedCompactAllowedValueOption(option)
+    ? option?.type || option?.ui_type
+    : isRendererOnly(option?.ui_type)
+    ? option?.type || option?.ui_type
+    : option?.ui_type || option?.type) || 'any') as TQorusType;
+
+const getOptionFieldStorageType = (
+  optionName: string,
+  fieldType: TQorusType | TQorusType[] | undefined,
+  schema?: IQorusFormSchema,
+  operators?: IOperatorsSchema,
+  operatorData?: TOperatorValue,
+  isRendererOnly: TRendererOnlyCheck = isRendererOnlyUiType
+): TQorusType => {
+  const schemaOption = schema?.[optionName];
+  const storedType =
+    fieldType && !(fieldType === schemaOption?.ui_type && isRendererOnly(fieldType))
+      ? fieldType
+      : getOptionSchemaStorageType(schemaOption, isRendererOnly);
+
+  return getType(storedType as TQorusType, operators, operatorData);
+};
+
 export const hasRequiredOptions = (options: IQorusFormSchema = {}) => {
   return !!findKey(options, (option) => option.required);
 };
@@ -237,11 +317,19 @@ export const OptionsContext = createContext<{
 
 export const fixOptions = (
   value: TQorusForm | TQorusFlatForm = {},
-  options: IQorusFormSchema,
-  operators?: IOperatorsSchema
+  options?: IQorusFormSchema,
+  operators?: IOperatorsSchema,
+  isRendererOnly: TRendererOnlyCheck = isRendererOnlyUiType
 ): TQorusForm => {
   const fixedValue = cloneDeep(value);
 
+  // Server-driven schemas can arrive after the persisted value. Preserve that
+  // value verbatim until its schema is available instead of manufacturing
+  // partially typed form fields that can crash the following render.
+  if (!size(options)) {
+    return fixedValue as TQorusForm;
+  }
+
   forEach(options, (option, name) => {
     if (
       option.value ||
@@ -251,7 +339,7 @@ export const fixOptions = (
     ) {
       let obj: IQorusFormField;
       const type = getType(
-        (option.ui_type || option.type) as TQorusType,
+        getOptionSchemaStorageType(option, isRendererOnly),
         operators,
         (fixedValue[name] as IQorusFormField)?.op
       );
@@ -287,20 +375,35 @@ export const fixOptions = (
       let newOption = option as IQorusFormField;
 
       if (!isPlainObject(newOption) || !(newOption as IQorusFormField)?.type) {
+        const isUntypedEnvelope = isPlainObject(newOption) && 'value' in newOption;
+        const untypedFieldValue =
+          isUntypedEnvelope ? (newOption as IQorusFormField).value : newOption;
+        // Spread the original envelope first so every key it carried survives —
+        // rebuilding from just {type, value} silently dropped `op`, `is_expression`
+        // and anything else a field needs to render, which emptied the card.
         const fixedOption: IQorusFormField = {
+          ...(isPlainObject(newOption) ? (newOption as IQorusFormField) : {}),
           type: getType(
-            (options?.[optionName]?.ui_type || options?.[optionName]?.type) as TQorusType,
+            getOptionSchemaStorageType(options?.[optionName], isRendererOnly),
             operators,
             (newOption as IQorusFormField)?.op
           ),
-          value: newOption,
+          value: untypedFieldValue,
         };
 
-        if ((newOption as IQorusFormField)?.is_expression) {
-          fixedOption.is_expression = true;
-        }
-
         newOption = fixedOption;
+      } else if (
+        newOption.type === options?.[optionName]?.ui_type &&
+        isRendererOnly(newOption.type)
+      ) {
+        newOption = {
+          ...newOption,
+          type: getType(
+            getOptionSchemaStorageType(options?.[optionName], isRendererOnly),
+            operators,
+            newOption.op
+          ),
+        };
       }
 
       if (
@@ -370,7 +473,7 @@ export const flattenOptions = (options: TQorusForm): TQorusFlatForm => {
 };
 
 export const getTypeAndCanBeNull = (
-  type: TQorusType | TQorusType[],
+  type?: TQorusType | TQorusType[],
   allowed_values?: any[],
   operatorData?: TOperatorValue,
   operators?: IOperatorsSchema
@@ -456,6 +559,11 @@ export interface IFormEngineProps extends Omit<IReqoreCollectionProps, 'onChange
   /** Opt-in: fetch global templates from `system/getContextData` for this context. */
   interfaceContext?: string;
   templateFieldProps?: Partial<ITemplateFieldProps>;
+  /**
+   * Force single-value selectors to use inline dropdowns even when their
+   * allowed values carry descriptions.
+   */
+  forceDropdown?: boolean;
   showTypeToggle?: boolean;
   /**
    * Compact (read-first) mode: each option renders as a row with its formatted
@@ -469,6 +577,26 @@ export interface IFormEngineProps extends Omit<IReqoreCollectionProps, 'onChange
    * form should line up with the section description above it. Default `false`.
    */
   compactFlush?: boolean;
+  /**
+   * Compact mode only: this form is an EMBEDDED sub-form (e.g. an arg_schema
+   * field's nested form) rather than the top-level scroller. It doesn't own a
+   * scroll context, so the toolbar isn't sticky and its header drops the dark
+   * blurred backdrop (and the stacking context that goes with it) — it sits
+   * transparently inside the parent's edit card. Default `false`.
+   */
+  compactNested?: boolean;
+  /**
+   * Compact mode only: props forwarded to the read-first form's outer
+   * `ReqorePanel` — the panel that carries the sticky toolbar header and holds
+   * the status boxes. Spread AFTER the engine's own defaults, so anything set
+   * here wins (`flat`, `raised`, `minimal`, `stickyHeader`, `label`, `icon`,
+   * `intent`, `padded`, `size`, …). Two props merge instead of replacing, so a
+   * consumer can add to the panel without dismantling the form:
+   * - `actions` — appended after the engine's toolbar action.
+   * - `contentStyle` — merged over the engine's flex-column layout.
+   * No-op in classic (non-compact) mode.
+   */
+  compactPanelProps?: IReqorePanelProps;
   /** Compact mode only: per-group display metadata (label / icon / subtitle /
    * order) — the server only sends the bare group key. */
   groups?: Record<string, IFormEngineGroup>;
@@ -485,19 +613,84 @@ export interface IFormEngineProps extends Omit<IReqoreCollectionProps, 'onChange
    * option's name/schema/value (the context the IDE's `AiAssistanceAction`
    * captures); the consumer injects the button, reqraft stays AI-free.
    */
-  optionActions?:
-    | IReqorePanelAction[]
-    | ((context: {
-        name: string;
-        schema: IQorusFormSchema[string];
-        value?: TOption;
-      }) => IReqorePanelAction[]);
+  optionActions?: TOptionActions;
+  /**
+   * Whether per-option injected actions collapse into the row's overflow menu
+   * instead of rendering as inline buttons.
+   *
+   * `'auto'` (default) collapses when the device cannot hover or the viewport is
+   * narrow — on a phone a hover-gated action would otherwise be unreachable, and
+   * a row has no width for a button strip. `'always'` / `'never'` force it, which
+   * consumers can use for a known-mobile surface and stories use to capture the
+   * collapsed state deterministically.
+   *
+   * Actions beyond `MAX_INLINE_OPTION_ACTIONS` always overflow into the menu, so
+   * a consumer injecting many actions can never blow out the row.
+   */
+  optionActionsCollapse?: 'auto' | 'always' | 'never';
   /**
    * SEAM (reqraft): consumer-injected field editors for types reqraft doesn't
    * ship (IDE domain fields). Keyed by field `type`/`ui_type`; forwarded through
    * `TemplateField` to the `AutoFormField` override seam.
    */
   componentOverrides?: Record<string, React.FC<any>>;
+  /**
+   * The `ui_type` names among `componentOverrides` that select a bespoke editor
+   * but store their value as the schema's plainer `type` (a `cron` editor stores
+   * a string). Declaring them here keeps the field's stored `type` correct —
+   * without it the renderer name is written into the value and validation and
+   * round-tripping both break. Merged with reqraft's own built-in list, so a
+   * consumer's new editor no longer needs a reqraft release to be handled.
+   */
+  rendererOnlyUiTypes?: string[];
+
+  /**
+   * Bag of values forwarded from an outer FormEngine scope, used as a
+   * fallback when a field's `inherit_props` names a sibling that isn't in
+   * this form's own `availableOptions`. Populated automatically when
+   * FormEngine renders a nested `arg_schema` sub-form (through
+   * AutoFormField's hash / list mount sites) so that each level accumulates
+   * its ancestors' inherited props. Consumers rarely set this by hand — it's
+   * plumbing for the inherit_props scope-forwarding contract.
+   */
+  inheritedFromParent?: Record<string, unknown>;
+
+  /**
+   * Opt-in: on mount, drop the user straight into the first field they must
+   * fill — the first empty, focusable field (in schema/sort order) that is
+   * `required` or a member of a still-unsatisfied one-of `required_groups`
+   * group. Disabled, readonly, read-only-form, and dependency-locked fields are
+   * skipped. In compact (read-first) mode the target row is expanded through
+   * the engine's own `expandedOptions` state, so its editor gains focus with no
+   * DOM scraping or synthetic clicks. Strictly one-shot: it fires the first
+   * time the form has focusable content (so an async-loaded schema is covered)
+   * and then never again — a later value edit, server-driven field update, or
+   * in-place schema reload will not re-focus; only a remount re-arms it. It also
+   * never steals focus from a control the user has already moved into. No-op in
+   * classic (non-compact) mode. Default: off.
+   */
+  autoFocusFirstRequired?: boolean;
+
+  /**
+   * Names of read-first rows to open on mount, in addition to whatever the
+   * user opens afterwards.
+   *
+   * Which rows are expanded is otherwise private to the engine, which is
+   * fine while expansion is only ever a click. It stops being fine when the
+   * expanded row is part of an address: a consumer whose field renders its
+   * own routable surface (a table whose rows open panes with their own URLs)
+   * can restore the pane from the URL, but not the row that has to be open
+   * for the pane to exist at all — so a pasted or reloaded link lands on a
+   * collapsed form.
+   *
+   * Applied once, on the first render where the schema has rows, so an
+   * async-loaded schema is covered. It never re-expands a row the user has
+   * since collapsed, and it does not participate in `expandMode: 'single'`
+   * accordion collapsing — the caller is naming a starting point, not
+   * driving the state. Only a remount re-arms it. No-op in classic
+   * (non-compact) mode.
+   */
+  initialExpandedOptions?: string[];
 }
 
 // Option types rendered full-width (IDE Options parity, commit 8e6b7781).
@@ -522,9 +715,12 @@ export const FormEngine = ({
   allowTemplates = true,
   interfaceContext,
   templateFieldProps,
+  forceDropdown,
   showTypeToggle = true,
   compact,
   compactFlush = false,
+  compactNested = false,
+  compactPanelProps,
   commitMode = 'immediate',
   expandMode = 'single',
   onCommit,
@@ -533,9 +729,35 @@ export const FormEngine = ({
   optionsLoader,
   onValidityChange,
   optionActions,
+  optionActionsCollapse = 'auto',
   componentOverrides,
+  rendererOnlyUiTypes,
+  inheritedFromParent,
+  autoFocusFirstRequired,
+  initialExpandedOptions,
   ...rest
 }: IFormEngineProps) => {
+  // Built-ins + whatever the consumer declared for its own injected editors.
+  const isRendererOnly = useMemo(
+    () => createRendererOnlyUiTypeCheck(rendererOnlyUiTypes),
+    [JSON.stringify(rendererOnlyUiTypes)]
+  );
+  // Pointer CAPABILITY and viewport WIDTH are different questions and both
+  // matter here: a hover-gated action is unreachable without a hover, and a
+  // phone-width row has no space for a button strip either way. Both now come
+  // from Reqore's context (one subscription for the whole app) rather than a
+  // reqraft-local matchMedia hook.
+  //
+  // `isHoverCapable` defaults to `true` in Reqore, but fall back explicitly so
+  // an older Reqore — where the property does not exist — degrades to "this
+  // pointer hovers" (the pre-existing behaviour) instead of collapsing every
+  // action into a menu for everyone.
+  const isHoverCapable = useReqoreProperty('isHoverCapable') ?? true;
+  const isMobile = useReqoreProperty('isMobile');
+  const collapseOptionActions =
+    optionActionsCollapse === 'always' ? true
+    : optionActionsCollapse === 'never' ? false
+    : !isHoverCapable || !!isMobile;
   const [options, setOptions] = useState<IQorusFormSchema | undefined>(rest?.options || undefined);
   // optionsLoader lifecycle: loading feeds the skeleton gate, error the banner.
   const [optionsLoading, setOptionsLoading] = useState<boolean>(!!optionsLoader && !rest?.options);
@@ -560,6 +782,10 @@ export const FormEngine = ({
   const [showInvalidOptionsOnly, setShowInvalidOptionsOnly] = useState<boolean>(false);
   // Which options are expanded into their editor (several can be open at once).
   const [expandedOptions, setExpandedOptions] = useState<string[]>([]);
+  // Remembers each row's last settled status box, so an actively-edited field
+  // stays put when its status flips (e.g. becomes valid) instead of jumping to
+  // another box mid-edit and stealing focus. Keyed by option name.
+  const settledBucket = useRef<Record<string, 'attention' | 'set' | 'optional'>>({});
   // Measured form width (not viewport — the form lives in drawers/panels of
   // arbitrary width) drives the stacked narrow layout.
   const [compactWrapRef, { width: compactWrapWidth }] = useMeasure<HTMLDivElement>();
@@ -614,9 +840,18 @@ export const FormEngine = ({
   const flashTimeout = useRef<ReturnType<typeof setTimeout>>();
   const flashOptions = useCallback((optionNames: string[], scrollToFirst = false) => {
     if (scrollToFirst && optionNames[0]) {
-      document
-        .querySelector(`.readfirst-row[data-field="${optionNames[0]}"]`)
-        ?.scrollIntoView({ block: 'center', behavior: 'smooth' });
+      // Defer to the next frame: when this fires for a field that just changed
+      // panels, its row has only just re-mounted in the new box — scrolling in the
+      // same tick targets the stale (pre-move) layout, so the page doesn't budge.
+      // A rAF lets the new position settle first.
+      requestAnimationFrame(() => {
+        const target = document.querySelector<HTMLElement>(
+          `.readfirst-row[data-field="${optionNames[0]}"]`
+        );
+        if (typeof target?.scrollIntoView === 'function') {
+          target.scrollIntoView({ block: 'center', behavior: 'smooth' });
+        }
+      });
     }
     setFlashedOptions(optionNames);
     clearTimeout(flashTimeout.current);
@@ -627,6 +862,28 @@ export const FormEngine = ({
     [flashOptions]
   );
   useEffect(() => () => clearTimeout(flashTimeout.current), []);
+
+  // Follow a field across panels: when its status bucket changes — e.g. you fill
+  // an optional field and it jumps to Set / Needs attention — scroll to its new
+  // row and flash it so it's easy to keep track of. `settledBucket` holds each
+  // field's current panel (frozen while the field is being edited, it re-buckets
+  // on collapse), so diffing it after every render catches the move the instant it
+  // lands in the new panel. Runs every render; the diff is cheap and only fires a
+  // scroll on an ACTUAL move of a non-expanded field.
+  const prevSettledBucket = useRef<Record<string, 'attention' | 'set' | 'optional'>>({});
+  useEffect(() => {
+    if (!compact) return;
+    const cur = settledBucket.current;
+    const prev = prevSettledBucket.current;
+    const moved = Object.keys(cur).find(
+      (name) => prev[name] && prev[name] !== cur[name] && !expandedOptions.includes(name)
+    );
+    prevSettledBucket.current = { ...cur };
+    if (moved) {
+      flashOptions([moved], true);
+    }
+  });
+
   const compactNarrow = !!compactWrapWidth && compactWrapWidth < 480;
   // Info panels auto-open on Tier-1 content; the per-row user override sticks.
   const [infoPanelOverrides, setInfoPanelOverrides] = useState<Record<string, boolean>>({});
@@ -639,7 +896,7 @@ export const FormEngine = ({
     fields: TQorusForm | TQorusFlatForm;
     meta?: IOptionsOnChangeMeta;
   }>(() => ({
-    fields: fixOptions(value, options || {}),
+    fields: fixOptions(value, options || {}, undefined, isRendererOnly),
     meta: undefined,
   }));
   const originalValue = useRef<any>();
@@ -732,7 +989,7 @@ export const FormEngine = ({
           setOptions({});
           return;
         }
-        setLocalValue({ fields: fixOptions(value, data.data), meta: undefined });
+        setLocalValue({ fields: fixOptions(value, data.data, undefined, isRendererOnly), meta: undefined });
         if (!operatorsUrl) {
           setLoading(false);
         }
@@ -777,7 +1034,7 @@ export const FormEngine = ({
         }
         setOptions(data.data);
         onOptionsLoaded?.(data.data);
-        setLocalValue({ fields: fixOptions({}, data.data), meta: undefined });
+        setLocalValue({ fields: fixOptions({}, data.data, undefined, isRendererOnly), meta: undefined });
       })();
     }
   }, [url, customUrl]);
@@ -801,7 +1058,7 @@ export const FormEngine = ({
   }, [operatorsUrl]);
 
   useUpdateEffect(() => {
-    const fixedValue = fixOptions(value, options || {});
+    const fixedValue = fixOptions(value, options || {}, undefined, isRendererOnly);
 
     // When the value we're receiving is the one we just emitted AND fixOptions has nothing to
     // meaningfully add or change, skip the update. This breaks the controlled-component loop for
@@ -825,19 +1082,21 @@ export const FormEngine = ({
     }
 
     setLocalValue?.({ fields: fixedValue, meta: undefined });
-  }, [JSON.stringify(options), JSON.stringify(value)]);
+  }, [JSON.stringify(options), JSON.stringify(value), isRendererOnly]);
 
   const handleValueChange = useCallback(
     (optionName: string, val?: any, _type?: string, isFunction?: boolean) => {
       setLocalValue(({ fields = {} }) => {
-        const schemaType = (options?.[optionName]?.ui_type ||
-          options?.[optionName]?.type) as TQorusType;
+        const schemaType = getOptionSchemaStorageType(options?.[optionName], isRendererOnly);
         const isAnyLike = schemaType === 'any' || schemaType === 'auto';
         // For any/auto schema types, preserve the user's chosen type stored in the field
         const resolvedSchemaType =
-          isAnyLike && (fields[optionName] as IQorusFormField)?.type ?
-            ((fields[optionName] as IQorusFormField).type as TQorusType)
-          : schemaType || ((fields[optionName] as IQorusFormField)?.type as TQorusType);
+          isAnyLike && (fields[optionName] as IQorusFormField)?.type
+            ? ((fields[optionName] as IQorusFormField).type as TQorusType)
+            : (fields[optionName] as IQorusFormField)?.type === options?.[optionName]?.ui_type &&
+                isRendererOnly((fields[optionName] as IQorusFormField)?.type)
+              ? schemaType
+              : schemaType || ((fields[optionName] as IQorusFormField)?.type as TQorusType);
         const type =
           _type ||
           getTypeAndCanBeNull(resolvedSchemaType, options?.[optionName]?.allowed_values).type;
@@ -911,6 +1170,14 @@ export const FormEngine = ({
 
         onSingleOptionsChange?.(optionName, updatedValue[optionName]);
 
+        if (
+          compact &&
+          !readOnly &&
+          shouldAutoCollapseCompactOption(options?.[optionName], val)
+        ) {
+          setExpandedOptions((prev) => prev.filter((name) => name !== optionName));
+        }
+
         return {
           fields: updatedValue,
           meta,
@@ -920,6 +1187,9 @@ export const FormEngine = ({
     [
       onSingleOptionsChange,
       onDependableOptionChange,
+      isRendererOnly,
+      compact,
+      readOnly,
       JSON.stringify(options),
       JSON.stringify(operators),
     ]
@@ -1028,6 +1298,10 @@ export const FormEngine = ({
         meta: undefined,
       };
     });
+    // Collapse it too: a removed field drops back to the (collapsed) Optional box
+    // as a quiet addable row — if it was being edited, that editor must close
+    // rather than linger as an open editor for a field that's no longer added.
+    setExpandedOptions((prev) => prev.filter((name) => name !== optionName));
   }, []);
 
   const handleAddOptionalFieldChange = useCallback(
@@ -1036,8 +1310,7 @@ export const FormEngine = ({
         optionName as string,
         getDefaultValue(options?.[optionName as string]),
         getTypeAndCanBeNull(
-          (options?.[optionName as string]?.ui_type ||
-            options?.[optionName as string]?.type) as TQorusType,
+          getOptionSchemaStorageType(options?.[optionName as string], isRendererOnly),
           options?.[optionName as string]?.allowed_values
         ).type
       );
@@ -1065,36 +1338,37 @@ export const FormEngine = ({
           return newValue;
         }
 
-        const schemaType = getType(
+        const rendererType = getType(
           (options[optionName].ui_type || options[optionName].type) as TQorusType,
           operators,
           (option as IQorusFormField)?.op
         );
+        const storageType = getOptionFieldStorageType(
+          optionName,
+          (option as IQorusFormField)?.type,
+          options,
+          operators,
+          (option as IQorusFormField)?.op,
+          isRendererOnly
+        );
 
         if (!isPlainObject(option)) {
           return {
             ...newValue,
             [optionName]: {
-              type: schemaType,
+              type: storageType || rendererType,
               value: option,
             },
           };
         }
 
-        // any/auto: preserve the user-picked type; otherwise normalize to the
-        // schema type (ui_type wins) so rendering and validation agree.
-        const isAnyLike = schemaType === 'any' || schemaType === 'auto';
-        const effectiveType =
-          isAnyLike && (option as IQorusFormField)?.type ?
-            (option as IQorusFormField).type
-          : schemaType;
-
         return {
           ...newValue,
-          [optionName]: { ...(option as IQorusFormField), type: effectiveType },
+          [optionName]: { ...(option as IQorusFormField), type: storageType || rendererType },
         };
       }, {});
   }, [
+    isRendererOnly,
     JSON.stringify(fixedValue),
     JSON.stringify(options),
     unavailableOptionsCount.current,
@@ -1191,10 +1465,14 @@ export const FormEngine = ({
     const fields: IFormFieldValidityData[] = reduce(
       availableOptions,
       (result, option, optionName) => {
-        const type =
-          (option as IQorusFormField).type ||
-          (options?.[optionName]?.ui_type as TQorusType) ||
-          (options?.[optionName]?.type as TQorusType);
+        const type = getOptionFieldStorageType(
+          optionName,
+          (option as IQorusFormField).type,
+          options,
+          operators,
+          (option as IQorusFormField).op,
+          isRendererOnly
+        );
         const optionValue = (option as IQorusFormField).value;
 
         const isRequired = options?.[optionName]?.required;
@@ -1236,8 +1514,10 @@ export const FormEngine = ({
       invalidFields,
     };
   }, [
+    isRendererOnly,
     JSON.stringify(availableOptions),
     JSON.stringify(options),
+    JSON.stringify(operators),
     JSON.stringify(localValue.fields),
   ]);
 
@@ -1256,8 +1536,14 @@ export const FormEngine = ({
           showInvalidOptionsOnly &&
           isOptionValid(
             optionName,
-            (options?.[optionName]?.ui_type as TQorusType) ||
-              (options?.[optionName]?.type as TQorusType),
+            getOptionFieldStorageType(
+              optionName,
+              (option as IQorusFormField).type,
+              options,
+              operators,
+              (option as IQorusFormField).op,
+              isRendererOnly
+            ),
             (option as IQorusFormField).value
           )
         ) {
@@ -1267,7 +1553,89 @@ export const FormEngine = ({
       },
       {}
     );
-  }, [showInvalidOptionsOnly, JSON.stringify(availableOptions)]);
+  }, [
+    showInvalidOptionsOnly,
+    isRendererOnly,
+    JSON.stringify(availableOptions),
+    JSON.stringify(options),
+    JSON.stringify(operators),
+  ]);
+
+  // Read-first STATUS / BOX for one option — lifted to component scope so the
+  // status boxes (renderCompact) and the header's "needs attention" count share
+  // exactly one definition. One-of group members travel together (bucket by the
+  // group's satisfaction); everything else by its own status.
+  const schemaMsgIntent = useCallback(
+    (name: string): 'danger' | 'warning' | undefined => {
+      const msgs = ((options?.[name] as { messages?: Array<{ intent?: string }> } | undefined)
+        ?.messages || []) as Array<{ intent?: string }>;
+      if (msgs.some((m) => m.intent === 'danger')) return 'danger';
+      if (msgs.some((m) => m.intent === 'warning')) return 'warning';
+      return undefined;
+    },
+    [JSON.stringify(options)]
+  );
+  const getOptionStatus = useCallback(
+    (name: string, hidden = false): TReadFirstStatus => {
+      if (hidden) return 'optional';
+      const schema = options?.[name];
+      const type = getOptionFieldStorageType(
+        name,
+        (availableOptions as TQorusForm)?.[name]?.type,
+        options,
+        operators,
+        (availableOptions as TQorusForm)?.[name]?.op,
+        isRendererOnly
+      );
+      const value = (availableOptions as TQorusForm)?.[name]?.value;
+      const empty = isOptionValueEmpty(value);
+      const reqGroups = (schema?.required_groups as string[] | undefined) || [];
+      const required = !!(schema?.required || reqGroups.length);
+      const covered =
+        empty &&
+        reqGroups.some((g) => {
+          const by = requiredGroupsInfo.satisfiedBy[g];
+          return !!by && by !== name;
+        });
+      const msgIntent = schemaMsgIntent(name);
+      const invalid = (!empty && !isOptionValid(name, type, value)) || msgIntent === 'danger';
+      return getReadFirstStatus({
+        empty,
+        required,
+        covered,
+        invalid,
+        warned: msgIntent === 'warning',
+      });
+    },
+    [
+      isRendererOnly,
+      JSON.stringify(options),
+      JSON.stringify(availableOptions),
+      JSON.stringify(operators),
+      isOptionValid,
+      requiredGroupsInfo,
+      schemaMsgIntent,
+    ]
+  );
+  const getOptionBucket = useCallback(
+    (name: string, hidden = false): 'attention' | 'set' | 'optional' => {
+      if (!hidden) {
+        const reqGroups = (options?.[name]?.required_groups as string[] | undefined) || [];
+        if (reqGroups.length) {
+          return reqGroups.some((g) => !requiredGroupsInfo.satisfiedBy[g]) ? 'attention' : 'set';
+        }
+      }
+      return getReadFirstBucket(getOptionStatus(name, hidden));
+    },
+    [JSON.stringify(options), requiredGroupsInfo, getOptionStatus]
+  );
+  // How many fields are in the "Needs attention" box — drives the header link.
+  const readFirstAttentionCount = useMemo(
+    () =>
+      Object.keys(availableOptions || {}).filter((name) => getOptionBucket(name) === 'attention')
+        .length,
+    [JSON.stringify(availableOptions), getOptionBucket]
+  );
 
   const getIntent = useCallback(
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
@@ -1346,6 +1714,120 @@ export const FormEngine = ({
     [expandMode]
   );
 
+  // --- Caller-named starting rows (opt-in) ----------------------------------
+  // `initialExpandedOptions` lets a consumer name the rows that must already
+  // be open when the form first paints — the case where the expanded row is
+  // part of an address rather than a click (see the prop's docs).
+  //
+  // One-shot for the same reason autofocus is: it fires on the first render
+  // that actually has rows (so an async-loaded schema is covered) and then
+  // never again, so a row the user collapses afterwards stays collapsed and a
+  // later schema reload does not reopen it.
+  const hasAppliedInitialExpansionRef = useRef(false);
+  useEffect(() => {
+    if (!initialExpandedOptions?.length || !compact || hasAppliedInitialExpansionRef.current) {
+      return;
+    }
+    const names = Object.keys(availableOptions);
+    if (!names.length) {
+      return;
+    }
+    hasAppliedInitialExpansionRef.current = true;
+    const toExpand = initialExpandedOptions.filter((name) => names.includes(name));
+    if (!toExpand.length) {
+      return;
+    }
+    setExpandedOptions((prev) => [...prev, ...toExpand.filter((name) => !prev.includes(name))]);
+  }, [initialExpandedOptions, compact, availableOptions]);
+
+  // --- First-attention-field autofocus (opt-in) -----------------------------
+  // With `autoFocusFirstRequired`, drop the user straight into the first field
+  // they must fix. We reuse the engine's own ordering (`availableOptions`), the
+  // very same `getOptionBucket` the status boxes use to decide "needs attention"
+  // (so we cover empty-required, unsatisfied one-of, AND filled-but-invalid rows
+  // without ever drifting from what the user sees), and dependency gating
+  // (`dependencyLockedNames`), then expand the target row through
+  // `expandedOptions` — the row's editor-focus effect does the rest. No DOM
+  // scraping, no synthetic clicks, no polling.
+  //
+  // Strictly one-shot: it fires the first time the form has focusable content
+  // (so an async-loaded schema is still covered — the empty first pass doesn't
+  // count), then never again for the life of this instance. A server-driven
+  // field update or an in-place schema reload will NOT re-grab focus; only a
+  // genuine remount (a fresh instance) auto-focuses again, which is the intended
+  // on-mount behaviour.
+  const hasAutoFocusedRef = useRef(false);
+  // The field expanded programmatically for autofocus. A ref (not state) so
+  // CompactRow's 60ms focus timer reads the current value regardless of render
+  // batching; CompactRow focuses this one with `preventScroll` so an off-screen
+  // (or below-the-fold) form is never scrolled into view on mount.
+  const autoFocusNameRef = useRef<string | undefined>(undefined);
+  useEffect(() => {
+    if (!autoFocusFirstRequired || !compact || !options) {
+      return;
+    }
+    if (hasAutoFocusedRef.current) {
+      return;
+    }
+
+    const orderedNames = Object.keys(availableOptions);
+    if (!orderedNames.length) {
+      return;
+    }
+
+    // Never grab focus from a control the user is already in — including a field
+    // *inside* this form. If a slow/async schema lets the user start typing
+    // before this first-required scan runs, we must not steal their caret. On a
+    // clean mount focus rests on the body, so the intended "drop into the first
+    // field" still fires. Bailing here leaves `hasAutoFocusedRef` false, so it
+    // retries once focus is free.
+    const active = document.activeElement as HTMLElement | null;
+    if (active && active !== document.body) {
+      return;
+    }
+
+    const target = getFirstAttentionOptionName(orderedNames, (fieldName) => {
+      const schema = options[fieldName];
+      if (!schema) {
+        return undefined;
+      }
+      return {
+        focusable:
+          !readOnly &&
+          !schema.disabled &&
+          !(schema as { readonly?: boolean }).readonly &&
+          !dependencyLockedNames.includes(fieldName),
+        // Single source of truth: the same bucket the read-first status boxes
+        // show, so a filled-but-invalid required row is a target too.
+        needsAttention: getOptionBucket(fieldName) === 'attention',
+      };
+    });
+
+    // Mark done even when nothing needs attention, so later value edits or an
+    // in-place schema reload never re-scan or re-focus. Only a remount arms it
+    // again.
+    hasAutoFocusedRef.current = true;
+
+    if (target) {
+      // Set the ref before the state update so CompactRow's focus timer sees it.
+      autoFocusNameRef.current = target;
+      setExpandedOptions((prev) =>
+        prev.includes(target) ? prev
+        : expandMode === 'multi' ? [...prev, target]
+        : [target]
+      );
+    }
+  }, [
+    autoFocusFirstRequired,
+    compact,
+    options,
+    availableOptions,
+    readOnly,
+    dependencyLockedNames,
+    getOptionBucket,
+    expandMode,
+  ]);
+
   // Read-first completion summary (how many shown options have a value set),
   // surfaced as a progress meter at the top of the compact form.
   const readFirstCompletion = useMemo(
@@ -1395,10 +1877,10 @@ export const FormEngine = ({
           next[optionName] = value as IQorusFormField;
         }
       });
-      return { fields: fixOptions(next, options || {}, operators), meta: undefined };
+      return { fields: fixOptions(next, options || {}, operators, isRendererOnly), meta: undefined };
     });
     setRequiredOnly(false);
-  }, [JSON.stringify(options), JSON.stringify(operators)]);
+  }, [JSON.stringify(options), JSON.stringify(operators), isRendererOnly]);
 
   const getCustomMenuTemplateItems = useCallback<(optionName: string) => TCustomTemplateItems>(
     (optionName) => {
@@ -1428,22 +1910,72 @@ export const FormEngine = ({
       suppressSchemaMessages?: boolean
     ) => {
       const operatorParts = fixOperatorValue(other.op);
+      // The RENDERER type for this row — which editor mounts. Distinct from the
+      // storage type on the value envelope: a `richtext` field stores a string
+      // but must render the richtext editor, so `ui_type` wins here.
+      //
+      // The exception is an any-like `ui_type`. Those schemas say
+      // `ui_type: 'any'` precisely so the user can pick a concrete type, and
+      // that pick lives on the field's stored `type` — letting 'any' win would
+      // pin the row to the untyped editor forever.
+      //
+      // The trailing fallbacks keep the row rendering when a server-driven
+      // schema has not arrived yet (`type` undefined) instead of crashing.
+      const optionSchema = options?.[optionName];
+      const schemaUiType = optionSchema?.ui_type as TQorusType;
+      const uiTypeIsAnyLike = schemaUiType === 'any' || schemaUiType === 'auto';
+      const resolvedType =
+        (isFixedCompactAllowedValueOption(optionSchema)
+          ? getOptionSchemaStorageType(optionSchema, isRendererOnly)
+          : schemaUiType && !uiTypeIsAnyLike
+            ? schemaUiType
+            : undefined) ||
+        type ||
+        schemaUiType ||
+        (optionSchema?.type as TQorusType) ||
+        'any';
+      const effectiveForceDropdown =
+        forceDropdown ??
+        (templateFieldProps as { forceDropdown?: boolean } | undefined)?.forceDropdown;
+
       return (
         <>
-          {(suppressSchemaMessages ? [] : (options?.[optionName] as any)?.messages || []).map(
-            ({ intent, title, content }: any, index: number) => (
+          {(() => {
+            const schemaMsgs = (
+              suppressSchemaMessages ?
+                []
+              : (options?.[optionName] as any)?.messages || []) as {
+              intent?: string;
+              title?: string;
+              content?: string;
+            }[];
+            if (!schemaMsgs.length) return null;
+            const items = schemaMsgs.map(({ intent, title, content }, index) => (
               <ReqoreMessage
-                intent={intent}
+                intent={intent as never}
                 title={title}
                 key={title || index}
                 opaque={false}
                 size='small'
-                margin='bottom'
+                // Compact: flat (no border) to match the read-row info panels;
+                // classic forms keep the bordered, bottom-margined message.
+                flat={compact || undefined}
+                margin={compact ? undefined : 'bottom'}
               >
                 {content}
               </ReqoreMessage>
-            )
-          )}
+            ));
+            // Compact: stack them in a 4px-gap panel so a field's messages look
+            // identical whether the row is collapsed (read panel) or expanded.
+            return compact ?
+                <div
+                  className='options-readfirst-info-panel'
+                  style={{ display: 'flex', flexFlow: 'column', gap: 4, marginBottom: 8 }}
+                >
+                  {items}
+                </div>
+              : <>{items}</>;
+          })()}
           {operators && size(operators) ?
             <>
               <ReqoreControlGroup fill wrap className='operators'>
@@ -1498,6 +2030,46 @@ export const FormEngine = ({
           <TemplateField
             fluid
             {...(options?.[optionName] as any)}
+            // qorus#347-followup: resolve the field's `inherit_props` against
+            // the CURRENT sibling values (with a fallback to
+            // `inheritedFromParent` — the bag threaded in from an outer
+            // FormEngine when this scope is an `arg_schema` sub-form),
+            // threading each entry as a top-level prop. Each
+            // `<prop-name>: <sibling-field-name>` mapping copies the
+            // sibling's value onto the rendered field's renderer — e.g. a
+            // `code-editor` with `inherit_props: { language: 'language' }`
+            // picks up the live `language` value as a `language` prop without
+            // a schema refetch. Spread AFTER `{...options?.[optionName]}` so
+            // the runtime value wins over any schema-defined default of the
+            // same key. Mirrored in qorus-ide's `systemOptions.tsx`; see the
+            // CLAUDE.md rule there.
+            {...resolveInheritProps(
+              options?.[optionName]?.inherit_props,
+              availableOptions,
+              inheritedFromParent
+            )}
+            // qorus#347-followup (scope forwarding): merge accumulated
+            // inheritance (`inheritedFromParent`) with THIS field's freshly
+            // resolved inherit_props, and pass down as a single bag so any
+            // nested `arg_schema` sub-form (mounted by AutoFormField for
+            // `hash` / `free-hash` / list-of-hash fields) sees every value
+            // the ancestor chain forwarded. This is the plumbing that lets a
+            // service-method row's `body` sub-field pick up the parent
+            // service form's `language` — the parent field declares
+            // `inherit_props: { language: 'language' }`, the list renderer
+            // forwards it into each row, and the row's body resolves against
+            // the accumulated bag.
+            inheritedFromParent={{
+              ...inheritedFromParent,
+              ...resolveInheritProps(
+                options?.[optionName]?.inherit_props,
+                availableOptions,
+                inheritedFromParent
+              ),
+            }}
+            // Propagate compact so an arg_schema field renders a COMPACT sub-form
+            // (consistent with the parent) rather than the classic FormEngine.
+            compact={compact}
             // SEAM: forwarded through TemplateField's rest-spread to AutoFormField,
             // which renders consumer-injected editors by field type/ui_type.
             componentOverrides={componentOverrides}
@@ -1506,16 +2078,27 @@ export const FormEngine = ({
             // reqraft: form-level expression fields get the Visual/Text shell
             // (DPQL text mode); opt out per-form via `templateFieldProps`.
             allowTextExpressions
+            // A fixed allowed-value field still needs its selector even when
+            // arbitrary custom values are forbidden. TemplateField uses this
+            // flag to decide whether to mount AutoFormField at all; treating
+            // `supports_custom_values: false` as "no input" left dependent
+            // delivery fields (Discord server/channel, for example) as empty
+            // control groups. The allowed-values renderer itself enforces the
+            // fixed catalogue and never exposes free-form entry.
             allowCustomValues={
-              options?.[optionName]?.supports_custom_values !== false && type !== 'any'
+              isFixedCompactAllowedValueOption(optionSchema) ||
+              (options?.[optionName]?.supports_custom_values !== false && resolvedType !== 'any')
             }
             templates={templates.value}
             {...getTypeAndCanBeNull(
-              type as TQorusType,
+              // The RENDERER type picks the editor — the storage type lives on
+              // the value envelope. Passing storage here rendered a `richtext`
+              // field as a plain string input.
+              resolvedType,
               options?.[optionName]?.allowed_values,
               other.op
             )}
-            ui_type={type}
+            ui_type={resolvedType}
             name={optionName}
             uniqueName={`${uniqueName ? `${uniqueName}.` : `${name ? `${name}.` : ''}`}${optionName}`}
             onChange={
@@ -1534,6 +2117,7 @@ export const FormEngine = ({
             default_value={getDefaultValue(options?.[optionName])}
             isDefaultTemplate={options?.[optionName]?.default_view === 'template'}
             allowed_values={options?.[optionName]?.allowed_values}
+            allowed_values_creatable={options?.[optionName]?.allowed_values_creatable}
             disabled={
               options?.[optionName]?.disabled ||
               readOnly ||
@@ -1551,12 +2135,13 @@ export const FormEngine = ({
               : undefined
             }
             {...templateFieldProps}
+            forceDropdown={effectiveForceDropdown}
           />
           <OptionFieldMessages
             schema={options || {}}
             allOptions={availableOptions}
             name={optionName}
-            option={{ type, ...other }}
+            option={{ type: resolvedType, ...other }}
             getType={getTypeForOption}
           />
           {operators && size(operators) && size(other.op) ?
@@ -1571,7 +2156,7 @@ export const FormEngine = ({
                     intent='info'
                     label={
                       other.value ?
-                        type === 'richtext' ?
+                        resolvedType === 'richtext' ?
                           richtextToString(other.value)
                         : JSON.stringify(other.value)
                       : ''
@@ -1594,6 +2179,7 @@ export const FormEngine = ({
       uniqueName,
       componentOverrides,
       templateFieldProps,
+      forceDropdown,
       availableOptions,
       fixedValue,
       // Depend on the specific `rest` values used, not the whole `rest` object
@@ -1643,6 +2229,7 @@ export const FormEngine = ({
       showFieldTypes,
       showAllDescriptions,
       expandedOptions,
+      autoFocusNameRef,
       highlightedOptions,
       flashedOptions,
       infoPanelOverrides,
@@ -1663,6 +2250,8 @@ export const FormEngine = ({
       getTypeForOption,
       isOptionValid,
       confirmAction,
+      optionActions,
+      collapseOptionActions,
       renderOption,
       theme,
       cText,
@@ -1687,6 +2276,7 @@ export const FormEngine = ({
       showFieldTypes,
       showAllDescriptions,
       expandedOptions,
+      autoFocusNameRef,
       highlightedOptions,
       flashedOptions,
       infoPanelOverrides,
@@ -1707,6 +2297,8 @@ export const FormEngine = ({
       getTypeForOption,
       isOptionValid,
       confirmAction,
+      optionActions,
+      collapseOptionActions,
       renderOption,
       theme,
       cText,
@@ -1726,6 +2318,7 @@ export const FormEngine = ({
     () => ({
       readOnly,
       invalidCount: size(validityData.invalidFields),
+      attentionCount: readFirstAttentionCount,
       completion: readFirstCompletion,
       showInvalidOnly: showInvalidOptionsOnly,
       onToggleInvalidOnly: handleToggleInvalidOnly,
@@ -1751,6 +2344,7 @@ export const FormEngine = ({
     [
       readOnly,
       validityData,
+      readFirstAttentionCount,
       readFirstCompletion,
       showInvalidOptionsOnly,
       handleToggleInvalidOnly,
@@ -1776,7 +2370,13 @@ export const FormEngine = ({
     ]
   );
 
-  const compactHeaderActions = useMemo(() => [{ as: CompactToolbar, responsive: false }], []);
+  // The engine's own toolbar action, plus whatever the consumer added through
+  // `compactPanelProps.actions` — appended, so an outside action can never
+  // knock the form's toolbar out of the header.
+  const compactHeaderActions = useMemo(
+    () => [{ as: CompactToolbar, responsive: false }, ...(compactPanelProps?.actions || [])],
+    [compactPanelProps?.actions]
+  );
   const renderCompact = () => {
     const headerBg = `${changeDarkness(getMainBackgroundColor(theme), 0.02)}${percentToHexAlpha(88)}`;
     // Toolbar filters narrow the listed rows; the meter reflects the full set.
@@ -1809,15 +2409,18 @@ export const FormEngine = ({
         pushRow(optionName, false);
       }
     });
-    // When searching, also surface matching hidden optional fields (not yet
-    // added) so the search spans the whole schema, not just the visible rows.
-    if (query) {
-      forEach(filteredOptions, (_schema, optionName) => {
-        if (matchesQuery(optionName)) {
-          pushRow(optionName, true);
-        }
-      });
-    }
+    // Surface EVERY not-yet-added optional field as an addable (hidden) row, so
+    // the whole schema is browsable inline — they all land in the Optional box
+    // (hidden ⇒ 'optional' bucket) instead of being buried in the Fields menu.
+    // Narrowed by the same filters as the listed rows (search query + required-
+    // only). availableOptions (listed) and filteredOptions (these) are disjoint —
+    // the former is built from fixedValue keys, the latter excludes them — so a
+    // field is never both a listed and a hidden row.
+    forEach(filteredOptions, (_schema, optionName) => {
+      if (matchesFilters(optionName)) {
+        pushRow(optionName, true);
+      }
+    });
 
     // User sort (Fields menu → "Sort by"), applied WITHIN each group so the
     // group sections and the required-group rails are preserved. Schema order is
@@ -1832,7 +2435,14 @@ export const FormEngine = ({
       const isFieldInvalid = (name: string) =>
         !isOptionValid(
           name,
-          (options?.[name]?.ui_type || options?.[name]?.type) as TQorusType,
+          getOptionFieldStorageType(
+            name,
+            (shownOptions as TQorusForm)[name]?.type,
+            options,
+            operators,
+            (shownOptions as TQorusForm)[name]?.op,
+            isRendererOnly
+          ),
           (shownOptions as TQorusForm)[name]?.value
         );
       const comparator = (a: { name: string }, b: { name: string }): number => {
@@ -1863,6 +2473,67 @@ export const FormEngine = ({
       return groupOrder.indexOf(a) - groupOrder.indexOf(b);
     });
 
+    // Read-first STATUS per row → one of three boxes (Needs attention / Set /
+    // Optional), via the component-scope getOptionBucket (shared with the header
+    // count and the row dot, so box ↔ dot ↔ header always agree). Buckets keep
+    // schema-group order (thin sub-labels) and the required-group clustering: an
+    // unmet one-of group's members all land in attention and still rail up.
+    type TRowEntry = { name: string; hidden: boolean };
+    type TBucketKey = 'attention' | 'set' | 'optional';
+    const buckets: Record<TBucketKey, Record<string, TRowEntry[]>> = {
+      attention: {},
+      set: {},
+      optional: {},
+    };
+    const bucketGroups: Record<TBucketKey, string[]> = { attention: [], set: [], optional: [] };
+    // Freeze the box of any field currently being edited (or whose one-of group
+    // has an edited member) to its last settled box — so finishing an edit that
+    // flips its status doesn't remount it in another box and steal focus.
+    const stableBucketOf = (entry: TRowEntry): TBucketKey => {
+      const fresh = getOptionBucket(entry.name, entry.hidden);
+      const groupBeingEdited =
+        !entry.hidden &&
+        ((options?.[entry.name]?.required_groups as string[] | undefined) || []).some((g) =>
+          (requiredGroupsInfo.members[g] || []).some((m) => expandedOptions.includes(m))
+        );
+      if (!entry.hidden && (expandedOptions.includes(entry.name) || groupBeingEdited)) {
+        const memo = settledBucket.current[entry.name];
+        if (memo) return memo;
+      }
+      settledBucket.current[entry.name] = fresh;
+      return fresh;
+    };
+    groupKeys.forEach((groupName) => {
+      grouped[groupName].forEach((entry) => {
+        const b = stableBucketOf(entry);
+        if (!buckets[b][groupName]) {
+          buckets[b][groupName] = [];
+          bucketGroups[b].push(groupName);
+        }
+        buckets[b][groupName].push(entry);
+      });
+    });
+    const bucketCount = (b: TBucketKey) =>
+      bucketGroups[b].reduce((n, g) => n + buckets[b][g].length, 0);
+    // 'general' / 'optional' are the SYNTHETIC fallback group keys getOptionGroup
+    // assigns to fields with no explicit `group` — printing a "General"/"Optional"
+    // sub-label for those is just noise, so suppress it. BUT a consumer may also
+    // use 'general' as a REAL group (defining it in the `groups` prop and tagging
+    // fields with `group: 'general'`); in that case it's a named group like any
+    // other and DOES get its sub-label.
+    const showGroupSubLabel = (groupName: string) =>
+      (groupName !== 'general' && groupName !== 'optional') || !!groups?.[groupName];
+    const STATUS_BOXES: Array<{
+      key: TBucketKey;
+      label: string;
+      intent?: 'warning' | 'success';
+      icon: IReqoreIconName;
+    }> = [
+      { key: 'attention', label: 'Needs attention', intent: 'warning', icon: 'ErrorWarningLine' },
+      { key: 'set', label: 'Set', intent: 'success', icon: 'CheckLine' },
+      { key: 'optional', label: 'Optional', icon: 'CheckboxBlankCircleLine' },
+    ];
+
     // Build the rows for one group: contiguous required-group members are pulled
     // together at the first member's slot and rendered as a connected rail (flat
     // rows — no wrapper — so the value surface applies normally; the rail + nodes
@@ -1880,7 +2551,7 @@ export const FormEngine = ({
           optionField={
             entry.hidden ?
               ({
-                type: (options?.[entry.name]?.ui_type || options?.[entry.name]?.type) as TQorusType,
+                type: getOptionSchemaStorageType(options?.[entry.name], isRendererOnly),
                 value: undefined,
               } as IQorusFormField)
             : ((shownOptions as TQorusForm)[entry.name] as IQorusFormField)
@@ -1891,7 +2562,9 @@ export const FormEngine = ({
           clusterLast={clusterLast}
         />
       );
-      if (compactNarrow) return names.map((entry) => renderRow(entry, false));
+      // (Clustering runs in narrow mode too now — the "One of the below is
+      // required" box wraps the members regardless of width; it no longer relies
+      // on a contiguous rail.)
       const emitted = new Set<string>();
       const groupOf = (name: string) =>
         (options?.[name]?.required_groups as string[] | undefined)?.[0];
@@ -1902,9 +2575,27 @@ export const FormEngine = ({
         const memberEntries = names.filter((e) => !e.hidden && groupOf(e.name) === grp);
         if (memberEntries.length < 2) return renderRow(entry, false);
         emitted.add(grp);
-        return memberEntries.map((e, idx) =>
+        const railed = memberEntries.map((e, idx) =>
           renderRow(e, true, idx === 0, idx === memberEntries.length - 1)
         );
+        // An UNMET one-of group gets the explicit "One of the below is required"
+        // box (the Focus cluster). A met group needs no banner — the rail + the
+        // "Covers"/"Covered by" chips already say which member satisfies it.
+        if (requiredGroupsInfo.satisfiedBy[grp]) return railed;
+        return (
+          <StyledRequiredClusterBox
+            key={grp}
+            className='options-readfirst-required-cluster'
+            $border={`${cWarning}33`}
+            $tint={`${cWarning}0d`}
+          >
+            <StyledRequiredClusterHeader $color={cWarning}>
+              <ReqoreIcon icon='LinkM' size='11px' style={{ color: cWarning }} />
+              One of the below is required
+            </StyledRequiredClusterHeader>
+            {railed}
+          </StyledRequiredClusterBox>
+        );
       });
     };
 
@@ -1922,19 +2613,37 @@ export const FormEngine = ({
               <StyledCompactWrap
                 ref={setCompactWrap}
                 className='options-readfirst-scroll'
-                $flush={compactFlush}
+                // A nested sub-form sits flush inside the parent's card — no outer
+                // gutter (the card already provides the breathing room).
+                $flush={compactFlush || compactNested}
               >
                 <StyledCompactPanel
-                  $headerBg={headerBg}
+                  // The top-level form scrolls, so its toolbar STICKS and carries a
+                  // dark blurred backdrop so content ghosts cleanly beneath it. A
+                  // nested (arg_schema) sub-form owns no scroll context — drop the
+                  // sticky, the backdrop, and the stacking context so its header is
+                  // transparent inside the parent's card.
+                  $headerBg={compactNested ? 'transparent' : headerBg}
+                  $nested={compactNested}
                   flat
-                  stickyHeader
-                  padded={false}
+                  raised
+                  minimal
+                  // No panel background: the form sits transparently on whatever
+                  // hosts it (page, drawer, or — for an arg_schema field — the
+                  // parent's edit card) instead of stacking its own dark surface.
+                  // The status boxes keep their own tints; the sticky toolbar keeps
+                  // its blurred header via the $headerBg override.
+                  stickyHeader={!compactNested}
+                  // Consumer overrides land last so they win over every default
+                  // above; `actions` and `contentStyle` below merge rather than
+                  // replace (see `compactPanelProps`).
+                  {...compactPanelProps}
                   actions={compactHeaderActions}
                   contentStyle={{
                     display: 'flex',
                     flexFlow: 'column',
                     gap: '10px',
-                    padding: '0 0 12px',
+                    ...compactPanelProps?.contentStyle,
                   }}
                 >
                   {size(groupKeys) === 0 ?
@@ -1943,78 +2652,61 @@ export const FormEngine = ({
                     </ReqoreMessage>
                   : null}
 
-                  {groupKeys.map((groupName) => {
-                    const names = grouped[groupName];
-                    const groupConfig = groups?.[groupName];
-                    const invalidCount = names.filter(
-                      (entry) =>
-                        !entry.hidden &&
-                        !isOptionValid(
-                          entry.name,
-                          (options?.[entry.name]?.ui_type as TQorusType) ||
-                            (options?.[entry.name]?.type as TQorusType),
-                          (shownOptions as TQorusForm)[entry.name]?.value
-                        )
-                    ).length;
-
+                  {STATUS_BOXES.map((box) => {
+                    const groupsInBox = bucketGroups[box.key];
+                    const count = bucketCount(box.key);
+                    if (!count) return null;
+                    const accent =
+                      box.key === 'attention' ? cWarning
+                      : box.key === 'set' ? cSuccess
+                      : cMuted;
+                    // The muted "Optional" box reads as a quieter, recessed
+                    // surface — a touch darker than the page rather than the
+                    // faint grey tint the accent would give.
+                    const boxBg =
+                      box.key === 'optional' ?
+                        changeDarkness(getMainBackgroundColor(theme), 0.06)
+                      : undefined;
                     return (
-                      <ReqorePanel
-                        key={groupName}
+                      <StyledStatusBox
+                        $accent={accent}
+                        $bg={boxBg}
+                        key={box.key}
                         flat
                         minimal
                         collapseButtonProps={{ flat: true, minimal: true, size: 'small' }}
                         collapsible
+                        // The Optional box now holds every not-yet-added field, so
+                        // it starts COLLAPSED to keep the form focused on what's in
+                        // use. But a SEARCH must surface matching addable fields —
+                        // and ReqorePanel unmounts collapsed content — so force it
+                        // open whenever a query is active. (isCollapsed is the
+                        // panel's controllable state; manual toggling still works
+                        // when no query is set.)
+                        isCollapsed={box.key === 'optional' && !query}
                         label={
                           <StyledGroupHeader>
-                            <ReqoreP effect={{ weight: 'bold' }} size='big'>
-                              {getOptionGroupLabel(groupName, groups)}
+                            <ReqoreP effect={{ weight: 'bold' }} size='normal'>
+                              {box.label}
                             </ReqoreP>
-                            <StyledGroupHeaderLine $color={cGroupLine} />
-                            <ReqoreButton
-                              readOnly
-                              size='tiny'
+                            <ReqoreTag
+                              size='small'
                               minimal
-                              flat
                               compact
-                              effect={{uppercase: true, spaced: 1}}
-                              {...(groupName === 'optional' ? { label: `${names.length} optional` }
-                              : invalidCount ?
-                                {
-                                  label: `${invalidCount} to resolve`,
-                                  intent: 'warning' as const,
-                                  icon: 'ErrorWarningLine' as const,
-                                }
-                              : {
-                                  label: 'All set',
-                                  intent: 'success' as const,
-                                  icon: 'CheckLine' as const,
-                                })}
+                              intent={box.intent}
+                              label={String(count)}
                             />
                           </StyledGroupHeader>
                         }
-                        icon={groupConfig?.icon}
+                        icon={box.icon}
                         className='options-readfirst-group'
                         padded={false}
                         contentStyle={{ padding: '4px 4px 6px' }}
                       >
-                        {groupConfig?.subtitle ?
-                          <ReqoreP
-                            size='small'
-                            effect={{ opacity: 0.6 }}
-                            // Indent to the same content line as the rows (StyledGroupBody's
-                            // `margin-left` clamp) so the subtitle sits tucked under the group
-                            // name instead of at the panel edge — and clears the group's
-                            // vertical rule (left:16px) rather than crossing it.
-                            style={{
-                              marginTop: 2,
-                              marginBottom: 8,
-                              marginLeft: GROUP_INDENT,
-                              paddingRight: 10,
-                            }}
-                          >
-                            {groupConfig.subtitle}
-                          </ReqoreP>
-                        : null}
+                        {/* ONE group body per box: every field block (and the
+                            thin schema sub-labels) is a direct flex child, so the
+                            inter-field gap is identical everywhere — including
+                            across schema-group boundaries. */}
                         <StyledGroupBody
                           $divider={cDivider}
                           $hover={cHover}
@@ -2024,9 +2716,35 @@ export const FormEngine = ({
                           $lineColor={cGroupLine}
                           className={compactNarrow ? 'readfirst-narrow' : undefined}
                         >
-                          {renderGroupRows(names)}
+                          {groupsInBox.map((groupName) => {
+                            const groupConfig = groups?.[groupName];
+                            return (
+                              <React.Fragment key={groupName}>
+                                {showGroupSubLabel(groupName) ?
+                                  <StyledStatusBoxGroupLabel>
+                                    {getOptionGroupLabel(groupName, groups)}
+                                  </StyledStatusBoxGroupLabel>
+                                : null}
+                                {showGroupSubLabel(groupName) && groupConfig?.subtitle ?
+                                  <ReqoreP
+                                    size='small'
+                                    effect={{ opacity: 0.6 }}
+                                    style={{
+                                      marginTop: 2,
+                                      marginBottom: 8,
+                                      marginLeft: GROUP_INDENT,
+                                      paddingRight: 10,
+                                    }}
+                                  >
+                                    {groupConfig.subtitle}
+                                  </ReqoreP>
+                                : null}
+                                {renderGroupRows(buckets[box.key][groupName])}
+                              </React.Fragment>
+                            );
+                          })}
                         </StyledGroupBody>
-                      </ReqorePanel>
+                      </StyledStatusBox>
                     );
                   })}
                 </StyledCompactPanel>
@@ -2294,13 +3012,11 @@ export const FormEngine = ({
                 // option's schema as context). The consumer (the IDE) injects
                 // it; same factory pattern as the ExpressionBuilder's
                 // `extraActions`.
-                ...(typeof optionActions === 'function' ?
-                  optionActions({
-                    name: optionName,
-                    schema: options[optionName],
-                    value: availableOptions?.[optionName] as TOption,
-                  })
-                : (optionActions ?? [])),
+                ...resolveOptionActions(optionActions, {
+                  name: optionName,
+                  schema: options[optionName],
+                  value: availableOptions?.[optionName] as TOption,
+                }),
                 {
                   size: 'tiny',
                   icon: 'FullscreenLine',