@taurgis/bonsai 3.2.0 → 4.0.0

package/dist/sites/salesforce-developer/route-markdown.js

@@ -1,6 +1,5 @@
 import { fetchText } from '../../lib/research/fetcher.js';
-import { validateTextArtifact } from '../../lib/research/docs/validate.js';
-import { extractFromSource } from '../../lib/research/docs/markdown-source.js';
+import { probeMarkdownTwin } from '../markdown-twin.js';
 // developer.salesforce.com now publishes a Markdown twin for supported doc articles (the
 // "View as Markdown" link): /docs/<cloud>/<book>/guide/<article>[.html] also serves
 // <article>.md with Content-Type text/markdown. The URL mapping is deterministic, so we derive
@@ -9,10 +8,9 @@ import { extractFromSource } from '../../lib/research/docs/markdown-source.js';
 //
 // Coverage is rolling out per doc set, so the probe result is only a candidate (T-19/T-24):
 // unsupported articles 404, and atlas.* books answer the .md route with an HTTP 200 HTML SPA
-// shell — which makes the strict content-type + body validation below load-bearing, not
-// defensive garnish.
+// shell — which makes the strict content-type + body validation in probeMarkdownTwin
+// load-bearing, not defensive garnish.
 const DEVELOPER_HOST = 'developer.salesforce.com';
-const MARKDOWN_CONTENT_TYPE = 'text/markdown';
 // Salesforce's WAF answers 403 unless the User-Agent LEADS with a recognized HTTP-tool token
 // (curl/wget/python-requests pass; bare product names and browser UAs on a non-browser TLS stack
 // are blocked). Lead with the compatibility token — the same convention as browsers' Mozilla/5.0
@@ -24,6 +22,9 @@ const PROBE_HEADERS = {
  * Derives the candidate `.md` route for a developer.salesforce.com doc URL, or null when the URL
  * can't serve one (wrong host, not under /docs/, or an atlas.* book — verified to answer `.md`
  * with an HTML shell, never Markdown). Query/hash are view state and are dropped.
