Editor: Vega-Lite expression intelligence; single-home render errors

docs/architecture/08-vega-editor-techniques.md

@@ -277,10 +277,10 @@ defaults-spread" discipline is worth keeping.
 
 ## 5 · Editor augmentation (our layer over the borrowed base)
 
-Beyond schema validation/completion (§1), the spec editor adds structural refactors and
-data-aware hints — the edits that are awkward in raw JSON and out of reach of the
-single-view visual builder. All transform logic is pure `src/core/`; the Monaco glue is
-thin app-layer services.
+Beyond schema validation/completion (§1), the spec editor adds structural refactors,
+data-aware hints, and expression intelligence — the edits and feedback that are awkward in
+raw JSON and out of reach of the single-view visual builder. All transform and analysis
+logic is pure `src/core/`; the Monaco glue is thin app-layer services.
 
 **Core (pure, portable):**
 
@@ -321,11 +321,25 @@ thin app-layer services.
   flatten/collapse cleanup runs after. `simplifyStructure` collapses redundant single-child
   compositions recursively (a `{hconcat:[v]}` is just `v`; `facet`/`repeat` hold one child by design
   and are left alone) — the wireframe's Simplify, returning null when nothing is redundant.
+- `expr-validate` — one Vega expression, parsed with Vega's own `parseExpression` (no divergent
+  grammar): `validateExpression` (valid + parser message), `referencedFields` (its `datum.<field>`
+  references), and `activeCall` (the enclosing call + which argument the cursor is in, for signature
+  help).
+- `spec-expressions` — the expressions embedded in a spec's JSON strings (`EXPRESSION_KEYS` =
+  `calculate`/`filter`/`expr`/`test`; only string values, so object predicates are skipped).
+  `expressionStringsIn` locates each (byte span + key) to drive markers; `firstExpressionError`
+  names the first malformed one (key + parser message + 1-based line) so a failed render can
+  attribute itself.
+- `vega-expr-catalog` — the expression language's function/constant **names derived from
+  `vega-expression`'s own registry** (zero drift; a test asserts the curated set ⊆ derived), plus
+  curated parameter signatures for the commonly-typed functions (what the registry can't supply).
 
 **Services (app, store-aware via `getState`):** `spec-transform-actions` (the
-wrap/simplify/add-view operations and their surfaces), `spec-dataset-hints` (completion,
-hover, inlay providers), `active-dataset` (`dataInfoAt(text, offset)` — the columns/types/stats
-plus derived fields the draft sees at the cursor). `SpecEditor` does the wiring.
+wrap/simplify/add-view operations and their surfaces), `spec-dataset-hints` (data-column
+completion, hover, inlay providers), `spec-expression-hints` (expression completion,
+signature help, hover, and the diagnostic markers), `active-dataset` (`dataInfoAt(text,
+offset)` — the columns/types/stats plus derived fields the draft sees at the cursor).
+`SpecEditor` does the wiring.
 
 Decision rules:
 
@@ -381,6 +395,19 @@ Decision rules:
 - **No unknown-field diagnostic.** Hints are additive and forgiving, so over- or
   under-listing costs nothing; a "field not in data" squiggle would false-positive on every
   derived or data-dependent field, so there is deliberately none.
+- **Expression intelligence is one service; its markers are per-editor.** `spec-expression-hints`
+  registers the expression completion/signature-help/hover **once for `json`** (like the other
+  providers), but the marker pass — validating every expression string and squiggling the invalid
+  ones with `setModelMarkers` (the app's only editor markers besides the JSON worker's, under the
+  `vega-expr` owner) — is **per editor**, since it writes to one model, and recomputes debounced on
+  edit and on a draft↔published toggle. All expression concerns (completion, hover, markers) live
+  here; `spec-dataset-hints` owns only data-column hints, so neither is a grab-bag.
+- **Completion replace-ranges come from a self-parsed partial, never `getWordUntilPosition`.**
+  Monaco's JSON `wordPattern` counts `.` and `(` as word characters, so the model's "word" after
+  `datum.` or `fn(` spans the whole `datum.`/`fn(` token; used as a completion item's range it both
+  mis-targets the edit and filters every suggestion out (none start with `datum.`). A provider
+  completing inside a string must build the replace range from the partial it parses itself — a rule
+  any future in-string completion (transform/param scaffolding) inherits.
 - **Code-action menu icons are kind-derived** (a wrench for the `refactor.*` kinds) — Monaco's
   `CodeAction` carries no icon field. Custom iconography lives only where it is supported:
   CodeLens titles (`$(codicon)`), completion-item kinds, and glyph-margin decorations.