The parser grammar

This document is the parser-level specification of MX: how source text is split into tags, attributes, values, bodies, placeholders, scriptlets and text, in HTML mode, concise mode, and the delimited blocks. It is written to be implementable and testable, not to be read as a tutorial.

It is a draft for review by the language lead, who owns language design. Where the language spec, the decision log and divergences.md disagree or are silent, the disagreement is recorded in Open questions for the language lead rather than resolved here. Nothing in this document decides syntax.

Status, sources of truth and method

Decision 157 (2026-10-05) makes the MX parser MX-owned, written in TypeScript, with no obligation to follow upstream (157.1, 157.2). Marko’s behaviour is the default answer wherever MX has no ruling of its own, and Marko byte parity is no longer a requirement (157.3). A divergence needs a decision and a divergences.md row (157.3).

Decision 158 (2026-10-05) fixes the delivery plan:

• MX2 defines its own AST with its own node types in @mxlang/babel. The design removes every accommodation made to fit Marko; decision 158.1 names “no markoTag family inside a patched @babel/types” and “no value: modifier split”, and makes sugars, atoms, attribute tags, wildcard children, defaultTag and <return> first-class nodes with native positions.
• The Marko compiler front end is not copied (158.2, superseding 157 addenda 2 and 4 on that point). @marko/compiler stays an npm dependency only until the MX AST and the ported lowering land. 158.2 kept “decision 151 §1” (the stock-parser diagnostic) for that interim, but decision 159 then made core’s build bundle @marko/compiler’s parse layer with htmljs-parser aliased to the in-repo template parser, so “a registry install of core parses with MX’s rules” (OQ 15).
• Packages (158.3): @mxlang/parser is the template parser (src/template/, derived from htmljs-parser) and, when it exists, the front end from parser events to the MX AST; @mxlang/babel is the vendored Babel fork with the MX node types; @mxlang/tsx-bridge is the MX-region bridge. There is no @mxlang/compiler package: @mxlang/core plus the host emitters are the compiler.

Two rules that this document mentions are implemented today in @marko/compiler, not in the template parser, and their fate differs:

Sources of truth, in this order:

1. the language spec, apps/docs/docs/specification.md (cited as spec §N with the subsection heading);
2. the decision log, notes/decisions-2026-09-10.md (cited as decision N and its addenda);
3. divergences.md at the repository root, cited by its row heading, because its rows carry no numbers (for example divergence row “The parser after-value rule”), plus fixtures/divergences.md.

The htmljs-parser fixtures and the Marko fixtures are evidence of the default behaviour, not a gate.

Decision 146 addenda 4 to 6 and atoms (decision 156 with its addenda 1 to 4 and 8) are implemented on main and are described here as they are, not as planned. Addendum 4 lives in core; addenda 5 and 6 and atoms live in the template parser.

Method: the tables and the probes are the specification

Decision 165 fixes what in this document is normative:

• Normative: every table whose last column is Probes. Each of its rows cites the probes that pin it.
• Informative: everything else, which is all prose and every table without a Probes column. It explains the tables and links them; it states no rule of its own.

A probe is one input, the options handed to the parser, and the parser’s whole ordered event list for it: every event with its ranges and the text read() returns, every error with its code, message and range. The probes are packages/parser/src/template/grammar-spec.corpus.json, and a probe id is written gNNNN. grammar-spec.test.ts runs the corpus against the template parser’s source, patches/htmljs-parser.test.ts runs it against both builds of the patched npm parser, and the first also fails when a row of a normative table cites no probe, when a cited id does not exist, or when a probe is cited by no row. grammar-spec.cases.ts gives the event format and the command that regenerates the expected events after a parser change.

How to read a normative table:

• A row’s cells summarise what its probes’ events show. Where a cell and a probe disagree, the probe is right and the cell is an error in this document.
• A table whose first column is # is in the branch order of the code symbol named above it: the first row whose condition holds is the one that applies.
• An input written x=v stands for <div x=v/>, or for div x=v where the row says concise; \n in an input is a newline. The probe holds the exact input.
• A row that pins a recorded defect or limit names its TODO. Its probes carry that name in the corpus, and the fix for the TODO regenerates them.
• A “Stock: …” remark in a cell, a column headed “Stock”, and the “Without atoms” column of the atoms table describe builds the corpus does not run (stock 5.18.0, and main with atom lexing switched off). They are observations made on 2026-10-06, informative and not probed.
• The probes’ consumer types script, style, textarea, html-comment, html-script and html-style as text tags, input and br as void tags, and static, import, export, server, client and class as statement tags.

The subject is MX’s template parser: the source on main at packages/parser/src/template/ (decision 158.3; read for this revision at origin/main 98f5df47b). It began as a copy of htmljs-parser 5.18.0 and is now MX’s own code; its PROVENANCE.md records its departures from 5.18.0. Code is cited by file and symbol, not by line number.

Stock means htmljs-parser 5.18.0 unchanged (the v5.18.0 tag of htmljs-parser). It appears as a comparison in some cells (“Stock: …”). The departures from stock, with the symbols that carry them:

The bun patch patches/htmljs-parser@5.18.0.patch, which @marko/compiler’s npm copy still runs under in this repository, carries the same after-value, addendum-5 and atom rules (PROVENANCE.md); the corpus and corpus-equivalence.test.ts hold the three builds together.

