# HTML editing support for `.wrn` files — Design

**Date:** 2026-08-18
**Status:** Approved for implementation
**Scope:** HTML autocomplete, tag closing, hover, Emmet, and folding inside `view { }` blocks.

## Goal

Writing markup in a `.wrn` file should feel like writing HTML. Today it does not: there is
syntax highlighting but no tag completion, no attribute completion, no tag closing, and no
tag-level folding.

The grammar already declares `embeddedLanguages` (`meta.embedded.block.html` → `html`), which is
why markup _highlights_. That mapping only affects tokenization — VS Code's HTML language
service does not run on `.wrn` documents, so none of the editing behaviour follows from it.

### Non-goals

- **HTML formatting.** See "Formatting is deliberately excluded" below.
- Editor support outside VS Code beyond what standard LSP gives for free.
- Changing `.wrn` syntax or the compiler.

## Decisions

| Question            | Decision                                                                     |
| ------------------- | ---------------------------------------------------------------------------- |
| Features            | Tag/attribute completion, auto-close and rename tags, hover + Emmet, folding |
| Placement           | Shared language server; only auto-close-on-type is VS Code-specific          |
| Completion strategy | One merged list, WRNexus entries ranked above HTML                           |
| Region detection    | Tolerant scanner over a virtual document, not the AST                        |
| HTML knowledge      | `vscode-html-languageservice`                                                |
| Formatting          | Excluded — `formatWrn` already owns markup formatting                        |

## Architecture

### Virtual HTML document

New module: `packages/language-server/src/html-regions.ts`, exporting
`virtualHtmlDocument(document)`.

Everything outside a `view { }` block is replaced by whitespace of **identical length**, with
newlines preserved. The virtual document therefore has the same size and the same line/column
geometry as the source, so a position in the source _is_ the position in the virtual document.
No mapping table and no translation layer.

This is deliberately **not** the same shape as the existing `virtualTypeScriptDocument`, which
compacts code and carries line mappings back to source. Compaction is necessary there because
the output must be valid TypeScript. HTML has no such requirement, so the simpler
offset-preserving form applies, and the class of off-by-one bugs that mapping tables produce
does not arise.

**The load-bearing invariant:** `virtualHtmlDocument(doc).text.length === doc.text.length`, with
newlines at identical offsets. If this breaks, every feature reports positions off by some
amount rather than failing loudly.

### Region detection

Region detection is a tolerant scanner, **not** the `@wrnexus/syntax` parser. Completion fires
while the document is being typed, which is exactly when it does not parse. The scanner finds
`view` followed by `{` and tracks brace depth to the matching close.

Two hazards it must handle, both of which defeat a naive implementation:

- **Apostrophes in text content.** `<p>it's fine</p>` — a scanner treating `'` as a string
  delimiter anywhere will consider the rest of the file one open string and lose every later
  region. Quotes are tracked only inside attribute values, never in text nodes.
- **Nested braces from interpolation.** `class={cond ? "a" : "b"}` and `{{ a: 1 }}` nest, so
  depth must be counted rather than scanning for the next `}`.

WRNexus-specific syntax (`@click`, `client:visible`, `{expr}`) is **not** blanked. The HTML
service tolerates unknown attributes, and blanking would cost region fidelity for no gain.

**Caching** is keyed on document URI and version, so a burst of requests from one keystroke
costs a single scan.

## Completion

### The server becomes the single authority inside view blocks

`textDocument/completion` gains a context check: a position is "in HTML" exactly when the
virtual document is non-blank there, which costs one character lookup.

**Inside a view block**, one list is assembled from two sources:

| Source  | `sortText` prefix | Content                                                                  |
| ------- | ----------------- | ------------------------------------------------------------------------ |
| WRNexus | `0`               | Components, their props/outputs/slots, directives (`@click`, `client:*`) |
| HTML    | `1`               | Tags, attributes, attribute values                                       |

`sortText` drives ordering independently of the label, so components rank above HTML tags
without filtering anything out. **Outside a view block**, behaviour is unchanged: WRN keywords
plus workspace items.

The server already indexes components, props, outputs, and slots
(`buildWorkspaceCompletionItems` in `packages/language-server/src/workspace.ts`), so both halves
of the merge are already available to it.

**Deduplication on exact label match, WRNexus wins.** A component named `Table` and the HTML
`table` differ in case and both survive; a component that genuinely shadows an HTML tag name
resolves to the component.

### Trigger characters

The server currently declares `["<", "@", ":", "."]`. Attributes and values additionally need
`" "`, `"="`, `"\""`, and `"/"`.

### This fixes an existing bug

The extension's `completion.js` registers its own provider with `<` among its trigger
characters, and the language server answers `textDocument/completion` as well. VS Code
concatenates both today, producing duplicate entries and unpredictable ordering before HTML is
involved at all.

As part of this work the extension's provider returns nothing when the position is inside a view
block, and keeps its current behaviour elsewhere. One owner per context.

**Consequence to accept knowingly:** the server becomes authoritative for the richest completion
context, so future component-intelligence work belongs in the server rather than in
`completion.js`.

## Hover

`textDocument/hover` answers from the HTML service over the virtual document when the position
is inside a view region, giving MDN documentation for tags and attributes. Outside a view
region, existing hover behaviour is unchanged.

