@qoretechnologies/reqraft 0.10.54 → 0.10.55-pr.115.g37abdfc

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

@@ -0,0 +1,115 @@
+// Copyright 2026 Qore Technologies, s.r.o.
+import { ReqoreTag } from '@qoretechnologies/reqore';
+import { IReqoreFormTemplates } from '@qoretechnologies/reqore/dist/components/Textarea';
+import { memo } from 'react';
+import { IRichtextSegment } from '../../../../helpers/common';
+import {
+  findTemplate,
+  getTemplateTagStyle,
+  templateTooltip,
+  TTemplateMeta,
+} from '../../../../helpers/templates';
+
+export interface ITemplateTextProps {
+  /** Prose runs and reference chips, from `templateTextSegments` or
+   *  `richtextToSegments` — both produce the same shape on purpose. */
+  segments: IRichtextSegment[];
+  /** The catalogue the chips are named and explained from. */
+  templates?: IReqoreFormTemplates;
+  /**
+   * A read-only row is the ONLY rendering its value gets, so it wraps and shows
+   * every chip. An editable row's value line is a one-line summary you click to
+   * open, so it clips instead of growing the row.
+   */
+  full?: boolean;
+  className?: string;
+}
+
+/**
+ * Flattens the line breaks in one prose segment of a one-line SUMMARY.
+ *
+ * Every other value type reaches the collapsed row through
+ * `whiteSpace: 'nowrap'`, which collapses newlines for free. This renderer is
+ * the only one that opts into `'pre'` — it has to, or the space separating a
+ * word from the chip beside it is dropped — and `pre` also honours the
+ * newlines, which `nowrap` would have eaten.
+ *
+ * So a genuinely multi-line value (an alert rule's Gmail message body is five
+ * `\n`-separated lines) gave every segment after the first a blank first line.
+ * The wrapper centres its items, so a two-line-tall box centred against
+ * one-line chips put every word 12px below the chip beside it, and the row read
+ * as a staircase. Measured on supah: prose boxes 30px against 14px chips.
+ *
+ * A space, not nothing: consecutive prose segments are merged before they get
+ * here, so a value with a break and no chip between its lines would otherwise
+ * lose the word boundary entirely.
+ */
+const collapseSummaryBreaks = (text: string): string => text.replace(/\s*\r?\n\s*/g, ' ');
+
+/**
+ * A value that mentions template references, drawn for READING.
+ *
+ * One renderer, because a value that reads two ways depending on which surface
+ * shows it is the defect this exists to close: a skip-when predicate read
+ * `$._case.mode != 'simulate'` on the compact row while the editor it opens
+ * drew the same reference as a named chip.
+ *
+ * The literal text around a reference is the AUTHOR'S, and it survives exactly
+ * as typed — a predicate is a comparison they wrote, and only the reference in
+ * it is the thing the template mechanism exists to name.
+ *
+ * The chip is `ReqoreTag`, the same one `ReadOnlyTemplateTag` and the rich-text
+ * editor use, with the same `$`-icon, the same intent scheme
+ * (`getTemplateTagStyle`) and the same hover card (`templateTooltip`), so a
+ * reference looks identical wherever it is shown.
+ */
+export const TemplateText = memo(({ segments, templates, full, className }: ITemplateTextProps) => (
+  <span
+    className={`reqraft-template-text${className ? ` ${className}` : ''}`}
+    style={{
+      display: 'inline-flex',
+      alignItems: 'center',
+      gap: 4,
+      minWidth: 0,
+      maxWidth: '100%',
+      ...(full ? { flexWrap: 'wrap' } : { overflow: 'hidden' }),
+    }}
+  >
+    {segments.map((segment, index) =>
+      segment.kind === 'tag' ?
+        <ReqoreTag
+          key={`tag-${index}`}
+          className='reqraft-template-chip'
+          size='tiny'
+          // The chip's label has to be the same size as the prose it is embedded
+          // in. The wrapper centres boxes, so two different text sizes centred
+          // against each other cannot share a baseline and the chips visibly
+          // float above the words. Inheriting makes centring align the baselines
+          // too, at whatever font size the consuming app uses.
+          style={{ fontSize: 'inherit' }}
+          icon='ExchangeDollarLine'
+          label={segment.text || segment.value}
+          // The same card the chosen-template chip shows: what the value IS, not
+          // the reference that names it.
+          tooltip={templateTooltip(templates, segment.value || '')}
+          {...getTemplateTagStyle(
+            (templates ? findTemplate(templates, segment.value || '') : undefined)?.metadata as
+              | TTemplateMeta
+              | undefined
+          )}
+        />
+      : <span
+          key={`text-${index}`}
+          className='reqraft-template-prose'
+          // `pre`, not the row's `nowrap`: the single space that separates a
+          // word from the chip beside it is real content here, and collapsing
+          // it would join them. A read row keeps the newlines too.
+          style={{ whiteSpace: full ? 'pre-wrap' : 'pre' }}
+        >
+          {full ? segment.text : collapseSummaryBreaks(segment.text)}
+        </span>
+    )}
+  </span>
+));
+
+TemplateText.displayName = 'TemplateText';