The parser does not throw (the language lead, 2026-10-06, recorded with decision 165): an internal failure is reported through onError.

Where the parser’s behaviour differs from what a source of truth says, or the parser accepts input that is not valid TypeScript, or rejects input that is, this document records it and raises an open question.

The central design change

The parser stops guessing where an embedded TypeScript expression ends. At the positions in Expression boundaries it will call a real TypeScript expression parser at the value’s start offset, supply stop conditions, and take the end offset back. The vendored @babel/parser 7.29.8 is that parser. Its startLine, startColumn and startIndex options exist and must be supplied with the value’s real base offsets, so a diagnostic column is the column in the MX file. No entry point of the vendored parser returns where an expression stopped yet (OQ 1).

The ruling governing that boundary

The language lead, who owns language design, ruled on 2026-10-05. The ruling has no decision number yet (OQ 22). Verbatim:

the language rule is the spec’s whitespace rule (146 and its addenda); a TS-aware boundary may only make an ambiguous case exact, never accept something the spec rejects.

This document applies it as written and no more strongly:

• Where the spec’s rule (decision 146 and its addenda, as spec §4 “Name sugar” and divergence row “The parser after-value rule” state it) splits or rejects an input, that result stands, and a TypeScript-aware boundary must not continue the value past it.
• Where the spec’s rule applies but its outcome turns on a fact only TypeScript’s grammar supplies, the boundary may supply that fact.
• Where the spec says nothing, the ruling does not decide. The default stands under decision 157.3 until the language lead rules, and the case is listed as not settled.

The table in Where a real TypeScript parser would end the value differently classifies the known differences in those classes.

Vocabulary

These are definitions of terms; the tables that use them carry the rules.

• Position. A place where the parser reads an expression, statement list, type list or pattern: one run of the EXPRESSION state, configured by flags and one stop function (Inventory of positions).
• Depth. The number of open groups in the position (groupStack.length).
• Hard stop. A character for which the position’s stop function (shouldTerminate) returns true (How a position is scanned, step 4).
• Soft stop. Whitespace or a newline in a position whose flags make it one (steps 1 and 3 of the same table).
• Whitespace is a character with code 32 or lower (isWhitespaceCode, util/util.ts). Where a look-behind asks whether a character is whitespace, the excepted characters below count as whitespace too (isUnicodeWhitespaceCode; decision 156, addenda 10 to 12): <div x=(é)\u00a0/ 2/> divides and <div x=a +\u00a0 y=1/> is one value, as with a space (Recorded defects). Current-character and look-ahead tests keep isWhitespaceCode; indent characters are space and tab (isIndentCode); a word character is A–Z, a–z, 0–9, $, _, or a character at or above U+0080 that TypeScript does not read as whitespace or a line terminator (isUnicodeWordCode, util/util.ts; decision 156, addendum 9). Those excepted characters are U+00A0, U+1680, U+2000 to U+200A, U+2028, U+2029, U+202F, U+205F, U+3000 and U+FEFF (isUnicodeSpaceCode). Step 2 of the scan and an atom’s own name use the ASCII part (isWordCode).
• The default is what the template parser does where no MX departure applies. Decision 157.3 makes it the normative answer wherever MX has no ruling.
• Supplied sets. Which names are statement tags, text tags and void tags is answered by the consumer’s onOpenTagName handler, which returns a TagType (TAG_NAME.exit). The AST catalogue makes the statement set and the tag shapes inputs supplied per target (decision 163 addenda 1 and 3; the AST catalogue §3.10 “Statement keywords per target” and §3.12). This document says “the supplied statement set” and “a text tag” for them.

Ranges, and the names the AST catalogue gives them

The parser reports ranges; it builds no nodes. The node types, their fields and their spans belong to the AST catalogue (apps/docs/docs/architecture/ast.md, decision 163), and this document uses its names and does not redefine them. Decision 163, ruling Q10: field names follow the AST, and for every expression container the catalogue’s span is the parser’s value range (the text between the position’s delimiters, inner whitespace included, a tag variable’s / excluded) and its outer is the parser’s event range (delimiters included). A position’s text as written here (“the value”, “the arguments”) is that value range.

A statement tag’s code is reported by no event of its own (E10): the parser reports the name and then onOpenTagEnd where the statement ends, and the catalogue’s MxModuleStatement (§3.10) takes the statement from that range.

Document structure and modes

Parser.parse enters CONCISE_HTML_CONTENT with isConcise = true. The content states:

Concise mode is the parser flag isConcise. CONCISE_HTML_CONTENT sets it, HTML_CONTENT.enter clears it, and PARSED_TEXT_CONTENT leaves it as it was, which is why a delimited block under a concise text tag is still concise mode. “In concise mode” in this document means this flag. Where the flag is read (grep -rnE "(this|parser)\.isConcise\b" states core | grep -v "isConcise = " lists the reads; tag.concise, the copy OPEN_TAG.enter records, is read by TAG_NAME.exit and htmlEOF):

Modes, regions and the end of input (CONCISE_HTML_CONTENT.parse, HTML_CONTENT.parse, OPEN_TAG.enter/OPEN_TAG.exit, Parser.closeTagEnd, htmlEOF):

