page-markdown 0.1.3 → 0.1.5

package/src/sanitize.js

@@ -1,193 +1,196 @@
-// Stage 1: clone the page into an inert document, inline open shadow roots
-// within limits, and strip non-content. The live page is never modified.
-
-export const DEFAULT_SANITIZE_OPTIONS = Object.freeze({
-  stripScripts: true,
-  stripStyles: true,
-  stripNoscript: true,
-  stripMeta: true,
-  stripLinkTags: true,
-  stripAds: true,
-  // App-specific overlays or widgets to drop, e.g. "[data-app-overlay]".
-  extraStripSelectors: [],
-  shadowNodeLimit: 5000,
-  shadowCharLimit: 500000,
-  shadowDepthLimit: 128,
-});
-
-const STRIP_RULES = {
-  stripScripts: "script",
-  stripStyles: "style",
-  stripNoscript: "noscript",
-  stripMeta: "meta",
-  stripLinkTags: "link",
-};
-
-// Advertising placements: explicit ad markup, plus custom elements named for ad
-// slots (e.g. MDN's <mdn-placement-sidebar>).
-const AD_SELECTOR = [
-  "ins.adsbygoogle", ".adsbygoogle", ".advertisement",
-  "[data-ad-slot]", "[data-ad-client]", "[data-ad-unit]",
-  "[aria-label='Advertisement' i]", "[aria-label='Advertisements' i]", "[aria-label='Sponsored' i]",
-  "iframe[src*='doubleclick.net']", "iframe[src*='googlesyndication.com']", "iframe[id^='google_ads_iframe']",
-].join(", ");
-const AD_ELEMENT_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*-(?:placement|advert|advertisement|ads?|sponsor|sponsored)(?:-[a-z0-9]+)*$/;
-
-/** @param {any} node */
-export function isAdvertisementElement(node) {
-  if (node?.nodeType !== 1) return false;
-  if (AD_ELEMENT_NAME.test(node.localName || "")) return true;
-  try {
-    return Boolean(node.matches?.(AD_SELECTOR));
-  } catch {
-    // DOM implementations without case-insensitive attribute selectors.
-    return Boolean(node.matches?.(AD_SELECTOR.replace(/ i\]/g, "]")));
-  }
-}
-
-function stripSelectors(options) {
-  const selectors = Object.entries(STRIP_RULES)
-    .filter(([flag]) => options[flag])
-    .map(([, selector]) => selector);
-  for (const extra of options.extraStripSelectors || []) {
-    if (typeof extra === "string" && extra.trim()) selectors.push(extra.trim());
-  }
-  return selectors;
-}
-
-function isStripped(node, selectors, options) {
-  if (node.nodeType !== 1) return false;
-  if (selectors.some((selector) => node.matches?.(selector))) return true;
-  return Boolean(options.stripAds && isAdvertisementElement(node));
-}
-
-/**
- * Creates an empty HTML document unconnected to the page: no scripts run and
- * no custom elements upgrade in it.
- * @param {Document} doc
- */
-export function createInertDocument(doc) {
-  const impl = doc?.implementation;
-  if (typeof impl?.createHTMLDocument === "function") return impl.createHTMLDocument("");
-  const Parser = doc?.defaultView?.DOMParser || globalThis.DOMParser;
-  if (typeof Parser === "function") {
-    return new Parser().parseFromString("<!doctype html><html><head></head><body></body></html>", "text/html");
-  }
-  throw new Error("page-markdown: cannot create an inert document (no createHTMLDocument or DOMParser)");
-}
-
-const SHADOW_LIMIT = Symbol("shadow limit");
-
-function positiveLimit(value, name) {
-  if (!Number.isSafeInteger(value) || value < 1) {
-    throw new RangeError(`page-markdown: ${name} must be a positive integer`);
-  }
-  return value;
-}
-
-/**
- * Clones `root` (a Document or Element) into a new inert document.
- * Open shadow roots replace their host's light children (native slots supply
- * assigned children). Limits apply only to shadow content; a host over the
- * limit is emptied and counted as an omission.
- *
- * @param {Document|Element} root
- * @param {Partial<typeof DEFAULT_SANITIZE_OPTIONS>} [options]
- * @returns {{ document: Document, omissions: { shadowHosts: number } }}
- */
-export function sanitizeToInertDocument(root, options = {}) {
-  const opts = { ...DEFAULT_SANITIZE_OPTIONS, ...options };
-  const limits = {
-    nodes: positiveLimit(opts.shadowNodeLimit, "shadowNodeLimit"),
-    chars: positiveLimit(opts.shadowCharLimit, "shadowCharLimit"),
-    depth: positiveLimit(opts.shadowDepthLimit, "shadowDepthLimit"),
-  };
-  const selectors = stripSelectors(opts);
-  const sourceDoc = root.nodeType === 9 ? root : root.ownerDocument;
-  const source = root.nodeType === 9 ? root.documentElement : root;
-  const inert = createInertDocument(sourceDoc);
-
-  function shallow(node) {
-    if (node.nodeType !== 1) return inert.importNode(node, false);
-    const name = node.prefix ? `${node.prefix}:${node.localName}` : node.localName;
-    const copy = node.namespaceURI
-      ? inert.createElementNS(node.namespaceURI, name)
-      : inert.createElement(name);
-    for (const attr of Array.from(node.attributes || [])) {
-      // HTML allows colon-bearing names without a namespace (framework
-      // directives); setAttributeNS rejects those.
-      if (attr.namespaceURI) copy.setAttributeNS(attr.namespaceURI, attr.name, attr.value);
-      else copy.setAttribute(attr.name, attr.value);
-    }
-    return copy;
-  }
-
-  let nodes = 0;
-  let chars = 0;
-  let shadowHosts = 0;
-
-  function isAssigningSlot(node) {
-    return node.nodeType === 1 && node.localName === "slot"
-      && typeof node.assignedNodes === "function" && Boolean(node.getRootNode?.().host);
-  }
-
-  function shadowNode(node, depth) {
-    if (++nodes > limits.nodes || depth > limits.depth) throw SHADOW_LIMIT;
-    if (isStripped(node, selectors, opts)) return inert.createDocumentFragment();
-    const copy = shallow(node);
-    chars += node.nodeType === 1 ? (copy.outerHTML || "").length : (node.nodeValue || "").length * 6;
-    if (chars > limits.chars) throw SHADOW_LIMIT;
-    let children = node.childNodes;
-    let target = copy;
-    if (isAssigningSlot(node)) {
-      const assigned = node.assignedNodes({ flatten: true });
-      children = assigned.length ? assigned : node.childNodes;
-      target = inert.createDocumentFragment();
-    } else if (node.shadowRoot) {
-      children = node.shadowRoot.childNodes;
-    } else if (node.nodeType === 1 && node.localName === "template" && node.content) {
-      children = node.content.childNodes;
-      target = copy.content || copy;
-    }
-    for (const child of Array.from(children || [])) target.appendChild(shadowNode(child, depth + 1));
-    return isAssigningSlot(node) ? target : copy;
-  }
-
-  const clone = shallow(source);
-  // Iterative light-DOM walk: ordinary pages get no depth limit.
-  const pending = [[source, clone]];
-  while (pending.length) {
-    const [live, copy] = pending.pop();
-    if (live.shadowRoot) {
-      const fragment = inert.createDocumentFragment();
-      try {
-        for (const child of Array.from(live.shadowRoot.childNodes)) fragment.appendChild(shadowNode(child, 1));
-        while (copy.firstChild) copy.removeChild(copy.firstChild);
-        copy.appendChild(fragment);
-      } catch (error) {
-        if (error !== SHADOW_LIMIT) throw error;
-        while (copy.firstChild) copy.removeChild(copy.firstChild);
-        shadowHosts += 1;
-      }
-      continue;
-    }
-    const children = live.content?.childNodes || live.childNodes;
-    const target = copy.content || copy;
-    const pairs = [];
-    for (const child of Array.from(children || [])) {
-      if (isStripped(child, selectors, opts)) continue;
-      const childCopy = shallow(child);
-      target.appendChild(childCopy);
-      pairs.push([child, childCopy]);
-    }
-    for (let i = pairs.length - 1; i >= 0; i -= 1) pending.push(pairs[i]);
-  }
-
-  if (clone.localName === "html") {
-    inert.removeChild(inert.documentElement);
-    inert.appendChild(clone);
-  } else {
-    inert.body.appendChild(clone);
-  }
-  return { document: inert, omissions: { shadowHosts } };
-}
+// Stage 1: clone the page into an inert document, inline open shadow roots
+// within limits, and strip non-content. The live page is never modified.
+
+/** @type {Readonly<Required<import("./types.js").SanitizeOptions>>} */
+export const DEFAULT_SANITIZE_OPTIONS = Object.freeze({
+  stripScripts: true,
+  stripStyles: true,
+  stripNoscript: true,
+  stripMeta: true,
+  stripLinkTags: true,
+  stripAds: true,
+  // App-specific overlays or widgets to drop, e.g. "[data-app-overlay]".
+  extraStripSelectors: [],
+  shadowNodeLimit: 5000,
+  shadowCharLimit: 500000,
+  shadowDepthLimit: 128,
+});
+
+const STRIP_RULES = {
+  stripScripts: "script",
+  stripStyles: "style",
+  stripNoscript: "noscript",
+  stripMeta: "meta",
+  stripLinkTags: "link",
+};
+
+// Advertising placements: explicit ad markup, plus custom elements named for ad
+// slots (e.g. MDN's <mdn-placement-sidebar>).
+const AD_SELECTOR = [
+  "ins.adsbygoogle", ".adsbygoogle", ".advertisement",
+  "[data-ad-slot]", "[data-ad-client]", "[data-ad-unit]",
+  "[aria-label='Advertisement' i]", "[aria-label='Advertisements' i]", "[aria-label='Sponsored' i]",
+  "iframe[src*='doubleclick.net']", "iframe[src*='googlesyndication.com']", "iframe[id^='google_ads_iframe']",
+].join(", ");
+const AD_ELEMENT_NAME = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*-(?:placement|advert|advertisement|ads?|sponsor|sponsored)(?:-[a-z0-9]+)*$/;
+
+/** @param {any} node */
+export function isAdvertisementElement(node) {
+  if (node?.nodeType !== 1) return false;
+  // Sites put page-wide ad settings on <body> (heise.de's data-ad-unit).
+  if (node.localName === "html" || node.localName === "body") return false;
+  if (AD_ELEMENT_NAME.test(node.localName || "")) return true;
+  try {
+    return Boolean(node.matches?.(AD_SELECTOR));
+  } catch {
+    // DOM implementations without case-insensitive attribute selectors.
+    return Boolean(node.matches?.(AD_SELECTOR.replace(/ i\]/g, "]")));
+  }
+}
+
+function stripSelectors(options) {
+  const selectors = Object.entries(STRIP_RULES)
+    .filter(([flag]) => options[flag])
+    .map(([, selector]) => selector);
+  for (const extra of options.extraStripSelectors || []) {
+    if (typeof extra === "string" && extra.trim()) selectors.push(extra.trim());
+  }
+  return selectors;
+}
+
+function isStripped(node, selectors, options) {
+  if (node.nodeType !== 1) return false;
+  if (selectors.some((selector) => node.matches?.(selector))) return true;
+  return Boolean(options.stripAds && isAdvertisementElement(node));
+}
+
+/**
+ * Creates an empty HTML document unconnected to the page: no scripts run and
+ * no custom elements upgrade in it.
+ * @param {Document} doc
+ */
+export function createInertDocument(doc) {
+  const impl = doc?.implementation;
+  if (typeof impl?.createHTMLDocument === "function") return impl.createHTMLDocument("");
+  const Parser = doc?.defaultView?.DOMParser || globalThis.DOMParser;
+  if (typeof Parser === "function") {
+    return new Parser().parseFromString("<!doctype html><html><head></head><body></body></html>", "text/html");
+  }
+  throw new Error("page-markdown: cannot create an inert document (no createHTMLDocument or DOMParser)");
+}
+
+const SHADOW_LIMIT = Symbol("shadow limit");
+
+function positiveLimit(value, name) {
+  if (!Number.isSafeInteger(value) || value < 1) {
+    throw new RangeError(`page-markdown: ${name} must be a positive integer`);
+  }
+  return value;
+}
+
+/**
+ * Clones `root` (a Document or Element) into a new inert document.
+ * Open shadow roots replace their host's light children (native slots supply
+ * assigned children). Limits apply only to shadow content; a host over the
+ * limit is emptied and counted as an omission.
+ *
+ * @param {Document|Element} root
+ * @param {import("./types.js").SanitizeOptions} [options]
+ * @returns {{ document: Document, omissions: { shadowHosts: number } }}
+ */
+export function sanitizeToInertDocument(root, options = {}) {
+  const opts = { ...DEFAULT_SANITIZE_OPTIONS, ...options };
+  const limits = {
+    nodes: positiveLimit(opts.shadowNodeLimit, "shadowNodeLimit"),
+    chars: positiveLimit(opts.shadowCharLimit, "shadowCharLimit"),
+    depth: positiveLimit(opts.shadowDepthLimit, "shadowDepthLimit"),
+  };
+  const selectors = stripSelectors(opts);
+  const sourceDoc = /** @type {Document} */ (root.nodeType === 9 ? root : root.ownerDocument);
+  const source = root.nodeType === 9 ? /** @type {Document} */ (root).documentElement : root;
+  const inert = createInertDocument(sourceDoc);
+
+  function shallow(node) {
+    if (node.nodeType !== 1) return inert.importNode(node, false);
+    const name = node.prefix ? `${node.prefix}:${node.localName}` : node.localName;
+    const copy = node.namespaceURI
+      ? inert.createElementNS(node.namespaceURI, name)
+      : inert.createElement(name);
+    for (const attr of Array.from(node.attributes || [])) {
+      // HTML allows colon-bearing names without a namespace (framework
+      // directives); setAttributeNS rejects those.
+      if (attr.namespaceURI) copy.setAttributeNS(attr.namespaceURI, attr.name, attr.value);
+      else copy.setAttribute(attr.name, attr.value);
+    }
+    return copy;
+  }
+
+  let nodes = 0;
+  let chars = 0;
+  let shadowHosts = 0;
+
+  function isAssigningSlot(node) {
+    return node.nodeType === 1 && node.localName === "slot"
+      && typeof node.assignedNodes === "function" && Boolean(node.getRootNode?.().host);
+  }
+
+  function shadowNode(node, depth) {
+    if (++nodes > limits.nodes || depth > limits.depth) throw SHADOW_LIMIT;
+    if (isStripped(node, selectors, opts)) return inert.createDocumentFragment();
+    const copy = shallow(node);
+    chars += node.nodeType === 1 ? (copy.outerHTML || "").length : (node.nodeValue || "").length * 6;
+    if (chars > limits.chars) throw SHADOW_LIMIT;
+    let children = node.childNodes;
+    let target = copy;
+    if (isAssigningSlot(node)) {
+      const assigned = node.assignedNodes({ flatten: true });
+      children = assigned.length ? assigned : node.childNodes;
+      target = inert.createDocumentFragment();
+    } else if (node.shadowRoot) {
+      children = node.shadowRoot.childNodes;
+    } else if (node.nodeType === 1 && node.localName === "template" && node.content) {
+      children = node.content.childNodes;
+      target = copy.content || copy;
+    }
+    for (const child of Array.from(children || [])) target.appendChild(shadowNode(child, depth + 1));
+    return isAssigningSlot(node) ? target : copy;
+  }
+
+  const clone = shallow(source);
+  // Iterative light-DOM walk: ordinary pages get no depth limit.
+  const pending = [[source, clone]];
+  while (pending.length) {
+    const [live, copy] = /** @type {any[]} */ (pending.pop());
+    if (live.shadowRoot) {
+      const fragment = inert.createDocumentFragment();
+      try {
+        for (const child of Array.from(live.shadowRoot.childNodes)) fragment.appendChild(shadowNode(child, 1));
+        while (copy.firstChild) copy.removeChild(copy.firstChild);
+        copy.appendChild(fragment);
+      } catch (error) {
+        if (error !== SHADOW_LIMIT) throw error;
+        while (copy.firstChild) copy.removeChild(copy.firstChild);
+        shadowHosts += 1;
+      }
+      continue;
+    }
+    const children = live.content?.childNodes || live.childNodes;
+    const target = copy.content || copy;
+    const pairs = [];
+    for (const child of Array.from(children || [])) {
+      if (isStripped(child, selectors, opts)) continue;
+      const childCopy = shallow(child);
+      target.appendChild(childCopy);
+      pairs.push([child, childCopy]);
+    }
+    for (let i = pairs.length - 1; i >= 0; i -= 1) pending.push(pairs[i]);
+  }
+
+  if (clone.localName === "html") {
+    inert.removeChild(inert.documentElement);
+    inert.appendChild(clone);
+  } else {
+    inert.body.appendChild(clone);
+  }
+  return { document: inert, omissions: { shadowHosts } };
+}

