@coywolf/emdash 0.0.0-stage → 0.35.13

package/src/backups/store.ts

@@ -0,0 +1,409 @@
+/**
+ * Backup storage layout (shared with .github/workflows/backup.yml):
+ *
+ *   d1/<stamp>/<file>.sql.gz   database dump
+ *   d1/<stamp>/manifest.json   what the dump is and where it came from
+ *   media/current/<key>        mirror of the media bucket
+ *   media/changed/<stamp>/<key> media replaced or deleted since the previous run
+ *   uploads/current/<key>      mirror of the private form uploads bucket (when bound)
+ *   uploads/changed/<stamp>/<key> uploads replaced or deleted since the previous run
+ *
+ * The backup bucket must stay private: uploads/ holds files people sent
+ * through forms, which aren't public on the site.
+ */
+
+export interface Manifest {
+	stamp: string;
+	database?: string;
+	file: string;
+	bytes: number;
+	sha256: string;
+	/** "github-actions" (external nightly job), "scheduled" (plugin), or "admin" (Back up now). */
+	source?: string;
+	timeTravelBookmark?: string;
+	gitSha?: string;
+	tables?: number;
+	rows?: number;
+	media?: MirrorResult;
+	/** Private form uploads, when the site has an uploads bucket. */
+	uploads?: MirrorResult;
+}
+
+export interface MirrorResult {
+	copied: number;
+	preserved: number;
+	total: number;
+	pending?: number;
+}
+
+/** Folder in the backup bucket for each mirrored bucket. */
+export type MirrorPrefix = "media" | "uploads";
+
+export interface BackupEntry extends Manifest {
+	createdAt: string;
+}
+
+export const STAMP = /^\d{4}-\d{2}-\d{2}T\d{4}Z$/;
+export const FILE = /^[a-z0-9._-]+$/i;
+
+/** 2026-10-03T1802Z — sortable, safe in object keys and URLs. */
+export function makeStamp(date = new Date()): string {
+	const iso = date.toISOString();
+	return `${iso.slice(0, 13)}${iso.slice(14, 16)}Z`;
+}
+
+export function stampToDate(stamp: string): Date {
+	return new Date(`${stamp.slice(0, 13)}:${stamp.slice(13, 15)}:00Z`);
+}
+
+async function sha256(bytes: Uint8Array<ArrayBuffer>): Promise<string> {
+	const digest = await crypto.subtle.digest("SHA-256", bytes);
+	return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+/** R2's smallest multipart part. Every part but the last must be the same size. */
+export const PART_BYTES = 5 * 1024 * 1024;
+/** Text handed to the gzip stream at a time. */
+const FEED_BYTES = 64 * 1024;
+const utf8 = new TextEncoder();
+
+/** SHA-256 over a stream of chunks: Workers' DigestStream, else (Node tests) the chunks kept and hashed at the end. */
+function digester(): { update(chunk: Uint8Array<ArrayBuffer>): Promise<void>; digest(): Promise<string> } {
+	const hex = (digest: ArrayBuffer) => [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+	const Stream = (crypto as unknown as { DigestStream?: new (algorithm: string) => WritableStream<Uint8Array> & { digest: Promise<ArrayBuffer> } }).DigestStream;
+	if (Stream) {
+		const stream = new Stream("SHA-256");
+		const writer = stream.getWriter();
+		return {
+			update: (chunk) => writer.write(chunk),
+			digest: async () => {
+				await writer.close();
+				return hex(await stream.digest);
+			},
+		};
+	}
+	const chunks: Uint8Array<ArrayBuffer>[] = [];
+	return {
+		update: async (chunk) => {
+			chunks.push(chunk);
+		},
+		digest: () => sha256(concat(chunks, chunks.reduce((n, c) => n + c.byteLength, 0))),
+	};
+}
+
+function concat(chunks: Uint8Array<ArrayBuffer>[], size: number): Uint8Array<ArrayBuffer> {
+	const out = new Uint8Array(size);
+	let at = 0;
+	for (const chunk of chunks) {
+		out.set(chunk, at);
+		at += chunk.byteLength;
+	}
+	return out;
+}
+
+/**
+ * Gzip the dump's statements (one per line) straight into the backup bucket:
+ * one put when it's under a part, else an R2 multipart upload in PART_BYTES
+ * parts. Memory stays around one part plus a page of rows, however big the
+ * database. Returns the stored size and SHA-256 of the gzip file.
+ */
+export async function writeDumpStream(
+	bucket: R2Bucket,
+	stamp: string,
+	file: string,
+	lines: AsyncIterable<string>,
+	partBytes = PART_BYTES,
+): Promise<{ bytes: number; sha256: string }> {
+	const key = `d1/${stamp}/${file}`;
+	const httpMetadata = { contentType: "application/gzip" };
+	const gzip = new CompressionStream("gzip");
+	const writer = gzip.writable.getWriter();
+	// Feed the compressor while the loop below drains it (each waits on the other).
+	/** An error from the dump itself (a failed query), which explains more than the stream errors it causes. */
+	let dumpError: { error: unknown } | null = null;
+	const feed = (async () => {
+		let batch = "";
+		const iterator = lines[Symbol.asyncIterator]();
+		for (;;) {
+			let next: IteratorResult<string>;
+			try {
+				next = await iterator.next();
+			} catch (error) {
+				dumpError = { error };
+				throw error;
+			}
+			if (next.done) break;
+			batch += `${next.value}\n`;
+			if (batch.length >= FEED_BYTES) {
+				await writer.write(utf8.encode(batch));
+				batch = "";
+			}
+		}
+		if (batch) await writer.write(utf8.encode(batch));
+		await writer.close();
+	})();
+	feed.catch((error) => writer.abort(error).catch(() => undefined));
+
+	const hash = digester();
+	let pending: Uint8Array<ArrayBuffer>[] = [];
+	let pendingBytes = 0;
+	let bytes = 0;
+	/** The first `size` pending bytes as one buffer; the rest stay pending. */
+	const take = (size: number): Uint8Array<ArrayBuffer> => {
+		const all = concat(pending, pendingBytes);
+		pending = size < pendingBytes ? [all.slice(size)] : [];
+		pendingBytes -= size;
+		return size < all.byteLength ? all.slice(0, size) : all;
+	};
+
+	let upload: R2MultipartUpload | null = null;
+	const parts: R2UploadedPart[] = [];
+	const reader = gzip.readable.getReader();
+	try {
+		for (;;) {
+			const { value, done } = await reader.read();
+			if (done) break;
+			const chunk = value as Uint8Array<ArrayBuffer>;
+			bytes += chunk.byteLength;
+			await hash.update(chunk);
+			pending.push(chunk);
+			pendingBytes += chunk.byteLength;
+			while (pendingBytes >= partBytes) {
+				upload ??= await bucket.createMultipartUpload(key, { httpMetadata });
+				parts.push(await upload.uploadPart(parts.length + 1, take(partBytes)));
+			}
+		}
+		await feed;
+		const rest = take(pendingBytes);
+		if (upload) {
+			if (rest.byteLength) parts.push(await upload.uploadPart(parts.length + 1, rest));
+			await upload.complete(parts);
+		} else {
+			await bucket.put(key, rest, { httpMetadata });
+		}
+	} catch (error) {
+		await upload?.abort().catch(() => undefined);
+		// Unblock the feed (it may be waiting for room in the stream) and let it finish.
+		await reader.cancel(error).catch(() => undefined);
+		await feed.catch(() => undefined);
+		throw dumpError ? (dumpError as { error: unknown }).error : error;
+	}
+	return { bytes, sha256: await hash.digest() };
+}
+
+/** Write (or rewrite) a backup's manifest for a dump already stored. */
+export async function writeManifest(
+	bucket: R2Bucket,
+	stamp: string,
+	file: string,
+	written: { bytes: number; sha256: string },
+	extra: Partial<Manifest>,
+): Promise<Manifest> {
+	const manifest: Manifest = { ...extra, stamp, file, bytes: written.bytes, sha256: written.sha256 };
+	await bucket.put(`d1/${stamp}/manifest.json`, JSON.stringify(manifest, null, 1), {
+		httpMetadata: { contentType: "application/json" },
+	});
+	return manifest;
+}
+
+
+/** Every backup with a manifest, newest first. */
+export async function listBackups(bucket: R2Bucket): Promise<BackupEntry[]> {
+	const stamps: string[] = [];
+	let cursor: string | undefined;
+	do {
+		const page = await bucket.list({ prefix: "d1/", delimiter: "/", cursor });
+		for (const prefix of page.delimitedPrefixes) {
+			const stamp = prefix.slice(3, -1);
+			if (STAMP.test(stamp)) stamps.push(stamp);
+		}
+		cursor = page.truncated ? page.cursor : undefined;
+	} while (cursor);
+
+	const entries = await Promise.all(
+		stamps.map(async (stamp) => {
+			const object = await bucket.get(`d1/${stamp}/manifest.json`);
+			if (!object) return null;
+			try {
+				const manifest = (await object.json()) as Manifest;
+				return { ...manifest, stamp, createdAt: stampToDate(stamp).toISOString() };
+			} catch {
+				return null;
+			}
+		}),
+	);
+	return entries.filter((e): e is BackupEntry => e !== null).sort((a, b) => b.stamp.localeCompare(a.stamp));
+}
+
+/**
+ * Mirror the media bucket into media/current/, moving anything replaced or
+ * deleted since the last run to media/changed/<stamp>/ (same as the nightly
+ * job's `rclone sync --backup-dir`). Compares by ETag.
+ *
+ * Copies at most `maxChanges` files per run so a large first mirror stays under
+ * the Workers subrequest limit; the rest are reported as `pending` and copied
+ * on the next run.
+ */
+export async function mirrorMedia(media: R2Bucket, backups: R2Bucket, stamp: string, maxChanges = 300): Promise<MirrorResult> {
+	return mirrorBucket(media, backups, stamp, "media", maxChanges);
+}
+
+/** mirrorMedia for any bucket, into <prefix>/current/ and <prefix>/changed/<stamp>/. */
+export async function mirrorBucket(
+	media: R2Bucket,
+	backups: R2Bucket,
+	stamp: string,
+	prefix: MirrorPrefix,
+	maxChanges = 300,
+): Promise<MirrorResult> {
+	const current = `${prefix}/current/`;
+	const source = new Map<string, string>();
+	let cursor: string | undefined;
+	do {
+		const page = await media.list({ cursor });
+		for (const object of page.objects) source.set(object.key, object.etag);
+		cursor = page.truncated ? page.cursor : undefined;
+	} while (cursor);
+
+	const mirror = new Map<string, string>();
+	do {
+		const page = await backups.list({ prefix: current, cursor });
+		for (const object of page.objects) mirror.set(object.key.slice(current.length), object.etag);
+		cursor = page.truncated ? page.cursor : undefined;
+	} while (cursor);
+
+	let copied = 0;
+	let preserved = 0;
+	const keep = async (key: string) => {
+		const old = await backups.get(`${current}${key}`);
+		if (!old) return;
+		await backups.put(`${prefix}/changed/${stamp}/${key}`, old.body, { httpMetadata: old.httpMetadata });
+		preserved++;
+	};
+
+	// Decide the changes first, then make them a few files at a time.
+	const tasks: Array<() => Promise<void>> = [];
+	let pending = 0;
+	for (const [key, etag] of source) {
+		if (mirror.get(key) === etag) continue;
+		if (tasks.length >= maxChanges) {
+			pending++;
+			continue;
+		}
+		tasks.push(async () => {
+			if (mirror.has(key)) await keep(key);
+			const object = await media.get(key);
+			if (!object) return;
+			await backups.put(`${current}${key}`, object.body, { httpMetadata: object.httpMetadata });
+			copied++;
+		});
+	}
+	for (const key of mirror.keys()) {
+		if (source.has(key)) continue;
+		if (tasks.length >= maxChanges) {
+			pending++;
+			continue;
+		}
+		tasks.push(async () => {
+			await keep(key);
+			await backups.delete(`${current}${key}`);
+		});
+	}
+	await inPool(tasks, MIRROR_CONCURRENCY);
+	return { copied, preserved, total: source.size, pending };
+}
+
+/** Files copied at once when mirroring (each copy is a get and a put, streamed). */
+export const MIRROR_CONCURRENCY = 8;
+
+/** Run tasks with at most `limit` in flight; the first failure is thrown once the others settle. */
+async function inPool(tasks: Array<() => Promise<void>>, limit: number): Promise<void> {
+	let next = 0;
+	let failure: { error: unknown } | null = null;
+	const worker = async () => {
+		while (next < tasks.length && !failure) {
+			const task = tasks[next++];
+			try {
+				await task();
+			} catch (error) {
+				failure ??= { error };
+			}
+		}
+	};
+	await Promise.all(Array.from({ length: Math.min(limit, tasks.length) }, worker));
+	if (failure) throw (failure as { error: unknown }).error;
+}
+
+/**
+ * Copy media files that are in the backup mirror but missing from the media
+ * bucket. Never overwrites. Copies at most `max` files per call so one request
+ * stays well inside Worker limits; `pending` is what's left for the next call
+ * (a coywolf.com restore trial copied 2,021 files in one request and took
+ * over five minutes).
+ */
+export async function restoreMissingMedia(
+	media: R2Bucket,
+	backups: R2Bucket,
+	max = 200,
+	prefix: MirrorPrefix = "media",
+): Promise<{ restored: number; checked: number; pending: number }> {
+	const current = `${prefix}/current/`;
+	const present = new Set<string>();
+	let cursor: string | undefined;
+	do {
+		const page = await media.list({ cursor });
+		for (const o of page.objects) present.add(o.key);
+		cursor = page.truncated ? page.cursor : undefined;
+	} while (cursor);
+
+	let restored = 0;
+	let checked = 0;
+	let pending = 0;
+	do {
+		const page = await backups.list({ prefix: current, cursor });
+		for (const o of page.objects) {
+			checked++;
+			const key = o.key.slice(current.length);
+			if (present.has(key)) continue;
+			if (restored >= max) {
+				pending++;
+				continue;
+			}
+			const object = await backups.get(o.key);
+			if (!object) continue;
+			await media.put(key, object.body, { httpMetadata: object.httpMetadata });
+			restored++;
+		}
+		cursor = page.truncated ? page.cursor : undefined;
+	} while (cursor);
+	return { restored, checked, pending };
+}
+
+/** Delete database backups and replaced media and upload copies older than `days`. Returns the number of stamps pruned. */
+export async function pruneBackups(bucket: R2Bucket, days: number): Promise<number> {
+	const cutoff = makeStamp(new Date(Date.now() - days * 86_400_000));
+	let pruned = 0;
+	for (const prefix of ["d1/", "media/changed/", "uploads/changed/"]) {
+		let cursor: string | undefined;
+		do {
+			const page = await bucket.list({ prefix, delimiter: "/", cursor });
+			for (const dir of page.delimitedPrefixes) {
+				const stamp = dir.slice(prefix.length, -1);
+				if (!STAMP.test(stamp) || stamp >= cutoff) continue;
+				await deletePrefix(bucket, dir);
+				if (prefix === "d1/") pruned++;
+			}
+			cursor = page.truncated ? page.cursor : undefined;
+		} while (cursor);
+	}
+	return pruned;
+}
+
+async function deletePrefix(bucket: R2Bucket, prefix: string) {
+	let cursor: string | undefined;
+	do {
+		const page = await bucket.list({ prefix, cursor });
+		if (page.objects.length) await bucket.delete(page.objects.map((o) => o.key));
+		cursor = page.truncated ? page.cursor : undefined;
+	} while (cursor);
+}

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