caracms 0.0.0-stage → 0.2.0

package/src/editor/client/block-list/BlockList.tsx

@@ -0,0 +1,342 @@
+/**
+ * The block list (the mockup's #blocks, #removed, #drag, #unknown): a section-builder
+ * document's blocks, one row each.
+ *
+ * - **Hover** sets `blockHover(editor)` (link.ts), and a row is drawn hovered while
+ *   that store holds its key, so the preview's overlays can follow it both ways.
+ *   **Selected** (`.is-current`) is `editor.view.block`.
+ * - **Reorder by drag** (the grip; the drop line is full width) **and by keys**
+ *   (M2's keys rule, on a focused row): ⌥↑/⌥↓ move it, ⌫ removes it (with Undo:
+ *   the toast and ⌘Z, Decision 18), Enter opens it, ↑/↓ move between rows. The row
+ *   menu has the same moves with their keys.
+ * - **An unknown block** (Decisions 7 and 21) is marked Skipped with its kept keys
+ *   summarised; it moves and is removed like any block, and opens to a panel, not
+ *   fields. The serializer writes it back as read (by its `source`).
+ *
+ * Everything that changes the document goes through `editor.doc` (document-store.ts).
+ */
+import { own } from '../../../document.ts';
+import { fieldHoldsMedia, fieldWarnings, type Field } from '../../../fields.ts';
+import { useEffect, useRef, useState, type KeyboardEvent } from 'react';
+import { useEditor, useStore } from '../context.tsx';
+import { Icon } from '../shell/Icons.tsx';
+import { blockLabel } from '../state/document-store.ts';
+import { offersBlock } from '../state/schema.ts';
+import { sameDoc, type EditorBlock, type EditorSite } from '../../types.ts';
+import { blockHover, openPicker, setBlockHover } from './link.ts';
+import { rowKeyAction, useRowDrag } from './reorder.ts';
+import { blockIcon, blockSummary, sharedOf, usedOnLine } from './summary.ts';
+
+export function BlockList() {
+	const editor = useEditor();
+	const blocks = useStore(editor.doc.state, (s) => s.document.blocks);
+	const title = useStore(editor.doc.state, (s) => s.document.title || s.entry.label);
+	const current = useStore(editor.view, (v) => v.block);
+	const hovered = useStore(blockHover(editor));
+	// The row's marks beside the name (the mockup's browHTML): too long for mobile, and has its own phone lines.
+	const showing = useStore(editor.previewStatus, (s) => s.showing);
+	const warnings = useStore(editor.previewStatus, (s) => s.warnings);
+	const ref = useStore(editor.doc.state, (s) => s.ref);
+	const tooLong = new Set(sameDoc(showing, ref) ? warnings.filter((w) => w.tooLong).map((w) => w.block) : []);
+	// Read-only (M4: a lock, held edits, signed out): rows still open their blocks, nothing moves or goes.
+	const readOnly = useStore(editor.access, (a) => a.readOnly);
+	const documents = useStore(editor.documents);
+	const [menu, setMenu] = useState<string | null>(null);
+	const list = useRef<HTMLOListElement>(null);
+	/** A row (by key) to focus once the list has re-rendered: after a keyboard move or remove. */
+	const focusNext = useRef<string | 'add' | null>(null);
+
+	useEffect(() => {
+		const want = focusNext.current;
+		if (!want) return;
+		focusNext.current = null;
+		const el =
+			want === 'add'
+				? list.current?.parentElement?.querySelector<HTMLElement>('.add-row')
+				: list.current?.querySelector<HTMLElement>(`.brow[data-block-key="${want}"] .brow-main`);
+		el?.focus();
+	});
+
+	// A row hovered or focused when the list goes (the picker opens, a block opens) isn't hovered any more.
+	useEffect(() => () => setBlockHover(editor, null), [editor]);
+
+	// The row menu closes on a click outside it.
+	useEffect(() => {
+		if (!menu) return;
+		const onDown = (event: MouseEvent) => {
+			const target = event.target as Element | null;
+			if (target?.closest?.('.menu') || target?.closest?.('.brow-more')) return;
+			setMenu(null);
+		};
+		document.addEventListener('mousedown', onDown);
+		return () => document.removeEventListener('mousedown', onDown);
+	}, [menu]);
+
+	// A shared entry that renders (M5a Decision 8) is named by its shared block; one that's skipped stays "Unknown block".
+	const label = (b: EditorBlock) => sharedOf(editor.site, documents, b)?.label ?? blockLabel(editor.site, b);
+
+	const move = (key: string, to: number, viaKeys: boolean) => {
+		const from = editor.doc.indexOf(key);
+		const block = editor.doc.block(key);
+		if (!block || from < 0 || to < 0 || to >= blocks.length || to === from) return;
+		if (viaKeys) focusNext.current = key;
+		editor.doc.moveBlock(key, to);
+		editor.announce(`Moved ${label(block)} to ${to + 1} of ${blocks.length}`);
+	};
+
+	const remove = (key: string, viaKeys: boolean) => {
+		const index = editor.doc.indexOf(key);
+		const block = editor.doc.block(key);
+		if (!block) return;
+		if (viaKeys) focusNext.current = blocks[index + 1]?.key ?? blocks[index - 1]?.key ?? 'add';
+		editor.doc.removeBlock(key);
+		editor.announce(`Removed ${label(block)}. Undo with Command Z.`);
+	};
+
+	const onRowKey = (event: KeyboardEvent<HTMLButtonElement>, block: EditorBlock, index: number) => {
+		if (readOnly && (event.altKey || event.key === 'Backspace' || event.key === 'Delete')) return;
+		const action = rowKeyAction(event, index, blocks.length);
+		if (action?.kind === 'move') move(block.key, action.to, true);
+		else if (action?.kind === 'remove') remove(block.key, true);
+		else if (action?.kind === 'focus') list.current?.querySelector<HTMLElement>(`.brow[data-block-key="${blocks[action.to]!.key}"] .brow-main`)?.focus();
+	};
+
+	// Drag (HTML drag and drop on the rows; the drop line is the mockup's): reorder.ts, shared with M5a's lists.
+	const rows = useRowDrag({
+		rowOf: (target) => target.closest?.('.brow[data-block-key]') as HTMLElement | null,
+		keyOf: (row) => row.dataset.blockKey!,
+		indexOf: (key) => editor.doc.indexOf(key),
+		onMove: (key, to) => move(key, to, false),
+		onStart: () => setMenu(null),
+	});
+	const drag = rows.drag;
+
+	const dragged = drag ? blocks.find((b) => b.key === drag.key) : undefined;
+	const target = drag?.drop ? blocks.find((b) => b.key === drag.drop!.key) : undefined;
+
+	return (
+		<>
+			<ol
+				ref={list}
+				className="blist"
+				aria-label={`Blocks on ${title}`}
+				onMouseLeave={() => setBlockHover(editor, null)}
+				onDragOver={rows.over}
+				onDrop={rows.drop}
+			>
+				{blocks.map((block, i) => {
+					const name = label(block);
+					const shared = sharedOf(editor.site, documents, block);
+					const skipped = !block.known && !shared;
+					const type = shared?.blockType ?? (block.known ? block.type : null);
+					const notOffered = !!type && !offersBlock(editor.site, ref.collection, type);
+					const cls = [
+						'brow',
+						current === block.key && !drag ? 'is-current' : '',
+						skipped ? 'is-unknown' : '',
+						readOnly ? 'is-disabled' : '',
+						hovered === block.key && !drag ? 'hov' : '',
+						rows.classes(block.key),
+					]
+						.filter(Boolean)
+						.join(' ');
+					return (
+						<li
+							key={block.key}
+							className={cls}
+							data-block-key={block.key}
+							data-block-type={shared?.blockType ?? block.type}
+							data-shared={shared ? shared.path : undefined}
+							draggable={!readOnly}
+							onMouseEnter={() => setBlockHover(editor, block.key)}
+							onDragStart={(e) => rows.start(e, block.key)}
+							onDragEnd={rows.cancel}
+						>
+							<button
+								type="button"
+								className="brow-main"
+								aria-current={current === block.key ? 'true' : undefined}
+								aria-label={`${name}${shared ? ', shared' : ''}, ${i + 1} of ${blocks.length}${skipped ? ', skipped' : ''}. Alt and arrow keys move it`}
+								onClick={() => editor.openBlock(block.key)}
+								onKeyDown={(e) => onRowKey(e, block, i)}
+								onFocus={() => setBlockHover(editor, block.key)}
+								onBlur={() => {
+									if (blockHover(editor).get() === block.key) setBlockHover(editor, null);
+								}}
+							>
+								<span className="grip" aria-hidden="true">
+									{readOnly ? null : <Icon name="grip" />}
+								</span>
+								<span className="bi">
+									<Icon name={blockIcon(shared ? { type: shared.blockType!, known: true } : block)} />
+								</span>
+								<span className="bt">
+									<span className="nm">
+										{name}
+										{shared ? (
+											<span className="chip shared" data-chip="shared">
+												<Icon name="shared" size="xs" />
+												Shared
+											</span>
+										) : null}
+										{!skipped ? null : (
+											<span className="chip warn" title="Its type isn't in the site's code: kept in the file, skipped on the page">
+												<Icon name="warn" size="xs" />
+												Skipped
+											</span>
+										)}
+										{notOffered ? (
+											<span className="chip warn" title="Not offered by this collection" data-chip="not-offered">
+												<Icon name="warn" size="xs" />
+												Not offered here
+											</span>
+										) : null}
+										{tooLong.has(i) ? (
+											<span className="chip warn" title="Too long for mobile" data-chip="too-long">
+												<Icon name="phone" size="xs" />
+												Long
+											</span>
+										) : null}
+										{altGaps(editor.site, block) ? (
+											<span className="chip warn" title="An image has no alt text" data-chip="alt">
+												<Icon name="image" size="xs" />
+												Alt
+											</span>
+										) : null}
+										{hasPhoneLines(editor.site, block) ? (
+											<span className="chip phone" title="Has its own lines on Phone" data-chip="phone-lines">
+												<Icon name="phone" size="xs" />
+											</span>
+										) : null}
+									</span>
+									<span className="sm">{shared ? usedOnLine(shared) : blockSummary(editor.site, block, editor.forms)}</span>
+								</span>
+							</button>
+							{readOnly ? null : (
+							<button
+								type="button"
+								className="ib brow-more"
+								aria-label={`Actions for ${name}`}
+								aria-haspopup="menu"
+								aria-expanded={menu === block.key}
+								onClick={() => setMenu(menu === block.key ? null : block.key)}
+							>
+								<Icon name="more" />
+							</button>
+							)}
+							{menu === block.key && !readOnly ? (
+								<RowMenu
+									first={i === 0}
+									last={i === blocks.length - 1}
+									onClose={() => {
+										setMenu(null);
+										list.current?.querySelector<HTMLElement>(`.brow[data-block-key="${block.key}"] .brow-more`)?.focus();
+									}}
+									onMove={(dir) => {
+										setMenu(null);
+										move(block.key, i + dir, true);
+									}}
+									onRemove={() => {
+										setMenu(null);
+										remove(block.key, true);
+									}}
+								/>
+							) : null}
+						</li>
+					);
+				})}
+			</ol>
+			<button type="button" className="add-row" disabled={readOnly} onClick={() => openPicker(editor, blocks.length)}>
+				<Icon name="plus" />
+				Add block
+			</button>
+			{!readOnly && drag && dragged && target && target.key !== dragged.key ? (
+				<p className="kb-hint" role="status" style={{ color: 'var(--select-strong)' }}>
+					Drop to put {label(dragged)} {drag.drop!.after ? 'below' : 'above'} {label(target)}.
+				</p>
+			) : null}
+		</>
+	);
+}
+
+function RowMenu(props: { first: boolean; last: boolean; onClose: () => void; onMove: (dir: -1 | 1) => void; onRemove: () => void }) {
+	const menu = useRef<HTMLDivElement>(null);
+	useEffect(() => {
+		menu.current?.querySelector<HTMLButtonElement>('button:not(:disabled)')?.focus();
+	}, []);
+	const onKey = (event: KeyboardEvent<HTMLDivElement>) => {
+		if (event.key === 'Escape') {
+			// Closes the menu only; App.tsx would otherwise go up a level.
+			event.preventDefault();
+			props.onClose();
+			return;
+		}
+		if (event.key === 'ArrowDown' || event.key === 'ArrowUp') {
+			event.preventDefault();
+			const items = [...(menu.current?.querySelectorAll<HTMLButtonElement>('button:not(:disabled)') ?? [])];
+			const at = items.indexOf(document.activeElement as HTMLButtonElement);
+			items[(at + (event.key === 'ArrowDown' ? 1 : -1) + items.length) % items.length]?.focus();
+		}
+	};
+	return (
+		<div ref={menu} className="menu" role="menu" style={{ right: 4, top: 'calc(100% + 2px)' }} onKeyDown={onKey}>
+			<button type="button" role="menuitem" disabled={props.first} onClick={() => props.onMove(-1)}>
+				<Icon name="up" />
+				Move up
+				<span className="k">
+					<kbd>⌥</kbd>
+					<kbd>↑</kbd>
+				</span>
+			</button>
+			<button type="button" role="menuitem" disabled={props.last} onClick={() => props.onMove(1)}>
+				<Icon name="down" />
+				Move down
+				<span className="k">
+					<kbd>⌥</kbd>
+					<kbd>↓</kbd>
+				</span>
+			</button>
+			<hr />
+			<button type="button" role="menuitem" className="danger" onClick={props.onRemove}>
+				<Icon name="trash" />
+				Remove
+				<span className="k">
+					<kbd>⌫</kbd>
+				</span>
+			</button>
+		</div>
+	);
+}
+
+/** A block with a lockup that has its own phone lines (Decision 10's object form), at the top level or inside a group. */
+function hasPhoneLines(site: EditorSite, block: EditorBlock): boolean {
+	if (!block.known) return false;
+	const fields = own(site.blocks, block.type)?.fields ?? {};
+	const phoned = (field: Field, value: unknown) => {
+		const phone = field.kind === 'lockup' && !!value && typeof value === 'object' ? (value as { phone?: unknown }).phone : undefined;
+		return Array.isArray(phone) && phone.length > 0;
+	};
+	return Object.entries(fields).some(([name, field]) => {
+		const value = block.data[name];
+		if (field.kind !== 'group') return phoned(field, value);
+		const inner = value && typeof value === 'object' ? (value as Record<string, unknown>) : {};
+		return Object.entries(field.fields).some(([key, f]) => phoned(f, inner[key]));
+	});
+}
+
+/**
+ * How many images in a block's rendered slots have no alt text (M5b Decision 9: the field's
+ * own `missing-alt` warning, so a decorative image never counts). The mockup's browHTML
+ * marks such a block (its "Alt" chip); it blocks nothing. An
+ * unknown block isn't rendered, and a shared entry's images are its shared block's.
+ */
+export function altGaps(site: EditorSite, block: EditorBlock): number {
+	if (!block.known || block.shared) return 0;
+	const fields = own(site.blocks, block.type)?.fields ?? {};
+	let n = 0;
+	for (const [name, field] of Object.entries(fields)) {
+		if (!fieldHoldsMedia(field)) continue;
+		n += fieldWarnings(field, block.data[name]).filter((w) => w.code === 'missing-alt').length;
+	}
+	return n;
+}

