@qoretechnologies/reqraft 0.10.62 → 0.10.63-pr.142.g0b675cd

package/design/FORM_ENGINE_COMPACT_UX_PLAN.md

@@ -1,353 +0,0 @@
-# FormEngine Compact — UX Improvement Plan
-
-> Status: **proposal / for review.** Nothing here is implemented yet.
-> Scope: the compact ("read-first") `FormEngine` that will replace the classic
-> engine in the IDE. Goal: keep its density but make it feel **calm, scannable,
-> and guiding** instead of crowded and alarming.
-
----
-
-## 0. TL;DR
-
-The compact engine's *information architecture is right* (read-first rows you
-drill into). What's wrong is **visual signal management**: it currently runs
-**five overlapping status systems at once** and treats *untouched draft fields*
-as **hard red errors**. The result reads like a form that's on fire when it's
-actually just unfinished.
-
-Three changes do ~80% of the work:
-
-1. **Collapse the 5 status systems into 1.** One global completion signal at the
-   top; demote/remove the redundant red banner and the per-group/per-row status
-   pills.
-2. **Reframe "errors" as "to-dos."** Don't show red validation errors on fields
-   the user hasn't touched. *Unset ≠ error.* Validate on interaction/submit.
-3. **Lock a strict one-line row template** and push everything variable
-   (descriptions, error reasons, nested previews, default hints) **behind
-   progressive disclosure**. One scannable line per field by default.
-
-Everything else (calmer value chips, less chrome, smarter ordering, a "what's
-next" path) compounds these.
-
----
-
-## 1. North star
-
-> A configuration **summary you can read top-to-bottom in seconds**, that quietly
-> tells you *what's done, what's left, and what to do next* — and gets out of the
-> way when you're just scanning.
-
-The audience is technical (developers configuring Qorus interfaces). They *want*
-density — the model is a **good data table / code editor**, not a consumer
-wizard. So the goal is **"calm density,"** not fewer fields. Think: the
-difference between a well-set spreadsheet and a ransom note.
-
----
-
-## 2. What's wrong today (diagnosis)
-
-Grounded in the screenshots + the implementation
-([`CompactToolbar.tsx`](../src/components/form/engine/CompactToolbar.tsx),
-[`CompactRow.tsx`](../src/components/form/engine/CompactRow.tsx),
-[`FormEngine.tsx`](../src/components/form/engine/FormEngine.tsx),
-[`compactRowStyles.ts`](../src/components/form/engine/compactRowStyles.ts)).
-
-### 2.1 Five competing status systems
-At one glance the user is shown completeness/validity **five different ways**:
-
-| # | System | Where | Code |
-|---|--------|-------|------|
-| 1 | Draft badge + `12/21 fields set` + progress bar + `57%` | header | `CompactToolbar` `StyledCompletion` |
-| 2 | Red banner: "6 fields are not valid… click to only show invalid" | header | `CompactToolbar` invalid banner |
-| 3 | Per-group pills: `4 OPTIONAL`, `5 TO RESOLVE` | group headers | `FormEngine.tsx:1973` |
-| 4 | Per-row red stripe + red ⓘ button + inline red message box | each invalid row | `CompactRow` tier-1 `StyledInfoPanel` |
-| 5 | Per-row Draft chip / required asterisk / ⓘ toggle | each row | `CompactRow` `draftChip`, asterisk |
-
-These don't reinforce — they **compete**. The user can't tell which is the
-"real" status, so the whole UI reads as urgent. (NN/g *Aesthetic & minimalist
-design*: every extra unit of status dilutes the rest.)
-
-### 2.2 Premature, alarmist validation
-The form is in **DRAFT**, yet untouched fields show **hard red errors** —
-"Text value is empty," "Hash arguments are invalid," "Required — not set." Two
-problems:
-
-- **Unset is not an error.** Showing red on fields the user hasn't even reached
-  punishes them for not-yet-doing-something. This is the single biggest driver
-  of the "overwhelming" feeling. (Baymard / NN/g on inline validation: validate
-  **on blur or on submit**, not aggressively on load; reserve red for *wrong*,
-  not *empty*.)
-- **The error chrome is layout-disruptive.** Full-width dark-red `ReqoreMessage`
-  boxes render *between rows*, shoving content down and shattering the table
-  rhythm that makes the form scannable. Six of them = a wall of red.
-
-### 2.3 No focal point / flat hierarchy
-Every row carries roughly equal visual weight; labels, values, blue chips,
-swatches, nested trees and error boxes all shout at the same volume. There's no
-"look here first," no obvious **next action**. The eye bounces. (Visual
-hierarchy via size/weight/colour/space is absent within the row grid.)
-
-### 2.4 Inconsistent row anatomy breaks scannability
-Rows are one line (`Option with value · 123`), or two (label + sub-description),
-or three+ (label + value + inline error box), or have an embedded object tree
-with "Show more." The **grid rhythm** — the thing that makes a dense list
-scannable — is constantly broken by inline variants rendered **by default**.
-
-### 2.5 The value column has no consistent visual language
-Plain text, **saturated-blue template chips** (`Test (local)`, `Richtext
-Template`), colour swatch + hex, file pill, nested data tree — each a different
-weight and colour. The blue chips in particular are *louder than the field
-labels*, so decoration outshouts meaning. (Tufte: colour should encode data, not
-ornament.)
-
-### 2.6 Heavy non-data "chrome"
-Recessed value surfaces, intent stripes, group spines, required-group rails,
-dividers, hover fills — a lot of subtle lines/fills create a **busy texture**
-before any content is read. (Tufte *data-ink ratio*: most separators could be
-whitespace.)
-
-### 2.7 Weak grouping semantics
-"General" is a vague catch-all; "Optional/General" isn't a meaning the user
-reasons with. 21 fields in 2 buckets, ordered by schema, with no
-prioritisation. Findability relies on the filter box.
-
----
-
-## 3. Principles we'll design to
-
-| Principle | Source | Applied here |
-|---|---|---|
-| **One primary status channel** | NN/g *Visibility of system status* + *Minimalist design* | Collapse 5 status systems → 1 meter |
-| **Validate at the right time** | Baymard; NN/g *Error prevention* | Unset ≠ error; validate on blur/submit |
-| **Severity = colour, not area** | Tufte; Material/Carbon error patterns | Replace red boxes with a dot/accent |
-| **Progressive disclosure** | NN/g | One line per row; reveal the rest on demand |
-| **Data-ink ratio** | Tufte | Whitespace > borders for separation |
-| **Recognition over recall** | NN/g | Read-first rows (already good) — keep |
-| **Chunking ~5–7** | Miller's law | Smaller, purpose-named groups |
-| **Ask only what's needed** | GOV.UK *question protocol* | Defer/hide rarely-used optional fields |
-| **Error summary + adjacent message** | GOV.UK Design System | A navigable "needs attention" section, not a red bar |
-
-The throughline: **the IDE audience tolerates density but not noise.** Cut
-*ink*, not *information*.
-
----
-
-## 4. The redesign — concrete moves
-
-### 4.1 Collapse 5 status systems into 1
-
-**Keep** the top completion strip as the *single* global status. **Evolve it** so
-it carries everything the other four systems were saying:
-
-- Segment the bar into **set-&-valid / needs-attention / unset** (e.g. green /
-  amber / track), so "57% done, 6 need attention" is legible in one glance —
-  no separate red banner needed.
-- The **"6 need attention"** count becomes a quiet, clickable affordance *on the
-  meter* ("→ 6 to resolve") that filters to those fields. This replaces the
-  red banner (system #2) with a calm, constructive control.
-- **Drop the per-group `4 OPTIONAL` pill entirely** (the group is already
-  labelled "Optional"). Keep a per-group "N to resolve" **only when > 0**, muted
-  and right-aligned — or better, a thin per-group progress underline.
-- **Demote the per-row Draft chip**: the *global* Draft state is enough; per-row,
-  "changed" is better shown by the revert ↺ affordance alone.
-
-Net: the user has **one** place to read status, and **one** click to act on it.
-
-### 4.2 Errors → To-dos (validation timing & severity)
-
-Introduce a 3-state model for a field's status, and **stop conflating them**:
-
-| State | Meaning | Default treatment |
-|---|---|---|
-| **Unset** | No value, not required | Muted `—` / "Not set". **No alarm.** |
-| **To-do** | Required (or required-group) but unset, untouched | **Quiet amber** dot + "Needs a value". Not red, not a box. |
-| **Invalid** | User entered something that fails validation | **Red**, but only **after the field is touched** or **after a submit attempt**. |
-
-Rules:
-- **Untouched required fields are to-dos, not errors.** In a DRAFT, "Required —
-  not set" should be a calm amber hint, not a red error with a full-width box.
-- **Validation fires on blur / on submit**, not on load. Track a per-field
-  `touched` flag (or a form-level `submitAttempted`).
-- **The error reason moves off the default row.** Show at most a 1-word/short
-  inline hint after the value ("empty", "invalid"); the full message appears
-  **only when the row is focused/expanded** (where the editor's own message strip
-  already lives) or in the "needs attention" summary.
-
-This one change removes the wall of red in the screenshot: those six boxes become
-calm amber to-dos until the user engages or hits Submit.
-
-### 4.3 The row: one strict template + progressive disclosure
-
-Lock a **constant 3-zone row** and keep it one line by default:
-
-```
-[ icon? · Label · req-dot ]   [ value summary ……………… ]   [ status · actions ]
-            label col                 value col (ellipsis)        fixed right
-```
-
-- **Constant height, constant alignment, constant zones.** The current grid is
-  already close (`StyledGroupBody .readfirst-row`); the fix is *what we allow to
-  break it.*
-- **Move out of the default row, behind disclosure (ⓘ / focus / expand):**
-  - field **descriptions / subtitles** (currently inline under the label),
-  - **error/validation messages** (currently full-width boxes),
-  - **default-value hints**,
-  - **nested object/hash previews** (the `schemaOption2 → Show more` tree) →
-    collapse to the "Object · 1 field" summary; reveal the tree only on expand.
-- Result: a 21-field form is **21 scannable lines**, each of which *can* expand —
-  rather than a variable-height stack you have to parse.
-
-### 4.4 Value language: calm & consistent
-
-- **Desaturate the template chips.** `Test (local)` / `Richtext Template`
-  currently use saturated blue and outshout the labels. Use a quiet, low-contrast
-  chip (subtle surface + the `$` template glyph) so the **label leads** and the
-  value supports. Reserve saturated colour for *state* (to-do/invalid), not for
-  *value type*.
-- **One muted weight for all "set" values** (text, hex, filename, count). The
-  swatch/file-icon/`$`-glyph carry the type; the text stays uniform.
-- **"Not set" gets the lightest possible treatment** (muted, no italics arms-race
-  with errors) so empty rows visually *recede* rather than read as problems.
-
-### 4.5 Reduce chrome (data-ink)
-
-- Replace the **red left stripe + red box + red ⓘ** trio with a **single status
-  dot** in the right-hand status slot (colour = severity). One mark, not three.
-- **Whitespace over borders.** Drop the recessed value-surface fill and the
-  group spine where they don't encode meaning; let alignment + a little more
-  vertical rhythm do the grouping. (Keep the **required-group rail** — that one
-  *does* encode a real relationship.)
-- Audit every line/fill in `compactRowStyles.ts` against "does this encode data?"
-  If not, it's a candidate for removal.
-
-### 4.6 Grouping, ordering, findability
-
-- **Default sort within a group = needs-attention → set → optional-unset.** Put
-  what the user must act on at the top of each group automatically (the existing
-  `invalid`/`unset` sort modes, but as the smart default for a draft).
-- **Name groups by purpose.** "General" is a non-answer; if the schema gives no
-  meaningful group, prefer a single **Required / Optional** split over a vague
-  "General" bucket.
-- **A pinned "Needs attention (6)" section** at the very top when there are
-  unresolved fields — the form's built-in answer to "what do I do next," and the
-  constructive replacement for the red banner (GOV.UK error-summary pattern, but
-  calm and always-navigable).
-- Keep optional-but-unset fields **collapsed by default** behind the existing
-  "Optional (N)" disclosure, so the default view is "what's set + what's needed."
-
-### 4.7 The "what's next" path
-
-The form should always answer *what's left?* and make it one click to get there:
-
-- Meter → click "6 to resolve" → filter to unresolved (reuse `showInvalidOnly`,
-  but renamed to *"needs attention"* and including required-unset to-dos).
-- On **Submit** with unresolved fields: scroll-to + focus the first, and *now*
-  promote to-dos to errors (the flash machinery already exists).
-- Optional niceties: keyboard `n`/`p` to jump between unresolved fields; a sticky
-  "Next: <field> →" hint while editing.
-
----
-
-## 5. Phased roadmap (impact × effort)
-
-### P0 — quick wins (high impact, low effort): "stop shouting"
-1. **Unset ≠ error.** Don't render red boxes/stripes for untouched required/empty
-   fields; downgrade to quiet amber to-dos. *(biggest single win)*
-2. **Remove the red invalid banner**; fold the count into the meter as a quiet
-   "→ N to resolve" control.
-3. **Drop the `N OPTIONAL` group pill**; show "N to resolve" only when > 0, muted.
-4. **Move field descriptions + error messages off the default row** (behind ⓘ /
-   focus). One line per row.
-5. **Desaturate template chips.**
-
-> P0 alone should resolve "crowded and overwhelming" for the screenshot case.
-
-### P1 — structural (medium effort): "calm density"
-6. Segmented completion meter (set / to-do / unset).
-7. Strict row template + collapse nested previews to summaries by default.
-8. Single status-dot system; remove redundant stripes/boxes/ⓘ-buttons.
-9. Validation timing: per-field `touched` + `submitAttempted`.
-10. Smart default ordering (needs-attention first) + purpose-named groups.
-
-### P2 — ambition (higher effort): "truly great"
-11. Pinned **"Needs attention"** navigator section + keyboard jump.
-12. Reduce the "edit card" modality — inline-first editing everywhere it fits.
-13. **Density toggle** (comfortable / compact) for newcomers vs power users.
-14. Per-group progress underline; section-level "all set" collapse.
-15. Telemetry-driven defaults (collapse rarely-touched optional fields).
-
----
-
-## 6. Component-level change list (where the work lands)
-
-| Area | File | Change |
-|---|---|---|
-| Status consolidation | `CompactToolbar.tsx` | Segmented meter; remove invalid banner; "N to resolve" control |
-| Group header | `FormEngine.tsx:1968` `StyledGroupHeader` | Drop `N OPTIONAL`; muted "to resolve"; optional progress underline |
-| Row template & disclosure | `CompactRow.tsx` | Move desc/error/default-hint behind disclosure; single status dot; calm chips |
-| Validation model | `FormEngine.tsx` validity data + `CompactRow` | `touched`/`submitAttempted`; unset→to-do vs invalid |
-| Visual chrome | `compactRowStyles.ts` | Remove non-data stripes/fills; whitespace rhythm; keep required rail |
-| Ordering / sections | `FormEngine.tsx` group + sort | Needs-attention-first default; "Needs attention" section |
-| Value language | `readFirst.ts` + `CompactRow` `renderReadFirstValue` | Uniform muted weight; desaturated template/richtext chips |
-
-None of this changes the schema/value/`onChange` contract — it's all
-presentation, consistent with the compact mode's existing "purely presentational"
-design.
-
----
-
-## 7. Open questions (to decide / validate with users)
-
-1. **Validation timing**: blur-only, or also a gentle "you skipped a required
-   field" on navigate-away? (Lean: blur + submit.)
-2. Is **"General"** a real schema group or a fallback bucket? If fallback, can we
-   suppress the group chrome entirely for single-group schemas?
-3. How often are the **nested object/hash previews** actually read at a glance vs
-   noise? (Telemetry / quick user check before investing in them.)
-4. Do power users want the **density toggle**, or should we just ship one
-   well-tuned density?
-5. Should **optional-unset** fields be collapsed by default (cleaner) or visible
-   (discoverable)? Likely collapsed with a strong "+ N optional" affordance.
-
----
-
-## 8. How we'll know it worked
-
-- **Time-to-first-meaningful-scan** (qual): can a new user say "what's left?" in
-  < 5s?
-- **Perceived calm** (5-pt survey before/after on the same schema).
-- **Error-recovery**: time from Submit-blocked to all-resolved.
-- **Eye-bounce** (optional): fewer fixations to locate the next action.
-- Objective: **default view height** for the screenshot schema should drop
-  substantially once errors/descriptions move behind disclosure.
-
----
-
-## 9. References
-
-- Nielsen Norman Group — *10 Usability Heuristics* (esp. Aesthetic & minimalist
-  design, Visibility of system status, Error prevention); *Progressive
-  Disclosure*; *Inline Validation in Web Forms*.
-- Baymard Institute — form usability research (inline validation timing;
-  required vs optional).
-- GOV.UK Design System — *Error summary* + *error message* patterns; *question
-  protocol* ("only ask what you need").
-- Edward Tufte — *The Visual Display of Quantitative Information* (data-ink
-  ratio).
-- Miller (1956) — chunking (~7±2).
-- Design-system form guidance: Material 3, IBM Carbon, Shopify Polaris
-  (error/state colour conventions, one-column dense forms).
-
----
-
-### Appendix — mapping the screenshot to the fixes
-
-| In the screenshot | Why it feels heavy | Fix (section) |
-|---|---|---|
-| Red banner "6 fields are not valid…" | System #2, alarmist | 4.1 / P0-2 |
-| `4 OPTIONAL` / `5 TO RESOLVE` pills | System #3, competes with titles | 4.1 / P0-3 |
-| Red box "Text value is empty" (untouched) | Premature error | 4.2 / P0-1 |
-| Red box "Hash arguments are invalid" inline | Layout-disruptive error | 4.2 / 4.3 |
-| Saturated blue `Test (local)` chip | Decoration outshouts label | 4.4 / P0-5 |
-| `schemaOption2 → Show more` tree inline | Breaks row rhythm | 4.3 / P1-7 |
-| Per-row red stripe + red ⓘ + red box | Three marks for one state | 4.5 / P1-8 |

package/design/FORM_ENGINE_EXPRESSIONS.md

@@ -1,257 +0,0 @@
-# Form engine — expression support (visual + DPQL text)
-
-Locked design + rationale for adding **expression** values to the
-ReqRaft form engine: any field can hold a Qorus expression, edited two
-interchangeable ways — a **visual builder** (ported from qorus-ide) and
-a **DPQL text editor** (ReqRaft's existing `DpqlEditor`) — plus an
-**Explain** button.
-
-Execution checklist: [`.tasks/FORM_ENGINE_EXPRESSIONS.md`](../.tasks/FORM_ENGINE_EXPRESSIONS.md).
-Server contract reference (memory): "Qorus expression/DPQL contract".
-Server ask for the Explain transport: `/tmp/render-expression-exposure.md`.
-
-## Background — the one insight everything rests on
-
-A Qorus **expression** is an AST: `{ exp, args }` (args are literals,
-field refs, templates, or nested expressions; `&&`/`||` are AND/OR
-groups). **DPQL is the text serialization of that same AST.** Verified
-live (2026-06-09, `wss://localhost:8012/lsp`):
-
-- `dpql/parse("1 == 1")` → `{ is_expression:true, value:{ exp:"==", args:[…] }, inferred_type:"bool" }`
-- `dpql/serialize({exp,args})` → `{ dpql, richtext }`
-
-So the **visual builder and the DPQL editor are two editors for one
-value.** That value, stored on a field, is `is_expression: true` + the
-AST. `parse`/`serialize` bridge text ↔ AST; the visual builder edits the
-AST directly.
-
-This is *new* integration: in qorus-ide the visual `ExpressionBuilder`
-is purely visual (no DPQL), and DPQL is used only for alert-rule `match`.
-ReqRaft unifies them.
-
-## Goal
-
-1. A field declared `supports_expressions: true` can be toggled from a
-   literal/template into an **expression**.
-2. The expression is editable in **Visual** mode (ported builder) and
-   **Text** mode (DPQL via `DpqlEditor`), switchable, over the same AST.
-3. An **Explain** button renders the expression to readable text.
-4. Operands reuse what we already built — `AutoFormField` / `FormField`
-   — rather than re-porting qorus-ide's field stack.
-
-## Verified server contract
-
-| Need | Transport | Status |
-|---|---|---|
-| Expression catalogue (operators/functions) | REST `GET /api/latest/system?action=expressions` | ✅ live; `useFetch` |
-| Per-provider extra expressions | REST `…/apps/{app}/actions/{action}/expressions` (`expressions_url`) | ✅ merge with system list |
-| Text ↔ AST | LSP `dpql/parse` · `dpql/serialize` · `dpql/validate` | ✅ live; `DpqlEditor` session |
-| **Explain** (AST → readable text) | `render-expression` | ⚠️ **Creator-WS only** — see "Explain transport" |
-
-Value shapes (from the live server):
-- catalogue entry: `{ name, display_name, short_desc, desc, symbol, type, return_type, ui_return_type, args[], varargs, subtype, groups, role }`
-- expression value: `{ is_expression:true, value:{ exp:string, args:IExpression[] } }`
-- `IExpression` arg: `{ type, value }` (literal/template) **or** `{ is_expression:true, value:{exp,args} }` (nested)
-
-## Locked decisions
-
-- **Both modes, one AST.** Visual + text are views of the same
-  `{exp,args}`; `parse`/`serialize` convert at the mode boundary.
-- **Attach at `TemplateField`** (matches qorus-ide). A "Use Expression"
-  entry sits beside the existing template toggle; FormEngine-driven
-  forms get it for free. The field opts in via `supports_expressions`.
-- **Operands render through `AutoFormField`/`FormField`**, not a
-  re-port of qorus-ide's `TemplateField→auto`. An operand is "a value of
-  a type" — exactly what `AutoFormField` (built this session, with the
-  type picker) already does, and it recurses into expressions via
-  `TemplateField` naturally.
-
-  **Revised 2026-06-10 (EXPRESSION_BUILDER_REPORT / FIELD_STACK_REPORT):**
-  superseded by the verbatim re-port — operands now render through the
-  IDE's own `TemplateField → auto` recursion (`TemplateField
-  component={auto}`), matching qorus-ide exactly. The architecture-table
-  row below ("operands → `AutoFormField`") reflects the original decision;
-  see `design/EXPRESSION_BUILDER_REPORT_STRATEGY.md` for the supersession
-  rationale.
-- **Explain behind a seam.** A `useRenderExpression` hook abstracts the
-  transport so the Creator-WS decision doesn't gate the editor (see
-  below).
-- **Catalogue via `useFetch`**, cached (it's static per server version);
-  merge `expressions_url` extras like qorus-ide's `useExpressions`.
-
-## Architecture
-
-New subsystem `src/components/form/expressions/`:
-
-| File | Role |
-|---|---|
-| `types.ts` | `IExpression`, `IExpressionSchema`, arg types (ported) |
-| `useExpressions.ts` | fetch `/system?action=expressions` (+ `expressions_url` merge) via `useFetch`; cached |
-| `useRenderExpression.ts` | **the Explain seam** — `(ast) => Promise<string>`; transport swappable |
-| `ExpressionField.tsx` | the shell `TemplateField` renders in expression mode: **Visual ⇄ Text toggle**, Explain button, owns the AST value |
-| `ExpressionBuilder.tsx` (+ `argument*.tsx`, `group`, `confirm*Modal`) | the **visual** tree (port); operands → `AutoFormField` |
-| `ExpressionBuilder.stories.tsx`, `ExpressionField.stories.tsx` | mock-LSP + mock-catalogue stories |
-
-Touched: `TemplateField.tsx` (Use-Expression toggle + render `ExpressionField` when `is_expression`), `FormField`/`FormEngine` value plumbing for `is_expression`, the form barrel (exports).
-
-**Flow:**
-```
-FormEngine option { supports_expressions:true }
-  └ TemplateField  ── "Use Expression" ──►  is_expression:true
-        └ ExpressionField  (value = { exp, args })
-            ├ [Visual]  ExpressionBuilder ──► edits AST; operands = AutoFormField
-            ├ [Text]    DpqlEditor ──► text; parse()→AST / serialize()←AST at the boundary
-            └ [Explain] useRenderExpression(AST) → readable string
-```
-
-## Explain transport (open decision — does NOT block build)
-
-`render-expression` is Creator-WS-only today. The editor is built behind
-`useRenderExpression`; until the server exposes it over REST or LSP:
-- **interim:** approximate via `dpql/serialize`'s `richtext`, or render
-  Explain disabled-with-tooltip.
-- **target:** server adds `dpql/explain` (preferred) or
-  `?action=render-expression` (REST). Then `useRenderExpression` swaps in
-  one place. Tracked in `/tmp/render-expression-exposure.md` (server ask).
-
-## DPQL-context nuance (design item, resolve in Phase 2)
-
-The `DpqlEditor`'s primary use (alert rules) binds a provider/record
-context for `@field` completions. A *generic field expression* may have
-no provider — its "fields" are the field's **templates** (`$local:…`).
-Phase 2 decides how the text-mode editor binds context: pass the field's
-templates/return-type, and bind a provider only when the field supplies
-one. Worst case, text mode still parses/serializes correctly with no
-provider; only completions are reduced.
-
-## Detecting an expression typed as plain text
-
-*Added 2026-09-06. As-built.*
-
-An author who never opens the expression view still types DPQL into the
-ordinary editor. `TemplateField` notices, and what it does next depends on
-the field's own type.
-
-**A successful parse means nothing.** This is the finding the whole design
-rests on, and it is counter-intuitive enough to be worth stating plainly.
-Verified against the live LSP: `dpql/parse` returns `success: true` for
-`hello`, for `42`, for `2026-09-06` and for `@a`. A bare literal is a valid
-DPQL program, so "does it parse?" cannot separate an expression from a
-value. What separates them is the shape of the AST that comes back:
-
-| typed text | `exp` | verdict |
-|---|---|---|
-| `hello`, `42`, `2026-09-06`, `@a` | `value` | a literal |
-| `$local:count` | `template` | a template |
-| `@a > 5`, `"a" + "b"`, `toInt("5")`, `@n LIKE "a%"` | `>`, `+`, `toInt`, `like` | an expression |
-
-Text that is not DPQL at all is safe on its own: `hello world`, `x@y.com`,
-`a - b test` and `{"a":1}` all fail to parse outright.
-
-**Three stages, in `helpers/dpqlDetection.ts`:**
-
-1. `mightBeDpqlExpression` — a cheap lexical pass whose ONLY job is to keep
-   a server round-trip off every keystroke. It decides nothing. `-` and `/`
-   require surrounding spaces so a date or a path never triggers a probe.
-2. `dpql/parse` on the shared probe document (below), debounced 400 ms.
-3. `classifyTypedText` — `switch` when the text could not be a literal of
-   the field's declared type (the form's own `validateField` answers that),
-   `offer` when it could, `none` otherwise.
-
-**Why the asymmetry.** Rewriting the string `a + b` into a concatenation on
-a `string` field would destroy a value the author meant, so a type that
-accepts any text is only ever OFFERED the switch. Text that could not be a
-literal there was already an error the moment it was typed, so switching
-costs nothing and explains the error. Every switch carries an Undo that
-restores the exact text, and a declined text is never asked about again.
-
-**Reachability.** The auto-switch only applies where the editor accepts free
-text — a constrained `string` (identifier / `validation_regex`), `binary`,
-`hash`. `int` and `float` render `input[type=number]`, which drops `@`, `>`
-and spaces before any handler runs, so detection there is unreachable by
-design of the editor and the ⋮ menu remains the way in. Pinned by a test.
-
-**Template precedence.** `isValueTemplate` is deliberately loose (starts
-with `$`, contains `:`), so `$local:count + 1` was being swallowed into
-template mode with its arithmetic as dead text. A value that is not one
-complete template token and carries an operator now stays in the plain
-editor, where detection can reach it. A token standing alone
-(`$local:count`, `$data:{1.field}`) still flips, unchanged.
-
-**The probe document** (`components/dpqlEditor/dpqlProbe.ts`). One shared,
-lazily-opened DPQL document for the whole app, reference-counted by
-`useDpqlProbe` and closed when the last field using it unmounts. It is
-cheap: `ReqraftLspClient` multiplexes every document over ONE socket per
-endpoint and `initialize` runs once for it, so a probe is one extra
-`didOpen` plus one server-side session — not a connection. It is still
-shared rather than per-field, because a form with forty expression-capable
-options would otherwise open forty sessions to ask the same question.
-
-The document binds NO provider context; verified live, a context-less
-`didOpen` still builds a session that `dpql/parse` answers on. It sends no
-`target_type` either: detection asks whether the text is an expression, not
-whether it is the right type — a mismatch is something to show the author
-inside the editor, never a reason to refuse to open it. A probe never
-throws; an unreachable instance simply leaves the typed text alone.
-
-## Return-type checking
-
-*Added 2026-09-06. As-built.*
-
-`dpql/parse` has always been able to answer "can this expression's result
-satisfy type X?" — it takes a `target_type` and returns `inferred_type`,
-`type_compatible`, `auto_coercible` and a `suggested_fix`. Nothing in the
-front end ever sent one, so it never answered.
-
-`ExpressionField` now sends the field's own type with every parse, and
-shows what comes back. Three outcomes, not two:
-
-| the expression | shown |
-|---|---|
-| already fits | nothing |
-| converts, and the conversion is TOTAL (a number used as text) | nothing |
-| converts, but the conversion may FAIL (text used as a number) | a warning, with the conversion offered |
-| cannot convert at all | a danger message, with the conversion offered |
-
-The middle row is why the server grew `coercion_may_fail`: `canAutoCoerce()`
-admits both kinds, and reporting a conversion that cannot fail is what
-teaches authors to ignore the reports that matter.
-
-`auto` and `any` are never sent as a target — they accept anything, so the
-answer would always be "compatible" and the round trip would buy nothing. A
-field offering a CHOICE of return types sends nothing either, rather than
-asking about one of them arbitrarily.
-
-**What the field cannot decide.** Whether text really denotes a number
-depends on the text, which does not exist until the expression runs. So the
-warning is a warning, not a refusal, and the value is checked again
-server-side at run time — see `design/test-interface-object.md` in the qorus
-repo. For that to be possible the FormEngine's stored envelope carries the
-field's `type` beside `is_expression` and the AST, which is the type the
-author was shown.
-
-The same analysis lives in two server handlers (the LSP's `dpql/parse` and
-the Creator WS equivalent); both were changed together. Deduplicating them
-is a separate cleanup.
-
-## Out of scope
-
-- `server_expression_handling` server-function-vs-qorus-function
-  filtering subtleties (port if a consumer needs them).
-- The AI-assistance button qorus-ide's builder has.
-- Wiring specific consumers (alert-rule editor lives in qorus-ide).
-
-## Migration impact
-
-- Purely additive: a new opt-in field capability + new files. Fields
-  without `supports_expressions` are unchanged.
-- Stacks on the uncommitted AutoFormField / FormField / FormEngine work
-  from the field-migration batch — must land/verify alongside it.
-
-## Status
-
-**Design locked 2026-06-09.** Server contract verified live. Scope: both
-modes + Explain, attached at `TemplateField`, operands via
-`AutoFormField`. Explain transport is an open server decision held behind
-`useRenderExpression` and does not gate implementation. Revisions require
-a "Revised &lt;date&gt;" note per the repo workflow.