emdash 0.40.0 → 0.41.0

package/dist/types-D0aJW2uR.d.mts

@@ -0,0 +1,1641 @@
+import { r as ContentFieldFilters } from "./content-list-query-D_7B1FE5.mjs";
+import { f as FieldType, m as FieldWidgetOptions, p as FieldValidation } from "./types-DbpN4Qto.mjs";
+import { z } from "astro/zod";
+import { Permission } from "@emdash-cms/auth";
+import { CAPABILITY_RENAMES, CurrentPluginCapability, DeclaredAccess, DeprecatedPluginCapability, ManifestHookEntry as ManifestHookEntry$1, ManifestRouteEntry as ManifestRouteEntry$1, PluginCapability, PluginEditorDraftAccess, PluginEditorDraftFieldSelector, PluginFormData, PluginMcpManifestConfig, PluginRouteBodyMode, PluginRouteQuery, PluginRouteRequest, PluginStorageConfig, RouteOptions, StorageCollectionConfig, isDeprecatedCapability, normalizeCapabilities, normalizeCapability } from "@emdash-cms/plugin-types";
+import { ConfirmDialog, Element, PluginUiContext } from "@emdash-cms/blocks";
+import { JSX } from "astro/jsx-runtime";
+
+//#region src/plugins/types.d.ts
+declare function normalizePluginCapabilities(capabilities: readonly PluginCapability[]): PluginCapability[];
+declare function normalizePluginCapabilities(capabilities: readonly string[]): string[];
+/**
+ * Query filter operators
+ */
+interface RangeFilter {
+  gt?: number | string;
+  gte?: number | string;
+  lt?: number | string;
+  lte?: number | string;
+}
+interface InFilter {
+  in: Array<string | number>;
+}
+interface StartsWithFilter {
+  startsWith: string;
+}
+/**
+ * Where clause value types
+ */
+type WhereValue = string | number | boolean | null | RangeFilter | InFilter | StartsWithFilter;
+/**
+ * Where clause for storage queries
+ */
+type WhereClause = Record<string, WhereValue>;
+/**
+ * Query options for storage.query()
+ */
+interface QueryOptions {
+  where?: WhereClause;
+  orderBy?: Record<string, "asc" | "desc">;
+  /** Default 50, max 100 */
+  limit?: number;
+  cursor?: string;
+}
+/**
+ * Paginated result (used by storage.query, content.list, media.list)
+ */
+interface PaginatedResult<T> {
+  items: T[];
+  cursor?: string;
+  hasMore: boolean;
+}
+interface VersionedValue<T = unknown> {
+  value: T;
+  /** Opaque host revision, valid only for the key from which it was read. */
+  revision: string;
+}
+type ConditionalWriteResult = {
+  applied: true;
+  revision: string;
+} | {
+  applied: false;
+};
+interface ConditionalDeleteResult {
+  applied: boolean;
+}
+/**
+ * A single per-field integer delta for {@link StorageCollection.updateIf}.
+ *
+ * `inc`/`dec` values must be safe integers, enforced at runtime with
+ * `Number.isSafeInteger` (which also rejects `NaN`/`Infinity`), because a TS
+ * `number` cannot forbid float literals. Deltas are applied entirely in-SQL
+ * over the stored value with `COALESCE(<value>, 0) ± n`, so a delta on a
+ * missing or JSON-`null` field starts from `0` (never corrupts the document).
+ *
+ * `updateIf` does NOT clamp: a `dec` can drive a field negative when the
+ * `where` guard doesn't cover the delta magnitude (e.g. stock `2` with
+ * `where: { stock: { gte: 1 } }` and `delta: { stock: { dec: 3 } }` → `-1`,
+ * `applied: true`). The guard is the caller's responsibility — pair a `dec: k`
+ * with a `gte: k` guard to prevent underflow.
+ */
+type NumericDelta = {
+  inc: number;
+} | {
+  dec: number;
+};
+/**
+ * Arguments to {@link StorageCollection.updateIf}.
+ *
+ * `where` reuses the {@link QueryOptions} `WhereClause` verbatim — the guard is
+ * evaluated in-SQL with the same numeric-correct, total comparisons as
+ * `query()`. An empty `where: {}` emits no guard, i.e. it matches the row
+ * unconditionally (update-if-row-exists) — a footgun in the no-oversell case,
+ * where a real predicate (e.g. `{ stock: { gte: 1 } }`) is what you want.
+ *
+ * At least one of `set` / `delta` must be present (a runtime error is thrown
+ * otherwise). A field may not appear in both `set` and `delta` in the same
+ * call. `set` and `delta` are separate arguments (not a union) so a wholesale
+ * value that happens to look like `{ inc: 5 }` is never mistaken for a delta.
+ */
+interface UpdateIfArgs<T> {
+  /**
+   * Guard evaluated in-SQL; identical semantics to `query({ where })`. An
+   * empty `{}` means "match the row unconditionally (no guard)".
+   */
+  where: WhereClause;
+  /** Wholesale field values merged into the stored JSON document. */
+  set?: Partial<T>;
+  /** Per-field integer deltas applied in-SQL (`COALESCE(base, 0) ± n`). */
+  delta?: { [K in keyof T]?: NumericDelta };
+}
+/**
+ * Result of {@link StorageCollection.updateIf}.
+ *
+ * `applied: false` intentionally conflates "row absent" and "guard failed": a
+ * single-statement guarded `UPDATE` cannot distinguish them, and the caller
+ * should not need to. `updateIf` is update-only — it never inserts a missing
+ * row.
+ */
+type UpdateIfResult<T> = {
+  applied: true;
+  data: T;
+} | {
+  applied: false;
+};
+/**
+ * Storage collection interface - the API exposed to plugins
+ * No async iterators - all operations return promises with pagination
+ */
+interface StorageCollection<T = unknown> {
+  get(id: string): Promise<T | null>;
+  put(id: string, data: T): Promise<void>;
+  delete(id: string): Promise<boolean>;
+  exists(id: string): Promise<boolean>;
+  /** A stored JSON null returns an envelope with value: null; only an absent row returns null. */
+  getVersioned(id: string): Promise<VersionedValue<T> | null>;
+  /** A null expected revision creates only when absent. Errors reject; conflicts return applied: false. */
+  compareAndSet(id: string, expectedRevision: string | null, data: T): Promise<ConditionalWriteResult>;
+  compareAndDelete(id: string, expectedRevision: string): Promise<ConditionalDeleteResult>;
+  getMany(ids: string[]): Promise<Map<string, T>>;
+  putMany(items: Array<{
+    id: string;
+    data: T;
+  }>): Promise<void>;
+  deleteMany(ids: string[]): Promise<number>;
+  query(options?: QueryOptions): Promise<PaginatedResult<{
+    id: string;
+    data: T;
+  }>>;
+  count(where?: WhereClause): Promise<number>;
+  /**
+   * Predicate-guarded atomic update. Applies `set`/`delta` to the row `id`
+   * only if it exists and the `where` guard matches, in a single guarded
+   * `UPDATE … RETURNING`. This is the no-oversell primitive: the guard and the
+   * arithmetic live in one statement, so N concurrent guarded decrements
+   * serialize correctly. `applied: false` means the row was absent OR the
+   * guard failed (the two are intentionally indistinguishable). Non-object
+   * documents, invalid counters and unsafe arithmetic results also fail the
+   * guard. Never inserts.
+   *
+   * Serialization failures and deadlocks throw `StorageSerializationError`.
+   * Retry the write with a bounded policy; restart an explicit transaction
+   * before retrying its operations.
+   */
+  updateIf(id: string, args: UpdateIfArgs<T>): Promise<UpdateIfResult<T>>;
+}
+/**
+ * Plugin storage context - typed based on declared collections
+ */
+type PluginStorage<T extends PluginStorageConfig> = { [K in keyof T]: StorageCollection };
+/**
+ * Plugin-scoped key-value state.
+ *
+ * Convention:
+ * - `state:*` - Internal plugin state (not shown to users)
+ * - `cache:*` - Reusable computed or remote data
+ *
+ * The `settings:*` namespace remains a compatibility alias through EmDash
+ * 0.x. New code uses `PluginContext.settings` for user configuration.
+ */
+interface KVAccess {
+  get<T>(key: string): Promise<T | null>;
+  getVersioned<T>(key: string): Promise<VersionedValue<T> | null>;
+  /** A null expected revision creates only when absent. Errors reject; conflicts return applied: false. */
+  compareAndSet(key: string, expectedRevision: string | null, value: unknown): Promise<ConditionalWriteResult>;
+  compareAndDelete(key: string, expectedRevision: string): Promise<ConditionalDeleteResult>;
+  set(key: string, value: unknown): Promise<void>;
+  delete(key: string): Promise<boolean>;
+  list(prefix?: string): Promise<Array<{
+    key: string;
+    value: unknown;
+  }>>;
+}
+/** Plugin settings. Fields declared as `secret` in `admin.settingsSchema` are encrypted. */
+interface SettingsAccess {
+  get<T>(key: string): Promise<T | null>;
+  getVersioned<T>(key: string): Promise<VersionedValue<T> | null>;
+  compareAndSet(key: string, expectedRevision: string | null, value: unknown): Promise<ConditionalWriteResult>;
+  compareAndDelete(key: string, expectedRevision: string): Promise<ConditionalDeleteResult>;
+  set(key: string, value: unknown): Promise<void>;
+  delete(key: string): Promise<boolean>;
+  list(prefix?: string): Promise<Array<{
+    key: string;
+    value: unknown;
+  }>>;
+}
+/**
+ * SEO metadata for a content item, as stored in the core SEO panel.
+ *
+ * Only present on items in collections with `has_seo = 1`. For collections
+ * without SEO enabled, `ContentItem.seo` is `undefined`.
+ */
+interface ContentItemSeo {
+  title: string | null;
+  description: string | null;
+  image: string | null;
+  canonical: string | null;
+  noIndex: boolean;
+}
+/**
+ * SEO input accepted by content write operations.
+ *
+ * All fields are optional — only fields that are present overwrite existing
+ * values. An empty object is treated as a no-op.
+ */
+interface ContentItemSeoInput {
+  title?: string | null;
+  description?: string | null;
+  image?: string | null;
+  canonical?: string | null;
+  noIndex?: boolean;
+}
+/**
+ * Content item returned from content API
+ */
+interface ContentItem {
+  id: string;
+  type: string;
+  slug: string | null;
+  status: string;
+  locale: string | null;
+  data: Record<string, unknown>;
+  /**
+   * SEO metadata, populated when the collection has SEO enabled
+   * (`has_seo = 1`). `undefined` for non-SEO collections.
+   */
+  seo?: ContentItemSeo;
+  createdAt: string;
+  updatedAt: string;
+  publishedAt: string | null;
+  /** Scheduled publication time, if set (e.g. scheduled items or scheduled draft changes). */
+  scheduledAt?: string | null;
+  authorId?: string | null;
+  translationGroup?: string | null;
+  liveRevisionId?: string | null;
+  draftRevisionId?: string | null;
+  version?: number;
+}
+interface ContentTranslationSummary {
+  id: string;
+  locale: string | null;
+  slug: string | null;
+  status: string;
+  updatedAt: string;
+}
+interface ContentRevisionInfo {
+  id: string;
+  collection: string;
+  entryId: string;
+  data: Record<string, unknown>;
+  createdAt: string;
+}
+interface FieldSchemaInfo {
+  slug: string;
+  label: string;
+  type: FieldType;
+  required: boolean;
+  unique: boolean;
+  default?: unknown;
+  validation?: FieldValidation;
+  widget?: string;
+  options?: FieldWidgetOptions;
+  searchable: boolean;
+  indexed: boolean;
+  translatable: boolean;
+  sortOrder: number;
+}
+interface CollectionSchemaInfo {
+  slug: string;
+  label: string;
+  labelSingular: string | null;
+  description: string | null;
+  supports: string[];
+  hasSeo: boolean;
+  titleField: string | null;
+  dateField: string | null;
+  urlPattern: string | null;
+  routable: boolean;
+  hidden: boolean;
+  fields: FieldSchemaInfo[];
+}
+interface SchemaAccess {
+  listCollections(): Promise<CollectionSchemaInfo[]>;
+  getCollection(slug: string): Promise<CollectionSchemaInfo | null>;
+}
+interface ContentListWhere {
+  /** Exact match on `status` (e.g. `"published"`, `"draft"`). */
+  status?: string;
+  /** Exact match on `locale` (e.g. `"en"`, `"fr-CA"`). */
+  locale?: string;
+  /** AND-combined filters over custom fields explicitly marked as indexed. */
+  fieldFilters?: ContentFieldFilters;
+}
+/**
+ * Content list options
+ */
+interface ContentListOptions {
+  limit?: number;
+  cursor?: string;
+  orderBy?: Record<string, "asc" | "desc">;
+  where?: ContentListWhere;
+}
+/**
+ * Input accepted by `content.create` / `content.update`.
+ *
+ * Most entries are field slugs mapped to their values. The reserved `seo`
+ * key is extracted and routed to the core SEO panel (the `_emdash_seo`
+ * table), matching the shape accepted by the REST API. Passing `seo` for a
+ * collection that does not have SEO enabled throws a validation error.
+ */
+type ContentWriteInput = Record<string, unknown> & {
+  seo?: ContentItemSeoInput;
+};
+/** Options accepted by `content.create`. */
+interface ContentCreateOptions {
+  /** Locale for the new content row. Defaults to the configured site locale, then `en`. */
+  locale?: string;
+  /** Existing row in the same collection whose translation group the new row joins. */
+  translationOf?: string;
+}
+type PluginContentCreateCallback = (pluginId: string, collection: string, data: ContentWriteInput, options?: ContentCreateOptions & {
+  /** Save-hook origin supplied by sandbox transports to prevent hook re-entry. */originHook?: "content:beforeSave" | "content:afterSave";
+  sandboxOrigin?: true;
+}) => Promise<ContentItem>;
+/**
+ * Taxonomy definition returned from the taxonomy API (e.g. "category", "tag").
+ */
+interface TaxonomyDefInfo {
+  name: string;
+  label: string;
+  labelSingular: string | null;
+  hierarchical: boolean;
+  /** Collections this taxonomy is attached to (e.g. `["posts"]`). */
+  collections: string[];
+  locale: string;
+}
+/**
+ * Taxonomy term returned from the taxonomy API. Flat shape — for hierarchical
+ * taxonomies the tree is reconstructed via `parentId` (which stores the
+ * parent's locale-agnostic `translationGroup`).
+ */
+interface TaxonomyTermInfo {
+  id: string;
+  /** Taxonomy name this term belongs to (e.g. "category"). */
+  taxonomy: string;
+  slug: string;
+  label: string;
+  parentId: string | null;
+  /** Term metadata as edited in the admin (`description` etc.). */
+  data: Record<string, unknown> | null;
+  locale: string;
+  translationGroup: string | null;
+}
+/**
+ * Options accepted by taxonomy read operations. Omitting `locale` returns
+ * rows for every locale.
+ */
+interface TaxonomyReadOptions {
+  locale?: string;
+}
+interface TaxonomyTermCreateInput {
+  label: string;
+  slug?: string;
+  parentId?: string | null;
+  description?: string;
+  locale?: string;
+  translationOf?: string;
+}
+/**
+ * Content access interface - capability-gated
+ */
+interface ContentAccess {
+  get(collection: string, id: string): Promise<ContentItem | null>;
+  list(collection: string, options?: ContentListOptions): Promise<PaginatedResult<ContentItem>>;
+  getTranslations?(collection: string, id: string): Promise<{
+    translationGroup: string;
+    translations: ContentTranslationSummary[];
+  }>;
+  getPublicUrl?(collection: string, id: string): Promise<string | null>;
+  listRevisions?(collection: string, id: string, options?: {
+    limit?: number;
+  }): Promise<ContentRevisionInfo[]>;
+  getRevision?(collection: string, id: string, revisionId: string): Promise<ContentRevisionInfo | null>;
+  create?(collection: string, data: ContentWriteInput, options?: ContentCreateOptions): Promise<ContentItem>;
+  update?(collection: string, id: string, data: ContentWriteInput): Promise<ContentItem>;
+  delete?(collection: string, id: string): Promise<boolean>;
+  getVersioned?(collection: string, id: string): Promise<VersionedContentItem | null>;
+  publish?(collection: string, id: string, options: {
+    _rev: string;
+  }): Promise<VersionedContentItem>;
+  unpublish?(collection: string, id: string, options: {
+    _rev: string;
+  }): Promise<VersionedContentItem>;
+  schedule?(collection: string, id: string, options: {
+    scheduledAt: string;
+    _rev: string;
+  }): Promise<VersionedContentItem>;
+  unschedule?(collection: string, id: string, options: {
+    _rev: string;
+  }): Promise<VersionedContentItem>;
+  getTrashedVersioned?(collection: string, id: string): Promise<VersionedContentItem | null>;
+  restore?(collection: string, id: string, options: {
+    _rev: string;
+  }): Promise<VersionedContentItem>;
+}
+interface VersionedContentItem {
+  item: ContentItem;
+  _rev: string;
+}
+/**
+ * Taxonomy access interface — capability-gated on `taxonomies:read`.
+ */
+interface TaxonomyAccess {
+  /** List taxonomy definitions. */
+  getAll(options?: TaxonomyReadOptions): Promise<TaxonomyDefInfo[]>;
+  /** All terms of a taxonomy, ordered by label. */
+  getTerms(taxonomy: string, options?: TaxonomyReadOptions): Promise<TaxonomyTermInfo[]>;
+  /** Terms assigned to a content entry, optionally scoped to one taxonomy. */
+  getEntryTerms(collection: string, entryId: string, options?: TaxonomyReadOptions & {
+    taxonomy?: string;
+  }): Promise<TaxonomyTermInfo[]>;
+  createTerm?(taxonomy: string, input: TaxonomyTermCreateInput): Promise<TaxonomyTermInfo>;
+  addEntryTerms?(collection: string, entryId: string, taxonomy: string, termIds: string[]): Promise<TaxonomyTermInfo[]>;
+  removeEntryTerms?(collection: string, entryId: string, taxonomy: string, termIds: string[]): Promise<TaxonomyTermInfo[]>;
+}
+/** Taxonomy mutations available with `taxonomies:write`. */
+interface TaxonomyAccessWithWrite extends TaxonomyAccess {
+  createTerm(taxonomy: string, input: TaxonomyTermCreateInput): Promise<TaxonomyTermInfo>;
+  addEntryTerms(collection: string, entryId: string, taxonomy: string, termIds: string[]): Promise<TaxonomyTermInfo[]>;
+  removeEntryTerms(collection: string, entryId: string, taxonomy: string, termIds: string[]): Promise<TaxonomyTermInfo[]>;
+}
+type RedirectStatus = 301 | 302 | 307 | 308 | 410 | 451;
+interface RedirectInfo {
+  id: string;
+  source: string;
+  destination: string;
+  type: RedirectStatus;
+  isPattern: boolean;
+  enabled: boolean;
+  hits: number;
+  lastHitAt: string | null;
+  groupName: string | null;
+  auto: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+interface VersionedRedirect {
+  redirect: RedirectInfo;
+  /** Opaque host revision. Pass it back unchanged for update or delete. */
+  _rev: string;
+}
+interface RedirectListOptions {
+  limit?: number;
+  cursor?: string;
+  search?: string;
+  group?: string;
+  enabled?: boolean;
+  auto?: boolean;
+}
+interface RedirectCreateInput {
+  source: string;
+  destination?: string;
+  type?: RedirectStatus;
+  enabled?: boolean;
+  groupName?: string | null;
+}
+interface RedirectUpdateInput {
+  source?: string;
+  destination?: string;
+  type?: RedirectStatus;
+  enabled?: boolean;
+  groupName?: string | null;
+}
+interface RedirectAccess {
+  list(options?: RedirectListOptions): Promise<PaginatedResult<RedirectInfo>>;
+  get(id: string): Promise<VersionedRedirect | null>;
+  create?(input: RedirectCreateInput): Promise<VersionedRedirect>;
+  update?(id: string, input: RedirectUpdateInput & {
+    _rev: string;
+  }): Promise<VersionedRedirect>;
+  delete?(id: string, options: {
+    _rev: string;
+  }): Promise<boolean>;
+}
+interface RedirectAccessWithWrite extends RedirectAccess {
+  create(input: RedirectCreateInput): Promise<VersionedRedirect>;
+  update(id: string, input: RedirectUpdateInput & {
+    _rev: string;
+  }): Promise<VersionedRedirect>;
+  delete(id: string, options: {
+    _rev: string;
+  }): Promise<boolean>;
+}
+/**
+ * Full content access with write operations
+ */
+interface ContentAccessWithWrite extends ContentAccess {
+  create(collection: string, data: ContentWriteInput, options?: ContentCreateOptions): Promise<ContentItem>;
+  update(collection: string, id: string, data: ContentWriteInput): Promise<ContentItem>;
+  delete(collection: string, id: string): Promise<boolean>;
+}
+/**
+ * Media item returned from media API
+ */
+interface MediaItem {
+  id: string;
+  filename: string;
+  mimeType: string;
+  size: number | null;
+  url: string;
+  createdAt: string;
+  width?: number | null;
+  height?: number | null;
+  alt?: string | null;
+  caption?: string | null;
+  focalX?: number | null;
+  focalY?: number | null;
+  blurhash?: string | null;
+  dominantColor?: string | null;
+  folderId?: string | null;
+  status?: "ready";
+}
+interface MediaBytes {
+  bytes: Uint8Array;
+  filename: string;
+  mimeType: string;
+  size: number;
+  contentHash?: string;
+}
+interface MediaMetadataPatch {
+  alt?: string | null;
+  caption?: string | null;
+  focalX?: number | null;
+  focalY?: number | null;
+}
+/**
+ * Media list options
+ */
+interface MediaListOptions {
+  limit?: number;
+  cursor?: string;
+  mimeType?: string;
+}
+/**
+ * Media access interface - capability-gated
+ */
+interface MediaAccess {
+  get(id: string): Promise<MediaItem | null>;
+  list(options?: MediaListOptions): Promise<PaginatedResult<MediaItem>>;
+  /** Read ready media bytes, bounded by the caller's limit and the host maximum. */
+  readBytes?(id: string, options?: {
+    maxBytes?: number;
+  }): Promise<MediaBytes>;
+  /** Change only alt text, caption, or the complete focal-point pair. */
+  updateMetadata?(id: string, patch: MediaMetadataPatch): Promise<MediaItem>;
+  getUploadUrl?(filename: string, contentType: string): Promise<{
+    uploadUrl: string;
+    mediaId: string;
+  }>;
+  /**
+   * Upload media bytes directly. Preferred in sandboxed mode where
+   * plugins cannot make external requests to a presigned URL.
+   * Returns the created media item.
+   */
+  upload?(filename: string, contentType: string, bytes: ArrayBuffer): Promise<{
+    mediaId: string;
+    storageKey: string;
+    url: string;
+  }>;
+  delete?(id: string): Promise<boolean>;
+}
+/**
+ * Full media access with write operations
+ */
+interface MediaAccessWithWrite extends MediaAccess {
+  getUploadUrl(filename: string, contentType: string): Promise<{
+    uploadUrl: string;
+    mediaId: string;
+  }>;
+  upload(filename: string, contentType: string, bytes: ArrayBuffer): Promise<{
+    mediaId: string;
+    storageKey: string;
+    url: string;
+  }>;
+  delete(id: string): Promise<boolean>;
+}
+/**
+ * HTTP client interface - requires network:request capability
+ */
+interface HttpAccess {
+  /**
+   * Fetch an allowed external URL and return a buffered response.
+   * Decoded request and response bodies are each limited to 8 MiB.
+   */
+  fetch(url: string, init?: RequestInit): Promise<Response>;
+}
+/**
+ * Logger interface - always available
+ */
+interface LogAccess {
+  debug(message: string, data?: unknown): void;
+  info(message: string, data?: unknown): void;
+  warn(message: string, data?: unknown): void;
+  error(message: string, data?: unknown): void;
+}
+/**
+ * Site information available to all plugins
+ */
+interface SiteInfo {
+  /** Site name (from settings) */
+  name: string;
+  /** Site URL (from settings or request) */
+  url: string;
+  /** Site locale (from settings, defaults to "en") */
+  locale: string;
+  /**
+   * Astro's `trailingSlash` routing policy, from the host's Astro config.
+   * Plugins that build absolute URLs (sitemap, canonical, hreflang) should
+   * honor this so the URLs they emit match what the site serves. `createSiteInfo`
+   * always populates it (defaulting to `"ignore"`, Astro's default); it is
+   * optional on the type so pre-existing `SiteInfo` construction stays valid.
+   */
+  trailingSlash?: "always" | "never" | "ignore";
+}
+/**
+ * Read-only user information exposed to plugins.
+ * Sensitive fields (password hashes, sessions, passkeys) are excluded.
+ */
+interface UserInfo {
+  id: string;
+  email: string;
+  name: string | null;
+  role: number;
+  createdAt: string;
+}
+/**
+ * User access interface - requires read:users capability
+ */
+interface UserAccess {
+  /** Get a user by ID */
+  get(id: string): Promise<UserInfo | null>;
+  /** Get a user by email */
+  getByEmail(email: string): Promise<UserInfo | null>;
+  /** List users with optional filters */
+  list(opts?: {
+    role?: number;
+    limit?: number;
+    cursor?: string;
+  }): Promise<{
+    items: UserInfo[];
+    nextCursor?: string;
+  }>;
+}
+type PluginCommentStatus = "approved" | "pending" | "spam";
+/** Comment data exposed by the explicit personal-data `comments:read` capability. */
+interface PluginComment {
+  id: string;
+  collection: string;
+  contentId: string;
+  parentId: string | null;
+  authorName: string;
+  authorEmail: string;
+  body: string;
+  status: PluginCommentStatus;
+  ipHash: string | null;
+  userAgent: string | null;
+  moderationMetadata: Record<string, unknown> | null;
+  createdAt: string;
+  updatedAt: string;
+}
+interface CommentListOptions {
+  status?: PluginCommentStatus;
+  collection?: string;
+  contentId?: string;
+  limit?: number;
+  cursor?: string;
+}
+interface CommentCountOptions {
+  status?: PluginCommentStatus;
+  collection?: string;
+  contentId?: string;
+}
+interface CommentAccess {
+  get(id: string): Promise<PluginComment | null>;
+  list(options?: CommentListOptions): Promise<PaginatedResult<PluginComment>>;
+  count(options?: CommentCountOptions): Promise<number>;
+  setStatus?(id: string, status: PluginCommentStatus, options: {
+    expectedStatus: PluginCommentStatus;
+  }): Promise<PluginComment>;
+}
+/**
+ * The unified plugin context - same shape for all hooks and routes
+ */
+interface PluginContext<TStorage extends PluginStorageConfig = PluginStorageConfig> {
+  /** Plugin metadata */
+  plugin: {
+    id: string;
+    version: string;
+  };
+  /** Storage collections - only if plugin declares storage */
+  storage: PluginStorage<TStorage>;
+  /** Key-value store for internal state */
+  kv: KVAccess;
+  /** Plugin settings. Secret schema fields are encrypted by the host. */
+  settings: SettingsAccess;
+  /** Content access - only if read:content or write:content capability */
+  content?: ContentAccess | ContentAccessWithWrite;
+  /** Schema discovery - only if schema:read capability */
+  schema?: SchemaAccess;
+  /** Taxonomy access - only if a taxonomy capability is declared. */
+  taxonomies?: TaxonomyAccess | TaxonomyAccessWithWrite;
+  /** Redirect access - only if redirects:read or redirects:write capability */
+  redirects?: RedirectAccess | RedirectAccessWithWrite;
+  /** Media access - only if read:media or write:media capability */
+  media?: MediaAccess | MediaAccessWithWrite;
+  /** HTTP client - only if network:request capability */
+  http?: HttpAccess;
+  /** Logger - always available */
+  log: LogAccess;
+  /** Site information - always available */
+  site: SiteInfo;
+  /** URL helper - generates absolute URLs from paths. Always available. */
+  url(path: string): string;
+  /** User access - only if read:users capability */
+  users?: UserAccess;
+  /** Comment access — only if comments:read or comments:moderate is declared. */
+  comments?: CommentAccess;
+  /** Cron task scheduling - always available, scoped to plugin */
+  cron?: CronAccess;
+  /** Email access - only if email:send capability and a provider is configured */
+  email?: EmailAccess;
+}
+/**
+ * Cron access interface �� always available on plugin context, scoped to plugin.
+ */
+interface CronAccess {
+  /** Schedule a recurring or one-shot task */
+  schedule(name: string, opts: {
+    schedule: string;
+    data?: Record<string, unknown>;
+  }): Promise<void>;
+  /** Cancel a scheduled task */
+  cancel(name: string): Promise<void>;
+  /** List this plugin's scheduled tasks */
+  list(): Promise<CronTaskInfo[]>;
+}
+/**
+ * Task info returned from CronAccess.list()
+ */
+interface CronTaskInfo {
+  name: string;
+  schedule: string;
+  nextRunAt: string;
+  lastRunAt: string | null;
+}
+/**
+ * Event passed to the `cron` hook handler
+ */
+interface CronEvent {
+  name: string;
+  data?: Record<string, unknown>;
+  scheduledAt: string;
+}
+/**
+ * Cron hook handler type
+ */
+type CronHandler = (event: CronEvent, ctx: PluginContext) => Promise<void>;
+/**
+ * Email access interface — requires `email:send` capability.
+ * Undefined when no `email:deliver` provider is configured.
+ *
+ * Related capabilities:
+ * - `email:send` — grants ctx.email (this interface)
+ * - `email:provide` — allows registering the `email:deliver` exclusive hook
+ * - `email:intercept` — allows registering `email:beforeSend` / `email:afterSend` hooks
+ */
+interface EmailAccess {
+  send(message: EmailMessage): Promise<void>;
+}
+/**
+ * Email message shape
+ */
+interface EmailMessage {
+  to: string;
+  /** Additional visible recipients. */
+  cc?: string[];
+  /** Address that replies go to instead of the sender. */
+  replyTo?: string;
+  subject: string;
+  text: string;
+  html?: string;
+}
+/**
+ * Event passed to email:beforeSend hooks (middleware — transform, validate, cancel)
+ */
+interface EmailBeforeSendEvent {
+  message: EmailMessage;
+  /** Where the email originated — "system" for auth emails, plugin ID for plugin emails */
+  source: string;
+}
+/**
+ * Event passed to email:deliver hook (exclusive — exactly one provider delivers)
+ */
+interface EmailDeliverEvent {
+  message: EmailMessage;
+  source: string;
+}
+/**
+ * Event passed to email:afterSend hooks (logging, analytics, fire-and-forget)
+ */
+interface EmailAfterSendEvent {
+  message: EmailMessage;
+  source: string;
+}
+/**
+ * Handler type for email:beforeSend hooks.
+ * Returns modified message, or false to cancel delivery.
+ */
+type EmailBeforeSendHandler = (event: EmailBeforeSendEvent, ctx: PluginContext) => Promise<EmailMessage | false>;
+/**
+ * Handler type for email:deliver hooks (exclusive provider).
+ */
+type EmailDeliverHandler = (event: EmailDeliverEvent, ctx: PluginContext) => Promise<void>;
+/**
+ * Handler type for email:afterSend hooks (fire-and-forget).
+ */
+type EmailAfterSendHandler = (event: EmailAfterSendEvent, ctx: PluginContext) => Promise<void>;
+/**
+ * Collection comment settings (read from _emdash_collections)
+ */
+interface CollectionCommentSettings {
+  commentsEnabled: boolean;
+  commentsModeration: "all" | "first_time" | "none";
+  commentsClosedAfterDays: number;
+  commentsAutoApproveUsers: boolean;
+}
+/**
+ * Event passed to comment:beforeCreate hooks (middleware — transform, enrich, reject)
+ */
+interface CommentBeforeCreateEvent {
+  comment: {
+    collection: string;
+    contentId: string;
+    parentId: string | null;
+    authorName: string;
+    authorEmail: string;
+    authorUserId: string | null;
+    body: string;
+    ipHash: string | null;
+    userAgent: string | null;
+  };
+  /** Metadata bag — plugins can attach signals for the moderator */
+  metadata: Record<string, unknown>;
+}
+/**
+ * Event passed to comment:moderate hook (exclusive — decides initial status)
+ */
+interface CommentModerateEvent {
+  comment: CommentBeforeCreateEvent["comment"];
+  metadata: Record<string, unknown>;
+  collectionSettings: CollectionCommentSettings;
+  /** Number of prior approved comments from this email address */
+  priorApprovedCount: number;
+}
+/**
+ * Moderation decision returned by the comment:moderate handler
+ */
+interface ModerationDecision {
+  status: "approved" | "pending" | "spam";
+  /** Optional reason for admin visibility */
+  reason?: string;
+}
+/**
+ * Stored comment shape (full record with id, status, timestamps)
+ */
+interface StoredComment {
+  id: string;
+  collection: string;
+  contentId: string;
+  parentId: string | null;
+  authorName: string;
+  authorEmail: string;
+  authorUserId: string | null;
+  body: string;
+  status: string;
+  moderationMetadata: Record<string, unknown> | null;
+  createdAt: string;
+  updatedAt: string;
+}
+/**
+ * Event passed to comment:afterCreate hooks (fire-and-forget)
+ */
+interface CommentAfterCreateEvent {
+  comment: StoredComment;
+  metadata: Record<string, unknown>;
+  /** The content item the comment is on */
+  content: {
+    id: string;
+    collection: string;
+    slug: string;
+    title?: string;
+  };
+  /** The content author (for notifications) */
+  contentAuthor?: {
+    id: string;
+    name: string | null;
+    email: string;
+  };
+}
+/**
+ * Event passed to comment:afterModerate hooks (fire-and-forget, admin status change)
+ */
+interface CommentAfterModerateEvent {
+  comment: StoredComment;
+  previousStatus: string;
+  newStatus: string;
+  /** The admin who moderated */
+  moderator: {
+    id: string;
+    name: string | null;
+  };
+  /** Identifies whether an administrator or a plugin initiated the transition. */
+  origin?: {
+    source: "admin";
+    userId: string;
+  } | {
+    source: "plugin";
+    pluginId: string;
+  };
+}
+/**
+ * Handler type for comment:beforeCreate hooks.
+ * Returns modified event, or false to reject the comment.
+ */
+type CommentBeforeCreateHandler = (event: CommentBeforeCreateEvent, ctx: PluginContext) => Promise<CommentBeforeCreateEvent | false | void>;
+/**
+ * Handler type for comment:moderate hook (exclusive provider).
+ */
+type CommentModerateHandler = (event: CommentModerateEvent, ctx: PluginContext) => Promise<ModerationDecision>;
+/**
+ * Handler type for comment:afterCreate hooks (fire-and-forget).
+ */
+type CommentAfterCreateHandler = (event: CommentAfterCreateEvent, ctx: PluginContext) => Promise<void>;
+/**
+ * Handler type for comment:afterModerate hooks (fire-and-forget).
+ */
+type CommentAfterModerateHandler = (event: CommentAfterModerateEvent, ctx: PluginContext) => Promise<void>;
+/**
+ * Hook configuration
+ */
+interface HookConfig<THandler> {
+  /** Explicit ordering - lower numbers run first (default: 100) */
+  priority?: number;
+  /** Max execution time in ms (default: 5000) */
+  timeout?: number;
+  /** Run after these plugins */
+  dependencies?: string[];
+  /** Error handling policy */
+  errorPolicy?: "continue" | "abort";
+  /**
+   * Mark this hook as exclusive — only one plugin can be the active provider.
+   * Exclusive hooks skip the priority pipeline and dispatch only to the
+   * admin-selected provider. Used for email:deliver, search, image optimization, etc.
+   */
+  exclusive?: boolean;
+  /** The hook handler */
+  handler: THandler;
+}
+/**
+ * Acting user that triggered a content hook. Present for authenticated
+ * saves; absent for unauthenticated or internal writes.
+ */
+interface ActorInfo {
+  readonly id: string;
+  readonly role: number;
+  readonly source?: "api" | "mcp" | "visual-editor";
+}
+type ContentActionOrigin = {
+  source: "api" | "mcp" | "visual-editor";
+} | {
+  source: "plugin";
+  pluginId: string;
+} | {
+  source: "scheduler";
+} | {
+  source: "system";
+};
+type ContentPolicyDecision = void | {
+  cancel: true;
+  reason: string;
+};
+/**
+ * Content hook event
+ */
+interface ContentHookEvent {
+  content: Record<string, unknown>;
+  collection: string;
+  isNew: boolean;
+  /**
+   * ID of the existing item on `content:beforeSave` for an update. Absent on
+   * creates, where the ID is assigned when the save completes, and on
+   * `content:afterSave`, where `content.id` carries it.
+   */
+  id?: string;
+  /**
+   * The acting user for this save. Carries the same authenticated identity
+   * used to set the revision author, so plugins (e.g. audit logs) can record
+   * who made the change.
+   */
+  actor?: ActorInfo;
+}
+/**
+ * Content delete hook event
+ */
+interface ContentDeleteEvent {
+  id: string;
+  collection: string;
+  /** `true` when the content is permanently deleted (not just trashed). */
+  permanent: boolean;
+}
+/**
+ * Content state-change hook event (fired after publish, unpublish, restore,
+ * schedule, or unschedule).
+ */
+interface ContentStateChangeEvent {
+  content: Record<string, unknown>;
+  collection: string;
+}
+/**
+ * Content publish/unpublish hook event.
+ */
+type ContentPublishStateChangeEvent = ContentStateChangeEvent;
+/**
+ * Content restore hook event.
+ */
+type ContentRestoreStateChangeEvent = ContentStateChangeEvent;
+/**
+ * Content schedule/unschedule hook event.
+ */
+type ContentScheduleStateChangeEvent = ContentStateChangeEvent;
+interface ContentPolicyEvent extends ContentStateChangeEvent {
+  origin: ContentActionOrigin;
+  actor?: ActorInfo;
+}
+interface ContentSchedulePolicyEvent extends ContentPolicyEvent {
+  scheduledAt: string;
+}
+/**
+ * Media hook event
+ */
+interface MediaUploadEvent {
+  file: {
+    name: string;
+    type: string;
+    size: number;
+  };
+}
+/**
+ * Media after upload event
+ */
+interface MediaAfterUploadEvent {
+  media: MediaItem;
+}
+/**
+ * Lifecycle hook event
+ */
+interface LifecycleEvent {}
+/**
+ * Uninstall hook event
+ */
+interface UninstallEvent {
+  deleteData: boolean;
+}
+type ContentBeforeSaveHandler = (event: ContentHookEvent, ctx: PluginContext) => Promise<Record<string, unknown> | void>;
+type ContentAfterSaveHandler = (event: ContentHookEvent, ctx: PluginContext) => Promise<void>;
+type ContentBeforeDeleteHandler = (event: ContentDeleteEvent, ctx: PluginContext) => Promise<boolean | void>;
+type ContentAfterDeleteHandler = (event: ContentDeleteEvent, ctx: PluginContext) => Promise<void>;
+type ContentBeforePublishHandler = (event: ContentPolicyEvent, ctx: PluginContext) => Promise<ContentPolicyDecision>;
+type ContentBeforeScheduleHandler = (event: ContentSchedulePolicyEvent, ctx: PluginContext) => Promise<ContentPolicyDecision>;
+type ContentBeforeUnpublishHandler = (event: ContentPolicyEvent, ctx: PluginContext) => Promise<ContentPolicyDecision>;
+type ContentAfterPublishHandler = (event: ContentPublishStateChangeEvent, ctx: PluginContext) => Promise<void>;
+type ContentAfterUnpublishHandler = (event: ContentPublishStateChangeEvent, ctx: PluginContext) => Promise<void>;
+type ContentAfterRestoreHandler = (event: ContentRestoreStateChangeEvent, ctx: PluginContext) => Promise<void>;
+type ContentAfterScheduleHandler = (event: ContentScheduleStateChangeEvent, ctx: PluginContext) => Promise<void>;
+type ContentAfterUnscheduleHandler = (event: ContentScheduleStateChangeEvent, ctx: PluginContext) => Promise<void>;
+type MediaBeforeUploadHandler = (event: MediaUploadEvent, ctx: PluginContext) => Promise<{
+  name: string;
+  type: string;
+  size: number;
+} | void>;
+type MediaAfterUploadHandler = (event: MediaAfterUploadEvent, ctx: PluginContext) => Promise<void>;
+type LifecycleHandler = (event: LifecycleEvent, ctx: PluginContext) => Promise<void>;
+type UninstallHandler = (event: UninstallEvent, ctx: PluginContext) => Promise<void>;
+/** Placement targets for page fragment contributions */
+type PagePlacement = "head" | "body:start" | "body:end";
+/**
+ * A single breadcrumb trail item. Used by `PublicPageContext.breadcrumbs`
+ * so themes can publish breadcrumb trails that SEO plugins consume.
+ */
+interface BreadcrumbItem {
+  /** Display name for this crumb (e.g. "Home", "Blog", "My Post"). */
+  name: string;
+  /** Absolute or root-relative URL for this crumb. */
+  url: string;
+}
+/**
+ * Describes the page being rendered. Passed to page hooks so plugins
+ * can decide what to contribute without fetching content themselves.
+ */
+interface PublicPageContext {
+  url: string;
+  path: string;
+  locale: string | null;
+  kind: "content" | "custom";
+  pageType: string;
+  /** Full document title for the rendered page */
+  title: string | null;
+  /** Page-only title for OG/Twitter/JSON-LD headline output */
+  pageTitle?: string | null;
+  description: string | null;
+  canonical: string | null;
+  image: string | null;
+  content?: {
+    collection: string;
+    id: string;
+    slug: string | null;
+  };
+  /** SEO meta for base metadata generation in EmDashHead */
+  seo?: {
+    ogTitle?: string | null;
+    ogDescription?: string | null;
+    ogImage?: string | null;
+    robots?: string | null;
+  };
+  /** Article metadata for Open Graph article: tags */
+  articleMeta?: {
+    publishedTime?: string | null;
+    modifiedTime?: string | null;
+    author?: string | null;
+  };
+  /** Site name for structured data and og:site_name */
+  siteName?: string;
+  /**
+   * Optional breadcrumb trail for this page, root first. When set,
+   * SEO plugins should use this verbatim rather than deriving a trail
+   * from `path`. Themes typically populate this at the point they
+   * build the context (e.g. from a content hierarchy walk, taxonomy
+   * lookup, or per-`pageType` routing logic).
+   *
+   * Semantics for consumers:
+   *   - `undefined` — theme has no opinion; consumer falls back to
+   *     its own derivation.
+   *   - `[]` — this page has no breadcrumbs (e.g. homepage); consumer
+   *     should skip `BreadcrumbList` emission entirely.
+   *   - Non-empty array — used verbatim for `BreadcrumbList` output.
+   */
+  breadcrumbs?: BreadcrumbItem[];
+  /** Public-facing site URL (origin) for structured data */
+  siteUrl?: string;
+}
+interface PageMetadataEvent {
+  page: PublicPageContext;
+}
+/**
+ * Allowed rel values for link contributions.
+ * This is a security-critical allowlist -- sandboxed plugins can only inject
+ * link tags with these rel values. Adding "stylesheet", "prefetch", "prerender"
+ * etc. would allow sandboxed plugins to inject external resources.
+ */
+type PageMetadataLinkRel = "canonical" | "alternate" | "author" | "license" | "nlweb" | "site.standard.document";
+type PageMetadataContribution = {
+  kind: "meta";
+  name: string;
+  content: string;
+  key?: string;
+} | {
+  kind: "property";
+  property: string;
+  content: string;
+  key?: string;
+} | {
+  kind: "link";
+  rel: PageMetadataLinkRel;
+  href: string;
+  hreflang?: string;
+  key?: string;
+} | {
+  kind: "jsonld";
+  id?: string;
+  graph: Record<string, unknown> | Array<Record<string, unknown>>;
+};
+type PageMetadataHandler = (event: PageMetadataEvent, ctx: PluginContext) => PageMetadataContribution | PageMetadataContribution[] | null | Promise<PageMetadataContribution | PageMetadataContribution[] | null>;
+interface PageFragmentEvent {
+  page: PublicPageContext;
+}
+type PageFragmentContribution = {
+  kind: "external-script";
+  placement: PagePlacement;
+  src: string;
+  async?: boolean;
+  defer?: boolean;
+  attributes?: Record<string, string>;
+  key?: string;
+} | {
+  kind: "inline-script";
+  placement: PagePlacement;
+  code: string;
+  attributes?: Record<string, string>;
+  key?: string;
+} | {
+  kind: "html";
+  placement: PagePlacement;
+  html: string;
+  key?: string;
+};
+type PageFragmentHandler = (event: PageFragmentEvent, ctx: PluginContext) => PageFragmentContribution | PageFragmentContribution[] | null | Promise<PageFragmentContribution | PageFragmentContribution[] | null>;
+/**
+ * Plugin hooks definition
+ */
+interface PluginHooks {
+  "plugin:install"?: HookConfig<LifecycleHandler> | LifecycleHandler;
+  "plugin:activate"?: HookConfig<LifecycleHandler> | LifecycleHandler;
+  "plugin:deactivate"?: HookConfig<LifecycleHandler> | LifecycleHandler;
+  "plugin:uninstall"?: HookConfig<UninstallHandler> | UninstallHandler;
+  "content:beforeSave"?: HookConfig<ContentBeforeSaveHandler> | ContentBeforeSaveHandler;
+  "content:afterSave"?: HookConfig<ContentAfterSaveHandler> | ContentAfterSaveHandler;
+  "content:beforeDelete"?: HookConfig<ContentBeforeDeleteHandler> | ContentBeforeDeleteHandler;
+  "content:afterDelete"?: HookConfig<ContentAfterDeleteHandler> | ContentAfterDeleteHandler;
+  "content:beforePublish"?: HookConfig<ContentBeforePublishHandler> | ContentBeforePublishHandler;
+  "content:beforeSchedule"?: HookConfig<ContentBeforeScheduleHandler> | ContentBeforeScheduleHandler;
+  "content:beforeUnpublish"?: HookConfig<ContentBeforeUnpublishHandler> | ContentBeforeUnpublishHandler;
+  "content:afterPublish"?: HookConfig<ContentAfterPublishHandler> | ContentAfterPublishHandler;
+  "content:afterUnpublish"?: HookConfig<ContentAfterUnpublishHandler> | ContentAfterUnpublishHandler;
+  "content:afterRestore"?: HookConfig<ContentAfterRestoreHandler> | ContentAfterRestoreHandler;
+  "content:afterSchedule"?: HookConfig<ContentAfterScheduleHandler> | ContentAfterScheduleHandler;
+  "content:afterUnschedule"?: HookConfig<ContentAfterUnscheduleHandler> | ContentAfterUnscheduleHandler;
+  "media:beforeUpload"?: HookConfig<MediaBeforeUploadHandler> | MediaBeforeUploadHandler;
+  "media:afterUpload"?: HookConfig<MediaAfterUploadHandler> | MediaAfterUploadHandler;
+  cron?: HookConfig<CronHandler> | CronHandler;
+  "email:beforeSend"?: HookConfig<EmailBeforeSendHandler> | EmailBeforeSendHandler;
+  "email:deliver"?: HookConfig<EmailDeliverHandler> | EmailDeliverHandler;
+  "email:afterSend"?: HookConfig<EmailAfterSendHandler> | EmailAfterSendHandler;
+  "comment:beforeCreate"?: HookConfig<CommentBeforeCreateHandler> | CommentBeforeCreateHandler;
+  "comment:moderate"?: HookConfig<CommentModerateHandler> | CommentModerateHandler;
+  "comment:afterCreate"?: HookConfig<CommentAfterCreateHandler> | CommentAfterCreateHandler;
+  "comment:afterModerate"?: HookConfig<CommentAfterModerateHandler> | CommentAfterModerateHandler;
+  "page:metadata"?: HookConfig<PageMetadataHandler> | PageMetadataHandler;
+  "page:fragments"?: HookConfig<PageFragmentHandler> | PageFragmentHandler;
+}
+/**
+ * Hook names
+ */
+/**
+ * Hook name in a manifest. Core's exhaustive union of recognised hook names,
+ * derived from the `PluginHooks` registry. The serialised manifest carries
+ * these as opaque strings; this stricter type is only used for type-checking
+ * inside core. `ManifestHookEntry` is re-exported from
+ * `@emdash-cms/plugin-types` near the top of this file.
+ */
+type HookName = keyof PluginHooks;
+/**
+ * Resolved hook with normalized config
+ */
+interface ResolvedHook<THandler> {
+  priority: number;
+  timeout: number;
+  dependencies: string[];
+  errorPolicy: "continue" | "abort";
+  /** Whether this hook is exclusive (provider pattern) */
+  exclusive: boolean;
+  handler: THandler;
+  pluginId: string;
+}
+/**
+ * Geographic location information derived from the request.
+ * Available when running on Cloudflare Workers (via the `cf` object).
+ */
+interface GeoInfo {
+  country: string | null;
+  region: string | null;
+  city: string | null;
+}
+/**
+ * Normalized request metadata available to plugin route handlers.
+ * Extracted from request headers and platform-specific properties.
+ */
+interface RequestMeta {
+  ip: string | null;
+  userAgent: string | null;
+  referer: string | null;
+  geo: GeoInfo | null;
+}
+/**
+ * Route handler context extends plugin context with request-specific data
+ */
+interface RouteContext<TInput = unknown> extends PluginContext {
+  /** Validated input from request body */
+  input: TInput;
+  /** Original request */
+  request: Request;
+  /** Normalized request metadata (IP, user agent, geo) */
+  requestMeta: RequestMeta;
+  /** Host-attested context for a validated Block Kit request. */
+  ui?: PluginUiContext;
+  /**
+   * Authenticated caller, if the route is private. The host has already
+   * authenticated and authorized this user before dispatch, so the value
+   * is trustworthy — unlike a user id read from the request body.
+   *
+   * `undefined` for public routes (which skip auth entirely) and for
+   * token-authed requests where no user is bound to the token.
+   *
+   * Not gated by the `users:read` capability: this is the caller's own
+   * identity for the current request, not a user directory lookup.
+   */
+  user?: UserInfo;
+}
+/**
+ * Route definition
+ */
+interface PluginRoute<TInput = unknown> extends Omit<RouteOptions, "request"> {
+  /** Zod schema for input validation */
+  input?: z.ZodType<TInput>;
+  /**
+   * Mark this route as publicly accessible (no authentication required).
+   * Public routes skip session/token auth and CSRF checks.
+   */
+  public?: boolean;
+  /** RBAC permission required to invoke the route. Legacy routes default to plugins:manage. */
+  permission?: Permission;
+  /**
+   * `Cache-Control` header value for successful GET responses, e.g.
+   * `"public, max-age=60, stale-while-revalidate=300"`. Only honored on
+   * routes that are also `public: true` — authenticated responses always
+   * keep the default `private, no-store`. Errors are never cached.
+   */
+  cacheControl?: string;
+  /** Bounded request parsing and incoming-header declaration. */
+  request?: PluginRouteRequest;
+  /** Route handler */
+  handler: {
+    bivarianceHack(ctx: RouteContext<TInput>): Promise<unknown>;
+  }["bivarianceHack"];
+}
+type PluginRouteInput<TMode extends PluginRouteBodyMode> = TMode extends "none" ? PluginRouteQuery : TMode extends "text" ? string : TMode extends "bytes" ? Uint8Array : TMode extends "form-data" ? PluginFormData : unknown;
+type PluginRouteDefinition<TMode extends PluginRouteBodyMode = PluginRouteBodyMode> = Omit<PluginRoute<PluginRouteInput<TMode>>, "request"> & {
+  request: PluginRouteRequest & {
+    body: TMode;
+  };
+};
+interface PluginMcpToolDefinition {
+  description: string;
+  route: string;
+  input: z.ZodType;
+  output?: z.ZodType;
+  destructive?: boolean;
+}
+interface PluginMcpConfig {
+  tools: Record<string, PluginMcpToolDefinition>;
+}
+/**
+ * Admin page definition
+ */
+interface PluginAdminPage {
+  path: string;
+  label: string;
+  icon?: string;
+}
+/**
+ * Dashboard widget definition
+ */
+interface PluginDashboardWidget {
+  id: string;
+  size?: "full" | "half" | "third";
+  title?: string;
+}
+interface PluginEditorPanel {
+  id: string;
+  title: string;
+  route: string;
+  collections?: string[];
+  order?: number;
+  draft?: PluginEditorDraftAccess;
+}
+interface PluginEditorAction {
+  id: string;
+  label: string;
+  route: string;
+  placement: "toolbar" | "overflow";
+  collections?: string[];
+  style?: "default" | "danger";
+  confirm?: ConfirmDialog;
+  draft?: PluginEditorDraftAccess;
+}
+/**
+ * Settings field types (for admin UI generation)
+ */
+type SettingFieldType = "string" | "number" | "boolean" | "select" | "secret" | "url" | "email";
+interface BaseSettingField {
+  type: SettingFieldType;
+  label: string;
+  description?: string;
+}
+interface StringSettingField extends BaseSettingField {
+  type: "string";
+  default?: string;
+  multiline?: boolean;
+}
+interface NumberSettingField extends BaseSettingField {
+  type: "number";
+  default?: number;
+  min?: number;
+  max?: number;
+}
+interface BooleanSettingField extends BaseSettingField {
+  type: "boolean";
+  default?: boolean;
+}
+interface SelectSettingField extends BaseSettingField {
+  type: "select";
+  options: Array<{
+    value: string;
+    label: string;
+  }>;
+  default?: string;
+}
+interface SecretSettingField extends BaseSettingField {
+  type: "secret";
+}
+interface UrlSettingField extends BaseSettingField {
+  type: "url";
+  default?: string;
+  placeholder?: string;
+}
+interface EmailSettingField extends BaseSettingField {
+  type: "email";
+  default?: string;
+  placeholder?: string;
+}
+type SettingField = StringSettingField | NumberSettingField | BooleanSettingField | SelectSettingField | SecretSettingField | UrlSettingField | EmailSettingField;
+/**
+ * Block Kit element for block editing fields.
+ * This is the `Element` discriminated union from `@emdash-cms/blocks`.
+ * Plugin authors should use `@emdash-cms/blocks` builder functions to create these.
+ */
+type PortableTextBlockField = Element;
+/**
+ * Configuration for a Portable Text block type contributed by a plugin
+ */
+interface PortableTextBlockConfig {
+  /** Block type name (must match the `_type` in Portable Text) */
+  type: string;
+  /** Human-readable label shown in slash commands and modals */
+  label: string;
+  /** Icon key (e.g., "video", "code", "link", "link-external") */
+  icon?: string;
+  /** Description shown in slash command menu */
+  description?: string;
+  /** Placeholder text for the URL input */
+  placeholder?: string;
+  /** Block Kit form fields for the editing UI. If declared, replaces the simple URL input. */
+  fields?: PortableTextBlockField[];
+  /**
+   * Optional. Display category in the slash menu. Defaults to "Embeds".
+   *
+   * Plugin authors should pick a meaningful category that reflects what the
+   * block actually is — e.g. "Sections", "Marketing", "Media", "Embeds",
+   * "Layout". Blocks with the same category are grouped together in the
+   * editor's slash menu.
+   */
+  category?: string;
+}
+/**
+ * Configuration for a field widget type contributed by a plugin.
+ * A field widget provides a custom editing UI for a schema field.
+ * The field references the widget via `widget: "pluginId:widgetName"`.
+ */
+interface FieldWidgetConfig {
+  /** Widget name (without plugin ID prefix) */
+  name: string;
+  /** Human-readable label for the admin UI */
+  label: string;
+  /** Which field types this widget can edit (e.g., ["json", "string"]) */
+  fieldTypes: FieldType[];
+  /** Block Kit elements for sandboxed rendering. Omit for trusted plugins using React. */
+  elements?: Element[];
+}
+/**
+ * Admin configuration
+ */
+interface PluginAdminConfig {
+  /** Module specifier for admin UI exports (e.g., "@emdash-cms/plugin-audit-log/admin") */
+  entry?: string;
+  /** Settings schema for auto-generated UI */
+  settingsSchema?: Record<string, SettingField>;
+  /** Admin pages */
+  pages?: PluginAdminPage[];
+  /** Dashboard widgets */
+  widgets?: PluginDashboardWidget[];
+  /** Saved-entry Block Kit panels. */
+  editorPanels?: PluginEditorPanel[];
+  /** Saved-entry host-rendered actions. */
+  editorActions?: PluginEditorAction[];
+  /** Portable Text block types this plugin provides */
+  portableTextBlocks?: PortableTextBlockConfig[];
+  /** Field widget types this plugin provides */
+  fieldWidgets?: FieldWidgetConfig[];
+}
+/**
+ * Plugin definition - input to definePlugin()
+ */
+interface PluginDefinition<TStorage extends PluginStorageConfig = PluginStorageConfig> {
+  /** Unique plugin identifier */
+  id: string;
+  /** Plugin version (semver) */
+  version: string;
+  /** Declared capabilities */
+  capabilities?: PluginCapability[];
+  /** Allowed hosts for network:request (wildcards supported: *.example.com) */
+  allowedHosts?: string[];
+  /** Storage collections with indexes */
+  storage?: TStorage;
+  /** Hooks */
+  hooks?: PluginHooks;
+  /** API routes */
+  routes?: Record<string, PluginRoute>;
+  /** Routes explicitly exposed as agent-callable MCP tools. */
+  mcp?: PluginMcpConfig;
+  /** Admin UI configuration */
+  admin?: PluginAdminConfig;
+}
+/**
+ * Resolved plugin - after definePlugin() processing
+ */
+interface ResolvedPlugin<TStorage extends PluginStorageConfig = PluginStorageConfig> {
+  id: string;
+  version: string;
+  capabilities: PluginCapability[];
+  allowedHosts: string[];
+  storage: TStorage;
+  hooks: ResolvedPluginHooks;
+  routes: Record<string, PluginRoute>;
+  mcp?: PluginMcpConfig;
+  admin: PluginAdminConfig;
+}
+/**
+ * Resolved hooks with normalized config
+ */
+interface ResolvedPluginHooks {
+  "plugin:install"?: ResolvedHook<LifecycleHandler>;
+  "plugin:activate"?: ResolvedHook<LifecycleHandler>;
+  "plugin:deactivate"?: ResolvedHook<LifecycleHandler>;
+  "plugin:uninstall"?: ResolvedHook<UninstallHandler>;
+  "content:beforeSave"?: ResolvedHook<ContentBeforeSaveHandler>;
+  "content:afterSave"?: ResolvedHook<ContentAfterSaveHandler>;
+  "content:beforeDelete"?: ResolvedHook<ContentBeforeDeleteHandler>;
+  "content:afterDelete"?: ResolvedHook<ContentAfterDeleteHandler>;
+  "content:beforePublish"?: ResolvedHook<ContentBeforePublishHandler>;
+  "content:beforeSchedule"?: ResolvedHook<ContentBeforeScheduleHandler>;
+  "content:beforeUnpublish"?: ResolvedHook<ContentBeforeUnpublishHandler>;
+  "content:afterPublish"?: ResolvedHook<ContentAfterPublishHandler>;
+  "content:afterUnpublish"?: ResolvedHook<ContentAfterUnpublishHandler>;
+  "content:afterRestore"?: ResolvedHook<ContentAfterRestoreHandler>;
+  "content:afterSchedule"?: ResolvedHook<ContentAfterScheduleHandler>;
+  "content:afterUnschedule"?: ResolvedHook<ContentAfterUnscheduleHandler>;
+  "media:beforeUpload"?: ResolvedHook<MediaBeforeUploadHandler>;
+  "media:afterUpload"?: ResolvedHook<MediaAfterUploadHandler>;
+  cron?: ResolvedHook<CronHandler>;
+  "email:beforeSend"?: ResolvedHook<EmailBeforeSendHandler>;
+  "email:deliver"?: ResolvedHook<EmailDeliverHandler>;
+  "email:afterSend"?: ResolvedHook<EmailAfterSendHandler>;
+  "comment:beforeCreate"?: ResolvedHook<CommentBeforeCreateHandler>;
+  "comment:moderate"?: ResolvedHook<CommentModerateHandler>;
+  "comment:afterCreate"?: ResolvedHook<CommentAfterCreateHandler>;
+  "comment:afterModerate"?: ResolvedHook<CommentAfterModerateHandler>;
+  "page:metadata"?: ResolvedHook<PageMetadataHandler>;
+  "page:fragments"?: ResolvedHook<PageFragmentHandler>;
+}
+/**
+ * What a plugin exports from its /admin entrypoint
+ * Uses generic component type to avoid React dependency
+ */
+interface PluginAdminExports {
+  widgets?: Record<string, JSX.Element>;
+  pages?: Record<string, JSX.Element>;
+  fields?: Record<string, JSX.Element>;
+}
+/**
+ * Plugin manifest — the metadata portion of a plugin bundle, used for
+ * sandboxed plugins loaded from the marketplace.
+ *
+ * This interface is core's stricter version of the manifest contract: it
+ * uses the exhaustive `HookName` union and core's typed `PluginAdminConfig`.
+ * The wire-shape lives in `@emdash-cms/plugin-types` as `PluginManifest`
+ * with looser types (so the registry CLI can serialise hook names it
+ * doesn't know about). Both must stay structurally compatible: every value
+ * of this type must be assignable to the shared one. The static assertion
+ * below catches any drift at compile time.
+ */
+interface PluginManifest {
+  id: string;
+  version: string;
+  /**
+   * The trust contract (see `@emdash-cms/plugin-types`). Authoritative;
+   * `capabilities`/`allowedHosts` are derived from it at the parse boundary
+   * via `reconcileManifestAccess`. Optional during the wire-format migration.
+   */
+  declaredAccess?: DeclaredAccess;
+  capabilities: PluginCapability[];
+  allowedHosts: string[];
+  storage: PluginStorageConfig;
+  /** Hook declarations — either plain name strings or structured objects */
+  hooks: Array<ManifestHookEntry$1 | HookName>;
+  /** Route declarations — either plain name strings or structured objects */
+  routes: Array<ManifestRouteEntry$1 | string>;
+  mcp?: PluginMcpManifestConfig;
+  admin: PluginAdminConfig;
+}
+//#endregion
+export { CurrentPluginCapability as $, PluginStorageConfig as $t, ContentBeforePublishHandler as A, UninstallHandler as An, PageMetadataContribution as At, ContentPolicyEvent as B, normalizeCapability as Bn, PluginComment as Bt, ContentAfterPublishHandler as C, TaxonomyAccess as Cn, MediaMetadataPatch as Ct, ContentAfterUnpublishHandler as D, TaxonomyTermCreateInput as Dn, PageFragmentContribution as Dt, ContentAfterScheduleHandler as E, TaxonomyReadOptions as En, NumericDelta as Et, ContentDeleteEvent as F, VersionedRedirect as Fn, PaginatedResult as Ft, ContentScheduleStateChangeEvent as G, PluginEditorAction as Gt, ContentRestoreStateChangeEvent as H, PluginContentCreateCallback as Ht, ContentHookEvent as I, VersionedValue as In, PluginAdminConfig as It, ContentWriteInput as J, PluginHooks as Jt, ContentStateChangeEvent as K, PluginEditorDraftFieldSelector as Kt, ContentItem as L, WhereClause as Ln, PluginAdminExports as Lt, ContentBeforeScheduleHandler as M, UpdateIfResult as Mn, PageMetadataHandler as Mt, ContentBeforeUnpublishHandler as N, UserInfo as Nn, PageMetadataLinkRel as Nt, ContentAfterUnscheduleHandler as O, TaxonomyTermInfo as On, PageFragmentEvent as Ot, ContentCreateOptions as P, VersionedContentItem as Pn, PagePlacement as Pt, CronTaskInfo as Q, PluginRouteDefinition as Qt, ContentListOptions as R, isDeprecatedCapability as Rn, PluginAdminPage as Rt, ContentAfterDeleteHandler as S, StoredComment as Sn, MediaItem as St, ContentAfterSaveHandler as T, TaxonomyDefInfo as Tn, ModerationDecision as Tt, ContentRevisionInfo as U, PluginContext as Ut, ContentPublishStateChangeEvent as V, normalizePluginCapabilities as Vn, PluginCommentStatus as Vt, ContentSchedulePolicyEvent as W, PluginDefinition as Wt, CronEvent as X, PluginMcpManifestConfig as Xt, CronAccess as Y, PluginManifest as Yt, CronHandler as Z, PluginRoute as Zt, ConditionalDeleteResult as _, SettingField as _n, MediaAccess as _t, CollectionSchemaInfo as a, RedirectAccessWithWrite as an, EmailDeliverEvent as at, ContentAccessWithWrite as b, StorageCollection as bn, MediaBeforeUploadHandler as bt, CommentAfterCreateHandler as c, RedirectListOptions as cn, FieldSchemaInfo as ct, CommentBeforeCreateEvent as d, RequestMeta as dn, HookName as dt, PortableTextBlockConfig as en, DeprecatedPluginCapability as et, CommentBeforeCreateHandler as f, ResolvedHook as fn, HttpAccess as ft, CommentModerateHandler as g, SchemaAccess as gn, LogAccess as gt, CommentModerateEvent as h, RouteContext as hn, LifecycleHandler as ht, CollectionCommentSettings as i, RedirectAccess as in, EmailBeforeSendHandler as it, ContentBeforeSaveHandler as j, UpdateIfArgs as jn, PageMetadataEvent as jt, ContentBeforeDeleteHandler as k, UninstallEvent as kn, PageFragmentHandler as kt, CommentAfterModerateEvent as l, RedirectStatus as ln, FieldWidgetConfig as lt, CommentListOptions as m, ResolvedPluginHooks as mn, LifecycleEvent as mt, BreadcrumbItem as n, PublicPageContext as nn, EmailAfterSendHandler as nt, CommentAccess as o, RedirectCreateInput as on, EmailDeliverHandler as ot, CommentCountOptions as p, ResolvedPlugin as pn, KVAccess as pt, ContentTranslationSummary as q, PluginEditorPanel as qt, CAPABILITY_RENAMES as r, QueryOptions as rn, EmailBeforeSendEvent as rt, CommentAfterCreateEvent as s, RedirectInfo as sn, EmailMessage as st, ActorInfo as t, PortableTextBlockField as tn, EmailAfterSendEvent as tt, CommentAfterModerateHandler as u, RedirectUpdateInput as un, HookConfig as ut, ConditionalWriteResult as v, SettingsAccess as vn, MediaAfterUploadEvent as vt, ContentAfterRestoreHandler as w, TaxonomyAccessWithWrite as wn, MediaUploadEvent as wt, ContentActionOrigin as x, StorageCollectionConfig as xn, MediaBytes as xt, ContentAccess as y, SiteInfo as yn, MediaAfterUploadHandler as yt, ContentPolicyDecision as z, normalizeCapabilities as zn, PluginCapability as zt };
+//# sourceMappingURL=types-D0aJW2uR.d.mts.map