@coywolf/emdash 0.0.0-stage → 0.35.14

package/src/breadcrumbs/pack.ts

@@ -0,0 +1,113 @@
+/**
+ * Breadcrumb Nav module: an accessible breadcrumb trail as a Portable Text
+ * block (`coywolf-breadcrumbs`) and as a theme component (`Breadcrumbs` from
+ * "@coywolf/emdash/astro"). Until 0.6.0 this was the `headings.breadcrumbs`
+ * sub-feature of Headings & TOC; the feature switch (FeatureDef.replaces) and
+ * the settings (./settings.ts) fall back to the old stored values, and the
+ * block type, component and stored data are unchanged.
+ */
+import type { PluginContext } from "emdash";
+import { definePluginRoute } from "emdash";
+import { z } from "zod";
+
+import { registerFeatures } from "../core/features.js";
+import type { FeatureDef, PackModule } from "../core/module.js";
+import { parseInput } from "../shared.js";
+import { SETTINGS_KEY, ctxBreadcrumbsSettings, invalidateBreadcrumbsSettings, normalizeSettings } from "./settings.js";
+import { BREADCRUMBS_BLOCK, stampBreadcrumbs } from "./stamp.js";
+import { capturePage } from "./trail.js";
+
+/** No build-time options yet: defaults live on the Breadcrumb Nav page. */
+export type BreadcrumbsOptions = Record<string, never>;
+
+export const FEATURES: FeatureDef[] = [
+	{
+		id: "breadcrumbs",
+		label: "Breadcrumb Nav",
+		description: "An accessible breadcrumb trail, as a Breadcrumbs block and as a component for theme layouts.",
+		default: false,
+		replaces: ["headings.breadcrumbs"],
+	},
+];
+registerFeatures(FEATURES);
+
+const BLOCKS = [
+	{
+		type: BREADCRUMBS_BLOCK,
+		label: "Breadcrumbs",
+		icon: "link",
+		category: "Sections",
+		description: "A breadcrumb trail for this page",
+		fields: [
+			{
+				type: "select",
+				action_id: "separator",
+				label: "Separator",
+				options: [
+					{ label: "Site default", value: "" },
+					{ label: "/", value: "slash" },
+					{ label: "›", value: "chevron" },
+					{ label: "»", value: "guillemet" },
+					{ label: "•", value: "bullet" },
+					{ label: "→", value: "arrow" },
+					{ label: ">", value: "gt" },
+				],
+			},
+			{ type: "text_input", action_id: "homeLabel", label: "Home label", placeholder: "Site default (Home)" },
+			{
+				type: "select",
+				action_id: "showCurrent",
+				label: "Current page",
+				options: [
+					{ label: "Site default", value: "" },
+					{ label: "Show", value: "show" },
+					{ label: "Hide", value: "hide" },
+				],
+			},
+		],
+	},
+];
+
+const settingsInput = z.object({ settings: z.record(z.string(), z.unknown()) });
+
+/** Stamp each Breadcrumbs block with the entry's title (its own hook, so it works with Headings & TOC off). */
+export function beforeSave(event: { content: Record<string, unknown> }): Record<string, unknown> | undefined {
+	return stampBreadcrumbs(event.content) ?? undefined;
+}
+
+export function breadcrumbsPack(_options: BreadcrumbsOptions): PackModule {
+	return {
+		id: "breadcrumbs",
+		label: "Breadcrumb Nav",
+		features: FEATURES,
+		capabilities: ["content:write"],
+		portableTextBlocks: BLOCKS,
+		adminPages: [{ path: "/breadcrumbs", label: "Breadcrumb Nav", icon: "path" }],
+		hooks: {
+			"content:beforeSave": beforeSave,
+			// Remember the theme's breadcrumb trail for the Breadcrumbs block in the body.
+			"page:metadata": (event: { page: Parameters<typeof capturePage>[0] }) => {
+				capturePage(event.page);
+				return [];
+			},
+		},
+		routes: {
+			"breadcrumbs/settings": {
+				permission: "plugins:manage" as const,
+				handler: async (ctx: PluginContext) => ({ settings: await ctxBreadcrumbsSettings(ctx) }),
+			},
+			"breadcrumbs/settings/save": definePluginRoute({
+				permission: "plugins:manage",
+				methods: ["POST"],
+				request: { body: "json" },
+				handler: async (ctx) => {
+					const settings = normalizeSettings(parseInput(settingsInput, ctx.input).settings);
+					await ctx.settings.set(SETTINGS_KEY, settings);
+					invalidateBreadcrumbsSettings();
+					ctx.log.info("Breadcrumb settings saved");
+					return { settings };
+				},
+			}),
+		},
+	};
+}

