@nitpicker/crawler 0.18.1 → 0.20.0

package/lib/archive/retarget-legacy-fk-tables.d.ts

@@ -1,21 +1,34 @@
 import type { Knex } from 'knex';
 /**
  * Rewrites the FK declarations of the adjunct tables from the legacy
- * `pages(id)` to `content_items(id)` by rebuilding each table. SQLite has
- * no `ALTER TABLE … DROP CONSTRAINT`, so the only way to change an FK
- * target is to recreate the table:
+ * `pages(id)` to `content_items(id)` by rebuilding each table, AND converts
+ * `page_tags` (if present) into `technology_signals` / `page_technologies`.
+ * SQLite has no `ALTER TABLE … DROP CONSTRAINT`, so the only way to change
+ * an FK target is to recreate the table:
  *
- * 1. Stage each table's rows into a constraint-free `<table>__retarget`
- *    copy (`CREATE TABLE … AS SELECT *`) and drop the original, freeing
- *    its index names.
- * 2. Recreate every table through {@link createAdjunctTables} — the same
- *    DDL fresh archives get, so migrated archives end up identical in
- *    shape and index naming. Rebuilding the DDL inline here instead
- *    would recreate the exact drift this function repairs.
- * 3. Copy the staged rows back using the recreated table's own column
- *    list (read via `pragma_table_info`). A column the canonical DDL has
- *    but the input archive lacks aborts the INSERT with a clear error —
- *    never a silent data drop.
+ * 1. Stage each {@link RETARGET_TABLES} table's rows into a constraint-free
+ *    `<table>__retarget` copy (`CREATE TABLE … AS SELECT *`) and drop the
+ *    original, freeing its index names. `page_tags`, if present, is read
+ *    into memory here too (converted via `convertLegacyPageTagsToInserts` —
+ *    the same helper `migrate-page-tags-to-page-technologies.ts` uses for
+ *    already-0.13+ archives) but NOT staged the same way: it has no
+ *    current-schema table to retarget onto, so there is nothing to copy
+ *    back — only something to drop, once its data lives in the tables
+ *    from step 2.
+ * 2. Recreate every {@link RETARGET_TABLES} table through
+ *    {@link createAdjunctTables} — the same DDL fresh archives get, so
+ *    migrated archives end up identical in shape and index naming.
+ *    Rebuilding the DDL inline here instead would recreate the exact
+ *    drift this function repairs. This same call also creates
+ *    `technology_signals` / `page_technologies` (idempotent
+ *    `hasTable`-guarded DDL — a no-op if a prior partial run already
+ *    created them).
+ * 3. Copy the staged {@link RETARGET_TABLES} rows back using the recreated
+ *    table's own column list (read via `pragma_table_info`). A column the
+ *    canonical DDL has but the input archive lacks aborts the INSERT with
+ *    a clear error — never a silent data drop. The converted `page_tags`
+ *    signals/technologies are inserted here too, then `page_tags` itself
+ *    is dropped (not recreated).
  *
  * A rename-based recipe (`ALTER TABLE x RENAME TO x__retarget`, skip
  * copy #1) is deliberately NOT used: SQLite keeps the renamed table's

package/lib/archive/retarget-legacy-fk-tables.js

@@ -1,4 +1,6 @@
+import { eachSplitted } from '../utils/array/each-splitted.js';
 import { createAdjunctTables } from './create-adjunct-tables.js';
+import { convertLegacyPageTagsToInserts } from './meta/technologies/convert-legacy-page-tags-to-inserts.js';
 /**
  * The adjunct tables whose FK declarations may still point at the legacy
  * `pages(id)` on migrated archives. Only names are listed — the column
@@ -6,10 +8,15 @@ import { createAdjunctTables } from './create-adjunct-tables.js';
  * {@link createAdjunctTables}, so a future column addition there cannot
  * silently drift from a hardcoded list (a missing column in the staged
  * copy fails the copy-back INSERT loudly instead of dropping data).
+ *
+ * `page_tags` is deliberately NOT here — it has no current-schema
+ * equivalent to retarget onto (removed in favor of `technology_signals` /
+ * `page_technologies`). {@link retargetLegacyFkTables} handles it as a
+ * special case: convert its rows, then drop it outright rather than
+ * recreating it. See that function's JSDoc.
  */
 const RETARGET_TABLES = [
     'page_html_ref',
-    'page_tags',
     'page_jsonld',
     'page_errors',
     'analysis_violations',
@@ -32,21 +39,34 @@ const NULLABLE_ON_RETARGET = {
 };
 /**
  * Rewrites the FK declarations of the adjunct tables from the legacy
- * `pages(id)` to `content_items(id)` by rebuilding each table. SQLite has
- * no `ALTER TABLE … DROP CONSTRAINT`, so the only way to change an FK
- * target is to recreate the table:
+ * `pages(id)` to `content_items(id)` by rebuilding each table, AND converts
+ * `page_tags` (if present) into `technology_signals` / `page_technologies`.
+ * SQLite has no `ALTER TABLE … DROP CONSTRAINT`, so the only way to change
+ * an FK target is to recreate the table:
  *
- * 1. Stage each table's rows into a constraint-free `<table>__retarget`
- *    copy (`CREATE TABLE … AS SELECT *`) and drop the original, freeing
- *    its index names.
- * 2. Recreate every table through {@link createAdjunctTables} — the same
- *    DDL fresh archives get, so migrated archives end up identical in
- *    shape and index naming. Rebuilding the DDL inline here instead
- *    would recreate the exact drift this function repairs.
- * 3. Copy the staged rows back using the recreated table's own column
- *    list (read via `pragma_table_info`). A column the canonical DDL has
- *    but the input archive lacks aborts the INSERT with a clear error —
- *    never a silent data drop.
+ * 1. Stage each {@link RETARGET_TABLES} table's rows into a constraint-free
+ *    `<table>__retarget` copy (`CREATE TABLE … AS SELECT *`) and drop the
+ *    original, freeing its index names. `page_tags`, if present, is read
+ *    into memory here too (converted via `convertLegacyPageTagsToInserts` —
+ *    the same helper `migrate-page-tags-to-page-technologies.ts` uses for
+ *    already-0.13+ archives) but NOT staged the same way: it has no
+ *    current-schema table to retarget onto, so there is nothing to copy
+ *    back — only something to drop, once its data lives in the tables
+ *    from step 2.
+ * 2. Recreate every {@link RETARGET_TABLES} table through
+ *    {@link createAdjunctTables} — the same DDL fresh archives get, so
+ *    migrated archives end up identical in shape and index naming.
+ *    Rebuilding the DDL inline here instead would recreate the exact
+ *    drift this function repairs. This same call also creates
+ *    `technology_signals` / `page_technologies` (idempotent
+ *    `hasTable`-guarded DDL — a no-op if a prior partial run already
+ *    created them).
+ * 3. Copy the staged {@link RETARGET_TABLES} rows back using the recreated
+ *    table's own column list (read via `pragma_table_info`). A column the
+ *    canonical DDL has but the input archive lacks aborts the INSERT with
+ *    a clear error — never a silent data drop. The converted `page_tags`
+ *    signals/technologies are inserted here too, then `page_tags` itself
+ *    is dropped (not recreated).
  *
  * A rename-based recipe (`ALTER TABLE x RENAME TO x__retarget`, skip
  * copy #1) is deliberately NOT used: SQLite keeps the renamed table's
@@ -85,6 +105,18 @@ export async function retargetLegacyFkTables(trx) {
         await trx.raw(`DROP TABLE "${table}"`);
         staged.push(table);
     }
+    // `page_tags` has no current-schema table to retarget onto (removed —
+    // see the module JSDoc), so its rows are converted to
+    // `technology_signals` / `page_technologies` shape HERE, while
+    // `page_tags` still exists, then only dropped (not staged/recreated)
+    // after `createAdjunctTables` below provisions the tables that will
+    // receive them.
+    const hasLegacyPageTags = await trx.schema.hasTable('page_tags');
+    const legacyTagRows = hasLegacyPageTags
+        ? await trx
+            .select('pageId', 'provider', 'version', 'confidence', 'categories')
+            .from('page_tags')
+        : [];
     await createAdjunctTables(trx);
     for (const table of staged) {
         const columns = await trx
@@ -104,4 +136,18 @@ export async function retargetLegacyFkTables(trx) {
         await trx.raw(`INSERT INTO "${table}" (${insertColumnList}) SELECT ${selectColumnList} FROM "${table}__retarget"`);
         await trx.raw(`DROP TABLE "${table}__retarget"`);
     }
+    if (hasLegacyPageTags) {
+        const { signalInserts, technologyInserts } = convertLegacyPageTagsToInserts(legacyTagRows);
+        if (signalInserts.length > 0) {
+            await eachSplitted(signalInserts, 100, async (chunk) => {
+                await trx('technology_signals').insert(chunk);
+            });
+        }
+        if (technologyInserts.length > 0) {
+            await eachSplitted(technologyInserts, 100, async (chunk) => {
+                await trx('page_technologies').insert(chunk);
+            });
+        }
+        await trx.raw('DROP TABLE "page_tags"');
+    }
 }

package/lib/archive/types.d.ts

@@ -1,4 +1,5 @@
 import type { DomPathCandidate } from './populate-entity-tables/types.js';
+import type { MainContentCustomElementCandidate } from '../crawler/types.js';
 import type { PageData } from '../utils/types/types.js';
 import type { ParseURLOptions } from '@d-zero/shared/parse-url';
 /**
@@ -13,6 +14,13 @@ import type { ParseURLOptions } from '@d-zero/shared/parse-url';
 export type PageDataWithDomPaths = PageData & {
     /** In-browser dom-path capture for the rendered document's images. */
     imageDomPaths?: readonly DomPathCandidate[];
+    /**
+     * In-browser Web Component (custom element) capture for the rendered
+     * document's main-content region (`crawler/capture-custom-elements.ts`).
+     * `undefined` means capture was not attempted or failed — a distinct
+     * state from "capture succeeded, zero elements found" (empty array).
+     */
+    mainContentCustomElements?: readonly MainContentCustomElementCandidate[];
 };
 /**
  * Event map for database-related events emitted by the Database and ArchiveAccessor classes.
@@ -388,6 +396,8 @@ export interface DB_Page {
     main_content_audio_count: number | null;
     /** Number of canvases within the main region, or null. */
     main_content_canvas_count: number | null;