package/src/editor/client/block-list/Picker.tsx

@@ -0,0 +1,105 @@
+/**
+ * The add-block picker (the mockup's #picker): on the document level, in place of
+ * the block list, while `pickerAt(editor)` holds an index (link.ts → openPicker).
+ * The site's block types, each with its fields; picking one adds an empty block of
+ * that type at the index and opens it. Back, or Esc, returns to the list.
+ *
+ * M5a: the Shared blocks section inserts a shared block's entry (`{ "shared": name }`),
+ * not a copy (Decision 8).
+ */
+import { own } from '../../../document.ts';
+import { useEffect, useRef } from 'react';
+import { useEditor, useStore } from '../context.tsx';
+import { Icon } from '../shell/Icons.tsx';
+import { blockLabel } from '../state/document-store.ts';
+import { offeredBlocks, offersBlock } from '../state/schema.ts';
+import { CurrentHead, DocumentsTab, GlobalNotes, LevelTab, RecentStrip, Trail } from '../pane/parts.tsx';
+import { closePicker } from './link.ts';
+import { blockIcon, fieldsSummary, sharedOf, usedOnLine } from './summary.ts';
+
+export function Picker({ at }: { at: number }) {
+	const editor = useEditor();
+	const blocks = useStore(editor.doc.state, (s) => s.document.blocks);
+	const title = useStore(editor.doc.state, (s) => s.document.title || s.entry.label);
+	const documents = useStore(editor.documents);
+	const collection = useStore(editor.doc.state, (s) => s.ref.collection);
+	const body = useRef<HTMLDivElement>(null);
+	const before = blocks[at - 1];
+	const n = blocks.length;
+
+	useEffect(() => {
+		body.current?.querySelector<HTMLElement>('.ptype')?.focus();
+		// Esc closes the picker, before App.tsx's Esc would go up a level.
+		const onKey = (event: KeyboardEvent) => {
+			if (event.key !== 'Escape' || event.defaultPrevented || editor.view.get().pop) return;
+			event.preventDefault();
+			closePicker(editor);
+		};
+		window.addEventListener('keydown', onKey, true);
+		return () => window.removeEventListener('keydown', onKey, true);
+	}, [editor]);
+
+	// The collection's offered blocks (config.ts `blocks`), else every block.
+	const offered = offeredBlocks(editor.site, collection);
+	const types = offered ? offered.map((type) => own(editor.site.blocks, type)).filter((b) => !!b) : Object.values(editor.site.blocks);
+	// M5a Decision 8: the shared blocks that render (their type is one the site knows), of a type the collection offers.
+	const shared = documents.filter((d) => d.collection === 'shared' && !d.warning && !!d.blockType && !!own(editor.site.blocks, d.blockType) && offersBlock(editor.site, collection, d.blockType));
+	const pickShared = (name: string, label: string) => {
+		const key = editor.doc.addShared(name, at);
+		closePicker(editor);
+		editor.openBlock(key);
+		editor.announce(`Added ${label}, a shared block`);
+	};
+
+	const pick = (type: string) => {
+		const key = editor.doc.addBlock(type, at);
+		closePicker(editor);
+		editor.openBlock(key);
+		editor.announce(`Added ${own(editor.site.blocks, type)?.label ?? type}`);
+	};
+
+	return (
+		<>
+			<Trail>
+				<DocumentsTab />
+				<LevelTab name={title} kind="Blocks" count={`${n} block${n === 1 ? '' : 's'}`} onClick={() => closePicker(editor)} />
+				<CurrentHead
+					back={{ label: `Back to ${title}`, onClick: () => closePicker(editor) }}
+					crumb={title}
+					title="Add a block"
+					sub={before ? `After ${sharedOf(editor.site, documents, before)?.label ?? blockLabel(editor.site, before)}` : n ? 'At the top of the page' : 'The first block on the page'}
+				/>
+			</Trail>
+			<div className="side-body" ref={body} data-picker-at={at}>
+				<GlobalNotes />
+				<p className="sec-h">Blocks</p>
+				<div className="picker-grid">
+					{types.map((schema) => (
+						<button key={schema.type} type="button" className="ptype" data-type={schema.type} onClick={() => pick(schema.type)}>
+							<span className="sk">
+								<Icon name={blockIcon({ type: schema.type, known: true })} />
+							</span>
+							<b>{schema.label}</b>
+							<small>{fieldsSummary(schema)}</small>
+						</button>
+					))}
+				</div>
+				{shared.length ? (
+					<>
+						<p className="sec-h" data-section="shared-blocks">
+							Shared blocks
+						</p>
+						{shared.map((d) => (
+							<button key={d.path} type="button" className="drow" data-shared={d.path} onClick={() => pickShared(d.path, d.label)}>
+								<Icon name="shared" />
+								<span className="nm">{d.label}</span>
+								<span className="meta">{usedOnLine(d)}</span>
+							</button>
+						))}
+					</>
+				) : null}
+			</div>
+			<RecentStrip />
+		</>
+	);
+}

