@coywolf/emdash 0.0.0-stage → 0.35.13

package/src/headings/headings.test.ts

@@ -0,0 +1,159 @@
+// Run: node --import ./src/headings/test-hooks.mjs --test src/headings/headings.test.ts
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { blockText, slugify, uniqueSlug, validAnchor } from "./slug.js";
+import { stampContent } from "./stamp.js";
+import { buildTocTree, countToc } from "./toc.js";
+import { normalizeSettings, withLegacyBreadcrumbs } from "./settings.js";
+
+const h = (key: string, style: string, text: string, extra: Record<string, unknown> = {}) => ({
+	_type: "block",
+	_key: key,
+	style,
+	children: [{ _type: "span", _key: `${key}s`, text, marks: [] }],
+	markDefs: [],
+	...extra,
+});
+const p = (key: string, text: string) => h(key, "normal", text);
+const opts = { anchors: true, toc: true, prefix: "jump-" };
+
+test("slugify mirrors sanitize_title", () => {
+	assert.equal(slugify("Hello, World!"), "hello-world");
+	assert.equal(slugify("Don't Panic"), "dont-panic");
+	assert.equal(slugify("  Café   au lait "), "cafe-au-lait");
+	assert.equal(slugify("Price & Plans — 2026"), "price-plans-2026");
+	assert.equal(slugify("snake_case words"), "snake-case-words");
+	assert.equal(slugify("日本語 見出し"), "日本語-見出し");
+	assert.equal(slugify("!!!"), "");
+	assert.ok(slugify("a".repeat(200)).length <= 80);
+});
+
+test("uniqueSlug prefixes and de-duplicates", () => {
+	const taken = new Set<string>();
+	assert.equal(uniqueSlug("Intro", taken), "jump-intro");
+	assert.equal(uniqueSlug("Intro", taken), "jump-intro-2");
+	assert.equal(uniqueSlug("Intro", taken), "jump-intro-3");
+	assert.equal(uniqueSlug("???", taken), "jump-section");
+	assert.equal(uniqueSlug("2026 plans", new Set(), ""), "h-2026-plans");
+	assert.equal(uniqueSlug("Intro", new Set(), "sec-"), "sec-intro");
+});
+
+test("validAnchor rejects unsafe ids", () => {
+	assert.ok(validAnchor("jump-intro"));
+	assert.ok(!validAnchor('x" onclick="y'));
+	assert.ok(!validAnchor("1abc"));
+	assert.ok(!validAnchor(""));
+	assert.ok(!validAnchor(42));
+});
+
+test("blockText reads nested marks trees", () => {
+	const node = { children: [{ _type: "@span", children: [{ _type: "@text", text: "Bold " }] }, { _type: "@text", text: "tail" }] };
+	assert.equal(blockText(node), "Bold tail");
+});
+
+test("stamping adds unique anchors and TOC headings (breadcrumb blocks are left to Breadcrumb Nav)", () => {
+	const content = {
+		title: "My Post",
+		body: [
+			{ _type: "coywolf-toc", _key: "t" },
+			{ _type: "coywolf-breadcrumbs", _key: "b" },
+			h("a", "h2", "Intro"),
+			p("x", "text"),
+			h("b2", "h3", "Intro"),
+			h("c", "h1", "Title"),
+			h("d", "h2", ""),
+		],
+		other: "not portable text",
+	};
+	const out = stampContent(content, opts);
+	assert.ok(out);
+	const body = out.body as Record<string, unknown>[];
+	assert.equal(body[2].anchor, "jump-intro");
+	assert.equal(body[4].anchor, "jump-intro-2");
+	assert.equal(body[5].anchor, undefined, "H1 is not anchored");
+	assert.equal(body[6].anchor, undefined, "empty heading is skipped");
+	assert.deepEqual(body[0]._headings, [
+		{ level: 2, id: "jump-intro", text: "Intro" },
+		{ level: 3, id: "jump-intro-2", text: "Intro" },
+	]);
+	assert.equal(body[1]._title, undefined);
+	assert.equal(out.other, "not portable text");
+	// Input untouched.
+	assert.equal((content.body[2] as Record<string, unknown>).anchor, undefined);
+});
+
+test("stamping is idempotent", () => {
+	const content = { title: "T", body: [{ _type: "coywolf-toc", _key: "t" }, h("a", "h2", "One"), h("b", "h2", "One")] };
+	const once = stampContent(content, opts);
+	assert.ok(once);
+	assert.equal(stampContent(once, opts), null);
+});
+
+test("anchors stay stable when the editor drops them and the heading is reworded", () => {
+	const saved = stampContent({ body: [h("a", "h2", "Pricing"), h("b", "h2", "FAQ")] }, opts);
+	assert.ok(saved);
+	// Editor round trip: anchor field gone, first heading renamed, a new heading inserted before it.
+	const edited = { body: [h("n", "h2", "FAQ"), h("a", "h2", "Plans and pricing"), h("b", "h2", "FAQ")] };
+	const out = stampContent(edited, { ...opts, previous: saved });
+	assert.ok(out);
+	const body = out.body as Record<string, unknown>[];
+	assert.equal(body[1].anchor, "jump-pricing", "kept by _key despite new text");
+	assert.equal(body[2].anchor, "jump-faq", "kept by _key");
+	assert.equal(body[0].anchor, "jump-faq-2", "new heading slugs around existing anchors");
+});
+
+test("anchors fall back to text matching when keys change", () => {
+	const saved = stampContent({ body: [h("a", "h2", "Setup")] }, { ...opts, prefix: "old-" });
+	assert.ok(saved);
+	const out = stampContent({ body: [h("z", "h2", "Setup")] }, { ...opts, previous: saved });
+	assert.equal((out?.body as Record<string, unknown>[])[0].anchor, "old-setup");
+});
+
+test("invalid stored anchors are replaced", () => {
+	const out = stampContent({ body: [h("a", "h2", "Hi", { anchor: '"><script>' })] }, opts);
+	assert.equal((out?.body as Record<string, unknown>[])[0].anchor, "jump-hi");
+});
+
+test("TOC tree nests by level and tolerates skipped levels", () => {
+	const flat = [
+		{ level: 2, id: "a", text: "A" },
+		{ level: 4, id: "a1", text: "A1" },
+		{ level: 3, id: "a2", text: "A2" },
+		{ level: 2, id: "b", text: "B" },
+		{ level: 5, id: "deep", text: "Deep" },
+		{ level: 3, id: "b1", text: "B1" },
+	];
+	const tree = buildTocTree(flat, [2, 3, 4]);
+	assert.deepEqual(
+		tree.map((n) => [n.id, n.children.map((c) => [c.id, c.children.map((g) => g.id)])]),
+		[
+			["a", [["a1", []], ["a2", []]]],
+			["b", [["b1", []]]],
+		],
+	);
+	assert.equal(countToc(tree), 5);
+	assert.deepEqual(
+		buildTocTree(flat, [3]).map((n) => n.id),
+		["a2", "b1"],
+	);
+	assert.deepEqual(
+		buildTocTree([{ level: 3, id: "x", text: "X" }, { level: 2, id: "y", text: "Y" }], [2, 3]).map((n) => n.id),
+		["x", "y"],
+	);
+});
+
+test("TOC title can be hidden; levels can be H2 only", () => {
+	assert.equal(normalizeSettings({}).toc.showTitle, true);
+	assert.equal(normalizeSettings({ toc: { showTitle: false } }).toc.showTitle, false);
+	assert.deepEqual(normalizeSettings({ toc: { levels: [2] } }).toc.levels, [2]);
+	assert.equal("breadcrumbs" in normalizeSettings({ breadcrumbs: { homeLabel: "Start" } }), false);
+});
+
+test("saving Headings settings keeps the legacy breadcrumb sub-object for Breadcrumb Nav", () => {
+	const legacy = { separator: "chevron", homeLabel: "Start" };
+	const next = normalizeSettings({ prefix: "sec-" });
+	assert.deepEqual(withLegacyBreadcrumbs({ prefix: "jump-", breadcrumbs: legacy }, next), { ...next, breadcrumbs: legacy });
+	assert.deepEqual(withLegacyBreadcrumbs({ prefix: "jump-" }, next), next);
+	assert.deepEqual(withLegacyBreadcrumbs(null, next), next);
+});

