seo 0.6.0 → 0.7.1

package/dist/index.js

@@ -1,5 +1,5 @@
 import { createRequire as __seoCreateRequire } from 'node:module'; const require = __seoCreateRequire(import.meta.url);
-import { n as load, t as version } from "./package-CwLtPH6B.js";
+import { n as load, t as version } from "./package-BaQwwfSG.js";
 import { SEO_PROVIDER_API_VERSION } from "./provider-sdk.js";
 import crypto, { createHash, randomUUID, sign } from "node:crypto";
 import { z } from "zod";
@@ -4694,7 +4694,7 @@ function extractCanonicalEvidence($, headers, baseUrl) {
 //#region packages/core/src/extract/content-sketch.ts
 const SHINGLE_SIZE = 5;
 const MAX_HASHES = 32;
-function words(value) {
+function words$1(value) {
 	return value.normalize("NFKC").toLocaleLowerCase("en").match(/[\p{L}\p{N}]+/gu) ?? [];
 }
 function sampleIndexes(total, limit) {
@@ -4705,7 +4705,7 @@ function digest(value) {
 	return createHash("sha256").update(value).digest("hex").slice(0, 16);
 }
 function contentSketch(value) {
-	const tokens = words(value);
+	const tokens = words$1(value);
 	const hashes = sampleIndexes(Math.max(0, tokens.length - SHINGLE_SIZE + 1), MAX_HASHES).map((index) => digest(tokens.slice(index, index + SHINGLE_SIZE).join(" ")));
 	return {
 		version: 1,
@@ -4717,6 +4717,11 @@ function contentSketch(value) {
 }
 //#endregion
 //#region packages/core/src/extract/main-content.ts
+function parseDocument$1(html) {
+	const { document } = parseHTML(html);
+	if (document.documentElement?.localName === "html") return document;
+	return parseHTML(`<!doctype html><html><head></head><body>${html}</body></html>`).document;
+}
 function readableError(error) {
 	return error instanceof Error ? error.message : String(error);
 }
@@ -4746,10 +4751,6 @@ function resolveDocumentUrls(document, baseUrl) {
 	}
 }
 function readabilityResult(fetchResult, requested, fallbackReason, fallbackDetail) {
-	const { document } = parseHTML(fetchResult.html);
-	const bodyText = document.body.textContent ?? "";
-	const article = new Readability(document).parse();
-	const text = article?.textContent ?? bodyText;
 	const fallback = requested !== "readability";
 	const diagnostics = {
 		requested,
@@ -4762,13 +4763,27 @@ function readabilityResult(fetchResult, requested, fallbackReason, fallbackDetai
 			fallbackDetail
 		} : {}
 	};
-	return {
-		text,
-		excerpt: normalizedText(article?.excerpt),
-		wordCount: countCjkAwareWords(text),
-		diagnostics,
-		warnings: fallback && fallbackDetail ? [`Defuddle extraction fell back to Readability: ${fallbackDetail}`] : []
-	};
+	const warnings = fallback && fallbackDetail ? [`Defuddle extraction fell back to Readability: ${fallbackDetail}`] : [];
+	try {
+		const document = parseDocument$1(fetchResult.html);
+		const bodyText = document.body?.textContent ?? "";
+		const article = new Readability(document).parse();
+		const text = article?.textContent ?? bodyText;
+		return {
+			text,
+			excerpt: normalizedText(article?.excerpt),
+			wordCount: countCjkAwareWords(text),
+			diagnostics,
+			warnings
+		};
+	} catch (error) {
+		return {
+			text: "",
+			wordCount: 0,
+			diagnostics,
+			warnings: [...warnings, `The page's main content could not be read: ${readableError(error)}`]
+		};
+	}
 }
 function defaultParseDefuddle(document, options) {
 	return new Defuddle(document, options).parse();
@@ -4776,13 +4791,13 @@ function defaultParseDefuddle(document, options) {
 function extractMainContent(fetchResult, extractor = "defuddle", dependencies = {}) {
 	if (extractor === "readability") return readabilityResult(fetchResult, extractor);
 	try {
-		const { document } = parseHTML(fetchResult.html);
+		const document = parseDocument$1(fetchResult.html);
 		resolveDocumentUrls(document, fetchResult.finalUrl);
 		const article = (dependencies.parseDefuddle ?? defaultParseDefuddle)(document, {
 			url: fetchResult.finalUrl,
 			useAsync: false
 		});
-		const text = typeof article.content === "string" ? load(article.content).text() : document.body.textContent ?? "";
+		const text = typeof article.content === "string" ? load(article.content).text() : document.body?.textContent ?? "";
 		if (!text.trim()) return readabilityResult(fetchResult, extractor, "defuddle_empty", "Defuddle returned no main content");
 		const reportedWordCount = article.wordCount;
 		const hasValidWordCount = typeof reportedWordCount === "number" && Number.isFinite(reportedWordCount) && reportedWordCount >= 0;
@@ -4805,6 +4820,28 @@ function extractMainContent(fetchResult, extractor = "defuddle", dependencies =
 		return readabilityResult(fetchResult, extractor, "defuddle_error", readableError(error));
 	}
 }
+const MARKDOWN_LIMIT = 2e4;
+async function extractMainMarkdown(fetchResult) {
+	const document = parseDocument$1(fetchResult.html);
+	resolveDocumentUrls(document, fetchResult.finalUrl);
+	const { Defuddle: toMarkdown } = await import("defuddle/node");
+	const markdown = ((await toMarkdown(document, fetchResult.finalUrl, {
+		markdown: true,
+		useAsync: false
+	})).content ?? "").trim();
+	if (markdown.length <= 2e4) return {
+		markdown,
+		characters: markdown.length,
+		truncated: false
+	};
+	const cut = markdown.slice(0, MARKDOWN_LIMIT);
+	const end = cut.lastIndexOf("\n");
+	return {
+		markdown: (end > 2e4 / 2 ? cut.slice(0, end) : cut).trimEnd(),
+		characters: markdown.length,
+		truncated: true
+	};
+}
 //#endregion
 //#region packages/core/src/extract/google-rich-results.ts
 const SUPPORTED_TYPES = /* @__PURE__ */ new Set([
@@ -8639,7 +8676,7 @@ const QUERY_FLAG_METHOD = {
 		"navigational-other": "Names a domain that is not the property's host, ends with a spoken domain suffix or a login/site/app word, starts with a large platform name and adds no topic word, or is one short ASCII word that is not a brand term. Such queries usually look for another site."
 	}
 };
-const FUNCTION_WORDS = /* @__PURE__ */ new Set([
+const FUNCTION_WORDS$1 = /* @__PURE__ */ new Set([
 	"a",
 	"about",
 	"an",
@@ -8704,7 +8741,7 @@ function isLikelyAutomatedQuery(query) {
 	if (query.trim().split(/\s+/).filter(Boolean).some((token) => IDENTIFIER_TOKEN.test(token))) return true;
 	const tokens = tokenize(query);
 	if (tokens.length >= 20) return true;
-	if (tokens.length >= 8 && !/[^\p{ASCII}]/u.test(query) && !tokens.some((token) => FUNCTION_WORDS.has(token))) return true;
+	if (tokens.length >= 8 && !/[^\p{ASCII}]/u.test(query) && !tokens.some((token) => FUNCTION_WORDS$1.has(token))) return true;
 	return false;
 }
 const FILE_EXTENSIONS = /* @__PURE__ */ new Set([
@@ -16682,7 +16719,7 @@ function analyzeCtrUnderperformersFromRows(input) {
 //#endregion
 //#region packages/core/src/analyze/ctr-underperformers-report.ts
 const MAX_GSC_ROWS$3 = 1e5;
-const DEFAULT_DAYS$3 = 28;
+const DEFAULT_DAYS$4 = 28;
 const MAX_DAYS$2 = 548;
 function plural$4(count, singular, pluralLabel = `${singular}s`) {
 	return count === 1 ? singular : pluralLabel;
@@ -16705,7 +16742,7 @@ async function ctrUnderperformersReportWith(input, dependencies) {
 	const explicitRange = explicitDateRange(input, MAX_DAYS$2);
 	const days = explicitRange?.days ?? integerOption$1({
 		value: input.days,
-		fallback: DEFAULT_DAYS$3,
+		fallback: DEFAULT_DAYS$4,
 		minimum: 1,
 		maximum: MAX_DAYS$2,
 		label: "Days"
@@ -19962,7 +19999,7 @@ function quickWinTemplateSummaries(items) {
 }
 //#endregion
 //#region packages/core/src/analyze/site-diagnostics/quick-wins-report.ts
-const DEFAULT_DAYS$2 = 28;
+const DEFAULT_DAYS$3 = 28;
 const MAX_DAYS$1 = 548;
 const DEFAULT_VERIFY_LIMIT$1 = 5;
 const MAX_VERIFY_LIMIT = 100;
@@ -19984,7 +20021,7 @@ async function quickWinsReportWith(input, dependencies) {
 	const explicitRange = explicitDateRange(input, MAX_DAYS$1);
 	const days = explicitRange?.days ?? integerOption$1({
 		value: input.days,
-		fallback: DEFAULT_DAYS$2,
+		fallback: DEFAULT_DAYS$3,
 		minimum: 1,
 		maximum: MAX_DAYS$1,
 		label: "Days"
@@ -20408,7 +20445,7 @@ function analyzeStrikingDistanceRows(input) {
 }
 //#endregion
 //#region packages/core/src/analyze/striking-distance-report.ts
-const DEFAULT_DAYS$1 = 28;
+const DEFAULT_DAYS$2 = 28;
 const MAX_DAYS = 548;
 const DEFAULT_VERIFY_LIMIT = 5;
 const MAX_SOURCE_ROWS$1 = 1e5;
@@ -20417,7 +20454,7 @@ function boundedInteger$2(value, fallback, minimum, maximum) {
 	return Math.min(maximum, Math.max(minimum, Math.floor(value)));
 }
 function reportDays(value) {
-	if (value === void 0) return DEFAULT_DAYS$1;
+	if (value === void 0) return DEFAULT_DAYS$2;
 	if (!Number.isInteger(value) || value < 1 || value > MAX_DAYS) throw new SeoError("INVALID_INPUT", `Days must be a whole number between 1 and ${MAX_DAYS}.`);
 	return value;
 }
@@ -21859,20 +21896,394 @@ function analyzeInternalLinksFromRows(input) {
 		}
 	};
 }
-//#endregion
-//#region packages/core/src/analyze/internal-links-report.ts
-function internalLinksIntegerOption(input) {
-	const value = input.value ?? input.fallback;
-	if (!Number.isInteger(value) || value < input.minimum || value > input.maximum) throw new SeoError("INVALID_INPUT", `${input.label} must be a whole number between ${input.minimum} and ${input.maximum}.`);
-	return value;
+const MAX_TERMS = 100;
+const PLACEMENT_SENTENCES = 2;
+const ANCHORS_PER_SENTENCE = 3;
+const MIN_SENTENCE_WORDS = 6;
+const NAME_WEIGHT = 2;
+const GENERIC_ANCHORS = /^(click here|here|read more|learn more|more|this|this post|this article|this page|link|website|check it out|see more|view|continue reading)$/i;
+function normalise(value) {
+	return value.normalize("NFKD").replace(/\p{Diacritic}/gu, "").normalize("NFC").replace(/([\p{L}\p{N}])[’'`]([\p{L}\p{N}])/gu, "$1$2").toLowerCase().replace(/&/g, " and ").replace(/[^\p{L}\p{N}]+/gu, " ").replace(/\s+/g, " ").trim();
+}
+const words = (value) => normalise(value).split(" ").filter(Boolean);
+const FUNCTION_WORDS = new Set("a an and are as at be but by for from has have how if in into is it its of on or that the their then there these they this to was we were what when where which who why will with you your our can do does not just more most also than too very about after before over under again all any each other some such no nor only own same so up out off one two both every few several many much should would could because while since although though until unless whether however".split(" "));
+const NOT_PLURAL = /* @__PURE__ */ new Set([
+	"always",
+	"atlas",
+	"canvas",
+	"gas",
+	"lens",
+	"means",
+	"news",
+	"perhaps",
+	"series",
+	"species",
+	"sometimes",
+	"whereas",
+	"yes",
+	"this",
+	"has",
+	"was",
+	"does",
+	"its"
+]);
+const CHE = /* @__PURE__ */ new Set([
+	"caches",
+	"niches",
+	"headaches",
+	"cliches",
+	"avalanches",
+	"moustaches"
+]);
+const NOT_AGENT = /* @__PURE__ */ new Set([
+	"customer",
+	"together",
+	"however",
+	"whatever",
+	"whenever",
+	"wherever",
+	"remember",
+	"consider",
+	"character",
+	"register",
+	"november",
+	"december",
+	"september",
+	"october"
+]);
+function singular(word) {
+	if (word.length <= 3 || !/^[a-z]+$/.test(word) || NOT_PLURAL.has(word) || /(ss|us|is)$/.test(word)) return word;
+	if (word.endsWith("ies") && word.length > 4) return `${word.slice(0, -3)}y`;
+	if (/(xes|ches|shes|sses)$/.test(word) && !CHE.has(word)) return word.slice(0, -2);
+	return word.endsWith("s") ? word.slice(0, -1) : word;
+}
+function stem(word) {
+	const one = singular(word);
+	if (!/^[a-z]+$/.test(one)) return one;
+	if (one.length >= 8 && one.endsWith("er") && !one.endsWith("eer") && one.at(-3) !== one.at(-4) && !NOT_AGENT.has(one)) return one.slice(0, -2);
+	if (one.length > 5 && one.endsWith("ly")) return one.slice(0, -2);
+	if (one.length > 5 && one.endsWith("ed") && !one.endsWith("eed")) return one.slice(0, -2);
+	if (one.length > 6 && one.endsWith("ing")) return one.slice(0, -3);
+	return one;
+}
+const terms = (text) => words(text).filter((word) => word.length > 1 && !FUNCTION_WORDS.has(word) && !/^\d+$/.test(word)).map(stem);
+const slugWords = (url) => {
+	try {
+		return new URL(url).pathname.split(/[/._-]+/).filter(Boolean).join(" ");
+	} catch {
+		return "";
+	}
+};
+function keyTerms(page) {
+	const key = /* @__PURE__ */ new Map();
+	const title = page.title.replace(/\s+[|\u2013\u2014-]\s+[^|\u2013\u2014]*$/u, "");
+	for (const term of terms(page.description)) key.set(term, 1);
+	for (const term of terms(`${title} ${page.h1} ${lastSegmentWords(page.url)}`)) key.set(term, NAME_WEIGHT);
+	for (const term of terms(siteName(page.url))) key.delete(term);
+	return key;
+}
+function lastSegmentWords(url) {
+	try {
+		return (new URL(url).pathname.split("/").filter(Boolean).at(-1) ?? "").split(/[._-]+/).join(" ");
+	} catch {
+		return "";
+	}
 }
-function internalLinksNumberOption(input) {
-	const value = input.value ?? input.fallback;
-	if (!Number.isFinite(value) || value < input.minimum || value > input.maximum) throw new SeoError("INVALID_INPUT", `${input.label} must be between ${input.minimum} and ${input.maximum}.`);
-	return value;
+function siteName(url) {
+	try {
+		return new URL(url).hostname.replace(/^www\./u, "").split(".")[0] ?? "";
+	} catch {
+		return "";
+	}
 }
-function internalLinksReportRange(days, now) {
-	return finalGscDateRange(days, now);
+function termCounts(page) {
+	const counts = {};
+	const add = (text, weight) => {
+		for (const term of terms(text)) counts[term] = (counts[term] ?? 0) + weight;
+	};
+	add(page.title, 3);
+	add(page.h1, 3);
+	add(slugWords(page.url), 3);
+	add(page.description, 2);
+	for (const heading of page.headings) add(heading, 2);
+	for (const sentence of page.sentences) add(sentence.text, 1);
+	return counts;
+}
+const SKIP = /* @__PURE__ */ new Set([
+	"script",
+	"style",
+	"noscript",
+	"svg",
+	"template",
+	"iframe",
+	"select"
+]);
+const CHROME = /* @__PURE__ */ new Set([
+	"nav",
+	"header",
+	"footer",
+	"aside"
+]);
+const MAIN = /* @__PURE__ */ new Set(["main", "article"]);
+const BLOCK = new Set("p div li h1 h2 h3 h4 h5 h6 blockquote td th dd dt pre section article main aside header footer nav figcaption summary details tr ul ol table body form".split(" "));
+const VOID = /* @__PURE__ */ new Set([
+	"br",
+	"hr",
+	"img",
+	"input",
+	"meta",
+	"link",
+	"wbr",
+	"source",
+	"col",
+	"embed"
+]);
+const ENTITIES = {
+	amp: "&",
+	lt: "<",
+	gt: ">",
+	quot: "\"",
+	apos: "'",
+	nbsp: " ",
+	hellip: "…",
+	mdash: "—",
+	ndash: "–",
+	rsquo: "’",
+	lsquo: "‘",
+	rdquo: "”",
+	ldquo: "“"
+};
+const TAG_ATTRS = String.raw`(?:[^>"'=]|=\s*"[^"]*"|=\s*'[^']*'|=(?!\s*["'])|["'])*`;
+const A_OPEN = "
";
+const UNSPACED = /[\p{Script=Han}\p{Script=Hiragana}\p{Script=Katakana}\p{Script=Thai}\p{Script=Lao}\p{Script=Khmer}\p{Script=Myanmar}]/u;
+function decode(text) {
+	return text.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (match, code) => {
+		if (code[0] === "#") {
+			const hex = code[1] === "x" || code[1] === "X";
+			const point = Number.parseInt(code.slice(hex ? 2 : 1), hex ? 16 : 10);
+			return point > 0 && point <= 1114111 ? String.fromCodePoint(point) : "";
+		}
+		return ENTITIES[code.toLowerCase()] ?? match;
+	});
+}
+const clean$1 = (value) => value.split(A_OPEN).join("").replace(/\s+/g, " ").trim();
+function splitSentences(block) {
+	return block.replace(/\s+/g, " ").split(/(?<=[.!?…]["”’)]?)\s+(?=["“‘(]?[A-Z0-9])|(?<=[。！？])/).map((sentence) => sentence.trim()).filter((sentence) => sentence.length <= 500);
+}
+function pageSentences(html) {
+	const sentences = [];
+	const hasMain = /<(main|article)[\s>]|role=["']main["']/i.test(html);
+	const stack = [];
+	let skip = 0;
+	let chrome = 0;
+	let mainDepth = 0;
+	let main = hasMain ? 0 : 1;
+	let section = "";
+	let buffer = "";
+	let inAnchor = false;
+	const flushRaw = (tag) => {
+		const raw = buffer;
+		const text = clean$1(raw);
+		buffer = "";
+		if (!text || sentences.length >= 250) return;
+		if (/^h[1-6]$/.test(tag)) {
+			if (tag !== "h1") section = text;
+			return;
+		}
+		for (const part of tag === "li" ? [raw] : splitSentences(raw)) {
+			const sentence = clean$1(part);
+			if (sentence.length >= 25 && sentence.split(" ").length >= 4 || UNSPACED.test(sentence) && sentence.length >= 10) {
+				if (sentences.length >= 250) return;
+				sentences.push({
+					text: sentence,
+					section,
+					hasLink: part.includes(A_OPEN)
+				});
+			}
+		}
+	};
+	const closeTo = (tag) => {
+		if (!stack.some((entry) => entry.tag === tag)) return;
+		while (stack.length) {
+			const entry = stack.pop();
+			if (!entry) break;
+			flushRaw(entry.tag);
+			if (entry.main) {
+				main -= 1;
+				mainDepth -= 1;
+			}
+			if (entry.chrome) chrome -= 1;
+			if (entry.tag === tag) break;
+		}
+	};
+	const tokens = html.matchAll(new RegExp(String.raw`<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|<(\/?)([a-zA-Z][\w:-]*)(${TAG_ATTRS})>|([^<]+)`, "g"));
+	for (const match of tokens) {
+		const [whole, close, rawTag, rawAttrs = "", text] = match;
+		if (text !== void 0) {
+			if (!skip && main > 0 && chrome === 0) buffer += decode(text);
+			continue;
+		}
+		if (!rawTag) continue;
+		const tag = rawTag.toLowerCase();
+		if (skip) {
+			if (close && SKIP.has(tag)) skip -= 1;
+			continue;
+		}
+		if (close) {
+			if (tag === "a") inAnchor = false;
+			else if (BLOCK.has(tag)) closeTo(tag);
+			continue;
+		}
+		if (SKIP.has(tag)) {
+			if (!whole.endsWith("/>")) skip += 1;
+			continue;
+		}
+		if (tag === "br") buffer += " ";
+		if (tag === "a" && !inAnchor && /\bhref\s*=/i.test(rawAttrs)) {
+			inAnchor = true;
+			if (main > 0 && chrome === 0) buffer += A_OPEN;
+		}
+		if (VOID.has(tag) || !BLOCK.has(tag)) continue;
+		const parent = stack[stack.length - 1];
+		if (parent) flushRaw(parent.tag);
+		const role = /\brole\s*=\s*["']?main/i.test(rawAttrs);
+		const isMain = MAIN.has(tag) || role;
+		const isChrome = tag === "nav" || tag === "aside" || CHROME.has(tag) && mainDepth === 0;
+		if (isMain) {
+			main += 1;
+			mainDepth += 1;
+		}
+		if (isChrome) chrome += 1;
+		stack.push({
+			tag,
+			main: isMain,
+			chrome: isChrome
+		});
+	}
+	while (stack.length) {
+		const last = stack[stack.length - 1];
+		if (!last) break;
+		closeTo(last.tag);
+	}
+	flushRaw("");
+	return sentences;
+}
+var LinkCorpus = class {
+	df = /* @__PURE__ */ new Map();
+	size;
+	constructor(pages) {
+		this.size = pages.length;
+		for (const counts of pages) for (const term in counts) this.df.set(term, (this.df.get(term) ?? 0) + 1);
+	}
+	idf(term) {
+		return Math.log((this.size + 1) / ((this.df.get(term) ?? 1) + 1)) + 1;
+	}
+	vector(counts) {
+		let norm = 0;
+		const shared = [];
+		for (const term in counts) {
+			const weight = (1 + Math.log(counts[term] ?? 1)) * this.idf(term);
+			norm += weight * weight;
+			if ((this.df.get(term) ?? 0) >= 2) shared.push([term, weight]);
+		}
+		norm = Math.sqrt(norm) || 1;
+		shared.sort((left, right) => right[1] - left[1] || (left[0] < right[0] ? -1 : left[0] > right[0] ? 1 : 0));
+		return new Map(shared.slice(0, MAX_TERMS).map(([term, weight]) => [term, weight / norm]));
+	}
+	similarity(left, right) {
+		let sum = 0;
+		for (const [term, weight] of left) sum += weight * (right.get(term) ?? 0);
+		return sum;
+	}
+	sentenceScore(sentence, key) {
+		if (!key.size) return 0;
+		const seen = new Set(terms(sentence));
+		let hit = 0;
+		let total = 0;
+		for (const [term, place] of key) {
+			const weight = this.idf(term) * place;
+			total += weight;
+			if (seen.has(term)) hit += weight;
+		}
+		return total ? hit / total : 0;
+	}
+};
+function anchorCandidates(sentence, key, corpus, limit) {
+	const scored = /* @__PURE__ */ new Map();
+	const parts = sentence.split(/\s+/).map((word) => word.replace(/^[^\p{L}\p{N}]+|[^\p{L}\p{N}]+$/gu, "")).filter(Boolean);
+	for (let size = 2; size <= 4; size += 1) for (let start = 0; start + size <= parts.length; start += 1) {
+		const gram = parts.slice(start, start + size);
+		const first = (gram[0] ?? "").toLowerCase();
+		const last = (gram[size - 1] ?? "").toLowerCase();
+		if (FUNCTION_WORDS.has(first) || FUNCTION_WORDS.has(last) || /^\d+$/.test(first) || /^\d+$/.test(last)) continue;
+		const stems = terms(gram.join(" "));
+		if (stems.length < 2) continue;
+		const hits = stems.filter((term) => key.has(term)).length;
+		const named = stems.reduce((sum, term) => sum + (key.get(term) ?? 0) * corpus.idf(term), 0);
+		if (!stems.some((term) => key.get(term) === NAME_WEIGHT)) continue;
+		if (Number(key.has(terms(first)[0] ?? "")) + Number(key.has(terms(last)[0] ?? "")) < 2) continue;
+		const text = gram.join(" ");
+		const lower = text.toLowerCase();
+		if (GENERIC_ANCHORS.test(lower)) continue;
+		const rarity = stems.reduce((sum, term) => sum + corpus.idf(term), 0);
+		const score = named * (1 + hits / key.size) + rarity * .05 - (size === 4 ? .2 : 0);
+		const existing = scored.get(lower);
+		if (!existing || existing.score < score) scored.set(lower, {
+			text,
+			score
+		});
+	}
+	return [...scored.values()].sort((left, right) => right.score - left.score || (left.text < right.text ? -1 : left.text > right.text ? 1 : 0)).slice(0, limit).map((item) => item.text);
+}
+function linkPlacement(source, target, corpus) {
+	const key = keyTerms(target);
+	const contentSimilarity = corpus.similarity(corpus.vector(termCounts(source)), corpus.vector(termCounts(target)));
+	const seen = /* @__PURE__ */ new Set();
+	const sentences = source.sentences.filter((sentence) => {
+		if (seen.has(sentence.text)) return false;
+		seen.add(sentence.text);
+		return !sentence.hasLink && sentence.text.split(/\s+/).length >= MIN_SENTENCE_WORDS;
+	}).map((sentence, index) => ({
+		sentence,
+		index,
+		match: corpus.sentenceScore(sentence.text, key)
+	})).filter((item) => item.match > 0).sort((left, right) => right.match - left.match || left.index - right.index).slice(0, PLACEMENT_SENTENCES).map(({ sentence, match }) => ({
+		text: sentence.text,
+		section: sentence.section,
+		match: Math.round(match * 100) / 100,
+		anchors: anchorCandidates(sentence.text, key, corpus, ANCHORS_PER_SENTENCE)
+	})).filter((item) => item.anchors.length > 0);
+	return {
+		contentSimilarity: Math.round(contentSimilarity * 100) / 100,
+		sentences
+	};
+}
+function placementPage(input) {
+	return {
+		url: input.url,
+		title: input.title ?? "",
+		h1: input.headings.find((heading) => heading.level === 1)?.text ?? "",
+		description: input.metaDescription ?? "",
+		headings: input.headings.filter((heading) => heading.level === 2 || heading.level === 3).slice(0, 8).map((heading) => heading.text),
+		sentences: pageSentences(input.html)
+	};
+}
+//#endregion
+//#region packages/core/src/analyze/internal-links-report.ts
+const DAY$1 = 864e5;
+const ISO_DAY = /^\d{4}-\d{2}-\d{2}$/;
+function internalLinksReportRange(input, fallbackDays, now) {
+	if (!input.startDate && !input.endDate) return {
+		...finalGscDateRange(fallbackDays, now),
+		days: fallbackDays
+	};
+	const { startDate, endDate } = input;
+	if (!startDate || !endDate || !ISO_DAY.test(startDate) || !ISO_DAY.test(endDate) || startDate > endDate) throw new SeoError("INVALID_INPUT", "Send a start date and an end date together, in order, as YYYY-MM-DD.");
+	return {
+		startDate,
+		endDate,
+		days: Math.round((Date.parse(`${endDate}T00:00:00Z`) - Date.parse(`${startDate}T00:00:00Z`)) / DAY$1) + 1
+	};
 }
 function completeInternalLinksSelection(analysis, runtime) {
 	return {
@@ -21930,9 +22341,8 @@ async function verifyInternalLinkTarget(input) {
 	let fetched;
 	try {
 		fetched = await input.dependencies.fetch(input.targetUrl, {
-			js: input.js ?? "auto",
-			refresh: input.refresh,
-			rate: input.rate
+			js: "auto",
+			refresh: input.refresh
 		});
 	} catch (error) {
 		return {
@@ -22002,7 +22412,12 @@ async function verifyInternalLinkTarget(input) {
 		verification: fatalSignals.length ? "technical-issue" : "verified",
 		technicalSignals: signals,
 		fetchDiagnostics: fetched.diagnostics,
-		warnings
+		warnings,
+		text: placementPage({
+			...page,
+			url: page.finalUrl,
+			html: fetched.html
+		})
 	};
 }
 function linksToAliases(page, aliases) {
@@ -22036,9 +22451,8 @@ async function verifyInternalLinkCandidate(input) {
 	let fetched;
 	try {
 		fetched = await input.dependencies.fetch(input.candidate.sourceUrl, {
-			js: input.js ?? "auto",
-			refresh: input.refresh,
-			rate: input.rate
+			js: "auto",
+			refresh: input.refresh
 		});
 	} catch (error) {
 		return {
@@ -22128,12 +22542,21 @@ async function verifyInternalLinkCandidate(input) {
 				confidence
 			}
 		},
+		text: placementPage({
+			...page,
+			url: page.finalUrl,
+			html: fetched.html
+		}),
 		warnings
 	};
 }
 //#endregion
 //#region packages/core/src/analyze/internal-links.ts
 const MAX_GSC_ROWS = 1e5;
+const DEFAULT_DAYS$1 = 90;
+const RESULT_LIMIT = 20;
+const CHECK_LIMIT = 40;
+const MIN_IMPRESSIONS = 1;
 const defaultDependencies$2 = {
 	searchAnalytics: querySearchAnalytics,
 	fetch: fetchPage,
@@ -22144,43 +22567,17 @@ async function internalLinksReport(input, dependencies = defaultDependencies$2)
 	const targetPage = new URL(assertUrlMatchesGscProperty(input.site, input.targetUrl));
 	targetPage.hash = "";
 	const targetUrl = targetPage.toString();
-	const days = internalLinksIntegerOption({
-		value: input.days,
-		fallback: 28,
-		minimum: 1,
-		maximum: 548,
-		label: "days"
-	});
-	const limit = internalLinksIntegerOption({
-		value: input.limit,
-		fallback: 20,
-		minimum: 1,
-		maximum: 100,
-		label: "limit"
-	});
-	const checkLimit = internalLinksIntegerOption({
-		value: input.checkLimit,
-		fallback: Math.max(limit, 40),
-		minimum: 1,
-		maximum: 200,
-		label: "checkLimit"
-	});
-	const minImpressions = internalLinksNumberOption({
-		value: input.minImpressions,
-		fallback: 1,
-		minimum: 0,
-		maximum: 1e9,
-		label: "minImpressions"
-	});
+	const limit = RESULT_LIMIT;
+	const checkLimit = CHECK_LIMIT;
+	const minImpressions = MIN_IMPRESSIONS;
 	const now = dependencies.now();
-	const range = internalLinksReportRange(days, now);
+	const { days, ...range } = internalLinksReportRange(input, DEFAULT_DAYS$1, now);
+	const brandTerms = deriveBrandTerms({ siteUrl: input.site });
 	const ledger = new SessionLedger();
 	const target = await verifyInternalLinkTarget({
 		site: input.site,
 		targetUrl,
-		js: input.js,
 		refresh: input.refresh,
-		rate: input.rate,
 		dependencies
 	});
 	const targetRequests = await Promise.all(target.aliases.map(async (alias) => {
@@ -22212,8 +22609,7 @@ async function internalLinksReport(input, dependencies = defaultDependencies$2)
 		site: input.site,
 		targetAliases: target.aliases,
 		minImpressions,
-		brandTerms: input.brandTerms,
-		includeBrand: input.includeBrand
+		brandTerms
 	});
 	const queryCandidates = target.verification === "verified" && preliminary.selection.targetEligibleQueries > 0;
 	const sourceResult = queryCandidates ? await dependencies.searchAnalytics(input.site, {
@@ -22234,10 +22630,9 @@ async function internalLinksReport(input, dependencies = defaultDependencies$2)
 		site: input.site,
 		targetAliases: target.aliases,
 		minImpressions,
-		brandTerms: input.brandTerms,
-		includeBrand: input.includeBrand
+		brandTerms
 	});
-	const items = [];
+	const found = [];
 	const warnings = [...target.warnings];
 	let attemptedSources = 0;
 	let checkedSources = 0;
@@ -22246,25 +22641,27 @@ async function internalLinksReport(input, dependencies = defaultDependencies$2)
 	let selfAliasExclusions = 0;
 	let failedChecks = 0;
 	for (const candidate of analysis.candidates) {
-		if (attemptedSources >= checkLimit || items.length >= limit) break;
+		if (attemptedSources >= checkLimit || found.length >= limit) break;
 		attemptedSources += 1;
 		const verified = await verifyInternalLinkCandidate({
 			site: input.site,
 			candidate,
 			target,
-			js: input.js,
 			refresh: input.refresh,
-			rate: input.rate,
 			dependencies
 		});
 		warnings.push(...verified.warnings);
-		if (verified.item) items.push(verified.item);
+		if (verified.item) found.push({
+			item: verified.item,
+			text: verified.text
+		});
 		if (verified.exclusion === "existing-link") existingLinkExclusions += 1;
 		if (verified.exclusion === "technical") technicalExclusions += 1;
 		if (verified.exclusion === "self-alias") selfAliasExclusions += 1;
 		if (verified.exclusion === "failed") failedChecks += 1;
 		else checkedSources += 1;
 	}
+	const items = placeLinks(found, target.text);
 	const uncheckedCandidates = Math.max(0, analysis.candidates.length - attemptedSources);
 	const targetTruncated = targetRequests.some(({ result }) => result.rowsFetched >= MAX_GSC_ROWS);
 	const sourceTruncated = sourceResult.rowsFetched >= MAX_GSC_ROWS;
@@ -22326,13 +22723,14 @@ async function internalLinksReport(input, dependencies = defaultDependencies$2)
 		},
 		methodology: {
 			id: "gsc_internal_link_candidates",
-			version: 3,
+			version: 4,
 			lexicalTargetLimit: 50,
 			matchedQueryEvidenceLimit: 10,
 			observedLinkEvidenceLimit: 20,
 			matching: "pairwise_exact_then_precision_lexical",
 			ranking: "exact_matches_then_matched_query_impressions_then_relevance",
-			contextualPlacementVerified: true
+			contextualPlacementVerified: true,
+			placement: "tfidf_sentence_match_then_phrase_anchors"
 		},
 		filters: {
 			minImpressions,
@@ -22364,18 +22762,20 @@ async function internalLinksReport(input, dependencies = defaultDependencies$2)
 			failedChecks,
 			uncheckedCandidates,
 			matchedQueryImpressions: items.reduce((sum, item) => sum + item.matchedQueryImpressions, 0),
-			brandFiltering: input.includeBrand ? "included" : "excluded",
+			brandFiltering: "excluded",
 			verdict: summaryVerdict
 		},
 		items,
 		warnings: structuredWarnings,
 		caveats: [
-			`Date window: ${range.startDate} to ${range.endDate} (${days} days), using final GSC data where available.`,
+			`Date window: ${range.startDate} to ${range.endDate} (${days} days), using final GSC data where available.${input.startDate ? "" : ` Without dates the window is the last ${DEFAULT_DAYS$1} days.`}`,
+			`Limits: up to ${checkLimit} source pages are checked live and up to ${limit} are returned. Queries need at least ${minImpressions} impression.`,
 			`Selection: ${analysis.selection.targetEligibleQueries} eligible target queries, ${analysis.selection.candidateUrls} matched source pages, ${attemptedSources} attempted, ${checkedSources} successfully checked, ${items.length} returned.`,
-			`Minimum retained query impressions: ${minImpressions}. Brand queries were ${input.includeBrand ? "included" : "excluded when detected or configured"}.`,
+			`Brand queries were left out. Brand terms found from the domain: ${brandTerms.join(", ") || "none"}.`,
 			"GSC query rows omit anonymized queries and lower-volume rows. A 100,000-row cap is reported separately when reached.",
 			"Exact query overlap is medium-confidence affinity evidence; lexical matches are low-confidence review evidence. Neither predicts traffic lift or link equity.",
 			"The fetch checks HTML link placement, but it cannot prove editorial relevance. Review intent and reader usefulness before adding a link.",
+			"Placement sentences are the source sentences without a link that share the most rare words with the target title, h1, description and URL. Anchors are phrases from those sentences. Content similarity compares the words of the checked pages only. All three are text heuristics, not ranking evidence.",
 			uncheckedCandidates ? `${uncheckedCandidates} matched source page${uncheckedCandidates === 1 ? " was" : "s were"} not checked because the output or check limit was reached.` : "",
 			failedChecks ? `${failedChecks} source verification attempt${failedChecks === 1 ? "" : "s"} failed. Failed fetches or extraction attempts are not counted as checked pages and do not support a missing-link conclusion.` : ""
 		].filter(Boolean),
@@ -22383,6 +22783,29 @@ async function internalLinksReport(input, dependencies = defaultDependencies$2)
 		ledgerSummary: ledger.summary()
 	};
 }
+function placeLinks(found, target) {
+	const corpus = new LinkCorpus([target, ...found.map((entry) => entry.text)].filter((page) => Boolean(page)).map(termCounts));
+	const placed = found.map(({ item, text }) => {
+		const placement = target && text ? linkPlacement(text, target, corpus) : {
+			contentSimilarity: 0,
+			sentences: []
+		};
+		const best = placement.sentences[0];
+		const recommendation = best ? {
+			...item.recommendation,
+			action: `${item.recommendation.action} It fits in: "${best.text}" Anchor text could be ${best.anchors.map((anchor) => `"${anchor}"`).join(" or ")}.`
+		} : {
+			...item.recommendation,
+			action: `${item.recommendation.action} No sentence on this page names the target, so a link here needs new text.`
+		};
+		return {
+			...item,
+			placement,
+			recommendation
+		};
+	});
+	return [...placed.filter((item) => item.placement.sentences.length > 0), ...placed.filter((item) => item.placement.sentences.length === 0)];
+}
 //#endregion
 //#region packages/core/src/analyze/url-templates.ts
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
@@ -26316,6 +26739,16 @@ const SECTIONS = {
 	bing: "Bing’s top queries from Bing Webmaster Tools with Google’s clicks, impressions and position for the same query beside them, and the same for pages."
 };
 const SECTION_IDS = Object.keys(SECTIONS);
+new Map(`
+  ae:ar al:sq am:hy ao:pt ar:es at:de au:en az:az ba:bs bd:bn be:nl bf:fr
+  bg:bg bh:ar bo:es br:pt ca:en ch:de ci:fr cl:es cm:fr co:es cr:es cy:el
+  cz:cs de:de dk:da dz:ar ec:es ee:et eg:ar es:es fi:fi fr:fr gb:en gh:en
+  gr:el gt:es hk:en hr:hr hu:hu id:id ie:en il:he in:en it:it jo:ar jp:ja
+  ke:en kh:en kr:ko kz:ru lk:en lt:lt lv:lv ma:ar mc:fr md:ro mk:mk mm:en
+  mt:en mx:es my:en ng:en ni:es nl:nl no:nb nz:en pa:es pe:es ph:en pk:en
+  pl:pl pt:pt py:es ro:ro rs:sr sa:ar se:sv sg:en si:sl sk:sk sn:fr sv:es
+  th:th tn:ar tr:tr tw:zh-TW ua:uk us:en uy:es ve:es vn:vi za:en
+`.trim().split(/\s+/).map((pair) => pair.split(":")));
 //#endregion
 //#region packages/core/src/commands/research.ts
 const RESEARCH_ACTIONS = [
@@ -26601,6 +27034,7 @@ function nodeCommandDeps(options) {
 				return null;
 			}
 		},
+		pageMarkdown: async (url) => extractMainMarkdown(await fetchPage(url, { refresh: options.refresh })),
 		call: options.call,
 		bing: localBing,
 		bingConnect: LOCAL_BING_CONNECT