@zeldrisho/pi-web-fetch 0.7.1 → 0.8.0

package/src/focus.ts

@@ -0,0 +1,125 @@
+const WORD_PATTERN = /[\p{L}\p{N}_+#]+/gu;
+const HEADING_PATTERN = /^#{1,6}\s+\S/;
+
+/** Metadata describing deterministic query-focused extraction. */
+export interface FocusDetails {
+  query: string;
+  matchedSections: number;
+  totalSections: number;
+  omittedSections: number;
+  originalCharacters: number;
+  focusedCharacters: number;
+}
+
+export interface FocusResult {
+  markdown: string;
+  details: FocusDetails;
+}
+
+interface Section {
+  markdown: string;
+  tokens: string[];
+}
+
+function tokens(value: string): string[] {
+  return (value.toLowerCase().match(WORD_PATTERN) ?? []).filter((token) => token.length > 1);
+}
+
+/**
+ * Splits Markdown into sections. Headings stay attached to their following content; a
+ * headingless document falls back to paragraphs so focused extraction remains useful for
+ * plain-text and basic-extractor responses.
+ */
+function splitSections(markdown: string): Section[] {
+  const blocks = markdown
+    .split(/\n{2,}/)
+    .map((block) => block.trim())
+    .filter(Boolean);
+  if (blocks.length === 0) return [];
+
+  const lines = markdown.split(/\r?\n/);
+  const hasHeadings = lines.some((line) => HEADING_PATTERN.test(line));
+  if (!hasHeadings) return blocks.map((block) => ({ markdown: block, tokens: tokens(block) }));
+
+  const sections: string[] = [];
+  let current: string[] = [];
+  const flush = () => {
+    const section = current.join("\n").trim();
+    if (section) sections.push(section);
+    current = [];
+  };
+  for (const line of lines) {
+    if (HEADING_PATTERN.test(line)) flush();
+    current.push(line);
+  }
+  flush();
+  return sections.map((section) => ({ markdown: section, tokens: tokens(section) }));
+}
+
+/**
+ * Produces a deterministic, query-focused view of Markdown using a compact BM25-style
+ * section ranker. Matching sections retain source order so the result remains readable
+ * and attributable to the fetched page. The complete document is never mutated.
+ */
+export function focusMarkdown(markdown: string, query: string): FocusResult {
+  const normalizedQuery = query.trim();
+  const queryTerms = [...new Set(tokens(normalizedQuery))];
+  const sections = splitSections(markdown);
+  const originalCharacters = markdown.length;
+
+  if (queryTerms.length === 0 || sections.length === 0) {
+    return {
+      markdown: "",
+      details: {
+        query: normalizedQuery,
+        matchedSections: 0,
+        totalSections: sections.length,
+        omittedSections: sections.length,
+        originalCharacters,
+        focusedCharacters: 0,
+      },
+    };
+  }
+
+  const averageLength =
+    sections.reduce((sum, section) => sum + section.tokens.length, 0) / sections.length || 1;
+  const documentFrequency = new Map<string, number>();
+  for (const term of queryTerms) {
+    documentFrequency.set(
+      term,
+      sections.reduce((count, section) => count + (section.tokens.includes(term) ? 1 : 0), 0),
+    );
+  }
+
+  const selected = sections.filter((section) => {
+    const frequencies = new Map<string, number>();
+    for (const token of section.tokens) frequencies.set(token, (frequencies.get(token) ?? 0) + 1);
+    const lengthNormalization = 1 - 0.75 + 0.75 * (section.tokens.length / averageLength);
+    let score = 0;
+    for (const term of queryTerms) {
+      const frequency = frequencies.get(term) ?? 0;
+      if (frequency === 0) continue;
+      const frequencyInDocuments = documentFrequency.get(term) ?? 0;
+      const inverseDocumentFrequency = Math.log(
+        1 + (sections.length - frequencyInDocuments + 0.5) / (frequencyInDocuments + 0.5),
+      );
+      score +=
+        inverseDocumentFrequency *
+        ((frequency * (1.2 + 1)) / (frequency + 1.2 * lengthNormalization));
+    }
+    return score > 0;
+  });
+
+  const focused = selected.map((section) => section.markdown).join("\n\n");
+  return {
+    markdown: focused,
+    details: {
+      query: normalizedQuery,
+      matchedSections: selected.length,
+      totalSections: sections.length,
+      omittedSections: sections.length - selected.length,
+      originalCharacters,
+      focusedCharacters: focused.length,
+    },
+  };
+}

package/src/index.ts

@@ -6,6 +6,7 @@ import {
   FETCH_DEFAULT_OFFSET,
   FETCH_MAX_CHARACTERS,
   FETCH_MAX_OFFSET_CHARACTERS,
+  FETCH_MAX_QUERY_CHARACTERS,
   FETCH_MAX_URL_CHARACTERS,
   FETCH_MIN_MAX_CHARACTERS,
 } from "./limits";
@@ -14,9 +15,19 @@ import { executeWebFetch } from "./service";
 
 export { ExpiringLruCache } from "./cache";
 export type { FetchResult } from "./content";
+export {
+  diagnoseExtraction,
+  extractDocumentLinks,
+  type ExtractedLink,
+  type ExtractedLinks,
+  type ExtractionDiagnostics,
+} from "./evidence";
 export { fetchRemoteContent, type FetchRemoteDependencies } from "./fetch";
+export { focusMarkdown, type FocusDetails, type FocusResult } from "./focus";
+export { createDocumentOutline, type DocumentOutline, type OutlineHeading } from "./outline";
 export {
   executeWebFetch,
+  type CacheStatus,
   type WebFetchDetails,
   type WebFetchParameters,
   type WebFetchTruncationDetails,
@@ -35,6 +46,14 @@ export const webFetchParameters = Type.Object({
     maxLength: FETCH_MAX_URL_CHARACTERS,
     description: "Public HTTP or HTTPS URL to fetch",
   }),
+  query: Type.Optional(
+    Type.String({
+      minLength: 1,
+      maxLength: FETCH_MAX_QUERY_CHARACTERS,
+      description:
+        "Optional focus query; returns matching source sections in document order (offsets apply to the focused view)",
+    }),
+  ),
   offset: Type.Optional(
     Type.Integer({
       minimum: 0,

package/src/inflight.ts

@@ -5,6 +5,14 @@ interface InflightEntry<V> {
   waiters: number;
 }
 
+/**
+ * Wraps a promise to respect a caller's abort signal without cancelling the underlying operation.
+ *
+ * @param operation - Promise to wait for
+ * @param signal - Optional abort signal for this caller
+ * @param cancelledMessage - Error message to use when signal is aborted
+ * @returns Promise that rejects if signal aborts, otherwise resolves with operation result
+ */
 function waitForCaller<T>(
   operation: Promise<T>,
   signal: AbortSignal | undefined,
@@ -28,10 +36,24 @@ export class InflightCoalescer<K, V> {
 
   constructor(readonly maxEntries: number) {}
 
+  /**
+   * Gets the number of currently in-flight operations.
+   *
+   * @returns Count of active operations
+   */
   get size(): number {
     return this.#entries.size;
   }
 
+  /**
+   * Runs an operation, coalescing with any identical in-flight operation.
+   *
+   * @param key - Operation key for coalescing identical operations
+   * @param operation - Function that performs the operation
+   * @param signal - Optional abort signal for this caller
+   * @param cancelledMessage - Error message when signal is aborted
+   * @returns Promise resolving to the operation result
+   */
   async run(
     key: K,
     operation: (signal: AbortSignal | undefined) => Promise<V>,

package/src/limits.ts

@@ -13,5 +13,8 @@ export const FETCH_MAX_CHARACTERS = 30_000;
 /** Maximum allowed offset for content extraction (characters). */
 export const FETCH_MAX_OFFSET_CHARACTERS = 20_000_000;
 
+/** Maximum allowed length for an optional focus query (characters). */
+export const FETCH_MAX_QUERY_CHARACTERS = 400;
+
 /** Maximum allowed length for input URLs (characters). */
 export const FETCH_MAX_URL_CHARACTERS = 2_048;

package/src/network-redirects.ts

@@ -5,33 +5,146 @@ import { requestPinned, responseHeader } from "./network-transport";
 
 /** Maximum number of HTTP redirects to follow before aborting. */
 export const FETCH_MAX_REDIRECTS = 5;
+const MAX_ORIGIN_CONCURRENCY = 4;
+const MAX_RETRIES = 2;
+const MAX_RETRY_DELAY_MS = 10_000;
+const BASE_RETRY_DELAY_MS = 250;
+
+interface OriginState {
+  active: number;
+  waiting: Array<() => void>;
+}
+const origins = new Map<string, OriginState>();
 
 /** Optional dependencies for redirect handling (used for testing). */
 export interface RedirectDependencies {
   validateUrl?: (value: string | URL) => Promise<ValidatedTarget>;
-  request?: (target: ValidatedTarget, signal: AbortSignal) => Promise<IncomingMessage>;
+  request?: (
+    target: ValidatedTarget,
+    signal: AbortSignal,
+    headers?: Readonly<Record<string, string>>,
+  ) => Promise<IncomingMessage>;
+  random?: () => number;
+  sleep?: (milliseconds: number, signal: AbortSignal) => Promise<void>;
+}
+
+function abortError(): Error {
+  const error = new Error("Operation aborted.");
+  error.name = "AbortError";
+  return error;
+}
+
+async function acquireOrigin(origin: string, signal: AbortSignal): Promise<() => void> {
+  const state = origins.get(origin) ?? { active: 0, waiting: [] };
+  origins.set(origin, state);
+  let reserved = false;
+  const release = () => {
+    state.active -= 1;
+    state.waiting.shift()?.();
+    if (state.active === 0 && state.waiting.length === 0) origins.delete(origin);
+  };
+  if (state.active >= MAX_ORIGIN_CONCURRENCY) {
+    await new Promise<void>((resolve, reject) => {
+      const enter = () => {
+        signal.removeEventListener("abort", cancel);
+        state.active += 1;
+        reserved = true;
+        resolve();
+      };
+      const cancel = () => {
+        const index = state.waiting.indexOf(enter);
+        if (index >= 0) state.waiting.splice(index, 1);
+        reject(abortError());
+      };
+      if (signal.aborted) cancel();
+      else {
+        state.waiting.push(enter);
+        signal.addEventListener("abort", cancel, { once: true });
+      }
+    });
+  }
+  if (signal.aborted) {
+    if (reserved) release();
+    throw abortError();
+  }
+  if (!reserved) state.active += 1;
+  return release;
+}
+
+async function defaultSleep(milliseconds: number, signal: AbortSignal): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    const timer = setTimeout(done, milliseconds);
+    function done(): void {
+      signal.removeEventListener("abort", cancel);
+      resolve();
+    }
+    function cancel(): void {
+      clearTimeout(timer);
+      reject(abortError());
+    }
+    if (signal.aborted) cancel();
+    else signal.addEventListener("abort", cancel, { once: true });
+  });
+}
+
+function retryAfterMilliseconds(value: string | undefined, now = Date.now()): number | undefined {
+  if (!value) return undefined;
+  const seconds = Number(value.trim());
+  if (Number.isFinite(seconds) && seconds >= 0)
+    return Math.min(seconds * 1_000, MAX_RETRY_DELAY_MS);
+  const date = Date.parse(value);
+  if (!Number.isFinite(date)) return undefined;
+  return Math.min(Math.max(0, date - now), MAX_RETRY_DELAY_MS);
+}
+
+async function coordinatedRequest(
+  target: ValidatedTarget,
+  signal: AbortSignal,
+  headers: Readonly<Record<string, string>>,
+  dependencies: RedirectDependencies,
+): Promise<IncomingMessage> {
+  const request =
+    dependencies.request ??
+    ((value, requestSignal, requestHeaders) =>
+      requestPinned(value, requestSignal, { headers: requestHeaders }));
+  const random = dependencies.random ?? Math.random;
+  const sleep = dependencies.sleep ?? defaultSleep;
+  for (let attempt = 0; ; attempt += 1) {
+    const release = await acquireOrigin(target.url.origin, signal);
+    let response: IncomingMessage;
+    try {
+      response = await request(target, signal, headers);
+    } finally {
+      release();
+    }
+    const status = response.statusCode ?? 0;
+    if (![429, 503].includes(status) || attempt >= MAX_RETRIES) return response;
+    // The retry decision uses headers only. Drop an untrusted error body so it cannot
+    // consume unbounded bandwidth while the caller is backing off.
+    response.destroy();
+    const advertised = retryAfterMilliseconds(responseHeader(response, "retry-after"));
+    const exponential = BASE_RETRY_DELAY_MS * 2 ** attempt;
+    const jittered = Math.round(exponential * (0.75 + Math.min(1, Math.max(0, random())) * 0.5));
+    await sleep(advertised ?? Math.min(jittered, MAX_RETRY_DELAY_MS), signal);
+  }
 }
 
 /**
- * Requests a URL and follows supported HTTP redirects.
- *
- * @param value - The initial URL to request
- * @param signal - Signal used to cancel validation and requests
- * @param dependencies - Optional URL-validation and request implementations
- * @returns The final validated target and its HTTP response
- * @throws If a redirect lacks a `Location` header or the redirect limit is exceeded
+ * Requests a URL and follows supported HTTP redirects. Every attempt, redirect, and retry
+ * remains inside URL validation, DNS pinning, origin coordination, and caller cancellation.
  */
 export async function requestFollowingRedirects(
   value: string | URL,
   signal: AbortSignal,
   dependencies: RedirectDependencies = {},
+  headers: Readonly<Record<string, string>> = {},
 ): Promise<{ target: ValidatedTarget; response: IncomingMessage }> {
   const validateUrl = dependencies.validateUrl ?? validateRemoteUrl;
-  const request = dependencies.request ?? requestPinned;
   let target = await awaitWithAbort(validateUrl(value), signal);
+  let requestHeaders = headers;
 
   for (let redirects = 0; redirects <= FETCH_MAX_REDIRECTS; redirects += 1) {
-    const response = await request(target, signal);
+    const response = await coordinatedRequest(target, signal, requestHeaders, dependencies);
     const status = response.statusCode ?? 0;
     if (![301, 302, 303, 307, 308].includes(status)) return { target, response };
 
@@ -41,6 +154,8 @@ export async function requestFollowingRedirects(
       throw new Error("web_fetch followed too many redirects.");
     response.resume();
     target = await awaitWithAbort(validateUrl(new URL(location, target.url)), signal);
+    // Validators describe the originally cached resource and must not leak to a redirect target.
+    requestHeaders = {};
   }
   throw new Error("web_fetch followed too many redirects.");
 }

package/src/network-transport.ts

@@ -60,6 +60,7 @@ async function requestOnce(
   address: string,
   signal: AbortSignal,
   attemptTimeoutMs: number,
+  headers: Readonly<Record<string, string>>,
 ): Promise<IncomingMessage> {
   const family = isIP(address);
   if (family !== 4 && family !== 6) throw new Error(`web_fetch could not resolve ${address}.`);
@@ -101,6 +102,7 @@ async function requestOnce(
         headers: {
           Accept: "text/markdown, text/html, text/plain, application/json;q=0.9, */*;q=0.1",
           "User-Agent": "Mozilla/5.0 (compatible; PiWebFetch/1.0; +https://pi.dev)",
+          ...headers,
         },
       },
       (response) => {
@@ -126,6 +128,8 @@ async function requestOnce(
 export interface RequestPinnedOptions {
   /** Per-address connect deadline used to fall back to the next address. */
   attemptTimeoutMs?: number;
+  /** Additional fixed request headers, used for conditional cache revalidation. */
+  headers?: Readonly<Record<string, string>>;
 }
 
 /**
@@ -146,7 +150,7 @@ export async function requestPinned(
   let lastError: unknown;
   for (const address of addresses) {
     try {
-      return await requestOnce(target, address, signal, attemptTimeoutMs);
+      return await requestOnce(target, address, signal, attemptTimeoutMs, options.headers ?? {});
     } catch (error) {
       lastError = error;
       if (signal.aborted) throw error;

package/src/outline.ts

@@ -0,0 +1,240 @@
+const FENCE = /^[ \t]{0,3}(`{3,}|~{3,})/;
+const MAX_FALLBACK_HEADING_CHARACTERS = 60;
+export const MAX_OUTLINE_HEADINGS = 12;
+export const MAX_OUTLINE_HEADING_CHARACTERS = 120;
+
+/** One bounded heading exposed as untrusted document-shape metadata. */
+export interface OutlineHeading {
+  level: number;
+  text: string;
+  words: number;
+  inferred: boolean;
+}
+
+/** Bounded structural summary of a complete extracted document. */
+export interface DocumentOutline {
+  totalWords: number;
+  totalHeadings: number;
+  headings: OutlineHeading[];
+  omittedHeadings: number;
+}
+
+interface HeadingLocation {
+  level: number;
+  text: string;
+  line: number;
+  inferred: boolean;
+}
+
+interface HeadingCollection {
+  locations: HeadingLocation[];
+  total: number;
+}
+
+interface ParsedAtxHeading {
+  level: number;
+  text: string;
+}
+
+interface MarkdownFence {
+  character: string;
+  length: number;
+}
+
+function updateFence(line: string, fence: MarkdownFence | undefined): MarkdownFence | undefined {
+  const match = FENCE.exec(line);
+  if (!match) return fence;
+  const marker = match[1];
+  if (!fence) return { character: marker[0], length: marker.length };
+  const closes =
+    marker[0] === fence.character &&
+    marker.length >= fence.length &&
+    !line.slice(match[0].length).trim();
+  return closes ? undefined : fence;
+}
+
+/**
+ * Checks if a character is a space or tab.
+ *
+ * @param character - The character to check
+ * @returns `true` if the character is a space or tab
+ */
+function isSpaceOrTab(character: string | undefined): boolean {
+  return character === " " || character === "\t";
+}
+
+/** Parses the bounded ATX prefix with a linear scan to avoid backtracking on remote input. */
+function parseAtxHeading(line: string): ParsedAtxHeading | undefined {
+  let index = 0;
+  while (index < 3 && isSpaceOrTab(line[index])) index += 1;
+  if (isSpaceOrTab(line[index])) return undefined;
+
+  const markerStart = index;
+  while (line[index] === "#") index += 1;
+  const level = index - markerStart;
+  if (level < 1 || level > 6 || !isSpaceOrTab(line[index])) return undefined;
+
+  while (isSpaceOrTab(line[index])) index += 1;
+  return { level, text: line.slice(index) };
+}
+
+/**
+ * Counts the number of whitespace-separated words in a string.
+ *
+ * @param value - The string to count words in
+ * @returns The number of words, or 0 if the string is empty after trimming
+ */
+function countWords(value: string): number {
+  const trimmed = value.trim();
+  return trimmed ? trimmed.split(/\s+/).length : 0;
+}
+
+/**
+ * Counts the total words in a document while respecting fenced code blocks.
+ *
+ * @param lines - The document lines to count words in
+ * @returns The total word count across all lines, including fenced content
+ */
+function countDocumentWords(lines: string[]): number {
+  let fence: MarkdownFence | undefined;
+  return lines.reduce((total, line) => {
+    const wasInsideFence = Boolean(fence);
+    fence = updateFence(line, fence);
+    const heading = wasInsideFence || fence ? undefined : parseAtxHeading(line);
+    return total + countWords(heading ? cleanHeading(heading.text) : line);
+  }, 0);
+}
+
+/**
+ * Removes trailing whitespace and optional closing markers from heading text, then bounds the result.
+ *
+ * @param value - The raw heading text to clean
+ * @returns The cleaned and bounded heading text
+ */
+function cleanHeading(value: string): string {
+  let contentEnd = value.length;
+  while (contentEnd > 0 && isSpaceOrTab(value[contentEnd - 1])) contentEnd -= 1;
+
+  let markerStart = contentEnd;
+  while (markerStart > 0 && value[markerStart - 1] === "#") markerStart -= 1;
+  if (markerStart < contentEnd && markerStart > 0 && isSpaceOrTab(value[markerStart - 1])) {
+    contentEnd = markerStart - 1;
+    while (contentEnd > 0 && isSpaceOrTab(value[contentEnd - 1])) contentEnd -= 1;
+  }
+
+  return value.slice(0, contentEnd).trim().slice(0, MAX_OUTLINE_HEADING_CHARACTERS);
+}
+
+/**
+ * Collects ATX headings from Markdown lines while respecting fenced code blocks.
+ *
+ * @param lines - The document lines to scan for ATX headings
+ * @returns Collection of heading locations and total heading count
+ */
+function collectAtxHeadings(lines: string[]): HeadingCollection {
+  const locations: HeadingLocation[] = [];
+  let total = 0;
+  let fence: MarkdownFence | undefined;
+
+  for (const [lineNumber, line] of lines.entries()) {
+    const wasInsideFence = Boolean(fence);
+    fence = updateFence(line, fence);
+    if (wasInsideFence || fence) continue;
+    const heading = parseAtxHeading(line);
+    if (!heading) continue;
+    const text = cleanHeading(heading.text);
+    if (!text) continue;
+    total += 1;
+    if (locations.length <= MAX_OUTLINE_HEADINGS) {
+      locations.push({ level: heading.level, text, line: lineNumber, inferred: false });
+    }
+  }
+  return { locations, total };
+}
+
+/**
+ * Heuristically determines if a line looks like a heading when ATX headings are unavailable.
+ *
+ * @param line - The current line to evaluate
+ * @param nextLine - The following non-empty line for context
+ * @returns `true` if the line appears to be a heading
+ */
+function looksLikeFallbackHeading(line: string, nextLine: string): boolean {
+  if (/^\s{4,}/.test(line)) return false;
+  const candidate = line.trim();
+  if (
+    !candidate ||
+    candidate.length > MAX_FALLBACK_HEADING_CHARACTERS ||
+    !/[A-Za-z]/.test(candidate) ||
+    /[.!?…,;:]$/.test(candidate) ||
+    /[,;]/.test(candidate) ||
+    /^([-*+]|\d+\.)\s/.test(candidate) ||
+    /^(>|\||https?:\/\/)/i.test(candidate)
+  ) {
+    return false;
+  }
+  if (!/^[A-Z]/.test(candidate) && !/[`()._]/.test(candidate)) return false;
+  const following = nextLine.trim();
+  return following.length > MAX_FALLBACK_HEADING_CHARACTERS || /[.!?]$/.test(following);
+}
+
+/**
+ * Collects inferred headings using heuristics when no ATX headings are present.
+ *
+ * @param lines - The document lines to scan for heading-like content
+ * @returns Collection of inferred heading locations and total count
+ */
+function collectFallbackHeadings(lines: string[]): HeadingCollection {
+  const locations: HeadingLocation[] = [];
+  let total = 0;
+  const nextNonEmptyIndexes = new Int32Array(lines.length);
+  nextNonEmptyIndexes.fill(-1);
+  let nextNonEmptyIndex = -1;
+  for (let lineNumber = lines.length - 1; lineNumber >= 0; lineNumber -= 1) {
+    nextNonEmptyIndexes[lineNumber] = nextNonEmptyIndex;
+    if (lines[lineNumber].trim()) nextNonEmptyIndex = lineNumber;
+  }
+  let fence: MarkdownFence | undefined;
+
+  for (const [lineNumber, line] of lines.entries()) {
+    const wasInsideFence = Boolean(fence);
+    fence = updateFence(line, fence);
+    if (wasInsideFence || fence) continue;
+    const followingIndex = nextNonEmptyIndexes[lineNumber];
+    const following = followingIndex === -1 ? "" : lines[followingIndex];
+    if (looksLikeFallbackHeading(line, following)) {
+      total += 1;
+      if (locations.length <= MAX_OUTLINE_HEADINGS) {
+        locations.push({ level: 2, text: cleanHeading(line), line: lineNumber, inferred: true });
+      }
+    }
+  }
+  return { locations, total };
+}
+
+/**
+ * Builds a bounded, fence-aware outline from complete extracted Markdown.
+ *
+ * ATX headings are preferred. Only documents with no ATX headings use conservative plain-text
+ * heading inference. Heading text is remote, untrusted metadata and is bounded before exposure.
+ */
+export function createDocumentOutline(markdown: string): DocumentOutline {
+  const lines = markdown.split("\n");
+  const explicit = collectAtxHeadings(lines);
+  const collection = explicit.total > 0 ? explicit : collectFallbackHeadings(lines);
+  const headings = collection.locations.slice(0, MAX_OUTLINE_HEADINGS).map((heading, index) => {
+    const next = collection.locations[index + 1]?.line ?? lines.length;
+    return {
+      level: heading.level,
+      text: heading.text,
+      words: countWords(lines.slice(heading.line + 1, next).join("\n")),
+      inferred: heading.inferred,
+    };
+  });
+  return {
+    totalWords: countDocumentWords(lines),
+    totalHeadings: collection.total,
+    headings,
+    omittedHeadings: Math.max(0, collection.total - headings.length),
+  };
+}