@qoretechnologies/reqraft 0.10.65 → 0.10.66-pr.137.ga1983bf

package/dist/components/form/engine/FormEngine.js

@@ -97,10 +97,14 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FormEngine = exports.getTypeAndCanBeNull = exports.flattenOptions = exports.shouldEmitLocalValue = exports.agreementFromRebuild = exports.isMirrorOfValue = exports.fixOptions = exports.OptionsContext = exports.hasRequiredOptions = exports.getOptionFieldStorageType = exports.fixOperatorValue = exports.getType = exports.inheritedScopeFor = void 0;
+exports.FormEngine = exports.getTypeAndCanBeNull = exports.flattenOptions = exports.shouldEmitLocalValue = exports.mergeOwnEdits = exports.takeHostsAttributes = exports.agreementFromRebuild = exports.isMirrorOfValue = exports.fixOptions = exports.OptionsContext = exports.hasRequiredOptions = exports.getOptionFieldStorageType = exports.fixOperatorValue = exports.getType = exports.inheritedScopeFor = void 0;
 var react_1 = require("react");
 var jsx_runtime_1 = require("react/jsx-runtime");
 var reqore_1 = require("@qoretechnologies/reqore");
+var readFirstColors_1 = require("./readFirstColors");
+var operatorSummary_1 = require("./operatorSummary");
+var inheritProps_1 = require("./inheritProps");
+var readableColors_1 = require("../../../helpers/readableColors");
 var colors_1 = require("@qoretechnologies/reqore/dist/helpers/colors");
 var argumentPresence_1 = require("../expressions/argumentPresence");
 var typeChoices_1 = require("./typeChoices");
@@ -118,6 +122,7 @@ var styled_components_1 = __importStar(require("styled-components"));
 var common_1 = require("../../../helpers/common");
 var options_1 = require("../../../helpers/options");
 var validations_1 = require("../../../helpers/validations");
+var useCoarsePointer_1 = require("../../../hooks/useCoarsePointer");
 var useQorusTypes_1 = require("../../../hooks/useQorusTypes");
 var useTemplates_1 = require("../../../hooks/useTemplates");
 var fetch_1 = require("../../../utils/fetch");
@@ -132,50 +137,18 @@ var compactRowContext_1 = require("./compactRowContext");
 var compactRowStyles_1 = require("./compactRowStyles");
 var CompactToolbar_1 = require("./CompactToolbar");
 var compactToolbarContext_1 = require("./compactToolbarContext");
+var HiddenFieldsNote_1 = require("./HiddenFieldsNote");
 var OptionFieldMessages_1 = require("./OptionFieldMessages");
 var optionsContext_1 = require("./optionsContext");
 var markdownRendererContext_1 = require("../../Description/markdownRendererContext");
 var OptionsHelpDialog_1 = require("./OptionsHelpDialog");
+var typeSentenceForm_1 = require("../typeSentenceForm");
+var referenceNames_1 = require("../fields/template/referenceNames");
+var qorusTypeCatalogue_1 = require("../../../helpers/qorusTypeCatalogue");
+var allowedValues_1 = require("../../../helpers/allowedValues");
+var rowFocus_1 = require("./rowFocus");
 var optionUiTypes_1 = require("../../../helpers/optionUiTypes");
 var readFirst_1 = require("./readFirst");
