@taurgis/bonsai 3.1.0 → 3.2.2

package/dist/sites/salesforce/help-tooling-markdown.js

@@ -0,0 +1,74 @@
+import { fetchText } from '../../lib/research/fetcher.js';
+import { probeMarkdownTwin } from '../markdown-twin.js';
+// Salesforce's official "B2C Developer Tooling" project (GA, SalesforceCommerceCloud org) mirrors
+// a curated subset of help.salesforce.com's B2C Commerce articles as static Markdown for its own
+// CLI/MCP `docs` tool: /help/<category>/<slug>.md on its GitHub Pages site. Two categories cover
+// admin- and merchant-facing content. Fetching that twin replaces Help's ~45s shadow-DOM render
+// with one static request — the same win developer.salesforce.com's route.md twin gives us.
+//
+// Unlike the developer.salesforce.com twin, the mirror lives on a DIFFERENT host than the article
+// (help.salesforce.com -> salesforcecommercecloud.github.io), and there is no public index mapping
+// a help.salesforce.com article to its slug/category: the mapping ships inside the b2c-developer-
+// tooling CLI's bundled package, not as a fetchable file. But B2C Commerce Help articles' `id` query
+// param follows a stable `cc.<slug>.htm` pattern that matches the mirror's slug exactly (verified
+// against several live articles spanning both categories), so the slug is derivable from the URL;
+// which of the two categories holds it is not, so both are probed (see probeMarkdownTwin).
+const HELP_HOST = 'help.salesforce.com';
+const TOOLING_HOST = 'salesforcecommercecloud.github.io';
+const TOOLING_HELP_BASE = `https://${TOOLING_HOST}/b2c-developer-tooling/help`;
+// Order doesn't reflect prevalence, just the two categories b2c-developer-tooling publishes.
+const HELP_TOOLING_CATEGORIES = ['help-admin', 'help-merchant'];
+// Every real B2C Commerce Help slug is lowercase word characters/underscores (e.g.
+// b2c_inventory_list_object_import_export); restricting the capture group to that charset (rather
+// than `.+`) keeps a crafted `id` query param from steering the mirror probe at an arbitrary path
+// on the trusted host.
+const HELP_ARTICLE_ID_PATTERN = /^cc\.([\w-]+)\.htm$/i;
+/**
+ * Extracts the b2c-developer-tooling slug from a help.salesforce.com article URL, or null when the
+ * URL isn't a `cc.<slug>.htm` B2C Commerce Help article (wrong host, missing `id`, or an `id` that
+ * doesn't follow that pattern — e.g. numeric knowledge-article ids, or other clouds' Help content).
+ *
+ * @param url - A help.salesforce.com article URL (or any URL; non-matching returns null).
+ * @returns The derived slug (e.g. `b2c_inventory_list_object_import_export`), or null.
+ */
+export function deriveHelpToolingSlug(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.hostname.toLowerCase() !== HELP_HOST)
+        return null;
+    const id = parsed.searchParams.get('id');
+    if (!id)
+        return null;
+    return HELP_ARTICLE_ID_PATTERN.exec(id)?.[1] ?? null;
+}
+/**
+ * Builds the candidate mirror URLs for a slug, one per known category. Category membership isn't
+ * derivable from the URL, so callers must probe each until one validates.
+ *
+ * @param slug - Slug derived by {@link deriveHelpToolingSlug}.
+ * @returns Candidate `.md` URLs on the b2c-developer-tooling mirror, one per category.
+ */
+export function candidateHelpToolingUrls(slug) {
+    return HELP_TOOLING_CATEGORIES.map((category) => `${TOOLING_HELP_BASE}/${category}/${slug}.md`);
+}
+/**
+ * Probes the b2c-developer-tooling Markdown mirror for a help.salesforce.com article. Returns a
+ * complete SiteFetchResult (with route_markdown provenance) for the first category whose twin
+ * validates, or null so the caller falls back to the browser capture. Never throws: any
+ * network/validation failure just means "no twin in this category," or "no twin at all."
+ *
+ * @param url - The help.salesforce.com article 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 fetchHelpToolingMarkdown(url, fetcher = fetchText) {
+    const slug = deriveHelpToolingSlug(url);
+    if (!slug)
+        return null;
+    return probeMarkdownTwin(candidateHelpToolingUrls(slug), { allowedHost: TOOLING_HOST, fetcher });
+}

package/dist/sites/salesforce/index.d.ts

@@ -1,2 +1,3 @@
 import type { SiteModule } from '../types.js';
+/** Site module for help.salesforce.com: forces rendered capture and applies the Help-specific Lightning Web Runtime (LWR) fetcher. */
 export declare const salesforce: SiteModule;