package/src/components/form/index.tsx

@@ -24,8 +24,12 @@ export * from './fields/string/String';
 export * from './fields/template/ExampleValueModal';
 export * from './fields/template/TemplateField';
 export * from './engine/FormEngine';
+export * from './engine/FormFieldsSkeleton';
 export * from './engine/optionActions';
 export * from './engine/rendererTypes';
+// A host's own editor is a compact row's editor too, so the instruction a row
+// gives when the AUTHOR opens it into a picker is part of the public surface.
+export * from './engine/rowOpenPicker';
 export * from './expressions/types';
 export * from './expressions/useExpressions';
 // Named (not wildcard) so the `_resetRenderExpressionTransportForTests`

package/src/components/log/Log.stories.tsx

@@ -2,6 +2,7 @@ import { StoryObj } from '@storybook/react-vite';
 import { expect, fireEvent, fn } from 'storybook/test';
 import { Server } from 'mock-socket';
 import { sleep, testsClickButton, testsWaitForText } from '../../../__tests__/utils';
+import { storySocketUrl } from '../../stories/storyNetwork';
 import { StoryMeta } from '../../types';
 import { ReqraftLog } from './Log';
 
@@ -24,7 +25,7 @@ const meta = {
     mockdate: new Date('2024-01-01T08:00:00.000Z'),
   },
   async beforeEach() {
-    const url = `wss://hq.qoretechnologies.com:8092/log-test?token=${process.env.REACT_APP_QORUS_TOKEN}`;
+    const url = storySocketUrl('log-test');
     let server = new Server(url);
     let killTimeout: NodeJS.Timeout;
     let fakeInterval: NodeJS.Timeout;

package/src/components/searchFilterBar/SearchFilterBar.stories.tsx

@@ -19,9 +19,9 @@ const meta = {
         icon: 'Filter3Line' as const,
         label: 'Any status',
         items: [
-          { label: 'Any status', value: 'any', selected: true },
-          { label: 'Open', value: 'open' },
-          { label: 'Resolved', value: 'resolved' },
+          { label: 'Any status', selected: true, onClick: fn() },
+          { label: 'Open', onClick: fn() },
+          { label: 'Resolved', onClick: fn() },
         ],
       },
     ],

package/src/components/smartEditor/SmartEditor.tsx

@@ -18,7 +18,16 @@ import {
 } from '@qoretechnologies/reqore/dist/components/RichTextEditor';
 import { getReadableColor } from '@qoretechnologies/reqore/dist/helpers/colors';
 import { IReqoreTooltip } from '@qoretechnologies/reqore/dist/types/global';
-import React, { forwardRef, memo, useCallback, useImperativeHandle, useMemo, useRef } from 'react';
+import React, {
+  forwardRef,
+  memo,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useReducer,
+  useRef,
+} from 'react';
 import { Editor, NodeEntry, Range, Transforms } from 'slate';
 import { ReactEditor, RenderLeafProps } from 'slate-react';
 import { ILspSignatureHelp } from '../../utils/lspClient.types';
@@ -320,6 +329,14 @@ export const SmartEditor = forwardRef<TReqoreRichTextEditorRef, ISmartEditorProp
     // ReqoreRichTextEditor's tokenizer mid-token (typed `@s` collapses to a
     // tag chip, making the rest of the field name impossible to type).
     const slateValueRef = useRef<ISlateElement[] | null>(null);
