@d-zero/beholder 2.1.6 → 3.0.0

package/dist/dom-evaluation.js

@@ -15,6 +15,8 @@
  */
 import { raceWithTimeout } from '@d-zero/shared/race-with-timeout';
 import { domDetailsLog, domLog } from './debug.js';
+import { classify, emptyMeta } from './meta/classify.js';
+import { detectTags } from './meta/tag-detection.js';
 import { parseUrl } from './parse-url.js';
 const pid = `${process.pid}`;
 const log = domLog.extend(pid);
@@ -23,8 +25,12 @@ const dLog = domDetailsLog.extend(pid);
  * Default timeout (ms) applied to DOM evaluation operations when the caller does not
  * specify one. Bounds how long a single `page.evaluate` / property read may hang on a
  * page whose main thread is unresponsive.
+ *
+ * WHY 180s: Aligned with the upstream `Scraper#fetchData` retryable timeout (3 min) so
+ * a single phase does not exceed the retry budget while still tolerating large pages
+ * (e.g., 1000+ anchors) and slow main threads.
  */
-export const DEFAULT_DOM_EVALUATION_TIMEOUT = 30_000;
+export const DEFAULT_DOM_EVALUATION_TIMEOUT = 180_000;
 /**
  * Retrieves a DOM property value from a Puppeteer element handle with a timeout.
  *
@@ -108,6 +114,114 @@ export async function getImageList(page, viewportWidth, timeout = DEFAULT_DOM_EV
     dLog('Images are: %O', imageList.map((i) => i.src));
     return imageList;
 }
+/**
+ * One-shot warning latch: only the first time `_client()` is missing in a
+ * process do we log the degradation. Subsequent calls stay silent to avoid
+ * spamming logs while every page in a crawl re-enters the fallback path.
+ */
+let warnedAboutMissingClient = false;
+/**
+ * Returns puppeteer's internal CDP session for the page, or `null` if it is
+ * unreachable (e.g., test mocks, puppeteer wrappers that hide the internal API,
+ * or a future puppeteer release that renames `_client`).
+ *
+ * WHY a warning log: callers transparently fall back to textContent-only mode
+ * when this returns `null`, which masks a silent perf regression if a
+ * puppeteer update removes `_client`. The warning makes the degraded state
+ * observable in production logs so a maintainer can patch the access path.
+ *
+ * Callers fall back to a textContent-only path when this returns `null`.
+ * @param page - The Puppeteer page.
+ */
+function getInternalCDPClient(page) {
+    try {
+        const client = page._client?.();
+        if (!client) {
+            if (!warnedAboutMissingClient) {
+                warnedAboutMissingClient = true;
+                log('WARN: puppeteer Page._client() returned no session — getAnchorList ' +
+                    'falls back to textContent-only mode. Verify the installed puppeteer ' +
+                    'version still exposes the internal _client() accessor.');
+            }
+            return null;
+        }
+        return client;
+    }
+    catch (error) {
+        if (!warnedAboutMissingClient) {
+            warnedAboutMissingClient = true;
+            log('WARN: puppeteer Page._client() threw — getAnchorList falls back to ' +
+                'textContent-only mode. Error: %O', error);
+        }
+        return null;
+    }
+}
+/**
+ * Fetches the full accessibility tree once and builds a `backendDOMNodeId → accessibleName`
+ * map covering every AX node that exposes a backend DOM id.
+ *
+ * WHY include every non-ignored node (not just `role === 'link'`): the original
+ * `page.accessibility.snapshot({ root })` returned whatever AX node represented
+ * the anchor — including anchors whose computed role was overridden via ARIA
+ * (e.g., `<a role="button">`). Mapping every non-ignored node preserves that.
+ *
+ * WHY skip `ignored === true`: puppeteer's high-level snapshot uses
+ * `interestingOnly: true` by default and returns `null` for ignored nodes
+ * (aria-hidden, display:none, visibility:hidden). The old code then fell back
+ * to `textContent.trim()`. Including ignored nodes here would short-circuit
+ * that fallback with the AX tree's empty name and silently drop link text.
+ *
+ * On timeout or CDP failure, an empty map is returned so callers transparently
+ * fall back to `textContent.trim()` for every anchor.
+ * @param client - The CDP session attached to the page.
+ * @param timeout - Maximum time to wait for the AX tree fetch.
+ */
+async function buildAccessibleNameMap(client, timeout) {
+    const { result, timeout: timedOut } = await raceWithTimeout(() => client
+        .send('Accessibility.getFullAXTree')
+        .then((res) => res)
+        .catch((error) => {
+        log('Accessibility.getFullAXTree failed: %O', error);
+        return null;
+    }), timeout);
+    const map = new Map();
+    if (timedOut) {
+        log('Accessibility.getFullAXTree timed out after %dms', timeout);
+        return map;
+    }
+    if (!result?.nodes) {
+        return map;
+    }
+    for (const node of result.nodes) {
+        if (node.backendDOMNodeId == null || node.ignored === true) {
+            continue;
+        }
+        const name = typeof node.name?.value === 'string' ? node.name.value : '';
+        map.set(node.backendDOMNodeId, name);
+    }
+    return map;
+}
+/**
+ * Resolves a CDP backend node id for a given element handle.
+ *
+ * Wrapped in {@link raceWithTimeout} so a single hung `DOM.describeNode` cannot
+ * stall the outer `Promise.all` over every anchor on the page.
+ * @param client - The CDP session attached to the page (must be the same session
+ *                 that owns the handle's `objectId`).
+ * @param objectId - The remote object id of the element handle.
+ * @param timeout - Maximum time to wait for the describeNode call.
+ * @returns The backend node id, or `null` if unavailable / timed out / failed.
+ */
+async function resolveBackendNodeId(client, objectId, timeout) {
+    const { result, timeout: timedOut } = await raceWithTimeout(() => client
+        .send('DOM.describeNode', { objectId })
+        .then((res) => res)
+        .catch(() => null), timeout);
+    if (timedOut || !result) {
+        return null;
+    }
+    return result.node?.backendNodeId ?? null;
+}
 /**
  * Extracts all anchor (`<a>` and `<area>`) elements with `href` attributes from the page.
  *
@@ -115,104 +229,348 @@ export async function getImageList(page, viewportWidth, timeout = DEFAULT_DOM_EV
  * the accessible name (from the accessibility tree, falling back to `textContent`),
  * and filters out non-HTTP links.
  *
- * WHY this keeps per-element CDP calls (unlike {@link getMeta} / {@link getImageList}):
- * the accessible name comes from Chrome's computed accessibility tree
- * (`page.accessibility.snapshot`), which is a CDP-only feature unavailable to in-page
- * DOM APIs. Each {@link getProp} read is still bounded by `timeout`.
+ * WHY Strategy F (single AX-tree fetch + parallel `DOM.describeNode`): the old
+ * implementation called `page.accessibility.snapshot({ root })` per anchor, which
+ * triggers a CDP round-trip *and* a Chrome-side AX subtree computation (~42ms
+ * each). On a page with 1181 anchors that compounded to ~53s. By fetching the
+ * full AX tree once and using `DOM.describeNode` in parallel to map element
+ * handles back to AX nodes by `backendDOMNodeId`, the same data is collected in
+ * ~150ms on the same page — a ~350× speed-up while preserving the original
+ * accessible-name semantics. See issue #876 for measurements.
+ *
+ * WHY the whole operation is wrapped in `raceWithTimeout`: even with bounded
+ * per-CDP-call timeouts, a degenerate page (blocked main thread, thousands of
+ * anchors, runaway describeNode latency) could chain enough sub-timeouts to
+ * exceed the caller's `timeout` budget. The outer race guarantees the function
+ * returns within `timeout`, surfacing whatever anchors were collected so far so
+ * the upstream scrape phase can continue rather than tripping a retryable retry.
  * @param page - The Puppeteer page to extract anchors from.
  * @param options - Optional URL parsing options (e.g., `disableQueries`).
- * @param timeout - Timeout in ms per property read. Defaults to {@link DEFAULT_DOM_EVALUATION_TIMEOUT}.
+ * @param timeout - Total time budget in ms for the whole extraction. Defaults to {@link DEFAULT_DOM_EVALUATION_TIMEOUT}.
  * @returns An array of {@link AnchorData} objects for all HTTP(S) links found on the page.
  */
 export async function getAnchorList(page, options, timeout = DEFAULT_DOM_EVALUATION_TIMEOUT) {
     log('Getting anchors');
     const $anchors = await page.$$('a[href], area[href]');
-    const anchorList = [];
-    for (const $anchor of $anchors) {
-        const $href = await getProp({ $el: $anchor, propName: 'href', fallback: '' }, timeout);
-        const hrefVal = $href.toString();
-        const href = parseUrl(hrefVal, options);
+    if ($anchors.length === 0) {
+        log('Got 0 anchors');
+        return [];
+    }
+    const collected = [];
+    let axHits = 0;
+    let textFallbacks = 0;
+    // Set after the overall race trips so in-flight `resolveAnchor` calls can
+    // short-circuit instead of continuing to consume CDP capacity and pushing
+    // late entries into the already-returned `collected` array.
+    let cancelled = false;
+    const work = async () => {
+        const client = getInternalCDPClient(page);
+        if (cancelled)
+            return;
+        const nameByBackendId = client
+            ? await buildAccessibleNameMap(client, timeout)
+            : new Map();
+        if (cancelled)
+            return;
+        await Promise.all($anchors.map(async ($anchor) => {
+            if (cancelled)
+                return;
+            const resolved = await resolveAnchor($anchor, client, nameByBackendId, options, timeout);
+            if (cancelled || !resolved) {
+                return;
+            }
+            if (resolved.source === 'ax') {
+                axHits++;
+            }
+            else {
+                textFallbacks++;
+            }
+            collected.push(resolved.anchor);
+        }));
+    };
+    const { timeout: timedOut } = await raceWithTimeout(work, timeout);
+    cancelled = true;
+    if (timedOut) {
+        log('getAnchorList timed out after %dms; returning %d anchors collected so far', timeout, collected.length);
+    }
+    // Snapshot so post-return mutations from any in-flight Promise.all callback
+    // (already gated by `cancelled`, but not synchronously cancellable) cannot
+    // alter the array the caller now holds.
+    const result = [...collected];
+    log('Got %d anchors (%d via AX, %d via textContent)', result.length, axHits, textFallbacks);
+    dLog('Anchors are: %O', result.map((a) => a.href.href));
+    return result;
+}
+/**
+ * Resolves a single anchor handle into an {@link AnchorData} entry, or `null`
+ * if the anchor's href is not an HTTP(S) URL.
+ *
+ * Fires `getProp(href)` and `DOM.describeNode` in parallel, then looks up the
+ * accessible name from the pre-built AX map. If the anchor is not represented
+ * in the AX map (or CDP is unavailable), falls back to a lazy `textContent`
+ * fetch — only paying the extra CDP round-trip when actually needed.
+ * @param $anchor - The Puppeteer element handle for an anchor element.
+ * @param client - The shared CDP session, or `null` if unavailable.
+ * @param nameByBackendId - Map from `backendDOMNodeId` to accessible name.
+ * @param options - URL parsing options.
+ * @param timeout - Per-CDP-call timeout in ms.
+ * @returns The resolved anchor along with the name source, or `null` when the
+ *          anchor's href is not crawlable.
+ */
+async function resolveAnchor($anchor, client, nameByBackendId, options, timeout) {
+    try {
+        const objectId = $anchor.remoteObject().objectId;
+        const [hrefVal, backendNodeId] = await Promise.all([
+            getProp({ $el: $anchor, propName: 'href', fallback: '' }, timeout),
+            client && objectId != null
+                ? resolveBackendNodeId(client, objectId, timeout)
+                : Promise.resolve(null),
+        ]);
+        const href = parseUrl(hrefVal.toString(), options);
         if (!href || !href.isHTTP) {
-            continue;
+            return null;
+        }
+        const axName = backendNodeId == null ? undefined : nameByBackendId.get(backendNodeId);
+        if (axName !== undefined) {
+            return { anchor: { href, textContent: axName }, source: 'ax' };
         }
-        const axNode = await page.accessibility.snapshot({ root: $anchor });
         const textContent = await getProp({ $el: $anchor, propName: 'textContent', fallback: '' }, timeout);
-        const accessibleName = axNode ? axNode.name || '' : textContent.trim();
-        const link = {
-            href,
-            textContent: accessibleName,
-        };
-        anchorList.push(link);
-    }
-    log('Got %d anchors', anchorList.length);
-    dLog('Anchors are: %O', anchorList.map((a) => a.href.href));
-    return anchorList;
+        return { anchor: { href, textContent: textContent.trim() }, source: 'text' };
+    }
+    catch (error) {
+        // `remoteObject()` (and other synchronous handle accesses) can throw when
+        // the handle is disposed (page navigated mid-extraction). Drop just this
+        // anchor rather than poisoning the Promise.all over every other anchor.
+        dLog('resolveAnchor failed for an anchor: %O', error);
+        return null;
+    }
 }