+    /** Number of Web Components (custom elements) within the main region, or null. */
+    main_content_custom_element_count: number | null;
     /** `document.body.scrollHeight` at the desktop-compact preset, or null. */
     scroll_height_desktop: number | null;
     /** `document.body.scrollHeight` at the mobile-small preset, or null. */
@@ -637,4 +647,12 @@ export interface DatabaseOption {
      * tmpDir, where any write would race the live crawler.
      */
     readOnly?: boolean;
+    /**
+     * Called instead of `console.error` for self-healing schema migration
+     * notices (issue #294) — see
+     * {@link import('./db-ops/lifecycle/init.js').init}'s `onLog` param for
+     * why a bare `console.error` at this point is unsafe. Ignored when
+     * `readOnly` is `true` (migrations never run there).
+     */
+    onLog?: (message: string) => void;
 }

package/lib/crawler/assert-puppeteer-shared-with-beholder.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Verifies that crawler's own `puppeteer` install and the `puppeteer` used
+ * internally by `@d-zero/beholder` resolve to the same directory on disk.
+ *
+ * `Crawler#scrapePage` launches the browser through crawler's own
+ * `puppeteer` import and hands the resulting `Page` across the module
+ * boundary into `Scraper.scrapeStart()` (`@d-zero/beholder`). If crawler's
+ * pinned `puppeteer` version drifts from whatever version `@d-zero/beholder`
+ * depends on internally, yarn installs two separate `puppeteer` copies and
+ * the `Page` instances are structurally similar but not the same class —
+ * this surfaces as a `TS2345` deep inside application code with no
+ * indication that a version mismatch is the actual cause. Comparing the
+ * resolved directories catches the drift directly, at the boundary where it
+ * actually matters.
+ * @throws {Error} When crawler's and beholder's `puppeteer` resolve to
+ *   different directories, naming both.
+ * @example
+ * ```ts
+ * import { assertPuppeteerSharedWithBeholder } from '@nitpicker/crawler';
+ *
+ * assertPuppeteerSharedWithBeholder();
+ * ```
+ */
+export declare function assertPuppeteerSharedWithBeholder(): void;

