meta-sovereign 0.49.4 → 0.49.5

package/js/src/sources/archive/context.js

@@ -0,0 +1,99 @@
+/**
+ * What an archive importer gets besides the parsed file (R-Z10): the
+ * other files of the same archive (to find a message's photo, video…),
+ * a sink that copies them into `<store>/media/<network>/<sha256>.<ext>`
+ * (owner-only, content-addressed so a second import writes nothing new),
+ * and per-import counters so ids stay unique across `message_N.json`.
+ */
+
+import { baseName } from './text.js';
+
+// Errors that mean "the disk cannot take this" (R-Z14): never swallowed.
+const FATAL = new Set(['ENOSPC', 'EDQUOT', 'EROFS', 'EIO', 'EACCES', 'EPERM']);
+
+export const isFatalWrite = (error) =>
+  FATAL.has(error?.code) ||
+  error?.code === 'STORE_WRITE_FAILED' ||
+  error?.code === 'STORE_FULL';
+
+/**
+ * @param {object} options
+ * @param {string} options.network   folder name under media/
+ * @param {Array} [options.entries]  files of the archive (zip entries)
+ * @param {Function|null} [options.save]  `({entry, folder}) => Promise<{path, sha256, size}>`
+ *   copies an archive file into media/ (Node only, ./media-store.js); null = not copied
+ */
+export const createArchiveContext = ({
+  network,
+  entries = [],
+  save = null,
+}) => {
+  const byName = new Map(entries.map((entry) => [entry.name, entry]));
+  const saved = new Map();
+  const counters = new Map();
+  const warnings = [];
+  let baseIndex = null;
+  const byBase = () => {
+    if (!baseIndex) {
+      baseIndex = new Map();
+      for (const entry of entries) {
+        const base = baseName(entry.name);
+        const list = baseIndex.get(base);
+        if (list) {
+          list.push(entry);
+        } else {
+          baseIndex.set(base, [entry]);
+        }
+      }
+    }
+    return baseIndex;
+  };
+  const find = (uri) => {
+    const clean = String(uri).replace(/^\.?\//, '');
+    if (byName.has(clean)) {
+      return byName.get(clean);
+    }
+    // The archive may sit in a top-level folder (`facebook-name-2026/`).
+    const suffix = `/${clean}`;
+    return (
+      (byBase().get(baseName(clean)) ?? []).find((entry) =>
+        entry.name.endsWith(suffix)
+      ) ?? null
+    );
+  };
+  return {
+    network,
+    warnings,
+    // Facts one file tells the next (X's account.js names "me").
+    state: {},
+    /** 0, 1, 2… for the n-th time `key` is seen in this import. */
+    ordinal(key) {
+      const n = counters.get(key) ?? 0;
+      counters.set(key, n + 1);
+      return n;
+    },
+    /** The archive file `uri` names, copied into media/; null if absent. */
+    async media(uri, folder = network) {
+      const entry = uri ? find(uri) : null;
+      if (!entry || !save) {
+        return null;
+      }
+      if (!saved.has(entry.name)) {
+        saved.set(entry.name, copyEntry({ entry, save, folder, warnings }));
+      }
+      return saved.get(entry.name);
+    },
+  };
+};
+
+const copyEntry = async ({ entry, save, folder, warnings }) => {
+  try {
+    return await save({ entry, folder });
+  } catch (error) {
+    if (isFatalWrite(error)) {
+      throw error;
+    }
+    warnings.push(`${entry.name}: ${error.message}`);
+    return null;
+  }
+};

package/js/src/sources/archive/legacy.js

@@ -0,0 +1,64 @@
+/**
+ * Re-importing an archive that an older build imported (R-Z10).
+ *
+ * Before R-Z10 a Facebook message was `msg:facebook:<ms>` and a LinkedIn
+ * one `msg:linkedin:<conversation>-<date>`. A link built from an archive
+ * row carries (under a symbol, so it is never stored) the old id it had
+ * and what that old link must look like (sender, chat). The importer
+ * skips a row whose old link is already in the store, under the old id or
+ * under the id migration 0005 moved it to (`alias:<old id>`), so the
+ * import does not double the history.
+ */
+
+import { fixMojibake } from './text.js';
+
+export const LEGACY = Symbol('legacyArchiveId');
+
+/** Mark `link` as the new form of the old `{ id, sender, chat }`. */
+export const withLegacy = (link, legacy) => ({ ...link, [LEGACY]: legacy });
+
+const lastPart = (chat) =>
+  String(chat ?? '')
+    .split('/')
+    .filter(Boolean)
+    .at(-1) ?? '';
+
+// An old Facebook chat was the whole `thread_path`; the new one its folder.
+const sameChat = (stored, wanted) =>
+  stored === wanted || lastPart(stored) === lastPart(wanted);
+
+const sameSender = (stored, wanted) =>
+  [stored?.sender, stored?.senderName].some(
+    (name) => fixMojibake(name) === wanted
+  );
+
+// The link the old id stands for, now or after migration; null if none.
+const storedLegacy = async (store, id) => {
+  if (typeof store.get !== 'function') {
+    return null;
+  }
+  const alias = await store.get(`alias:${id}`);
+  return (alias?.to ? await store.get(alias.to) : null) ?? store.get(id);
+};
+
+/**
+ * True when `link`'s old-scheme twin is already stored. `claimed` makes
+ * one old link account for one row (old ids collided, so a second row
+ * with the same old id is a different message and is written).
+ */
+export const alreadyImported = async (store, link, claimed) => {
+  const legacy = link[LEGACY];
+  if (!legacy || claimed.has(legacy.id)) {
+    return false;
+  }
+  const there = await storedLegacy(store, legacy.id);
+  if (
+    there &&
+    sameChat(there.chat, legacy.chat) &&
+    sameSender(there, legacy.sender)
+  ) {
+    claimed.add(legacy.id);
+    return true;
+  }
+  return false;
+};

package/js/src/sources/archive/media-store.js

@@ -0,0 +1,60 @@
+/**
+ * Copies archive files into `<store>/media/<network>/<sha256><ext>`
+ * (R-Z10): owner-only, content-addressed (a second import writes
+ * nothing new), streamed through a hash so large videos never sit in
+ * memory. Node only; the page never loads this.
+ */
+
+import { createHash, randomBytes } from 'node:crypto';
+import { createWriteStream, promises as fs } from 'node:fs';
+import path from 'node:path';
+import { pipeline } from 'node:stream/promises';
+
+const extensionOf = (name) => {
+  const ext = path.extname(String(name ?? '')).toLowerCase();
+  return /^\.[a-z0-9]{1,8}$/.test(ext) ? ext : '';
+};
+
+/** Copy a byte stream to `<mediaDir>/<network>/<sha256><ext>` (0600). */
+export const saveMedia = async ({ mediaDir, network, stream, name }) => {
+  const dir = path.join(mediaDir, network);
+  // Private from the first byte: media/ and media/<network>/ are 0700.
+  for (const folder of [mediaDir, dir]) {
+    await fs.mkdir(folder, { recursive: true, mode: 0o700 });
+  }
+  const temp = path.join(dir, `.tmp-${randomBytes(6).toString('hex')}`);
+  const hash = createHash('sha256');
+  let size = 0;
+  try {
+    await pipeline(
+      stream,
+      async function* (source) {
+        for await (const chunk of source) {
+          hash.update(chunk);
+          size += chunk.length;
+          yield chunk;
+        }
+      },
+      createWriteStream(temp, { mode: 0o600 })
+    );
+    const sha256 = hash.digest('hex');
+    const file = `${sha256}${extensionOf(name)}`;
+    await fs.rename(temp, path.join(dir, file));
+    await fs.chmod(path.join(dir, file), 0o600);
+    return { path: `media/${network}/${file}`, sha256, size };
+  } catch (error) {
+    await fs.rm(temp, { force: true }).catch(() => {});
+    throw error;
+  }
+};
+
+/** A `save` function for createArchiveContext, writing under `mediaDir`. */
+export const mediaSaver =
+  (mediaDir) =>
+  async ({ entry, folder }) =>
+    saveMedia({
+      mediaDir,
+      network: folder,
+      stream: await entry.stream(),
+      name: entry.name,
+    });

package/js/src/sources/archive/meta-thread.js

@@ -0,0 +1,278 @@
+/**
+ * Facebook / Messenger and Instagram "Download your information" threads
+ * (R-Z10): `messages/inbox/<thread>/message_N.json` (and `.html`) turned
+ * into message links.
+ *
+ * Ids are `<thread folder>:<timestamp ms>:<sender digest>:<n>` where n
+ * counts messages of the same sender in the same millisecond, so two
+ * messages never collide and importing the same archive again lands on
+ * the same ids (no duplicates). The thread id is the folder name.
+ * Learned from Meta's documented export layout, never from real data.
+ */
+
+import { buildMessageLink } from '../link.js';
+import { withLegacy } from './legacy.js';
+import {
+  fixDeep,
+  baseName,
+  extName,
+  fixMojibake,
+  findAll,
+  hasClass,
+  isoOf,
+  parseHtml,
+  shortHash,
+  textOf,
+} from './text.js';
+
+const MIME = {
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.png': 'image/png',
+  '.gif': 'image/gif',
+  '.webp': 'image/webp',
+  '.heic': 'image/heic',
+  '.mp4': 'video/mp4',
+  '.mov': 'video/quicktime',
+  '.webm': 'video/webm',
+  '.mp3': 'audio/mpeg',
+  '.m4a': 'audio/mp4',
+  '.aac': 'audio/aac',
+  '.ogg': 'audio/ogg',
+  '.wav': 'audio/wav',
+  '.pdf': 'application/pdf',
+};
+
+// JSON key → attachment kind (a list of items, except `sticker`).
+const ATTACHMENT_KEYS = [
+  ['photos', 'photo'],
+  ['videos', 'video'],
+  ['audio_files', 'audio'],
+  ['files', 'file'],
+  ['gifs', 'gif'],
+  ['sticker', 'sticker'],
+];
+
+const attachmentOf = async (ctx, network, kind, item) => {
+  const uri = typeof item === 'string' ? item : item?.uri;
+  if (!uri) {
+    return null;
+  }
+  const name = baseName(uri);
+  const mime = MIME[extName(name)];
+  const copy = await ctx.media(uri, network);
+  return {
+    kind,
+    name,
+    ...(mime ? { mime } : {}),
+    ...(copy ? { path: copy.path, sha256: copy.sha256, size: copy.size } : {}),
+  };
+};
+
+const attachmentsOf = async (ctx, network, message) => {
+  const out = [];
+  for (const [key, kind] of ATTACHMENT_KEYS) {
+    const value = message[key];
+    for (const item of Array.isArray(value) ? value : value ? [value] : []) {
+      const att = await attachmentOf(ctx, network, kind, item);
+      if (att) {
+        out.push(att);
+      }
+    }
+  }
+  if (message.share?.link) {
+    out.push({
+      kind: 'link',
+      url: message.share.link,
+      caption: message.share.share_text ?? null,
+    });
+  }
+  return out;
+};
+
+// [{reaction, actor}] → [{emoji, count, by}] (one row per emoji).
+const reactionsOf = (list) => {
+  const byEmoji = new Map();
+  for (const r of Array.isArray(list) ? list : []) {
+    if (r?.reaction) {
+      const row = byEmoji.get(r.reaction) ?? {
+        emoji: r.reaction,
+        count: 0,
+        by: [],
+      };
+      row.count += 1;
+      if (r.actor) {
+        row.by.push(r.actor);
+      }
+      byEmoji.set(r.reaction, row);
+    }
+  }
+  return [...byEmoji.values()];
+};
+
+/** The thread id: the folder holding the message files. */
+export const threadIdOf = (entryName, obj) => {
+  const parts = String(entryName ?? '')
+    .split(/[\\/]/)
+    .filter(Boolean);
+  const folder = parts.length >= 2 ? parts.at(-2) : null;
+  const fromPath = String(obj?.thread_path ?? '')
+    .split('/')
+    .filter(Boolean)
+    .at(-1);
+  return folder || fromPath || obj?.title || 'unknown';
+};
+
+const chatTypeOf = (participants) => {
+  if (participants.length === 0) {
+    return null;
+  }
+  return participants.length > 2 ? 'group' : 'private';
+};
+
+const linkOf = async ({ network, ctx, thread, header, message }) => {
+  const sender = message.sender_name ?? 'unknown';
+  const ts = message.timestamp_ms ?? message.timestamp ?? 'nots';
+  const n = ctx.ordinal(`${thread}|${ts}|${sender}`);
+  const link = buildMessageLink({
+    source: network,
+    externalId: `${thread}:${ts}:${shortHash(sender)}:${n}`,
+    sender,
+    chat: thread,
+    body: typeof message.content === 'string' ? message.content : '',
+    timestamp: isoOf(message.timestamp_ms ?? message.timestamp),
+    senderName: sender,
+    chatName: header.title,
+    chatType: chatTypeOf(header.participants),
+    participants: header.participants,
+    attachments: await attachmentsOf(ctx, network, message),
+    reactions: reactionsOf(message.reactions),
+    deleted: message.is_unsent === true ? true : null,
+  });
+  // What an older build called it: `<ms>` or `<sender>-<seconds>`.
+  const old =
+    message.timestamp_ms ?? `${message.sender_name}-${message.timestamp}`;
+  return withLegacy(link, { id: `msg:facebook:${old}`, sender, chat: thread });
+};
+
+const headerOf = (obj) => ({
+  title: obj.title ?? null,
+  participants: (obj.participants ?? [])
+    .map((p) => (typeof p === 'string' ? p : p?.name))
+    .filter(Boolean),
+});
+
+/** One `message_N.json` (object or text) → links. */
+export const metaJsonToLinks = async ({ network, archive, ctx, entryName }) => {
+  const obj = fixDeep(
+    typeof archive === 'string' ? JSON.parse(archive) : archive
+  );
+  const thread = threadIdOf(entryName, obj);
+  const header = headerOf(obj);
+  const links = [];
+  for (const message of obj.messages ?? []) {
+    links.push(await linkOf({ network, ctx, thread, header, message }));
+  }
+  return links;
+};
+
+// ---- HTML export ---------------------------------------------------------
+
+const MONTHS = 'jan feb mar apr may jun jul aug sep oct nov dec'.split(' ');
+const DATE =
+  /([A-Za-z]{3,9})\.? (\d{1,2}),? (\d{4}),? (\d{1,2}):(\d{2})(?::(\d{2}))?\s*(am|pm)?/i;
+
+// "Jan 01, 2024 10:00:00 am" (English exports; the export does not say
+// its zone, so it is read in this machine's time zone). Other languages fall through to Date.parse.
+export const htmlDateToMs = (text) => {
+  const m = DATE.exec(text ?? '');
+  const month = m ? MONTHS.indexOf(m[1].slice(0, 3).toLowerCase()) : -1;
+  if (!m || month < 0) {
+    const parsed = Date.parse(text ?? '');
+    return Number.isNaN(parsed) ? null : parsed;
+  }
+  let hour = Number(m[4]) % (m[7] ? 12 : 24);
+  if (m[7]?.toLowerCase() === 'pm') {
+    hour += 12;
+  }
+  return new Date(
+    Number(m[3]),
+    month,
+    Number(m[2]),
+    hour,
+    Number(m[5]),
+    Number(m[6] ?? 0)
+  ).getTime();
+};
+
+const MESSAGE = ['_a6-g', '_3-95'];
+const SENDER = ['_a6-h', '_2lek'];
+const BODY = ['_a6-p', '_2let'];
+const WHEN = ['_a6-o', '_2lem'];
+const REACTIONS = ['_a6-q', '_tqp'];
+
+const REACTION = /^(\P{L}+?)\s*(\p{L}.*)$/su;
+
+const firstOf = (node, names) =>
+  findAll(node, (n) => hasClass(n, names))[0] ?? null;
+
+const htmlAttachments = async (ctx, network, body) => {
+  const out = [];
+  const media = findAll(body, (n) =>
+    ['img', 'video', 'audio', 'source', 'a'].includes(n.tag)
+  );
+  const kinds = {
+    img: 'photo',
+    video: 'video',
+    audio: 'audio',
+    source: 'video',
+    a: 'file',
+  };
+  for (const node of media) {
+    const uri = node.attrs.src ?? node.attrs.href;
+    if (uri && !/^[a-z]+:/i.test(uri)) {
+      const att = await attachmentOf(ctx, network, kinds[node.tag], uri);
+      if (att) {
+        out.push(att);
+      }
+    }
+  }
+  return out;
+};
+
+const htmlMessage = async (ctx, network, node) => {
+  const body = firstOf(node, BODY);
+  const reactions = firstOf(body ?? node, REACTIONS);
+  const likes = findAll(reactions, (n) => n.tag === 'li').map((li) => {
+    const m = REACTION.exec(textOf(li).trim());
+    return m ? { reaction: m[1].trim(), actor: m[2].trim() } : null;
+  });
+  const content = body
+    ? textOf(body, (n) => hasClass(n, REACTIONS))
+        .replace(/[ \t]*\n[ \t]*/g, '\n')
+        .trim()
+    : '';
+  return {
+    sender_name: textOf(firstOf(node, SENDER) ?? '').trim(),
+    timestamp_ms: htmlDateToMs(textOf(firstOf(node, WHEN) ?? '').trim()),
+    content,
+    reactions: likes.filter(Boolean),
+    _attachments: body ? await htmlAttachments(ctx, network, body) : [],
+  };
+};
+
+/** One `message_N.html` → links (English dates; see htmlDateToMs). */
+export const metaHtmlToLinks = async ({ network, html, ctx, entryName }) => {
+  const tree = parseHtml(html);
+  const title = textOf(findAll(tree, (n) => n.tag === 'title')[0] ?? '').trim();
+  const thread = threadIdOf(entryName, { title });
+  const header = { title: fixMojibake(title) || null, participants: [] };
+  const links = [];
+  for (const node of findAll(tree, (n) => hasClass(n, MESSAGE))) {
+    const message = await htmlMessage(ctx, network, node);
+    const link = await linkOf({ network, ctx, thread, header, message });
+    const attachments = message._attachments;
+    links.push(attachments.length ? { ...link, attachments } : link);
+  }
+  return links;
+};

package/js/src/sources/archive/text.js

@@ -0,0 +1,207 @@
+/**
+ * Text repairs shared by the data-archive importers (R-Z10).
+ */
+
+const FFFD = '�';
+
+/**
+ * Facebook / Instagram JSON exports write UTF-8 bytes as if each byte
+ * were a latin-1 character ("Ð\u0098" for "И"). Decode only when the
+ * text is all single-byte characters AND the bytes are valid UTF-8 that
+ * encodes back to the same bytes, so honest latin-1 text is never damaged.
+ */
+export const fixMojibake = (value) => {
+  if (typeof value !== 'string' || !/[\u0080-\u00ff]/.test(value)) {
+    return value;
+  }
+  if ([...value].some((c) => c.codePointAt(0) > 0xff)) {
+    return value;
+  }
+  const bytes = Uint8Array.from(value, (c) => c.charCodeAt(0));
+  let decoded;
+  try {
+    decoded = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+  } catch {
+    return value;
+  }
+  const again = new TextEncoder().encode(decoded);
+  const same =
+    again.length === bytes.length && again.every((b, i) => b === bytes[i]);
+  return same && !decoded.includes(FFFD) ? decoded : value;
+};
+
+/** `fixMojibake` over every string inside a parsed JSON value. */
+export const fixDeep = (value) => {
+  if (typeof value === 'string') {
+    return fixMojibake(value);
+  }
+  if (Array.isArray(value)) {
+    return value.map(fixDeep);
+  }
+  if (value && typeof value === 'object') {
+    return Object.fromEntries(
+      Object.entries(value).map(([key, item]) => [key, fixDeep(item)])
+    );
+  }
+  return value;
+};
+
+/**
+ * A short stable hex digest (cyrb53, 53 bits), for parts of ids that may
+ * hold odd text. Pure JS so the module also loads in the page.
+ */
+export const shortHash = (text) => {
+  let h1 = 0xdeadbeef;
+  let h2 = 0x41c6ce57;
+  for (const ch of String(text)) {
+    const code = ch.codePointAt(0);
+    h1 = Math.imul(h1 ^ code, 2654435761);
+    h2 = Math.imul(h2 ^ code, 1597334677);
+  }
+  h1 =
+    Math.imul(h1 ^ (h1 >>> 16), 2246822507) ^
+    Math.imul(h2 ^ (h2 >>> 13), 3266489909);
+  h2 =
+    Math.imul(h2 ^ (h2 >>> 16), 2246822507) ^
+    Math.imul(h1 ^ (h1 >>> 13), 3266489909);
+  return (4294967296 * (2097151 & h2) + (h1 >>> 0))
+    .toString(16)
+    .padStart(14, '0');
+};
+
+/** The last path segment ("a/b/c.jpg" -> "c.jpg"), "/" or "\\" separated. */
+export const baseName = (p) =>
+  String(p).split(/[\\/]/).filter(Boolean).at(-1) ?? '';
+
+/** The extension with its dot, lower case ("c.JPG" -> ".jpg"), or "". */
+export const extName = (p) => {
+  const m = /\.[^./\\]+$/.exec(baseName(p));
+  return m ? m[0].toLowerCase() : '';
+};
+
+/** ISO text for an epoch (ms) or a date string; null when unreadable. */
+export const isoOf = (value) => {
+  if (value === null || value === undefined || value === '') {
+    return null;
+  }
+  const numeric = typeof value === 'string' && /^\d+$/.test(value);
+  const date = new Date(numeric ? Number(value) : value);
+  return Number.isNaN(date.getTime()) ? null : date.toISOString();
+};
+
+// "2026-01-01 10:00:00 UTC" is UTC; a time that names no zone is read in
+// this machine's time zone (like WhatsApp and VK exports); other shapes
+// fall back to Date.parse.
+const STAMP =
+  /^(\d{4})-(\d\d)-(\d\d)[ T](\d\d):(\d\d)(?::(\d\d))?\s*(UTC|GMT|Z)?$/i;
+
+/** ISO text for a LinkedIn export date; null when unreadable. */
+export const linkedinDate = (text) => {
+  const m = STAMP.exec(String(text ?? '').trim());
+  if (m) {
+    const parts = [+m[1], +m[2] - 1, +m[3], +m[4], +m[5], +(m[6] ?? 0)];
+    return (
+      m[7] ? new Date(Date.UTC(...parts)) : new Date(...parts)
+    ).toISOString();
+  }
+  return isoOf(String(text ?? '').trim());
+};
+
+const ENTITIES = {
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+  nbsp: ' ',
+};
+
+export const decodeEntities = (text) =>
+  text.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (whole, code) => {
+    if (code[0] === '#') {
+      const point =
+        code[1].toLowerCase() === 'x'
+          ? parseInt(code.slice(2), 16)
+          : parseInt(code.slice(1), 10);
+      return Number.isFinite(point) && point <= 0x10ffff
+        ? String.fromCodePoint(point)
+        : whole;
+    }
+    return ENTITIES[code.toLowerCase()] ?? whole;
+  });
+
+const VOID = new Set(['br', 'img', 'hr', 'input', 'meta', 'link']);
+const TOKEN =
+  /<!--[\s\S]*?-->|<(\/?)([a-zA-Z][\w-]*)((?:[^>"']|"[^"]*"|'[^']*')*)>|([^<]+)/g;
+const ATTRIBUTE = /([\w:-]+)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
+
+const attributesOf = (source) => {
+  const attrs = {};
+  for (const a of source.matchAll(ATTRIBUTE)) {
+    attrs[a[1].toLowerCase()] = decodeEntities(a[2] ?? a[3]);
+  }
+  return attrs;
+};
+
+/**
+ * A tiny HTML reader for the data exports (no dependency): a tree of
+ * `{tag, attrs, children}` and text strings. Tolerant: stray end tags
+ * are ignored, unclosed tags are closed at the end.
+ */
+export const parseHtml = (html) => {
+  const root = { tag: 'root', attrs: {}, children: [] };
+  const stack = [root];
+  for (const m of html.matchAll(TOKEN)) {
+    const top = stack.at(-1);
+    if (m[4] !== undefined) {
+      top.children.push(decodeEntities(m[4]));
+    } else if (m[2] && m[1]) {
+      const at = stack.map((n) => n.tag).lastIndexOf(m[2].toLowerCase());
+      if (at > 0) {
+        stack.length = at;
+      }
+    } else if (m[2]) {
+      const node = {
+        tag: m[2].toLowerCase(),
+        attrs: attributesOf(m[3]),
+        children: [],
+      };
+      top.children.push(node);
+      if (!VOID.has(node.tag) && !m[3].trimEnd().endsWith('/')) {
+        stack.push(node);
+      }
+    }
+  }
+  return root;
+};
+
+export const hasClass = (node, names) => {
+  const classes = (node?.attrs?.class ?? '').split(/\s+/);
+  return names.some((name) => classes.includes(name));
+};
+
+/** Every element under `node` (depth-first) accepted by `test`. */
+export const findAll = (node, test, out = []) => {
+  for (const child of node?.children ?? []) {
+    if (typeof child !== 'string') {
+      if (test(child)) {
+        out.push(child);
+      }
+      findAll(child, test, out);
+    }
+  }
+  return out;
+};
+
+/** The text of a node; `skip(node)` leaves a subtree out. */
+export const textOf = (node, skip = null) => {
+  if (typeof node === 'string') {
+    return node;
+  }
+  if (skip?.(node)) {
+    return '';
+  }
+  return node.tag === 'br'
+    ? '\n'
+    : node.children.map((child) => textOf(child, skip)).join('');
+};