RFC: a closed, testable HCON grammar (no regex, hosts interpret maps)

[manwithacat]

HCON is the right kind of thing for a server-rendered attribute language: JSON semantics, less punctuation, lives in HTML attributes. It is not yet a language. Shipping 4.0.0 HCON is a global regex plus a peeler per attribute (hx-swap first token, hx-trigger event[filter], hx-swap-oob style:selector). That last peeler is #4029.

This is an RFC for one LL(1) grammar, a recursive-descent parser, and a Node CI job that does not need Playwright. Shipping src/htmx.js is unchanged.

Claim

• HCON produces maps (or a list of maps). That is the whole language.
• Attribute hosts interpret maps. They do not re-tokenize.
• CSS and JS are string values, never productions. Trigger filters that eval stay outside the grammar.
• Regex is not part of the parser. CI fails if one appears.

Two start symbols (comma cannot mean two things)

Start	Hosts	Pair separator
Map	hx-swap modifiers, hx-vals, hx-config, hx-headers, hx-swap-oob	whitespace
List	hx-trigger	comma between maps, whitespace inside

delay:100ms throttle:200ms is one map. click delay:500ms, keyup is a list of two. delay:100ms, throttle:200ms as a Map is a syntax error (today it is one map).

#4029 is an interpret error, not a parse error

beforeend:#table tbody is a well-formed Map {beforeend:"#table", tbody:true}. A grammar of maps cannot reject it without a swap-style vocabulary. interpretOob rejects a swap-style key whose value is not true and asks for beforeend target:'#table tbody'. Colon form is a second language; HCON should not grow a smarter space heuristic to host it.

Evidence

• Spec: hcon/GRAMMAR.md
• Parser: hcon/src/hcon.js (no regex)
• Corpus vs the shipping regex: hcon/test/corpus.json
• CI job hcon_grammar: node --test hcon/test/*.test.js (Node 20, no Chromium). 40 tests, ~60ms locally.
• Draft PR (not for merge until this discussion lands): will link here.

Quoted values are always strings (count:"42" stays "42"). Leftover input that is not a pair is an error. JSON remains the {...} escape hatch and is not mixed with HCON.

Happy to change any of this. The point is: specify the microlanguage, test it without a browser, then decide whether 4.x adopts it behind upgrade-check.

[manwithacat]

Draft PR (not for merge until this discussion lands): #4047