+const WINDOW_GLOBALS_TO_CHECK = [
+    'dataLayer',
+    'gtag',
+    'ga',
+    '_gaq',
+    'fbq',
+    '_fbq',
+    'clarity',
+    '_hjSettings',
+    '_hjid',
+    'twq',
+    'ttq',
+    '_linkedin_partner_id',
+    'pintrk',
+    'amplitude',
+    'mixpanel',
+    'analytics',
+    'heap',
+    'posthog',
+    'plausible',
+    'fathom',
+    '_paq',
+    's_account',
+    's',
+    'ym',
+    'UET',
+    'optimizely',
+    '_hsq',
+    'Sentry',
+    'Intercom',
+    'intercomSettings',
+    'drift',
+    'Tawk_API',
+    'zE',
+    'OneTrust',
+    'Cookiebot',
+    'Stripe',
+    'grecaptcha',
+];
 /**
- * Extracts comprehensive meta information from the page's `<head>`.
- *
- * Collects all metadata in a single `page.evaluate` call (14 CDP round-trips
- * collapsed into 1) wrapped in {@link raceWithTimeout}. On timeout (an unresponsive
- * page) a minimal `{ title: '' }` is returned rather than hanging.
- *
- * Collected metadata:
- * - `title` - The document title.
- * - `lang` - The `lang` attribute of the `<html>` element.
- * - `description` - The `<meta name="description">` content.
- * - `keywords` - The `<meta name="keywords">` content.
- * - `noindex` / `nofollow` / `noarchive` - Parsed from the `<meta name="robots">` directives.
- * - `canonical` - The `<link rel="canonical">` content.
- * - `alternate` - The `<link rel="alternate">` content.
- * - Open Graph tags: `og:type`, `og:title`, `og:site_name`, `og:description`, `og:url`, `og:image`.
- * - `twitter:card` - The Twitter Card type.
- * @param page - The Puppeteer page to extract meta information from.
- * @param timeout - Timeout in ms for the evaluation. Defaults to {@link DEFAULT_DOM_EVALUATION_TIMEOUT}.
- * @returns An object containing all extracted meta properties.
+ * Extracts comprehensive metadata from the page.
+ *
+ * Two passes happen in parallel:
+ * 1. Browser-side `collectHead()` serializes every `<meta>`, `<link>`,
+ *    relevant `<script>`, `<base>`, `<noscript>`/`<iframe>` and a curated
+ *    set of `window` globals into a `RawHeadEntry[]`. Node-side `classify()`
+ *    then maps those entries to typed `Meta` fields using the lookup tables
+ *    in `./meta/keys.ts`, with unknown entries preserved in `Meta.others`.
+ * 2. `detectTags()` runs `simple-wappalyzer` over the page HTML to produce
+ *    `Meta.tags` (technology detection + real-ID extraction).
+ *
+ * The whole call is wrapped in `raceWithTimeout`. On timeout an empty `Meta`
+ * (with `title: ''` and empty required arrays/objects) is returned.
+ * @param page
+ * @param context
+ * @param timeout
+ * @example
+ * ```ts
+ * const meta = await getMeta(page, {
+ *   url: 'https://example.com/',
+ *   html: await page.content(),
+ *   statusCode: response.status,
+ *   headers: response.headers,
+ * });
+ * console.log(meta.title);                         // <title> text
+ * console.log(meta.og?.image);                     // og:image[] array
+ * console.log(meta.robots?.noindex);               // parsed robots
+ * console.log(meta.tags.detected.Analytics);       // Wappalyzer hits
+ * console.log(meta.tags.entries.find(e => e.provider === 'Google Analytics')?.id);
+ * ```
  */
