@coywolf/emdash 0.0.0-stage → 0.35.14

package/src/core/features.ts

@@ -0,0 +1,392 @@
+/**
+ * Feature switches. Every Coywolf Pack feature can be turned off on the
+ * Features admin page; the choices are one plugin setting ("features", an
+ * object of id → boolean). Hooks and routes read it through the plugin
+ * context; middleware and Astro block renderers, which run outside it, read
+ * the same option row from D1 with a per-isolate cache (five minutes).
+ *
+ * That one query also reads every registered site setting and a few pack
+ * option rows (the settings generation, the deployed version), so the
+ * settings a page render needs cost no query of their own. A save through
+ * the pack's admin routes clears this isolate's cache at once and records a
+ * new settings generation; other isolates see it on their next read and drop
+ * every cache keyed on settingsEpoch() (see src/core/generation.ts).
+ */
+import type { FeatureDef } from "./module.js";
+import { workerEnv } from "../shared.js";
+import { batchedAll } from "./d1-batch.js";
+import { noteReadFailure } from "./read-failures.js";
+
+export const PLUGIN_ID = "coywolf-pack";
+export const FEATURES_SETTING = "features";
+const OPTION_NAME = `plugin:${PLUGIN_ID}:settings:${FEATURES_SETTING}`;
+
+export type FeatureMap = Record<string, boolean>;
+
+/** Every feature the pack knows about. Modules register theirs at import time. */
+const catalog = new Map<string, FeatureDef>();
+
+export function registerFeatures(defs: FeatureDef[]): void {
+	for (const def of defs) catalog.set(def.id, def);
+}
+
+export function featureCatalog(): FeatureDef[] {
+	return [...catalog.values()];
+}
+
+const parentOf = (id: string) => (id.includes(".") ? id.slice(0, id.indexOf(".")) : null);
+
+/**
+ * The stored choice of a feature's legacy ids (FeatureDef.replaces): the
+ * first one present in the map wins. A legacy sub-feature ("a.b") counted
+ * only while its parent was on, so its parent's state (stored, else the
+ * parent's default) is applied too. Undefined when none is stored.
+ */
+export function legacyChoice(stored: FeatureMap | null | undefined, def: FeatureDef): boolean | undefined {
+	if (!stored || !def.replaces) return undefined;
+	for (const legacy of def.replaces) {
+		if (typeof stored[legacy] !== "boolean") continue;
+		const parent = parentOf(legacy);
+		// A parent that's no longer in the catalog (and wasn't stored) doesn't hold the choice back.
+		const parentOn = !parent || (stored[parent] ?? (catalog.has(parent) ? (catalog.get(parent)?.default ?? false) : true));
+		return stored[legacy] && parentOn;
+	}
+	return undefined;
+}
+
+/**
+ * Stored choices over catalog defaults. A feature with no stored choice
+ * takes its legacy ids' choice (FeatureDef.replaces), then its default. A
+ * sub-feature ("a.b") is on only when its parent ("a") is on too.
+ */
+export function resolveFeatures(stored: FeatureMap | null | undefined): FeatureMap {
+	const out: FeatureMap = {};
+	for (const def of catalog.values()) out[def.id] = stored?.[def.id] ?? legacyChoice(stored, def) ?? def.default ?? false;
+	for (const id of Object.keys(out)) {
+		const parent = parentOf(id);
+		if (parent && parent in out && !out[parent]) out[id] = false;
+	}
+	return out;
+}
+
+export function isOn(features: FeatureMap, id: string): boolean {
+	return features[id] ?? false;
+}
+
+// ── Plugin context (hooks, routes) ───────────────────────────────
+
+interface SettingsCtx {
+	settings: { get<T>(key: string): Promise<T | null | undefined> };
+}
+
+export async function ctxFeatures(ctx: SettingsCtx): Promise<FeatureMap> {
+	let stored: FeatureMap | null | undefined;
+	try {
+		stored = await ctx.settings.get<FeatureMap>(FEATURES_SETTING);
+	} catch (error) {
+		// A page hook that can't read the switches adds nothing to the page: keep that page out of the edge cache.
+		noteReadFailure("feature switches (plugin context)");
+		throw error;
+	}
+	return remember(resolveFeatures(stored));
+}
+
+/** The switches most recently read in this isolate (null before the first read). */
+let lastKnown: FeatureMap | null = null;
+function remember(features: FeatureMap): FeatureMap {
+	lastKnown = features;
+	return features;
+}
+
+/**
+ * Synchronous view of the switches, for EmDash's admin manifest (sidebar
+ * pages and dashboard widgets), which reads the plugin's page list on every
+ * admin request. The pack middleware reads the switches before EmDash's
+ * routes run, so this is current; before any read it returns null.
+ */
+export function knownFeatures(): FeatureMap | null {
+	return lastKnown;
+}
+
+/**
+ * Like ctxFeatures, but shares the per-isolate cache with siteFeatures so
+ * hooks that run on every page view (page:metadata, page:fragments) don't
+ * add a settings read to each render.
+ */
+export async function cachedCtxFeatures(ctx: SettingsCtx): Promise<FeatureMap> {
+	if (cached && Date.now() - cached.at < TTL_MS) return cached.features;
+	const started = generation;
+	const features = await ctxFeatures(ctx);
+	// Same guard as queryOptions: a save in this isolate while this read ran (invalidateFeatures) makes it stale.
+	if (generation === started) cached = { features, at: Date.now() };
+	return features;
+}
+
+/** For public routes: like requireFeature, but from the per-isolate cache (no settings read on most requests). */
+export async function requireCachedFeature(ctx: SettingsCtx, id: string): Promise<void> {
+	if (!isOn(await cachedCtxFeatures(ctx), id)) {
+		const { PluginRouteError } = await import("emdash");
+		throw PluginRouteError.notFound("This feature is turned off (Plugins → Coywolf Pack).");
+	}
+}
+
+// ── Outside the plugin context (middleware, Astro components) ────
+
+/** How long this isolate trusts its read of the switches, settings and generation. */
+export const FEATURES_TTL_MS = 5 * 60_000;
+const TTL_MS = FEATURES_TTL_MS;
+/**
+ * `settings` is set when the read came from D1 (siteFeatures), which also
+ * reads the registered settings; `keys` are the settings that read asked for;
+ * `options` are the raw values of the registered option rows (registerSiteOption).
+ */
+let cached: { features: FeatureMap; at: number; settings?: Map<string, unknown>; keys?: Set<string>; options?: Map<string, string> } | null = null;
+/** A D1 read in progress: concurrent cache misses in this isolate share it. */
+let reading: Promise<SiteOptions> | null = null;
+/** Bumped by invalidateFeatures, so a read that started before a save isn't cached. */
+let generation = 0;
+
+/**
+ * Bumped whenever settings may have changed: a save in this isolate
+ * (invalidateFeatures) or a new settings generation seen in D1 (a save in
+ * another isolate). Per-isolate caches of settings-derived data store the
+ * epoch they were read at and are dropped when it moves (isCurrent).
+ */
+let epoch = 0;
+export function settingsEpoch(): number {
+	return epoch;
+}
+
+/** A per-isolate cache entry is usable while the settings epoch hasn't moved and it's younger than `maxAgeMs`. */
+export function isCurrent(entry: { epoch: number; at: number } | null | undefined, maxAgeMs: number): boolean {
+	return Boolean(entry && entry.epoch === epoch && Date.now() - entry.at < maxAgeMs);
+}
+
+/**
+ * Settings read on most page renders, registered up front so the first read
+ * of an isolate already includes them (a key registered after that read costs
+ * a second query). Modules still call registerSiteSetting for their own keys.
+ */
+const PRELOADED_SETTINGS = [
+	// Content blocks, Headings, Breadcrumbs (+ its legacy key), Code blocks, Reviews.
+	"contentBlocks",
+	"customBlocksPodcast",
+	"headings",
+	"breadcrumbs",
+	"codeBlocksTheme",
+	"reviewsStyle",
+	// Clean image URLs, Page cache, Search, Videos posters.
+	"imagesMediaHost",
+	"pageCacheMaxAgeDays",
+	"pageCacheRefreshDays",
+	"pageCacheWarm",
+	"searchVersion",
+	"videosMirroredPosters",
+	// Coywolf Files.
+	"filesBase",
+	"filesPublicBaseUrl",
+	"filesScheme",
+	"filesAccent",
+	// Schema & Social (src/schema/module.ts schemaSettingsSchema).
+	"schemaSearchUrl",
+	"schemaAuthorUrlPattern",
+	"schemaBreadcrumbHome",
+	"schemaRobotsMaxImage",
+	"schemaRobotsMaxSnippet",
+	"schemaRobotsMaxVideo",
+	"schemaRobotsNofollow",
+	"schemaOgLocale",
+	// Videos player settings (src/videos/store.ts publicConfig).
+	"videosCustomerSubdomain",
+	"videosAccentColor",
+	"videosBackgroundColor",
+	"videosLightEmbed",
+	"videosDisplay",
+	// Discovery.
+	"discoverySettings",
+];
+
+/**
+ * Other plugin settings read in the same query as the switches, sharing
+ * their per-isolate cache, so middleware, page hooks and Astro renderers that
+ * need them on every request add no query (e.g. the search content version,
+ * the code block theme, the review style).
+ */
+const siteSettingKeys = new Set<string>(PRELOADED_SETTINGS);
+export function registerSiteSetting(key: string): void {
+	siteSettingKeys.add(key);
+}
+
+/** Whole option rows (not plugin settings) read in the same query, raw (see siteOption). */
+const siteOptionNames = new Set<string>();
+export function registerSiteOption(name: string): void {
+	siteOptionNames.add(name);
+}
+
+const settingOption = (key: string) => `plugin:${PLUGIN_ID}:settings:${key}`;
+
+/** Forget cached switches and registered settings (call after saving them). */
+export function invalidateFeatures(): void {
+	cached = null;
+	reading = null;
+	generation++;
+	epoch++;
+}
+
+/** The option row last read for the settings generation, to notice saves made in other isolates. */
+let lastGeneration: string | null | undefined;
+/** Name of the settings-generation row (written by src/core/generation.ts). */
+export const GENERATION_OPTION = `plugin:${PLUGIN_ID}:state:settingsGeneration`;
+registerSiteOption(GENERATION_OPTION);
+
+/**
+ * Read the switches straight from D1. Fails closed (all off) if the database
+ * can't be read, and notes the failure (src/core/read-failures.ts), so the
+ * page rendered with them isn't edge-cached.
+ */
+export async function siteFeatures(database = "DB", fresh = false): Promise<FeatureMap> {
+	if (!fresh && cached && Date.now() - cached.at < TTL_MS) return cached.features;
+	return (await readSiteOptions(database)).features;
+}
+
+/** A D1 binding name, or the binding itself (for callers that already have it). */
+type Database = string | D1Database;
+
+interface SiteOptions {
+	features: FeatureMap;
+	settings: Map<string, unknown>;
+	/** The registered settings this read asked for. */
+	keys: Set<string>;
+	/** False when D1 couldn't be read (features are then all off and settings empty; each caller notes it, see readSiteOptions). */
+	ok: boolean;
+}
+
+function readSiteOptions(database: Database): Promise<SiteOptions> {
+	if (!reading) {
+		const read = queryOptions(database).finally(() => {
+			if (reading === read) reading = null;
+		});
+		reading = read;
+	}
+	// Noted for each caller handed a failed read (concurrent requests share one), not once per query.
+	return reading.then((read) => {
+		if (!read.ok) noteReadFailure("feature switches and settings");
+		return read;
+	});
+}
+
+async function queryOptions(database: Database): Promise<SiteOptions> {
+	let stored: FeatureMap | null = null;
+	const settings = new Map<string, unknown>();
+	const options = new Map<string, string>();
+	const keys = new Set(siteSettingKeys);
+	const optionNames = new Set(siteOptionNames);
+	const started = generation;
+	try {
+		const db = typeof database === "string" ? ((await workerEnv())[database] as D1Database | undefined) : database;
+		const names = [OPTION_NAME, ...[...keys].map(settingOption), ...optionNames];
+		// With the pack's other reads of this tick (the request's redirect lookup): one D1 batch.
+		const rows = db
+			? await batchedAll<{ name: string; value: string }>(db, db.prepare(`SELECT name, value FROM options WHERE name IN (${names.map(() => "?").join(",")})`).bind(...names))
+			: [];
+		for (const row of rows) {
+			if (!row.value) continue;
+			if (optionNames.has(row.name)) options.set(row.name, row.value);
+			else if (row.name === OPTION_NAME) stored = JSON.parse(row.value) as FeatureMap;
+			else {
+				try {
+					settings.set(row.name.slice(settingOption("").length), JSON.parse(row.value));
+				} catch {
+					// An unreadable setting reads as unset.
+				}
+			}
+		}
+	} catch (error) {
+		console.error("coywolf-pack: could not read feature switches", error);
+		return { features: resolveFeatures({}), settings, keys, ok: false };
+	}
+	const features = remember(resolveFeatures(stored));
+	// A save in another isolate since the last read: drop this isolate's settings-derived caches.
+	const seen = options.get(GENERATION_OPTION) ?? null;
+	if (lastGeneration !== undefined && seen !== lastGeneration && savedGeneration(seen) !== savedGeneration(lastGeneration)) epoch++;
+	lastGeneration = seen;
+	// A save in this isolate while the query ran (invalidateFeatures) makes this read stale: don't cache it.
+	if (generation === started) cached = { features, at: Date.now(), settings, keys, options };
+	return { features, settings, keys, ok: true };
+}
+
+/** The generation id in a settings-generation row ("settled" changes don't count as a new save). */
+function savedGeneration(raw: string | null | undefined): string | null {
+	if (!raw) return null;
+	try {
+		const value = JSON.parse(raw) as { id?: unknown };
+		return typeof value?.id === "string" ? value.id : raw;
+	} catch {
+		return raw;
+	}
+}
+
+/**
+ * A registered option row (registerSiteOption) from the last read of this
+ * isolate, raw. Undefined when there's no current read with it (call
+ * siteFeatures first); null when the row doesn't exist.
+ */
+export function siteOption(name: string): string | null | undefined {
+	if (!cached?.options || Date.now() - cached.at >= TTL_MS) return undefined;
+	return cached.options.get(name) ?? null;
+}
+
+/** Update a registered option row in this isolate's cache after writing it. */
+export function rememberSiteOption(name: string, raw: string | null): void {
+	if (!cached?.options) return;
+	if (raw === null) cached.options.delete(name);
+	else cached.options.set(name, raw);
+	if (name === GENERATION_OPTION) lastGeneration = raw;
+}
+
+/**
+ * The registered settings from the per-isolate cache, or a fresh read when
+ * the cache is old or was read before `key` was registered (a module imported
+ * after the first read of this isolate). Null when D1 can't be read (a noted
+ * read failure, see src/core/read-failures.ts).
+ */
+async function siteSettings(key: string, database: Database): Promise<Map<string, unknown> | null> {
+	registerSiteSetting(key);
+	if (cached?.settings && cached.keys?.has(key) && Date.now() - cached.at < TTL_MS) return cached.settings;
+	let read = await readSiteOptions(database);
+	// A read that was already in flight may have been started before `key` was registered.
+	if (read.ok && !read.keys.has(key)) read = await readSiteOptions(database);
+	return read.ok ? read.settings : null;
+}
+
+/** A setting registered with registerSiteSetting, from the switches' per-isolate cache (null when unset). */
+export async function siteSetting<T>(key: string, database = "DB"): Promise<T | null> {
+	return (((await siteSettings(key, database))?.get(key) as T | undefined) ?? null);
+}
+
+/**
+ * Like siteSetting, but tells an unset setting (`{ value: null }`) from one
+ * that couldn't be read (null), for callers that keep their last value or
+ * skip caching a default when D1 is unavailable.
+ */
+export async function readSiteSetting<T = unknown>(key: string, database: Database = "DB"): Promise<{ value: T | null } | null> {
+	const settings = await siteSettings(key, database);
+	return settings ? { value: (settings.get(key) as T | undefined) ?? null } : null;
+}
+
+/** Update a registered setting in this isolate's cache after writing it (other isolates see it within FEATURES_TTL_MS). */
+export function rememberSiteSetting(key: string, value: unknown): void {
+	cached?.settings?.set(key, value);
+}
+
+export async function siteFeatureOn(id: string, database?: string): Promise<boolean> {
+	return isOn(await siteFeatures(database), id);
+}
+
+/** For routes: answer 404 when the feature is off, so a disabled module looks absent. */
+export async function requireFeature(ctx: SettingsCtx, id: string): Promise<void> {
+	if (!isOn(await ctxFeatures(ctx), id)) {
+		const { PluginRouteError } = await import("emdash");
+		throw PluginRouteError.notFound("This feature is turned off (Plugins → Coywolf Pack).");
+	}
+}

