emdash 0.29.0 → 0.30.0

package/src/loader.ts

@@ -646,6 +646,263 @@ function buildFieldConditions(
 	return conditions;
 }
 
+/**
+ * Resolve a taxonomy filter (`name` + one or more `slug`s, optionally scoped to
+ * `locale`) to the set of `translation_group`s the pivot stores in
+ * `content_taxonomies.taxonomy_id`. Exact terms only — no subtree expansion.
+ *
+ * Mirrors the meaning of the old EXISTS join (`t.name = ? AND t.slug IN (?)
+ * [AND t.locale = ?]`): a pivot row matches when its group has a term with that
+ * name/slug in the active locale. Resolving to explicit values (rather than an
+ * `IN (subquery)`) keeps the single-term case a plain equality on the pivot
+ * index, which is what gives the clean early-`LIMIT` seek.
+ */
+async function resolveTermGroups(
+	db: Kysely<Database>,
+	name: string,
+	slugs: string[],
+	locale: string | undefined,
+): Promise<string[]> {
+	let query = db
+		.selectFrom("taxonomies")
+		.select("translation_group")
+		.distinct()
+		.where("name", "=", name)
+		.where("slug", "in", slugs);
+	if (locale) query = query.where("locale", "=", locale);
+	const rows = await query.execute();
+	const groups = new Set<string>();
+	for (const row of rows) {
+		if (row.translation_group) groups.add(row.translation_group);
+	}
+	return [...groups];
+}
+
+/** Equality (single) or `IN` (multiple) condition on a pivot group column. */
+function pivotGroupCondition(ref: string, groups: string[]): ReturnType<typeof sql> {
+	if (groups.length === 1) return sql`${sql.ref(ref)} = ${groups[0]}`;
+	return sql`${sql.ref(ref)} IN (${sql.join(groups.map((g) => sql`${g}`))})`;
+}
+
+/** LIMIT/OFFSET fragment matching the loader's single-table variant. */
+function buildPivotLimitOffset(
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any -- any Kysely instance
+	db: Kysely<any>,
+	fetchLimit: number | undefined,
+	offset: number | undefined,
+): ReturnType<typeof sql> {
+	if (fetchLimit != null && offset != null) return sql`LIMIT ${fetchLimit} OFFSET ${offset}`;
+	if (fetchLimit != null) return sql`LIMIT ${fetchLimit}`;
+	if (offset != null) {
+		return isPostgres(db) ? sql`OFFSET ${offset}` : sql`LIMIT -1 OFFSET ${offset}`;
+	}
+	return sql``;
+}
+
+/**
+ * Options for {@link buildTaxonomyPivotQuery}.
+ *
+ * Parameterized on the `deletedIsNull` predicate and `status` condition so the
+ * same builder serves the public live path (`deleted_at IS NULL` + published/
+ * scheduled) and, without any schema change, an admin trash (`deleted_at IS NOT
+ * NULL`) or all-statuses shape. Admin wiring is out of scope today; the
+ * parameters exist so `ContentRepository` can adopt this if it gains taxonomy
+ * filtering.
+ */
+export interface TaxonomyPivotQueryOptions {
+	// eslint-disable-next-line @typescript-eslint/no-explicit-any -- any Kysely instance
+	db: Kysely<any>;
+	/** Collection slug (pivot `collection` value). */
+	collection: string;
+	/** Content table name (`ec_<collection>`). */
+	tableName: string;
+	/**
+	 * Resolved translation_group sets, one per taxonomy filter. The first drives
+	 * the pivot seek; each additional set becomes a residual `EXISTS` (AND across
+	 * taxonomies). Multiple groups within a set are OR'd (dedup via GROUP BY).
+	 */
+	groupSets: string[][];
+	orderBy: OrderBySpec | undefined;
+	cursor: string | undefined;
+	locale: string | undefined;
+	/**
+	 * Status shape. A concrete value (`published`/`draft`/…) applies the same
+	 * condition `buildStatusCondition` produces (public: published-or-scheduled).
+	 * `undefined` drops the status filter entirely — the admin all-statuses shape.
+	 */
+	status: string | undefined;
+	/** `true` → `deleted_at IS NULL` (live); `false` → `IS NOT NULL` (trash). */
+	deletedIsNull: boolean;
+	/** Byline translation_groups for an AND'd byline filter, or `null`. */
+	bylineGroups: string[] | null;
+	fetchLimit: number | undefined;
+	offset: number | undefined;
+}
+
+/**
+ * Build the pivot-driven taxonomy listing query (#1834).
+ *
+ * Drives from a pivot-only CTE (`picked`) that carries the sort column, seeks
+ * the term on a `(taxonomy_id, collection, deleted_at, [locale,] <sort> DESC,
+ * entry_id DESC)` index, and lets `LIMIT` short-circuit; then joins `ec_*` by primary
+ * key to hydrate the page **and re-checks the real filter predicates on the
+ * joined row** — the pivot columns are advisory (non-atomic re-stamp on D1), so
+ * `ec_*` is authoritative for membership. Ordering stays pivot-driven to keep
+ * the early-`LIMIT`.
+ *
+ * Two shapes:
+ * - **Indexed sort** (`published_at`/`created_at`, single sort field): the
+ *   pivot index is covering for `(entry_id, sortval)`, so `LIMIT` lives in
+ *   `picked` and short-circuits.
+ * - **Temp-sort** (`updated_at` or any other field, or multi-field sort): no
+ *   pivot sort index applies, so `picked` collects the tagged candidate set and
+ *   the outer query sorts the joined rows. Bounded to tagged rows — no
+ *   `ec_*` full scan — but no early-`LIMIT`.
+ */
+export function buildTaxonomyPivotQuery(
+	opts: TaxonomyPivotQueryOptions,
+): ReturnType<typeof sql<Record<string, unknown>>> {
+	const {
+		db,
+		collection,
+		tableName,
+		groupSets,
+		orderBy,
+		cursor,
+		locale,
+		status,
+		deletedIsNull,
+		bylineGroups,
+		fetchLimit,
+		offset,
+	} = opts;
+
+	const primary = getPrimarySort(orderBy);
+	const validSortKeys = orderBy
+		? Object.keys(orderBy).filter((k) => FIELD_NAME_PATTERN.test(k))
+		: [];
+	const singleSort = validSortKeys.length <= 1;
+	const isIndexedSort =
+		singleSort && (primary.field === "published_at" || primary.field === "created_at");
+	const dir = primary.direction === "asc" ? sql`ASC` : sql`DESC`;
+	const cmp = primary.direction === "asc" ? sql.raw(">") : sql.raw("<");
+
+	const firstGroups = groupSets[0] ?? [];
+	const restGroups = groupSets.slice(1);
+	const multiGroup = firstGroups.length > 1;
+
+	// Pivot-local narrowing predicates (advisory — re-checked on `ec_*` below).
+	// `status === undefined` means an all-statuses shape (admin), so the status
+	// condition is dropped entirely.
+	const deletedCt = deletedIsNull ? sql`ct.deleted_at IS NULL` : sql`ct.deleted_at IS NOT NULL`;
+	const statusCt =
+		status !== undefined ? sql`AND ${buildStatusCondition(db, status, "ct")}` : sql``;
+	const localeCt = locale ? sql`AND ct.locale = ${locale}` : sql``;
+
+	// Multi-term AND: one residual pivot-PK EXISTS per additional taxonomy.
+	const residual =
+		restGroups.length > 0
+			? sql`${sql.join(
+					restGroups.map(
+						(g) => sql`AND EXISTS (
+						SELECT 1 FROM content_taxonomies ct2
+						WHERE ct2.collection = ${collection}
+							AND ct2.entry_id = ct.entry_id
+							AND ${pivotGroupCondition("ct2.taxonomy_id", g)}
+					)`,
+					),
+					sql` `,
+				)}`
+			: sql``;
+
+	// Byline filter keeps its EXISTS, correlated on `ct.entry_id`.
+	const bylineCt = bylineGroups
+		? sql`AND EXISTS (
+				SELECT 1 FROM _emdash_content_bylines cb
+				WHERE cb.collection_slug = ${collection}
+					AND cb.content_id = ct.entry_id
+					AND cb.byline_id IN (${sql.join(bylineGroups.map((g) => sql`${g}`))})
+			)`
+		: sql``;
+
+	const firstGroupCond = pivotGroupCondition("ct.taxonomy_id", firstGroups);
+	const { terms: termsSelect, bylines: bylinesSelect } = foldedHydrationSelects(
+		db,
+		collection,
+		"r",
+	);
+
+	// Authoritative re-check on the joined `ec_*` row.
+	const deletedR = deletedIsNull ? sql`r.deleted_at IS NULL` : sql`r.deleted_at IS NOT NULL`;
+	const statusR = status !== undefined ? sql`AND ${buildStatusCondition(db, status, "r")}` : sql``;
+	const localeR = locale ? sql`AND r.locale = ${locale}` : sql``;
+
+	if (isIndexedSort) {
+		const sortRef = sql.ref(`ct.${primary.field}`);
+		const sortval = multiGroup ? sql`MAX(${sortRef})` : sortRef;
+		const groupByClause = multiGroup ? sql`GROUP BY ct.entry_id` : sql``;
+
+		let cursorClause = sql``;
+		let havingClause = sql``;
+		if (cursor) {
+			const { orderValue, id } = decodeCursor(cursor);
+			const cond = sql`(${sortval} ${cmp} ${orderValue} OR (${sortval} = ${orderValue} AND ct.entry_id ${cmp} ${id}))`;
+			// A GROUP BY makes `sortval` an aggregate → cursor goes in HAVING.
+			if (multiGroup) havingClause = sql`HAVING ${cond}`;
+			else cursorClause = sql`AND ${cond}`;
+		}
+
+		const limitClause = buildPivotLimitOffset(db, fetchLimit, offset);
+
+		return sql<Record<string, unknown>>`
+			WITH picked AS (
+				SELECT ct.entry_id AS entry_id, ${sortval} AS sortval
+				FROM content_taxonomies ct
+				WHERE ct.collection = ${collection}
+					AND ${firstGroupCond}
+					AND ${deletedCt}
+					${statusCt}
+					${localeCt}
+					${residual}
+					${bylineCt}
+					${cursorClause}
+				${groupByClause}
+				${havingClause}
+				ORDER BY sortval ${dir}, ct.entry_id ${dir}
+				${limitClause}
+			)
+			SELECT r.*, ${termsSelect}, ${bylinesSelect}
+			FROM picked JOIN ${sql.ref(tableName)} AS r ON r.id = picked.entry_id
+			WHERE ${deletedR} ${statusR} ${localeR}
+			ORDER BY picked.sortval ${dir}, picked.entry_id ${dir}
+		`;
+	}
+
+	// Temp-sort path: seek the term via the pivot, sort the joined candidate set.
+	const orderByClause = buildOrderByClause(orderBy, "r");
+	const cursorCond = cursor ? sql`AND ${buildCursorCondition(cursor, orderBy, "r")}` : sql``;
+	const limitClause = buildPivotLimitOffset(db, fetchLimit, offset);
+	return sql<Record<string, unknown>>`
+		WITH picked AS (
+			SELECT DISTINCT ct.entry_id AS entry_id
+			FROM content_taxonomies ct
+			WHERE ct.collection = ${collection}
+				AND ${firstGroupCond}
+				AND ${deletedCt}
+				${statusCt}
+				${localeCt}
+				${residual}
+				${bylineCt}
+		)
+		SELECT r.*, ${termsSelect}, ${bylinesSelect}
+		FROM picked JOIN ${sql.ref(tableName)} AS r ON r.id = picked.entry_id
+		WHERE ${deletedR} ${statusR} ${localeR}
+			${cursorCond}
+		${orderByClause}
+		${limitClause}
+	`;
+}
+
 /**
  * Range filter for comparison operators on field values.
  * Values are compared as strings in the database. This works correctly for
@@ -912,7 +1169,41 @@ export function emdashLoader(): LiveLoader<EntryData, EntryFilter, CollectionFil
 					return { entries: [], cacheHint: { tags: [type] } };
 				}
 
-				{
+				if (taxonomyFilters.length > 0 && Object.keys(fieldFilters).length === 0) {
+					// Pivot-drive fast path (#1834): seek the matching entries on the
+					// denormalized `content_taxonomies` pivot instead of scanning the
+					// whole collection and probing a taxonomy EXISTS per row. Only the
+					// taxonomy path is restructured — a taxonomy filter combined with a
+					// content-field filter falls through to the single-table shape
+					// below (field predicates live on `ec_*`, not the pivot). A byline
+					// filter rides along inside the pivot CTE (see the builder).
+					const groupSets: string[][] = [];
+					for (const taxFilter of taxonomyFilters) {
+						const groups = await resolveTermGroups(db, taxFilter.name, taxFilter.slugs, locale);
+						// A slug that resolves to no term matches nothing; since taxonomy
+						// filters AND together, one empty set empties the whole result.
+						if (groups.length === 0) {
+							return { entries: [], cacheHint: { tags: [type] } };
+						}
+						groupSets.push(groups);
+					}
+
+					result = await buildTaxonomyPivotQuery({
+						db,
+						collection: type,
+						tableName,
+						groupSets,
+						orderBy,
+						cursor,
+						locale,
+						status,
+						// Public listings only ever want live content.
+						deletedIsNull: true,
+						bylineGroups: bylineFilter ? bylineFilter.groups : null,
+						fetchLimit,
+						offset,
+					}).execute(db);
+				} else {
 					// Taxonomy and byline filters are applied as correlated
 					// `EXISTS` semi-joins rather than `INNER JOIN ... DISTINCT`.
 					// A join fan-out would force `SELECT DISTINCT table.*`, and

package/src/mcp/server.ts

@@ -10,17 +10,19 @@
  */
 
 import type { Permission, RoleLevel } from "@emdash-cms/auth";