-export async function getMeta(page, timeout = DEFAULT_DOM_EVALUATION_TIMEOUT) {
+export async function getMeta(page, context, timeout = DEFAULT_DOM_EVALUATION_TIMEOUT) {
     log('Getting Meta');
-    const { result, timeout: timedOut } = await raceWithTimeout(() => page
-        .evaluate(() => {
-        /* global document, HTMLMetaElement, HTMLLinkElement */
-        const content = (selector) => {
-            const el = document.querySelector(selector);
-            return el instanceof HTMLMetaElement ? el.content : '';
-        };
-        const linkHref = (selector) => {
-            const el = document.querySelector(selector);
-            return el instanceof HTMLLinkElement ? el.href : '';
-        };
-        return {
-            title: document.title,
-            lang: document.documentElement.lang,
-            description: content('meta[name="description"]'),
-            keywords: content('meta[name="keywords"]'),
-            robots: content('meta[name="robots"]'),
-            canonical: linkHref('link[rel="canonical"]'),
-            alternate: linkHref('link[rel="alternate"]'),
-            'og:type': content('meta[property="og:type"]'),
-            'og:title': content('meta[property="og:title"]'),
-            'og:site_name': content('meta[property="og:site_name"]'),
-            'og:description': content('meta[property="og:description"]'),
-            'og:url': content('meta[property="og:url"]'),
-            'og:image': content('meta[property="og:image"]'),
-            'twitter:card': content('meta[name="twitter:card"]'),
-        };
-    })
-        .catch(() => null), timeout);
+    const { result, timeout: timedOut } = await raceWithTimeout(() => runGetMeta(page, context), timeout);
     if (timedOut || result == null) {
         log('Meta extraction timed out or failed; returning fallback');
-        return { title: '' };
-    }
-    const { robots: robotsVal, ...rest } = result;
-    const robots = new Set(robotsVal.split(',').map((robot) => robot.trim().toLowerCase()));
-    const meta = {
-        ...rest,
-        noindex: robots.has('noindex'),
-        nofollow: robots.has('nofollow'),
-        noarchive: robots.has('noarchive'),
-    };
+        return emptyMeta();
+    }
     log('Got meta');
-    dLog('Meta data are: %O', meta);
-    return meta;
+    dLog('Meta data are: %O', result);
+    return result;
+}
+/**
+ *
+ * @param page
+ * @param context
+ */
+async function runGetMeta(page, context) {
+    try {
+        const rawPromise = collectHeadOnPage(page);
+        const htmlPromise = context.html === undefined
+            ? page.content().catch(() => '')
+            : Promise.resolve(context.html);
+        const [raw, html] = await Promise.all([rawPromise, htmlPromise]);
+        const tags = await detectTags({
+            url: context.url,
+            html,
+            ...(context.statusCode === undefined ? {} : { statusCode: context.statusCode }),
+            ...(context.headers === undefined ? {} : { headers: context.headers }),
+        });
+        return classify(raw, {
+            tags,
+            ...(context.includeRaw ? { includeRaw: true } : {}),
+        });
+    }
+    catch (error) {
+        log('runGetMeta failed: %O', error);
+        return null;
+    }
+}
+/**
+ *
+ * @param page
+ */
+async function collectHeadOnPage(page) {
+    const raw = await page
+        .evaluate((knownGlobals) => {
+        const entries = [];
+        const html = document.documentElement;
+        entries.push({
+            kind: 'html',
+            lang: html.lang || undefined,
+            dir: html.dir || undefined,
+            xmlns: html.getAttribute('xmlns') ?? undefined,
+            prefix: html.getAttribute('prefix') ?? undefined,
+            vocab: html.getAttribute('vocab') ?? undefined,
+            typeOf: html.getAttribute('typeof') ?? undefined,
+            itemscope: html.hasAttribute('itemscope') || undefined,
+            itemtype: html.getAttribute('itemtype') ?? undefined,
+            amp: html.hasAttribute('amp') || undefined,
+            lightning: html.hasAttribute('⚡') || undefined,
+        }, { kind: 'title', content: document.title });
+        for (const base of document.querySelectorAll('base')) {
+            if (!(base instanceof HTMLBaseElement))
+                continue;
+            entries.push({
+                kind: 'base',
+                href: base.getAttribute('href') ?? undefined,
+                target: base.getAttribute('target') ?? undefined,
+            });
+        }
+        for (const meta of document.querySelectorAll('meta')) {
+            if (!(meta instanceof HTMLMetaElement))
+                continue;
+            const name = meta.getAttribute('name');
+            const property = meta.getAttribute('property');
+            const httpEquiv = meta.getAttribute('http-equiv');
+            const itemprop = meta.getAttribute('itemprop');
+            const charset = meta.getAttribute('charset');
+            const content = meta.getAttribute('content');
+            const media = meta.getAttribute('media');
+            entries.push({
+                kind: 'meta',
+                name: name ? name.toLowerCase() : undefined,
+                property: property ? property.toLowerCase() : undefined,
+                httpEquiv: httpEquiv ? httpEquiv.toLowerCase() : undefined,
+                itemprop: itemprop ?? undefined,
+                charset: charset ?? undefined,
+                content: content ?? undefined,
+                media: media ?? undefined,
+            });
+        }
+        for (const link of document.querySelectorAll('link[href]')) {
+            if (!(link instanceof HTMLLinkElement))
+                continue;
+            const relRaw = link.getAttribute('rel') ?? '';
+            const rel = relRaw.toLowerCase().split(/\s+/u).filter(Boolean);
+            entries.push({
+                kind: 'link',
+                rel,
+                href: link.getAttribute('href') ?? '',
+                type: link.getAttribute('type') ?? undefined,
+                media: link.getAttribute('media') ?? undefined,
+                sizes: link.getAttribute('sizes') ?? undefined,
+                title: link.getAttribute('title') ?? undefined,
+                hreflang: link.getAttribute('hreflang') ?? undefined,
+                as: link.getAttribute('as') ?? undefined,
+                crossorigin: link.getAttribute('crossorigin') ?? undefined,
+                color: link.getAttribute('color') ?? undefined,
+                blocking: link.getAttribute('blocking') ?? undefined,
+                imagesrcset: link.getAttribute('imagesrcset') ?? undefined,
+            });
+        }
+        const STRUCTURED_TYPES = new Set([
+            'application/ld+json',
+            'speculationrules',
+            'application/json+oembed',
+            'application/xml+oembed',
+        ]);
+        for (const script of document.querySelectorAll('script[type]')) {
+            if (!(script instanceof HTMLScriptElement))
+                continue;
+            const scriptType = (script.getAttribute('type') ?? '').toLowerCase();
+            if (!STRUCTURED_TYPES.has(scriptType))
+                continue;
+            const src = script.getAttribute('src') ?? undefined;
+            const text = script.textContent ?? '';
+            const inHead = !!script.closest('head');
+            const inNoscript = !!script.closest('noscript');
+            const location = inHead ? 'head' : inNoscript ? 'noscript' : 'body';
+            entries.push({
+                kind: 'script',
+                scriptType,
+                content: text || undefined,
+                src,
+                location,
+            });
+        }
+        for (const iframe of document.querySelectorAll('iframe[src]')) {
+            if (!(iframe instanceof HTMLIFrameElement))
+                continue;
+            const src = iframe.getAttribute('src') ?? '';
+            if (!src)
+                continue;
+            const inHead = !!iframe.closest('head');
+            const inNoscript = !!iframe.closest('noscript');
+            const location = inHead ? 'head' : inNoscript ? 'noscript' : 'body';
+            entries.push({ kind: 'iframe', src, location });
+        }
+        const win = window;
+        const presentGlobals = knownGlobals.filter((name) => win[name] !== undefined);
+        if (presentGlobals.length > 0) {
+            entries.push({ kind: 'window-global', names: presentGlobals });
+        }
+        return entries;
+    }, WINDOW_GLOBALS_TO_CHECK)
+        .catch(() => []);
+    return raw;
 }

