@cube-drone/marquee-html-renderer 0.9.2 → 0.10.0

package/README.md

@@ -22,6 +22,23 @@ children. Pair the output with
 class contract this renderer targets) and optionally
 [`@cube-drone/marquee-fonts`](https://www.npmjs.com/package/@cube-drone/marquee-fonts).
 
+`linkAllowed` decides *whether* a target links; the optional `linkTarget` decides *where* it
+points — return another address (a note's chapter inside an ePub, a file inside an export) or
+`null` to keep the target as written. It's asked only after `linkAllowed` says yes, for every
+anchor drawn from an author target (links, turbolinks, an embed's fallback link), and the
+visible text stays the author's. The React renderer honors it too.
+
+For a page that must be well-formed XML — an ePub chapter, any XHTML document — pass
+`{ output: "xhtml" }`: void elements close themselves (`<br/>`, `<img …/>`), boolean
+attributes carry values (`controls="controls"`), the only entities are XML's own five, and
+characters XML forbids become U+FFFD. Same elements, classes, and words. Hook output is placed
+as given, so a profile used this way must return XHTML too.
+
+```ts
+render(parse(source), bookProfile, { output: "xhtml" });
+renderMarquee(source, bookProfile, { output: "xhtml" }); // same, from source
+```
+
 The renderer's obligations (never eat content, comments render nothing, unknown vocabulary
 shrugs, invalid constructs render inert placeholders, author bytes never become markup) are
 enforced by its behavioral test suite. You probably want

package/dist/index.d.ts

@@ -1,8 +1,10 @@
+import { type RenderOptions } from "./render.ts";
 import type { Profile } from "./profile.ts";
-export { render, escapeText, escapeAttr, FONTS, usedFontTokens, containerLook } from "./render.ts";
+export { render, type RenderOptions, escapeText, escapeAttr, FONTS, usedFontTokens, containerLook } from "./render.ts";
 export { bareWebProfile } from "./profile.ts";
 export { EFFECT_NAMES, effectLook, splitPieces, type EffectLook, type EffectUnit, type SplitPiece } from "./effects.ts";
 export type { EmojiResolution, Profile, MediaResolution, TurbolinkLevel } from "./profile.ts";
 /** Parse and render in one step. Throws UnsupportedVersionError for unknown
- * dialect versions, exactly as the parser does. */
-export declare function renderMarquee(source: string, profile?: Profile): string;
+ * dialect versions, exactly as the parser does. `{ output: "xhtml" }` for a
+ * page that must be well-formed XML, like an ePub's. */
+export declare function renderMarquee(source: string, profile?: Profile, options?: RenderOptions): string;

package/dist/index.js

@@ -10,7 +10,8 @@ export { render, escapeText, escapeAttr, FONTS, usedFontTokens, containerLook }
 export { bareWebProfile } from "./profile.js";
 export { EFFECT_NAMES, effectLook, splitPieces } from "./effects.js";
 /** Parse and render in one step. Throws UnsupportedVersionError for unknown
- * dialect versions, exactly as the parser does. */
-export function renderMarquee(source, profile) {
-    return render(parse(source), profile);
+ * dialect versions, exactly as the parser does. `{ output: "xhtml" }` for a
+ * page that must be well-formed XML, like an ePub's. */
+export function renderMarquee(source, profile, options) {
+    return render(parse(source), profile, options);
 }

package/dist/profile.d.ts

@@ -17,6 +17,14 @@ export interface Profile {
     /** May this target become a hyperlink? Disallowed links render their
      * children without an anchor (content survives, capability doesn't). */
     linkAllowed(target: string): boolean;
+    /** Where an allowed link points: null (or no method) keeps the target as
+     * written; a string is the address the anchor uses instead (a note's
+     * chapter inside an ePub, a file's path inside an export). Asked only after
+     * `linkAllowed` says yes - a refused link stays refused - and for every
+     * anchor the renderer draws from an author target: links, turbolinks, and
+     * the fallback link of an embed. The visible text stays the author's;
+     * `turbolink` and `media` still see the original target. */
+    linkTarget?(target: string): string | null;
     /** Resolve an embed target to a media kind, or null for the inert
      * fallback. The kind is resolved at render time (SPEC.md, "Media"). */
     media(target: string): MediaResolution | null;
@@ -48,6 +56,9 @@ export interface Profile {
      * - Place the children: a claiming answer MUST include `renderedChildren`
      *   (already-escaped HTML) or a known substitute for them - the shrug's
      *   never-eat-content rule binds embedder vocabulary too.
+     * - Match the output: a profile rendered with `{ output: "xhtml" }` must
+     *   return well-formed XHTML (here and in `span` and `turbolink`) - the
+     *   renderer places embedder HTML as given and can't rewrite it.
      * Embedder-first: a claim on a name the language defines wins. */
     directive(name: string, attrs: Attrs, renderedChildren: string): string | null;
     /** Embedder span vocabulary - the inline twin of `directive`

package/dist/profile.js

@@ -4,14 +4,19 @@
 // guesses trust, never widens a scheme allowlist.
 // Mirror of the Rust renderer's table (rust/html_renderer/src/profile.rs). `apng` and
 // `opus` joined 2026-09-03: ringtome mints both and they rendered as the placeholder.
-const MEDIA_KINDS = {
+const MEDIA_KINDS = Object.assign(Object.create(null), {
     png: "image", jpg: "image", jpeg: "image", gif: "image", webp: "image",
     avif: "image", apng: "image", svg: "image",
     mp3: "audio", ogg: "audio", opus: "audio", wav: "audio", flac: "audio", m4a: "audio",
     mp4: "video", webm: "video",
-};
+});
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+// Read the scheme the way a browser will: the URL parser strips leading C0
+// controls and spaces and drops tabs/newlines anywhere, so
+// "\x01javascript:" and "java\tscript:" are javascript: URLs. Targets with
+// controls are refused outright (see linkAllowed); leading spaces are skipped.
 function scheme(target) {
-    const m = /^([A-Za-z][A-Za-z0-9+.-]*):/.exec(target);
+    const m = /^ *([A-Za-z][A-Za-z0-9+.-]*):/.exec(target);
     return m ? m[1].toLowerCase() : null;
 }
 /** The bare-web default: https links, extension-sniffed media, no widgets,
@@ -19,6 +24,11 @@ function scheme(target) {
  * degrades inert. */
 export const bareWebProfile = {
     linkAllowed(target) {
+        // A lone surrogate isn't a URL anyone can write; refusing it here keeps
+        // every anchor and media path well-formed.
+        if (/[\x00-\x1f\x7f]/.test(target) || LONE_SURROGATE.test(target)) {
+            return false;
+        }
         const s = scheme(target);
         return s === null || s === "http" || s === "https" || s === "mailto";
     },

package/dist/render.d.ts

@@ -1,11 +1,24 @@
 import type { Attrs, Node } from "@cube-drone/marquee-parser";
 import { type Profile } from "./profile.ts";
-export declare function render(node: Node, profile?: Profile): string;
+export interface RenderOptions {
+    /** Which serialization to write. "html" (the default) is HTML5 for a web
+     * page: void elements unclosed (`<br>`), boolean attributes bare
+     * (`controls`). "xhtml" is well-formed XML for an ePub page or any XHTML
+     * document: void elements close themselves (`<br/>`), every attribute
+     * carries a quoted value, the only entities are XML's own, and characters
+     * XML forbids become U+FFFD. Same elements, same classes, same words.
+     * Embedder vocabulary is placed as given, so a profile used with "xhtml"
+     * must return XHTML too (see `Profile.directive`). */
+    output?: "html" | "xhtml";
+}
+export declare function render(node: Node, profile?: Profile, options?: RenderOptions): string;
 /** The font vocabulary (closed, two tiers): four standard stacks that need
  * no files, and the grab bag - SIL OFL faces the embedder serves itself
  * (never a third-party CDN: fonts are a tracking vector, care-modes apply).
  * Values are the `face` presentational attribute - the no-stylesheet floor;
- * the mq-font-* class is the ceiling, where the real @font-face lives. */
+ * the mq-font-* class is the ceiling, where the real @font-face lives.
+ * Author-keyed tables like this one have no prototype, so `font=constructor`
+ * finds nothing instead of Object's own properties. */
 export declare const FONTS: Record<string, string>;
 /** Which grab-bag faces does this rendered HTML actually wear? Pure string
  * scan of the mq-font-* class contract - feed the result to

package/dist/render.js

@@ -5,8 +5,21 @@
 // nothing; invalid constructs render inert placeholders.
 import { bareWebProfile } from "./profile.js";
 import { effectLook, splitPieces } from "./effects.js";
-export function render(node, profile = bareWebProfile) {
-    return renderNode(node, { profile, note: { n: 0, pending: [] } });
+export function render(node, profile = bareWebProfile, options = {}) {
+    const xhtml = options.output === "xhtml";
+    const ctx = {
+        profile,
+        text: xhtml ? escapeTextXml : escapeText,
+        attr: xhtml ? escapeAttrXml : escapeAttr,
+        void: xhtml ? "/>" : ">",
+        flag: xhtml ? (name) => ` ${name}="${name}"` : (name) => ` ${name}`,
+        note: { n: 0, pending: [] },
+    };
+    return renderNode(node, ctx);
+}
+/** The href an allowed link wears: the profile's rewrite, or the target. */
+function href(target, ctx) {
+    return ctx.attr(ctx.profile.linkTarget?.(target) ?? target);
 }
 /** Asides render just below the paragraph (or heading) that triggered
  * them - part of regular flow, no floats, no popups. */
@@ -35,8 +48,8 @@ function renderNode(node, ctx) {
         }
         case "code_block": {
             const lang = infoToken(node.info);
-            const cls = lang === null ? "" : ` class="language-${escapeAttr(lang)}"`;
-            const text = node.text === "" ? "" : `${escapeText(node.text)}\n`;
+            const cls = lang === null ? "" : ` class="language-${ctx.attr(lang)}"`;
+            const text = node.text === "" ? "" : `${ctx.text(node.text)}\n`;
             return `<pre class="mq-code"><code${cls}>${text}</code></pre>`;
         }
         case "blockquote":
@@ -48,15 +61,15 @@ function renderNode(node, ctx) {
         case "list_item":
             return `<li>${children(node.children, ctx)}</li>`;
         case "thematic_break":
-            return "<hr>";
+            return `<hr${ctx.void}`;
         case "directive":
             return directive(node.name, node.attrs, node.children, ctx);
         case "invalid_directive":
-            return `<div class="mq-invalid" data-reason="${escapeAttr(node.reason)}"></div>`;
+            return `<div class="mq-invalid" data-reason="${ctx.attr(node.reason)}"></div>`;
         case "comment":
             return ""; // the anti-shrug: correct rendering is absence
         case "text":
-            return escapeText(node.value);
+            return ctx.text(node.value);
         case "emphasis":
             return `<em>${children(node.children, ctx)}</em>`;
         case "strong":
@@ -64,29 +77,29 @@ function renderNode(node, ctx) {
         case "strikethrough":
             return `<del>${children(node.children, ctx)}</del>`;
         case "code_span":
-            return `<code>${escapeText(node.text)}</code>`;
+            return `<code>${ctx.text(node.text)}</code>`;
         case "link": {
             const inner = children(node.children, ctx);
             return ctx.profile.linkAllowed(node.target)
-                ? `<a href="${escapeAttr(node.target)}">${inner}</a>`
+                ? `<a href="${href(node.target, ctx)}">${inner}</a>`
                 : `<span class="mq-blocked">${inner}</span>`;
         }
         case "embed":
-            return embed(node.target, node.alt, ctx.profile);
+            return embed(node.target, node.alt, ctx);
         case "turbolink":
-            return turbolink(node.target, undefined, ctx.profile);
+            return turbolink(node.target, undefined, ctx);
         case "span":
             return span(node.name, node.attrs, node.children, ctx);
         case "emoji": {
             const resolved = ctx.profile.emoji(node.slug);
             if (resolved !== null && typeof resolved === "object") {
                 const alt = resolved.alt ?? `:${node.slug}:`;
-                return `<img class="mq-emoji" src="${escapeAttr(resolved.image)}" alt="${escapeAttr(alt)}" loading="lazy">`;
+                return `<img class="mq-emoji" src="${ctx.attr(resolved.image)}" alt="${ctx.attr(alt)}" loading="lazy"${ctx.void}`;
             }
-            return escapeText(resolved ?? `:${node.slug}:`);
+            return ctx.text(resolved ?? `:${node.slug}:`);
         }
         case "hard_break":
-            return "<br>";
+            return `<br${ctx.void}`;
     }
 }
 function children(nodes, ctx) {
@@ -106,8 +119,10 @@ function isToken(v) {
  * no files, and the grab bag - SIL OFL faces the embedder serves itself
  * (never a third-party CDN: fonts are a tracking vector, care-modes apply).
  * Values are the `face` presentational attribute - the no-stylesheet floor;
- * the mq-font-* class is the ceiling, where the real @font-face lives. */
-export const FONTS = {
+ * the mq-font-* class is the ceiling, where the real @font-face lives.
+ * Author-keyed tables like this one have no prototype, so `font=constructor`
+ * finds nothing instead of Object's own properties. */
+export const FONTS = Object.assign(Object.create(null), {
     // standard stacks
     sans: "sans-serif",
     serif: "serif",
@@ -145,7 +160,7 @@ export const FONTS = {
     rye: "Rye",
     bitcount: "Bitcount",
     quicksand: "Quicksand",
-};
+});
 /** Which grab-bag faces does this rendered HTML actually wear? Pure string
  * scan of the mq-font-* class contract - feed the result to
  * @cube-drone/marquee-fonts (externalFontFaces / inlineFontFaces) to deliver
@@ -180,12 +195,12 @@ const SCHEME_FONTS = [
 function sizeRung(value, inner) {
     return `<font class="mq-size-${value}" size="${value}">${inner}</font>`;
 }
-const MEDIA_SIZE_TOKENS = {
+const MEDIA_SIZE_TOKENS = Object.assign(Object.create(null), {
     small: "10rem",
     medium: "20rem",
     large: "32rem",
     full: "100%",
-};
+});
 /** Media width/height: a size token or a capped integer of pixels (SPEC.md,
  * "Media"). Anything else degrades to natural sizing. */
 function mediaSize(v) {
@@ -212,32 +227,35 @@ function infoToken(info) {
     return /^[A-Za-z0-9_+.#-]{1,64}$/.test(first) ? first : null;
 }
 // -- constructs
-function embed(target, alt, profile) {
-    const media = profile.media(target);
+function embed(target, alt, ctx) {
+    const media = ctx.profile.media(target);
     if (media !== null) {
-        const url = escapeAttr(media.url);
+        const url = ctx.attr(media.url);
+        const label = ctx.attr(alt);
+        const flag = ctx.flag;
         switch (media.kind) {
             case "image":
-                return `<img class="mq-embed" src="${url}" alt="${escapeAttr(alt)}" loading="lazy">`;
+                return `<img class="mq-embed" src="${url}" alt="${label}" loading="lazy"${ctx.void}`;
             case "audio":
-                return `<audio class="mq-embed" controls src="${url}" aria-label="${escapeAttr(alt)}"></audio>`;
+                return `<audio class="mq-embed"${flag("controls")} src="${url}" aria-label="${label}"></audio>`;
             case "video":
                 return media.loop === true
-                    ? `<video class="mq-embed" autoplay loop muted playsinline src="${url}" aria-label="${escapeAttr(alt)}"></video>`
-                    : `<video class="mq-embed" controls src="${url}" aria-label="${escapeAttr(alt)}"></video>`;
+                    ? `<video class="mq-embed"${flag("autoplay")}${flag("loop")}${flag("muted")}${flag("playsinline")} src="${url}" aria-label="${label}"></video>`
+                    : `<video class="mq-embed"${flag("controls")} src="${url}" aria-label="${label}"></video>`;
         }
     }
     // The contractual shrug applied to media: degrade to a labeled link, or
     // to inert text when the scheme is out of policy.
-    const label = escapeText(`[${alt === "" ? target : alt}]`);
-    return profile.linkAllowed(target)
-        ? `<a class="mq-embed-fallback" href="${escapeAttr(target)}">${label}</a>`
+    const label = ctx.text(`[${alt === "" ? target : alt}]`);
+    return ctx.profile.linkAllowed(target)
+        ? `<a class="mq-embed-fallback" href="${href(target, ctx)}">${label}</a>`
         : `<span class="mq-embed-fallback">${label}</span>`;
 }
 const TURBOLINK_LEVELS = new Set(["full", "title", "bare"]);
-function turbolink(target, levelAttr, profile) {
+function turbolink(target, levelAttr, ctx) {
+    const { profile } = ctx;
     if (!profile.linkAllowed(target)) {
-        return `<p class="mq-turbolink">${escapeText(target)}</p>`;
+        return `<p class="mq-turbolink">${ctx.text(target)}</p>`;
     }
     const level = levelAttr !== undefined && TURBOLINK_LEVELS.has(levelAttr)
         ? levelAttr
@@ -247,19 +265,21 @@ function turbolink(target, levelAttr, profile) {
         if (rich !== null) {
             // Enrichment augments, never replaces: the wrapper itself carries the
             // original link, so no plugin can eat it - not even by accident.
-            return `<div class="mq-turbolink mq-turbolink-rich">${rich}<a class="mq-turbolink-source" href="${escapeAttr(target)}">${escapeText(target)}</a></div>`;
+            return `<div class="mq-turbolink mq-turbolink-rich">${rich}<a class="mq-turbolink-source" href="${href(target, ctx)}">${ctx.text(target)}</a></div>`;
         }
     }
     // The contractual floor: a plain link, always reachable.
-    return `<p class="mq-turbolink"><a href="${escapeAttr(target)}">${escapeText(target)}</a></p>`;
+    return `<p class="mq-turbolink"><a href="${href(target, ctx)}">${ctx.text(target)}</a></p>`;
 }
 /** A resolved URL made safe for a CSS url("...") token: encodeURI handles
  * whitespace, controls, backslashes, and double quotes; quotes and parens
  * that encodeURI deliberately leaves are percent-encoded on top, so the
  * value can never terminate the url() or the declaration - author bytes
  * must not write CSS, even inside their own style attribute. */
+// encodeURI throws on a lone surrogate; an embedder's media() may pass one.
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
 function cssUrl(url) {
-    return encodeURI(url).replaceAll("'", "%27").replaceAll("(", "%28").replaceAll(")", "%29");
+    return encodeURI(url.replace(LONE_SURROGATE, "\uFFFD")).replaceAll("'", "%27").replaceAll("(", "%28").replaceAll(")", "%29");
 }
 /** Style knobs on a block node: validated values into --mq-* slots; the
  * stylesheet owns which CSS property each slot feeds. `background` takes a
@@ -290,9 +310,12 @@ function styleVarList(attrs, profile) {
     }
     return vars.join(";");
 }
-function styleVars(attrs, profile) {
-    const list = styleVarList(attrs, profile);
-    return list === "" ? "" : ` style="${list}"`;
+/** The style attribute, attribute-escaped like any other: the browser
+ * decodes character references before CSS sees the value, so a raw `&apos;`
+ * in a tile URL would otherwise close the url() and write CSS. */
+function styleVars(attrs, ctx) {
+    const list = styleVarList(attrs, ctx.profile);
+    return list === "" ? "" : ` style="${ctx.attr(list)}"`;
 }
 /** The visual identity a layout container (:::page / :::section) wears -
  * its scheme/font classes and validated style knobs - as bare class/style
@@ -315,14 +338,13 @@ function fontClass(attrs) {
 }
 function directive(name, attrs, nodes, ctx) {
     const { profile } = ctx;
-    // The profile hook sees the children rendered; built-ins that lay their
-    // children out themselves (table, stack) render them again, so rewind the
-    // aside numbering first - or a note inside counts twice.
-    const saved = { n: ctx.note.n, pending: [...ctx.note.pending] };
-    const rewind = () => {
-        ctx.note.n = saved.n;
-        ctx.note.pending = [...saved.pending];
-    };
+    // Built-ins that lay their children out themselves (table, stack) probe
+    // the hook (it claims on name and attrs alone) instead of rendering the
+    // children for it: rendering them twice per level is exponential in
+    // nesting, and a note inside would count twice.
+    if ((name === "table" || name === "stack") && profile.directive(name, attrs, "") === null) {
+        return name === "table" ? renderTable(attrs, nodes, ctx) : renderStack(attrs, nodes, ctx);
+    }
     const inner = children(nodes, ctx);
     const custom = profile.directive(name, attrs, inner);
     if (custom !== null) {
@@ -335,16 +357,16 @@ function directive(name, attrs, nodes, ctx) {
             return inner;
         case "page": {
             const layout = isToken(attrs["layout"]) ? ` mq-layout-${attrs["layout"]}` : "";
-            return `<div class="mq-page${layout}${schemeClass(attrs)}${fontClass(attrs)}"${styleVars(attrs, profile)}>${inner}</div>`;
+            return `<div class="mq-page${layout}${schemeClass(attrs)}${fontClass(attrs)}"${styleVars(attrs, ctx)}>${inner}</div>`;
         }
         case "section": {
             const slot = isToken(attrs["slot"]) ? ` data-slot="${attrs["slot"]}"` : "";
-            return `<section class="mq-section${schemeClass(attrs)}${fontClass(attrs)}"${slot}${styleVars(attrs, profile)}>${inner}</section>`;
+            return `<section class="mq-section${schemeClass(attrs)}${fontClass(attrs)}"${slot}${styleVars(attrs, ctx)}>${inner}</section>`;
         }
         case "turbolink": {
             const target = attrs["target"];
             if (target !== undefined) {
-                return turbolink(target, attrs["level"], profile);
+                return turbolink(target, attrs["level"], ctx);
             }
             break; // malformed use: fall through to the placeholder
         }
@@ -361,16 +383,10 @@ function directive(name, attrs, nodes, ctx) {
             const style = vars.length === 0 ? "" : ` style="${vars.join(";")}"`;
             return `<div class="mq-media"${style}>${inner}</div>`;
         }
-        case "table":
-            rewind();
-            return renderTable(attrs, nodes, ctx);
-        case "stack":
-            rewind();
-            return renderStack(attrs, nodes, ctx);
         case "layer":
             // Outside a stack a layer is just a section-like container: its style
             // knobs apply, place/backing mean nothing.
-            return `<div class="mq-layer${schemeClass(attrs)}${fontClass(attrs)}"${styleVars(attrs, profile)}>${inner}</div>`;
+            return `<div class="mq-layer${schemeClass(attrs)}${fontClass(attrs)}"${styleVars(attrs, ctx)}>${inner}</div>`;
         case "center":
         case "right":
         case "left":
@@ -397,10 +413,10 @@ function directive(name, attrs, nodes, ctx) {
             // differential-rendering hazard); role=base marks the common ancestor.
             const head = [];
             if (attrs["label"] !== undefined) {
-                head.push(`<span class="mq-variant-label">${escapeText(attrs["label"])}</span>`);
+                head.push(`<span class="mq-variant-label">${ctx.text(attrs["label"])}</span>`);
             }
             if (attrs["when"] !== undefined) {
-                head.push(`<span class="mq-variant-when">${escapeText(attrs["when"])}</span>`);
+                head.push(`<span class="mq-variant-when">${ctx.text(attrs["when"])}</span>`);
             }
             const cls = attrs["role"] === "base" ? "mq-variant mq-variant-base" : "mq-variant";
             const headHtml = head.length === 0 ? "" : `<div class="mq-variant-head">${head.join(" ")}</div>`;
@@ -411,8 +427,8 @@ function directive(name, attrs, nodes, ctx) {
     // that something wrapped them; a leaf renders the inert placeholder.
     // Never eat authored content.
     return nodes.length > 0
-        ? `<div class="mq-unknown" data-directive="${escapeAttr(name)}">${inner}</div>`
-        : `<div class="mq-placeholder" data-directive="${escapeAttr(name)}"></div>`;
+        ? `<div class="mq-unknown" data-directive="${ctx.attr(name)}">${inner}</div>`
+        : `<div class="mq-placeholder" data-directive="${ctx.attr(name)}"></div>`;
 }
 /** :::table (SPEC.md, "Tables"): each paragraph child is a row; a row's
  * cells are its top-level `[c]` spans, and loose inline content between
@@ -466,13 +482,13 @@ const PLACES = new Set([
     "fill", "top-left", "top", "top-right", "left", "center", "right", "bottom-left", "bottom", "bottom-right",
 ]);
 /** The `aspect` vocabulary as CSS aspect-ratio values. */
-const STACK_ASPECTS = {
+const STACK_ASPECTS = Object.assign(Object.create(null), {
     "16:9": "16/9",
     "4:3": "4/3",
     "3:2": "3/2",
     "1:1": "1/1",
     card: "5/7",
-};
+});
 /** :::stack (SPEC.md, "Stacks"): every direct child is a layer, source order
  * is z-order. The stylesheet puts every layer in one grid cell, so the box
  * is as big as its biggest layer needs and paint order is DOM order: no
@@ -512,7 +528,7 @@ function renderLayer(node, ctx) {
         ? " mq-layer-cover"
         : "";
     const inner = children(content, ctx);
-    return `<div class="mq-layer mq-place-${place}${backing}${cover}${schemeClass(attrs)}${fontClass(attrs)}"${styleVars(attrs, ctx.profile)}>${inner}</div>`;
+    return `<div class="mq-layer mq-place-${place}${backing}${cover}${schemeClass(attrs)}${fontClass(attrs)}"${styleVars(attrs, ctx)}>${inner}</div>`;
 }
 /** Effect/typographic spans. The `<font>` tag is deliberate: presentational
  * attributes are outside CSP's jurisdiction and are implemented by the
@@ -520,19 +536,19 @@ function renderLayer(node, ctx) {
  * attributes - the floor of the degradation ladder. The --mq-color slot is
  * the stylesheet-era ceiling on the same element. */
 function span(name, attrs, nodes, ctx) {
-    const saved = { n: ctx.note.n, pending: [...ctx.note.pending] };
+    // Probe first (the hook claims on name and attrs alone): a split renders
+    // its children itself, and rendering them here as well doubled the work at
+    // every nesting level - exponential in a document anyone can sync.
+    const look = ctx.profile.span(name, attrs, "") === null ? effectLook(name, attrs, nodes) : null;
+    if (look !== null && look.units !== null) {
+        return renderEffect(name, look, nodes, "", ctx);
+    }
     const inner = children(nodes, ctx);
     const custom = ctx.profile.span(name, attrs, inner);
     if (custom !== null) {
         return custom;
     }
-    const look = effectLook(name, attrs, nodes);
     if (look !== null) {
-        if (look.units !== null) {
-            // A split renders its children again: rewind the aside numbering.
-            ctx.note.n = saved.n;
-            ctx.note.pending = [...saved.pending];
-        }
         return renderEffect(name, look, nodes, inner, ctx);
     }
     switch (name) {
@@ -562,7 +578,7 @@ function span(name, attrs, nodes, ctx) {
             const value = attrs["font"];
             const face = value !== undefined ? FONTS[value] : undefined;
             if (face !== undefined) {
-                return `<font class="mq-font-${value}" face="${escapeAttr(face)}">${inner}</font>`;
+                return `<font class="mq-font-${value}" face="${ctx.attr(face)}">${inner}</font>`;
             }
             return inner; // not on the list: the words survive in their own clothes
         }
@@ -600,8 +616,8 @@ function span(name, attrs, nodes, ctx) {
 // -- effects: the look (classes, knobs, per-unit split) comes from
 // effects.ts, shared with every other surface that draws effects.
 function renderEffect(name, look, nodes, inner, ctx) {
-    const data = look.data.map(([k, v]) => ` data-${k}="${escapeAttr(v)}"`).join("");
-    const style = look.vars.length === 0 ? "" : ` style="${look.vars.map(([k, v]) => `${k}:${escapeAttr(v)}`).join(";")}"`;
+    const data = look.data.map(([k, v]) => ` data-${k}="${ctx.attr(v)}"`).join("");
+    const style = look.vars.length === 0 ? "" : ` style="${look.vars.map(([k, v]) => `${k}:${ctx.attr(v)}`).join(";")}"`;
     if (name === "marquee") {
         return `<span class="${look.className}"${data}${style}><span class="mq-marquee-inner">${inner}</span></span>`;
     }
@@ -614,9 +630,9 @@ function renderEffect(name, look, nodes, inner, ctx) {
 function splitRender(nodes, ctx, look) {
     const pieces = (list) => list
         .map((p) => p.kind === "text"
-        ? escapeText(p.text)
+        ? ctx.text(p.text)
         : p.kind === "unit"
-            ? `<span class="mq-l" style="--mq-o:${p.offset}">${escapeText(p.text)}</span>`
+            ? `<span class="mq-l" style="--mq-o:${p.offset}">${ctx.text(p.text)}</span>`
             : `<span class="mq-w">${pieces(p.pieces)}</span>`)
         .join("");
     let out = "";
@@ -646,3 +662,21 @@ export function escapeText(s) {
 export function escapeAttr(s) {
     return escapeText(s).replaceAll('"', "&quot;");
 }
+/** Characters XML 1.0 forbids outright - even as a numeric reference: the C0
+ * controls bar tab, newline, and return, the noncharacters U+FFFE/U+FFFF,
+ * and (a JS string can hold one) a lone surrogate. HTML parsers shrug these
+ * off; an XML parser refuses the whole page, so XHTML output carries U+FFFD
+ * in their place. */
+const XML_FORBIDDEN = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\uFFFE\uFFFF]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+function escapeTextXml(s) {
+    return escapeText(s).replace(XML_FORBIDDEN, "\uFFFD");
+}
+/** An XML parser normalizes whitespace in an attribute value to spaces, so a
+ * newline in alt text survives only as a character reference. */
+function escapeAttrXml(s) {
+    return escapeTextXml(s)
+        .replaceAll('"', "&quot;")
+        .replaceAll("\t", "&#9;")
+        .replaceAll("\n", "&#10;")
+        .replaceAll("\r", "&#13;");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-drone/marquee-html-renderer",
-  "version": "0.9.2",
+  "version": "0.10.0",
   "description": "Reference static HTML renderer for the Marquee markup language",
   "license": "MPL-2.0",
   "repository": {
@@ -35,13 +35,14 @@
     "prepack": "npm run build"
   },
   "dependencies": {
-    "@cube-drone/marquee-parser": "^0.9.2"
+    "@cube-drone/marquee-parser": "^0.10.0"
   },
   "devDependencies": {
-    "@cube-drone/marquee-css": "^0.9.2",
-    "@cube-drone/marquee-fonts": "^0.9.2",
-    "@cube-drone/marquee-turbolink": "^0.9.2",
+    "@cube-drone/marquee-css": "^0.10.0",
+    "@cube-drone/marquee-fonts": "^0.10.0",
+    "@cube-drone/marquee-turbolink": "^0.10.0",
     "@types/node": "^24.0.0",
+    "saxes": "^6.0.0",
     "typescript": "^5.9.0"
   }
 }

package/src/index.ts

@@ -6,16 +6,17 @@
 // tap-to-skip) belong to the interactive renderer.
 
 import { parse } from "@cube-drone/marquee-parser";
-import { render } from "./render.ts";
+import { render, type RenderOptions } from "./render.ts";
 import type { Profile } from "./profile.ts";
 
-export { render, escapeText, escapeAttr, FONTS, usedFontTokens, containerLook } from "./render.ts";
+export { render, type RenderOptions, escapeText, escapeAttr, FONTS, usedFontTokens, containerLook } from "./render.ts";
 export { bareWebProfile } from "./profile.ts";
 export { EFFECT_NAMES, effectLook, splitPieces, type EffectLook, type EffectUnit, type SplitPiece } from "./effects.ts";
 export type { EmojiResolution, Profile, MediaResolution, TurbolinkLevel } from "./profile.ts";
 
 /** Parse and render in one step. Throws UnsupportedVersionError for unknown
- * dialect versions, exactly as the parser does. */
-export function renderMarquee(source: string, profile?: Profile): string {
-  return render(parse(source), profile);
+ * dialect versions, exactly as the parser does. `{ output: "xhtml" }` for a
+ * page that must be well-formed XML, like an ePub's. */
+export function renderMarquee(source: string, profile?: Profile, options?: RenderOptions): string {
+  return render(parse(source), profile, options);
 }

package/src/profile.ts

@@ -23,6 +23,14 @@ export interface Profile {
   /** May this target become a hyperlink? Disallowed links render their
    * children without an anchor (content survives, capability doesn't). */
   linkAllowed(target: string): boolean;
+  /** Where an allowed link points: null (or no method) keeps the target as
+   * written; a string is the address the anchor uses instead (a note's
+   * chapter inside an ePub, a file's path inside an export). Asked only after
+   * `linkAllowed` says yes - a refused link stays refused - and for every
+   * anchor the renderer draws from an author target: links, turbolinks, and
+   * the fallback link of an embed. The visible text stays the author's;
+   * `turbolink` and `media` still see the original target. */
+  linkTarget?(target: string): string | null;
   /** Resolve an embed target to a media kind, or null for the inert
    * fallback. The kind is resolved at render time (SPEC.md, "Media"). */
   media(target: string): MediaResolution | null;
@@ -54,6 +62,9 @@ export interface Profile {
    * - Place the children: a claiming answer MUST include `renderedChildren`
    *   (already-escaped HTML) or a known substitute for them - the shrug's
    *   never-eat-content rule binds embedder vocabulary too.
+   * - Match the output: a profile rendered with `{ output: "xhtml" }` must
+   *   return well-formed XHTML (here and in `span` and `turbolink`) - the
+   *   renderer places embedder HTML as given and can't rewrite it.
    * Embedder-first: a claim on a name the language defines wins. */
   directive(name: string, attrs: Attrs, renderedChildren: string): string | null;
   /** Embedder span vocabulary - the inline twin of `directive`
@@ -65,15 +76,21 @@ export interface Profile {
 
 // Mirror of the Rust renderer's table (rust/html_renderer/src/profile.rs). `apng` and
 // `opus` joined 2026-09-03: ringtome mints both and they rendered as the placeholder.
-const MEDIA_KINDS: Record<string, MediaResolution["kind"]> = {
+const MEDIA_KINDS: Record<string, MediaResolution["kind"]> = Object.assign(Object.create(null), {
   png: "image", jpg: "image", jpeg: "image", gif: "image", webp: "image",
   avif: "image", apng: "image", svg: "image",
   mp3: "audio", ogg: "audio", opus: "audio", wav: "audio", flac: "audio", m4a: "audio",
   mp4: "video", webm: "video",
-};
+});
+
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
 
+// Read the scheme the way a browser will: the URL parser strips leading C0
+// controls and spaces and drops tabs/newlines anywhere, so
+// "\x01javascript:" and "java\tscript:" are javascript: URLs. Targets with
+// controls are refused outright (see linkAllowed); leading spaces are skipped.
 function scheme(target: string): string | null {
-  const m = /^([A-Za-z][A-Za-z0-9+.-]*):/.exec(target);
+  const m = /^ *([A-Za-z][A-Za-z0-9+.-]*):/.exec(target);
   return m ? m[1]!.toLowerCase() : null;
 }
 
@@ -82,6 +99,11 @@ function scheme(target: string): string | null {
  * degrades inert. */
 export const bareWebProfile: Profile = {
   linkAllowed(target) {
+    // A lone surrogate isn't a URL anyone can write; refusing it here keeps
+    // every anchor and media path well-formed.
+    if (/[\x00-\x1f\x7f]/.test(target) || LONE_SURROGATE.test(target)) {
+      return false;
+    }
     const s = scheme(target);
     return s === null || s === "http" || s === "https" || s === "mailto";
   },

package/src/render.ts

@@ -8,16 +8,51 @@ import type { Attrs, Node } from "@cube-drone/marquee-parser";
 import { bareWebProfile, type Profile, type TurbolinkLevel } from "./profile.ts";
 import { effectLook, splitPieces, type EffectLook, type SplitPiece } from "./effects.ts";
 
-/** Render state: the profile, plus the one piece of cross-block
- * coordination the renderer owns - aside numbering (sequential through the
- * document) and the pending notes that flush after the triggering block. */
+export interface RenderOptions {
+  /** Which serialization to write. "html" (the default) is HTML5 for a web
+   * page: void elements unclosed (`<br>`), boolean attributes bare
+   * (`controls`). "xhtml" is well-formed XML for an ePub page or any XHTML
+   * document: void elements close themselves (`<br/>`), every attribute
+   * carries a quoted value, the only entities are XML's own, and characters
+   * XML forbids become U+FFFD. Same elements, same classes, same words.
+   * Embedder vocabulary is placed as given, so a profile used with "xhtml"
+   * must return XHTML too (see `Profile.directive`). */
+  output?: "html" | "xhtml";
+}
+
+/** Render state: the profile and the output spelling, plus the one piece of
+ * cross-block coordination the renderer owns - aside numbering (sequential
+ * through the document) and the pending notes that flush after the
+ * triggering block. */
 interface Ctx {
   profile: Profile;
+  /** Escape author text / an attribute value for the output spelling. */
+  text: (s: string) => string;
+  attr: (s: string) => string;
+  /** The end of a void element's start tag. */
+  void: string;
+  /** A boolean attribute with its leading space: bare in HTML, `name="name"`
+   * in XHTML (XML has no attribute without a value). */
+  flag: (name: string) => string;
   note: { n: number; pending: string[] };
 }
 
-export function render(node: Node, profile: Profile = bareWebProfile): string {
-  return renderNode(node, { profile, note: { n: 0, pending: [] } });
+export function render(node: Node, profile: Profile = bareWebProfile, options: RenderOptions = {}): string {
+  const xhtml = options.output === "xhtml";
+  const ctx: Ctx = {
+    profile,
+    text: xhtml ? escapeTextXml : escapeText,
+    attr: xhtml ? escapeAttrXml : escapeAttr,
+    void: xhtml ? "/>" : ">",
+    flag: xhtml ? (name) => ` ${name}="${name}"` : (name) => ` ${name}`,
+    note: { n: 0, pending: [] },
+  };
+  return renderNode(node, ctx);
+}
+
+/** The href an allowed link wears: the profile's rewrite, or the target. */
+function href(target: string, ctx: Ctx): string {
+  return ctx.attr(ctx.profile.linkTarget?.(target) ?? target);
 }
 
 /** Asides render just below the paragraph (or heading) that triggered
@@ -49,8 +84,8 @@ function renderNode(node: Node, ctx: Ctx): string {
     }
     case "code_block": {
       const lang = infoToken(node.info);
-      const cls = lang === null ? "" : ` class="language-${escapeAttr(lang)}"`;
-      const text = node.text === "" ? "" : `${escapeText(node.text)}\n`;
+      const cls = lang === null ? "" : ` class="language-${ctx.attr(lang)}"`;
+      const text = node.text === "" ? "" : `${ctx.text(node.text)}\n`;
       return `<pre class="mq-code"><code${cls}>${text}</code></pre>`;
     }
     case "blockquote":
@@ -62,15 +97,15 @@ function renderNode(node: Node, ctx: Ctx): string {
     case "list_item":
       return `<li>${children(node.children, ctx)}</li>`;
     case "thematic_break":
-      return "<hr>";
+      return `<hr${ctx.void}`;
     case "directive":
       return directive(node.name, node.attrs, node.children, ctx);
     case "invalid_directive":
-      return `<div class="mq-invalid" data-reason="${escapeAttr(node.reason)}"></div>`;
+      return `<div class="mq-invalid" data-reason="${ctx.attr(node.reason)}"></div>`;
     case "comment":
       return ""; // the anti-shrug: correct rendering is absence
     case "text":
-      return escapeText(node.value);
+      return ctx.text(node.value);
     case "emphasis":
       return `<em>${children(node.children, ctx)}</em>`;
     case "strong":
@@ -78,29 +113,29 @@ function renderNode(node: Node, ctx: Ctx): string {
     case "strikethrough":
       return `<del>${children(node.children, ctx)}</del>`;
     case "code_span":
-      return `<code>${escapeText(node.text)}</code>`;
+      return `<code>${ctx.text(node.text)}</code>`;
     case "link": {
       const inner = children(node.children, ctx);
       return ctx.profile.linkAllowed(node.target)
-        ? `<a href="${escapeAttr(node.target)}">${inner}</a>`
+        ? `<a href="${href(node.target, ctx)}">${inner}</a>`
         : `<span class="mq-blocked">${inner}</span>`;
     }
     case "embed":
-      return embed(node.target, node.alt, ctx.profile);
+      return embed(node.target, node.alt, ctx);
     case "turbolink":
-      return turbolink(node.target, undefined, ctx.profile);
+      return turbolink(node.target, undefined, ctx);
     case "span":
       return span(node.name, node.attrs, node.children, ctx);
     case "emoji": {
       const resolved = ctx.profile.emoji(node.slug);
       if (resolved !== null && typeof resolved === "object") {
         const alt = resolved.alt ?? `:${node.slug}:`;
-        return `<img class="mq-emoji" src="${escapeAttr(resolved.image)}" alt="${escapeAttr(alt)}" loading="lazy">`;
+        return `<img class="mq-emoji" src="${ctx.attr(resolved.image)}" alt="${ctx.attr(alt)}" loading="lazy"${ctx.void}`;
       }
-      return escapeText(resolved ?? `:${node.slug}:`);
+      return ctx.text(resolved ?? `:${node.slug}:`);
     }
     case "hard_break":
-      return "<br>";
+      return `<br${ctx.void}`;
   }
 }
 
@@ -126,8 +161,10 @@ function isToken(v: string | undefined): v is string {
  * no files, and the grab bag - SIL OFL faces the embedder serves itself
  * (never a third-party CDN: fonts are a tracking vector, care-modes apply).
  * Values are the `face` presentational attribute - the no-stylesheet floor;
- * the mq-font-* class is the ceiling, where the real @font-face lives. */
-export const FONTS: Record<string, string> = {
+ * the mq-font-* class is the ceiling, where the real @font-face lives.
+ * Author-keyed tables like this one have no prototype, so `font=constructor`
+ * finds nothing instead of Object's own properties. */
+export const FONTS: Record<string, string> = Object.assign(Object.create(null), {
   // standard stacks
   sans: "sans-serif",
   serif: "serif",
@@ -165,7 +202,7 @@ export const FONTS: Record<string, string> = {
   rye: "Rye",
   bitcount: "Bitcount",
   quicksand: "Quicksand",
-};
+});
 
 /** Which grab-bag faces does this rendered HTML actually wear? Pure string
  * scan of the mq-font-* class contract - feed the result to
@@ -204,12 +241,12 @@ function sizeRung(value: string, inner: string): string {
   return `<font class="mq-size-${value}" size="${value}">${inner}</font>`;
 }
 
-const MEDIA_SIZE_TOKENS: Record<string, string> = {
+const MEDIA_SIZE_TOKENS: Record<string, string> = Object.assign(Object.create(null), {
   small: "10rem",
   medium: "20rem",
   large: "32rem",
   full: "100%",
-};
+});
 
 /** Media width/height: a size token or a capped integer of pixels (SPEC.md,
  * "Media"). Anything else degrades to natural sizing. */
@@ -240,34 +277,37 @@ function infoToken(info: string | undefined): string | null {
 
 // -- constructs
 
-function embed(target: string, alt: string, profile: Profile): string {
-  const media = profile.media(target);
+function embed(target: string, alt: string, ctx: Ctx): string {
+  const media = ctx.profile.media(target);
   if (media !== null) {
-    const url = escapeAttr(media.url);
+    const url = ctx.attr(media.url);
+    const label = ctx.attr(alt);
+    const flag = ctx.flag;
     switch (media.kind) {
       case "image":
-        return `<img class="mq-embed" src="${url}" alt="${escapeAttr(alt)}" loading="lazy">`;
+        return `<img class="mq-embed" src="${url}" alt="${label}" loading="lazy"${ctx.void}`;
       case "audio":
-        return `<audio class="mq-embed" controls src="${url}" aria-label="${escapeAttr(alt)}"></audio>`;
+        return `<audio class="mq-embed"${flag("controls")} src="${url}" aria-label="${label}"></audio>`;
       case "video":
         return media.loop === true
-          ? `<video class="mq-embed" autoplay loop muted playsinline src="${url}" aria-label="${escapeAttr(alt)}"></video>`
-          : `<video class="mq-embed" controls src="${url}" aria-label="${escapeAttr(alt)}"></video>`;
+          ? `<video class="mq-embed"${flag("autoplay")}${flag("loop")}${flag("muted")}${flag("playsinline")} src="${url}" aria-label="${label}"></video>`
+          : `<video class="mq-embed"${flag("controls")} src="${url}" aria-label="${label}"></video>`;
     }
   }
   // The contractual shrug applied to media: degrade to a labeled link, or
   // to inert text when the scheme is out of policy.
-  const label = escapeText(`[${alt === "" ? target : alt}]`);
-  return profile.linkAllowed(target)
-    ? `<a class="mq-embed-fallback" href="${escapeAttr(target)}">${label}</a>`
+  const label = ctx.text(`[${alt === "" ? target : alt}]`);
+  return ctx.profile.linkAllowed(target)
+    ? `<a class="mq-embed-fallback" href="${href(target, ctx)}">${label}</a>`
     : `<span class="mq-embed-fallback">${label}</span>`;
 }
 
 const TURBOLINK_LEVELS = new Set<TurbolinkLevel>(["full", "title", "bare"]);
 
-function turbolink(target: string, levelAttr: string | undefined, profile: Profile): string {
+function turbolink(target: string, levelAttr: string | undefined, ctx: Ctx): string {
+  const { profile } = ctx;
   if (!profile.linkAllowed(target)) {
-    return `<p class="mq-turbolink">${escapeText(target)}</p>`;
+    return `<p class="mq-turbolink">${ctx.text(target)}</p>`;
   }
   const level =
     levelAttr !== undefined && TURBOLINK_LEVELS.has(levelAttr as TurbolinkLevel)
@@ -278,11 +318,11 @@ function turbolink(target: string, levelAttr: string | undefined, profile: Profi
     if (rich !== null) {
       // Enrichment augments, never replaces: the wrapper itself carries the
       // original link, so no plugin can eat it - not even by accident.
-      return `<div class="mq-turbolink mq-turbolink-rich">${rich}<a class="mq-turbolink-source" href="${escapeAttr(target)}">${escapeText(target)}</a></div>`;
+      return `<div class="mq-turbolink mq-turbolink-rich">${rich}<a class="mq-turbolink-source" href="${href(target, ctx)}">${ctx.text(target)}</a></div>`;
     }
   }
   // The contractual floor: a plain link, always reachable.
-  return `<p class="mq-turbolink"><a href="${escapeAttr(target)}">${escapeText(target)}</a></p>`;
+  return `<p class="mq-turbolink"><a href="${href(target, ctx)}">${ctx.text(target)}</a></p>`;
 }
 
 /** A resolved URL made safe for a CSS url("...") token: encodeURI handles
@@ -290,8 +330,11 @@ function turbolink(target: string, levelAttr: string | undefined, profile: Profi
  * that encodeURI deliberately leaves are percent-encoded on top, so the
  * value can never terminate the url() or the declaration - author bytes
  * must not write CSS, even inside their own style attribute. */
+// encodeURI throws on a lone surrogate; an embedder's media() may pass one.
+const LONE_SURROGATE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+
 function cssUrl(url: string): string {
-  return encodeURI(url).replaceAll("'", "%27").replaceAll("(", "%28").replaceAll(")", "%29");
+  return encodeURI(url.replace(LONE_SURROGATE, "\uFFFD")).replaceAll("'", "%27").replaceAll("(", "%28").replaceAll(")", "%29");
 }
 
 /** Style knobs on a block node: validated values into --mq-* slots; the
@@ -323,9 +366,12 @@ function styleVarList(attrs: Attrs, profile: Profile): string {
   return vars.join(";");
 }
 
-function styleVars(attrs: Attrs, profile: Profile): string {
-  const list = styleVarList(attrs, profile);
-  return list === "" ? "" : ` style="${list}"`;
+/** The style attribute, attribute-escaped like any other: the browser
+ * decodes character references before CSS sees the value, so a raw `&apos;`
+ * in a tile URL would otherwise close the url() and write CSS. */
+function styleVars(attrs: Attrs, ctx: Ctx): string {
+  const list = styleVarList(attrs, ctx.profile);
+  return list === "" ? "" : ` style="${ctx.attr(list)}"`;
 }
 
 /** The visual identity a layout container (:::page / :::section) wears -
@@ -352,14 +398,13 @@ function fontClass(attrs: Attrs): string {
 
 function directive(name: string, attrs: Attrs, nodes: Node[], ctx: Ctx): string {
   const { profile } = ctx;
-  // The profile hook sees the children rendered; built-ins that lay their
-  // children out themselves (table, stack) render them again, so rewind the
-  // aside numbering first - or a note inside counts twice.
-  const saved = { n: ctx.note.n, pending: [...ctx.note.pending] };
-  const rewind = () => {
-    ctx.note.n = saved.n;
-    ctx.note.pending = [...saved.pending];
-  };
+  // Built-ins that lay their children out themselves (table, stack) probe
+  // the hook (it claims on name and attrs alone) instead of rendering the
+  // children for it: rendering them twice per level is exponential in
+  // nesting, and a note inside would count twice.
+  if ((name === "table" || name === "stack") && profile.directive(name, attrs, "") === null) {
+    return name === "table" ? renderTable(attrs, nodes, ctx) : renderStack(attrs, nodes, ctx);
+  }
   const inner = children(nodes, ctx);
   const custom = profile.directive(name, attrs, inner);
   if (custom !== null) {
@@ -372,16 +417,16 @@ function directive(name: string, attrs: Attrs, nodes: Node[], ctx: Ctx): string
       return inner;
     case "page": {
       const layout = isToken(attrs["layout"]) ? ` mq-layout-${attrs["layout"]}` : "";
-      return `<div class="mq-page${layout}${schemeClass(attrs)}${fontClass(attrs)}"${styleVars(attrs, profile)}>${inner}</div>`;
+      return `<div class="mq-page${layout}${schemeClass(attrs)}${fontClass(attrs)}"${styleVars(attrs, ctx)}>${inner}</div>`;
     }
     case "section": {
       const slot = isToken(attrs["slot"]) ? ` data-slot="${attrs["slot"]}"` : "";
-      return `<section class="mq-section${schemeClass(attrs)}${fontClass(attrs)}"${slot}${styleVars(attrs, profile)}>${inner}</section>`;
+      return `<section class="mq-section${schemeClass(attrs)}${fontClass(attrs)}"${slot}${styleVars(attrs, ctx)}>${inner}</section>`;
     }
     case "turbolink": {
       const target = attrs["target"];
       if (target !== undefined) {
-        return turbolink(target, attrs["level"], profile);
+        return turbolink(target, attrs["level"], ctx);
       }
       break; // malformed use: fall through to the placeholder
     }
@@ -398,16 +443,10 @@ function directive(name: string, attrs: Attrs, nodes: Node[], ctx: Ctx): string
       const style = vars.length === 0 ? "" : ` style="${vars.join(";")}"`;
       return `<div class="mq-media"${style}>${inner}</div>`;
     }
-    case "table":
-      rewind();
-      return renderTable(attrs, nodes, ctx);
-    case "stack":
-      rewind();
-      return renderStack(attrs, nodes, ctx);
     case "layer":
       // Outside a stack a layer is just a section-like container: its style
       // knobs apply, place/backing mean nothing.
-      return `<div class="mq-layer${schemeClass(attrs)}${fontClass(attrs)}"${styleVars(attrs, profile)}>${inner}</div>`;
+      return `<div class="mq-layer${schemeClass(attrs)}${fontClass(attrs)}"${styleVars(attrs, ctx)}>${inner}</div>`;
     case "center":
     case "right":
     case "left":
@@ -434,10 +473,10 @@ function directive(name: string, attrs: Attrs, nodes: Node[], ctx: Ctx): string
       // differential-rendering hazard); role=base marks the common ancestor.
       const head: string[] = [];
       if (attrs["label"] !== undefined) {
-        head.push(`<span class="mq-variant-label">${escapeText(attrs["label"])}</span>`);
+        head.push(`<span class="mq-variant-label">${ctx.text(attrs["label"])}</span>`);
       }
       if (attrs["when"] !== undefined) {
-        head.push(`<span class="mq-variant-when">${escapeText(attrs["when"])}</span>`);
+        head.push(`<span class="mq-variant-when">${ctx.text(attrs["when"])}</span>`);
       }
       const cls = attrs["role"] === "base" ? "mq-variant mq-variant-base" : "mq-variant";
       const headHtml = head.length === 0 ? "" : `<div class="mq-variant-head">${head.join(" ")}</div>`;
@@ -448,8 +487,8 @@ function directive(name: string, attrs: Attrs, nodes: Node[], ctx: Ctx): string
   // that something wrapped them; a leaf renders the inert placeholder.
   // Never eat authored content.
   return nodes.length > 0
-    ? `<div class="mq-unknown" data-directive="${escapeAttr(name)}">${inner}</div>`
-    : `<div class="mq-placeholder" data-directive="${escapeAttr(name)}"></div>`;
+    ? `<div class="mq-unknown" data-directive="${ctx.attr(name)}">${inner}</div>`
+    : `<div class="mq-placeholder" data-directive="${ctx.attr(name)}"></div>`;
 }
 
 /** :::table (SPEC.md, "Tables"): each paragraph child is a row; a row's
@@ -507,13 +546,13 @@ const PLACES = new Set([
 ]);
 
 /** The `aspect` vocabulary as CSS aspect-ratio values. */
-const STACK_ASPECTS: Record<string, string> = {
+const STACK_ASPECTS: Record<string, string> = Object.assign(Object.create(null), {
   "16:9": "16/9",
   "4:3": "4/3",
   "3:2": "3/2",
   "1:1": "1/1",
   card: "5/7",
-};
+});
 
 /** :::stack (SPEC.md, "Stacks"): every direct child is a layer, source order
  * is z-order. The stylesheet puts every layer in one grid cell, so the box
@@ -556,7 +595,7 @@ function renderLayer(node: Node, ctx: Ctx): string {
       ? " mq-layer-cover"
       : "";
   const inner = children(content, ctx);
-  return `<div class="mq-layer mq-place-${place}${backing}${cover}${schemeClass(attrs)}${fontClass(attrs)}"${styleVars(attrs, ctx.profile)}>${inner}</div>`;
+  return `<div class="mq-layer mq-place-${place}${backing}${cover}${schemeClass(attrs)}${fontClass(attrs)}"${styleVars(attrs, ctx)}>${inner}</div>`;
 }
 
 /** Effect/typographic spans. The `<font>` tag is deliberate: presentational
@@ -565,19 +604,19 @@ function renderLayer(node: Node, ctx: Ctx): string {
  * attributes - the floor of the degradation ladder. The --mq-color slot is
  * the stylesheet-era ceiling on the same element. */
 function span(name: string, attrs: Attrs, nodes: Node[], ctx: Ctx): string {
-  const saved = { n: ctx.note.n, pending: [...ctx.note.pending] };
+  // Probe first (the hook claims on name and attrs alone): a split renders
+  // its children itself, and rendering them here as well doubled the work at
+  // every nesting level - exponential in a document anyone can sync.
+  const look = ctx.profile.span(name, attrs, "") === null ? effectLook(name, attrs, nodes) : null;
+  if (look !== null && look.units !== null) {
+    return renderEffect(name, look, nodes, "", ctx);
+  }
   const inner = children(nodes, ctx);
   const custom = ctx.profile.span(name, attrs, inner);
   if (custom !== null) {
     return custom;
   }
-  const look = effectLook(name, attrs, nodes);
   if (look !== null) {
-    if (look.units !== null) {
-      // A split renders its children again: rewind the aside numbering.
-      ctx.note.n = saved.n;
-      ctx.note.pending = [...saved.pending];
-    }
     return renderEffect(name, look, nodes, inner, ctx);
   }
   switch (name) {
@@ -607,7 +646,7 @@ function span(name: string, attrs: Attrs, nodes: Node[], ctx: Ctx): string {
       const value = attrs["font"];
       const face = value !== undefined ? FONTS[value] : undefined;
       if (face !== undefined) {
-        return `<font class="mq-font-${value}" face="${escapeAttr(face)}">${inner}</font>`;
+        return `<font class="mq-font-${value}" face="${ctx.attr(face)}">${inner}</font>`;
       }
       return inner; // not on the list: the words survive in their own clothes
     }
@@ -647,8 +686,8 @@ function span(name: string, attrs: Attrs, nodes: Node[], ctx: Ctx): string {
 // effects.ts, shared with every other surface that draws effects.
 
 function renderEffect(name: string, look: EffectLook, nodes: Node[], inner: string, ctx: Ctx): string {
-  const data = look.data.map(([k, v]) => ` data-${k}="${escapeAttr(v)}"`).join("");
-  const style = look.vars.length === 0 ? "" : ` style="${look.vars.map(([k, v]) => `${k}:${escapeAttr(v)}`).join(";")}"`;
+  const data = look.data.map(([k, v]) => ` data-${k}="${ctx.attr(v)}"`).join("");
+  const style = look.vars.length === 0 ? "" : ` style="${look.vars.map(([k, v]) => `${k}:${ctx.attr(v)}`).join(";")}"`;
   if (name === "marquee") {
     return `<span class="${look.className}"${data}${style}><span class="mq-marquee-inner">${inner}</span></span>`;
   }
@@ -664,9 +703,9 @@ function splitRender(nodes: Node[], ctx: Ctx, look: EffectLook): string {
     list
       .map((p) =>
         p.kind === "text"
-          ? escapeText(p.text)
+          ? ctx.text(p.text)
           : p.kind === "unit"
-            ? `<span class="mq-l" style="--mq-o:${p.offset}">${escapeText(p.text)}</span>`
+            ? `<span class="mq-l" style="--mq-o:${p.offset}">${ctx.text(p.text)}</span>`
             : `<span class="mq-w">${pieces(p.pieces)}</span>`,
       )
       .join("");
@@ -696,3 +735,24 @@ export function escapeText(s: string): string {
 export function escapeAttr(s: string): string {
   return escapeText(s).replaceAll('"', "&quot;");
 }
+
+/** Characters XML 1.0 forbids outright - even as a numeric reference: the C0
+ * controls bar tab, newline, and return, the noncharacters U+FFFE/U+FFFF,
+ * and (a JS string can hold one) a lone surrogate. HTML parsers shrug these
+ * off; an XML parser refuses the whole page, so XHTML output carries U+FFFD
+ * in their place. */
+const XML_FORBIDDEN = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\uFFFE\uFFFF]|[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/g;
+
+function escapeTextXml(s: string): string {
+  return escapeText(s).replace(XML_FORBIDDEN, "\uFFFD");
+}
+
+/** An XML parser normalizes whitespace in an attribute value to spaces, so a
+ * newline in alt text survives only as a character reference. */
+function escapeAttrXml(s: string): string {
+  return escapeTextXml(s)
+    .replaceAll('"', "&quot;")
+    .replaceAll("\t", "&#9;")
+    .replaceAll("\n", "&#10;")
+    .replaceAll("\r", "&#13;");
+}