caracms 0.0.0-stage → 0.2.0

package/src/editor/client/preview/page-edit.ts

@@ -0,0 +1,632 @@
+/**
+ * Editing from the page (Decision 12; M2 → "click to edit", "text typed on the
+ * page"), in the iframe on screen:
+ *
+ * - **Click to edit:** a click opens that block's level and picks the field under
+ *   it ("Picked from the page"). A plain text field is then typed right there; a
+ *   lockup opens its sidebar field (lockups are edited only in the sidebar); a
+ *   click on a skipped block's pill opens that block (the overlay's own button).
+ * - **Typing on the page:** plain text fields are `contenteditable="plaintext-only"`
+ *   in preview renders (Text.astro). What's typed goes to the store with
+ *   `origin: 'page'`; the driver mirrors it into the other two iframes instead of
+ *   rendering (Decision 13), and the sidebar field follows. One-line fields take no
+ *   line breaks (Enter leaves the field, a paste's breaks become spaces).
+ * - **Rich text typed on the page** (on-page rich text, Decisions 1, 5–8, 10): a
+ *   top-level rich-text field (`tabindex="0"` in preview renders, RichText.astro)
+ *   gets the page editor (page-editor.ts: /admin's own Tiptap mounted on the field's
+ *   element) in the iframe on screen, at most one: mounted when the pointer enters
+ *   the field or focus reaches it (a tap, Tab), so the first press lands on it.
+ *   **A typing session** is focus in the editor or in the overlay layer of its iframe
+ *   (where its formatting bar and link popover live); while it's on, the editor stays mounted
+ *   and `typing` stays set. It's torn down when no session is on and the pointer has
+ *   left the field, when the block's level closes, another document opens or the
+ *   width changes, and when the tab goes read-only; the element is left exactly as a
+ *   render. Each edit is stored with `origin: 'page'` (the driver mirrors it); a
+ *   change from elsewhere is put into the mounted editor (Decision 8). Rich text in
+ *   a list item, and a shared entry on a page that uses it, stay in the sidebar.
+ * - **Hover:** the block and field under the pointer, for the overlays.
+ * - **Following the sidebar:** a block or field picked in the sidebar is scrolled
+ *   into view in the preview if it's out of sight.
+ * - **Keys in the page:** Esc leaves the field, then goes up a level, as in the sidebar;
+ *   in rich text the formatting bar's menu or link popover closes first (Esc and ⌘K
+ *   reach the bar through `onEditorKey`; overlays/rich-text-bar.ts).
+ *
+ * The caret on the page survives every re-render whether focus is here or in the
+ * sidebar: the driver saves and restores each iframe's selection around a morph
+ * (selection.ts; Decision 13). Nothing here changes that.
+ */
+import type { Editor } from '../editor.ts';
+import type { Editor as TiptapEditor } from '@tiptap/core';
+import type { EditorView } from '@tiptap/pm/view';
+import { createStore, type Store } from '../state/store.ts';
+import { sameDoc, type Width } from '../../types.ts';
+import type { PreviewFrame } from './driver.ts';
+import { fieldText } from './field-text.ts';
+import { blockElement, blockIndexOf, blockRootOf, fieldElement, skippedAnchor, skippedTop } from './markers.ts';
+import { mountPageEditor, pointInField, positionOf, type MountedPageEditor } from './page-editor.ts';
+import { mountedIn, setMounted } from './page-editor-registry.ts';
+import { fieldsOfBlock } from '../state/schema.ts';
+import { fieldAt, getAtPath, isKeyPath, richTextOptions } from '../../../fields.ts';
+import type { RichTextOptions } from '../../../rich-text.ts';
+
+export interface Typing {
+	/** The block's key in the document store. */
+	key: string;
+	field: string;
+	width: Width;
+}
+
+export interface PageHover {
+	/** The block's index in the rendered document. */
+	block: number;
+	field: string | null;
+}
+
+/** The page editor mounted in the iframe on screen (on-page rich text), for its formatting bar (overlays/rich-text-bar.ts). */
+export interface PageEditorState {
+	/** The block's key in the document store, and the (top-level) rich-text field. */
+	key: string;
+	field: string;
+	width: Width;
+	frame: PreviewFrame;
+	/** The mounted Tiptap editor (its events: 'transaction', 'selectionUpdate', 'focus', 'blur'). */
+	editor: TiptapEditor;
+	view: EditorView;
+	/** The field's options (its headings, links): the bar shows only its controls. */
+	options: RichTextOptions;
+	/** A typing session is on: focus is in the editor or in its iframe's overlay layer. */
+	session: boolean;
+}
+
+export interface PageEdit {
+	/** The field being typed on the page (plain text, or rich text during a typing session), or null. */
+	typing: Store<Typing | null>;
+	/** The page editor mounted in the iframe on screen, or null (published on mount, teardown and session changes). */
+	pageEditor: Store<PageEditorState | null>;
+	/** What the pointer is over in the iframe on screen, or null. */
+	hover: Store<PageHover | null>;
+	/**
+	 * Keys pressed in the page editor, before its own (on-page rich text, Decision 2: the
+	 * bar's ⌘K and Esc, rich-text-bar.ts). Return true when handled. Returns a remove.
+	 */
+	onEditorKey(handler: (event: KeyboardEvent) => boolean): () => void;
+	/** A key the bar took elsewhere (its popover's search): page-edit's Esc skips it, as it does `onEditorKey`'s. */
+	claimKey(event: Event): void;
+	/** Scroll the iframe on screen so a block (or a field in it) is in view. */
+	reveal(index: number, field?: string | null, options?: { instant?: boolean }): void;
+	destroy(): void;
+}
+
+const LAYER = '#cms-overlays';
+const made = new WeakMap<Editor, PageEdit>();
+
+/**
+ * Focus a field in the block level's sidebar (a lockup's first line), once it's
+ * rendered. `field` may be a dotted path (M5a Decision 16): the control for that
+ * path (`data-path`) inside the field's frame, once a list has opened the row that
+ * holds it (`credits.1.name`); the field's first control otherwise.
+ */
+export function focusSidebarField(field: string, tries = 12): void {
+	// The field's frame: the longest `data-ff` the path starts with, at a path-part
+	// boundary (a group's fields have frames of their own: `left.button`).
+	const frameOf = (): { frame: HTMLElement; name: string } | null => {
+		let best: { frame: HTMLElement; name: string } | null = null;
+		for (const frame of document.querySelectorAll<HTMLElement>('[data-pane-level="block"] .field-frame[data-ff], [data-pane-level="document"] [data-form] .field-frame[data-ff]')) {
+			const name = frame.dataset.ff!;
+			if ((field === name || field.startsWith(`${name}.`)) && (!best || name.length > best.name.length)) best = { frame, name };
+		}
+		return best;
+	};
+	// M3's controls first (a lockup's lines before its Main lines / Phone lines switch), then any control.
+	const controls = 'input:not([disabled]),textarea:not([disabled]),select:not([disabled]),button.btn:not([disabled])';
+	const any = '[contenteditable="true"],button:not([disabled])';
+	const attempt = (left: number) => {
+		// The block level's fields, or (M5a) the form of a fields document, a shared block or Site Settings.
+		const found = frameOf();
+		const frame = found?.frame;
+		const exact = frame?.querySelector<HTMLElement>(`[data-path="${CSS.escape(field)}"]`);
+		// A nested path waits for its row to open; past the tries, the field's own control will do.
+		const input = exact ?? (field === found?.name || left === 0 ? (frame?.querySelector<HTMLElement>(controls) ?? frame?.querySelector<HTMLElement>(any)) : null);
+		if (!frame || !input) {
+			if (left > 0) requestAnimationFrame(() => attempt(left - 1));
+			return;
+		}
+		(input.closest('.item, .btnf, .ref') ?? frame).scrollIntoView({ block: 'nearest', behavior: reducedMotion() ? 'auto' : 'smooth' });
+		input.focus({ preventScroll: true });
+		if (input instanceof HTMLInputElement && /^(text|search|url|tel)$/.test(input.type)) input.setSelectionRange(input.value.length, input.value.length);
+	};
+	requestAnimationFrame(() => attempt(tries));
+}
+
+/**
+ * A top-level text or rich-text field, or one in a group (`left.heading`), is typed on the
+ * page (M5a Decision 13; on-page rich text, Decision 1); everything else (a list item's
+ * field, a lockup) opens in the sidebar.
+ */
+const typedOnPage = (kind: string | null, field: string) => (kind === 'text' || kind === 'richText') && isKeyPath(field);
+
+/** A rich-text field the page editor can mount on: top level, focusable in the preview render (RichText.astro). */
+const isPageRichText = (el: Element | null | undefined): el is HTMLElement =>
+	!!el && el.matches('[data-cms-kind="richText"][data-cms-field][tabindex]') && isKeyPath(el.getAttribute('data-cms-field')!);
+
+const reducedMotion = () => typeof matchMedia === 'function' && matchMedia('(prefers-reduced-motion: reduce)').matches;
+
+export function pageEditFor(editor: Editor): PageEdit | null {
+	const driver = editor.preview;
+	if (!driver || typeof window === 'undefined') return null;
+	const existing = made.get(editor);
+	if (existing) return existing;
+
+	const typing = createStore<Typing | null>(null);
+	const hover = createStore<PageHover | null>(null);
+	const pageEditor = createStore<PageEditorState | null>(null);
+	const editorKeys = new Set<(event: KeyboardEvent) => boolean>();
+	/** Keys an `onEditorKey` handler took (ProseMirror prevents every Esc, so defaultPrevented can't say). */
+	const claimed = new WeakSet<Event>();
+	const stops: (() => void)[] = [];
+
+	/** The preview shows the document the sidebar has open (not the old one while another opens). */
+	const live = () => {
+		const status = editor.previewStatus.get();
+		return !status.opening && sameDoc(status.showing, editor.doc.get().ref);
+	};
+	const visible = (frame: PreviewFrame) => frame.width === editor.view.get().width;
+	/** M4 (Decision 9): read-only (a lock, held edits, signed out): no clicking to edit, no typing on the page. */
+	const readOnly = () => editor.access.get().readOnly;
+	const elementOf = (target: EventTarget | null): Element | null =>
+		target && (target as Node).nodeType === 1 ? (target as Element) : ((target as Node | null)?.parentElement ?? null);
+	const inLayer = (el: Element) => !!el.closest(LAYER);
+
+	/** The block (index and key) and field an element belongs to. */
+	function locate(el: Element) {
+		const blockEl = blockRootOf(el);
+		if (!blockEl) return null;
+		const index = blockIndexOf(blockEl);
+		const key = editor.doc.keyAt(index);
+		if (!Number.isInteger(index) || !key) return null;
+		const fieldEl = el.closest<HTMLElement>('[data-cms-field]');
+		const field = fieldEl && blockEl.contains(fieldEl) ? fieldEl.dataset.cmsField! : null;
+		return { index, key, blockEl, fieldEl: field ? fieldEl! : null, field, kind: fieldEl?.dataset.cmsKind ?? null };
+	}
+
+	const isMultiline = (key: string, field: string) => {
+		const block = editor.doc.block(key);
+		const session = editor.doc.get();
+		const descriptor = block ? fieldAt(fieldsOfBlock(editor.site, session.document, session.ref.collection, block), field) : undefined;
+		return descriptor?.kind === 'text' ? descriptor.multiline : false;
+	};
+
+	// ---- The page editor (on-page rich text) ----
+
+	interface Active {
+		frame: PreviewFrame;
+		doc: Document;
+		key: string;
+		field: string;
+		pe: MountedPageEditor;
+		session: boolean;
+	}
+	/** The mounted page editor (at most one, in the iframe on screen). */
+	let active: Active | null = null;
+	/** The page-typed rich-text field under the pointer in the iframe on screen. */
+	let pointerOn: HTMLElement | null = null;
+	/** The primary button is down in the iframe, and the editor a press mounted (by focus) that its release places the caret in. */
+	let pressing: { x: number; y: number } | null = null;
+	let pressMounted: Active | null = null;
+	/** Torn down by a morph (Decision 6): remounted after it, with this selection. */
+	let resume: { key: string; field: string; width: Width; anchor: number; head: number; focused: boolean } | null = null;
+
+	const publish = () =>
+		pageEditor.set(
+			active
+				? { key: active.key, field: active.field, width: active.frame.width, frame: active.frame, editor: active.pe.editor, view: active.pe.view, options: active.pe.options, session: active.session }
+				: null,
+		);
+
+	const richOptions = (key: string, field: string) => {
+		const block = editor.doc.block(key);
+		const session = editor.doc.get();
+		const descriptor = block?.known ? fieldAt(fieldsOfBlock(editor.site, session.document, session.ref.collection, block), field) : undefined;
+		return descriptor?.kind === 'richText' ? richTextOptions(descriptor) : null;
+	};
+
+	/** Mount the page editor on a field (tearing down any other). Null where it isn't typed on the page. */
+	function mountOn(frame: PreviewFrame, el: HTMLElement): Active | null {
+		if (active && active.pe.el === el && !active.pe.destroyed) return active;
+		const doc = frame.document;
+		// Never in the hidden widths (they're laid out; they get the mirror), never read-only (Decision 10).
+		if (!doc || !visible(frame) || !live() || readOnly() || !isPageRichText(el) || !el.isConnected || el.ownerDocument !== doc) return null;
+		const at = locate(el);
+		if (!at?.field || at.fieldEl !== el) return null;
+		const options = richOptions(at.key, at.field);
+		if (!options) return null;
+		teardown();
+		const { key, field } = at;
+		// One task: ProseMirror swaps the children synchronously (no await here).
+		const pe = mountPageEditor(el, {
+			value: getAtPath(editor.doc.block(key)?.data, field),
+			options,
+			onChange: (value) => {
+				if (!readOnly()) editor.doc.setField(key, field, value, { origin: 'page' });
+			},
+			onKeyDown: (event) => {
+				const handled = [...editorKeys].some((handler) => handler(event));
+				if (handled) claimed.add(event);
+				return handled;
+			},
+		});
+		const next: Active = { frame, doc, key, field, pe, session: false };
+		active = next;
+		setMounted(doc, {
+			el,
+			key,
+			field,
+			syncAttributes: (from) => pe.syncAttributes(from),
+			teardownForMorph() {
+				if (active !== next) return;
+				resume = { key, field, width: frame.width, ...pe.selection(), focused: next.session };
+				teardown({ blur: false });
+			},
+		});
+		publish();
+		return next;
+	}
+
+	/** Tear the page editor down (Decision 5): the element is left exactly as a render of the current value. */
+	function teardown(options: { blur?: boolean } = {}) {
+		const was = active;
+		if (!was) return;
+		active = null;
+		if (mountedIn(was.doc)?.el === was.pe.el) setMounted(was.doc, null);
+		was.pe.destroy();
+		// Focus doesn't stay on a field that can't be typed in (blur the element, never Tiptap's commands.blur()).
+		if (options.blur !== false && was.doc.activeElement === was.pe.el) was.pe.el.blur();
+		const now = typing.get();
+		if (now && now.key === was.key && now.field === was.field && now.width === was.frame.width) typing.set(null);
+		publish();
+	}
+
+	/** A session starts: focus reached the editor (a click, a tap, Tab, or a remount after a morph). */
+	function startSession(frame: PreviewFrame, a: Active) {
+		a.session = true;
+		typing.set({ key: a.key, field: a.field, width: frame.width });
+		publish();
+		const view = editor.view.get();
+		if (!editor.fieldsOpen(view) || view.block !== a.key || view.field !== a.field) editor.openBlock(a.key, a.field, { picked: true });
+	}
+
+	function attach(frame: PreviewFrame): () => void {
+		const doc = frame.document!;
+		const on = <K extends keyof DocumentEventMap>(type: K, fn: (event: DocumentEventMap[K]) => void, capture = false) => {
+			doc.addEventListener(type, fn as EventListener, capture);
+			return () => doc.removeEventListener(type, fn as EventListener, capture);
+		};
+		const offs = [
+			on('mousemove', (event) => {
+				if (!visible(frame) || !live() || readOnly()) return;
+				const el = elementOf(event.target);
+				const at = el && !inLayer(el) ? locate(el) : null;
+				const next = at ? { block: at.index, field: at.field } : null;
+				const now = hover.get();
+				if (now?.block !== next?.block || now?.field !== next?.field) hover.set(next);
+				// The page editor is mounted before the first press lands (Decision 5); never mid-press.
+				const rich = at?.field && typedOnPage(at.kind, at.field) && isPageRichText(at.fieldEl) ? at.fieldEl : null;
+				pointerOn = rich;
+				if (rich) {
+					// While a session is on in this frame the pointer doesn't matter (Decision 5): the other field mounts on its focus.
+					const session = active?.session && active.frame === frame;
+					if (event.buttons === 0 && !session) mountOn(frame, rich);
+				} else if (active && active.frame === frame && !active.session) teardown();
+			}),
+			// A press that mounts the editor by focus (the pointer crossed the field while another session was on,
+			// so mousemove left it alone): the browser put its caret in the render's text, which the mount replaced.
+			// When the press is released the selection goes from where it was pressed to where it was
+			// released: a caret for a click, the range for a drag.
+			on(
+				'mousedown',
+				(event) => {
+					pressing = event.button === 0 ? { x: event.clientX, y: event.clientY } : null;
+					pressMounted = null;
+				},
+				true,
+			),
+			on(
+				'mouseup',
+				(event) => {
+					const a = pressMounted;
+					const from = pressing;
+					pressing = null;
+					pressMounted = null;
+					if (!a || !from || active !== a || a.pe.destroyed) return;
+					const head = a.pe.view.posAtCoords({ left: event.clientX, top: event.clientY });
+					const anchor = a.pe.view.posAtCoords({ left: from.x, top: from.y }) ?? head;
+					if (head && anchor) a.pe.select(anchor.pos, head.pos);
+				},
+				true,
+			),
+			on('mouseleave', () => {
+				hover.set(null);
+				pointerOn = null;
+				if (active && active.frame === frame && !active.session) teardown();
+			}),
+			on('click', (event) => {
+				if (!visible(frame) || !live() || readOnly()) return;
+				const el = elementOf(event.target);
+				if (!el || inLayer(el)) return;
+				const at = locate(el);
+				if (!at) return;
+				editor.openBlock(at.key, at.field, { picked: !!at.field });
+				// A nested path (`credits.1.name`, `buttons.0.label`) opens its field and the row that holds it.
+				if (at.field && !typedOnPage(at.kind, at.field)) focusSidebarField(at.field);
+			}),
+			on('focusin', (event) => {
+				const el = elementOf(event.target);
+				// Focus moving into the overlay layer (the formatting bar, the link popover's search) keeps the session on.
+				if (el && inLayer(el)) {
+					if (active && active.frame === frame && !active.session) {
+						active.session = true;
+						publish();
+					}
+					return;
+				}
+				if (isPageRichText(el)) {
+					if (!live()) return;
+					if (readOnly()) {
+						el.blur();
+						return;
+					}
+					let a = active && active.pe.el === el ? active : null;
+					if (!a) {
+						// Mounted by focus (a tap, Tab): the caret goes where the browser put it.
+						const point = pointInField(el);
+						a = mountOn(frame, el);
+						if (!a) return;
+						if (pressing) pressMounted = a;
+						// ProseMirror missed this focus event (it wasn't there yet): give it one.
+						const win = frame.window as (Window & typeof globalThis) | null;
+						if (win) a.pe.view.dom.dispatchEvent(new win.FocusEvent('focus'));
+						const pos = point ? positionOf(a.pe.view, point) : null;
+						if (pos !== null) a.pe.select(pos);
+					}
+					startSession(frame, a);
+					return;
+				}
+				if (!el?.matches('[data-cms-kind="text"]') || !live()) return;
+				if (readOnly()) {
+					(el as HTMLElement).blur();
+					return;
+				}
+				const at = locate(el);
+				if (!at?.field) return;
+				typing.set({ key: at.key, field: at.field, width: frame.width });
+				const view = editor.view.get();
+				if (!editor.fieldsOpen(view) || view.block !== at.key || view.field !== at.field) editor.openBlock(at.key, at.field, { picked: true });
+			}),
+			on('focusout', (event) => {
+				const el = elementOf(event.target);
+				if (active && active.frame === frame && el && (el === active.pe.el || inLayer(el))) {
+					const to = elementOf(event.relatedTarget);
+					// Between the text and the layer (the bar, the popover's search): still one session.
+					if (to && to.ownerDocument === doc && (active.pe.el.contains(to) || inLayer(to))) return;
+					active.session = false;
+					const now = typing.get();
+					if (now && now.key === active.key && now.field === active.field && now.width === frame.width) typing.set(null);
+					publish();
+					if (pointerOn !== active.pe.el) teardown({ blur: false });
+					return;
+				}
+				const now = typing.get();
+				if (!now || !el?.matches('[data-cms-kind="text"]') || now.width !== frame.width) return;
+				typing.set(null);
+			}),
+			on('input', (event) => {
+				const el = elementOf(event.target)?.closest('[data-cms-kind="text"]');
+				if (!el || !live() || readOnly()) return;
+				const at = locate(el);
+				if (!at?.field) return;
+				editor.doc.setField(at.key, at.field, fieldText(el, isMultiline(at.key, at.field)), { origin: 'page' });
+			}),
+			on('beforeinput', (event) => {
+				const el = elementOf(event.target)?.closest('[data-cms-kind="text"]');
+				if (!el) return;
+				if (readOnly()) {
+					event.preventDefault();
+					return;
+				}
+				const at = locate(el);
+				if (!at?.field || isMultiline(at.key, at.field)) return;
+				if (event.inputType === 'insertParagraph' || event.inputType === 'insertLineBreak') event.preventDefault();
+			}),
+			on('paste', (event) => {
+				const el = elementOf(event.target)?.closest('[data-cms-kind="text"]');
+				if (!el) return;
+				const at = locate(el);
+				if (!at?.field || isMultiline(at.key, at.field)) return;
+				if (readOnly()) {
+					event.preventDefault();
+					return;
+				}
+				const text = event.clipboardData?.getData('text/plain');
+				if (text === undefined) return;
+				event.preventDefault();
+				doc.execCommand('insertText', false, text.replace(/\s*\n\s*/g, ' '));
+			}),
+			on('keydown', (event) => {
+				const el = elementOf(event.target);
+				const field = el?.closest<HTMLElement>('[data-cms-kind="text"]');
+				const rich = el && active && active.frame === frame && active.pe.el.contains(el) ? active : null;
+				// ⌘\ hides or shows the sidebar from the page too (App.tsx has it for the editor's own window).
+				if ((event.metaKey || event.ctrlKey) && !event.shiftKey && !event.altKey && (event.key === '\\' || event.code === 'Backslash')) {
+					event.preventDefault();
+					editor.setSideHidden(editor.ui.get().side !== 'hidden');
+					return;
+				}
+				// ⌘K opens the document switcher from the page too (App.tsx has it for the editor's own window).
+				// In a rich-text field the rich-text bar claims it first, for the link popover.
+				if ((event.metaKey || event.ctrlKey) && !event.shiftKey && !event.altKey && event.key.toLowerCase() === 'k') {
+					if (claimed.has(event) || event.defaultPrevented) return;
+					event.preventDefault();
+					editor.setPop(editor.view.get().pop === 'switcher' ? null : 'switcher');
+					return;
+				}
+				if (event.key === 'Escape') {
+					// The bar's menu or link popover closed first (rich-text-bar.ts): then the field, then the level.
+					if (claimed.has(event)) return;
+					event.preventDefault();
+					if (field) field.blur();
+					// Leave the rich-text field (view.dom.blur(): Tiptap's commands.blur() clears /admin's selection).
+					else if (rich) rich.pe.view.dom.blur();
+					else editor.goUp();
+					return;
+				}
+				if (event.key === 'Enter' && field) {
+					const at = locate(field);
+					if (at?.field && !isMultiline(at.key, at.field)) {
+						event.preventDefault();
+						field.blur();
+					}
+				}
+			}),
+		];
+		return () => offs.forEach((off) => off());
+	}
+
+	// A hook's cleanup runs before its next run for that frame (after every morph too), so
+	// listeners are kept per document instead: attached once when a frame's document loads.
+	const attached = new WeakSet<Document>();
+	const detachers: (() => void)[] = [];
+	stops.push(
+		driver.registerFrameHook((frame) => {
+			const doc = frame.document;
+			if (!doc || attached.has(doc)) return;
+			attached.add(doc);
+			detachers.push(attach(frame));
+		}),
+	);
+	stops.push(() => detachers.forEach((detach) => detach()));
+
+	// After a morph: a torn-down (or detached) page editor is remounted when the session
+	// or the pointer is still there (Decision 6); a reloaded document drops it.
+	stops.push(
+		driver.registerFrameHook((frame, reason) => {
+			const doc = frame.document;
+			if (active && active.frame.width === frame.width && (reason === 'load' || active.doc !== doc || !active.pe.el.isConnected)) teardown({ blur: false });
+			if (!doc || reason !== 'morph') return;
+			const r = resume && resume.width === frame.width ? resume : null;
+			if (r) resume = null;
+			const pointer = pointerOn && pointerOn.isConnected && pointerOn.ownerDocument === doc ? pointerOn : null;
+			if (r && (r.focused || pointer)) {
+				const index = editor.doc.indexOf(r.key);
+				const el = index >= 0 ? fieldElement(doc, index, r.field, 'richText') : null;
+				const a = el ? mountOn(frame, el) : null;
+				if (a) a.pe.select(r.anchor, r.head, r.focused);
+				return;
+			}
+			if (pointer && !active) mountOn(frame, pointer);
+		}),
+	);
+
+	function reveal(index: number, field?: string | null, options: { instant?: boolean } = {}) {
+		const frame = driver?.frames().find((f) => f.width === editor.view.get().width);
+		const doc = frame?.document;
+		const win = frame?.window;
+		if (!doc || !win) return;
+		const block = blockElement(doc, index);
+		const el = (field && block?.querySelector<HTMLElement>(`[data-cms-field="${CSS.escape(field)}"]`)) || block;
+		// A skipped block has no element, only its comment (skipped.ts): scroll to where it would be.
+		const anchor = el ? null : skippedAnchor(doc, index);
+		if (!el && !anchor) return;
+		const r = el ? el.getBoundingClientRect() : { top: skippedTop(anchor!), bottom: skippedTop(anchor!) };
+		const vh = win.innerHeight;
+		if (!options.instant && r.top >= 40 && r.bottom <= vh - 40) return;
+		if (options.instant && r.top >= 0 && r.top <= vh - 40) return;
+		const scale = editor.stageLayout.get()?.[frame!.width].scale ?? 1;
+		const y = win.scrollY + r.top - Math.min(vh * 0.2, 120 / scale);
+		win.scrollTo({ top: Math.max(0, y), behavior: options.instant || reducedMotion() ? 'auto' : 'smooth' });
+	}
+
+	// Follow the sidebar: a block or field picked there scrolls into view; leaving the block ends typing.
+	stops.push(
+		editor.view.subscribe((view, previous) => {
+			const now = typing.get();
+			if (now && (!editor.fieldsOpen(view) || view.block !== now.key)) {
+				const frame = driver.frames().find((f) => f.width === now.width);
+				const focused = frame?.document?.activeElement as HTMLElement | null | undefined;
+				focused?.blur?.();
+				typing.set(null);
+			}
+			if (!editor.fieldsOpen(view) || !view.block || view.picked || !live()) return;
+			const widthChanged = view.width !== previous.width;
+			if (view.block === previous.block && view.field === previous.field && previous.level === view.level && !widthChanged) return;
+			const index = editor.doc.indexOf(view.block);
+			if (index >= 0) requestAnimationFrame(() => reveal(index, view.field, { instant: widthChanged }));
+		}),
+	);
+	stops.push(editor.view.subscribe((view, previous) => view.width !== previous.width && hover.set(null)));
+	// The page editor goes when the width changes or its block's level closes (Decision 5).
+	stops.push(
+		editor.view.subscribe((view, previous) => {
+			if (!active) return;
+			if (view.width !== previous.width) {
+				pointerOn = null;
+				teardown();
+				return;
+			}
+			const wasOpen = editor.fieldsOpen(previous) && previous.block === active.key;
+			const isOpen = editor.fieldsOpen(view) && view.block === active.key;
+			if (wasOpen && !isOpen) teardown();
+		}),
+	);
+	// A change from elsewhere reaches the mounted editor (Decision 8: without an update, its own echo
+	// ignored); another document opening, or its block going, tears it down.
+	stops.push(
+		editor.doc.subscribe((_session, change) => {
+			if (!active) return;
+			if (change.kind === 'load') {
+				teardown();
+				return;
+			}
+			const block = editor.doc.block(active.key);
+			if (!block) {
+				teardown();
+				return;
+			}
+			active.pe.setValue(block.data[active.field]);
+		}),
+	);
+	// Going read-only mid-typing (a lock arrived, signed out): leave the field on the page.
+	stops.push(
+		editor.access.subscribe((access) => {
+			if (!access.readOnly) return;
+			hover.set(null);
+			// Decision 10: the page editor goes at once; the value already stored stays.
+			resume = null;
+			teardown();
+			const now = typing.get();
+			if (!now) return;
+			const frame = driver.frames().find((f) => f.width === now.width);
+			(frame?.document?.activeElement as HTMLElement | null | undefined)?.blur?.();
+			typing.set(null);
+		}),
+	);
+
+	const pageEdit: PageEdit = {
+		typing,
+		pageEditor,
+		hover,
+		onEditorKey(handler) {
+			editorKeys.add(handler);
+			return () => editorKeys.delete(handler);
+		},
+		claimKey(event) {
+			claimed.add(event);
+		},
+		reveal,
+		destroy() {
+			teardown();
+			for (const stop of stops) stop();
+		},
+	};
+	made.set(editor, pageEdit);
+	return pageEdit;
+}