Close tags (CLOSE_TAG.parse, ensureExpectedCloseTag). </ in HTML content reads to the next >, and the text between is compared:

The literal div in row 2 is OQ 25. Spec §3 “Concise mode” describes the last row as a parse error (OQ 26).

Tags

The open tag

OPEN_TAG.parse:

What the row order means for some inputs:

Tag names

TAG_NAME.parse, for a name and for each shorthand part:

The name forms:

The empty name range is the parser’s signal that the tag is unnamed (the catalogue’s MxTagName kind: "unnamed", ast.md §3.3); core resolves it through the defaultTag ladder (dialect rule 9).

The : split of a static tag name (tag:rest is the tag tag plus name="rest"; divergence row “A static tag name may not contain :”; decision 146, divergence 1) is core’s, after the parse; the parser reports the written head as the name (the rows <:email/> and <a:b:c/> above). A dynamic name is not split (spec §4 “Name sugar”, “Left alone”).

Shorthand #id and .class

A shorthand part is read by the tag-name loop above (TAG_NAME.parse, TAG_NAME.exit):

Core splits the static part of a shorthand class/id value at its first : (divergence row “A shorthand class or id cannot contain :”; decision 146, addendum of 23:23).

Attributes

ATTRIBUTE.parse, which the open tag enters at its rows 13 and 14. “Read” in the Condition column is how far the attribute has got: nothing, a name, arguments, type parameters.

What the row order means for some inputs:

After each part is read (ATTRIBUTE.return):

async methods (isAsyncMethodPrefix, flushPendingAsync): how a leading async is read.

The attribute forms:

Attribute names

A name is an EXPRESSION position with the flag terminatedByWhitespace (ATTRIBUTE.parse, row 13; Inventory), scanned by How a position is scanned. Its hard stops:

The ambiguous > check

detectAmbiguousCloseAngleBracket runs in HTML mode after an attribute name and after an attribute value that ended at a space or tab followed, on the same line, by >. From that > it scans on by the table below. It reports Ambiguous ">" in attribute. … when the scan reaches a later top-level > not followed by =, or a top-level />, that is preceded by an operand; otherwise the first > ends the tag.

Whether the TypeScript-aware boundary keeps this check is OQ 8.

Tag arguments, tag variables, tag parameters and types

Each of these begins at row 14 of The open tag; the positions are E6, E7, E9, E14 to E17 below.

That a tag must not have both arguments and plain attributes is not a parser rule (see Status; decision 109). Spec §8 “Tag params” gives the parameters’ meaning.

Attribute tags

What an attribute tag means is decided after the parse: its name is a property key, so the : split does not apply (decision 146, addendum 3; spec §4 “Name sugar”, “Attribute tags”); attribute-position sugar on it does apply; placement and collision rules are in spec §8 “Collisions and placement”; an attribute tag on a native element is rejected (spec §8 “Deferred to MX 2”).

Placeholders

${expr} interpolates escaped and $!{expr} interpolates raw (spec §3 “Interpolation”); the value is position E8 (checkForPlaceholder).

Scriptlets and statement tags

Scriptlets $ statement and $ { … } are position E11 and are rejected on every host (spec §3 “Scriptlets”).

Statement tags are position E10. A tag is a statement tag when its name is in the supplied statement set: when the consumer’s onOpenTagName returns TagType.statement (TAG_NAME.exit).

The sets are the AST catalogue’s (ast.md §3.10, “Statement keywords per target”; decision 163, addendum 3): the language’s import, export, static, server, client and class; on the data target import, static, export; and today an empty set on the hosts and parseFragment callers that MX1 TODO statement-tags-not-declared-on-five-hosts names.

Text, comments, CDATA, doctype, declarations and text bodies

HTML content

HTML_CONTENT.parse, first matching row:

CDATA sections and declarations parse to events and are rejected in lowering (spec §3 “CDATA sections and XML declarations”).

Text bodies

A text body is the body of a tag the consumer typed TagType.text. In this repository the consumer’s set is html-comment, html-script, html-style, script, style, textarea (TEXT in packages/core/src/close-tag-opener.ts). PARSED_TEXT_CONTENT.parse:

Spec §3 “CDATA sections and XML declarations” describes a raw-text body as “a single MarkoText” and lists <title> among them; both differ from the rows above (OQ 13).

Concise mode: indentation and line rules

CONCISE_HTML_CONTENT.parse takes a line’s leading whitespace as its indentation and then acts on the first other character:

The open tag’s concise-mode rows are in The open tag; a value that reaches the end of a line is E2. Spec §3 “Concise mode” says these rules are inherited from Marko and fixed by no MX decision.

Whitespace at the parser level

The template parser reports text as raw source ranges (htmlEOF, handleDelimitedBlockEOL):

The whitespace rules of spec §3 “Whitespace” (boundary trimming, dropping a whitespace-only run that begins with a newline, collapsing runs to one space, ignoring comments, the preserveWhitespace bypass) are applied by the consumer of the parser’s events, not by the parser. Today that is @marko/compiler’s onText. When @marko/compiler is dropped (decision 158.2), the design intent is that the MX layer taking its place applies them once (decision 158.3 puts the front end from parser events to the MX AST in @mxlang/parser) and that core and hosts do not re-normalize (spec §3 “Whitespace”). This is a statement about consumers, not a parser rule.