package/src/editor/client/block-list/UnknownBlock.tsx

@@ -0,0 +1,119 @@
+/**
+ * An unknown block's panel (the mockup's #unknown, its unknownPanel; Decisions 7
+ * and 21), for the block level to show in place of fields when the open block's
+ * type isn't in the site's config:
+ *
+ *   {block.known ? <fields…/> : <UnknownBlockPanel block={block} />}
+ *
+ * It says the block is kept in the file and skipped on the page, lists what's kept
+ * (its top-level keys, each with a short preview of its value), and offers Remove,
+ * with Undo. It can't be edited.
+ */
+import { useEditor, useStore } from '../context.tsx';
+import { Icon } from '../shell/Icons.tsx';
+import type { EditorBlock } from '../../types.ts';
+import { keptSummary, sharedOf } from './summary.ts';
+import { sharedEntryOf } from '../../../document.ts';
+
+export function UnknownBlockPanel({ block }: { block: EditorBlock }) {
+	const editor = useEditor();
+	const readOnly = useStore(editor.access, (a) => a.readOnly);
+	const documents = useStore(editor.documents);
+	const kept = keptSummary(block.data);
+	const remove = () => {
+		editor.doc.removeBlock(block.key);
+		editor.goTo('document');
+		editor.announce('Removed Unknown block. Undo with Command Z.');
+	};
+	const removeEntry = () => {
+		editor.doc.removeBlock(block.key, { label: `Removed ${sharedOf(editor.site, documents, block)?.label ?? 'shared block'}` });
+		editor.goTo('document');
+		editor.announce('Removed the shared block from this page. Undo with Command Z.');
+	};
+	// A shared-block entry (M5a Decision 8): selected, moved and removed like a block, never
+	// edited here. One that renders offers its own document (the mockup's #shared panel).
+	const entry = sharedEntryOf(block);
+	const shared = entry !== undefined ? sharedOf(editor.site, documents, block) : null;
+	if (shared) {
+		const used = (shared.usedOn ?? []).map((u) => documents.find((d) => d.collection === u.collection && d.path === u.path)?.label ?? u.path);
+		const n = used.length;
+		return (
+			<div className="panel" data-shared-entry={entry} data-shared-panel="">
+				<h3>{shared.label} is a shared block</h3>
+				<p>Edit it in Shared blocks; it's on every page that uses it.</p>
+				<div className="used">
+					{used.map((t, i) => (
+						<span key={`${i}:${t}`} className="chip shared">
+							{t}
+						</span>
+					))}
+				</div>
+				<div className="acts">
+					<button type="button" className="btn ink" data-act="edit-shared" onClick={() => void editor.openDocument({ collection: 'shared', path: shared.path })}>
+						<Icon name="shared" size="sm" />
+						Edit {shared.label} (used on {n} page{n === 1 ? '' : 's'})
+					</button>
+					<button type="button" className="btn" disabled={readOnly} onClick={removeEntry}>
+						Remove from this page
+					</button>
+				</div>
+			</div>
+		);
+	}
+	if (entry !== undefined) {
+		// Skipped on the page (Phase 2's warning): no such shared block, or a type the code doesn't know.
+		const listedShared = documents.find((d) => d.collection === 'shared' && d.path === entry && !d.warning);
+		const name = listedShared?.label ?? entry;
+		return (
+			<div data-unknown-block={block.key} data-shared-entry={entry}>
+				<div className="note warn">
+					<Icon name="warn" />
+					<div>
+						<b>{!listedShared ? `There's no shared block "${entry}"` : `${name}'s type isn't in the site's code any more`}</b>
+						<p>Skipped on the page; kept in the file.</p>
+					</div>
+				</div>
+				<div className="panel">
+					<div className="acts">
+						<button type="button" className="btn" disabled={readOnly} onClick={remove}>
+							Remove from this page
+						</button>
+					</div>
+				</div>
+			</div>
+		);
+	}
+	return (
+		<div data-unknown-block={block.key}>
+			<div className="note warn">
+				<Icon name="warn" />
+				<div>
+					<b>This block's type isn't in the site's code any more</b>
+					<p>
+						<span className="mono">{block.type || 'No type'}</span> is skipped on the page; kept in the file.
+					</p>
+				</div>
+			</div>
+			<div className="panel">
+				<h3>What's kept</h3>
+				{kept.length ? (
+					<dl className="kept">
+						{kept.map((k) => (
+							<div key={k.key}>
+								<dt>{k.label}</dt>
+								<dd>{k.preview}</dd>
+							</div>
+						))}
+					</dl>
+				) : (
+					<p>Nothing but its type.</p>
+				)}
+				<div className="acts">
+					<button type="button" className="btn" disabled={readOnly} onClick={remove}>
+						Remove block
+					</button>
+				</div>
+			</div>
+		</div>
+	);
+}

