feat: toolbar config option with client-side bootstrap mode for shared caches (emdash-cms#1886)

* feat: add toolbar config with client-side bootstrap mode for shared caches

Implements the design agreed in Discussion emdash-cms#1742: a `toolbar` option with
"server" (default, unchanged), "client" (cache-identical public HTML with a
client-rendered Edit pill and an `_edit` query param for fresh editor
renders), and `false` (disabled). The toolbar is now also dismissible in
the browser.

* fix: mark _edit canonical redirect and render as uncacheable

Addresses review: the 302 for non-editors now carries
Cache-Control: private, no-store, and both the redirect and the
editor render opt out of the route cache (a cached redirect would
bounce editors back to the canonical URL).

* test: extract bootstrap script by index instead of regex

CodeQL flags the <script>…</script> regex as a bad HTML-filtering
pattern (case-sensitive tags). Use indexOf/lastIndexOf — we are
slicing our own generated string, not filtering HTML.

Author: swissky

.changeset/toolbar-client-mode.md

@@ -0,0 +1,6 @@
+---
+"emdash": minor
+"@emdash-cms/admin": patch
+---
+
+Adds a `toolbar` config option for reliable editor-toolbar delivery behind shared caches. `toolbar: "client"` keeps public HTML identical for every visitor and shows a client-side "Edit" pill for logged-in editors that opens a fresh, uncached editor render via an `_edit` query param; `toolbar: false` disables the toolbar entirely. The toolbar can now also be dismissed in the browser via its × button. The default (`"server"`) is unchanged.

docs/src/content/docs/reference/configuration.mdx

@@ -367,6 +367,33 @@ emdash({
 
 Uploads that exceed the configured limit are rejected with a `413 Payload Too Large` response on the direct upload path, or a `400 Validation Error` on the signed-URL path.
 
+### `toolbar`
+
+**Optional.** Controls how the editor toolbar (the floating pill on public pages) is delivered. Defaults to `"server"`.
+
+| Value | Behavior |
+| ----- | -------- |
+| `"server"` (default) | The toolbar is injected server-side into every HTML response rendered for an authenticated editor. |
+| `"client"` | Public HTML is identical for every visitor. A tiny bootstrap script shows an "Edit" pill in browsers that have logged into the admin; 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. |
+| `false` | Never render the toolbar or the bootstrap script. |
+
+```js
+emdash({
+	toolbar: "client",
+})
+```
+
+Use `"client"` when your public HTML is served through a shared cache (Cloudflare Cache Everything / [Workers Cache](https://developers.cloudflare.com/workers/cache/), Fastly, Varnish, …). With server-side injection, an editor browsing the public site receives the cached anonymous variant — without the toolbar — whenever an anonymous visitor primed the cache first, so the toolbar appears and disappears with cache state. In client mode nothing session-specific is injected into shareable HTML, so the cache stays fully effective and the toolbar is reliable.
+
+Notes on `"client"` mode:
+
+- Logged-out visitors who open a shared `?_edit` URL are redirected to the canonical URL, so the param can't leak drafts or prime extra cache entries with page content.
+- The "logged in" signal is a non-secret `localStorage` flag set by the admin; the pill verifies the real session before entering the edit view.
+- The bootstrap is a small inline `<script>`. If your site sends a strict `Content-Security-Policy` without `'unsafe-inline'`, add a hash for it — the same applies to the server-injected toolbar.
+- EmDash injects nothing session-specific — but if your own templates branch on `Astro.locals.user` (e.g. an "Admin" nav link for logged-in users), that variance is still in your HTML and still fragments the cache.
+
+In every mode, the toolbar can be dismissed in the browser via its × button (per-browser, until the next time an editor opens the admin). Preview and edit-mode responses always render server-side with `Cache-Control: private, no-store`.
+
 ### `experimental`
 
 **Optional.** Opt-in features whose behaviour or wire format may change, or be removed, in a minor release. Each field is independently enabled.

packages/admin/src/components/Header.tsx

@@ -12,6 +12,12 @@ import { ThemeToggle } from "./ThemeToggle";
 export type { CurrentUser } from "../lib/api/current-user";
 
 async function handleLogout() {
+	// Clear the public-site toolbar-bootstrap flag (see Shell.tsx).
+	try {
+		localStorage.removeItem("emdash-editor");
+	} catch {
+		// ignore — flag is best-effort
+	}
 	const res = await apiFetch("/_emdash/api/auth/logout?redirect=/_emdash/admin/login", {
 		method: "POST",
 		credentials: "same-origin",

packages/admin/src/components/Shell.tsx

@@ -47,6 +47,26 @@ export function Shell({ children, manifest }: ShellProps) {
 		}
 	}, [user?.isFirstLogin]);
 
+	// Maintain the non-secret "an editor session may exist in this browser"
+	// localStorage flag consumed by the public-site toolbar bootstrap
+	// (`toolbar: "client"`, Discussion #1742). Set here — not in the login
+	// flows — so every auth method (passkey, OAuth, magic link, dev bypass)
+	// is covered. Opening the admin also un-dismisses the toolbar.
+	// Key literals are duplicated in emdash core, which the admin can't import.
+	React.useEffect(() => {
+		if (!user) return;
+		try {
+			if (user.role >= 30) {
+				localStorage.setItem("emdash-editor", "1");
+				localStorage.removeItem("emdash-toolbar-dismissed");
+			} else {
+				localStorage.removeItem("emdash-editor");
+			}
+		} catch {
+			// localStorage unavailable — the toolbar pill just won't appear
+		}
+	}, [user]);
+
 	return (
 		<Sidebar.Provider
 			defaultOpen

packages/core/src/astro/integration/index.ts

@@ -350,6 +350,7 @@ export function emdash(config: EmDashConfig = {}): AstroIntegration {
 		trustedProxyHeaders: resolvedConfig.trustedProxyHeaders,
 		maxUploadSize: resolvedConfig.maxUploadSize,
 		admin: resolvedConfig.admin,
+		toolbar: resolvedConfig.toolbar,
 	};
 
 	// Determine auth mode for route injection

packages/core/src/astro/integration/runtime.ts

@@ -589,6 +589,30 @@ export interface EmDashConfig {
 		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

packages/core/src/astro/middleware/request-context.ts

@@ -8,17 +8,27 @@
  * - 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"];
 
@@ -35,6 +45,34 @@ 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, injected: false };
+
+	const html = await response.text();
+	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.
@@ -44,25 +82,49 @@ async function injectToolbar(
 	toolbarHtml: string,
 	routeCache: RouteCache,
 ): Promise<Response> {
-	const contentType = response.headers.get("content-type");
-	if (!contentType?.includes("text/html")) return 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 html = await response.text();
-	if (!html.includes("</body>")) return new Response(html, response);
+/**
+ * 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;
+}
 
-	const injected = html.replace("</body>", `${toolbarHtml}</body>`);
-	const result = new Response(injected, {
-		status: response.status,
-		headers: response.headers,
+/**
+ * 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).
-	// `Cache-Control` covers browsers/downstream proxies; the route-cache
-	// opt-out covers the shared edge cache, which ignores `Cache-Control`.
-	result.headers.set("Cache-Control", "private, no-store");
-	optOutOfRouteCache(routeCache);
-	return result;
 }
 
 export const onRequest = defineMiddleware(async (context, next) => {
@@ -97,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();
 	}
 
@@ -162,21 +245,45 @@ export const onRequest = defineMiddleware(async (context, next) => {
 				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, 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,

packages/core/src/virtual-modules.d.ts

@@ -20,6 +20,7 @@ declare module "virtual:emdash/config" {
 		auth?: AuthDescriptor;
 		authProviders?: AuthProviderDescriptor[];
 		i18n?: I18nConfig | null;
+		toolbar?: "server" | "client" | false;
 	}
 
 	const config: VirtualConfig;