@spooky-sync/core 0.0.1-canary.262 → 0.0.1-canary.264

package/AGENTS.md

@@ -33,7 +33,7 @@ re-materialized from state, never patched in place.
 
 ## Key exports (`src/index.ts`)
 
-- `Sp00kyClient<S>` — main class. Methods: `init()`, `create(id, payload)`, `update(table, id, payload, options?)`, `delete(table, id)`, `query(table, opts?)`, `preload(query, { signal? })`, `run(backend, route, payload)`, `bucket(name)`, `remoteQuery(sql, vars?)`, `useRemote(fn)`, `authenticate(token)`, `auth.signOut()`. Admin impersonation (`impersonation.enabled` in sp00ky.yml, admins only, server-enforced): `auth.impersonate(targetId, reason)`, `auth.stopImpersonating()`, `auth.impersonation`, `auth.subscribeImpersonation(cb)`, `auth.searchImpersonationTargets(search)`; while active the client injects a warning bar with a Stop button (see `/docs/client/impersonation`). Traffic indicators: `pendingMutationCount` / `subscribeToPendingMutations(cb)` (outbox depth), `fetchingQueryCount` / `subscribeToFetchActivity(cb)`. Failed-writes tray: `failedMutationCount`, `subscribeToFailedMutations(cb)`, `listFailedMutations()`, `retryFailedMutation(id)`, `discardFailedMutation(id)`.
+- `Sp00kyClient<S>` — main class. Methods: `init()`, `create(id, payload)`, `update(table, id, payload, options?)`, `delete(table, id)`, `query(table, opts?)`, `preload(query, { signal? })`, `run(backend, route, payload)`, `bucket(name)`, `remoteQuery(sql, vars?)`, `useRemote(fn)`, `authenticate(token)`, `auth.signOut()`. Admin impersonation (`impersonation.enabled` in sp00ky.yml, admins only, server-enforced): `auth.impersonate(targetId, reason)`, `auth.stopImpersonating()`, `auth.impersonation`, `auth.subscribeImpersonation(cb)`, `auth.searchImpersonationTargets(search)`; while active the client injects a warning bar with a Stop button and shifts the page down onto a hazard-striped layer. `impersonationBanner` in the client config restyles it (`theme`), replaces it (`mode: 'custom'` + `client.acknowledgeImpersonationBanner()`, else it falls back after ~2.5s) or turns it off (`mode: 'none'`). See `/docs/client/impersonation`. Traffic indicators: `pendingMutationCount` / `subscribeToPendingMutations(cb)` (outbox depth), `fetchingQueryCount` / `subscribeToFetchActivity(cb)`. Failed-writes tray: `failedMutationCount`, `subscribeToFailedMutations(cb)`, `listFailedMutations()`, `retryFailedMutation(id)`, `discardFailedMutation(id)`.
 - `FailedMutation` — a row of the `_00_failed_mutations` tray (`mutationType`, `recordId`, `data`, `beforeRecord`, `error`, `revert`).
 - `BucketHandle` — file storage handle (`put`, `get`, `delete`, `exists`), plus the cache-aware `read`, `url`, `pin`/`unpin`, `evict`, `prefetch`. `get` is always remote; `read`/`url` go through the blob cache.
 - `services/blobs/` — durable cache for bucket bytes: OPFS holds the files, `_00_blob` holds a manifest that reconcile rebuilds from disk (so a wiped local store costs metadata, not the offline cache). Nothing expires on a timer; eviction is LRU under a byte budget only, skipping pinned and on-screen entries. Config: `blobCache` in `types.ts`.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { A as RunOptions, B as SyncHealthStatus, C as QueryTimeToLive, D as RecordVersionArray, E as ReconnectConfig, F as StorageHealth, G as DatabaseEventTypes, H as UpdateOptions, I as StorageHealthStatus, J as EventSystem, K as SealedQuery, L as StoreType, M as Sp00kyConfig, N as Sp00kyQueryResult, O as RecordVersionDiff, P as Sp00kyQueryResultPromise, R as SyncHealth, S as QueryStatusCallback, T as QueryUpdateCallback, U as LocalStore, V as TimingPhase, W as DatabaseEventSystem, _ as QueryConfig, a as Level, b as QueryState, c as MutationCallback, d as PersistenceClient, f as PhaseStat, g as QueryAuthorityCallback, h as PreloadRefresh, i as InlineRow, j as ServerViewMeta, k as RegistrationTimings, l as MutationEvent, m as PreloadOptions, n as DebounceOptions, o as MATERIALIZATION_SAMPLE_WINDOW, p as PinoTransmit, q as EventDefinition, r as EventSubscriptionOptions, s as MembershipOutcome, t as ConnectionState, u as MutationEventType, v as QueryConfigRecord, w as QueryTimings, x as QueryStatus, y as QueryHash, z as SyncHealthConfig } from "./types.js";
+import { $ as ORIGIN_TOKEN_KEY, A as RunOptions, B as SyncHealthStatus, C as QueryTimeToLive, D as RecordVersionArray, E as ReconnectConfig, F as StorageHealth, G as DatabaseEventTypes, H as UpdateOptions, I as StorageHealthStatus, J as EventSystem, K as SealedQuery, L as StoreType, M as Sp00kyConfig, N as Sp00kyQueryResult, O as RecordVersionDiff, P as Sp00kyQueryResultPromise, Q as ImpersonationTimers, R as SyncHealth, S as QueryStatusCallback, T as QueryUpdateCallback, U as LocalStore, V as TimingPhase, W as DatabaseEventSystem, X as ImpersonationInfo, Y as IMPERSONATION_ACCESS, Z as ImpersonationTimerHost, _ as QueryConfig, a as Level, at as sameImpersonation, b as QueryState, c as MutationCallback, d as PersistenceClient, et as SESSION_POLL_MS, f as PhaseStat, g as QueryAuthorityCallback, h as PreloadRefresh, i as InlineRow, it as renewDelayMs, j as ServerViewMeta, k as RegistrationTimings, l as MutationEvent, m as PreloadOptions, n as DebounceOptions, nt as decodeTokenClaims, o as MATERIALIZATION_SAMPLE_WINDOW, p as PinoTransmit, q as EventDefinition, r as EventSubscriptionOptions, rt as impersonationFromToken, s as MembershipOutcome, t as ConnectionState, tt as TokenClaims, u as MutationEventType, v as QueryConfigRecord, w as QueryTimings, x as QueryStatus, y as QueryHash, z as SyncHealthConfig } from "./types.js";
 import { AccessDefinition, BackendNames, BackendRoutes, BucketNames, ColumnSchema, FinalQuery, GetTable, QueryBuilder, QueryOptions, QueryPlan, RecordId, RoutePayload, SchemaStructure, TableModel, TableNames, TypeNameToTypeMap } from "@spooky-sync/query-builder";
 import * as surrealdb0 from "surrealdb";
 import { Duration, RecordId as RecordId$1, Surreal, SurrealEvents, SurrealTransaction } from "surrealdb";
@@ -674,92 +674,6 @@ declare class StreamProcessorService {
   private normalizeValue;
 }
 //#endregion
