emdash 0.8.0 → 0.9.0

package/src/mcp/server.ts

@@ -14,6 +14,8 @@ import { canActOnOwn, hasPermission, Role } from "@emdash-cms/auth";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { z } from "zod";
 
+import { contentBylineInputSchema, contentSeoInput } from "#api/schemas.js";
+
 import type { EmDashHandlers } from "../astro/types.js";
 import { hasScope } from "../auth/api-tokens.js";
 
@@ -623,7 +625,10 @@ export function createMcpServer(): McpServer {
 				"Update an existing content item. Only include fields you want to change " +
 				"in the 'data' object — unspecified fields are left unchanged. Pass the " +
 				"_rev token from content_get to enable optimistic concurrency checking " +
-				"(the update fails if the item was modified since you read it).",
+				"(the update fails if the item was modified since you read it). " +
+				"`seo` and `bylines` are persisted alongside the field updates in a " +
+				"single transaction. `publishedAt` requires the content:publish_any " +
+				"permission and is useful for migrations or correcting historical dates.",
 			inputSchema: z.object({
 				collection: z.string().describe("Collection slug"),
 				id: z.string().describe("Content item ID or slug"),
@@ -638,6 +643,28 @@ export function createMcpServer(): McpServer {
 					.describe(
 						"New status. Setting to 'published' requires publish permission. Setting to 'draft' unpublishes the item and also requires publish permission.",
 					),
+				// Reuse the REST schema rather than redefining inline. The REST schema's
+				// `canonical` field is gated through `httpUrl` (validates the URL parses
+				// AND has an http(s) scheme) which rejects javascript:/data: URIs that
+				// would otherwise become stored XSS in the rendered <link rel="canonical">.
+				// Inlining a looser shape here would let MCP callers bypass that.
+				seo: contentSeoInput
+					.optional()
+					.describe(
+						"Per-content SEO metadata. Only valid for collections with SEO enabled (see schema_get_collection.hasSeo). Fields not included are left unchanged; pass null to clear.",
+					),
+				bylines: z
+					.array(contentBylineInputSchema)
+					.optional()
+					.describe(
+						"Replace the byline list for this item. The first entry becomes the primary byline. Pass an empty array to clear all bylines.",
+					),
+				publishedAt: z.iso
+					.datetime({ offset: true, message: "must be an ISO 8601 datetime" })
+					.nullish()
+					.describe(
+						"Override the publication timestamp (ISO 8601). Requires content:publish_any permission. Pass null to clear. Useful for content migrations.",
+					),
 				_rev: z
 					.string()
 					.optional()
@@ -647,35 +674,48 @@ export function createMcpServer(): McpServer {
 		async (args, extra) => {
 			requireScope(extra, "content:write");
 			requireRole(extra, Role.AUTHOR);
-			const { emdash, userId } = getExtra(extra);
+			const { emdash, userId, userRole } = getExtra(extra);
 
 			// Fetch item to check ownership
 			const existing = await emdash.handleContentGet(args.collection, args.id);
 			if (!existing.success) {
 				return unwrap(existing);
 			}
-			requireOwnership(
-				extra,
-				extractContentAuthorId(existing.data),
-				"content:edit_own",
-				"content:edit_any",
-			);
+			const ownerId = extractContentAuthorId(existing.data);
+			requireOwnership(extra, ownerId, "content:edit_own", "content:edit_any");
+
+			// Writing publishedAt directly (incl. clearing to null) overwrites
+			// historical record — gate behind publish_any, mirroring the REST PUT
+			// route. Status-driven publishes are gated separately below.
+			if (args.publishedAt !== undefined) {
+				const user = { id: userId, role: userRole };
+				if (!hasPermission(user, "content:publish_any" as Permission)) {
+					throw new EmDashAuthError(
+						"Setting publishedAt requires content:publish_any permission",
+						"INSUFFICIENT_PERMISSIONS",
+					);
+				}
+			}
 
 			const resolvedId = extractContentId(existing.data) ?? args.id;
 
 			// Status transitions route through dedicated handlers for proper revision management
 			if (args.status === "published") {
-				requireOwnership(
-					extra,
-					extractContentAuthorId(existing.data),
-					"content:publish_own",
-					"content:publish_any",
-				);
-				if (args.data || args.slug) {
+				requireOwnership(extra, ownerId, "content:publish_own", "content:publish_any");
+				if (
+					args.data ||
+					args.slug ||
+					args.seo !== undefined ||
+					args.bylines !== undefined ||
+					args.publishedAt !== undefined
+				) {
 					const updateResult = await emdash.handleContentUpdate(args.collection, resolvedId, {
 						data: args.data,
 						slug: args.slug,
 						authorId: userId,
+						seo: args.seo,
+						bylines: args.bylines,
+						publishedAt: args.publishedAt,
 						_rev: args._rev,
 					});
 					if (!updateResult.success) return unwrap(updateResult);
@@ -684,17 +724,21 @@ export function createMcpServer(): McpServer {
 			}
 
 			if (args.status === "draft") {
-				requireOwnership(
-					extra,
-					extractContentAuthorId(existing.data),
-					"content:publish_own",
-					"content:publish_any",
-				);
-				if (args.data || args.slug) {
+				requireOwnership(extra, ownerId, "content:publish_own", "content:publish_any");
+				if (
+					args.data ||
+					args.slug ||
+					args.seo !== undefined ||
+					args.bylines !== undefined ||
+					args.publishedAt !== undefined
+				) {
 					const updateResult = await emdash.handleContentUpdate(args.collection, resolvedId, {
 						data: args.data,
 						slug: args.slug,
 						authorId: userId,
+						seo: args.seo,
+						bylines: args.bylines,
+						publishedAt: args.publishedAt,
 						_rev: args._rev,
 					});
 					if (!updateResult.success) return unwrap(updateResult);
@@ -707,6 +751,9 @@ export function createMcpServer(): McpServer {
 					data: args.data,
 					slug: args.slug,
 					authorId: userId,
+					seo: args.seo,
+					bylines: args.bylines,
+					publishedAt: args.publishedAt,
 					_rev: args._rev,
 				}),
 			);
@@ -809,31 +856,53 @@ export function createMcpServer(): McpServer {
 			description:
 				"Publish a content item, making it live on the site. Creates a published " +
 				"revision from the current draft. Further edits create a new draft without " +
-				"affecting the live version until re-published.",
+				"affecting the live version until re-published. Pass `publishedAt` to " +
+				"backdate (e.g. when migrating content from another CMS) — this requires " +
+				"the content:publish_any permission. Without `publishedAt`, the existing " +
+				"`published_at` is preserved on re-publish (idempotent) and falls back to " +
+				"the current time on first publish.",
 			inputSchema: z.object({
 				collection: z.string().describe("Collection slug"),
 				id: z.string().describe("Content item ID or slug"),
+				publishedAt: z.iso
+					.datetime({ offset: true, message: "must be an ISO 8601 datetime" })
+					.optional()
+					.describe(
+						"Override publication timestamp (ISO 8601). Requires content:publish_any permission. Useful when importing content with original publish dates.",
+					),
 			}),
 		},
 		async (args, extra) => {
 			requireScope(extra, "content:write");
 			requireRole(extra, Role.AUTHOR);
-			const ec = getEmDash(extra);
+			const { emdash, userId, userRole } = getExtra(extra);
 
 			// Fetch item to check ownership
-			const existing = await ec.handleContentGet(args.collection, args.id);
+			const existing = await emdash.handleContentGet(args.collection, args.id);
 			if (!existing.success) {
 				return unwrap(existing);
 			}
-			requireOwnership(
-				extra,
-				extractContentAuthorId(existing.data),
-				"content:publish_own",
-				"content:publish_any",
-			);
+			const ownerId = extractContentAuthorId(existing.data);
+			requireOwnership(extra, ownerId, "content:publish_own", "content:publish_any");
+
+			// Backdating overwrites historical record — gate behind publish_any
+			// regardless of ownership (mirrors the REST PUT route's publishedAt gate).
+			if (args.publishedAt !== undefined) {
+				const user = { id: userId, role: userRole };
+				if (!hasPermission(user, "content:publish_any" as Permission)) {
+					throw new EmDashAuthError(
+						"Setting publishedAt requires content:publish_any permission",
+						"INSUFFICIENT_PERMISSIONS",
+					);
+				}
+			}
 
 			const resolvedId = extractContentId(existing.data) ?? args.id;
-			return unwrap(await ec.handleContentPublish(args.collection, resolvedId));
+			return unwrap(
+				await emdash.handleContentPublish(args.collection, resolvedId, {
+					publishedAt: args.publishedAt,
+				}),
+			);
 		},
 	);
 
@@ -1195,7 +1264,7 @@ export function createMcpServer(): McpServer {
 					// ['drafts', 'revisions'] when undefined; pass through verbatim.
 					supports: args.supports,
 				});
-				ec.invalidateManifest();
+				ec.invalidateUrlPatternCache();
 				return jsonResult(collection);
 			} catch (error) {
 				return respondHandlerError(error, "SCHEMA_CREATE_ERROR");
@@ -1227,7 +1296,7 @@ export function createMcpServer(): McpServer {
 				const { SchemaRegistry } = await import("../schema/index.js");
 				const registry = new SchemaRegistry(ec.db);
 				await registry.deleteCollection(args.slug, { force: args.force });
-				ec.invalidateManifest();
+				ec.invalidateUrlPatternCache();
 				return jsonResult({ deleted: args.slug });
 			} catch (error) {
 				return respondHandlerError(error, "SCHEMA_DELETE_ERROR");
@@ -1331,7 +1400,6 @@ export function createMcpServer(): McpServer {
 					searchable: args.searchable,
 					translatable: args.translatable,
 				});
-				ec.invalidateManifest();
 				return jsonResult(field);
 			} catch (error) {
 				return respondHandlerError(error, "FIELD_CREATE_ERROR");
@@ -1360,7 +1428,6 @@ export function createMcpServer(): McpServer {
 				const { SchemaRegistry } = await import("../schema/index.js");
 				const registry = new SchemaRegistry(ec.db);
 				await registry.deleteField(args.collection, args.fieldSlug);
-				ec.invalidateManifest();
 				return jsonResult({ deleted: args.fieldSlug, collection: args.collection });
 			} catch (error) {
 				return respondHandlerError(error, "FIELD_DELETE_ERROR");

package/src/page/site-identity.ts

@@ -0,0 +1,58 @@
+/**
+ * Site identity head injection.
+ *
+ * Emits first-party `<head>` tags sourced from the user-configured Site
+ * Identity. These are rendered alongside, but separate from, the plugin
+ * contribution pipeline (`page/metadata.ts`) because:
+ *
+ * - Site identity is first-party, not plugin-supplied. The contribution
+ *   pipeline's `isSafeHref` allowlist rejects same-origin paths like
+ *   `/_emdash/api/media/file/...` (which is correct for sandboxed plugin
+ *   contributions, but blocks our own favicon URLs).
+ * - The data shape is fixed and small. Routing it through a generic
+ *   deduper buys nothing.
+ *
+ * Currently emits only `<link rel="icon">`. Other site-identity tags
+ * (`apple-touch-icon`, `theme-color`, `application-name`) need their own
+ * configurable fields in `SiteSettings` before they ship; emitting them
+ * automatically from the favicon would produce broken icons on iOS for
+ * SVG favicons or blurry home-screen icons when the favicon is a small
+ * PNG. Tracked separately.
+ *
+ * Templates that previously emitted their own `<link rel="icon">` are
+ * getting their lines dropped in the same change that introduced this
+ * helper.
+ */
+
+import type { MediaReference } from "../settings/types.js";
+import { escapeHtmlAttr } from "./metadata.js";
+
+/**
+ * Subset of site settings consumed by `renderSiteIdentity`. Kept narrow
+ * so callers don't have to fetch fields they don't use.
+ */
+export interface SiteIdentityInput {
+	favicon?: MediaReference;
+}
+
+/**
+ * Build the `<head>` HTML for site identity tags. Returns an empty string
+ * when no identity fields are configured.
+ */
+export function renderSiteIdentity(input: SiteIdentityInput | undefined): string {
+	if (!input) return "";
+
+	const parts: string[] = [];
+
+	const favicon = input.favicon;
+	if (favicon?.url) {
+		let tag = `<link rel="icon" href="${escapeHtmlAttr(favicon.url)}"`;
+		if (favicon.contentType) {
+			tag += ` type="${escapeHtmlAttr(favicon.contentType)}"`;
+		}
+		tag += ">";
+		parts.push(tag);
+	}
+
+	return parts.join("\n");
+}

package/src/plugins/adapt-sandbox-entry.ts

@@ -12,6 +12,7 @@
 
 import type { PluginDescriptor } from "../astro/integration/runtime.js";
 import { PLUGIN_CAPABILITIES, HOOK_NAMES } from "./manifest-schema.js";
+import { normalizeCapabilities } from "./types.js";
 import type {
 	StandardPluginDefinition,
 	StandardHookEntry,
@@ -147,7 +148,10 @@ export function adaptSandboxEntry(
 	}
 
 	// Build capabilities from descriptor.
-	// Validate against the known set (same as defineNativePlugin).
+	// Validate against the known set (same as defineNativePlugin). Both
+	// current and deprecated names are accepted; deprecated names are
+	// silently normalized to current names below so the runtime only ever
+	// sees the canonical form.
 	const rawCapabilities = descriptor.capabilities ?? [];
 	for (const cap of rawCapabilities) {
 		if (!VALID_CAPABILITIES_SET.has(cap)) {
@@ -157,20 +161,28 @@ export function adaptSandboxEntry(
 			);
 		}
 	}
-	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- validated against VALID_CAPABILITIES_SET above; descriptor uses string[] for flexibility
-	const capabilities = [...rawCapabilities] as PluginCapability[];
+
+	// Silent normalization: rewrite deprecated names to current names.
+	// Safe assertion — `normalizeCapabilities` only emits validated input
+	// plus current names from the rename map, all of which are in the union.
+	// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- validated above; normalizeCapabilities only returns capabilities from the union
+	const capabilities = normalizeCapabilities(rawCapabilities) as PluginCapability[];
 	const allowedHosts = descriptor.allowedHosts ?? [];
 
 	// Capability implications: broader capabilities imply narrower ones
-	// (mirrors the normalization in define-plugin.ts for native format)
-	if (capabilities.includes("write:content") && !capabilities.includes("read:content")) {
-		capabilities.push("read:content");
+	// (mirrors the normalization in define-plugin.ts for native format).
+	// Operates on canonical names only.
+	if (capabilities.includes("content:write") && !capabilities.includes("content:read")) {
+		capabilities.push("content:read");
 	}
-	if (capabilities.includes("write:media") && !capabilities.includes("read:media")) {
-		capabilities.push("read:media");
+	if (capabilities.includes("media:write") && !capabilities.includes("media:read")) {
+		capabilities.push("media:read");
 	}
-	if (capabilities.includes("network:fetch:any") && !capabilities.includes("network:fetch")) {
-		capabilities.push("network:fetch");
+	if (
+		capabilities.includes("network:request:unrestricted") &&
+		!capabilities.includes("network:request")
+	) {
+		capabilities.push("network:request");
 	}
 
 	// Build storage config from descriptor.

package/src/plugins/context.ts

@@ -647,14 +647,14 @@ export function createUnrestrictedHttpAccess(pluginId: string): HttpAccess {
 }
 
 /**
- * Create blocked HTTP access (for plugins without network:fetch capability)
+ * Create blocked HTTP access (for plugins without network:request capability)
  */
 export function createBlockedHttpAccess(pluginId: string): HttpAccess {
 	return {
 		async fetch(): Promise<never> {
 			throw new Error(
-				`Plugin "${pluginId}" does not have the "network:fetch" capability. ` +
-					`Add "network:fetch" to the plugin's capabilities to enable HTTP requests.`,
+				`Plugin "${pluginId}" does not have the "network:request" capability. ` +
+					`Add "network:request" to the plugin's capabilities to enable HTTP requests.`,
 			);
 		},
 	};
@@ -902,32 +902,35 @@ export class PluginContextFactory {
 		const storage = createStorageAccess(this.db, plugin.id, plugin.storage);
 
 		// Capability-gated: content
+		// Note: capabilities reach this point already normalized to the
+		// canonical names by definePlugin / adaptSandboxEntry. Deprecated
+		// names ("read:content", "write:content") never appear here.
 		let content: ContentAccess | ContentAccessWithWrite | undefined;
-		if (capabilities.has("write:content")) {
+		if (capabilities.has("content:write")) {
 			content = createContentAccessWithWrite(this.db);
-		} else if (capabilities.has("read:content")) {
+		} else if (capabilities.has("content:read")) {
 			content = createContentAccess(this.db);
 		}
 
 		// Capability-gated: media
 		let media: MediaAccess | MediaAccessWithWrite | undefined;
-		if (capabilities.has("write:media") && this.getUploadUrl) {
+		if (capabilities.has("media:write") && this.getUploadUrl) {
 			media = createMediaAccessWithWrite(this.db, this.getUploadUrl, this.storage);
-		} else if (capabilities.has("read:media")) {
+		} else if (capabilities.has("media:read")) {
 			media = createMediaAccess(this.db);
 		}
 
 		// Capability-gated: http
 		let http: HttpAccess | undefined;
-		if (capabilities.has("network:fetch:any")) {
+		if (capabilities.has("network:request:unrestricted")) {
 			http = createUnrestrictedHttpAccess(plugin.id);
-		} else if (capabilities.has("network:fetch")) {
+		} else if (capabilities.has("network:request")) {
 			http = createHttpAccess(plugin.id, plugin.allowedHosts);
 		}
 
 		// Capability-gated: users
 		let users: UserAccess | undefined;
-		if (capabilities.has("read:users")) {
+		if (capabilities.has("users:read")) {
 			users = createUserAccess(this.db);
 		}
 

package/src/plugins/define-plugin.ts

@@ -13,6 +13,7 @@
  *
  */
 
+import { normalizeCapabilities } from "./types.js";
 import type {
 	PluginDefinition,
 	ResolvedPlugin,
@@ -20,6 +21,7 @@ import type {
 	ResolvedPluginHooks,
 	ResolvedHook,
 	HookConfig,
+	PluginCapability,
 	PluginStorageConfig,
 	StandardPluginDefinition,
 } from "./types.js";
@@ -65,7 +67,7 @@ const SEMVER_PATTERN = /^\d+\.\d+\.\d+/;
  * export default definePlugin({
  *   id: "my-plugin",
  *   version: "1.0.0",
- *   capabilities: ["read:content"],
+ *   capabilities: ["content:read"],
  *   hooks: {
  *     "content:beforeSave": async (event, ctx) => {
  *       ctx.log.info("Saving content", { collection: event.collection });
@@ -143,8 +145,24 @@ function defineNativePlugin<TStorage extends PluginStorageConfig>(
 		throw new Error(`Invalid plugin version "${version}". Must be semver format (e.g., "1.0.0").`);
 	}
 
-	// Validate capabilities
-	const validCapabilities = new Set([
+	// Validate capabilities. Both current names and deprecated aliases are
+	// accepted; aliases are silently rewritten to current names below so the
+	// runtime only ever sees the canonical form. Authors are warned at
+	// bundle/validate and hard-failed at publish.
+	const validCapabilities = new Set<string>([
+		// Current names
+		"network:request",
+		"network:request:unrestricted",
+		"content:read",
+		"content:write",
+		"media:read",
+		"media:write",
+		"users:read",
+		"email:send",
+		"hooks.email-transport:register",
+		"hooks.email-events:register",
+		"hooks.page-fragments:register",
+		// Deprecated aliases
 		"network:fetch",
 		"network:fetch:any",
 		"read:content",
@@ -152,7 +170,6 @@ function defineNativePlugin<TStorage extends PluginStorageConfig>(
 		"read:media",
 		"write:media",
 		"read:users",
-		"email:send",
 		"email:provide",
 		"email:intercept",
 		"page:inject",
@@ -163,16 +180,27 @@ function defineNativePlugin<TStorage extends PluginStorageConfig>(
 		}
 	}
 
-	// Capability implications: broader capabilities imply narrower ones
-	const normalizedCapabilities = [...capabilities];
-	if (capabilities.includes("write:content") && !capabilities.includes("read:content")) {
-		normalizedCapabilities.push("read:content");
+	// Silent normalization: rewrite deprecated names to current names. Done
+	// before the implication pass so implications work on canonical names.
+	// `as PluginCapability[]` is safe because `normalizeCapabilities` only
+	// returns strings from the validated input plus current names from the
+	// rename map, all of which are in the union.
+	const canonical = normalizeCapabilities(capabilities) as PluginCapability[];
+
+	// Capability implications: broader capabilities imply narrower ones.
+	// Operates on canonical names only.
+	const normalizedCapabilities: PluginCapability[] = [...canonical];
+	if (canonical.includes("content:write") && !canonical.includes("content:read")) {
+		normalizedCapabilities.push("content:read");
 	}
-	if (capabilities.includes("write:media") && !capabilities.includes("read:media")) {
-		normalizedCapabilities.push("read:media");
+	if (canonical.includes("media:write") && !canonical.includes("media:read")) {
+		normalizedCapabilities.push("media:read");
 	}
-	if (capabilities.includes("network:fetch:any") && !capabilities.includes("network:fetch")) {
-		normalizedCapabilities.push("network:fetch");
+	if (
+		canonical.includes("network:request:unrestricted") &&
+		!canonical.includes("network:request")
+	) {
+		normalizedCapabilities.push("network:request");
 	}
 
 	// Normalize hooks

package/src/plugins/hooks.ts

@@ -248,28 +248,32 @@ export class HookPipeline {
 	 * capability will have that hook silently skipped at registration time.
 	 */
 	private static readonly HOOK_REQUIRED_CAPABILITY: ReadonlyMap<string, string> = new Map([
-		// Email
-		["email:beforeSend", "email:intercept"],
-		["email:afterSend", "email:intercept"],
-		["email:deliver", "email:provide"],
-		// Content — beforeSave can mutate content, so requires write:content.
-		// afterSave is read-only notification, so read:content suffices.
-		["content:beforeSave", "write:content"],
-		["content:afterSave", "read:content"],
-		["content:beforeDelete", "read:content"],
-		["content:afterDelete", "read:content"],
-		["content:afterPublish", "read:content"],
-		["content:afterUnpublish", "read:content"],
+		// Email — registering email:beforeSend/afterSend/deliver requires the
+		// matching `hooks.email-*:register` capability. These are distinct
+		// from `email:send` (which gates ctx.email) so that "this plugin
+		// reads/writes email events" is visible separately from "this
+		// plugin can send email".
+		["email:beforeSend", "hooks.email-events:register"],
+		["email:afterSend", "hooks.email-events:register"],
+		["email:deliver", "hooks.email-transport:register"],
+		// Content — beforeSave can mutate content, so requires content:write.
+		// afterSave is read-only notification, so content:read suffices.
+		["content:beforeSave", "content:write"],
+		["content:afterSave", "content:read"],
+		["content:beforeDelete", "content:read"],
+		["content:afterDelete", "content:read"],
+		["content:afterPublish", "content:read"],
+		["content:afterUnpublish", "content:read"],
 		// Media
-		["media:beforeUpload", "write:media"],
-		["media:afterUpload", "read:media"],
+		["media:beforeUpload", "media:write"],
+		["media:afterUpload", "media:read"],
 		// Comments — hooks expose author email, IP hash, user agent
-		["comment:beforeCreate", "read:users"],
-		["comment:moderate", "read:users"],
-		["comment:afterCreate", "read:users"],
-		["comment:afterModerate", "read:users"],
+		["comment:beforeCreate", "users:read"],
+		["comment:moderate", "users:read"],
+		["comment:afterCreate", "users:read"],
+		["comment:afterModerate", "users:read"],
 		// Page fragments — can inject arbitrary scripts into every public page
-		["page:fragments", "page:inject"],
+		["page:fragments", "hooks.page-fragments:register"],
 	]);
 
 	/**

package/src/plugins/index.ts

@@ -192,3 +192,12 @@ export type {
 	StandardRouteEntry,
 } from "./types.js";
 export { isStandardPluginDefinition } from "./types.js";
+
+// Capability normalization (legacy → canonical alias layer)
+export {
+	CAPABILITY_RENAMES,
+	isDeprecatedCapability,
+	normalizeCapability,
+	normalizeCapabilities,
+} from "./types.js";
+export type { CurrentPluginCapability, DeprecatedPluginCapability } from "./types.js";

package/src/plugins/manifest-schema.ts

@@ -12,7 +12,31 @@ import { z } from "zod";
 
 // ── Enum values (must stay in sync with types.ts) ───────────────
 
-export const PLUGIN_CAPABILITIES = [
+/**
+ * Current capability names — the ones authors should use going forward.
+ * See `PluginCapability` in `types.ts` for documentation of each.
+ */
+export const CURRENT_PLUGIN_CAPABILITIES = [
+	"network:request",
+	"network:request:unrestricted",
+	"content:read",
+	"content:write",
+	"media:read",
+	"media:write",
+	"users:read",
+	"email:send",
+	"hooks.email-transport:register",
+	"hooks.email-events:register",
+	"hooks.page-fragments:register",
+] as const;
+
+/**
+ * Legacy capability names accepted during the deprecation window.
+ * Normalized to current names via `normalizeCapability()` in types.ts
+ * before reaching the runtime. Plugin authors are warned at bundle/validate
+ * and hard-failed at publish.
+ */
+export const DEPRECATED_PLUGIN_CAPABILITIES = [
 	"network:fetch",
 	"network:fetch:any",
 	"read:content",
@@ -20,12 +44,23 @@ export const PLUGIN_CAPABILITIES = [
 	"read:media",
 	"write:media",
 	"read:users",
-	"email:send",
 	"email:provide",
 	"email:intercept",
 	"page:inject",
 ] as const;
 
+/**
+ * Full set of accepted capability strings — current + deprecated.
+ *
+ * The manifest schema accepts both during the transition. The runtime only
+ * ever sees current names because `normalizeCapability()` rewrites legacy
+ * names at every external boundary (definePlugin, adaptSandboxEntry).
+ */
+export const PLUGIN_CAPABILITIES = [
+	...CURRENT_PLUGIN_CAPABILITIES,
+	...DEPRECATED_PLUGIN_CAPABILITIES,
+] as const;
+
 /** Must stay in sync with FieldType in schema/types.ts */
 const FIELD_TYPES = [
 	"string",