@coywolf/emdash 0.0.0-stage → 0.35.14

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;
+}

package/src/headings/stamp.ts

@@ -0,0 +1,142 @@
+/**
+ * Save-time stamping (content:beforeSave). EmDash's Portable Text renderer
+ * emits headings without ids, and a block component only sees its own node,
+ * so everything the site needs is written into the content when it's saved:
+ *
+ * - each H2–H6 heading block gets an `anchor` field (e.g. "jump-pricing"),
+ *   unique within its field and kept across edits (matched to the previous
+ *   save by block `_key`, then by text), because the editor drops unknown
+ *   fields on heading blocks;
+ * - each `coywolf-toc` block gets `_headings`, the field's heading list.
+ *
+ * (Breadcrumbs blocks are stamped by the Breadcrumb Nav module, src/breadcrumbs/stamp.ts.)
+ *
+ * Pure: returns new objects and never mutates its input. Running it twice
+ * gives the same result (`changed: false` the second time).
+ */
+import { blockText, headingLevel, uniqueSlug, validAnchor } from "./slug.js";
+import type { TocHeading } from "./toc.js";
+
+export const TOC_BLOCK = "coywolf-toc";
+export const ANCHOR_LEVELS = [2, 3, 4, 5, 6];
+
+export interface StampOptions {
+	/** Stamp heading anchors (and TOC heading lists, when `toc`). */
+	anchors: boolean;
+	toc: boolean;
+	prefix: string;
+	/** The entry's stored data before this save, to keep anchors stable. */
+	previous?: Record<string, unknown> | null;
+}
+
+type Block = Record<string, unknown> & { _type: string; _key?: 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")
+	);
+}
+
+function sameJson(a: unknown, b: unknown): boolean {
+	return JSON.stringify(a) === JSON.stringify(b);
+}
+
+/** Previous anchors of one field, by block key and by heading text. */
+function previousAnchors(previous: unknown) {
+	const byKey = new Map<string, string>();
+	const byText = new Map<string, string>();
+	if (isPortableText(previous)) {
+		for (const block of previous) {
+			if (!headingLevel(block) || !validAnchor(block.anchor)) continue;
+			if (typeof block._key === "string") byKey.set(block._key, block.anchor);
+			const text = blockText(block);
+			if (text && !byText.has(text)) byText.set(text, block.anchor);
+		}
+	}
+	return { byKey, byText };
+}
+
+/** Stamp one Portable Text field. Returns the new array, or null when nothing changed. */
+export function stampField(blocks: Block[], options: StampOptions, previousField: unknown): Block[] | null {
+	const out = blocks.slice();
+	let changed = false;
+	const set = (i: number, patch: Record<string, unknown>, remove?: string) => {
+		const next: Block = { ...out[i], ...patch };
+		if (remove) delete next[remove];
+		out[i] = next;
+		changed = true;
+	};
+
+	const headings: TocHeading[] = [];
+	if (options.anchors) {
+		const { byKey, byText } = previousAnchors(previousField);
+		const taken = new Set<string>();
+		const pending: { index: number; level: number; text: string; kept: string | null; byText: string | null }[] = [];
+
+		blocks.forEach((block, index) => {
+			const level = headingLevel(block);
+			if (!level || !ANCHOR_LEVELS.includes(level)) return;
+			const text = blockText(block);
+			if (!text) {
+				if ("anchor" in block) set(index, {}, "anchor");
+				return;
+			}
+			const kept = (validAnchor(block.anchor) ? block.anchor : null) ?? (typeof block._key === "string" ? byKey.get(block._key) : undefined) ?? null;
+			pending.push({ index, level, text, kept, byText: byText.get(text) ?? null });
+		});
+
+		// Claim anchors in priority order (first claim wins): the block's own or its previous
+		// anchor (by _key), then a previous anchor with the same text, then a new slug.
+		const ids = new Map<number, string>();
+		const claim = (pick: (p: (typeof pending)[number]) => string | null) => {
+			for (const p of pending) {
+				const id = ids.has(p.index) ? null : pick(p);
+				if (id && !taken.has(id)) {
+					taken.add(id);
+					ids.set(p.index, id);
+				}
+			}
+		};
+		claim((p) => p.kept);
+		claim((p) => p.byText);
+		for (const p of pending) if (!ids.has(p.index)) ids.set(p.index, uniqueSlug(p.text, taken, options.prefix));
+
+		for (const p of pending) {
+			const id = ids.get(p.index) as string;
+			if (blocks[p.index].anchor !== id) set(p.index, { anchor: id });
+			headings.push({ level: p.level, id, text: p.text });
+		}
+	}
+
+	if (options.toc && options.anchors) {
+		blocks.forEach((block, index) => {
+			if (block._type === TOC_BLOCK && !sameJson(block._headings, headings)) set(index, { _headings: headings });
+		});
+	}
+
+	return changed ? out : null;
+}
+
+/** Stamp every Portable Text field of an entry. Returns the new content, or null when nothing changed. */
+export function stampContent(content: Record<string, unknown>, options: StampOptions): Record<string, unknown> | null {
+	let result: Record<string, unknown> | null = null;
+	for (const [field, value] of Object.entries(content)) {
+		if (!isPortableText(value)) continue;
+		const stamped = stampField(value, options, options.previous?.[field]);
+		if (stamped) {
+			result ??= { ...content };
+			result[field] = stamped;
+		}
+	}
+	return result;
+}
+
+/** Whether any field has a heading without a valid anchor (so the previous version is worth reading). */
+export function needsPrevious(content: Record<string, unknown>): boolean {
+	return Object.values(content).some(
+		(value) => isPortableText(value) && value.some((block) => headingLevel(block) && !validAnchor(block.anchor)),
+	);
+}