package/src/headings/pack.ts

@@ -0,0 +1,154 @@
+/**
+ * Headings & TOC module: heading anchors and a Table of Contents block,
+ * ported from Coywolf SEO. Anchors and TOC heading lists are stamped into the
+ * content on save (see ./stamp.ts); the Astro components in
+ * src/astro/headings render them. Breadcrumbs moved to their own module
+ * (Breadcrumb Nav, src/breadcrumbs) in 0.6.0.
+ */
+import type { PluginContext } from "emdash";
+import { definePluginRoute } from "emdash";
+import { z } from "zod";
+
+import { ctxFeatures, isOn, registerFeatures } from "../core/features.js";
+import type { PackModule } from "../core/module.js";
+import { parseInput } from "../shared.js";
+import { SETTINGS_KEY, invalidateHeadingsSettings, normalizeSettings, withLegacyBreadcrumbs } from "./settings.js";
+import { TOC_BLOCK, needsPrevious, stampContent } from "./stamp.js";
+
+/** No build-time options yet: defaults live on the Headings & TOC settings page. */
+export type HeadingsOptions = Record<string, never>;
+
+export const FEATURES = [
+	{
+		id: "headings",
+		label: "Headings & TOC",
+		description: "Linkable headings and a Table of Contents block.",
+		default: false,
+	},
+	{
+		id: "headings.anchors",
+		label: "Heading anchors",
+		description: "Give every H2–H6 a stable id (e.g. #jump-pricing) so sections can be linked, with an optional copy-link button.",
+		default: false,
+	},
+	{
+		id: "headings.toc",
+		label: "Table of Contents block",
+		description: "A Table of Contents block built from the entry's headings, with numbered or bulleted lists and an optional collapsible panel.",
+		default: false,
+	},
+];
+registerFeatures(FEATURES);
+
+const LEVEL_OPTIONS = [2, 3, 4, 5, 6].map((n) => ({ label: `H${n}`, value: String(n) }));
+
+const BLOCKS = [
+	{
+		type: TOC_BLOCK,
+		label: "Table of Contents",
+		icon: "list",
+		category: "Sections",
+		description: "A linked list of this entry's headings",
+		fields: [
+			{ type: "text_input", action_id: "title", label: "Title", placeholder: "Site default (Table of contents)" },
+			{
+				type: "select",
+				action_id: "showTitle",
+				label: "Show title",
+				options: [
+					{ label: "Site default", value: "" },
+					{ label: "Show", value: "show" },
+					{ label: "Hide (collapsible tables keep it as the toggle)", value: "hide" },
+				],
+			},
+			{
+				type: "select",
+				action_id: "titleTag",
+				label: "Title heading level (always-open tables)",
+				options: [
+					{ label: "Heading 2", value: "h2" },
+					{ label: "Heading 3", value: "h3" },
+					{ label: "Heading 4", value: "h4" },
+					{ label: "Heading 5", value: "h5" },
+					{ label: "Heading 6", value: "h6" },
+				],
+				initial_value: "h2",
+			},
+			{ type: "checkbox", action_id: "levels", label: "Heading levels (none checked: site default)", options: LEVEL_OPTIONS },
+			{
+				type: "select",
+				action_id: "listStyle",
+				label: "List style",
+				options: [
+					{ label: "Site default", value: "" },
+					{ label: "Plain", value: "none" },
+					{ label: "Bulleted", value: "bulleted" },
+					{ label: "Numbered", value: "numbered" },
+				],
+			},
+			{
+				type: "select",
+				action_id: "display",
+				label: "Display",
+				options: [
+					{ label: "Site default", value: "" },
+					{ label: "Always open", value: "open" },
+					{ label: "Collapsible, open", value: "collapsible" },
+					{ label: "Collapsible, collapsed", value: "collapsed" },
+				],
+			},
+		],
+	},
+];
+
+const settingsInput = z.object({ settings: z.record(z.string(), z.unknown()) });
+
+async function beforeSave(event: { content: Record<string, unknown>; collection: string; isNew: boolean; id?: string }, ctx: PluginContext) {
+	const features = await ctxFeatures(ctx);
+	const toc = isOn(features, "headings.toc");
+	const anchors = isOn(features, "headings.anchors") || toc;
+	if (!anchors) return undefined;
+
+	const settings = normalizeSettings(await ctx.settings.get(SETTINGS_KEY));
+	let previous: Record<string, unknown> | null = null;
+	if (anchors && !event.isNew && event.id && ctx.content && needsPrevious(event.content)) {
+		try {
+			previous = (await ctx.content.get(event.collection, event.id))?.data ?? null;
+		} catch (error) {
+			ctx.log.warn("headings: could not read the previous version; anchors follow the heading text", { error: String(error) });
+		}
+	}
+	return stampContent(event.content, { anchors, toc, prefix: settings.prefix, previous }) ?? undefined;
+}
+
+export function headingsPack(_options: HeadingsOptions): PackModule {
+	return {
+		id: "headings",
+		label: "Headings & TOC",
+		features: FEATURES,
+		capabilities: ["content:read", "content:write"],
+		portableTextBlocks: BLOCKS,
+		adminPages: [{ path: "/headings", label: "Headings & TOC", icon: "list" }],
+		hooks: {
+			"content:beforeSave": beforeSave,
+		},
+		routes: {
+			"headings/settings": {
+				permission: "plugins:manage" as const,
+				handler: async (ctx: PluginContext) => ({ settings: normalizeSettings(await ctx.settings.get(SETTINGS_KEY)) }),
+			},
+			"headings/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, withLegacyBreadcrumbs(await ctx.settings.get(SETTINGS_KEY), settings));
+					invalidateHeadingsSettings();
+					ctx.log.info("Heading settings saved");
+					return { settings };
+				},
+			}),
+		},
+	};
+}

