caracms 0.0.0-stage → 0.2.0

package/src/editor/client/overlays/layer.ts

@@ -0,0 +1,437 @@
+/**
+ * The overlay layer: what the editor draws over the preview, inside each iframe
+ * (M2 Decision 6; Phase 3). One shared layer, which the editor's own marks
+ * (editor-marks.ts) and other modules (Phase 4: the block list's hover, insert
+ * points) draw into through a small API. See editor/README.md → Overlays.
+ *
+ *   overlays.set(channel, marks)    show these marks, replacing the channel's last ones
+ *   overlays.clear(channel)         show none of the channel's marks
+ *   overlays.addPainter(painter)    draw your own elements, positioned against a block, on every redraw
+ *   overlays.redraw()               draw again soon (a painter's own state changed)
+ *
+ * A child of the layer marked `data-cms-keep` (KEEP) is left where it is by every
+ * redraw, on top: the formatting bar of rich text on the page (rich-text-bar.ts).
+ *
+ * **Preview renders only.** The layer is created at run time by /admin in its own
+ * iframes; nothing of it is in any render, so the public build can't have it
+ * (Decision 17). In each frame it's one element, `#cms-overlays`, appended to
+ * `<html>` (outside `<body>`, so the driver's body morph never touches it), plus one
+ * `<style>` in `<head>` (never morphed either). It's absolutely positioned in
+ * document coordinates, so it scrolls with the page; `pointer-events: none`, except
+ * on the buttons marks and painters put there.
+ *
+ * **Constant size on screen** (M2 → Overlays): each frame is shown scaled, so the
+ * layer sets `--k` to 1 / that scale and every size in the CSS is `calc(var(--k) * Npx)`.
+ */
+import type { PreviewDriver, PreviewFrame } from '../preview/driver.ts';
+import type { StageLayout } from '../preview/layout.ts';
+import type { Store } from '../state/store.ts';
+import type { Width } from '../../types.ts';
+import { OVERLAY_CSS, OVERLAY_TOKENS } from './overlay-css.ts';
+import { blockElement, blockElements, fieldElement, skippedAnchor, skippedTop } from '../preview/markers.ts';
+
+export type MarkKind =
+	/** A block under the pointer (or its row in the block list): thin outline, a wash, a light tag. */
+	| 'hover'
+	/** The open block: 2px outline, a filled tag. */
+	| 'selected'
+	/** A field under the pointer inside the open block: a thin dashed ring. */
+	| 'field-hover'
+	/** The picked field: a 2px ring with the field's name above it. */
+	| 'picked'
+	/** The field being typed on the page: a soft ring, "Typing on the page". */
+	| 'typing'
+	/** Amber dashes with an amber chip: "Too long for mobile". */
+	| 'warn'
+	/** An unknown block, skipped on the page: an amber dashed line across the page where it would be, with a pill. */
+	| 'skipped';
+
+export interface Mark {
+	kind: MarkKind;
+	/** The block's index in the rendered document (`data-cms-block`). */
+	block: number;
+	/** A field in it (`data-cms-field`); the whole block when absent. */
+	field?: string | null;
+	/** The tag's, chip's or pill's text. None: no tag. */
+	label?: string;
+	/** `phone`: teal, for phone lines. */
+	tone?: 'phone';
+	/** The frames to draw it in. Default: all three. */
+	frames?: readonly Width[];
+	/** Makes the mark's label a button (the skipped pill opens its block). */
+	onClick?: (event: MouseEvent) => void;
+}
+
+export interface Rect {
+	left: number;
+	top: number;
+	width: number;
+	height: number;
+}
+
+/** What a painter gets, once per frame per redraw. */
+export interface OverlayContext {
+	frame: PreviewFrame;
+	width: Width;
+	/** The frame on screen (the others are drawn too, behind it). */
+	visible: boolean;
+	/** The frame's document. Create elements with `el()`, not the editor's `document`. */
+	doc: Document;
+	/** 1 / the frame's scale: multiply a size you want on screen by this. The CSS has `--k`. */
+	k: number;
+	/** A block's element (`[data-cms-block="i"]`), or null. A skipped block has none (see `skippedTop`). */
+	block(index: number): HTMLElement | null;
+	/** Where skipped block `index` would be, in the layer's coordinates (its comment, preview/markers.ts), or null. */
+	skippedTop(index: number): number | null;
+	/** A field's element inside a block, or null. */
+	field(index: number, field: string): HTMLElement | null;
+	/** Every block element on the page, in order. */
+	blocks(): HTMLElement[];
+	/** An element's box in the layer's coordinates (the document's), grown by `pad` px on screen. */
+	rect(el: Element, pad?: number): Rect;
+	/** `left/top/width/height` as a style string for a Rect. */
+	place(rect: Rect): string;
+	/** An element in the frame's document: `el('div', 'cms-ins', { left: '0px' })`. */
+	el<K extends keyof HTMLElementTagNameMap>(tag: K, className?: string, style?: Partial<Record<string, string>>): HTMLElementTagNameMap[K];
+}
+
+/** Returns the elements to put in the layer for this frame (or nothing). Called on every redraw. */
+export type OverlayPainter = (ctx: OverlayContext) => Node | readonly Node[] | null | undefined | void;
+
+export interface Overlays {
+	set(channel: string, marks: readonly Mark[]): void;
+	clear(channel: string): void;
+	/** Returns a remove. Painters run after the marks, in the order added. */
+	addPainter(painter: OverlayPainter): () => void;
+	/** Redraw on the next animation frame (coalesced). */
+	redraw(): void;
+	/** Redraw now (tests). */
+	flush(): void;
+	/** The layer element in a frame, if it's mounted. */
+	layerOf(frame: PreviewFrame): HTMLElement | null;
+	/** Unmount from every frame and stop. */
+	destroy(): void;
+}
+
+export const LAYER_ID = 'cms-overlays';
+/** A child of the layer with this attribute is left alone by every redraw (it draws itself). */
+export const KEEP = 'data-cms-keep';
+const STYLE_ID = 'cms-overlays-css';
+const FONT_FAMILY = 'caracms UI';
+
+/**
+ * Mark kinds in drawing order (later ones on top), as the mockup draws them: the
+ * painters' elements (insert points, the empty page's invitation) go between the
+ * block marks (up to `selected`) and the field marks, so a picked field's ring and
+ * a warning sit over an insert point.
+ */
+const ORDER: MarkKind[] = ['skipped', 'hover', 'selected', 'field-hover', 'picked', 'typing', 'warn'];
+const UNDER_PAINTERS = new Set<MarkKind>(['skipped', 'hover', 'selected']);
+
+export function createOverlays(options: {
+	driver: PreviewDriver;
+	/** The stage's layout, for each frame's scale. */
+	layout: Store<StageLayout | null>;
+	/** The width on screen. */
+	visibleWidth: () => Width;
+	/** The editor's document, to read the overlay tokens from (default: the global document). */
+	tokensFrom?: Document;
+	/**
+	 * M4 (Decision 9): `quiet` draws nothing (a read-only document: no overlays);
+	 * `veil` draws only the lock's veil, a two-tone hatch over the whole page that
+	 * takes the pointer, so nothing on the page can be clicked or typed. Default normal.
+	 */
+	mode?: () => { kind: 'normal' } | { kind: 'quiet' } | { kind: 'veil'; title: string };
+}): Overlays {
+	const { driver, layout } = options;
+	const channels = new Map<string, readonly Mark[]>();
+	const painters: OverlayPainter[] = [];
+	const stops: (() => void)[] = [];
+	const tokensFrom = options.tokensFrom ?? document;
+	let raf = 0;
+	let destroyed = false;
+	/** Each frame's veil, while it shows or lifts. */
+	const veils = new WeakMap<Document, HTMLElement>();
+
+	const tokens = (() => {
+		const style = getComputedStyle(tokensFrom.documentElement);
+		const out: string[] = [];
+		for (const [name, token] of Object.entries(OVERLAY_TOKENS)) {
+			const value = style.getPropertyValue(token).trim();
+			if (value) out.push(`${name}:${value}`);
+		}
+		return out.join(';');
+	})();
+	// The editor's UI font (the first preloaded font on /admin is Instrument Sans), for the tags.
+	const fontUrl = (() => {
+		const link = tokensFrom.querySelector<HTMLLinkElement>('link[rel="preload"][as="font"][href*="instrument-sans"]');
+		return link ? new URL(link.getAttribute('href')!, tokensFrom.baseURI).href : null;
+	})();
+
+	function mount(frame: PreviewFrame): HTMLElement | null {
+		const doc = frame.document;
+		if (!doc?.documentElement) return null;
+		if (!doc.getElementById(STYLE_ID)) {
+			const style = doc.createElement('style');
+			style.id = STYLE_ID;
+			style.textContent =
+				(fontUrl ? `@font-face{font-family:"${FONT_FAMILY}";src:url("${fontUrl}") format("woff2");font-weight:100 900;font-display:swap}\n` : '') + OVERLAY_CSS;
+			(doc.head ?? doc.documentElement).appendChild(style);
+		}
+		let layer = doc.getElementById(LAYER_ID);
+		if (!layer || layer.parentElement !== doc.documentElement) {
+			layer?.remove();
+			layer = doc.createElement('div');
+			layer.id = LAYER_ID;
+			layer.setAttribute('aria-hidden', 'true');
+			layer.setAttribute('style', tokens);
+			doc.documentElement.appendChild(layer);
+		}
+		return layer;
+	}
+
+	function context(frame: PreviewFrame, doc: Document, win: Window): OverlayContext {
+		const scale = layout.get()?.[frame.width].scale ?? 1;
+		const k = 1 / (scale > 0 ? scale : 1);
+		return {
+			frame,
+			width: frame.width,
+			visible: options.visibleWidth() === frame.width,
+			doc,
+			k,
+			// A fields document's root (`data-cms-document`) is block 0 (preview/markers.ts).
+			block: (i) => blockElement(doc, i),
+			field: (i, field) => fieldElement(doc, i, field),
+			blocks: () => blockElements(doc),
+			skippedTop(i) {
+				const anchor = skippedAnchor(doc, i);
+				return anchor ? skippedTop(anchor) + win.scrollY : null;
+			},
+			rect(el, pad = 0) {
+				const r = el.getBoundingClientRect();
+				const p = pad * k;
+				return { left: r.left + win.scrollX - p, top: r.top + win.scrollY - p, width: r.width + 2 * p, height: r.height + 2 * p };
+			},
+			place: (r) => `left:${r.left}px;top:${r.top}px;width:${r.width}px;height:${r.height}px`,
+			el(tag, className, style) {
+				const node = doc.createElement(tag);
+				if (className) node.className = className;
+				if (style) for (const [key, value] of Object.entries(style)) if (value !== undefined) node.style.setProperty(key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`), value);
+				return node;
+			},
+		};
+	}
+
+	function drawMark(ctx: OverlayContext, mark: Mark): Node | null {
+		// A skipped block has no element: its mark goes where its comment is.
+		const skippedAt = mark.kind === 'skipped' ? ctx.skippedTop(mark.block) : null;
+		const target = mark.kind === 'skipped' ? null : mark.field ? ctx.field(mark.block, mark.field) : ctx.block(mark.block);
+		if (!target && skippedAt === null) return null;
+		const tone = mark.tone === 'phone' ? ' phone' : '';
+		const label = (cls: string) => {
+			if (!mark.label) return null;
+			const tag = ctx.el(mark.onClick ? 'button' : 'span', cls);
+			if (mark.onClick) {
+				(tag as HTMLButtonElement).type = 'button';
+				tag.addEventListener('click', (event) => {
+					event.preventDefault();
+					event.stopPropagation();
+					mark.onClick!(event as MouseEvent);
+				});
+			}
+			tag.textContent = mark.label;
+			return tag;
+		};
+		const box = (cls: string, pad: number, labelClass: string | null) => {
+			const el = ctx.el('div', `cms-box ${cls}${tone}`);
+			el.setAttribute('style', ctx.place(ctx.rect(target!, pad)));
+			el.dataset.mark = mark.kind;
+			el.dataset.block = String(mark.block);
+			if (mark.field) el.dataset.field = mark.field;
+			const tag = labelClass ? label(labelClass) : null;
+			if (tag) el.appendChild(tag);
+			return el;
+		};
+		switch (mark.kind) {
+			case 'hover':
+				return box('cms-hov', 0, 'cms-tag');
+			case 'selected':
+				return box('cms-sel', 0, 'cms-tag');
+			case 'field-hover':
+				return box('cms-fhov', 4, null);
+			case 'picked':
+				return box('cms-pick', 6, 'cms-chip');
+			case 'typing':
+				return box('cms-type', 6, 'cms-chip');
+			case 'warn':
+				return box('cms-warn', 4, 'cms-chip warn');
+			case 'skipped': {
+				const el = ctx.el('div', 'cms-skip');
+				el.style.top = `${skippedAt}px`;
+				el.dataset.mark = 'skipped';
+				el.dataset.block = String(mark.block);
+				const pill = label('');
+				if (pill) el.appendChild(pill);
+				return el;
+			}
+		}
+	}
+
+	function drawFrame(frame: PreviewFrame) {
+		const doc = frame.document;
+		const win = frame.window;
+		if (!doc || !win) return;
+		const layer = mount(frame);
+		if (!layer) return;
+		const ctx = context(frame, doc, win);
+		layer.style.setProperty('--k', ctx.k.toFixed(4));
+		const mode = options.mode?.() ?? { kind: 'normal' };
+		const height = () => `${Math.max(doc.documentElement.scrollHeight, doc.body?.scrollHeight ?? 0)}px`;
+		// The veil is one node per frame, kept across redraws, so it can lift: when the lock
+		// goes it fades out (`.out`, over --dur-slow) above whatever is drawn now, then goes.
+		let veil = veils.get(doc) ?? null;
+		if (mode.kind === 'veil') {
+			if (!veil || veil.ownerDocument !== doc) {
+				veil = ctx.el('div', 'cms-veil');
+				veil.dataset.mark = 'veil';
+				veils.set(doc, veil);
+			}
+			veil.classList.remove('out');
+			veil.title = mode.title;
+			veil.style.height = height();
+		} else if (veil) {
+			if (!veil.classList.contains('out')) {
+				const ms = parseFloat(getComputedStyle(veil).transitionDuration) * 1000 || 0;
+				if (ms > 0 && veil.isConnected) {
+					veil.classList.add('out');
+					const lifting = veil;
+					win.setTimeout(() => {
+						if (veils.get(doc) !== lifting || !lifting.classList.contains('out')) return;
+						veils.delete(doc);
+						lifting.remove();
+					}, ms + 40);
+				} else {
+					veils.delete(doc);
+					veil = null;
+				}
+			}
+		}
+		if (mode.kind !== 'normal') {
+			replaceMarks(layer, veil ? [veil] : []);
+			return;
+		}
+		const out: Node[] = [];
+		const marks = [...channels.values()].flat().filter((m) => !m.frames || m.frames.includes(frame.width));
+		marks.sort((a, b) => ORDER.indexOf(a.kind) - ORDER.indexOf(b.kind));
+		const draw = (mark: Mark) => {
+			try {
+				const node = drawMark(ctx, mark);
+				if (node) out.push(node);
+			} catch (error) {
+				console.error('[caracms] an overlay mark failed:', error);
+			}
+		};
+		marks.filter((m) => UNDER_PAINTERS.has(m.kind)).forEach(draw);
+		for (const painter of painters) {
+			try {
+				const result = painter(ctx);
+				if (result) out.push(...(Array.isArray(result) ? result : [result as Node]));
+			} catch (error) {
+				console.error('[caracms] an overlay painter failed:', error);
+			}
+		}
+		marks.filter((m) => !UNDER_PAINTERS.has(m.kind)).forEach(draw);
+		if (veil) out.push(veil);
+		replaceMarks(layer, out);
+	}
+
+	/**
+	 * The layer's children become `nodes`, except the ones marked `data-cms-keep` (the
+	 * formatting bar of on-page rich text, rich-text-bar.ts), which stay where they are,
+	 * on top: never taken out, since taking out a node that holds focus (the link
+	 * popover's search) blurs it.
+	 */
+	function replaceMarks(layer: HTMLElement, nodes: readonly Node[]) {
+		let kept: Element | null = null;
+		for (const child of [...layer.childNodes]) {
+			if (child.nodeType === 1 && (child as Element).hasAttribute(KEEP)) kept ??= child as Element;
+			else child.remove();
+		}
+		const doc = layer.ownerDocument;
+		const frag = doc.createDocumentFragment();
+		frag.append(...nodes);
+		layer.insertBefore(frag, kept);
+	}
+
+	function flush() {
+		cancelAnimationFrame(raf);
+		raf = 0;
+		if (destroyed) return;
+		for (const frame of driver.frames()) drawFrame(frame);
+	}
+
+	function redraw() {
+		if (destroyed || raf) return;
+		raf = requestAnimationFrame(() => {
+			raf = 0;
+			flush();
+		});
+	}
+
+	// Each frame: the layer on load, again after every morph; a redraw when its page changes size.
+	stops.push(
+		driver.registerFrameHook((frame) => {
+			const doc = frame.document;
+			const win = frame.window as (Window & typeof globalThis) | null;
+			if (!doc || !win) return;
+			mount(frame);
+			redraw();
+			const observer = new win.ResizeObserver(() => redraw());
+			observer.observe(doc.documentElement);
+			if (doc.body) observer.observe(doc.body);
+			const onFonts = () => redraw();
+			doc.fonts?.addEventListener?.('loadingdone', onFonts);
+			doc.addEventListener('input', onFonts, true);
+			return () => {
+				observer.disconnect();
+				doc.fonts?.removeEventListener?.('loadingdone', onFonts);
+				doc.removeEventListener('input', onFonts, true);
+			};
+		}),
+	);
+	stops.push(layout.subscribe(() => redraw()));
+
+	return {
+		set(channel, marks) {
+			channels.set(channel, marks);
+			redraw();
+		},
+		clear(channel) {
+			if (channels.delete(channel)) redraw();
+		},
+		addPainter(painter) {
+			painters.push(painter);
+			redraw();
+			return () => {
+				const i = painters.indexOf(painter);
+				if (i >= 0) painters.splice(i, 1);
+				redraw();
+			};
+		},
+		redraw,
+		flush,
+		layerOf(frame) {
+			const layer = frame.document?.getElementById(LAYER_ID);
+			return layer ?? null;
+		},
+		destroy() {
+			destroyed = true;
+			cancelAnimationFrame(raf);
+			for (const stop of stops) stop();
+			for (const frame of driver.frames()) {
+				frame.document?.getElementById(LAYER_ID)?.remove();
+				frame.document?.getElementById(STYLE_ID)?.remove();
+			}
+		},
+	};
+}

package/src/editor/client/overlays/overlay-css.ts

@@ -0,0 +1,177 @@
+/**
+ * The overlays' CSS, injected into each preview iframe's <head> (never into the
+ * public page; Decision 17). Lifted from the mockup's overlayCSS() (notes/mockups/
+ * m2-editor.html), M2 → Rules → Overlays: a blue core with a white line both sides,
+ * the same size on screen at any scale (`--k` = 1 / the frame's scale), hover thin
+ * with a wash, selected 2px with a filled tag, a picked field ringed with its name,
+ * teal for phone lines, amber dashes for too long and skipped, and the lock's veil,
+ * a two-tone hatch that lifts (fades out over --dur-slow) when the lock goes.
+ *
+ * Colours come from the editor's tokens (`--ov*` in styles/tokens.css): the layer
+ * copies them onto itself as `--cms-*` when it mounts (layer.ts), so there are no
+ * raw colours here (M2 Decision 7). Everything is scoped under `#cms-overlays`, the
+ * layer, so it can't touch the site; the rules outside it only set cursors, hide
+ * the browser's own outline on the fields the layer rings, and give a mounted page
+ * editor (on-page rich text) the one style ProseMirror needs, `white-space:
+ * pre-wrap`, which applies only while it's mounted (Decision 3).
+ *
+ * A string, not a .css file: it goes into another document, so the editor's own
+ * stylesheet pipeline doesn't apply.
+ */
+/** A size that stays the same on screen at any preview scale. */
+const K = (n: number) => `calc(var(--k)*${n}px)`;
+
+/**
+ * The formatting bar of rich text typed on the page and what opens from it (on-page
+ * rich text, Decision 9; rich-text-bar.ts), lifted from the mockup's RT CSS: the
+ * sidebar toolbar's look at a constant size, the style menu, the link popover, and
+ * the linked words' wash. A reset first, so a site's own rules for `button`, `input`
+ * or `p` can't reach in.
+ */
+const RICH_TEXT_BAR_CSS = `#cms-overlays .cms-rt{position:absolute;left:0;top:0;width:100%;height:0;pointer-events:none;font:400 ${K(13)}/1.45 "caracms UI",system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;color:var(--cms-t);letter-spacing:0;text-transform:none;text-align:left;white-space:normal}
+#cms-overlays .cms-rt :where(div,p,span,b,i,button,input){margin:0;padding:0;border:0;background:none;box-shadow:none;letter-spacing:0;text-transform:none;text-shadow:none;text-decoration:none;text-indent:0;float:none;min-width:0;min-height:0;max-width:none;font-style:normal;color:inherit}
+#cms-overlays .cms-rt button{font-family:"caracms UI",system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;-webkit-appearance:none;appearance:none}
+#cms-overlays .cms-rt :focus-visible{outline:${K(2)} solid var(--cms-focus);outline-offset:${K(1)}}
+#cms-overlays .cms-rt .cms-i{width:${K(14)};height:${K(14)};flex:none;fill:none;stroke:currentColor;stroke-width:1.5;stroke-linecap:round;stroke-linejoin:round}
+#cms-overlays .cms-hold{position:absolute;background:var(--cms-sel-halo);border-radius:${K(2)}}
+#cms-overlays .cms-rtw{position:absolute;pointer-events:auto;transition:top var(--cms-dur-fast) cubic-bezier(.2,.8,.2,1),left var(--cms-dur-fast) cubic-bezier(.2,.8,.2,1);animation:cms-rise var(--cms-dur-base) cubic-bezier(.2,.8,.2,1)}
+#cms-overlays .cms-rtw[data-place=below]{animation-name:cms-drop}
+@keyframes cms-rise{from{opacity:0;translate:0 ${K(6)}}}
+@keyframes cms-drop{from{opacity:0;translate:0 ${K(-6)}}}
+#cms-overlays .cms-rtbar,#cms-overlays .cms-rtmenu,#cms-overlays .cms-lpop{background:var(--cms-surface);box-shadow:0 ${K(14)} ${K(36)} var(--cms-pop),0 0 0 ${K(1)} var(--cms-pop-line)}
+#cms-overlays .cms-rtbar{display:flex;align-items:center;gap:${K(2)};padding:${K(3)};border-radius:${K(8)};white-space:nowrap}
+#cms-overlays .cms-rtbar button{display:inline-grid;place-items:center;width:${K(28)};height:${K(26)};padding:0;border:0;border-radius:${K(5)};background:none;color:var(--cms-muted);font-size:${K(13)};font-weight:600;line-height:1;cursor:pointer;transition:background var(--cms-dur-fast),color var(--cms-dur-fast)}
+#cms-overlays .cms-rtbar button:hover{background:var(--cms-hover);color:var(--cms-t)}
+#cms-overlays .cms-rtbar button[aria-pressed=true],#cms-overlays .cms-rtbar button[aria-expanded=true]{background:var(--cms-pressed);color:var(--cms-t)}
+#cms-overlays .cms-rtbar button b{font-weight:700}
+#cms-overlays .cms-rtbar button i{font:italic 600 ${K(14)}/1 Georgia,serif}
+#cms-overlays .cms-rtbar .cms-st{display:inline-flex;align-items:center;justify-content:space-between;gap:${K(4)};width:auto;min-width:${K(100)};padding:0 ${K(6)} 0 ${K(8)};color:var(--cms-t);font-weight:500}
+#cms-overlays .cms-rtbar .cms-st .cms-i{width:${K(12)};height:${K(12)};color:var(--cms-icon)}
+#cms-overlays .cms-rtsep{flex:none;width:${K(1)};height:${K(16)};margin:0 ${K(3)};background:var(--cms-line)}
+#cms-overlays .cms-rtmenu{position:absolute;left:0;top:100%;min-width:${K(188)};padding:${K(4)};border-radius:${K(10)}}
+#cms-overlays .cms-rtmenu button{display:flex;align-items:center;gap:${K(8)};width:100%;height:${K(30)};padding:0 ${K(8)};border:0;border-radius:${K(5)};background:none;color:var(--cms-t);font-size:${K(13)};line-height:1;text-align:left;cursor:pointer}
+#cms-overlays .cms-rtmenu button:hover{background:var(--cms-hover)}
+#cms-overlays .cms-rtmenu button[aria-checked=true]{background:var(--cms-sel-wash);color:var(--cms-sel-strong)}
+#cms-overlays .cms-rtmenu .k{margin-left:auto;display:inline-flex}
+#cms-overlays .cms-rtmenu .st-h2{font-size:${K(16)};font-weight:600;letter-spacing:-.01em}
+#cms-overlays .cms-rtmenu .st-h3{font-size:${K(14)};font-weight:600}
+#cms-overlays .cms-lpop{position:absolute;left:0;top:100%;padding:${K(4)};border-radius:${K(10)}}
+#cms-overlays .cms-lpop .find{position:relative;margin:0 0 ${K(4)}}
+#cms-overlays .cms-lpop .find .cms-i{position:absolute;left:${K(10)};top:50%;translate:0 -50%;width:${K(16)};height:${K(16)};color:var(--cms-icon)}
+#cms-overlays .cms-lpop input{box-sizing:border-box;width:100%;height:${K(32)};padding:0 ${K(10)} 0 ${K(34)};border:${K(1)} solid var(--cms-line-strong);border-radius:${K(7)};background:var(--cms-surface);color:var(--cms-t);font:400 ${K(13)}/1 "caracms UI",system-ui,sans-serif;outline:0;-webkit-appearance:none;appearance:none}
+#cms-overlays .cms-lpop input:focus{border-color:var(--cms-sel);box-shadow:0 0 0 ${K(3)} var(--cms-sel-halo)}
+#cms-overlays .cms-lpop input[aria-invalid=true]{border-color:var(--cms-wdot)}
+#cms-overlays .cms-msg{display:flex;align-items:flex-start;gap:${K(6)};margin:${K(2)} ${K(6)} ${K(6)};font-size:${K(12)};font-weight:500;line-height:1.4;color:var(--cms-wtext)}
+#cms-overlays .cms-msg .cms-i{margin-top:${K(1)};color:var(--cms-wdot)}
+#cms-overlays .cms-lpop .sw-h{padding:${K(6)} ${K(8)} ${K(4)};font-size:${K(11)};font-weight:600;letter-spacing:.06em;text-transform:uppercase;color:var(--cms-muted)}
+#cms-overlays .cms-lpop .drow{display:flex;align-items:center;gap:${K(8)};width:100%;min-height:${K(32)};padding:0 ${K(8)};border:0;border-radius:${K(7)};background:none;color:var(--cms-t);font-size:${K(13)};line-height:1.3;text-align:left;cursor:pointer}
+#cms-overlays .cms-lpop .drow:hover,#cms-overlays .cms-lpop .drow.is-active{background:var(--cms-hover)}
+#cms-overlays .cms-lpop .drow .cms-i{width:${K(16)};height:${K(16)};color:var(--cms-icon)}
+#cms-overlays .cms-lpop .nm{flex:1;min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+#cms-overlays .cms-lpop .crumb{color:var(--cms-subtle);font-weight:500}
+#cms-overlays .cms-lpop .meta{flex:none;color:var(--cms-subtle)}
+#cms-overlays .cms-lpop .mono{font-family:"Geist Mono",ui-monospace,SFMono-Regular,Menlo,monospace;font-size:${K(10.5)}}
+#cms-overlays .cms-lpop .sw-more{padding:${K(6)} ${K(8)};font-size:${K(12)};color:var(--cms-subtle)}
+#cms-overlays .cms-lpop-foot{margin-top:${K(4)};padding:${K(8)} ${K(8)} ${K(4)};border-top:${K(1)} solid var(--cms-line);font-size:${K(11)};line-height:1.5;color:var(--cms-subtle)}
+#cms-overlays .cms-lpop .cms-top{display:flex;gap:${K(4)};margin:0 0 ${K(4)}}
+#cms-overlays .cms-lpop .cms-top .find{flex:1;min-width:0;margin:0}
+#cms-overlays .cms-lpop .cms-btn{display:inline-flex;align-items:center;gap:${K(6)};flex:none;height:${K(32)};padding:0 ${K(10)};border:${K(1)} solid var(--cms-line-strong);border-radius:${K(7)};background:var(--cms-surface);color:var(--cms-t);font-size:${K(13)};font-weight:500;cursor:pointer}
+#cms-overlays .cms-lpop .cms-btn:hover{background:var(--cms-hover)}
+#cms-overlays .cms-lpop .cms-btn .cms-i{color:var(--cms-icon)}
+#cms-overlays .cms-ftype{position:relative;display:block;width:${K(18)};height:${K(22)};flex:none;border:${K(1)} solid var(--cms-line-strong);border-radius:${K(2)};background:linear-gradient(var(--cms-line-strong),var(--cms-line-strong)) ${K(4)} ${K(8)}/calc(100% - ${K(8)}) ${K(1)} no-repeat,linear-gradient(var(--cms-line-strong),var(--cms-line-strong)) ${K(4)} ${K(11)}/calc(100% - ${K(8)}) ${K(1)} no-repeat,var(--cms-surface);clip-path:polygon(0 0,calc(100% - ${K(6)}) 0,100% ${K(6)},100% 100%,0 100%)}
+#cms-overlays .cms-picked{display:flex;align-items:center;gap:${K(8)};padding:${K(6)} ${K(4)} ${K(6)} ${K(8)};border-radius:${K(7)};background:var(--cms-wash)}
+#cms-overlays .cms-picked .ft{flex:1;min-width:0;display:flex;flex-direction:column;line-height:1.35}
+#cms-overlays .cms-picked b{font-weight:500;white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+#cms-overlays .cms-picked small{font-size:${K(11.5)};color:var(--cms-subtle)}
+#cms-overlays .cms-picked>.cms-i{color:var(--cms-wdot)}
+#cms-overlays .cms-ib{display:grid;place-items:center;width:${K(26)};height:${K(26)};flex:none;border-radius:${K(6)};color:var(--cms-icon);cursor:pointer}
+#cms-overlays .cms-ib:hover{background:var(--cms-hover);color:var(--cms-t)}
+#cms-overlays .cms-opens{display:flex;align-items:center;gap:${K(8)};margin-top:${K(6)};padding:0 ${K(4)}}
+#cms-overlays .cms-opens .lbl{flex:none;font-size:${K(11.5)};font-weight:600;color:var(--cms-muted)}
+#cms-overlays .cms-seg{display:flex;flex:1;padding:${K(2)};border-radius:${K(7)};background:var(--cms-pressed)}
+#cms-overlays .cms-seg button{display:inline-flex;flex:1;align-items:center;justify-content:center;gap:${K(5)};height:${K(26)};border-radius:${K(5)};color:var(--cms-muted);font-size:${K(12.5)};font-weight:500;cursor:pointer}
+#cms-overlays .cms-seg button[aria-checked=true]{background:var(--cms-surface);color:var(--cms-t);box-shadow:0 ${K(1)} ${K(2)} var(--cms-pop)}
+#cms-overlays .cms-seg .cms-i{width:${K(13)};height:${K(13)}}
+@media (prefers-reduced-motion:reduce){#cms-overlays .cms-rtw,#cms-overlays .cms-rtbar button{transition:none;animation:none}}
+`;
+
+export const OVERLAY_CSS = `
+html [data-cms-block]{cursor:default}
+html [data-cms-kind="text"]{cursor:text}
+html [data-cms-kind="lockup"]{cursor:pointer}
+html [data-cms-kind="text"]:focus{outline:none}
+html [data-cms-kind="richText"][tabindex]{cursor:text}
+html [data-cms-kind="richText"][tabindex]:focus{outline:none}
+html [data-cms-kind="richText"].ProseMirror{white-space:pre-wrap}
+#cms-overlays{all:initial;position:absolute;left:0;top:0;width:100%;height:0;overflow:visible;pointer-events:none;z-index:2147483000;font-family:"caracms UI",system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;-webkit-font-smoothing:antialiased;line-height:1;letter-spacing:0;text-transform:none}
+#cms-overlays *{box-sizing:border-box}
+#cms-overlays .cms-box{position:absolute;border-radius:calc(var(--k)*3px)}
+#cms-overlays .cms-hov{border:calc(var(--k)*1.5px) solid var(--cms-ov);background:var(--cms-wash);box-shadow:0 0 0 calc(var(--k)*1px) var(--cms-halo),inset 0 0 0 calc(var(--k)*1px) var(--cms-halo)}
+#cms-overlays .cms-sel{border:calc(var(--k)*2px) solid var(--cms-ov);box-shadow:0 0 0 calc(var(--k)*1px) var(--cms-halo),inset 0 0 0 calc(var(--k)*1px) var(--cms-halo)}
+#cms-overlays .cms-fhov{border:calc(var(--k)*1px) dashed var(--cms-ov);box-shadow:0 0 0 calc(var(--k)*1px) var(--cms-halo)}
+#cms-overlays .cms-pick{border:calc(var(--k)*2px) solid var(--cms-ov);border-radius:calc(var(--k)*4px);box-shadow:0 0 0 calc(var(--k)*1.5px) var(--cms-halo),inset 0 0 0 calc(var(--k)*1px) var(--cms-halo)}
+#cms-overlays .phone{--cms-ov:var(--cms-phone)}
+#cms-overlays .cms-type{border:calc(var(--k)*1.5px) solid var(--cms-ov);border-radius:calc(var(--k)*4px);box-shadow:0 0 0 calc(var(--k)*1px) var(--cms-halo),0 0 0 calc(var(--k)*5px) var(--cms-ring)}
+#cms-overlays .cms-warn{border:calc(var(--k)*2px) dashed var(--cms-warn);border-radius:calc(var(--k)*4px);box-shadow:0 0 0 calc(var(--k)*1px) var(--cms-halo),inset 0 0 0 calc(var(--k)*1px) var(--cms-halo)}
+#cms-overlays .cms-tag,#cms-overlays .cms-chip{position:absolute;display:inline-flex;align-items:center;gap:calc(var(--k)*5px);height:calc(var(--k)*22px);padding:0 calc(var(--k)*8px);background:var(--cms-ov);color:var(--cms-on);font-size:calc(var(--k)*11.5px);font-weight:600;line-height:1;white-space:nowrap;box-shadow:0 0 0 calc(var(--k)*1px) var(--cms-halo)}
+#cms-overlays .cms-tag{left:calc(var(--k)*-2px);top:calc(var(--k)*-2px);border-radius:calc(var(--k)*3px) 0 calc(var(--k)*6px) 0}
+#cms-overlays .cms-hov .cms-tag{background:var(--cms-surface);color:var(--cms-ov-text);left:calc(var(--k)*-1.5px);top:calc(var(--k)*-1.5px);box-shadow:inset 0 0 0 calc(var(--k)*1.5px) var(--cms-ov)}
+#cms-overlays .cms-chip{left:calc(var(--k)*-2px);bottom:100%;margin-bottom:calc(var(--k)*5px);border-radius:calc(var(--k)*5px)}
+#cms-overlays .cms-chip.in{bottom:auto;top:calc(var(--k)*4px);left:calc(var(--k)*4px);margin:0}
+#cms-overlays .cms-chip.warn{background:var(--cms-warn-wash);color:var(--cms-warn-text);box-shadow:inset 0 0 0 calc(var(--k)*1.5px) var(--cms-warn),0 0 0 calc(var(--k)*1px) var(--cms-halo)}
+#cms-overlays .cms-go{pointer-events:auto;position:absolute;display:inline-flex;align-items:center;height:calc(var(--k)*22px);padding:0 calc(var(--k)*9px);border:0;border-radius:999px;background:var(--cms-surface);color:var(--cms-ov-text);font:600 calc(var(--k)*11.5px)/1 "caracms UI",system-ui,sans-serif;box-shadow:0 0 0 calc(var(--k)*1.5px) var(--cms-ov),0 calc(var(--k)*3px) calc(var(--k)*10px) var(--cms-lift);cursor:pointer;white-space:nowrap}
+#cms-overlays .cms-go.off{pointer-events:none;cursor:default;box-shadow:0 0 0 calc(var(--k)*1px) var(--cms-halo),0 calc(var(--k)*3px) calc(var(--k)*10px) var(--cms-lift)}
+#cms-overlays .cms-go:focus-visible{outline:calc(var(--k)*2px) solid var(--cms-ov);outline-offset:calc(var(--k)*2px)}
+#cms-overlays .cms-add{pointer-events:auto;position:absolute;left:50%;top:0;transform:translate(-50%,-50%);display:inline-flex;align-items:center;gap:calc(var(--k)*4px);height:calc(var(--k)*24px);padding:0 calc(var(--k)*11px);border:0;border-radius:999px;background:var(--cms-surface);color:var(--cms-ov-text);font:600 calc(var(--k)*11.5px)/1 "caracms UI",system-ui,sans-serif;box-shadow:0 0 0 calc(var(--k)*1.5px) var(--cms-ov),0 calc(var(--k)*3px) calc(var(--k)*10px) var(--cms-lift);cursor:pointer;white-space:nowrap}
+#cms-overlays .cms-add:hover{background:var(--cms-ov);color:var(--cms-on)}
+#cms-overlays .cms-add:focus-visible,#cms-overlays .cms-skip button:focus-visible{outline:calc(var(--k)*2px) solid var(--cms-ov);outline-offset:calc(var(--k)*2px)}
+#cms-overlays .cms-empty{position:absolute;border:calc(var(--k)*1.5px) dashed var(--cms-ov);border-radius:calc(var(--k)*6px);box-shadow:0 0 0 calc(var(--k)*1px) var(--cms-halo),inset 0 0 0 calc(var(--k)*1px) var(--cms-halo)}
+#cms-overlays .cms-empty .cms-add{top:50%;height:calc(var(--k)*34px);font-size:calc(var(--k)*13px);padding:0 calc(var(--k)*16px)}
+#cms-overlays .cms-skip{position:absolute;left:0;right:0;height:0}
+#cms-overlays .cms-skip::before{content:"";position:absolute;left:0;right:0;top:calc(var(--k)*-1px);border-top:calc(var(--k)*2px) dashed var(--cms-warn);box-shadow:0 0 0 calc(var(--k)*1px) var(--cms-halo)}
+#cms-overlays .cms-skip button{pointer-events:auto;cursor:pointer;position:absolute;left:50%;top:0;transform:translate(-50%,-50%);height:calc(var(--k)*22px);padding:0 calc(var(--k)*9px);display:inline-flex;align-items:center;border:0;border-radius:999px;background:var(--cms-warn-wash);color:var(--cms-warn-text);font:600 calc(var(--k)*11.5px)/1 "caracms UI",system-ui,sans-serif;white-space:nowrap;box-shadow:inset 0 0 0 calc(var(--k)*1.5px) var(--cms-warn),0 0 0 calc(var(--k)*1px) var(--cms-halo)}
+#cms-overlays .cms-skip.on button{box-shadow:inset 0 0 0 calc(var(--k)*2px) var(--cms-warn),0 0 0 calc(var(--k)*1px) var(--cms-halo),0 0 0 calc(var(--k)*4px) var(--cms-ring)}
+#cms-overlays .cms-veil{position:absolute;left:0;top:0;width:100%;pointer-events:auto;cursor:not-allowed;background:repeating-linear-gradient(135deg,var(--cms-veil-a) 0 calc(var(--k)*7px),var(--cms-veil-b) calc(var(--k)*7px) calc(var(--k)*14px));transition:opacity var(--cms-dur,0ms) ease}
+#cms-overlays .cms-veil.out{opacity:0;pointer-events:none}
+@media (prefers-reduced-motion:reduce){#cms-overlays .cms-veil{transition:none}}
+${RICH_TEXT_BAR_CSS}`;
+
+/** The editor's overlay tokens, copied onto the layer as `--cms-*` (overlay-css.ts uses only these). */
+export const OVERLAY_TOKENS: Record<string, string> = {
+	'--cms-ov': '--ov',
+	'--cms-ov-text': '--ov-text',
+	'--cms-halo': '--ov-halo',
+	'--cms-on': '--ov-on',
+	'--cms-surface': '--ov-surface',
+	'--cms-wash': '--ov-wash',
+	'--cms-phone': '--ov-phone',
+	'--cms-warn': '--ov-warn',
+	'--cms-warn-text': '--ov-warn-text',
+	'--cms-warn-wash': '--ov-warn-wash',
+	'--cms-ring': '--ov-ring',
+	'--cms-lift': '--ov-lift',
+	'--cms-veil-a': '--ov-veil-a',
+	'--cms-veil-b': '--ov-veil-b',
+	// The veil lifts over --dur-slow (M2 → Motion); 0ms under reduced motion, as the token is.
+	'--cms-dur': '--dur-slow',
+	// The formatting bar of rich text on the page (RICH_TEXT_BAR_CSS): the chrome's own tokens, as the sidebar's toolbar has them.
+	'--cms-t': '--text',
+	'--cms-muted': '--text-muted',
+	'--cms-subtle': '--text-subtle',
+	'--cms-icon': '--icon',
+	'--cms-hover': '--surface-hover',
+	'--cms-pressed': '--surface-pressed',
+	'--cms-line': '--border',
+	'--cms-line-strong': '--border-strong',
+	'--cms-sel': '--select',
+	'--cms-sel-strong': '--select-strong',
+	'--cms-sel-wash': '--select-wash',
+	'--cms-sel-halo': '--select-halo',
+	'--cms-focus': '--focus',
+	'--cms-wtext': '--status-warning',
+	'--cms-wdot': '--status-warning-dot',
+	'--cms-pop': '--ov-pop',
+	'--cms-pop-line': '--ov-pop-line',
+	'--cms-dur-fast': '--dur-fast',
+	'--cms-dur-base': '--dur-base',
+};