package/src/editor/client/block-list/insert-points.ts

@@ -0,0 +1,56 @@
+/**
+ * The empty page's invitation in the preview (the mockup's renderPreview:
+ * `.cms-empty .cms-add`), painted into Phase 3's overlay layer (client/overlays): a
+ * dashed area where its blocks would go (Blocks.astro's preview-only
+ * `data-cms-empty`) with "+ Add the first block", in every frame. A click opens the
+ * add-block picker at 0 (link.ts → openPicker).
+ *
+ * (The "+ Add block" points on a selected block's edges went in the pre-M7 polish:
+ * the sidebar's Add block row is the one way to add after the first.) Nothing is
+ * drawn while the preview shows another document than the sidebar (one is opening).
+ *
+ *   startEmptyPageAdd(editor)   // a stop; DocumentsLevel mounts it once (it's always mounted)
+ */
+import type { Editor } from '../editor.ts';
+import { overlaysFor } from '../overlays/index.ts';
+import { sameDoc } from '../../types.ts';
+import { openPicker } from './link.ts';
+
+/** Whether the preview offers "+ Add the first block" now (pure apart from reading stores). */
+export function offersFirstBlock(editor: Pick<Editor, 'doc' | 'previewStatus'>): boolean {
+	const status = editor.previewStatus.get();
+	const session = editor.doc.get();
+	if (status.opening || !sameDoc(status.showing, session.ref)) return false;
+	// Only a section builder has blocks (M5a: not a form or a shared block).
+	return session.document.kind === 'sections' && session.document.blocks.length === 0;
+}
+
+export function startEmptyPageAdd(editor: Editor): () => void {
+	const overlays = overlaysFor(editor);
+	if (!overlays) return () => {};
+
+	const remove = overlays.addPainter((ctx) => {
+		if (!offersFirstBlock(editor)) return null;
+		const area = ctx.doc.querySelector('[data-cms-empty]');
+		if (!area) return null;
+		const box = ctx.el('div', 'cms-empty');
+		box.setAttribute('style', ctx.place(ctx.rect(area, -24)));
+		const b = ctx.el('button', 'cms-add');
+		b.type = 'button';
+		b.dataset.ins = '0';
+		b.textContent = '+ Add the first block';
+		// The page's own handlers (click to edit) ignore the layer; keep the press here anyway.
+		b.addEventListener('mousedown', (event) => event.stopPropagation());
+		b.addEventListener('click', (event) => {
+			event.preventDefault();
+			event.stopPropagation();
+			openPicker(editor, 0);
+		});
+		box.appendChild(b);
+		return box;
+	});
+
+	const redraw = () => overlays.redraw();
+	const stops = [remove, editor.doc.state.subscribe(redraw), editor.previewStatus.subscribe(redraw)];
+	return () => stops.forEach((stop) => stop());
+}