package/lib/crawler/assert-puppeteer-shared-with-beholder.js

@@ -0,0 +1,36 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { findPackageDir } from './find-package-dir.js';
+/**
+ * Verifies that crawler's own `puppeteer` install and the `puppeteer` used
+ * internally by `@d-zero/beholder` resolve to the same directory on disk.
+ *
+ * `Crawler#scrapePage` launches the browser through crawler's own
+ * `puppeteer` import and hands the resulting `Page` across the module
+ * boundary into `Scraper.scrapeStart()` (`@d-zero/beholder`). If crawler's
+ * pinned `puppeteer` version drifts from whatever version `@d-zero/beholder`
+ * depends on internally, yarn installs two separate `puppeteer` copies and
+ * the `Page` instances are structurally similar but not the same class —
+ * this surfaces as a `TS2345` deep inside application code with no
+ * indication that a version mismatch is the actual cause. Comparing the
+ * resolved directories catches the drift directly, at the boundary where it
+ * actually matters.
+ * @throws {Error} When crawler's and beholder's `puppeteer` resolve to
+ *   different directories, naming both.
+ * @example
+ * ```ts
+ * import { assertPuppeteerSharedWithBeholder } from '@nitpicker/crawler';
+ *
+ * assertPuppeteerSharedWithBeholder();
+ * ```
+ */
+export function assertPuppeteerSharedWithBeholder() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const crawlerPuppeteerDir = findPackageDir(here, 'puppeteer');
+    const beholderDir = findPackageDir(here, '@d-zero/beholder');
+    const beholderPuppeteerDir = findPackageDir(beholderDir, 'puppeteer');
+    if (crawlerPuppeteerDir !== beholderPuppeteerDir) {
+        throw new Error(`crawler's puppeteer (${crawlerPuppeteerDir}) and @d-zero/beholder's puppeteer (${beholderPuppeteerDir}) resolve to different installs. ` +
+            `Pin crawler's own "puppeteer" version in package.json to match the version @d-zero/beholder depends on internally.`);
+    }
+}

