emdash 0.28.1 → 0.30.0

package/src/astro/middleware/request-context.ts

@@ -8,37 +8,123 @@
  * - Preview tokens: _preview query param with signed HMAC token
  * - Edit mode: emdash-edit-mode cookie (for visual editing)
  * - Toolbar injection: floating pill for authenticated editors
+ * - Client toolbar mode (`toolbar: "client"`): cache-identical HTML with a
+ *   client-side bootstrap pill and an `_edit` query param for fresh editor
+ *   renders (Discussion #1742)
  */
 
+import type { APIContext } from "astro";
 import { defineMiddleware } from "astro:middleware";
+// @ts-ignore - virtual module
+import virtualConfig from "virtual:emdash/config";
 
 import { resolveSecretsCached } from "#config/secrets.js";
 
 import { verifyPreviewToken, parseContentId } from "../../preview/tokens.js";
 import { getRequestContext, runWithContext } from "../../request-context.js";
+import { EDIT_PARAM, renderToolbarBootstrap } from "../../visual-editing/toolbar-bootstrap.js";
 import { renderToolbar } from "../../visual-editing/toolbar.js";
 
+type ToolbarMode = "server" | "client" | false;
+
+const toolbarMode: ToolbarMode = virtualConfig?.toolbar ?? "server";
+
+/** Astro's route-cache handle. EmDash requires Astro 6+, so it's always present. */
+type RouteCache = APIContext["cache"];
+
 /**
- * Inject toolbar HTML into a response if it's an HTML page.
- * Returns the original response if not HTML.
+ * Opt the current request out of Astro's route cache (e.g. Workers Cache on
+ * Cloudflare). `Cache-Control` headers do NOT cover this: the adapter derives
+ * the shared-cache TTL from the route-cache options (on Cloudflare via
+ * `Cloudflare-CDN-Cache-Control`), so session-specific responses must
+ * explicitly disable it or they get stored in the shared cache and served to
+ * anonymous visitors without ever invoking the middleware again. With no cache
+ * provider configured this is a no-op (`NoopAstroCache`/`DisabledAstroCache`).
  */
-async function injectToolbar(response: Response, toolbarHtml: string): Promise<Response> {
+function optOutOfRouteCache(cache: RouteCache): void {
+	cache.set(false);
+}
+
+/**
+ * Inject HTML before `</body>` if the response is an HTML page with a body
+ * end tag. Does not touch cache headers — callers decide whether the result
+ * is still shareable. `injected` tells the caller whether anything changed.
+ */
+async function injectBeforeBodyEnd(
+	response: Response,
+	htmlToInject: string,
+): Promise<{ response: Response; injected: boolean }> {
 	const contentType = response.headers.get("content-type");
-	if (!contentType?.includes("text/html")) return response;
+	if (!contentType?.includes("text/html")) return { response, injected: false };
 
 	const html = await response.text();
-	if (!html.includes("</body>")) return new Response(html, response);
+	if (!html.includes("</body>")) {
+		// Body already consumed — rebuild the response unchanged.
+		return { response: new Response(html, response), injected: false };
+	}
+
+	const injected = html.replace("</body>", `${htmlToInject}</body>`);
+	return {
+		response: new Response(injected, {
+			status: response.status,
+			headers: response.headers,
+		}),
+		injected: true,
+	};
+}
+
+/**
+ * Inject toolbar HTML into a response if it's an HTML page.
+ * Returns the original response if not HTML.
+ */
+async function injectToolbar(
+	response: Response,
+	toolbarHtml: string,
+	routeCache: RouteCache,
+): Promise<Response> {
+	const result = await injectBeforeBodyEnd(response, toolbarHtml);
+	if (result.injected) {
+		// Toolbar-injected HTML is session-specific (its presence reveals an
+		// active editor session); it must never be stored in a shared CDN cache
+		// and served to anonymous visitors. Mirrors the preview branch's guard
+		// (#1398). `Cache-Control` covers browsers/downstream proxies; the
+		// route-cache opt-out covers the shared edge cache, which ignores
+		// `Cache-Control`.
+		result.response.headers.set("Cache-Control", "private, no-store");
+		optOutOfRouteCache(routeCache);
+	}
+	return result.response;
+}
 
-	const injected = html.replace("</body>", `${toolbarHtml}</body>`);
-	const result = new Response(injected, {
-		status: response.status,
-		headers: response.headers,
+/**
+ * Inject the client-toolbar bootstrap script. Identical for every visitor, so
+ * cache headers and route-cache options are left untouched and the response
+ * stays fully shareable.
+ */
+async function injectBootstrap(response: Response): Promise<Response> {
+	const result = await injectBeforeBodyEnd(response, renderToolbarBootstrap());
+	return result.response;
+}
+
+/**
+ * Redirect an `_edit` URL to its canonical form (same URL without the param).
+ * Applied when the requester is not an authenticated editor, so a shared
+ * `?_edit` link degrades gracefully for everyone else (Discussion #1742).
+ */
+function redirectToCanonical(url: URL): Response {
+	const canonical = new URL(url);
+	canonical.searchParams.delete(EDIT_PARAM);
+	return new Response(null, {
+		status: 302,
+		headers: {
+			Location: canonical.pathname + canonical.search + canonical.hash,
+			// Header-following caches (Fastly, Varnish, browsers) must not store
+			// the redirect — a cached 302 would bounce editors back to the
+			// canonical URL. The route-cache opt-out at the call site covers the
+			// Workers Cache, which ignores Cache-Control.
+			"Cache-Control": "private, no-store",
+		},
 	});
-	// Toolbar-injected HTML is session-specific (its presence reveals an active
-	// editor session); it must never be stored in a shared CDN cache and served
-	// to anonymous visitors. Mirrors the preview branch's guard (#1398).
-	result.headers.set("Cache-Control", "private, no-store");
-	return result;
 }
 
 export const onRequest = defineMiddleware(async (context, next) => {
@@ -73,9 +159,30 @@ export const onRequest = defineMiddleware(async (context, next) => {
 	// Fast path: check for CMS signals before doing any work
 	const hasEditCookie = cookies.get("emdash-edit-mode")?.value === "true";
 	const hasPreviewToken = url.searchParams.has("_preview");
+	// `_edit` requests a fresh (never cached) editor render; only meaningful in
+	// client toolbar mode where public HTML is otherwise identical for everyone.
+	const hasEditParam = toolbarMode === "client" && url.searchParams.has(EDIT_PARAM);
+
+	if (hasEditParam) {
+		// `_edit` URLs are their own cache key. Never store them in the route
+		// cache — a cached anonymous redirect would bounce editors back to the
+		// canonical URL, and a cached editor render must never be shared.
+		optOutOfRouteCache(context.cache);
+
+		// A non-editor (anonymous, logged-out, or insufficient role) opening an
+		// `_edit` URL is sent to the canonical URL — shared `?_edit` links
+		// degrade gracefully and never prime a cache entry with page content.
+		if (!isEditor) {
+			return redirectToCanonical(url);
+		}
+	}
 
-	// No CMS signals and not an editor → skip everything (zero overhead)
+	// No CMS signals and not an editor → skip everything (zero overhead in
+	// server mode; client mode injects the identical-for-everyone bootstrap)
 	if (!hasEditCookie && !hasPreviewToken && !isEditor) {
+		if (toolbarMode === "client") {
+			return injectBootstrap(await next());
+		}
 		return next();
 	}
 
@@ -86,6 +193,8 @@ export const onRequest = defineMiddleware(async (context, next) => {
 	// eslint-disable-next-line typescript/no-unsafe-type-assertion -- Astro context includes currentLocale when i18n is configured
 	const locale = (context as { currentLocale?: string }).currentLocale;
 
+	const routeCache = context.cache;
+
 	// Verify preview token if present.
 	// The preview secret is resolved via `resolveSecretsCached`: env wins,
 	// otherwise a DB-stored value is read (or generated on first need).
@@ -122,32 +231,65 @@ export const onRequest = defineMiddleware(async (context, next) => {
 
 			// Preview responses must not be cached -- draft content could leak past token expiry.
 			// Clone the response before modifying headers — the original may be immutable.
+			// `Cache-Control` only governs browsers/downstream proxies; the shared
+			// edge cache follows the route-cache options, so opt out of those too —
+			// otherwise the draft response is stored in the shared cache and served
+			// on cache hits without token verification until TTL/purge. Opt out for
+			// any request carrying a `_preview` param (valid or not): those URLs are
+			// per-token, so cached copies are useless at best and drafts at worst.
+			if (hasPreviewToken) {
+				optOutOfRouteCache(routeCache);
+			}
 			if (preview) {
 				response = new Response(response.body, response);
 				response.headers.set("Cache-Control", "private, no-store");
 			}
 
-			// Inject toolbar for authenticated editors
-			if (isEditor) {
+			// Inject toolbar for authenticated editors. Preview and edit-mode
+			// responses are session-specific (`private, no-store` + route-cache
+			// opt-out) in every toolbar mode, so the server toolbar is safe to
+			// inject here even in client mode.
+			if (isEditor && toolbarMode !== false) {
 				const toolbarHtml = renderToolbar({
 					editMode,
 					isPreview: !!preview,
 				});
-				return injectToolbar(response, toolbarHtml);
+				return injectToolbar(response, toolbarHtml, routeCache);
+			}
+
+			// Stale edit cookie without a session (client mode): still serve the
+			// shareable bootstrap variant.
+			if (toolbarMode === "client" && !isEditor && !preview) {
+				return injectBootstrap(response);
 			}
 
 			return response;
 		});
 	}
 
-	// Editor without CMS signals — no ALS needed, but inject toolbar
+	// Editor without preview/edit-mode signals.
 	if (isEditor) {
+		if (toolbarMode === false) {
+			return next();
+		}
+
+		// Client mode: without the `_edit` param the response must stay
+		// byte-identical to the anonymous variant (plus the same bootstrap
+		// script), so shared caches serve one entry for everyone. The bootstrap
+		// pill is the editor's entry point into the fresh `_edit` render.
+		if (toolbarMode === "client" && !hasEditParam) {
+			return injectBootstrap(await next());
+		}
+
+		// Server mode, or an `_edit` request in client mode: inject the full
+		// toolbar (response becomes `private, no-store` and route-cache
+		// opted out).
 		const response = await next();
 		const toolbarHtml = renderToolbar({
 			editMode: false,
 			isPreview: false,
 		});
-		return injectToolbar(response, toolbarHtml);
+		return injectToolbar(response, toolbarHtml, routeCache);
 	}
 
 	return next();

package/src/astro/middleware.ts

@@ -47,7 +47,7 @@ import {
 import { setI18nConfig } from "../i18n/config.js";
 import type { Database, Storage } from "../index.js";
 import { createPublicMediaUrlResolver } from "../media/url.js";
-import type { SandboxRunner } from "../plugins/sandbox/types.js";
+import type { SandboxRunnerFactory } from "../plugins/sandbox/types.js";
 import type { ResolvedPlugin } from "../plugins/types.js";
 import { invalidateUrlPatternCache } from "../query.js";
 import {
@@ -67,6 +67,9 @@ import { createPublicPluginApiRouteHandler } from "./public-plugin-api-routes.js
 import { resolveSessionUser } from "./session-user.js";
 import type { EmDashHandlers } from "./types.js";
 
+// Public type for withEmDashRuntime() consumers (queue/scheduled handlers).
+export type { EmDashRuntime } from "../emdash-runtime.js";
+
 /**
  * Runtime init lock reclaim deadline. Must be strictly larger than the db
  * init deadline: this lock wraps EmDashRuntime.create() → getDatabase() →
@@ -76,6 +79,17 @@ import type { EmDashHandlers } from "./types.js";
  */
 const RUNTIME_INIT_DEADLINE_MS = DB_INIT_DEADLINE_MS + 15_000;
 
+/**
+ * Throttle for the anonymous-path runtime-init failure log. While a site is
+ * stuck (e.g. a failing migration in its backoff window, #1744) every
+ * anonymous request lands in that catch; one line per interval per isolate
+ * keeps the failure visible without flooding logs on a busy site. Plain
+ * module state (not globalThis): a duplicated SSR chunk just means an extra
+ * log line, which is harmless.
+ */
+const RUNTIME_INIT_ERROR_LOG_INTERVAL_MS = 30_000;
+let lastRuntimeInitErrorLogAt = 0;
+
 /**
  * Whether we've verified the database has been set up.
  * On a fresh deployment the first request may hit a public page, bypassing
@@ -152,8 +166,7 @@ function getConfig(): EmDashConfig | null {
 			}
 		}
 
-		// eslint-disable-next-line typescript/no-unsafe-type-assertion -- virtual module import is untyped (@ts-ignore above)
-		return virtualConfig as EmDashConfig;
+		return virtualConfig;
 	}
 	return null;
 }
@@ -190,19 +203,7 @@ function buildDependencies(config: EmDashConfig): RuntimeDependencies {
 		sandboxEnabled: sandboxModule.sandboxEnabled as boolean,
 		sandboxBypassed: (sandboxModule.sandboxBypassed as boolean) ?? false,
 		sandboxedPluginEntries: (virtualSandboxedPlugins as SandboxedPluginEntry[]) || [],
-		createSandboxRunner: sandboxModule.createSandboxRunner as
-			| ((opts: {
-					db: Kysely<Database>;
-					mediaStorage?: {
-						upload(options: {
-							key: string;
-							body: Uint8Array;
-							contentType: string;
-						}): Promise<unknown>;
-						delete(key: string): Promise<unknown>;
-					};
-			  }) => SandboxRunner)
-			| null,
+		createSandboxRunner: sandboxModule.createSandboxRunner as SandboxRunnerFactory | null,
 		mediaProviderEntries: (virtualMediaProviders as MediaProviderEntry[]) || [],
 	};
 	/* eslint-enable typescript-eslint/no-unsafe-type-assertion */
@@ -275,22 +276,81 @@ export async function runScheduledTasks(
 ): Promise<{ published: PublishedRef[] }> {
 	const config = getConfig();
 	if (!config) return { published: [] };
+	return runOutsideRequest(config, (runtime) => runtime.runScheduledTasks(options));
+}
+
+/**
+ * Run a callback against the EmDash runtime outside any HTTP request — from a
+ * Cloudflare Queue consumer, a `scheduled()` handler, or any other
+ * platform-event handler that has no request and therefore no `locals.emdash`.
+ *
+ * Resolves the same cached runtime singleton request handlers use, so hooks,
+ * plugin state, and storage all behave exactly as they do during a request.
+ * A typical queue consumer finishes a job by calling back into a plugin route:
+ *
+ * ```ts
+ * import { withEmDashRuntime } from "emdash/middleware";
+ *
+ * async function queue(batch: MessageBatch) {
+ * 	await withEmDashRuntime(async (runtime) => {
+ * 		for (const message of batch.messages) {
+ * 			await runtime.handlePluginApiRoute(
+ * 				"my-plugin",
+ * 				"POST",
+ * 				"/finishJob",
+ * 				new Request("https://internal/", {
+ * 					method: "POST",
+ * 					body: JSON.stringify(message.body),
+ * 				}),
+ * 			);
+ * 		}
+ * 	});
+ * }
+ * ```
+ *
+ * Server-only and fully trusted: the callback gets the raw runtime with no
+ * auth or CSRF checks, same trust level as plugin cron. Never expose it to
+ * user input without validating that input yourself.
+ *
+ * Throws when EmDash is not configured (no `emdash()` Astro integration).
+ */
+export async function withEmDashRuntime<T>(
+	run: (runtime: EmDashRuntime) => T | Promise<T>,
+): Promise<T> {
+	const config = getConfig();
+	if (!config) {
+		throw new Error(
+			"EmDash is not configured — withEmDashRuntime() requires the emdash() Astro integration.",
+		);
+	}
+	return runOutsideRequest(config, async (runtime) => run(runtime));
+}
+
+/**
+ * Shared plumbing for request-free entry points (`runScheduledTasks`,
+ * `withEmDashRuntime`): resolve the runtime singleton, then run the callback
+ * under an event-scoped db connection when the adapter needs one.
+ *
+ * Connection-backed adapters (e.g. Postgres over Hyperdrive) cannot reuse
+ * the per-isolate singleton from a platform event: its socket belongs to the
+ * request that opened it, and workerd rejects cross-event I/O. Open an
+ * event-scoped connection and run the callback under it in ALS — the
+ * runtime's db getter, the cron executor, and plugin contexts all resolve
+ * the connection from ALS — then close it. Gated on the adapter being
+ * connection-backed (it exposes `close()`); stateless adapters (D1, Node
+ * SQLite) return null or a close-less scope and keep using the singleton.
+ */
+async function runOutsideRequest<T>(
+	config: EmDashConfig,
+	fn: (runtime: EmDashRuntime) => Promise<T>,
+): Promise<T> {
 	const runtime = await getRuntime(config);
 
-	// Connection-backed adapters (e.g. Postgres over Hyperdrive) cannot reuse
-	// the per-isolate singleton from a Cron Trigger: its socket belongs to the
-	// request that opened it, and workerd rejects cross-event I/O. Open an
-	// event-scoped connection for the sweep and run the batch under it in ALS —
-	// the runtime's db getter, the cron executor, and plugin cron contexts all
-	// resolve the connection from ALS — then close it. Gated on the adapter
-	// being connection-backed (it exposes `close()`); stateless adapters (D1,
-	// Node SQLite) return null or a close-less scope and keep using the
-	// singleton, so their cron path is unchanged.
 	const scoped = createRequestScopedDb({
 		config: config.database?.config,
 		isAuthenticated: false,
-		// The sweep publishes and cleans up — a write workload — so a
-		// connection-backed adapter routes it to the primary.
+		// Event handlers publish, clean up, or run jobs — a write workload —
+		// so a connection-backed adapter routes them to the primary.
 		isWrite: true,
 		cookies: NOOP_COOKIE_JAR,
 		url: CRON_EVENT_URL,
@@ -298,7 +358,7 @@ export async function runScheduledTasks(
 	if (!scoped?.close) {
 		// Stateless adapter (or no per-request scoping): the singleton is safe
 		// outside a request. Any close-less scope created above is discarded.
-		return runtime.runScheduledTasks(options);
+		return fn(runtime);
 	}
 
 	const parent = getRequestContext();
@@ -306,19 +366,19 @@ export async function runScheduledTasks(
 		? { ...parent, db: scoped.db }
 		: { editMode: false, db: scoped.db, metrics: createRequestMetrics(performance.now()) };
 	try {
-		return await runWithContext(ctx, () => runtime.runScheduledTasks(options));
+		return await runWithContext(ctx, () => fn(runtime));
 	} finally {
-		// Guard both so a throw in teardown can't mask the sweep result or skip
-		// close() and leak the connection. Mirrors closeSafely() in scoped-db.ts.
+		// Guard both so a throw in teardown can't mask the callback result or
+		// skip close() and leak the connection. Mirrors closeSafely() in scoped-db.ts.
 		try {
 			scoped.commit();
 		} catch (error) {
-			console.error("[scheduled] request-scoped db commit failed:", error);
+			console.error("[emdash] event-scoped db commit failed:", error);
 		}
 		try {
 			scoped.close();
 		} catch (error) {
-			console.error("[scheduled] request-scoped db close failed:", error);
+			console.error("[emdash] event-scoped db close failed:", error);
 		}
 	}
 }
@@ -524,11 +584,7 @@ export const onRequest = defineMiddleware(async (context, next) => {
 					try {
 						const { getDb } = await import("../loader.js");
 						const db = await getDb();
-						await db
-							.selectFrom("_emdash_migrations" as keyof Database)
-							.selectAll()
-							.limit(1)
-							.execute();
+						await db.selectFrom("_emdash_migrations").selectAll().limit(1).execute();
 						markSetupVerified();
 					} catch (error) {
 						// Only a genuinely-missing migrations table means a fresh,
@@ -571,8 +627,15 @@ export const onRequest = defineMiddleware(async (context, next) => {
 							// requests carry no session.
 							storage: runtime.storage,
 						} as EmDashHandlers;
-					} catch {
-						// Non-fatal — EmDashHead will fall back to base SEO contributions
+					} catch (error) {
+						// Non-fatal — EmDashHead falls back to base SEO contributions —
+						// but log it (throttled): a persistently failing init (e.g. a
+						// failing migration, #1744) is otherwise invisible on the
+						// anonymous path, silently degrading every public page.
+						if (Date.now() - lastRuntimeInitErrorLogAt >= RUNTIME_INIT_ERROR_LOG_INTERVAL_MS) {
+							lastRuntimeInitErrorLogAt = Date.now();
+							console.error("[emdash] runtime init failed (page renders without CMS data):", error);
+						}
 					}
 					timings.push({ name: "rt", dur: performance.now() - t0, desc: "Runtime init" });
 					// Append cold-only sub-phase timings so the breakdown is visible
@@ -721,6 +784,11 @@ export const onRequest = defineMiddleware(async (context, next) => {
 					handlePluginApiRoute: runtime.handlePluginApiRoute.bind(runtime),
 					handlePublicPluginApiRoute: createPublicPluginApiRouteHandler(runtime),
 					getPluginRouteMeta: runtime.getPluginRouteMeta.bind(runtime),
+					getPluginMcpTools: runtime.getPluginMcpTools.bind(runtime),
+					getEnabledPluginMcpTools: runtime.getEnabledPluginMcpTools.bind(runtime),
+					serializePluginMcpConsent: runtime.serializePluginMcpConsent.bind(runtime),
+					handlePluginMcpTool: runtime.handlePluginMcpTool.bind(runtime),
+					handlePluginMcpDenied: runtime.handlePluginMcpDenied.bind(runtime),
 
 					// Media provider methods
 					getMediaProvider: runtime.getMediaProvider.bind(runtime),

package/src/astro/public-plugin-api-routes.ts

@@ -1,3 +1,4 @@
+import type { RouteMeta } from "../plugins/routes.js";
 import type { HandlerResponse } from "./types.js";
 
 export type PublicPluginApiRouteHandler = (
@@ -8,7 +9,7 @@ export type PublicPluginApiRouteHandler = (
 ) => Promise<HandlerResponse>;
 
 interface PublicPluginApiRouteRuntime {
-	getPluginRouteMeta(pluginId: string, path: string): { public: boolean } | null;
+	getPluginRouteMeta(pluginId: string, path: string): RouteMeta | null;
 	handlePluginApiRoute(
 		pluginId: string,
 		method: string,

package/src/astro/routes/PluginRegistry.tsx

@@ -6,7 +6,7 @@
  * together with the admin app and available via React context.
  */
 
-import { AdminApp } from "@emdash-cms/admin";
+import { AdminApp, type AdminBranding } from "@emdash-cms/admin";
 import type { Messages } from "@lingui/core";
 // @ts-ignore - virtual module generated by integration
 import { pluginAdmins } from "virtual:emdash/admin-registry";
@@ -16,13 +16,16 @@ import { authProviders } from "virtual:emdash/auth-providers";
 interface AdminWrapperProps {
 	locale: string;
 	messages: Messages;
+	/** Configured admin white-label branding (logo, site name), read server-side from `admin.astro`. */
+	adminBranding?: AdminBranding;
 }
 
-export default function AdminWrapper({ locale, messages }: AdminWrapperProps) {
+export default function AdminWrapper({ locale, messages, adminBranding }: AdminWrapperProps) {
 	return (
 		<AdminApp
 			pluginAdmins={pluginAdmins}
 			authProviders={authProviders}
+			adminBranding={adminBranding}
 			locale={locale}
 			messages={messages}
 		/>

package/src/astro/routes/admin.astro

@@ -17,6 +17,7 @@ import { Font } from "astro:assets";
 export const prerender = false;
 
 import { resolveLocale, loadMessages, getLocaleDir } from "@emdash-cms/admin/locales";
+import { getSiteSettingsWithDb } from "#settings/index.js";
 
 const resolvedLocale = resolveLocale(Astro.request);
 const resolvedDir = getLocaleDir(resolvedLocale);
@@ -33,17 +34,59 @@ const pageTitle = adminConfig?.siteName ? `${adminConfig.siteName} Admin` : "EmD
 // via cookie/Accept-Language). API routes already send `private, no-store`
 // (API_CACHE_HEADERS); this closes the same gap for the admin HTML.
 Astro.response.headers.set("Cache-Control", "private, no-store");
+
+// Favicon precedence: an explicit build-time `admin.favicon` is admin-specific
+// and always wins — in that case the settings read is skipped entirely.
+// Otherwise fall back to the Site Icon configured in Settings → General, so
+// the admin shell is branded like the public site (WordPress-style Site Icon,
+// which also brands wp-admin), and finally the bundled EmDash mark below.
+const emdash = Astro.locals.emdash;
+let siteFavicon: string | undefined;
+let siteFaviconType: string | undefined;
+if (!adminConfig?.favicon && emdash?.db) {
+	try {
+		const settings = await getSiteSettingsWithDb(emdash.db, emdash.storage ?? null);
+		siteFavicon = settings.favicon?.url ?? undefined;
+		siteFaviconType = settings.favicon?.contentType ?? undefined;
+	} catch {
+		// Settings unavailable (e.g. pre-setup) — fall back to the config/default.
+	}
+}
+const favicon = adminConfig?.favicon ?? siteFavicon;
+// The media-file URL has no extension, so browsers need the MIME type —
+// Chromium ignores SVG favicons without type="image/svg+xml". Only set for
+// Site Icons; build-time `admin.favicon` strings keep their current behavior.
+const faviconType = adminConfig?.favicon ? undefined : siteFaviconType;
 ---
 
 <!doctype html>
-<html lang={resolvedLocale} dir={resolvedDir}>
+<html lang={resolvedLocale} dir={resolvedDir} data-theme="classic">
 	<head>
 		<meta charset="UTF-8" />
 		<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+		<script is:inline>
+			(() => {
+				let preference = "system";
+
+				try {
+					const storedPreference = localStorage.getItem("emdash-theme");
+					if (storedPreference === "light" || storedPreference === "dark") {
+						preference = storedPreference;
+					}
+				} catch {
+					// Storage can be unavailable in privacy-restricted contexts. Use the system theme.
+				}
+
+				const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
+				const mode =
+					preference === "dark" || (preference === "system" && prefersDark) ? "dark" : "light";
+				document.documentElement.setAttribute("data-mode", mode);
+			})();
+		</script>
 		<link rel="stylesheet" href={adminStylesUrl} />
 		<Font cssVariable="--font-emdash" />
-		{adminConfig?.favicon ? (
-			<link rel="icon" href={adminConfig.favicon} />
+		{favicon ? (
+			<link rel="icon" href={favicon} type={faviconType} />
 		) : (
 			<link
 				rel="icon"
@@ -61,8 +104,7 @@ Astro.response.headers.set("Cache-Control", "private, no-store");
 						align-items: center;
 						justify-content: center;
 						min-height: 100vh;
-						color-scheme: light dark;
-						background: light-dark(hsl(0 0% 100%), hsl(222.2 84% 4.9%));
+						background: var(--color-kumo-elevated);
 					}
 					#emdash-boot-loader .loader-inner {
 						text-align: center;
@@ -71,15 +113,8 @@ Astro.response.headers.set("Cache-Control", "private, no-store");
 						width: 24px;
 						height: 24px;
 						margin: 0 auto;
-						border: 2.5px solid
-							light-dark(
-								hsl(215.4 16.3% 46.9% / 0.3),
-								hsl(215 20.2% 65.1% / 0.3)
-							);
-						border-top-color: light-dark(
-							hsl(215.4 16.3% 46.9%),
-							hsl(215 20.2% 65.1%)
-						);
+						border: 2.5px solid var(--color-kumo-line);
+						border-top-color: var(--text-color-kumo-subtle);
 						border-radius: 50%;
 						animation: emdash-spin 0.8s linear infinite;
 					}
@@ -92,7 +127,7 @@ Astro.response.headers.set("Cache-Control", "private, no-store");
 							sans-serif
 						);
 						font-size: 0.875rem;
-						color: light-dark(hsl(215.4 16.3% 46.9%), hsl(215 20.2% 65.1%));
+						color: var(--text-color-kumo-subtle);
 					}
 					@keyframes emdash-spin {
 						to {
@@ -105,7 +140,12 @@ Astro.response.headers.set("Cache-Control", "private, no-store");
 					<p>{adminConfig?.siteName ? `Loading ${adminConfig.siteName}...` : "Loading EmDash..."}</p>
 				</div>
 			</div>
-			<AdminWrapper client:only="react" locale={resolvedLocale} messages={messages} />
+			<AdminWrapper
+				client:only="react"
+				locale={resolvedLocale}
+				messages={messages}
+				adminBranding={{ logo: adminConfig?.logo, siteName: adminConfig?.siteName }}
+			/>
 		</div>
 	</body>
 </html>

package/src/astro/routes/api/admin/api-tokens/index.ts

@@ -12,13 +12,13 @@ import { z } from "zod";
 import { apiError, handleError, unwrapResult } from "#api/error.js";
 import { handleApiTokenCreate, handleApiTokenList } from "#api/handlers/api-tokens.js";
 import { isParseError, parseBody } from "#api/parse.js";
-import { VALID_SCOPES } from "#auth/api-tokens.js";
+import { isValidScope } from "#auth/api-tokens.js";
 
 export const prerender = false;
 
 const createTokenSchema = z.object({
 	name: z.string().min(1).max(100),
-	scopes: z.array(z.enum(VALID_SCOPES)).min(1),
+	scopes: z.array(z.string().refine(isValidScope)).min(1),
 	expiresAt: z.string().datetime().optional(),
 });