@refrakt-md/runes 0.38.0 → 0.40.0

package/dist/lib/composition.js

@@ -0,0 +1,1120 @@
+/**
+ * Composed runes — SPEC-145.
+ *
+ * A composed rune is defined by a Markdoc template that places its authored
+ * content into slots of existing primitive runes. It has no block and ships no
+ * CSS (D2); it does own its identity, its field bag and, when it declares them,
+ * its schema row and registration (D3).
+ *
+ * A definition is two halves joined by slot names:
+ *
+ * ```md
+ * ---
+ * tag: aside
+ * attributes:
+ *   from: { type: string, required: true }
+ * content:
+ *   type: sequence
+ *   fields:
+ *     body: { match: any, optional: true, greedy: true }
+ * ---
+ *
+ * {% hint type="note" %}
+ * **{% $attrs.from %}**
+ *
+ * {% slot name="body" /%}
+ * {% /hint %}
+ * ```
+ *
+ * The frontmatter is the input declaration — SPEC-143's and SPEC-144's
+ * vocabulary — and the body is the output template. The rune's name is not in
+ * the frontmatter: it is the file's name (SPEC-153 D9), passed in here.
+ *
+ * ## When the template renders (D4)
+ *
+ * Where a `transform` would have: after the content model has resolved, at the
+ * one call site in `createContentModelSchema`. `compileComposition` checks and
+ * parses the template once, at construction, and returns an ordinary transform
+ * closure. Per instance, the closure substitutes the resolved fields and the
+ * attributes into a copy of the template AST and calls `Markdoc.transform` on it,
+ * so every rune the template places runs its own transform unchanged.
+ *
+ * ## The vocabulary, and nothing more
+ *
+ * - `{% slot name="x" /%}` places field `x`; with a body, the body is the
+ *   fallback for an empty field.
+ * - `{% slot name="xs" each %}…{% /slot %}` describes **one** item of a list
+ *   field; inside it, a bare `{% slot /%}` is that item's content and `$each`
+ *   is bound to its `emitAttributes` (D26).
+ * - `$attrs.<name>` is a declared attribute, in content or attribute position.
+ * - `{% if %}` / `{% else /%}` are Markdoc's own.
+ *
+ * ## Markers (D10a, D10c)
+ *
+ * Every node a slot places carries `data-owner` (the composed rune) and
+ * `data-slot` (the slot's name); every node the template places at its top level
+ * carries `data-owner`. `data-owner` is bookkeeping and is stripped once the
+ * composed rune's own transform finishes (`releaseOwnedNodes`); `data-slot` is
+ * the published name of the part. A slot adds no element.
+ */
+import Markdoc from '@markdoc/markdoc';
+import yaml from 'yaml';
+import { METABLOCK_ATTR, METABLOCK_OWNER_ATTR } from '@refrakt-md/transform';
+import { createComponentRenderable } from './component.js';
+import { resolveEmitReference, sectionLookup } from './resolver.js';
+import { OWNER_ATTR, SLOT_ATTR, findAllByName } from './schema-table.js';
+import { SchemaSideTable } from './schema-side-table.js';
+import { declareSlotMarkers, declareSlotMarkersOnNodes } from './slot-markers.js';
+import { registersSources } from './registers.js';
+const { Ast, Tag: MarkdocTag } = Markdoc;
+/** Compositions by schema — the same pattern as `schemaTables`: tooling has only
+ *  the schema to read from. */
+export const schemaCompositions = new SchemaSideTable();
+/** The composition a schema renders, if it is one. */
+export function compositionFor(schema) {
+    return schema && typeof schema === 'object'
+        ? schemaCompositions.get(schema)
+        : undefined;
+}
+/** Tags a template may not contain: they resolve at preprocess, a stage a
+ *  template comes after (D4). `include` is the route for a repeated block that
+ *  needs one. */
+const PREPROCESSOR_TAGS = new Set(['data', 'snippet', 'include']);
+/** Markdoc's own tags, which are template vocabulary rather than placed runes. */
+const MARKDOC_TAGS = new Set(['if', 'else']);
+/**
+ * The tag a template writes to place one of the rune's declared meta blocks
+ * (D7). It is template vocabulary, like `{% slot %}`: it is never registered as
+ * a page tag, so on a page it is an undefined tag, and authored slot content
+ * cannot reach the marker it renders to.
+ */
+const METABLOCK_TAG = 'metablock';
+/**
+ * The key the expanded marker is transformed under. `:` cannot appear in a
+ * Markdoc tag name, so no authored `{% … %}` — in a slot or anywhere else —
+ * resolves to it: only a template's own `{% metablock %}` becomes a marker.
+ */
+const METABLOCK_MARKER = 'refrakt:metablock';
+/** Renders a `{% metablock %}` to the marker the engine fills (D7). It carries
+ *  the block's name and its owner, and nothing else. */
+const metablockMarkerSchema = {
+    attributes: { name: { type: String, required: true }, owner: { type: String, required: true } },
+    transform(node) {
+        return new MarkdocTag('div', {
+            [METABLOCK_ATTR]: node.attributes.name,
+            [METABLOCK_OWNER_ATTR]: node.attributes.owner,
+        });
+    },
+};
+/** Schema types a placed rune may emit under a composed type: a media object
+ *  that becomes a property of the outer entity, not a peer of it (D9). */
+export const SUBORDINATE_SCHEMA_TYPES = new Set([
+    'ImageObject',
+    'ImageGallery',
+    'VideoObject',
+    'AudioObject',
+    'MediaObject',
+]);
+/**
+ * Every field the content model resolves, by name. A composition reads
+ * `sequence` and `sections` models; the others are rejected by name rather
+ * than half-supported.
+ */
+function slotFields(model, fail) {
+    const fields = new Map();
+    const m = typeof model === 'function' ? model({}) : model;
+    if ('when' in m) {
+        fail('a conditional (`when`) content model is not supported by a composition — the template, not the model, is where an assembly varies.');
+    }
+    const s = m;
+    const addField = (f) => {
+        const emitted = f.emitTag !== undefined && f.itemModel !== undefined;
+        const refs = emitted ? (f.emitAttributes ?? {}) : {};
+        fields.set(f.name, { list: !!f.greedy || emitted, each: Object.keys(refs), refs });
+    };
+    if (s.type === 'sequence') {
+        for (const f of s.fields ?? [])
+            addField(f);
+    }
+    else if (s.type === 'sections') {
+        for (const f of s.fields ?? [])
+            addField(f);
+        const refs = s.emitAttributes ?? {};
+        fields.set('sections', {
+            list: true,
+            each: Object.keys(refs),
+            refs,
+            sections: s.emitTag === undefined,
+        });
+    }
+    else {
+        fail(`a \`${s.type}\` content model is not supported by a composition. Declare a \`sequence\` or \`sections\` model, whose fields are the slots.`);
+    }
+    return fields;
+}
+// ---------------------------------------------------------------------------
+// Template parsing and the construction-time checks
+// ---------------------------------------------------------------------------
+/**
+ * `{% slot name="x" each %}` is the spec's spelling, and Markdoc's tag grammar
+ * has no bare boolean attribute. Rewrite it to `each=true` inside slot tags
+ * only, outside quoted values, before parsing.
+ */
+function normaliseEach(body) {
+    return body.replace(/\{%-?\s*slot\b([^%]*?)(-?%\})/g, (whole, inner, close) => {
+        let out = '';
+        let quote = null;
+        let i = 0;
+        while (i < inner.length) {
+            const ch = inner[i];
+            if (quote) {
+                if (ch === '\\') {
+                    out += inner.slice(i, i + 2);
+                    i += 2;
+                    continue;
+                }
+                if (ch === quote)
+                    quote = null;
+                out += ch;
+                i++;
+                continue;
+            }
+            if (ch === '"' || ch === "'") {
+                quote = ch;
+                out += ch;
+                i++;
+                continue;
+            }
+            const rest = inner.slice(i);
+            const m = /^each(?![\w=-])/.exec(rest);
+            if (m && (i === 0 || /\s/.test(inner[i - 1]))) {
+                out += 'each=true';
+                i += m[0].length;
+                continue;
+            }
+            out += ch;
+            i++;
+        }
+        return whole.replace(inner + close, out + close);
+    });
+}
+/** Variables a template node reads, by path, in attribute or content position. */
+function variablePaths(value, out = []) {
+    if (!value || typeof value !== 'object')
+        return out;
+    const v = value;
+    if (v.$$mdtype === 'Variable' && Array.isArray(v.path)) {
+        out.push(v.path.map(String));
+        return out;
+    }
+    if (v.$$mdtype === 'Function') {
+        variablePaths(v.parameters, out);
+        return out;
+    }
+    if (Array.isArray(value)) {
+        for (const x of value)
+            variablePaths(x, out);
+        return out;
+    }
+    if (Object.getPrototypeOf(value) === Object.prototype) {
+        for (const x of Object.values(value))
+            variablePaths(x, out);
+    }
+    return out;
+}
+/** Is this node a `{% slot %}` — the composition's own placement tag? */
+function isSlotTag(n) {
+    return n.type === 'tag' && n.tag === 'slot';
+}
+/** A paragraph whose only content is one slot tag: a block slot written on its
+ *  own line with inline fallback content. */
+function soleSlot(n) {
+    if (n.type !== 'paragraph' || n.children.length !== 1)
+        return undefined;
+    const inline = n.children[0];
+    if (inline.type !== 'inline')
+        return undefined;
+    const meaningful = inline.children.filter((c) => !(c.type === 'text' && String(c.attributes.content ?? '').trim() === ''));
+    return meaningful.length === 1 && isSlotTag(meaningful[0]) ? meaningful[0] : undefined;
+}
+/**
+ * Check a template against the rune's content model and attributes, and build
+ * the transform that renders it. Called once, at schema construction. Throws,
+ * naming the rune and the offending tag, slot, field or name, rather than
+ * building anything it cannot honour.
+ */
+export function compileComposition(template, options) {
+    const { rune, tag, body } = template;
+    const fail = (msg) => {
+        throw new Error(`Rune "${rune}": invalid composition template — ${msg}`);
+    };
+    if (typeof body !== 'string')
+        fail('the template body must be a string.');
+    if (typeof tag !== 'string' || !/^[a-z][a-z0-9]*$/.test(tag)) {
+        fail('`tag` must be an element name.');
+    }
+    const ast = Markdoc.parse(normaliseEach(body));
+    const fields = slotFields(options.contentModel, fail);
+    const declared = new Set(options.attributes);
+    const selfNames = new Set([rune, ...(template.aliases ?? [])]);
+    const placedSlots = new Map();
+    const slotOrder = [];
+    const placements = [];
+    const checkVariables = (n, scope) => {
+        for (const path of variablePaths(n.attributes)) {
+            const [root, name] = path;
+            if (root === 'attrs') {
+                if (name === undefined)
+                    fail('`$attrs` must name an attribute, as `$attrs.<name>`.');
+                if (!declared.has(name)) {
+                    fail(`\`$attrs.${name}\` names no declared attribute (declared: ${[...declared].join(', ') || 'none'}).`);
+                }
+            }
+            else if (root === 'each') {
+                if (!scope.each) {
+                    fail(`\`$each${name ? `.${name}` : ''}\` is used outside an \`each\` slot; it exists only inside one (D26).`);
+                }
+                if (name === undefined)
+                    fail('`$each` must name a field, as `$each.<name>`.');
+                if (!scope.each.fields.includes(name)) {
+                    const exposed = scope.each.fields;
+                    fail(`\`$each.${name}\` names no field of slot \`${scope.each.slot}\`. \`$each\` exposes exactly the content model's \`emitAttributes\` (${exposed.join(', ') || 'none declared'}) — declare it there (D26).`);
+                }
+            }
+        }
+    };
+    const outlineOf = (nodes, scope) => {
+        const out = [];
+        for (const n of nodes) {
+            const entry = check(n, scope);
+            if (entry)
+                out.push(...entry);
+        }
+        return out;
+    };
+    /** Check one template node and return its outline entries. */
+    const check = (n, scope) => {
+        if (n.type === 'error') {
+            const errors = n.errors ?? [];
+            fail(`Markdoc could not parse it: ${errors.map((e) => e.message).join('; ') || 'syntax error'}.`);
+        }
+        checkVariables(n, scope);
+        if (isSlotTag(n))
+            return [checkSlot(n, scope)];
+        if (n.type === 'tag' && n.tag === METABLOCK_TAG)
+            return [checkMetablock(n, scope)];
+        if (n.type === 'tag' && n.tag) {
+            if (PREPROCESSOR_TAGS.has(n.tag)) {
+                fail(`it contains \`{% ${n.tag} %}\`, which resolves at preprocess, before a template renders (D4). A repeated block that needs \`${n.tag}\` is an \`{% include %}\`, not a composition.`);
+            }
+            if (MARKDOC_TAGS.has(n.tag)) {
+                const children = outlineOf(n.children, scope);
+                return n.tag === 'if' ? [{ conditional: true, children }] : children;
+            }
+            if (selfNames.has(n.tag)) {
+                fail(`it places \`{% ${n.tag} %}\`, which is the rune itself — a composition cycle.`);
+            }
+            placements.push({ rune: n.tag, ...(scope.parentRune ? { parent: scope.parentRune } : {}) });
+            const children = outlineOf(n.children, { ...scope, parentRune: n.tag });
+            return [{ rune: n.tag, ...(children.length > 0 ? { children } : {}) }];
+        }
+        const children = outlineOf(n.children, scope);
+        // Inline structure is the block's own business; the outline names blocks.
+        if (n.inline || n.type === 'inline' || n.type === 'document')
+            return children;
+        return [{ node: n.type, ...(children.length > 0 ? { children } : {}) }];
+    };
+    const checkSlot = (n, scope) => {
+        const name = n.attributes.name;
+        const each = n.attributes.each;
+        for (const key of Object.keys(n.attributes)) {
+            if (key !== 'name' && key !== 'each') {
+                fail(`a \`{% slot %}\` takes \`name\` and \`each\` only, not \`${key}\`.`);
+            }
+        }
+        if (each !== undefined && each !== true)
+            fail('`each` on a slot takes no value.');
+        if (name === undefined) {
+            if (!scope.each) {
+                fail('a bare `{% slot /%}` means "this item\'s content" and is only valid inside an `each` slot. Name the field it places.');
+            }
+            if (each)
+                fail('a bare `{% slot /%}` cannot itself iterate.');
+            if (n.children.length > 0)
+                fail('a bare `{% slot /%}` takes no fallback content.');
+            return { slot: '' };
+        }
+        if (typeof name !== 'string' || name === '')
+            fail('a slot `name` must be a non-empty string.');
+        if (scope.each) {
+            fail(`slot \`${name}\` is placed inside the \`each\` slot \`${scope.each.slot}\`, which would place it once per item. Place it outside.`);
+        }
+        const field = fields.get(name);
+        if (!field) {
+            fail(`slot \`${name}\` names no field of the content model (fields: ${[...fields.keys()].join(', ') || 'none'}) (D26).`);
+        }
+        if (placedSlots.has(name)) {
+            fail(`slot \`${name}\` is placed twice. A slot is placed exactly once; two positions are two declared fields, or a theme's concern (D26).`);
+        }
+        placedSlots.set(name, n);
+        slotOrder.push(name);
+        if (each) {
+            if (!field.list) {
+                fail(`slot \`${name}\` iterates with \`each\`, but field \`${name}\` holds a single value, not a list (D26).`);
+            }
+            const children = outlineOf(n.children, {
+                ...scope,
+                each: { slot: name, fields: field.each },
+            });
+            const sawBare = JSON.stringify(children).includes('"slot":""');
+            if (!sawBare) {
+                fail(`the \`each\` slot \`${name}\` never places its item — a bare \`{% slot /%}\` inside it is the item's content, and without one that content is dropped (D11).`);
+            }
+            return { slot: name, each: true, ...(children.length > 0 ? { children } : {}) };
+        }
+        const fallback = outlineOf(n.children, scope);
+        return {
+            slot: name,
+            ...(n.children.length > 0 ? { fallback: true } : {}),
+            ...(fallback.length > 0 ? { children: fallback } : {}),
+        };
+    };
+    const declaredBlocks = new Set(template.blocks ?? []);
+    const placedBlocks = new Set();
+    /** D7 — a meta block placement: a declared block, placed once, standing on
+     *  its own line. Its values resolve two stages later, in the engine. */
+    function checkMetablock(n, scope) {
+        for (const key of Object.keys(n.attributes)) {
+            if (key !== 'name') {
+                fail(`a \`{% metablock %}\` takes \`name\` only, not \`${key}\`.`);
+            }
+        }
+        const name = n.attributes.name;
+        if (typeof name !== 'string' || name === '') {
+            fail('a `{% metablock %}` needs a `name`: the declared block it places.');
+        }
+        if (n.children.length > 0) {
+            fail(`\`{% metablock name="${name}" %}\` takes no content; write it self-closing.`);
+        }
+        if (n.inline) {
+            fail(`\`{% metablock name="${name}" /%}\` sits inside a line of text. A meta block is a block; place it on its own line.`);
+        }
+        if (scope.each) {
+            fail(`\`{% metablock name="${name}" /%}\` is placed inside the \`each\` slot \`${scope.each.slot}\`, which would place it once per item. Place it outside (D7).`);
+        }
+        if (!declaredBlocks.has(name)) {
+            fail(`\`{% metablock name="${name}" /%}\` names no declared block (declared: ${[...declaredBlocks].join(', ') || 'none'}). Declare it under \`blocks\` (D7).`);
+        }
+        if (placedBlocks.has(name)) {
+            fail(`meta block \`${name}\` is placed twice. A block is placed exactly once: two placements would give two nodes one \`data-name\` (D7).`);
+        }
+        placedBlocks.add(name);
+        return { metablock: name };
+    }
+    const outline = outlineOf(ast.children, {});
+    // D11 — a field no slot places parses and then silently does not render.
+    const unplaced = [...fields.keys()].filter((f) => !placedSlots.has(f));
+    if (unplaced.length > 0) {
+        fail(`content-model field${unplaced.length > 1 ? 's' : ''} ${unplaced.map((f) => `\`${f}\``).join(', ')} ${unplaced.length > 1 ? 'are' : 'is'} placed by no slot, so authored content would be dropped. Place ${unplaced.length > 1 ? 'each' : 'it'} with \`{% slot name="…" /%}\` (D11).`);
+    }
+    // The type the rune claims — on the table, its fallback, or any of its rows.
+    const schemaType = options.schema?.type ??
+        options.schema?.fallback?.type ??
+        Object.values(options.schema?.rows ?? {}).find((r) => r.type)?.type;
+    const nodeSources = registersNodeSources(options.registers, fields, declared);
+    const info = {
+        rune,
+        slots: slotOrder,
+        placements,
+        outline,
+        ...(schemaType ? { schemaType } : {}),
+    };
+    const attributeNames = [...declared];
+    const transform = (resolved, attrs, config) => {
+        const bound = {};
+        for (const name of attributeNames)
+            bound[name] = attrs[name];
+        const ctx = { rune, resolved, attrs: bound, fields };
+        const placed = expand(ast.children, ctx);
+        // Top-level template nodes are the composed rune's own (D10). A slot
+        // placed at the top level already carries both markers.
+        for (const n of placed) {
+            if (n.attributes[OWNER_ATTR] === undefined)
+                n.attributes[OWNER_ATTR] = rune;
+        }
+        const children = Markdoc.transform(placed, templateConfig(config));
+        // The field bag holds every attribute the author set (or that defaulted):
+        // it is what `modifiers`, the schema row's attribute sources and
+        // registration read.
+        const properties = {};
+        for (const name of attributeNames) {
+            const value = attrs[name];
+            if (value === undefined || value === null)
+                continue;
+            properties[name] = new MarkdocTag('meta', { content: value });
+        }
+        const root = createComponentRenderable({
+            rune,
+            tag: tag,
+            properties,
+            children,
+        });
+        copyRegisteredNodes(root, nodeSources);
+        return root;
+    };
+    return { transform, info };
+}
+function asNodes(value) {
+    if (Array.isArray(value))
+        return value;
+    if (value != null)
+        return [value];
+    return [];
+}
+/** A shallow copy of a node: its own attributes, the same children. */
+function cloneNode(node, attributes, children) {
+    const copy = new Ast.Node(node.type, attributes, children, node.tag);
+    // The constructor takes four fields; the rest of what the parser sets is
+    // carried by hand, as `include` does — `inline` decides how a node renders.
+    if (node.lines)
+        copy.lines = node.lines;
+    if (node.location)
+        copy.location = node.location;
+    copy.inline = node.inline;
+    if (node.annotations?.length)
+        copy.annotations = node.annotations;
+    if (node.slots && Object.keys(node.slots).length > 0)
+        copy.slots = node.slots;
+    return copy;
+}
+/** Mark a node a slot places. The author's node is never mutated. */
+function place(node, owner, slot) {
+    return cloneNode(node, { ...node.attributes, [OWNER_ATTR]: owner, [SLOT_ATTR]: slot }, node.children);
+}
+/** Replace `$attrs.*` and `$each.*` with their values. Any other variable is
+ *  page scope and resolves at transform, as in any content. */
+function substitute(value, ctx) {
+    if (!value || typeof value !== 'object')
+        return value;
+    const v = value;
+    if (v.$$mdtype === 'Variable' && Array.isArray(v.path)) {
+        const [root, name] = v.path;
+        if (root === 'attrs')
+            return ctx.attrs[name];
+        if (root === 'each')
+            return ctx.item?.each[name];
+        return value;
+    }
+    if (v.$$mdtype === 'Function') {
+        const copy = Object.assign(Object.create(Object.getPrototypeOf(value)), value);
+        copy.parameters = substitute(v.parameters, ctx);
+        return copy;
+    }
+    if (Array.isArray(value))
+        return value.map((x) => substitute(x, ctx));
+    if (Object.getPrototypeOf(value) === Object.prototype) {
+        const out = {};
+        for (const [k, x] of Object.entries(value))
+            out[k] = substitute(x, ctx);
+        return out;
+    }
+    return value;
+}
+function substituteNode(node, ctx) {
+    const attributes = {};
+    for (const [key, value] of Object.entries(node.attributes ?? {})) {
+        const resolved = substitute(value, ctx);
+        // An unset attribute leaves the placed rune's own default in force.
+        if (resolved === undefined) {
+            if (node.type === 'text' && key === 'content')
+                attributes[key] = '';
+            continue;
+        }
+        attributes[key] = resolved;
+    }
+    return cloneNode(node, attributes, expand(node.children, ctx));
+}
+/** The items a list field resolved to, each with its `$each` binding and content. */
+function itemsOf(field, value) {
+    return asNodes(value).map((item) => {
+        if (field.sections) {
+            // A section entry: heading info under `$` keys, then the body's fields.
+            // The model has no `emitTag`, so `$each` is resolved here — by the
+            // resolver's own rule for the three reference forms (D4a).
+            const entry = item;
+            const extracted = {};
+            for (const [k, v] of Object.entries(entry)) {
+                if (k.startsWith('$'))
+                    extracted[k.slice(1)] = v;
+            }
+            const lookup = sectionLookup(String(entry.$heading ?? ''), extracted);
+            const each = {};
+            for (const [key, ref] of Object.entries(field.refs)) {
+                each[key] = resolveEmitReference(ref, lookup);
+            }
+            const content = Object.entries(entry)
+                .filter(([k]) => !k.startsWith('$'))
+                .flatMap(([, v]) => asNodes(v));
+            return { each, content };
+        }
+        // A node — an emitted child tag carries its `emitAttributes` already.
+        const node = item;
+        const each = {};
+        for (const key of field.each)
+            each[key] = node.attributes?.[key];
+        return { each, content: [node] };
+    });
+}
+/** The paragraphs a slot places, opened up so they sit in a line of text. */
+function inlineContent(nodes) {
+    return nodes.flatMap((n) => {
+        if (n.type !== 'paragraph')
+            return [n];
+        return n.children.flatMap((c) => (c.type === 'inline' ? c.children : [c]));
+    });
+}
+function expandSlot(slot, ctx, inline, block) {
+    const name = slot.attributes.name;
+    let placed;
+    if (name === undefined) {
+        const item = ctx.item;
+        placed = item.content.map((n) => place(n, ctx.rune, item.slot));
+    }
+    else if (slot.attributes.each === true) {
+        const field = ctx.fields.get(name);
+        placed = [];
+        for (const item of itemsOf(field, ctx.resolved[name])) {
+            placed.push(...expand(slot.children, { ...ctx, item: { slot: name, ...item } }).filter((n) => !(n.type === 'text' && String(n.attributes.content ?? '').trim() === '')));
+        }
+        return placed;
+    }
+    else {
+        const nodes = asNodes(ctx.resolved[name]);
+        if (nodes.length === 0) {
+            // Fallback content is the template's, not the field's: it carries no
+            // slot name, so the schema row never reads it as authored content.
+            const fallback = expand(slot.children, ctx);
+            if (block && fallback.length > 0 && fallback.every((n) => n.inline)) {
+                return [new Ast.Node('paragraph', {}, [new Ast.Node('inline', {}, fallback)])];
+            }
+            return fallback;
+        }
+        placed = nodes.map((n) => place(n, ctx.rune, name));
+    }
+    return inline ? inlineContent(placed) : placed;
+}
+/** Substitute into a list of template nodes, placing slots where they stand. */
+function expand(nodes, ctx) {
+    const out = [];
+    for (const n of nodes) {
+        if (isSlotTag(n)) {
+            out.push(...expandSlot(n, ctx, !!n.inline, !n.inline));
+            continue;
+        }
+        if (n.type === 'tag' && n.tag === METABLOCK_TAG) {
+            out.push(new Ast.Node('tag', { name: n.attributes.name, owner: ctx.rune }, [], METABLOCK_MARKER));
+            continue;
+        }
+        const sole = soleSlot(n);
+        if (sole) {
+            out.push(...expandSlot(sole, ctx, false, true));
+            continue;
+        }
+        out.push(substituteNode(n, ctx));
+    }
+    return out;
+}
+// ---------------------------------------------------------------------------
+// Markers and registration
+// ---------------------------------------------------------------------------
+/**
+ * The config a template is transformed against, with the slot markers declared
+ * on every schema. A site assembles its config that way already
+ * (`assembleMarkdocSchemas`); a config that was not is assembled here, so a
+ * marker is never lost to where the transform was called from.
+ */
+function markerConfig(config) {
+    const nodes = (config.nodes ?? {});
+    const tags = (config.tags ?? {});
+    const declared = (s) => !!s?.attributes?.[SLOT_ATTR];
+    const ready = declared(nodes.paragraph) && Object.values(tags).every((s) => !s || declared(s));
+    if (ready)
+        return config;
+    return {
+        ...config,
+        tags: declareSlotMarkers(tags),
+        nodes: declareSlotMarkersOnNodes(nodes),
+    };
+}
+/** The config a template renders against: the slot markers declared, and the
+ *  meta block marker resolvable — for the template's own `{% metablock %}`
+ *  only, since nothing authored can name its key. */
+function templateConfig(config) {
+    const marked = markerConfig(config);
+    return { ...marked, tags: { ...marked.tags, [METABLOCK_MARKER]: metablockMarkerSchema } };
+}
+/** The `registers` sources that name a slot rather than an attribute (D10b). */
+function registersNodeSources(registers, fields, attributes) {
+    if (!registers)
+        return [];
+    const out = new Set();
+    for (const { source } of registersSources(registers)) {
+        if (fields.has(source) && !attributes.has(source))
+            out.add(source);
+    }
+    return [...out];
+}
+function textOf(node) {
+    if (typeof node === 'string')
+        return node;
+    if (!MarkdocTag.isTag(node))
+        return '';
+    return (node.children ?? []).map(textOf).join('');
+}
+/**
+ * SPEC-145 D10b — copy each node-sourced `registers` value into the composed
+ * rune's own field bag, now, while the slot markers still let the resolvers
+ * reach the placed node. Phase 2 reads it from the bag, through the fallback
+ * `readRegistersSource` already has; `findRef` and the strip timing are
+ * unchanged.
+ */
+function copyRegisteredNodes(root, sources) {
+    if (sources.length === 0)
+        return;
+    let bag = {};
+    try {
+        bag = JSON.parse(String(root.attributes['data-rune-fields'] ?? '{}'));
+    }
+    catch {
+        bag = {};
+    }
+    let changed = false;
+    for (const source of sources) {
+        if (bag[source] !== undefined)
+            continue;
+        const [node] = findAllByName(root, source);
+        if (!node)
+            continue;
+        bag[source] = textOf(node).trim();
+        changed = true;
+    }
+    if (changed)
+        root.attributes['data-rune-fields'] = JSON.stringify(bag);
+}
+const DEFINITION_KEYS = new Set([
+    'tag',
+    'aliases',
+    'description',
+    'attributes',
+    'content',
+    'schema',
+    'registers',
+    'metaFields',
+    'blocks',
+    'provides',
+]);
+/** Keys that would give a composed rune styles of its own (D2). */
+const STYLE_KEYS = new Set(['css', 'style', 'styles', 'stylesheet', 'block', 'class']);
+/** Keys that would declare a second emit path beside the template (D5). */
+const EMIT_KEYS = new Set(['transform', 'emits', 'slots']);
+const ATTRIBUTE_KEYS = new Set(['type', 'required', 'default', 'matches', 'description']);
+const ATTRIBUTE_TYPES = {
+    string: String,
+    number: Number,
+    boolean: Boolean,
+};
+/**
+ * Attribute names the engine already writes as `data-*` on a rune root. An
+ * enum attribute becomes a `data-*` modifier (D2a), so one of these would
+ * overwrite engine structure.
+ */
+const RESERVED_MODIFIERS = new Set([
+    'name',
+    'field',
+    'rune',
+    'rune-fields',
+    'slot',
+    'owner',
+    'section',
+    'zone',
+]);
+/** kebab-case → PascalCase: the config key the engine finds a rune under. */
+export function composedTypeName(rune) {
+    return rune
+        .split('-')
+        .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+        .join('');
+}
+const kebab = (s) => s.replace(/([a-z0-9])([A-Z])/g, '$1-$2').toLowerCase();
+/**
+ * Split and parse a definition. The rune's name is the file's name (SPEC-153
+ * D9), passed in; a frontmatter key restating it is rejected rather than
+ * silently preferred.
+ */
+export function parseCompositionDefinition(rune, source) {
+    const fail = (msg) => {
+        throw new Error(`Rune "${rune}": invalid composition definition — ${msg}`);
+    };
+    if (!/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/.test(rune)) {
+        fail('the rune name must be kebab-case.');
+    }
+    if (typeof source !== 'string')
+        fail('the definition must be a string.');
+    const match = /^?---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)([\s\S]*)$/.exec(source);
+    if (!match)
+        fail('it has no frontmatter block (`---` … `---`) declaring its input.');
+    let front;
+    try {
+        front = yaml.parse(match[1]) ?? {};
+    }
+    catch (e) {
+        fail(`its frontmatter is not valid YAML: ${e.message}`);
+    }
+    if (!front || typeof front !== 'object' || Array.isArray(front)) {
+        fail('its frontmatter must be a mapping.');
+    }
+    const fm = front;
+    for (const key of Object.keys(fm)) {
+        if (DEFINITION_KEYS.has(key))
+            continue;
+        if (key === 'rune' || key === 'name') {
+            fail(`frontmatter key \`${key}\` restates the rune's name, which is the file's name. Remove it (SPEC-153 D9).`);
+        }
+        if (STYLE_KEYS.has(key)) {
+            fail(`frontmatter key \`${key}\` would ship styles. A composed rune has no block and ships no CSS: its appearance is the primitives' (D2). A rune that needs its own styling is a declared rune in a plugin.`);
+        }
+        if (EMIT_KEYS.has(key)) {
+            fail(`frontmatter key \`${key}\` declares a second emit path. A definition's template is its emit path; exactly one of a slot declaration, a template or a \`transform\` (D5).`);
+        }
+        if (key === 'layout') {
+            fail("frontmatter key `layout` cannot apply: `layout` places a rune's own containers, and a composed rune's containers belong to the primitives it places (D7). Arrange them in the template.");
+        }
+        fail(`unknown frontmatter key \`${key}\` (expected ${[...DEFINITION_KEYS].join(', ')}).`);
+    }
+    const tag = (fm.tag ?? 'div');
+    if (typeof tag !== 'string' || !/^[a-z][a-z0-9]*$/.test(tag))
+        fail('`tag` must be an element name.');
+    let aliases;
+    if (fm.aliases !== undefined) {
+        if (!Array.isArray(fm.aliases) || !fm.aliases.every((a) => typeof a === 'string')) {
+            fail('`aliases` must be a list of names.');
+        }
+        aliases = fm.aliases;
+    }
+    if (fm.description !== undefined && typeof fm.description !== 'string') {
+        fail('`description` must be a string.');
+    }
+    const attributes = parseAttributes(fm.attributes, fail);
+    const contentModel = parseContentModel(fm.content, fail);
+    for (const key of ['schema', 'registers', 'metaFields', 'blocks']) {
+        const v = fm[key];
+        if (v !== undefined && (!v || typeof v !== 'object' || Array.isArray(v))) {
+            fail(`\`${key}\` must be a mapping.`);
+        }
+    }
+    if (fm.provides !== undefined &&
+        (!Array.isArray(fm.provides) || !fm.provides.every((p) => typeof p === 'string'))) {
+        fail('`provides` must be a list of names.');
+    }
+    return {
+        rune,
+        tag,
+        ...(aliases ? { aliases } : {}),
+        ...(fm.description ? { description: fm.description } : {}),
+        attributes,
+        contentModel,
+        ...(fm.schema ? { schema: fm.schema } : {}),
+        ...(fm.registers ? { registers: fm.registers } : {}),
+        ...(fm.metaFields ? { metaFields: fm.metaFields } : {}),
+        ...(fm.blocks ? { blocks: fm.blocks } : {}),
+        ...(fm.provides ? { provides: fm.provides } : {}),
+        template: match[2],
+    };
+}
+function parseAttributes(raw, fail) {
+    if (raw === undefined)
+        return {};
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        fail('`attributes` must be a mapping.');
+    const out = {};
+    for (const [name, decl] of Object.entries(raw)) {
+        const where = `attribute \`${name}\``;
+        if (!/^[a-z][a-zA-Z0-9]*(-[a-z0-9]+)*$/.test(name))
+            fail(`${where}: not a valid attribute name.`);
+        if (!decl || typeof decl !== 'object' || Array.isArray(decl)) {
+            fail(`${where} must be a mapping such as \`{ type: string }\`.`);
+        }
+        const d = decl;
+        for (const key of Object.keys(d)) {
+            if (!ATTRIBUTE_KEYS.has(key)) {
+                fail(`${where}: unknown key \`${key}\` (expected ${[...ATTRIBUTE_KEYS].join(', ')}).`);
+            }
+        }
+        const type = ATTRIBUTE_TYPES[String(d.type ?? 'string')];
+        if (!type)
+            fail(`${where}: \`type\` must be string, number or boolean.`);
+        if (d.matches !== undefined) {
+            if (!Array.isArray(d.matches) || d.matches.length === 0) {
+                fail(`${where}: \`matches\` must be a non-empty list.`);
+            }
+            if (RESERVED_MODIFIERS.has(kebab(name))) {
+                fail(`${where} declares \`matches\`, so it would render as \`data-${kebab(name)}\` — an attribute the engine writes itself. Rename it (D2a).`);
+            }
+        }
+        out[name] = {
+            type,
+            required: d.required === true,
+            ...(d.default !== undefined ? { default: d.default } : {}),
+            ...(d.matches !== undefined ? { matches: d.matches } : {}),
+            ...(typeof d.description === 'string' ? { description: d.description } : {}),
+        };
+    }
+    return out;
+}
+const FIELD_KEYS = new Set([
+    'match',
+    'optional',
+    'greedy',
+    'description',
+    'itemModel',
+    'emitTag',
+    'emitAttributes',
+]);
+/** A field list as YAML writes it: a mapping keyed by name, or a list with `name`. */
+function parseFields(raw, where, fail) {
+    if (raw === undefined)
+        return [];
+    const entries = Array.isArray(raw)
+        ? raw.map((f) => [String(f?.name ?? ''), f])
+        : raw && typeof raw === 'object'
+            ? Object.entries(raw)
+            : fail(`\`${where}\` must be a mapping of fields.`);
+    return entries.map(([name, f]) => {
+        if (!/^[a-z][a-zA-Z0-9]*(-[a-zA-Z0-9]+)*$/.test(name)) {
+            fail(`\`${where}\`: \`${name}\` is not a valid field name.`);
+        }
+        if (!f || typeof f !== 'object')
+            fail(`\`${where}.${name}\` must be a mapping.`);
+        const def = { ...f };
+        delete def.name;
+        for (const key of Object.keys(def)) {
+            if (!FIELD_KEYS.has(key)) {
+                fail(`\`${where}.${name}\`: unknown key \`${key}\` (expected ${[...FIELD_KEYS].join(', ')}).`);
+            }
+        }
+        if (typeof def.match !== 'string')
+            fail(`\`${where}.${name}\` needs a \`match\`.`);
+        return { name, ...def };
+    });
+}
+function parseHeadingExtract(raw, fail) {
+    const fields = raw?.fields;
+    if (!Array.isArray(fields))
+        fail('`content.headingExtract.fields` must be a list.');
+    return {
+        fields: fields.map((f) => {
+            if (typeof f?.name !== 'string' || typeof f.pattern !== 'string') {
+                fail('a `headingExtract` field needs a `name` and a `pattern`.');
+            }
+            let pattern = 'remainder';
+            if (f.pattern !== 'remainder') {
+                try {
+                    pattern = new RegExp(f.pattern);
+                }
+                catch (e) {
+                    fail(`headingExtract \`${f.name}\`: \`pattern\` is not a regular expression: ${e.message}`);
+                }
+            }
+            return {
+                name: f.name,
+                match: 'text',
+                pattern,
+                ...(f.optional === true ? { optional: true } : {}),
+            };
+        }),
+    };
+}
+const SEQUENCE_KEYS = new Set(['type', 'fields']);
+const SECTIONS_KEYS = new Set([
+    'type',
+    'sectionHeading',
+    'fields',
+    'preamble',
+    'sectionModel',
+    'emitTag',
+    'emitAttributes',
+    'headingExtract',
+    'knownSections',
+]);
+function parseContentModel(raw, fail) {
+    if (raw === undefined)
+        return { type: 'sequence', fields: [] };
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        fail('`content` must be a mapping.');
+    const c = raw;
+    const allowed = c.type === 'sequence' ? SEQUENCE_KEYS : c.type === 'sections' ? SECTIONS_KEYS : null;
+    if (!allowed) {
+        fail(`\`content.type\` must be \`sequence\` or \`sections\`${c.type ? `, not \`${String(c.type)}\`` : ''}: a composition's slots are the model's fields.`);
+    }
+    for (const key of Object.keys(c)) {
+        if (!allowed.has(key)) {
+            fail(`\`content\`: unknown key \`${key}\` for a ${String(c.type)} model.`);
+        }
+    }
+    if (c.type === 'sequence') {
+        return {
+            type: 'sequence',
+            fields: parseFields(c.fields, 'content.fields', fail),
+        };
+    }
+    if (c.fields !== undefined && c.preamble !== undefined) {
+        fail('`content` declares both `fields` and `preamble`; they are one thing — use `preamble`.');
+    }
+    const sectionModel = c.sectionModel === undefined
+        ? {
+            type: 'sequence',
+            fields: [{ name: 'body', match: 'any', optional: true, greedy: true }],
+        }
+        : parseContentModel(c.sectionModel, fail);
+    if (c.emitAttributes !== undefined) {
+        const ea = c.emitAttributes;
+        if (!ea ||
+            typeof ea !== 'object' ||
+            Array.isArray(ea) ||
+            !Object.values(ea).every((v) => typeof v === 'string')) {
+            fail('`content.emitAttributes` must map names to `$heading`, `$<field>` or a literal.');
+        }
+    }
+    return {
+        type: 'sections',
+        sectionHeading: typeof c.sectionHeading === 'string' ? c.sectionHeading : 'heading',
+        fields: parseFields(c.preamble ?? c.fields, c.preamble ? 'content.preamble' : 'content.fields', fail),
+        sectionModel,
+        ...(typeof c.emitTag === 'string' ? { emitTag: c.emitTag } : {}),
+        ...(c.emitAttributes ? { emitAttributes: c.emitAttributes } : {}),
+        ...(c.headingExtract ? { headingExtract: parseHeadingExtract(c.headingExtract, fail) } : {}),
+        ...(c.knownSections
+            ? { knownSections: c.knownSections }
+            : {}),
+    };
+}
+/**
+ * The generated, block-less engine config of a composed rune (D2a). Not
+ * hand-written beside the definition: modifiers come from its enum attributes
+ * and from every attribute a `metaFields` entry reads, and `metaFields` /
+ * `blocks` are carried as declared.
+ *
+ * The second source is what lets a placed meta block render (D7): the engine
+ * resolves a field against the rune's modifier values, exactly as it does for a
+ * tree-owning rune — which must declare the same attributes as modifiers for
+ * its own blocks to fill.
+ */
+export function composedRuneConfig(def) {
+    const read = new Set();
+    for (const [name, field] of Object.entries(def.metaFields ?? {})) {
+        read.add(name);
+        const f = (field ?? {});
+        for (const ref of [f.condition, f.href, f.rating?.total]) {
+            if (typeof ref === 'string')
+                read.add(ref);
+        }
+    }
+    const modifiers = {};
+    for (const [name, attr] of Object.entries(def.attributes)) {
+        if (!attr.matches && !read.has(name))
+            continue;
+        modifiers[name] = {
+            source: 'meta',
+            ...(attr.default !== undefined ? { default: String(attr.default) } : {}),
+        };
+    }
+    return {
+        ...(Object.keys(modifiers).length > 0 ? { modifiers } : {}),
+        ...(def.metaFields ? { metaFields: def.metaFields } : {}),
+        ...(def.blocks ? { blocks: def.blocks } : {}),
+        ...(def.provides ? { provides: def.provides } : {}),
+    };
+}
+/** The schema types a rune can emit at its root — its table's, and its `seoType`. */
+function emittedTypes(entry, table) {
+    return [
+        entry.seoType,
+        table?.type,
+        table?.fallback?.type,
+        ...Object.values(table?.rows ?? {}).map((r) => r.type),
+    ].filter((t) => Boolean(t));
+}
+/**
+ * The checks that need every rune in hand: a composition cycle (A places B
+ * places A), a composed type placed over a peer type (D9), and a placed rune
+ * that requires a parent the template does not give it (D12). Run once the
+ * catalog is assembled — by `mergePlugins`, before any page renders — and
+ * throws on the first problem, naming the runes involved.
+ *
+ * D9 is relational: a composition that declares no type of its own may place
+ * an entity rune, because then exactly one type exists in the subtree. The
+ * check fires only when the composed rune declares a type and a placed rune
+ * declares a non-subordinate one.
+ */
+export function checkCompositions(catalog, tableOf) {
+    const byName = new Map();
+    for (const [name, entry] of Object.entries(catalog)) {
+        byName.set(name, { name, entry });
+        for (const alias of entry.aliases ?? []) {
+            if (!byName.has(alias))
+                byName.set(alias, { name, entry });
+        }
+    }
+    const composed = Object.entries(catalog)
+        .map(([name, entry]) => ({ name, entry, info: compositionFor(entry.schema) }))
+        .filter((c) => Boolean(c.info));
+    for (const { name, info } of composed) {
+        for (const { rune: placedName, parent } of info.placements) {
+            const placed = byName.get(placedName);
+            if (!placed)
+                continue; // An unknown tag is Markdoc validation's to report.
+            const required = placed.entry.requiresParent;
+            if (required && required !== '*') {
+                const requiredRune = kebab(required);
+                const parentEntry = parent ? byName.get(parent) : undefined;
+                const parentRune = parent
+                    ? (parentEntry?.entry.dataRune ?? parentEntry?.name ?? parent)
+                    : undefined;
+                if (parentRune !== requiredRune) {
+                    throw new Error(`Rune "${name}": its template places \`{% ${placedName} %}\`, which requires \`{% ${requiredRune} %}\` as its parent, ${parent ? `but sits inside \`{% ${parent} %}\`` : `but the template's nearest rune around it is "${name}" itself`}. Place \`{% ${requiredRune} %}\` and let its content model produce the \`${placed.name}\` children (D12).`);
+                }
+            }
+            if (info.schemaType && placed.entry.schema) {
+                const peer = emittedTypes(placed.entry, tableOf(placed.entry.schema)).find((t) => !SUBORDINATE_SCHEMA_TYPES.has(t));
+                if (peer) {
+                    throw new Error(`Rune "${name}": it declares schema type \`${info.schemaType}\` and its template places \`{% ${placedName} %}\`, which declares the peer type \`${peer}\`. Two top-level entities in one subtree — compose into a type, never from one: place primitives that emit no type, or a subordinate one such as \`figure\` (D9).`);
+                }
+            }
+        }
+    }
+    // Cycles: depth-first over the placement graph, composed runes only.
+    const edges = new Map();
+    for (const { name, info } of composed) {
+        edges.set(name, info.placements.map((p) => byName.get(p.rune)?.name).filter((n) => Boolean(n)));
+    }
+    const state = new Map();
+    const stack = [];
+    const visit = (name) => {
+        if (state.get(name) === 'done')
+            return;
+        if (state.get(name) === 'visiting') {
+            const cycle = [...stack.slice(stack.indexOf(name)), name];
+            throw new Error(`Composition cycle: ${cycle.map((n) => `"${n}"`).join(' places ')}. A composed rune cannot place itself, directly or through another.`);
+        }
+        state.set(name, 'visiting');
+        stack.push(name);
+        for (const next of edges.get(name) ?? [])
+            if (edges.has(next))
+                visit(next);
+        stack.pop();
+        state.set(name, 'done');
+    };
+    for (const name of edges.keys())
+        visit(name);
+}
+//# sourceMappingURL=composition.js.map