Relationships
Informs 1
Related 26
Context
Composition gave refrakt two ways to arrange a rune, and the line between them depends on how each rune happens to be implemented:
- A composed rune is one definition file. Its frontmatter is the input (attributes, content model, fields, schema row), and its body is a template. A theme or site may replace the template (ADR-045, SPEC-177).
- A native rune is a TypeScript transform that builds a tree, plus an engine config entry that builds more of it (
structure,layout,contentWrapper,autoLabel,projection,postTransform). A theme may override that config, as legacy only (ADR-043 decision 6), and cannot rearrange the rune in any other way (ADR-045 decision 7).
So a theme author meets two conventions for the same need, and which one applies to recipe or codegroup is an implementation detail they should not have to know.
The engine was doing two jobs
The engine was designed as the theme layer: the place a theme reshapes a rune without running its code (SPEC-081, ADR-029). That job never ran in practice:
- Lumina's config overrides no rune (
packages/lumina/src/config.ts,luminaOverrides). - ADR-029 (structural assembly is theme-owned) and ADR-031 (site-level rune config overrides) are both still
proposed. ADR-029 records that the structure contract is correct "by accident" because no theme exercises the right. - ADR-043 retired it for everything new.
The engine's other job, rendering the shared vocabulary, is more central than before. Composed runes run through it. composedRuneConfig (packages/runes/src/lib/composition.ts) generates modifiers, metaFields, blocks, axis defaults and sequence from a definition, and the engine is what renders a {% field %} a template places.
What remains on the native side is therefore a second template language inside engine config. Native runes use it, composed runes do not, and themes may not use it.
Native runes need code to compute, not to parse
Fourteen runes declare a custom content model, the escape hatch that CustomModel (packages/types/src/content-model.ts) describes as "genuinely stateful and cannot be expressed declaratively". Read one by one, each processChildren mixes a parse that could be declared with a computation that needs code. SPEC-194 D6 has the inventory. Examples:
- Budget:
Description: $Amountis anitemModelpattern; the subtotal is arithmetic. - Comparison: columns from headings and rows from bold-labelled items are declarable; aligning rows across columns is a computation.
- Form: the field groupings are declarable; inferring each field's type from its option count and modifier words is a computation.
A custom model is also opaque to tooling: packages/runes/src/reference.ts can report only its prose description. The language server, editor, reference docs and validation see a grammar for most runes and a sentence for these fourteen.
Terms, and the third decision
- "Native" means written in TypeScript today. Once a rune moves, it is a definition like any composition; one that needs code names a
preparestage. "The first native runes to move" (SPEC-194 D14) means runes that are TypeScript now. - Macros are the one kind with no template (added 2026-11-10, SPEC-194 D15).
include,snippetanddatareplace themselves with authored Markdoc before the transform, so no part of them reaches the output for a theme to arrange. Their definitions declare the input as every rune does, and name a registeredpreprocessstage (SPEC-141) instead of a template. "Every rune is input + template" means every rune with output. - Decision 3 came later. While settling which runes keep classes (SPEC-196), it became clear that converting a rune had been aiming at parity with its current look, and that this kept rune-specific CSS alive under another name. ADR-044 already states the end the project wants: a theme that names no rune. Decision 3 makes conversions aim at it.
Decision
Option 4. It is made of three decisions.
Decision 1: every rune is input + template; native runes add a prepare stage
- One definition format for every rune.
- Frontmatter declares the input: attributes, content model, fields,
metaFields, presets, schema row and translation keys. - The body is the template.
- A native rune's definition additionally names a
preparestage and declares what itcomputes.
- Frontmatter declares the input: attributes, content model, fields,
preparecomputes; it does not parse or build.- It receives the resolved fields and the attributes, never raw AST.
- It returns values for the fields declared under
computes: on the rune, or on each item of a repeated slot. - It cannot create, remove or reorder slots, and it returns no tree.
- Code lives only in a package.
- A
preparestage is TypeScript, registered by a plugin or by core. - A
.mddefinition may name a registered stage. It cannot contain one. - A site-authored rune therefore stays code-free. This restates SPEC-161 D3 precisely: a template never runs code, and a composition never contains it.
- A
- The template is arrangeable for every rune. SPEC-177's lookup (site, then theme, then definition), its
defaults, and its checks apply to a native rune's template unchanged. ADR-045 decision 7 ("native runes are unaffected") is superseded. - The engine renders the vocabulary; it assembles no rune.
- Kept as vocabulary semantics:
modifiers,metaFields,blocks(a named group of fields the template places),sequence, axis defaults,rootAttributes,interactiveandeditHints. SPEC-194 D5 classifies every field.blockgoes: a rune's name is its tag name, and its classes are the theme's (SPEC-196 D10). - Deprecated as structure assembly, as each rune moves:
structure,layout,contentWrapper,autoLabel,projectionandpostTransform. - Engine config becomes compiler output, generated from a definition as
composedRuneConfigalready does, and is never a theme surface.
- Kept as vocabulary semantics:
- An opaque visual is one slot. A rune whose inside is a drawing (
chart,map,diagram,audio,juxtapose; the list is SPEC-194 D8's) places its drawing as a single slot. Its title, legend, caption and controls are fields and slots around that slot, which a theme may arrange. The drawing's own CSS stays the plugin's, written in tokens only (ADR-044 tier 3). - A template never names an HTML element. It places slots, fields, groups and runes. Elements come from what the definition declares: a group's arrangement, a value's
metaType, a primitive. This is what lets the deprecatedstructure,layoutandcontentWrapperfields go without moving their freetaginto templates, where it would reopen the theme boundary, let a template assert meaning the definition never declared, and need an allowlist to keep templates code-free. SPEC-194 D11 maps each need such a tag would serve to the vocabulary.
Decision 2: content models are declarative everywhere
A rune's content model is always declared in frontmatter.
CustomModelis deprecated, and removed once no first-party rune uses it.The grammar grows where the inventory shows a gap. SPEC-194 D7 names four extensions:
- node-started groups;
- a field taken from anywhere in the body;
- inline extraction from headings;
- repeated choice.
Each is specified once and is available to every definition, site-authored ones included.
What cannot be declared is a named gap, not an escape hatch. A rune whose input truly cannot be described by the grammar is recorded as a gap against the grammar and closed there. It does not get its own parser.
Decision 3: converting a rune aims at a simpler design language, not parity
Added 2026-11-09.
- A converted rune ships no rune CSS. Whether it becomes a composition or a native definition, a domain rune is styled through the primitives it places and the universal dimensions. Parity with how it looks today is not the bar.
- Its stylesheet is triaged at conversion. Each rule is dropped as an accepted simplification, promoted into a primitive, a dimension or the shared vocabulary, or kept as a recorded exception (a drawing, or a reviewed special case on
[data-rune]). A Lumina lint with an allowlist that may only shrink holds the line (SPEC-196 D11), and the triage is a go-live gate (SPEC-181). - Only the vocabulary gets classes. The theme's default
"bem"setting classes primitives and drawings, declared by a definition'srole, and never domain runes (SPEC-196 D8).
Rationale
- It gives a theme author one convention. CSS on the vocabulary for everything, plus a template where the theme has an opinion about arrangement, for any rune. Whether
codegroupruns code is invisible to them. - It removes the engine's second template language. Arrangement is expressed once, in the template language, which is readable, checkable and overridable.
- It keeps code where code is needed, and nowhere else.
prepareis small and pure: provider tables, diffing, field-type inference. Arithmetic and label chains are SPEC-195's functions. Everything around it is declared, so tooling sees every rune's grammar and every rune's output shape. - It completes ADR-043 and ADR-045 rather than reversing them. ADR-043's line (a theme does not change meaning) and ADR-045's (a theme may change arrangement) hold unchanged. This decision removes the exception that kept native runes out of ADR-045.
- It is incremental. A native rune without a template is today's native rune. Each rune moves on its own, and the deprecated config fields go when the last user goes.
Consequences
- ADR-045 decision 7 is superseded by decision 1.4. ADR-045's other decisions apply to every rune.
- ADR-043 decision 6 gets an end. A theme's
runes:section is removed fromThemeConfigOverridesonce no first-party rune needs a config-only lever. SPEC-194 D9 sets the condition. - ADR-029 and ADR-031 should be rejected.
- ADR-029: a theme reshapes structure through a template, not through config.
- ADR-031: a site does so through
templates/, SPEC-177 D4's site level. - Neither is accepted today, so rejecting them breaks nothing.
- SPEC-161 D3 is restated as decision 1.3 and gets a pointer here.
- SPEC-177 widens from composed runes to every rune with a template. Its checks read slots and fields from the content model and
computes, so they still run without content. - Structure contracts are per theme for every rune, as ADR-045 already made them for composed runes.
- Each native rune needs a pass to separate its parse, its computation and its arrangement. Some transforms make arrangement decisions while parsing (
codegroup's single-fence case). Under this decision, the fact is computed in the input half and selects a template variant (SPEC-168 D9), so the arrangement stays the template's. - Tooling gains a full grammar for the fourteen runes that today report only a prose
descriptioninrefrakt reference, the language server and the editor. - The vocabulary must grow ahead of the conversions. Every rule a triage promotes needs a primitive, a dimension or a vocabulary value to land in. Gaps found during conversions are the expected input to that work, not a reason to keep rune CSS.
Implementation order
Recorded 2026-11-09. Neither "after every composition" nor "all first": what changes the cost or shape of conversions comes first, and the native-rune work follows the compositions, which prove the definition format on many runes first.
- Accept this decision and review SPEC-194, SPEC-195 and SPEC-196 together before any work items.
- Independent fixes, now: BUG-048; SPEC-196 D6 (behaviour scripts select by attribute, which also fixes the prefix bug) and D5 (the additive attributes).
- Vocabulary first:
- the primitive and dimension work the triage will need: SPEC-160's
sectionandcard, SPEC-156's arrangements, and the draft sentiment and glyph specs (SPEC-163, SPEC-164); - SPEC-195's basics, which unblock conversions such as
recipe'stotalTimeandbudget's sum: the function registry with signatures,computesexpressions,matches,first,item,splitand the fan-out rule. Values may stay strings until SPEC-166 lands; - the Lumina lint (SPEC-196 D11), with an allowlist that starts as today's rune stylesheets.
- the primitive and dimension work the triage will need: SPEC-160's
- Template-language extensions, each just before its first user: two-level iteration (SPEC-194 D12) and
fragment(SPEC-168 D8). - SPEC-196's role-based classes: the
classessetting with"bem"classing primitives and drawings, androleon definitions. It changes no output on the day it lands, and it must precede the first native domain rune that becomes a definition (embed), so that rune loses its classes the way compositions do. - The composition migration continues (the plugin audits SPEC-147 to SPEC-157), each conversion with its stylesheet triaged and its rune removed from the allowlist. Alongside it run the first native definitions, in SPEC-194 D14's order (
pull-quotewith theattributionprimitive, thencodegroup, thenembedwith theframeprimitive), and the loader split for$pageand$site(SPEC-194 D12). - The remaining native runes move to definitions, in SPEC-194 D10's order. Each is triaged like a conversion.
- Removals, last, once nothing first-party uses them (SPEC-194 D9): the structure-assembly config fields, the
runes:section of theme config,CustomModel, and the olddata-runenames SPEC-196 D10 replaces.featured-tiergoes with thepricingcomposition.
One rule holds throughout: no conversion is merged that would need its CSS triaged twice. If a conversion is ready before the vocabulary it needs, the vocabulary is extended first.