emdash 1.0.0 → 1.0.1-rc.0

package/src/astro/integration/runtime.ts

@@ -7,12 +7,27 @@
  * DO NOT import Node.js-only modules here (fs, path, module, etc.)
  */
 
+import type { ManifestHookEntry, ManifestRouteEntry } from "@emdash-cms/plugin-types";
+
 import type { AuthDescriptor, AuthProviderDescriptor } from "../../auth/types.js";
+import type { RuntimeMigrationConfig } from "../../database/migrations/policy.js";
 import type { DatabaseDescriptor } from "../../db/adapters.js";
 import type { MediaProviderDescriptor } from "../../media/types.js";
-import type { ResolvedPlugin } from "../../plugins/types.js";
+import type { ObjectCacheDescriptor } from "../../object-cache/types.js";
+import type {
+	FieldWidgetConfig,
+	PluginEditorAction,
+	PluginEditorPanel,
+	PluginMcpManifestConfig,
+	PortableTextBlockConfig,
+	ResolvedPlugin,
+	SettingField,
+} from "../../plugins/types.js";
+import type { RegistryConfigOption } from "../../registry/types.js";
 import type { StorageDescriptor } from "../storage/types.js";
 
+export type { RegistryConfig, RegistryConfigOption } from "../../registry/types.js";
+
 export type { ResolvedPlugin };
 export type { MediaProviderDescriptor };
 
@@ -62,7 +77,7 @@ export interface StorageCollectionDeclaration {
 	uniqueIndexes?: string[];
 }
 