package/src/core/generation.ts

@@ -0,0 +1,88 @@
+/**
+ * The settings generation: one option row the pack middleware rewrites after
+ * every successful pack admin write (settings, redirects, schema, videos…).
+ * Every isolate reads it in the feature switches' query (src/core/features.ts),
+ * so a save made in one isolate reaches the others on their next read
+ * (FEATURES_TTL_MS at most) without a query of its own, and they drop every
+ * cache keyed on settingsEpoch().
+ *
+ * Until then another isolate may still render a page with the old settings,
+ * and the page cache would keep that page for days. So a save that cleared
+ * the page cache asks for a second, "settling" purge once every isolate must
+ * have seen it: the first request after that time, in any isolate, claims it
+ * (a compare-and-set on the row, so only one does) and purges again.
+ */
+import type { PurgeScope } from "../pageCache/lib.js";
+import { FEATURES_TTL_MS, GENERATION_OPTION, rememberSiteOption, siteOption } from "./features.js";
+
+/** Margin after the switches' lifetime before the settling purge, for reads that were in flight at save time. */
+const SETTLE_MARGIN_MS = 15_000;
+
+export interface GenerationRow {
+	/** New on every save. */
+	id: string;
+	/** When the save happened (ms since the epoch). */
+	at: number;
+	/** The purge to repeat once every isolate has the new settings; absent when nothing needs it (or it's done). */
+	settle?: PurgeScope;
+}
+
+export function parseGeneration(raw: string | null | undefined): GenerationRow | null {
+	if (!raw) return null;
+	try {
+		const row = JSON.parse(raw) as GenerationRow;
+		return row && typeof row.id === "string" && typeof row.at === "number" ? row : null;
+	} catch {
+		return null;
+	}
+}
+
+/** Both purges in one: every path prefix (or tag) of both, or everything when either clears everything or they're of different kinds. */
+export function mergeScopes(a: PurgeScope | null | undefined, b: PurgeScope | null | undefined): PurgeScope | null {
+	if (!a || !b) return a ?? b ?? null;
+	if ("pathPrefixes" in a && "pathPrefixes" in b) return { pathPrefixes: [...new Set([...a.pathPrefixes, ...b.pathPrefixes])] };
+	if ("tags" in a && "tags" in b) return { tags: [...new Set([...a.tags, ...b.tags])] };
+	return { purgeEverything: true };
+}
+
+/**
+ * Record a save: a new generation, and the purge to settle later when the
+ * save purged the page cache. A settling purge still pending from an earlier
+ * save is kept (merged), and its clock restarts: isolates may have read the
+ * earlier generation just before this save.
+ */
+export async function recordSettingsChange(db: D1Database, settle: PurgeScope | null, now = Date.now()): Promise<GenerationRow> {
+	const current = await db.prepare("SELECT value FROM options WHERE name = ?").bind(GENERATION_OPTION).first<{ value: string }>();
+	const pending = mergeScopes(parseGeneration(current?.value)?.settle, settle);
+	const row: GenerationRow = { id: crypto.randomUUID(), at: now, ...(pending ? { settle: pending } : {}) };
+	const raw = JSON.stringify(row);
+	await db
+		.prepare("INSERT INTO options (name, value) VALUES (?, ?) ON CONFLICT(name) DO UPDATE SET value = excluded.value")
+		.bind(GENERATION_OPTION, raw)
+		.run();
+	rememberSiteOption(GENERATION_OPTION, raw);
+	return row;
+}
+
+/** True when the last read generation has a settling purge whose time has come. */
+export function settleDue(row: GenerationRow | null, now = Date.now()): row is GenerationRow & { settle: PurgeScope } {
+	return Boolean(row?.settle && now - row.at > FEATURES_TTL_MS + SETTLE_MARGIN_MS);
+}
+
+/**
+ * Claim the settling purge of the generation this isolate last read: returns
+ * its scope when this call won it (the caller purges), null otherwise. Reads
+ * nothing: the row comes from the switches' cached query; the claim is one
+ * conditional write, and only when a purge is due.
+ */
+export async function claimSettle(db: D1Database, now = Date.now()): Promise<PurgeScope | null> {
+	const raw = siteOption(GENERATION_OPTION);
+	const row = parseGeneration(raw);
+	if (!raw || !settleDue(row, now)) return null;
+	const { settle, ...rest } = row;
+	const next = JSON.stringify(rest);
+	// Only one isolate claims it, and a newer save (another row) isn't touched.
+	rememberSiteOption(GENERATION_OPTION, next);
+	const result = await db.prepare("UPDATE options SET value = ? WHERE name = ? AND value = ?").bind(next, GENERATION_OPTION, raw).run();
+	return (result.meta?.changes ?? 0) > 0 ? settle : null;
+}

