emdash 0.29.0 → 0.31.0

package/src/cli/commands/media.ts

@@ -10,9 +10,12 @@ import { basename } from "node:path";
 import { defineCommand } from "citty";
 import { consola } from "consola";
 
+import type { MediaUsageRepairInput, MediaUsageRepairResponse } from "../../client/index.js";
 import { connectionArgs, createClientFromArgs } from "../client-factory.js";
 import { configureOutputMode, output } from "../output.js";
 
+const repairScopeError = "Specify exactly one of --collection or --all";
+
 const listCommand = defineCommand({
 	meta: {
 		name: "list",
@@ -155,6 +158,129 @@ const deleteCommand = defineCommand({
 	},
 });
 
+const repairUsageCommand = defineCommand({
+	meta: {
+		name: "repair-usage",
+		description:
+			"Repair content media usage indexes. partial/stale exit 0; automation should use --json and parse status.",
+	},
+	args: {
+		...connectionArgs,
+		collection: {
+			type: "string",
+			alias: "c",
+			description: "Repair one content collection",
+		},
+		all: {
+			type: "boolean",
+			description: "Repair every content collection",
+		},
+	},
+	async run({ args }) {
+		configureOutputMode(args);
+
+		const hasCollectionArg = args.collection !== undefined;
+		const hasCollection = typeof args.collection === "string";
+		const hasAll = args.all === true;
+		if ((hasCollectionArg && !hasCollection) || hasCollection === hasAll) {
+			consola.error(repairScopeError);
+			process.exit(1);
+		}
+
+		const client = createClientFromArgs(args);
+
+		try {
+			const repairInput: MediaUsageRepairInput = hasCollection
+				? { scope: "collection", collection: args.collection }
+				: { scope: "all" };
+			const result = await client.mediaRepairUsage(repairInput);
+
+			if (args.json || !process.stdout.isTTY) {
+				output(result, args);
+			} else {
+				printRepairUsageSummary(result, repairInput);
+			}
+
+			if (result.status === "failed") {
+				process.exitCode = 1;
+			}
+		} catch (error) {
+			consola.error(
+				"Failed to repair media usage:",
+				error instanceof Error ? error.message : error,
+			);
+			process.exit(1);
+		}
+	},
+});
+
+type RepairUsageSummary = {
+	level: "success" | "warn";
+	message: string;
+};
+
+export function formatRepairUsageSummary(
+	result: MediaUsageRepairResponse,
+	input: MediaUsageRepairInput,
+): RepairUsageSummary {
+	const counts = `indexed ${result.indexedSourceCount}, failed ${result.failedSourceCount}, skipped ${result.skippedSourceCount}, deleted ${result.deletedSourceCount}`;
+	const scope =
+		input.scope === "collection"
+			? `collection ${input.collection}`
+			: `all content (${formatCollectionCount(result.collections.length)})`;
+
+	if (result.status === "complete") {
+		return {
+			level: "success",
+			message: `Media usage repair complete for ${scope} (${counts}).`,
+		};
+	}
+
+	const details = result.collections
+		.filter((collection) => collection.status !== "complete")
+		.map((collection) => {
+			const error = collection.lastErrorCode ? `, ${collection.lastErrorCode}` : "";
+			return `${collection.collection}: ${collection.status}${error}`;
+		})
+		.join("; ");
+	const suffix = details ? ` ${details}.` : "";
+
+	if (result.status === "stale") {
+		return {
+			level: "warn",
+			message: `Media usage repair is stale for ${scope}; trustworthy complete coverage was not established because another writer, repair, or stale marker won the race. Rerun when writes are quiet (${counts}).${suffix}`,
+		};
+	}
+
+	if (result.status === "partial") {
+		return {
+			level: "warn",
+			message: `Media usage repair is partial for ${scope}; some sources or collections need attention (${counts}).${suffix}`,
+		};
+	}
+
+	return {
+		level: "warn",
+		message: `Media usage repair failed for ${scope} (${counts}).${suffix}`,
+	};
+}
+
+function printRepairUsageSummary(
+	result: MediaUsageRepairResponse,
+	input: MediaUsageRepairInput,
+): void {
+	const summary = formatRepairUsageSummary(result, input);
+	if (summary.level === "success") {
+		consola.success(summary.message);
+	} else {
+		consola.warn(summary.message);
+	}
+}
+
+function formatCollectionCount(count: number): string {
+	return `${count} collection${count === 1 ? "" : "s"}`;
+}
+
 export const mediaCommand = defineCommand({
 	meta: {
 		name: "media",
@@ -165,5 +291,6 @@ export const mediaCommand = defineCommand({
 		upload: uploadCommand,
 		get: getCommand,
 		delete: deleteCommand,
+		"repair-usage": repairUsageCommand,
 	},
 });

package/src/client/index.ts

@@ -127,6 +127,62 @@ export interface Field {
 	sortOrder?: number;
 }
 
+/** Aggregate trust state for media usage reads */
+export type MediaUsageCoverageStatus =
+	| "complete"
+	| "never"
+	| "running"
+	| "partial"
+	| "failed"
+	| "stale"
+	| "unknown";
+
+/** Aggregate media usage coverage across all content collections */
+export interface MediaUsageCoverage {
+	scope: "all_content_collections";
+	status: MediaUsageCoverageStatus;
+}
+
+/** Coverage-aware usage count for a media item */
+export interface MediaUsageSummary {
+	count: number | null;
+	coverage: MediaUsageCoverage;
+}
+
+/** One indexed media reference within a content source */
+export interface MediaUsageOccurrenceDetail {
+	fieldSlug: string;
+	fieldPath: string;
+	occurrenceIndex: number;
+	referenceType: "image_field" | "file_field" | "portable_text_image" | "unknown";
+}
+
+/** Indexed references from one visible content source */
+export interface MediaUsageSourceDetail {
+	variant: "columns" | "draft_overlay";
+	occurrences: MediaUsageOccurrenceDetail[];
+}
+
+/** One content entry that references a media item */
+export interface MediaUsageEntryDetail {
+	collection: string;
+	contentId: string;
+	title: string | null;
+	slug: string | null;
+	locale: string | null;
+	status: string | null;
+	scheduledAt: string | null;
+	deletedAt: string | null;
+	sources: MediaUsageSourceDetail[];
+}
+
+/** Entry-grouped media usage details */
+export interface MediaUsageDetailsResponse {
+	items: MediaUsageEntryDetail[];
+	nextCursor?: string;
+	coverage: MediaUsageCoverage;
+}
+
 /** Media item */
 export interface MediaItem {
 	id: string;
@@ -140,6 +196,7 @@ export interface MediaItem {
 	caption?: string;
 	createdAt: string;
 	updatedAt: string;
+	usage?: MediaUsageSummary;
 }
 
 /** Media usage repair request */
@@ -678,22 +735,47 @@ export class EmDashClient {
 		mimeType?: string;
 		limit?: number;
 		cursor?: string;
+		includeUsage?: boolean;
 	}): Promise<ListResult<MediaItem>> {
 		const params = new URLSearchParams();
 		if (options?.mimeType) params.set("mimeType", options.mimeType);
 		if (options?.limit) params.set("limit", String(options.limit));
 		if (options?.cursor) params.set("cursor", options.cursor);
+		if (options?.includeUsage === true) params.set("includeUsage", "1");
 
 		const qs = params.toString();
 		return this.request<ListResult<MediaItem>>("GET", `/media${qs ? `?${qs}` : ""}`);
 	}
 
 	/** Get a single media item */
-	async mediaGet(id: string): Promise<MediaItem> {
-		const data = await this.request<{ item: MediaItem }>("GET", `/media/${encodeURIComponent(id)}`);
+	async mediaGet(id: string, options?: { includeUsage?: boolean }): Promise<MediaItem> {
+		const params = new URLSearchParams();
+		if (options?.includeUsage === true) params.set("includeUsage", "1");
+
+		const qs = params.toString();
+		const data = await this.request<{ item: MediaItem }>(
+			"GET",
+			`/media/${encodeURIComponent(id)}${qs ? `?${qs}` : ""}`,
+		);
 		return data.item;
 	}
 
+	/** Get entry-grouped usage details for a media item */
+	async mediaGetUsage(
+		id: string,
+		options?: { limit?: number; cursor?: string },
+	): Promise<MediaUsageDetailsResponse> {
+		const params = new URLSearchParams();
+		if (options?.limit !== undefined) params.set("limit", String(options.limit));
+		if (options?.cursor !== undefined) params.set("cursor", options.cursor);
+
+		const qs = params.toString();
+		return this.request<MediaUsageDetailsResponse>(
+			"GET",
+			`/media/${encodeURIComponent(id)}/usage${qs ? `?${qs}` : ""}`,
+		);
+	}
+
 	/** Upload a media file */
 	async mediaUpload(
 		file: Uint8Array | Blob,

package/src/client/transport.ts

@@ -163,7 +163,7 @@ export function refreshInterceptor(options: {
 
 		const json = (await res.json()) as Record<string, unknown>;
 
-		// The token endpoint wraps the response in { data: ... } via apiSuccess.
+		// The token endpoint wraps the response in { success, data: ... } via apiSuccess.
 		// Handle both wrapped and bare shapes for robustness.
 		const tokenData: TokenFields =
 			json.data && typeof json.data === "object" && "access_token" in json.data

package/src/components/EmDashHead.astro

@@ -17,8 +17,10 @@
  * ```
  */
 import type { PublicPageContext, PageMetadataContribution } from "../plugins/types.js";
+// @ts-ignore - virtual module
+import virtualConfig from "virtual:emdash/config";
 import {
-	createSha256CspHash,
+	registerJsonLdCspHashes,
 	resolvePageMetadata,
 	renderPageMetadata,
 	type ResolvedPageMetadata,
@@ -124,13 +126,7 @@ if (runtime) {
 	metadataHtml = renderPageMetadata(resolved, { includeJsonLd: false });
 }
 
-if (Astro.csp && jsonLdScripts.length > 0) {
-	await Promise.all(
-		jsonLdScripts.map(async ({ json }) => {
-			Astro.csp?.insertScriptHash(await createSha256CspHash(json));
-		}),
-	);
-}
+await registerJsonLdCspHashes(virtualConfig.astroCspEnabled === true, () => Astro.csp, jsonLdScripts);
 ---
 
 <Fragment set:html={metadataHtml} />

package/src/components/Gallery.astro

@@ -2,11 +2,17 @@
 /**
  * Portable Text Gallery block component
  *
- * Renders image galleries from WordPress imports.
- * Uses Astro's Image component for optimization when dimensions are available.
+ * Renders image galleries from WordPress imports and EmDash media.
+ * Uses the provider's getEmbed/getSrc functions for external media (mirrors
+ * Image.astro), falling back to Astro's Image component when dimensions are
+ * available for locally-stored media.
  */
 import { Image as AstroImage } from "astro:assets";
+import type { ImageEmbed } from "../media/types.js";
+import { getMediaProvider } from "../media/provider-loader.js";
 import { buildRenderMediaUrl } from "../media/url.js";
+import { toAbsoluteMediaUrl, RESPONSIVE_BREAKPOINTS } from "../media/responsive.js";
+import { getPublicOrigin } from "../api/public-url.js";
 
 export interface Props {
 	node: {
@@ -18,50 +24,159 @@ export interface Props {
 			asset: {
 				_ref: string;
 				url?: string;
+				/** Provider ID for external media (e.g., "cloudflare-images") */
+				provider?: string;
 			};
 			alt?: string;
 			caption?: string;
 			width?: number;
 			height?: number;
+			/** LQIP blurhash placeholder (images only) */
+			blurhash?: string;
+			/** LQIP dominant-color placeholder, as a CSS color (images only) */
+			dominantColor?: string;
 		}>;
 		columns?: number;
 	};
+	/** Render the LQIP placeholder as an inline background. Disable for strict CSP. */
+	placeholder?: boolean;
 }
 
-const { node } = Astro.props;
+/**
+ * Generate srcset using provider's getSrc function
+ */
+function generateSrcset(
+	getSrc: NonNullable<ImageEmbed["getSrc"]>,
+	maxWidth: number,
+	aspectRatio?: number,
+): string {
+	return RESPONSIVE_BREAKPOINTS.filter((w) => w <= maxWidth * 2)
+		.map((w) => {
+			const h = aspectRatio ? Math.round(w / aspectRatio) : undefined;
+			return `${getSrc({ width: w, height: h })} ${w}w`;
+		})
+		.join(", ");
+}
+
+const { node, placeholder = true } = Astro.props;
 const images = node?.images ?? [];
 const columns = node?.columns ?? 3;
 
 if (!images.length) {
 	return null;
 }
+
+// Resolve provider embeds up front (async), keeping the template's `.map()`
+// synchronous over the resolved data — mirrors Image.astro's per-image logic.
+const resolvedImages = await Promise.all(
+	images.map(async (image) => {
+		const { asset, alt = "", width, height } = image;
+		const aspectRatio = width && height ? width / height : undefined;
+
+		let src = "";
+		let srcset: string | undefined;
+		let sizes: string | undefined;
+		let astroImageSrc = "";
+		const providerId = asset.provider;
+
+		if (providerId && providerId !== "local") {
+			const provider = await getMediaProvider(providerId);
+			if (provider) {
+				try {
+					const mediaValue = {
+						provider: providerId,
+						id: asset._ref,
+						width,
+						height,
+						alt,
+					};
+					const result = provider.getEmbed(mediaValue, { width, height });
+					const embed = result instanceof Promise ? await result : result;
+					if (embed.type === "image") {
+						src = embed.src;
+
+						if (embed.getSrc) {
+							const maxWidth = width || 1200;
+							srcset = generateSrcset(embed.getSrc, maxWidth, aspectRatio);
+							sizes = width ? `(min-width: ${width}px) ${width}px, 100vw` : "100vw";
+						}
+					}
+				} catch (error) {
+					console.warn(`Failed to get embed for image ${asset._ref}:`, error);
+				}
+			}
+		}
+
+		// Fallback for local provider. `asset.url` carries the storage key with
+		// extension when present; `asset._ref` is a bare ULID that only the
+		// internal `/file/{id}` route can resolve. `buildRenderMediaUrl` picks
+		// the right shape.
+		if (!src) {
+			src = buildRenderMediaUrl(Astro.locals.emdash?.getPublicMediaUrl, {
+				url: asset.url,
+				id: asset._ref,
+			});
+			if (width && height) {
+				astroImageSrc = toAbsoluteMediaUrl(
+					src,
+					getPublicOrigin(Astro.url, Astro.locals.emdash?.config),
+				);
+			}
+		}
+
+		// Prefer blurhash over dominant color for the LQIP placeholder, like
+		// Image.astro.
+		let placeholderStyle = "";
+		if (placeholder && image.blurhash) {
+			const { blurhashToImageCssString } = await import("@unpic/placeholder");
+			placeholderStyle = blurhashToImageCssString(image.blurhash);
+		} else if (placeholder && image.dominantColor) {
+			placeholderStyle = `background-color: ${image.dominantColor};`;
+		}
+
+		return {
+			key: image._key,
+			alt,
+			caption: image.caption,
+			width,
+			height,
+			src,
+			srcset,
+			sizes,
+			astroImageSrc,
+			placeholderStyle,
+		};
+	}),
+);
 ---
 
 <div class="emdash-gallery" style={`--columns: ${columns}`}>
 	{
-		images.map((image) => {
-			const src = buildRenderMediaUrl(Astro.locals.emdash?.getPublicMediaUrl, {
-				url: image.asset.url,
-				id: image.asset._ref,
-			});
-			const hasSize = image.width && image.height;
-			return (
-				<figure class="emdash-gallery-item">
-					{hasSize ? (
-						<AstroImage
-							src={src}
-							alt={image.alt || ""}
-							width={image.width!}
-							height={image.height!}
-							layout="constrained"
-						/>
-					) : (
-						<img src={src} alt={image.alt || ""} loading="lazy" decoding="async" />
-					)}
-					{image.caption && <figcaption>{image.caption}</figcaption>}
-				</figure>
-			);
-		})
+		resolvedImages.map((image) => (
+			<figure class="emdash-gallery-item" style={image.placeholderStyle || undefined}>
+				{image.astroImageSrc ? (
+					<AstroImage
+						src={image.astroImageSrc}
+						alt={image.alt}
+						width={image.width!}
+						height={image.height!}
+						layout="constrained"
+					/>
+				) : (
+					<img
+						src={image.src}
+						srcset={image.srcset}
+						sizes={image.sizes}
+						alt={image.alt}
+						width={image.width}
+						height={image.height}
+						loading="lazy"
+						decoding="async"
+					/>
+				)}
+				{image.caption && <figcaption>{image.caption}</figcaption>}
+			</figure>
+		))
 	}
 </div>
 

package/src/components/InlinePortableTextEditor.tsx

@@ -1864,44 +1864,65 @@ export function InlinePortableTextEditor({
 		return pmToPortableText(json);
 	}, []);
 
-	const save = React.useCallback(async () => {
-		if (savingRef.current) return;
-
-		const current = JSON.stringify(getBlocks());
-		const initial = JSON.stringify(initialRef.current);
-		if (current === initial) return;
-
-		savingRef.current = true;
-		try {
-			const res = await fetch(
-				`/_emdash/api/content/${encodeURIComponent(collection)}/${encodeURIComponent(entryId)}`,
-				{
-					method: "PUT",
-					credentials: "same-origin",
-					headers: { "Content-Type": "application/json", "X-EmDash-Request": "1" },
-					body: JSON.stringify({ data: { [field]: getBlocks() } }),
-				},
-			);
-
-			if (res.ok) {
-				initialRef.current = getBlocks();
-				document.dispatchEvent(new CustomEvent("emdash:save", { detail: { state: "saved" } }));
-				document.dispatchEvent(
-					new CustomEvent("emdash:content-changed", {
-						detail: { collection, id: entryId },
-					}),
+	const save = React.useCallback(
+		async (options?: { keepalive?: boolean }) => {
+			// A pagehide flush must not be skipped: an in-flight blur save is
+			// cancelled by the navigation, so the keepalive request is the only
+			// one that can still land (#1582).
+			if (savingRef.current && !options?.keepalive) return;
+
+			const current = JSON.stringify(getBlocks());
+			const initial = JSON.stringify(initialRef.current);
+			if (current === initial) return;
+
+			savingRef.current = true;
+			try {
+				const res = await fetch(
+					`/_emdash/api/content/${encodeURIComponent(collection)}/${encodeURIComponent(entryId)}`,
+					{
+						method: "PUT",
+						credentials: "same-origin",
+						headers: { "Content-Type": "application/json", "X-EmDash-Request": "1" },
+						body: JSON.stringify({ data: { [field]: getBlocks() } }),
+						keepalive: options?.keepalive ?? false,
+					},
 				);
-			} else {
+
+				if (res.ok) {
+					initialRef.current = getBlocks();
+					document.dispatchEvent(new CustomEvent("emdash:save", { detail: { state: "saved" } }));
+					document.dispatchEvent(
+						new CustomEvent("emdash:content-changed", {
+							detail: { collection, id: entryId },
+						}),
+					);
+				} else {
+					document.dispatchEvent(new CustomEvent("emdash:save", { detail: { state: "error" } }));
+					console.error("Save failed:", res.status);
+				}
+			} catch (err) {
 				document.dispatchEvent(new CustomEvent("emdash:save", { detail: { state: "error" } }));
-				console.error("Save failed:", res.status);
+				console.error("Save failed:", err);
+			} finally {
+				savingRef.current = false;
 			}
-		} catch (err) {
-			document.dispatchEvent(new CustomEvent("emdash:save", { detail: { state: "error" } }));
-			console.error("Save failed:", err);
-		} finally {
-			savingRef.current = false;
-		}
-	}, [collection, entryId, field, getBlocks]);
+		},
+		[collection, entryId, field, getBlocks],
+	);
+
+	// Flush unsaved edits when the page goes away (browser back/forward,
+	// link click, tab close). The blur handler doesn't cover this: unload
+	// doesn't reliably fire React blur, and a plain fetch started during
+	// unload is cancelled by the navigation — edits were silently lost
+	// (#1582). `keepalive` lets the PUT outlive the page.
+	// Caveat: keepalive caps the body at 64KB — a very long document
+	// can still be lost on unload. Upgrade path: debounced autosave
+	// while typing (like the admin editor) so unload flushes are rare.
+	React.useEffect(() => {
+		const flush = () => void save({ keepalive: true });
+		window.addEventListener("pagehide", flush);
+		return () => window.removeEventListener("pagehide", flush);
+	}, [save]);
 
 	// Create slash commands extension once — uses refs to avoid re-render loop
 	const slashCommandsExtension = React.useMemo(

package/src/components/marks/Link.astro

@@ -19,7 +19,11 @@ export interface Props {
 
 const { node } = Astro.props;
 const href = sanitizeHref(node?.markDef?.href);
-const blank = node?.markDef?.blank;
+// Same-page anchor links (`#section`) are on-page jumps — opening them in a
+// new tab is never desirable, so force same-tab regardless of the mark's
+// `blank` flag.
+const isSamePageAnchor = href.startsWith("#");
+const blank = !isSamePageAnchor && node?.markDef?.blank;
 ---
 
 <a