The MX AST

Status: draft for review (decisions 158 and 163). Owners: mx-lead (IR, lowering) and native-parser (parser, node types). The MX AST, its front end and the ported lowering are not implemented yet. Section 1 describes what exists today; sections 2 to 9 are the proposal, and where they describe today’s code (the IR’s atoms in §4.3, the shorthand merge in §6.1a, today’s statement and error behaviour) they say so. Every statement about Marko, htmljs-parser or the current code cites the file and symbol it was read from (Marko’s installed bundle by line), or a probe that was run.

Decision 158 gives MX2 its own syntax tree: node types defined in MX’s Babel fork (@mxlang/babel), built by a front end in @mxlang/parser from the template parser’s events, and read directly by lower() in @mxlang/core. This page is the catalogue those three pieces are built from.

Citation shorthand. [C] is the installed compiler, node_modules/.bun/@marko+compiler@5.42.10/node_modules/@marko/compiler/dist/. [H] is the installed template parser, node_modules/.bun/htmljs-parser@5.18.0/node_modules/htmljs-parser/dist/. Template-parser source is cited in this repository, under packages/parser/src/template/ (htmljs-parser 5.18.0 copied in, byte-identical to upstream except states/ATTRIBUTE.ts and states/EXPRESSION.ts, which carry the MX patch as source; see its PROVENANCE.md). “The IR spec” is the IR specification. Paths without a prefix are relative to the repo root. “Probe” means a script run on 2026-10-05 against the installed compiler, kept outside the repo under ~/tmp/mx2-ast/ (raw.ts: parse-only translator, as parseFragment uses; core.ts: MX’s core taglib registered the way packages/targets/html/src/compiler.ts host registers it).

Version. The workspace resolves @marko/compiler 5.42.10 (the only copy under node_modules/.bun/; bun.lock, its @marko/compiler entries; packages/core/package.json dependencies) and htmljs-parser 5.18.0 with the MX patch (root package.json: devDependencies htmljs-parser and patchedDependencies). The compiler’s own htmljs-parser link resolves to the same patched 5.18.0 copy. A research note citing 5.42.5 predates commit c2e521347.

1. Marko AST as it is

1.1 Where the node types live

Marko’s thirteen node types are declared in a patched @babel/types 7.29.7 bundled into the compiler: [C]babel.js:8065 opens the region @babel+types@7.29.7_patch_hash=…/lib/definitions/marko.js, and defineAliasedType("Marko") defines every type at [C]babel.js:8069-8280. The TypeScript declarations are at [C]types.d.ts:3630-3716, and the Marko types are members of Babel’s own Node union ([C]types.d.ts:381). The same patch adds a non-standard params field to Program ([C]types.d.ts:576, [C]babel.js:5511), which the compiler fills with a single input identifier ([C]chunk-src.js:6447).

Every node extends Babel’s BaseNode: optional start, end, loc, range, comments and extra ([C]types.d.ts:369-378).

Positions in practice. MX never sees start/end on a Marko node. The compiler’s parserOverride returns types.cloneNode(file.ast, true) ([C]chunk-src.js:6710), and Babel’s cloneNode copies only the declared fields, loc, comments and extra, never start/end ([C]babel.js:13217-13241). Probe raw.ts on <div#a.b x=foo :y/> confirms it: every Marko node has start === undefined; Marko nodes carry loc without index; Babel expression nodes inside them carry loc.start.index. packages/core/src/fragment.ts shiftNode relies on exactly this (“Present on plain Babel nodes only; absent on Marko’s own”).

1.2 The thirteen node types

Optionality is from the defineType field definitions; “default” means the builder fills the value. “Read by” lists the MX reading sites (all under packages/, tests excluded); “not read” means no MX source reads the field.

MarkoTag

Defined [C]babel.js:8233-8280; declared [C]types.d.ts:3704-3714. Aliases Marko, Statement.

Also set at runtime but not a declared field, so dropped by the clone: tagDef ([C]chunk-src.js:6080). Not in the builder but declared in the d.ts: none beyond the table.

MarkoTagBody

Defined [C]babel.js:8200-8232; declared [C]types.d.ts:3696-3702. Aliases Marko, BlockParent, FunctionParent, Scope, Scopable (it is the Babel scope for tag params). Probe: it carries no loc.

MarkoAttribute

Defined [C]babel.js:8162-8193; declared [C]types.d.ts:3681-3689. Alias Marko only (not Expression, not Statement).

MX adds four ad hoc fields to attributes it synthesizes for name sugar: sugarNameSpan, sugarLabel, sugarAt and real start/end (core/src/name-sugar.ts sugarAttr, mergeClassTokens); lower.ts attrNameSpan, lowerAttr and lowerAttrNamed read them.

MarkoSpreadAttribute

Defined [C]babel.js:8194-8199; [C]types.d.ts:3691-3694. One field, value: Expression, required. Read by lower.ts lowerAttrNamed.

MarkoText

[C]babel.js:8115-8119; [C]types.d.ts:3658-3661. value: string, required, already whitespace-normalized by the front end ([C]chunk-src.js:5985-6037). Read by lower.ts lowerChildList, isLayout, lowerIfChain, authoredChildTree; core.ts hasContent.

MarkoPlaceholder

[C]babel.js:8120-8131; [C]types.d.ts:3663-3667. value: Expression required; escape: boolean default true. Read by lower.ts lowerChildList (both fields).

MarkoScriptlet

[C]babel.js:8132-8151; [C]types.d.ts:3669-3674. body: Statement[] required; static: boolean default false; target: "server" \| "client" optional. MX reads only the type: lower.ts lowerChildList rejects every scriptlet (decision 54). static and target are not read; they are never set by the front end either ([C]chunk-src.js:6067 builds markoScriptlet(block.body)).

MarkoComment

[C]babel.js:8104-8114; [C]types.d.ts:3652-3656. value: string required (delimiters stripped); kind: "html" \| "line" \| "block" optional, set by getCommentKind ([C]chunk-src.js:6250-6256). MX reads value (lower.ts lowerChildList) but not kind: it re-derives “is this an HTML comment” by slicing the source (lower.ts lowerChildList).

MarkoCDATA, MarkoDocumentType, MarkoDeclaration

[C]babel.js:8099-8103, :8089-8093, :8094-8098; [C]types.d.ts:3647, :3637, :3642. Each has one required value: string, delimiters stripped (probe: <!doctype html> gives "doctype html", <?xml v?> gives "xml v"). MarkoDocumentType.value is read by lower.ts lowerChildList; MarkoCDATA and MarkoDeclaration are rejected by type (lower.ts lowerChildList, decision 139).

MarkoClass