package/dist/index.d.ts

@@ -18,4 +18,4 @@ export { detectCDN } from '@d-zero/shared/detect-cdn';
 export type { CDNType } from '@d-zero/shared/detect-cdn';
 export type { ScrapeResult, ResourceEntry, PageData } from './types.js';
 export type { ScraperOptions, ChangePhaseEvent, ScraperEventTypes } from './types.js';
-export type { Resource, AnchorData, Meta, ImageElement, SkippedPageData, NetworkLog, } from './types.js';
+export type { Resource, AnchorData, Meta, ImageElement, SkippedPageData, NetworkLog, OpenGraphMeta, OgArticleMeta, OgBookMeta, OgProfileMeta, OgMusicMeta, OgVideoNsMeta, TwitterMeta, FbMeta, FediverseMeta, AppleMeta, MsApplicationMeta, VerificationMeta, GoogleMeta, GeoMeta, CitationMeta, RdfaMeta, MicrodataMeta, AmpMeta, LegacyMeta, MobileMeta, MicroformatsMeta, PinterestMeta, SlackMeta, LinkedInMeta, ExperimentalMeta, WikiMeta, LinkMeta, LinkEntry, JsonLdEntry, OthersBucket, ScriptEntry, IframeEntry, TagsMeta, TagDetail, TagEntry, TagSource, ViewportMeta, RobotsMeta, ReferrerMeta, FormatDetectionMeta, HttpEquivMeta, HttpEquivRefresh, RawHeadEntry, } from './types.js';