Where a position resolves to a WRNexus component or prop, the component's own detail wins over
any HTML entry of the same name, matching the completion precedence rule above.

## Tag handling

### Linked editing is standard LSP

Renaming `<div>` and having `</div>` follow is `textDocument/linkedEditingRange` (LSP 3.16), so
it lives in the shared server like everything else.

### Auto-close on type is the one client-side piece

LSP has no request for "close this tag as I type". VS Code's own HTML extension implements it
client-side, and this follows the same shape:

1. The extension subscribes to `onDidChangeTextDocument`, filtered to `wrn` documents.
2. When the typed character is `>` or `/`, it sends a custom request, `wrn/tagComplete`.
3. The server runs the HTML service's `doTagComplete` against the virtual document and returns a
   snippet or `null`.
4. The client inserts it with `insertSnippet`, so the cursor lands between the tags.

The decision stays server-side because it needs parse knowledge: void elements (`<br>`, `<img>`,
`<input>`) must not be closed, and an already-closed tag must not be closed twice. Returning
`null` outside a view region is what stops it firing inside `functions { }` or `style { }`.

Component tags come along for free: `<Card>` closes to `</Card>` because the HTML service closes
unknown tags like any other, and `<Card /` completes to `<Card />` through the same `/` path.

**New setting:** `wrnexus.html.autoClosingTags`, default `true`, following the existing
`wrnexus.*` naming.

### Emmet

A manifest change: `emmet.includeLanguages: { "wrn": "html" }` in `contributes.configurationDefaults`.

**Known limitation:** `emmet.includeLanguages` is per-language, not per-region, so Emmet is also
live inside `functions { }` and `style { }` blocks. VS Code offers no way to scope it to a
region. Emmet only expands on Tab against an abbreviation pattern, so misfires are rare, but the
edge is real.

## Folding

`textDocument/foldingRange` in the server returns tag-level ranges from the HTML service over
the virtual document, filtered to view regions.

Today folding comes only from `language-configuration.json` markers, which work at block level
(`page`, `component`, `view`, braces). Markup does not fold, so a long `<table>` cannot be
collapsed. VS Code merges marker-based folding with provider ranges, so block folding continues
to work unchanged and tag folding appears inside markup.

**One rule:** return ranges only where the virtual document is non-blank. A range spanning
outside a view region would let a fold swallow a brace boundary.

## Formatting is deliberately excluded

`formatWrn` (`packages/syntax/src/formatter.ts`) is 927 lines, iterates to a fixed point with
cycle detection, and already handles tags, attribute wrapping, `multilineAttributes`, and
`printWidth`. It is a markup formatter that understands WRNexus syntax.

Adding HTML formatting would do two harmful things:

- **Two formatters would fight.** Output would depend on which ran last.
- **It would mangle syntax it does not model.** `@click={handler}` and `client:visible` are not
  HTML attributes, and an HTML formatter is free to rewrite spacing inside them.

If markup formatting is unsatisfying, the fix is improving `formatWrn`. That is separate work.

## Dependencies

`vscode-html-languageservice` becomes a dependency of **both** `packages/language-server` and
`editors/vscode`.

The editor bundler (`scripts/build-editor-language-server.mjs`) bundles only workspace sources
and passes other `require`s through to Node, so the package must be resolvable at runtime from
the extension. `editors/vscode` currently ships exactly one runtime dependency
(`vscode-languageclient`); this adds the second.

`check:editor-language-server` already verifies the bundled `.cjs` starts under Node, so a
missing or unresolvable dependency fails the gate rather than shipping a broken VSIX.

## Testing

### Region scanner (`packages/language-server/test/`)

- **The invariant**, property-style across fixtures: virtual text length equals source length and
  newlines sit at identical offsets.
- **Apostrophes in text**: `<p>it's fine</p>` followed by a second view block — both regions
  found.
- **Nested interpolation**: `class={cond ? "a" : "b"}` and `{{ a: 1 }}` do not end the region.
- **Broken markup**: `<div class="` mid-typing still yields a region. This is the normal case for
  completion, not an edge case.
- **Multiple view blocks**, and files with none.

### Completion

- Inside a view block: both sources present, WRNexus `sortText` ordering first.
- Outside a view block: response identical to current behaviour — the guard proving non-markup
  contexts are undisturbed.
- Collision: a component named `Table` yields one entry, the component.

### Tag handling

- `<div>` → `</div>`; `<br>` → nothing; `<Card /` → `/>`; outside a view region → `null`.
- Linked editing returns ranges covering both the opening and closing tag names.

### Hover

- Inside a view region, a known tag returns HTML documentation.
- A component name returns the component detail, not an HTML entry of the same name.

### Folding

- Every returned range lies inside a view region.
- Block-level marker folding still works.

### Toolchain guards

- `check:editor-language-server` passes with the new dependency (bundle starts under Node).
- Manifest assertion that `emmet.includeLanguages` maps `wrn` → `html`, alongside the existing
  marketplace checks in `editors/vscode/test`.

## Deferred

- HTML formatting — see above; improve `formatWrn` instead.
- Moving the remaining `completion.js` component intelligence into the server. This design only
  requires it to stand down inside view blocks; relocating the rest is follow-up work.