@wirebench/engine 2.1.1

package/dist/xpath/evaluate.js

@@ -0,0 +1,340 @@
+/**
+ * XPath 3.1 / XQuery 3.1 evaluation against a response, for the response Query scratchpad. Where
+ * classic SOAP workbenches limit querying to XPath 2.0 inside assertions, this runs both languages
+ * over the actual bytes the server returned, ahead of any assertion.
+ *
+ * A JSON response is queried by the same two languages ({@link evaluateJson}) rather than by a third
+ * one: XPath 3.1 has maps, arrays and the `?` lookup operator, so `?items?*[?status = "open"]?id`
+ * needs no new dependency and no second expression syntax for users to learn. The context item is
+ * the parsed document itself.
+ */
+import fontoxpathModule from 'fontoxpath';
+import { getPosition, parseXml } from '../xml/parse.js';
+import { serializeXml } from '../xml/serialize.js';
+import { LineIndex } from '../xml/positions.js';
+import { evaluateJsonPath } from './jsonpath.js';
+// `fontoxpath` ships as CommonJS; its named exports only land on the default import under
+// Node's ESM interop, so every entry point this module needs is re-destructured here once.
+const { evaluateXPath, Language } = fontoxpathModule;
+/** The result of {@link evaluate} is capped at this many items; a query producing more is
+ * still evaluated to completion, but only the first `RESULT_CAP` are returned to the caller,
+ * with `truncated: true` so the UI can say so instead of silently hiding the rest. */
+const RESULT_CAP = 1_000;
+const NODE_TYPE = {
+    1: 'element',
+    2: 'attribute',
+    3: 'text',
+    7: 'pi',
+    8: 'comment',
+    9: 'document',
+};
+/** True when `value` looks like a DOM node (has a numeric `nodeType`), as opposed to an atomic
+ * XPath value (string, number, boolean, map, array). Fontoxpath's `ALL_RESULTS_TYPE` mixes both
+ * shapes in one array, so every item has to be classified individually. */
+function isNode(value) {
+    return typeof value === 'object' && value !== null && typeof value.nodeType === 'number';
+}
+/**
+ * Builds `/a/b[2]`-shaped paths for the nodes of one result set.
+ *
+ * Doing this naively — walking `previousSibling` for every ancestor of every result — is
+ * quadratic in the number of siblings, and a 1 MB response is typically one element with tens
+ * of thousands of children. Both the per-element positional index (filled a whole sibling list
+ * at a time) and the finished path string are cached, so the whole result set costs one pass.
+ * Together with the shared `LineIndex` below, that took the budgeted 1 MB query from a median
+ * of 353 ms to 145 ms, and `…/p:Row` from 333 ms to 123 ms (see the Task 50 report).
+ */
+class PathIndex {
+    positions = new Map();
+    paths = new Map();
+    /** The path of `node`; attributes are addressed as `@name` on their owning element. */
+    path(node) {
+        if (node.nodeType === 2) {
+            const owner = node.ownerElement ?? undefined;
+            const ownerPath = owner === undefined ? '/' : this.elementPath(owner);
+            return `${ownerPath}/@${node.nodeName ?? ''}`;
+        }
+        return this.elementPath(node);
+    }
+    /**
+     * The path of an element — or of the nearest element at or above a non-element node.
+     *
+     * Iterative on purpose: a deeply nested document (an envelope wrapping thousands of levels)
+     * would otherwise overflow the call stack on what is only a walk to the root. Ancestors are
+     * collected upwards until a cached path (or the root) is reached, then the path is built back
+     * down, caching every ancestor on the way so the next result in the same subtree is free.
+     */
+    elementPath(node) {
+        // Non-element nodes (text, comment, PI) have no step of their own: they are reported at the
+        // path of their owning element, which is what a user needs to locate them in the document.
+        let current = node;
+        while (current !== null && current !== undefined && current.nodeType !== 1) {
+            current = current.parentNode ?? null;
+        }
+        if (current === null || current === undefined) {
+            return '/';
+        }
+        const pending = [];
+        let path;
+        let walk = current;
+        while (walk !== null && walk !== undefined && walk.nodeType === 1) {
+            const cached = this.paths.get(walk);
+            if (cached !== undefined) {
+                path = cached;
+                break;
+            }
+            pending.push(walk);
+            walk = walk.parentNode ?? null;
+        }
+        let prefix = path ?? '';
+        for (let i = pending.length - 1; i >= 0; i -= 1) {
+            const element = pending[i];
+            if (element === undefined) {
+                continue;
+            }
+            prefix = `${prefix}/${element.nodeName ?? '*'}[${this.position(element)}]`;
+            this.paths.set(element, prefix);
+        }
+        return prefix === '' ? '/' : prefix;
+    }
+    /** The 1-based position of `node` among its same-named element siblings. */
+    position(node) {
+        const cached = this.positions.get(node);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const parent = node.parentNode ?? undefined;
+        if (parent === undefined || parent === null) {
+            this.positions.set(node, 1);
+            return 1;
+        }
+        // Index the entire sibling list in one forward pass: the next result node under the same
+        // parent — the common case for a query over a list — then costs nothing.
+        const counts = new Map();
+        let child = parent.firstChild ?? null;
+        while (child !== null && child !== undefined) {
+            if (child.nodeType === 1) {
+                const name = child.nodeName ?? '*';
+                const next = (counts.get(name) ?? 0) + 1;
+                counts.set(name, next);
+                this.positions.set(child, next);
+            }
+            child = child.nextSibling ?? null;
+        }
+        return this.positions.get(node) ?? 1;
+    }
+}
+/** Best-effort text range for a node: available whenever xmldom recorded a source position for
+ * it (i.e. it was parsed, not constructed by an XQuery node constructor). The end offset is
+ * approximated from the serialised length, so it can drift on nodes containing entity
+ * references or non-canonical whitespace; callers treat it as advisory ("Reveal" selection),
+ * not as an exact byte-for-byte span. */
+function rangeOf(node, lineIndex, serialized) {
+    const position = getPosition(node);
+    if (position === undefined) {
+        return undefined;
+    }
+    const start = lineIndex.positionToOffset(position.line, position.column);
+    return { start, end: start + serialized.length };
+}
+/** Renders one node-shaped result item. */
+function toNodeItem(node, lineIndex, paths) {
+    const kind = NODE_TYPE[node.nodeType] ?? 'element';
+    if (node.nodeType === 2) {
+        const text = node.nodeValue ?? '';
+        return { text, nodeKind: 'attribute', path: paths.path(node) };
+    }
+    if (node.nodeType === 3) {
+        const text = node.nodeValue ?? '';
+        return { text, nodeKind: 'text', path: paths.path(node), ...withRange(node, lineIndex, text) };
+    }
+    const text = serializeXml(node);
+    return { text, nodeKind: kind, path: paths.path(node), ...withRange(node, lineIndex, text) };
+}
+/** Spreads `{range}` in only when one could be computed, keeping `exactOptionalPropertyTypes` happy. */
+function withRange(node, lineIndex, serialized) {
+    const range = rangeOf(node, lineIndex, serialized);
+    return range === undefined ? {} : { range };
+}
+/** A type label for an atomic XPath 3.1 value: maps and arrays are structural, everything else
+ * is reported by its JavaScript runtime type (fontoxpath does not expose the XML Schema type a
+ * value was cast from once it has been atomised, so this is a best-effort approximation). */
+function typeOf(value) {
+    if (Array.isArray(value)) {
+        return 'array';
+    }
+    if (typeof value === 'number') {
+        return Number.isInteger(value) ? 'xs:integer' : 'xs:double';
+    }
+    if (typeof value === 'boolean') {
+        return 'xs:boolean';
+    }
+    if (typeof value === 'string') {
+        return 'xs:string';
+    }
+    if (typeof value === 'object' && value !== null) {
+        return 'map';
+    }
+    /* v8 ignore next -- no fontoxpath item observed to be untyped-atomic under ALL_RESULTS_TYPE */
+    return 'xs:untypedAtomic';
+}
+/** Renders one atomic value as the Query view shows it: JSON for structures, plain text otherwise. */
+function toValueText(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    /* v8 ignore next 3 -- fontoxpath's own xs:dateTime/xs:date values are not JS `Date` instances */
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (typeof value === 'object' && value !== null) {
+        return JSON.stringify(value);
+    }
+    return String(value);
+}
+/** Reads the `{line, column}` fontoxpath attaches to a parse/evaluation error, when present. */
+function positionOf(error) {
+    const start = error.position?.start;
+    if (start === undefined || start.line === undefined) {
+        return undefined;
+    }
+    const column = start.ga ?? (start.offset !== undefined ? start.offset + 1 : undefined);
+    return column === undefined ? undefined : { line: start.line, column };
+}
+/** Extracts the stable error code fontoxpath prefixes onto most of its messages, e.g. `XPST0003`. */
+function codeOf(message) {
+    const match = /\b([A-Z]{4}\d{4})\b/.exec(message);
+    return match?.[1];
+}
+/**
+ * Evaluates an XPath 3.1 or XQuery 3.1 `expression` against `xml`.
+ *
+ * Never throws: parse failures, unresolved namespace prefixes, and runtime errors are all
+ * reported as `{kind: 'error'}` results instead, since a scratchpad query is expected to be
+ * wrong sometimes and the caller (the Query view) needs a value to render either way.
+ *
+ * @param xml the document to query (typically a response envelope)
+ * @param expression the XPath or XQuery source
+ * @param options language and namespace bindings
+ */
+export function evaluate(xml, expression, options) {
+    if (options.language === 'jsonpath') {
+        // Reachable only from a caller that paired the language with the wrong document kind; the
+        // Query view hides the JSONPath option for an XML response. Reported rather than thrown, like
+        // every other way a query can be wrong.
+        return { kind: 'error', message: 'JSONPath queries a JSON response, not an XML one' };
+    }
+    let doc;
+    try {
+        doc = parseXml(xml);
+    }
+    catch (error) {
+        return { kind: 'error', message: error instanceof Error ? error.message : String(error) };
+    }
+    const namespaces = options.namespaces ?? {};
+    const namespaceResolver = (prefix) => {
+        if (prefix === '') {
+            return namespaces[''] ?? null;
+        }
+        return namespaces[prefix] ?? null;
+    };
+    let raw;
+    try {
+        raw = evaluateXPath(expression, doc, null, null, evaluateXPath.ALL_RESULTS_TYPE, {
+            language: options.language === 'xquery' ? Language.XQUERY_3_1_LANGUAGE : Language.XPATH_3_1_LANGUAGE,
+            namespaceResolver,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const code = codeOf(message);
+        const position = positionOf(error);
+        const result = {
+            kind: 'error',
+            message,
+            ...(code !== undefined ? { code } : {}),
+            ...(position !== undefined ? { position } : {}),
+        };
+        return result;
+    }
+    if (raw.length === 0) {
+        return { kind: 'empty' };
+    }
+    const truncated = raw.length > RESULT_CAP;
+    const capped = raw.slice(0, RESULT_CAP);
+    const nodeLike = capped.filter(isNode);
+    // A query result is treated as "nodes" when every item is node-shaped; a mix (which XPath
+    // itself never produces from a single path expression, but a hand-written FLWOR could)
+    // falls back to "values" so nothing is silently dropped.
+    if (nodeLike.length === capped.length) {
+        // One `LineIndex` for the whole result set: `rangeOf` used to re-split the source document
+        // per item, which on a 1 MB response cost more than the XPath evaluation itself.
+        const lineIndex = new LineIndex(xml);
+        const paths = new PathIndex();
+        return {
+            kind: 'nodes',
+            items: capped.map((item) => toNodeItem(item, lineIndex, paths)),
+            truncated,
+        };
+    }
+    return {
+        kind: 'values',
+        items: capped.map((item) => ({ text: toValueText(item), type: typeOf(item) })),
+        truncated,
+    };
+}
+/**
+ * Evaluates `expression` against a JSON document.
+ *
+ * The parsed JSON *is* the context item, so a lookup starts at `?`: `?name` reads a field of a
+ * top-level object, `?*` every member of an array, and `?items?*[?status = "open"]?id` filters and
+ * projects in one expression. Results are always values — JSON has no nodes — so nothing here needs
+ * the document's text, and a result carries no source range.
+ *
+ * A `language` of `jsonpath` is delegated to {@link evaluateJsonPath} instead, which answers in this same
+ * result shape — so one caller, and one result renderer, covers all three languages.
+ *
+ * @param json the response body as text
+ * @param expression the XPath, XQuery or JSONPath source
+ * @param options language (namespaces are accepted and unused: JSON has no names to qualify)
+ */
+export function evaluateJson(json, expression, options) {
+    if (options.language === 'jsonpath') {
+        return evaluateJsonPath(json, expression);
+    }
+    let context;
+    try {
+        context = JSON.parse(json);
+    }
+    catch (error) {
+        // The same shape a malformed XML document produces, so one caller handles both.
+        return { kind: 'error', message: error instanceof Error ? error.message : String(error) };
+    }
+    let raw;
+    try {
+        raw = evaluateXPath(expression, context, null, null, evaluateXPath.ALL_RESULTS_TYPE, {
+            language: options.language === 'xquery' ? Language.XQUERY_3_1_LANGUAGE : Language.XPATH_3_1_LANGUAGE,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const code = codeOf(message);
+        const position = positionOf(error);
+        return {
+            kind: 'error',
+            message,
+            ...(code !== undefined ? { code } : {}),
+            ...(position !== undefined ? { position } : {}),
+        };
+    }
+    if (raw.length === 0) {
+        return { kind: 'empty' };
+    }
+    const truncated = raw.length > RESULT_CAP;
+    const capped = raw.slice(0, RESULT_CAP);
+    return {
+        kind: 'values',
+        items: capped.map((item) => ({ text: toValueText(item), type: typeOf(item) })),
+        truncated,
+    };
+}

package/dist/xpath/jsonpath.d.ts

@@ -0,0 +1,40 @@
+/**
+ * JSONPath evaluation against a JSON response body, for the response Query view's third language.
+ *
+ * It lives beside the XPath evaluators, not under `rest/`, for two reasons: JSONPath is a query
+ * language for JSON rather than anything REST-specific, and `rest/` carries the browser-safe subpath
+ * export (`@wirebench/engine/rest`) that the renderer imports — a Node-only dependency must not be
+ * reachable from there, for the same reason `fontoxpath` is not.
+ *
+ * XPath 3.1 already queries JSON (`xpath/evaluate.ts`'s `evaluateJson`), and it is the more capable
+ * of the two. JSONPath is here because it is the syntax REST users already have in their heads and
+ * in their notes — `$.items[?(@.status=="open")].id` is what a person pastes in from a README — and
+ * asking them to translate it into `?items?*[?status = "open"]?id` before they can check one field
+ * is friction with no payoff. Both languages stay available side by side.
+ *
+ * The result shape is identical to the XPath evaluators' {@link QueryResult}, so the Query view
+ * renders all three languages through one code path. JSONPath yields **values**, never nodes — JSON
+ * has none — and each item carries the normalised path it was found at, which is what makes a
+ * multi-match result readable.
+ *
+ * Filter and script expressions run under `eval: 'safe'`, which is load-bearing rather than a
+ * default worth inheriting silently. `jsonpath-plus` can evaluate `?(...)` and `(...)` with the
+ * platform's real `eval`/`Function`, or with a `jsep` expression parser that has no access to the
+ * host; `'safe'` selects the parser. So `$..book[?(@.price<10)]` works, and nothing reachable from a
+ * *response body* can execute. The expression is the user's own; the data it walks is whatever
+ * server answered, and that data never gets to run. (`eval: false` was the first thing tried and is
+ * wrong here: it does not harden the filter, it removes it — `?(...)` is refused outright, which
+ * takes most of JSONPath's usefulness with it.)
+ */
+import type { QueryResult } from './evaluate.js';
+/**
+ * Evaluates a JSONPath `expression` against a JSON document.
+ *
+ * Never throws: a malformed document and a malformed expression are both reported as
+ * `{kind: 'error'}`, the same as the XPath evaluators, because a scratchpad query is expected to be
+ * wrong sometimes and the caller needs a value to render either way.
+ *
+ * @param json the response body as text
+ * @param expression the JSONPath source, e.g. `$.items[?(@.status=="open")].id`
+ */
+export declare function evaluateJsonPath(json: string, expression: string): QueryResult;

package/dist/xpath/jsonpath.js

@@ -0,0 +1,109 @@
+/**
+ * JSONPath evaluation against a JSON response body, for the response Query view's third language.
+ *
+ * It lives beside the XPath evaluators, not under `rest/`, for two reasons: JSONPath is a query
+ * language for JSON rather than anything REST-specific, and `rest/` carries the browser-safe subpath
+ * export (`@wirebench/engine/rest`) that the renderer imports — a Node-only dependency must not be
+ * reachable from there, for the same reason `fontoxpath` is not.
+ *
+ * XPath 3.1 already queries JSON (`xpath/evaluate.ts`'s `evaluateJson`), and it is the more capable
+ * of the two. JSONPath is here because it is the syntax REST users already have in their heads and
+ * in their notes — `$.items[?(@.status=="open")].id` is what a person pastes in from a README — and
+ * asking them to translate it into `?items?*[?status = "open"]?id` before they can check one field
+ * is friction with no payoff. Both languages stay available side by side.
+ *
+ * The result shape is identical to the XPath evaluators' {@link QueryResult}, so the Query view
+ * renders all three languages through one code path. JSONPath yields **values**, never nodes — JSON
+ * has none — and each item carries the normalised path it was found at, which is what makes a
+ * multi-match result readable.
+ *
+ * Filter and script expressions run under `eval: 'safe'`, which is load-bearing rather than a
+ * default worth inheriting silently. `jsonpath-plus` can evaluate `?(...)` and `(...)` with the
+ * platform's real `eval`/`Function`, or with a `jsep` expression parser that has no access to the
+ * host; `'safe'` selects the parser. So `$..book[?(@.price<10)]` works, and nothing reachable from a
+ * *response body* can execute. The expression is the user's own; the data it walks is whatever
+ * server answered, and that data never gets to run. (`eval: false` was the first thing tried and is
+ * wrong here: it does not harden the filter, it removes it — `?(...)` is refused outright, which
+ * takes most of JSONPath's usefulness with it.)
+ */
+import { JSONPath } from 'jsonpath-plus';
+/** Result cap, matching `xpath/evaluate.ts`: a bigger result set is evaluated but reported
+ * truncated, so the UI can say so instead of silently hiding the rest. */
+const RESULT_CAP = 1_000;
+/** A type label for a JSON value, in JSON's own vocabulary rather than XML Schema's — a JSONPath
+ * user is thinking in `object`/`array`/`string`, not `xs:string`. */
+function typeOf(value) {
+    if (value === null) {
+        return 'null';
+    }
+    if (Array.isArray(value)) {
+        return 'array';
+    }
+    const type = typeof value;
+    return type === 'object' ? 'object' : type;
+}
+/** Renders one match as the Query view shows it: a string as itself, anything structural as JSON.
+ *
+ * Every branch is a JSON value, so the cases are closed: string, number, boolean, null, and the two
+ * structural kinds. `undefined` is not a JSON value but `JSONPath` can hand one back for a path that
+ * walked off the end of an object, so it gets a branch rather than becoming `"undefined"` by
+ * accident. */
+function toValueText(value) {
+    if (typeof value === 'string') {
+        return value;
+    }
+    if (typeof value === 'number' || typeof value === 'boolean') {
+        return String(value);
+    }
+    if (value === null) {
+        return 'null';
+    }
+    if (value === undefined) {
+        return 'undefined';
+    }
+    return JSON.stringify(value);
+}
+/**
+ * Evaluates a JSONPath `expression` against a JSON document.
+ *
+ * Never throws: a malformed document and a malformed expression are both reported as
+ * `{kind: 'error'}`, the same as the XPath evaluators, because a scratchpad query is expected to be
+ * wrong sometimes and the caller needs a value to render either way.
+ *
+ * @param json the response body as text
+ * @param expression the JSONPath source, e.g. `$.items[?(@.status=="open")].id`
+ */
+export function evaluateJsonPath(json, expression) {
+    let document;
+    try {
+        document = JSON.parse(json);
+    }
+    catch (error) {
+        return { kind: 'error', message: error instanceof Error ? error.message : String(error) };
+    }
+    let matches;
+    try {
+        // `resultType: 'all'` is what carries each match's normalised path alongside its value; `wrap`
+        // keeps the return an array even for a single match, so there is one shape to handle.
+        matches = JSONPath({
+            path: expression,
+            json: document,
+            resultType: 'all',
+            wrap: true,
+            eval: 'safe',
+        });
+    }
+    catch (error) {
+        return { kind: 'error', message: error instanceof Error ? error.message : String(error) };
+    }
+    if (matches.length === 0) {
+        return { kind: 'empty' };
+    }
+    const truncated = matches.length > RESULT_CAP;
+    const items = matches.slice(0, RESULT_CAP).map((match) => ({
+        text: toValueText(match.value),
+        type: typeOf(match.value),
+        path: match.path,
+    }));
+    return { kind: 'values', items, truncated };
+}

package/dist/xpath/namespaces.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Namespace discovery for the XPath/XQuery scratchpad: what prefixes are already bound in a
+ * response document, and what the engine would suggest for the ones that aren't.
+ */
+/**
+ * Collects every namespace prefix declared anywhere in `xml`, first binding wins (outermost
+ * declaration first, since traversal is document order and a descendant re-declaring a prefix
+ * does not overwrite the ancestor's entry here — the scratchpad only needs *a* usable binding
+ * per prefix, not exact in-scope shadowing at every node).
+ *
+ * The default namespace (`xmlns="..."`) is exposed under the empty-string key `''`; the caller
+ * (the Query view's namespace table) lets the user assign it a real prefix before running a
+ * query, since XPath has no syntax for referring to the default namespace directly.
+ *
+ * @param xml a well-formed XML document (typically a response envelope)
+ * @returns prefix (or `''` for the default namespace) to namespace URI
+ */
+export declare function collectNamespaces(xml: string): Record<string, string>;
+/**
+ * Suggests a prefix for every namespace URI used by an element or attribute in `xml` that has
+ * no prefix bound to it by {@link collectNamespaces} (e.g. the document only declares it as the
+ * default namespace, or an attribute uses a namespace no element declaration names). Reuses the
+ * engine's conventional-prefix heuristic ({@link prefixForNamespace}) so suggestions match what
+ * the rest of Wirebench would generate for the same URI.
+ *
+ * @param xml a well-formed XML document
+ * @returns namespace URI to suggested prefix, for URIs {@link collectNamespaces} left unbound
+ */
+export declare function suggestPrefixes(xml: string): Record<string, string>;

package/dist/xpath/namespaces.js

@@ -0,0 +1,101 @@
+/**
+ * Namespace discovery for the XPath/XQuery scratchpad: what prefixes are already bound in a
+ * response document, and what the engine would suggest for the ones that aren't.
+ */
+import { parseXml } from '../xml/parse.js';
+import { prefixForNamespace } from '../soap/prefixes.js';
+/** True for element nodes (xmldom `nodeType` 1) — the only nodes that carry `xmlns:*` attributes. */
+function isElement(node) {
+    return node.nodeType === 1;
+}
+/**
+ * Collects every namespace prefix declared anywhere in `xml`, first binding wins (outermost
+ * declaration first, since traversal is document order and a descendant re-declaring a prefix
+ * does not overwrite the ancestor's entry here — the scratchpad only needs *a* usable binding
+ * per prefix, not exact in-scope shadowing at every node).
+ *
+ * The default namespace (`xmlns="..."`) is exposed under the empty-string key `''`; the caller
+ * (the Query view's namespace table) lets the user assign it a real prefix before running a
+ * query, since XPath has no syntax for referring to the default namespace directly.
+ *
+ * @param xml a well-formed XML document (typically a response envelope)
+ * @returns prefix (or `''` for the default namespace) to namespace URI
+ */
+export function collectNamespaces(xml) {
+    const doc = parseXml(xml);
+    const bindings = {};
+    const visit = (node) => {
+        if (isElement(node)) {
+            const attributes = node.attributes;
+            for (let i = 0; i < attributes.length; i += 1) {
+                const attr = attributes.item(i);
+                /* v8 ignore next 3 -- `i < attributes.length` guarantees `item(i)` is non-null */
+                if (attr === null) {
+                    continue;
+                }
+                if (attr.name === 'xmlns') {
+                    if (!('' in bindings)) {
+                        bindings[''] = attr.value;
+                    }
+                }
+                else if (attr.name.startsWith('xmlns:')) {
+                    const prefix = attr.name.slice('xmlns:'.length);
+                    if (!(prefix in bindings)) {
+                        bindings[prefix] = attr.value;
+                    }
+                }
+            }
+        }
+        for (let child = node.firstChild; child !== null; child = child.nextSibling) {
+            visit(child);
+        }
+    };
+    /* v8 ignore next 3 -- `parseXml` throws before returning a document with no root element */
+    if (doc.documentElement !== null) {
+        visit(doc.documentElement);
+    }
+    return bindings;
+}
+/**
+ * Suggests a prefix for every namespace URI used by an element or attribute in `xml` that has
+ * no prefix bound to it by {@link collectNamespaces} (e.g. the document only declares it as the
+ * default namespace, or an attribute uses a namespace no element declaration names). Reuses the
+ * engine's conventional-prefix heuristic ({@link prefixForNamespace}) so suggestions match what
+ * the rest of Wirebench would generate for the same URI.
+ *
+ * @param xml a well-formed XML document
+ * @returns namespace URI to suggested prefix, for URIs {@link collectNamespaces} left unbound
+ */
+export function suggestPrefixes(xml) {
+    const doc = parseXml(xml);
+    const bound = collectNamespaces(xml);
+    // Only a *real* prefix (not the default namespace's '' entry) lets an XPath expression
+    // address the namespace directly — a URI bound only as the default namespace still needs a
+    // suggestion here even though `collectNamespaces` already reports it under ''.
+    const boundUris = new Set(Object.entries(bound)
+        .filter(([prefix]) => prefix !== '')
+        .map(([, uri]) => uri));
+    const taken = new Set(Object.keys(bound).filter((prefix) => prefix !== ''));
+    const suggestions = {};
+    // Attributes are never affected: an attribute can only carry a namespace URI via an explicit
+    // prefix (there is no such thing as a "default namespace" attribute in XML), and that prefix
+    // is always one `collectNamespaces` already found — so only element namespaces can be unbound.
+    const visit = (node) => {
+        if (isElement(node)) {
+            const uri = node.namespaceURI;
+            if (uri !== null && uri !== '' && !boundUris.has(uri) && !(uri in suggestions)) {
+                const prefix = prefixForNamespace(uri, taken);
+                taken.add(prefix);
+                suggestions[uri] = prefix;
+            }
+        }
+        for (let child = node.firstChild; child !== null; child = child.nextSibling) {
+            visit(child);
+        }
+    };
+    /* v8 ignore next 3 -- `parseXml` throws before returning a document with no root element */
+    if (doc.documentElement !== null) {
+        visit(doc.documentElement);
+    }
+    return suggestions;
+}

package/dist/xpath/worker.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Entry point run inside a `node:worker_threads` Worker by {@link evaluateWithTimeout}. Receives
+ * `{text, kind, expression, options}` as `workerData`, runs the synchronous evaluator once, and
+ * posts the {@link QueryResult} back — this file never imports anything Electron/DOM-specific,
+ * only what the evaluators themselves need, so it can run unmodified in a bare worker thread.
+ */
+export {};

package/dist/xpath/worker.js

@@ -0,0 +1,26 @@
+/**
+ * Entry point run inside a `node:worker_threads` Worker by {@link evaluateWithTimeout}. Receives
+ * `{text, kind, expression, options}` as `workerData`, runs the synchronous evaluator once, and
+ * posts the {@link QueryResult} back — this file never imports anything Electron/DOM-specific,
+ * only what the evaluators themselves need, so it can run unmodified in a bare worker thread.
+ */
+import { parentPort, workerData } from 'node:worker_threads';
+import { evaluate, evaluateJson } from './evaluate.js';
+/* v8 ignore start -- exercised only inside a real worker thread; covered by evaluate-async.test.ts
+   end-to-end (a query actually running to completion, or timing out), not by unit-level coverage
+   instrumentation, which does not attach across the thread boundary. */
+if (parentPort !== null) {
+    const request = workerData;
+    let result;
+    try {
+        result =
+            request.kind === 'json'
+                ? evaluateJson(request.text, request.expression, request.options)
+                : evaluate(request.text, request.expression, request.options);
+    }
+    catch (error) {
+        result = { kind: 'error', message: error instanceof Error ? error.message : String(error) };
+    }
+    parentPort.postMessage(result);
+}
+/* v8 ignore stop */