-/**
- * 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`).
- */
-var resolveInheritProps = function (inheritProps, availableOptions, inheritedFromParent) {
-    var _a;
-    if (!inheritProps)
-        return {};
-    var out = {};
-    for (var propName in inheritProps) {
-        var siblingName = inheritProps[propName];
-        var localValue = (_a = availableOptions === null || availableOptions === void 0 ? void 0 : availableOptions[siblingName]) === null || _a === void 0 ? void 0 : _a.value;
-        out[propName] = localValue !== undefined ? localValue : inheritedFromParent === null || inheritedFromParent === void 0 ? void 0 : inheritedFromParent[siblingName];
-    }
-    return out;
-};
 /** One shared "nothing came down from above" bag. See `inheritedScopeFor`. */
 var NO_INHERITED_SCOPE = Object.freeze({});
 /**
@@ -206,7 +179,7 @@ var NO_INHERITED_SCOPE = Object.freeze({});
  * @param inheritedFromParent the bag threaded in from an outer form
  */
 var inheritedScopeFor = function (inheritProps, availableOptions, inheritedFromParent) {
-    var resolved = resolveInheritProps(inheritProps, availableOptions, inheritedFromParent);
+    var resolved = (0, inheritProps_1.resolveInheritProps)(inheritProps, availableOptions, inheritedFromParent);
     if (!Object.keys(resolved).length) {
         return inheritedFromParent !== null && inheritedFromParent !== void 0 ? inheritedFromParent : NO_INHERITED_SCOPE;
     }
@@ -228,7 +201,7 @@ var PositiveColorEffect = {
     glow: 'success',
 };
 // Compact (read-first) layout: flat label | value | action rows in collapsible
-// group panels; colours come in as props so the layout follows the Reqore theme.
+// group panels; colors come in as props so the layout follows the Reqore theme.
 var StyledCompactWrap = styled_components_1.default.div(templateObject_3 || (templateObject_3 = __makeTemplateObject(["\n  display: flex;\n  flex-flow: column;\n  gap: 10px;\n  width: 100%;\n  /* Allow the wrap to shrink inside flex/grid parents so its rows' ellipsis can\n     engage instead of overflowing the container horizontally. */\n  min-width: 0;\n  max-width: 100%;\n\n  /* Scroll ownership \u2014 see `compactScroll`.\n\n     'host' (the default): the page or panel around us already scrolls, so we\n     must not cap our height and scroll our own body, or the reader gets two\n     scrollbars in two styles and cannot tell which moves what.\n\n     `overflow-x: clip`, NOT `hidden`: CSS coerces an `overflow-y: visible`\n     to `auto` whenever the other axis is neither visible nor clip, which would\n     leave this box a scroll container \u2014 the element stops scrolling only\n     because `max-height: none` means nothing overflows, while `position:\n     sticky` inside it still resolves against US instead of the host, so the\n     toolbar silently stops pinning. `clip` keeps the horizontal guard without\n     that coercion. */\n  ", "\n\n  /* Option logos (e.g. language images) render as <img> inside ReqoreIcon's\n     square box; constrain them so portrait PNGs don't overflow the row. */\n  .reqore-icon img {\n    width: 100%;\n    height: 100%;\n    object-fit: contain;\n  }\n"], ["\n  display: flex;\n  flex-flow: column;\n  gap: 10px;\n  width: 100%;\n  /* Allow the wrap to shrink inside flex/grid parents so its rows' ellipsis can\n     engage instead of overflowing the container horizontally. */\n  min-width: 0;\n  max-width: 100%;\n\n  /* Scroll ownership \u2014 see \\`compactScroll\\`.\n\n     'host' (the default): the page or panel around us already scrolls, so we\n     must not cap our height and scroll our own body, or the reader gets two\n     scrollbars in two styles and cannot tell which moves what.\n\n     \\`overflow-x: clip\\`, NOT \\`hidden\\`: CSS coerces an \\`overflow-y: visible\\`\n     to \\`auto\\` whenever the other axis is neither visible nor clip, which would\n     leave this box a scroll container \u2014 the element stops scrolling only\n     because \\`max-height: none\\` means nothing overflows, while \\`position:\n     sticky\\` inside it still resolves against US instead of the host, so the\n     toolbar silently stops pinning. \\`clip\\` keeps the horizontal guard without\n     that coercion. */\n  ", "\n\n  /* Option logos (e.g. language images) render as <img> inside ReqoreIcon's\n     square box; constrain them so portrait PNGs don't overflow the row. */\n  .reqore-icon img {\n    width: 100%;\n    height: 100%;\n    object-fit: contain;\n  }\n"])), function (_a) {
     var $ownScroll = _a.$ownScroll;
     return $ownScroll ? (0, styled_components_1.css)(templateObject_1 || (templateObject_1 = __makeTemplateObject(["\n        /* 'own': we are the scroller. The sticky toolbar pins to whatever\n             scrolls, so a host whose scrollport carries top padding would\n             resolve sticky `top: 0` against its padding box and leave an\n             unblurred strip above the toolbar. Scrolling in this unpadded box\n             pins it flush. Cap at the host's available height, but do not grow\n             to fill it \u2014 short forms still hug their content.\n\n             `min-height: 0` is what lets a flex item shrink below its content\n             so there is something to scroll; it belongs to this branch only. */\n        min-height: 0;\n        max-height: 100%;\n        overflow-y: auto;\n        overflow-x: hidden;\n      "], ["\n        /* 'own': we are the scroller. The sticky toolbar pins to whatever\n             scrolls, so a host whose scrollport carries top padding would\n             resolve sticky \\`top: 0\\` against its padding box and leave an\n             unblurred strip above the toolbar. Scrolling in this unpadded box\n             pins it flush. Cap at the host's available height, but do not grow\n             to fill it \u2014 short forms still hug their content.\n\n             \\`min-height: 0\\` is what lets a flex item shrink below its content\n             so there is something to scroll; it belongs to this branch only. */\n        min-height: 0;\n        max-height: 100%;\n        overflow-y: auto;\n        overflow-x: hidden;\n      "]))) : (0, styled_components_1.css)(templateObject_2 || (templateObject_2 = __makeTemplateObject(["\n        /* `min-height: auto` is load-bearing, not a default: inside a column\n             flex parent the shrink allowance above collapses this box to zero\n             height while its rows paint outside it, so the form looks right but\n             contributes nothing to layout \u2014 the host cannot size or scroll to\n             it and anything below it stacks against nothing. */\n        min-height: auto;\n        max-height: none;\n        overflow-y: visible;\n        overflow-x: clip;\n      "], ["\n        /* \\`min-height: auto\\` is load-bearing, not a default: inside a column\n             flex parent the shrink allowance above collapses this box to zero\n             height while its rows paint outside it, so the form looks right but\n             contributes nothing to layout \u2014 the host cannot size or scroll to\n             it and anything below it stacks against nothing. */\n        min-height: auto;\n        max-height: none;\n        overflow-y: visible;\n        overflow-x: clip;\n      "])));
@@ -431,6 +404,34 @@ var normalizeEmptyFieldValues = function (fields) {
         return acc;
     }, {});
 };
+/**
+ * The value as a host can hand it back: each field as its value, and the fields that hold nothing left out.
+ *
+ * A report of the form's is recognised by what it says, not by how the host writes it back. A host that
+ * stores only the fields holding a value (the Qorus IDE's editors) hands a report back without its empty
+ * fields; one that stores a field under its own type (the IDE stores what an `int` field reported as a
+ * `string`) hands it back with that type. Compared field for field, type and all, the report never came
+ * back as itself:
+ * - the form took it for the host's own change and went back to it, losing what had been typed since, and
+ *   the two chased each other's reports on every echo;
+ * - an edit back to a value reported before (A, then B, then A again), made as the echo of B arrived, was
+ *   held back as made before the host's change, and the field went back to B (qorus#646: a template
+ *   field's text, deleted back to its reference, kept the text in the IDE).
+ *
+ * For recognising a value only. Whether a rebuild adds anything is still read with the empty fields in
+ * (`isMirrorOfValue`): a new schema's empty required field is a row the form has to add.
+ */
+var reportedValues = function (fields) {
+    return (0, reduce_1.default)(fields || {}, function (acc, field, name) {
+        var fieldValue = comparableField(field);
+        if (fieldValue !== undefined) {
+            acc[name] = fieldValue;
+        }
+        return acc;
+    }, {});
+};
+/** The same value, as a report coming back from a host is recognised. */
+var sameReportedValue = function (a, b) { return (0, lodash_1.isEqual)(reportedValues(a), reportedValues(b)); };
 /**
  * Does this rebuild say anything the parent does not already hold?
  *
@@ -460,6 +461,118 @@ var agreementFromRebuild = function (fixedValue, value) {
     return (0, exports.isMirrorOfValue)(fixedValue, value) ? fixedValue : undefined;
 };
 exports.agreementFromRebuild = agreementFromRebuild;
+/**
+ * A field as the form compares one host value with another: an empty field ('' or none, whatever its type) is
+ * the same as no field, and a field is its value, however it is written (`{ type, value }` or the bare value).
+ */
+var comparableField = function (field) {
+    var fieldValue = field !== null && typeof field === 'object' && !Array.isArray(field) && 'value' in field ?
+        field.value
+        : field !== null && typeof field === 'object' && !Array.isArray(field) && 'type' in field ?
+            undefined
+            : field;
+    return fieldValue === '' ? undefined : fieldValue;
+};
+var sameField = function (a, b) {
+    return (0, lodash_1.isEqual)(comparableField(a), comparableField(b));
+};
+/** A field written as `{ type, value }`, not a bare value. */
+var isTypedField = function (field) {
+    return field !== null &&
+        typeof field === 'object' &&
+        !Array.isArray(field) &&
+        typeof field.type === 'string';
+};
+/**
+ * The form's copy of a field, with everything the host changed beside its value since `base`: its type, whether
+ * it is an expression, its operator, or anything else it says. `own` itself where the host changed nothing.
+ *
+ * A report of the form's is recognised by its values, and a field's value is merged by its value (see
+ * `reportedValues`, `mergeOwnEdits`), so a change the host made to a field's type alone said nothing: the form
+ * kept its own type. The Qorus IDE makes an added field's whole number true or false, holding the same field
+ * `pos`; the form kept the `int` and drew `pos` as text on the Value tab, where a true or false field shows it on
+ * its Expression tab (qorus#646).
+ *
+ * Every key but `value` is compared, not a list of the ones known today: whatever a host writes into a field
+ * beside its value, a change of it is the host's. A key the host writes as it always has is not a change, so a
+ * host that stores a field under its own type does not change the form's (that is why the value alone is what
+ * recognises a report).
+ */
+var withHostsAttributes = function (own, host, base) {
+    if (!isTypedField(own) || !isTypedField(host)) {
+        return own;
+    }
+    var hostField = host;
+    var baseField = isTypedField(base) ? base : {};
+    var ownField = own;
+    var taken;
+    new Set(__spreadArray(__spreadArray([], Object.keys(hostField), true), Object.keys(baseField), true)).forEach(function (key) {
+        var hosts = hostField[key];
+        if (key === 'value' || (0, lodash_1.isEqual)(hosts, baseField[key]) || (0, lodash_1.isEqual)(ownField[key], hosts)) {
+            return;
+        }
+        taken = taken !== null && taken !== void 0 ? taken : __assign({}, ownField);
+        if (hosts === undefined) {
+            delete taken[key];
+        }
+        else {
+            taken[key] = hosts;
+        }
+    });
+    return taken !== null && taken !== void 0 ? taken : own;
+};
+/**
+ * The form's copy with what the host changed beside each field's value since `base` taken (see
+ * `withHostsAttributes`). Returns `ours` itself when there is nothing the form's copy does not have already.
+ */
+var takeHostsAttributes = function (theirs, ours, base) {
+    var _a;
+    var typed;
+    (0, lodash_1.forEach)(theirs || {}, function (host, name) {
+        var own = ours === null || ours === void 0 ? void 0 : ours[name];
+        var taken = withHostsAttributes(own, host, base === null || base === void 0 ? void 0 : base[name]);
+        if (taken !== own) {
+            typed = typed !== null && typed !== void 0 ? typed : __assign({}, (ours || {}));
+            typed[name] = taken;
+        }
+    });
+    return (_a = typed) !== null && _a !== void 0 ? _a : ours;
+};
+exports.takeHostsAttributes = takeHostsAttributes;
+/**
+ * The host's change, with the form's own edits kept: a three-way merge of `theirs` (the `value` the host
+ * hands down now) and `ours` (the form's copy) against `base` (the `value` the form last saw).
+ *
+ * A field the form changed and the host did not keeps the form's value; every other field takes the host's,
+ * a field both changed included. The host and the form can change the value in the same commit - a host
+ * renaming something as the user's edit reaches the form - and taking either side whole lost the other's
+ * change; sending the form's copy over the host's change made the two trade places forever (qorus#646).
+ *
+ * Returns `theirs` itself when the form has nothing of its own to keep.
+ */
+var mergeOwnEdits = function (theirs, ours, base) {
+    var _a;
+    var merged;
+    var names = new Set(__spreadArray(__spreadArray([], Object.keys(ours || {}), true), Object.keys(base || {}), true));
+    names.forEach(function (name) {
+        var own = ours === null || ours === void 0 ? void 0 : ours[name];
+        var before = base === null || base === void 0 ? void 0 : base[name];
+        var host = theirs === null || theirs === void 0 ? void 0 : theirs[name];
+        if (sameField(own, before) || !sameField(host, before) || sameField(host, own)) {
+            return;
+        }
+        merged = merged !== null && merged !== void 0 ? merged : __assign({}, (theirs || {}));
+        if (own === undefined) {
+            delete merged[name];
+        }
+        else {
+            // the form's value, with what the host changed beside it (its type, say)
+            merged[name] = withHostsAttributes(own, host, before);
+        }
+    });
+    return (_a = merged) !== null && _a !== void 0 ? _a : theirs;
+};
+exports.mergeOwnEdits = mergeOwnEdits;
 /**
  * Should the form report `localValue` to its parent as an answer?
  *
@@ -516,6 +629,8 @@ var getTypeAndCanBeNull = function (type, allowed_values, operatorData, operator
 exports.getTypeAndCanBeNull = getTypeAndCanBeNull;
 // Option types rendered full-width (IDE Options parity, commit 8e6b7781).
 var STRECHABLE_TYPES = new Set(['tool-catalog']);
+/** How faded reqore draws a panel's title icon. */
+var PANEL_TITLE_ICON_ALPHA = 0.7;
 var FormEngineImpl = function (_a) {
     var _b, _c, _d, _f, _g;
     var name = _a.name, uniqueName = _a.uniqueName, value = _a.value, onChange = _a.onChange, onSingleOptionsChange = _a.onSingleOptionsChange, onDependableOptionChange = _a.onDependableOptionChange, placeholder = _a.placeholder, noValueString = _a.noValueString, // eslint-disable-line @typescript-eslint/no-unused-vars
@@ -534,12 +649,14 @@ var FormEngineImpl = function (_a) {
     // been a no-op. Removing it from the API is a separate, breaking change —
     // every consumer passing it today already gets the flush layout by default.
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
-    compactFlush = _k === void 0 ? false : _k, _l = _a.compactNested, compactNested = _l === void 0 ? false : _l, _m = _a.compactScroll, compactScroll = _m === void 0 ? 'host' : _m, compactPanelProps = _a.compactPanelProps, compactCollapsedGroupsProp = _a.compactCollapsedGroups, compactBoxLabels = _a.compactBoxLabels, _o = _a.compactStickyBoxHeaders, compactStickyBoxHeaders = _o === void 0 ? true : _o, _p = _a.compactStickyOffset, compactStickyOffset = _p === void 0 ? 0 : _p, _q = _a.compactToolbar, compactToolbar = _q === void 0 ? true : _q, _r = _a.commitMode, commitMode = _r === void 0 ? 'immediate' : _r, _s = _a.expandMode, expandMode = _s === void 0 ? 'single' : _s, onCommit = _a.onCommit, operatorsProp = _a.operators, groups = _a.groups, optionsLoader = _a.optionsLoader, onValidityChange = _a.onValidityChange, optionActions = _a.optionActions, _t = _a.optionActionsCollapse, optionActionsCollapse = _t === void 0 ? 'auto' : _t, componentOverrides = _a.componentOverrides, codePreviewRenderer = _a.codePreviewRenderer, 
+    compactFlush = _k === void 0 ? false : _k, _l = _a.compactNested, compactNested = _l === void 0 ? false : _l, _m = _a.compactScroll, compactScroll = _m === void 0 ? 'host' : _m, compactPanelProps = _a.compactPanelProps, compactCollapsedGroupsProp = _a.compactCollapsedGroups, compactBoxLabels = _a.compactBoxLabels, _o = _a.compactStickyBoxHeaders, compactStickyBoxHeaders = _o === void 0 ? true : _o, _p = _a.compactStickyOffset, compactStickyOffset = _p === void 0 ? 0 : _p, _q = _a.compactToolbar, compactToolbar = _q === void 0 ? true : _q, _r = _a.commitMode, commitMode = _r === void 0 ? 'immediate' : _r, _s = _a.expandMode, expandMode = _s === void 0 ? 'single' : _s, onCommit = _a.onCommit, operatorsProp = _a.operators, groups = _a.groups, optionsLoader = _a.optionsLoader, onValidityChange = _a.onValidityChange, optionActions = _a.optionActions, _t = _a.optionActionsCollapse, optionActionsCollapse = _t === void 0 ? 'auto' : _t, componentOverrides = _a.componentOverrides, codePreviewRenderer = _a.codePreviewRenderer, readSummaries = _a.readSummaries, cardEditorTypes = _a.cardEditorTypes, 
     // consumed by the wrapper below, which publishes it to every description this
     // form draws; destructured here only so it cannot reach `rest` and be spread
     // onto a DOM node
     _markdownRenderer = _a.markdownRenderer, // eslint-disable-line @typescript-eslint/no-unused-vars
-    rendererOnlyUiTypes = _a.rendererOnlyUiTypes, templateAwareUiTypes = _a.templateAwareUiTypes, anyLikeUiTypes = _a.anyLikeUiTypes, inheritedFromParent = _a.inheritedFromParent, autoFocusFirstRequired = _a.autoFocusFirstRequired, expandFirstRequired = _a.expandFirstRequired, initialExpandedOptions = _a.initialExpandedOptions, maxFieldsShown = _a.maxFieldsShown, rest = __rest(_a, ["name", "uniqueName", "value", "onChange", "onSingleOptionsChange", "onDependableOptionChange", "placeholder", "noValueString", "isValid", "url", "customUrl", "operatorsUrl", "onOptionsLoaded", "recordRequiresSearchOptions", "readOnly", "onReadOnlyActivate", "allowTemplates", "interfaceContext", "templateFieldProps", "forceDropdown", "showTypeToggle", "compact", "compactFlush", "compactNested", "compactScroll", "compactPanelProps", "compactCollapsedGroups", "compactBoxLabels", "compactStickyBoxHeaders", "compactStickyOffset", "compactToolbar", "commitMode", "expandMode", "onCommit", "operators", "groups", "optionsLoader", "onValidityChange", "optionActions", "optionActionsCollapse", "componentOverrides", "codePreviewRenderer", "markdownRenderer", "rendererOnlyUiTypes", "templateAwareUiTypes", "anyLikeUiTypes", "inheritedFromParent", "autoFocusFirstRequired", "expandFirstRequired", "initialExpandedOptions", "maxFieldsShown"]);
+    rendererOnlyUiTypes = _a.rendererOnlyUiTypes, templateAwareUiTypes = _a.templateAwareUiTypes, anyLikeUiTypes = _a.anyLikeUiTypes, inheritedFromParent = _a.inheritedFromParent, autoFocusFirstRequired = _a.autoFocusFirstRequired, expandFirstRequired = _a.expandFirstRequired, initialExpandedOptions = _a.initialExpandedOptions, valueKey = _a.valueKey, maxFieldsShown = _a.maxFieldsShown, 
+    // The form's own props, read here and never handed on to the collection drawn below (`{...rest}`).
+    optionsSchema = _a.options, stringTemplates = _a.stringTemplates, skeletonReason = _a.skeletonReason, rest = __rest(_a, ["name", "uniqueName", "value", "onChange", "onSingleOptionsChange", "onDependableOptionChange", "placeholder", "noValueString", "isValid", "url", "customUrl", "operatorsUrl", "onOptionsLoaded", "recordRequiresSearchOptions", "readOnly", "onReadOnlyActivate", "allowTemplates", "interfaceContext", "templateFieldProps", "forceDropdown", "showTypeToggle", "compact", "compactFlush", "compactNested", "compactScroll", "compactPanelProps", "compactCollapsedGroups", "compactBoxLabels", "compactStickyBoxHeaders", "compactStickyOffset", "compactToolbar", "commitMode", "expandMode", "onCommit", "operators", "groups", "optionsLoader", "onValidityChange", "optionActions", "optionActionsCollapse", "componentOverrides", "codePreviewRenderer", "readSummaries", "cardEditorTypes", "markdownRenderer", "rendererOnlyUiTypes", "templateAwareUiTypes", "anyLikeUiTypes", "inheritedFromParent", "autoFocusFirstRequired", "expandFirstRequired", "initialExpandedOptions", "valueKey", "maxFieldsShown", "options", "stringTemplates", "skeletonReason"]);
     // Built-ins + whatever the consumer declared for its own injected editors.
     var isRendererOnly = (0, react_2.useMemo)(function () { return (0, rendererTypes_1.createRendererOnlyUiTypeCheck)(rendererOnlyUiTypes); }, [JSON.stringify(rendererOnlyUiTypes)]);
     // Pointer CAPABILITY and viewport WIDTH are different questions and both
@@ -564,10 +681,22 @@ var FormEngineImpl = function (_a) {
        enters the component, so the header, the chips, the messages, the meter and
        the read-first summary cannot disagree about it: every one of them reads
        `options`, and none of them has to know the rule. */
-    var _u = (0, react_2.useState)((rest === null || rest === void 0 ? void 0 : rest.options) || undefined), servedOptions = _u[0], setOptions = _u[1];
+    var _u = (0, react_2.useState)(optionsSchema || undefined), servedOptions = _u[0], setOptions = _u[1];
     var options = (0, react_2.useMemo)(function () { return (0, options_1.resolveDegenerateRequiredGroups)(servedOptions); }, [servedOptions]);
+    /* Whether the schema the form holds is the one in force: its host is not waiting behind the skeleton, and a
+       schema the host hands down has been taken in (`servedOptions` follows the `options` prop a render later).
+       Until then the value is neither pruned against the schema nor emitted. A host loading the schema hands an
+       empty or an earlier one meanwhile; read against that, every stored field was "not on this instance" and
+       was removed, so a Qog state opened before its options had loaded showed them empty and, once emitted,
+       lost them (qorus#646). */
+    var hostSchemaPending = !optionsLoader &&
+        !url &&
+        !customUrl &&
+        optionsSchema !== servedOptions &&
+        JSON.stringify(optionsSchema || undefined) !== JSON.stringify(servedOptions);
+    var schemaInForce = !rest.skeleton && !hostSchemaPending;
     // optionsLoader lifecycle: loading feeds the skeleton gate, error the banner.
-    var _v = (0, react_2.useState)(!!optionsLoader && !(rest === null || rest === void 0 ? void 0 : rest.options)), optionsLoading = _v[0], setOptionsLoading = _v[1];
+    var _v = (0, react_2.useState)(!!optionsLoader && !optionsSchema), optionsLoading = _v[0], setOptionsLoading = _v[1];
     var _w = (0, react_2.useState)(), optionsError = _w[0], setOptionsError = _w[1];
     // Operators: prop-provided (compact) or fetched via operatorsUrl (dpql,
     // ported from IDE Options) — the fetch overrides the seeded prop value.
@@ -657,7 +786,13 @@ var FormEngineImpl = function (_a) {
        measurement below takes it as a dependency, and a dependency array is
        evaluated during render — a `const` declared further down would still be
        in its temporal dead zone. */
-    var compactNarrow = !!compactWrapWidth && compactWrapWidth < 480;
+    /* The label column the rows are laid out with: measured from the labels (see below), the
+       default until it is. A form stacks its rows where its value column would be too narrow
+       beside it (`isCompactNarrow`), not at one form width whatever its labels are. */
+    var _9 = (0, react_2.useState)(compactRowStyles_1.COMPACT_LABEL_COL), compactLabelColumn = _9[0], setCompactLabelColumn = _9[1];
+    // the label column holds a finger's help button where the pointer is a finger (`labelAffordanceWidth`)
+    var coarsePointer = (0, useCoarsePointer_1.useCoarsePointer)();
+    var compactNarrow = !!compactWrapWidth && (0, compactRowStyles_1.isCompactNarrow)(compactWrapWidth, compactLabelColumn);
     /* How much pinned chrome sits above a status-box header.
     
        Sticky offsets do not compose on their own: everything pinned in one
@@ -672,7 +807,7 @@ var FormEngineImpl = function (_a) {
        a search row and a field picker that each hide themselves when they have
        nothing to say, and what is left wraps differently at every form width.
        Zero when this form draws no toolbar at all. */
-    var _9 = (0, react_2.useState)(0), compactToolbarHeight = _9[0], setCompactToolbarHeight = _9[1];
+    var _10 = (0, react_2.useState)(0), compactToolbarHeight = _10[0], setCompactToolbarHeight = _10[1];
     (0, react_2.useLayoutEffect)(function () {
         var wrap = compactWrapNode;
         if (!compact || !wrap || compactNested || !compactStickyBoxHeaders) {
@@ -749,16 +884,19 @@ var FormEngineImpl = function (_a) {
         // survives at every label length. MAX still bounds how much room the NAME may
         // take, which is what it is for; the asterisk and the `?` are chrome that has
         // to fit beside it either way.
-        var text = Math.max(compactRowStyles_1.LABEL_COL_MIN, Math.min(compactRowStyles_1.LABEL_COL_MAX, Math.round(widest)));
-        wrap.style.setProperty(compactRowStyles_1.LABEL_COL_VAR, "".concat(text + compactRowStyles_1.LABEL_AFFORDANCE_WIDTH, "px"));
-    }, [compact, options, theme, compactWrapNode]);
+        var text = Math.min(compactRowStyles_1.LABEL_COL_MAX, Math.round(widest));
+        // a finger's help button is wider than a mouse's (`labelAffordanceWidth`); a short name's column is the floor
+        var column = Math.max(compactRowStyles_1.LABEL_COLUMN_MIN, text + (0, compactRowStyles_1.labelAffordanceWidth)(coarsePointer));
+        wrap.style.setProperty(compactRowStyles_1.LABEL_COL_VAR, "".concat(column, "px"));
+        setCompactLabelColumn(column);
+    }, [compact, options, theme, compactWrapNode, coarsePointer]);
     // Editing rows pin min-height to the measured read row they replace, so the
     // toggle never shifts neighbours (height varies with chrome — measure it).
     var readRowHeights = (0, react_2.useRef)({});
     // Required-groups linkage: hovering a group chip highlights every member row;
     // clicking a sibling in the chip's popover scrolls to it and flashes it.
-    var _10 = (0, react_2.useState)([]), highlightedOptions = _10[0], setHighlightedOptions = _10[1];
-    var _11 = (0, react_2.useState)([]), flashedOptions = _11[0], setFlashedOptions = _11[1];
+    var _11 = (0, react_2.useState)([]), highlightedOptions = _11[0], setHighlightedOptions = _11[1];
+    var _12 = (0, react_2.useState)([]), flashedOptions = _12[0], setFlashedOptions = _12[1];
     var flashTimeout = (0, react_2.useRef)();
     var flashOptions = (0, react_2.useCallback)(function (optionNames, scrollToFirst) {
         if (scrollToFirst === void 0) { scrollToFirst = false; }
@@ -810,16 +948,16 @@ var FormEngineImpl = function (_a) {
         }
     });
     // Info panels auto-open on Tier-1 content; the per-row user override sticks.
-    var _12 = (0, react_2.useState)({}), infoPanelOverrides = _12[0], setInfoPanelOverrides = _12[1];
+    var _13 = (0, react_2.useState)({}), infoPanelOverrides = _13[0], setInfoPanelOverrides = _13[1];
     // Toolbar filters affect the listed rows only — the meter reflects the full set.
-    var _13 = (0, react_2.useState)(false), requiredOnly = _13[0], setRequiredOnly = _13[1];
-    var _14 = (0, react_2.useState)(''), compactQuery = _14[0], setCompactQuery = _14[1];
+    var _14 = (0, react_2.useState)(false), requiredOnly = _14[0], setRequiredOnly = _14[1];
+    var _15 = (0, react_2.useState)(''), compactQuery = _15[0], setCompactQuery = _15[1];
     // Compact field sort (Fields menu → "Sort by"); 'schema' = declared order.
-    var _15 = (0, react_2.useState)('schema'), compactSort = _15[0], setCompactSort = _15[1];
-    var _16 = (0, react_2.useState)(function () { return ({
+    var _16 = (0, react_2.useState)('schema'), compactSort = _16[0], setCompactSort = _16[1];
+    var _17 = (0, react_2.useState)(function () { return ({
         fields: (0, exports.fixOptions)(value, options || {}, undefined, isRendererOnly),
         meta: undefined,
-    }); }), localValue = _16[0], setLocalValue = _16[1];
+    }); }), localValue = _17[0], setLocalValue = _17[1];
     var originalValue = (0, react_2.useRef)();
     // Track the last value we emitted via onChange so we can skip re-applying fixOptions
     // when the parent echoes it back as the new value prop (controlled component loop prevention)
@@ -857,16 +995,52 @@ var FormEngineImpl = function (_a) {
      * reset the form to it: the field under the cursor went back a step and the keys typed since were lost
      * ("I have value" came out as "I he value" in a story under load).
      */
-    var inFlight = (0, emittedValues_1.useEmittedValues)(function (a, b) {
-        return (0, lodash_1.isEqual)(normalizeEmptyFieldValues(a), normalizeEmptyFieldValues(b));
-    });
+    var inFlight = (0, emittedValues_1.useEmittedValues)(sameReportedValue);
+    /**
+     * The `value` (and `valueKey`) as of the last commit: what a new `value` is a change from. The sync-down
+     * merges the host's change against it, and the emit effect tells by it that the host changed the value in
+     * the very commit it runs in. Updated by the last effect of each commit (below the sync-down).
+     */
+    var seenValue = (0, react_2.useRef)(value);
+    var seenValueKey = (0, react_2.useRef)(valueKey);
+    /** Whether `value` is the host's own change, made since the last commit: neither seen before nor a report of
+     *  this form's coming back. */
+    var isHostsOwnChange = function () {
+        return valueKey !== seenValueKey.current ||
+            (!sameReportedValue(value, seenValue.current) &&
+                !inFlight.includes(value) &&
+                !sameReportedValue(value, lastEmittedValue.current));
+    };
     if (originalValue.current === undefined && (0, size_1.default)(value)) {
         originalValue.current = localValue.fields;
     }
     var unavailableOptionsCount = (0, react_2.useRef)(0);
-    var _17 = (0, useQorusTypes_1.useQorusTypes)(), compactValue = _17.compactValue, typesLoading = _17.loading;
-    var templates = (0, useTemplates_1.useTemplates)(allowTemplates, rest.stringTemplates, interfaceContext);
+    var _18 = (0, useQorusTypes_1.useQorusTypes)(), compactValue = _18.compactValue, typesLoading = _18.loading;
+    // an option's type in words, while the form shows field types (qorus#646: it said the type's code, `<string>`)
+    var typeName = (0, typeSentenceForm_1.useTypeName)();
+    var templates = (0, useTemplates_1.useTemplates)(allowTemplates, stringTemplates, interfaceContext);
     (0, react_2.useEffect)(function () {
+        /* Nothing is emitted until the schema is in force (`schemaInForce`): read against the empty or earlier
+           schema a host hands down while it loads its own, the value is no answer, and emitted it wiped a Qog
+           state's stored options the moment the state was opened (qorus#646).
+    
+           When it comes into force this check runs (it is a dependency). A host also shows the skeleton for other
+           waits: qorus-ide shows it while the templates load, with the schema already there. The form completes the
+           value meanwhile (a required field's default, e.g. the server's `created_by_user`), and nothing read it
+           again when the skeleton cleared: the default was shown and never emitted, so never saved. A value that
+           adds nothing still emits nothing. */
+        if (!schemaInForce) {
+            return;
+        }
+        /* The host changed the value in this same commit (effects run in order, and this one runs before the
+           sync-down that takes the change in). The form's copy was made before that change: sent, it overwrote
+           the host's change, the sync-down then took the host's value in, and the next commit sent that back -
+           the form and the host traded places on every commit, forever (qorus#646: the Qorus IDE's OPC UA node
+           editor, its namespace flipping between the old and the renamed one). The sync-down below merges the
+           change with the form's own edits, and the next commit reports the result. */
+        if (isHostsOwnChange()) {
+            return;
+        }
         if (!(0, exports.shouldEmitLocalValue)({
             localValue: localValue.fields,
             value: value,
@@ -881,15 +1055,15 @@ var FormEngineImpl = function (_a) {
         // Batched mode still emits every staged change (consumers may want to
         // live-validate), but flags it as a draft — persistence waits for Save.
         onChange === null || onChange === void 0 ? void 0 : onChange(name, toEmit, commitMode === 'batched' ? __assign(__assign({}, (meta || {})), { draft: true }) : meta);
-    }, [JSON.stringify(localValue)]);
+    }, [JSON.stringify(localValue), schemaInForce]);
     (0, react_use_1.useUpdateEffect)(function () {
         // When a loader owns the schema, ignore controlled `options` syncs so a
         // late/undefined `options` prop can't clobber the loaded schema.
         if (optionsLoader) {
             return;
         }
-        setOptions(rest.options);
-    }, [JSON.stringify(rest.options)]);
+        setOptions(optionsSchema);
+    }, [JSON.stringify(optionsSchema)]);
     // Fetch the schema on mount and on loader identity change.
     (0, react_2.useEffect)(function () {
         if (!optionsLoader) {
@@ -1076,14 +1250,32 @@ var FormEngineImpl = function (_a) {
         // change and re-fixes forever (e.g. byte-size / expression / ruled string fields).
         // Note: compare fixedValue against value, not localValue.fields — localValue may have been
         // updated by nested FormEngine emissions, so comparing against it would never skip.
-        var normalizedValue = normalizeEmptyFieldValues(value);
         /* What this rebuild lets us agree with the parent on — `undefined` when it
            contributed something the parent has yet to learn. */
         var agreed = (0, exports.agreementFromRebuild)(fixedValue, value);
+        // a different record: nothing of the previous one is carried into it (see `valueKey`)
+        var sameRecord = valueKey === seenValueKey.current;
         // the echo of an emit still in flight - the last or an older one - is not the parent's change
         var echo = inFlight.isEcho(value);
-        if ((echo || (0, lodash_1.isEqual)(normalizedValue, normalizeEmptyFieldValues(lastEmittedValue.current))) &&
-            agreed !== undefined) {
+        if (sameRecord && (echo || sameReportedValue(value, lastEmittedValue.current))) {
+            /* The form's own report coming back. Whatever the rebuild adds - a schema that changed in the same
+               commit, a field the host does not store - is added to the form's copy, never by going back to the
+               report: the report may be older than edits made since (an echo of "a" arriving after "ab" was
+               reported lost the "b"). Nothing changes when the form's copy has it all already. */
+            var rebuild_1 = function (fields) {
+                return (0, exports.fixOptions)(fields, options || {}, undefined, isRendererOnly);
+            };
+            if (!(0, lodash_1.isEqual)(rebuild_1(localValue.fields), localValue.fields)) {
+                // the parent has to learn what the rebuild added
+                mirroredValue.current = undefined;
+            }
+            /* What the host changed beside a field's value is taken (its type, say): the report is recognised by its
+               values (see `takeHostsAttributes`). */
+            var base_1 = seenValue.current;
+            setLocalValue(function (current) {
+                var rebuilt = rebuild_1((0, exports.takeHostsAttributes)(value, current.fields, base_1));
+                return (0, lodash_1.isEqual)(rebuilt, current.fields) ? current : { fields: rebuilt, meta: current.meta };
+            });
             return;
         }
         if (!originalValue.current && (0, size_1.default)(fixedValue)) {
@@ -1096,8 +1288,25 @@ var FormEngineImpl = function (_a) {
         if (agreed !== undefined) {
             lastEmittedValue.current = agreed;
         }
-        setLocalValue === null || setLocalValue === void 0 ? void 0 : setLocalValue({ fields: fixedValue, meta: undefined });
-    }, [JSON.stringify(options), JSON.stringify(value), isRendererOnly]);
+        if (!sameRecord) {
+            setLocalValue({ fields: fixedValue, meta: undefined });
+            return;
+        }
+        // The host's change, with the form's own edits it did not touch kept (see `mergeOwnEdits`).
+        var base = seenValue.current;
+        setLocalValue(function (current) {
+            var merged = (0, exports.mergeOwnEdits)(value, current.fields, base);
+            return {
+                fields: merged === value ? fixedValue : ((0, exports.fixOptions)(merged, options || {}, undefined, isRendererOnly)),
+                meta: undefined,
+            };
+        });
+    }, [JSON.stringify(options), JSON.stringify(value), isRendererOnly, valueKey]);
+    // Last of the value effects: what the next commit's `value` is a change from.
+    (0, react_2.useEffect)(function () {
+        seenValue.current = value;
+        seenValueKey.current = valueKey;
+    });
     var handleValueChange = (0, react_2.useCallback)(function (optionName, val, _type, isFunction) {
         setLocalValue(function (_a) {
             var _b, _c;
@@ -1294,8 +1503,11 @@ var FormEngineImpl = function (_a) {
             var _a, _b;
             var option = fixedValue[optionName];
             if (!(options === null || options === void 0 ? void 0 : options[optionName])) {
-                unavailableOptionsCount.current += 1;
-                removeSelectedOption(optionName);
+                // not on this instance - unless the schema is not yet the one in force (see `schemaInForce`)
+                if (schemaInForce) {
+                    unavailableOptionsCount.current += 1;
+                    removeSelectedOption(optionName);
+                }
                 return newValue;
             }
             var rendererType = (0, exports.getType)((options[optionName].ui_type || options[optionName].type), operators, option === null || option === void 0 ? void 0 : option.op);
@@ -1315,6 +1527,7 @@ var FormEngineImpl = function (_a) {
         unavailableOptionsCount.current,
         JSON.stringify(operators),
         showInvalidOptionsOnly,
+        schemaInForce,
     ]);
     // Per required-group: its member options, and which member (if any) already
     // satisfies it — drives the "One of" chips and the "covered by" notes.
@@ -1383,9 +1596,8 @@ var FormEngineImpl = function (_a) {
         var locked = [];
         (0, lodash_1.forEach)(options || {}, function (optionSchema, name) {
             (0, lodash_1.forEach)((optionSchema === null || optionSchema === void 0 ? void 0 : optionSchema.allowed_values) || [], function (allowedValue) {
-                var _a;
                 if (!(0, OptionFieldMessages_1.getAllowedValueAvailability)(allowedValue, availableOptions, options || {}).available) {
-                    locked.push("".concat(name, "\0").concat(JSON.stringify((_a = allowedValue === null || allowedValue === void 0 ? void 0 : allowedValue.value) === null || _a === void 0 ? void 0 : _a.value)));
+                    locked.push("".concat(name, "\0").concat(JSON.stringify((0, allowedValues_1.allowedValueOf)(allowedValue))));
                 }
             });
         });
@@ -1445,12 +1657,15 @@ var FormEngineImpl = function (_a) {
     }, [JSON.stringify(options), JSON.stringify(fixedValue), JSON.stringify(availableOptions)]);
     var isOptionValid = (0, react_2.useCallback)(function (optionName, type, optionValue) {
         var _a, _b, _c, _d;
-        var isEmpty = optionValue === undefined || optionValue === '';
-        // An empty field locked by an unmet `depends_on` does not apply, so it is
-        // not missing — the same rule the read-first status follows.
-        if (isEmpty &&
-            ((!((_a = options === null || options === void 0 ? void 0 : options[optionName]) === null || _a === void 0 ? void 0 : _a.required) && !((_b = options === null || options === void 0 ? void 0 : options[optionName]) === null || _b === void 0 ? void 0 : _b.required_groups)) ||
-                dependencyLockedNames.includes(optionName))) {
+        // the same "not set" the row's status reads: an empty list is no value
+        var isEmpty = (0, readFirst_1.isOptionValueEmpty)(optionValue);
+        // A field whose `depends_on` does not hold does not apply: it is hidden, and nothing in it can make the
+        // form invalid - a value it holds is kept, and said in the form's note, valid or not (qorus#646).
+        if (dependencyLockedNames.includes(optionName)) {
+            return true;
+        }
+        // An empty field that is not required is not missing.
+        if (isEmpty && !((_a = options === null || options === void 0 ? void 0 : options[optionName]) === null || _a === void 0 ? void 0 : _a.required) && !((_b = options === null || options === void 0 ? void 0 : options[optionName]) === null || _b === void 0 ? void 0 : _b.required_groups)) {
             return true;
         }
         return (0, validations_1.validateField)((0, exports.getType)(type), optionValue, __assign(__assign({ has_to_have_value: true, optionSchema: options, options: availableOptions }, options === null || options === void 0 ? void 0 : options[optionName]), { 
@@ -1469,28 +1684,41 @@ var FormEngineImpl = function (_a) {
     ]);
     var getValidityData = (0, react_2.useCallback)(function () {
         var fields = (0, reduce_1.default)(availableOptions, function (result, option, optionName) {
-            var _a, _b, _c;
+            var _a, _b, _c, _d;
             var type = (0, exports.getOptionFieldStorageType)(optionName, option.type, options, operators, option.op, isRendererOnly, optionHoldsExpression(option));
             var optionValue = option.value;
             var isRequired = (_a = options === null || options === void 0 ? void 0 : options[optionName]) === null || _a === void 0 ? void 0 : _a.required;
             var hasRequiredGroups = !!((_b = options === null || options === void 0 ? void 0 : options[optionName]) === null || _b === void 0 ? void 0 : _b.required_groups);
-            var isEmpty = optionValue === undefined || optionValue === '';
+            // the same "not set" the row's status reads: an empty list is no value
+            var isEmpty = (0, readFirst_1.isOptionValueEmpty)(optionValue);
             var validation;
-            /* A required field locked by an unmet `depends_on` does not apply
-               while it is locked: it is not in "Needs attention", and an empty one
-               does not make the form incomplete either. Otherwise a check whose
-               kind is Equals could never be saved, because Minimum — required for
-               Between alone — is empty; and a form whose only gaps are fields
-               nobody can fill in would say Incomplete with nothing to act on. A
-               locked field that still HOLDS a value is validated as before. */
-            if (isEmpty &&
-                ((!isRequired && !hasRequiredGroups) || dependencyLockedNames.includes(optionName))) {
-                validation = { isValid: true, reasons: [] };
+            /* A field whose host gives its own reason (`invalid_reason`) is invalid while it does, whatever the
+               field makes of its value: the host knows something the field cannot - that a field it names
+               is not in the record, that text around a field is not a whole number - and says it in the field,
+               in place of the field's own message (`getOptionFieldMessages`). */
+            var hostReason = (_c = options === null || options === void 0 ? void 0 : options[optionName]) === null || _c === void 0 ? void 0 : _c.invalid_reason;
+            if (hostReason) {
+                validation = { isValid: false, reason: hostReason, reasons: [hostReason] };
             }
             else {
-                validation = (0, validations_1.validateFieldWithResult)((0, exports.getType)(type), optionValue, __assign(__assign({ has_to_have_value: true, optionSchema: options, options: availableOptions }, options === null || options === void 0 ? void 0 : options[optionName]), { 
-                    // The expression flag lives on the field value, not the schema.
-                    isFunction: option.is_expression, hasOwnEditor: isRendererOnly((_c = options === null || options === void 0 ? void 0 : options[optionName]) === null || _c === void 0 ? void 0 : _c.ui_type) }));
+                /* A required field locked by an unmet `depends_on` does not apply
+                 while it is locked: it is not in "Needs attention", and an empty one
+                 does not make the form incomplete either. Otherwise a check whose
+                 kind is Equals could never be saved, because Minimum — required for
+                 Between alone — is empty; and a form whose only gaps are fields
+                 nobody can fill in would say Incomplete with nothing to act on. A
+                 locked field that still HOLDS a value is validated as before. */
+                if (dependencyLockedNames.includes(optionName) ||
+                    (isEmpty && !isRequired && !hasRequiredGroups)) {
+                    /* A field whose `depends_on` does not hold is hidden and does not apply: nothing in it makes the
+                       form invalid, empty or holding a value (kept, and said in the form's note - qorus#646). */
+                    validation = { isValid: true, reasons: [] };
+                }
+                else {
+                    validation = (0, validations_1.validateFieldWithResult)((0, exports.getType)(type), optionValue, __assign(__assign({ has_to_have_value: true, optionSchema: options, options: availableOptions }, options === null || options === void 0 ? void 0 : options[optionName]), { 
+                        // The expression flag lives on the field value, not the schema.
+                        isFunction: option.is_expression, hasOwnEditor: isRendererOnly((_d = options === null || options === void 0 ? void 0 : options[optionName]) === null || _d === void 0 ? void 0 : _d.ui_type) }));
+                }
             }
             result.push({
                 fieldName: optionName,
@@ -1519,9 +1747,16 @@ var FormEngineImpl = function (_a) {
     (0, react_2.useEffect)(function () {
         onValidityChange === null || onValidityChange === void 0 ? void 0 : onValidityChange(optionsAreValid, validityData);
     }, [JSON.stringify(validityData)]);
+    /* A field whose `depends_on` does not hold is not shown (qorus#646, David): it is not of use until it applies,
+       so it is left out of the form - not shown waiting, locked - and appears once its dependency holds (and
+       flashes - see `dependencyLockedNames`). Its value is kept; one it holds meanwhile is said in the form's
+       note (`hiddenFieldsWithValues`). */
     var shownOptions = (0, react_2.useMemo)(function () {
         return (0, reduce_1.default)(availableOptions, function (newValue, option, optionName) {
             var _a;
+            if (dependencyLockedNames.includes(optionName)) {
+                return newValue;
+            }
             if (showInvalidOptionsOnly &&
                 isOptionValid(optionName, (0, exports.getOptionFieldStorageType)(optionName, option.type, options, operators, option.op, isRendererOnly, optionHoldsExpression(option)), option.value)) {
                 return newValue;
@@ -1529,6 +1764,7 @@ var FormEngineImpl = function (_a) {
             return __assign(__assign({}, newValue), (_a = {}, _a[optionName] = option, _a));
         }, {});
     }, [
+        dependencyLockedNames,
         showInvalidOptionsOnly,
         isRendererOnly,
         JSON.stringify(availableOptions),
@@ -1542,7 +1778,7 @@ var FormEngineImpl = function (_a) {
     var schemaMsgIntent = (0, react_2.useCallback)(function (name) {
         var _a;
         // Filtered, not raw: a message hidden by its own `when`/`unless` must not
-        // colour the row or push the field into "Needs attention" — the whole point
+        // color the row or push the field into "Needs attention" — the whole point
         // of a conditional warning is that it is absent while it does not apply.
         var msgs = (0, OptionFieldMessages_1.getShownSchemaMessages)((_a = options === null || options === void 0 ? void 0 : options[name]) === null || _a === void 0 ? void 0 : _a.messages, availableOptions, options);
         if (msgs.some(function (m) { return m.intent === 'danger'; }))
@@ -1612,9 +1848,10 @@ var FormEngineImpl = function (_a) {
     }, [JSON.stringify(options), requiredGroupsInfo, getOptionStatus, dependencyLockedNames]);
     // How many fields are in the "Needs attention" box — drives the header link.
     var readFirstAttentionCount = (0, react_2.useMemo)(function () {
-        return Object.keys(availableOptions || {}).filter(function (name) { return getOptionBucket(name) === 'attention'; })
-            .length;
-    }, [JSON.stringify(availableOptions), getOptionBucket]);
+        return Object.keys(availableOptions || {}).filter(
+        // a hidden field (its `depends_on` does not hold) is not in the form, nor in its counts
+        function (name) { return !dependencyLockedNames.includes(name) && getOptionBucket(name) === 'attention'; }).length;
+    }, [JSON.stringify(availableOptions), getOptionBucket, dependencyLockedNames]);
     var getIntent = (0, react_2.useCallback)(
     // eslint-disable-next-line @typescript-eslint/no-unused-vars
     function (optName, type, optValue, _op) {
@@ -1663,14 +1900,35 @@ var FormEngineImpl = function (_a) {
     var handleOptionLabelClick = (0, react_2.useCallback)(function (optionName) {
         setShowHelpForOption(optionName);
     }, []);
-    var toggleExpandedOption = (0, react_2.useCallback)(function (optionName) {
+    /** Whether the first-required scan below has opened its row, or is spent by the user's first move (see it). Only a
+     *  remount arms it again. */
+    var hasAutoFocusedRef = (0, react_2.useRef)(false);
+    /** The fields the first-required scan has looked at: it opens a field that needs an answer when the field first
+     *  appears in the form, not when one already there comes to need one. */
+    var scannedFieldsRef = (0, react_2.useRef)(new Set());
+    /* A row is opened or closed by what the user did to the row as it was drawn, never by flipping whatever the
+       state is by the time React applies the update. A toggle read the direction from the latest state: the
+       first-required scan opens its row with an update of its own, and a click on that row, drawn closed, landed on
+       top of it and closed the row the user had just opened (qorus#646: the Qorus IDE's Schema "Draft Is Saved").
+       Each of these does nothing to a row already in its state.
+  
+       A row the user opens or closes is where they have chosen to work: the first-required scan, if it is still
+       waiting for the focus to be free, does not run after either (qorus#646). */
+    var expandOption = (0, react_2.useCallback)(function (optionName) {
+        hasAutoFocusedRef.current = true;
         setExpandedOptions(function (prev) {
-            return prev.includes(optionName) ? prev.filter(function (name) { return name !== optionName; })
+            return prev.includes(optionName) ? prev
                 // single (default): opening a row collapses any other open one.
                 : expandMode === 'single' ? [optionName]
                     : __spreadArray(__spreadArray([], prev, true), [optionName], false);
         });
     }, [expandMode]);
+    var collapseOption = (0, react_2.useCallback)(function (optionName) {
+        hasAutoFocusedRef.current = true;
+        setExpandedOptions(function (prev) {
+            return prev.includes(optionName) ? prev.filter(function (name) { return name !== optionName; }) : prev;
+        });
+    }, []);
     // --- 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
@@ -1702,6 +1960,41 @@ var FormEngineImpl = function (_a) {
         setExpandedOptions(function (prev) { return __spreadArray(__spreadArray([], prev, true), toExpand.filter(function (name) { return !prev.includes(name); }), true); });
     }, [initialExpandedOptions, compact, availableOptions]);
     // --- First-attention-field autofocus (opt-in) -----------------------------
+    /** The first row (of `names`, in order: every row by default) that needs an answer and can take one, if any: what
+     *  the first-required scan opens. */
+    var firstAttentionRow = function (names) {
+        if (names === void 0) { names = Object.keys(availableOptions); }
+        return (0, readFirst_1.getFirstAttentionOptionName)(names, function (fieldName) {
+            var schema = options === null || options === void 0 ? void 0 : options[fieldName];
+            if (!schema) {
+                return undefined;
+            }
+            return {
+                focusable: !readOnly &&
+                    !schema.disabled &&
+                    !schema.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',
+            };
+        });
+    };
+    var openFirstAttentionRow = function (target) {
+        if (target) {
+            setExpandedOptions(function (prev) {
+                return prev.includes(target) ? prev
+                    : expandMode === 'multi' ? __spreadArray(__spreadArray([], prev, true), [target], false) 
+                    // `expandMode: 'single'` is a rule about what a CLICK does: opening a
+                    // row closes the one the reader last opened. It is not a licence to
+                    // close a row the HOST named through `initialExpandedOptions`. That
+                    // is an address — a statement about what the page is FOR, made before
+                    // the reader did anything — and this scan is a convenience layered on
+                    // top of it. Keep the named rows; replace only what a click could.
+                    : __spreadArray(__spreadArray([], prev.filter(function (name) { return initialExpandedOptions === null || initialExpandedOptions === void 0 ? void 0 : initialExpandedOptions.includes(name); }), true), [target], false);
+            });
+        }
+    };
     // 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"
@@ -1711,13 +2004,17 @@ var FormEngineImpl = function (_a) {
     // `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.
-    var hasAutoFocusedRef = (0, react_2.useRef)(false);
+    // It opens one row for the life of this instance, keyed on a field's arrival: the first field that needs an
+    // answer when it first appears in the form. A schema that arrives after the mount, or in pieces, is covered: the
+    // fields of a later piece are looked at when they arrive, as long as the scan has opened nothing yet. A field
+    // already in the form that comes to need an answer (a value edited, a server-driven update) is not a reason to
+    // open it, nor to re-grab focus; only a genuine remount (a fresh instance) arms the scan again.
+    //
+    // It waits only for the user's first move. A form opened from a button mounts while that button holds the
+    // focus, and the scan waits for it to be free - but the user does not wait: they open a row (which spends
+    // the scan, `expandOption`) or come into the form from the keyboard (which runs it, below). Waiting
+    // past that, the scan ran the first time the focus rested on nothing, which is the Done that closes the
+    // user's row, and opened the next row that needed an answer by itself in the middle of their work.
     (0, react_2.useEffect)(function () {
         // Two decisions, one scan. Both open the row that needs attention;
         // `autoFocusFirstRequired` additionally promises the caret lands in it, and
@@ -1726,14 +2023,25 @@ var FormEngineImpl = function (_a) {
         // CompactRow's tap-to-edit rule, and it declines just as firmly to take one
         // that is already somewhere outside the row.
         var wantsFocus = !!autoFocusFirstRequired;
-        if ((!wantsFocus && !expandFirstRequired) || !compact || !options) {
+        // the schema the form holds is the one in force: not one a skeleton stands for, nor one the host has replaced
+        if ((!wantsFocus && !expandFirstRequired) || !compact || !options || !schemaInForce) {
             return;
         }
         if (hasAutoFocusedRef.current) {
             return;
         }
         var orderedNames = Object.keys(availableOptions);
-        if (!orderedNames.length) {
+        // the fields that have appeared since the scan last looked: only they can be what it opens
+        var arrived = orderedNames.filter(function (name) { return !scannedFieldsRef.current.has(name); });
+        if (!arrived.length) {
+            return;
+        }
+        /* Read on the form the schema makes: a required field the schema brings is added to the form's value by the
+           sync-down, an effect, so the render after the schema arrives. Read before that, the form had no row for it:
+           the scan found nothing to open and was spent, and the field's row stayed closed (qorus#646: the Qorus IDE's
+           pipeline processor, whose required field mappings arrive with its schema). */
+        var formTheSchemaMakes = (0, exports.fixOptions)(fixedValue, options, undefined, isRendererOnly);
+        if (Object.keys(formTheSchemaMakes || {}).some(function (name) { return !(name in fixedValue); })) {
             return;
         }
         // Never grab focus from a control the user is already in — including a field
@@ -1752,55 +2060,107 @@ var FormEngineImpl = function (_a) {
         if (wantsFocus && active && active !== document.body) {
             return;
         }
-        var target = (0, readFirst_1.getFirstAttentionOptionName)(orderedNames, function (fieldName) {
-            var schema = options[fieldName];
-            if (!schema) {
-                return undefined;
-            }
-            return {
-                focusable: !readOnly &&
-                    !schema.disabled &&
-                    !schema.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) {
-            setExpandedOptions(function (prev) {
-                return prev.includes(target) ? prev
-                    : expandMode === 'multi' ? __spreadArray(__spreadArray([], prev, true), [target], false) 
-                    // `expandMode: 'single'` is a rule about what a CLICK does: opening a
-                    // row closes the one the reader last opened. It is not a licence to
-                    // close a row the HOST named through `initialExpandedOptions`. That
-                    // is an address — a statement about what the page is FOR, made before
-                    // the reader did anything — and this scan is a convenience layered on
-                    // top of it. Keep the named rows; replace only what a click could.
-                    : __spreadArray(__spreadArray([], prev.filter(function (name) { return initialExpandedOptions === null || initialExpandedOptions === void 0 ? void 0 : initialExpandedOptions.includes(name); }), true), [target], false);
-            });
+        // Looked at: a field here now is not looked at again, whatever it comes to hold.
+        orderedNames.forEach(function (name) { return scannedFieldsRef.current.add(name); });
+        var target = firstAttentionRow(arrived);
+        if (!target) {
+            // nothing that arrived needs an answer: the scan waits for the fields still to come
+            return;
         }
+        hasAutoFocusedRef.current = true;
+        openFirstAttentionRow(target);
     }, [
         autoFocusFirstRequired,
         expandFirstRequired,
         compact,
         options,
+        schemaInForce,
         availableOptions,
+        isRendererOnly,
         readOnly,
         dependencyLockedNames,
         getOptionBucket,
         expandMode,
         initialExpandedOptions,
     ]);
+    /* The two first moves a user makes in a form opened from a button, while the scan above waits for the
+       focus to be free:
+       - pointing into the form (a click on a row, a field, the toolbar) is choosing where to work, and spends
+         the scan, as opening a row does (`expandOption`);
+       - coming into it from the keyboard (Tab from the button) chooses nothing, and runs the scan now: the user
+         is put in the first row that needs an answer, once. Coming straight into a control they can type in
+         (a field already open, the search box) is theirs, and spends the scan without moving them.
+       Only while the scan still waits; it never runs twice. */
+    var keyboardEntry = (0, react_2.useRef)();
+    keyboardEntry.current = function (event) {
+        if (hasAutoFocusedRef.current || !options || !Object.keys(availableOptions).length) {
+            return;
+        }
+        var from = event.relatedTarget;
+        if (from && (compactWrapNode === null || compactWrapNode === void 0 ? void 0 : compactWrapNode.contains(from))) {
+            return;
+        }
+        hasAutoFocusedRef.current = true;
+        var entered = event.target;
+        if ((0, rowFocus_1.isTypingControl)(entered)) {
+            return;
+        }
+        var target = firstAttentionRow();
+        if (!target) {
+            return;
+        }
+        // A row takes the caret only from nothing - never from an element the reader is on (see CompactRow) - so
+        // the element the Tab landed on lets it go: the scan is what the reader came in for.
+        entered.blur();
+        openFirstAttentionRow(target);
+    };
+    (0, react_2.useEffect)(function () {
+        if (!autoFocusFirstRequired || !compact || !compactWrapNode) {
+            return undefined;
+        }
+        var onPointerDown = function () {
+            hasAutoFocusedRef.current = true;
+        };
+        var onFocusIn = function (event) { var _a; return (_a = keyboardEntry.current) === null || _a === void 0 ? void 0 : _a.call(keyboardEntry, event); };
+        // capture: the pointer is the user's choice before anything in the form answers it
+        compactWrapNode.addEventListener('pointerdown', onPointerDown, true);
+        compactWrapNode.addEventListener('focusin', onFocusIn);
+        return function () {
+            compactWrapNode.removeEventListener('pointerdown', onPointerDown, true);
+            compactWrapNode.removeEventListener('focusin', onFocusIn);
+        };
+    }, [autoFocusFirstRequired, compact, compactWrapNode]);
     // Read-first completion summary (how many shown options have a value set),
     // surfaced as a progress meter at the top of the compact form.
     var readFirstCompletion = (0, react_2.useMemo)(function () {
-        return (0, readFirst_1.getReadFirstCompletion)(availableOptions, function (name) { return getOptionBucket(name) === 'attention'; });
-    }, [JSON.stringify(availableOptions), getOptionBucket]);
+        return (0, readFirst_1.getReadFirstCompletion)(
+        // a hidden field (its `depends_on` does not hold) is not in the form, nor in its meter
+        (0, lodash_1.omit)(availableOptions, dependencyLockedNames), function (name) { return getOptionBucket(name) === 'attention'; });
+    }, [JSON.stringify(availableOptions), getOptionBucket, dependencyLockedNames]);
+    /* The hidden fields (their `depends_on` does not hold) that hold a value: kept, not dropped silently, so the form
+       says so in a note - and whether the value is valid, as no field shows it (qorus#646, David). */
+    var hiddenFieldsWithValues = (0, react_2.useMemo)(function () {
+        return dependencyLockedNames
+            .filter(function (name) { var _a; return !(0, readFirst_1.isOptionValueEmpty)((_a = availableOptions === null || availableOptions === void 0 ? void 0 : availableOptions[name]) === null || _a === void 0 ? void 0 : _a.value); })
+            .map(function (name) {
+            var field = availableOptions[name];
+            var schema = options === null || options === void 0 ? void 0 : options[name];
+            var type = (0, exports.getOptionFieldStorageType)(name, field.type, options, operators, field.op, isRendererOnly, optionHoldsExpression(field));
+            var validation = (0, validations_1.validateFieldWithResult)((0, exports.getType)(type), field.value, __assign(__assign({ has_to_have_value: true, optionSchema: options, options: availableOptions }, schema), { isFunction: field.is_expression, hasOwnEditor: isRendererOnly(schema === null || schema === void 0 ? void 0 : schema.ui_type) }));
+            return {
+                name: name,
+                label: (schema === null || schema === void 0 ? void 0 : schema.display_name) || name,
+                conditions: (0, OptionFieldMessages_1.describeDependencies)(((schema === null || schema === void 0 ? void 0 : schema.depends_on) || []), options || {}),
+                invalidReason: validation.isValid ? undefined : validation.reason,
+            };
+        });
+    }, [
+        dependencyLockedNames,
+        JSON.stringify(availableOptions),
+        JSON.stringify(options),
+        JSON.stringify(operators),
+        isRendererOnly,
+    ]);
     var optionalFields = (0, react_2.useMemo)(function () {
         return Object.keys(filteredOptions).map(function (option) {
             var _a, _b, _c, _d, _f, _g;
@@ -1970,7 +2330,7 @@ var FormEngineImpl = function (_a) {
                                                 (0, jsx_runtime_1.jsx)(reqore_1.ReqoreButton, { disabled: readOnly, icon: 'DeleteBinLine', effect: NegativeColorEffect, fixed: true, onClick: function () { return handleRemoveOperator(optionName, fixedValue, index); } })
                                                 : null] }, index));
                                 }) }), (0, jsx_runtime_1.jsx)(reqore_1.ReqoreVerticalSpacer, { height: 5 })] })
-                    : null, (0, react_1.createElement)(TemplateField_1.TemplateField, __assign({ fluid: true }, options === null || options === void 0 ? void 0 : options[optionName], resolveInheritProps((_c = options === null || options === void 0 ? void 0 : options[optionName]) === null || _c === void 0 ? void 0 : _c.inherit_props, availableOptions, inheritedFromParent), { 
+                    : null, (0, react_1.createElement)(TemplateField_1.TemplateField, __assign({ fluid: true }, options === null || options === void 0 ? void 0 : options[optionName], (0, inheritProps_1.resolveInheritProps)((_c = options === null || options === void 0 ? void 0 : options[optionName]) === null || _c === void 0 ? void 0 : _c.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
@@ -1999,6 +2359,9 @@ var FormEngineImpl = function (_a) {
                     // reqraft: form-level expression fields get the Visual/Text shell
                     // (DPQL text mode); opt out per-form via `templateFieldProps`.
                     allowTextExpressions: true, 
+                    // a form's options enter their value on tabs: Value · Expression · Visual, or Value · Template
+                    // where only templates are taken (qorus#646); opt out per-form via `templateFieldProps`
+                    valueTabs: true, 
                     // 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
@@ -2043,11 +2406,13 @@ var FormEngineImpl = function (_a) {
                         !(0, validations_1.hasAllDependenciesFullfilled)((_v = options === null || options === void 0 ? void 0 : options[optionName]) === null || _v === void 0 ? void 0 : _v.depends_on, availableOptions, options || {}), readOnly: readOnly, size: editorSize || rest.size, menuItems: (0, typeChoices_1.offersTypeChoices)(options === null || options === void 0 ? void 0 : options[optionName], anyLikeUiTypes) ?
                         getCustomMenuTemplateItems(optionName)
                         : undefined }, templateFieldProps, { forceDropdown: effectiveForceDropdown })), (0, jsx_runtime_1.jsx)(OptionFieldMessages_1.OptionFieldMessages, { schema: options || {}, allOptions: availableOptions, name: optionName, option: __assign({ type: resolvedType }, other), getType: getTypeForOption, isRendererOnly: isRendererOnly }), operators && (0, size_1.default)(operators) && (0, size_1.default)(other.op) ?
-                    (0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreVerticalSpacer, { height: 5 }), (0, jsx_runtime_1.jsx)(reqore_1.ReqoreMessage, { size: 'small', children: (0, jsx_runtime_1.jsxs)(reqore_1.ReqoreTagGroup, { children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreTag, { size: 'small', labelKey: 'WHERE', label: optionName }), (0, jsx_runtime_1.jsx)(reqore_1.ReqoreTag, { size: 'small', labelKey: 'IS', label: operatorParts.join(' ') }), (0, jsx_runtime_1.jsx)(reqore_1.ReqoreTag, { size: 'small', intent: 'info', label: other.value ?
-                                                resolvedType === 'richtext' ?
-                                                    (0, common_1.richtextToString)(other.value)
-                                                    : JSON.stringify(other.value)
-                                                : '' })] }) })] })
+                    (0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreVerticalSpacer, { height: 5 }), (0, jsx_runtime_1.jsx)(reqore_1.ReqoreMessage, { size: 'small', className: 'options-operator-summary', children: (0, operatorSummary_1.operatorSummary)({
+                                    label: (optionSchema === null || optionSchema === void 0 ? void 0 : optionSchema.display_name) || optionName,
+                                    operatorKeys: operatorParts,
+                                    operators: operators,
+                                    value: other.value,
+                                    shown: (0, readFirst_1.formatOptionValue)(__assign({ type: resolvedType }, other), optionSchema),
+                                }) })] })
                     : null] }));
     }, [
         options,
@@ -2064,7 +2429,7 @@ var FormEngineImpl = function (_a) {
         fixedValue,
         // Depend on the specific `rest` values used, not the whole `rest` object
         // (which is a fresh `{...rest}` every render and would defeat the memo).
-        rest === null || rest === void 0 ? void 0 : rest.options,
+        optionsSchema,
         rest === null || rest === void 0 ? void 0 : rest.size,
         handleValueChange,
         handleOperatorChange,
@@ -2076,11 +2441,11 @@ var FormEngineImpl = function (_a) {
         inheritedFromParent,
     ]);
     // Compact (read-first) rendering.
-    // Theme-derived colours so the flat-row layout adapts to light/dark/custom themes.
+    // Theme-derived colors so the flat-row layout adapts to light/dark/custom themes.
     var cText = ((_b = theme === null || theme === void 0 ? void 0 : theme.text) === null || _b === void 0 ? void 0 : _b.color) || '#f1f0ee';
-    // Text emphasis tiers via reqore's readable-colour helper (key = full readable
+    // Text emphasis tiers via reqore's readable-color helper (key = full readable
     // text, muted = its dimmed variant, faint = the dimmed variant softened
-    // further) instead of hand-rolled hex-alpha suffixes on the raw text colour.
+    // further) instead of hand-rolled hex-alpha suffixes on the raw text color.
     var cKey = (0, colors_1.getReadableColor)(theme);
     var cMuted = (0, colors_1.getReadableColor)(theme, undefined, undefined, true);
     var cFaint = "".concat(cMuted, "99");
@@ -2090,6 +2455,15 @@ var FormEngineImpl = function (_a) {
     var cWarning = ((_d = theme === null || theme === void 0 ? void 0 : theme.intents) === null || _d === void 0 ? void 0 : _d.warning) || '#ffdf34';
     var cInfo = ((_f = theme === null || theme === void 0 ? void 0 : theme.intents) === null || _f === void 0 ? void 0 : _f.info) || '#3b8eea';
     var cSuccess = ((_g = theme === null || theme === void 0 ? void 0 : theme.intents) === null || _g === void 0 ? void 0 : _g.success) || '#36b37e';
+    // the rows' own words and marks, in colors that read on every surface a row is drawn on
+    var rowInks = (0, react_2.useMemo)(function () { return (0, readFirstColors_1.getReadFirstInks)(theme); }, [theme]);
+    // an option panel's short description, faint: as faint as it still reads in the theme
+    var optionDescOpacity = (0, react_2.useMemo)(function () { return (0, readableColors_1.getReadableTextOpacity)(theme, 0.3); }, [theme]);
+    /* an invalid option's mark in its panel's title: the danger, in the shade of it that stands out as reqore draws a
+       title icon, at 70% (danger:lighten:5 was 2.9:1) */
+    var invalidOptionIconColor = (0, react_2.useMemo)(function () {
+        return (0, readableColors_1.getReadableShade)(cDanger, (0, readableColors_1.getThemeSurfaces)(theme), readableColors_1.READABLE_ICON, PANEL_TITLE_ICON_ALPHA);
+    }, [theme, cDanger]);
     var cBg = (theme === null || theme === void 0 ? void 0 : theme.main) || '#181818';
     var cRowBg = (0, colors_1.changeDarkness)((0, colors_1.getMainBackgroundColor)(theme), 0.01);
     var cGroupLine = "".concat(cText, "1f");
@@ -2110,6 +2484,9 @@ var FormEngineImpl = function (_a) {
         focusedEditing: focusedEditing,
         showFieldTypes: showFieldTypes,
         codePreviewRenderer: codePreviewRenderer,
+        codeEditor: componentOverrides === null || componentOverrides === void 0 ? void 0 : componentOverrides['code-editor'],
+        readSummaries: readSummaries,
+        cardEditorTypes: cardEditorTypes,
         showAllDescriptions: showAllDescriptions,
         expandedOptions: expandedOptions,
         highlightedOptions: highlightedOptions,
@@ -2124,7 +2501,8 @@ var FormEngineImpl = function (_a) {
         requiredGroupsInfo: requiredGroupsInfo,
         handleValueChange: handleValueChange,
         handleAddOptionalFieldChange: handleAddOptionalFieldChange,
-        toggleExpandedOption: toggleExpandedOption,
+        expandOption: expandOption,
+        collapseOption: collapseOption,
         flashOption: flashOption,
         hasOptionChanged: hasOptionChanged,
         handleOptionLabelClick: handleOptionLabelClick,
@@ -2147,6 +2525,7 @@ var FormEngineImpl = function (_a) {
         cWarning: cWarning,
         cInfo: cInfo,
         cBg: cBg,
+        rowInks: rowInks,
     }); }, [
         templates.value,
         readOnly,
@@ -2157,6 +2536,9 @@ var FormEngineImpl = function (_a) {
         focusedEditing,
         showFieldTypes,
         codePreviewRenderer,
+        componentOverrides,
+        readSummaries,
+        cardEditorTypes,
         showAllDescriptions,
         expandedOptions,
         highlightedOptions,
@@ -2171,7 +2553,8 @@ var FormEngineImpl = function (_a) {
         requiredGroupsInfo,
         handleValueChange,
         handleAddOptionalFieldChange,
-        toggleExpandedOption,
+        expandOption,
+        collapseOption,
         flashOption,
         hasOptionChanged,
         handleOptionLabelClick,
@@ -2194,6 +2577,7 @@ var FormEngineImpl = function (_a) {
         cWarning,
         cInfo,
         cBg,
+        rowInks,
     ]);
     // `compactToolbar` resolved to a full object, so neither the context type nor
     // the toolbar itself has to re-default anything. `null` means no toolbar.
@@ -2571,7 +2955,7 @@ var FormEngineImpl = function (_a) {
                 // "Covers"/"Covered by" chips already say which member satisfies it.
                 if (requiredGroupsInfo.satisfiedBy[grp])
                     return railed;
-                return ((0, jsx_runtime_1.jsxs)(compactRowStyles_1.StyledRequiredClusterBox, { className: 'options-readfirst-required-cluster', "$border": "".concat(cWarning, "33"), "$tint": "".concat(cWarning, "0d"), children: [(0, jsx_runtime_1.jsxs)(compactRowStyles_1.StyledRequiredClusterHeader, { "$color": cWarning, children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreIcon, { icon: 'LinkM', size: '11px', style: { color: cWarning } }), "One of the below is required"] }), railed] }, grp));
+                return ((0, jsx_runtime_1.jsxs)(compactRowStyles_1.StyledRequiredClusterBox, { className: 'options-readfirst-required-cluster', "$border": "".concat(cWarning, "33"), "$tint": "".concat(cWarning, "0d"), children: [(0, jsx_runtime_1.jsxs)(compactRowStyles_1.StyledRequiredClusterHeader, { "$color": rowInks.warning, children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreIcon, { icon: 'LinkM', size: '11px', style: { color: rowInks.warning } }), "One of the below is required"] }), railed] }, grp));
             });
         };
         // One schema group inside a status box: its thin sub-label, the group's
@@ -2655,7 +3039,7 @@ var FormEngineImpl = function (_a) {
                                                visible` to `auto` unless the other axis is visible or
                                                clip, which would put the scrollport straight back. `clip`
                                                keeps the horizontal guard the row ellipsis relies on. */
-                                            overflowY: 'visible', overflowX: 'clip' }, compactPanelProps === null || compactPanelProps === void 0 ? void 0 : compactPanelProps.contentStyle), children: [(0, size_1.default)(groupKeys) === 0 || (readOnly && !bucketCount('set')) ?
+                                            overflowY: 'visible', overflowX: 'clip' }, compactPanelProps === null || compactPanelProps === void 0 ? void 0 : compactPanelProps.contentStyle), children: [(0, jsx_runtime_1.jsx)(HiddenFieldsNote_1.HiddenFieldsNote, { fields: hiddenFieldsWithValues }), (0, size_1.default)(groupKeys) === 0 || (readOnly && !bucketCount('set')) ?
                                                 (0, jsx_runtime_1.jsx)(reqore_1.ReqoreMessage, { flat: true, opaque: false, size: 'small', children: readOnly && !query ?
                                                         'Nothing is set.'
                                                         : 'No fields match the current filters.' })
@@ -2772,7 +3156,7 @@ var FormEngineImpl = function (_a) {
                                                                     })
                                                                     : null] }) }, box.key));
                                                 })] })), commitMode === 'batched' && !readOnly && dirtyOptionNames.length ?
-                                        (0, jsx_runtime_1.jsx)(StyledCommitDock, { "$bg": cBg, "$border": cDivider, children: (0, jsx_runtime_1.jsxs)(reqore_1.ReqoreControlGroup, { className: 'options-readfirst-commitbar', verticalAlign: 'center', wrap: true, children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreTag, { size: 'tiny', minimal: true, flat: true, compact: true, effect: { uppercase: true, spaced: 1 }, intent: 'warning', icon: 'EditLine', label: "".concat(dirtyOptionNames.length, " unsaved change").concat(dirtyOptionNames.length === 1 ? '' : 's') }), (0, jsx_runtime_1.jsx)(reqore_1.ReqoreButton, { size: 'small', intent: 'success', icon: 'CheckLine', fixed: true, className: 'options-readfirst-save', disabled: !validityData.isValid, tooltip: validityData.isValid ?
+                                        (0, jsx_runtime_1.jsx)(StyledCommitDock, { "$bg": cBg, "$border": cDivider, children: (0, jsx_runtime_1.jsxs)(reqore_1.ReqoreControlGroup, { className: 'options-readfirst-commitbar', verticalAlign: 'center', wrap: true, children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreTag, { size: 'tiny', minimal: true, flat: true, compact: true, effect: { uppercase: true, spaced: 1 }, intent: 'warning', icon: 'EditLine', label: "".concat(dirtyOptionNames.length, " unsaved change").concat(dirtyOptionNames.length === 1 ? '' : 's') }), validityData.isValid ? null : ((0, jsx_runtime_1.jsx)(reqore_1.ReqoreTag, { size: 'tiny', minimal: true, flat: true, wrap: true, intent: 'danger', icon: 'ErrorWarningLine', className: 'options-readfirst-commit-blocked', label: (0, readFirst_1.describeBlockedSave)(validityData.invalidFields, options) })), (0, jsx_runtime_1.jsx)(reqore_1.ReqoreButton, { size: 'small', intent: 'success', icon: 'CheckLine', fixed: true, className: 'options-readfirst-save', disabled: !validityData.isValid, tooltip: validityData.isValid ?
                                                             'Apply the staged changes'
                                                             : 'Resolve the invalid fields before saving', onClick: handleCommitClick, children: "Save" }), (0, jsx_runtime_1.jsx)(reqore_1.ReqoreButton, { size: 'small', minimal: true, flat: true, fixed: true, icon: 'HistoryLine', className: 'options-readfirst-discard', onClick: handleRevertChangesClick, children: "Discard" })] }) })
                                         : null] }) })] }) }) }));
@@ -2780,7 +3164,10 @@ var FormEngineImpl = function (_a) {
     /* Which of the seven waits is holding the form, in the order they are
        tested. Rendered as `data-wait` on the placeholder so a page can be asked
        what it is waiting FOR instead of only that it is waiting. */
-    var waitReason = rest.skeleton ? (rest.skeletonReason ? "host:".concat(rest.skeletonReason) : 'host')
+    var waitReason = rest.skeleton ?
+        skeletonReason ?
+            "host:".concat(skeletonReason)
+            : 'host'
         : templates.loading ? 'templates'
             : typesLoading ? 'types'
                 : optionsLoading ? 'options'
@@ -2815,11 +3202,11 @@ var FormEngineImpl = function (_a) {
                                         'Showing invalid fields only. Click here again to show all fields.'
                                         : "".concat((0, size_1.default)(validityData.invalidFields) < 2 ? 'A field is not valid and requires' : "".concat((0, size_1.default)(validityData.invalidFields), " fields are not valid and require"), " attention. Click here to only show invalid fields.") })
                                 : null, unavailableOptionsCount.current ?
-                                (0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreMessage, { intent: 'warning', opaque: false, size: 'small', margin: 'bottom', children: "".concat(unavailableOptionsCount.current, " fields(s) hidden because they are not supported on the current instance") }), (0, jsx_runtime_1.jsx)(reqore_1.ReqoreVerticalSpacer, { height: 10 })] })
-                                : null, children, (0, size_1.default)(filteredOptions) >= 1 && !readOnly ?
+                                (0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreMessage, { intent: 'warning', opaque: false, size: 'small', margin: 'bottom', children: "".concat(unavailableOptionsCount.current, " ").concat(unavailableOptionsCount.current === 1 ? 'field' : 'fields', " hidden because they are not supported on the current instance") }), (0, jsx_runtime_1.jsx)(reqore_1.ReqoreVerticalSpacer, { height: 10 })] })
+                                : null, (0, jsx_runtime_1.jsx)(HiddenFieldsNote_1.HiddenFieldsNote, { fields: hiddenFieldsWithValues }), children, (0, size_1.default)(filteredOptions) >= 1 && !readOnly ?
                                 (0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)(reqore_1.ReqoreVerticalSpacer, { height: 10 }), (0, jsx_runtime_1.jsx)(Select_1.SelectFormField, { items: optionalFields, onChange: function (val) { return handleAddOptionalFieldChange('options', val); }, placeholder: placeholder || 'More Options Available', minimal: true, icon: 'ListView', showDescription: false, fluid: true, size: rest.size })] })
                                 : null] })); }, sortButtonProps: { minimal: true }, showLayoutSwitch: false, style: { width: '100%' }, items: (0, map_1.default)(shownOptions, function (_a, optionName) {
-                        var _b, _c, _d, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u, _v;
+                        var _b, _c, _d, _f, _g, _h, _j, _k, _l, _m, _o, _p, _q, _r, _s, _t, _u;
                         var type = _a.type, other = __rest(_a, ["type"]);
                         return ({
                             label: ((_b = options[optionName]) === null || _b === void 0 ? void 0 : _b.display_name) || optionName,
@@ -2843,12 +3230,14 @@ var FormEngineImpl = function (_a) {
                                 content: ((0, jsx_runtime_1.jsx)(Description_1.Description, { longDescription: "".concat((_h = options[optionName]) === null || _h === void 0 ? void 0 : _h.short_desc).concat(((_j = options[optionName]) === null || _j === void 0 ? void 0 : _j.desc) ? '. Click to learn more.' : ''), margin: 'none' })),
                             },
                             description: showFieldTypes ?
-                                "<".concat(options[optionName].ui_type || options[optionName].type).concat(((_k = options[optionName]) === null || _k === void 0 ? void 0 : _k.ui_element_type) ? "[".concat(options[optionName].ui_element_type, "]") : '', "> ").concat(options[optionName].short_desc || '')
+                                [(0, qorusTypeCatalogue_1.optionTypeWords)(options[optionName], typeName), options[optionName].short_desc]
+                                    .filter(Boolean)
+                                    .join(' · ')
                                 : options[optionName].short_desc || '',
                             descriptionEffect: {
                                 textSize: '11px',
-                                opacity: 0.3,
-                                underline: ((_l = options[optionName]) === null || _l === void 0 ? void 0 : _l.desc) ? 'underline dotted #878787' : undefined,
+                                opacity: optionDescOpacity,
+                                underline: ((_k = options[optionName]) === null || _k === void 0 ? void 0 : _k.desc) ? 'underline dotted #878787' : undefined,
                             },
                             customTheme: {
                                 main: 'main:darken:1',
@@ -2857,7 +3246,7 @@ var FormEngineImpl = function (_a) {
                             icon: !isOptionValid(optionName, type, other.value) ? 'SpamFill'
                                 : undefined,
                             iconColor: !isOptionValid(optionName, type, other.value) ?
-                                'danger:lighten:5'
+                                invalidOptionIconColor
                                 : undefined,
                             transparent: false,
                             intent: getIntent(optionName, type, other.value, other.op),
@@ -2885,7 +3274,7 @@ var FormEngineImpl = function (_a) {
                                 menu: [
                                     !readOnly &&
                                         type !== 'code-editor' &&
-                                        (((_m = options[optionName]) === null || _m === void 0 ? void 0 : _m.ui_type) || ((_o = options[optionName]) === null || _o === void 0 ? void 0 : _o.type)) !==
+                                        (((_l = options[optionName]) === null || _l === void 0 ? void 0 : _l.ui_type) || ((_m = options[optionName]) === null || _m === void 0 ? void 0 : _m.type)) !==
                                             'code-editor' && {
                                         label: 'Focused editing',
                                         icon: 'FullscreenLine',
@@ -2898,22 +3287,22 @@ var FormEngineImpl = function (_a) {
                                         icon: 'HistoryLine',
                                         className: 'options-item-revert',
                                         onClick: function () {
-                                            var _a, _b, _c, _d;
-                                            handleValueChange(optionName, (_b = (_a = originalValue.current) === null || _a === void 0 ? void 0 : _a[optionName]) === null || _b === void 0 ? void 0 : _b.value, (_d = (_c = originalValue.current) === null || _c === void 0 ? void 0 : _c[optionName]) === null || _d === void 0 ? void 0 : _d.type);
+                                            var _a;
+                                            handleValueChange.apply(void 0, __spreadArray([optionName], (0, argumentPresence_1.restoredFieldChange)((_a = originalValue.current) === null || _a === void 0 ? void 0 : _a[optionName]), false));
                                         },
                                     },
                                     !readOnly &&
                                         other.value &&
                                         !(0, lodash_1.isEqual)(other.value, (0, common_1.getDefaultValue)(options[optionName])) &&
-                                        !(((_p = options[optionName]) === null || _p === void 0 ? void 0 : _p.disabled) || ((_q = options[optionName]) === null || _q === void 0 ? void 0 : _q.readonly)) && {
+                                        !(((_o = options[optionName]) === null || _o === void 0 ? void 0 : _o.disabled) || ((_p = options[optionName]) === null || _p === void 0 ? void 0 : _p.readonly)) && {
                                         label: 'Remove value',
                                         icon: 'CloseLine',
                                         className: 'options-item-remove',
                                         onClick: function () { return handleValueChange(optionName, undefined); },
                                     },
                                     !readOnly &&
-                                        !((_r = options[optionName]) === null || _r === void 0 ? void 0 : _r.preselected) &&
-                                        !((_s = options[optionName]) === null || _s === void 0 ? void 0 : _s.required) && {
+                                        !((_q = options[optionName]) === null || _q === void 0 ? void 0 : _q.preselected) &&
+                                        !((_r = options[optionName]) === null || _r === void 0 ? void 0 : _r.required) && {
                                         label: 'Remove option',
                                         icon: 'DeleteBinLine',
                                         intent: 'danger',
@@ -2929,8 +3318,8 @@ var FormEngineImpl = function (_a) {
                                     },
                                 ],
                             }),
-                            content: ((0, jsx_runtime_1.jsxs)(FocusedEditing_1.FocusedEditing, { isFullscreen: focusedEditing === optionName, onClose: function () { return setFocusedEditing(undefined); }, description: (_t = options[optionName]) === null || _t === void 0 ? void 0 : _t.display_name, intent: getIntent(optionName, type, other.value, other.op), children: [focusedEditing === optionName ?
-                                        (0, jsx_runtime_1.jsx)(Description_1.Description, { longDescription: (_u = options[optionName]) === null || _u === void 0 ? void 0 : _u.desc, shortDescription: (_v = options[optionName]) === null || _v === void 0 ? void 0 : _v.short_desc, longDescriptionShownByDefault: true })
+                            content: ((0, jsx_runtime_1.jsxs)(FocusedEditing_1.FocusedEditing, { isFullscreen: focusedEditing === optionName, onClose: function () { return setFocusedEditing(undefined); }, description: (_s = options[optionName]) === null || _s === void 0 ? void 0 : _s.display_name, intent: getIntent(optionName, type, other.value, other.op), children: [focusedEditing === optionName ?
+                                        (0, jsx_runtime_1.jsx)(Description_1.Description, { longDescription: (_t = options[optionName]) === null || _t === void 0 ? void 0 : _t.desc, shortDescription: (_u = options[optionName]) === null || _u === void 0 ? void 0 : _u.short_desc, longDescriptionShownByDefault: true })
                                         : null, renderOption(optionName, __assign({ type: type }, other))] })),
                         });
                     }), defaultZoom: 1, zoomable: false, actions: __spreadArray(__spreadArray([], (rest.actions || []).map(function (action) { return (__assign(__assign({}, action), { minimal: true })); }), true), [
@@ -2967,8 +3356,13 @@ var FormEngineImpl = function (_a) {
  * a child of the row it belongs to. Threading a renderer to each of them by
  * hand is how one of them gets missed.
  */
-var FormEngine = function (props) { return ((0, jsx_runtime_1.jsx)(markdownRendererContext_1.MarkdownRendererContext.Provider, { value: props.markdownRenderer, children: (0, jsx_runtime_1.jsx)(FormEngineImpl, __assign({}, props)) })); };
+var FormEngine = function (props) {
+    // what the host knows of references beyond the catalogue, for every chip the form draws (qorus#646)
+    var referenceNames = (0, react_2.useMemo)(function () { var _a; return (_a = props.templateReferences) !== null && _a !== void 0 ? _a : NO_REFERENCE_NAMES; }, [props.templateReferences]);
+    return ((0, jsx_runtime_1.jsx)(markdownRendererContext_1.MarkdownRendererContext.Provider, { value: props.markdownRenderer, children: (0, jsx_runtime_1.jsx)(typeSentenceForm_1.TypeSentenceFormProvider, { children: (0, jsx_runtime_1.jsx)(referenceNames_1.TemplateReferenceNamesProvider, { value: referenceNames, children: (0, jsx_runtime_1.jsx)(FormEngineImpl, __assign({}, props)) }) }) }));
+};
 exports.FormEngine = FormEngine;
+var NO_REFERENCE_NAMES = {};
 exports.default = exports.FormEngine;
 var templateObject_1, templateObject_2, templateObject_3, templateObject_4;
 //# sourceMappingURL=FormEngine.js.map