IR specification

This page is the normative description of the IR that @mxlang/core produces and every emitter consumes. It is the written interface between the two halves of the compiler: a lowering (today packages/core/src/lower.ts, over Marko’s parser) produces an Ir; an emitter (a host or target) consumes it and never sees a parser node. Someone writing a new lowering should be able to build one from this page alone, without reading an emitter.

The IR is the prose introduction. This page is the contract. Where they disagree, this page wins, and the disagreement is a bug in the prose.

Everything here is derived from the code and the tests that pin it, at the commit this page was last changed in. Each invariant names the test that pins it; “no pinning test” says so where none exists (none does at present). The types live in packages/core/src/ir.ts; the walk in packages/core/src/emit.ts; spans in packages/core/src/mapping.ts.

The key words must, must not, may and should are used in the RFC 2119 sense. “Lowering” means whatever produces the Ir; “emitter” means anything that reads one (an Emitter<Out> driven by drive(), or a direct walker such as @mxlang/data’s tree builder).

1. The pipeline: what a parser produces and what lowering adds

The IR is not the parser’s output. It is the result of a parse plus a sequence of resolution steps, several of which consult the host. A new lowering must perform every step below, in this order, or produce the same result by other means.

compileSource (compile.ts) parses the whole file with @marko/compiler and, in the translator’s Program.exit, builds a Ctx and calls lower(ctx, body) once, then hands the result to the host’s required HostOptions.emitIr(ir, ctx). parseFragment (fragment.ts) is the same parse for a substring of a larger file, with positions shifted (section 3.4). lower() (lower.ts) then runs:

