Content-to-text value functions:
Relationships
Related 8
History 1
c37a447Created (draft)
Summary
preview shows a demo three ways: its source, the demo rendered, and the demo's rune output as HTML. Today it does all three in its own transform, with two privileges no other rune has: it reads the page's raw text, and it runs Markdoc's transform inside its own. That is why SPEC-194 lists it among the runes that need a prepare stage and treats it as one opaque slot (D8).
This spec takes the three jobs apart into general pieces:
- one rule: a template function may turn content into text, never text into content (D1);
source(slot): the text the author wrote for a slot (D2);output(slot): the slot's rune output before the engine runs, as HTML (D3). It is a second stage and may be dropped without affecting the rest;- a block code primitive that takes its content as a value (D4);
previewbecomes a composition, with nopreparestage and no privileges (D5, D6).
The motivation is fewer special cases, not new capability. The conversion is worth doing even if output is dropped and preview loses its HTML panel.
Prerequisites
| Needs | From | State on 2026-11-11 |
|---|---|---|
The value vocabulary, $slots, text() | SPEC-195 | accepted |
| The raw-source exception this removes | SPEC-194 D2, D8 | accepted |
| Pasted content remembers its file | SPEC-197 D5 | draft |
| Templates and fragments | SPEC-168 | draft |
What exists, measured
Measured 2026-11-11, plugins/design/src/tags/preview.ts.
| Job | How preview does it today | Weakness |
|---|---|---|
| Source panel | a fence written inside it is the source (sourceFenceIndex, :109); otherwise it cuts the page's raw text (config.variables.__source) between its own opening and closing lines, and dedents it (:183) | correct only when the demo is written inline on the page: inside a composition or after include, its own lines point into another file |
| Rendered demo | runs Markdoc.transform on its remaining children inside its own transform (:204) | a nested transform, which SPEC-194 D2 forbids to code in general |
| HTML panel | pretty-prints that transform's result (renderRuneHtml, :41, :210) | pre-engine output; the behaviour's own comment says so (packages/behaviors/src/behaviors/preview.ts:55) |
| Tabs, light/dark, viewport widths | the preview behaviour, from data-name parts and the theme and responsive attributes | none; already general |
Placed slot content keeps its source position: composition's cloneNode copies lines and location onto every node it places (packages/runes/src/lib/composition.ts:1372).
No block code primitive takes its content as a value. code is inline only (packages/runes/src/tags/code.ts), and snippet reads files.
Decisions
D1: template functions turn content into text, never text into content
- Allowed: functions whose argument is content and whose result is a string a template can only display:
text()(SPEC-195),source(),output(). - Not allowed: a function that parses or transforms a string into content (
parse(),transform(),render()). Once a template can do that:contracts, SPEC-177's checks and the editor can no longer see a template's structure without content;- a theme or plugin template, which ships in a third-party package, could turn an attribute's string into runes;
- SPEC-194 D2's rule that code computes values and never builds trees no longer holds.
- Parsing, transforming and rendering are a library API, for tools rather than templates.
parse(@refrakt-md/runes) andrenderToHtml(@refrakt-md/transform) exist already; they are documented as the public way for tools to do it.
D2: source(slot) is the text the author wrote
- Returns the source of the slot's nodes, from the first node's first line to the last node's last line, dedented, with blank lines at either end trimmed.
- Reads each node's own position, not the template's. Inline content reads the page's text; content placed by a composition keeps its lines (
cloneNode); content pasted byincludereads the file named in itslocation(SPEC-197 D5). - An empty slot returns the empty string.
- Any composition may call it. It replaces SPEC-194 D2's named exception: no definition declares
input: [source], and no rune's context carries the page's raw text.
D3: output(slot) is the slot's rune output before the engine runs
A second stage. The rest of this spec does not depend on it, and it may be dropped.
- Returns the slot's output after the composition's own transform and before the identity transform, as indented HTML. It is the rune's theme-independent contract:
data-rune,data-field,data-name. - It is a late value. A template's values are worked out while the template is expanded, before
Markdoc.transformruns (composition.ts:1255), so the slot has no output yet:- expansion leaves a placeholder where the value is used;
- after the composition's transform, the placeholder is filled from the nodes the slot actually produced, found by their
data-slotmarks; - the slot is transformed once. Transforming it a second time for the value would run registration, side tables, heading ids and counters twice.
{% metablock %}is the precedent: a marker filled after the transform (composition.ts:258).
- Composition's bookkeeping is removed from the string:
data-owner,data-slot. - The pretty-printer moves to
@refrakt-md/transform, frompreview'srenderRuneHtml. - A late value may only be displayed. It cannot appear in
{% if %}, in a variant selector, incomputes, or anywhere a value decides structure; doing so reportslate-value-in-decision. It is accepted in a display position, D4'scontent. - For a rune drawn by a component (ADR-049), the output is its rune node, printed.
Accurate final HTML, after the engine and the renderer, is out of scope. If wanted later, it is a behaviour that captures a stage's rendered HTML in the browser, or a build-time step in adapters that see the final HTML string.
D4: a block code primitive takes its content as a value
{% codeblock language="markdoc" content=source($slots.demo) /%}
- A primitive (
role: primitive), template-only, asattributionandframeare (SPEC-194 D13). - Renders exactly as a fence would, through the same highlighting, so it needs no CSS of its own.
contentaccepts a string value, including a late one (D3).languageis a string.- It exists because SPEC-194 D11 lets elements come only from primitives, and nothing else can turn a value into a code block.
D5: preview becomes a composition in the design plugin
{% template %} {% group name="stage" %} {% slot name="demo" /%} {% /group %} {% codeblock name="source" language="markdoc" content=first(text($slots.fence), source($slots.demo)) /%} {% codeblock name="html-source" language="html" content=output($slots.demo) /%} {% /template %}
- Content model: an optional fence (an author's explicit source, as today) and the demo.
- Attributes stay:
title,theme,responsive,source. The behaviour reads them from the root as today. - The behaviour finds the code blocks by
data-name(source,html-source), as it does today. A primitive placement takingnameis checked against SPEC-194 D11 when the primitive is built. - Without D3, the
html-sourceblock is left out and the HTML panel goes away. That is acceptable. - SPEC-194 changes:
previewleaves D6's list of runes that needprepare, D8's "the whole arrangement" row is removed, and D2's exception names onlysandbox. sandboxstays native. It puts raw HTML into an iframe; that is not a demo of content.
D6: refrakt's own site shows examples through a site composition
site/runes/demo.md, not shipped in any package:
{% demo %} Use different types to convey different levels of importance. --- {% include file="core:hint.md#all-types" /%} {% /demo %}
- Content model: delimited by
---: prose above, the demo below. A delimiter is needed because a demo can itself be paragraphs (badgeis inline). - Its template places the prose, then a
previewaround the demo slot. includeruns before the transform (SPEC-141), so the composition sees the pasted example as if it had been written inline, andsource()reads it from the definition file.- It is named
demo, notexample, so it is not confused with SPEC-197's definition block, and notshowcase, which is an existing core rune.
Implementation order
source()and thecodeblockprimitive.previewas a composition without the HTML panel, through SPEC-181's staging; then the SPEC-194 amendments.- The site's
democomposition, once SPEC-197'sfile#nameaddressing lands. output(), if a second user appears or the HTML panel is missed.
Acceptance criteria
source(slot)returns a slot's authored text, correct for inline content, content placed by a composition and content pasted byinclude- No rune's context carries the page's raw text; SPEC-194 D2's exception names only
sandbox - No template function parses or transforms a string into content, and a test pins the function registry to that rule (D1)
- The
codeblockprimitive renders a string value as a fence would, with highlighting previewis a definition with nopreparestage, its tabs, theme and viewport behaviour unchanged- Every
previewon the site renders, and every difference from today's output is listed and accepted site/runes/demo.mdshows an example included by name, with its source panel correct- If D3 lands:
output(slot)is filled from the slot's single transform, without composition marks, and a late value in a deciding position reportslate-value-in-decision
Open questions
- Does
previewkeep the explicit fence? It lets an author show source that differs from the demo (simplified, or annotated). Keeping it costs one optional field and onefirst(). - Where
output()'s placeholder lives. A marker node likemetablock's, or a value type in SPEC-195's vocabulary. The second is more general; the first exists. source()and SPEC-170 indentation. A demo written indented inside a block tag is dedented to its least-indented line. Check that this matches what authors expect inside nested tags.
References
- SPEC-194: D2's raw-source exception, D6, D8, D11, D13
- SPEC-195: the value vocabulary and
text() - SPEC-197: examples,
file#nameaddressing, pasted content's origin - SPEC-141: preprocess, which runs
includebefore the transform - SPEC-181: staging a composition before it goes live
- ADR-049: components and their output