package/src/core/guide-content.ts

@@ -0,0 +1,166 @@
+/**
+ * Step-by-step guides for the API keys and tokens some features need, as
+ * static HTML strings (trusted: written here, never from user data). Shown in
+ * a closed <details> next to each credential field on module pages
+ * (src/admin/guides.tsx) and on EmDash's generic plugin Settings page, where
+ * the admin enhancement script (src/core/settings-enhance.ts) swaps each
+ * field's plain-text description for the same guide.
+ *
+ * Kept free of imports so tests can load it directly.
+ */
+
+export type GuideId = "anthropic" | "openai" | "gemini" | "workers-ai" | "r2" | "stream" | "radar" | "media-host" | "images-token";
+
+export interface Guide {
+	summary: string;
+	/** Each step's HTML. */
+	steps: string[];
+	/** Optional note under the steps (HTML). */
+	note?: string;
+}
+
+const link = (href: string, text: string) => `<a href="${href}" target="_blank" rel="noreferrer" class="text-kumo-link underline">${text}</a>`;
+const code = (text: string) => `<code class="rounded bg-kumo-tint px-1 text-xs">${text}</code>`;
+const b = (text: string) => `<strong class="font-medium">${text}</strong>`;
+
+/** Creating a Cloudflare API token: the steps every token guide shares. */
+const cloudflareTokenSteps = (permission: string, zone = false) => [
+	`Sign in to the ${link("https://dash.cloudflare.com/profile/api-tokens", "Cloudflare dashboard → My Profile → API Tokens")}.`,
+	`Select ${b("Create Token")}, then ${b("Create Custom Token → Get started")}.`,
+	"Name it after this site so you'll recognize it later.",
+	`Under Permissions, choose ${permission}.`,
+	`Under Account Resources, choose ${b("Include → your account")}.`,
+	...(zone ? [`Under Zone Resources, choose ${b("Include → Specific zone → your site's domain")}.`] : []),
+	`Select ${b("Continue to summary")}, then ${b("Create Token")}.`,
+	"Copy the token right away. Cloudflare shows it only once.",
+];
+
+export const GUIDES: Record<GuideId, Guide> = {
+	anthropic: {
+		summary: "How to get an Anthropic API key",
+		steps: [
+			`Sign in to the ${link("https://platform.claude.com/settings/keys", "Claude Console")} (create an account if you don't have one).`,
+			`Add a payment method or credits under ${b("Billing")}. Keys don't work without them.`,
+			`Go to ${b("API Keys")} and select ${b("Create Key")}. Name it after this site.`,
+			"Copy the key (it starts with sk-ant-). It's shown only once.",
+			"Paste it into the API key field and save.",
+		],
+		note: "Each analyzed entry or image is one model call, billed by Anthropic. The daily call limit caps what you spend.",
+	},
+	openai: {
+		summary: "How to get an OpenAI API key",
+		steps: [
+			`Sign in to the ${link("https://platform.openai.com/api-keys", "OpenAI Platform → API keys")}.`,
+			`Add a payment method or credits under ${b("Settings → Billing")}. Keys don't work without them.`,
+			`Select ${b("Create new secret key")}, name it after this site, and keep the default permissions.`,
+			"Copy the key (it starts with sk-). It's shown only once.",
+			"Paste it into the API key field and save.",
+		],
+		note: "Each analyzed entry or image is one model call, billed by OpenAI. The daily call limit caps what you spend.",
+	},
+	gemini: {
+		summary: "How to get a Google Gemini API key",
+		steps: [
+			`Sign in to ${link("https://aistudio.google.com/apikey", "Google AI Studio → API keys")} with a Google account.`,
+			`Select ${b("Create API key")} and pick (or create) a Google Cloud project.`,
+			"Copy the key.",
+			"Paste it into the API key field and save.",
+		],
+		note: "The free tier has low rate limits. For steady use, turn on billing for the project in Google AI Studio.",
+	},
+	"workers-ai": {
+		summary: "How to connect Workers AI (no key needed)",
+		steps: [
+			`Open your site's ${code("wrangler.jsonc")}.`,
+			`Add ${code('"ai": { "binding": "AI" }')} at the top level.`,
+			"Deploy the site. This page then shows the binding as connected.",
+		],
+		note: "Workers AI is billed to your Cloudflare account, with a daily free allowance.",
+	},
+	r2: {
+		summary: "How to get the R2 account ID and keys",
+		steps: [
+			`In the ${link("https://dash.cloudflare.com/?to=/:account/r2/overview", "Cloudflare dashboard → R2")}, copy your ${b("Account ID")} (shown on the R2 overview page) into R2 account ID on the Files page → Settings.`,
+			`Under Buckets, note the name of the bucket bound as ${code("MEDIA")} in your ${code("wrangler.jsonc")}. Enter it as the R2 bucket name.`,
+			`Select ${b("Manage API tokens")} (on the R2 overview page), then ${b("Create Account API token")}.`,
+			`Choose the ${b("Object Read &amp; Write")} permission and ${b("Apply to specific buckets only")} → that bucket.`,
+			`Select ${b("Create API Token")}. Copy the ${b("Access Key ID")} and ${b("Secret Access Key")}. The secret is shown only once.`,
+			"Paste them into their fields and save. The secret is stored encrypted.",
+		],
+	},
+	stream: {
+		summary: "How to get the Stream account ID and API token",
+		steps: [
+			`In the ${link("https://dash.cloudflare.com/?to=/:account/stream", "Cloudflare dashboard → Stream")}, copy your ${b("Account ID")} (in the right-hand column, or from the address bar after dash.cloudflare.com/) into Cloudflare account ID on the Videos page → Settings.`,
+			...cloudflareTokenSteps(b("Account → Stream → Edit")),
+			"Paste the token into Stream API token and save. It's stored encrypted.",
+		],
+		note: `Or set them as Worker variables instead: ${code("CF_ACCOUNT_ID")}, and the token with ${code("npx wrangler secret put CF_STREAM_TOKEN")}.`,
+	},
+	radar: {
+		summary: "How to get a Cloudflare Radar API token",
+		steps: [...cloudflareTokenSteps(b("Account → Radar → Read")), "Paste the token into Cloudflare Radar API token and save. It's stored encrypted."],
+		note: `Radar's API is free. Or set the token as a Worker secret instead: ${code("npx wrangler secret put RADAR_API_TOKEN")}.`,
+	},
+	"media-host": {
+		summary: "How to set up a media host by hand in the Cloudflare dashboard",
+		steps: [
+			`Find the R2 bucket bound as ${code("MEDIA")} in your site's ${code("wrangler.jsonc")} (its ${code("bucket_name")}). The media host serves that bucket, at a subdomain of the site's own domain, such as ${code("media.example.com")}.`,
+			`Turn on Image Transformations: ${link("https://dash.cloudflare.com/?to=/:account/images/transformations", "Cloudflare dashboard → Images → Transformations")}, find the site's domain and select ${b("Enable for zone")}. Leave ${b("Resize images from any origin")} off: the media host is on the same domain.`,
+			`Connect the domain to the bucket: ${link("https://dash.cloudflare.com/?to=/:account/r2/overview", "R2")} → the media bucket → ${b("Settings → Custom Domains → Add")}. Enter ${code("media.example.com")}, set the minimum TLS version to 1.2, and confirm. Cloudflare adds the DNS record; the certificate takes a few minutes.`,
+			`Add the first URL rewrite rule: the site's domain → ${b("Rules → Overview → Create rule → URL Rewrite Rule")}. Name it ${code("media.example.com: /s/&lt;W&gt;x&lt;H&gt;/&lt;file&gt; → cropped resize (Coywolf Pack clean image URLs)")}. Choose ${b("Custom filter expression → Edit expression")} and enter ${code('(http.host eq "media.example.com" and http.request.uri.path wildcard "/s/*x*/*")')}. Under Path, choose ${b("Rewrite to… → Dynamic")} and enter ${code('wildcard_replace(http.request.uri.path, "/s/*x*/*", "/cdn-cgi/image/width=${1},height=${2},fit=cover,format=auto,quality=85/${3}")')}. Leave Query as is and deploy.`,
+			`Add the second rule, named ${code("media.example.com: /s/&lt;W&gt;/&lt;file&gt; → resize to width (Coywolf Pack clean image URLs)")}, with the expression ${code('(http.host eq "media.example.com" and http.request.uri.path wildcard "/s/*/*" and not http.request.uri.path wildcard "/s/*x*/*")')} and the dynamic path ${code('wildcard_replace(http.request.uri.path, "/s/*/*", "/cdn-cgi/image/width=${1},format=auto,quality=85/${2}")')}. Deploy it.`,
+			`Turn on Smart Tiered Cache (free): the site's domain → ${b("Caching → Tiered Cache")} → ${b("Smart Tiered Caching")}. A data center that hasn't cached an image yet then asks a nearby Cloudflare cache instead of going back to R2.`,
+			`Use your own host name in place of ${code("media.example.com")} everywhere (keep the names exactly as shown otherwise: Set up media host recognizes its rules by name).`,
+			`Enter the host as the Media host on this page and select ${b("Check")}. When every check passes, save. Or set it in ${code("astro.config.mjs")}: ${code('coywolfPlugin({ images: { cdn: "https://media.example.com" } })')}.`,
+		],
+		note: "Cloudflare's Free plan includes 5,000 unique image transformations a month (each new size of each image counts once a month). Beyond that, transformations need a paid Cloudflare Images plan.",
+	},
+	"images-token": {
+		summary: "How to get a Cloudflare API token for Set up media host",
+		steps: [
+			`In the ${link("https://dash.cloudflare.com/", "Cloudflare dashboard")}, open the site's domain and copy the ${b("Account ID")} from the right-hand column (API section) into Cloudflare account ID.`,
+			...cloudflareTokenSteps(
+				`these six: ${b("Zone → Zone → Read")}, ${b("Zone → Zone Settings → Edit")}, ${b("Zone → Transform Rules → Edit")}, ${b("Zone → DNS → Edit")}, ${b("Account → Workers R2 Storage → Edit")} and ${b("Account → Account Rulesets → Read")}`,
+				true,
+			),
+			"Paste the token into Cloudflare API token. Save it to keep it (stored encrypted), or leave it unsaved to use it just this once.",
+		],
+		note: `The token is used only for the setup, and only with api.cloudflare.com. You can delete it in Cloudflare afterward. Or set it as a Worker secret instead: ${code("npx wrangler secret put IMAGES_API_TOKEN")}.`,
+	},
+};
+
+/**
+ * What the generic Settings page shows for each secret once enhanced: a short
+ * plain description, then the guides (closed). Keys match SECRET_SETTINGS.
+ */
+export const SETTINGS_PAGE_GUIDES: Record<string, { intro: string; guides: GuideId[] }> = {
+	aiApiKey: {
+		intro: "For Anthropic, OpenAI or Gemini (Workers AI needs no key). The provider and model settings are on the AI Enrichment page.",
+		guides: ["anthropic", "openai", "gemini"],
+	},
+	filesR2SecretAccessKey: {
+		intro: "For large uploads. The account ID, access key ID and bucket name go on the Files page → Settings.",
+		guides: ["r2"],
+	},
+	videosApiToken: {
+		intro: "Or set the CF_STREAM_TOKEN Worker secret. The account ID goes on the Videos page → Settings.",
+		guides: ["stream"],
+	},
+	imagesApiToken: {
+		intro: "Optional. Only for Set up media host on the Clean Image URLs page. Or set the IMAGES_API_TOKEN Worker secret.",
+		guides: ["images-token"],
+	},
+	robotsRadarToken: {
+		intro: "Optional. Keeps the crawler list current from Cloudflare Radar each week. Or set the RADAR_API_TOKEN Worker secret.",
+		guides: ["radar"],
+	},
+};
+
+/** A guide as a closed <details> (HTML), styled with the admin's own classes. */
+export function guideHtml(guide: Guide): string {
+	const steps = guide.steps.map((s) => `<li>${s}</li>`).join("");
+	return `<details class="rounded-md border border-kumo-line text-sm"><summary class="cursor-pointer px-3 py-2 font-medium" style="display:list-item">${guide.summary}</summary><div class="space-y-2 border-t border-kumo-line px-3 py-3"><ol class="space-y-1.5" style="list-style:decimal;padding-inline-start:1.25rem">${steps}</ol>${
+		guide.note ? `<p class="text-xs text-kumo-subtle">${guide.note}</p>` : ""
+	}</div></details>`;
+}