@gjsify/adwaita-web 0.62.0 → 0.63.0

package/src/gtk-window.spec.ts

@@ -5,6 +5,8 @@
 // (gtkwindow.c:1274-1287).
 import { describe, expect, it } from '@gjsify/unit';
 
+import { driveWindowVectors, WINDOW_VECTORS, type WindowSubject } from '@gjsify/adwaita-core/conformance';
+
 import type { GtkWindow } from './elements/gtk-window.js';
 
 function mount(attrs: Record<string, string> = {}): { el: GtkWindow; host: HTMLElement } {
@@ -199,4 +201,124 @@ export const GtkWindowTest = async () => {
             host.remove();
         });
     });
+
+    // The element's native close contract is `preventDefault()`; a GTK handler "returns true". The
+    // adapter below is that mapping, and it also stops later listeners, which is what the handled
+    // accumulator does. So the "third never runs" row exercises the adapter plus the element's
+    // sequence, not DOM dispatch alone.
+    const windows = new Map<object, HTMLElement>();
+    const webSubject: WindowSubject = {
+        name: '<gtk-window>',
+        isOracle: false,
+        capabilities: { maximizable: true, observesFocus: true, hideOnClose: true },
+        create({ hideOnClose }) {
+            // Never in a page: not realized, which is GTK's state for a window before `present()`.
+            const el = document.createElement('gtk-window') as GtkWindow;
+            if (hideOnClose) el.setAttribute('hide-on-close', 'true');
+            el.append(document.createElement('button'), document.createElement('button'));
+            return el;
+        },
+        show(w) {
+            const host = document.createElement('div');
+            document.body.appendChild(host);
+            host.appendChild(w as GtkWindow);
+            windows.set(w, host);
+            (w as GtkWindow).present();
+        },
+        connect(w, signal, handler) {
+            (w as GtkWindow).addEventListener(signal, (event) => {
+                if (signal === 'close-request') {
+                    if (event.defaultPrevented) return;
+                    if (handler()) {
+                        event.preventDefault();
+                        event.stopImmediatePropagation();
+                    }
+                    return;
+                }
+                handler();
+            });
+            return 1;
+        },
+        close: (w) => void (w as GtkWindow).close(),
+        maximize: (w) => (w as GtkWindow).maximize(),
+        unmaximize: (w) => (w as GtkWindow).unmaximize(),
+        isMaximized: (w) => (w as GtkWindow).is_maximized(),
+        isVisible: (w) => (w as GtkWindow).isConnected && !(w as GtkWindow).hidden,
+        focusables: (w) => [...(w as GtkWindow).querySelectorAll('button')] as unknown as [Element, Element],
+        setFocus: (w, widget) => (w as GtkWindow).set_focus(widget as Element | null),
+        getFocus: (w) => (w as GtkWindow).get_focus(),
+    };
+    await driveWindowVectors(webSubject, { describe, it, expect }, WINDOW_VECTORS);
+    for (const host of windows.values()) host.remove();
+
+    await describe('<gtk-window> state members', async () => {
+        await it('a frame that was never connected is not realized: close() does nothing', async () => {
+            const el = document.createElement('gtk-window') as GtkWindow;
+            let seen = 0;
+            el.addEventListener('close-request', () => void seen++);
+            expect(el.close()).toBe(false);
+            expect(seen).toBe(0);
+        });
+
+        await it('is-active follows the document focus and notifies only on change', async () => {
+            const { el, host } = mount();
+            const seen: boolean[] = [];
+            el.addEventListener('notify::is-active', (e) => seen.push((e as CustomEvent).detail['is-active']));
+            const before = el.isActive;
+            expect(before).toBe(document.hasFocus());
+            el.hidden = true;
+            expect(el.is_active()).toBe(false);
+            el.present();
+            expect(el.isActive).toBe(document.hasFocus());
+            // Every transition above is one notification at most, and none repeats a value.
+            for (let i = 1; i < seen.length; i++) expect(seen[i]).not.toBe(seen[i - 1]);
+            host.remove();
+            expect(el.isActive).toBe(false);
+        });
+
+        await it('is-active has no setter: GTK declares it read-only', async () => {
+            const { el, host } = mount();
+            const descriptor =
+                Object.getOwnPropertyDescriptor(Object.getPrototypeOf(el.constructor.prototype), 'isActive') ??
+                Object.getOwnPropertyDescriptor(el.constructor.prototype, 'isActive');
+            expect(descriptor?.set).toBe(undefined);
+            host.remove();
+        });
+
+        await it('set_focus refuses an element outside the frame, by name', async () => {
+            const { el, host } = mount();
+            const outside = document.createElement('button');
+            document.body.append(outside);
+            let message = '';
+            try {
+                el.set_focus(outside);
+            } catch (error) {
+                message = (error as Error).message;
+            }
+            expect(message.includes('set_focus')).toBe(true);
+            outside.remove();
+            host.remove();
+        });
+
+        await it('focus-widget notifies with the widget in its detail', async () => {
+            const { el, host } = mount();
+            const button = document.createElement('button');
+            el.append(button);
+            await Promise.resolve();
+            let detail: unknown;
+            el.addEventListener('notify::focus-widget', (e) => (detail = (e as CustomEvent).detail['focus-widget']));
+            el.set_focus(button);
+            expect(detail).toBe(button);
+            expect(el.focusWidget).toBe(button);
+            host.remove();
+        });
+
+        await it('is_maximized() reads the frame state', async () => {
+            const { el, host } = mount();
+            expect(el.is_maximized()).toBe(false);
+            el.maximize();
+            expect(el.is_maximized()).toBe(true);
+            host.remove();
+        });
+    });
 };

