---
id: NS-0003
type: northstar
status: ready
title: Hemplate highlighting and editor grammar boundary
refs:
  - docs/editor-support.md
  - docs/hemplate-syntax.md
  - REQUIREMENTS.md
  - README.md
---

## Objective

Make `.heml` highlighting predictable in editors by defining the repo-owned highlighting boundary: HTML/tree-sitter remains the base, hemplate overlays cover only the documented syntax facts, and diagnostics/completion stay owned by `hemx-build`/`hemx-lsp`.

## Authority

- `docs/editor-support.md` says `.heml` should keep normal HTML highlighting and layer hemx-specific editor support on top.
- `docs/hemplate-syntax.md` defines escaped/trusted text, dynamic attributes, control flow, generated hemx targets, and boundaries.
- `REQUIREMENTS.md` `diagnostics/004` through `diagnostics/008` require optional overlays to share authority with `hemx-build` and avoid a second template language or custom editor framework.

## Close when

- Highlighting ownership is explicit: repo-owned fixtures/queries can cover documented hemplate tokens, while external editor distribution remains a separate slice or blocker.
- Tree-sitter work is bounded to syntax highlighting/injection facts and never owns diagnostics, completion, formatting, Rust type checking, or template validation.
- Ready slices distinguish repo-testable grammar/query behavior from editor packaging/publishing work that may require external authority.

## Verification

- `workledger check`
- `workledger list`
- Later implementation slices should use repo-owned fixture/query tests where available; provider-specific visual/manual checks must name the editor and blocker.

## Non-goals

- Do not create a second `.heml` parser for hemx-build.
- Do not make highlighting responsible for compiler diagnostics, completion, hover, formatting, or generated Rust facts.
- Do not publish editor extensions or tree-sitter packages without explicit release authority.

## Evidence

- Current docs already frame `.heml` as HTML first with a small hemplate overlay.
- No current repo authority grants external package publishing; that is represented as a separate blocked/future slice rather than assumed.