Relationships
Related 40
Summary
ADR-048 makes every rune one definition: a declared input and a template. A rune that needs code is a definition that also names a prepare stage, TypeScript that computes values from already-parsed content. Throughout, "native" means written in TypeScript today; once moved, every rune is a definition. This spec is the mechanism:
- the definition format for a native rune:
prepareandcomputes(D1, D2); - where code may live (D3);
- template override for every rune (D4);
- what engine config keeps and what it loses (D5);
- the inventory of
customcontent models (D6) and the grammar extensions that replace them (D7); - opaque visuals (D8);
- when the legacy levers are removed (D9), and the migration order (D10);
- a template never names an HTML element (D11);
- a rune reads data from three scopes, and only the entity registry makes it wait (D12);
- a primitive is a definition too, and places smaller primitives such as
attribution(D13); - the first migrations, worked:
pull-quote,codegroup,embed(D14).
Prerequisites
| Needs | From | State on 2026-11-09 |
|---|---|---|
| Theme and site templates, their lookup and checks | SPEC-177 | draft |
The function vocabulary computes is written in | SPEC-195 | accepted with this spec |
| Template variants, including a computed selector, and fragments | SPEC-168 D8, D9 | draft |
Classes as a theme setting, and role | SPEC-196 | accepted with this spec |
First-party definitions loaded from .md rune directories | SPEC-153 | see spec |
Content-model groups, nested models and position: last | SPEC-186 | accepted |
Paragraph itemModel and fills | SPEC-182 | implemented |
D1–D3 and D6–D7 can be built before SPEC-177: a native rune with a template is useful as soon as its template replaces its engine structure, even before anyone can override it. D4 needs SPEC-177.
What exists, measured
- A composed definition is one Markdoc file. Frontmatter holds
attributes,content,metaFields,blocks,schemaanddefaults, and the body is the template (plugins/marketing/runes/testimonial.md).defineComposedRunebuilds the rune from it, andcomposedRuneConfig(packages/runes/src/lib/composition.ts) generates its engine config, markedcomposed: true. - A template places slots (
{% slot %}), metadata blocks ({% metablock %}), core runes and repeated items.$each.<name>exposes exactly the content model'semitAttributes. - A native rune is two artifacts.
- A
createContentModelSchematransform builds a tree withcreateComponentRenderable. - A
RuneConfigentry (packages/runes/src/config.ts, 2,846 lines, plus about 1,600 lines across the plugin configs) adds structure on top of that tree.
- A
- Fourteen runes use
type: 'custom', listed in D6.packages/runes/src/reference.tsreports such a model as{ type: 'custom', description }and nothing more. - No theme overrides any rune (
luminaOverrides,packages/lumina/src/config.ts). Composed runes refuse overrides (WORK-669).
Decisions
D1: a native rune is a definition file that names a prepare stage
Example revised 2026-11-09: embed, the rune D14 works through, replaces an earlier codegroup example that needed no stage once SPEC-195's functions existed.
--- tag: figure attributes: url: { type: string, required: true } aspect: { type: string, matches: ["16:9", "4:3", "1:1", auto], default: "16:9" } title: { type: string } content: type: sequence fields: fallback: { match: any, greedy: true, optional: true } prepare: embed computes: provider: { type: string } embedUrl: { type: string } frameTitle: first($attrs.title, "Embedded content") schema: type: VideoObject properties: { title: name, url: contentUrl, embedUrl: embedUrl } ---
The body is a template, as for any composition (D14 has the full examples).
The same keys as a composition, plus two.
preparenames a registered stage (D3).computesdeclares every value the stage returns: its name, its type, and whether it sits on the rune or on each item of a repeated slot (panels.label). The same key also holds expressions (SPEC-195 D8), so a rune may mix values its stage fills with values a function computes.
One more key for every definition,
role(added 2026-11-09):primitive(something other runes place),drawing(an opaque visual, D8) or domain, the default. It is a claim to be part of the shared design language, and it decides whether the theme's"bem"setting gives the rune classes (SPEC-196 D8). A composition declares it too. A primitive also names the runes that place it,placedBy: [testimonial], which is what SPEC-196 D8's test checks.A rune's name is its tag name (added 2026-11-09). A definition file is named after the tag authors write (
pullquote.md,codegroup.md), and that name is also itsdata-runeand its BEM block. Several native runes today emit a differentdata-rune(pull-quote,code-group); moving to a definition aligns it with the tag (SPEC-196 D10).Nothing else about the format changes. A definition without
prepareis a composition, exactly as today.Computed values are values, not slots.
- A rune-level computed value is readable in the template as
$computed.<name>. - A per-item value is added to what
$eachexposes, beside the content model'semitAttributes. - A computed value may also feed
metaFieldsand theschemarow by name, so a subtotal can be both shown and published.
- A rune-level computed value is readable in the template as
A matched node's own attributes. The example reads a fence's attributes through
$node.<name>inemitAttributes. TodayemitAttributesreads only item-model fields and heading-extracted values, so this is a small addition, made withcodegroup(D14).$computedis its own scope (decided 2026-11-07). Computed values never join$attrs. SPEC-177 D3's precedence tells an author's explicit value from a default, and a computed value is neither, so mixing the scopes would blur both.A computed value is read-only in the editor (decided 2026-11-09). The block editor infers it: a value under
computesis not in the content model, so there is nothing an author could edit. No new key marks it. Where a template shows a computed value inside an editable region, the editor displays it and does not make it editable.
D2: prepare computes; it does not parse or build
// registered by core as Plugin.prepare.embed export const prepareEmbed: Prepare<EmbedInput, EmbedComputed> = ({ attrs }) => { const { provider, embedUrl } = detectProvider(attrs.url); // today's provider table return { provider, embedUrl }; };
Input:
- the resolved fields, with emitted attributes and item-model values already extracted;
- the attributes, after defaults;
- a context of locale, site and source path.
It never receives raw AST.
One exception, named rather than general:
previewandsandboxdisplay an example's own source text, which no resolved field holds (they readconfig.variables.__sourcetoday). The definition declares that need (input: [source]), and only then does the context carry the raw source of the rune's own body. No other rune gets it.Output: exactly the values
computesdeclares, nothing else.- An undeclared key is an error (
prepare-undeclared-value). - A missing required key is an error (
prepare-missing-value). - Both are checked in development and in tests. Production trusts the declaration.
- An undeclared key is an error (
It cannot touch structure. It returns no tree, creates no slot, and cannot remove, reorder or filter the items of a slot. If items need to be filtered or reordered, that is a content-model or template concern.
It is pure and synchronous. Data fetching stays where it is today, in the cross-page pipeline hooks.
preparecan read what a hook put in its context, but cannot start I/O.Context comes from the three scopes of D12, as values only. Resolvers return data, never markup (D12.5).
Facts, not arrangement. Where a transform today chooses an arrangement while it parses (
codegroup's single-fence branch), the fact is computed in the input half and selects a template variant (SPEC-168 D9): the template decides what to do with it.
D3: code is registered by a package, never written in a definition
- A plugin registers stages beside its runes:
Plugin.prepare: Record<string, Prepare>. Core registers its own the same way. - A definition names a stage by key. A name that no loaded package registers reports
prepare-unknownand the rune is not loaded. - A site's
runes/directory may name a registered stage but never define one. A site-authored definition stays code-free, so this restates SPEC-161 D3 precisely: a template never runs code, and a definition file never contains it. - A stage is private to its rune (decided 2026-11-07). It may be named only by the definition its package ships. Letting other runes name it would make every stage's input and output a public API, versioned like a rune, and no case needs that yet. Shared logic is reused another way; see "Future: reusing computation" below.
D4: every rune with a template is arrangeable
SPEC-177 applies to a native rune's template without change:
- lookup is site, then theme, then definition, per template value and per
defaultskey; - every slot must be placed;
- a replacement file carries only
defaultsand a body, and any input key in it, now includingprepareandcomputes, reportstemplate-override-input; - structured data is compared with the definition's own template.
The checks read slots from the content model and values from computes, so they run when the site loads, without content and without running prepare.
codegroup's own templates are in D14: two variants, single and tabs, chosen by a computed selector. An editorial theme that prints code groups as stacked, captioned listings replaces only the tabs variant, in its templates/codegroup.md:
{% template layout="tabs" %} {% metablock name="topbar" /%} {% slot name="panels" each %} {% group name="listing" as="figure" %} {% slot /%} {% caption text=$each.label /%} {% /group %} {% /slot %} {% /template %}
It inherits the single variant, places every slot once, and changes no input: the label fallback chain and the labels attribute are untouched. It uses only what a template may: group as="figure" (D11) and the caption primitive ("Candidate primitives", below).
D5: engine config keeps vocabulary and loses assembly
Each RuneConfig field (packages/transform/src/types.ts) falls into one of three groups:
| Group | Fields | Fate |
|---|---|---|
| Identity and vocabulary | modifiers, contextModifiers (a list of parents, emitted as data-in, SPEC-196 D5), metaFields, blocks, sections, provides, universalAttributes, mediaSlots, frameTarget, substrateTarget, rootAttributes, interactive, editHints, sequence, sequenceDirection, staggerItems, parent, requiresParent, sectionRoleExceptions, guestFit, composed, the axis defaults (defaultWidth, defaultSpacing, defaultInset, defaultReading, contentMeasure, defaultDensity, defaultElevation, defaultProminence, childDensity) | kept; generated from the definition |
| Structure assembly | structure, layout, contentWrapper, autoLabel, projection, postTransform | deprecated; the template does it |
| Classified on 2026-11-09 | variants, styles, staticModifiers, checklist, scope | each settled below |
The five fields settled last (measured 2026-11-09):
| Field | What it is | Uses | Fate |
|---|---|---|---|
variants | merges a partial config over the base, per modifier value, before assembly | 4: card, section, recipe, track | deprecated with assembly. Two of the four deltas override assembly (recipe and track add layout wrappers; recipe's is a free div with attributes, which D11 forbids). The template expresses each as a {% if %}. The other two deltas only add the cover static modifier and a root attribute, both already said by data-media-position="cover" |
styles | turns a modifier value into an inline style or custom property | 15 (6 core, 9 plugin) | vocabulary, but not a definition key. Definitions already reject a styles key (STYLE_KEYS, packages/runes/src/lib/composition.ts:1735). A definition forwards the attribute to the primitive that owns the style, as hero already forwards valign to section. 8 of the 15 uses are the same valign → --split-valign entry, which belongs to the split primitive |
staticModifiers | always adds rf-{block}--{name}, as a class only | 4: featured-tier, and cover inside 3 variants | deprecated. Every use is already said by an attribute (data-rune="featured-tier", data-media-position="cover"); SPEC-196 D5 retargets the 14 selectors that use it |
checklist | nothing: no engine code reads it (checkbox detection runs on every list item) | 2: work, bug | removed |
scope | the i18n key prefix, stamped from the owning plugin (assemble.ts:155) | 0 authored | identity, generated: no authored replacement is needed |
blockgoes away. Which classes the output carries is the theme's setting (SPEC-196). Its"bem"generator classes primitives and drawings, named after the rune's tag name, and gives domain runes none (SPEC-196 D8, D10, revised 2026-11-09). A native rune keeps its configuredblockand today's classes until it moves to a definition. Then a primitive keeps its classes unchanged (its tag name is its old block), only itsdata-runechanges where it differed, and a domain rune loses its classes as its stylesheet is triaged (SPEC-196 D11). Definitions keep rejecting ablockkey (STYLE_KEYS, SPEC-145 D2).- A rune with a definition gets its engine config generated, as
composedRuneConfigdoes.config.tskeeps only runes that have not moved. - A deprecated field on a rune that has a template is an error (
engine-config-assembly-with-template). It also reports while that rune keeps its config, so the two cannot overlap on one rune. postTransformhas no replacement in config. The code it holds goes intopreparewhen it computes a value. When it rearranges, the arrangement goes into the template.
D6: the custom content models, sorted
Each processChildren mixes a parse with a computation. Sorted by what is left once the computation moves to prepare:
Declarable today
| Rune | Declarative model | prepare |
|---|---|---|
nav | sections on heading:1, with implicitSection for a flat list | none (slug resolution is a pipeline step) |
symbol (group kinds) | one sections model on heading:3; the template varies the arrangement by kind (SPEC-169 D2 and D5: a definition's content model never depends on attribute values). Corrected 2026-11-09: an earlier draft used when | none |
symbol-group | sections on heading:4 + emitTag: symbol-member | none |
definition | sequence: a term group (headings, and paragraphs read by an itemModel for image, icon or bold text), then the description | none (processChildren is the identity function today; the split is in transform) |
bento | sections for cells | none; pushing frame attributes down to cells is the template's (SPEC-145 D32) |
Needs a D7 extension
| Rune | Extension | prepare |
|---|---|---|
storyboard | node-started groups: each image starts a panel | none |
preview | a field taken from anywhere: the fence | renders the example's source and HTML; it reads the raw source (D2's named exception). Corrected 2026-11-07: an earlier draft said none |
tabs | inline extraction from headings: a tab's image | none |
form | repeated choice, a SPEC-186 D1 group for blockquote + list, position: last for the submit paragraph | field type inference (option count, modifier words) |
Declarable, with a computation left
| Rune | prepare |
|---|---|
budget, budget-category | subtotals, or none once SPEC-162's tally lands |
conversation | speaker fallback speakers[i % n] (the bold speaker is a nested model) |
comparison | aligning rows across columns against a master label list |
map | parsing coordinates into numbers (name, description and link are an itemModel) |
This sorting is a hypothesis. form was read in full; the others from their processChildren descriptions and the opening of their transforms. The first work item for each rune confirms its row or moves it.
D7: four content-model extensions
Each is a general grammar feature, available to every definition and reported by refrakt reference like the existing patterns.
- Node-started groups.
sectionstakes any node type as its delimiter (sectionHeading: image), and the delimiter node stays in its group. WithoutemitTag, a group's leading node is bound like a heading. - A field from anywhere.
position: anyon a field takes the first node that matches it, wherever it sits, before the rest of the sequence is walked. It is a sibling of SPEC-186 D3'sposition: last, with the same "only one per model" limit. - Inline extraction from headings.
headingExtractfields accept the inline matches anitemModelaccepts (image,strong,link,code), not onlytext. - Repeated choice.
{ type: repeat, of: [ …fields or groups… ] }matches, in any order and any number of times, whichever alternative fits next, and yields an ordered list of tagged items. The template places them with{% slot name="…" each %}and branches on$each.kind.
Each extension is specified and implemented with the first rune that needs it, not in advance.
D8: an opaque visual is one slot
chart, map, diagram, audio and juxtapose draw something no template can rearrange. This is the list of drawings (role: drawing, SPEC-196 D8) every document uses; embed and gallery are not on it: embed places a frame primitive, and gallery's items are content with a behaviour.
- Their drawing is one slot.
- Their title, legend, caption, controls and fallback content are fields and slots around it, which a theme may arrange.
- The drawing's own CSS stays with the plugin, in tokens only (ADR-044 tier 3).
A theme can put a map's legend under the map. It cannot restyle the map's tiles except through tokens.
Parts a behaviour depends on are primitives or opaque slots (decided 2026-11-09, after an audit of every behaviour and web component). A replacement template keeps every slot and every data-name, but a behaviour that relies on element choice or DOM shape needs more than that:
| Depends on | Behaviours | So |
|---|---|---|
| a fixed element | accordion (native <details> and <summary>), tabs (<button>), datatable and chart (<table>), form (<form>) | the part is a primitive that owns its element |
| a custom-element root | rf-chart, rf-map, rf-diagram, rf-audio, rf-sandbox, rf-nav | a template never changes the root element of these runes |
| direct-child order | tabs (button i pairs with panel i), juxtapose (two panels by position), carousel (slides are the track's children) | the container and its items are one primitive; "direct children" is documented as its contract |
| the whole arrangement | preview, which turns every other root child into canvas content | preview is one opaque slot; a template arranges nothing inside it |
Every other behaviour needs only selector changes, listed in SPEC-196 D6.
D9: when the legacy levers are removed
CustomModelis removed in the release after the last first-party rune leaves it. Until then it is marked deprecated in its type, andrefrakt validatewarns on a third-party plugin rune that uses it.- Structure-assembly config fields (D5) are removed in the release after the last first-party rune leaves them. Their removal is a breaking change for third-party plugins and ships through SPEC-189's migration table.
- A theme's
runes:section (ADR-043 decision 6) is removed in the same release. By then every lever it offered is either identity (refused already) or assembly (gone), so nothing is left to override.
D10: migration order
Three acceptance cases, worked in D14, in this order:
pull-quotefor a primitive written as a definition (D13), with noprepareand nocomputes.codegroupfor the template andcomputes. Its parse is declarative already, its two computed values (layout,panels.file,panels.label) are SPEC-195 expressions, and its arrangement (tabs, or a single panel with chrome) is one a theme plausibly wants to change.embedforprepare. Provider detection and the embed-URL rewrite are real rune-specific computation (packages/runes/src/tags/embed.ts), with no second adopter that would make them functions.
Revised 2026-11-07. An earlier draft made
codegroupthe single acceptance case, before the measurement below showed it needs no stage. Revised 2026-11-09:pull-quoteadded as the first case.The "declarable today" runes in D6: they need no new grammar and no
prepare, so each one probably becomes a plain composition (ADR-044 tier 1) rather than a native rune with a template.Each D7 extension, with its first rune:
storyboard,preview,tabs, thenform.The computed rows of D6, after
budgetfollows SPEC-162.The remaining native runes without a
custommodel, ordered by how much engine structure they carry.The opaque visuals (D8) last: they gain the least.
Rune by rune, each moves under SPEC-181's staging process, as plugin runes moving to compositions do now. That includes its fifth gate: the rune's stylesheet is triaged, and parity with its current look is not the bar (SPEC-196 D11). For a domain rune that stays native, this is the larger part of the work: about 1,000 of Lumina's rune-stylesheet selectors belong to runes that stay native, and each move is a design pass, not a mechanical migration.
D11: a template never names an HTML element
A template places slots, fields, metadata blocks, groups and runes. It has no tag that emits an element by name ({% tag name="div" %}), and no tag that takes free attributes.
Elements come from facts the definition declares.
- A group's arrangement picks its element: a
ladderis<ol>when the rune declares asequence,<ul>otherwise (SPEC-156 D3). - A value's
metaTypepicks the value element (SPEC-145 D28). - A primitive picks its own elements.
- A group's arrangement picks its element: a
Why not a free element tag:
- The theme boundary. An element no vocabulary describes is structure no theme knows, which ADR-043 and ADR-044 bound away.
- Meaning.
ol,aside,headerandtimeare claims about content. A free tag could assert an order or a role the definition never declared. - Engine-owned attributes. Free attributes could write
data-rune(a name-resolution boundary that silently drops schema properties, SPEC-145 D19),data-field,data-zone-layoutordata-sequence. - No code in templates. ADR-045 decision 2 holds only if
script,iframe,styleandon*cannot be written. Theme and plugin templates ship in third-party packages. - Checks. A contract records such an element, but no check can say anything about it, and the editor has no edit hint for it.
The needs a free tag would serve, and where they go:
Need Where Grouping or arranging parts {% group name layout %}(SPEC-156 D2)A header, body or footer zone the sectionprimitive's zones (SPEC-160)A semantic wrapper ( aside,footer)a closed as=ongroup, admitted one value at a time with its first case, aslayoutadmits topologiesAn inline wrapper around part of a line an inline group, same rules (missing today)Decoration (ornament, divider, flourish) glyph and ornament sets (SPEC-164), or CSS An icon beside a value metaFieldsiconsStructure the vocabulary cannot express an opaque slot drawn by the plugin (D8) The same rule binds
prepare(D2): it returns no tree, so it cannot emit an element either. Elements that native transforms build today (breadcrumb'snav,olandli) move to the template and follow this rule.
What names an element today, measured on 2026-11-06. The structure field itself is unused in first-party configs; elements are named in three other places:
| Where | What | Maps to |
|---|---|---|
layout created wrappers | eleven { tag: 'div' } wrappers (nine content wrappers, two nested) and nine { tag: 'header' } preambles, some inside variants (core, docs, learning, marketing, media, places, storytelling) | section's header and body zones; a group where a wrapper is styled; nothing where it is not |
contentWrapper | two divs (packages/runes/src/config.ts, plugins/places/src/config.ts) | a group, or nothing |
metaFields.*.tag | time on plan's temporal fields (plugins/plan/src/config.ts) | the value element from metaType: temporal, which D28 already implies |
Each rune's work item confirms its rows. An entry that maps to no row is a vocabulary gap, recorded and closed the way D7 closes content-model gaps. A div that exists only so that CSS has something to select needs no replacement: the template places its children directly.
D12: a rune reads data from three scopes, and only the registry makes it wait
Decided 2026-11-08, answering the open question the measurement below raised about pipeline resolvers that build output.
| Scope | Read through | Known | Runes that read it |
|---|---|---|---|
| the rune's own input | $attrs, slots, $computed | at transform | every rune |
| the page and the site's page index | $page, $site, and the functions over them (SPEC-195) | at transform, once every page is parsed | pagination, breadcrumb, toc, nav (auto), drawer, file-ref |
| the entity registry | a data: entry with a registry query | after every page is transformed | collection, relationships, aggregate, blog, xref, expand |
The loader parses every page before it transforms any.
processContentTree(packages/content/src/site.ts:611–678) runs one loop that parses and transforms each page in turn. It becomes two loops in the same function:- frontmatter, route, parse and title for every page, then the page index is built;
- variables (now including the index), preprocess and transform.
The content tree has already read every file before the loop starts, and everything the index needs comes from frontmatter, route and AST: the title is the frontmatter's or the first H1's (
derivePageTitle). The ASTs are held between the loops; each is dropped after its transform.$pagegrows;$siteis new.$pageexists already (url,path,dir,slug,title,draft;buildPageContentVariables). It gainsparent,ancestors,children,prev,nextandheadings, and$siteholdspagesand the page tree. They are getters over the index, computed only when read. Anything that takes a parameter is a function instead (neighbours($page, "section"),url(slug),select($page, …)), since Markdoc has no method calls.Data lists are repeated slots. A definition declares a list it reads under
data:, and the template iterates it like any repeated slot, with$itembound to each entry ascollectionbinds it today (projectItem):data: entries: select($page, "heading", concat("level:2..", add($attrs.depth, 1))) # the page as written items: { query: entities, type: $attrs.type, filter: $attrs.filter, sort: $attrs.sort, limit: $attrs.limit } # the registry
Single values need no declaration: an expression reads
$page.prev.urldirectly. The range2..3assumes SPEC-138's comparison gap is closed; SPEC-070 has no range today. Building the filter withconcatis the interim form SPEC-195 D7 allows until SPEC-138's structured predicates exist;tocmoves to the structured form with them.Only a registry read defers. A rune whose
data:contains a registry query is expanded after the pipeline, with its authored source preserved, throughtransformDeferredTemplate(packages/runes/src/deferred-body.ts), ascollection's body already is. The schema applier runs after expansion, as the auto breadcrumb's already does. Every other rune is expanded at transform. The loader sees which scope a definition reads from itsdata:and expressions, without running it.Resolvers return data, never markup. A resolver finds, sorts and limits, and returns entries; the rune's template arranges them. This extends D2 and D11 to the pipeline. What it removes:
- the built-in renderers (
renderBuiltInItem,renderTable, the group wrappers incollection-resolve.ts,buildAutoBreadcrumb'snav,olandli), which become default templates; - the
__slug:placeholders and the postProcess pass that resolves them, sinceurl()resolves at transform; - the region pass after the pipeline (
site.ts:813–853), since layout regions see$pageat transform; - the SEO re-harvest workaround for breadcrumbs (
site.ts:785–811), since their structured data exists at the first harvest.
- the built-in renderers (
Layouts see
$page. Layouts are already transformed once per page:resolveLayoutsruns inside the page loop, andparseLayoutcallsMarkdoc.transformfor every layout in the chain, with no cache (packages/content/src/layout.ts:65). Passing the page's variables to that transform costs nothing extra. The comment insite.tssaying layouts "are parsed once and shared across pages" is wrong and is corrected with this change.Manual and automatic forms share one definition.
breadcrumb,paginationandnaveach have a written form and an automatic one, built today by two code paths. Under this decision both fill the same data, and one template arranges both. An author's explicit value wins throughfirst(…).The page as written versus what runes registered.
select($page, type, filter)reads the page's own AST: headings, images, code blocks, tables, links and rune tags with their attributes. It sees what was written, not what runes derive: afigurerune's caption, taken from its first paragraph, is not in the AST. A list that needs derived values reads the registry with a page filter, and waits.
Costs and limits:
- Nav order needs reading from layout ASTs. Auto pagination prefers the reading order written in a layout's
{% nav %}over sibling order, and reads it today from the transformed nav after__slug:resolution (collectNavSequences). The index has to read it from the AST, through nav's content model. That is straightforward once the model is declarative (D6 lists it as declarable today). Pagination moves only after that, so its output does not change in between. - Contributed pages are not in the index. Pages from
entityRoutesor a plugin'scontributePages(SPEC-069) are created during the pipeline, from registered entities.$siteat transform holds file-backed pages only. A pagination or nav that must include contributed pages reads the registry and waits. This follows from the scope rule, but authors may notice it, so it is documented. - Titles are derived before preprocess, as today. A title that only an
{% include %}supplies is still not seen. - The dev server is unaffected. Any content change already reloads the whole site (
invalidateSite(),packages/sveltekit/src/plugin.ts:283), so there is no per-page dependency tracking to keep correct.
Examples. pagination, with no data: and no deferral:
computes: prevUrl: first(url($attrs.prev), if($attrs.auto, $page.prev.url)) prevLabel: first($attrs["prev-label"], if($attrs.auto, $page.prev.title), $attrs.prev) nextUrl: first(url($attrs.next), if($attrs.auto, $page.next.url)) nextLabel: first($attrs["next-label"], if($attrs.auto, $page.next.title), $attrs.next)
{% if $computed.prevUrl %} {% link href=$computed.prevUrl %} {% group name="prev" layout="bar" %} {% icon name="arrow-left" /%} {% $computed.prevLabel %} {% /group %} {% /link %} {% /if %}
toc, reading the page as written:
{% group name="entries" layout="ladder" %} {% slot name="entries" each %} {% link href=concat("#", $item.id) %}{% $item.text %}{% /link %} {% /slot %} {% /group %}
collection, reading the registry and deferred. Its item is a fragment, declared at the top level of the body and used with {% partial %}, as SPEC-168 D8 specifies. The author's body, when present, replaces the item fragment, so a theme can arrange every collection on a site without touching an author's item template:
{% fragment name="item" %} {% card href=$item.url %} ### {% $item.data.title %} {% /card %} {% /fragment %} {% template layout="grid" %} {% grid %} {% slot name="items" each %} {% partial file="#item" /%} {% /slot %} {% /grid %} {% /template %}
Decided within D12 (2026-11-09):
nav's tree. Up to two levels (groups and their items), nav is arranged by its template like any other data list. Deeper than that, the tree is one opaque nested-list primitive drawn in the shared vocabulary (D8), and the template arranges everything around it: the title, the groups, the layout. Templates gain no recursion. That keeps ADR-036's line: a recursive fragment would be new power in the template language for one rune. The cost is that a theme cannot rearrange individual items below the second level.- A variable list of fields (
collection'sfields="status,priority") is shown by a small core primitive,{% fields of=$item names=$attrs.fields /%}. It renders the named fields of an entity as labelled values through the shared vocabulary (metaType,data-field), since a template cannot iterate a list of attribute names.
Specified within D12, not built yet:
Two-level iteration: a repeated slot inside a repeated slot. Grouped collections,
relationships' groups, nested headings intocand the two template-arranged levels ofnavall need it. Measured 2026-11-09: not supported today. Expansion rejects any named slot inside aneachslot (slot-inside-each,packages/runes/src/lib/composition.ts:934), because a rune-level field placed there would repeat once per item. An item also exposes only itsemitAttributes, never a list of its own. The extension it needs:- an item may carry a list of its own: a group's entries, a section's sub-items;
- inside an
each,{% slot name="<item field>" each %}iterates that list; - the check distinguishes an item's field (allowed) from the rune's field (still rejected, for the original reason).
Exactly one nested level, no deeper, matching the
navdecision above.The
fragmentoverride point: a definition names the fragment an author's body replaces (deferBody: item), on top of SPEC-168 D8's fragments, which are a draft.
D13: a primitive is a definition too, and places smaller primitives
Added 2026-11-09, from writing pull-quote as a definition. A primitive (SPEC-196 D8's role: primitive) is written in the same format as any rune. Where its template needs structure D11 does not let a template name, that structure is a smaller primitive it places, never an exception to D11.
Worked example: pull-quote. It needs no prepare stage and no computes. About 170 lines of packages/runes/src/tags/pullquote.ts and its PullQuote engine entry become this file:
--- tag: if($attrs.excerpt, "aside", "figure") role: primitive placedBy: [testimonial] aliases: [pull-quote, quote] templates: { by: excerpt } description: A featured quotation, or with `excerpt` a pull quote repeated from the text attributes: author: { type: string, description: "Who said it, when not written as a paragraph" } source: { type: string, description: "Where it is from: a role, a work or a date" } align: { type: string, matches: [left, center, right], default: center } excerpt: { type: boolean, description: "The words already appear in the text; hidden from assistive technology" } content: type: sequence fields: quoted: group: - name: quote match: blockquote model: type: sequence fields: - { name: body, match: any, greedy: true, optional: true } - name: attribution match: paragraph optional: true position: last itemModel: prefix: '^\s*[—–]\s*$' fields: - { name: name, match: strong } - { name: source, match: text, pattern: '^\s*[,—–]\s*(.+)$', optional: true } fills: { author: $name, source: $source } - name: attribution match: paragraph optional: true itemModel: fields: - { name: name, match: strong } - { name: source, match: text, pattern: '^\s*[-–—,]\s*(.+)$', optional: true } fills: { author: $name, source: $source } body: { match: any, greedy: true, optional: true } rootAttributes: data-quote: if($attrs.excerpt, "excerpt", "featured") aria-hidden: if($attrs.excerpt, "true") sections: { quote: body } provides: [prose, featured-quotation] defaults: { density: compact, elevation: flush, reading: prose } editHints: { quote: inline } --- {% template excerpt=false %} {% group name="quote" as="blockquote" %} {% slot name="quote.body" %}{% slot name="body" /%}{% /slot %} {% /group %} {% attribution name=$attrs.author source=$attrs.source /%} {% /template %} {% template excerpt=true %} {% group name="figure" as="figure" %} {% group name="quote" as="blockquote" %} {% slot name="quote.body" %}{% slot name="body" /%}{% /slot %} {% /group %} {% attribution name=$attrs.author source=$attrs.source /%} {% /group %} {% /template %}
The two templates share their inside, which SPEC-168 D8's fragments will hold once they exist.
| Today | In the definition |
|---|---|
a when: { hasChild: blockquote } model | one model with a group (SPEC-186 D1); definitions cannot use when (SPEC-169 D2) |
splitInsideAttribution | the nested model on quote, with position: last |
| precedence in code: author attribute, then the paragraph after, then the inside one | fills (SPEC-182 D2): a paragraph supplies author and source only when the author did not write them |
renderAttribution | the attribution primitive, below |
new Tag('blockquote', …) for the bare form, plus withoutQuoteRole | group as="blockquote" around quote.body, falling back to body; the authored blockquote is never rendered as its own node |
data-quote and aria-hidden set in code | rootAttributes as expressions |
the excerpt's <aside> root around a <figure> (SPEC-185 D1) | the root tag: as an expression, and two template variants selected by excerpt (SPEC-168 D9); the excerpt's inner figure is group as="figure" |
align defaulted by fieldMetas | the attribute's own default; the engine generates the modifier |
block: pullquote, the axis defaults, sections, provides, editHints | definition keys. The definition is pullquote.md, so its data-rune becomes pullquote (today pull-quote, kept as an alias) and its classes stay rf-pullquote (SPEC-196 D10) |
the deprecated variant | a SPEC-189 migration row, not part of the definition |
The attribution primitive. SPEC-185 D6 makes attribution "one shared part" of every quotation role. Today that part is renderAttribution (packages/runes/src/lib/attribution.ts): <figcaption> holding <cite> and a source <span>, used by pull-quote, the core blockquote node, epigraphs and, through pull-quote, testimonial. A template cannot build <figcaption> or <cite> (D11), so it becomes a primitive:
- template-only, like
{% group %}(SPEC-156 D2): authors keep writing**Name** — Source, the content model reads it, and templates place{% attribution name=… source=… /%}; - rendered from values, not nodes. A placed rune is a name-resolution boundary for structured data (SPEC-145 D19), so the values reach the published graph through the outer rune's attributes and field bag (
fills), and the primitive only displays them; - its element follows its placement:
<figcaption>inside a<figure>, a neutral element elsewhere, so a template cannot produce invalid HTML by placing it in, say, a card; - one implementation for every role, styled once under
"bem"(rf-attribution,rf-attribution__name,rf-attribution__source); it renders nothing when there is no name.
What the example needs that does not exist yet, each settled in pull-quote's work item:
group as="blockquote"andgroup as="figure": the first two values admitted to D11's closedas=.- The
attributionprimitive. - A slot whose fallback content is another slot (
{% slot name="quote.body" %}{% slot name="body" /%}{% /slot %}). rootAttributesand the roottag:in definitions, as expressions (SPEC-195: input half, so meaningful).tag:takes only element names a definition could write literally; a theme's replacement template cannot change it.- Which filler wins when two fields fill one attribute. Today the paragraph after the quote beats the inside one;
fillsmust say so by model order or explicitly. - A behaviour difference to accept or fix: today an explicit
authorignores the paragraph entirely; with per-attributefills, an explicitauthorcould still takesourcefrom it. - The excerpt keeps its
<aside>(decided 2026-11-09, revising a decision of the same day to drop it). An earlier draft dropped the<aside>because a template branch would place the quote slot twice, which SPEC-145 D30 rejects. Template variants selected byexcerpt(SPEC-168 D9) place each slot once per variant, so SPEC-185 D1's structure stays:<aside aria-hidden="true">holding the figure. The output is unchanged.
The rule this sets. When a template needs structure it cannot express, the answer is a small primitive with a role in the shared design language, placed by every rune that needs it, never an element name in the template. "Candidate primitives", below, records the cases measured so far.
Containment primitives are admitted with one user. A primitive whose job is to contain something else (an <iframe> for embedded content, a sandboxed document) is admitted even with a single user, against the usual two-adopter bar. Its security-relevant attributes (allow, sandbox, loading, referrerpolicy) must be fixed in code, never written by a template or a theme's replacement template. frame, for embed (D14), is the first.
D14: the first migrations, worked
Decided 2026-11-09. The first native runes to move each prove one new part of the mechanism, and none depends on a draft spec the way hint does (ADR-042 makes it wait for keyed strings and SPEC-163's sentiment, which would break SPEC-181's fourth gate):
pull-quote(D13): the definition format for a primitive,group as=,fills, template variants selected by an attribute, and root attributes as expressions. It keeps its classes, so little CSS moves.codegroup, below:computeswritten with SPEC-195's functions, template variants selected by a computed value, and placing a primitive with behaviour.embed, below:prepare, beside expressioncomputes, and the first containment primitive.
The pipeline runes (pagination, breadcrumb, toc) follow the loader split (D12).
codegroup replaces about 140 lines of packages/runes/src/tags/codegroup.ts and its engine entry:
--- tag: section role: primitive placedBy: [preview] description: Code blocks shown in a window, as tabs when there are several attributes: title: { type: string, description: "Filename in the bar; an empty value shows the bar alone" } labels: { type: string, description: "Comma-separated tab labels, overriding the derived ones" } overflow: { type: string, matches: [scroll, wrap, hide], default: scroll } content: type: sequence fields: panels: match: fence greedy: true emitAttributes: { language: $node.language, source: $node.source, lines: $node.lines, label: $node.label } templates: { by: layout } computes: single: and(equals(count($slots.panels), 1), not($attrs.labels)) layout: value: if($computed.single, "single", "tabs") values: [single, tabs] panels.file: if($node.lines, concat(basename($node.source), ":", $node.lines), basename($node.source)) panels.label: first(item(split($attrs.labels), $index), $node.label, $each.file, language(first($node.language, "shell"))) metaFields: title: { metaType: code, condition: title, renderWhenEmpty: true } blocks: topbar: { fields: [title], layout: bar } rootAttributes: data-code-host: "true" defaults: { density: compact, elevation: flat } editHints: { panels: code } --- {% template layout="single" %} {% metablock name="topbar" /%} {% slot name="panels" each %}{% slot /%}{% /slot %} {% /template %} {% template layout="tabs" %} {% metablock name="topbar" /%} {% tabs %} {% slot name="panels" each %} {% tab name=$each.label %}{% slot /%}{% /tab %} {% /slot %} {% /tabs %} {% /template %}
- It is a primitive, not a domain rune (SPEC-196 D8's test).
previewshows three source views built in code today, and placescodegroupinstead;sandboxandfile-refshow source too. And a code window looks the same wherever it appears. So it keeps its look and its classes (rf-codegroup; itsdata-runebecomescodegroup, SPEC-196 D10), and its stylesheet stays Lumina's. - The single panel is
codegroup's own rule, nottab-group's: a lone fence without custom labels is shown without a tab bar. The choice is a computed template selector (SPEC-168 D9, as amended), so each variant placespanelsonce, and a theme can replace either variant without being able to change which one a code group gets. - Its tabs are
tab-group's, the primitive that already owns the tab behaviour. The engine marks thattab-groupwithdata-in="codegroup"(SPEC-196 D5), which needstab-group's definition to listcodegroupamong the parents it records. The theme styles the tabs-in-the-bar look on[data-rune="tabs"][data-in="codegroup"]: two primitives meeting, which is the theme's to style. - Its labels come from SPEC-195's functions: the fallback chain that is four helpers in code today, and
language(), shared withcompare, which today shows "js" wherecodegroupshows "JavaScript". The deepest expression nests three calls. - Triage, as a primitive (SPEC-196 D11): the question is which rules are the window's own look, not drop or promote.
overflowis the one rule that may move, to code blocks in general. - Needs first: SPEC-195's
first,item,split,basename,language,concat,count,if,and,equals,not;$nodeinemitAttributes(D1);$slotsand a sibling per-item value ($each.file) incomputes' scope; and the computed selector in SPEC-168 D9.
embed is the prepare acceptance case:
--- tag: figure description: An embedded video, audio or page, from a URL attributes: url: { type: string, required: true, description: "The page or media to embed" } aspect: { type: string, matches: ["16:9", "4:3", "1:1", auto], default: "16:9" } title: { type: string, description: "Accessible title for the embedded frame" } content: type: sequence fields: fallback: { match: any, greedy: true, optional: true } prepare: embed computes: provider: { type: string } embedUrl: { type: string } frameTitle: first($attrs.title, "Embedded content") schema: type: VideoObject properties: { title: name, url: contentUrl, embedUrl: embedUrl } defaults: { density: compact, elevation: flat } editHints: { fallback: none } --- {% frame src=$computed.embedUrl title=$computed.frameTitle ratio=$attrs.aspect /%} {% slot name="fallback" /%}
// registered by core as Plugin.prepare.embed export const prepareEmbed: Prepare = ({ attrs }) => { const { provider, embedUrl } = detectProvider(attrs.url); // today's provider table, unchanged return { provider, embedUrl }; };
prepareand expressions side by side:providerandembedUrlare declarations the stage fills;frameTitleis an expression. SPEC-195 D8's mixed case.- The schema row reads a computed value (
embedUrl), and the publishedVideoObjectis unchanged. - The inline
padding-bottomstyle goes:frameowns the aspect ratio. - A dead attribute:
typeis declared ("override auto-detected embed type") and read by nothing. The definition drops it, through a SPEC-189 row. frameis the first containment primitive (D13): an<iframe>whoseallowandloadingare fixed in code.embeditself is a domain rune: it arrangesframeand a fallback slot, so under SPEC-196 D8 it loses its classes, and its 8 selectors are triaged intoframe, which as a primitive keeps classes.
D15: a preprocess rune is a macro definition, with a preprocess stage and no template
Decided 2026-11-10. include, snippet and data resolve before the transform (SPEC-141). The measurement below counts them among the native runes, but nothing above says what form they take, and D2 rules out the obvious one: a preprocessor receives its own AST node and returns AST, which is exactly what prepare may not do.
They are macros, not runes with output. Each replaces itself with authored Markdoc: include with a partial's AST, data with its row template cloned per row (SPEC-127), snippet with a fence. Other runes' definitions then transform that content. By the time a theme sees the page, include and data have left no trace, and a snippet is a code block that the code-block primitive arranges (D13). There is nothing for a template to arrange, so ADR-048's "input and template" has no template half to apply to.
--- tag: include attributes: file: { type: string, required: true } variables: { type: object } preprocess: include ---
- Input in frontmatter, as for every rune. Attributes and their descriptions are declared the same way, so the rune reference, the block editor and
refrakt editread a macro like any other definition. A content model is declared only where the rune has one (data's body is the row template, read as a whole). preprocessnames a stage a package registers (D3), with SPEC-141's contract unchanged:(node, page, ctx) → Node | Node[] | void, one walk in tree order that descends into replacements, the ancestor chain in the context, andinclude's own cycle stack. It is a separate key fromprepare, because its contract is the opposite of D2's: it may only return AST, and it never receives resolved fields.- A macro definition has no body, no
computesand norole. No template, because there is nothing to arrange. Nocomputes, because nothing reads$computedafter a macro is gone. Norole, because no element of it reaches the output to be classed (SPEC-196 D8). A definition that declarespreprocesstogether with any of the three reportsmacro-with-template,macro-with-computesormacro-with-role. It also cannot declareprepare. - The throwing transform stays, generated (SPEC-141 D7). A macro that reaches the transform unresolved fails with an error that names the stage and the likely cause (a
partialinstead of aninclude), asinclude.tsanddata.tsdo today by hand. The loader generates it from the declaration. - The ban in SPEC-145 D4 stands. A template renders at transform, after preprocess, so it may not place a macro (
preprocessor-tag). A repeated block that needs one is an{% include %}. emitTagis unaffected. It stays a declared content-model field, and may still execute at preprocess (SPEC-141 D8). It is not a macro: the rune it belongs to has output.- The plugin-level hook stays (
PluginPipelineHooks.preprocess, SPEC-141 D2) for concerns that span the whole page tree. Nothing first-party uses it.
What a preprocess stage sees from D12. After the loader split, preprocess runs in the second loop, when the page index exists. A stage keeps what its context carries today: the page's own variables, frontmatter included. It does not gain the index-derived members of $page (parent, ancestors, children, prev, next) or $site. No macro needs them, and a preprocessor that read them would paste content that depends on other pages, which nothing in the dev server or a future incremental build (ADR-025) tracks. A macro that genuinely needs other pages reads the registry instead, and that rune is a deferred definition, not a macro (D12.4).
Paste-time bindings and functions. data binds $row and include binds variables by substitution at preprocess; SPEC-195's functions are evaluated at transform. So a call in a row template, first($row.title, "Untitled"), sees the literal its argument was replaced with. That is the intended order (SPEC-195 D8). It does not hold today: both substitutions replace a variable only when it is a whole attribute value, not inside a function's parameters, so the call reads undefined and nothing reports it. That is BUG-054, and it is fixed before any macro moves to a definition.
Order. The three macros move after the composition migration and the first native definitions (D10), in the work item that gives the loader definition-declared preprocess. They change no output: the walk, the stages and the results are SPEC-141's.
Candidate primitives, measured
Measured 2026-11-09: every shared render helper and every meaningful element choice in rune transforms, resolvers and the engine, checked against what a template can already place. The render helpers, nodes.ts, drawer and its resolvers, collection-helpers.ts, figure, gallery, chart, diagram, cast and tab were read in full; the plan pipeline, comparison, form, nav, progress and the engine's value rendering were skimmed.
New primitives. Each is template-only, like attribution, and renders from values:
| Primitive | Renders | Inputs | Users today | Why nothing existing covers it |
|---|---|---|---|---|
attribution | <figcaption><cite>, by placement | name, source | pull-quote, the blockquote node, epigraphs, testimonial | D13 |
code-block | <pre><code> with data-language | a source string, language; optionally line numbers, highlights, line range | the fence node (nodes.ts:143), sandbox (:198), diagram (:41), preview's three source views (:163, :184, :199), the design plugin's themed-source postTransform, file-ref's drawer body (file-ref-resolve.ts:288) | {% code %} is inline only, and a template can write a literal fence but cannot fill one from a value. Raw source is D2's named exception, so prepare can produce the string and only a primitive can show it |
caption | <figcaption> inside a figure, <caption> inside a table, a neutral element elsewhere | a text value or an inline slot | figure (:70), gallery (:49, :58), diagram's title (:34), chart (:71), aggregate's chart title (aggregate-resolve.ts:119) | D8 has a template arrange a drawing's title around it, but it cannot write a figcaption, and placing figure inside a root that is already a figure would nest them |
image | <img src alt> from attribute values, resolving the icon: and placeholder: schemes | src, alt | cast's portrait from image= (cast.ts:39), tab's image= (tabs.ts:18), both through the image node (nodes.ts:378) | Markdoc's image syntax takes no variable src. Content images placed by a slot are fine; only an image from an attribute is stuck. Two small users: it waits for a third (decided 2026-11-09); until then cast and tab keep their image in code |
attribution, code-block and caption share one rule: the element follows the placement, so a template cannot produce invalid HTML by placing them somewhere unexpected.
Not primitives:
- A table from records (
collection-resolve.ts:161–195, two paths, andaggregate-resolve.ts:99):data-emit.tsalready turns records into Markdoc table AST, so D12's resolvers can emit through that path and the template places the result. - An empty state (
collection,relationships,aggregate):{% if %}and a{% group name="empty" %}. - A heading whose level comes from the outline: only
drawerneeds it (DRAWER_TITLE_AUTO_MARKER,drawer.ts:85), so it stays insidedrawer.
as= values. D11 admits a value only with its first real case:
| Value | Case | Status |
|---|---|---|
blockquote | pull-quote's bare form (D13) | the first value |
footer | bento-cell's footer (bento.ts:134) | only if the part is not a section; section's footer zone is the better home |
header | the nine preamble: { tag: 'header' } layouts | already mapped to section's header zone (D11); a fallback only |
figure | pull-quote's excerpt, the figure inside its <aside> (D13) | admitted with pull-quote; gallery's items (gallery.ts:51) could use it when gallery becomes a definition |
No rune builds aside, small, address, mark or abbr inside its output. aside appears only as a root (sidenote, annotate, the excerpt), which a definition's tag: covers.
Already covered, so no gap:
- root elements (
article,li,nav,figure,aside,details,form): a definition'stag:; - links from values:
{% link href=… %}(nodes.ts:248) and thelinkvalue element; - dates:
timeis the temporal value element; - lists:
ladder(SPEC-156); - definition lists:
deflist,fieldandmetablock; - inline code:
{% code %}; icons:{% icon %}andmetaFieldsicons; ratings: themarksvalue element; - headings from values: a Markdown heading in the template with a field or variable inside it.
Duplications the move removes. Each is a resolver or helper rebuilding a rune's output by hand, which D12's "resolvers return data" ends:
- Drawer markup is built three times:
drawer.ts:85–110,xref-preview-resolve.ts:181–240andfile-ref-resolve.ts:290–328. The two resolvers hard-coderf-drawer__*classes anddata-rune="drawer", and always useh3. Under D12 they place{% drawer %}, andcode-blockreplacesfile-ref's hand-built body. renderGroupAccordioncopiesaccordion's output (collection-helpers.ts:323), withrf-accordion-itemclasses written by hand, for groupedcollectionandrelationships. Their templates placeaccordioninstead.- Entity items are built twice or three times:
collection(collection-resolve.ts:97),relationships(relationships-resolve.ts:131) andaggregate's group headings. - The same meaning gets different elements: only the fence wraps code in a
rf-codeblockdiv, anddiagramomitsdata-language;diagram's title is a<figcaption>wherechartandaggregateuse a table<caption>.code-blockandcaptionmake each one decision. - Hand-built
<time>never carriesdatetime(timeline,changelog,itinerary,plan-history); only the engine'smetaFieldspath adds it (engine.ts:1311). Moving them to the temporal value element fixes that, anditinerary's clock times ("9:00 AM") mean the temporal kind must handle a time of day (SPEC-166). plan-progressmay not place theprogressrune: skimmed, to confirm in its work item.
The native runes that remain, measured
Measured on 2026-11-07 from the catalogs (packages/runes/src/index.ts and each plugins/*/src/index.ts), every rune's source, and the conversion plans in plan/.
| Runes | |
|---|---|
| All runes (core 62, plugins 65) | 127 |
Already compositions (hero, cta, testimonial) | 3 |
| Planned compositions | 58 |
| Remaining native | 66 (core 58, plugins 8) |
The plan behind the 58 is mostly draft. Only steps, feature, pricing and card, with their child runes, are planned in accepted or implemented specs. The rest come from the plugin audits (SPEC-147 to SPEC-157), SPEC-162, SPEC-165, SPEC-167 and SPEC-171, all drafts. Fewer conversions would move runes into the table below.
What the 66 need. Each rune is counted once, in the first group that applies:
| Group | Count | Runes |
|---|---|---|
Needs prepare | 6 | embed (provider detection, URL rewrite), diff (line diff), form (field-type inference), sandbox and preview (raw source, D2's exception), design-context (collects tokens from child runes) |
| Cross-page pipeline or preprocess | 18 | nav, toc, breadcrumb, pagination, collection, relationships, aggregate, xref, expand, blog, snippet, include, data, region, layout, drawer, file-ref, plan-history |
| Drawing or behaviour, nothing to compute | 11 | codegroup, tabs, gallery, accordion, datatable, chart, diagram, reveal, juxtapose, audio, map |
| SPEC-195 functions only | 8 | grid, details, compare, conversation, progress, actions, figure, map-pin |
| Purely declarative | 23 | among them hint, badge, bar, code, section, deflist, pullquote, tint, textblock, mediatext, storyboard; five need a D7 extension |
This table is a snapshot of 2026-11-07. Later decisions reclassify two rows: codegroup needs SPEC-195's functions (D14), and pullquote needs if() for its root attributes (D13). Neither changes the count of runes that need prepare.
60 of the 66 need no prepare stage. The six that do hold genuinely rune-specific logic, which is what D2 intends the stage for.
Confidence. Each rune's source was read. For nav, diff, form, sandbox, map, section, snippet, include, data and icon the reading was a skim; their rows are the first to recheck in each rune's work item.
Two gaps it found:
- The pipeline group builds output in code. These runes emit a placeholder, and a postProcess resolver later builds their tree. For example,
resolveCollections, and the breadcrumb resolver'snav,olandli(packages/runes/src/config.ts). D2 assumes a pipeline hook only supplies values, and D11 binds templates andprepare, not resolvers. So 18 runes would still build markup no theme can arrange. Answered by D12: resolvers return data, most of these runes read the page index at transform, and only registry reads wait. previewandsandboxread raw source. This is now D2's named exception, and D6's row forpreviewis corrected.
Acceptance criteria
- A definition may declare
prepareandcomputes; a definition without them loads as a composition, unchanged preparereceives resolved fields and attributes, never AST, and its output is checked againstcomputesin development and tests (prepare-undeclared-value,prepare-missing-value)- Computed values are readable in the template as
$computed.<name>and, per item, through$each, and may feedmetaFieldsand the schema row - A plugin registers stages in
Plugin.prepare; a definition naming an unregistered stage reportsprepare-unknown; a site definition cannot contain code codegroupis a definition with expressioncomputesand a template, and nopreparestage; its contract and SEO baseline are unchanged, or every difference is explainedembedis a definition with apreparestage and a template; its contract and SEO baseline are unchanged, or every difference is explainedpreviewandsandboxdeclare their need for raw source, and no other rune's context carries it- A theme
templates/codegroup.mdreplaces its arrangement and passes SPEC-177's checks - A rune with a template that also declares a D5 assembly field reports
engine-config-assembly-with-template refrakt referencereports a full grammar, not a description, for every rune moved offcustom- The template language has no tag that emits an element by name or takes free attributes, and a test pins it (D11)
- Every element-naming config entry of a moved rune maps to a D11 row, or is recorded as a vocabulary gap
- The theme-authoring and plugin-authoring docs describe one arrangement convention for every rune
- The loader parses every page before transforming any, and
$page(withparent,ancestors,children,prev,next,headings) and$siteare available at transform, including in layouts (D12) - A rune whose
data:reads the registry is deferred and expanded after the pipeline; no other rune is (D12.4) pagination,breadcrumbandtocare definitions read from$pageat transform, each with one template for its written and automatic forms; contracts and SEO baseline are unchanged, or every difference is explainedcollection's built-in rendering is its default template, and an author's body replaces itsitemfragment with no change to existing pages- The
__slug:placeholders, the post-pipeline region pass and the breadcrumb SEO re-harvest are removed - A
{% fields of=… names=… /%}primitive renders an entity's named fields through the shared vocabulary, andcollection's default templates use it - The block editor treats values under
computesas read-only without any new key include,snippetanddataare definitions that declare their attributes in frontmatter and name a registeredpreprocessstage, with no body,computesorrole; their output, contracts and SEO baseline are unchanged (D15)- A definition that declares
preprocesswith a template,computes,roleorpreparereports an error naming the conflict (D15) - A macro that reaches the transform unresolved throws an error generated from its declaration, naming the stage (D15)
- A preprocess stage's context carries the page's own variables and not
$siteor the index-derived members of$page(D15) - Definitions accept
role(primitive,drawing, domain by default) andplacedBy; a definition's name is its tag name, and itsdata-runefollows it (D1) pullquoteis a definition with nopreparestage, its output unchanged apart fromdata-rune(D13); its excerpt keeps the<aside>through template variants- The
attributionandframeprimitives exist, are template-only, and render from values;framefixes itsallowandloadingin code (D13) group as=accepts only admitted values (blockquote,figure), and an unknown value is reported (D11)emitAttributescan read a matched node's own attributes through$node.<name>(D1)- Each D7 content-model extension lands with its first rune, and
CustomModelis removed once no first-party rune uses it (D7, D9) - Parts a behaviour depends on are primitives or opaque slots as D8 lists, and a replacement template cannot change a custom-element rune's root element
- The removals in D9 land in the release after their last first-party user goes, through SPEC-189
Open questions
None remain at the top level. What is still open sits where it applies:
- within D12: two-level iteration (specified, not built) and the
fragmentoverride point, which depends on SPEC-168 D8.
Future: reusing computation
Not decided here. Recorded because D3 closes one route to reuse, and the code shows the pressure is real.
What repeats today, measured on 2026-11-07:
| Computation | Where | How it differs |
|---|---|---|
| A label per item: an author's comma list by index, else a fallback chain | codegroup (labels → fence label → source basename → prettified language), compare (labels → raw data-language → "Panel N"), juxtapose (labels → none), conversation (speakers, cycled, after the bold speaker) | the two code-panel runes disagree: compare neither prettifies the language nor reads the source |
| Parsing and formatting durations | parseIsoDuration and formatDurationLocale in packages/transform/src/engine.ts; parseDuration and formatDuration in plugins/media/src/duration.ts, used by track, audio and playlist | two implementations of one value kind |
| Adding values up | budget's subtotal; recipe's totalTime (SPEC-145's open {% let %} question) | no shared operation |
| Domain-specific rules | comparison's row alignment, form's field-type inference, codegroup's language-name table | none: genuinely per rune |
Three kinds of reuse, none of which needs a shared stage:
Value kinds belong to the value primitives. Parsing and formatting a duration, an amount, a number or a coordinate is SPEC-166's contract, and the format is the theme's
formats(ADR-043 decision 4). The two duration implementations collapse into one there, and nopreparestage parses a duration.Small, generic computations become registered functions, written in
computeswith Markdoc's own call syntax, the same functions templates and pages already call:computes: panels.label: first(item($attrs.labels, $index), $node.label, basename($node.source), language($node.language)) totalTime: sum($attrs.prepTime, $attrs.cookTime)
A function needs no code in the definition, so site-authored definitions can use them too. SPEC-195 specifies the function set, its typed signatures, the
matches()bridge to the SPEC-070 filter grammar, and the rule that the place decides the result: undercomputesit is a field, in a template it is display text. That rule is what keeps these values in the input half, where a theme's replacement template cannot change or lose them and a schema row may read them (ADR-045 decision 4).Revised 2026-11-07. An earlier draft of this section proposed YAML named patterns (
pattern: item-label). They were dropped: they would have been a third syntax beside Markdoc's function calls and the SPEC-070 grammar, for the same operations.Shared domain logic becomes a primitive. If two runes really need the same rule (say
compareandcodegroupagree on what a code panel's label is), the ADR-044 shape applies: a primitive owns the code (acode-panelthat computes its own label), and both runes place it.
What would remain for prepare is the last row of the table: rules that belong to one rune. That is the case where privacy (D3) costs nothing.
References
- ADR-048: the decision this spec implements.
- ADR-043, ADR-044, ADR-045: the theme boundary this completes.
- ADR-029, ADR-031: proposed config-override routes that templates replace.
- SPEC-145: composed runes and the template language.
- SPEC-161 D3: a primitive may own code, a composition may not.
- SPEC-177: theme and site templates.
- SPEC-186, SPEC-182: the content-model features D7 builds on.
- SPEC-195: the value vocabulary
computesis written in. - SPEC-141: the per-rune preprocess hook and the tree-order walk D15 keeps.
- BUG-054: paste-time bindings miss variables inside function calls (D15).