-//#region src/modules/auth/impersonation.d.ts
-/**
- * Admin impersonation, client side.
- *
- * The server does the enforcing (see `impersonation_remote.surql` in the CLI):
- * an admin calls `fn::_00_impersonate::start`, receives a token for the
- * `_00_impersonate` access method, and authenticates with it, so `$auth.id` is
- * the target user. Everything here is state and timers around that:
- *
- * - the admin's own token is kept under {@link ORIGIN_TOKEN_KEY} so Stop (and a
- *   reload in between) can return to it;
- * - the impersonation state is derived from the token's claims, never stored
- *   separately, so it cannot disagree with the session actually in use;
- * - the token is re-signed before it expires, and the session is polled so a
- *   stop or revocation made elsewhere reaches an open WebSocket quickly.
- */
-/** Access method impersonation tokens are issued for. */
-declare const IMPERSONATION_ACCESS = "_00_impersonate";
-/** Persistence key holding the admin's own token while impersonating. */
-declare const ORIGIN_TOKEN_KEY = "sp00ky_auth_token_origin";
-/** How often an active impersonation re-checks its session on the server. */
-declare const SESSION_POLL_MS = 60000;
-interface ImpersonationInfo {
-  /** `_00_impersonation:<id>` the session is bound to. */
-  session: string;
-  /** Record id being impersonated. */
-  target: string;
-  /** Record id of the admin. */
-  admin: string;
-  /** When the current token expires (it is renewed before then). */
-  tokenExpiresAt: Date | null;
-}
-interface TokenClaims {
-  access: string | null;
-  userId: string | null;
-  exp: number | null;
-  impersonation: {
-    session: string;
-    admin: string;
-  } | null;
-}
-/**
- * Read the claims of a SurrealDB record-access JWT WITHOUT verifying it. The
- * server still enforces the token on every request; this is only so the client
- * can act on what it already holds before a round trip completes.
- *
- * Returns nulls on any malformed input.
- */
-declare function decodeTokenClaims(token: string): TokenClaims;
-/** The impersonation a token represents, or null for a regular session. */
-declare function impersonationFromToken(token: string | null): ImpersonationInfo | null;
-/** Same impersonation, for change detection (renewals only move the expiry). */
-declare function sameImpersonation(a: ImpersonationInfo | null, b: ImpersonationInfo | null): boolean;
-/**
- * When to renew a token expiring at `expSecs`: at 80% of its remaining life,
- * never sooner than 5s from now, and immediately once it is inside that.
- */
-declare function renewDelayMs(expSecs: number, nowMs: number): number;
-interface ImpersonationTimerHost {
-  /** Current impersonation, or null. */
-  current(): ImpersonationInfo | null;
-  /** Re-sign the token. Rejects when the session has ended. */
-  renew(): Promise<void>;
-  /** Whether the server still considers the session live. */
-  stillActive(): Promise<boolean>;
-  /** Leave the impersonation because the server ended it. */
-  endedRemotely(reason: string): Promise<void>;
-  /** Whether a failure was a reachability problem (retry) rather than an answer. */
-  isNetworkError(error: unknown): boolean;
-}
-/**
- * The two timers an active impersonation needs. `sync()` is called whenever
- * the auth state changes and arms or clears them to match.
- */
-declare class ImpersonationTimers {
-  private host;
-  private renewTimer;
-  private pollTimer;
-  private armedFor;
-  constructor(host: ImpersonationTimerHost);
-  sync(): void;
-  clear(): void;
-  private renew;
-  private poll;
-}
-//#endregion
 //#region src/modules/auth/events/index.d.ts
 declare const AuthEventTypes: {
   readonly AuthStateChanged: "AUTH_STATE_CHANGED";
@@ -2407,6 +2321,8 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   private readonly appReleases;
   /** Teardown for subscriptions the client itself owns. */
   private readonly disposers;
+  /** Assigned in `wireAdapters`, which the constructor always runs. */
+  private impersonationBanner;
   private readonly devTools;
   private hub;
   private forwarder;
@@ -2476,6 +2392,14 @@ declare class Sp00kyClient<S extends SchemaStructure> {
   deauthenticate(): Promise<void>;
   useRemote<T>(fn: (client: Surreal) => Promise<T> | T): Promise<T>;
   remoteQuery<T extends unknown[]>(sql: string, vars?: Record<string, unknown>): Promise<T>;
+  /**
+   * Tell the client that the app's own impersonation banner is on screen.
+   * Only meaningful with `impersonationBanner: { mode: 'custom' }`, where it
+   * cancels the fallback that would otherwise show the built-in banner. Call
+   * it while the custom banner is rendered (the Solid `useImpersonation`
+   * hook does it for you with `rendersBanner: true`).
+   */
+  acknowledgeImpersonationBanner(): void;
   feature(key: string, options?: FeatureFlagOptions): FeatureFlagHandle;
   setFeatureOverride(key: string, variant: string | null, payload?: unknown): void;
   clearFeatureOverrides(): void;

package/dist/index.js

@@ -1076,8 +1076,8 @@ function selfAllowlistedVariant(flag, userId) {
 
 //#endregion
 //#region src/modules/devtools/index.ts
-const CORE_VERSION = "0.0.1-canary.262";
-const WASM_VERSION = "0.0.1-canary.262";
+const CORE_VERSION = "0.0.1-canary.264";
+const WASM_VERSION = "0.0.1-canary.264";
 const SURREAL_VERSION = "3.0.3";
 var DevToolsService = class DevToolsService {
 	eventsHistory = [];
@@ -13025,7 +13025,7 @@ function createTabsCoordinator(config, s, host) {
 	return new TabsCoordinator({
 		tabId: s.tabId,
 		fingerprint: computeTabsFingerprint({
-			coreVersion: "0.0.1-canary.262",
+			coreVersion: "0.0.1-canary.264",
 			schemaHash: hash53(config.schemaSurql),
 			endpoint: config.database.endpoint ?? "",
 			namespace: config.database.namespace,
@@ -13296,23 +13296,43 @@ function createAdapters(config, s, host, lateModules) {
 
 //#endregion
 //#region src/modules/auth/impersonation-banner.ts
-/** Height of the warning layer the page is shifted down by. Also published as
-*  the CSS variable `--sp00ky-impersonation-banner-height` on `<html>` (`0px`
-*  when hidden), so an app can offset its own fixed header. */
+/** Default height of the warning layer the page is shifted down by. The
+*  effective height is published as the CSS variable
+*  `--sp00ky-impersonation-banner-height` on `<html>` (`0px` when hidden), so
+*  an app can offset its own fixed header. */
 const BANNER_HEIGHT_PX = 44;
-/** Radius of the page's new top corners. */
+/** Default radius of the page's new top corners. */
 const PAGE_RADIUS_PX = 14;
+/** Default hazard stripes: the warning layer, and the `<html>` backdrop the
+*  page's rounded corners reveal. */
+const BANNER_STRIPES = "repeating-linear-gradient(45deg, #f2b600 0 14px, #1c1403 14px 28px)";
 const HOST_TAG = "sp00ky-impersonation-banner";
-/** Hazard stripes: the warning layer, and the `<html>` backdrop the page's
-*  rounded corners reveal. */
-const STRIPES = "repeating-linear-gradient(45deg, #f2b600 0 14px, #1c1403 14px 28px)";
+/** How long a `custom` banner has to acknowledge itself before the built-in
+*  one is shown anyway. Long enough for a first paint, short enough that
+*  nobody browses unwarned. */
+const CUSTOM_BANNER_GRACE_MS = 2500;
+function resolveTheme(theme = {}) {
+	return {
+		heightPx: theme.heightPx ?? BANNER_HEIGHT_PX,
+		radiusPx: theme.radiusPx ?? PAGE_RADIUS_PX,
+		background: theme.background ?? BANNER_STRIPES,
+		pill: theme.pill ?? "rgba(14, 11, 2, .88)",
+		pillText: theme.pillText ?? "#fde68a",
+		accent: theme.accent ?? "#fde68a",
+		accentText: theme.accentText ?? "#1c1403",
+		stopLabel: theme.stopLabel ?? "Stop",
+		noPageShift: theme.noPageShift ?? false,
+		label: theme.label ?? ((info) => `Impersonating **${info.target}** as ${info.admin}`)
+	};
+}
 /** Keeps only the area OUTSIDE a corner's curve, so the nub is striped and
 *  everything inside the curve stays the app's own. `center` is the curve's
 *  centre inside the corner square. */
-function cornerMask(center) {
-	return `radial-gradient(circle ${PAGE_RADIUS_PX}px at ${center}, transparent 0 ${PAGE_RADIUS_PX}px, #000 ${PAGE_RADIUS_PX}px)`;
+function cornerMask(center, radius) {
+	return `radial-gradient(circle ${radius}px at ${center}, transparent 0 ${radius}px, #000 ${radius}px)`;
 }
-const STYLE = `
+function bannerCss(t) {
+	return `
 :host {
   all: initial !important;
   display: block !important;
@@ -13324,7 +13344,7 @@ const STYLE = `
 }
 .layer {
   position: fixed; inset: 0 0 auto 0; z-index: 2147483646; pointer-events: none;
-  height: ${BANNER_HEIGHT_PX}px; background: ${STRIPES};
+  height: ${t.heightPx}px; background: ${t.background};
 }
 /* The page's rounded top corners, drawn over whatever the app puts there.
    The body element's own border-radius rounds its background, but a fixed app
@@ -13332,25 +13352,25 @@ const STYLE = `
    square masked down to the nub OUTSIDE the corner's curve, so the app's own
    colour still shows inside it. */
 .corners {
-  position: fixed; left: 0; right: 0; top: ${BANNER_HEIGHT_PX}px;
-  height: ${PAGE_RADIUS_PX}px; z-index: 2147483646; pointer-events: none;
+  position: fixed; left: 0; right: 0; top: ${t.heightPx}px;
+  height: ${t.radiusPx}px; z-index: 2147483646; pointer-events: none;
 }
 .corner {
-  position: absolute; top: 0; width: ${PAGE_RADIUS_PX}px; height: ${PAGE_RADIUS_PX}px;
-  background: ${STRIPES};
+  position: absolute; top: 0; width: ${t.radiusPx}px; height: ${t.radiusPx}px;
+  background: ${t.background};
 }
 .corner.left {
   left: 0;
-  -webkit-mask: ${cornerMask("100% 100%")};
-  mask: ${cornerMask("100% 100%")};
+  -webkit-mask: ${cornerMask("100% 100%", t.radiusPx)};
+  mask: ${cornerMask("100% 100%", t.radiusPx)};
 }
 .corner.right {
   right: 0;
-  -webkit-mask: ${cornerMask("0% 100%")};
-  mask: ${cornerMask("0% 100%")};
+  -webkit-mask: ${cornerMask("0% 100%", t.radiusPx)};
+  mask: ${cornerMask("0% 100%", t.radiusPx)};
 }
 .bar {
-  position: fixed; inset: 0 0 auto 0; height: ${BANNER_HEIGHT_PX}px; z-index: 2147483647;
+  position: fixed; inset: 0 0 auto 0; height: ${t.heightPx}px; z-index: 2147483647;
   display: flex; align-items: center; justify-content: center; gap: 10px;
   padding: 0 12px; box-sizing: border-box;
   font: 600 13px/1 system-ui, -apple-system, "Segoe UI", sans-serif;
@@ -13358,25 +13378,25 @@ const STYLE = `
 .pill {
   display: flex; align-items: center; gap: 8px; min-width: 0; max-width: 100%;
   padding: 6px 10px; border-radius: 999px;
-  background: rgba(14, 11, 2, .88); color: #fde68a;
+  background: ${t.pill}; color: ${t.pillText};
   box-shadow: 0 1px 6px rgba(0, 0, 0, .45);
 }
 .sign { flex: none; font-size: 14px; line-height: 1; }
 .text { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; min-width: 0; }
-.text b { color: #fff; font-weight: 800; }
 button {
   flex: none; cursor: pointer; border: 0; border-radius: 999px;
-  background: #fde68a; color: #1c1403;
+  background: ${t.accent}; color: ${t.accentText};
   font: 800 12px/1 system-ui, sans-serif; padding: 7px 12px;
   box-shadow: 0 1px 6px rgba(0, 0, 0, .45);
 }
-button:hover { background: #fff; }
+button:hover { filter: brightness(1.12); }
 button:disabled { opacity: .6; cursor: progress; }
 @media (max-width: 520px) {
   .bar { gap: 6px; padding: 0 8px; }
   .pill { padding: 5px 8px; }
 }
 `;
+}
 /**
 * The "you are impersonating" warning.
 *
@@ -13395,8 +13415,27 @@ var ImpersonationBanner = class ImpersonationBanner {
 	text = null;
 	/** `style` attributes as the page had them before the shift. */
 	saved = null;
-	constructor(onStop) {
+	theme;
+	mode;
+	/** Grace timer for `custom` mode. */
+	fallbackTimer = null;
+	/** The app said its own banner is on screen for this impersonation. */
+	acknowledged = false;
+	warnedAboutNone = false;
+	constructor(onStop, config = {}) {
 		this.onStop = onStop;
+		this.mode = config.mode ?? "default";
+		this.theme = resolveTheme(config.theme);
+	}
+	/**
+	* The app's own banner is rendered. Cancels the `custom`-mode fallback, and
+	* removes the built-in banner if the fallback already fired (a slow first
+	* paint, say). No-op in the other modes.
+	*/
+	acknowledge() {
+		this.acknowledged = true;
+		this.clearFallback();
+		if (this.mode === "custom") this.teardown();
 	}
 	static supported() {
 		return typeof document !== "undefined" && typeof document.createElement === "function";
@@ -13404,15 +13443,41 @@ var ImpersonationBanner = class ImpersonationBanner {
 	update(info) {
 		if (!ImpersonationBanner.supported()) return;
 		if (!info) {
+			this.acknowledged = false;
 			this.unmount();
 			return;
 		}
+		if (this.mode === "none") {
+			if (!this.warnedAboutNone) {
+				this.warnedAboutNone = true;
+				console.warn("[sp00ky] impersonation is active and impersonationBanner.mode is \"none\": nothing marks this page as another user's session.");
+			}
+			return;
+		}
+		if (this.mode === "custom" && !this.acknowledged) {
+			if (!this.fallbackTimer && !this.host) this.fallbackTimer = setTimeout(() => {
+				this.fallbackTimer = null;
+				if (!this.acknowledged) this.render(info);
+			}, CUSTOM_BANNER_GRACE_MS);
+			return;
+		}
+		if (this.mode === "custom") return;
+		this.render(info);
+	}
+	unmount() {
+		this.clearFallback();
+		this.teardown();
+	}
+	/** Mount (if needed) and write the current identities into the bar. */
+	render(info) {
 		this.mount();
 		const text = this.text;
-		text.replaceChildren(document.createTextNode("Impersonating "), bold(info.target), document.createTextNode(` as ${info.admin}`));
-		text.title = `Impersonating ${info.target} as ${info.admin}. Every write is audited.`;
+		text.textContent = "";
+		text.append(...labelNodes(this.theme.label(info)));
+		text.title = `${this.theme.label(info)}. Every write is audited.`;
 	}
-	unmount() {
+	/** Remove the bar and undo the page shift. */
+	teardown() {
 		this.host?.remove();
 		this.host = this.text = null;
 		if (typeof document === "undefined") return;
@@ -13423,12 +13488,16 @@ var ImpersonationBanner = class ImpersonationBanner {
 		}
 		document.documentElement?.style.setProperty("--sp00ky-impersonation-banner-height", "0px");
 	}
+	clearFallback() {
+		if (this.fallbackTimer) clearTimeout(this.fallbackTimer);
+		this.fallbackTimer = null;
+	}
 	mount() {
 		if (this.host?.isConnected) return;
 		const host = document.createElement(HOST_TAG);
 		const root = host.attachShadow({ mode: "closed" });
 		const style = document.createElement("style");
-		style.textContent = STYLE;
+		style.textContent = bannerCss(this.theme);
 		const layer = document.createElement("div");
 		layer.className = "layer";
 		layer.setAttribute("aria-hidden", "true");
@@ -13440,6 +13509,7 @@ var ImpersonationBanner = class ImpersonationBanner {
 			corner.className = `corner ${side}`;
 			corners.append(corner);
 		}
+		if (this.theme.noPageShift || this.theme.radiusPx <= 0) corners.remove();
 		const bar = document.createElement("div");
 		bar.className = "bar";
 		bar.setAttribute("role", "alert");
@@ -13452,7 +13522,7 @@ var ImpersonationBanner = class ImpersonationBanner {
 		text.className = "text";
 		const button = document.createElement("button");
 		button.type = "button";
-		button.textContent = "Stop";
+		button.textContent = this.theme.stopLabel;
 		button.addEventListener("click", () => {
 			button.disabled = true;
 			this.onStop().finally(() => {
@@ -13480,20 +13550,24 @@ var ImpersonationBanner = class ImpersonationBanner {
 		const root = document.documentElement;
 		const body = document.body;
 		if (!root || !body) return;
+		const { heightPx, radiusPx, background, noPageShift } = this.theme;
+		root.style.setProperty("--sp00ky-impersonation-banner-height", `${heightPx}px`);
+		if (noPageShift) return;
 		this.saved = {
 			html: root.getAttribute("style"),
 			body: body.getAttribute("style")
 		};
 		const surface = resolveSurface(root, body);
-		root.style.setProperty("--sp00ky-impersonation-banner-height", `${BANNER_HEIGHT_PX}px`);
-		root.style.setProperty("background-image", STRIPES, "important");
-		root.style.setProperty("padding-top", `${BANNER_HEIGHT_PX}px`, "important");
+		root.style.setProperty("background-image", background, "important");
+		root.style.setProperty("padding-top", `${heightPx}px`, "important");
 		root.style.setProperty("box-sizing", "border-box", "important");
 		body.style.setProperty("background-color", surface, "important");
-		body.style.setProperty("border-radius", `${PAGE_RADIUS_PX}px ${PAGE_RADIUS_PX}px 0 0`, "important");
-		body.style.setProperty("clip-path", `inset(0 round ${PAGE_RADIUS_PX}px ${PAGE_RADIUS_PX}px 0 0)`, "important");
+		if (radiusPx > 0) {
+			body.style.setProperty("border-radius", `${radiusPx}px ${radiusPx}px 0 0`, "important");
+			body.style.setProperty("clip-path", `inset(0 round ${radiusPx}px ${radiusPx}px 0 0)`, "important");
+		}
 		body.style.setProperty("box-shadow", "0 -6px 18px rgba(0, 0, 0, .35)", "important");
-		body.style.setProperty("min-height", `calc(100vh - ${BANNER_HEIGHT_PX}px)`, "important");
+		body.style.setProperty("min-height", `calc(100vh - ${heightPx}px)`, "important");
 	}
 };
 /** Put an element's inline styles back exactly as they were. */
@@ -13519,10 +13593,26 @@ function isTransparent(color) {
 	const parts = color.match(/[\d.]+/g);
 	return !!parts && parts.length === 4 && Number(parts[3]) === 0;
 }
-function bold(value) {
-	const b = document.createElement("b");
-	b.textContent = value;
-	return b;
+/**
+* The label, with every `<b>…</b>`-free segment as a text node and the record
+* ids emphasised. The label is a plain string (an app's own function can
+* return anything), so it never reaches the DOM as markup: `**bold**` marks
+* emphasis instead.
+*/
+function labelNodes(label) {
+	return labelSegments(label).map(({ text, bold }) => {
+		if (!bold) return document.createTextNode(text);
+		const b = document.createElement("b");
+		b.textContent = text;
+		return b;
+	});
+}
+/** The label split into plain and emphasised runs. Pure, so it is unit tested. */
+function labelSegments(label) {
+	return label.split(/\*\*(.+?)\*\*/g).map((text, i) => ({
+		text,
+		bold: i % 2 === 1
+	})).filter((part) => part.text !== "");
 }
 
 //#endregion
@@ -13546,6 +13636,8 @@ var Sp00kyClient = class {
 	appReleases;
 	/** Teardown for subscriptions the client itself owns. */
 	disposers = [];
+	/** Assigned in `wireAdapters`, which the constructor always runs. */
+	impersonationBanner;
 	devTools;
 	hub = null;
 	forwarder = null;
@@ -13656,7 +13748,8 @@ var Sp00kyClient = class {
 			type: "AuthFlip",
 			userId
 		}));
-		const banner = new ImpersonationBanner(() => s.auth.stopImpersonating());
+		this.impersonationBanner = new ImpersonationBanner(() => s.auth.stopImpersonating(), this.config.impersonationBanner);
+		const banner = this.impersonationBanner;
 		this.disposers.push(s.auth.subscribeImpersonation((info) => banner.update(info)), () => banner.unmount());
 		this.runtime.on("tabs:broadcast", (e) => {
 			if (e.type !== "tabs:broadcast") return;
@@ -13910,6 +14003,16 @@ var Sp00kyClient = class {
 		this.assertRawRemoteAllowed("remoteQuery");
 		return this.services.remote.query(sql, vars);
 	}
+	/**
+	* Tell the client that the app's own impersonation banner is on screen.
+	* Only meaningful with `impersonationBanner: { mode: 'custom' }`, where it
+	* cancels the fallback that would otherwise show the built-in banner. Call
+	* it while the custom banner is rendered (the Solid `useImpersonation`
+	* hook does it for you with `rendersBanner: true`).
+	*/
+	acknowledgeImpersonationBanner() {
+		this.impersonationBanner.acknowledge();
+	}
 	feature(key, options) {
 		return this.featureFlags.feature(key, options);
 	}

package/dist/types.d.ts

@@ -1,6 +1,140 @@
 import { QueryPlan, QueryPlan as QueryPlan$1, RecordId, SchemaStructure, WhereNode } from "@spooky-sync/query-builder";
 import { Level as Level$1, LoggerOptions } from "pino";
 
+//#region src/modules/auth/impersonation.d.ts
+
+/**
+ * Admin impersonation, client side.
+ *
+ * The server does the enforcing (see `impersonation_remote.surql` in the CLI):
+ * an admin calls `fn::_00_impersonate::start`, receives a token for the
+ * `_00_impersonate` access method, and authenticates with it, so `$auth.id` is
+ * the target user. Everything here is state and timers around that:
+ *
+ * - the admin's own token is kept under {@link ORIGIN_TOKEN_KEY} so Stop (and a
+ *   reload in between) can return to it;
+ * - the impersonation state is derived from the token's claims, never stored
+ *   separately, so it cannot disagree with the session actually in use;
+ * - the token is re-signed before it expires, and the session is polled so a
+ *   stop or revocation made elsewhere reaches an open WebSocket quickly.
+ */
+/** Access method impersonation tokens are issued for. */
+declare const IMPERSONATION_ACCESS = "_00_impersonate";
+/** Persistence key holding the admin's own token while impersonating. */
+declare const ORIGIN_TOKEN_KEY = "sp00ky_auth_token_origin";
+/** How often an active impersonation re-checks its session on the server. */
+declare const SESSION_POLL_MS = 60000;
+interface ImpersonationInfo {
+  /** `_00_impersonation:<id>` the session is bound to. */
+  session: string;
+  /** Record id being impersonated. */
+  target: string;
+  /** Record id of the admin. */
+  admin: string;
+  /** When the current token expires (it is renewed before then). */
+  tokenExpiresAt: Date | null;
+}
+interface TokenClaims {
+  access: string | null;
+  userId: string | null;
+  exp: number | null;
+  impersonation: {
+    session: string;
+    admin: string;
+  } | null;
+}
+/**
+ * Read the claims of a SurrealDB record-access JWT WITHOUT verifying it. The
+ * server still enforces the token on every request; this is only so the client
+ * can act on what it already holds before a round trip completes.
+ *
+ * Returns nulls on any malformed input.
+ */
+declare function decodeTokenClaims(token: string): TokenClaims;
+/** The impersonation a token represents, or null for a regular session. */
+declare function impersonationFromToken(token: string | null): ImpersonationInfo | null;
+/** Same impersonation, for change detection (renewals only move the expiry). */
+declare function sameImpersonation(a: ImpersonationInfo | null, b: ImpersonationInfo | null): boolean;
+/**
+ * When to renew a token expiring at `expSecs`: at 80% of its remaining life,
+ * never sooner than 5s from now, and immediately once it is inside that.
+ */
+declare function renewDelayMs(expSecs: number, nowMs: number): number;
+interface ImpersonationTimerHost {
+  /** Current impersonation, or null. */
+  current(): ImpersonationInfo | null;
+  /** Re-sign the token. Rejects when the session has ended. */
+  renew(): Promise<void>;
+  /** Whether the server still considers the session live. */
+  stillActive(): Promise<boolean>;
+  /** Leave the impersonation because the server ended it. */
+  endedRemotely(reason: string): Promise<void>;
+  /** Whether a failure was a reachability problem (retry) rather than an answer. */
+  isNetworkError(error: unknown): boolean;
+}
+/**
+ * The two timers an active impersonation needs. `sync()` is called whenever
+ * the auth state changes and arms or clears them to match.
+ */
+declare class ImpersonationTimers {
+  private host;
+  private renewTimer;
+  private pollTimer;
+  private armedFor;
+  constructor(host: ImpersonationTimerHost);
+  sync(): void;
+  clear(): void;
+  private renew;
+  private poll;
+}
+//#endregion
+//#region src/modules/auth/impersonation-banner.d.ts
+/**
+ * Restyling of the built-in banner. Every field is optional; anything unset
+ * keeps the default. Colours are plain CSS values, so a project can pass its
+ * own tokens (`var(--brand-warning)`) as long as they resolve at the document
+ * level.
+ */
+interface ImpersonationBannerTheme {
+  /** Height of the bar, and therefore how far the page is pushed down. */
+  heightPx?: number;
+  /** Radius of the page's new top corners. `0` squares them off. */
+  radiusPx?: number;
+  /** Background of the warning layer. Any CSS `background` value. */
+  background?: string;
+  /** Background of the pill the text sits in. */
+  pill?: string;
+  /** Text colour inside the pill. */
+  pillText?: string;
+  /** Background of the Stop button. */
+  accent?: string;
+  /** Text colour of the Stop button. */
+  accentText?: string;
+  /** Label for the Stop button. Defaults to `Stop`. */
+  stopLabel?: string;
+  /** The warning sentence. Defaults to `Impersonating <target> as <admin>`. */
+  label?: (info: ImpersonationInfo) => string;
+  /** Drop the page shift and the rounded corners, leaving only the bar.
+   *  The CSS variable is still published, so the app can do its own offset. */
+  noPageShift?: boolean;
+}
+interface ImpersonationBannerConfig {
+  /**
+   * - `'default'` renders the built-in banner.
+   * - `'custom'` leaves the page alone so the app can render its own from
+   *   `useImpersonation()` / `auth.subscribeImpersonation`. Acknowledge it
+   *   with `client.acknowledgeImpersonationBanner()` while it is on screen;
+   *   if nothing acknowledges within {@link CUSTOM_BANNER_GRACE_MS}, the
+   *   built-in banner appears, on the assumption that the custom one failed
+   *   to render rather than that nobody should be warned.
+   * - `'none'` renders nothing, ever. The app takes over responsibility for
+   *   telling whoever is looking at the page that it is not their session.
+   */
+  mode?: 'default' | 'custom' | 'none';
+  /** Restyle the built-in banner (also used if `custom` falls back). */
+  theme?: ImpersonationBannerTheme;
+}
+//#endregion
 //#region src/events/index.d.ts
 /**
  * Utility type to define the payload structure of an event.
@@ -643,6 +777,17 @@ interface Sp00kyConfig<S extends SchemaStructure> {
    * flag is `true`. Defaults to `false`.
    */
   allowRawRemote?: boolean;
+  /**
+   * How the "you are impersonating" warning is shown while an admin acts as
+   * another user. The built-in one (hazard stripes at the top, the page
+   * shifted down onto them) needs no configuration; this is for restyling it,
+   * or replacing it with the app's own.
+   *
+   * See `ImpersonationBannerConfig`. Replacing it does not mean "no warning":
+   * if the app has not acknowledged its own banner shortly after impersonation
+   * starts, the built-in one appears anyway.
+   */
+  impersonationBanner?: ImpersonationBannerConfig;
   /**
    * Surface sustained sync failures as a "degraded" health status that the app
    * can observe via `subscribeToSyncHealth` (or the client-solid
@@ -1103,4 +1248,4 @@ interface DebounceOptions {
   delay?: number;
 }
 //#endregion
-export { RunOptions as A, SyncHealthStatus as B, QueryTimeToLive as C, RecordVersionArray as D, ReconnectConfig as E, StorageHealth as F, DatabaseEventTypes as G, UpdateOptions as H, StorageHealthStatus as I, EventSystem as J, SealedQuery as K, StoreType as L, Sp00kyConfig as M, Sp00kyQueryResult as N, RecordVersionDiff as O, Sp00kyQueryResultPromise as P, SyncHealth as R, QueryStatusCallback as S, QueryUpdateCallback as T, LocalStore as U, TimingPhase as V, DatabaseEventSystem as W, QueryConfig as _, Level$1 as a, QueryState as b, MutationCallback as c, PersistenceClient as d, PhaseStat as f, QueryAuthorityCallback as g, PreloadRefresh as h, InlineRow as i, ServerViewMeta as j, RegistrationTimings as k, MutationEvent as l, PreloadOptions as m, DebounceOptions as n, MATERIALIZATION_SAMPLE_WINDOW as o, PinoTransmit as p, EventDefinition as q, EventSubscriptionOptions as r, MembershipOutcome as s, ConnectionState as t, MutationEventType as u, QueryConfigRecord as v, QueryTimings as w, QueryStatus as x, QueryHash as y, SyncHealthConfig as z };
+export { ORIGIN_TOKEN_KEY as $, RunOptions as A, SyncHealthStatus as B, QueryTimeToLive as C, RecordVersionArray as D, ReconnectConfig as E, StorageHealth as F, DatabaseEventTypes as G, UpdateOptions as H, StorageHealthStatus as I, EventSystem as J, SealedQuery as K, StoreType as L, Sp00kyConfig as M, Sp00kyQueryResult as N, RecordVersionDiff as O, Sp00kyQueryResultPromise as P, ImpersonationTimers as Q, SyncHealth as R, QueryStatusCallback as S, QueryUpdateCallback as T, LocalStore as U, TimingPhase as V, DatabaseEventSystem as W, ImpersonationInfo as X, IMPERSONATION_ACCESS as Y, ImpersonationTimerHost as Z, QueryConfig as _, Level$1 as a, sameImpersonation as at, QueryState as b, MutationCallback as c, PersistenceClient as d, SESSION_POLL_MS as et, PhaseStat as f, QueryAuthorityCallback as g, PreloadRefresh as h, InlineRow as i, renewDelayMs as it, ServerViewMeta as j, RegistrationTimings as k, MutationEvent as l, PreloadOptions as m, DebounceOptions as n, decodeTokenClaims as nt, MATERIALIZATION_SAMPLE_WINDOW as o, PinoTransmit as p, EventDefinition as q, EventSubscriptionOptions as r, impersonationFromToken as rt, MembershipOutcome as s, ConnectionState as t, TokenClaims as tt, MutationEventType as u, QueryConfigRecord as v, QueryTimings as w, QueryStatus as x, QueryHash as y, SyncHealthConfig as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/core",
-  "version": "0.0.1-canary.262",
+  "version": "0.0.1-canary.264",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -63,8 +63,8 @@
     }
   },
   "dependencies": {
-    "@spooky-sync/query-builder": "0.0.1-canary.262",
-    "@spooky-sync/ssp-wasm": "0.0.1-canary.262",
+    "@spooky-sync/query-builder": "0.0.1-canary.264",
+    "@spooky-sync/ssp-wasm": "0.0.1-canary.264",
     "@sqlite.org/sqlite-wasm": "3.53.0-build1",
     "@surrealdb/wasm": "^3.0.3",
     "blurhash": "^2.0.5",

package/src/client/sp00ky-client.ts

@@ -81,6 +81,8 @@ export class Sp00kyClient<S extends SchemaStructure> {
   private readonly appReleases: AppReleaseModule<S>;
   /** Teardown for subscriptions the client itself owns. */
   private readonly disposers: Array<() => void> = [];
+  /** Assigned in `wireAdapters`, which the constructor always runs. */
+  private impersonationBanner!: ImpersonationBanner;
   private readonly devTools: DevToolsService;
   private hub: LeaderSyncHub | null = null;
   private forwarder: SyncForwarder | null = null;
@@ -177,10 +179,18 @@ export class Sp00kyClient<S extends SchemaStructure> {
     s.streamProcessor.addReceiver(receiver);
     s.connectionSupervisor.subscribe((state) => void this.runtime.dispatch({ type: 'ConnectionChanged', state }));
     s.auth.subscribe((userId) => void this.runtime.dispatch({ type: 'AuthFlip', userId }));
-    // The impersonation banner is not optional: whoever is looking at the page
-    // must be able to tell, and leave, whatever the app renders.
-    const banner = new ImpersonationBanner(() => s.auth.stopImpersonating());
-    this.disposers.push(s.auth.subscribeImpersonation((info) => banner.update(info)), () => banner.unmount());
+    // Whoever is looking at the page should be able to tell, and leave. The
+    // app can restyle this, replace it (`mode: 'custom'`, with a fallback if
+    // its own never renders) or take the job over entirely (`mode: 'none'`).
+    this.impersonationBanner = new ImpersonationBanner(
+      () => s.auth.stopImpersonating(),
+      this.config.impersonationBanner
+    );
+    const banner = this.impersonationBanner;
+    this.disposers.push(
+      s.auth.subscribeImpersonation((info) => banner.update(info)),
+      () => banner.unmount()
+    );
     this.runtime.on('tabs:broadcast', (e) => {
       if (e.type !== 'tabs:broadcast') return;
       const msg = e.message as { type: string; records?: unknown[]; mutationId?: string };
@@ -468,6 +478,17 @@ export class Sp00kyClient<S extends SchemaStructure> {
     return this.services.remote.query<T>(sql, vars);
   }
 
+  /**
+   * Tell the client that the app's own impersonation banner is on screen.
+   * Only meaningful with `impersonationBanner: { mode: 'custom' }`, where it
+   * cancels the fallback that would otherwise show the built-in banner. Call
+   * it while the custom banner is rendered (the Solid `useImpersonation`
+   * hook does it for you with `rendersBanner: true`).
+   */
+  acknowledgeImpersonationBanner(): void {
+    this.impersonationBanner.acknowledge();
+  }
+
   feature(key: string, options?: FeatureFlagOptions): FeatureFlagHandle {
     return this.featureFlags.feature(key, options);
   }

package/src/modules/auth/impersonation-banner.ts

@@ -1,31 +1,106 @@
 import type { ImpersonationInfo } from './impersonation';
 
-/** Height of the warning layer the page is shifted down by. Also published as
- *  the CSS variable `--sp00ky-impersonation-banner-height` on `<html>` (`0px`
- *  when hidden), so an app can offset its own fixed header. */
+/** Default height of the warning layer the page is shifted down by. The
+ *  effective height is published as the CSS variable
+ *  `--sp00ky-impersonation-banner-height` on `<html>` (`0px` when hidden), so
+ *  an app can offset its own fixed header. */
 export const BANNER_HEIGHT_PX = 44;
 
-/** Radius of the page's new top corners. */
-const PAGE_RADIUS_PX = 14;
+/** Default radius of the page's new top corners. */
+export const PAGE_RADIUS_PX = 14;
+
+/** Default hazard stripes: the warning layer, and the `<html>` backdrop the
+ *  page's rounded corners reveal. */
+export const BANNER_STRIPES =
+  'repeating-linear-gradient(45deg, #f2b600 0 14px, #1c1403 14px 28px)';
 
 const HOST_TAG = 'sp00ky-impersonation-banner';
 
-/** Hazard stripes: the warning layer, and the `<html>` backdrop the page's
- *  rounded corners reveal. */
-const STRIPES = 'repeating-linear-gradient(45deg, #f2b600 0 14px, #1c1403 14px 28px)';
+/** How long a `custom` banner has to acknowledge itself before the built-in
+ *  one is shown anyway. Long enough for a first paint, short enough that
+ *  nobody browses unwarned. */
+export const CUSTOM_BANNER_GRACE_MS = 2500;
+
+/**
+ * Restyling of the built-in banner. Every field is optional; anything unset
+ * keeps the default. Colours are plain CSS values, so a project can pass its
+ * own tokens (`var(--brand-warning)`) as long as they resolve at the document
+ * level.
+ */
+export interface ImpersonationBannerTheme {
+  /** Height of the bar, and therefore how far the page is pushed down. */
+  heightPx?: number;
+  /** Radius of the page's new top corners. `0` squares them off. */
+  radiusPx?: number;
+  /** Background of the warning layer. Any CSS `background` value. */
+  background?: string;
+  /** Background of the pill the text sits in. */
+  pill?: string;
+  /** Text colour inside the pill. */
+  pillText?: string;
+  /** Background of the Stop button. */
+  accent?: string;
+  /** Text colour of the Stop button. */
+  accentText?: string;
+  /** Label for the Stop button. Defaults to `Stop`. */
+  stopLabel?: string;
+  /** The warning sentence. Defaults to `Impersonating <target> as <admin>`. */
+  label?: (info: ImpersonationInfo) => string;
+  /** Drop the page shift and the rounded corners, leaving only the bar.
+   *  The CSS variable is still published, so the app can do its own offset. */
+  noPageShift?: boolean;
+}
+
+export interface ImpersonationBannerConfig {
+  /**
+   * - `'default'` renders the built-in banner.
+   * - `'custom'` leaves the page alone so the app can render its own from
+   *   `useImpersonation()` / `auth.subscribeImpersonation`. Acknowledge it
+   *   with `client.acknowledgeImpersonationBanner()` while it is on screen;
+   *   if nothing acknowledges within {@link CUSTOM_BANNER_GRACE_MS}, the
+   *   built-in banner appears, on the assumption that the custom one failed
+   *   to render rather than that nobody should be warned.
+   * - `'none'` renders nothing, ever. The app takes over responsibility for
+   *   telling whoever is looking at the page that it is not their session.
+   */
+  mode?: 'default' | 'custom' | 'none';
+  /** Restyle the built-in banner (also used if `custom` falls back). */
+  theme?: ImpersonationBannerTheme;
+}
+
+interface ResolvedTheme extends Required<Omit<ImpersonationBannerTheme, 'label' | 'stopLabel'>> {
+  stopLabel: string;
+  label: (info: ImpersonationInfo) => string;
+}
+
+function resolveTheme(theme: ImpersonationBannerTheme = {}): ResolvedTheme {
+  return {
+    heightPx: theme.heightPx ?? BANNER_HEIGHT_PX,
+    radiusPx: theme.radiusPx ?? PAGE_RADIUS_PX,
+    background: theme.background ?? BANNER_STRIPES,
+    pill: theme.pill ?? 'rgba(14, 11, 2, .88)',
+    pillText: theme.pillText ?? '#fde68a',
+    accent: theme.accent ?? '#fde68a',
+    accentText: theme.accentText ?? '#1c1403',
+    stopLabel: theme.stopLabel ?? 'Stop',
+    noPageShift: theme.noPageShift ?? false,
+    label: theme.label ?? ((info) => `Impersonating **${info.target}** as ${info.admin}`),
+  };
+}
 
 /** Keeps only the area OUTSIDE a corner's curve, so the nub is striped and
  *  everything inside the curve stays the app's own. `center` is the curve's
  *  centre inside the corner square. */
-function cornerMask(center: string): string {
-  return `radial-gradient(circle ${PAGE_RADIUS_PX}px at ${center}, transparent 0 ${PAGE_RADIUS_PX}px, #000 ${PAGE_RADIUS_PX}px)`;
+function cornerMask(center: string, radius: number): string {
+  return `radial-gradient(circle ${radius}px at ${center}, transparent 0 ${radius}px, #000 ${radius}px)`;
 }
 
 // The shadow root keeps app CSS away from the bar, but the host element itself
 // is in the page and matches the page's selectors (`div { display: none }`).
 // An `!important` rule on `:host` wins over the page's own `!important`
 // (inner tree context), which keeps the host rendered whatever the app says.
-const STYLE = `
+export function bannerCss(t: ResolvedTheme): string {
+  return `
 :host {
   all: initial !important;
   display: block !important;
@@ -37,7 +112,7 @@ const STYLE = `
 }
 .layer {
   position: fixed; inset: 0 0 auto 0; z-index: 2147483646; pointer-events: none;
-  height: ${BANNER_HEIGHT_PX}px; background: ${STRIPES};
+  height: ${t.heightPx}px; background: ${t.background};
 }
 /* The page's rounded top corners, drawn over whatever the app puts there.
    The body element's own border-radius rounds its background, but a fixed app
@@ -45,25 +120,25 @@ const STYLE = `
    square masked down to the nub OUTSIDE the corner's curve, so the app's own
    colour still shows inside it. */
 .corners {
-  position: fixed; left: 0; right: 0; top: ${BANNER_HEIGHT_PX}px;
-  height: ${PAGE_RADIUS_PX}px; z-index: 2147483646; pointer-events: none;
+  position: fixed; left: 0; right: 0; top: ${t.heightPx}px;
+  height: ${t.radiusPx}px; z-index: 2147483646; pointer-events: none;
 }
 .corner {
-  position: absolute; top: 0; width: ${PAGE_RADIUS_PX}px; height: ${PAGE_RADIUS_PX}px;
-  background: ${STRIPES};
+  position: absolute; top: 0; width: ${t.radiusPx}px; height: ${t.radiusPx}px;
+  background: ${t.background};
 }
 .corner.left {
   left: 0;
-  -webkit-mask: ${cornerMask('100% 100%')};
-  mask: ${cornerMask('100% 100%')};
+  -webkit-mask: ${cornerMask('100% 100%', t.radiusPx)};
+  mask: ${cornerMask('100% 100%', t.radiusPx)};
 }
 .corner.right {
   right: 0;
-  -webkit-mask: ${cornerMask('0% 100%')};
-  mask: ${cornerMask('0% 100%')};
+  -webkit-mask: ${cornerMask('0% 100%', t.radiusPx)};
+  mask: ${cornerMask('0% 100%', t.radiusPx)};
 }
 .bar {
-  position: fixed; inset: 0 0 auto 0; height: ${BANNER_HEIGHT_PX}px; z-index: 2147483647;
+  position: fixed; inset: 0 0 auto 0; height: ${t.heightPx}px; z-index: 2147483647;
   display: flex; align-items: center; justify-content: center; gap: 10px;
   padding: 0 12px; box-sizing: border-box;
   font: 600 13px/1 system-ui, -apple-system, "Segoe UI", sans-serif;
@@ -71,25 +146,25 @@ const STYLE = `
 .pill {
   display: flex; align-items: center; gap: 8px; min-width: 0; max-width: 100%;
   padding: 6px 10px; border-radius: 999px;
-  background: rgba(14, 11, 2, .88); color: #fde68a;
+  background: ${t.pill}; color: ${t.pillText};
   box-shadow: 0 1px 6px rgba(0, 0, 0, .45);
 }
 .sign { flex: none; font-size: 14px; line-height: 1; }
 .text { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; min-width: 0; }
-.text b { color: #fff; font-weight: 800; }
 button {
   flex: none; cursor: pointer; border: 0; border-radius: 999px;
-  background: #fde68a; color: #1c1403;
+  background: ${t.accent}; color: ${t.accentText};
   font: 800 12px/1 system-ui, sans-serif; padding: 7px 12px;
   box-shadow: 0 1px 6px rgba(0, 0, 0, .45);
 }
-button:hover { background: #fff; }
+button:hover { filter: brightness(1.12); }
 button:disabled { opacity: .6; cursor: progress; }
 @media (max-width: 520px) {
   .bar { gap: 6px; padding: 0 8px; }
   .pill { padding: 5px 8px; }
 }
 `;
+}
 
 /**
  * The "you are impersonating" warning.
@@ -109,8 +184,32 @@ export class ImpersonationBanner {
   private text: HTMLElement | null = null;
   /** `style` attributes as the page had them before the shift. */
   private saved: { html: string | null; body: string | null } | null = null;
+  private theme: ResolvedTheme;
+  private mode: 'default' | 'custom' | 'none';
+  /** Grace timer for `custom` mode. */
+  private fallbackTimer: ReturnType<typeof setTimeout> | null = null;
+  /** The app said its own banner is on screen for this impersonation. */
+  private acknowledged = false;
+  private warnedAboutNone = false;
+
+  constructor(
+    private onStop: () => Promise<void>,
+    config: ImpersonationBannerConfig = {}
+  ) {
+    this.mode = config.mode ?? 'default';
+    this.theme = resolveTheme(config.theme);
+  }
 
-  constructor(private onStop: () => Promise<void>) {}
+  /**
+   * The app's own banner is rendered. Cancels the `custom`-mode fallback, and
+   * removes the built-in banner if the fallback already fired (a slow first
+   * paint, say). No-op in the other modes.
+   */
+  acknowledge(): void {
+    this.acknowledged = true;
+    this.clearFallback();
+    if (this.mode === 'custom') this.teardown();
+  }
 
   static supported(): boolean {
     return typeof document !== 'undefined' && typeof document.createElement === 'function';
@@ -119,20 +218,53 @@ export class ImpersonationBanner {
   update(info: ImpersonationInfo | null): void {
     if (!ImpersonationBanner.supported()) return;
     if (!info) {
+      this.acknowledged = false;
       this.unmount();
       return;
     }
+    if (this.mode === 'none') {
+      // The app owns the warning entirely. Said once, loudly, because the
+      // page now looks like an ordinary session of someone else's account.
+      if (!this.warnedAboutNone) {
+        this.warnedAboutNone = true;
+        // oxlint-disable-next-line no-console
+        console.warn(
+          '[sp00ky] impersonation is active and impersonationBanner.mode is "none": ' +
+            'nothing marks this page as another user\'s session.'
+        );
+      }
+      return;
+    }
+    if (this.mode === 'custom' && !this.acknowledged) {
+      // Give the app its grace period, then warn anyway.
+      if (!this.fallbackTimer && !this.host) {
+        this.fallbackTimer = setTimeout(() => {
+          this.fallbackTimer = null;
+          if (!this.acknowledged) this.render(info);
+        }, CUSTOM_BANNER_GRACE_MS);
+      }
+      return;
+    }
+    if (this.mode === 'custom') return;
+    this.render(info);
+  }
+
+  unmount(): void {
+    this.clearFallback();
+    this.teardown();
+  }
+
+  /** Mount (if needed) and write the current identities into the bar. */
+  private render(info: ImpersonationInfo): void {
     this.mount();
     const text = this.text!;
-    text.replaceChildren(
-      document.createTextNode('Impersonating '),
-      bold(info.target),
-      document.createTextNode(` as ${info.admin}`)
-    );
-    text.title = `Impersonating ${info.target} as ${info.admin}. Every write is audited.`;
+    text.textContent = '';
+    text.append(...labelNodes(this.theme.label(info)));
+    text.title = `${this.theme.label(info)}. Every write is audited.`;
   }
 
-  unmount(): void {
+  /** Remove the bar and undo the page shift. */
+  private teardown(): void {
     this.host?.remove();
     this.host = this.text = null;
     if (typeof document === 'undefined') return;
@@ -144,12 +276,17 @@ export class ImpersonationBanner {
     document.documentElement?.style.setProperty('--sp00ky-impersonation-banner-height', '0px');
   }
 
+  private clearFallback(): void {
+    if (this.fallbackTimer) clearTimeout(this.fallbackTimer);
+    this.fallbackTimer = null;
+  }
+
   private mount(): void {
     if (this.host?.isConnected) return;
     const host = document.createElement(HOST_TAG);
     const root = host.attachShadow({ mode: 'closed' });
     const style = document.createElement('style');
-    style.textContent = STYLE;
+    style.textContent = bannerCss(this.theme);
 
     // The striped ground the bar's text sits on: fixed, so it stays put while
     // the page scrolls underneath. Never takes a click.
@@ -164,6 +301,7 @@ export class ImpersonationBanner {
       corner.className = `corner ${side}`;
       corners.append(corner);
     }
+    if (this.theme.noPageShift || this.theme.radiusPx <= 0) corners.remove();
 
     const bar = document.createElement('div');
     bar.className = 'bar';
@@ -177,7 +315,7 @@ export class ImpersonationBanner {
     text.className = 'text';
     const button = document.createElement('button');
     button.type = 'button';
-    button.textContent = 'Stop';
+    button.textContent = this.theme.stopLabel;
     button.addEventListener('click', () => {
       button.disabled = true;
       this.onStop().finally(() => {
@@ -210,31 +348,33 @@ export class ImpersonationBanner {
     const root = document.documentElement;
     const body = document.body;
     if (!root || !body) return;
-    this.saved = { html: root.getAttribute('style'), body: body.getAttribute('style') };
+    const { heightPx, radiusPx, background, noPageShift } = this.theme;
+    // Published even when the shift is off, so an app doing its own offset
+    // has one number to read either way.
+    root.style.setProperty('--sp00ky-impersonation-banner-height', `${heightPx}px`);
+    if (noPageShift) return;
 
+    this.saved = { html: root.getAttribute('style'), body: body.getAttribute('style') };
     const surface = resolveSurface(root, body);
-    root.style.setProperty('--sp00ky-impersonation-banner-height', `${BANNER_HEIGHT_PX}px`);
-    root.style.setProperty('background-image', STRIPES, 'important');
-    root.style.setProperty('padding-top', `${BANNER_HEIGHT_PX}px`, 'important');
+    root.style.setProperty('background-image', background, 'important');
+    root.style.setProperty('padding-top', `${heightPx}px`, 'important');
     root.style.setProperty('box-sizing', 'border-box', 'important');
 
     body.style.setProperty('background-color', surface, 'important');
-    body.style.setProperty(
-      'border-radius',
-      `${PAGE_RADIUS_PX}px ${PAGE_RADIUS_PX}px 0 0`,
-      'important'
-    );
-    // Clips the app's own content — a fixed header included — to the rounded
-    // top, which is what makes the page read as a sheet over the stripes.
-    body.style.setProperty(
-      'clip-path',
-      `inset(0 round ${PAGE_RADIUS_PX}px ${PAGE_RADIUS_PX}px 0 0)`,
-      'important'
-    );
+    if (radiusPx > 0) {
+      body.style.setProperty('border-radius', `${radiusPx}px ${radiusPx}px 0 0`, 'important');
+      // Clips the app's own content — a fixed header included — to the rounded
+      // top, which is what makes the page read as a sheet over the stripes.
+      body.style.setProperty(
+        'clip-path',
+        `inset(0 round ${radiusPx}px ${radiusPx}px 0 0)`,
+        'important'
+      );
+    }
     body.style.setProperty('box-shadow', '0 -6px 18px rgba(0, 0, 0, .35)', 'important');
     // An app sized to `100vh` would otherwise overflow by the bar's height and
     // put a scrollbar on a page that had none.
-    body.style.setProperty('min-height', `calc(100vh - ${BANNER_HEIGHT_PX}px)`, 'important');
+    body.style.setProperty('min-height', `calc(100vh - ${heightPx}px)`, 'important');
   }
 }
 
@@ -266,8 +406,28 @@ function isTransparent(color: string): boolean {
   return !!parts && parts.length === 4 && Number(parts[3]) === 0;
 }
 
-function bold(value: string): HTMLElement {
-  const b = document.createElement('b');
-  b.textContent = value;
-  return b;
+/**
+ * The label, with every `<b>…</b>`-free segment as a text node and the record
+ * ids emphasised. The label is a plain string (an app's own function can
+ * return anything), so it never reaches the DOM as markup: `**bold**` marks
+ * emphasis instead.
+ */
+function labelNodes(label: string): Node[] {
+  return labelSegments(label).map(({ text, bold }) => {
+    if (!bold) return document.createTextNode(text);
+    const b = document.createElement('b');
+    b.textContent = text;
+    return b;
+  });
+}
+
+/** The label split into plain and emphasised runs. Pure, so it is unit tested. */
+function labelSegments(label: string): Array<{ text: string; bold: boolean }> {
+  return label
+    .split(/\*\*(.+?)\*\*/g)
+    .map((text, i) => ({ text, bold: i % 2 === 1 }))
+    .filter((part) => part.text !== '');
 }
+
+/** Exported for unit tests only. */
+export const __test = { labelSegments, resolveTheme };

package/src/modules/auth/impersonation.test.ts

@@ -280,3 +280,39 @@ describe('timers', () => {
     timers.clear();
   });
 });
+
+describe('banner configuration', () => {
+  it('builds CSS from the theme, defaults included', async () => {
+    const { bannerCss, BANNER_STRIPES } = await import('./impersonation-banner');
+    // `bannerCss` takes a resolved theme; the client resolves it, so this
+    // pins the rendered output for a fully specified one.
+    const css = bannerCss({
+      heightPx: 60,
+      radiusPx: 0,
+      background: 'var(--brand-warning)',
+      pill: '#000',
+      pillText: '#fff',
+      accent: '#f00',
+      accentText: '#fff',
+      stopLabel: 'Leave',
+      noPageShift: true,
+      label: () => 'x',
+    });
+    expect(css).toContain('height: 60px; background: var(--brand-warning)');
+    expect(css).toContain('background: #000; color: #fff');
+    expect(css).not.toContain(BANNER_STRIPES);
+  });
+
+  it('emphasises the label between ** markers instead of parsing markup', async () => {
+    const { __test } = await import('./impersonation-banner');
+    // A label is a plain string an app supplies, so markup in it must stay text.
+    expect(__test.labelSegments('Impersonating **user:bob** as user:alice')).toEqual([
+      { text: 'Impersonating ', bold: false },
+      { text: 'user:bob', bold: true },
+      { text: ' as user:alice', bold: false },
+    ]);
+    expect(__test.labelSegments('<img src=x onerror=alert(1)>')).toEqual([
+      { text: '<img src=x onerror=alert(1)>', bold: false },
+    ]);
+  });
+});

package/src/types.ts

@@ -1,3 +1,4 @@
+import type { ImpersonationBannerConfig } from './modules/auth/impersonation-banner';
 import type { RecordId, SchemaStructure, QueryPlan } from '@spooky-sync/query-builder';
 import type { Level, LoggerOptions } from 'pino';
 import type { PushEventOptions } from './events/index';
@@ -331,6 +332,17 @@ export interface Sp00kyConfig<S extends SchemaStructure> {
    * flag is `true`. Defaults to `false`.
    */
   allowRawRemote?: boolean;
+  /**
+   * How the "you are impersonating" warning is shown while an admin acts as
+   * another user. The built-in one (hazard stripes at the top, the page
+   * shifted down onto them) needs no configuration; this is for restyling it,
+   * or replacing it with the app's own.
+   *
+   * See `ImpersonationBannerConfig`. Replacing it does not mean "no warning":
+   * if the app has not acknowledged its own banner shortly after impersonation
+   * starts, the built-in one appears anyway.
+   */
+  impersonationBanner?: ImpersonationBannerConfig;
   /**
    * Surface sustained sync failures as a "degraded" health status that the app
    * can observe via `subscribeToSyncHealth` (or the client-solid