package/src/breadcrumbs/settings.ts

@@ -0,0 +1,102 @@
+/**
+ * Breadcrumb Nav site defaults: one plugin setting ("breadcrumbs"). Before
+ * 0.6.0 they lived inside the Headings & TOC setting ("headings", under
+ * `breadcrumbs`), so reads fall back to that sub-object until the Breadcrumb
+ * Nav page saves its own. Hooks and routes read through the plugin context;
+ * Astro components read the option rows from D1 in the feature switches'
+ * query and per-isolate cache.
+ */
+import { invalidateFeatures, readSiteSetting, registerSiteSetting } from "../core/features.js";
+
+export const SETTINGS_KEY = "breadcrumbs";
+/** The setting that held these values before Breadcrumb Nav was its own module. */
+export const LEGACY_SETTINGS_KEY = "headings";
+
+export const SEPARATORS = {
+	slash: "/",
+	chevron: "›",
+	guillemet: "»",
+	bullet: "•",
+	arrow: "→",
+	gt: ">",
+} as const;
+export type SeparatorPreset = keyof typeof SEPARATORS;
+
+export interface BreadcrumbsSettings {
+	separator: SeparatorPreset;
+	/** Overrides the preset when not empty (max 8 characters). */
+	customSeparator: string;
+	homeLabel: string;
+	showHome: boolean;
+	showCurrent: boolean;
+}
+
+export const DEFAULT_SETTINGS: BreadcrumbsSettings = {
+	separator: "slash",
+	customSeparator: "",
+	homeLabel: "Home",
+	showHome: true,
+	showCurrent: true,
+};
+
+const asObject = (value: unknown) => (value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : null);
+const bool = (value: unknown, fallback: boolean) => (typeof value === "boolean" ? value : fallback);
+const text = (value: unknown, max: number, fallback: string) =>
+	typeof value === "string" ? value.replace(/[\u0000-\u001f<>]/g, "").trim().slice(0, max) : fallback;
+
+/** Fill in and clamp stored settings. Never throws. */
+export function normalizeSettings(raw: unknown): BreadcrumbsSettings {
+	const r = asObject(raw) ?? {};
+	const d = DEFAULT_SETTINGS;
+	return {
+		separator: Object.hasOwn(SEPARATORS, r.separator as string) ? (r.separator as SeparatorPreset) : d.separator,
+		customSeparator: [...text(r.customSeparator, 32, "")].slice(0, 8).join(""),
+		homeLabel: text(r.homeLabel, 60, d.homeLabel) || d.homeLabel,
+		showHome: bool(r.showHome, d.showHome),
+		showCurrent: bool(r.showCurrent, d.showCurrent),
+	};
+}
+
+/**
+ * The effective settings from the stored "breadcrumbs" setting, else the
+ * `breadcrumbs` sub-object of the legacy "headings" setting, else defaults.
+ */
+export function resolveSettings(stored: unknown, legacyHeadings: unknown): BreadcrumbsSettings {
+	return normalizeSettings(asObject(stored) ?? asObject(asObject(legacyHeadings)?.breadcrumbs));
+}
+
+interface SettingsCtx {
+	settings: { get<T>(key: string): Promise<T | null | undefined> };
+}
+
+/** Settings inside the plugin context (hooks, routes). */
+export async function ctxBreadcrumbsSettings(ctx: SettingsCtx): Promise<BreadcrumbsSettings> {
+	const stored = await ctx.settings.get<unknown>(SETTINGS_KEY);
+	if (asObject(stored)) return normalizeSettings(stored);
+	return resolveSettings(null, await ctx.settings.get<unknown>(LEGACY_SETTINGS_KEY));
+}
+
+// ── Outside the plugin context (Astro components) ────────────────
+
+registerSiteSetting(SETTINGS_KEY);
+registerSiteSetting(LEGACY_SETTINGS_KEY);
+
+/** The last stored values and their resolved settings, so a cache hit doesn't resolve again. */
+let memo: { stored: unknown; legacy: unknown; settings: BreadcrumbsSettings } | null = null;
+
+export function invalidateBreadcrumbsSettings(): void {
+	invalidateFeatures();
+}
+
+/** The settings from D1 (both rows, in the feature switches' query and cache). Falls back to defaults if the database can't be read. */
+export async function siteBreadcrumbsSettings(database = "DB"): Promise<BreadcrumbsSettings> {
+	const [stored, legacy] = await Promise.all([readSiteSetting(SETTINGS_KEY, database), readSiteSetting(LEGACY_SETTINGS_KEY, database)]);
+	if (!stored || !legacy) {
+		console.error("coywolf-pack: could not read breadcrumb settings");
+		return DEFAULT_SETTINGS;
+	}
+	if (memo && memo.stored === stored.value && memo.legacy === legacy.value) return memo.settings;
+	const settings = resolveSettings(stored.value, legacy.value);
+	memo = { stored: stored.value, legacy: legacy.value, settings };
+	return settings;
+}

