docs(editor): define hemplate highlight boundary

Document the repo-owned .heml highlighting overlay tokens and exclude diagnostics/completion/formatting/build validation from highlighting authority.

req: diagnostics/004

req: diagnostics/008
This commit is contained in:
slhx agent
2026-06-26 00:16:47 +02:00
parent 5d38d0ca0a
commit 34327d6b8f
2 changed files with 24 additions and 2 deletions
+22
View File
@@ -67,6 +67,28 @@ The one-shot command prints a JSON object shaped like LSP
The diagnostic payload comes from `hemx-build`; editor integrations should display
it as-is instead of recreating the rule.
## Highlighting boundary
Repo-owned `.heml` highlighting is an HTML overlay, not a new language. Normal
HTML highlighting owns tags, attributes, strings, comments, folding, and tag
matching. The hemplate overlay may highlight only documented syntax tokens from
`docs/hemplate-syntax.md`:
- escaped text delimiters and expression regions: `{+` and `+}`;
- trusted/rendered HTML delimiters and expression regions: `{+=` and `=+}`;
- dynamic attribute prefixes such as `+class`, `+disabled`, and `+aria-label`;
- structural directives: `h-if`, `h-for`, `h-key`, `h-match`, and `h-case`;
- hemx facts recorded as ordinary attributes: `data-hemx-root`,
`data-hemx-slot`, `data-hemx-form`, `data-hemx-handle`, and other checked
`data-hemx-*` authoring attributes.
Highlighting must not own diagnostics, completion, hover, formatting, Rust
expression parsing, selector behavior, generated Rust facts, or build
validation. Those remain with `hemx-build`, `hemx-lsp`, normal HTML tooling, and
Rust tooling. Repo tests for highlighting should therefore be fixture/query tests
for captures over these token classes; provider packaging or visual editor smoke
is a separate release slice and cannot become syntax authority. req: diagnostics/004 req: diagnostics/008
## VS Code and Cursor
Use the shared repo extension in `editors/vscode-hemx` for VS Code and Cursor.
+2 -2
View File
@@ -1,7 +1,7 @@
---
id: SLICE-0010
type: slice
status: ready
status: done
parent: NS-0003
title: Define repo-owned hemplate highlighting boundary
refs:
@@ -36,4 +36,4 @@ Turn "tree-sitter highlighting for hemplate" into a bounded repo-owned contract:
## Evidence
The docs already establish `.heml` as HTML plus a small overlay; this slice makes that boundary executable before writing queries.
Done at commit `5d38d0c` follow-up and verified with `workledger check`: `docs/editor-support.md` now lists repo-owned overlay token classes, explicitly excludes diagnostics/completion/hover/formatting/Rust parsing/build validation from highlighting authority, and names fixture/query tests as the repo-owned proof boundary before provider packaging.