-export interface PluginDescriptor<TOptions = Record<string, unknown>> {
+export interface PluginDescriptor<TOptions extends object = object> {
 	/** Unique plugin identifier */
 	id: string;
 	/** Plugin version (semver) */
@@ -95,6 +110,21 @@ export interface PluginDescriptor<TOptions = Record<string, unknown>> {
 	adminPages?: PluginAdminPage[];
 	/** Dashboard widgets */
 	adminWidgets?: PluginDashboardWidget[];
+	/** Saved-entry Block Kit panels. */
+	editorPanels?: PluginEditorPanel[];
+	/** Saved-entry host-rendered actions. */
+	editorActions?: PluginEditorAction[];
+	/** Settings schema for the auto-generated admin settings form */
+	settingsSchema?: Record<string, SettingField>;
+	/**
+	 * Portable Text block types this plugin contributes to the editor.
+	 * Declarative (Block Kit) — surfaced in the admin slash menu and consumed
+	 * from the manifest, so standard/sandboxed plugins can contribute blocks
+	 * without a native render component.
+	 */
+	portableTextBlocks?: PortableTextBlockConfig[];
+	/** Field widget types this plugin contributes for schema-field editing UIs. */
+	fieldWidgets?: FieldWidgetConfig[];
 
 	// === Sandbox-specific fields (for sandboxed plugins) ===
 
@@ -114,6 +144,19 @@ export interface PluginDescriptor<TOptions = Record<string, unknown>> {
 	 * Sandboxed plugins can only access declared collections.
 	 */
 	storage?: Record<string, StorageCollectionDeclaration>;
+	/** Serialized MCP declarations emitted by the plugin build. */
+	mcp?: PluginMcpManifestConfig;
+	/**
+	 * Route declarations for sandboxed config-declared plugins. Mirrors
+	 * definePlugin({ routes }) and drives route auth decisions; omitted routes
+	 * default to non-public.
+	 */
+	routes?: Array<ManifestRouteEntry | string>;
+	/**
+	 * Hook declarations for sandboxed config-declared plugins. Mirrors
+	 * definePlugin({ hooks }).
+	 */
+	hooks?: Array<ManifestHookEntry | string>;
 }
 
 /**
@@ -122,7 +165,7 @@ export interface PluginDescriptor<TOptions = Record<string, unknown>> {
  * These run in isolated V8 isolates via Worker Loader on Cloudflare.
  * The `entrypoint` is resolved to a file and bundled at build time.
  */
-export type SandboxedPluginDescriptor<TOptions = Record<string, unknown>> =
+export type SandboxedPluginDescriptor<TOptions extends object = object> =
 	PluginDescriptor<TOptions>;
 
 export interface EmDashConfig {
@@ -144,23 +187,74 @@ export interface EmDashConfig {
 	 * ```
 	 */
 	database?: DatabaseDescriptor;
+	/** Core database migration behavior at runtime. Defaults to `auto`. */
+	migrations?: RuntimeMigrationConfig;
 	/**
 	 * Storage configuration (for media)
 	 */
 	storage?: StorageDescriptor;
+
+	/**
+	 * Optional distributed object cache for query results.
+	 *
+	 * Off by default. When configured, content and chrome (settings, menus,
+	 * taxonomies) reads are cached in a fast key/value store and served without
+	 * touching the database on repeat requests across isolates. This offloads
+	 * read pressure from D1/SQLite, which is especially valuable on Cloudflare
+	 * where D1 has far lower request capacity than KV.
+	 *
+	 * Use a backend adapter:
+	 * - `memoryCache()` from `emdash/astro` — in-isolate (Node / local dev)
+	 * - `kvCache({ binding: "CACHE" })` from `@emdash-cms/cloudflare` — KV
+	 *
+	 * Preview and visual-edit requests bypass the cache, so editors previewing
+	 * see live content. All other reads — including authenticated browsing outside
+	 * edit mode — are served from the cache, which only ever stores published
+	 * content. When Astro route caching is enabled, a rendered cache fill bypasses
+	 * the object cache so a purged page cannot be rebuilt from an older snapshot.
+	 * Other requests may see stale content until isolates pick up the bumped epoch:
+	 * immediate with the memory backend, and on KV bounded by KV's edge-cache
+	 * propagation (eventual consistency, up to ~60s) plus the isolate-local
+	 * `revalidate` window (default 1s).
+	 *
+	 * Scheduled content becomes visible at query time (no write event fires when
+	 * its publish time passes), so a cached list/entry won't surface a newly-due
+	 * scheduled item until the next write to that collection or until the
+	 * entry's TTL lapses (`defaultTtl`, default 1h). Sites that rely on precise
+	 * scheduled publishing should lower `defaultTtl` accordingly.
+	 *
+	 * @example
+	 * ```ts
+	 * import { kvCache } from "@emdash-cms/cloudflare";
+	 *
+	 * emdash({
+	 *   database: d1({ binding: "DB" }),
+	 *   objectCache: kvCache({ binding: "CACHE" }),
+	 * })
+	 * ```
+	 */
+	objectCache?: ObjectCacheDescriptor;
+	/**
+	 * Image optimization.
+	 *
+	 * By default EmDash wraps Astro's image endpoint so media served from
+	 * storage is optimized through the normal `<Image>` / `getImage` pipeline,
+	 * loading source bytes directly from the storage adapter (works behind
+	 * Cloudflare Access). Set to `false` to leave Astro's image endpoint
+	 * untouched -- media then renders as a plain `<img>` unless your image
+	 * service can fetch it over HTTP.
+	 */
+	images?: boolean;
 	/**
 	 * Trusted plugins to load (run in main isolate)
 	 *
 	 * @example
 	 * ```ts
-	 * import { auditLogPlugin } from "@emdash-cms/plugin-audit-log";
-	 * import { webhookNotifierPlugin } from "@emdash-cms/plugin-webhook-notifier";
+	 * import auditLog from "@emdash-cms/plugin-audit-log";
+	 * import webhookNotifier from "@emdash-cms/plugin-webhook-notifier";
 	 *
 	 * emdash({
-	 *   plugins: [
-	 *     auditLogPlugin(),
-	 *     webhookNotifierPlugin({ url: "https://example.com/webhook" }),
-	 *   ],
+	 *   plugins: [auditLog, webhookNotifier],
 	 * })
 	 * ```
 	 */
@@ -173,12 +267,13 @@ export interface EmDashConfig {
 	 *
 	 * @example
 	 * ```ts
+	 * import { sandbox } from "@emdash-cms/cloudflare";
 	 * import { untrustedPlugin } from "some-third-party-plugin";
 	 *
 	 * emdash({
 	 *   plugins: [trustedPlugin()],     // runs in host
 	 *   sandboxed: [untrustedPlugin()], // runs in isolate
-	 *   sandboxRunner: "@emdash-cms/sandbox-cloudflare",
+	 *   sandboxRunner: sandbox(),
 	 * })
 	 * ```
 	 */
@@ -189,13 +284,26 @@ export interface EmDashConfig {
 	 *
 	 * @example
 	 * ```ts
+	 * import { sandbox } from "@emdash-cms/cloudflare";
+	 *
 	 * emdash({
-	 *   sandboxRunner: "@emdash-cms/sandbox-cloudflare",
+	 *   sandboxRunner: sandbox(),
 	 * })
 	 * ```
 	 */
 	sandboxRunner?: string;
 
+	/**
+	 * Explicitly disable plugin sandboxing, even if a sandbox runner is configured.
+	 * Use this as a debugging escape hatch to determine whether a bug is in your
+	 * plugin code or in the sandbox runtime.
+	 *
+	 * When set to `false`, all plugins run in-process without isolation.
+	 *
+	 * @default true (sandboxing enabled if sandboxRunner is configured)
+	 */
+	sandbox?: boolean;
+
 	/**
 	 * Authentication configuration
 	 *
@@ -258,22 +366,62 @@ export interface EmDashConfig {
 	/**
 	 * Plugin marketplace URL
 	 *
-	 * When set, enables the marketplace features: browse, install, update,
-	 * and uninstall plugins from a remote marketplace.
+	 * Existing marketplace-installed plugins use this URL for updates.
+	 * Marketplace browsing and new installs are no longer shown in the admin.
 	 *
 	 * Must be an HTTPS URL in production, or localhost/127.0.0.1 in dev.
-	 * Requires `sandboxRunner` to be configured (marketplace plugins run sandboxed).
+	 * Installing or updating plugins requires an available `sandboxRunner`.
+	 * Existing marketplace-installed plugins remain updateable and uninstallable.
+	 * New plugin discovery and installs use the registry.
 	 *
 	 * @example
 	 * ```ts
+	 * import { sandbox } from "@emdash-cms/cloudflare";
+	 *
 	 * emdash({
 	 *   marketplace: "https://marketplace.emdashcms.com",
-	 *   sandboxRunner: "@emdash-cms/sandbox-cloudflare",
+	 *   sandboxRunner: sandbox(),
 	 * })
 	 * ```
+	 *
+	 * @deprecated Keep this option only while the site has plugins installed from
+	 * the legacy marketplace. Remove it after those plugins are replaced or
+	 * uninstalled.
 	 */
 	marketplace?: string;
 
+	/**
+	 * Plugin registry discovery and installation.
+	 *
+	 * An enabled sandbox runner uses the hosted registry by default. Pass a
+	 * registry URL or configuration object to customize it, or `false` to
+	 * disable registry discovery while retaining the sandbox runner.
+	 *
+	 * @default "https://registry.emdashcms.com" when sandboxing is enabled
+	 */
+	registry?: RegistryConfigOption;
+
+	/**
+	 * Core update notice in the admin dashboard.
+	 *
+	 * When enabled (the default), EmDash checks the public npm registry
+	 * (`registry.npmjs.org`) at most once per day for published `emdash`
+	 * releases and shows a dismissible banner in the admin dashboard when
+	 * a newer version is available. The check is deferred after the
+	 * response and carries no site data — it's a plain GET to the public
+	 * registry. Sites without outbound internet simply never see the banner.
+	 *
+	 * The banner names the newest stable release that has been public for
+	 * `minimumReleaseAge`: a duration string (`"48h"`, `"7d"`) or a number
+	 * of seconds, `"24h"` by default. Set it to match a package manager's
+	 * release-age policy, such as pnpm's `minimumReleaseAge`.
+	 *
+	 * Set to `false` to disable the check entirely.
+	 *
+	 * @default true
+	 */
+	updateCheck?: boolean | { minimumReleaseAge?: string | number };
+
 	/**
 	 * Maximum allowed media file upload size in bytes.
 	 *
@@ -303,6 +451,36 @@ export interface EmDashConfig {
 	siteUrl?: string;
 
 	/**
+	 * Additional origins accepted by passkey verification.
+	 *
+	 * When the same EmDash deployment is reachable under several hostnames sharing
+	 * a registrable parent (e.g. `https://example.com` plus
+	 * `https://preview.example.com`), the canonical `siteUrl` defines the `rpId`
+	 * and the entries here are the *additional* origins from which assertions
+	 * are accepted. Each entry must be the same hostname as `siteUrl` or a
+	 * subdomain of it — WebAuthn requires `rpId` to be a registrable suffix of
+	 * every origin.
+	 *
+	 * Merged at runtime with the `EMDASH_ALLOWED_ORIGINS` env var (comma-separated).
+	 * Validation:
+	 *   - Config-declared entries are shape-checked at Astro startup.
+	 *   - Subdomain relationship to `siteUrl` is checked at startup when
+	 *     `siteUrl` is also config-declared, otherwise at first passkey
+	 *     verification (since `siteUrl` may come from `EMDASH_SITE_URL`).
+	 *
+	 * Mismatches throw with a source-attributed message naming
+	 * `config.allowedOrigins` or `EMDASH_ALLOWED_ORIGINS`.
+	 *
+	 * @example
+	 * ```ts
+	 * emdash({
+	 *   siteUrl: "https://example.com",
+	 *   allowedOrigins: ["https://preview.example.com"],
+	 * })
+	 * ```
+	 */
+	allowedOrigins?: string[];
+	/*
 	 * Headers to trust for client IP resolution when running behind a reverse
 	 * proxy. The first header in this list that is present on the request
 	 * wins. Applies to rate limiting for auth endpoints and comment
@@ -328,6 +506,21 @@ export interface EmDashConfig {
 	 */
 	trustedProxyHeaders?: string[];
 
+	/**
+	 * User middleware that wraps the complete EmDash request pipeline.
+	 *
+	 * Before `next()` it runs before EmDash initializes its runtime or database,
+	 * so `locals.emdash`, the authenticated user, and request-scoped EmDash state
+	 * are unavailable. This allows cached responses and request gates to return
+	 * without paying initialization cost. When it calls `next()`, the resolved
+	 * response includes EmDash HTML injection and all other response mutations,
+	 * allowing the middleware to finalize caching and response headers safely.
+	 */
+	middleware?: {
+		/** Astro middleware module entrypoint. */
+		outer: string | URL;
+	};
+
 	/**
 	 * Enable playground mode for ephemeral "try EmDash" sites.
 	 *
@@ -444,6 +637,7 @@ export interface EmDashConfig {
 	 *   admin: {
 	 *     logo: "/images/agency-logo.webp",
 	 *     siteName: "AgencyX CMS",
+	 *     footerLabel: "AgencyX",
 	 *     favicon: "/favicon.ico",
 	 *   },
 	 * })
@@ -452,19 +646,57 @@ export interface EmDashConfig {
 	admin?: {
 		/** URL or path to a custom logo image for the admin UI (login page, sidebar). */
 		logo?: string;
-		/** Custom name displayed in the admin sidebar and browser tab. */
+		/** Custom name displayed in the admin sidebar header and browser tab. */
 		siteName?: string;
+		/** Label displayed beside the version in the sidebar footer. Set to false to hide it. */
+		footerLabel?: string | false;
 		/** URL or path to a custom favicon for the admin panel. */
 		favicon?: string;
 	};
+
+	/**
+	 * Editor toolbar delivery on public pages.
+	 *
+	 * - `"server"` (default): the toolbar is injected server-side into every
+	 *   HTML response rendered for an authenticated editor. Simple and
+	 *   zero-config, but behind a shared cache (Cloudflare Cache Everything /
+	 *   Workers Cache, Fastly, Varnish, …) editors often receive the cached
+	 *   anonymous variant — without the toolbar — whenever an anonymous visitor
+	 *   primed the cache first, so the toolbar appears and disappears with
+	 *   cache state.
+	 * - `"client"`: public HTML is identical for everyone (nothing
+	 *   session-specific is injected server-side, so shared caches stay fully
+	 *   effective). A tiny bootstrap script shows an "Edit" pill for browsers
+	 *   that have logged into the admin (non-secret localStorage flag). Clicking
+	 *   it verifies the session and reloads the page with an `_edit` query
+	 *   param, which is always rendered fresh (never cached) with the full
+	 *   toolbar. Logged-out visitors opening an `_edit` URL are redirected to
+	 *   the canonical URL.
+	 * - `false`: never render the toolbar or bootstrap script.
+	 *
+	 * See the visual-editing docs for the cache-behavior details.
+	 */
+	toolbar?: "server" | "client" | false;
+
+	/**
+	 * Version of Astro the host project is building with. Populated by the
+	 * integration's `astro:config:setup` hook (not authored by the user) and
+	 * surfaced to the admin and the registry install gate so a plugin's
+	 * `env:astro` requirement can be evaluated against the real host version.
+	 */
+	astroVersion?: string;
 }
 
+const STORED_CONFIG_KEY = Symbol.for("emdash:stored-config");
+const configHolder = globalThis as Record<symbol, unknown>;
+
 /**
  * Get stored config from global
  * This is set by the virtual module at build time
  */
 export function getStoredConfig(): EmDashConfig | null {
-	return globalThis.__emdashConfig || null;
+	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- globalThis singleton pattern (see request-context.ts)
+	return (configHolder[STORED_CONFIG_KEY] as EmDashConfig | undefined) ?? null;
 }
 
 /**
@@ -472,11 +704,5 @@ export function getStoredConfig(): EmDashConfig | null {
  * Called by the integration at config time
  */
 export function setStoredConfig(config: EmDashConfig): void {
-	globalThis.__emdashConfig = config;
-}
-
-// Declare global type
-declare global {
-	// eslint-disable-next-line no-var
-	var __emdashConfig: EmDashConfig | undefined;
+	configHolder[STORED_CONFIG_KEY] = config;
 }

package/src/astro/integration/shims/use-sync-external-store-with-selector.js

@@ -0,0 +1,71 @@
+import * as React from "react";
+
+const objectIs =
+	typeof Object.is === "function"
+		? Object.is
+		: (x, y) => (x === y && (x !== 0 || 1 / x === 1 / y)) || (x !== x && y !== y);
+
+export function useSyncExternalStoreWithSelector(
+	subscribe,
+	getSnapshot,
+	getServerSnapshot,
+	selector,
+	isEqual,
+) {
+	const instRef = React.useRef(null);
+	if (instRef.current === null) {
+		instRef.current = { hasValue: false, value: null };
+	}
+	const inst = instRef.current;
+
+	const [getSelection, getServerSelection] = React.useMemo(() => {
+		let hasMemo = false;
+		let memoizedSnapshot;
+		let memoizedSelection;
+
+		const memoizedSelector = (nextSnapshot) => {
+			if (!hasMemo) {
+				hasMemo = true;
+				memoizedSnapshot = nextSnapshot;
+				const nextSelection = selector(nextSnapshot);
+				if (isEqual !== undefined && inst.hasValue) {
+					const currentSelection = inst.value;
+					if (isEqual(currentSelection, nextSelection)) {
+						memoizedSelection = currentSelection;
+						return currentSelection;
+					}
+				}
+				memoizedSelection = nextSelection;
+				return nextSelection;
+			}
+
+			const previousSelection = memoizedSelection;
+			if (objectIs(memoizedSnapshot, nextSnapshot)) {
+				return previousSelection;
+			}
+
+			const nextSelection = selector(nextSnapshot);
+			if (isEqual !== undefined && isEqual(previousSelection, nextSelection)) {
+				memoizedSnapshot = nextSnapshot;
+				return previousSelection;
+			}
+
+			memoizedSnapshot = nextSnapshot;
+			memoizedSelection = nextSelection;
+			return nextSelection;
+		};
+
+		return [
+			() => memoizedSelector(getSnapshot()),
+			getServerSnapshot === undefined ? undefined : () => memoizedSelector(getServerSnapshot()),
+		];
+	}, [getSnapshot, getServerSnapshot, selector, isEqual]);
+
+	const value = React.useSyncExternalStore(subscribe, getSelection, getServerSelection);
+	React.useEffect(() => {
+		inst.hasValue = true;
+		inst.value = value;
+	}, [inst, value]);
+	React.useDebugValue(value);
+	return value;
+}

package/src/astro/integration/shims/use-sync-external-store.js

@@ -0,0 +1 @@
+export { useSyncExternalStore } from "react";