package/src/headings/render.ts

@@ -0,0 +1,139 @@
+/**
+ * Table of Contents markup and CSS, shared by the coywolf-toc block
+ * (src/astro/headings/TableOfContents.astro) and the live preview on the
+ * Headings & TOC admin page, so the preview is exactly what the site prints.
+ * Only type imports, so `node --test` can load it.
+ */
+import type { TocDisplay, TocListStyle } from "./settings.js";
+import type { TocNode } from "./toc.js";
+
+/** Heading levels the TOC title can use when it's shown as a heading (always open). */
+export const TOC_TITLE_TAGS = ["h2", "h3", "h4", "h5", "h6"] as const;
+export type TocTitleTag = (typeof TOC_TITLE_TAGS)[number];
+
+/** A block's titleTag, or h2. */
+export function tocTitleTag(value: unknown): TocTitleTag {
+	return TOC_TITLE_TAGS.includes(value as TocTitleTag) ? (value as TocTitleTag) : "h2";
+}
+
+export interface TocRenderOptions {
+	title: string;
+	showTitle: boolean;
+	/** Heading level of a shown title in an always-open TOC (default h2), so it fits the page's outline. */
+	titleTag?: TocTitleTag;
+	listStyle: TocListStyle;
+	display: TocDisplay;
+	smooth: boolean;
+	/** Id for the title element (unique per block on a page). */
+	titleId: string;
+}
+
+const escapeHtml = (text: string) =>
+	String(text).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c] as string);
+
+function listHtml(nodes: readonly TocNode[], ordered: boolean, root: boolean): string {
+	const tag = ordered ? "ol" : "ul";
+	const items = nodes
+		.map(
+			(n) =>
+				`<li><a href="#${escapeHtml(n.id)}">${escapeHtml(n.text)}</a>${n.children.length ? listHtml(n.children, ordered, false) : ""}</li>`,
+		)
+		.join("");
+	return `<${tag}${root ? ' class="cw-toc__list"' : ""}>${items}</${tag}>`;
+}
+
+/** The <nav> for a TOC tree. */
+export function renderTocHtml(tree: readonly TocNode[], o: TocRenderOptions): string {
+	const id = escapeHtml(o.titleId);
+	const title = escapeHtml(o.title);
+	const list = listHtml(tree, o.listStyle === "numbered", true);
+	const labelled = o.display !== "open" || o.showTitle;
+	const tag = tocTitleTag(o.titleTag);
+	const attrs = [
+		`class="cw-toc cw-toc--${o.listStyle}"`,
+		labelled ? `aria-labelledby="${id}"` : `aria-label="${title}"`,
+		o.smooth ? "data-smooth" : "",
+	]
+		.filter(Boolean)
+		.join(" ");
+	const body =
+		o.display === "open"
+			? `${o.showTitle ? `<${tag} id="${id}" class="cw-toc__title">${title}</${tag}>` : ""}${list}`
+			: `<details class="cw-toc__details"${o.display === "collapsible" ? " open" : ""}><summary class="cw-toc__summary"><span id="${id}" class="cw-toc__title">${title}</span></summary>${list}</details>`;
+	return `<nav ${attrs}>${body}</nav>`;
+}
+
+/** Sample headings for the admin preview (H2–H4, so level choices show). */
+export const SAMPLE_TOC_HEADINGS = [
+	{ level: 2, id: "jump-getting-started", text: "Getting started" },
+	{ level: 3, id: "jump-what-you-need", text: "What you need" },
+	{ level: 3, id: "jump-first-steps", text: "First steps" },
+	{ level: 4, id: "jump-a-quick-tip", text: "A quick tip" },
+	{ level: 2, id: "jump-how-it-works", text: "How it works" },
+	{ level: 3, id: "jump-the-details", text: "The details" },
+	{ level: 2, id: "jump-final-thoughts", text: "Final thoughts" },
+];
+
+export const TOC_CSS = `.cw-toc {
+	--cw-toc-line: color-mix(in srgb, currentColor 18%, transparent);
+	--cw-toc-bg: color-mix(in srgb, currentColor 4%, transparent);
+	margin-block: 1.5em;
+	padding: 1em 1.25em;
+	border: 1px solid var(--cw-toc-line);
+	border-radius: 0.5em;
+	background: var(--cw-toc-bg);
+}
+@media (prefers-color-scheme: dark) {
+	.cw-toc {
+		--cw-toc-bg: color-mix(in srgb, currentColor 7%, transparent);
+	}
+}
+.cw-toc .cw-toc__title {
+	margin: 0 0 0.5em;
+	font-size: 1.1em;
+}
+.cw-toc ul,
+.cw-toc ol {
+	margin: 0;
+}
+.cw-toc li {
+	margin: 0.25em 0;
+}
+.cw-toc--none ul,
+.cw-toc--numbered ol {
+	list-style: none;
+	padding-inline-start: 0;
+}
+.cw-toc--none li > ul,
+.cw-toc--bulleted ul {
+	padding-inline-start: 1.25em;
+}
+.cw-toc--numbered ol {
+	counter-reset: cw-toc;
+}
+.cw-toc--numbered li > ol {
+	padding-inline-start: 1.5em;
+}
+.cw-toc--numbered li {
+	counter-increment: cw-toc;
+}
+.cw-toc--numbered li > a::before {
+	content: counters(cw-toc, ".") ". ";
+}
+.cw-toc__summary {
+	cursor: pointer;
+}
+.cw-toc__summary .cw-toc__title {
+	display: inline;
+	margin: 0;
+	font-size: inherit;
+	font-weight: 600;
+}
+.cw-toc__details[open] > .cw-toc__summary {
+	margin-bottom: 0.5em;
+}
+@media (prefers-reduced-motion: no-preference) {
+	html:has(.cw-toc[data-smooth]) {
+		scroll-behavior: smooth;
+	}
+}`;