package/src/headings/test-hooks.mjs

@@ -0,0 +1,14 @@
+// Test-only resolve hook: source files import "./x.js" (bundler style); under
+// `node --test` with type stripping, map those to the sibling .ts file.
+import { registerHooks } from "node:module";
+
+registerHooks({
+	resolve(specifier, context, next) {
+		try {
+			return next(specifier, context);
+		} catch (error) {
+			if (specifier.startsWith(".") && specifier.endsWith(".js")) return next(specifier.slice(0, -3) + ".ts", context);
+			throw error;
+		}
+	},
+});

package/src/headings/toc.ts

@@ -0,0 +1,48 @@
+/**
+ * Table of contents tree: the flat heading list stamped into a TOC block,
+ * filtered to the block's levels and nested by level. Tolerant of skipped
+ * levels (an H4 straight after an H2 nests under the H2).
+ */
+
+export interface TocHeading {
+	level: number;
+	id: string;
+	text: string;
+}
+
+export interface TocNode extends TocHeading {
+	children: TocNode[];
+}
+
+export function buildTocTree(headings: readonly TocHeading[], levels: readonly number[]): TocNode[] {
+	const wanted = new Set(levels);
+	const root: TocNode[] = [];
+	const stack: TocNode[] = [];
+	for (const heading of headings) {
+		if (!wanted.has(heading.level)) continue;
+		const node: TocNode = { level: heading.level, id: heading.id, text: heading.text, children: [] };
+		while (stack.length && stack[stack.length - 1].level >= node.level) stack.pop();
+		(stack.length ? stack[stack.length - 1].children : root).push(node);
+		stack.push(node);
+	}
+	return root;
+}
+
+/** Count every node in a tree. */
+export function countToc(nodes: readonly TocNode[]): number {
+	return nodes.reduce((n, node) => n + 1 + countToc(node.children), 0);
+}
+
+/** Clean the heading list stored on a TOC block (it's content data, so treat it as untrusted). */
+export function storedHeadings(value: unknown): TocHeading[] {
+	if (!Array.isArray(value)) return [];
+	const out: TocHeading[] = [];
+	for (const item of value) {
+		if (!item || typeof item !== "object") continue;
+		const { level, id, text } = item as Record<string, unknown>;
+		if (typeof level !== "number" || level < 1 || level > 6) continue;
+		if (typeof id !== "string" || !id || typeof text !== "string" || !text) continue;
+		out.push({ level, id, text });
+	}
+	return out;
+}