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

package/.tasks/SMART_EDITOR_LSP_FEATURES.md

@@ -1,299 +0,0 @@
-# SmartEditor — unused LSP methods
-
-Follow-up to the `0.10.0` UX batch (see
-[`SMART_EDITOR_UX_POLISH.md`](./SMART_EDITOR_UX_POLISH.md)). The Qorus
-LSP server advertises 13+ standard LSP methods we don't consume from
-the client. This task triages each, lands the ones with real value
-for DPQL / Qonsole today, and documents why the rest are deferred or
-permanently out of scope.
-
-**Status:** done — committed in `d54597e`. Wires `textDocument/signatureHelp`; other 12 LSP methods deferred per the per-method rationale below. **Awaiting browser verification (mock + live story exist; live story confirmed against the real Qorus DPQL LSP).**
-
-**Live-verification notes (captured after the initial implementation):**
-
-- Real server signature shape differs from the hypothetical one
-  documented in §"Design decisions → 1." below. The Qorus DPQL handler
-  emits a single `→ <type>` return annotation in the `label`, and uses
-  **human-friendly capitalized parameter names** (`"String Value"`,
-  `"Start Character"`) rather than identifier-style (`"value1"`,
-  `"start"`). Both are valid LSP `SignatureInformation`; the render
-  path handles both.
-- **`coalesce` and `concat` are single-variadic-parameter on the
-  server.** Both return one parameter (`"Value"`). Typing more commas
-  does NOT advance the active parameter — the server semantically
-  treats all args as the same conceptual slot. The original task plan
-  used `coalesce` as the demo case; the live story uses `substr`
-  instead because it has three distinct positional parameters and
-  visibly demos active-parameter advancement.
-- Server-probed shapes for functions with distinct positional params:
-  - `substr(String Value, Start Character, Length) → string`
-  - `round(Number, Precision) → auto`
-  - `format_date(Date To Format, Format String) → string`
-  - `nullif(Value, Compare Value) → auto`
-  - `split(String To Split, Separator) → list<auto>`
-- Real server **also pushes a `textDocument/publishDiagnostics`** for
-  incomplete input — `substr("hello", ` flags as "Unexpected token ''
-  in value position". The diagnostic clears once the syntax is
-  complete. The editor's existing diagnostic panel renders it.
-  Expected behavior.
-- Capability advertisement: real server advertises 22 LSP providers
-  in `initialize`, but per the per-method rationale below, most return
-  null/empty for `languageId: 'dpql'`. The capability gate on
-  `session.capabilities?.signatureHelpProvider` is the right check
-  before wiring features.
-**Scope:** one new feature (signatureHelp), one capability-detection
-helper, eight explicit "rejected — defer" decisions.
-**Estimated size:** ~250 lines + tests, ~1.5 days.
-
-## Goal
-
-The DpqlEditor should feel like a real code editor when you're inside
-a function call — typing `coalesce(@a, ` should show a popover with
-the signature `coalesce(value1, value2, …, default)`, the current
-argument highlighted. This is the single highest-leverage LSP feature
-we don't yet use.
-
-## Research findings (server)
-
-Full audit at the foot of this file. Summary:
-
-The server (`qorus/Classes/QorusLspWebSocketHandler.qc`)
-unconditionally advertises every LSP provider it knows about in the
-`initialize` response (line 841-907), but **most of them early-return
-`[]` or `null` for DPQL and Qonsole** — the handlers branch by
-`languageId` and only the Qore / TypeScript / Python paths do
-meaningful work. DPQL is implemented only for `completion`, `hover`,
-`semanticTokens`, `formatting`, `signatureHelp`. Qonsole is
-implemented for `completion`, `hover`, `semanticTokens`, `codeAction`.
-
-| Method | DPQL | Qonsole | Value for DPQL |
-|---|---|---|---|
-| `textDocument/signatureHelp` | **yes** (`dpql-get-signature-help`) | yes | **HIGH** ← this task lands this |
-| `textDocument/codeAction` | no | yes | LOW (no DPQL impl) |
-| `textDocument/documentHighlight` | no | no | LOW |
-| `textDocument/inlayHint` | no | no | LOW |
-| `textDocument/prepareRename` + `rename` | no | no | LOW |
-| `textDocument/selectionRange` | no | no | LOW today; MEDIUM if DPQL gains AST-driven |
-| `textDocument/onTypeFormatting` | no | no | LOW (single-line) |
-| `textDocument/definition` | no | no | LOW (hover covers it) |
-| `textDocument/references` | no | no | LOW (single-line) |
-| `textDocument/foldingRange` | no | no | LOW (single-line) |
-| `textDocument/documentSymbol` | no | no | LOW (no symbols) |
-| `textDocument/codeLens` | no | no | LOW (no top-level decls) |
-| `workspace/executeCommand` | no | no (rejects `qonsole.*`) | LOW |
-
-**Only one method is worth implementing now for the DPQL story we
-ship.** The rest are documented as known not-supported-server-side
-and revisited if/when the server gains support.
-
-## Design decisions
-
-### 1. `textDocument/signatureHelp` — implement
-
-**Server contract:**
-- Triggers: `(`, `,`, ` `, `-`, `=` (advertised by
-  `signatureHelpProvider.triggerCharacters`)
-- Response shape:
-  ```json
-  {
-    "signatures": [
-      {
-        "label": "coalesce(value1, value2, ..., default)",
-        "documentation": { "kind": "markdown", "value": "..." },
-        "parameters": [
-          { "label": "value1", "documentation": {"kind":"markdown","value":"..."} },
-          ...
-        ]
-      }
-    ],
-    "activeSignature": 0,
-    "activeParameter": 1
-  }
-  ```
-- Empty case: `{ "signatures": [], "activeSignature": 0, "activeParameter": 0 }`
-
-**Client UX:**
-- Small pinned pill **above** the caret (above, not below, so the
-  completion popover and signature pill don't overlap; they coexist
-  side-by-side or stacked)
-- Shows the active signature's `label` with the parameter at
-  `activeParameter` highlighted (bold + accent color from the
-  `info` intent)
-- Below the label: the active parameter's `documentation.value` as
-  markdown (capped at ~2 lines, scrollable past)
-- Dismisses on: Escape, closing paren, cursor moves outside the
-  call (heuristic: cursor offset < open-paren position), or
-  `session.diagnostics` reports an error covering the call site
-
-**Trigger logic:**
-- Fire on the server-advertised triggers via the existing
-  `onSlateChangeImpl` path (`useLspAutocomplete.ts:443`)
-- Also re-fire on any cursor move while a signature is currently
-  open — `activeParameter` advances when the user types a comma or
-  moves between args
-- Debounce ~100ms (a bit faster than completions — feels snappier
-  for "where is my cursor inside this call")
-
-**Position:**
-- Anchor at the caret's DOM rect like the completion popover, but
-  `top: rect.top - 4` (above the line, with a 4px gap)
-- Re-use the same "measure-after-debounce" pattern that fixed the
-  completion popover positioning bug from Phase 5
-
-### 2. Generic LSP capability detection
-
-The completion handler already captures the semantic-tokens legend
-from initialize. Extend the same pattern so consumers can check
-whether the server supports a given provider:
-
-```ts
-// lspClient.ts
-public capabilities: ILspServerCapabilities | null = null;
-// ILspServerCapabilities — minimal shape; just the providers we care about
-//   signatureHelpProvider?: { triggerCharacters?, retriggerCharacters? }
-//   hoverProvider?: boolean
-//   completionProvider?: { triggerCharacters? }
-//   semanticTokensProvider?: { legend, full?, range? }
-//   codeActionProvider?: { codeActionKinds? }
-//   ... (only what we read)
-```
-
-Surface as `session.capabilities` (and `session.semanticTokensLegend`
-becomes a thin alias for `capabilities?.semanticTokensProvider?.legend`).
-
-This gives wrappers a clean way to test "does this server support
-signature help?" before wiring the trigger — no hardcoded server
-assumptions.
-
-### 3. Rejected — defer with rationale
-
-For each LOW-value method, explicitly land a "we considered this and
-declined" note in the README or design doc rather than leaving them
-silently unimplemented. Future contributors should not have to redo
-this research.
-
-The rationale per method is in §research-findings below. The README's
-Components section gains a short subsection "LSP methods supported"
-that lists `completion`, `hover`, `formatting`, `semanticTokens`,
-`diagnostics`, `signatureHelp` (after this task) and a one-line "Why
-not X / Y" pointer.
-
-## Surface area
-
-| File | Change |
-|---|---|
-| `src/utils/lspClient.types.ts` | new `ILspSignatureHelp`, `ILspSignatureInformation`, `ILspParameterInformation`, `ILspServerCapabilities` types |
-| `src/utils/lspClient.ts` | capture full `initialize` `capabilities` (not just the semantic-tokens legend); new `getSignatureHelp(line, character): Promise<ILspSignatureHelp \| null>` |
-| `src/components/smartEditor/useLspSession.ts` | surface `capabilities: ILspServerCapabilities \| null` in the result |
-| `src/components/smartEditor/useLspSignatureHelp.ts` | **new** — hook returning `{ signature, activePill, position, clear }`. Same skeleton as `useLspHover` (mousemove → here it's cursor-position-aware) |
-| `src/components/smartEditor/SmartEditor.tsx` | render the signature pill `<ReqorePopover>` above the caret; trigger via the existing `onSlateChangeImpl` based on capability's `triggerCharacters` |
-| `src/components/smartEditor/types.ts` | new `enableSignatureHelp?: boolean` prop (default `true`) |
-| `__tests__/smartEditor/signatureHelp.test.ts` | **new** — unit tests for position mapping + active-parameter advancement |
-| `src/components/dpqlEditor/DpqlEditor.stories.tsx` | mock `textDocument/signatureHelp` handler (return a synthetic `coalesce(...)` signature); new `WithSignatureHelp` story |
-| `README.md` | document `enableSignatureHelp`; "LSP methods supported" subsection |
-
-## Tasks
-
-### Setup
-
-- [ ] Read the Qore-spec dpql signature-help test fixtures to capture
-      a realistic signature shape (`/Users/nick/Projects/QoreTechnologies/qore-2/test/...` if any) — falls back to the `coalesce` example if no fixture exists
-
-### Types + LspClient
-
-- [ ] `src/utils/lspClient.types.ts` — add `ILspParameterInformation`,
-      `ILspSignatureInformation`, `ILspSignatureHelp`,
-      `ILspServerCapabilities` (minimal — only fields we read)
-- [ ] `src/utils/lspClient.ts` — store the full `capabilities` hash
-      from `initialize` response (currently we only extract the
-      semantic-tokens legend). Backwards-compat: keep the existing
-      `semanticTokensLegend` field as a derived getter
-- [ ] `LspClient.getSignatureHelp(line, character)` — sends
-      `textDocument/signatureHelp` with the URI + position; returns
-      the response or `null` on no signatures
-
-### Session hook
-
-- [ ] `useLspSession` — expose `capabilities` in the result
-- [ ] Re-capture in the connect-effect alongside the existing legend
-      capture
-
-### `useLspSignatureHelp` hook
-
-- [ ] New file: `src/components/smartEditor/useLspSignatureHelp.ts`
-- [ ] Signature: `useLspSignatureHelp(session, editorRef, converter, options?)`
-- [ ] State: `{ signature: ILspSignatureHelp | null, position: { left, top } | null, clear: () => void }`
-- [ ] Debounce 100ms; cancel on cursor moves outside any open paren
-- [ ] Stale-response guard via `requestIdRef` (same pattern as hover)
-- [ ] Skips if `!session.capabilities?.signatureHelpProvider`
-
-### SmartEditor wiring
-
-- [ ] New prop `enableSignatureHelp?: boolean` (default `true`)
-- [ ] Call `useLspSignatureHelp(...)` alongside the other LSP hooks
-- [ ] Trigger from `onSlateChangeImpl` when the typed character is in
-      the server's advertised `signatureHelpProvider.triggerCharacters`
-      AND `enableSignatureHelp` is true
-- [ ] Render the signature pill `<ReqorePopover>` anchored at
-      `{ top: rect.top - 4, left: rect.left }` with `placement='top-start'`
-- [ ] Pill content: signature label with active parameter bolded,
-      below it the active parameter's documentation rendered via
-      `react-markdown`
-- [ ] Dismiss on Escape (extend the existing keyboard handler), on
-      cursor moves out of the call, on close-paren
-
-### Stories + tests
-
-- [ ] DpqlEditor mock: handle `textDocument/signatureHelp` by
-      returning a synthetic `coalesce(value1, value2, default)`
-      signature
-- [ ] New story `Components/DpqlEditor → WithSignatureHelp` — initial
-      value `coalesce(@name, ` so the pill is visible on mount
-- [ ] Play test: assert the pill appears, `activeParameter` is 1
-      (`value2`), advances to 2 (`default`) on typing a comma
-- [ ] Unit tests for `getSignatureHelp` request shape, the
-      capability gate (no request when provider absent)
-
-### Documentation
-
-- [ ] README.md — add `enableSignatureHelp` to SmartEditor props
-      table; add an "LSP methods supported" subsection that lists
-      what's wired and includes a one-line "Why not X" entry for
-      each of the 12 deferred methods
-- [ ] Inline TSDoc on `enableSignatureHelp` explains it's gated on
-      server capability — turning it on with a non-supporting server
-      is a silent no-op
-
-### Checks
-
-- [ ] Typecheck, lint, jest, storybook play tests all pass
-- [ ] **STOP — user verifies in browser** before commit
-
-## Research findings — per-method deferral rationale
-
-(For the README's "Why not X" pointers. Sourced from the deep server
-audit; full notes in research transcript.)
-
-| Method | Why deferred |
-|---|---|
-| `textDocument/codeAction` | Server has no DPQL handler. For Qonsole it works but our editor primitive isn't where quick-fix UI belongs — that's qorus-ide-side. Add later if a Qonsole-specific consumer needs it. |
-| `textDocument/documentHighlight` | Server returns `[]` for both DPQL and Qonsole. |
-| `textDocument/inlayHint` | Server returns `[]`. Single-line DPQL would crowd ghost-text. |
-| `textDocument/prepareRename` + `rename` | Server returns `null`. DPQL field names aren't user-renameable (server-owned schema). |
-| `textDocument/selectionRange` | Server returns `[]`. Could become useful if DPQL parser exposes AST ranges, but no current consumer asks for it. |
-| `textDocument/onTypeFormatting` | Server returns `[]`. DPQL is single-line, no `{}` blocks. |
-| `textDocument/definition` | Server returns `[]`. Field "definitions" already surfaced via hover. |
-| `textDocument/references` | Server returns `[]`. Short expressions; no cross-reference scope. |
-| `textDocument/foldingRange` | Server returns `[]`. Single-line. |
-| `textDocument/documentSymbol` | Server returns `[]`. Server comment: "command buffers are single-line and do not expose symbols". |
-| `textDocument/codeLens` | Server returns `[]`. No top-level declarations in DPQL/Qonsole input. |
-| `workspace/executeCommand` | Server rejects `qonsole.*` (wizard launch is REST-based — see Qonsole task). No other commands defined. |
-
-## Out of scope
-
-- Wiring code-actions for Qonsole only (would land in the Qonsole
-  features task, not here)
-- Implementing client-side rename UI even if the server stays no-op
-- Adding signature help to QonsoleSmartInput (covered by the
-  Qonsole-features task; signature help for natural-language input
-  doesn't make sense the same way it does for DPQL function calls)

package/.tasks/SMART_EDITOR_REVIEW_FOLLOWUPS.md

@@ -1,280 +0,0 @@
-# SmartEditor / DpqlEditor — review follow-ups (PR #62)
-
-Source: reviewer feedback on toolkit-react PR #62 (the `0.10.0` editor batch).
-Four work items.
-
-**Status:** all 4 items done pending user verify (uncommitted)
-
-- **Task 1** ✅ removed the client "Templates" button + `templates`/`stateId`
-  props (our work, unreleased, server-redundant). Mock now position-aware:
-  `$`→templates, `@`→fields. `WithTemplates` story reworked to demo the
-  `$`-server flow.
-- **Task 2** ✅ play tests added: DPQL `WithSignatureHelp` (pill on mount),
-  `WithTemplates` (`$`/`@` routing), Qonsole `WithCommitCharacters`
-  (`=` commit, no `==`), `WithWizardItems` (`onWizardStart` fires),
-  SmartEditor `WithMarkdownDocs` + `WithGroupedKinds` (open dropdowns).
-- **Task 3** ✅ theme-transparency: popovers inherit the ambient theme
-  (no more hardcoded `#1a1a1a`); focused row uses `custom1` (QorusPurple);
-  `#160437` → semantic `pending:darken`. Storybook decorator applies
-  qorus-ide's theme (`#121212` + Qorus intents) so snapshots show the
-  in-IDE look.
-- **Task 4** ✅ the look-alike SmartEditor stories now open their
-  dropdowns via `play` (combined with Task 2).
-- **Bonus** ✅ two live stories: `LiveDpqlEditorWithAlertPayload` (verify
-  `@` fields live) + `LiveDpqlEditorWithFsmContext` (verify `$data:`).
-
-**Verification:** 263 jest pass; 161/162 storybook play tests pass (the 1
-is the pre-existing unrelated `FormEngine.OnValidityChange` flake). Design
-verified in browser — dropdown on `#121212`, purple focused row.
-
----
-
-Reviewer's message (verbatim):
-> Because I think the idea was that when you type `$` it should show you
-> templates, when you write `@` it should show you fields etc.
->
-> can you please go back and also add more storybook play tests, so that
-> if the story is wrong we can detect it in the CI?
-> Also the design could be improved I think as well, so that it matches
-> the IDE more (eg the screenshot)
-> There are multiple stories that look the same in the SmartEditor (just
-> an empty input box)
-
----
-
-## Task 1 — `$` → templates, `@` → fields (fix the trigger model)
-
-**Intended UX (per reviewer):** typing `$` surfaces templates; typing `@`
-surfaces field references. Both through the same on-typing completion
-dropdown — NOT a separate button, NOT on-focus.
-
-**Current state (the mismatch):**
-- `$` IS already a trigger char: `DPQL_TRIGGERS = new Set(['@', '$', '.', ':'])`
-  (`DpqlEditor.tsx:52`). So typing `$` fires `getCompletions` → the LSP
-  **server**. Whether the server returns templates for a `$` context is a
-  server-side question we haven't confirmed.
-- The client-supplied `templates` prop (static items like `$local:input`,
-  `$timestamp:now`) is rendered as a **separate "Templates" dropdown
-  button above the editor** (`DpqlEditor.tsx:241` `topActions` →
-  `ReqoreDropdown`). This is redundant with the `$`-trigger idea and is
-  the thing the reviewer is questioning.
-
-**Important nuance discovered while scoping** — there are *two different*
-trigger models in play, and they're not the same:
-- **Native `ReqoreTextarea`/`ReqoreRichTextEditor` `templates` prop**
-  (inherited via `IReqoreRichTextEditorProps extends IReqoreTextareaProps`)
-  → opens the templates popover on **click/focus** of the editor
-  (`ReqoreDropdown` with `closeOnTargetClick: false`). This is the "click
-  in → popup shows" behaviour the reviewer first referenced for the other
-  fields.
-- **Reviewer's stated intent now** → `$` (typing) shows templates.
-
-These differ. For an LSP-backed editor where `@` already opens fields
-**on typing**, the **`$`-on-typing** model is the consistent one — a
-click/focus popup would compete with the `@` completion overlay and
-reverse the deliberate "trigger-on-typing-only" design (commit
-`6fb9bf3`). So Task 1 = the `$`-on-typing model, not the native
-click-popup.
-
-**ANSWER — confirmed from the qorus server source** (`Classes/QorusLspWebSocketHandler.qc`):
-
-The server is the **single authoritative source for both** `@` fields and
-`$` templates. It is **position-aware** — one `dpql-get-completions` call
-returns the right items based on the cursor context. So `$`→templates and
-`@`→fields is **already the server's design**; the client does NOT branch.
-
-Evidence:
-- Triggers advertised: `"dpql": {"@": True, "$": True, ".": True, " ": True}`
-  (`:269`).
-- The completion handler (`:1260-1294`) calls a single
-  `DpqlActionSession.handleAction("dpql-get-completions", {text, position,
-  template_context, fields})` and maps the unified result to LSP items. The
-  server parses text+position and returns fields after `@`, templates after
-  `$`, plus functions/keywords/operators (`:7910` fallback comment:
-  "functions, keywords, operators, templates").
-- **Templates are server-derived, NOT client-supplied.**
-  `buildDpqlTemplateContext` (`:8648`) builds the template context from:
-  - `state_data` from the **FSM context** (set via `dpql/setFsmContext` →
-    `uriToFsmContext`), and
-  - `record_fields` from the provider/recordType fields, and
-  - global Qorus template namespaces via `QorusExpressionHandler::QorusExpressionMap`
-    (`:7916` fallback path) — this is very likely where `$local:` /
-    `$timestamp:` / `$config:` come from (the exact items our static
-    `templates` prop hard-codes). **[verify: confirm QorusExpressionMap
-    yields those namespaces]**
-
-**Conclusion: it is NOT "both" — the proper source is the server.**
-`$`→templates already works **today** via the existing `$` trigger +
-`getCompletions`, *provided the editor's context is set* (`fsmContext`
-and/or `provider`/`recordType`). The static client `templates` prop +
-the "Templates" button **duplicate** what the server already returns on
-`$`, and worse, present it as a button instead of the `$`-trigger flow.
-
-**The most correct + proper implementation:**
-1. **Remove the `topActions` "Templates" button** from `DpqlEditor`
-   (`:241`). It duplicates the server's `$` completions.
-2. Rely on the existing `$` trigger → `getCompletions` → server returns
-   templates. No client branching, no injection in the normal path.
-3. The `WithTemplates` story is demonstrating the **wrong mechanism** (the
-   static button). Rework it to set an `fsmContext` (or provider) and a
-   mock that returns templates on `$`, so it shows the real `$`→templates
-   flow.
-4. **Remove the static `templates` prop entirely (the "clean" version) —
-   confirmed SAFE, no reviewer sign-off needed.** Rationale:
-   - The prop is **our** addition (commit `6e11c7b`, this batch), not a
-     reqore feature. Only the *type* `IReqoreFormTemplates` is reqore's.
-   - `DpqlEditor` is **brand-new in the unreleased `0.10.0`** — the
-     published `0.8.11` doesn't even export it, so there is **no external
-     consumer** of the prop.
-   - The qorus-ide wrapper does **not** pass `templates`.
-   - **Server-confirmed redundant**: live `$` returned `$autovar:`,
-     `$config:`, `$data:`, `$env:`, `$for:`, `$foreach:`, … — a *fuller*
-     set than the prop's hard-coded `$local`/`$timestamp`/`$config`. The
-     server (QorusExpressionMap + FSM `state_data` + record fields) is
-     strictly better and always present for an LSP-backed editor.
-   - No realistic DPQL case needs client-supplied templates.
-   → Drop the prop + the button. (`IReqoreFormTemplates` import goes too.)
-
-**EMPIRICALLY VERIFIED (live server):**
-- `$` in `LiveDpqlEditorWithSignatureHelp` (no context) → server returns the
-  global namespaces (`$autovar:`, `$config:`, `$data:`, `$env:`, `$for:`,
-  `$foreach:`, …). ✓ confirms `$`→templates is server-driven + context-free.
-- `@` in the same (no-context) story → **nothing**, which is **correct**:
-  field refs come from `getDpqlFields(uri)`, which only exist once a context
-  is bound (`provider`/`recordType`, `alertPayloadContext`, or FSM). The
-  server's NO-CONTEXT fallback returns "functions, keywords, operators,
-  templates" — **fields are deliberately not in that list**. So `@`-empty
-  without a context is by design, not a bug.
-- **Still to verify (needs a new live story with a real context):** `@`
-  returning actual fields. Add `LiveDpqlEditorWithAlertPayload`
-  (`alertPayloadContext: true`) and type `@` → expect real alert-payload
-  fields. Optionally `LiveDpqlEditorWithFsmContext` for `$data:` state
-  templates beyond the globals.
-
----
-
-## Task 2 — Storybook play tests for CI regression detection
-
-Reviewer wants CI to catch a broken story. Current coverage:
-- 26 stories across DpqlEditor / SmartEditor / QonsoleSmartInput.
-- Only **4 explicit `play` tests** (`CanTypeText`, `LspCompletionRoundtrip`,
-  SmartEditor `BasicMock`, QonsoleSmartInput `BasicMock`). The rest are
-  smoke-only (render-without-throw) — which is why "158/159 pass" sounded
-  like more behavioural coverage than it is.
-
-**Add deterministic play tests to the MOCK stories** (live stories stay
-smoke-only — non-deterministic against real `/lsp`):
-- DpqlEditor `WithSignatureHelp` (mock): pill on mount with `Start Character`
-  highlighted → type `0, ` → `Length` highlighted → type `)` → pill gone.
-- DpqlEditor `$`→templates and `@`→fields (after Task 1): assert the right
-  dropdown opens per trigger.
-- QonsoleSmartInput `WithCommitCharacters`: type `-`,`-`,`l`,`=` → no `==` dup.
-- QonsoleSmartInput `WithWizardItems`: select wizard item → `onWizardStart`
-  spy called with the descriptor.
-- QonsoleSmartInput `BasicMock`: already has the `/l`→`/list` no-dup +
-  slot-grammar assertions — keep / extend.
-
-**Constraint already learned:** programmatic `execCommand`/synthetic
-`InputEvent` do NOT reliably go through Slate's `beforeinput` pipeline —
-use `@storybook/test` `userEvent.type` (the existing 4 play tests do this
-successfully). Some assertions (signature param advance) were only verified
-manually; codifying them is the point of this task.
-
----
-
-## Task 3 — Design polish to match the IDE
-
-Reviewer: "the design could be improved … so that it matches the IDE more
-(eg the screenshot)".
-
-**The IDE's design tokens (confirmed — `qorus-ide/src/constants/util.ts`
-`defaultReqoreTheme`, applied app-wide via `ReqoreUIProvider` in
-`src/index.tsx`):**
-- `main: '#121212'` (app surface)
-- `header.background: '#000000'`
-- intents: `success: '#4a7110'`, **`custom1: '#762f7e'` (QorusPurple)**,
-  `custom2: '#b34e1d'` (Attention/orange)
-- theme name `vscode`; options: button/dialog animations off, `glowingIcons`,
-  tooltip delay 300, `closePopoversOnEscPress`.
-
-**The mismatch:** our `styling.ts` **hardcodes** its own surfaces instead
-of inheriting the ambient theme:
-- `SMART_EDITOR_POPOVER_CUSTOM_THEME.main = '#1a1a1a'` (vs the IDE's
-  `#121212`)
-- gradient `#160437` etc.
-- focused row / chips use generic `info` (blue) — the IDE's brand accent is
-  **QorusPurple `#762f7e` (custom1)**, which is why our blue-accented
-  dropdown reads as "not quite the IDE".
-
-**The correct approach (per `qorus-ide/design/REQORE_REQRAFT.md`: "use
-customTheme/effect/intent, don't hardcode"):** the editor is a **library**
-component — it must NOT bake in qorus-ide's brand hexes (that couples
-reqraft to one consumer). Instead:
-
-1. **Make the editor theme-transparent** — stop forcing `#1a1a1a`; use
-   `transparent` + inherit the ambient Reqore theme so the popover surface
-   becomes whatever the host app's `main` is. Embedded in qorus-ide →
-   automatically `#121212`; embedded elsewhere → that app's surface. This is
-   the "matches the IDE" win AND keeps reqraft consumer-agnostic.
-2. **Use semantic intents, not hexes** — let the focused-row / chip accent
-   resolve through the theme's intent palette (so qorus-ide colours it with
-   its `custom1` purple; the library ships a sensible default).
-3. **Storybook preview** — add a decorator that wraps the editor stories in
-   a qorus-ide-like theme (`main: '#121212'`, `intents.custom1 = '#762f7e'`,
-   `custom2 = '#b34e1d'`) so the Chromatic snapshots show the in-IDE look.
-   This is how we "see the match" without running the whole IDE — and it's
-   what the reviewer's screenshot compares against.
-
-**To do:**
-- `styling.ts`: replace hardcoded `#1a1a1a`/`#160437` popover surfaces with
-  `transparent` + ambient-theme inheritance; keep `backgroundBlur`.
-- Audit `COMPLETION_KIND_INTENTS` + focused-row + chip intents → semantic
-  intents that the host theme colours (not literal blue).
-- Add the qorus-ide-theme Storybook decorator (global, in `.storybook` or a
-  per-editor-story decorator) so stories render on `#121212` with the Qorus
-  intents.
-- Then eyeball row padding/height, chip style, type-caption treatment
-  against the screenshot and nudge spacing.
-
-**Why we can do this without reviewer back-and-forth:** the design target is
-the IDE's own published theme tokens (`defaultReqoreTheme`) — not a
-subjective choice. "Match the IDE" = "inherit the IDE's theme + use its
-intent palette", which is objectively defined in `constants/util.ts`. The
-only subjective polish (exact padding/row height) we tune against the
-screenshot.
-
----
-
-## Task 4 — Deduplicate / differentiate empty-looking SmartEditor stories
-
-Reviewer: "multiple stories that look the same in the SmartEditor (just an
-empty input box)".
-
-**Confirmed:** the 3 SmartEditor mock stories all seed `initialValue: ''`:
-- `BasicMock`, `WithMarkdownDocs`, `WithGroupedKinds` → all render as an
-  identical empty box at rest, so their Chromatic snapshots are
-  indistinguishable. (`LiveQonsole` seeds `/list services ` so it differs.)
-
-**Options (pick per story):**
-- Seed a representative `initialValue` so each looks distinct at rest, OR
-- Add a `play` that opens the dropdown so the Chromatic snapshot captures
-  the differentiated content (this doubles as Task 2 coverage), OR
-- Consolidate stories that genuinely demo the same thing.
-
-Recommendation: combine with Task 2 — give each a `play` that opens its
-characteristic dropdown state, which both differentiates the snapshot AND
-adds the CI assertion. Net: one pass covers Tasks 2 + 4 for SmartEditor.
-
----
-
-## Suggested order
-
-1. **Task 1** decision (ask reviewer: server `$` templates vs client-injected
-   vs both) — blocks the implementation but not the others.
-2. **Tasks 2 + 4 together** — play tests that open dropdowns differentiate
-   the snapshots AND give CI coverage. Do the non-`$` ones now; add the
-   `$`→templates assertion after Task 1 lands.
-3. **Task 3** — needs the reviewer's design target; iterative.
-
-All on `feature/dpql-editor` (PR #62) as follow-up commits **after** the
-user verifies — no commits without explicit OK.