Base position for fragment parses

parse(code, options?) (index.ts, Parser.parse) takes an optional base position for the case where code is a substring of a larger file: startOffset, startLine (zero-based) and startColumn (zero-based) (ParseOptions, core/Parser.ts). The source copy has this API; the patched npm builds do not, so these probes run on the source copy.

Positions are UTF-16 code units. This is the base the AST catalogue’s fragment rule (ast.md §5.3) builds on: the catalogue adds base.offset to every reported range when it builds a node.

Error conditions

The template parser’s own messages:

End of input inside a position (End of input has the rule and the silent cases); the message depends on the state that owns the position:

End of input in the opaque spans and outside a position, and the other conditions:

Rejections raised outside the template parser, by core: scriptlets, CDATA and declarations (spec §3); a second : in a tag head, a bare : in attribute position, a :name that is not an identifier (divergence rows; spec §4 “Name sugar”); sugar after a default value (decision 151, ruling 2; spec §4 “Name sugar”, “Left alone”), except after a single-atom default value (decision 146, addendum 5); duplicate attributes, a warning with the last occurrence winning (decision 135); the atom misuses of spec §4 “Atoms”. The catalogue’s list of front-end codes is ast.md §3.13.

Expression boundaries

A place where a TypeScript expression, statement list, type list or pattern appears in MX source is one run of the parser’s EXPRESSION state. This section gives the scan they share, then the inventory of positions, then each position.

How a position is scanned

A position is created with a start offset, a stop function shouldTerminate, and flags (EXPRESSION.enter). This table says where each flag is read; the rules themselves are the rows it points to.

State the position keeps as it scans:

EXPRESSION.parse, for each character:

Source: EXPRESSION.parse; canFollowDivision for the division test. What the steps and the character table mean together, for some inputs:

The continuation test

checkForOperators, called at a newline (step 1) and at whitespace (step 3) of the scan, at depth 0:

Look-behind table (lookBehindForOperator). c is the character immediately before the whitespace:

Look-ahead table (lookAheadForOperator). n is the next character found in step 4:

What as and satisfies do to the type context is read 7 of The type context. MX changes the : and . rows for an attribute value (E1 overrides).

Source: checkForOperators, lookBehindForOperator, lookAheadForOperator, lookBehindForKeyword, and the keyword tables at the top of states/EXPRESSION.ts (unaryKeywords, jsUnaryKeywords, tsUnaryKeywords, binaryKeywords, relationalKeywords).

The type context

The type context is the flag inType.