-import { canActOnOwn, hasPermission, Role } from "@emdash-cms/auth";
+import { canActOnOwn, hasPermission, Permissions, Role } from "@emdash-cms/auth";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 
 import {
 	bylineCreateBody,
 	bylineUpdateBody,
+	CONTENT_TYPE_RE,
 	contentBylineInputSchema,
 	contentSeoInput,
 } from "#api/schemas.js";
 
+import type { MediaUsageRepairRequest } from "../api/schemas/media-usage.js";
 import type { EmDashHandlers } from "../astro/types.js";
 import { hasScope } from "../auth/api-tokens.js";
 import { convertDataForRead, convertDataForWrite } from "../client/portable-text.js";
@@ -76,6 +78,35 @@ const settingsSeoSchema = z.object({
 		.describe("Bing Webmaster Tools verification token"),
 });
 
+const mediaUsageRepairToolSchema = z
+	.object({
+		scope: z.enum(["collection", "all"]).describe("Repair one collection or all collections"),
+		collection: z
+			.string()
+			.min(1)
+			.max(63)
+			.regex(COLLECTION_SLUG_PATTERN, "Invalid collection slug")
+			.optional()
+			.describe("Collection slug; required only when scope is collection"),
+	})
+	.strict()
+	.superRefine((input, ctx) => {
+		if (input.scope === "collection" && input.collection === undefined) {
+			ctx.addIssue({
+				code: "custom",
+				path: ["collection"],
+				message: "Collection is required when scope is collection",
+			});
+		}
+		if (input.scope === "all" && input.collection !== undefined) {
+			ctx.addIssue({
+				code: "custom",
+				path: ["collection"],
+				message: "Collection must be omitted when scope is all",
+			});
+		}
+	});
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -88,6 +119,7 @@ type HandlerResult = {
 
 type SuccessEnvelope = {
 	content: Array<{ type: "text"; text: string }>;
+	structuredContent?: Record<string, unknown>;
 	_meta?: Record<string, unknown>;
 };
 
@@ -450,7 +482,21 @@ function extractContentId(data: unknown): string | undefined {
 // Server factory
 // ---------------------------------------------------------------------------
 
-export function createMcpServer(): McpServer {
+export interface PluginMcpRegistration {
+	pluginId: string;
+	name: string;
+	description: string;
+	route: string;
+	permission: string;
+	destructive: boolean;
+	inputSchema: z.ZodType;
+	outputSchema?: z.ZodType;
+}
+
+export function createMcpServer(
+	pluginTools: PluginMcpRegistration[] = [],
+	request?: Request,
+): McpServer {
 	const server = new McpServer(
 		{ name: "emdash", version: "0.1.0" },
 		{ capabilities: { logging: {} } },
@@ -484,6 +530,78 @@ export function createMcpServer(): McpServer {
 		)(name, config, wrapped);
 	}) as typeof server.registerTool;
 
+	for (const tool of pluginTools) {
+		if (!(tool.permission in Permissions)) continue;
+		server.registerTool(
+			`${tool.pluginId}__${tool.name}`,
+			{
+				description: tool.description,
+				inputSchema: tool.inputSchema,
+				outputSchema: tool.outputSchema,
+				annotations: { destructiveHint: tool.destructive },
+			},
+			async (input, extra) => {
+				const payload = getExtra(extra);
+				const requiredScope = `mcp:tools:${tool.pluginId}`;
+				if (payload.tokenScopes && !hasScope(payload.tokenScopes, requiredScope)) {
+					if (request) {
+						await payload.emdash.handlePluginMcpDenied(
+							tool.pluginId,
+							tool.name,
+							tool.route,
+							payload.userId,
+							request,
+							`Missing scope: ${requiredScope}`,
+						);
+					}
+					throw new EmDashAuthError(
+						`Insufficient scope: requires ${requiredScope}`,
+						"INSUFFICIENT_SCOPE",
+					);
+				}
+				if (!hasPermission({ role: payload.userRole }, tool.permission as Permission)) {
+					if (request) {
+						await payload.emdash.handlePluginMcpDenied(
+							tool.pluginId,
+							tool.name,
+							tool.route,
+							payload.userId,
+							request,
+							`Missing permission: ${tool.permission}`,
+						);
+					}
+					throw new EmDashAuthError(
+						`Insufficient permission: requires ${tool.permission}`,
+						"INSUFFICIENT_PERMISSIONS",
+					);
+				}
+				if (!request) return respondError("INTERNAL_ERROR", "Missing MCP request context");
+				const result = await payload.emdash.handlePluginMcpTool(
+					tool.pluginId,
+					tool.name,
+					tool.route,
+					input,
+					payload.userId,
+					request,
+				);
+				if (!result.success) return unwrap(result);
+				if (tool.outputSchema) {
+					if (!result.data || typeof result.data !== "object" || Array.isArray(result.data)) {
+						return respondError(
+							"INVALID_PLUGIN_OUTPUT",
+							"Plugin tool output must be an object when outputSchema is declared",
+						);
+					}
+					return {
+						content: [{ type: "text", text: JSON.stringify(result.data, null, 2) }],
+						structuredContent: result.data as Record<string, unknown>,
+					};
+				}
+				return respondData(result.data);
+			},
+		);
+	}
+
 	// =====================================================================
 	// Content tools
 	// =====================================================================
@@ -1794,9 +1912,8 @@ export function createMcpServer(): McpServer {
 				"caller is responsible for placing the file at `storageKey` (typically " +
 				"using a signed upload URL obtained from the admin UI or a separate API). " +
 				"This tool persists the metadata record so the file is discoverable via " +
-				"media_list / media_get and can be referenced by content. For binary " +
-				"uploads the MCP transport is not appropriate — use the signed-upload " +
-				"flow instead.",
+				"media_list / media_get and can be referenced by content. To upload the " +
+				"file itself, use media_upload (base64 data or a public URL) instead.",
 			inputSchema: z.object({
 				filename: z.string().describe("Original filename (e.g. 'logo.png')"),
 				mimeType: z.string().describe("MIME type (e.g. 'image/png')"),
@@ -1833,6 +1950,70 @@ export function createMcpServer(): McpServer {
 		},
 	);
 
+	server.registerTool(
+		"media_upload",
+		{
+			title: "Upload Media",
+			description:
+				"Upload a media file from base64-encoded data or an external URL and " +
+				"register it in the media library. Returns the media item with id, " +
+				"storageKey, and url — ready to reference from content fields (e.g. " +
+				"featured_image) via content_create / content_update. Uploads are " +
+				"deduplicated by content hash: re-uploading identical bytes returns " +
+				"the existing item with deduplicated: true. URL fetches must resolve " +
+				"to a public http(s) host (SSRF-guarded). Subject to the global " +
+				"upload MIME allowlist and the configured maximum upload size.",
+			inputSchema: z.object({
+				filename: z.string().min(1).describe("Filename including extension (e.g. 'cover.png')"),
+				base64: z
+					.string()
+					.optional()
+					.describe("Base64-encoded file contents. Provide exactly one of base64 / url."),
+				url: z
+					.string()
+					.url()
+					.optional()
+					.describe(
+						"Public http(s) URL to fetch the file from. Provide exactly one of base64 / url.",
+					),
+				contentType: z
+					.string()
+					.regex(CONTENT_TYPE_RE, "Invalid content type")
+					.optional()
+					.describe(
+						"MIME type (e.g. 'image/png'). Required with base64; with url it " +
+							"defaults to the response's Content-Type header.",
+					),
+				alt: z.string().optional().describe("Alt text for accessibility"),
+			}),
+			annotations: { destructiveHint: false },
+		},
+		async (args, extra) => {
+			requireScope(extra, "media:write");
+			requireRole(extra, Role.CONTRIBUTOR);
+			const { emdash, userId } = getExtra(extra);
+			if (!emdash.storage) {
+				return respondError("NO_STORAGE", "Storage not configured");
+			}
+			try {
+				const { handleMediaUpload } = await import("../api/handlers/media-upload.js");
+				return unwrap(
+					await handleMediaUpload(emdash.db, emdash.storage, {
+						filename: args.filename,
+						base64: args.base64,
+						url: args.url,
+						contentType: args.contentType,
+						alt: args.alt,
+						authorId: userId,
+						maxUploadSize: emdash.config.maxUploadSize,
+					}),
+				);
+			} catch (error) {
+				return respondHandlerError(error, "UPLOAD_ERROR");
+			}
+		},
+	);
+
 	server.registerTool(
 		"media_get",
 		{
@@ -1927,6 +2108,42 @@ export function createMcpServer(): McpServer {
 		},
 	);
 
+	server.registerTool(
+		"media_usage_repair",
+		{
+			title: "Repair Media Usage Index",
+			description:
+				"Repair content media usage indexes for one collection or every collection. " +
+				"Returns complete, partial, failed, or stale status; inspect the structured result.",
+			inputSchema: mediaUsageRepairToolSchema,
+		},
+		async (args, extra) => {
+			requireScope(extra, "admin");
+			requireRole(extra, Role.ADMIN);
+			const ec = getEmDash(extra);
+
+			let input: MediaUsageRepairRequest;
+			if (args.scope === "collection") {
+				if (args.collection === undefined) {
+					return respondError(
+						"VALIDATION_ERROR",
+						"Collection is required when scope is collection",
+					);
+				}
+				input = { scope: "collection", collection: args.collection };
+			} else {
+				input = { scope: "all" };
+			}
+
+			try {
+				const { handleMediaUsageRepair } = await import("../api/handlers/media-usage.js");
+				return unwrap(await handleMediaUsageRepair(ec.db, input));
+			} catch (error) {
+				return respondHandlerError(error, "MEDIA_USAGE_REPAIR_ERROR");
+			}
+		},
+	);
+
 	// =====================================================================
 	// Search tool
 	// =====================================================================

package/src/media/image-endpoint.ts

@@ -20,6 +20,17 @@ export const ALLOWED_TRANSFORM_FORMATS = ["webp", "avif", "jpeg", "png"] as cons
 /** Default output format -- broad support, strong compression. */
 export const DEFAULT_TRANSFORM_FORMAT: ImageTransformFormat = "webp";
 
+/**
+ * Default output quality for lossy formats (WebP/AVIF/JPEG) when the request
+ * doesn't specify one. Matches the default Cloudflare applies to URL-based
+ * image transformations. The Images *binding* applies no default of its own
+ * and encodes near-losslessly when quality is omitted (a 2048px WebP comes
+ * out ~900 KB instead of ~100 KB), so the endpoint sends an explicit quality
+ * for lossy output. PNG is exempt: an explicit PNG quality switches the
+ * binding to lossy PNG8, which is not a safe default for a lossless format.
+ */
+export const DEFAULT_TRANSFORM_QUALITY = 85;
+
 /** Upper bound for a requested dimension; caps the work a single request asks for. */
 export const MAX_TRANSFORM_DIMENSION = 4000;
 
@@ -31,6 +42,11 @@ export interface ImageTransformOptions {
 	width?: number;
 	height?: number;
 	format: ImageTransformFormat;
+	/**
+	 * Explicitly-requested quality (1-100), or `undefined` when the request
+	 * carried no `q`. Callers apply their own default per format (see
+	 * {@link DEFAULT_TRANSFORM_QUALITY}); lossless PNG deliberately gets none.
+	 */
 	quality?: number;
 }
 
@@ -117,10 +133,30 @@ export type ParsedTransformParams =
 	| { ok: true; options: ImageTransformOptions }
 	| { ok: false; message: string };
 
+/**
+ * Resolve the quality to send to the image binding for a transform. An
+ * explicitly-requested quality always wins. Otherwise lossy formats
+ * (WebP/AVIF/JPEG) get {@link DEFAULT_TRANSFORM_QUALITY} because the Images
+ * binding encodes near-losslessly when quality is omitted; lossless PNG gets
+ * `undefined` because an explicit PNG quality switches the binding to lossy
+ * PNG8, which is not a safe default for a lossless format.
+ */
+export function resolveTransformQuality(
+	format: ImageTransformFormat,
+	requested: number | undefined,
+): number | undefined {
+	if (requested !== undefined) return requested;
+	return format === "png" ? undefined : DEFAULT_TRANSFORM_QUALITY;
+}
+
 /**
  * Parse and validate `?w=&h=&f=&q=` query params. Width is required (it sizes
  * the rendition); dimensions are bounded so a request can't ask for an
- * unbounded or nonsensical transform.
+ * unbounded or nonsensical transform. Format falls back to
+ * {@link DEFAULT_TRANSFORM_FORMAT} when not requested. `q` is validated when
+ * present but otherwise left `undefined` so the caller can apply a per-format
+ * default (lossy formats get one, lossless PNG does not — see
+ * {@link DEFAULT_TRANSFORM_QUALITY}).
  */
 export function parseTransformParams(params: URLSearchParams): ParsedTransformParams {
 	const width = parseDimension(params.get("w"));
@@ -139,8 +175,8 @@ export function parseTransformParams(params: URLSearchParams): ParsedTransformPa
 		format = formatRaw;
 	}
 
-	const qualityRaw = params.get("q");
 	let quality: number | undefined;
+	const qualityRaw = params.get("q");
 	if (qualityRaw !== null) {
 		const q = Number(qualityRaw);
 		if (!Number.isInteger(q) || q < 1 || q > 100) {

package/src/page/metadata.ts

@@ -80,6 +80,33 @@ export async function createSha256CspHash(value: string): Promise<string> {
 	return `sha256-${btoa(binary)}`;
 }
 
+interface CspScriptHashSink {
+	insertScriptHash(hash: string): void;
+}
+
+/**
+ * Register JSON-LD hashes with Astro's CSP runtime when CSP is enabled.
+ *
+ * The getter stays lazy because Astro warns when `Astro.csp` is accessed on a
+ * project that has not enabled its built-in CSP support.
+ */
+export async function registerJsonLdCspHashes(
+	enabled: boolean,
+	getCsp: () => CspScriptHashSink | undefined,
+	scripts: ReadonlyArray<{ json: string }>,
+): Promise<void> {
+	if (!enabled || scripts.length === 0) return;
+
+	const csp = getCsp();
+	if (!csp) return;
+
+	await Promise.all(
+		scripts.map(async ({ json }) => {
+			csp.insertScriptHash(await createSha256CspHash(json));
+		}),
+	);
+}
+
 // ── Merge / dedupe ──────────────────────────────────────────────
 
 /**