# Editor support for the new syntax — Design **Date:** 2026-08-19 **Status:** Approved for implementation **Scope:** Language server and VS Code extension updated for `apis { }`, the `api.()` call, and the removal of the mode data blocks. **Depends on:** `2026-08-19-apis-block-design.md`. The syntax must exist before the editor can describe it. ## Goal A syntax change that the editor does not know about is worse than no change: valid code is red-underlined, removed constructs still autocomplete, and the new block gets no highlighting. This spec keeps the tooling level with the language. It also settles a question left open by earlier work: whether type errors from the generated assertions actually appear inside the `.wrn` file, or only in the generated file. That was never verified — it was inferred from reading source — and inference is not good enough for the thing developers rely on to tell them their code is wrong. ### Non-goals - New editor features unrelated to this syntax change. - Editors other than VS Code beyond what standard LSP provides. - HTML formatting — `formatWrn` still owns markup. ## What exists - **Grammar:** `editors/vscode/syntaxes/wrn.tmLanguage.json` names block keywords directly — `api` appears 4 times, `client` 6, `server` 5, `ssr` once. - **Keyword list:** `WRN_KEYWORDS` in `packages/language-server/src/index.ts` drives completion and includes `api` but not `apis`. - **Extension completions:** `editors/vscode/src/completion.js` carries block snippets. - **Server features:** completion, hover, folding, linked editing, tag completion, and TypeScript diagnostics over a virtual document. ## Changes by surface ### Grammar Add `apis` as a block keyword. Remove the `ssr` / `client` **data block** patterns, keeping `client` and `server` where they mean other things — `client state { }`, the `runtime` values, and the function modifiers in `functions { }`. This is the change most likely to over-reach: `client` is one word with several jobs in this language, and blanket removal would un-highlight constructs that still exist. Highlight an `apis` entry's shape — name, method, path — so a declaration reads as a declaration rather than as loose identifiers. ### Keyword and block completion - `apis` joins `WRN_KEYWORDS`. - A snippet for the container and a snippet for an entry, including the `request` / `response` / `error` sections, so the shape is discoverable without the docs. - `ssr` and `client` data-block snippets are removed from `completion.js`. Offering a construct the compiler rejects is worse than offering nothing. ### Call completion — the feature worth building Inside a function body, `api.` should complete to the names declared in that page's `apis { }` block, with the method and path as detail. The server already indexes the document to build completions, and the block names are in the AST. This is where the syntax pays off in the editor: the set of legal calls is knowable, so the editor should know it. Without it, `api.` is an empty namespace and every call is typed from memory. Hovering a name inside `api.()` shows its method, path, and declared request fields. ### The `api=` attribute in markup `api="searchUsers({ name: nameFilter })"` is an attribute whose value is a call expression. The HTML service must not flag it as an unknown attribute, and the expression must not be treated as plain text. Completion inside the quotes offers the page's block names, matching the `api.` behaviour. ### Diagnostics for removed constructs An `ssr { api … }` or `client { api … }` block gets a diagnostic naming `apis { }` as the replacement, positioned on the block keyword. The compiler already rejects these; the editor should say so while typing rather than at build time, and it should say what to do instead. ## Inline type errors — verifying, not assuming The `apis` spec generates assertions into `app/types/wrnexus.generated.api-checks.ts`, and `tsc` fails when a block declares a field its endpoint rejects. Whether that failure surfaces **inside the `.wrn` file** has never been confirmed. This spec resolves it in two steps, in order: 1. **Observe the current behaviour.** With a deliberately wrong field in place, open the page in VS Code and record where the error appears: on the block, only in the generated file, or nowhere. 2. **Act on what is observed.** If the error already surfaces usefully, document it and stop. If it appears only in the generated file, map the diagnostic back to the block that produced it — the generator knows which page and block each assertion came from, so the mapping is available if it is recorded rather than discarded. If step 2 proves larger than this spec can hold, it becomes its own work, and the spec says so plainly rather than leaving an unfinished feature implied. **Nothing here should claim inline diagnostics work until someone has seen them work.** ## Testing **Grammar** — a fixture page using `apis { }`, `client state { }`, `functions { shared function }`, and `runtime = "client"` tokenizes correctly; `client` keeps its highlighting everywhere it is still valid. This is the guard against over-reaching removal. **Completion** - `apis` is offered at page level; `ssr` / `client` data blocks are not. - `api.` inside a function body offers the page's declared names with method and path. - Inside `api="…"` in markup, the same names are offered. - Outside those contexts, completion is unchanged — the guard that non-API editing is undisturbed. **Hover** — a name inside `api.()` reports its method, path, and request fields. **Diagnostics** — an `ssr { api … }` block produces a diagnostic naming `apis { }`, positioned on the block keyword. **Bundles** — `check:editor-compiler`, `check:editor-language-server`, and `check:editor-extension` pass. These embed the compiler and language server, so they must be rebuilt after the syntax change; a stale bundle fails the gate. **Manual, and recorded in the implementation notes** — open the migrated `examples/basic-app` in VS Code: `apis { }` highlights, `api.` completes, a removed construct is flagged, and the inline type-error question above is answered by observation. ## Deferred - Mapping generated assertion diagnostics back into `.wrn`, if step 2 above proves too large. - Moving the remaining component intelligence out of `completion.js` and into the server. - Editors other than VS Code.