package/lib/crawler/capture-custom-elements.d.ts

@@ -0,0 +1,33 @@
+import type { MainContentCustomElementCandidate } from './types.js';
+import type { Page as PuppeteerPage } from 'puppeteer';
+/**
+ * Captures every Web Component (custom element) inside a page's
+ * main-content region, in document order.
+ *
+ * `@d-zero/beholder`'s `MainContentsData` has no `customElements` category
+ * (confirmed by reading its `types.ts` / `get-main-contents.ts`), so the
+ * crawler runs this one extra `page.evaluate` after `scrapeStart` returns,
+ * while the page is still alive — the exact same pattern as
+ * {@link ./capture-image-dom-paths.ts}, which fills a different gap in
+ * beholder's image metadata for the same reason (beholder does not own
+ * this detection and does not need to; nitpicker already owns the live
+ * `page` object at this point in the scrape).
+ *
+ * Returns `undefined` on any evaluation failure (page context died,
+ * navigation raced the call) — custom-element capture is best-effort
+ * enrichment and a capture failure must not fail the scrape. Callers
+ * treat `undefined` as "unknown" (a distinct state from "zero elements
+ * found"), matching
+ * {@link ../archive/meta/compute-main-contents-denormalized.ts}'s
+ * three-value handling of `main_content_custom_element_count`.
+ * @param page - The live puppeteer page, after the scrape completed and
+ *   before the browser closes.
+ * @param mainContentSelector - Optional selector override, forwarded
+ *   verbatim to {@link ./collect-custom-elements.ts}.
+ * @returns Candidates in document order, or `undefined` when the page
+ *   could not be evaluated.
+ * @example
+ * const result = await scraper.scrapeStart(page, url, options);
+ * const customElements = await captureCustomElements(page, options.mainContentSelector);
+ */
+export declare function captureCustomElements(page: PuppeteerPage, mainContentSelector?: string | null): Promise<MainContentCustomElementCandidate[] | undefined>;