package/src/breadcrumbs/stamp.ts

@@ -0,0 +1,40 @@
+/**
+ * Save-time stamping for Breadcrumbs blocks (content:beforeSave). A block
+ * component only sees its own node, so each `coywolf-breadcrumbs` block gets
+ * `_title`, the entry's title, for the last crumb of a trail derived from the
+ * URL. Pure: returns new objects, never mutates its input, and is idempotent.
+ */
+
+export const BREADCRUMBS_BLOCK = "coywolf-breadcrumbs";
+
+type Block = Record<string, unknown> & { _type: string };
+
+/** An array that looks like Portable Text: every item is an object with a string `_type`. */
+function isPortableText(value: unknown): value is Block[] {
+	return (
+		Array.isArray(value) &&
+		value.length > 0 &&
+		value.every((b) => b && typeof b === "object" && typeof (b as { _type?: unknown })._type === "string")
+	);
+}
+
+/** Stamp the title into every Breadcrumbs block. Returns the new content, or null when nothing changed. */
+export function stampBreadcrumbs(content: Record<string, unknown>): Record<string, unknown> | null {
+	const title = typeof content.title === "string" ? content.title.trim() || null : null;
+	if (title === null) return null;
+	let result: Record<string, unknown> | null = null;
+	for (const [field, value] of Object.entries(content)) {
+		if (!isPortableText(value)) continue;
+		let out: Block[] | null = null;
+		value.forEach((block, i) => {
+			if (block._type !== BREADCRUMBS_BLOCK || block._title === title) return;
+			out ??= value.slice();
+			out[i] = { ...block, _title: title };
+		});
+		if (out) {
+			result ??= { ...content };
+			result[field] = out;
+		}
+	}
+	return result;
+}

package/src/breadcrumbs/trail.ts

