@formicoidea/labre-core 0.50.0 → 0.52.0

package/dist/_pkgs/affine-block-surface/extensions/svg-sketch.js

@@ -1,7 +1,8 @@
-import { ShapeStyle, ShapeType, StrokeStyle, TextAlign, } from '../../affine-model/index.js';
-import DOMPurify from 'dompurify';
+import { ShapeStyle, ShapeType, StrokeStyle, TextAlign, } from '../../affine-model/headless.js';
 import { InterchangeImportError, } from './interchange.js';
-import { SVG_SKETCH_CURRENT_COLOR, SVG_SKETCH_CURVE, SVG_SKETCH_EMPTY, SVG_SKETCH_EMPTY_BOX, SVG_SKETCH_EMPTY_TEXT, SVG_SKETCH_ERROR_MALFORMED_XML, SVG_SKETCH_ERROR_NOT_SVG, SVG_SKETCH_ERROR_SANITIZED_AWAY, SVG_SKETCH_FLAT_POLYGON, SVG_SKETCH_FONT_UNIT, SVG_SKETCH_HIDDEN_DISPLAY, SVG_SKETCH_HIDDEN_VISIBILITY, SVG_SKETCH_LONE_POINT, SVG_SKETCH_OPACITY, SVG_SKETCH_PAINT_SERVER, SVG_SKETCH_PERCENT_RADIUS, SVG_SKETCH_REMOVED, SVG_SKETCH_REMOVED_ATTRIBUTE, SVG_SKETCH_SKIPPED, SVG_SKETCH_SWITCH, SVG_SKETCH_TRANSFORM, } from './svg-sketch-translations.js';
+import { MAX_SVG_DEPTH, sanitizeSvgNode } from './svg-sanitize.js';
+import { SVG_SKETCH_CURRENT_COLOR, SVG_SKETCH_CURVE, SVG_SKETCH_EMPTY, SVG_SKETCH_EMPTY_BOX, SVG_SKETCH_EMPTY_TEXT, SVG_SKETCH_ERROR_MALFORMED_XML, SVG_SKETCH_ERROR_NOT_SVG, SVG_SKETCH_ERROR_SANITIZED_AWAY, SVG_SKETCH_FLAT_POLYGON, SVG_SKETCH_FONT_UNIT, SVG_SKETCH_HIDDEN_DISPLAY, SVG_SKETCH_HIDDEN_VISIBILITY, SVG_SKETCH_LONE_POINT, SVG_SKETCH_OPACITY, SVG_SKETCH_PAINT_SERVER, SVG_SKETCH_PERCENT_RADIUS, SVG_SKETCH_REMOVED, SVG_SKETCH_REMOVED_ATTRIBUTE, SVG_SKETCH_SKIPPED, SVG_SKETCH_SWITCH, SVG_SKETCH_TOO_DEEP, SVG_SKETCH_TRANSFORM, } from './svg-sketch-translations.js';
+import { readXml } from './xml-reader.js';
 /**
  * **SVG → a canvas sketch.** The platform's VISUAL-tier importer, shared by
  * every framework that declares it (`docs/adr/0012`, P2).
@@ -99,27 +100,14 @@ export const SVG_SKETCH_EXTENSION = '.svg';
 export const SVG_SKETCH_MIME = 'image/svg+xml';
 /* ── Small readers ────────────────────────────────────────────────────── */
 /**
- * happy-dom (the vitest environment two of the three packages that test this
- * run in) does not implement namespace-aware lookups, so this file walks
- * children by hand and compares `localName`, exactly as the BPMN reader does.
- * `children` is also skipped in favour of `childNodes`, because the former is
- * an `HTMLCollection` whose behaviour on a foreign-namespaced document is one
- * more thing that differs between the two environments.
+ * The walk reads the sanitizer's tree (`svg-sanitize.ts`), a DOM-shaped view
+ * over `readXml` rather than a DOM, so a server reads an `.svg` with no DOM
+ * installed (ADR 0012, P3 as amended 2026-10-14). It compares `localName`
+ * folded to lower case, as it did when that tree came out of an HTML parser.
  */
-const ELEMENT_NODE = 1;
 const TEXT_NODE = 3;