+ *
+ * @param url - A developer.salesforce.com doc URL (or any URL; non-matching returns null).
+ * @returns The derived `.md` URL, or null when no `.md` route exists for this URL.
  */
 export function deriveMarkdownUrl(url) {
     let parsed;
@@ -46,7 +47,11 @@ export function deriveMarkdownUrl(url) {
 // `::include{src="../../shared/….md"}` directives reference build-time snippet files that are
 // not published on the .md route (they 404), so they'd survive as inert noise in the artifact.
 const INCLUDE_DIRECTIVE = /^\s*::include\{[^}]*\}\s*$/;
-/** Removes unresolvable `::include{…}` directive lines, reporting how many were dropped. */
+/** Removes unresolvable `::include{…}` directive lines, reporting how many were dropped.
+ *
+ * @param md - Markdown body from the `.md` route response.
+ * @returns Cleaned body string and a count of removed directive lines.
+ */
 export function stripIncludeDirectives(md) {
     let dropped = 0;
     const body = md
@@ -68,75 +73,32 @@ export function stripIncludeDirectives(md) {
         .join('');
     return { body, dropped };
 }
-// A probe response counts as the Markdown twin only when the server labels it text/markdown AND
-// the redirect chain ended on https at the developer host AND the body validates as non-HTML,
-// non-error text. Atlas shells fail the content-type check; non-2xx statuses already threw in
-// the fetcher (the probe sends no conditional headers, so a 304 can't occur either).
-function isMarkdownResponse(res) {
-    if (!res.content)
-        return false;
-    const mediaType = (res.contentType?.split(';')[0] ?? '').trim().toLowerCase();
-    if (mediaType !== MARKDOWN_CONTENT_TYPE)
-        return false;
-    let finalUrl;
-    try {
-        finalUrl = new URL(res.finalUrl);
-    }
-    catch {
-        return false;
-    }
-    // Scheme matters, not just host: a redirect hop downgrading to plain http would let an on-path
-    // response be cached as the trusted twin.
-    if (finalUrl.protocol !== 'https:' || finalUrl.hostname.toLowerCase() !== DEVELOPER_HOST) {
-        return false;
-    }
-    return validateTextArtifact(res.content).ok;
+function stripIncludesForTwin(raw) {
+    const { body, dropped } = stripIncludeDirectives(raw);
+    if (dropped === 0)
+        return { body };
+    return {
+        body,
+        qualityNote: `${dropped} ::include directive(s) removed (shared snippets are not published on the .md route)`,
+    };
 }
-// A real twin is a small static file that answers fast; anything slower should mean "no twin,
-// fall back now" instead of stacking the fetcher's default 10s on top of the browser render.
-const PROBE_TIMEOUT_MS = 4_000;
-// The browser path refuses to cache captures under this floor (MIN_CONTAINER_CHARS); a twin that
-// thin is a rollout stub, and falling back gives the rendered page a chance to do better.
-const MIN_TWIN_CHARS = 100;
 /**
  * Probes the derived `.md` route for a developer doc URL. Returns a complete SiteFetchResult
  * (with route_markdown provenance) when the twin validates, or null so the caller falls back to
  * the browser capture. Never throws: any network/validation failure is just "no twin".
+ *
+ * @param url - The developer.salesforce.com doc page URL to probe.
+ * @param fetcher - HTTP fetcher (injectable for tests; defaults to `fetchText`).
+ * @returns SiteFetchResult with route_markdown provenance, or null when no valid twin is found.
  */
 export async function fetchDeveloperRouteMarkdown(url, fetcher = fetchText) {
     const candidate = deriveMarkdownUrl(url);
     if (!candidate)
         return null;
-    let res;
-    try {
-        res = await fetcher(candidate, { headers: PROBE_HEADERS, timeoutMs: PROBE_TIMEOUT_MS });
-    }
-    catch {
-        return null;
-    }
-    if (!isMarkdownResponse(res))
-        return null;
-    const { body, dropped } = stripIncludeDirectives(res.content);
-    const extraction = extractFromSource(body, res.finalUrl);
-    if (extraction.detailedMarkdown.length < MIN_TWIN_CHARS)
-        return null;
-    if (dropped > 0) {
-        extraction.qualityNotes = [
-            ...(extraction.qualityNotes ?? []),
-            `${dropped} ::include directive(s) removed (shared snippets are not published on the .md route)`,
-        ];
-    }
-    return {
-        fetchResult: {
-            contentType: res.contentType,
-            etag: res.etag,
-            lastModified: res.lastModified,
-            finalUrl: res.finalUrl,
-            responseSize: res.responseSize,
-            content: res.content,
-        },
-        extraction,
-        captureMethod: 'route_markdown',
-        sourceDocUrl: res.finalUrl,
-    };
+    return probeMarkdownTwin([candidate], {
+        allowedHost: DEVELOPER_HOST,
+        fetcher,
+        headers: PROBE_HEADERS,
+        transformBody: stripIncludesForTwin,
+    });
 }

package/dist/sites/salesforce-doc-fetch.d.ts

@@ -1,25 +1,59 @@
 import type { SiteFetchResult } from './types.js';
-/** True when the extracted text is an error/not-found/loading shell rather than real content. */
+/** True when the extracted text is an error/not-found/loading shell rather than real content.
+ *
+ * @param text - Extracted Markdown text to check.
+ * @returns True when the text matches a Salesforce error/not-found pattern.
+ */
 export declare function looksLikeSalesforceError(text: string): boolean;
+/**
+ * Removes known boilerplate lines from converted Salesforce Markdown: the feedback widget text,
+ * "View as Markdown" toolbar labels, and empty icon-anchor lines.
+ *
+ * @param markdown - Markdown output from the DOM or content API conversion.
+ * @returns Markdown with boilerplate lines stripped and excess blank lines collapsed.
+ */
 export declare function stripBoilerplate(markdown: string): string;
-/** Parses the Salesforce private content API JSON payload. */
+/** Parses the Salesforce private content API JSON payload.
+ *
+ * @param raw - Raw JSON string from the `/docs/get_document_content/` network response.
+ * @returns Parsed `{ content, title }` object, or null when the body is empty or unparseable.
+ */
 export declare function parseDocsApiPayload(raw: string): {
     content: string;
     title: string;
 } | null;
-/** Keeps whichever Markdown source carries more structural content (DOM vs content API HTML). */
+/** Keeps whichever Markdown source carries more structural content (DOM vs content API HTML).
+ *
+ * @param domMarkdown - Markdown serialized from the shadow-DOM container.
+ * @param apiHtml - Raw HTML body from the Salesforce content API.
+ * @param domTitle - Page title from the DOM capture.
+ * @param apiTitle - Title from the content API response.
+ * @returns The richer Markdown, the winning title, and a flag indicating whether the API source won.
+ */
 export declare function preferRicherMarkdown(domMarkdown: string, apiHtml: string, domTitle: string, apiTitle: string): {
     markdown: string;
     title: string;
     usedApi: boolean;
 };
+/**
+ * Options for the shared Salesforce Lightning Web Runtime (LWR) shadow-DOM fetcher.
+ * `contentSelectors` drive the priority content-container pick; `removeSelectors` strips
+ * per-site chrome that survives the shared BASE_REMOVE_SELECTORS list.
+ */
 export interface SalesforceDocOptions {
     allowedHost: string;
     contentSelectors: string[];
     removeSelectors?: string[];
 }
 /**
- * Renders a Salesforce LWR doc page, serializes its shadow-DOM content container, and converts
- * it to Markdown. Validates the host before any network access.
+ * Renders a Salesforce Lightning Web Runtime (LWR) doc page, serializes its shadow-DOM content
+ * container, and converts it to Markdown. Validates the host before any network access.
+ *
+ * @param url - The Salesforce doc page URL to fetch.
+ * @param options - Allowed host, priority content selectors, and optional per-site remove selectors.
+ * @returns Extracted Markdown, fetch metadata, and browser-capture provenance.
+ * @throws {Error} When the URL is invalid, the host is not the allowed host, DNS is unsafe,
+ *   Chrome/CDP navigation or evaluation fails, the response body exceeds the size limit,
+ *   or the captured content is too short / looks like an error page.
  */
 export declare function fetchSalesforceDoc(url: string, { allowedHost, contentSelectors, removeSelectors }: SalesforceDocOptions): Promise<SiteFetchResult>;

package/dist/sites/salesforce-doc-fetch.js

@@ -1,6 +1,7 @@
 import { openCdpPage, waitForLoad, ResponseCapture, describeNavigationFailure, } from '../lib/research/browser.js';
 import { checkDnsSafety } from '../lib/research/fetcher.js';
 import { htmlToMarkdown } from '../lib/research/markdown.js';
+import { sanitizePromptInjection } from '../lib/research/prompt-injection.js';
 import { contentMetrics, contentRicherThan } from '../lib/research/regression.js';
 import { SALESFORCE_SHADOW_DOM_HELPERS, buildPriorityContainerPickBlock, pollSalesforceContentReady, } from './salesforce-dom-probe.js';
 // Both help.salesforce.com and developer.salesforce.com are LWR sites that render doc content
@@ -24,7 +25,11 @@ const ERROR_PATTERNS = [
     /we looked high and low/i,
     /sorry to interrupt/i,
 ];
-/** True when the extracted text is an error/not-found/loading shell rather than real content. */
+/** True when the extracted text is an error/not-found/loading shell rather than real content.
+ *
+ * @param text - Extracted Markdown text to check.
+ * @returns True when the text matches a Salesforce error/not-found pattern.
+ */
 export function looksLikeSalesforceError(text) {
     return ERROR_PATTERNS.some((re) => re.test(text));
 }
@@ -71,6 +76,13 @@ const MARKDOWN_TOOLBAR_LINE = /^(copy as markdown|view as markdown|copy url to m
 // A link with empty anchor text — e.g. an icon-only "home" logo link. It carries no readable
 // content and renders as a bare `[](url)`. (Images `![](url)` are intentionally not matched.)
 const EMPTY_LINK_LINE = /^\[\]\([^)]*\)$/;
+/**
+ * Removes known boilerplate lines from converted Salesforce Markdown: the feedback widget text,
+ * "View as Markdown" toolbar labels, and empty icon-anchor lines.
+ *
+ * @param markdown - Markdown output from the DOM or content API conversion.
+ * @returns Markdown with boilerplate lines stripped and excess blank lines collapsed.
+ */
 export function stripBoilerplate(markdown) {
     return markdown
         .split('\n')
@@ -82,7 +94,11 @@ export function stripBoilerplate(markdown) {
         .trim();
 }
 const DOCS_CONTENT_API = '/docs/get_document_content/';
-/** Parses the Salesforce private content API JSON payload. */
+/** Parses the Salesforce private content API JSON payload.
+ *
+ * @param raw - Raw JSON string from the `/docs/get_document_content/` network response.
+ * @returns Parsed `{ content, title }` object, or null when the body is empty or unparseable.
+ */
 export function parseDocsApiPayload(raw) {
     if (!raw?.trim())
         return null;
@@ -96,7 +112,14 @@ export function parseDocsApiPayload(raw) {
         return null;
     }
 }
-/** Keeps whichever Markdown source carries more structural content (DOM vs content API HTML). */
+/** Keeps whichever Markdown source carries more structural content (DOM vs content API HTML).
+ *
+ * @param domMarkdown - Markdown serialized from the shadow-DOM container.
+ * @param apiHtml - Raw HTML body from the Salesforce content API.
+ * @param domTitle - Page title from the DOM capture.
+ * @param apiTitle - Title from the content API response.
+ * @returns The richer Markdown, the winning title, and a flag indicating whether the API source won.
+ */
 export function preferRicherMarkdown(domMarkdown, apiHtml, domTitle, apiTitle) {
     const apiMarkdown = stripBoilerplate(htmlToMarkdown(apiHtml));
     if (contentRicherThan(contentMetrics(apiMarkdown), contentMetrics(domMarkdown))) {
@@ -295,10 +318,22 @@ async function captureSalesforceAttempt(page, url, captureScript, contentSelecto
     // as if it were real article content — it's plausible-length HTML that isn't a 404/loading shell — so
     // the fetch would silently "succeed" with Chrome's error page cached as the documentation.
     const nav = await page.client.send('Page.navigate', { url }, page.sessionId);
+    // A fast redirect can fail synchronously within Page.navigate's own response (surfacing as
+    // nav.errorText below); check the Fetch-domain safety guard first so a blocked navigation (e.g.
+    // an SSRF attempt via a private-address redirect) reports its specific reason instead of the
+    // opaque net::ERR_BLOCKED_BY_CLIENT that Chrome's own errorText would otherwise give it.
+    const blockedNavigation = page.takeBlockedNavigationError();
+    if (blockedNavigation)
+        throw blockedNavigation;
     if (nav.errorText) {
         throw describeNavigationFailure(nav.errorText, url);
     }
     await waitForLoad(page.client, page.sessionId, TIMEOUT_MS, 0).catch(() => { });
+    // A mid-navigation redirect may have been blocked after Page.navigate returned; surface that
+    // instead of letting Chrome's resulting error page sail through as captured content.
+    const blockedNavigationAfterLoad = page.takeBlockedNavigationError();
+    if (blockedNavigationAfterLoad)
+        throw blockedNavigationAfterLoad;
     await page.client
         .send('Runtime.evaluate', { expression: ACCEPT_CONSENT_EXPRESSION }, page.sessionId)
         .catch(() => { });
@@ -327,6 +362,9 @@ async function captureSalesforceAttempt(page, url, captureScript, contentSelecto
     return { html, title, detailedMarkdown, usedDocsApi };
 }
 function buildSalesforceFetchResult(url, html, title, detailedMarkdown, qualityNotes) {
+    // Same untrusted-HTML → Markdown path as extractHtmlContent: sanitize before the artifact
+    // is built so site-module browser captures cannot skip the shared prompt-injection guard.
+    const sanitizedMarkdown = sanitizePromptInjection(detailedMarkdown);
     return {
         fetchResult: {
             contentType: 'text/html',
@@ -338,8 +376,8 @@ function buildSalesforceFetchResult(url, html, title, detailedMarkdown, qualityN
         },
         extraction: {
             title: title || url,
-            detailedMarkdown,
-            confidence: confidenceFor(detailedMarkdown.length),
+            detailedMarkdown: sanitizedMarkdown,
+            confidence: confidenceFor(sanitizedMarkdown.length),
             qualityNotes,
         },
         // Rendered capture is this fetcher's only strategy; reporting it lets a refresh overwrite
@@ -348,8 +386,15 @@ function buildSalesforceFetchResult(url, html, title, detailedMarkdown, qualityN
     };
 }
 /**
- * Renders a Salesforce LWR doc page, serializes its shadow-DOM content container, and converts
- * it to Markdown. Validates the host before any network access.
+ * Renders a Salesforce Lightning Web Runtime (LWR) doc page, serializes its shadow-DOM content
+ * container, and converts it to Markdown. Validates the host before any network access.
+ *
+ * @param url - The Salesforce doc page URL to fetch.
+ * @param options - Allowed host, priority content selectors, and optional per-site remove selectors.
+ * @returns Extracted Markdown, fetch metadata, and browser-capture provenance.
+ * @throws {Error} When the URL is invalid, the host is not the allowed host, DNS is unsafe,
+ *   Chrome/CDP navigation or evaluation fails, the response body exceeds the size limit,
+ *   or the captured content is too short / looks like an error page.
  */
 export async function fetchSalesforceDoc(url, { allowedHost, contentSelectors, removeSelectors = [] }) {
     const parsed = parseSalesforceDocUrl(url, allowedHost);

package/dist/sites/salesforce-dom-probe.d.ts

@@ -1,16 +1,34 @@
 import type { CdpPage } from '../lib/research/browser.js';
-/** Shared in-page helpers for traversing Salesforce LWR open shadow roots. */
+/** Shared in-page helpers for traversing Salesforce Lightning Web Runtime (LWR) open shadow roots. */
 export declare const SALESFORCE_SHADOW_DOM_HELPERS = "\nconst deepElements = (root) => {\n  const out = [];\n  const visit = (node) => {\n    if (node.shadowRoot) visit(node.shadowRoot);\n    for (const child of Array.from(node.children || [])) {\n      out.push(child);\n      visit(child);\n    }\n  };\n  visit(root);\n  return out;\n};\n\nconst deepText = (root) => {\n  let txt = '';\n  const visit = (node) => {\n    if (node.nodeType === 3) {\n      txt += node.textContent || '';\n    } else if (node.nodeType === 1 || node.nodeType === 9 || node.nodeType === 11) {\n      const tag = node.tagName ? node.tagName.toLowerCase() : '';\n      if (tag !== 'style' && tag !== 'script') {\n        if (node.shadowRoot) visit(node.shadowRoot);\n        for (const child of Array.from(node.childNodes || [])) visit(child);\n      }\n    }\n  };\n  visit(root);\n  return txt;\n};\n\nconst textLenFor = (el) =>\n  Math.max((el.innerText || '').trim().length, deepText(el).trim().length);\n";
 /**
  * In-page block: pick the highest-priority content container that exists on the page.
  * Does not fall through to lower-priority selectors when a higher-priority host is present
  * (e.g. doc-content-layout banner vs doc-amf-reference table).
+ *
+ * @param selectors - CSS selectors in priority order; the first that matches wins.
+ * @param minChars - Minimum text length a matched container must have to be accepted.
+ * @param containerVar - Name of the JS variable to assign the result to (default `'container'`).
+ * @returns A JavaScript code block string (without the surrounding `(() => {…})()` wrapper).
  */
 export declare function buildPriorityContainerPickBlock(selectors: string[], minChars: number, containerVar?: string): string;
-/** CDP expression polled until the priority content host reaches minChars and the body settles. */
+/**
+ * Chrome DevTools Protocol (CDP) expression polled until the priority content host reaches
+ * `minChars` and the body settles.
+ *
+ * @param selectors - CSS selectors in priority order matching the site's content containers.
+ * @param minChars - Minimum text length before the container is considered ready.
+ * @returns A self-invoking JS expression string that evaluates to `{ has: boolean, len: number }`.
+ */
 export declare function buildContentReadyProbeExpression(selectors: string[], minChars: number): string;
 /**
  * Polls until the priority Salesforce content host is ready and body text has settled.
  * Returns without throwing on timeout; the caller captures whatever rendered and judges quality.
+ *
+ * @param page - Open Chrome DevTools Protocol (CDP) page to evaluate expressions on.
+ * @param selectors - CSS selectors in priority order matching the site's content containers.
+ * @param minChars - Minimum container text length before polling stops.
+ * @param timeoutMs - Maximum wall-clock time (ms) to wait before giving up.
+ * @returns Resolves when content is ready, or when `timeoutMs` elapses (no throw on timeout).
  */
 export declare function pollSalesforceContentReady(page: CdpPage, selectors: string[], minChars: number, timeoutMs: number): Promise<void>;

package/dist/sites/salesforce-dom-probe.js

@@ -1,4 +1,4 @@
-/** Shared in-page helpers for traversing Salesforce LWR open shadow roots. */
+/** Shared in-page helpers for traversing Salesforce Lightning Web Runtime (LWR) open shadow roots. */
 export const SALESFORCE_SHADOW_DOM_HELPERS = `
 const deepElements = (root) => {
   const out = [];
@@ -37,6 +37,11 @@ const textLenFor = (el) =>
  * In-page block: pick the highest-priority content container that exists on the page.
  * Does not fall through to lower-priority selectors when a higher-priority host is present
  * (e.g. doc-content-layout banner vs doc-amf-reference table).
+ *
+ * @param selectors - CSS selectors in priority order; the first that matches wins.
+ * @param minChars - Minimum text length a matched container must have to be accepted.
+ * @param containerVar - Name of the JS variable to assign the result to (default `'container'`).
+ * @returns A JavaScript code block string (without the surrounding `(() => {…})()` wrapper).
  */
 export function buildPriorityContainerPickBlock(selectors, minChars, containerVar = 'container') {
     return `
@@ -61,7 +66,14 @@ export function buildPriorityContainerPickBlock(selectors, minChars, containerVa
     ${containerVar} = ${containerVar} || document.body || document.documentElement;
   `;
 }
-/** CDP expression polled until the priority content host reaches minChars and the body settles. */
+/**
+ * Chrome DevTools Protocol (CDP) expression polled until the priority content host reaches
+ * `minChars` and the body settles.
+ *
+ * @param selectors - CSS selectors in priority order matching the site's content containers.
+ * @param minChars - Minimum text length before the container is considered ready.
+ * @returns A self-invoking JS expression string that evaluates to `{ has: boolean, len: number }`.
+ */
 export function buildContentReadyProbeExpression(selectors, minChars) {
     return `(() => {
     ${SALESFORCE_SHADOW_DOM_HELPERS}
@@ -90,6 +102,12 @@ export function buildContentReadyProbeExpression(selectors, minChars) {
 /**
  * Polls until the priority Salesforce content host is ready and body text has settled.
  * Returns without throwing on timeout; the caller captures whatever rendered and judges quality.
+ *
+ * @param page - Open Chrome DevTools Protocol (CDP) page to evaluate expressions on.
+ * @param selectors - CSS selectors in priority order matching the site's content containers.
+ * @param minChars - Minimum container text length before polling stops.
+ * @param timeoutMs - Maximum wall-clock time (ms) to wait before giving up.
+ * @returns Resolves when content is ready, or when `timeoutMs` elapses (no throw on timeout).
  */
 export async function pollSalesforceContentReady(page, selectors, minChars, timeoutMs) {
     const expression = buildContentReadyProbeExpression(selectors, minChars);

package/dist/sites/types.d.ts

@@ -1,14 +1,13 @@
 import type { ExtractionResult } from '../lib/research/extract.js';
+import type { FetchedContent } from '../lib/research/fetcher.js';
 import type { CaptureMethod } from '../lib/research/schema.js';
+/**
+ * Result returned by a site module's custom `fetchPage` implementation.
+ * Carries the raw fetch metadata, the extracted Markdown, and optional provenance fields
+ * (`captureMethod`, `sourceDocUrl`) so the cache pipeline can record how the content was obtained.
+ */
 export interface SiteFetchResult {
-    fetchResult: {
-        contentType: string | null;
-        etag: string | null;
-        lastModified: string | null;
-        finalUrl: string;
-        responseSize: number;
-        content: string;
-    };
+    fetchResult: FetchedContent;
     extraction: ExtractionResult;
     captureMethod?: CaptureMethod;
     sourceDocUrl?: string;
@@ -17,12 +16,19 @@ export interface SiteFetchResult {
  * Stamps a site module's reported provenance onto artifact metadata. Shared by the cache-miss
  * fetch and revalidation so the two write paths can't drift. A result without captureMethod (a
  * module predating provenance reporting) leaves the metadata untouched.
+ *
+ * @param metadata - Artifact metadata fields updated in place.
+ * @param siteFetch - Site-module fetch result carrying optional provenance.
  */
 export declare function applySiteFetchProvenance(metadata: {
     capture_method: CaptureMethod | null;
     source_doc_url: string | null;
     source_urls: string[];
 }, siteFetch: SiteFetchResult): void;
+/** Registered site-specific fetch/extract strategy for a domain family.
+ * `defaults.rendered` ORs with the user's `--rendered` flag; a missing or false value is a safe default.
+ * When `fetchPage` is absent, callers use the generic fetch/extract pipeline.
+ */
 export interface SiteModule {
     id: string;
     name: string;

package/dist/sites/types.js

@@ -2,6 +2,9 @@
  * Stamps a site module's reported provenance onto artifact metadata. Shared by the cache-miss
  * fetch and revalidation so the two write paths can't drift. A result without captureMethod (a
  * module predating provenance reporting) leaves the metadata untouched.
+ *
+ * @param metadata - Artifact metadata fields updated in place.
+ * @param siteFetch - Site-module fetch result carrying optional provenance.
  */
 export function applySiteFetchProvenance(metadata, siteFetch) {
     if (!siteFetch.captureMethod)