@qoretechnologies/reqraft 0.10.57 → 0.10.58-pr.129.g2af0cf5

package/src/components/form/engine/variants/variantModel.ts

@@ -20,6 +20,7 @@ import {
   isOptionValueEmpty,
 } from '../readFirst';
 import { isValueTemplate } from '../../../../helpers/templates';
+import { hasAllDependenciesFullfilled } from '../../../../helpers/validations';
 
 export type TVariantStatus =
   | 'set' // has a valid value
@@ -153,8 +154,13 @@ export function buildVariantGroups(
     const empty = isOptionValueEmpty(field?.value);
     const ownGroups: string[] = schema?.required_groups || [];
     // Member of a one-of group that nobody has satisfied yet.
-    const inUnmetGroup = ownGroups.some((k) => reqGroups[k] && !reqGroups[k].satisfied);
-    const required = !!schema?.required;
+    // A field locked by an unmet `depends_on` does not apply yet, so it is
+    // neither required nor part of an unmet group — the engine's rule.
+    const locked =
+      !!schema?.depends_on && !hasAllDependenciesFullfilled(schema.depends_on, values, options);
+    const inUnmetGroup =
+      !locked && ownGroups.some((k) => reqGroups[k] && !reqGroups[k].satisfied);
+    const required = !locked && !!schema?.required;
 
     let status: TVariantStatus;
     let reason: string | undefined;
@@ -183,7 +189,8 @@ export function buildVariantGroups(
       label: (schema?.display_name as string) || name,
       shortDesc: schema?.short_desc,
       longDesc: schema?.desc,
-      required: required || ownGroups.length > 0,
+      // The asterisk still marks it: it is required once it applies.
+      required: !!schema?.required || ownGroups.length > 0,
       readOnly: !!schema?.readonly,
       status,
       reason,

package/src/components/form/expressions/builder/index.tsx

@@ -24,7 +24,11 @@ import { darken, rgba } from 'polished';
 import React, { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import styled from 'styled-components';
 import { moveItem } from '../../../../helpers/common';
-import { areQorusTypesCompatible, getArgumentType } from '../../../../helpers/expressions';
+import {
+  areQorusTypesCompatible,
+  expressionFitsReturnType,
+  getArgumentType,
+} from '../../../../helpers/expressions';
 import { addMissingExpressionArgs } from '../argumentPresence';
 import { findTemplate } from '../../../../helpers/templates';
 import { validateField, validateFieldWithResult } from '../../../../helpers/validations';
@@ -594,6 +598,15 @@ export const Expression = ({
   const defaultItems = useMemo(
     () =>
       expressions.value
+        // a condition (a field or an operand that must be true or false) offers the operations that
+        // give true or false; a group's members are its own business, and the operation already chosen
+        // stays, so a stored mismatch can be seen and fixed
+        .filter(
+          (exp) =>
+            isChild ||
+            exp.name === value?.value?.exp ||
+            expressionFitsReturnType(returnType as string | string[] | undefined, exp)
+        )
         .map((exp) => ({
           name: exp.name,
           value: exp.name,
@@ -612,7 +625,7 @@ export const Expression = ({
               ? !exp.from_server
               : true
         ),
-    [JSON.stringify(expressions.value), serverExpression, level]
+    [JSON.stringify(expressions.value), serverExpression, level, isChild, returnType, value?.value?.exp]
   );
 
   // SEAM (reqraft): reqraft's `SelectFormField` calls `onChange(value)` with

package/src/components/form/fields/array/ArrayAuto.tsx

@@ -17,9 +17,10 @@ import {
   ReqoreVerticalSpacer,
   useReqoreProperty,
 } from '@qoretechnologies/reqore';
-import { map, size } from 'lodash';
+import { isEqual, map, size } from 'lodash';
 import { useEffect, useState } from 'react';
 import { useDebounce } from 'react-use';
+import { useEmittedValues } from '../emittedValues';
 import { validateFieldWithResult } from '../../../../helpers/validations';
 import { useWhyDidYouUpdate } from '../../../../hooks/useWhyDidYouUpdate';
 // Direct imports — the cycle (ArrayAuto → TemplateField/auto → ArrayAuto) is
@@ -81,12 +82,20 @@ export const ArrayAuto = ({
     ...rest,
   });
 
+  // The parent's echo of an emit still in flight is not a change: copying it
+  // over the local list lost what was edited since. See `EmittedValues`.
+  const emitted = useEmittedValues<unknown>(isEqual);
+
   useEffect(() => {
+    if (emitted.isEcho(value)) {
+      return;
+    }
     setLocalValue(value);
   }, [JSON.stringify(value)]);
 
   useDebounce(
     () => {
+      emitted.record(localValue);
       onChange?.(name, localValue);
     },
     300,

package/src/components/form/fields/array/ArrayAutoField.tsx

@@ -8,10 +8,11 @@ import {
   useReqoreProperty,
 } from '@qoretechnologies/reqore';
 import { IQorusFormSchema } from '@qoretechnologies/ts-toolkit';
-import { map, size } from 'lodash';
+import { isEqual, map, size } from 'lodash';
 import { recordIdentity } from '../../engine/readFirst';
 import React, { memo, useCallback, useEffect, useRef, useState } from 'react';
 import { useDebounce } from 'react-use';
+import { useEmittedValues } from '../emittedValues';
 import { validateFieldWithResult } from '../../../../helpers/validations';
 
 export interface IArrayAutoFieldProps {
@@ -77,12 +78,20 @@ export const ArrayAutoField = memo(
     const [editingIndex, setEditingIndex] = useState<number | null>(null);
     const inputKeyRef = useRef(0);
 
+    // The parent's echo of an emit still in flight is not a change: copying it
+    // over the local list lost what was edited since. See `EmittedValues`.
+    const emitted = useEmittedValues<unknown>(isEqual);
+
     useEffect(() => {
+      if (emitted.isEcho(value)) {
+        return;
+      }
       setLocalValue(value);
     }, [JSON.stringify(value)]);
 
     useDebounce(
       () => {
+        emitted.record(localValue);
         onChange(name, localValue);
       },
       300,

package/src/components/form/fields/auto/AutoFormField.tsx

@@ -819,9 +819,12 @@ function AutoField<T = any>({
                 );
               }
 
+              // the multi-select reads each item's `{type, value}` envelope itself, as Field.tsx gives it;
+              // handing it the unwrapped values left every choice `undefined`, so a pick stored an empty
+              // element and drew an "undefined" chip
               return (
                 <MultiSelectFormField
-                  items={mappedAllowedValues}
+                  items={rest.element_allowed_values}
                   value={formatFromServerValue(value)}
                   onChange={(selected) => {
                     handleChange(name, formatToServerValue(selected));

package/src/components/form/fields/binary/Binary.tsx

@@ -2,6 +2,7 @@ import { ReqoreControlGroup, ReqoreTextarea } from '@qoretechnologies/reqore';
 import { IReqoreTextareaProps } from '@qoretechnologies/reqore/dist/components/Textarea';
 import { ChangeEvent, memo, useCallback, useEffect, useState } from 'react';
 import { useDebounce } from 'react-use';
+import { useEmittedValues } from '../emittedValues';
 import { IFileFormFieldValue, ReqraftFileFormField } from '../file/File';
 
 export interface IReqraftBinaryFormFieldProps extends Omit<IReqoreTextareaProps, 'onChange' | 'value'> {
@@ -28,8 +29,14 @@ const stripDataUrlPrefix = (dataUrl: string): string => {
 export const ReqraftBinaryFormField = memo(
   ({ value, onChange, ...rest }: IReqraftBinaryFormFieldProps) => {
     const [localValue, setLocalValue] = useState<string>(value ?? '');
+    // The parent's echo of an emit still in flight is not a change: copying it
+    // over the local value lost what was typed since. See `EmittedValues`.
+    const emitted = useEmittedValues<string | undefined>();
 
     useEffect(() => {
+      if (emitted.isEcho(value)) {
+        return;
+      }
       if (value !== localValue) {
         setLocalValue(value ?? '');
       }
@@ -38,6 +45,7 @@ export const ReqraftBinaryFormField = memo(
     useDebounce(
       () => {
         if (localValue !== value) {
+          emitted.record(localValue);
           onChange?.(localValue);
         }
       },
@@ -53,6 +61,7 @@ export const ReqraftBinaryFormField = memo(
       (file?: IFileFormFieldValue) => {
         const base64 = stripDataUrlPrefix(file?.content ?? '');
         setLocalValue(base64);
+        emitted.record(base64);
         onChange?.(base64);
       },
       [onChange]
@@ -67,6 +76,7 @@ export const ReqraftBinaryFormField = memo(
           onChange={handleChange}
           onClearClick={() => {
             setLocalValue('');
+            emitted.record('');
             onChange?.('');
           }}
           placeholder='Base64-encoded binary value'

package/src/components/form/fields/emittedValues.ts

@@ -0,0 +1,62 @@
+import { useRef } from 'react';
+
+/**
+ * What a debounced field has told its parent and not yet heard back.
+ *
+ * A field that keeps a local copy of what is being typed reports it after a
+ * short pause, and the parent hands that value back down as the `value` prop —
+ * usually after its OWN debounce, so the echo of an emit arrives while the
+ * person is already typing the next character. Treating every incoming value
+ * as an external change copied that stale echo over the newer text: typing
+ * "ship-order" with 150 ms between keys left "shp-order".
+ *
+ * So an incoming value is first checked against what is in flight. One that
+ * matches an emit is the parent catching up, not a change, and it acknowledges
+ * that emit and every one before it (a parent that debounces skips some).
+ * Anything else is a genuine change from outside and replaces the local text;
+ * it also drops whatever was in flight, since the parent has moved past it.
+ *
+ * A genuine external change that happens to equal an emit still in flight is
+ * indistinguishable from its echo, and is treated as one — harmless, because it
+ * sets the very value the field already reported.
+ */
+export class EmittedValues<T> {
+  private pending: T[] = [];
+
+  /** Bounded: a parent that never feeds its value back never acknowledges. */
+  private static readonly LIMIT = 50;
+
+  constructor(private readonly equals: (a: T, b: T) => boolean = Object.is) {}
+
+  /** Record a value just reported to the parent. */
+  record(value: T): void {
+    this.pending.push(value);
+    if (this.pending.length > EmittedValues.LIMIT) {
+      this.pending.shift();
+    }
+  }
+
+  /**
+   * Whether `incoming` is the echo of an emit still in flight. An echo
+   * acknowledges that emit and every earlier one; anything else clears the
+   * in-flight list, because the parent has a value of its own.
+   */
+  isEcho(incoming: T): boolean {
+    const index = this.pending.findIndex((value) => this.equals(value, incoming));
+    if (index === -1) {
+      this.pending = [];
+      return false;
+    }
+    this.pending = this.pending.slice(index + 1);
+    return true;
+  }
+}
+
+/** One `EmittedValues` for the life of the component. */
+export const useEmittedValues = <T>(equals?: (a: T, b: T) => boolean): EmittedValues<T> => {
+  const ref = useRef<EmittedValues<T>>();
+  if (!ref.current) {
+    ref.current = new EmittedValues<T>(equals);
+  }
+  return ref.current;
+};

package/src/components/form/fields/long-string/LongString.tsx

@@ -7,6 +7,7 @@ import {
   hasLineBreak,
   isSingleLineStringType,
 } from '../../../../helpers/singleLineString';
+import { useEmittedValues } from '../emittedValues';
 
 export interface ILongStringFormFieldProps extends Omit<IReqoreTextareaProps, 'onChange'> {
   value?: string;
@@ -38,24 +39,41 @@ export const LongStringFormField = ({
      and reporting that difference marked every form holding an empty text
      field as changed before anyone typed. */
   const lastEmittedRef = useRef<string>(value ?? '');
+  /* The emits the parent has not handed back yet. Its echo of an earlier one
+     arrives while the next keys are being typed, and copying it over the text
+     lost them ("ship-order" typed 150 ms apart became "shp-order"). An echo is
+     the parent catching up, not a change; see `EmittedValues`. */
+  const emitted = useEmittedValues<string>();
+
+  const emit = useCallback(
+    (next: string) => {
+      lastEmittedRef.current = next;
+      emitted.record(next);
+      onChange?.(next);
+    },
+    [onChange, emitted]
+  );
 
   useEffect(() => {
-    if ((value ?? '') !== localValue) {
-      setLocalValue(value ?? '');
+    const incoming = value ?? '';
+    if (emitted.isEcho(incoming)) {
+      return;
+    }
+    if (incoming !== localValue) {
+      setLocalValue(incoming);
     }
     // A value from outside is not something to report back to whoever sent it.
-    lastEmittedRef.current = value ?? '';
+    lastEmittedRef.current = incoming;
   }, [value]);
 
   useDebounce(
     () => {
       if (localValue !== lastEmittedRef.current) {
-        lastEmittedRef.current = localValue;
-        onChange?.(localValue);
+        emit(localValue);
       }
     },
     100,
-    [localValue, onChange]
+    [localValue, emit]
   );
 
   const singleLine = isSingleLineStringType(type);
@@ -87,9 +105,11 @@ export const LongStringFormField = ({
 
   const handleClearClick = useCallback(() => {
     setLocalValue('');
-    onChange?.('');
+    // Reported at once, and recorded like any emit, so the debounce does not
+    // report it a second time and its echo is not mistaken for a change.
+    emit('');
     onClearClick?.();
-  }, [onChange, onClearClick]);
+  }, [emit, onClearClick]);
 
   return (
     <ReqoreTextarea

package/src/components/form/fields/number/Number.tsx

@@ -3,6 +3,7 @@ import { IReqoreInputProps } from '@qoretechnologies/reqore/dist/components/Inpu
 import { IReqoreFormTemplates } from '@qoretechnologies/reqore/dist/components/Textarea';
 import { ChangeEvent, useCallback, useEffect, useMemo, useState } from 'react';
 import { useDebounce } from 'react-use';
+import { useEmittedValues } from '../emittedValues';
 // Const-only usage at render time — the cycle (Number → TemplateField → Number)
 // is safe the same way Field → AutoFormField → Field is.
 import { TemplatesListProps } from '../template/TemplateField';
@@ -37,8 +38,14 @@ export const NumberFormField = ({
   ...rest
 }: INumberFormFieldProps) => {
   const [localValue, setLocalValue] = useState<number | string>(value ?? '');
+  // The parent's echo of an emit still in flight is not a change: copying it
+  // over the local value lost what was typed since. See `EmittedValues`.
+  const emitted = useEmittedValues<number | string | undefined>();
 
   useEffect(() => {
+    if (emitted.isEcho(value)) {
+      return;
+    }
     if (value !== localValue) {
       setLocalValue(value ?? '');
     }
@@ -47,6 +54,7 @@ export const NumberFormField = ({
   useDebounce(
     () => {
       if (localValue !== value) {
+        emitted.record(localValue);
         onChange?.(localValue);
       }
     },
@@ -75,6 +83,7 @@ export const NumberFormField = ({
 
   const handleResetClick = useCallback((): void => {
     setLocalValue(0);
+    emitted.record(0);
     onChange?.(0);
   }, [onChange]);
 

package/src/components/form/fields/rich-text/RichText.tsx

@@ -8,6 +8,7 @@ import { IReqoreTooltip } from '@qoretechnologies/reqore/dist/types/global';
 import { isEqual, size } from 'lodash';
 import { KeyboardEvent, memo, useCallback, useEffect, useMemo, useRef, useState } from 'react';
 import { useDebounce } from 'react-use';
+import { useEmittedValues } from '../emittedValues';
 import { flattenToSingleLine, hasLineBreak } from '../../../../helpers/singleLineString';
 import {
   renderTemplateItemDescriptions,
@@ -129,8 +130,15 @@ export const RichTextFormField = memo(({
      document from it would hand the editor a new tree on every keystroke —
      which it answers by replacing its content and moving the cursor to the end. */
   const lastTextRef = useRef(isText ? String(value ?? '') : '');
+  /* The parent's echo of an emit still in flight is not a change. It arrives
+     while the next keys are typed, and rebuilding the document from it threw
+     them away. See `EmittedValues`. */
+  const emitted = useEmittedValues<unknown>(isEqual);
 
   useEffect(() => {
+    if (emitted.isEcho(isText ? String(value ?? '') : value)) {
+      return;
+    }
     if (isText) {
       const text = String(value ?? '');
       if (text !== lastTextRef.current) {
@@ -148,11 +156,13 @@ export const RichTextFormField = memo(({
     () => {
       if (isText) {
         if (lastTextRef.current !== String(value ?? '')) {
+          emitted.record(lastTextRef.current);
           onChange?.(lastTextRef.current);
         }
         return;
       }
       if (!isEqual(localValue, value)) {
+        emitted.record(localValue);
         onChange?.(localValue);
       }
     },

package/src/components/form/fields/template/TemplateField.tsx

@@ -803,7 +803,10 @@ const TemplateFieldImpl = memo(
       }
     }, [JSON.stringify(templateValue)]);
 
-    const showTemplateToggle = allowCustomValues && allowTemplates && !rest.arg_schema;
+    // an editor that takes templates into its own text has no template mode to switch to: "Use Template"
+    // there emptied the field and showed nothing in its place
+    const showTemplateToggle =
+      allowCustomValues && allowTemplates && !rest.arg_schema && !editorHandlesTemplates;
 
     // Only a BRACED context ref (`$data:{…}` — machine-written, nobody types
     // one) renders as the picker chip (named via `resolveTemplateLabel`)

package/src/components/smartEditor/useLspSession.ts

@@ -132,6 +132,8 @@ export function useLspSession(
 
     c.onReady(setIsReady);
 
+    // the session ends when the editor goes: a connection it closes itself has not failed
+    let disposed = false;
     c.connect()
       .then(() => {
         // Initialize completed — mirror the captured server
@@ -152,12 +154,18 @@ export function useLspSession(
         setIsReady(true);
       })
       .catch((err) => {
+        if (disposed) {
+          // the editor went before the connection opened (Text mode left again, a form closed): it was
+          // closed on purpose, which is not a failure to report
+          return;
+        }
         // eslint-disable-next-line no-console
         console.error('[LSP session] Connect failed:', err);
         setIsReady(false);
       });
 
     return () => {
+      disposed = true;
       c.disconnect();
       clientRef.current = null;
       serverTextRef.current = null;

package/src/components/supportTicket/InterfaceReferenceTags.stories.tsx

@@ -3,6 +3,14 @@ import { expect, fn, userEvent, waitFor, within } from 'storybook/test';
 import { StoryMeta } from '../../types';
 import { InterfaceReferenceTags } from './InterfaceReferenceTags';
 import { IInterfaceReference } from './meta';
+import {
+  STORY_APP_LOGO,
+  STORY_BROKEN_IMAGE,
+  STORY_QOG_IMAGE,
+  storyBrokenKindMark,
+  storyKindMark,
+} from './__fixtures__/kindMarks';
+import { whenImageSettled } from './useLoadedImages';
 
 // Several references, including two of the same kind (workflow), as `{kind, name}`
 // snapshots — no `resolveInterfaceIcon` is passed, so the built-in per-kind default
@@ -169,3 +177,81 @@ export const Empty: Story = {
     await expect(within(canvasElement).queryByText('order-sync:1.2')).not.toBeInTheDocument();
   },
 };
+
+const QOG_REFERENCES: IInterfaceReference[] = [
+  { interface_kind: 'fsm', interface_name: 'order-flow', reference_id: 'q1' },
+  {
+    interface_kind: 'fsm',
+    interface_name: 'telegram-intake',
+    reference_id: 'q2',
+    logo: STORY_APP_LOGO,
+  },
+  { interface_kind: 'service', interface_name: 'notification-svc', reference_id: 'q3' },
+];
+
+const chipImages = (canvasElement: HTMLElement) =>
+  Array.from(canvasElement.querySelectorAll('.reqore-tag img')).map((img) =>
+    img.getAttribute('src')
+  );
+
+export const KindImage: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Renders references with a host resolver that gives a Qog an image (the green mark) and a font icon fallback. The plain Qog shows the image; the app-triggered Qog keeps its stored trigger-app logo, because by default a reference's own logo comes first; the service has no image and shows its font icon.",
+      },
+    },
+  },
+  args: { references: QOG_REFERENCES, resolveInterfaceIcon: storyKindMark },
+  async play({ canvasElement }) {
+    await waitFor(() =>
+      expect(chipImages(canvasElement).sort()).toEqual([STORY_APP_LOGO, STORY_QOG_IMAGE].sort())
+    );
+  },
+};
+
+export const KindImagePreferred: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the same references with preferKindImage: the kind image comes before a reference\'s own logo, so both Qogs show the green Qog mark and the service keeps its font icon.',
+      },
+    },
+  },
+  args: {
+    references: QOG_REFERENCES,
+    resolveInterfaceIcon: storyKindMark,
+    preferKindImage: true,
+  },
+  async play({ canvasElement }) {
+    await waitFor(() =>
+      expect(chipImages(canvasElement)).toEqual([STORY_QOG_IMAGE, STORY_QOG_IMAGE])
+    );
+  },
+};
+
+export const KindImageFailsToLoad: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a Qog reference whose kind image cannot load: the chip keeps the font icon instead of drawing a broken picture.',
+      },
+    },
+  },
+  args: {
+    references: [QOG_REFERENCES[0]],
+    resolveInterfaceIcon: storyBrokenKindMark,
+    preferKindImage: true,
+  },
+  async play({ canvasElement }) {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText('order-flow')).toBeInTheDocument();
+    // Once the load has failed, no picture is drawn.
+    await whenImageSettled(STORY_BROKEN_IMAGE);
+    await expect(chipImages(canvasElement)).toEqual([]);
+    await expect(canvasElement.querySelector('.reqore-tag .reqore-icon')).toBeTruthy();
+  },
+};

package/src/components/supportTicket/InterfaceReferenceTags.tsx

@@ -1,17 +1,24 @@
 import { ReqoreControlGroup, ReqoreP, ReqoreTag } from '@qoretechnologies/reqore';
 import { TSizes } from '@qoretechnologies/reqore/dist/constants/sizes';
-import { IReqoreIconName } from '@qoretechnologies/reqore/dist/types/icons';
 import { ComponentProps } from 'react';
-import { defaultInterfaceIcon, IInterfaceReference } from './meta';
+import {
+  defaultInterfaceIcon,
+  IInterfaceReference,
+  toInterfaceKindMark,
+  TResolveInterfaceIcon,
+} from './meta';
+import { useLoadedImages } from './useLoadedImages';
 
 export interface IInterfaceReferenceTagsProps {
   references?: IInterfaceReference[];
   /** Optional leading label, e.g. "References" in a ticket header. Omitted (the
    *  default) inside the thread, where the chips sit under a message. */
   label?: string;
-  /** Resolve a per-kind icon. Consumers with their own icon vocabulary (the IDE)
+  /** Resolve a per-kind icon: a font icon, or a mark `{ icon, image }` whose image
+   *  (e.g. the Qog logo) is drawn once it loads, with the font icon before that and
+   *  instead of it if it fails. Consumers with their own icon vocabulary (the IDE)
    *  pass one; when omitted the built-in per-kind default is used. */
-  resolveInterfaceIcon?: (kind: string) => IReqoreIconName;
+  resolveInterfaceIcon?: TResolveInterfaceIcon;
   /** Open a referenced interface; chips are static (informational) when omitted —
    *  e.g. the staff view, which can't reach the customer's instance. */
   onInterfaceClick?: (reference: IInterfaceReference) => void;
@@ -32,6 +39,21 @@ export interface IInterfaceReferenceTagsProps {
    *  qogs list does. When this (or the reference's own `logo`) returns a value, the
    *  chip shows the image in place of the kind icon. */
   resolveInterfaceImage?: (reference: IInterfaceReference) => string | undefined;
+  /**
+   * Which image a chip draws when there is more than one:
+   *
+   * - `false` (the default): the reference's own image first — its stored `logo`,
+   *   then `resolveInterfaceImage` — and the kind's image (from
+   *   `resolveInterfaceIcon`) only when it has neither. This is how chips have
+   *   always looked: an app-triggered Qog shows its trigger app's logo.
+   * - `true`: the kind's image first, then the reference's own. For a host that
+   *   draws every interface of a kind with one mark (the IDE's green Qog), so a
+   *   Qog reads as a Qog whatever app triggers it.
+   *
+   * Either way the kind's font icon shows until the chosen image loads, and
+   * instead of it if it cannot.
+   */
+  preferKindImage?: boolean;
 }
 
 /**
@@ -51,11 +73,22 @@ export const InterfaceReferenceTags = ({
   intent,
   customTheme,
   resolveInterfaceImage,
+  preferKindImage = false,
 }: IInterfaceReferenceTagsProps) => {
+  const resolveIcon = resolveInterfaceIcon ?? defaultInterfaceIcon;
+  const marks = (references ?? []).map((reference) => {
+    const mark = toInterfaceKindMark(resolveIcon(reference.interface_kind));
+    const own = reference.logo ?? resolveInterfaceImage?.(reference);
+    return {
+      reference,
+      icon: mark.icon,
+      image: preferKindImage ? (mark.image ?? own) : (own ?? mark.image),
+    };
+  });
+  const isLoaded = useLoadedImages(marks.map(({ image }) => image));
   if (!references?.length) {
     return null;
   }
-  const resolveIcon = resolveInterfaceIcon ?? defaultInterfaceIcon;
   return (
     <ReqoreControlGroup verticalAlign='center' wrap gapSize='small'>
       {label ? (
@@ -63,18 +96,18 @@ export const InterfaceReferenceTags = ({
           {label}
         </ReqoreP>
       ) : null}
-      {references.map((reference) => {
-        // an app-triggered qog shows the trigger app's logo (stored, or resolved by
-        // a viewer with the app catalogue); everything else shows its kind glyph.
-        const image = reference.logo ?? resolveInterfaceImage?.(reference);
+      {marks.map(({ reference, icon, image }) => {
+        // The chosen image (see `preferKindImage`) once it has loaded; the kind's
+        // font icon until then, and if it fails.
+        const loaded = isLoaded(image);
         return (
           <ReqoreTag
             key={
               reference.reference_id ??
               `${reference.interface_kind}:${reference.interface_name}`
             }
-            icon={image ? undefined : resolveIcon(reference.interface_kind)}
-            leftIconProps={image ? { image } : undefined}
+            icon={icon}
+            leftIconProps={loaded ? { image } : undefined}
             labelKey={reference.interface_kind}
             label={reference.interface_name}
             size={size}