@coywolf/emdash 0.0.0-stage → 0.35.13

package/src/customBlocks/rich.ts

@@ -0,0 +1,313 @@
+/**
+ * Rich text for the Custom Blocks' text fields. EmDash block fields are
+ * plain text inputs, so a field holds simple markup that's turned into safe
+ * HTML here:
+ *
+ * - A blank line starts a new paragraph; a single line break is a <br>.
+ * - `[link text](https://…)` is a link and `**text**` is bold.
+ * - A small set of HTML tags is kept (links, bold, italics, code, <abbr>,
+ *   <q>, lists, paragraphs, headings, images, …), so content imported from
+ *   WordPress keeps its exact markup. Their attributes are limited to safe ones
+ *   (href, title, rel, cite, src, alt, …), URLs to http(s), mailto, tel and
+ *   site-relative ones, and inline styles to text styling (color, font size,
+ *   weight, …) with plain values.
+ * - Any other tag is dropped (its text stays; <script> and <style> bodies go),
+ *   stray "<" and "&" are escaped, and tags left open are closed, so a field
+ *   can't break the page around it.
+ *
+ * Pure, no imports: runs in the Worker, the admin and tests.
+ */
+
+type Attrs = Record<string, string>;
+
+interface TagRule {
+	/** Allowed attributes (others are dropped). */
+	attrs?: string[];
+	/** Block-level: ends the current paragraph, not allowed in inline fields. */
+	block?: boolean;
+	void?: boolean;
+}
+
+const RULES: Record<string, TagRule> = {
+	a: { attrs: ["href", "title", "rel", "hreflang"] },
+	abbr: { attrs: ["title"] },
+	b: {},
+	strong: {},
+	i: {},
+	em: {},
+	u: {},
+	s: {},
+	del: {},
+	ins: {},
+	mark: {},
+	small: {},
+	sub: {},
+	sup: {},
+	code: {},
+	kbd: {},
+	samp: {},
+	var: {},
+	cite: {},
+	dfn: { attrs: ["title"] },
+	q: { attrs: ["cite"] },
+	time: { attrs: ["datetime"] },
+	span: { attrs: ["lang", "dir"] },
+	br: { void: true },
+	wbr: { void: true },
+	p: { block: true },
+	ul: { block: true },
+	ol: { block: true, attrs: ["start", "reversed", "type"] },
+	li: { block: true, attrs: ["value"] },
+	dl: { block: true },
+	dt: { block: true },
+	dd: { block: true },
+	blockquote: { block: true, attrs: ["cite"] },
+	pre: { block: true },
+	figure: { block: true },
+	figcaption: { block: true },
+	h2: { block: true },
+	h3: { block: true },
+	h4: { block: true },
+	h5: { block: true },
+	h6: { block: true },
+	hr: { block: true, void: true },
+	img: { block: true, void: true, attrs: ["src", "alt", "width", "height", "loading", "decoding", "title"] },
+};
+
+const URL_ATTRS = new Set(["href", "src", "cite"]);
+const REL_TOKENS = new Set(["nofollow", "sponsored", "ugc", "noopener", "noreferrer", "external", "me", "author", "license", "tag"]);
+const DROP_BODY = new Set(["script", "style", "template", "noscript", "iframe", "object", "textarea", "title", "svg", "math"]);
+
+const ESC: Record<string, string> = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
+export const escapeHtml = (text: string) => String(text).replace(/[&<>"']/g, (c) => ESC[c] as string);
+
+const NAMED: Record<string, string> = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'", nbsp: " " };
+
+/** Decode the entities an attribute value may hold (enough to check a URL's scheme). */
+function decodeAttr(value: string): string {
+	return value.replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);?/gi, (whole, code: string) => {
+		if (code[0] === "#") {
+			const n = code[1] === "x" || code[1] === "X" ? Number.parseInt(code.slice(2), 16) : Number.parseInt(code.slice(1), 10);
+			return Number.isFinite(n) && n > 0 && n <= 0x10ffff && !(n >= 0xd800 && n <= 0xdfff) ? String.fromCodePoint(n) : "";
+		}
+		return NAMED[code.toLowerCase()] ?? whole;
+	});
+}
+
+/** A link or image URL that's safe to print: http(s), mailto, tel, or relative. Null otherwise. */
+export function safeUrl(value: string): string | null {
+	// biome-ignore lint/suspicious/noControlCharactersInRegex: browsers ignore these inside a scheme.
+	const url = decodeAttr(value).replace(/[\u0000- \u007f]+/g, (m, i: number) => (i === 0 ? "" : m)).trim();
+	if (!url || url.length > 2000) return null;
+	// biome-ignore lint/suspicious/noControlCharactersInRegex: see above.
+	const scheme = url.replace(/[\u0000- \u007f]/g, "").match(/^([a-z][a-z0-9+.-]*):/i)?.[1]?.toLowerCase();
+	if (scheme && !["http", "https", "mailto", "tel"].includes(scheme)) return null;
+	return url;
+}
+
+/** Escape text, keeping valid entity references (&amp; &#8217; &nbsp; …) as written. */
+function text(chunk: string): string {
+	return chunk.replace(/&(?!(?:#x[0-9a-f]{1,6}|#\d{1,7}|[a-z][a-z0-9]{1,31});)/gi, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/** `[text](url)` links and `**bold**` inside an escaped text run. */
+function markdownLite(escaped: string): string {
+	return escaped
+		.replace(/\[([^\]\n]{1,500})\]\(([^()\s]{1,2000})\)/g, (whole, label: string, href: string) => {
+			const url = safeUrl(href);
+			return url ? `<a href="${escapeHtml(url)}">${label}</a>` : whole;
+		})
+		.replace(/\*\*(?=\S)([^*\n]{1,1000}?)\*\*/g, "<strong>$1</strong>");
+}
+
+const TAG = /<!--[\s\S]*?(?:-->|$)|<(\/?)([a-zA-Z][a-zA-Z0-9]*)((?:\s+[^\s"'>\/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'=<>`]+))?)*)\s*(\/?)>/g;
+const ATTR = /([^\s"'>\/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+
+const STYLE_PROPS = new Set(["color", "background-color", "font-size", "font-weight", "font-style", "font-variant", "text-decoration", "text-transform", "text-align", "letter-spacing", "white-space"]);
+
+/** Inline styles WordPress content uses for emphasis (color, size, weight, …); anything else is dropped. */
+export function cleanStyle(value: string): string {
+	return value
+		.split(";")
+		.map((decl) => {
+			const at = decl.indexOf(":");
+			if (at < 0) return "";
+			const prop = decl.slice(0, at).trim().toLowerCase();
+			const val = decl.slice(at + 1).trim();
+			if (!STYLE_PROPS.has(prop) || !val || val.length > 60) return "";
+			if (!/^[#a-z0-9.%,\s()-]+$/i.test(val) || /url|expression|image|var|attr|env/i.test(val)) return "";
+			return `${prop}:${val}`;
+		})
+		.filter(Boolean)
+		.join(";");
+}
+
+function cleanAttrs(name: string, raw: string): string {
+	const allowed = [...(RULES[name]?.attrs ?? []), ...(RULES[name]?.void ? [] : ["style"])];
+	if (!allowed.length || !raw.trim()) return "";
+	const out: Attrs = {};
+	for (const m of raw.matchAll(ATTR)) {
+		const key = (m[1] as string).toLowerCase();
+		if (!allowed.includes(key) || key in out) continue;
+		let value = decodeAttr(m[2] ?? m[3] ?? m[4] ?? "");
+		if (URL_ATTRS.has(key)) {
+			const url = safeUrl(value);
+			if (!url) continue;
+			value = url;
+		} else if (key === "rel") {
+			value = value
+				.toLowerCase()
+				.split(/\s+/)
+				.filter((t) => REL_TOKENS.has(t))
+				.join(" ");
+			if (!value) continue;
+		} else if (["width", "height", "start", "value"].includes(key)) {
+			if (!/^-?\d{1,6}$/.test(value.trim())) continue;
+			value = value.trim();
+		} else if (key === "loading" || key === "decoding") {
+			if (!["lazy", "eager", "async", "sync", "auto"].includes(value)) continue;
+		} else if (key === "reversed") {
+			value = "";
+		} else if (key === "style") {
+			value = cleanStyle(value);
+			if (!value) continue;
+		}
+		out[key] = value.slice(0, 2000);
+	}
+	if (name === "img" && !out.src) return "\u0000";
+	return Object.entries(out)
+		.map(([k, v]) => (k === "reversed" ? " reversed" : ` ${k}="${escapeHtml(v)}"`))
+		.join("");
+}
+
+export interface RichOptions {
+	/** One line of inline content (titles, citations): no paragraphs or block tags; line breaks become <br>. */
+	inline?: boolean;
+}
+
+/**
+ * Turn a field's text into safe HTML. Block content gets paragraphs (text that
+ * isn't already inside a <p>, list, … is wrapped); inline content doesn't.
+ */
+export function renderRich(input: unknown, opts: RichOptions = {}): string {
+	if (typeof input !== "string" || !input.trim()) return "";
+	const source = input
+		.slice(0, 500_000)
+		.replace(/\r\n?/g, "\n")
+		// biome-ignore lint/suspicious/noControlCharactersInRegex: strip control characters (keep tab and newline).
+		.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, "");
+	const inline = Boolean(opts.inline);
+	let out = "";
+	/** Open allowed elements, outermost first. */
+	const stack: string[] = [];
+	/** The paragraph being collected at the top level (block mode). */
+	let para = "";
+	let paraOpen: string[] = [];
+	let skipUntil: string | null = null;
+
+	const blockOpen = () => stack.some((t) => RULES[t]?.block);
+	const flush = () => {
+		// Close inline tags opened in this paragraph, then emit it.
+		while (paraOpen.length) para += `</${paraOpen.pop()}>`;
+		const body = para.replace(/^(?:\s|<br>)+|(?:\s|<br>)+$/g, "");
+		if (body) out += `<p>${body}</p>`;
+		para = "";
+	};
+	const emitText = (chunk: string) => {
+		if (!chunk) return;
+		if (inline) {
+			out += markdownLite(text(chunk)).replace(/\n+/g, "<br>");
+			return;
+		}
+		if (blockOpen()) {
+			out += markdownLite(text(chunk));
+			return;
+		}
+		const parts = chunk.split(/\n[ \t]*\n\s*/);
+		parts.forEach((part, i) => {
+			if (i > 0) flush();
+			para += markdownLite(text(part)).replace(/\n/g, "<br>");
+		});
+	};
+	const emitTag = (html: string, name: string, kind: "open" | "close" | "void") => {
+		const rule = RULES[name] as TagRule;
+		if (inline || blockOpen() || rule.block) {
+			if (!inline && rule.block && !blockOpen()) flush();
+			out += html;
+			if (kind === "open") stack.push(name);
+			return;
+		}
+		// An inline tag at the top level belongs to the current paragraph.
+		para += html;
+		if (kind === "open") paraOpen.push(name);
+		else if (kind === "close") paraOpen.splice(paraOpen.lastIndexOf(name), 1);
+	};
+
+	let last = 0;
+	TAG.lastIndex = 0;
+	for (let m = TAG.exec(source); m; m = TAG.exec(source)) {
+		const before = source.slice(last, m.index);
+		last = m.index + m[0].length;
+		if (skipUntil) {
+			if (m[1] && m[2]?.toLowerCase() === skipUntil) skipUntil = null;
+			continue;
+		}
+		emitText(before);
+		if (!m[2]) continue; // A comment.
+		const name = m[2].toLowerCase();
+		const closing = Boolean(m[1]);
+		if (!closing && DROP_BODY.has(name)) {
+			if (!m[4]) skipUntil = name;
+			continue;
+		}
+		const rule = RULES[name];
+		if (!rule || (inline && rule.block && name !== "br")) continue;
+		if (rule.void) {
+			if (closing) continue;
+			const attrs = cleanAttrs(name, m[3] ?? "");
+			if (attrs === "\u0000") continue;
+			emitTag(`<${name}${attrs}>`, name, "void");
+			continue;
+		}
+		if (!closing) {
+			const attrs = cleanAttrs(name, m[3] ?? "");
+			emitTag(`<${name}${attrs}>`, name, "open");
+			if (m[4]) emitTag(`</${name}>`, name, "close"); // <b/>: treat as empty.
+			continue;
+		}
+		// A closing tag: only when it closes something open; close what's inside it first.
+		if (!inline && !blockOpen() && paraOpen.includes(name)) {
+			while (paraOpen.length) {
+				const top = paraOpen[paraOpen.length - 1] as string;
+				emitTag(`</${top}>`, top, "close");
+				if (top === name) break;
+			}
+			continue;
+		}
+		const at = stack.lastIndexOf(name);
+		if (at < 0) continue;
+		while (stack.length > at) out += `</${stack.pop()}>`;
+	}
+	if (!skipUntil) emitText(source.slice(last));
+	if (!inline) {
+		while (stack.length) out += `</${stack.pop()}>`;
+		flush();
+	} else {
+		while (stack.length) out += `</${stack.pop()}>`;
+	}
+	return out.trim();
+}
+
+/** Plain text of a field (for labels, schema and checks): tags dropped, entities decoded, whitespace collapsed. */
+export function plainText(input: unknown): string {
+	if (typeof input !== "string") return "";
+	return decodeAttr(
+		input
+			.replace(/<(script|style)\b[\s\S]*?<\/\1\s*>/gi, "")
+			.replace(/<[^>]*>/g, " ")
+			.replace(/\[([^\]\n]+)\]\([^()\s]+\)/g, "$1")
+			.replace(/\*\*([^*\n]+)\*\*/g, "$1"),
+	)
+		.replace(/\s+/g, " ")
+		.trim();
+}

package/src/customBlocks/settings.ts

@@ -0,0 +1,46 @@
+/**
+ * Custom Blocks settings (the affiliate disclosure wording and the podcast
+ * links), read outside the plugin context (Astro renderer) from D1 in the
+ * feature switches' query, sharing their per-isolate cache.
+ *
+ * The disclosure wording keeps the storage key it had when the module was
+ * called Content Blocks ("contentBlocks"), so saved wording carries over.
+ */
+import { invalidateFeatures, readSiteSetting, registerSiteSetting } from "../core/features.js";
+import { DEFAULT_DISCLOSURE, DEFAULT_PODCAST, type DisclosureSettings, type PodcastSettings, normalizeDisclosureSettings, normalizePodcastSettings } from "./render.js";
+
+/** Disclosure wording. Unchanged since 0.11.0 (Content Blocks): don't rename. */
+export const SETTINGS_KEY = "contentBlocks";
+/** Podcast links (0.12.0). */
+export const PODCAST_SETTINGS_KEY = "customBlocksPodcast";
+
+registerSiteSetting(SETTINGS_KEY);
+registerSiteSetting(PODCAST_SETTINGS_KEY);
+
+/** Per key: the last stored value and its normalized settings, so a cache hit doesn't normalize again. */
+const memo = new Map<string, { raw: unknown; value: unknown }>();
+
+export function invalidateCustomBlockSettings(): void {
+	invalidateFeatures();
+}
+
+async function readSetting<T>(key: string, normalize: (raw: unknown) => T, fallback: T, database: string): Promise<T> {
+	const read = await readSiteSetting(key, database);
+	if (!read) {
+		console.error("coywolf-pack: could not read the custom block settings");
+		return fallback;
+	}
+	const hit = memo.get(key);
+	if (hit && hit.raw === read.value) return hit.value as T;
+	const value = normalize(read.value);
+	memo.set(key, { raw: read.value, value });
+	return value;
+}
+
+export function siteDisclosureSettings(database = "DB"): Promise<DisclosureSettings> {
+	return readSetting(SETTINGS_KEY, normalizeDisclosureSettings, DEFAULT_DISCLOSURE, database);
+}
+
+export function sitePodcastSettings(database = "DB"): Promise<PodcastSettings> {
+	return readSetting(PODCAST_SETTINGS_KEY, normalizePodcastSettings, DEFAULT_PODCAST, database);
+}

package/src/discovery/build.ts

@@ -0,0 +1,252 @@
+/**
+ * Builds llms.txt, the news sitemap, and per-entry Markdown from EmDash
+ * content (inside the plugin context), with KV caching for the two lists.
+ */
+import { siteName } from "../core/site.js";
+import { type CollectionSchemaInfo, type PluginContentItem, type PluginContext, after, getSiteSetting } from "emdash";
+
+import { absoluteUrl, matchEntryPath } from "../core/content-url.js";
+
+import { buildLlmsTxt, type LlmsSection } from "./llms.js";
+import { estimateTokens, frontmatter, markdownUrl, portableTextToMarkdown } from "./markdown.js";
+import { NEWS_LIMIT, NEWS_WINDOW_MS, buildNewsSitemap, parseDate, selectNewsArticles, type NewsArticle } from "./news.js";
+import { type DiscoverySettings, loadSettings, selected } from "./settings.js";
+import { createUrlResolver, siteOrigin } from "./urls.js";
+
+export const LLMS_CACHE = "cache:discovery:llms";
+export const NEWS_CACHE = "cache:discovery:news";
+/** The news sitemap's 48-hour window moves, so its cache is short. */
+export const NEWS_TTL_MS = 5 * 60_000;
+/** llms.txt is invalidated on content changes; this is only a safety net. */
+export const LLMS_TTL_MS = 24 * 60 * 60_000;
+
+export interface CachedDocument {
+	body: string;
+	count: number;
+	builtAt: string;
+}
+
+const str = (value: unknown) => (typeof value === "string" ? value : "");
+
+export function entryTitle(collection: CollectionSchemaInfo, item: PluginContentItem): string {
+	return str(item.data[collection.titleField ?? "title"]) || str(item.data.title) || item.slug || item.id;
+}
+
+function entryNote(item: PluginContentItem): string {
+	return str(item.data.excerpt).trim() || str(item.seo?.description).trim();
+}
+
+/** Routable collections in the selection. Hidden collections are listed only when picked explicitly. */
+export async function pickCollections(ctx: PluginContext, selection: string[]): Promise<CollectionSchemaInfo[]> {
+	const all = (await ctx.schema?.listCollections()) ?? [];
+	return all.filter((c) => c.routable && (selection.length ? selection.includes(c.slug) : !c.hidden));
+}
+
+/** Published entries of a collection, newest first, a page at a time. `stop` ends the walk early. */
+async function* published(ctx: PluginContext, collection: string, max: number, stop?: (item: PluginContentItem) => boolean) {
+	if (!ctx.content || max <= 0) return;
+	let cursor: string | undefined;
+	let count = 0;
+	do {
+		const page = await ctx.content.list(collection, { limit: 100, cursor, orderBy: { publishedAt: "desc" }, where: { status: "published" } });
+		const batch: PluginContentItem[] = [];
+		let done = false;
+		for (const item of page.items) {
+			if (stop?.(item)) {
+				done = true;
+				break;
+			}
+			batch.push(item);
+			if (++count >= max) {
+				done = true;
+				break;
+			}
+		}
+		if (batch.length) yield batch;
+		if (done) return;
+		cursor = page.hasMore ? page.cursor : undefined;
+	} while (cursor);
+}
+
+// ── llms.txt ─────────────────────────────────────────────────────
+
+export async function buildLlms(ctx: PluginContext, settings: DiscoverySettings): Promise<CachedDocument> {
+	const resolver = createUrlResolver(ctx);
+	const max = settings.llms.maxEntries;
+	const sections: LlmsSection[] = [];
+	let remaining = max;
+	for (const collection of await pickCollections(ctx, settings.llms.collections)) {
+		if (remaining <= 0) break;
+		const entries: LlmsSection["entries"] = [];
+		for await (const batch of published(ctx, collection.slug, remaining)) {
+			const listed = batch.filter((item) => !item.seo?.noIndex);
+			const urls = await resolver.urls(collection, listed);
+			for (const item of listed) {
+				const url = urls.get(item.id);
+				if (!url) continue;
+				entries.push({ title: entryTitle(collection, item), url: settings.llms.markdown ? markdownUrl(url) : url, note: entryNote(item) });
+			}
+		}
+		remaining -= entries.length;
+		if (entries.length) sections.push({ label: collection.label, entries });
+	}
+	const tagline = await getSiteSetting("tagline").catch(() => undefined);
+	const body = buildLlmsTxt({
+		name: await siteName(ctx),
+		siteUrl: siteOrigin(ctx),
+		summary: settings.llms.summary || tagline,
+		intro: settings.llms.intro,
+		markdownLinks: settings.llms.markdown,
+		sections,
+		maxEntries: max,
+	});
+	return { body, count: sections.reduce((n, s) => n + s.entries.length, 0), builtAt: new Date().toISOString() };
+}
+
+// ── News sitemap ─────────────────────────────────────────────────
+
+export async function buildNews(ctx: PluginContext, settings: DiscoverySettings, now = Date.now()): Promise<CachedDocument> {
+	const resolver = createUrlResolver(ctx);
+	const articles: NewsArticle[] = [];
+	const tooOld = (item: PluginContentItem) => (parseDate(item.publishedAt)?.getTime() ?? 0) <= now - NEWS_WINDOW_MS;
+	// An empty news selection lists nothing (unlike llms.txt, where empty means all).
+	const collections = settings.news.collections.length ? await pickCollections(ctx, settings.news.collections) : [];
+	for (const collection of collections) {
+		for await (const batch of published(ctx, collection.slug, NEWS_LIMIT, tooOld)) {
+			const listed = batch.filter((item) => !item.seo?.noIndex && item.publishedAt);
+			const urls = await resolver.urls(collection, listed);
+			for (const item of listed) {
+				const url = urls.get(item.id);
+				if (url && item.publishedAt) articles.push({ url, title: entryTitle(collection, item), publishedAt: item.publishedAt });
+			}
+		}
+	}
+	const selectedArticles = selectNewsArticles(articles, now);
+	const body = buildNewsSitemap(selectedArticles, {
+		name: settings.news.publicationName || (await siteName(ctx)) || new URL(ctx.site.url).host,
+		language: settings.news.language || ctx.site.locale,
+	});
+	return { body, count: selectedArticles.length, builtAt: new Date(now).toISOString() };
+}
+
+// ── Caching (stale-while-revalidate) ─────────────────────────────
+//
+// Visitor requests only read the last good copy from plugin KV. Content
+// hooks, settings saves and stale reads schedule a rebuild with after(),
+// debounced per isolate, which overwrites the copy when it's done. The one
+// exception is a cold start (nothing stored yet), which builds inline once.
+
+export type DocKind = "llms" | "news";
+const DOC_KEY: Record<DocKind, string> = { llms: LLMS_CACHE, news: NEWS_CACHE };
+const DOC_TTL: Record<DocKind, number> = { llms: LLMS_TTL_MS, news: NEWS_TTL_MS };
+/** Wait this long after a change for more changes before rebuilding. */
+const REBUILD_DEBOUNCE_MS = 5000;
+
+async function buildDoc(ctx: PluginContext, kind: DocKind): Promise<CachedDocument> {
+	const settings = await loadSettings(ctx);
+	const doc = kind === "llms" ? await buildLlms(ctx, settings) : await buildNews(ctx, settings);
+	await ctx.kv.set(DOC_KEY[kind], doc);
+	return doc;
+}
+
+const pendingRebuild = new Set<DocKind>();
+let rebuildScheduled = false;
+const coldBuilds = new Map<DocKind, Promise<CachedDocument>>();
+
+/** Rebuild these documents in the background, after the response (debounced). */
+export function scheduleRebuild(ctx: PluginContext, kinds: DocKind[], delayMs = REBUILD_DEBOUNCE_MS): void {
+	for (const kind of kinds) pendingRebuild.add(kind);
+	if (rebuildScheduled || !pendingRebuild.size) return;
+	rebuildScheduled = true;
+	after(async () => {
+		await new Promise((resolve) => setTimeout(resolve, delayMs));
+		const kinds = [...pendingRebuild];
+		pendingRebuild.clear();
+		rebuildScheduled = false;
+		for (const kind of kinds) {
+			try {
+				await buildDoc(ctx, kind);
+			} catch (error) {
+				ctx.log.error(`Discovery: rebuilding ${kind} failed`, { error: String(error) });
+			}
+		}
+	});
+}
+
+/** The stored document; a stale one is served while a rebuild is scheduled. */
+export async function readDoc(ctx: PluginContext, kind: DocKind): Promise<CachedDocument> {
+	const hit = await ctx.kv.get<CachedDocument>(DOC_KEY[kind]);
+	if (hit?.body) {
+		if (Date.now() - Date.parse(hit.builtAt) >= DOC_TTL[kind]) scheduleRebuild(ctx, [kind], 0);
+		return hit;
+	}
+	let cold = coldBuilds.get(kind);
+	if (!cold) {
+		cold = buildDoc(ctx, kind).finally(() => coldBuilds.delete(kind));
+		coldBuilds.set(kind, cold);
+	}
+	return cold;
+}
+
+/** Rebuild now (admin "Rebuild now"). */
+export async function rebuildNow(ctx: PluginContext, kind: DocKind): Promise<CachedDocument> {
+	return buildDoc(ctx, kind);
+}
+
+// ── Per-entry Markdown ───────────────────────────────────────────
+
+export interface MarkdownDocument {
+	body: string;
+	tokens: number;
+	pageUrl: string;
+	markdownUrl: string;
+}
+
+/**
+ * Find the published entry a site path belongs to: the pack-wide reverse
+ * resolver (core/content-url.ts matchEntryPath), which knows the site's
+ * `urls` overrides and otherwise uses EmDash's own routing, and only
+ * answers when the entry's canonical URL is this path.
+ */
+async function resolveEntry(ctx: PluginContext, pagePath: string): Promise<{ collection: CollectionSchemaInfo; id: string; url: string } | null> {
+	const match = await matchEntryPath(ctx, pagePath);
+	if (!match) return null;
+	const collection = await ctx.schema?.getCollection(match.collection);
+	if (!collection) return null;
+	return { collection, id: match.id, url: absoluteUrl(match.path, siteOrigin(ctx)) };
+}
+
+export async function buildMarkdown(ctx: PluginContext, settings: DiscoverySettings, pagePath: string): Promise<MarkdownDocument | null> {
+	if (!settings.llms.markdown) return null;
+	const resolved = await resolveEntry(ctx, pagePath);
+	if (!resolved || !selected(settings.llms.collections, resolved.collection.slug)) return null;
+	if (!settings.llms.collections.length && resolved.collection.hidden) return null;
+	const item = await ctx.content?.get(resolved.collection.slug, resolved.id);
+	if (!item || item.status !== "published" || item.seo?.noIndex) return null;
+
+	const origin = siteOrigin(ctx);
+	const absolute = (href: string) => {
+		if (href.startsWith("#") || /^[a-z][a-z0-9+.-]*:/i.test(href)) return href;
+		try {
+			return new URL(href, `${origin}/`).href;
+		} catch {
+			return href;
+		}
+	};
+	const body = resolved.collection.fields
+		.filter((f) => f.type === "portableText")
+		.sort((a, b) => a.sortOrder - b.sortOrder)
+		.map((f) => portableTextToMarkdown(item.data[f.slug], { absolute }))
+		.filter(Boolean)
+		.join("\n\n");
+
+	const markdown = `${frontmatter({
+		title: entryTitle(resolved.collection, item),
+		url: resolved.url,
+		published: item.publishedAt ? (parseDate(item.publishedAt)?.toISOString() ?? undefined) : undefined,
+		updated: parseDate(item.updatedAt)?.toISOString() ?? undefined,
+		sources: [resolved.url],
+		license: settings.llms.license || undefined,
+	})}\n${body}\n`;
+	return { body: markdown, tokens: estimateTokens(markdown), pageUrl: resolved.url, markdownUrl: markdownUrl(resolved.url) };
+}