@@ -0,0 +1,123 @@
+/**
+ * Breadcrumb trails. The theme's trail (PublicPageContext.breadcrumbs) wins
+ * when it has one; otherwise the trail is derived from the URL path, with
+ * the page title for the last crumb and humanized path segments for the
+ * ancestors.
+ */
+
+export interface Crumb {
+	name: string;
+	url: string;
+}
+
+export interface TrailOptions {
+	/** Current URL path, e.g. "/guides/setup/". */
+	path: string;
+	/** The theme's trail, root first. `[]` means "no breadcrumbs on this page". */
+	items?: readonly Crumb[] | null;
+	/** Title of the current page (last crumb when deriving). */
+	title?: string | null;
+	homeLabel: string;
+	showHome: boolean;
+	showCurrent: boolean;
+}
+
+/** "getting-started_now" → "Getting started now". */
+export function humanize(segment: string): string {
+	let decoded = segment;
+	try {
+		decoded = decodeURIComponent(segment);
+	} catch {
+		// Keep the raw segment.
+	}
+	const words = decoded.replace(/\.[a-z0-9]+$/i, "").replace(/[-_+]+/g, " ").trim();
+	return words ? words.charAt(0).toUpperCase() + words.slice(1) : segment;
+}
+
+const normalizePath = (path: string) => (path.length > 1 ? path.replace(/\/+$/, "") : path) || "/";
+
+/** Root-relative path of a crumb URL (absolute URLs are reduced to their path). */
+function crumbPath(url: string): string {
+	try {
+		return normalizePath(new URL(url, "https://x.invalid").pathname);
+	} catch {
+		return url;
+	}
+}
+
+/** The trail to render: home first, current page last (unless hidden). Empty when there's nothing useful to show. */
+export function resolveTrail(options: TrailOptions): Crumb[] {
+	const current = normalizePath(options.path.split(/[?#]/)[0] || "/");
+	let trail: Crumb[];
+
+	if (options.items) {
+		trail = options.items.filter((c) => c && typeof c.name === "string" && c.name.trim() && typeof c.url === "string").map((c) => ({ name: c.name.trim(), url: c.url }));
+		if (!options.showHome && trail.length && crumbPath(trail[0].url) === "/") trail = trail.slice(1);
+		else if (options.showHome && trail.length && crumbPath(trail[0].url) !== "/") trail.unshift({ name: options.homeLabel, url: "/" });
+	} else {
+		if (current === "/") return [];
+		const trailingSlash = options.path.split(/[?#]/)[0].endsWith("/");
+		const segments = current.split("/").filter(Boolean);
+		trail = options.showHome ? [{ name: options.homeLabel, url: "/" }] : [];
+		segments.forEach((segment, i) => {
+			const url = `/${segments.slice(0, i + 1).join("/")}${trailingSlash ? "/" : ""}`;
+			const last = i === segments.length - 1;
+			trail.push({ name: last && options.title?.trim() ? options.title.trim() : humanize(segment), url });
+		});
+	}
+
+	if (!options.showCurrent && trail.length && crumbPath(trail[trail.length - 1].url) === current) trail = trail.slice(0, -1);
+	// A lone crumb (just Home, or just the page) isn't a useful trail.
+	return trail.length >= 2 ? trail : [];
+}
+
+/** Escape a separator for a CSS string (`content: "…"`). */
+export function cssString(value: string): string {
+	return `"${value.replace(/[\\"]/g, (c) => `\\${c}`).replace(/[\u0000-\u001f<>]/g, "")}"`;
+}
+
+// ── Theme trails captured from page:metadata ─────────────────────
+//
+// EmDashHead runs the page:metadata hook (with the theme's
+// PublicPageContext) before the body renders. The hook records the page's
+// breadcrumbs and title here so a Breadcrumbs block in the body can use the
+// theme's trail without the theme wiring anything. This relies on the theme
+// rendering <EmDashHead page={page}> with an accurate `url`; without it the
+// block derives the trail from the URL path. Keyed by the page URL (path plus
+// query, so locales and variants don't mix); short-lived.
+
+interface Captured {
+	items?: Crumb[];
+	title: string | null;
+	at: number;
+}
+
+const CAPTURE_TTL_MS = 60_000;
+const CAPTURE_MAX = 200;
+const captured = new Map<string, Captured>();
+
+/** Cache key for a page URL: normalized path plus query string, ignoring origin and fragment. */
+export function captureKey(url: string): string {
+	try {
+		const parsed = new URL(url, "https://x.invalid");
+		return `${normalizePath(parsed.pathname)}${parsed.search}`;
+	} catch {
+		return url;
+	}
+}
+
+export function capturePage(page: { path?: string; url?: string; locale?: string | null; breadcrumbs?: Crumb[]; pageTitle?: string | null; title?: string | null }): void {
+	const source = page.url ?? page.path;
+	if (!source) return;
+	const key = captureKey(source);
+	captured.delete(key);
+	captured.set(key, { items: page.breadcrumbs, title: page.pageTitle ?? page.title ?? null, at: Date.now() });
+	while (captured.size > CAPTURE_MAX) captured.delete(captured.keys().next().value as string);
+}
+
+/** The trail captured for this request URL, if EmDashHead published one in the last minute. */
+export function capturedPage(url: string): Omit<Captured, "at"> | null {
+	const entry = captured.get(captureKey(url));
+	if (!entry || Date.now() - entry.at > CAPTURE_TTL_MS) return null;
+	return entry;
+}

package/src/codeBlocks/contrast.ts

@@ -0,0 +1,179 @@
+/**
+ * Readable code block themes (WCAG 1.4.3). Several highlight.js themes color
+ * comments, and a few their body text, below 4.5:1 against their own
+ * background. Rather than hand-edit the generated themes, each theme's CSS is
+ * checked once and any color under the minimum is moved in lightness only
+ * (same hue and saturation) until it reaches it, so the theme keeps its look.
+ */
+
+export const MIN_CONTRAST = 4.5;
+/** Aim a little above the minimum so rounding to hex never lands under it. */
+const TARGET = 4.6;
+
+type Rgba = [number, number, number, number];
+
+const NAMED: Record<string, string> = { black: "#000000", white: "#ffffff", gold: "#ffd700", gray: "#808080", grey: "#808080", red: "#ff0000", green: "#008000", blue: "#0000ff", navy: "#000080", purple: "#800080", maroon: "#800000", teal: "#008080", olive: "#808000", silver: "#c0c0c0" };
+
+/** A CSS color as RGBA (0–255, alpha 0–1), or null for anything else (url(), gradients, inherit…). */
+export function parseColor(value: string): Rgba | null {
+	const v = value.trim().toLowerCase().replace(/\s*!important$/, "");
+	const hex = NAMED[v] ?? v;
+	let m = /^#([0-9a-f]{3,4})$/.exec(hex);
+	if (m) {
+		const [r, g, b, a = "f"] = m[1].split("");
+		return [parseInt(r + r, 16), parseInt(g + g, 16), parseInt(b + b, 16), parseInt(a + a, 16) / 255];
+	}
+	m = /^#([0-9a-f]{6})([0-9a-f]{2})?$/.exec(hex);
+	if (m) return [parseInt(m[1].slice(0, 2), 16), parseInt(m[1].slice(2, 4), 16), parseInt(m[1].slice(4, 6), 16), m[2] ? parseInt(m[2], 16) / 255 : 1];
+	m = /^rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*(?:,\s*([\d.]+)\s*)?\)$/.exec(v);
+	if (m) return [Number(m[1]), Number(m[2]), Number(m[3]), m[4] === undefined ? 1 : Number(m[4])];
+	return null;
+}
+
+/** `top` drawn over an opaque `bottom`. */
+function over(top: Rgba, bottom: Rgba): Rgba {
+	const a = top[3];
+	return [top[0] * a + bottom[0] * (1 - a), top[1] * a + bottom[1] * (1 - a), top[2] * a + bottom[2] * (1 - a), 1];
+}
+
+function luminance([r, g, b]: Rgba): number {
+	const lin = (c: number) => {
+		const s = c / 255;
+		return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+	};
+	return 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+}
+
+export function contrastRatio(a: Rgba, b: Rgba): number {
+	const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+	return (hi + 0.05) / (lo + 0.05);
+}
+
+function toHsl([r, g, b]: Rgba): [number, number, number] {
+	const [rr, gg, bb] = [r / 255, g / 255, b / 255];
+	const max = Math.max(rr, gg, bb);
+	const min = Math.min(rr, gg, bb);
+	const l = (max + min) / 2;
+	if (max === min) return [0, 0, l];
+	const d = max - min;
+	const s = l > 0.5 ? d / (2 - max - min) : d / (max + min);
+	const h = max === rr ? (gg - bb) / d + (gg < bb ? 6 : 0) : max === gg ? (bb - rr) / d + 2 : (rr - gg) / d + 4;
+	return [h / 6, s, l];
+}
+
+function fromHsl(h: number, s: number, l: number): Rgba {
+	if (s === 0) return [l * 255, l * 255, l * 255, 1];
+	const q = l < 0.5 ? l * (1 + s) : l + s - l * s;
+	const p = 2 * l - q;
+	const ch = (t: number) => {
+		const x = t < 0 ? t + 1 : t > 1 ? t - 1 : t;
+		if (x < 1 / 6) return p + (q - p) * 6 * x;
+		if (x < 1 / 2) return q;
+		if (x < 2 / 3) return p + (q - p) * (2 / 3 - x) * 6;
+		return p;
+	};
+	return [ch(h + 1 / 3) * 255, ch(h) * 255, ch(h - 1 / 3) * 255, 1];
+}
+
+const toHex = (c: Rgba) => `#${c.slice(0, 3).map((x) => Math.round(Math.min(255, Math.max(0, x))).toString(16).padStart(2, "0")).join("")}`;
+
+/**
+ * `color` (any alpha, drawn over `background`) made readable on `background`:
+ * unchanged when it already passes, else the nearest lightness that does
+ * (lighter on dark backgrounds, darker on light ones). Returns an opaque hex.
+ */
+export function readableOn(color: Rgba, background: Rgba): Rgba {
+	const solid = over(color, background);
+	if (contrastRatio(solid, background) >= MIN_CONTRAST) return solid;
+	const [h, s, l] = toHsl(solid);
+	const lighter = luminance(background) < 0.18;
+	let [lo, hi] = lighter ? [l, 1] : [0, l];
+	for (let i = 0; i < 24; i++) {
+		const mid = (lo + hi) / 2;
+		const ok = contrastRatio(fromHsl(h, s, mid), background) >= TARGET;
+		if (lighter) ok ? (hi = mid) : (lo = mid);
+		else ok ? (lo = mid) : (hi = mid);
+	}
+	const fixed = parseColor(toHex(fromHsl(h, s, lighter ? hi : lo))) as Rgba;
+	return contrastRatio(fixed, background) >= MIN_CONTRAST ? fixed : lighter ? [255, 255, 255, 1] : [0, 0, 0, 1];
+}
+
+interface Rule {
+	selectors: string[];
+	body: string;
+}
+
+const RULE = /([^{}]+)\{([^{}]*)\}/g;
+const DECL = (name: string) => new RegExp(`(^|;)(\\s*${name}\\s*:\\s*)([^;]+)`, "i");
+
+function parseRules(css: string): Rule[] {
+	return [...css.matchAll(RULE)].map((m) => ({ selectors: m[1].split(",").map((s) => s.trim()), body: m[2] }));
+}
+
+const declared = (body: string, name: string) => DECL(name).exec(body)?.[3] ?? null;
+const backgroundOf = (body: string) => parseColor(declared(body, "background-color") ?? declared(body, "background") ?? "");
+
+/** The theme's own background and text color (the rules for `.cw-code` itself). */
+export function themeBase(css: string): { background: Rgba; color: Rgba } {
+	const rules = parseRules(css).filter((r) => r.selectors.includes(".cw-code"));
+	let background: Rgba | null = null;
+	let color: Rgba | null = null;
+	for (const r of rules) {
+		background = backgroundOf(r.body) ?? background;
+		color = parseColor(declared(r.body, "color") ?? "") ?? color;
+	}
+	const bg = background ?? [255, 255, 255, 1];
+	return { background: bg, color: color ?? (luminance(bg) < 0.18 ? [255, 255, 255, 1] : [0, 0, 0, 1]) };
+}
+
+/** Every text color a theme's rules set, each with the background it's read on. */
+export function themeTextColors(css: string): Array<{ selector: string; color: Rgba; background: Rgba }> {
+	const base = themeBase(css);
+	const out: Array<{ selector: string; color: Rgba; background: Rgba }> = [];
+	for (const r of parseRules(css)) {
+		const own = backgroundOf(r.body);
+		const background = own ? over(own, base.background) : base.background;
+		const color = parseColor(declared(r.body, "color") ?? "");
+		if (color) out.push({ selector: r.selectors.join(","), color: over(color, background), background });
+		else if (own) out.push({ selector: r.selectors.join(","), color: base.color, background });
+	}
+	return out;
+}
+
+/** Opacity line numbers had (now a color per theme, --cw-line). */
+export const LINE_OPACITY = 0.5;
+/** Opacity the language label had (now a color per theme, --cw-label). */
+export const LABEL_OPACITY = 0.75;
+
+/**
+ * `color` at `opacity` over `background`, as an opaque hex: exactly what the
+ * opacity looked like when that already reaches 4.5:1, else the nearest
+ * lightness that does (readableOn).
+ */
+export function fadedColor(color: Rgba, background: Rgba, opacity: number): string {
+	return toHex(readableOn([color[0], color[1], color[2], color[3] * opacity], background));
+}
+
+/**
+ * A muted text color for a theme (line numbers by default): its text color at
+ * `opacity` over its background, as before, raised to 4.5:1 only where that's
+ * too faint.
+ */
+export function mutedColor(css: string, opacity = LINE_OPACITY): string {
+	const { color, background } = themeBase(css);
+	return fadedColor(color, background, opacity);
+}
+
+/** The theme CSS with every text color under 4.5:1 replaced by a readable one of the same hue. */
+export function readableThemeCss(css: string): string {
+	const base = themeBase(css);
+	return css.replace(RULE, (whole, selectors: string, body: string) => {
+		const own = backgroundOf(body);
+		const background = own ? over(own, base.background) : base.background;
+		const value = declared(body, "color");
+		const color = value ? parseColor(value) : own ? base.color : null;
+		if (!color || contrastRatio(over(color, background), background) >= MIN_CONTRAST) return whole;
+		const hex = toHex(readableOn(color, background));
+		return value ? `${selectors}{${body.replace(DECL("color"), `$1$2${hex}`)}}` : `${selectors}{${body};color:${hex}}`;
+	});
+}

package/src/codeBlocks/hljs.d.ts

@@ -0,0 +1,5 @@
+declare module "highlight.js/lib/languages/*" {
+	import type { LanguageFn } from "highlight.js";
+	const language: LanguageFn;
+	export default language;
+}

package/src/codeBlocks/pack.ts

@@ -0,0 +1,110 @@
+/**
+ * Code Blocks module: server-side syntax highlighting, themes, language
+ * label, copy button and line numbers for EmDash's built-in code block
+ * (rendered by src/astro/codeBlocks/CodeBlock.astro). Port of Coywolf Code
+ * Block Enhancer.
+ */
+import { PluginRouteError, definePluginRoute } from "emdash";
+import { z } from "zod";
+
+import { registerFeatures } from "../core/features.js";
+import type { PackModule } from "../core/module.js";
+import { parseInput } from "../shared.js";
+import { invalidateTheme } from "./settings.js";
+import { DEFAULT_THEME, THEME_SETTING, isTheme, themeCss, themeOptions } from "./themes.js";
+
+// biome-ignore lint/suspicious/noEmptyInterface: reserved for future options.
+export interface CodeBlocksOptions {}
+
+export const FEATURES = [
+	{
+		id: "codeBlocks",
+		label: "Code blocks",
+		description: "Syntax highlighting and themes for code blocks on the site, rendered on the server (no highlighting script for visitors).",
+		default: false,
+	},
+	{
+		id: "codeBlocks.label",
+		label: "Language label",
+		description: "Show the code's language (e.g. TypeScript) above each block.",
+		default: false,
+	},
+	{
+		id: "codeBlocks.copy",
+		label: "Copy button",
+		description: "An accessible copy-to-clipboard button on each block (one small inline script, only on pages with code).",
+		default: false,
+	},
+	{
+		id: "codeBlocks.lineNumbers",
+		label: "Line numbers",
+		description: "Number each line. Numbers aren't selected or copied with the code.",
+		default: false,
+	},
+];
+registerFeatures(FEATURES);
+
+const SAMPLE = {
+	language: "typescript",
+	code: `/** Say hello to someone. */
+export function greet(name: string, times = 1): string {
+  const words = ["Hello", name].join(", ");
+  // Repeat it if asked
+  return \`\${words}!\`.repeat(times);
+}
+
+console.log(greet("Coywolf", 2));
+`,
+};
+
+export function codeBlocksPack(_options: CodeBlocksOptions): PackModule {
+	return {
+		id: "codeBlocks",
+		label: "Code Blocks",
+		features: FEATURES,
+		adminPages: [{ path: "/code-blocks", label: "Code Blocks", icon: "code" }],
+		routes: {
+			"codeBlocks/settings": {
+				permission: "plugins:manage" as const,
+				// biome-ignore lint/suspicious/noExplicitAny: plugin context.
+				handler: async (ctx: any) => {
+					const stored = await ctx.settings.get(THEME_SETTING);
+					return { theme: isTheme(stored) ? stored : DEFAULT_THEME, themes: themeOptions() };
+				},
+			},
+
+			"codeBlocks/save": definePluginRoute({
+				permission: "plugins:manage",
+				methods: ["POST"],
+				request: { body: "json" },
+				handler: async (ctx) => {
+					const { theme } = parseInput(z.object({ theme: z.string().max(100) }), ctx.input);
+					if (!isTheme(theme)) throw PluginRouteError.badRequest("Unknown theme.");
+					await ctx.settings.set(THEME_SETTING, theme);
+					invalidateTheme();
+					ctx.log.info("Code block theme saved", { theme });
+					return { theme };
+				},
+			}),
+
+			/** Preview markup + CSS for the admin page (same renderer as the site). */
+			"codeBlocks/preview": definePluginRoute({
+				permission: "plugins:manage",
+				methods: ["POST"],
+				request: { body: "json" },
+				handler: async (ctx) => {
+					const input = parseInput(
+						z.object({ theme: z.string().max(100), label: z.boolean(), copy: z.boolean(), lineNumbers: z.boolean() }),
+						ctx.input,
+					);
+					// Lazy: keeps lowlight and its grammars out of the plugin's startup path.
+					const { CHROME_CSS, renderBlock } = await import("./render.js");
+					return {
+						css: CHROME_CSS + themeCss(input.theme),
+						html: renderBlock(SAMPLE, { label: input.label, copy: input.copy, lineNumbers: input.lineNumbers }),
+					};
+				},
+			}),
+		},
+	};
+}