package/src/standardize.js

@@ -15,6 +15,10 @@ const NON_LANGUAGES = new Set(["default", "none", "text", "plain", "plaintext",
 const EDIT_WIDGETS = ".mw-editsection, .headerlink, .anchor, .heading-anchor, a.anchor, [aria-hidden='true'] a";
 // Content without text that a heading wrapper may still hold.
 const MEDIA = "img, picture, video, audio";
+// Highlighters mark up each code line with one of these.
+const CODE_LINE_ELEMENTS = new Set(["div", "p", "li", "tr", "section"]);
+// As URL parsers read a scheme: control characters and spaces don't count.
+const isUnsafeUrl = (value) => /^(?:javascript|vbscript|data):/i.test(String(value).replace(/[\x00-\x20]+/g, ""));
 
 function resolveUrl(value, base) {
   const raw = String(value || "").trim();
@@ -44,7 +48,7 @@ function languageFrom(el, maxDepth = 3) {
 
 function hasMeaningfulContent(el) {
   if ((el.textContent || "").trim()) return true;
-  return Boolean(el.querySelector?.("img[alt]:not([alt='']), svg title"));
+  return Boolean(el.querySelector?.("img, svg title"));
 }
 
 /**
@@ -62,7 +66,7 @@ function standardizeImages(doc, base, stats) {
       }
     }
     const current = img.getAttribute("src") || "";
-    if (!current || current.startsWith("data:")) {
+    if (!current || isUnsafeUrl(current)) {
       img.remove();
       stats.inlineImagesDropped += 1;
       continue;
@@ -74,7 +78,7 @@ function standardizeImages(doc, base, stats) {
 function standardizeLinks(doc, base, stats) {
   for (const a of Array.from(doc.querySelectorAll("a"))) {
     const href = a.getAttribute("href") || "";
-    if (/^\s*javascript:/i.test(href)) {
+    if (isUnsafeUrl(href)) {
       a.replaceWith(...Array.from(a.childNodes));
       stats.scriptLinksUnwrapped += 1;
       continue;
@@ -88,20 +92,41 @@ function standardizeLinks(doc, base, stats) {
   }
 }
 
+/** Text of a code block, with <br> and block-level lines as line breaks. */
+function codeText(root) {
+  let text = "";
+  const walk = (node) => {
+    for (const child of Array.from(node.childNodes)) {
+      if (child.nodeType === 3) text += child.nodeValue;
+      else if (child.nodeType !== 1) continue;
+      else if (child.localName === "br") text += "\n";
+      else {
+        const block = CODE_LINE_ELEMENTS.has(child.localName);
+        if (block && text && !text.endsWith("\n")) text += "\n";
+        walk(child);
+        if (block && text && !text.endsWith("\n")) text += "\n";
+      }
+    }
+  };
+  walk(root);
+  return text;
+}
+
 /** <pre> without <code> (and code without a language) gets a language-tagged <code>. */
 function standardizeCode(doc, stats) {
   for (const pre of Array.from(doc.querySelectorAll("pre"))) {
-    const lang = languageFrom(pre);
-    let code = Array.from(pre.children || []).length === 1 && pre.firstElementChild?.localName === "code"
-      ? pre.firstElementChild
-      : null;
-    if (!code) {
-      code = doc.createElement("code");
-      code.textContent = pre.textContent || "";
-      while (pre.firstChild) pre.removeChild(pre.firstChild);
-      pre.appendChild(code);
-      stats.preWrapped += 1;
-    }
+    for (const button of Array.from(pre.querySelectorAll("button"))) button.remove();
+    const inner = pre.querySelector("code");
+    const lang = languageFrom(inner || pre, inner ? 4 : 3);
+    // One <code> and only whitespace around it: that <code> is the block.
+    const sole = pre.children.length === 1 && pre.firstElementChild === inner
+      && !(pre.textContent || "").replace(inner.textContent || "", "").trim();
+    const code = sole ? inner : doc.createElement("code");
+    if (!sole) stats.preWrapped += 1;
+    // Turndown reads textContent, so lines kept apart by markup become text.
+    code.textContent = codeText(sole ? inner : pre);
+    while (pre.firstChild) pre.removeChild(pre.firstChild);
+    pre.appendChild(code);
     if (lang && !/(?:^|\s)language-/.test(code.getAttribute("class") || "")) {
       code.setAttribute("class", `${code.getAttribute("class") || ""} language-${lang}`.trim());
     }
@@ -124,7 +149,8 @@ function standardizeHeadings(doc, stats) {
     const parent = heading.parentElement;
     if (!parent || parent.localName !== "div") continue;
     const others = Array.from(parent.children).filter((el) => el !== heading);
-    if (others.every((el) => !(el.textContent || "").trim() && !el.matches?.(MEDIA) && !el.querySelector?.(MEDIA))) {
+    const hasBareText = Array.from(parent.childNodes).some((node) => node.nodeType === 3 && node.nodeValue.trim());
+    if (!hasBareText && others.every((el) => !(el.textContent || "").trim() && !el.matches?.(MEDIA) && !el.querySelector?.(MEDIA))) {
       parent.replaceWith(heading);
       stats.headingsUnwrapped += 1;
     }

package/src/types.js

@@ -0,0 +1,118 @@
+/// <reference lib="dom" preserve="true" />
+// Types only: nothing here exists at runtime. `npm run build:types` turns these
+// and the JSDoc in the other modules into dist/types, which is what TypeScript
+// consumers see.
+export {};
+
+/** @typedef {"full"|"no_links"|"text_only"} OutputMode */
+
+/**
+ * @typedef {object} SanitizeOptions
+ * @property {boolean} [stripScripts]
+ * @property {boolean} [stripStyles]
+ * @property {boolean} [stripNoscript]
+ * @property {boolean} [stripMeta]
+ * @property {boolean} [stripLinkTags]
+ * @property {boolean} [stripAds]
+ * @property {readonly string[]} [extraStripSelectors] app-specific overlays or widgets to drop, e.g. "[data-app-overlay]"
+ * @property {number} [shadowNodeLimit]
+ * @property {number} [shadowCharLimit]
+ * @property {number} [shadowDepthLimit]
+ */
+
+/** @typedef {NonNullable<ConstructorParameters<typeof import("@mozilla/readability").Readability<string>>[1]>} ReadabilityOptions */
+
+/** @typedef {import("./extract.js").Extraction} Extraction */
+
+/** @typedef {import("./extract.js").Extractor} Extractor */
+
+/** @typedef {ReturnType<typeof import("./metadata.js").collectMetadata>} CollectedMetadata */
+
+/**
+ * @typedef {object} ExtractedMetadata
+ * @property {string} [headline] the heading chosen for the capture
+ * @property {string} [extractedTitle] the title the extractor reported
+ * @property {string} [byline] the byline the extractor reported
+ */
+
+/** @typedef {CollectedMetadata & ExtractedMetadata} PageMarkdownMetadata */
+
+/**
+ * @typedef {object} PageMarkdownExtraction
+ * @property {Extraction["method"]} method
+ * @property {string} [fallbackReason] why extraction fell back to the full page
+ * @property {true} [leadRecovered] a dropped lead paragraph was restored
+ * @property {number} [pageFacts] how many facts `pageFacts` appended
+ */
+
+/** @typedef {"tag"|"variation_selector"|"invisible_operator"|"reserved_tag_plane"} HiddenRunKind */
+
+/**
+ * A run as text-sanctifier's findHiddenRuns reports it.
+ * @typedef {object} HiddenRun
+ * @property {HiddenRunKind} kind
+ * @property {number} offset UTF-16 index of the first character
+ * @property {number} end UTF-16 index just past the last character
+ * @property {number} count code points in the run
+ * @property {number} line 1-based line of the first character
+ * @property {number} column 1-based column of the first character, in UTF-16 units
+ * @property {string} [decoded] tag runs only: the ASCII the tags spell
+ * @property {boolean} [decodedTruncated] tag runs only: true when `decoded` stops short of the run
+ */
+
+/**
+ * @typedef {object} HiddenTextOmission
+ * @property {`hidden_${HiddenRunKind}`} kind
+ * @property {number} count runs removed from `markdown`
+ * @property {number} chars code points in those runs
+ * @property {string} note
+ */
+
+/**
+ * Check `kind` before reading `chars`: only hidden-text omissions have it.
+ * @typedef {{ kind: "shadow_content", count: number, note: string }
+ *   | { kind: "json_line", count: number, note: string }
+ *   | HiddenTextOmission} PageMarkdownOmission
+ */
+
+/** @typedef {ReturnType<typeof import("./standardize.js").standardizeDocument>} StandardizationStats */
+
+/**
+ * @typedef {object} PageMarkdownStats
+ * @property {OutputMode} mode
+ * @property {number} extractedHtmlChars
+ * @property {number} convertedChars
+ * @property {number} markdownChars
+ * @property {StandardizationStats} standardization
+ */
+
+/**
+ * @typedef {object} PageMarkdownResult
+ * @property {string} version the package version that made this result
+ * @property {string} markdown
+ * @property {PageMarkdownMetadata} metadata
+ * @property {PageMarkdownExtraction} extraction
+ * @property {PageMarkdownOmission[]} omissions
+ * @property {string[]} warnings
+ * @property {PageMarkdownStats} stats
+ * @property {string} [fullPageMarkdown] present only with `includeFullPage`
+ */
+
+/** @typedef {{ label: string, value: string }} PageFact */
+
+/**
+ * @typedef {string | string[] | ((node: HTMLElement, options: Record<string, unknown>) => boolean)} TurndownFilter
+ */
+
+/**
+ * Turndown's public methods; Turndown ships no types of its own.
+ * @typedef {object} TurndownInstance
+ * @property {(input: string | Node) => string} turndown
+ * @property {(plugin: TurndownPlugin | TurndownPlugin[]) => TurndownInstance} use
+ * @property {(key: string, rule: { filter: TurndownFilter, replacement: (content: string, node: Node, options: Record<string, unknown>) => string }) => TurndownInstance} addRule
+ * @property {(filter: TurndownFilter) => TurndownInstance} keep
+ * @property {(filter: TurndownFilter) => TurndownInstance} remove
+ * @property {(text: string) => string} escape
+ */
+
+/** @typedef {(service: TurndownInstance) => void} TurndownPlugin */