package/dist/sites/salesforce/index.js

@@ -2,6 +2,7 @@ import { fetchSalesforcePage } from './fetch-page.js';
 // Scoped to help.salesforce.com — an LWR Experience site with light-DOM article content.
 // developer.salesforce.com is intentionally NOT routed here: its API-reference docs render
 // inside shadow DOM with tabbed/code content that needs a different extraction strategy.
+/** Site module for help.salesforce.com: forces rendered capture and applies the Help-specific Lightning Web Runtime (LWR) fetcher. */
 export const salesforce = {
     id: 'salesforce',
     name: 'Salesforce Help',

package/dist/sites/salesforce-developer/fetch-page.d.ts

@@ -3,6 +3,11 @@ import type { SiteFetchResult } from '../types.js';
  * Fetches a developer.salesforce.com doc page. Supported articles publish a Markdown twin at the
  * derived `.md` route ("View as Markdown"), which is preferred: one static request instead of a
  * browser render, and it returns the article's source. Pages without a validated twin (API
- * reference, atlas.* books, landing pages) fall back to the shared LWR shadow-DOM fetcher.
+ * reference, atlas.* books, landing pages) fall back to the shared Lightning Web Runtime (LWR)
+ * shadow-DOM fetcher.
+ *
+ * @param url - The developer.salesforce.com doc page URL.
+ * @returns Extracted Markdown, fetch metadata, and capture provenance (route_markdown or browser_fallback).
+ * @throws {Error} When the browser fallback path fails (same modes as `fetchSalesforceDoc`).
  */
 export declare function fetchDeveloperPage(url: string): Promise<SiteFetchResult>;

package/dist/sites/salesforce-developer/fetch-page.js

@@ -16,7 +16,12 @@ const CONTENT_SELECTORS = [
  * Fetches a developer.salesforce.com doc page. Supported articles publish a Markdown twin at the
  * derived `.md` route ("View as Markdown"), which is preferred: one static request instead of a
  * browser render, and it returns the article's source. Pages without a validated twin (API
- * reference, atlas.* books, landing pages) fall back to the shared LWR shadow-DOM fetcher.
+ * reference, atlas.* books, landing pages) fall back to the shared Lightning Web Runtime (LWR)
+ * shadow-DOM fetcher.
+ *
+ * @param url - The developer.salesforce.com doc page URL.
+ * @returns Extracted Markdown, fetch metadata, and capture provenance (route_markdown or browser_fallback).
+ * @throws {Error} When the browser fallback path fails (same modes as `fetchSalesforceDoc`).
  */
 export async function fetchDeveloperPage(url) {
     const fromMarkdownRoute = await fetchDeveloperRouteMarkdown(url);

package/dist/sites/salesforce-developer/index.d.ts

@@ -1,2 +1,3 @@
 import type { SiteModule } from '../types.js';
+/** Site module for developer.salesforce.com: forces rendered capture and applies the shadow-DOM Lightning Web Runtime (LWR) fetcher. */
 export declare const salesforceDeveloper: SiteModule;

package/dist/sites/salesforce-developer/index.js

@@ -2,6 +2,7 @@ import { fetchDeveloperPage } from './fetch-page.js';
 // developer.salesforce.com docs (guides + API reference) render client-side inside web
 // components, so content lives in shadow DOM — a fundamentally different extraction strategy
 // than help.salesforce.com (see ../salesforce).
+/** Site module for developer.salesforce.com: forces rendered capture and applies the shadow-DOM Lightning Web Runtime (LWR) fetcher. */
 export const salesforceDeveloper = {
     id: 'salesforce-developer',
     name: 'Salesforce Developer',

package/dist/sites/salesforce-developer/route-markdown.d.ts

@@ -1,23 +1,35 @@
-import { type FetchResult } from '../../lib/research/fetcher.js';
+import { fetchText } from '../../lib/research/fetcher.js';
 import type { SiteFetchResult } from '../types.js';
 /**
  * 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 declare function deriveMarkdownUrl(url: string): string | null;
-/** 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 declare function stripIncludeDirectives(md: string): {
     body: string;
     dropped: number;
 };
-export type RouteMarkdownFetcher = (url: string, options?: {
-    headers?: Record<string, string>;
-    timeoutMs?: number;
-}) => Promise<FetchResult>;
+/**
+ * Injectable HTTP fetcher used by `fetchDeveloperRouteMarkdown`. The default is `fetchText`;
+ * tests inject a fixture fetcher to avoid real network calls.
+ */
+export type RouteMarkdownFetcher = typeof fetchText;
 /**
  * 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 declare function fetchDeveloperRouteMarkdown(url: string, fetcher?: RouteMarkdownFetcher): Promise<SiteFetchResult | null>;

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)