package/lib/crawler/capture-custom-elements.js

@@ -0,0 +1,39 @@
+import { collectCustomElements } from './collect-custom-elements.js';
+/**
+ * Captures every Web Component (custom element) inside a page's
+ * main-content region, in document order.
+ *
+ * `@d-zero/beholder`'s `MainContentsData` has no `customElements` category
+ * (confirmed by reading its `types.ts` / `get-main-contents.ts`), so the
+ * crawler runs this one extra `page.evaluate` after `scrapeStart` returns,
+ * while the page is still alive — the exact same pattern as
+ * {@link ./capture-image-dom-paths.ts}, which fills a different gap in
+ * beholder's image metadata for the same reason (beholder does not own
+ * this detection and does not need to; nitpicker already owns the live
+ * `page` object at this point in the scrape).
+ *
+ * Returns `undefined` on any evaluation failure (page context died,
+ * navigation raced the call) — custom-element capture is best-effort
+ * enrichment and a capture failure must not fail the scrape. Callers
+ * treat `undefined` as "unknown" (a distinct state from "zero elements
+ * found"), matching
+ * {@link ../archive/meta/compute-main-contents-denormalized.ts}'s
+ * three-value handling of `main_content_custom_element_count`.
+ * @param page - The live puppeteer page, after the scrape completed and
+ *   before the browser closes.
+ * @param mainContentSelector - Optional selector override, forwarded
+ *   verbatim to {@link ./collect-custom-elements.ts}.
+ * @returns Candidates in document order, or `undefined` when the page
+ *   could not be evaluated.
+ * @example
+ * const result = await scraper.scrapeStart(page, url, options);
+ * const customElements = await captureCustomElements(page, options.mainContentSelector);
+ */
+export async function captureCustomElements(page, mainContentSelector) {
+    try {
+        return await page.evaluate(collectCustomElements, mainContentSelector ?? null);
+    }
+    catch {
+        return undefined;
+    }
+}

package/lib/crawler/close-browser-safely.d.ts

