0023. The TextMate grammar is generated from the language definition
- Status: Accepted (provisional)
- Date: 2026-11-14
- Decided by: integrator (internal only)
- Planning item: none; WP2 grammars and WP3 editors v0
Context
Every editor needs highlighting for page files before the language server exists, and the element list will keep growing. editors/AGENTS.md already says keyword lists are generated from spec/language/, never typed by hand. VS Code, JetBrains (through its TextMate bundle support), Sublime, Zed's fallback and Shiki all read TextMate grammars.
Decision
tools/generate/grammar.tswriteseditors/grammars/duolith.tmLanguage.jsonfromspec/language/elements.yaml;pnpm generateruns it andtools/check-generated.tsfails CI when the committed grammar is stale.- Scopes, so every theme colours page files sensibly:
- elements from the definition:
entity.name.tag.duolith keyword.other.element.duolith(themes show them as keywords); - capitalised tags:
support.class.component.duolith(as JSX components are in VS Code); - any other tag:
entity.name.tag.duolith; prefix:nameattributes such ason:pressandbind:value: the prefix iskeyword.control.directive.duolith; events from the definition areentity.other.attribute-name.event.duolith;- the script block and
{expressions}embedsource.ts;<style>embedssource.css; their content names (meta.embedded.block.script.duolith,meta.embedded.expression.duolith,meta.embedded.block.style.duolith) let editors switch comment and bracket behaviour by language.
- elements from the definition:
- Snapshot tests tokenise fixtures with vscode-textmate and Oniguruma, the same engine VS Code uses, and compare with committed snapshots.
- Editor shells copy the grammar at build time; nothing commits a second copy.
Alternatives considered
| Option | Why not |
|---|---|
| A hand-written grammar | Drifts from the definition the first time an element is added |
| tree-sitter first | Needs a C toolchain and per-editor packaging; planned later for Neovim, Helix and Zed, and does not replace TextMate for VS Code or JetBrains |
| Semantic tokens from the language server only | Nothing to show until WP6, and no highlighting on GitHub or in docs |
Consequences
Adding an element to spec/language/elements.yaml needs pnpm generate and, when a fixture uses the element, UPDATE_SNAPSHOTS=1 pnpm grammars:test with the snapshot diff reviewed. Directive prefixes are matched generically, so a new prefix is highlighted without a grammar change.