package/src/pango-markup.spec.ts

@@ -0,0 +1,257 @@
+// `renderPangoMarkup` — markup becomes NODES, and a string the browser never parses.
+//
+// The rows that matter here are the ones that used to be `innerHTML`: a `<b>` has to come
+// out as an ELEMENT (that is the whole feature — the reviewer who flagged the innerHTML
+// was right about the sink and wrong that the only alternative is plain text), and an
+// `<img src=x onerror=…>` or a `<script>` has to come out as NOTHING an element could
+// carry. Both run through the real elements where they can, because a helper tested alone
+// only proves the helper.
+
+import { describe, expect, it } from '@gjsify/unit';
+
+import { renderPangoMarkup } from './pango-markup.js';
+import type { AdwAlertDialog } from './elements/adw-alert-dialog.js';
+import type { AdwBanner } from './elements/adw-banner.js';
+
+/** Render markup into a detached target and hand both back. */
+function render(markup: string): { target: HTMLElement; text: string } {
+    const target = document.createElement('span');
+    document.body.appendChild(target);
+    renderPangoMarkup(target, markup);
+    return { target, text: target.textContent ?? '' };
+}
+
+/** Computed `font-weight`, which is `bold` or `700` depending on the engine. */
+function isBold(el: Element): boolean {
+    const weight = getComputedStyle(el).fontWeight;
+    return weight === 'bold' || Number.parseInt(weight, 10) >= 600;
+}
+
+function mount<T extends HTMLElement>(tag: string, attributes: Record<string, string>): { el: T; host: HTMLElement } {
+    const host = document.createElement('div');
+    document.body.appendChild(host);
+    const el = document.createElement(tag) as T;
+    for (const [name, value] of Object.entries(attributes)) el.setAttribute(name, value);
+    host.appendChild(el);
+    return { el, host };
+}
+
+const bannerTitle = (el: AdwBanner): HTMLElement => el.querySelector('.adw-banner-title') as HTMLElement;
+const alertHeading = (el: AdwAlertDialog): HTMLElement => el.querySelector('.adw-alert-dialog-heading') as HTMLElement;
+const alertBody = (el: AdwAlertDialog): HTMLElement => el.querySelector('.adw-alert-dialog-body') as HTMLElement;
+
+export const PangoMarkupTest = async () => {
+    await describe('renderPangoMarkup — <b> is drawn bold, because the tree says so', async () => {
+        await it('<b>x</b> becomes a <b> ELEMENT, and it computes bold', () => {
+            const { target } = render('<b>x</b>');
+            const bold = target.querySelector('b');
+            expect(bold).not.toBe(null);
+            expect(bold?.textContent).toBe('x');
+            expect(isBold(bold!)).toBe(true);
+            target.remove();
+        });
+
+        // The four tags with no presentational UA rule, each spelled out as a style — the
+        // rows a "map the tag name to the same HTML element" port silently gets wrong,
+        // because <tt>, <big> and <small> exist in the HTML namespace and mean nothing.
+        await it('tt, big and small draw through styles, not through obsolete elements', () => {
+            const { target } = render('<tt>code</tt><big>big</big><small>small</small>');
+            const tt = target.querySelector('span')!;
+            expect(getComputedStyle(tt).fontFamily.toLowerCase()).toContain('monospace');
+            const big = target.children[1] as HTMLElement;
+            const small = target.children[2] as HTMLElement;
+            expect(Number.parseFloat(getComputedStyle(big).fontSize)).toBeGreaterThan(
+                Number.parseFloat(getComputedStyle(small).fontSize),
+            );
+            expect(big.tagName).toBe('SPAN');
+            expect(small.tagName).toBe('SPAN');
+        });
+
+        await it('the remaining tags become their own elements, nested as written', () => {
+            const { target } = render('<i>a<u>b</u></i><s>c</s><sub>d</sub><sup>e</sup>');
+            expect([...target.children].map((el) => el.tagName)).toStrictEqual(['I', 'S', 'SUB', 'SUP']);
+            expect(target.querySelector('i > u')?.textContent).toBe('b');
+        });
+
+        await it("<markup> draws its children — it is pango's implicit root, not a box", async () => {
+            const { target } = render('<markup><b>x</b></markup>');
+            expect(target.querySelector('b')?.textContent).toBe('x');
+        });
+    });
+
+    await describe('renderPangoMarkup — the rows that were the injection sink', async () => {
+        // Each of these was reachable as `banner.innerHTML = title` / `heading.innerHTML
+        // = heading`. There is no branch in the renderer that creates an element for a
+        // tag pango does not know, and no branch that sets an HTML attribute from a
+        // `<span>` attribute — so none of them can produce an element at all.
+        for (const markup of [
+            '<img src=x onerror="alert(1)">',
+            '<script>alert(1)</script>',
+            '<div onclick="alert(1)">x</div>',
+            '<iframe src="javascript:alert(1)"></iframe>',
+            '<a href="javascript:alert(1)">x</a>',
+            '<b onclick="alert(1)">x</b>',
+        ]) {
+            await it(`${JSON.stringify(markup)} → no element, the raw string as text`, () => {
+                const { target, text } = render(markup);
+                expect(text).toBe(markup);
+                expect(target.children.length).toBe(0);
+                expect(target.querySelector('img, script, div, iframe, a, b, span')).toBe(null);
+                expect(target.getAttribute('onerror')).toBe(null);
+                expect(target.getAttribute('onclick')).toBe(null);
+            });
+        }
+
+        // The one shape that DOES parse and could still carry an `on*`: `<span>` takes
+        // attributes, so an unknown one reaches the tree. It is dropped there and here —
+        // the run renders as plain text with no attribute on it, which is what makes the
+        // whitelist load-bearing rather than decoration.
+        await it('an unknown <span> attribute is dropped, never set on the element', () => {
+            const { target } = render('<span onmouseover="alert(1)">x</span>');
+            const span = target.querySelector('span')!;
+            expect(span.textContent).toBe('x');
+            expect(span.attributes.length).toBe(0);
+            expect((span as HTMLElement).style.cssText).toBe('');
+        });
+
+        await it('unparseable markup keeps the raw string, which is the C fallback', () => {
+            for (const markup of ['a < b', 'Tom & Jerry', '<b>unclosed', '<b>wrong</i>']) {
+                const { target, text } = render(markup);
+                expect(text).toBe(markup);
+                expect(target.children.length).toBe(0);
+            }
+        });
+
+        await it('no element carries an attribute derived from a <span> attribute', () => {
+            const { target } = render('<span weight="bold" font_family="Serif">x</span>');
+            const span = target.querySelector('span')!;
+            // `style` and nothing else: CSSOM reflects the declarations it holds, but a
+            // MARKUP attribute must never reach the DOM as one.
+            expect([...span.attributes].map((attribute) => attribute.name)).toStrictEqual(['style']);
+            expect(span.style.fontWeight).toBe('bold');
+        });
+    });
+
+    await describe('renderPangoMarkup — a <span> attribute reaches CSS, or nothing', async () => {
+        await it("weight and style take pango's NAMED values", () => {
+            const { target } = render('<span weight="bold" style="italic">x</span>');
+            const span = target.querySelector('span')!;
+            expect(span.style.fontWeight).toBe('bold');
+            expect(span.style.fontStyle).toBe('italic');
+        });
+
+        await it('an unmapped weight is DROPPED, never passed through to CSS', () => {
+            const { target } = render('<span weight="expression(alert(1))">x</span>');
+            expect(target.querySelector('span')!.style.fontWeight).toBe('');
+        });
+
+        await it('underline and strikethrough ADD, so a span carrying both keeps both', () => {
+            const { target } = render('<span underline="single" strikethrough="true">x</span>');
+            const decoration = target.querySelector('span')!.style.textDecorationLine;
+            expect(decoration).toContain('underline');
+            expect(decoration).toContain('line-through');
+        });
+
+        await it('underline="none" and strikethrough="false" draw neither', () => {
+            const { target } = render('<span underline="none" strikethrough="false">x</span>');
+            expect(target.querySelector('span')!.style.textDecorationLine).toBe('');
+        });
+
+        await it('a font family list keeps its order; an unparseable one is refused whole', () => {
+            const ok = render('<span font_family="Cantarell, sans-serif">x</span>');
+            expect(ok.target.querySelector('span')!.style.fontFamily).toContain('Cantarell');
+            const refused = render('<span font_family="a&quot;; color: red">x</span>');
+            expect(refused.target.querySelector('span')!.style.fontFamily).toBe('');
+            expect(refused.target.querySelector('span')!.style.color).toBe('');
+        });
+
+        await it('a size travels with its unit — a bare pango number is 1024ths of a point', () => {
+            const units = render('<span size="12288">x</span>');
+            expect(units.target.querySelector('span')!.style.fontSize).toBe('12pt');
+            const points = render('<span size="12.5pt">x</span>');
+            expect(points.target.querySelector('span')!.style.fontSize).toBe('12.5pt');
+            const relative = render('<span font_size="larger">x</span>');
+            expect(relative.target.querySelector('span')!.style.fontSize).toBe('larger');
+            const percent = render('<span size="150%">x</span>');
+            expect(percent.target.querySelector('span')!.style.fontSize).toBe('150%');
+            const named = render('<span size="x-small">x</span>');
+            expect(named.target.querySelector('span')!.style.fontSize).toBe('x-small');
+        });
+
+        await it("reads pango's aliases and a numeric weight", () => {
+            const { target } = render('<span font_weight="600" font_style="italic" face="monospace">x</span>');
+            const span = target.querySelector('span')!;
+            expect(span.style.fontWeight).toBe('600');
+            expect(span.style.fontStyle).toBe('italic');
+            expect(span.style.fontFamily).toBe('monospace');
+        });
+
+        await it('an attribute pango accepts but CSS cannot express is dropped', () => {
+            // `rise` and `letter_spacing` are pango attributes with no equivalent here.
+            const { target } = render('<span rise="4" letter_spacing="2">x</span>');
+            expect(target.querySelector('span')!.getAttribute('style')).toBe(null);
+        });
+    });
+
+    await describe('the elements render the same way', async () => {
+        await it('<adw-banner> draws its <b> bold when use-markup is set', () => {
+            const { el, host } = mount<AdwBanner>('adw-banner', {
+                title: '<b>Metered</b> connection',
+                revealed: '',
+                'use-markup': '',
+            });
+            const bold = bannerTitle(el).querySelector('b');
+            expect(bold?.textContent).toBe('Metered');
+            expect(isBold(bold!)).toBe(true);
+            host.remove();
+        });
+
+        await it('<adw-banner> shows an unknown tag as text, never as an element', () => {
+            const { el, host } = mount<AdwBanner>('adw-banner', {
+                title: '<img src=x onerror="alert(1)">',
+                revealed: '',
+                'use-markup': '',
+            });
+            expect(bannerTitle(el).querySelector('img')).toBe(null);
+            expect(bannerTitle(el).textContent).toBe('<img src=x onerror="alert(1)">');
+            host.remove();
+        });
+
+        await it('<adw-alert-dialog> draws heading AND body markup bold/italic', () => {
+            const { el, host } = mount<AdwAlertDialog>('adw-alert-dialog', {
+                heading: '<b>Delete</b> file?',
+                'heading-use-markup': '',
+                body: 'Really delete <i>notes.txt</i>?',
+                'body-use-markup': '',
+            });
+            expect(isBold(alertHeading(el).querySelector('b')!)).toBe(true);
+            expect(getComputedStyle(alertBody(el).querySelector('i')!).fontStyle).toBe('italic');
+            host.remove();
+        });
+
+        await it('<adw-alert-dialog> shows an unknown tag in either slot as text', () => {
+            const { el, host } = mount<AdwAlertDialog>('adw-alert-dialog', {
+                heading: '<script>alert(1)</script>',
+                'heading-use-markup': '',
+                body: '<img src=x onerror="alert(1)">',
+                'body-use-markup': '',
+            });
+            expect(alertHeading(el).querySelector('script')).toBe(null);
+            expect(alertHeading(el).textContent).toBe('<script>alert(1)</script>');
+            expect(alertBody(el).querySelector('img')).toBe(null);
+            expect(alertBody(el).textContent).toBe('<img src=x onerror="alert(1)">');
+            host.remove();
+        });
+
+        await it('without use-markup both slots stay literal text', () => {
+            const { el, host } = mount<AdwAlertDialog>('adw-alert-dialog', {
+                heading: '<b>Delete</b> file?',
+                body: '<i>notes.txt</i>',
+            });
+            expect(alertHeading(el).textContent).toBe('<b>Delete</b> file?');
+            expect(alertHeading(el).querySelector('b')).toBe(null);
+            expect(alertBody(el).querySelector('i')).toBe(null);
+            host.remove();
+        });
+    });
+};