+    /* Counts the node trees the editor has reported. The tree a value converts
+       to is not always the tree the editor holds: Slate normalises a value set
+       from outside — a leading chip gains an empty text leaf before it — without
+       changing its text, so `value` never changes and the cache above kept the
+       tree the editor no longer had. Every offset computed from it (token
+       colours, diagnostics, signature help) then pointed one leaf off: a Text
+       view seeded with `"$local:name" == "John"` was never highlighted. */
+    const [editorTreeVersion, noteEditorTree] = useReducer((count: number) => count + 1, 0);
 
     useImperativeHandle(ref, () => editorRef.current as TReqoreRichTextEditorRef, []);
 
@@ -350,7 +367,17 @@ export const SmartEditor = forwardRef<TReqoreRichTextEditorRef, ISmartEditorProp
       const next = converter.toSlateNodes(value);
       slateValueRef.current = next;
       return next;
-    }, [value, converter]);
+      // `editorTreeVersion` re-reads the cache once the editor reports its own tree.
+    }, [value, converter, editorTreeVersion]);
+
+    /* A value set from outside is a change to the document as much as typing
+       is — a Text view seeded after mount, a Preview following the author. The
+       server colours and diagnoses its own copy of the text, so it must hold
+       this one; typing already sent its text, and is not resent. */
+    const { didChange: syncDocument } = session;
+    useEffect(() => {
+      syncDocument(value);
+    }, [syncDocument, value]);
 
     const diagnosticDecorate = useLspDiagnosticDecorations(
       session.diagnostics,
@@ -450,15 +477,20 @@ export const SmartEditor = forwardRef<TReqoreRichTextEditorRef, ISmartEditorProp
       (newNodes: ISlateElement[]) => {
         const plainText = converter.fromSlateNodes(newNodes);
 
+        // A selection change reports the same tree; anything else is the tree
+        // the editor now holds, and the one every offset is computed against.
+        if (newNodes !== slateValueRef.current) {
+          slateValueRef.current = newNodes;
+          noteEditorTree();
+        }
+
         if (plainText !== lastPlainTextRef.current) {
           lastPlainTextRef.current = plainText;
-          // CRITICAL: refresh `slateValueRef` to the live nodes too. The
-          // next render's `value` equals `lastPlainTextRef` (the typing
-          // echo), so `slateValue`'s cache returns this ref — leave it
-          // stale and downstream hooks (signature help, semantic tokens)
-          // never recompute, so the signature pill's active parameter
-          // never advances.
-          slateValueRef.current = newNodes;
+          // CRITICAL: the next render's `value` equals `lastPlainTextRef` (the
+          // typing echo), so `slateValue`'s cache returns the live nodes set
+          // above — leave them stale and downstream hooks (signature help,
+          // semantic tokens) never recompute, so the signature pill's active
+          // parameter never advances.
           onChange(plainText);
           session.didChange(plainText);
         }

package/src/components/smartEditor/__fixtures__/mockLspServer.ts

@@ -2,8 +2,10 @@
 // (heartbeat, initialize, document tracking, request dispatch); story files
 // register only their language-specific handlers.
 import { Client, Server } from 'mock-socket';
+import { storySocketUrl } from '../../../stories/storyNetwork';
 
-export const MOCK_LSP_URL = `wss://hq.qoretechnologies.com:8092/lsp?token=${process.env.REACT_APP_QORUS_TOKEN}`;
+/** Where `ReqraftLspClient` dials by default, on the instance stories use. */
+export const MOCK_LSP_URL = storySocketUrl('lsp');
 
 // LSP-standard 16-type / 6-modifier legend, as the real Qorus server
 // advertises in `initialize` (qorus/Classes/QorusLspWebSocketHandler.qc:847).
@@ -76,31 +78,69 @@ export interface IMockLspServer {
   received: IMockLspMessage[];
   connectionCount: number;
   getOpenConnectionCount: () => number;
-  // Most-recent document text from didOpen / didChange.
+  // Most-recent document text from didOpen / didChange, whichever document.
   documentText: string;
+  /**
+   * The text of every open document, by URI. Clients share ONE socket per
+   * endpoint and open a document each — an editor and several read-only
+   * renderings at once — so a per-document answer (semantic tokens) must read
+   * its own document, not whichever one changed last.
+   */
+  textOf: (uri?: string) => string;
   delays: Record<string, number>;
   notify: (method: string, params: unknown) => void;
   close: () => void;
 }
 
+/* One mock per URL at a time. `.storybook/preview.tsx` starts a default DPQL
+   language server for every story, and a story that needs its own handlers
+   creates a server on the same URL; mock-socket refuses a second server there,
+   so creating one replaces whichever is listening. */
+const activeServers = new Map<string, IMockLspServer>();
+
 export const createMockLspServer = (
   url: string,
   options: IMockLspServerOptions = {}
 ): IMockLspServer => {
+  // No connection reset here: `.storybook/preview.tsx` resets the shared LSP
+  // connections (and the expression render client) before every story, which
+  // covers stories that never create a mock server as well as those that do.
+  activeServers.get(url)?.close();
   const server = new Server(url);
   const sockets: Client[] = [];
+  const documents = new Map<string, string>();
+  let closed = false;
   const lsp: IMockLspServer = {
     received: [],
     connectionCount: 0,
     getOpenConnectionCount: () => sockets.filter((socket) => socket.readyState === 1).length,
     documentText: '',
+    textOf: (uri) => (uri !== undefined && documents.has(uri) ? documents.get(uri)! : lsp.documentText),
     delays: { ...options.delays },
     notify: (method, params) =>
       sockets.forEach((socket) =>
         socket.send(JSON.stringify({ jsonrpc: '2.0', method, params }))
       ),
-    close: () => server.close(),
+    close: () => {
+      /* Once only. mock-socket finds clients by URL, not by server, so closing a
+         server that was already replaced would close its REPLACEMENT's clients
+         — and the default server is closed twice when a story replaces it: once
+         on replacement, once in the preview's teardown. */
+      if (closed) {
+        return;
+      }
+      closed = true;
+      if (activeServers.get(url) === lsp) {
+        activeServers.delete(url);
+      }
+      server.close();
+      // `close()` drops the clients but leaves mock-socket's WebSocket installed
+      // on the page; only `stop()` puts the real one back. Without it a story
+      // that reaches a real server (`parameters.live`) dials the mock instead.
+      server.stop();
+    },
   };
+  activeServers.set(url, lsp);
 
   server.on('connection', (socket) => {
     lsp.connectionCount++;
@@ -119,14 +159,23 @@ export const createMockLspServer = (
       }
       lsp.received.push(msg);
 
+      const uri = msg.params?.textDocument?.uri;
       if (msg.method === 'textDocument/didOpen') {
         lsp.documentText = msg.params?.textDocument?.text ?? '';
+        if (uri !== undefined) {
+          documents.set(uri, lsp.documentText);
+        }
       } else if (msg.method === 'textDocument/didChange') {
         // The client sends a single full-document content change.
         const change = msg.params?.contentChanges?.[0];
         if (change && typeof change.text === 'string') {
           lsp.documentText = change.text;
+          if (uri !== undefined) {
+            documents.set(uri, change.text);
+          }
         }
+      } else if (msg.method === 'textDocument/didClose' && uri !== undefined) {
+        documents.delete(uri);
       }
 
       const handler = options.handlers?.[msg.method];

package/src/components/smartEditor/useLspSession.ts

@@ -77,7 +77,11 @@ export interface IUseLspSessionResult {
    * only fires when `capabilities?.signatureHelpProvider` exists).
    */
   capabilities: ILspServerCapabilities | null;
-  /** Forward content changes to the server via `didChange`. */
+  /**
+   * The editor now holds `text`: the server is sent it via `didChange`, or via
+   * `didOpen` if the document is not open yet. Text the server already holds
+   * is not resent, so it is safe to call for every value the editor shows.
+   */
   didChange: (text: string) => void;
   /**
    * Request `textDocument/completion` at a plain-text offset. Converts
@@ -96,6 +100,13 @@ export function useLspSession(
 
   const clientRef = useRef<ReqraftLspClient | null>(null);
   const versionRef = useRef(1);
+  /* The text the editor holds, and the text the server holds for this
+     document — `null` until the document is open. The server tokenises and
+     diagnoses ITS copy, so every text the editor shows has to reach it, however
+     it got there: typed, or set from outside after mount (a Text view seeded
+     once `dpql/serialize` answers, a Preview following the typing). */
+  const editorTextRef = useRef(initialText);
+  const serverTextRef = useRef<string | null>(null);
   const uriRef = useRef(uriProp ?? `${languageId}://session/${++lspUriCounter}`);
 
   const [client, setClient] = useState<ReqraftLspClient | null>(null);
@@ -129,8 +140,11 @@ export function useLspSession(
         // result.
         setSemanticTokensLegend(c.semanticTokensLegend);
         setCapabilities(c.capabilities);
+        // Opened with the text the editor holds NOW, which may have been set
+        // while the connection was opening.
+        serverTextRef.current = editorTextRef.current;
         c.didOpen(
-          initialText,
+          editorTextRef.current,
           initialMetadata && Object.keys(initialMetadata).length > 0
             ? initialMetadata
             : undefined
@@ -146,6 +160,7 @@ export function useLspSession(
     return () => {
       c.disconnect();
       clientRef.current = null;
+      serverTextRef.current = null;
       setClient(null);
       setIsReady(false);
       setSemanticTokensLegend(null);
@@ -158,8 +173,11 @@ export function useLspSession(
   }, []);
 
   const didChange = useCallback((text: string) => {
+    editorTextRef.current = text;
     const c = clientRef.current;
-    if (!c) return;
+    // Not open yet: `didOpen` will carry it. Already held: nothing to send.
+    if (!c || serverTextRef.current === null || serverTextRef.current === text) return;
+    serverTextRef.current = text;
     c.didChange(text, ++versionRef.current);
   }, []);
 

package/src/components/supportTicket/TicketReplyBox.tsx

@@ -1,11 +1,15 @@
-import { ReqoreDropdown } from '@qoretechnologies/reqore';
-import { ComponentProps, ReactNode } from 'react';
+import type { TReqoreDropdownItems } from '@qoretechnologies/reqore/dist/components/Dropdown/list';
+import { ReactNode } from 'react';
 import { Composer, IComposerSendAction, TComposerEditor } from '../composer/Composer';
 import { fileToAttachment as defaultFileToAttachment } from './fileToAttachment';
 import { IAttachmentUpload } from './meta';
 
-/** The exact `items` shape ReqoreDropdown accepts — no import-path guessing. */
-type TAttachMenuItems = NonNullable<ComponentProps<typeof ReqoreDropdown>['items']>;
+/**
+ * The `items` shape ReqoreDropdown accepts. Named, not derived: `ReqoreDropdown`
+ * is a generic component, and `ComponentProps` of a generic resolves to `{}`
+ * under strict checking — so the derived type had no `items` at all.
+ */
+type TAttachMenuItems = TReqoreDropdownItems;
 
 export interface ITicketReplyBoxProps {
   /** Send the composed message. `internal` is only ever true when

package/src/components/ticketThread/TicketThread.stories.tsx

@@ -4,6 +4,7 @@ import styled from 'styled-components';
 
 import { thinScrollbar } from '../../helpers/scrollbar';
 import { StoryMeta } from '../../types';
+import type { IInterfaceReference, TTicketMessageAuthor } from '../supportTicket/meta';
 import { ITicketThreadMessage, TicketThread } from './TicketThread';
 
 /* The drawer body's scroll area — the thin Qorus scrollbar rather than the platform

package/src/helpers/common.ts

@@ -79,11 +79,15 @@ export const getDefaultValue = (schema?: TQorusFormFieldSchema): unknown | undef
     return undefined;
   }
   if ('default_value' in schema) {
-    if (schema.default_value != null && typeof schema.default_value === 'object') {
-      return schema.default_value.value;
+    const value: unknown = schema.default_value;
+    // The server sends a default either bare, of any type — a list or a hash
+    // included — or in a `{ type, value }` envelope; only the envelope is
+    // unwrapped.
+    if (value != null && typeof value === 'object' && !Array.isArray(value) && 'type' in value) {
+      return (value as { value?: unknown }).value;
     }
 
-    return schema.default_value;
+    return value;
   }
 
   return undefined;

package/src/helpers/dpqlDetection.ts

@@ -0,0 +1,209 @@
+// Copyright 2026 Qore Technologies, s.r.o.
+/**
+ * Noticing that text typed into a PLAIN (non-expression) field is really a
+ * DPQL expression, and deciding what to do about it.
+ *
+ * The rule this implements, in one sentence: **switch the field into
+ * expression mode only when the text cannot be a valid literal for the
+ * field's type but IS a real expression; otherwise offer, never silently
+ * reinterpret.** Quietly turning the string `a + b` into a concatenation on a
+ * `string` field would destroy a legitimate literal, so a type that accepts
+ * any text never auto-switches — it only ever offers.
+ *
+ * ## Why the server has the last word
+ *
+ * "Does this parse as DPQL?" is NOT a usable test, which is the trap here.
+ * Verified against the live LSP: `dpql/parse` reports `success: true` for
+ * `hello`, for `42`, for `2026-09-06` and for `@a` — it wraps each of them in
+ * a trivial `{exp: 'value', args: [...]}` node. Everything is a valid DPQL
+ * program, because a bare literal is one. So a text that parses tells us
+ * nothing; what tells us something is the SHAPE of the AST that comes back:
+ *
+ * | typed text        | `exp`      | verdict    |
+ * |-------------------|------------|------------|
+ * | `hello`, `42`     | `value`    | a literal  |
+ * | `$local:count`    | `template` | a template |
+ * | `@a > 5`          | `>`        | expression |
+ * | `"a" + "b"`       | `+`        | expression |
+ * | `toInt("5")`      | `toInt`    | expression |
+ *
+ * `isRealExpressionAst` is that test, and it is the only authority. The
+ * lexical pass below decides nothing — its sole job is to keep a server
+ * round-trip off every keystroke of every field.
+ */
+import { validateField } from './validations';
+
+/** What to do about text that turned out to be an expression. */
+export type TDpqlDetectionOutcome =
+  /** Not an expression, or not one we may act on — leave the field alone. */
+  | 'none'
+  /** A real expression, but the text is also a valid literal here: ask. */
+  | 'offer'
+  /** A real expression, and the text cannot be a literal here: switch. */
+  | 'switch';
+
+/**
+ * The `exp` values that mean "this is not an expression": a bare literal and
+ * a bare template reference. A template is already the template field's job
+ * (`isValueTemplate`), and a literal is what the plain field is for.
+ */
+const NON_EXPRESSION_OPS = new Set(['value', 'template']);
+
+/**
+ * Operators and calls whose presence makes a server probe worth the trip.
+ * Deliberately generous — a false positive costs one debounced request that
+ * comes back `exp: 'value'`, while a false negative silently loses the whole
+ * feature.
+ *
+ * ## Why the spacing rules differ per operator
+ *
+ * `-` and `/` are ambiguous: they appear inside values nobody means as
+ * arithmetic — dates (`2026-09-06`), negative numbers (`-5`), paths (`a/b`),
+ * hyphenated names (`well-known-name`). A space next to one is what separates
+ * `@a - 1` from those, so they keep a spacing requirement.
+ *
+ * `+` is NOT ambiguous in that way, and requiring spaces around it lost the
+ * feature for the most natural way to type arithmetic: `2 + 1` was offered as
+ * an expression while `2+1` and `2+ 1` were not, which reads as the detection
+ * working only sometimes. Reported from the live IDE. `+` now counts wherever
+ * it appears; if the text turns out to be an ordinary literal the server says
+ * so and the offer never appears.
+ *
+ * The `-`/`/` rule is also relaxed from "spaces on BOTH sides" to "a space on
+ * either side", so `@a -1` and `@a- 1` are probed too while every ambiguous
+ * value above still is not.
+ */
+const DPQL_OPERATOR_PATTERN = new RegExp(
+  [
+    '(==|!=|<>|>=|<=)', // two-character comparisons
+    '[<>*%]', // unambiguous single-character operators
+    '(?<!=)=(?!=)', // a lone `=`, not part of `==`
+    '\\+', // `+` — unambiguous, so spacing is irrelevant
+    '(\\s[-/]|[-/]\\s)', // `-` and `/` need a space on at least one side
+    '\\b(and|or|not|like|in|contains)\\b', // word operators
+  ].join('|'),
+  'i'
+);
+
+/** A function call — `toInt("5")`, `upper(@name)`. */
+const DPQL_CALL_PATTERN = /\b[a-z_]\w*\s*\(/i;
+
+/**
+ * The longest text worth probing. An expression a person types into a form
+ * field is short; anything longer is a document, and probing it on every
+ * keystroke would be a waste of a round-trip.
+ */
+const MAX_PROBE_LENGTH = 512;
+
+/**
+ * Cheap, purely lexical "might this be worth asking the server about?".
+ * Never decides anything on its own — see the module comment.
+ */
+export const mightBeDpqlExpression = (text: unknown): boolean => {
+  if (typeof text !== 'string') {
+    return false;
+  }
+
+  const trimmed = text.trim();
+
+  if (!trimmed || trimmed.length > MAX_PROBE_LENGTH) {
+    return false;
+  }
+
+  return DPQL_OPERATOR_PATTERN.test(trimmed) || DPQL_CALL_PATTERN.test(trimmed);
+};
+
+/**
+ * The authority: does this `dpql/parse` result describe a REAL expression
+ * rather than a literal or a bare template reference? Accepts either the
+ * field-ready envelope (`{is_expression, value: {exp, args}}`) the server
+ * returns or a bare `{exp, args}` node.
+ */
+export const isRealExpressionAst = (expression: unknown): boolean => {
+  if (!expression || typeof expression !== 'object') {
+    return false;
+  }
+
+  const envelope = expression as { value?: unknown; exp?: unknown };
+  const node = (
+    envelope.exp === undefined && envelope.value && typeof envelope.value === 'object'
+      ? envelope.value
+      : envelope
+  ) as { exp?: unknown };
+
+  return typeof node.exp === 'string' && !!node.exp && !NON_EXPRESSION_OPS.has(node.exp);
+};
+
+/**
+ * `true` when any diagnostic is an outright error. The server reports
+ * severity as the string `'error'` on this route and LSP proper uses `1`;
+ * both are accepted rather than assuming one.
+ */
+export const hasErrorDiagnostic = (
+  diagnostics?: Array<{ severity?: number | string } | undefined | null>
+): boolean =>
+  !!diagnostics?.some((diagnostic) => {
+    const severity = diagnostic?.severity;
+    return severity === 1 || severity === 'error';
+  });
+
+/**
+ * Could this text stand as a literal value of the field's own type? A type
+ * that accepts any text (`string`, and every type the form validator passes
+ * by default) always can, which is exactly why such a field never
+ * auto-switches. Delegates to the form's own validator so the answer is the
+ * same one the field itself would give.
+ */
+export const canBeLiteralOfType = (
+  text: string,
+  type?: string,
+  field?: Record<string, any>
+): boolean => {
+  if (!type) {
+    return true;
+  }
+
+  try {
+    return validateField(type, text, field as any);
+  } catch {
+    // A validator that throws must not be read as "this cannot be a
+    // literal" — that would auto-switch the field on the strength of a bug.
+    return true;
+  }
+};
+
+export interface IClassifyTypedTextArgs {
+  /** The text the author typed into the plain field. */
+  text: string;
+  /** The field's declared type (`ui_type ?? type`). */
+  type?: string;
+  /** The field schema, for validators that consult `validation_regex` etc. */
+  field?: Record<string, any>;
+  /** The `dpql/parse` result for `text`, or `undefined` if it has not run. */
+  parsed?: {
+    success?: boolean;
+    expression?: unknown;
+    diagnostics?: Array<{ severity?: number | string }>;
+  };
+}
+
+/**
+ * The whole decision, in one pure function so it can be tested without a
+ * server, a socket or a rendered field.
+ */
+export const classifyTypedText = ({
+  text,
+  type,
+  field,
+  parsed,
+}: IClassifyTypedTextArgs): TDpqlDetectionOutcome => {
+  if (!parsed?.success || !parsed.expression) {
+    return 'none';
+  }
+
+  if (!isRealExpressionAst(parsed.expression) || hasErrorDiagnostic(parsed.diagnostics)) {
+    return 'none';
+  }
+
+  return canBeLiteralOfType(text, type, field) ? 'offer' : 'switch';
+};