Leaving it is the = and { rows of the character table (reads 5 and 6 below).

The reads of inType (grep -nE "\.inType\b" states/*.ts | grep -v "inType = " lists them), with an input on each side:

Reads 3 and 4 are in the look-behind table. Its callers (grep -n "lookBehindForOperator(" states/EXPRESSION.ts), each with an input inside and outside a type context:

Which positions enter the type context, and which reads each can reach, is the last column of the inventory.

Consequences:

End of input

EXPRESSION.parse, after its loop:

Per position:

div(a and $ {a end silently because their ( and { were consumed by the owning state (OPEN_TAG.parse, INLINE_SCRIPT.parse) and are not on the position’s group stack. The rows that lose an event are recorded defects (below; OQ 19).

Inventory of positions

The enterState(STATE.EXPRESSION) calls in the parser’s source (grep -rn "enterState(STATE.EXPRESSION)" states util; the one in util/validators.ts is a validation helper for callers of the parser’s API and is not a place in a template). For each: the flags and hard stop it sets, and how the position can enter the type context with the reads of that section it can then reach.

The positions with the atoms flag are where atoms are lexed (decision 156, addendum 2; the AST catalogue’s table “Where the atom lexer runs”, ast.md §4.3). An attribute’s ( branch opens one position whether the attribute turns out to have arguments or to be a method, so a method’s parameters lex atoms too (decision 163, addendum 1). Tag shorthands and tag names are read by TAG_NAME.parse, not by a position.

E1 — Attribute value, HTML mode

The value starts after the = or := and the whitespace that follows it (ATTRIBUTE.parse, rows 5–6 of Attributes). Hard stops (shouldTerminateHtmlAttrValue):

Overrides (MX). The after-value rule of divergence row “The parser after-value rule” (decision 146, divergence 3, with addendum 6) and decision 146, addendum 5. Condition © of the : row is addendum 6: after whitespace, “a : starts a new attribute only when it is followed by an identifier start, or is bare before >, />, a newline or the end of input”.

The first two rows are look-ahead rows, so they apply at step 7 of the continuation test: after whitespace whose preceding character is not a look-behind operator. On stock, which has no after-value rule, the inputs of the next table are one value, apart from x=a : before /> (the regular-expression error) and before > (Mismatched group).

The digit exclusion is OQ 4.

Default attribute. A value with no name has attrValue off (decision 151, ruling 2; divergence row “The parser after-value rule”); core reports :name after such a value as an error (spec §4 “Name sugar”, “Left alone”). A default value that is one single atom splits at :name (decision 146, addendum 5). On stock the inputs of this table are one value.

E2 — Attribute value, concise mode

The value starts as in E1. Hard stops:

Soft stops are as in E1 with the concise-mode steps 3 and 4 of the continuation test. A value continues onto the next line in these cases:

Otherwise the newline ends the value and the attribute; the open tag then ends too, unless the next line begins with , or the tag is inside [ … ] (rows 1–2 of The open tag). The inputs are concise:

A TypeScript parser continues across the newline where the next line begins with <, ., (, a binary operator, ? or in; the default continues where the current line ends with a keyword operator or a lone ., even onto a line at column 0, which spec §3 “Concise mode” calls a sibling (OQ 18).

E3 — Spread attribute

The value starts at the character immediately after ..., with no whitespace skipped (ATTRIBUTE.parse, row 7), so whitespace there is the first thing the scan sees, with the third dot before it. It is the same call site as E1 and E2.

E4 — Attribute arguments

onClick(a, b): from the character after ( to the ) at depth 0.

E5 — Attribute method body

onClick(a) { … }: from the character after { to the } at depth 0; the content is a statement list.

E6 — Tag arguments

<Tag(expr)>: from the character after ( to the ) at depth 0 (OPEN_TAG.return decides what follows).

E7 — Tag parameters

<Tag|a, b|>: from the character after | to the next | at depth 0. The content is a parameter list (spec §8 “Tag params”).

E8 — Placeholder

${expr}, $!{expr}: from the character after ${ or $!{ to the } at depth 0.

E9 — Tag variable

<Tag/x>: from the character after /. Hard stops (shouldTerminateHtmlTagVar, shouldTerminateConciseTagVar):

The flags are E1’s (Inventory), so the scan, the continuation test and the type context apply as there.

E10 — Statement tags

A tag whose name the consumer types TagType.statement (Scriptlets and statement tags; TAG_NAME.exit, prepareStatement, prepareScriptlet). The position begins at the character that ended the tag name and has no hard stop; no event carries the statement’s text, and the open tag ends where the position ends. It ends at a newline by step 1 of the scan with the flags of the inventory, or at end of input:

The other type-context inputs are in the inventory.

E11 — Scriptlets

$ statement, $ { … } (HTML_CONTENT.parse, isBeginningOfLine, INLINE_SCRIPT.parse, INLINE_SCRIPT.return). After the $ the whitespace is consumed; { then begins the block form, which runs to its } at depth 0, and anything else the line form, which has the flags of the inventory and no hard stop. The line form:

The second row is OQ 24.

E12 — Delimited HTML blocks

A delimited block begins with a run of hyphens (--, ---), as a concise line of its own or after a concise open tag (row 4 of The open tag). BEGIN_DELIMITED_HTML_BLOCK.parse, Parser.beginHtmlBlock:

At each newline inside a multi-line block the following line is tested (handleDelimitedBlockEOL):

A line that ends the block by row 3 is then read by the concise indentation rules:

E13 — Interpolation in a tag name or shorthand

<${expr}>, <div.${x}>, <div#${x}>: from the character after ${ (TAG_NAME.parse, row 2) to the } at depth 0.

E14 — Tag type arguments

<Tag<A, B>>: the character after a < read at row 14 of The open tag, to the > at depth 0 (OPEN_TAG.return). The flags and the type-context reads are in the inventory.

E15 — Tag type parameters

<Tag <A, B>|x|>, <Tag <A, B>(x) { … }>: as E14, for a < that is not directly after the tag name. After it (OPEN_TAG.return), whitespace is skipped and then:

E16 — Attribute-method type parameters

<div onClick<T>(a) { … }>: the character after a < read at row 9 of Attributes; flags and stop as E14.

E17 — Tag-level default method

<Tag(a) { … }>: parameters are position E6 and the body position E5 (OPEN_TAG.return).

Types inside the other positions

TypeScript’s own type syntax (as, satisfies, annotations, generic arguments) is not a separate MX position. In the default it is handled by the type context. In the planned design the TypeScript parser reads it and returns the end offset, and each position’s hard stops still bound the value.

Atoms

An atom is :name written where an expression is expected, in a position that lexes atoms (decision 156; spec §4 “Atoms”). The template parser finds atoms, reports them and reserves ::; it gives them no meaning. The catalogue node is MxAtom (ast.md §4.3).

Where atoms are lexed

In the positions whose EXPRESSION has the atoms flag (Inventory of positions; decision 156.1 and addendum 2; ast.md §4.3 states it per catalogue field):

At a : (lexAtom)

In a position with atoms, a : the scan reaches in its character table goes to lexAtom before the ternary and type handling:

A name (atomNameEnd) is [A-Za-z_$][\w$]*(-[\w$]+)*:

Is an expression expected? (expectsExpression)

Word characters here are those of Vocabulary, so a non-ASCII identifier is an operand (decision 156, addendum 9). An atom’s own name is ASCII (lexAtom, rows 3 and 4).

expectsExpression scans backwards from the character before the :, skipping whitespace and each comment already read in this position, and stops at the position’s start. p is the character reached:

Unicode whitespace (decision 156, addendum 10; isUnicodeWhitespaceCode): in the atom look-behind the characters excepted from the word characters behave as ASCII whitespace. In this table   stands for the character U+00A0 at that place in the input; the second probe of a row is the same input with a space there.

Operator words (isOperatorWord), for rows 5 and 11. The word is the run of word characters ending at p, within the position:

A type argument list’s closing > (closesTypeArguments), for row 6. It scans backwards from the >, counting each > not preceded by = up and each < down, and each closing bracket ) ] } up and each opening one down:

More inputs:

The reserved :: outside expressions

rejectReservedName reserves :: in the static text of a tag name and shorthand part (Tag names) and in an attribute name’s range (Attributes):

How atoms interact with the other rules

Lexing an atom changes where a value ends through the code paths of this table. The last text column is the same input read without atom lexing, run on a probe build: main’s source with its atoms = true assignments set to false, which keeps the after-value rule. Where stock, which has neither, differs from the probe build, the cell gives stock too. The probes pin main.

What the parser reports

The stand-in exists for consumers that hand read() text to Babel (today @marko/compiler); the catalogue’s front end builds the atom’s StringLiteral with extra.mxAtom itself (ast.md §4.3, §7).

Dialect rules

MX’s own rules, with the layer that applies each: the template parser or core, after the parse. The list summarises the sources it cites; what the parser reports for each form is the table after it.

1. Tag-adjacent sugar. #x sets an id, .x a class and :x a name, on a named tag or the unnamed tag (decision 146 and its addendum of 23:23; spec §4 “Name sugar”). Layer: the parser reports the written head (Tag names, Shorthand); core splits it.
2. Attribute-position sugar, first or after a boolean attribute. The parser reports attributes named #x, .x, :x; core rewrites them to id, class and name (spec §4 “Name sugar”, “In attribute position”).
3. Attribute-position sugar after a value. :x and .x after a value are new attributes through MX’s after-value rule (E1 overrides; decision 146, divergence 3). The default attribute’s value is exempt (decision 151, ruling 2), except when it is a single atom (decision 146, addendum 5).
4. The sugar’s value. :name takes an identifier, [A-Za-z_$][\w$-]*; #x and .x take what a shorthand part takes (spec §4 “Name sugar”). The after-value rule tests the character right after the sigil (E1 overrides; OQ 4).
5. A sugar followed by =value or (params) { body } sets the tag’s default attribute (decision 146, addendum 4). Layer: core (packages/core/src/name-sugar.ts). The catalogue records the result as MxShorthand.operator and default (ast.md §3.6).
6. Left alone (spec §4 “Name sugar”, “Left alone”; decision 146, divergence 2 and addendum 3): the named forms class:x, style:x, value:fn:=x and the explicit value:x; a dynamic tag name; a bound attribute; the default attribute; an attribute tag’s own name.
7. Repeated sugars follow the duplicate rule: the later one wins, with a warning (decision 135; spec §4 “Name sugar”).
8. A bare : in attribute position is a positioned error from core (divergence row “Bare :x is name="x"”).
9. The unnamed tag and defaultTag (decision 145). The parser reports an empty name range; by design it writes no tag name there. Core resolves the name afterwards: parent contract defaultTag, then user config package.json#mx.<target>.defaultTag, then the host override, then the target’s built-in (decision 145, addendum 2). An invalid defaultTag value is an error at its declaration (decision 145 and its addendum 1).
10. Wildcard children (decision 147) add no syntax: a child keeps its authored tag name, and <:att> yields a child whose name is att.
11. Atoms (decision 156 and its addenda 1 to 4 and 8 to 10). :name in an MX expression position is a value that represents itself; its runtime value is the name as a string (156.1, 156.2). Layer: the template parser lexes it and reserves :: (Atoms); core gives it meaning and raises the misuse errors of spec §4 “Atoms”.

Ternary depth

The counter is the ? and : rows of the character table.

Ambiguous inputs

Each row gives an input and the parse the grammar requires. Where the parser reports a name and core gives it meaning, both are given.

Open questions for the language lead

The numbers are stable across drafts, because the text cites them. An item that has been settled says so in place, with the decision or ruling that settled it. The list is informative: where an item says what the parser does with an input, it restates a row of the table after the list, and that row is the normative one.

1. End offset from the expression parser. The vendored @babel/parser has no entry point that returns where an expression stopped; startIndex fixes only the start. Recommendation: a thin wrapper, owned by the parser lead, that returns the node and its end index, built first.
2. Where the default and a TypeScript parser end a value differently. The cases are in the table below, each with its class under the 2026-10-05 ruling. Recommendation: rule the rows of class © one by one; until then the boundary reproduces the default for them, as decision 157.3 requires.
3. ??, ?. and ?:. MX’s after-value rule stops ?? and ?. from opening a ternary, and tests pin it, but no spec paragraph or decision states it, and ?: still counts as a ternary (and on main x=a ?:b reads :b as an atom). Recommendation: state ?? and ?. in the spec as what “no open ?” means, and decide whether x=a ?:b is an error.
4. . followed by a digit. The after-value rule does not split x=a .2xl, while spec §4 “Name sugar” says .2xl works as a class “in both positions”. Recommendation: keep the exclusion and say so in the spec, or align the positions.
5. Spreads. MX applies the after-value rule to a spread (...props .b splits); the spec text and divergence row speak of “an attribute value”. Recommendation: rule spreads in explicitly.
6. | inside tag parameters and tag variables. <foo|x: A | B|/> ends the parameters at the first |, and <let/x: A | B = 1/> ends the variable there. Recommendation: require parentheses around a union or bitwise or in both positions, and say so in spec §8.
7. Generic calls and generic arrows in an HTML-mode value. x=f<T>(y) and x=<T,>(a) => a are cut at > with no error. Recommendation: the TypeScript-aware boundary consumes the type arguments; rule whether E1’s > stop yields to it.
8. The ambiguous > error. Recommendation: keep it; a TypeScript parser cannot tell > the operator from > the tag end either.
9. Atoms in a ternary. Settled by decision 156 and spec §4 “Atoms” (“an atom’s own : is never the ternary’s”): x=a ? :b :c is one value on main (Ternary depth).
10. Wording of the parser’s own errors. Messages such as A semicolon indicates the end of a line. Only comments may follow it. and the HTML comment error are the stock parser’s; no MX source says whether MX keeps the wording. Recommendation: keep them and pin each with a fixture.
11. Spec §4 contradicts itself on a bare :foo. Spec §4 “Attribute forms” (row “Namespaced name”: :foo=y is “Marko’s own attribute named value:foo”) and spec §4 “:modifier” (<div :foo="y"/> “is one attribute literally named value:foo”; <div :/> is value:) say the opposite of spec §4 “Name sugar” and divergence row “Bare :x is name="x"”, which decision 158.1’s “no value: modifier split” also supports. (The earlier question here, :x=1 listed as an error, is settled: spec §4 “Name sugar” now states decision 146 addendum 4.) Recommendation: rewrite the two value: paragraphs for named heads only (x:foo, value:foo) and point bare :foo at the name sugar.
12. $!{…} in an attribute value. The template parser accepts it as value text; spec §3 “Interpolation” says “Marko’s parser rejects it”. Under decision 158 there is no Marko compiler; which MX layer raises it? Recommendation: the expression parse at the boundary, with an MX message.
13. Text bodies. The parser recognises placeholders, strings and template literals in a TagType.text body, and an unbalanced quote there is an end-of-input error (<textarea>don't</textarea>), and a backslash does not escape a quote there, so valid JavaScript such as <script>var s = "a\"b";</script> is that error too; spec §3 “CDATA sections and XML declarations” says such a body is “a single MarkoText” and lists <title>, which the consumer’s TEXT set does not contain. Recommendation: amend the spec to “text and placeholders”, decide whether quotes stay significant in textarea, honour \ escapes in a text-body string, and settle title.
14. Atoms outside the first ruled positions. Settled: decision 156, addendum 2 (every ${}; “script blocks” are statement blocks), decision 163 (ruling C11 and addendum 1: attribute arguments and method parameters, method bodies, and never the tag variable, tag parameters or type lists) and the lead ruling of 2026-10-05 on method bodies. The positions are in Atoms.
15. Spec §4 “Consumers on a stock parser” and divergence row “The parser after-value rule” describe the stock-parser diagnostic of decision 151, ruling 1. Decision 157 addendum 3 removed it, 158.2 kept it for the interim, and decision 159 makes core bundle the in-repo template parser, so a published core no longer reaches it. Recommendation: the paragraphs lapse now (decision 159), not at the drop of @marko/compiler; keep only the sentence for a caller that bypasses the bundle, as spec §4 “Atoms” already does.
16. A tag name’s first character. A leading digit is accepted (<1abc/>). Recommendation: state the terminator rule in the spec, or add a rule and a diagnostic.
17. The operator exemption. A hard stop written directly after an operator is consumed (x=a + ,b is one value; x=a +/> is a regular-expression error). Valid TypeScript is affected, because the look-behind table counts a legal identifier spelled like a unary keyword and a non-type >: <div x=async/> is the value async/, <div x=async, y=1/> the value async,, concise div x=async\n span swallows the child, and div x=f<T> ,y=1 (a trailing instantiation expression) is one value. Recommendation: make the stop unconditional and let the expression parser report a +.
18. Newline continuation. In concise mode a value continues past a newline only in the cases E2 lists. Some of them reach a line that spec §3 “Concise mode” would call a child or a sibling: a keyword operator or a lone . at the end of the line draws in the next line at any indentation (div x=a instanceof\nB swallows a column-0 line), and so does a trailing look-behind operator (div x=a +\nspan). In HTML mode the look-ahead crosses newlines, which yields values such as a\n <span. Recommendation: keep the concise rule, and rule whether a continuation may reach a line at column 0, and whether HTML mode keeps the look-ahead across a newline.
19. End of input with an open delimiter, in concise mode. div x=(a is an error; div(a, $ {a, div|a, div<A, div (a, div onClick(a) {b and, under a concise text tag, script -- ${b end silently, because the delimiter is not on the position’s group stack. These lose an event entirely: div.a${b (no shorthand event), ${x (no event at all) and a template literal’s ${ in a concise value (span\n div x=`${a: no value event). Recommendation: an error in each case.
20. :: followed by whitespace. Settled by decision 156, addendum 2 (“:: is the reserved token in every position MX lexes”): on main x=a :: b is the reserved-token error (Atoms).
21. Agreement with the AST catalogue. Settled by decision 163, ruling Q10: field names follow the AST; a container’s span is the parser’s value range and outer its event range. This document adopts both (Ranges).
22. The 2026-10-05 boundary ruling has no decision number, so nothing outside this document can cite it and divergences.md has no row for it. Recommendation: number it in the entry that fixes the boundary mechanism (OQ 1).
23. x=a !b and x=a ++b. The default reads each as one value, which is not a TypeScript expression; TypeScript reads a! and a++ and stops. No spec text covers either. Recommendation: let the boundary end the value after a! and a++, which turns a later compile error into x plus a boolean attribute b; confirm that this is wanted.
24. Valid TypeScript that the default rejects or cuts, beyond OQ 7: concise div x=a as T > b (Mismatched group); an arrow type at the top level of a type list (<foo<() => void>>, onClick<T extends () => void>(a) {}); a block comment after an operator (x=a + /* c */ b ends at the comment); a space between a trailing operator and the newline in a scriptlet or statement ($ a = 1 + ⏎); ... [a] and ... "s"; <div x=/* c */ a/>, a block comment at the value’s start, is the value /* c */ and then an attribute a; and the exemption cases of OQ 17. One oddity on the other side: a , line after a statement tag adds attributes to it. Recommendation: treat each as a defect for the TypeScript-aware boundary to remove; none is covered by spec text.
25. div in close-tag matching. <.a></div> is accepted because the parser compares against the literal div for an unnamed tag, whatever defaultTag resolves to (decision 145). The htmljs fixture shorthand-closing-html2 pins it. Recommendation: accept only </> for an unnamed tag, or compare against the resolved name in core.
26. A close tag in a concise region. Spec §3 “Concise mode” says closing tags are a parse error there; the parser reports one only when no tag is open or the name differs, and div\n </div> closes the concise div. Recommendation: make it an error, as the spec says.
27. The character after a -- run. It is skipped unexamined (--abc is the text bc). Recommendation: require whitespace or the end of the line after the hyphens.
28. Decision 146, divergence 3 and the : condition. Settled by decision 146, addendum 6: “a : starts a new attribute only when it is followed by an identifier start, or is bare before >, />, a newline or the end of input”, amending the divergence row’s wording. x=(a) : T => a stays one value (E1).
29. await :name. Settled by decision 156, addendum 8: addendum 3’s rule restated by addendum 2’s principle, “a : TypeScript could own is TypeScript’s” (Atoms, operator words, rule 5).
30. Statement tags and their “attributes”. Spec §2 “Syntax” says import, static and export parse as tags whose “attributes are the remaining words”. With the statement set supplied, the parser reports no attributes for them (E10); without the set the words are attributes. Recommendation: correct spec §2 when MX1 TODO statement-tags-not-declared-on-five-hosts lands.
31. A template literal’s ${} in a text body. Decision 156, addendum 2 makes “every ${} placeholder” an atom position, <script> bodies included. A template literal inside a text body is text to the parser, so its ${…} is no placeholder and lexes no atom (<script>`${:a}`</script>). Recommendation: confirm that addendum 2 means placeholders only.
32. Non-ASCII identifiers before an atom. Settled by decision 156, addendum 9: the atom look-behind treats as a word character any character at or above U+0080 that is not Unicode whitespace or a line terminator (U+00A0, U+1680, U+2000 to U+200A, U+2028, U+2029, U+202F, U+205F, U+3000, U+FEFF), and decision 156, addendum 10: those excepted characters are skipped as ASCII whitespace is. Main implements both (isUnicodeWordCode, isUnicodeWhitespaceCode; Atoms).

The inputs the open questions mention:

Where a real TypeScript parser would end the value differently

“Default” is main’s result. The class is assigned from the spec text and decision 146 under the 2026-10-05 ruling:

• (a) the spec’s rule applies and its outcome turns on a fact only TypeScript’s grammar supplies; a TypeScript-aware boundary may make the case exact;
• (b) the spec’s rule, in text that exists, decides the input; that result stands and the boundary must not change it;
• © the spec is silent; the default stands under decision 157.3 until the language lead rules. The last column notes whether TypeScript’s reading would accept anything the spec rejects.

Recorded defects in the default

These behaviours are defects or recorded limits, not grammar. Each row pins today’s behaviour; the probes of a row with a TODO carry its name in the corpus.

The behaviours of OQ 13 (no \ escape in a text-body string), OQ 17, OQ 24, OQ 25 and OQ 27 look like defects as well and are not filed. An implementer must not treat a row of this table as intended grammar.

Conformance

The probe corpus (decision 165) pins the rows of this document’s normative tables on the three builds (Method). Beside it: the htmljs fixtures, upstream’s fixture directories kept byte-identical in packages/parser/src/template/__tests__/fixtures/ and run by upstream-suite.test.ts, which are evidence of the default behaviour and not a gate; mx-after-value.test.ts (the after-value rule, re-pointed from patches/htmljs-parser.test.ts); mx-atoms.test.ts over the case table mx-atoms.cases.ts; __tests__/base-offset.test.ts; and corpus-equivalence.test.ts, which pins identical event streams between this source and the patched npm build. Where the fixtures and MX’s other tests exercise a section:

Further probes

These probes are the inputs written in earlier review rounds to attack the rules above. They are grouped by the kinds of event the parser reports for the input, in order (×n is a run of the same kind; an error is given by the start of its message). A row states that sequence; the probes hold the ranges and the text.