@@ -44,9 +44,9 @@ export interface CloseBrowserSafelyDeps {
  * expiry guarantees the worker always completes and no orphan subprocesses are
  * left behind.
  *
- * The losing timer is cleared explicitly in `.finally()` so it never keeps the
- * event loop alive after the race settles (a plain `delay()` in `Promise.race`
- * would leak the timer until it fires).
+ * Timer cleanup is delegated to `raceWithTimeout` (`@d-zero/shared`), which
+ * clears the losing timer internally so it never keeps the event loop alive
+ * after the race settles.
  *
  * The tree-kill happens via {@link killProcessTree}, which enumerates
  * descendants through `ps` (POSIX) or delegates to `taskkill /T /F` (Windows).

package/lib/crawler/close-browser-safely.js

@@ -1,3 +1,4 @@
+import { raceWithTimeout } from '@d-zero/shared/race-with-timeout';
 import { crawlerLog } from '../debug.js';
 import { killProcessTree } from './kill-process-tree.js';
 /**
@@ -18,9 +19,9 @@ const DEFAULT_CLOSE_TIMEOUT_MS = 30 * 1000;
  * expiry guarantees the worker always completes and no orphan subprocesses are
  * left behind.
  *
- * The losing timer is cleared explicitly in `.finally()` so it never keeps the
- * event loop alive after the race settles (a plain `delay()` in `Promise.race`
- * would leak the timer until it fires).
+ * Timer cleanup is delegated to `raceWithTimeout` (`@d-zero/shared`), which
+ * clears the losing timer internally so it never keeps the event loop alive
+ * after the race settles.
  *
  * The tree-kill happens via {@link killProcessTree}, which enumerates
  * descendants through `ps` (POSIX) or delegates to `taskkill /T /F` (Windows).
@@ -40,20 +41,10 @@ export async function closeBrowserSafely(browser, timeoutMs = DEFAULT_CLOSE_TIME
     // releases its internal reference and process() returns null, so we would
     // have no handle to tree-kill on timeout.
     const childProcess = browser.process();
-    let timeoutHandle;
-    const timedOut = await Promise.race([
-        browser
-            .close()
-            .then(() => false)
-            .catch(() => false),
-        new Promise((resolve) => {
-            timeoutHandle = setTimeout(() => resolve(true), timeoutMs);
-        }),
-    ]).finally(() => {
-        if (timeoutHandle) {
-            clearTimeout(timeoutHandle);
-        }
-    });
+    const { timeout: timedOut } = await raceWithTimeout(() => browser
+        .close()
+        .then(() => { })
+        .catch(() => { }), timeoutMs);
     if (timedOut && childProcess && !childProcess.killed) {
         // Mark the Node ChildProcess as killed so Node's reaping logic treats
         // it correctly; then walk the OS process tree.

package/lib/crawler/collect-custom-elements.d.ts

@@ -0,0 +1,33 @@
+import type { MainContentCustomElementCandidate } from './types.js';
+/**
+ * Collects every Web Component (custom element) inside a page's main-content
+ * region — its `nodeName`, `id`, and `classList` — in document order.
+ *
+ * **Self-contained by contract.** Passed verbatim to Puppeteer's
+ * `page.evaluate`, which serialises the function source and executes it
+ * inside the browser: it must not reference imports, module-scope bindings,
+ * or any closure state. This is why the main-content selector priority
+ * lists below are inlined rather than imported from
+ * `@d-zero/beholder`'s `main-content-selectors.ts` — the same
+ * closure-free constraint that forces beholder's own
+ * `extractMainContentsFromDocument` to inline them. The two copies (this
+ * file's and beholder's) are kept in sync by
+ * {@link ./collect-custom-elements.spec.ts}, which asserts the resolved
+ * main element matches beholder's own resolution for the same fixture.
+ *
+ * A "custom element" here means: the tag name (case-insensitively)
+ * contains a hyphen, and is not one of the eight hyphenated SVG/MathML
+ * element names the Custom Elements spec reserves as non-registrable
+ * (`annotation-xml`, `color-profile`, `font-face`, `font-face-src`,
+ * `font-face-uri`, `font-face-format`, `font-face-name`, `missing-glyph`).
+ * @param mainContentSelector - Optional selector prepended to the default
+ *   list, mirroring beholder's `getMainContents` option of the same name.
+ * @param doc - The document to walk. Defaults to the global `document`,
+ *   which is how the in-browser `page.evaluate(collectCustomElements, sel)`
+ *   call resolves it; Node callers (specs) pass a jsdom document.
+ * @returns Candidates in document order, or an empty array when no
+ *   main-content region can be resolved.
+ * @example
+ * const candidates = await page.evaluate(collectCustomElements, mainContentSelector);
+ */
+export declare function collectCustomElements(mainContentSelector?: string | null, doc?: Document): MainContentCustomElementCandidate[];

package/lib/crawler/collect-custom-elements.js

@@ -0,0 +1,110 @@
+/**
+ * Collects every Web Component (custom element) inside a page's main-content
+ * region — its `nodeName`, `id`, and `classList` — in document order.
+ *
+ * **Self-contained by contract.** Passed verbatim to Puppeteer's
+ * `page.evaluate`, which serialises the function source and executes it
+ * inside the browser: it must not reference imports, module-scope bindings,
+ * or any closure state. This is why the main-content selector priority
+ * lists below are inlined rather than imported from
+ * `@d-zero/beholder`'s `main-content-selectors.ts` — the same
+ * closure-free constraint that forces beholder's own
+ * `extractMainContentsFromDocument` to inline them. The two copies (this
+ * file's and beholder's) are kept in sync by
+ * {@link ./collect-custom-elements.spec.ts}, which asserts the resolved
+ * main element matches beholder's own resolution for the same fixture.
+ *
+ * A "custom element" here means: the tag name (case-insensitively)
+ * contains a hyphen, and is not one of the eight hyphenated SVG/MathML
+ * element names the Custom Elements spec reserves as non-registrable
+ * (`annotation-xml`, `color-profile`, `font-face`, `font-face-src`,
+ * `font-face-uri`, `font-face-format`, `font-face-name`, `missing-glyph`).
+ * @param mainContentSelector - Optional selector prepended to the default
+ *   list, mirroring beholder's `getMainContents` option of the same name.
+ * @param doc - The document to walk. Defaults to the global `document`,
+ *   which is how the in-browser `page.evaluate(collectCustomElements, sel)`
+ *   call resolves it; Node callers (specs) pass a jsdom document.
+ * @returns Candidates in document order, or an empty array when no
+ *   main-content region can be resolved.
+ * @example
+ * const candidates = await page.evaluate(collectCustomElements, mainContentSelector);
+ */
+export function collectCustomElements(mainContentSelector = null, doc = document) {
+    // Kept in sync with beholder's MAIN_CONTENT_SELECTORS
+    // (main-content-selectors.ts) — see the module JSDoc. Inlined rather
+    // than imported because this function must stay closure-free.
+    const selectors = [
+        'main',
+        '[role="main"]',
+        '#main',
+        '.main',
+        '#content',
+        '.content',
+        '#contents',
+        '.contents',
+        '#main-content',
+        '.main-content',
+        '#main_content',
+        '.main_content',
+        '#mainContent',
+        '.mainContent',
+    ];
+    if (mainContentSelector) {
+        selectors.unshift(mainContentSelector);
+    }
+    let $main = null;
+    for (const sel of selectors) {
+        try {
+            $main = doc.querySelector(sel);
+        }
+        catch {
+            continue;
+        }
+        if ($main) {
+            break;
+        }
+    }
+    if (!$main) {
+        // Kept in sync with beholder's MAIN_CONTENT_FALLBACK_SELECTORS.
+        const fallbackSelectors = [
+            '[id*="main" i]',
+            '[class*="main" i]',
+            '[id*="content" i]',
+            '[class*="content" i]',
+        ];
+        for (const sel of fallbackSelectors) {
+            const candidate = doc.querySelector(sel);
+            if (candidate && candidate !== doc.body && candidate !== doc.documentElement) {
+                $main = candidate;
+                break;
+            }
+        }
+    }
+    if (!$main)
+        return [];
+    // The eight hyphenated element names the Custom Elements spec reserves
+    // as non-registrable (SVG/MathML legacy names) — the sole exception to
+    // "a hyphenated tag name is a custom element".
+    const reservedHyphenatedNames = new Set([
+        'annotation-xml',
+        'color-profile',
+        'font-face',
+        'font-face-src',
+        'font-face-uri',
+        'font-face-format',
+        'font-face-name',
+        'missing-glyph',
+    ]);
+    const candidates = [];
+    for (const el of $main.querySelectorAll('*')) {
+        const tagName = el.nodeName.toLowerCase();
+        if (!tagName.includes('-') || reservedHyphenatedNames.has(tagName))
+            continue;
+        candidates.push({
+            nodeName: el.nodeName,
+            elementId: el.id || null,
+            classList: [...el.classList],
+        });
+    }
+    return candidates;
+}