package/src/headings/settings.ts

@@ -0,0 +1,117 @@
+/**
+ * Headings & TOC site defaults: one plugin setting ("headings"). Hooks and
+ * routes read it through the plugin context; Astro components read the same
+ * option row from D1 in the feature switches' query and per-isolate cache.
+ */
+import { invalidateFeatures, readSiteSetting, registerSiteSetting } from "../core/features.js";
+import { validPrefix } from "./slug.js";
+
+export const SETTINGS_KEY = "headings";
+
+export type TocListStyle = "none" | "bulleted" | "numbered";
+export type TocDisplay = "open" | "collapsible" | "collapsed";
+
+export interface HeadingsSettings {
+	/** Prefix for generated heading ids ("jump-"). */
+	prefix: string;
+	/** Show a "copy link to section" link on hover/focus. */
+	copyLink: boolean;
+	/** scroll-margin-top for anchored headings, so a sticky header doesn't cover them. 0 = none. */
+	scrollOffset: number;
+	scrollUnit: "px" | "rem";
+	toc: {
+		title: string;
+		/** Show the title above the list. A collapsible table always shows it (it's the toggle). */
+		showTitle: boolean;
+		levels: number[];
+		listStyle: TocListStyle;
+		display: TocDisplay;
+		/** Hide the table when it would list fewer headings than this. */
+		minHeadings: number;
+		/** Smooth scrolling on TOC pages (always off for visitors who prefer reduced motion). */
+		smoothScroll: boolean;
+	};
+}
+
+export const DEFAULT_SETTINGS: HeadingsSettings = {
+	prefix: "jump-",
+	copyLink: false,
+	scrollOffset: 0,
+	scrollUnit: "px",
+	toc: { title: "Table of contents", showTitle: true, levels: [2, 3], listStyle: "none", display: "open", minHeadings: 2, smoothScroll: true },
+};
+
+const pick = <T extends string>(value: unknown, allowed: readonly T[], fallback: T): T =>
+	allowed.includes(value as T) ? (value as T) : fallback;
+const bool = (value: unknown, fallback: boolean) => (typeof value === "boolean" ? value : fallback);
+const int = (value: unknown, min: number, max: number, fallback: number) =>
+	typeof value === "number" && Number.isFinite(value) ? Math.min(max, Math.max(min, Math.round(value))) : fallback;
+const text = (value: unknown, max: number, fallback: string) =>
+	typeof value === "string" ? value.replace(/[\u0000-\u001f<>]/g, "").trim().slice(0, max) : fallback;
+
+/** Heading levels from block or setting input (numbers or "2"/"h2" strings), sorted, 2–6. */
+export function parseLevels(value: unknown): number[] {
+	if (!Array.isArray(value)) return [];
+	const levels = value
+		.map((v) => (typeof v === "number" ? v : Number(String(v).replace(/^h/i, ""))))
+		.filter((n) => Number.isInteger(n) && n >= 2 && n <= 6);
+	return [...new Set(levels)].sort((a, b) => a - b);
+}
+
+/** Fill in and clamp stored settings. Never throws. */
+export function normalizeSettings(raw: unknown): HeadingsSettings {
+	const r = (raw && typeof raw === "object" ? raw : {}) as Record<string, unknown>;
+	const toc = (r.toc && typeof r.toc === "object" ? r.toc : {}) as Record<string, unknown>;
+	const d = DEFAULT_SETTINGS;
+	const levels = parseLevels(toc.levels);
+	return {
+		prefix: validPrefix(r.prefix) ? r.prefix : d.prefix,
+		copyLink: bool(r.copyLink, d.copyLink),
+		scrollOffset: int(r.scrollOffset, 0, 500, d.scrollOffset),
+		scrollUnit: pick(r.scrollUnit, ["px", "rem"], d.scrollUnit),
+		toc: {
+			title: text(toc.title, 100, d.toc.title) || d.toc.title,
+			showTitle: bool(toc.showTitle, d.toc.showTitle),
+			levels: levels.length ? levels : d.toc.levels,
+			listStyle: pick(toc.listStyle, ["none", "bulleted", "numbered"], d.toc.listStyle),
+			display: pick(toc.display, ["open", "collapsible", "collapsed"], d.toc.display),
+			minHeadings: int(toc.minHeadings, 1, 10, d.toc.minHeadings),
+			smoothScroll: bool(toc.smoothScroll, d.toc.smoothScroll),
+		},
+	};
+}
+
+/**
+ * The value to store when Headings & TOC settings are saved. Breadcrumb
+ * defaults used to live in this setting (`breadcrumbs`); Breadcrumb Nav
+ * falls back to that sub-object until it saves its own setting, so it's
+ * carried over unchanged rather than dropped.
+ */
+export function withLegacyBreadcrumbs(previous: unknown, settings: HeadingsSettings): HeadingsSettings & { breadcrumbs?: unknown } {
+	const legacy = previous && typeof previous === "object" ? (previous as Record<string, unknown>).breadcrumbs : undefined;
+	return legacy && typeof legacy === "object" ? { ...settings, breadcrumbs: legacy } : settings;
+}
+
+// ── Outside the plugin context (Astro components) ────────────────
+
+registerSiteSetting(SETTINGS_KEY);
+
+/** The last stored value and its normalized settings, so a cache hit doesn't normalize again. */
+let memo: { raw: unknown; settings: HeadingsSettings } | null = null;
+
+export function invalidateHeadingsSettings(): void {
+	invalidateFeatures();
+}
+
+/** The settings from D1 (in the feature switches' query and cache). Falls back to defaults if the database can't be read. */
+export async function siteHeadingsSettings(database = "DB"): Promise<HeadingsSettings> {
+	const read = await readSiteSetting(SETTINGS_KEY, database);
+	if (!read) {
+		console.error("coywolf-pack: could not read heading settings");
+		return DEFAULT_SETTINGS;
+	}
+	if (memo && memo.raw === read.value) return memo.settings;
+	const settings = normalizeSettings(read.value);
+	memo = { raw: read.value, settings };
+	return settings;
+}