package/src/pango-markup.ts

@@ -0,0 +1,266 @@
+// Pango markup → DOM NODES. Never markup, never a string the browser parses.
+//
+// WHY THIS FILE EXISTS. `use-markup` used to be implemented as `element.innerHTML =
+// markup`, in three elements: `<adw-banner>`'s title, `<adw-alert-dialog>`'s heading and
+// body. That is an INJECTION SINK dressed as a renderer, and it is also wrong on the
+// merits: Pango markup and HTML are different languages (eleven tags, `<span>`
+// attributes, five entities, no scripting — versus the whole of HTML). Mozilla's add-on
+// reviewer flagged it, correctly.
+//
+// THE THREE STEPS, and why they are in this order:
+//
+//   1. `parsePangoMarkup` (`@gjsify/adwaita-core`, headless) — the STRING becomes a tree
+//      of plain data, or `null`. It is shared with the search pipeline, so the two can
+//      never disagree about what pango accepts.
+//   2. Anything the tree does not name becomes NOTHING. A tag outside pango's set is not
+//      markup at all: the parse fails, and {@link renderPangoMarkup} writes the RAW
+//      STRING as a text node — the same fallback `gtk_label_set_markup` takes. There is
+//      no branch anywhere below that creates an element from an unrecognised name, so
+//      `<img src=x onerror=…>` and `<script>` cannot become nodes at all.
+//   3. `<span>` attributes become CSS DECLARATIONS, never HTML attributes. Each is matched
+//      against a whitelist below and written with `style.setProperty`, which REJECTS an
+//      invalid value outright — so an attribute pango accepts but CSS does not (an unknown
+//      `weight`, a `font_family` with a quote in it) leaves the run unstyled rather than
+//      smuggling a declaration past the parser. Nothing here reads an attribute name off
+//      the element.
+//
+// WHY ELEMENTS AND NOT THE TAG NAMES VERBATIM. Six of pango's eleven tags map onto an
+// HTML element of the SAME name with the SAME meaning (`b`, `i`, `u`, `s`, `sub`, `sup`),
+// and the remaining four (`tt`, `big`, `small`, and `<span>` itself) are all
+// {@link TAG_STYLES} entries: a style declaration on a `<span>`, because a semantic
+// element is a thing an author's CSS can then reach, and because `<b>`/`<i>` are what a
+// reader of the DOM expects. `<markup>` is pango's IMPLICIT root and draws nothing, so it
+// becomes a `display: contents` span: its children land where the root was, with no box of
+// its own for a stylesheet to trip over.
+//
+// `<tt>`/`<big>`/`<small>` are real HTML elements but OBSOLETE ones: they carry no
+// presentational meaning in a modern UA stylesheet, which is exactly why their styles are
+// spelled out here.
+//
+// Reference: packages/web/adwaita-core/src/pango-markup.ts (the parse, and why it is
+//   shared with the search pipeline)
+// Reference: refs/gtk/gtk/gtklabel.c (gtk_label_set_markup's warn-and-keep-the-string
+//   fallback, which is what the `null` branch reproduces)
+// Reference: Mozilla add-on reviewer guidance on innerHTML (the report this answers)
+// Copyright (c) 2025 gjsify contributors. MIT License.
+
+import { parsePangoMarkup, type PangoMarkupNode } from '@gjsify/adwaita-core';
+
+/**
+ * Pango tag → the HTML element that draws it, with the CSS it needs because no
+ * presentational UA rule covers it. Every entry is a CLOSED set: a tag missing here is a
+ * parse error, so there is no default branch to fall through.
+ */
+const TAG_STYLES: Readonly<Record<string, { element: string; style?: Readonly<Record<string, string>> }>> = {
+    b: { element: 'b' },
+    i: { element: 'i' },
+    u: { element: 'u' },
+    s: { element: 's' },
+    tt: { element: 'span', style: { 'font-family': 'monospace' } },
+    big: { element: 'span', style: { 'font-size': 'larger' } },
+    small: { element: 'span', style: { 'font-size': 'smaller' } },
+    sub: { element: 'sub' },
+    sup: { element: 'sup' },
+    markup: { element: 'span', style: { display: 'contents' } },
+    span: { element: 'span' },
+};
+
+/**
+ * `<span>` attribute → the CSS property it becomes, and the values accepted for it. An
+ * attribute NOT listed here is dropped — pango accepts more of them than a stylesheet can
+ * express (`rise`, `letter_spacing`, `lang`, `variant`, `stretch`, …), and dropping one is
+ * what keeps this from becoming a general-purpose attribute→style bridge.
+ */
+const SPAN_STYLES: Readonly<Record<string, string>> = {
+    weight: 'font-weight',
+    style: 'font-style',
+    underline: 'text-decoration-line',
+    strikethrough: 'text-decoration-line',
+    font_family: 'font-family',
+    size: 'font-size',
+};
+
+/**
+ * pango's alternative spellings for the attributes above, which `<span>` documents as
+ * equivalent (`pango_markup.html`: "the `font_weight` attribute is an alias for `weight`",
+ * and so on). Resolved BEFORE {@link SPAN_STYLES}, so an alias reaches the same whitelist
+ * as the name it aliases — reading them as separate properties would let one of the pair
+ * through as an unstyled run while the other worked.
+ */
+const SPAN_ALIASES: Readonly<Record<string, string>> = {
+    font_weight: 'weight',
+    font_style: 'style',
+    face: 'font_family',
+    font_size: 'size',
+};
+
+/**
+ * The pango attribute values each property accepts, by NAME. `font-weight` takes pango's
+ * weight names and, beside them, pango's own numbers — CSS numbers weights on the same
+ * 1–1000 scale, so `weight="600"` is the one value that needs no translation. `weight`
+ * and `style` are the only two with a table; `text-decoration-line` takes CSS keywords,
+ * which are NOT pango's underline / strikethrough booleans — `underline="single"` has to
+ * become `underline`, and that mapping is one line per attribute, not a parser.
+ */
+const ATTRIBUTE_VALUES: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+    weight: {
+        ultralight: '100',
+        light: '300',
+        normal: '400',
+        medium: '500',
+        semibold: '600',
+        bold: 'bold',
+        ultrabold: '700',
+        heavy: '900',
+    },
+    style: { normal: 'normal', oblique: 'oblique', italic: 'italic' },
+};
+
+/**
+ * One node of the parsed tree, built. Returns `null` for a tag this file does not draw —
+ * the fail-closed half: an unrecognised tag DROPS its element (and pango's parser would
+ * have refused the string entirely anyway), rather than falling back to some catch-all
+ * that would put an arbitrary element into the tree.
+ */
+function buildNode(node: PangoMarkupNode, doc: Document): Node | null {
+    if (node.kind === 'text') return doc.createTextNode(node.text);
+
+    const spec = TAG_STYLES[node.tag];
+    if (spec === undefined) return null;
+
+    const el = doc.createElement(spec.element);
+    if (spec.style !== undefined)
+        for (const [property, value] of Object.entries(spec.style)) el.style.setProperty(property, value);
+    if (node.tag === 'span') applySpanAttributes(el, node.attributes);
+
+    for (const child of node.children) {
+        const built = buildNode(child, doc);
+        if (built !== null) el.append(built);
+    }
+    return el;
+}
+
+/** Write the recognised `<span>` attributes onto `el` as style declarations. */
+function applySpanAttributes(el: HTMLElement, attributes: Readonly<Record<string, string>>): void {
+    // Additive, so `<span underline="single" strikethrough="true">` draws BOTH —
+    // `text-decoration` is a shorthand that would drop the first one.
+    const decorations: string[] = [];
+    for (const [name, value] of Object.entries(attributes)) {
+        const attribute = SPAN_ALIASES[name] ?? name;
+        const property = SPAN_STYLES[attribute];
+        if (property === undefined) continue;
+
+        if (attribute === 'underline') {
+            // pango: any value but `none` underlines.
+            if (value !== 'none') decorations.push('underline');
+            continue;
+        }
+        if (attribute === 'strikethrough') {
+            if (value !== 'false' && value !== 'none') decorations.push('line-through');
+            continue;
+        }
+        if (attribute === 'font_family') {
+            const family = sanitizeFontFamily(value);
+            if (family !== null) el.style.setProperty(property, family);
+            continue;
+        }
+        if (attribute === 'size') {
+            const size = sanitizeFontSize(value);
+            if (size !== null) el.style.setProperty(property, size);
+            continue;
+        }
+
+        // pango also takes a numeric weight; CSS reads the same integers from 1 to 1000.
+        if (attribute === 'weight' && /^[0-9]{1,4}$/.test(value) && +value >= 1 && +value <= 1000) {
+            el.style.setProperty(property, value);
+            continue;
+        }
+
+        const named = ATTRIBUTE_VALUES[attribute]?.[value];
+        // An unmapped value is DROPPED rather than passed through: `setProperty` would
+        // reject an invalid declaration anyway, but an unvalidated string reaching CSS is
+        // the shape of bug this file exists to end, so it never gets there.
+        if (named !== undefined) el.style.setProperty(property, named);
+    }
+    if (decorations.length > 0) el.style.setProperty('text-decoration-line', decorations.join(' '));
+}
+
+/** The generic families CSS parses unquoted; everything else must be a plain name. */
+const CSS_GENERIC_FAMILIES: ReadonlySet<string> = new Set([
+    'serif',
+    'sans-serif',
+    'monospace',
+    'cursive',
+    'fantasy',
+    'system-ui',
+    'ui-serif',
+    'ui-sans-serif',
+    'ui-monospace',
+    'ui-rounded',
+]);
+
+/**
+ * A pango `font_family` list as a CSS `font-family`, or `null` when any entry cannot be
+ * one. Pango takes a bare comma-separated list; CSS additionally parses quotes and
+ * escapes, so an entry holding either is refused as a WHOLE list rather than escaped —
+ * refusing is the answer that cannot produce a family name CSS reads differently.
+ */
+function sanitizeFontFamily(value: string): string | null {
+    const families: string[] = [];
+    for (const raw of value.split(',')) {
+        const family = raw.trim();
+        if (family === '') continue;
+        const generic = CSS_GENERIC_FAMILIES.has(family.toLowerCase());
+        // A quoted CSS identifier is the general form; a bare one is safe only when it is
+        // a plain name, so anything carrying a quote, backslash or semicolon is refused.
+        if (!generic && !/^["']?[A-Za-z0-9 _-]+["']?$/.test(family)) return null;
+        families.push(family);
+    }
+    return families.length > 0 ? families.join(', ') : null;
+}
+
+/** A pango `size` as a CSS `font-size`, or `null` when it cannot be one. */
+function sanitizeFontSize(value: string): string | null {
+    const trimmed = value.trim();
+    // pango's named sizes, which CSS ALSO names — the same absolute ladder, plus pango's
+    // two relative steps, so the whole set needs no conversion at all.
+    const named: Readonly<Record<string, string>> = {
+        'xx-small': 'xx-small',
+        'x-small': 'x-small',
+        small: 'small',
+        medium: 'medium',
+        large: 'large',
+        'x-large': 'x-large',
+        'xx-large': 'xx-large',
+        smaller: 'smaller',
+        larger: 'larger',
+    };
+    const namedSize = named[trimmed];
+    if (namedSize !== undefined) return namedSize;
+    // A bare pango size is in 1024ths of a point (`size="12288"` is 12pt), so it is scaled,
+    // never passed on: CSS would read a bare number as no length at all.
+    if (/^[0-9]+$/.test(trimmed)) return `${+trimmed / 1024}pt`;
+    // Since pango 1.50: points with their unit, and a percentage of the parent.
+    if (/^[0-9]+(\.[0-9]+)?pt$/.test(trimmed)) return trimmed;
+    if (/^[0-9]+(\.[0-9]+)?%$/.test(trimmed)) return trimmed;
+    return null;
+}
+
+/**
+ * Render Pango markup into `target`, replacing its content — the one door every
+ * `use-markup` surface in this package goes through.
+ *
+ * The `null` branch is the C fallback and is the SECURITY property: markup that does not
+ * parse is written as TEXT, so an unrecognised tag can never become an element. Callers
+ * that want markup only when a caller has asked for it read that from their own flag and
+ * pass plain text here — this function never decides whether markup is meant.
+ */
+export function renderPangoMarkup(target: HTMLElement, markup: string): void {
+    const nodes = parsePangoMarkup(markup);
+    if (nodes === null) {
+        target.textContent = markup;
+        return;
+    }
+    const doc = target.ownerDocument ?? document;
+    target.replaceChildren(...nodes.map((node) => buildNode(node, doc)).filter((node): node is Node => node !== null));
+}