1. Tree rewrites, before any tag name is read (resolveUnnamedTags, default-tag.ts). Top-down over the parsed tree, per tag:

   1. Name sugar (decision 146, name-sugar.ts rewriteNameSugar): <input:email>, #id, .class and attribute-position :x/#x/.x become the name/id/class attributes the author would otherwise have written. The rewritten attribute remembers its token as sugarLabel, which becomes Attr.sugar (section 6). A host declaring claimsAttributeHash keeps attribute-position #x for itself.
   2. Default tag (resolveDefaultTag host hook, decision 145): an unnamed tag (<#a>, <.b>, <:c>) is renamed to what the host answers, given its ancestors. With no hook it is a positioned error (“no default tag is declared…”).

   After this step the tree contains no sugar and no unnamed tag. A new parser may produce that tree directly; it must not hand an unnamed tag to the walk (step 5).

2. Reserved-name check (checkReservedTemplate) and the file’s own Input (readOwnInput, raiseInvalidOwnInput).

3. Custom-tag analyze pre-walk (runCustomTagAnalyze), only at the file root and only when a registered tag defines analyze: the whole body is lowered once on a scratch Ctx whose output is discarded, so every analyze receives the same TagCall its transform will.

4. Export name (Ir.exportName), computed before the walk because a self-recursive call resolves to it during the walk (invariant §7.5-7).

5. The walk (lowerChildren). Each child becomes zero or more IR nodes. Tag routing, in precedence order (lowerAuthoredTag):

   1. a dynamic tag name (<${expr}>) → DelegatedTag if the host claims DYNAMIC_TAG, else Component with a dynamic target;
   2. a host disposition (declarations.tags[name]): error fails, inert validates the shape and yields an empty Text;
   3. core structural tags: import/static/export (statement nodes), for, const, define, return, a stray else/else-if (error); if is grouped with its else siblings before this switch;
   4. built-in custom tags (try, never shadowable);
   5. a PascalCase name the file binds (an import, a <define>, a <const>, a tag param — fileLocalBinding) skips steps 6 and 7;
   6. a registered or discovered custom tag (lowerCustomTag): its contract is validated (attributes, attribute tags, children, parents; decisions 130, 138, 142) and its transform or template replaces the call with ordinary IR (zero or more nodes);
   7. a host claim (isDelegatedTag) → DelegatedTag, with the host’s resolveDelegatedTag answer in data;
   8. a component (fileLocalBinding or isComponent) → Component;
   9. an unbound PascalCase name, or a lowercase name isElement rejects → positioned error;
   10. otherwise an Element.

   During the walk, attributes are lowered, de-duplicated last-wins (decision 135) and offered to the host’s orderAttrs; attribute tags are planned against the callee’s Input (section 8); ctx.hoist calls collect Hoisted statements for the enclosing function.

6. Assembly (lowerTemplate), after the walk: module-level kinds are lifted out of the body into Ir.imports, Ir.hoisted, Ir.inputInterface and Ir.prelude; imports synthesized for discovered tags are appended to Ir.imports; needsAttrTagImport is computed; at the file root, every used tag’s finalize output is prepended to Ir.body in tag-name order; returnValue is read off the walk; tagMetadata is derived from the finished IR (metadataOfIr).

There are no passes after lower() returns. Everything an emitter reads is set by the time emitIr is called.

The IR is host-independent in shape, not in content. Several fields record a host’s answer at lower time: DelegatedTag.data (resolveDelegatedTag), an Attr’s kind and name (resolveModifier, the isElement gate for event), attribute order (orderAttrs), ComponentTarget.binding (resolveDiscoveredTagModule), whether a tag is an Element, a Component or a DelegatedTag at all, and whether a comment survives (keepComments). A lowering must take a HostDeclarations (declarations.ts) and ask it the same questions at the same points.

2. Conventions

2.1 Required and optional

A field typed without ? is always present; T | null is always present and may be null. A field typed ?: may be absent; this page says when. JSON.stringify drops absent fields, which is why the worked example (section 12) shows none.

2.2 Synthesized nodes

A node is synthesized when no authored source backs it: built by a custom tag’s transform/finalize through ctx.build (custom-tags.ts buildersFor), a discovered tag’s routed Component (template-tag.ts), an import minted for a discovered tag, or the empty Text that a <return> or an inert tag leaves behind. Synthesized nodes:

• carry a loc (the call site’s) like every node;
• carry no span, nameSpan (where optional), valueSpan or paramSpans;
• carry nameSpan: { sourceStart: 0, sourceEnd: 0 } on an Attr built by ctx.build.attr/dynamicAttr/booleanAttr, because Attr.nameSpan is required. A zero-width span at offset 0 cannot be an authored name (a tag always precedes an attribute), so a consumer may treat it as “no source”;
• carry an Expr whose node is null and whose shape is "other" (syntheticExpr), with no span.

An emitter must not assume that any optional span is present. @mxlang/data is the one consumer that requires spans; it refuses a missing one with “core IR invariant broken — … carries no span” (packages/targets/data/src/build.ts requiredSpan) rather than guessing.

3. Positions

3.1 Position (loc)

Every IR node carries loc: Position: { line, column, file? }, the shape TranslateError reports.

• line is 1-based; column is 0-based, counted in UTF-16 code units from the start of the line.
• file is absent for a position in the file under compilation, which is every position core produces today. When set, the position is measured in that file (a tag template’s own text, spec §2’s third position rule). A consumer that can only report against one file drops a foreign-file position rather than misplacing it.
• loc is the start of the construct: the < of a tag, the first character of an attribute name, the $ of an interpolation. Pinned by lower.test.ts › “positions” › “records a 1-based line and 0-based column on every node” and “records the position of a nested node, not its parent’s”.

The statement kinds Static, Import, Export, InputInterface and Hoisted also carry end: Position, the end of the authored statement, because their code is a plain string with no Expr to read a range from. For a synthesized import end equals loc. For a Hoisted node both come from the node the host passed to ctx.hoist(code, node).

3.2 SourceSpan

SourceSpan (mapping.ts) is { sourceStart, sourceEnd }: a half-open range [sourceStart, sourceEnd) of UTF-16 code-unit offsets into the file’s source string — the unit of a JS string index, so source.slice(sourceStart, sourceEnd) yields the authored text. Not bytes: an emoji before a span shifts it by two. CRLF line endings are ordinary characters (the \r belongs to its line). Pinned by spans.test.ts › “spans under UTF-16 and CRLF” › “an emoji counts two code units before every span after it” and “CRLF line endings slice correctly (the \r belongs to its line)”, and “non-ASCII source” › “every span is a UTF-16 code-unit offset into the source string”.

Every span is file-absolute: offsets into the whole file, not into a fragment (section 3.4). Pinned by lower.test.ts › “Expr.span” › “a span computed under a distinct ctx.source is absolute in that source”.

What each span covers is listed with its field. The rule throughout: slicing the source with a span yields exactly the authored text of that construct, which spans.test.ts asserts for every span kind.

3.3 Which nodes carry spans

InputInterface, Hoisted, DocumentType and a synthesized Import carry no span. Pinned by spans.test.ts (one describe per row group).

3.4 Fragments and baseOffset

When MX is a region inside another file (a .solid.mx region, found by packages/parser/src/mx/bridge.ts), parseFragment(source, { filename, baseOffset, baseLine, baseColumn }) parses the substring and shifts every position so the IR is file-absolute. The bridge passes baseOffset: inner.start. The numbers (fragment.ts, FragmentBase):

• all three count UTF-16 code units;
• baseOffset is the number of units before the fragment; baseLine is zero-based (the number of \n before it); baseColumn is zero-based (units between the last \n and the fragment);
• baseLine === 0 requires baseOffset === baseColumn; baseLine >= 1 requires baseOffset >= baseLine + baseColumn. assertBaseContract rejects anything else.

Line/column positions shift by baseLine (and by baseColumn on the fragment’s first line only); index positions shift by baseOffset. Shared position objects are shifted once (the walk dedupes them). A thrown parse error’s position is on the exception and is shifted separately. A host that also reads positions through a padded copy of the file must pad it as the “padding contract” in fragment.ts describes, or line/column and index positions disagree. Pinned by fragment.test.ts.

A new lowering over its own parser has no reason to reproduce the shift mechanics, but it must produce the same result: every loc and every span in the IR is measured against the enclosing file.

3.5 What diagnostics require

• A lowering error is a TranslateError with a 1-based line, 0-based column, and file when it is about another file (cross-file-error.test.ts). Each fail(…, node) reports the node’s loc.start. An error about several places also carries the optional spans: SourceSpan[] (file-absolute UTF-16 offsets, source order; line/column are the last span’s): a duplicate atom-contract declaration holds the first and the second (decision 156).
• An attribute diagnostic is positioned at the attribute name (Attr.loc, which for an authored, spelled attribute is the position of nameSpan.sourceStart; a shorthand #id/.class with no position of its own reports at its tag, a merged sugar class at its first sugar token). Hosts rely on this for event-attribute errors (pinned per host by position tests on solid/preact/html/astro).
• Warnings (MxWarning) carry the same structured position; the message text prints columns 1-based.
• The TypeScript plugin and language server map only through authored positions — spans, and for an expression today Expr.node.loc (section 4). A missing position means “no mapping”, never a guessed one (Spans and mappings).

4. Expr

interface Expr {
  code: string;
  shape: "object" | "array" | "string" | "other";
  node: Node;
  span?: SourceSpan;
  file?: string;
  atoms?: Atom[];
}

interface Atom {
  kind: "atom";
  name: string;
  span: SourceSpan; // the whole atom, `:` included
}

What an emitter may assume:

• code is a complete JavaScript/TypeScript expression and may be emitted verbatim inside parentheses.
• The only rewritings core performs on code are the binding-registry rewrite above, which is a host’s own request, and the atom splice (:a is "a", decision 156). Core does not rename, hygienize or reformat expressions. Name sugar (decision 146) rewrites the tree before lowering and never touches an expression’s text.
• Hosts may rewrite code further when emitting; the lowering does not. Section 10.3 lists who does.
• Consumers recognize an Expr structurally — an object with a string code and a shape (rewrite-codes.ts) or a node (mx-language.ts, Angular’s tag-module.ts). The statement kinds also carry code; they must never carry shape or node.

5. The root and the body kinds

5.1 Ir

5.2 The node kinds

IrNode is a discriminated union on kind. Every member has loc (section 3.1). The table says where each kind may appear.

A module-level kind in a body is a malformed IR: drive() throws (“unexpected module-level node kind”), pinned by emit.test.ts › “throws on a module-level kind reaching the body walk”.

5.3 Text

{ kind: "Text", value: string, span? }. value is the text after Marko’s whitespace normalization (decision 33: newline-bearing whitespace runs dropped, the rest collapsed); span covers the text as authored, so the two differ (spans.test.ts › “Text: span slices the authored text, which value has normalized”). Same-line spaces are content (decision 141). A lowering must apply the same normalization: emitters print value and never re-normalize. value may be "" (the placeholder an inert tag or <return> leaves); an emitter must emit nothing for it.

5.4 Interpolation

{ kind: "Interpolation", expr: Expr, escaped: boolean, span? }. escaped is true for ${…}, false for $!{…}.

5.5 Element

{ kind: "Element", name, nameSpan?, span?, attrs: Attr[], children: IrNode[], void: boolean }. A native HTML/SVG/MathML element, after the host’s isElement accepted it. void is true for the HTML void elements (VOID_TAGS), whose children is always []. Pinned by lower.test.ts › “Element marks a void tag and takes no children”. An Element never has attribute tags (the host’s rejectElementAttributeTags or the generic field guard refuses them). Only an Element lowers on* attributes to kind: "event" (section 6).

5.6 Component

A named custom tag’s argument form is exclusive (Marko’s assertAttributesOrSingleArg): arguments with attributes, attribute tags or a body is an error. A dynamic or define target follows Marko’s lenient rule: arguments with a body or attribute tags are allowed, arguments with a plain attribute are not (decision 109). Pinned by lower.test.ts › “allows a define call mixing tag-argument form with an attribute tag…”, “…with a body…”, “still rejects a define call mixing tag-argument form with a plain attribute”.

5.7 ComponentTarget

Pinned by lower.test.ts › “Component resolves an import binding as its target”, “Component records a define target with its declared params”, and the “decision 116” and “local-value-as-tag” tests.

5.8 IfChain and Branch

{ kind: "IfChain", branches: Branch[], span? }; Branch is { condition: Expr | null, children, span?, loc }. The chain is <if> plus every following <else if>/<else-if>/<else> sibling, already grouped; whitespace-only text and comments between branches are layout and are dropped. Only the last branch may have condition: null (an <else> ends the chain). Emitters must not re-scan siblings for <else>. Pinned by lower.test.ts › “IfChain groups every branch, with a null condition for else” and “leaves a second else after an unconditional else to the ordinary stray-else error”.

Each branch is its own binding scope: a <const> inside one does not leak (lower.test.ts › “restores a name shadowed inside an branch after the branch”).

5.9 For, ForSource, ForHead

For is ForHead plus { kind: "For", children, span? }. ForHead (also used by AttributeTagFor):

Range rules: to= gives inclusive: true, until= gives false; both together is an error. from is null when omitted — the host supplies the start (0), core does not invent a literal. step is null when omitted and only legal on a range. More than one of of=/in=/a range is an error, as is key= (Marko spells it by=) and a string by= on anything but of=. Pinned by lower.test.ts › “For normalizes of=, with params and their bindings”, “For normalizes the inclusive and exclusive ranges apart”, and the “ by=/key= (Marko parity)” block.

The params shadow host bindings inside children only; emitters must not re-shadow.

5.10 Define

{ kind: "Define", name, nameSpan?, span?, params: string[], paramSpans?, children }. name and params are source text. Any statement a host hoisted from inside the body is placed first in children as Hoisted nodes, so a define-scoped hoist lands at that function’s head. The define is registered after its body is lowered. Pinned by lower.test.ts › “Define carries its name, params and body”.

5.11 Const

{ kind: "Const", name, init: Expr, span? }. name is the binding pattern as source text, printed through declName (never rewritten). The binding shadows a host binding of the same name for the rest of its scope, which a <const> inside a branch confines to that branch.

5.12 Statement kinds

Pinned by lower.test.ts › “Import and Static are lifted out of the body to module scope” and “Export hoists verbatim and InputInterface is kept apart”.

5.13 DelegatedTag

{ kind: "DelegatedTag", tag: DelegatedTag<unknown> }, where DelegatedTag<Data> is:

This is decision 79’s narrow escape hatch: every host-owned construct (<try>, <html-comment>, a future <signal>) arrives here fully resolved. The parser node is deliberately not carried; a host records what it needs in data while the node is in hand, and an emitter must consume only the IR and data. A claimed tag’s children are lowered exactly once (lower.test.ts › “a claimed tag’s children are lowered exactly once”). A contract-only custom tag (decision 130) also becomes a DelegatedTag on a name the host claims; <try> is a built-in custom tag that asks for one through ctx.build.delegatedTag.

5.14 DocumentType and Comment

DocumentType is { value }, delimiters stripped. Comment is { value, html: boolean, span? }: value has the delimiters stripped, and html is true for <!-- -->, false for a // line comment (only the source can tell). A // comment (html: false) is author-only: no host writes it out. An HTML comment is written out by Astro and Angular as <!--value--> and dropped by html, Preact (React, Hono) and Solid, as stock Marko drops it (<html-comment> is how an author emits one there). Pinned by lower.test.ts › “Comment records whether the source spelled an HTML comment”; ir-contract.test.ts › “5.14: …” in html, preact, solid, astro and angular. (HostDeclarations.keepComments is declared and set by Astro, but no code reads it: the emitter’s own comment() decides.)

6. Attr

Every non-spread attribute has name, nameSpan (required), loc at the name, and an optional sugar (the decision-146 token, :email, when the attribute came from sugar).

Rules a lowering must apply, in this order (lowerAttrNamed):

1. Spread first. Then an invalid attribute name is an error unless the host sets acceptsForeignAttrNames.
2. A colon name keeps its complete spelling (x:foo) except, on a native element, the reserved class:/style:/on: prefixes, which go to the host’s resolveModifier (a returned name makes a dynamic attr) or are an error (rejectModifier, then core’s wording).
3. An attribute method (onClick() { … }) is allowed only when the host’s resolveAttributeMethod returns true; its value is an Expr over the function expression Marko builds for the method, whose body is synthetic (so its column mapping can drift, Spans and mappings). Preact and Solid reprint it in their own function form. Pinned by lower.test.ts › “lowers an attribute method on an element to an event with an arrow value”.
4. bound, then static (string literal), then boolean (literal true), then event, then dynamic. The event check comes last so <div onClick> stays boolean and <button onClick="alert(1)"> stays static. Pinned by lower.test.ts › “event attributes” (all tests) and “on* outside a native element stays a prop”.
5. Duplicates resolve last-wins by name (case-sensitive), with a warning for each dropped occurrence; spreads never count (decision 135). The IR never carries two attributes of the same name. Pinned by lower.test.ts › “duplicate attributes resolve last-wins (decision 135)”.
6. The host’s orderAttrs(name, attrs, on, ctx) may reorder the result.

Pinned overall by lower.test.ts › “Attr separates static, dynamic, bound and spread”.

7. Block

{ hasParams: boolean, params: string[], children, loc }: a child list a host emits as a callable unit — a component’s content, an attribute tag’s block. params are the block’s tag params as source text; hasParams distinguishes <Tag||> (true, params: []) from no pipes. Params shadow host bindings inside children only. A host with no render-prop form rejects non-empty params itself; core resolves the shape and does not decide whether the target can express it.

8. Attribute tags

A Component and a DelegatedTag (and, recursively, an AttributeTag) carry three synchronized views of their <@name> tags (decisions 106–108):

AttributeTag is { name, nameSpan, span?, attrs, block: Block, hasBody, attributeTags, attributeTagTree, attrTagProps }. name excludes the @. hasBody follows hasContent. content is reserved and rejected as an attribute name.

How attrTagProps is resolved:

• Against the callee’s declared Input, read synchronously and cross-file (callee-input.ts). A declared AttrTag is single (at most once, never inside <for>), AttrTag[] is array, a required one must appear on every <if> path; each violation is a positioned error. A declared shape is authoritative and defaults to as: "data".
• With no declaration (untyped, unresolved, dynamic callee), cardinality comes from the occurrences (array if more than one or inside a <for>), and as is renderable only if every occurrence of that name is body-only; one occurrence with attributes or nested tags makes it data.
• A required declared tag absent from the call is a positioned error (“missing required attribute tag”).
• @children collides with ordinary children when the call also has body content.

The v2 gate. A host that declares attrTags: 2 in its HostDeclarations must emit from attrTagProps and must not regroup attributeTags or resolve declarations itself. For a host that has not declared it, core positions an error on every construct whose shape could otherwise be dropped (attributes on attribute tags, nested attribute tags, a declared shape that differs from the flat view) — “… isn’t supported by <host> yet”. Pinned by lower.test.ts › “attribute-tag v2 IR and validation” and attribute-tag-contracts.test.ts.

Builder-made tags (ctx.build.delegatedTag, a routed template call without a precomputed plan) get a plan with as: "data" and occurrence-count cardinality (custom-tags.ts, template-tag.ts).

9. Custom tags, contracts and sugar: what reaches the IR

None of these is an IR kind. Each is resolved during lowering into ordinary nodes:

• Name sugar and default tag: tree rewrites before the walk (section 1, step 1). Visible in the IR only as Attr.sugar.
• Custom tags (programmatic, discovered sidecars and templates): validated against their contract, then replaced by whatever transform returns (IrNode[], possibly empty or several nodes), or routed to their template as a Component with a generated name target, authoredName, returnsValue and a synthesized Import. A finalize hook’s nodes are prepended to Ir.body.
• Contracts (mx.contracts, decision 142): validation only; a contract-only tag on a claimed name becomes a DelegatedTag (decision 130).
• <try>: a built-in custom tag that validates and emits a DelegatedTag named try.
• Not yet in the IR: decision 147 (wildcard children["*"], its alias capture) and decision 156 (atoms) have no IR representation in the code today. This page gains their nodes when they land.

10. The emitter contract

10.1 Emitter<Out> and drive

interface Emitter<Out> {
  text(node): void;
  interpolation(node): void;
  element(node): void;
  component(node): void;
  ifChain(node): void;
  forLoop(node): void;
  define(node): void;
  constant(node): void;
  hoisted(node): void;
  delegatedTag(node): void;
  documentType(node): void;
  comment(node): void;
  done(): Out;
}

drive(emitter, nodes) calls one method per node in order; emit(emitter, ir) drives ir.body and returns done(). Every method is required. A host that cannot express a kind throws from its method, naming the construct and its position; it must never silently skip one (the S8 class). drive throws on a module-level kind and on an unknown kind. Pinned by emit.test.ts › “dispatches each kind to its own emitter method”, “throws on an unknown IR kind rather than ignoring it”, “throws on a module-level kind reaching the body walk”.

A host renders nested child lists (a Block, a branch, a loop body) by calling drive recursively. Module-level fields (imports, hoisted, inputInterface, prelude, returnValue, exportName, needsAttrTagImport) are placed by the host from Ir, not by the walk. A host need not use drive: @mxlang/data walks the IR directly and throws on any kind its declarations make impossible.

10.2 Invariants emitters rely on

Each of these is assumed by at least one shipped emitter or tool without re-checking. A lowering that breaks one produces wrong output or a crash downstream, not a diagnostic.

10.3 Who rewrites expressions

Core: only the binding-registry rewrite a host requests (section 4). In emitters:

• @mxlang/solid rewrites every read of a <for> param Solid hands as an accessor into a call (p.name → p().name, decision 94; rewriteAccessorReads in accessor-reads.ts, applied in the emitter’s rewriteForBody, on a private copy of the For, E21). Pinned by solid/src/client-render.test.ts › “re-renders a same-key row replacement under <for by="id">, …”.
• @mxlang/angular’s tag module rewrites input.x to the class property x (tag-module.ts rewriteExpr, on a private copy of the IR, E21), and its by= lowering slices key.code by Babel offsets. Pinned by angular/test/for-by-scope.test.ts › “still lowers the forms Angular supports to track”.
• @mxlang/preact (and React, Hono) and @mxlang/solid reprint an attribute-method value as a function expression.
• @mxlang/html and @mxlang/astro print code unchanged.

10.4 What each emitter rejects

An emitter rejects a construct by throwing a positioned error from its method. The IR does not pre-filter by host (except through HostDeclarations), so a new lowering must still produce these nodes; the emitter decides. Known rejections:

A host whose output has a returning unit invoked as a plain function also refuses hook imports in it (preact/src/index.test.ts › “rejects a hook in a unit that declares ”).

11. Stability and adding a node

Public. @mxlang/core exports the IR types Attr, AttributeTag, AttributeTagNode, AttrTagProp, Block, Branch, ComponentTarget, DelegatedTag, Expr, ExprShape, ForHead, ForSource, Ir, IrNode, Position; SourceSpan, GeneratedMapping, MappedCode and the mapping helpers; Emitter, drive, emit; lower, lowerChildren, expressionShape. AttrSugar and IrBase are not exported by name (they reach consumers only inside Attr and each node). None of the IR types is marked @unstable; the only @unstable surface in core is the target contract (target-descriptor.ts, target-loader.ts, descriptorVersion: 0). The package is 0.1.0-alpha.1, so no semver guarantee applies yet.

Rules for changing the IR (decisions 79 and 80):

• The kind set is closed in MX 1: structural core plus “component call”. A new construct with compile-time meaning becomes an IR kind (or a field on one) only when every host must emit it differently; host-owned constructs travel as DelegatedTag with their decision in data.
• Adding a kind means adding it to IrNode, to Emitter (a required method) and to drive’s switch. Because drive’s default narrows to never, the compiler then fails every emitter until each one handles or rejects the kind; no emitter may ignore it. A direct walker (@mxlang/data) must handle it or throw.
• User-defined compile-time tags (decision 80, MX 2) must produce IR, not host output: input IR in, IR out, positions preserved, run in core before emitters. That is what transform already is for custom tags. No opaque “user node” every host must handle is admitted.
• A new optional field must document its absence (synthesized or not applicable); a new span field follows section 3.

12. Worked example

One template, the IR the core lowers it to under @mxlang/html’s declarations, and the module @mxlang/html emits from that IR. All three are real files in apps/docs/example/ir-spec/, quoted here verbatim; apps/docs/scripts/ir-example.test.ts regenerates both outputs on every docs test run and fails when either drifts or a block below stops matching its file. Regenerate with bun scripts/ir-example.ts --write from apps/docs.

The template, greeting.mx:

export interface Input {
  name: string;
  items: string[];
}

<const/count=input.items.length/>
<h1 class="title">Hello, ${input.name}!</h1>
<if=count>
  <ul>
    <for|item| of=input.items>
      <li>${item}</li>
    </for>
  </ul>
</if>
<else>
  <p hidden>Nothing yet.</p>
</else>

Its IR, greeting.ir.json. Expr.node and For.paramNodes are elided (section 4); everything else is exactly what lower() returned. Note the lifted inputInterface, the empty prelude, count as a Const before the elements, the two Text runs around the interpolation, the chain with condition: null on its <else>, the boolean hidden attribute and the exportName derived from the filename:

{
  "imports": [],
  "hoisted": [],
  "inputInterface": {
    "kind": "InputInterface",
    "code": "export interface Input {\n  name: string;\n  items: string[];\n}",
    "loc": {
      "line": 1,
      "column": 0
    },
    "end": {
      "line": 4,
      "column": 1
    },
    "span": {
      "sourceStart": 0,
      "sourceEnd": 61
    }
  },
  "needsAttrTagImport": false,
  "prelude": [],
  "body": [
    {
      "kind": "Const",
      "name": "count",
      "init": {
        "code": "input.items.length",
        "shape": "other",
        "span": {
          "sourceStart": 76,
          "sourceEnd": 94
        }
      },
      "span": {
        "sourceStart": 63,
        "sourceEnd": 96
      },
      "loc": {
        "line": 6,
        "column": 0
      }
    },
    {
      "kind": "Element",
      "name": "h1",
      "nameSpan": {
        "sourceStart": 98,
        "sourceEnd": 100
      },
      "span": {
        "sourceStart": 97,
        "sourceEnd": 141
      },
      "attrs": [
        {
          "kind": "static",
          "name": "class",
          "value": "title",
          "valueSpan": {
            "sourceStart": 107,
            "sourceEnd": 114
          },
          "nameSpan": {
            "sourceStart": 101,
            "sourceEnd": 106
          },
          "loc": {
            "line": 7,
            "column": 4
          }
        }
      ],
      "children": [
        {
          "kind": "Text",
          "value": "Hello, ",
          "span": {
            "sourceStart": 115,
            "sourceEnd": 122
          },
          "loc": {
            "line": 7,
            "column": 18
          }
        },
        {
          "kind": "Interpolation",
          "expr": {
            "code": "input.name",
            "shape": "other",
            "span": {
              "sourceStart": 124,
              "sourceEnd": 134
            }
          },
          "escaped": true,
          "span": {
            "sourceStart": 122,
            "sourceEnd": 135
          },
          "loc": {
            "line": 7,
            "column": 25
          }
        },
        {
          "kind": "Text",
          "value": "!",
          "span": {
            "sourceStart": 135,
            "sourceEnd": 136
          },
          "loc": {
            "line": 7,
            "column": 38
          }
        }
      ],
      "void": false,
      "loc": {
        "line": 7,
        "column": 0
      }
    },
    {
      "kind": "IfChain",
      "branches": [
        {
          "condition": {
            "code": "count",
            "shape": "other",
            "span": {
              "sourceStart": 146,
              "sourceEnd": 151
            }
          },
          "children": [
            {
              "kind": "Element",
              "name": "ul",
              "nameSpan": {
                "sourceStart": 156,
                "sourceEnd": 158
              },
              "span": {
                "sourceStart": 155,
                "sourceEnd": 232
              },
              "attrs": [],
              "children": [
                {
                  "kind": "For",
                  "source": {
                    "kind": "of",
                    "list": {
                      "code": "input.items",
                      "shape": "other",
                      "span": {
                        "sourceStart": 178,
                        "sourceEnd": 189
                      }
                    }
                  },
                  "params": [
                    "item"
                  ],
                  "bindings": [
                    "item"
                  ],
                  "paramSpans": [
                    {
                      "sourceStart": 169,
                      "sourceEnd": 173
                    }
                  ],
                  "key": null,
                  "children": [
                    {
                      "kind": "Element",
                      "name": "li",
                      "nameSpan": {
                        "sourceStart": 198,
                        "sourceEnd": 200
                      },
                      "span": {
                        "sourceStart": 197,
                        "sourceEnd": 213
                      },
                      "attrs": [],
                      "children": [
                        {
                          "kind": "Interpolation",
                          "expr": {
                            "code": "item",
                            "shape": "other",
                            "span": {
                              "sourceStart": 203,
                              "sourceEnd": 207
                            }
                          },
                          "escaped": true,
                          "span": {
                            "sourceStart": 201,
                            "sourceEnd": 208
                          },
                          "loc": {
                            "line": 11,
                            "column": 10
                          }
                        }
                      ],
                      "void": false,
                      "loc": {
                        "line": 11,
                        "column": 6
                      }
                    }
                  ],
                  "span": {
                    "sourceStart": 164,
                    "sourceEnd": 224
                  },
                  "loc": {
                    "line": 10,
                    "column": 4
                  }
                }
              ],
              "void": false,
              "loc": {
                "line": 9,
                "column": 2
              }
            }
          ],
          "span": {
            "sourceStart": 142,
            "sourceEnd": 238
          },
          "loc": {
            "line": 8,
            "column": 0
          }
        },
        {
          "condition": null,
          "children": [
            {
              "kind": "Element",
              "name": "p",
              "nameSpan": {
                "sourceStart": 249,
                "sourceEnd": 250
              },
              "span": {
                "sourceStart": 248,
                "sourceEnd": 274
              },
              "attrs": [
                {
                  "kind": "boolean",
                  "name": "hidden",
                  "nameSpan": {
                    "sourceStart": 251,
                    "sourceEnd": 257
                  },
                  "loc": {
                    "line": 16,
                    "column": 5
                  }
                }
              ],
              "children": [
                {
                  "kind": "Text",
                  "value": "Nothing yet.",
                  "span": {
                    "sourceStart": 258,
                    "sourceEnd": 270
                  },
                  "loc": {
                    "line": 16,
                    "column": 12
                  }
                }
              ],
              "void": false,
              "loc": {
                "line": 16,
                "column": 2
              }
            }
          ],
          "span": {
            "sourceStart": 239,
            "sourceEnd": 282
          },
          "loc": {
            "line": 15,
            "column": 0
          }
        }
      ],
      "span": {
        "sourceStart": 142,
        "sourceEnd": 282
      },
      "loc": {
        "line": 8,
        "column": 0
      }
    }
  ],
  "tagMetadata": {
    "readsContent": false,
    "attributeTags": [
      "items",
      "name"
    ],
    "inputCode": "export interface Input {\n  name: string;\n  items: string[];\n}"
  },
  "exportName": "Greeting",
  "returnValue": null
}

The module @mxlang/html emits from it, greeting.html.ts:

import { escape as __mxEscape, createOut as __mxCreateOut, type Out as __MxOut } from "@mxlang/html";

export interface Input {
  name: string;
  items: string[];
}

function Greeting(input: Input): string {
  const __mxOut = __mxCreateOut();
  __mxRender(input, __mxOut);
  return __mxOut.toString();
}
Greeting.render = __mxRender;

function __mxRender(input: Input, __mxOut: __MxOut): void {
  const count = input.items.length;
  __mxOut.write("<h1 class=\"title\">Hello, ");
  __mxOut.write(__mxEscape(input.name));
  __mxOut.write("!</h1>");
  if (count) {
    __mxOut.write("<ul>");
    const __mxFor6 = input.items;
    const __mxFor7 = __mxFor6 ? __mxFor6 : [];
    for (const item of __mxFor7) {
      __mxOut.write("<li>");
      __mxOut.write(__mxEscape(item));
      __mxOut.write("</li>");
    }
    __mxOut.write("</ul>");
  } else {
    __mxOut.write("<p hidden>Nothing yet.</p>");
  }
}
export { __mxRender as render };
Object.defineProperty(Greeting, Symbol.for("mx.component"), { value: true });

export default Greeting as ((input: Input) => string) & { render: typeof __mxRender };

The default export renders into a fresh sink through render(input, out), the module’s sink entry (decision 155). Called with { name: "<Ada>", items: ["a", "b"] } it returns <h1 class="title">Hello, &lt;Ada&gt;!</h1><ul><li>a</li><li>b</li></ul>; with an empty items it takes the <else> branch. The test asserts both.