[C]babel.js:8152-8161; [C]types.d.ts:3676-3679. Aliases Marko, Statement, Class. One field, body: ClassBody. The front end never builds it ([C]chunk-src.js has no markoClass( call); it is produced by Marko’s translator for the class tag. No MX source references it.

MarkoParseError

[C]babel.js:8069-8088; [C]types.d.ts:3630-3635. Aliases Marko, Expression, Statement, so it can stand in any expression or statement slot. Fields: source: string and label: string required, errorLoc: object \| null optional. Built by createParseError ([C]chunk-src.js:1027) when a Babel sub-parse fails; it also sets file.___hasParseErrors. Probe on <div x=(1 +)/>: the attribute’s value is MarkoParseError { source: "(1 +)", label: "Unexpected token", errorLoc: { start: { line: 1, column: 11, index: 11 } } }. Read by lower.ts exprOf (label, errorLoc, loc), core/src/stock-parser.ts stockParserError, hosts/solid/src/compile.ts repairEmbeddedTsx (source).

1.3 Marko’s front end, handler by handler

parseMarko ([C]chunk-src.js:5887-6249) implements 24 of the template parser’s 27 handlers ([H]util/constants.d.ts:64-90). It does not implement onOpenTagStart, onCloseTagStart or onCloseTagName.

Expression parsing ([C]chunk-src.js:947-1016): each position is parsed by wrapping the slice and passing startIndex/startLine/startColumn, so the Babel node’s positions are file-relative: params as (${str})=>{} with offset 1 (956), arguments as _(${str}) with offset 2 (961), a tag var as (${str}\n)=>{} (966), type arguments as _<${str}> (978), type parameters as <${str}>()=>{} (983).

1.4 How MX gets a Marko tree today

Two entry points, both through compileSync:

• parseFragment (packages/core/src/fragment.ts) with PARSE_ONLY_TRANSLATOR (fragment.ts): no core taglib. Probe: import x from "./y" parses as a MarkoTag named import with attributes x, from and "./y"; class { x = 1 } as a tag class with one attribute named { x = 1 }. name-sugar.ts CORE_STATEMENT_TAGS carries a fallback list of statement tag names for exactly this case.
• compileSource (packages/core/src/compile.ts) with the host’s translator (compile.ts createTranslator), which registers MX’s core taglib (packages/core/src/taglib/core-tags.json; statement: true, rawOpenTag: true for import, static, export, client, server, class at lines 75-90; controlFlow: true for if, else, else-if, for at 4-16). Probe core.ts: the same statement then parses as a MarkoTag named import with no attributes and rawValue: "import x from \"./y\"". lower() runs in the translator’s Program.exit (compile.ts createTranslator).

2. Accommodations removed

One row per thing Marko’s AST or front end does to fit Marko. “Why” is Marko’s reason as far as the source shows it; where the source does not say, the row says “not stated”.

3. MX nodes

3.0 Naming scheme

Every type this catalogue defines is Mx + a PascalCase noun (MxDocument, MxTag, MxAttribute). Two kinds of Mx type exist:

• Nodes have a type discriminator equal to their name and a span, and are members of the MxNode union below. Expression containers (§4) are nodes too: they have a type and a span, but they only appear in fields, never in a child list.
• Field shapes (MxTagName, MxShorthandValue, MxCloseTag) have no type; each is documented with the field that holds it.

Span is the one unprefixed helper. No name starts with Marko (criterion 11). Collision check: the Babel fork’s node types in packages/parser/src/babel/types.ts contain no Mx prefix (rg 'type: "Mx' returns 0), while unprefixed candidates would collide (Placeholder is a Babel type in packages/parser/src/babel/types.ts, as is TemplateLiteral).

interface Span { start: number; end: number }      // §5
interface MxNodeBase extends Span { type: `Mx${string}` }

type MxChild =
  | MxTag | MxAttributeTag | MxReturn | MxText | MxPlaceholder
  | MxScriptlet | MxComment | MxCDATA | MxDoctype | MxDeclaration
  | MxModuleStatement;

type MxNode =
  | MxDocument | MxChild
  | MxAttribute | MxShorthand | MxSpreadAttribute | MxMethod
  | MxParseError | MxAtom
  // expression containers (§4)
  | MxExpression | MxStatements | MxPattern | MxArguments
  | MxParameterList | MxTypeArguments | MxTypeParameters;

Offsets in the examples are [start, end) within the example line alone (a whole file starting with that line), computed by script.

3.1 MxDocument

Purpose: the root of a parse (a whole .mx file, an .astro.mx template body, or a region/fragment).

There is no document-level mode: htmljs decides concise or HTML per line, and each MxTag.concise records it per tag.

Spans: start = base.offset, end = base.offset + source.length (not length - 1, unlike [C]chunk-src.js:6241). A leading byte-order mark is skipped by the parser (packages/parser/src/template/core/Parser.ts Parser.parse), so the first node can start at offset 1.

Example: the document for <p>x</p> is [0, 8) with body one MxTag [0, 8), errors empty, complete: true.

Invariants: body is in source order; every node’s span lies in [start, end]; complete === false iff errors ends with a template-parser error (§3.13).

3.2 MxTag

Purpose: an element, component call, structural tag, custom tag or dynamic tag. The AST does not decide which: resolution is lowering’s (spec §7).

MxCloseTag is { span: Span; name: string \| null; nameSpan: Span \| null }: span is </ through >; name is the written closing name, sugar included (</div:x> gives "div:x", spec “Name sugar”, specification.md (“Name sugar: :name, #id and .class anywhere on a tag”); divergences.md, row “A static tag name may not contain :”), from onCloseTagName; name and nameSpan are null for </>. The front end does not compare it with the open name: htmljs reports MISMATCHED_CLOSING_TAG (code 21, [H]util/error-code.d.ts) itself.

Spans: start is the < in HTML mode (Marko does the same, [C]chunk-src.js:6075), the first head character in concise mode. end is the end of the onCloseTagEnd range: the end of closeTag when one was written, the end of openTag for a self-closed or void tag, and for a concise block the end of its last descendant (probe on div.a\n -- some text ${y}\n span#b: the tag’s loc ends at 3:8, the end of span#b). For an incomplete tag, end (and openTag.end, when onOpenTagEnd had not arrived) is the start of the template-parser error. Sub-spans: name (§3.3), each head part’s own span (§3.4).

Source forms and example:

<Row<string>/row(a, b)<T>|item: T| class="x">${item}</Row>

Offsets ([start, end), this line alone):

• tag: [0, 58); openTag: [0, 45); closeTag.span: [52, 58), closeTag.nameSpan [54, 57)
• name.span: [1, 4) (Row)
• typeArgs: [5, 11) (string), outer [4, 12)
• var: [13, 16) (row)
• args: [17, 21) (a, b)
• typeParams: [23, 24) (T)
• params: [26, 33) (item: T)
• attributes[0]: [35, 44); body[0] (MxPlaceholder): [45, 52)

Invariants: params !== null iff pipes were written; head parts appear at most once each (a second one is an htmljs error, which stops the parse, §3.13); body never contains MxModuleStatement (top level only, §3.10); bodyMode === "void" implies body === null and closeTag === null.

HTML-mode statement tags. <import …>, <static …> and the other statement keywords written with < are an MxParseError with code MX_STATEMENT_IN_HTML_MODE and Marko’s message (statementTagInHTMLModeError, [C]chunk-src.js:6087, :6278-6284); the front end produces an MxModuleStatement only for a concise top-level line. Unlike Marko, which throws, the error is recorded and the parse continues (this error is the front end’s, not the template parser’s).

<%. Marko rejects the tag name % (“<% scriptlets %> are no longer supported”, [C]chunk-src.js:6079). MX has no such tag; <% is an MxParseError MX_RESERVED_TAG_NAME with the same message, recorded the same way.

3.3 MxTagName

A field shape of MxTag (no type).

type MxTagName =
  | { kind: "static"; value: string; span: Span }
  | { kind: "dynamic"; expression: MxExpression; span: Span }  // <${x}>, <my-${x}>
  | { kind: "unnamed"; span: Span };                            // <#a>, <.b>, <:c>, concise #a

• static: the authored name with the head sugar removed. The written name (htmljs’s onOpenTagName range) is split at its first : (specification.md (“Name sugar: :name, #id and .class anywhere on a tag”); decision 146, 23:23 addendum): before it is value, from it on is a tag-position MxShorthand { sigil: ":" } (§3.6). <input:email> is value: "input", span [1, 6). So value never contains : (divergences.md, row “A static tag name may not contain :”). An empty part before the : (<:email>) makes the name unnamed. Marko splits attribute names at the last : (A2); that rule does not apply here. Attribute tags are not split (§3.7). Because the split happens after htmljs has read the name, htmljs still sees the written name input:email when deciding whether the tag is void or may self-close, so <input:email type="email"/> needs its /> in HTML mode and the closing tag repeats the written name (specification.md (“Name sugar: :name, #id and .class anywhere on a tag”)). Which table decides self-closing after @marko/compiler is dropped (today its self-closing-tags dependency, bun.lock) belongs to the element-shape table (§3.12, ruling Q21).
• dynamic: htmljs reports a Template (packages/parser/src/template/util/constants.ts Ranges.Template). expression is the whole name as one container, built by Marko’s template-string rule (parseTemplateString, [C]chunk-src.js:5954-5973), which the front end keeps on purpose (the “replaced” of A17 does not apply to it): one ${…} with both quasis empty is that expression, except that a StringLiteral result is wrapped in a one-quasi TemplateLiteral (<${"div"}>, [C]chunk-src.js:5962-5963); any other name is a Babel TemplateLiteral over the whole written text. It is needed because Expr.code for a dynamic name is printed from that node today (`my-${x}`, `div`; §7.1, generator row). There is no separate list of quasis or inner expressions: they would re-parse the same text into a second Babel tree. span covers the written name, ${ and } included.
• unnamed (decision 145): span is empty, at the offset right after < (concise: at the first sugar character). Lowering resolves it through the defaultTag ladder (spec “The unnamed tag”); the AST never writes div.

Examples (<input:email>, <${x}>, <.card>): static [1, 6); dynamic span [1, 5), expression.span [3, 4); unnamed [1, 1).

3.4 Head parts: MxPattern, MxArguments, MxParameterList, MxTypeArguments, MxTypeParameters

Each is an expression container (§4) with a specific Babel payload. One span rule for all five: start/end cover the text inside the delimiters (htmljs’s value range); outer: Span covers the delimiters too (htmljs’s event range) (Ranges.Value, packages/parser/src/template/util/constants.ts).

For a method, htmljs’s AttrMethod.params range includes the parentheses and its value excludes them (packages/parser/src/template/states/ATTRIBUTE.ts ATTRIBUTE), so MxParameterList for onInput(e) { … } has span (e)'s inside and outer the parenthesised text.

3.5 MxAttribute

Purpose: one named attribute, or the tag’s default value.

Spans, one rule: start = min(nameSpan.start, value?.start) and end = the end of value, of args, or of nameSpan, whichever is last. The min matters for an async method, whose range starts at async, before the name (packages/parser/src/template/util/constants.ts Ranges.AttrMethod; ATTRIBUTE.ts ATTRIBUTE; probe: <div async onLoad<T>(e: T) { a() }/> gives the method 1:5-1:34 and the name 1:11). For the default value, start is the = (or () and nameSpan is zero-width there (htmljs reports an empty onAttrName range). For an expression value, value.span is htmljs’s AttrValue.value (after =/:= and whitespace, ATTRIBUTE.ts ATTRIBUTE).

<input disabled type="email" value:=draft onInput(e) { set(e) }/>

Offsets:

• disabled: [7, 15), nameSpan the same, operator and value null
• type="email": [16, 28); nameSpan [16, 20); value.span [21, 28) (quotes included, as the IR’s string spans)
• value:=draft: [29, 41); name: "value", operator: ":="; value.span [36, 41)
• onInput(e) { set(e) }: [42, 63); nameSpan [42, 49); value is an MxMethod [49, 63)

Invariants: operator === ":=" implies value is an MxExpression (bound attribute); value.type === "MxMethod" implies operator === null. The AST records every default value written, and never decides whether a second one is an error: that depends on the host and on the position (an attribute-position #x=1 is no default value on a host that claims #, P8), so the rule is lowering’s (§6.1a, MX_DUPLICATE_DEFAULT). Lowering reads a default value (name: null) as the attribute value through one adapter, with the zero-width nameSpan kept (IR invariant E7): the one Marko convention MX keeps on purpose, because every tag reads its default input as value. Bound attributes keep their full name: value:=x is name: "value", because htmljs reports := as the operator (part.bound, [C]chunk-src.js:6127).

3.5a MxMethod

Purpose: method shorthand, name(params) { body }, as an attribute value or a sugar’s default (onAttrMethod).

Spans: htmljs’s AttrMethod range: from async when written, else from the type parameters’ <, else from (, through } (ATTRIBUTE.ts ATTRIBUTE). There is no Babel FunctionExpression in the AST; lowering builds the one Attr needs from params, typeParams and body (Marko builds it in the front end, [C]chunk-src.js:6131-6138).

Example: in <b onInput(e) { set(e) }/>, the method is [10, 24), params [11, 12) (outer [10, 13)), body [15, 23) (outer [14, 24)).

3.5b MxSpreadAttribute

Purpose: ...expr in the attribute list (onAttrSpread).

Spans: start at the first ., end at the end of the expression (onAttrSpread range, ATTRIBUTE.ts ATTRIBUTE); value.span is the expression only. Example: in <b ...rest/>, the node is [3, 10) and value.span [6, 10). Invariants: no name, no nameSpan, no sugar (IR spec §6, spread row); it takes part in source order with the other attributes.

3.6 MxShorthand (#id, .class, :name)

Purpose: the three name sugars in any position (decision 146 and addenda).

type MxShorthandValue =
  | { kind: "static"; value: string; span: Span }
  | { kind: "dynamic"; template: MxExpression; quasis: Span[];
      expressions: MxExpression[]; span: Span };   // tag position only: <div.a${x}>

Spans: start = the sigil; end = end of value (not of default, which has its own span). value.span excludes the sigil. The node’s span is the authored token (#x, .c, :n), kept exactly: lowering takes Attr.sugar and, on a host that claims #, the attribute name #x from it (P8, §6.1).

What each sigil takes (specification.md (“Name sugar: :name, #id and .class anywhere on a tag”)): :name an identifier, [A-Za-z_$][\w$-]*; #x and .x what Marko’s shorthand takes, a run up to whitespace, =, (, /, |, <, , or >, with . and # starting the next part.

Splitting a shorthand value: one rule for both positions. htmljs reports a tag-adjacent #d:b as one onTagShorthandId Template (reviewer’s probe: [4, 8) for <a.c#d:b …>), and an attribute-position .c#m.d:y as one attribute name. The front end splits each into MxShorthands with the same rule (specification.md (“Name sugar: :name, #id and .class anywhere on a tag”); today rewriteHead and rewriteAttributes in core/src/name-sugar.ts, where the attribute-position chain is cut into ./# parts outside any ${…} by splitShorthandChain):

1. Static value: split at its first :. .c:b gives .c and a tag-position :b. A second : anywhere in the tag head is an MxParseError MX_SECOND_NAME at the second : (spec: “a tag takes one name”).
2. Dynamic value: only the static tail after the last ${…} splits. <a.${x}:b> gives . with a dynamic value (template over ${x}) and a static :b.
3. A : in a static part before a ${…} (<a.c:b${x}>) is an MxParseError MX_COLON_BEFORE_DYNAMIC at that :.
4. A value left empty by a split (<a.:b>) produces no MxShorthand for that sigil (tag position, rewriteHead); in attribute position an empty part (., #) is an error, as today (rewriteAttributes: “. needs a name after it”).
5. A ${…} in an attribute-position shorthand is an MxParseError MX_SUGAR_DYNAMIC at its sigil (today: “a dynamic shorthand works only tag-adjacent”, rewriteAttributes).
6. Arguments without a body after a sugar (#x(p), .c(p), :x(p)) are an MxParseError MX_SUGAR_ARGUMENTS at the sugar (today checkNearSugar, two branches: #/. and :). With a body, #x(p) { … } is a method default (decision 146 addendum 4), operator: null.
7. := after a sugar (:n:=y, .c:=y, #x:=y) is operator: ":=" and an MxParseError MX_SUGAR_BOUND at the sugar (“a bound value is not supported on name sugar”, checkNearSugar), except where the sugar is not one: attribute-position #x on a host that claims # (P8). Because that depends on the host, the front end records MX_SUGAR_BOUND for : and . only, and lowering raises it for #. Today, a :n:=y whose value cannot be bound (not an identifier or member expression) keeps the ordinary bound value error instead (checkNearSugar, bindable).

<a.c#d:b title="t" .big :mail/>

Offsets:

• tag position: .c [2, 4) (value.span [3, 4)), #d [4, 6), :b [6, 8) (split out of htmljs’s #d:b [4, 8))
• attribute position: .big [19, 23), :mail [24, 29)
• <a.${x}:b>: . [2, 7) with value.span [3, 7) and template.span [5, 6); :b [7, 9)

Invariants: a tag has at most one : sugar in its head; value.kind === "dynamic" implies position === "tag"; default !== null implies position === "attribute" (tag-adjacent <a#x=1> is an ordinary default attribute, MxAttribute { name: null }, because htmljs ends the shorthand at =); operator === null and default !== null implies default is an MxMethod; order within shorthands and within attributes is source order, so the spec’s class-order rule can be applied by lowering without positions. Atoms: :name standing alone in attribute position is this node (decision 156 §4); :name inside an expression is an MxAtom (§4.3).

3.7 MxAttributeTag

Purpose: <@name> — a property of the nearest enclosing tag.

Fields: the same as MxTag (§3.2) except name, which is { value: string; span: Span }: value is the key without @, span covers @name as written (Marko’s name loc does the same; probe: StringLiteral@1:7-1:12 for @head). Head sugar is not split: <@svg:rect> keeps value: "svg:rect" (decision 146 addendum 3); attribute-position sugar applies.

Example: in <Card><@head x=1>H</@head></Card> the attribute tag is [6, 26), name.span [7, 12), name.value "head", and it is body[0] of Card.

Invariants: always somewhere under an MxTag (Marko throws “@tags must be nested within another element”, [C]chunk-src.js:5917; MX records an MxParseError MX_ATTRIBUTE_TAG_AT_ROOT and keeps the node); never moved: an <if> holding attribute tags keeps them in its own body (§8 D2). Because nothing moves, two things Marko’s front end did at parse time become lowering’s, at today’s positions (P7): the error “Cannot have attribute tags and body content under a control flow tag.” (Marko throws it at the first body child, [C]chunk-src.js:6206; lowering already raises the same message for the multi-branch and nested cases, lower.ts lowerAttributeIf and lowerAttributeTags, and takes over the single-tag case at Marko’s position), and comments directly before an attribute tag, which Marko moves into attributeTags with it ([C]chunk-src.js:5918-5926) and lowering skips as layout.

3.8 MxText

Spans: the node span is the whole onText range, newline-led whitespace included (formatters need the authored run). valueSpan in a normalizing body is Marko’s withLoc range ([C]chunk-src.js:6029-6033): start = part.start + rawValue.indexOf(trimmed) and end = start + trimmed.length, where trimmed is the text after the newline-led runs at each end were removed and before inner whitespace was collapsed into value; in a preserving body it equals the node span. Lowering writes Text.span from valueSpan, which keeps it exactly what it is today (the goldens are unchanged). Concise -- text lines produce MxText too, starting after -- .

Examples: <p> a\n b</p> gives value: " a b", span [3, 10), valueSpan [3, 10); <p>\n a</p> gives span [3, 7) and valueSpan [6, 7); <pre> a\n b</pre> gives value: " a\n b" (probe: Marko keeps the newline and the spaces for <pre>, which marko-html.json marks preserveWhitespace, [C]chunk-src.js:3606).

Invariant: in a normalizing body, a run that normalizes to "" produces no node (its whitespace is layout, with no node, as in Marko); raw is never empty; valueSpan lies inside the node span.

3.9 MxPlaceholder

Spans: start at $, end after }; expression.span inside the braces. Source forms: ${x} in HTML content, in parsed-text bodies (<script>: the probe shows a MarkoPlaceholder inside <script>), and a bare ${expr} concise line.

Example: in <p>$!{html}</p> the placeholder is [3, 11) with escape: false; expression.span [6, 10).

3.10 MxModuleStatement, MxScriptlet, MxStatements

MxModuleStatement — a statement keyword of the target (see “Statement keywords per target” below) written as a concise top-level line.

Spans: the htmljs statement range, right-trimmed of whitespace: start at the keyword, end after the last non-whitespace character on the line, so a trailing same-line comment is inside the span (today’s statementSpan, lower.ts, which trims the Marko range whose end sits on the next line; IR spec §3.3, Import/Export/Static row). code.span is Babel’s statement range, which ends before such a comment; it is not the source of any IR text.

What lowering takes from where (P2):

Example: static const A = 1 // trailing is [0, 30) and Static.code is const A = 1 // trailing (the reviewer’s probe d); code.span is [7, 18).

end is a separate fact (decision 163 addendum 1). Today end is endPosOf(node) (lower.ts), Marko’s loc.end of the statement tag, which is not trimmed: it is the end of htmljs’s statement range, trailing whitespace and following line breaks included (reviewer’s probes: static const A = 1 then <div/> gives end { line: 1, column: 21 } with span [0, 18); export const B = 2 followed by two blank lines gives end { line: 3, column: 0 }). The port reproduces it from the untrimmed range. Two readers use it: the TypeScript plugin’s block mapping (mx-language.ts locateSourceCode, item.end) and Astro’s statement mappings (astro-template.ts, statement.end). Whether they depend on it is being measured under MX1 TODO statement-end-untrimmed.

Invariants: only in MxDocument.body; export interface Input is an MxModuleStatement { keyword: "export" } whose payload is a TSInterfaceDeclaration. Splitting it out is lowering’s, by payload type, keeping today’s asymmetry: export interface Input becomes InputInterface (lowerStatement, lower.ts), while export type Input stays an ordinary Export in the IR but is still read as the template’s own input (lower.ts lowerTemplate, which matches interface|type).

Statement keywords per target (decision 163 addenda 1 and 3). The keyword set is an input to the front end, supplied per target, beside tagShape (§7.1). The language’s set is the same six on every target, import, export, static, server, client and class, with one documented exception: on the data target class, client and server are vocabulary names, so its set is import, static, export. A keyword outside the target’s set is an ordinary tag name there: server and client are MxModuleStatements only where the target’s set includes them (Q5/P5).

Today, by target:

On the last row a statement line parses as a tag with attributes (probe: static const a = 1 is the tag static with attributes const, a), and lowering recovers Static/Import/Export by name (lowerAuthoredTag’s switch) and by slicing the source (lowerStatement); isStatementTag (name-sugar.ts) answers from the compile’s lookup, so the name sugar runs on those tags under compileSource and does not under parseFragment (CORE_STATEMENT_TAGS). This is an accident, not a rule: MX1 TODO statement-tags-not-declared-on-five-hosts (decision 163 addendum 3) makes those hosts pass the core set before the port, with the moved goldens listed in that change, so the port carries nothing.

MxScriptlet — $ stmt and $ { block }.

Spans: from $ to the end of the statement or }. Example: $ const z = 1; is [0, 14), code.span [2, 14). MX rejects scriptlets (decision 54, lower.ts lowerChildList); the node exists so the error is positioned.

MxStatements — the expression container (§4) for statements: MxExpressionContainer<Statement[]> & { type: "MxStatements" }. Span: the statement text only; for a method body or a scriptlet block, inside the braces, with outer including them. Used by MxModuleStatement.code, MxScriptlet.code, MxMethod.body.

3.11 MxComment, MxCDATA, MxDoctype, MxDeclaration

Each of the four has type equal to its name (MxNodeBase, §3.0).

Examples: <!-- a --> is [0, 10), valueSpan [4, 7); <![CDATA[ d ]]> is [0, 15), valueSpan [9, 12); <!doctype html> is [0, 15), valueSpan [2, 14); <?xml v?> is [0, 9), valueSpan [2, 7).

MxComment also appears in MxTag.attributes for an open-tag comment (onOpenTagComment). Invariant: value === source.slice(valueSpan.start, valueSpan.end).

3.12 Body modes and tagShape

MxTag.bodyMode records the parse shape tagShape(name) answered at onOpenTagName (the value the front end returns to htmljs as a TagType, [H]util/tag-type.d.ts):

Preserving mode lasts until the tag that started it closes, and applies to every descendant text (Marko’s preservingWhitespaceUntil, set at [C]chunk-src.js:6082 and cleared at :6185).

A custom tag’s openTagOnly is not a parse shape: core forwards only text and preserveWhitespace to the parser (custom-tags.ts customTagTaglib) and enforces openTagOnly in lowering with a positioned call-site error (specification.md (“9.4 Units”)). tagShape never answers "void" for a custom tag.

bodyMode is a parse fact, not the IR’s Element.void: lowering keeps taking Element.void from VOID_TAGS (core/src/core.ts, read at lower.ts lowerAuthoredTag; IR spec §5.5).

Invariant: in a parsed-text* body no MxTag appears; <x> inside <script> is text (probe: MarkoText " <x>"), and so is <b> inside <title>.

The table also records, for each name it knows, whether that name is an element. Today that is the html flag of Marko’s tag definition, which contractDefaultTag’s isStructural (core/src/contract-default-tag.ts) reads to treat a known non-element (await, define) as structure (§6.4).

Who owns the table. The element-shape table belongs to the target descriptor, with a core default (the html family’s void, text and preserve-whitespace elements); a target overrides entries, as the data target does today (targets/data/src/taglib.ts neutralizations). It is one table with two readers: the front end’s tagShape and decision 145’s check that a defaultTag has a plain parse shape (adr-default-tag.md (“Decision”)).

Shape before shadowing (ruling Q23). tagShape answers from the name alone, before lowering knows whether a file-local binding shadows that name (§3.15, D3). A file-local component named pre therefore still has its body parsed with whitespace preserved, as today: Marko makes the same choice at the same point ([C]chunk-src.js:6080, the tagDef lookup in onOpenTagName).

3.13 MxParseError and what a failed parse contains

Three producers, with different consequences:

1. The template parser (htmljs) stops at its first error. Parser.emitError calls onError and then sets this.pos = this.maxPos + 1 (packages/parser/src/template/core/Parser.ts Parser.emitError), and parse loops while (this.pos <= maxPos) (Parser.parse), so no event follows onError: no close events for open tags, no further text. One parse therefore yields at most one template error. (Marko throws on it, [C]chunk-src.js:5975-5984, so MX today gets no tree at all.)

2. Expression sub-parses fail per container and do not stop the template parse (Marko’s tryParse returns a MarkoParseError and continues, [C]chunk-src.js:1009-1015). There may be any number. When an attribute value written { … } fails and parses once the braces are removed, the message gets Marko’s hint “Attribute values in Marko are plain JavaScript expressions, not JSX; remove the wrapping { }” (withWrappedAttrValueHint, [C]chunk-src.js:6292-6297), reworded for MX (“… in MX …”).

3. Front-end rules are recorded and do not stop the parse. Each has a code. The ones that exist today as positioned errors in core/src/name-sugar.ts (and, for the last three, in Marko’s front end) are:

   Code	Today	Where today
   MX_SECOND_NAME	a second :name on a tag (<a:b:c>, <a.c:b:d>, :x:y, .c:x:y)	SECOND_NAME in rewriteHead, checkNearSugar, rewriteAttributes
   MX_COLON_BEFORE_DYNAMIC	a : before a ${…} in a shorthand	headNamesIn
   MX_SUGAR_NAME_MISSING	a sigil with nothing after it: : in a tag name with no name, a bare attribute-position :, an empty ./# part	checkToken, checkNearSugar, rewriteAttributes
   MX_SUGAR_NAME_INVALID	a :name that is not [A-Za-z_$][\w$-]*	checkToken, rewriteAttributes (SUGAR_TOKEN)
   MX_SHORTHAND_INVALID	an attribute-position .x/#x word Marko’s shorthand would not accept	rewriteAttributes (isShorthandWord)
   MX_SUGAR_DYNAMIC	a ${…} in an attribute-position shorthand	rewriteAttributes (“a dynamic shorthand works only tag-adjacent”)
   MX_SUGAR_ARGUMENTS	arguments without a body after a sugar	checkNearSugar
   MX_SUGAR_BOUND	:= after a sugar (front end for : and .; lowering for #, §3.6 rule 7)	checkNearSugar (BOUND_ON_SUGAR)
   MX_SUGAR_ON_STATEMENT	a :name on a statement keyword (<import:x/>)	rewriteNameSugar
   MX_STATEMENT_IN_HTML_MODE	<import …> written with <	Marko, [C]chunk-src.js:6087
   MX_RESERVED_TAG_NAME	the tag name %	Marko, [C]chunk-src.js:6079
   MX_ATTRIBUTE_TAG_AT_ROOT	an attribute tag with no enclosing tag	Marko, [C]chunk-src.js:5917

   A duplicate default value is not among them: it is lowering’s (MX_DUPLICATE_DEFAULT, §3.5, §6.1a), as is MX_SUGAR_BOUND for #. This table lists front-end errors only. Errors lowering raises (those two, “Cannot have shorthand id and id attribute.” of §6.1a, the control-flow attribute-tag error of §3.7, and every error lowering raises today) are out of this document’s error table: they keep today’s text and position, and coding them is the IR spec’s “Errors” section (decision 162). Today every one of them throws, so only the first is reported; as data, all are kept (decision 162).

All three go into one list, MxDocument.errors, ordered by span.start, with the template error (at most one) last even when an earlier-recorded entry starts after it.

What the AST contains when the template parser reports an error (from the parser code above, not from what would be desirable):

• MxDocument.complete is false; errors ends with the template error.
• Every node whose closing event arrived before onError is complete and exact.
• Every tag still open at that point (the error’s ancestors) exists with incomplete: true, closeTag: null, and end = the error’s start; its body holds the children completed before the error.
• The construct the parser was inside exists only as far as its events arrived: htmljs emits each attribute part when that part ends and a text run when the next construct starts, so an attribute whose onAttrName arrived but whose value did not is an MxAttribute with value: null, and a text run pending at the error is absent. A consumer tells such a part from a genuine bare attribute only by the error’s start falling inside the tag’s head; the front end does not mark it.
• Nothing exists at or after the error’s start.

What a consumer such as the language server may rely on: the template error’s code, message and span; every expression and front-end error before it; and every complete node. It must not rely on the shape of an incomplete tag’s head or body beyond what is listed, and it gets no diagnostics for the text after the error. There is no parser recovery (ruling Q20 (a), decision 163): a parse yields at most one template error, and recovery is not planned until a tool can project a partial template, which is a lowering feature.

What compileSource does with the errors. complete === false implies the document is not lowered; neither is a document with any entry in errors. Decision 162 makes compiling report every error as data rather than throw the first one (decision 161 makes the same rule for diagnostics whose generated position has no mapping: never dropped). For a document with errors, compileSource therefore throws TranslateErrors, whose .errors: TranslateError[] holds every entry of errors, in the order above (template error last), and whose .errors[0] is the first error, in today’s frame format (today a document with several expression errors throws one aggregate, [C]chunk-src.js:5975-5984, :6474), so the 14 host-dispatch goldens (tooling/tsc/src/fixtures/host-dispatch/__golden__/, each recording "name": "CompileError" and Marko’s code frame) keep their first message. The three post-processors that rewrite Marko’s errors today (compile.ts, the catch around compileSync: annotateCloseTagOpener from close-tag-opener.ts, hintParseError from parse-error-hints.ts, and sugarAfterDefaultError/stockParserError/stockAtomError from stock-parser.ts) key on MxParseError.code instead of matching message text. Status on main: neither decision is implemented yet (TranslateErrors does not exist; compileSource rethrows one error); the code is landing under decisions 161 and 162, and this paragraph follows the decision text.

Examples: <div x=(1 +)/> gives a complete tree, one error origin: "expression", span [11, 11), context [7, 12), and the attribute’s value container has node: null. <div></span> gives errors [{ code: "MISMATCHED_CLOSING_TAG", span: [5, 12) }] (reviewer’s probe: onError [5,12)/21), complete: false, and one MxTag div [0, 5) with incomplete: true.

When the error replaces an expression, the container’s node is null and its error is the same object as the entry in errors (§4).

3.14 MxReturn

Purpose: <return=x/> / <return value=x/> (decision 155, spec §10).

Fields: exactly those of MxTag (§3.2), with type: "MxReturn"; no nested tag and no value field. Lowering reads the returned value as it reads any tag’s default value (the name: null attribute or value=, §3.5), and keeps its shape errors (lowerReturn).

Spans: as MxTag. Example: <return=x/> is [0, 11); its default value’s value.span is [8, 9). Invariant: the front end produces MxReturn for every tag whose static name is return; shape validation (no body, no spread, one value, top level only, one per template) stays in lowering, as today.

3.15 Things that are not nodes

• Wildcard children (decision 147) have no syntax, so they are not an AST node (ruling C1 of decision 163, which amends decision 158 §1’s list). A child tag keeps its authored name (MxTagName.static), and matching it against children["*"] patterns is contract validation in lowering. The IR records the match as merged in #347/#354: TagAlias { authored, span?, groups } (ir.ts TagAlias) on Component.alias and DelegatedTag.alias, where authored and span come from MxTagName.static’s value and span and groups from the pattern match. The AST’s contribution is the invariant that a name is never rewritten and always has a span.
• defaultTag (decision 145): MxTagName.unnamed; the ladder is lowering’s.
• Structural tags (if, else, for, const, define, try, …) are MxTags: their meaning is resolution, and a file-local binding can shadow a name (spec §7). Only <return> gets its own node, because decision 158 names it.

4. Expressions

4.1 The contract

Every field that holds embedded TypeScript is an expression container:

interface MxExpressionContainer<N> extends Span {
  source: string;            // the authored text, source.slice(start, end)
  outer: Span;               // the span with the position's delimiters (§3.4); equal to the span when none
  node: N | null;            // the Babel payload; null when the parse failed
  error: MxParseError | null;
  atoms: MxAtom[];           // §4.3, empty when none
}
type MxExpression    = MxExpressionContainer<Expression>   & { type: "MxExpression" };
type MxStatements    = MxExpressionContainer<Statement[]>  & { type: "MxStatements" };
type MxPattern       = MxExpressionContainer<LVal>         & { type: "MxPattern" };
type MxArguments     = MxExpressionContainer<(Expression | SpreadElement)[]> & { type: "MxArguments" };
type MxParameterList = MxExpressionContainer<FunctionParameter[]> & { type: "MxParameterList" };
type MxTypeArguments = MxExpressionContainer<TSTypeParameterInstantiation> & { type: "MxTypeArguments" };
type MxTypeParameters = MxExpressionContainer<TSTypeParameterDeclaration> & { type: "MxTypeParameters" };

• Span is on the original file (§5), exactly the characters the author wrote for this position, delimiters excluded.
• node’s own positions are file-relative: the sub-parse is given the container’s start, line and column, as Marko already does with startIndex/startLine/startColumn ([C]chunk-src.js:988-1003). A wrapper prefix ((…)=>{}, _(…)) is compensated the same way Marko’s sourceOffset does (956-983). The payload’s own range is not the container’s: the container span is htmljs’s value range, which includes inner whitespace (${ y } is [2, 5) in ${ y }), while the node covers the expression alone ([3, 4)). Lowering takes Expr.span, paramSpans and every For param span from the payload node, never from the container (P1). Today’s exprSpan (lower.ts) reads the Babel node’s loc (through offsetOf, which prefers loc.start.index) and returns undefined for a node without loc; the payload’s start/end are the same offsets, so the port may read either.
• source is kept because lowering prints the authored slice, not the generated AST, so TypeScript type arguments survive (core/src/core.ts expr, expr(); IR spec §4, code row).
• node is Babel-shaped and carries loc. The IR spec requires a lowering to supply Expr.node “positioned, for every authored expression”, with loc.start/loc.end as { line, column, index? } (IR spec §4, node row), because three emitter-side consumers still read it: the TypeScript plugin maps through node.loc (packages/tooling/typescript-plugin/src/mx-language.ts locateSourceCode), Angular’s tag module walks node and regenerates code from it (packages/hosts/angular/src/tag-module.ts rewriteInputReads), and Preact reads a by= key’s node.value (packages/hosts/preact/src/emitter.ts PreactEmitter). For.paramNodes must also be positioned parser nodes (IR spec §5.9, E11; Angular reads them, packages/hosts/angular/src/emitter.ts AngularEmitter). So until mx-lead moves those consumers to Expr.span/Expr.code, the Babel payload of every container keeps Babel’s start, end and loc with index, all file-relative. This is the one place the AST stores loc (§5.1): inside Babel payloads, never on Mx* nodes.

4.1a Sharing and copying

The IR spec makes the IR read-only to emitters (IR spec §10.2, E21): one lowered Ir may be emitted more than once, and a lowering may share an object (an Expr, a loc) between two places. An emitter that rewrites Expr.code, For.bindings or a parser node first takes a private copy with cloneIr (packages/core/src/clone-ir.ts): Solid copies each For it rewrites (packages/hosts/solid/src/emitter.ts SolidEmitter), and Angular’s tag module copies the whole Ir, parser nodes included (cloneIr(lowered, { nodes: true }), packages/hosts/angular/src/tag-module.ts compileTagModule), before rewriting input.x reads in place (rewriteInputReads). ir-readonly.test.ts in every host freezes the IR, parser nodes included, so a write throws. For the AST this means:

• Containers never share. Two containers never hold the same Babel node or the same position object; two textually identical expressions get two containers and two Babel trees. Inside one payload Babel itself may share a position object between a parent and a child at a coincident boundary (ir.ts, Expr.span comment).
• The AST is read-only. Neither lowering nor anything after it mutates an Mx* node or a container’s Babel payload. One AST is lowered more than once (the custom-tag analyze pre-walk lowers the whole body on a scratch Ctx before the real walk, IR spec §1, step 3; a tool may lower the same parse for several hosts), and that is safe only because of this rule.
• No copy is required at the AST/IR seam. Since E21 forbids emitters to mutate and allows a lowering to share, Expr.node and For.paramNodes (ir.ts, Expr.node, For.paramNodes, ForHead) may be the container’s payload itself; an emitter that edits one copies it first with cloneIr. The host test suites freeze the IR, parser nodes included (ir-readonly.test.ts), so the port’s lowering must not mutate a payload either: anything it changes (the shorthand merge of §6.1a included) it builds as a new node.

What each consumer reads, and why it is unaffected:

4.2 Compared with the IR’s Expr

Expr is { code, shape, node, span?, file?, atoms? } (packages/core/src/ir.ts; normative contract in the IR spec §4, apps/docs/docs/architecture/ir-spec.md).

4.3 MxAtom

Decision 156: :name in an expression position is an atom. The container lists each atom found in its source:

interface MxAtom extends Span { type: "MxAtom"; name: string }  // span covers ':' and the name

The Babel payload holds the atom as a StringLiteral whose value is the name and whose extra.mxAtom is { span }, the atom’s own span, : included (MxAtomMark, ir.ts; decision 156 addendum 1, item 1, which makes that node shape public API of @mxlang/core and @mxlang/data). Every Babel-based consumer sees a string. Today the template parser lexes the atom, reports it through onAtom and hands Babel a numeric stand-in of the same length (0.), and core’s convertAtoms (core/src/atoms.ts) turns the stand-in into that StringLiteral; the front end builds the StringLiteral directly. ::name is a template-parser error (INVALID_EXPRESSION, reserved, decision 156 §5; packages/parser/src/template/PROVENANCE.md, “Atoms”).

What the IR makes of atoms is what shipped (#342, #346, #348, #357):

• Expr.atoms?: Atom[], one per MxAtom of the container, and Expr.code holds each as its string literal (core splices JSON.stringify(name) at each atom’s span; IR spec §4, atoms row).
• A whole value that is one atom (mode=:strict) is a static Attr with atom?: Atom, value the name and valueSpan the atom’s span; so is the name the :name sugar sets (decision 156 addendum 1, item 2; ir.ts, Attr; IR spec §6, static row).
• In parseData, such a value is DataAttr { kind: "atom", name, value, nameSpan?, span } (targets/data/src/tree.ts DataAttr), the sugar-derived name included; nested atoms stay StringLiteral + extra.mxAtom.

MxExpressionContainer.atoms stays: lowering needs the spans to splice the literal into Expr.code and to fill Expr.atoms.

Where the atom lexer runs, per container field (ruling C11 of decision 163, amended to describe main; PROVENANCE.md, “Atoms”, and the expr.atoms = true sites in packages/parser/src/template/states/):

Inside a lexed field, a : is an atom only where an expression is expected, never as TypeScript’s ternary, type or optional marker (decision 156 addenda 2 and 3; PROVENANCE.md, “Behaviour”).

<input accept=[:title, :rename-all]/>

Offsets: atom title [15, 21), atom rename-all [23, 34) (the : included).

5. Positions

5.1 The rule

Every MX node has start and end: 0-based offsets into the original file, in UTF-16 code units, half-open [start, end) — the unit of a JavaScript string index, which htmljs-parser already reports (Range.start/end, packages/parser/src/template/util/constants.ts Range) and which the IR’s SourceSpan uses (packages/core/src/mapping.ts SourceSpan, documented as UTF-16 in packages/core/src/fragment.ts FragmentBase). This is the IR spec’s SourceSpan rule exactly: half-open, UTF-16, file-absolute, CRLF’s \r belonging to its line, source.slice yielding the authored text (IR spec §3.2). No Mx* node stores loc; the Babel payloads inside containers do, for the reason in §4.1.

What lowering derives: every IR node’s loc is the start of the construct as a 1-based line and 0-based column (IR spec §3.1), which is lineColumnAt(node.start); the statement kinds’ end: Position is the untrimmed statement end of §3.10 (not lineColumnAt(node.end)); each IR span is the AST span of the node or sub-part the IR spec’s §3.3 table names (for example Attr.nameSpan ← MxAttribute.nameSpan, zero-width at the = for the default value, which is invariant E7; Interpolation.span ← MxPlaceholder span, delimiters included; Element.nameSpan ← MxTagName.span, and for an attribute tag the name after the @, IR spec §3.3, so lowering trims one unit off MxAttributeTag.name.span).

5.2 Line and column

Obtained on demand from the document: MxDocument keeps (or lazily builds) a line-start index, one entry per \n, as htmljs’s getLines does (packages/parser/src/template/util/util.ts). lineColumnAt(offset) returns a 1-based line and 0-based column (Babel’s convention, and what TranslateError and the spec’s structured fields carry, apps/docs/docs/specification.md (“The contract”) and “One base for every printed position (ruling #227)”). htmljs’s own positions are LSP-style, 0-based line and character (packages/parser/src/template/util/constants.ts Position); Marko adds 1 to the line (toBabelPosition, [C]chunk-src.js:6300-6303), and MX does the same. A \r is an ordinary column character (only \n starts a line), as in htmljs.

5.3 Fragments

A fragment parse takes base = { offset, line, column } with the meanings of today’s FragmentBase (baseOffset, zero-based baseLine, zero-based baseColumn; fragment.ts FragmentBase) and its invariants (baseOffset === baseColumn on line 0; baseOffset >= baseLine + baseColumn otherwise).

• Every offset is base.offset + local offset, at creation; there is no post-hoc walk (today’s shiftNode, fragment.ts, and its shared-position dedupe both disappear).
• lineColumnAt adds base.line to the line and, on the fragment’s first line only, base.column to the column.
• A Babel sub-parse receives startIndex = base.offset + local start, startLine = 1 + base.line + local line, startColumn = local column plus base.column when on the first line. This is what parseFragmentNative already demonstrates through Marko’s offset options (fragment.ts).

The IR spec states the required result, not the mechanism: “every loc and every span in the IR is measured against the enclosing file”, and a new lowering over its own parser “has no reason to reproduce the shift mechanics” (IR spec §3.4). Offsets at creation satisfy that. Parse errors are data (§3.13), so the separately-shifted thrown error of today disappears too.

6. Mapping to the IR

IR kinds today: packages/core/src/ir.ts IrNode defines 16 IrNode kinds (Text, Interpolation, Element, Component, IfChain, For, Define, Const, Static, Import, Export, InputInterface, Hoisted, DelegatedTag, DocumentType, Comment), plus Attr, AttributeTag, Block and the Ir root (each its own type in ir.ts). The IR spec lists the same 16 kinds (IR spec §5.2) and is the reference for every field below.

Where the AST enters the IR spec’s pipeline. The IR spec’s step 1 (tree rewrites before any tag name is read) turns sugar into name/id/class attributes and resolves the unnamed tag, and says “a new parser may produce that tree directly; it must not hand an unnamed tag to the walk” (IR spec §1). The MX AST deliberately does not produce that tree: it keeps MxShorthand and MxTagName.unnamed, because the default-tag ladder needs the host’s resolveDefaultTag and the ancestor chain, which a parser does not have. Step 1 therefore stays in lowering and reads the AST: the MxShorthands become Attrs by the merge of §6.1a, and each unnamed name is resolved before step 5. Steps 2 to 6 are unchanged.

What the port must reproduce. The port’s contract is byte-identity with MX’s own output before the port (goldens, oracles), not Marko parity (decision 157); a deliberate change of output is allowed only as its own recorded change, never inside the port (decision 163).

6.1 IR kind ← AST

6.1a The shorthand merge, a lowering step

Today Marko’s front end merges tag-adjacent shorthands (onOpenTagEnd, [C]chunk-src.js:6143-6171), and core/src/name-sugar.ts merges the attribute-position ones on top (rewriteAttributes, mergeClassTokens); the Attr fields then come from lowerAttr/lowerAttrNamed/attrNameSpan (lower.ts). With the MX AST the whole merge is lowering’s. It reproduces main as it is after #338 (666d0f56e, real nameSpan for a tag’s own shorthand) and 474258b65 (a dynamic shorthand’s nameSpan covers its sigil), field by field.

Order and grouping:

1. All . shorthands of a tag become one class Attr; tag-adjacent # becomes one id Attr. Tag-adjacent class comes before id (Marko pushes class first, [C]chunk-src.js:6148-6170).
2. Attribute-position .x tokens are merged into that class (or start one at the first token’s position if there is none); attribute-position #x is its own id Attr at its position. Marko’s shorthand class, when present, is moved before the first attribute-position id, and a tag-adjacent id beside an attribute-position # is moved first (rewriteAttributes, end). Duplicates then resolve last-wins with decision 135’s warning (<div#a #b/> keeps id "b").
3. A tag-adjacent #x beside an authored id= is an error (“Cannot have shorthand id and id attribute.”, [C]chunk-src.js:6168).
4. :name becomes a name Attr at its own position, static, with atom set (§4.3).
5. A sugar’s default becomes a separate default value (value) Attr right after the sugar’s own, with sugarValueOf the token plus =… or (…), its nameSpan zero-width at the value, and loc at the value. A second default value on the tag, when at least one comes from a sugar, is the error MX_DUPLICATE_DEFAULT at the second (“#x=… would set the default attribute (value), but the tag already has a default value (at …)”, ALREADY_HAS_DEFAULT); two authored value= stay decision 135’s warning; a host that claims # exempts attribute-position #x (P8).

The class value, by case (probed on main from source, lower() with a plain element host; offsets in each input alone):

Rules behind the table (mergeClassTokens, attrNameSpan, lowerAttrNamed). Today these are in-place edits of Marko’s nodes; the port builds each resulting value as a new node and never edits a payload (§4.1a). Value:

• Tag-adjacent only (Marko’s merge, [C]chunk-src.js:6148-6171): one part is that part; several all-static parts are one string joined by spaces; otherwise an array of the parts in written order. Beside an authored class: both strings gives the template `${shorthand} ${class}`; anything else an array, shorthand parts first.
• Attribute-position . tokens (all static) are joined by spaces into one string and merged by cases (mergeClassTokens): no class yet, a new static attribute; a shorthand-only class (no authored attribute), the string grows when it is one string, else the token is appended to the array (a single expression becomes [expr, token]); a class that holds shorthand parts beside an authored value, the token joins the last shorthand part (a single string part grows, else the token is inserted after it), so it lands before the authored value; an authored string literal with no shorthand, the token joins the literal on the side it was written; an authored false, 0, null or undefined is replaced by the token; an authored other number or true is joined with the token into one string; any other authored value becomes an array in written order.

nameSpan: from the first to the last attribute-position token when such tokens took part; else (no own position) the value’s span plus the sigil before it, ${/} included for a single dynamic part; else the authored class name. When none of these exists, which happens exactly when the value Marko merged has no loc and nothing else gave the attribute a position, the span is NaN (the bug row above): attrNameSpan then falls through to offsetOf on an empty position.

loc: the first attribute-position token when such tokens took part; else the authored attribute; else the tag.

sugar (the label), set only when an attribute-position token took part: the tag-adjacent words, then the attribute-position tokens, each with its .. The tag-adjacent words are included only when they are one static string (mergeClassTokens, mark): for a shorthand-only class, when the merged value is a string literal (<div.a.b .c/> gives .a .b .c; <div.a.${x} .b/> gives .b); beside an authored value, the words of the first shorthand part when it is a string literal (<div.a.${x} class="y" .d/> gives .a .d; <div.${x} class="y" .d/> gives .d). Dynamic parts never appear in it.

6.2 AST node → IR consumers

6.3 Gaps

The IR needs, and the AST as drafted does not carry:

• Resolution facts: which tag is native, a component, a define, a custom tag; the binding registry; Element.void, which is lowering’s (VOID_TAGS, core.ts), not a parse fact. These are lowering’s by design.
• Expr.code after rewrites and ExprShape: derived in lowering from source + node.

The AST carries, and no IR kind reads:

• MxComment.kind line vs block (IR has only html: boolean), and open-tag comments.
• typeArgs, typeParams (rejected today, core.ts rejectUnsupportedFields).
• MxTag.openTag/closeTag spans, concise, selfClosed (tools only).
• MxCDATA, MxDeclaration, MxScriptlet (errors only).
• MxText.span beyond valueSpan (newline-led whitespace; formatters only).

6.4 Who sees the AST and who sees the IR

The view the hooks receive after the port (ruling Q19, decision 163, widened by addendum 1). The hooks are re-typed in the port change, but not to Mx* nodes: that would make the whole AST public API of @mxlang/core through third-party hosts (decision 148), and every later AST edit a host-breaking change. Lowering builds a narrow view, as plain data, and hands that over:

interface HostTagView {
  name: string;                 // the tag name; for a module statement, its keyword
  nameSpan: Span;
  span: Span;                   // the whole tag, or the statement span of §3.10
  attributes: (                // what lowering produced, in source order
    | { kind: "attribute";
        name: string;           // before the last `:` (Marko's split, as hooks read it today);
                                // "value" for a default value
        modifier: string | null; // after the last `:`; null without one
        nameSpan: Span;         // zero-width at the `=` for a default value (Q8)
        value?: Expr }
    | { kind: "spread"; span: Span; value: Expr }
  )[];
  var: { span: Span } | null;                   // the tag variable's pattern range, when written
  attributeTags: { name: string; span: Span }[]; // `@`-names as written, in source order
  params: { span: Span; count: number } | null; // the body parameters, when pipes were written
  dynamicName: Expr | null;                     // the `<${…}>` name expression
  handle: MxNodeHandle;                         // opaque, below
}

Every field, and the hook that reads it today (opened on main):

What attributes holds (decision 163 addendum 4, item 2): what lowering produced, as hooks see the post-rewrite node today. A default value is an entry named "value" with a zero-width nameSpan (the Q8 adapter); a spread is its own entry kind, in source order, so attributes[0] means the first authored entry; attributes made from shorthands (class, id, name, a sugar’s default value) appear as the merge of §6.1a produced them. The one hook that reads node.attributes on main, html’s <let>/<const> in translate.ts resolveDelegatedTag, reads attrByName(node, "value") ?? node.attributes[0], then its .value (core.ts attrByName skips spreads):

Probed through lower() with a host that claims let and makes html’s read (attrByName(node, "value") ?? node.attributes[0]): <let/x ...y/> picks the spread, initial value y; <let.a/x/> picks class, "a"; <let/x=1/> and <let/x value=2/> pick value; <let/x/> picks nothing.

resolveModifier has no implementation in any host on main; resolveAttributeMethod is () => true wherever it is set (Preact, Solid, Angular, data) and reads nothing. resolveDefaultTag receives the parents as views: every host passes them to core’s contractDefaultTag, which reads name, attributeTag, the tag definition and, through the handle, the wildcard match (wildcard-resolve.ts wildcardMatchOf). The tag definition today is Marko’s tagDef (DefaultTagParent.tagDef), and isStructural (contract-default-tag.ts) reads only its html flag: a name the lookup knows that is not an element is structure. With Marko dropped it comes from the target’s element-shape table (§3.12), which records, per known name, whether it is an element.

The handle. MxNodeHandle is opaque: it has no fields, is not serialisable, and is valid only during the hook call. Only core’s exported helpers can resolve it to the AST node, so a third-party host cannot read through it. Hosts keep their call sites: no check moves, so error order and text are untouched by the port. The reads served through the handle today:

bindingSpan(target, name): Span | null. target is a view’s handle (the tag variable inside it) or a binding pattern payload (a plain Babel pattern, as checkBinding receives). It returns the span of the binding identifier named name inside that pattern, the first in source order, or null when the pattern binds no such name. It finds exactly the identifiers html’s bindingNames (translate.ts) finds today: the pattern itself when it is an identifier; in an object pattern, each property’s value (shorthand { input }, renamed { a: input }) or rest argument ({ ...input }); in an array pattern, each element, holes skipped; through a default, its left side ({ input = 1 }, [input = 1]); and a rest element’s argument. html keeps its check, its message and its position: rejectInputShadowing uses bindingSpan(…, "input") !== null as the presence test, called with whichever it holds (the handle from resolveDelegatedTag, the pattern from checkBinding), and fails at the start of the pattern, as today (core fail reports target.loc.start, the pattern node’s start). That start equals view.var.span.start: the view’s var span is the pattern payload’s range, which starts at the first character after / (probe: <let/x=1/>, <let/{ a: input }=1/> and <let/[b, input]: T=1/> all start at offset 5, before any type annotation). html’s checkBinding keeps calling the same function on the Babel pattern it already receives, which passes that pattern to bindingSpan and fails at its start, as today. (Addendum 4 item 1, applied as option (a) by the lead under decision 163’s frame.)

server and client are MxModuleStatements in the AST where the target’s statement set includes them (§3.10), and route through the same machinery as tags (ruling Q5/P5): first the host’s declarations.tags disposition (inert/error, with rejectInertShape, lower.ts lowerAuthoredTag, which is how html’s client disposition, targets/html/src/translate.ts TAGS, applies), then isDelegatedTag / resolveDelegatedTag (lower.ts lowerAuthoredTag) with the statement’s view, so html’s server stays a DelegatedTag { kind: "statement" } whose code html slices from the view’s span (today from node.loc, translate.ts resolveDelegatedTag). The view’s fields are the decision text; its TypeScript names are the port’s.

The HostDeclarations hooks (packages/core/src/declarations.ts HostDeclarations) and what each receives:

Every host fail/rawFail(msg, node) reads the node’s position; after the port it takes a view (or an attribute entry) and reports lineColumnAt(span.start) (or nameSpan.start).

After the port, possibly. Moving the checks the handle serves into lowering (hosts pass flags, not nodes) would remove the handle; reporting html’s input collision at the identifier (bindingSpan’s span) instead of the pattern start would be a better position. Neither is part of the port: each changes output (which error fires first, or where), so each is its own change with its own goldens, if it is made.

7. Mapping from parser events

htmljs-parser 5.18.0 defines 27 handlers ([H]util/constants.d.ts:64-90); the in-repo template parser adds a 28th, onAtom (decision 156; source packages/parser/src/template/util/constants.ts ParserOptions).

7.1 Inputs from outside the source text

Every option or signal Marko’s front end reads that does not come from the source, and where it comes from for the MX front end. A node field may only depend on an input marked “front end” in the last column.

So the front end takes two external inputs, both supplied per target: the statement keyword set (§3.10) and tagShape(name) → bodyMode, supplied by core from the active target (its element shapes, the core tags, the custom tags’ text/preserveWhitespace, and a target’s overrides such as the data target’s). Every other decision Marko made from a tag definition moves to lowering or disappears. The element-shape table is the target descriptor’s, with a core default (§3.12, ruling Q21).

Events the MX patch adds or changes. One added: onAtom (atoms, decision 156; packages/parser/src/template/PROVENANCE.md, “Atoms”). The patch (patches/htmljs-parser@5.18.0.patch, hunks at dist/index.js 311, 1147, 1382, 1432, mirrored in index.mjs; the same rules live as source in packages/parser/src/template/states/ATTRIBUTE.ts ATTRIBUTE and packages/parser/src/template/states/EXPRESSION.ts EXPRESSION, lookAheadForOperator, isIdentStartCode) changes where onAttrValue ends: it marks named-attribute and spread values (expr.attrValue), skips ?? and ?. when counting ternary depth, and inside such a value lets a : followed by an identifier (or a bare : at a tag end) and a . followed by an identifier, after whitespace, terminate the value so onAttrName fires for the next sugar (decision 146 §3). Atom lexing lives in EXPRESSION too (lexAtom), turned on per expression by the states listed in §4.3, and reported through onAtom; while it is on, read() returns the atom’s numeric stand-in, so a front end that slices source for an expression’s text must not use read() for it.

8. Design choices and alternatives

Names in italics (MxIf, MxFor, MxConst, MxImport, MxExport, MxStatic, MxInputInterface) are rejected alternatives, not node types; the node types are listed in the appendix.

D1. One MxAttribute node with a nullable name, plus a separate MxShorthand. Alternative: one MxAttribute with kind: "named" | "default" | "sugar". Chosen because sugar has a sigil, a position and an optional default that named attributes never have, and a default value is a named attribute without a name, not a third shape.

D2. Flat children list; attribute tags stay where they were written. Alternative: typed slots (body, attributeTags) filled by the front end, as Marko does. Chosen because lowering already rebuilds the structure from source order (three views, lower.ts mergeBySourceOffset), moving changes spans’ parentage, and Marko’s move depends on controlFlow taglib flags the AST should not know.

D3. Structural tags are MxTag, only <return> is its own node. Alternative: MxIf, MxFor, MxConst nodes. Chosen because a structural name can be shadowed by a file-local binding (spec §7, decision 113), so the front end cannot know; <return> cannot be shadowed (reserved word) and decision 158 names it.

D4. Attribute names keep their colons. Alternative: keep Marko’s modifier split. Chosen because MX’s lowering re-joins the split for every name except the class:/style:/on: prefixes (lower.ts isOrdinaryColonName, lowerAttrNamed), so the split encodes Marko’s semantics, not MX’s.

D5. Spans only, no stored loc. Alternative: Babel-style loc on every node. Chosen because offsets are what the IR, Volar and LSP consume, line and column are cheap from one index, and shared position objects were a measured bug source (packages/core/AGENTS.md, parseFragment bullet).

D6. MxText carries both normalized value and raw. Alternative: raw only, normalize in lowering. Chosen because normalization needs neighbour lookahead that the front end already has while building the list; raw and the node span keep the whole authored run, and valueSpan the range Marko’s trim leaves, which the IR’s Text.span needs (§3.8). In a preserving body value equals raw (§3.8).

D7. One MxModuleStatement with a keyword. Alternative: MxImport, MxExport, MxStatic. Chosen because the payload is a Babel statement list in every case and the per-keyword meaning is lowering’s; client and class must still parse to give a positioned error.

D8. Errors in one list, referenced from the failed container. Alternative: errors only inline (Marko) or only in a list. Chosen so a consumer can report all errors without walking (one list, ordered by position, template error last), and lowering can still find “this expression failed” locally.

D9. Parse shape by callback (tagShape(name) → "html" | "parsed-text" | "parsed-text-preserve" | "preserve" | "void"). Alternative: a fixed built-in list. Chosen because custom tags’ parseOptions and a target’s own overrides change the parse (spec §9.3, custom-tags.ts customTagTaglib, targets/data/src/taglib.ts neutralizations).

D10. Expressions keep a Babel payload. Alternative: store only source and spans and let lowering parse on demand. Chosen because the IR spec requires a positioned Expr.node and For.paramNodes today (IR spec §4, E11), and parsing once in the front end gives every expression error a place in errors at parse time.

D11. The AST is read-only and hands its payloads to the IR. Alternative: lowering copies every parser node it puts in the IR. Chosen because the IR spec’s E21 makes emitters copy before they mutate (cloneIr) and allows a lowering to share, so a copy at the seam protects nothing (§4.1a).

D12. MxAttributeTag is its own node. Alternative: an MxTag with an attributeTag: true flag. Chosen because its name is a property key with different rules (never split, never resolved, never unnamed), and a distinct type lets a walker skip or collect attribute tags without inspecting names.

D13. Open-tag comments live in MxTag.attributes. Alternative: a separate comments list on the tag. Chosen because the attribute list is the only place that preserves their position relative to the attributes.

D14. MxDocument.source/base and MxTag.concise/selfClosed are stored. Alternative: recompute them from the original text. Chosen because a fragment parse’s consumers (region bridges, tools) receive the document without the enclosing file, and formatters need the authored form.

D15. A failed template parse returns a partial tree. Alternative: return no tree, as Marko does by throwing. Chosen because the parser’s events up to the error are exact and tools can read them; the limits are stated in §3.13. Lowering never reads a partial tree (complete === false implies not lowered).

9. Open questions for mx-lead

Decision 163 ruled on Q1 to Q23 (scratch/reports/mx2/ast-catalogue-rulings.md in the project space). Numbers are stable across revisions. Closed by the rulings, with where the text now lives:

Deferred, still open (each after the port, as its own change):

• Q17. Drop loc from Expr.node and For.paramNodes payloads (keep only start/end). Deferred: a later, separate IR-contract change, after the TypeScript plugin maps through Expr.span instead of node.loc (mx-language.ts locateSourceCode); until then the payloads keep loc (§4.1).
• Checks served through the hook handle, moved into lowering, and html’s input collision reported at the identifier (§6.4, “After the port, possibly”). Not part of the port: each changes output, so each would be its own change with its own goldens.
• Generator output to source slices (TODO ir-generated-text-to-source-slices). Deferred: wanted, but as a separate recorded change after the port, because it changes emitted text (probe c, { a,b } printed as { a, b }); the port keeps the pinned generator (§7.1).
• MxShorthandValue.dynamic without quasis/expressions (§3.6). Deferred: the port keeps both beside template; dropping the duplicate is the same later clean-up as ruling C4 made for the dynamic tag name (§3.3), where one container holds the whole name and there is no separate list of quasis or inner expressions.

Appendix A. Node types and where each is defined

Every Mx type in this document, with the section and line of its definition. Each is used elsewhere in the catalogue; no type is used without a definition. The italic names in §8 and §9 are rejected alternatives and are not listed.