package/dist/meta/classify.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Pure-function classifier that turns `RawHeadEntry[]` (collected on the browser
+ * side by `collectHead`) into a typed `Meta` object.
+ *
+ * The classifier is the **only place** where dot-paths from `keys.ts` get
+ * resolved against the `Meta` shape. Parsers (viewport/robots/refresh/etc.)
+ * are dispatched on the fly for the few entries that need value normalization.
+ *
+ * Unknown entries (names/properties/rels not in the lookup tables) are
+ * preserved in {@link Meta.others} so consumers never lose information.
+ * @module
+ */
+import type { Meta, RawHeadEntry, TagsMeta } from './types.js';
+/**
+ * Options for {@link classify}.
+ */
+export type ClassifyOptions = {
+    /**
+     * When `true`, copies the input `raw` entries onto `Meta._raw` for debugging.
+     * Default `false` to keep the serialized `Meta` small.
+     */
+    readonly includeRaw?: boolean;
+    /**
+     * Pre-computed `TagsMeta` from `tag-detection.ts`. When omitted, an empty
+     * `TagsMeta` (with `detected: {}` and `entries: []`) is used.
+     */
+    readonly tags?: TagsMeta;
+};
+/**
+ * Builds the empty `Meta` skeleton with all required fields initialized.
+ */
+/** Returns a fresh `Meta` skeleton with all required fields initialized. */
+export declare function emptyMeta(): Meta;
+/**
+ * Writes `value` to `target` along `dotPath`. Intermediate objects are created
+ * on demand. When `multi` is `true`, the leaf is treated as an array and `value`
+ * is appended; otherwise the first assignment wins (subsequent calls are no-ops).
+ *
+ * Exported for the unit tests in `classify.spec.ts`.
+ * @param target
+ * @param dotPath
+ * @param value
+ * @param multi
+ */
+export declare function setByPath(target: Record<string, unknown>, dotPath: string, value: unknown, multi: boolean): void;
+/**
+ * Top-level classifier. Takes a list of raw entries collected from the page
+ * and produces a populated `Meta`.
+ * @param raw
+ * @param options
+ */
+export declare function classify(raw: readonly RawHeadEntry[], options?: ClassifyOptions): Meta;