-const CDATA_NODE = 4;
-// `Node` and not `Element`, because only `childNodes` is ever read and one
-// caller is DOMPurify's `RETURN_DOM` answer — which its own typed overload
-// declares as a `Node`. Widening the parameter is more honest than casting the
-// argument at that one call site.
 function childElements(parent) {
-    const found = [];
-    for (const node of Array.from(parent.childNodes)) {
-        if (node.nodeType === ELEMENT_NODE)
-            found.push(node);
-    }
-    return found;
+    return parent.children;
 }
 const nameOf = (element) => element.localName?.toLowerCase() ?? '';
 /** One attribute as a finite number, or the caller's default. */
@@ -614,10 +602,10 @@ function readPolygon(element, frame, paint, sketch) {
     }
     const xs = points.map(p => p[0]);
     const ys = points.map(p => p[1]);
-    const minX = Math.min(...xs);
-    const minY = Math.min(...ys);
-    const w = Math.max(...xs) - minX;
-    const h = Math.max(...ys) - minY;
+    const minX = xs.reduce((a, b) => Math.min(a, b), Infinity);
+    const minY = ys.reduce((a, b) => Math.min(a, b), Infinity);
+    const w = xs.reduce((a, b) => Math.max(a, b), -Infinity) - minX;
+    const h = ys.reduce((a, b) => Math.max(a, b), -Infinity) - minY;
     if (points.length < 3 || w <= 0 || h <= 0) {
         if (points.length === 0 || w < 0 || h < 0) {
             sketch.notes.once('empty-box', EMPTY_BOX_NOTE, SVG_SKETCH_EMPTY_BOX);
@@ -712,13 +700,14 @@ const LINE_HEIGHT_RATIO = 1.2;
 function readText(element, frame, paint, sketch) {
     const lines = [];
     const collapse = (raw) => raw.replace(/\s+/g, ' ').trim();
-    for (const node of Array.from(element.childNodes)) {
-        if (node.nodeType === TEXT_NODE || node.nodeType === CDATA_NODE) {
-            const line = collapse(node.nodeValue ?? '');
+    for (const node of element.childNodes) {
+        if (!('localName' in node)) {
+            // Text and CDATA alike; a comment is not a line.
+            const line = node.nodeType === TEXT_NODE ? collapse(node.nodeValue) : '';
             if (line)
                 lines.push(line);
         }
-        else if (node.nodeType === ELEMENT_NODE) {
+        else {
             const child = node;
             if (nameOf(child) !== 'tspan')
                 continue;
@@ -734,7 +723,9 @@ function readText(element, frame, paint, sketch) {
         return;
     }
     const fontSize = len(frame, paint.fontSize ?? DEFAULT_FONT_SIZE);
-    const widest = Math.max(...lines.map(line => line.length));
+    const widest = lines
+        .map(line => line.length)
+        .reduce((a, b) => Math.max(a, b), -Infinity);
     const w = Math.max(widest * fontSize * CHARACTER_WIDTH_RATIO, fontSize);
     const h = lines.length * fontSize * LINE_HEIGHT_RATIO;
     // `text-anchor` says which end of the box `x` names, and it INHERITS — a
@@ -771,8 +762,6 @@ const CONTAINERS = new Set(['g', 'a']);
  * most visible thing this reader does to a mermaid diagram.
  */
 const NON_RENDERING = new Set(['title', 'desc', 'metadata']);
-/** The sanitizer's own HTML wrapper, which no `.svg` on a disk ever contained. */
-const PARSER_SCAFFOLDING = new Set(['html', 'head', 'body']);
 function walk(parent, frame, inherited, sketch) {
     for (const element of childElements(parent)) {
         visit(element, frame, inherited, sketch);
@@ -925,83 +914,66 @@ export function svgFrameOf(element) {
 /**
  * The document, sanitized, or an exception naming what is wrong with it.
  *
- * Well-formedness FIRST, because `DOMParser` reports a malformed document as a
- * `parsererror` element rather than by throwing — a verdict in the shape of a
- * document — and because DOMPurify's parser is the forgiving HTML one, which
- * would quietly repair the very thing the caller needs to be told about. So:
- * parse for the verdict, reading nothing out of the result but that; sanitize
- * the SOURCE; and walk only what came back from the sanitizer.
+ * Read with `readXml` in its conformant mode, then filtered by the allow-list
+ * in `svg-sanitize.ts`; the walk and every recogniser see only what came back.
+ * No DOM is involved at any step, so the same function runs in the editor, in
+ * a test and on a server (ADR 0012, P3 as amended 2026-10-14). It replaced
+ * `DOMParser` + DOMPurify, which needed a DOM installed before the library was
+ * even imported (the P0 import spike measured that trap).
+ *
+ * Well-formedness first: anything the reader had to recover from is refused,
+ * with the reader's first remark as the detail, as `DOMParser` used to refuse
+ * it. A `DOCTYPE` is not an error: it is skipped and no entity it declares is
+ * ever expanded, so a `&name;` it declares stays those characters.
  *
  * The sanitizer is not optional and it is not defensive programming. An `.svg`
  * is an executable document — `<script>`, `<foreignObject>` with markup, event
- * handler attributes — handed over by whoever sent the file. The same
- * `USE_PROFILES: { svg: true }` guard is what the edgeless clipboard already
- * puts in front of a pasted SVG.
+ * handler attributes — handed over by whoever sent the file.
  *
  * The first of the two passes {@link parseSvgSketch} is made of, exported so a
  * framework that recognises part of a picture reads the SAME sanitised tree
  * the sketch walks (ADR 0032 §2, §7) — never the source.
  */
 export function sanitizeSvg(source, notes) {
-    const doc = new DOMParser().parseFromString(source, 'image/svg+xml');
-    const error = doc.querySelector('parsererror');
-    if (error) {
-        // The FIRST line only. Chromium's `parsererror` is a whole rendered
-        // document — a heading, the message, then the offending source line with a
-        // caret under it — and pouring that into a toast makes the one sentence
-        // that matters unreadable.
-        const [summary = ''] = (error.textContent ?? '')
-            .split('\n')
-            .map(line => line.trim())
-            .filter(line => line.length > 0);
-        const detail = summary.slice(0, 200);
+    const document = readXml(source, { conformant: true });
+    const [complaint] = document.notes;
+    if (complaint !== undefined) {
+        const detail = complaint.slice(0, 200);
         throw new InterchangeImportError(`This file is not well-formed XML, so no drawing can be read out of it: ${detail}`, {
             messageKey: SVG_SKETCH_ERROR_MALFORMED_XML[0],
             messageParams: { detail },
         });
     }
-    if (nameOf(doc.documentElement) !== 'svg') {
-        const tag = doc.documentElement?.localName ?? 'nothing';
+    if (document.root?.local.toLowerCase() !== 'svg') {
+        const tag = document.root?.local ?? 'nothing';
         throw new InterchangeImportError(`An SVG opens on <svg>; this one opens on <${tag}>.`, { messageKey: SVG_SKETCH_ERROR_NOT_SVG[0], messageParams: { tag } });
     }
-    const clean = DOMPurify.sanitize(source, {
-        USE_PROFILES: { svg: true },
-        RETURN_DOM: true,
-    });
+    const { root, report } = sanitizeSvgNode(document.root);
     // …and then say what the sanitizer took, which is NOT the same list as what
     // the walk below skips. `<use>` and `<foreignObject>` never reach the walk at
-    // all — they are two of the SVG format's genuine attack surfaces and DOMPurify
-    // removes them outright — so a drawing built out of symbol instances arrives
-    // empty. Without this the only remark would be "nothing was recognised",
-    // which is true and useless. `DOMPurify.removed` is repopulated by each call
-    // and is read here immediately, before anything else can sanitize.
-    for (const entry of DOMPurify.removed) {
-        const removed = entry;
-        if (removed.element) {
+    // all — they are two of the SVG format's genuine attack surfaces — so a
+    // drawing built out of symbol instances arrives empty. Without this the only
+    // remark would be "nothing was recognised", which is true and useless.
+    for (const removal of report.removed) {
+        if ('element' in removal) {
             // The node's OWN spelling, because `foreignObject` is camel-cased in the
             // format and a remark that called it `foreignobject` would send its
             // reader looking for something the spec does not have. The dedup key is
             // folded; the sentence is not.
-            const name = removed.element.nodeName ?? '';
-            // The sanitizer parses into an HTML document and reports unwinding its
-            // own wrapper as a removal. Nobody wrote a `<body>` into an `.svg`, and a
-            // remark about one would be this reader telling the user about its own
-            // plumbing.
-            if (PARSER_SCAFFOLDING.has(name.toLowerCase()))
-                continue;
+            const name = removal.element;
             notes.once(`removed:${name.toLowerCase()}`, `\`<${name}>\` was removed while sanitizing the file — it is one of the constructs an SVG can carry code in — so nothing it drew was imported.`, SVG_SKETCH_REMOVED, { name }, name);
         }
-        else if (removed.attribute) {
+        else {
             // Worded for what this actually is, which is broader than "unsafe": the
-            // sanitizer's allow-list drops an event handler AND a `requiredFeatures`,
-            // and calling the second one dangerous would be this reader accusing a
+            // allow-list drops an event handler AND a `requiredFeatures`, and
+            // calling the second one dangerous would be this reader accusing a
             // perfectly ordinary file of something.
             notes.once('removed-attribute', 'Attributes outside the safe SVG drawing vocabulary — event handlers, script URLs, and anything else the sanitizer does not know — were removed before the file was read.', SVG_SKETCH_REMOVED_ATTRIBUTE);
         }
     }
-    // No cast: `RETURN_DOM: true` in the literal selects DOMPurify's typed
-    // overload, which answers an `HTMLElement` — the sanitized body wrapper.
-    const root = childElements(clean).find(child => nameOf(child) === 'svg');
+    if (report.tooDeep) {
+        notes.once('too-deep', `Elements nested more than ${MAX_SVG_DEPTH} levels deep were not read.`, SVG_SKETCH_TOO_DEEP, { depth: MAX_SVG_DEPTH });
+    }
     if (!root) {
         throw new InterchangeImportError(SVG_SKETCH_ERROR_SANITIZED_AWAY[1], {
             messageKey: SVG_SKETCH_ERROR_SANITIZED_AWAY[0],

package/dist/_pkgs/affine-block-surface/extensions/xml-element.d.ts

@@ -0,0 +1,98 @@
+import { type XmlDocument, type XmlNode, type XmlReadOptions } from './xml-reader.js';
+/**
+ * A read-only, DOM-SHAPED view over {@link readXml}'s tree, with namespaces
+ * resolved — what the BPMN reader and the SVG sketch walk instead of a
+ * `DOMParser` document (ADR 0012, P3 as amended 2026-10-14).
+ *
+ * Both readers were written against the DOM and read only a small part of it:
+ * `localName`, `namespaceURI`, `attributes`, `getAttribute`, `children`,
+ * `childNodes`, `textContent`, `parentElement` and a few compound selectors.
+ * This class answers exactly that part, with the DOM's names and the DOM's
+ * answers for an XML document (case-sensitive names, `null` for a missing
+ * attribute or namespace), so the readers kept their logic and lost their
+ * global. It is not a DOM: nothing here mutates, and a member a reader does
+ * not use does not exist.
+ *
+ * Built with an explicit stack: the depth of a file is its author's choice.
+ */
+export declare const XML_NAMESPACE = "http://www.w3.org/XML/1998/namespace";
+export declare const XMLNS_NAMESPACE = "http://www.w3.org/2000/xmlns/";
+/** One attribute, as the DOM's `Attr` names it. */
+export interface XmlAttribute {
+    /** The qualified name as written: `xlink:href`, `fill`. */
+    name: string;
+    prefix: string | null;
+    localName: string;
+    /** Resolved; `null` for an unprefixed attribute, as XML namespaces say. */
+    namespaceURI: string | null;
+    value: string;
+}
+/** Character data or a comment, as the DOM's `Text` / `Comment` show it. */
+export interface XmlCharacterNode {
+    /** 3 for text and CDATA, 8 for a comment, 7 for an instruction. */
+    nodeType: 3 | 7 | 8;
+    nodeValue: string;
+}
+export declare class XmlElement {
+    /** The reader's node, for a caller that wants its range or its content. */
+    readonly node: XmlNode;
+    readonly parentElement: XmlElement | null;
+    readonly namespaceURI: string | null;
+    readonly attributes: XmlAttribute[];
+    readonly nodeType = 1;
+    readonly children: XmlElement[];
+    readonly childNodes: (XmlElement | XmlCharacterNode)[];
+    constructor(
+    /** The reader's node, for a caller that wants its range or its content. */
+    node: XmlNode, parentElement: XmlElement | null, namespaceURI: string | null, attributes: XmlAttribute[]);
+    get localName(): string;
+    get prefix(): string | null;
+    /** The qualified name as written, which is what the DOM says for XML. */
+    get nodeName(): string;
+    get tagName(): string;
+    get firstElementChild(): XmlElement | null;
+    /** Every text and CDATA under this element, in order; comments excluded. */
+    get textContent(): string;
+    /** By qualified name, exactly as written — the DOM's rule for XML. */
+    getAttribute(name: string): string | null;
+    hasAttribute(name: string): boolean;
+    get classList(): {
+        contains(token: string): boolean;
+    };
+    /** Is `other` this element or one of its descendants? */
+    contains(other: XmlElement | null): boolean;
+    /** Every descendant (never this element), in document order. */
+    descendants(): XmlElement[];
+    matches(selectors: string): boolean;
+    querySelectorAll(selectors: string): XmlElement[];
+    querySelector(selectors: string): XmlElement | null;
+    private is;
+}
+/**
+ * The namespaces in scope during a depth-first walk, as one stack per prefix:
+ * {@link enter} and {@link exit} cost the element's own declarations, and
+ * {@link resolve} is one lookup. A copied map per declaring element was
+ * quadratic: a root declaring 2 000 prefixes over thousands of
+ * `<g xmlns:q="x"/>` took 28 s and 284 MiB (security review, 2026-10-14).
+ */
+export declare class XmlNamespaceScope {
+    private readonly bound;
+    enter(node: XmlNode): void;
+    exit(node: XmlNode): void;
+    /** `null` when unbound — or undeclared by `xmlns=""` (Namespaces in XML §6.2). */
+    resolve(prefix: string): string | null;
+    /** The node's attributes, resolved in this scope (entered first). */
+    attributesOf(node: XmlNode): XmlAttribute[];
+}
+/**
+ * The element view of a node the reader produced, namespaces resolved from the
+ * `xmlns` declarations on the way down (`xml` is bound, as XML says it is).
+ * An unbound prefix resolves to `null`, which is what a reader then refuses or
+ * ignores: this function never guesses a namespace.
+ */
+export declare function xmlElementOf(root: XmlNode): XmlElement;
+/** {@link readXml}, then {@link xmlElementOf} on its first root. */
+export declare function readXmlElement(source: string, options?: XmlReadOptions): {
+    document: XmlDocument;
+    root: XmlElement | undefined;
+};

package/dist/_pkgs/affine-block-surface/extensions/xml-element.js

@@ -0,0 +1,261 @@
+import { readXml, } from './xml-reader.js';
+/**
+ * A read-only, DOM-SHAPED view over {@link readXml}'s tree, with namespaces
+ * resolved — what the BPMN reader and the SVG sketch walk instead of a
+ * `DOMParser` document (ADR 0012, P3 as amended 2026-10-14).
+ *
+ * Both readers were written against the DOM and read only a small part of it:
+ * `localName`, `namespaceURI`, `attributes`, `getAttribute`, `children`,
+ * `childNodes`, `textContent`, `parentElement` and a few compound selectors.
+ * This class answers exactly that part, with the DOM's names and the DOM's
+ * answers for an XML document (case-sensitive names, `null` for a missing
+ * attribute or namespace), so the readers kept their logic and lost their
+ * global. It is not a DOM: nothing here mutates, and a member a reader does
+ * not use does not exist.
+ *
+ * Built with an explicit stack: the depth of a file is its author's choice.
+ */
+export const XML_NAMESPACE = 'http://www.w3.org/XML/1998/namespace';
+export const XMLNS_NAMESPACE = 'http://www.w3.org/2000/xmlns/';
+/** `Node.ELEMENT_NODE`, spelled. */
+const ELEMENT_NODE = 1;
+const COMPOUND = /^([A-Za-z][\w-]*)?((?:[.#][\w-]+|\[[\w:-]+(?:="[^"]*")?\])*)$/;
+const PART = /\.([\w-]+)|#([\w-]+)|\[([\w:-]+)(?:="([^"]*)")?\]/g;
+/**
+ * A selector list without combinators — the only shape the readers write.
+ * Anything else is a programming error in a reader, and says so.
+ */
+function parseSelectors(selectors) {
+    return selectors.split(',').map(raw => {
+        const text = raw.trim();
+        const match = COMPOUND.exec(text);
+        if (!match || text.length === 0) {
+            throw new Error(`XmlElement does not support the selector "${text}"`);
+        }
+        const compound = { type: match[1], classes: [], attrs: [] };
+        for (const part of (match[2] ?? '').matchAll(PART)) {
+            if (part[1] !== undefined)
+                compound.classes.push(part[1]);
+            else if (part[2] !== undefined)
+                compound.attrs.push({ name: 'id', value: part[2] });
+            else
+                compound.attrs.push({ name: part[3], value: part[4] });
+        }
+        return compound;
+    });
+}
+export class XmlElement {
+    constructor(
+    /** The reader's node, for a caller that wants its range or its content. */
+    node, parentElement, namespaceURI, attributes) {
+        this.node = node;
+        this.parentElement = parentElement;
+        this.namespaceURI = namespaceURI;
+        this.attributes = attributes;
+        this.nodeType = ELEMENT_NODE;
+        this.children = [];
+        this.childNodes = [];
+    }
+    get localName() {
+        return this.node.local;
+    }
+    get prefix() {
+        return this.node.prefix === '' ? null : this.node.prefix;
+    }
+    /** The qualified name as written, which is what the DOM says for XML. */
+    get nodeName() {
+        return this.node.name;
+    }
+    get tagName() {
+        return this.node.name;
+    }
+    get firstElementChild() {
+        return this.children[0] ?? null;
+    }
+    /** Every text and CDATA under this element, in order; comments excluded. */
+    get textContent() {
+        const parts = [];
+        const stack = [
+            ...this.childNodes,
+        ].reverse();
+        while (stack.length > 0) {
+            const next = stack.pop();
+            if (next instanceof XmlElement) {
+                for (let index = next.childNodes.length - 1; index >= 0; index -= 1) {
+                    stack.push(next.childNodes[index]);
+                }
+            }
+            else if (next.nodeType === 3) {
+                parts.push(next.nodeValue);
+            }
+        }
+        return parts.join('');
+    }
+    /** By qualified name, exactly as written — the DOM's rule for XML. */
+    getAttribute(name) {
+        // Own properties only: an attribute named `constructor` is a string, and
+        // a missing one is never `Object.prototype`'s.
+        return Object.hasOwn(this.node.attrs, name) ? this.node.attrs[name] : null;
+    }
+    hasAttribute(name) {
+        return Object.hasOwn(this.node.attrs, name);
+    }
+    get classList() {
+        const tokens = (this.getAttribute('class') ?? '').split(/\s+/);
+        return { contains: token => tokens.includes(token) };
+    }
+    /** Is `other` this element or one of its descendants? */
+    contains(other) {
+        for (let at = other; at; at = at.parentElement) {
+            if (at === this)
+                return true;
+        }
+        return false;
+    }
+    /** Every descendant (never this element), in document order. */
+    descendants() {
+        const found = [];
+        const stack = [...this.children].reverse();
+        while (stack.length > 0) {
+            const next = stack.pop();
+            found.push(next);
+            for (let index = next.children.length - 1; index >= 0; index -= 1) {
+                stack.push(next.children[index]);
+            }
+        }
+        return found;
+    }
+    matches(selectors) {
+        return parseSelectors(selectors).some(compound => this.is(compound));
+    }
+    querySelectorAll(selectors) {
+        const list = parseSelectors(selectors);
+        return this.descendants().filter(element => list.some(compound => element.is(compound)));
+    }
+    querySelector(selectors) {
+        return this.querySelectorAll(selectors)[0] ?? null;
+    }
+    is(compound) {
+        if (compound.type !== undefined && compound.type !== this.localName) {
+            return false;
+        }
+        if (compound.classes.some(token => !this.classList.contains(token))) {
+            return false;
+        }
+        return compound.attrs.every(({ name, value }) => {
+            const actual = this.getAttribute(name);
+            return actual !== null && (value === undefined || actual === value);
+        });
+    }
+}
+/**
+ * The namespaces in scope during a depth-first walk, as one stack per prefix:
+ * {@link enter} and {@link exit} cost the element's own declarations, and
+ * {@link resolve} is one lookup. A copied map per declaring element was
+ * quadratic: a root declaring 2 000 prefixes over thousands of
+ * `<g xmlns:q="x"/>` took 28 s and 284 MiB (security review, 2026-10-14).
+ */
+export class XmlNamespaceScope {
+    constructor() {
+        this.bound = new Map([
+            ['xml', [XML_NAMESPACE]],
+        ]);
+    }
+    enter(node) {
+        for (const [prefix, value] of declarationsOf(node)) {
+            const stack = this.bound.get(prefix);
+            if (stack)
+                stack.push(value);
+            else
+                this.bound.set(prefix, [value]);
+        }
+    }
+    exit(node) {
+        for (const [prefix] of declarationsOf(node))
+            this.bound.get(prefix)?.pop();
+    }
+    /** `null` when unbound — or undeclared by `xmlns=""` (Namespaces in XML §6.2). */
+    resolve(prefix) {
+        const stack = this.bound.get(prefix);
+        return stack?.at(-1) || null;
+    }
+    /** The node's attributes, resolved in this scope (entered first). */
+    attributesOf(node) {
+        return Object.entries(node.attrs).map(([name, value]) => {
+            const colon = name.indexOf(':');
+            const prefix = colon < 0 ? null : name.slice(0, colon);
+            const localName = colon < 0 ? name : name.slice(colon + 1);
+            let namespaceURI = null;
+            if (name === 'xmlns' || prefix === 'xmlns')
+                namespaceURI = XMLNS_NAMESPACE;
+            else if (prefix !== null)
+                namespaceURI = this.resolve(prefix);
+            return { name, prefix, localName, namespaceURI, value };
+        });
+    }
+}
+function* declarationsOf(node) {
+    for (const name in node.attrs) {
+        if (name === 'xmlns')
+            yield ['', node.attrs[name]];
+        else if (name.startsWith('xmlns:'))
+            yield [name.slice(6), node.attrs[name]];
+    }
+}
+/**
+ * The element view of a node the reader produced, namespaces resolved from the
+ * `xmlns` declarations on the way down (`xml` is bound, as XML says it is).
+ * An unbound prefix resolves to `null`, which is what a reader then refuses or
+ * ignores: this function never guesses a namespace.
+ */
+export function xmlElementOf(root) {
+    const scope = new XmlNamespaceScope();
+    const make = (node, parent) => {
+        scope.enter(node);
+        return new XmlElement(node, parent, scope.resolve(node.prefix), scope.attributesOf(node));
+    };
+    // A node assembled by hand has no `content`; its children are all it has.
+    const frameOf = (node, element) => ({
+        node,
+        element,
+        entries: node.content ?? node.children,
+        index: 0,
+    });
+    const top = make(root, null);
+    const stack = [frameOf(root, top)];
+    while (stack.length > 0) {
+        const frame = stack[stack.length - 1];
+        if (frame.index >= frame.entries.length) {
+            scope.exit(frame.node);
+            stack.pop();
+            continue;
+        }
+        const entry = frame.entries[frame.index];
+        frame.index += 1;
+        const { element } = frame;
+        if (!('kind' in entry)) {
+            const child = make(entry, element);
+            element.children.push(child);
+            element.childNodes.push(child);
+            stack.push(frameOf(entry, child));
+        }
+        else if (entry.kind === 'text') {
+            element.childNodes.push({ nodeType: 3, nodeValue: entry.value });
+        }
+        else if (entry.kind === 'comment') {
+            element.childNodes.push({ nodeType: 8, nodeValue: entry.value });
+        }
+        else {
+            element.childNodes.push({ nodeType: 7, nodeValue: entry.data });
+        }
+    }
+    return top;
+}
+/** {@link readXml}, then {@link xmlElementOf} on its first root. */
+export function readXmlElement(source, options = {}) {
+    const document = readXml(source, options);
+    return {
+        document,
+        root: document.root ? xmlElementOf(document.root) : undefined,
+    };
+}