package/src/headings/slug.ts

@@ -0,0 +1,68 @@
+/**
+ * Heading anchor slugs, ported from Coywolf SEO (WordPress `sanitize_title`
+ * plus a `jump-` prefix): lowercase, accents removed, punctuation dropped,
+ * spaces to hyphens, unique within the document.
+ */
+
+/** A Portable Text heading level from a block's style ("h2" → 2), or null. */
+export function headingLevel(block: unknown): number | null {
+	if (!block || typeof block !== "object") return null;
+	const b = block as { _type?: unknown; style?: unknown };
+	if (b._type !== "block" || typeof b.style !== "string") return null;
+	const match = /^h([1-6])$/.exec(b.style);
+	return match ? Number(match[1]) : null;
+}
+
+/**
+ * The plain text of a Portable Text block. Walks nested `children`, so it
+ * also works on the marks tree astro-portabletext hands block components.
+ */
+export function blockText(block: unknown): string {
+	const parts: string[] = [];
+	const walk = (node: unknown) => {
+		if (!node || typeof node !== "object") return;
+		const { text, children } = node as { text?: unknown; children?: unknown };
+		if (typeof text === "string") parts.push(text);
+		else if (Array.isArray(children)) children.forEach(walk);
+	};
+	const children = (block as { children?: unknown })?.children;
+	if (Array.isArray(children)) children.forEach(walk);
+	return parts.join("").replace(/\s+/g, " ").trim();
+}
+
+const MAX_SLUG = 80;
+
+/** A URL-safe slug for heading text ("Don't Panic!" → "dont-panic"). Empty text gives "". */
+export function slugify(text: string): string {
+	const slug = text
+		.normalize("NFKD")
+		.replace(/\p{M}+/gu, "")
+		.toLowerCase()
+		.replace(/&[a-z0-9#]+;/g, "")
+		.replace(/[^\p{L}\p{N}\s_-]+/gu, "")
+		.trim()
+		.replace(/[\s_]+/g, "-")
+		.replace(/-{2,}/g, "-")
+		.replace(/^-+|-+$/g, "");
+	return slug.length > MAX_SLUG ? slug.slice(0, MAX_SLUG).replace(/-+$/, "") : slug;
+}
+
+/** A prefix is empty or a short id-safe string starting with a letter. */
+export function validPrefix(prefix: unknown): prefix is string {
+	return typeof prefix === "string" && /^(?:[A-Za-z][A-Za-z0-9_-]{0,19})?$/.test(prefix);
+}
+
+/** Whether a stored anchor is safe to emit as an HTML id and in a fragment link. */
+export function validAnchor(anchor: unknown): anchor is string {
+	return typeof anchor === "string" && anchor.length <= 120 && /^[\p{L}][\p{L}\p{N}_-]*$/u.test(anchor);
+}
+
+/** `prefix + slug(text)`, with -2, -3… appended until it's not in `taken`. Adds the result to `taken`. */
+export function uniqueSlug(text: string, taken: Set<string>, prefix = "jump-"): string {
+	let base = `${prefix}${slugify(text) || "section"}`;
+	if (!/^\p{L}/u.test(base)) base = `h-${base}`;
+	let slug = base;
+	for (let i = 2; taken.has(slug); i++) slug = `${base}-${i}`;
+	taken.add(slug);
+	return slug;
+}