buninu-browser 0.1.0 → 0.2.1

package/lib/document-types.js

@@ -0,0 +1,308 @@
+/**
+ * What a top-level response looks like in the viewport. HTML is shown as
+ * itself; anything else gets a small generated HTML document, as browsers do
+ * for "standalone" resources (HTML §7.4.4-§7.4.7):
+ *
+ * - images: the image alone on a dark background, centered and fitted to the
+ *   width (SVG inline, other formats as a data: URL so they are not fetched
+ *   twice);
+ * - video and audio: a <video> or <audio> element for the URL on the same
+ *   background, with the file's name and type under it;
+ * - the formats bunmsh's `serve` previews, handled the way it does: Markdown
+ *   rendered with Bun.markdown.html, and JSON, JSON5, JSONC, JSON Lines, YAML,
+ *   TOML and XML parsed with Bun's parsers and printed as highlighted JSON,
+ *   under a "Pretty-print" checkbox that is on by default and, unticked,
+ *   shows the text as sent;
+ * - everything else, whatever its bytes: the text in a <pre>. There is no
+ *   "cannot be shown" page (see AGENTS.md).
+ *
+ * Large files would stall layout (on a phone, 1 MB of text takes seconds and
+ * 4 MB never finished): past DISPLAY_LIMIT only the start of the text is
+ * shown, and past PRETTY_LIMIT the preview is skipped for the text, each
+ * with a bar at the top that says so and points to casty's `download`.
+ *
+ * The bytes kept for downloads are the response's own, not this HTML. Text is
+ * decoded with the Content-Type charset, UTF-8 when there is none.
+ */
+
+const HTML_TYPES = new Set(["text/html", "application/xhtml+xml"]);
+// Measured on a phone: 256 KiB of text lays out in about 2 s; a 32 KiB
+// preview (highlighted JSON, many spans) in about 2.5 s.
+export const DISPLAY_LIMIT = 256 * 1024;
+export const PRETTY_LIMIT = 32 * 1024;
+
+// From bunmsh serve.js (MIT, same author): the formats it previews, by file
+// extension, with its parser names, pretty() and highlightJson().
+const PARSERS = new Map([
+  ["json", { name: "JSON.parse", parse: JSON.parse }],
+  ["json5", { name: "Bun.JSON5.parse", parse: Bun.JSON5.parse }],
+  ["jsonc", { name: "Bun.JSONC.parse", parse: Bun.JSONC.parse }],
+  ["jsonl", { name: "Bun.JSONL.parse", parse: Bun.JSONL.parse }],
+  ["ndjson", { name: "Bun.JSONL.parse", parse: Bun.JSONL.parse }],
+  ["yaml", { name: "Bun.YAML.parse", parse: Bun.YAML.parse }],
+  ["yml", { name: "Bun.YAML.parse", parse: Bun.YAML.parse }],
+  ["toml", { name: "Bun.TOML.parse", parse: Bun.TOML.parse }],
+]);
+if (typeof Bun.XML?.parse === "function") {
+  PARSERS.set("xml", { name: "Bun.XML.parse", parse: Bun.XML.parse });
+}
+const MARKDOWN = "Bun.markdown.html";
+
+// A URL without one of those extensions: its Content-Type names the format.
+const EXTENSION_BY_TYPE = new Map([
+  ["text/markdown", "md"], ["text/x-markdown", "md"],
+  ["application/json", "json"], ["text/json", "json"], ["application/json5", "json5"], ["application/jsonc", "jsonc"],
+  ["application/jsonl", "jsonl"], ["application/x-ndjson", "ndjson"], ["application/jsonlines", "jsonl"],
+  ["text/yaml", "yaml"], ["application/yaml", "yaml"], ["application/x-yaml", "yaml"], ["text/x-yaml", "yaml"],
+  ["application/toml", "toml"], ["text/x-toml", "toml"],
+  ["application/xml", "xml"], ["text/xml", "xml"],
+]);
+
+/** "md", a PARSERS key, or null: what bunmsh serve would preview this as. */
+function previewKind(name, type) {
+  const byName = extension(name);
+  if (byName === "md" || PARSERS.has(byName)) return byName;
+  const byType = EXTENSION_BY_TYPE.get(type) ?? (type.endsWith("+json") ? "json" : type.endsWith("+xml") ? "xml" : null);
+  return byType === "md" || PARSERS.has(byType) ? byType : null;
+}
+
+/**
+ * @param {{ url: string, contentType?: string, body: Uint8Array }} response
+ * @returns {{ source: string, contentType: string }}
+ */
+export function displayDocument({ url, contentType = "", body }) {
+  const { type, charset } = parseContentType(contentType);
+  const name = fileName(url);
+  if (HTML_TYPES.has(type) || (type === "" && looksLikeHtml(body))) {
+    return { source: decode(body, charset), contentType: contentType || "text/html" };
+  }
+  if (type === "image/svg+xml") return html(name, IMAGE_STYLE, `<div class="image">${stripProlog(decode(body, charset))}</div>`);
+  if (type.startsWith("image/")) {
+    const src = `data:${type};base64,${Buffer.from(body).toString("base64")}`;
+    return html(name, IMAGE_STYLE, `<div class="image"><img src="${src}" alt="${Bun.escapeHTML(name)}"></div>`);
+  }
+  const media = mediaKind(type, name);
+  if (media) return mediaDocument(url, name, type || media, media, body.byteLength);
+  const kind = previewKind(name, type);
+  if (kind && body.byteLength <= PRETTY_LIMIT) return previewDocument(url, name, kind, decode(body, charset));
+  // Everything else is shown as text, whatever the bytes are: no file is unviewable.
+  const note = kind
+    ? `Too large to pretty-print quickly (${formatSize(body.byteLength)})${body.byteLength > DISPLAY_LIMIT ? `; showing the first ${formatSize(DISPLAY_LIMIT)}` : ""}.`
+    : body.byteLength > DISPLAY_LIMIT ? `Large file (${formatSize(body.byteLength)}); showing the first ${formatSize(DISPLAY_LIMIT)}.` : null;
+  const shown = body.byteLength > DISPLAY_LIMIT ? body.subarray(0, DISPLAY_LIMIT) : body;
+  const bar = `<div class="bar"><span>${note ? `${note} The whole file: casty's <code>download</code> (Ctrl+E).` : ""}</span>${downloadButton(url)}</div>`;
+  return html(name, TEXT_STYLE, `${bar}<pre>${Bun.escapeHTML(decode(shown, charset))}</pre>`);
+}
+
+/** Built-in audio diagnostics page; CSS keys work without SVG or page scripts. */
+export function audioDemoDocument() {
+  const whites = [["A4", 69], ["B4", 71], ["C5", 72], ["D5", 74],
+    ["E5", 76], ["F5", 77], ["G5", 79], ["A5", 81]]
+    .map(([name, note]) => `<button type="button" class="white-key" data-piano-note="${note}"><span>${name}</span></button>`).join("");
+  const blacks = [["A♯4", 70, "8.75"], ["C♯5", 73, "33.75"], ["D♯5", 75, "46.25"],
+    ["F♯5", 78, "71.25"], ["G♯5", 80, "83.75"]]
+    .map(([name, note, left]) => `<button type="button" class="black-key" data-piano-note="${note}" style="left:${left}%"><span>${name}</span></button>`).join("");
+  const style = `:root { color-scheme: dark }
+body { margin: 0; min-height: 100vh; background: #151820; color: #f4f5f7; font: 15px sans-serif }
+.demo { max-width: 560px; margin: 0 auto; padding: 42px 18px 24px; text-align: center }
+h1 { margin: 0 0 8px; font-size: 24px }
+.note { color: #abb1c0; font-size: 13px; line-height: 1.5 }
+.keyboard { display: flex; position: relative; width: 100%; max-width: 420px; height: 150px; margin: 32px auto 20px; box-shadow: 0 8px 22px #0008 }
+.white-key { flex: 1; position: relative; box-sizing: border-box; padding: 0; border: 1px solid #6f7683; border-radius: 0 0 6px 6px; background: #f5f3ed; color: #2c3039; cursor: pointer; font: inherit }
+.white-key span { position: absolute; bottom: 9px; left: 0; right: 0; font-size: 12px }
+.black-key { position: absolute; z-index: 1; top: 0; width: 8.6%; height: 92px; padding: 0; border: 0; border-radius: 0 0 5px 5px; background: #262b35; box-shadow: 0 4px 5px #0008; color: #e8e8e8; cursor: pointer; font: inherit }
+.black-key span { position: absolute; bottom: 8px; left: 0; right: 0; font-size: 10px }
+input { box-sizing: border-box; width: 100%; max-width: 420px; padding: 10px 12px; border: 1px solid #858da0; border-radius: 7px; background: #222735; color: white; font: 15px sans-serif }
+input:focus { outline: 2px solid #90b4ff; outline-offset: 2px }`;
+  return html("Audio demo", style, `<main class="demo"><h1>Audio demo</h1>`
+    + `<p class="note">Tap a key, or click the field and play with Space, J, K and the LazyI keyboard bindings.</p>`
+    + `<div class="keyboard" aria-label="Piano keyboard">${whites}${blacks}</div>`
+    + `<input id="buninu-piano-input" type="text" autocomplete="off" placeholder="Play Piano · 彈鋼琴 · ピアノを弾く" aria-label="Play Piano">`
+    + `<p class="note">Space = A4 · J = B4 · K = C♯5</p></main>`);
+}
+
+function formatSize(bytes) {
+  return bytes >= 1024 * 1024 ? `${(bytes / 1024 / 1024).toFixed(1)} MB` : `${Math.round(bytes / 1024)} KB`;
+}
+
+// Media the renderer's decoder (wasmpeg's FFmpeg) handles: by type, or by
+// extension when the server's type says nothing.
+const VIDEO_TYPES = new Set(["application/ogg", "application/mp4", "application/x-matroska", "application/mxf"]);
+const VIDEO_EXTENSIONS = new Set(["mp4", "m4v", "mov", "webm", "mkv", "avi", "ogv", "ogg", "ts", "mts", "m2ts",
+  "mpg", "mpeg", "3gp", "3g2", "wmv", "flv", "mxf", "y4m"]);
+const AUDIO_EXTENSIONS = new Set(["mp3", "wav", "flac", "oga", "opus", "m4a", "aac", "wma", "aiff", "aif", "amr", "ac3", "mka"]);
+
+/** "video", "audio" or null. */
+function mediaKind(type, name) {
+  if (type.startsWith("video/") || VIDEO_TYPES.has(type)) return "video";
+  if (type.startsWith("audio/")) return "audio";
+  if (!["", "application/octet-stream", "binary/octet-stream"].includes(type)) return null;
+  const ext = extension(name);
+  return VIDEO_EXTENSIONS.has(ext) ? "video" : AUDIO_EXTENSIONS.has(ext) ? "audio" : null;
+}
+
+/** A media document (HTML §7.4.6): the element alone, playing the URL itself. */
+function mediaDocument(url, name, type, kind, size) {
+  const src = Bun.escapeHTML(url);
+  const about = `${Bun.escapeHTML(name)} (${Bun.escapeHTML(type)}, ${size} bytes)`;
+  const element = kind === "video"
+    ? `<video controls autoplay src="${src}"></video><p class="note">${about}. Click the video to play.</p>`
+    : `<audio controls src="${src}"></audio><p class="note">${about}. Click to play; `
+      + "sound goes to a PulseAudio server on 127.0.0.1:4713, such as jspulse.</p>";
+  const piano = kind === "audio" && (type === "audio/mpeg" || extension(name) === "mp3")
+    ? `<label class="piano">鋼琴 <input id="buninu-piano-input" type="text" autocomplete="off" placeholder="Space J K · F1–F12" aria-label="鋼琴鍵盤"></label>`
+    : "";
+  return html(name, IMAGE_STYLE, `${piano}<div class="image">${element}</div>`);
+}
+
+/** bunmsh serve's preview (its previewResponse), under a Pretty-print checkbox over the text as sent. */
+function previewDocument(url, name, kind, source) {
+  const raw = (hidden) => `<pre id="raw"${hidden ? " hidden" : ""}>${Bun.escapeHTML(source)}</pre>`;
+  const parser = PARSERS.get(kind);
+  const previewer = kind === "md" ? MARKDOWN : parser.name;
+  let formatted;
+  try {
+    formatted = kind === "md"
+      ? `<div id="formatted">${Bun.markdown.html(source, { headings: true })}</div>`
+      : `<pre id="formatted"><code>${highlightJson(pretty(parser.parse(source)))}</code></pre>`;
+  } catch (error) {
+    return html(`Cannot preview ${name}`, TEXT_STYLE, `<div class="bar"><span></span>${downloadButton(url)}</div><h1>Cannot preview ${Bun.escapeHTML(name)}</h1>`
+      + `<pre>${Bun.escapeHTML(error?.stack ?? String(error))}</pre>${raw(false)}`);
+  }
+  return html(`${name} — ${previewer}`, TEXT_STYLE, `<div class="bar"><span><label><input type="checkbox" id="pretty-print" checked> Pretty-print</label>`
+    + ` <span class="note">(${previewer})</span></span>${downloadButton(url)}</div>${formatted}${raw(true)}`
+    + `<script>(() => {
+  const box = document.getElementById("pretty-print");
+  const show = () => {
+    document.getElementById("formatted").hidden = !box.checked;
+    document.getElementById("raw").hidden = box.checked;
+  };
+  box.addEventListener("change", show);
+})();</script>`);
+}
+
+function downloadButton(url) {
+  return `<a class="download" href="${Bun.escapeHTML(url)}" download>Download</a>`;
+}
+
+// Centered in the viewport both ways, as browsers show a standalone image.
+const IMAGE_STYLE = `body { margin: 0; background: #0e0e0e }
+.image { min-height: 100vh; display: flex; align-items: center; justify-content: center }
+.image { flex-direction: column }
+.image img, .image svg { max-width: 100%; height: auto; background: white }
+.image video { max-width: 100% }
+.image .note { color: #bbb; font-family: sans-serif; font-size: 13px }
+.piano { position: fixed; z-index: 2; top: 8px; left: 8px; display: flex; align-items: center; gap: 5px; color: #eee; font: 13px sans-serif }
+.piano input { width: 128px; padding: 3px 5px; font: 13px sans-serif }`;
+// The link style and highlight colors are bunmsh serve's.
+const TEXT_STYLE = `:root { color-scheme: light dark }
+body { margin: 8px }
+a { color: inherit; text-decoration: none }
+pre { margin: 0; white-space: pre-wrap; overflow-wrap: anywhere; font-family: monospace }
+code { font: inherit }
+.bar { display: flex; justify-content: space-between; align-items: center; gap: 16px; font-family: sans-serif; margin-bottom: 8px }
+.download { margin-left: auto; padding: 4px 9px; border: 1px solid currentColor; border-radius: 4px; white-space: nowrap }
+.note { font-family: sans-serif; color: #666 }
+.json-statement { color: #b0005a }
+.json-string { color: #6b5d00 }
+.json-special { color: #087f5b }
+.json-number, .json-constant { color: #5f3dc4 }
+@media (prefers-color-scheme: dark) {
+  .json-statement { color: #f92672 }
+  .json-string { color: #e6db74 }
+  .json-special { color: #a6e22e }
+  .json-number, .json-constant { color: #ae81ff }
+}`;
+
+function html(title, style, body) {
+  return {
+    source: `<!doctype html><html><head><meta charset="utf-8"><title>${Bun.escapeHTML(title)}</title>`
+      + `<style>${style}</style></head><body>${body}</body></html>`,
+    contentType: "text/html",
+  };
+}
+
+// bunmsh serve.js pretty(): BigInts (TOML integers) keep their digits as "123n".
+const pretty = (value) => {
+  try {
+    return JSON.stringify(value, (_key, item) =>
+      typeof item === "bigint" ? `${item}n` : item, 2) ?? String(value);
+  } catch {
+    return Bun.inspect(value, { colors: false, depth: Infinity });
+  }
+};
+
+// bunmsh serve.js highlightJson(): statement keys, strings and escapes,
+// numbers, and true/false/null constants of the JSON pretty() emits.
+export const highlightJson = (source) => {
+  const input = String(source);
+  const token = /"(?:\\(?:u[\da-fA-F]{4}|.)|[^"\\])*"|-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?|\b(?:true|false|null)\b/g;
+  let output = "", cursor = 0, match;
+  const stringHtml = (value) => {
+    let html = "", offset = 0;
+    for (const escape of value.matchAll(/\\(?:u[\da-fA-F]{4}|.)/g)) {
+      html += Bun.escapeHTML(value.slice(offset, escape.index));
+      html += `<span class="json-special">${Bun.escapeHTML(escape[0])}</span>`;
+      offset = escape.index + escape[0].length;
+    }
+    return html + Bun.escapeHTML(value.slice(offset));
+  };
+  while ((match = token.exec(input))) {
+    output += Bun.escapeHTML(input.slice(cursor, match.index));
+    const value = match[0];
+    let end = token.lastIndex;
+    if (value.startsWith('"')) {
+      const propertyEnd = /^\s*:/.exec(input.slice(end));
+      if (propertyEnd) {
+        end += propertyEnd[0].length;
+        output += `<span class="json-statement">${Bun.escapeHTML(input.slice(match.index, end))}</span>`;
+      } else {
+        output += `<span class="json-string">${stringHtml(value)}</span>`;
+      }
+    } else if (value === "true" || value === "false" || value === "null") {
+      output += `<span class="json-constant">${value}</span>`;
+    } else {
+      output += `<span class="json-number">${value}</span>`;
+    }
+    cursor = end;
+    token.lastIndex = end;
+  }
+  return output + Bun.escapeHTML(input.slice(cursor));
+};
+
+export function parseContentType(value) {
+  const [type = "", ...parameters] = String(value).split(";");
+  const charset = parameters.map((part) => part.trim().match(/^charset=["']?([^"';]+)/i)?.[1]).find(Boolean) ?? null;
+  return { type: type.trim().toLowerCase(), charset };
+}
+
+function decode(body, charset) {
+  try {
+    return new TextDecoder(charset ?? "utf-8").decode(body);
+  } catch {
+    return new TextDecoder().decode(body);
+  }
+}
+
+function fileName(url) {
+  try {
+    const segment = new URL(url).pathname.split("/").filter(Boolean).pop() ?? "";
+    return decodeURIComponent(segment) || new URL(url).hostname || url;
+  } catch {
+    return String(url);
+  }
+}
+
+function extension(name) {
+  const dot = name.lastIndexOf(".");
+  return dot > 0 ? name.slice(dot + 1).toLowerCase() : "";
+}
+
+function stripProlog(svg) {
+  return svg.replace(/^\s*<\?xml[^>]*>\s*/i, "").replace(/<!DOCTYPE[^>]*>\s*/i, "");
+}
+
+function looksLikeHtml(body) {
+  const head = new TextDecoder().decode(body.subarray(0, 512)).trimStart().toLowerCase();
+  return head.startsWith("<!doctype html") || head.startsWith("<html") || head.startsWith("<head") || head.startsWith("<body") || head === "";
+}

package/lib/download-directory.js

@@ -0,0 +1,28 @@
+import { homedir } from "node:os";
+import { join, win32 } from "node:path";
+
+// Windows can move the Downloads known folder away from %USERPROFILE%. Query
+// its registered location through PowerShell so non-ASCII paths stay UTF-8.
+const WINDOWS_DOWNLOADS = [
+  "$OutputEncoding = [Console]::OutputEncoding = [Text.UTF8Encoding]::new($false)",
+  "$key = [Microsoft.Win32.Registry]::CurrentUser.OpenSubKey('Software\\Microsoft\\Windows\\CurrentVersion\\Explorer\\User Shell Folders')",
+  "if ($key) { $path = $key.GetValue('{374DE290-123F-4565-9164-39C4925E467B}'); if ($path) { [Console]::Write([Environment]::ExpandEnvironmentVariables($path)) } }",
+].join("; ");
+
+function windowsDownloads() {
+  try {
+    const result = Bun.spawnSync({ cmd: ["powershell.exe", "-NoProfile", "-NonInteractive", "-Command", WINDOWS_DOWNLOADS],
+      stdout: "pipe", stderr: "ignore" });
+    return result.exitCode === 0 ? new TextDecoder().decode(result.stdout).trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+export function downloadsDirectory({ platform = process.platform, home = homedir(), queryWindows = windowsDownloads } = {}) {
+  if (platform === "win32") {
+    const known = queryWindows();
+    return known && win32.isAbsolute(known) ? known : win32.join(home, "Downloads");
+  }
+  return join(home, "Downloads");
+}

package/lib/download.js

@@ -0,0 +1,63 @@
+import { mkdir, open, unlink } from "node:fs/promises";
+import { extname, join } from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { downloadsDirectory } from "./download-directory.js";
+
+export const DEFAULT_DOWNLOAD_DIR = downloadsDirectory();
+
+export function isAttachment(value) {
+  return /^\s*attachment\s*(?:;|$)/i.test(value ?? "");
+}
+
+export function suggestedFilename(url, disposition = "", attributeName = "") {
+  const encoded = /(?:^|;)\s*filename\*\s*=\s*(?:UTF-8''|utf-8'[^']*')([^;]+)/i.exec(disposition)?.[1];
+  const plain = /(?:^|;)\s*filename\s*=\s*(?:"([^"]*)"|([^;]*))/i.exec(disposition);
+  let name = "";
+  if (encoded) { try { name = decodeURIComponent(encoded.trim().replace(/^"|"$/g, "")); } catch {} }
+  if (!name) name = plain?.[1] ?? plain?.[2]?.trim() ?? attributeName;
+  if (!name) {
+    const target = new URL(url);
+    const segment = target.pathname.split("/").filter(Boolean).at(-1);
+    try { name = decodeURIComponent(segment ?? ""); } catch { name = segment ?? ""; }
+    if (!name) name = target.hostname || "download";
+  }
+  name = name.split(/[\\/]/).at(-1).replace(/[<>:"|?*\x00-\x1f\x7f]/g, "_").replace(/^\.+/, "_").replace(/[. ]+$/, "").slice(0, 200);
+  return name || "download";
+}
+
+/** Save a response stream or already held bytes without replacing an existing file. */
+export async function saveDownload({ url, disposition = "", attributeName = "", filename = null, body, dir = DEFAULT_DOWNLOAD_DIR }) {
+  await mkdir(dir, { recursive: true });
+  const name = filename ?? suggestedFilename(url, disposition, attributeName);
+  const extension = extname(name);
+  const stem = name.slice(0, name.length - extension.length);
+  let file;
+  let path;
+  for (let number = 1; ; number++) {
+    path = join(dir, number === 1 ? name : `${stem} (${number})${extension}`);
+    try { file = await open(path, "wx"); break; }
+    catch (error) { if (error.code !== "EEXIST") throw error; }
+  }
+  try {
+    let bytes = 0;
+    if (body instanceof Uint8Array) {
+      bytes = body.byteLength;
+      await file.writeFile(body);
+    } else if (body) {
+      const count = new Transform({ transform(chunk, _encoding, done) {
+        bytes += chunk.byteLength;
+        done(null, chunk);
+      } });
+      await pipeline(Readable.fromWeb(body), count, file.createWriteStream());
+    }
+    else await file.close();
+    return { path, name: path.slice(dir.length + 1), bytes };
+  } catch (error) {
+    await file.close().catch(() => {});
+    await unlink(path).catch(() => {});
+    throw error;
+  } finally {
+    await file.close().catch(() => {});
+  }
+}

package/lib/happy-dom/selector-matcher.js

@@ -0,0 +1,83 @@
+import * as PropertySymbol from "../../vendor/happy-dom/packages/happy-dom/src/PropertySymbol.ts";
+import QuerySelector from "../../vendor/happy-dom/packages/happy-dom/src/query-selector/QuerySelector.ts";
+import SelectorCombinatorEnum from "../../vendor/happy-dom/packages/happy-dom/src/query-selector/SelectorCombinatorEnum.ts";
+import SelectorParser from "../../vendor/happy-dom/packages/happy-dom/src/query-selector/SelectorParser.ts";
+
+/**
+ * Selector matching for the style engine, which matches tens of thousands of
+ * stylesheet selectors against every element. It gives the answers of Happy
+ * DOM's Element.matches() (same parser, same per-compound matching), without
+ * what that pays on every call: re-validating and looking up the selector
+ * string, and recording a cached result on the element and the elements it
+ * visited. The style engine keeps its own results.
+ */
+
+// Element.matches() rejects these before parsing (Happy DOM's QuerySelector).
+const INVALID_SELECTOR = /^[.#\[]?\d|[.#]$/;
+
+/**
+ * A selector compiled for matchesCompiled(), or null when it is invalid.
+ * `element` is any element of the document (it provides the window). The
+ * result does not depend on the document and may be kept with the selector.
+ * Returns undefined for objects that are not Happy DOM elements.
+ */
+export function compileSelector(element, selector) {
+  const window = element?.[PropertySymbol.window];
+  if (!window) return undefined;
+  selector = String(selector);
+  if (INVALID_SELECTOR.test(selector)) return null;
+  try {
+    const groups = new SelectorParser({ window, scope: element, globalMatchFunction: QuerySelector.globalMatchFunction })
+      .getSelectorGroups(selector);
+    // Matching walks from the subject (the last compound) leftwards.
+    return groups.map((items) => items.slice().reverse());
+  } catch {
+    return null;
+  }
+}
+
+/** Whether `element` matches a compiled selector, as element.matches(selector) would. */
+export function matchesCompiled(element, compiled) {
+  for (const items of compiled) {
+    if (matchItems(element, element, items, 0, null)) return true;
+  }
+  return false;
+}
+
+/** Happy DOM's QuerySelector.matchSelector, reduced to a yes or no. */
+function matchItems(scope, element, items, index, previous) {
+  const item = items[index];
+  if (!item) return false;
+  if (item.match(scope, element)) {
+    if (index === items.length - 1) return true;
+    switch (item.combinator) {
+      case SelectorCombinatorEnum.adjacentSibling: {
+        const sibling = element.previousElementSibling;
+        if (sibling && matchItems(scope, sibling, items, index + 1, item)) return true;
+        break;
+      }
+      case SelectorCombinatorEnum.none:
+      case SelectorCombinatorEnum.child:
+      case SelectorCombinatorEnum.descendant: {
+        const parent = element.parentNode;
+        if (parent && parent !== element[PropertySymbol.ownerDocument] && matchItems(scope, parent, items, index + 1, item)) return true;
+        break;
+      }
+      case SelectorCombinatorEnum.subsequentSibling: {
+        const parent = element.parentNode;
+        if (parent && parent !== element[PropertySymbol.ownerDocument]) {
+          const siblings = parent[PropertySymbol.elementArray];
+          for (let i = siblings.indexOf(element) - 1; i >= 0; i--) {
+            if (matchItems(scope, siblings[i], items, index + 1, item)) return true;
+          }
+        }
+        break;
+      }
+    }
+  }
+  if (previous?.combinator === SelectorCombinatorEnum.none || previous?.combinator === SelectorCombinatorEnum.descendant) {
+    const parent = element.parentNode;
+    if (parent && parent !== element[PropertySymbol.ownerDocument]) return matchItems(scope, parent, items, index, previous);
+  }
+  return false;
+}