caracms 0.4.0 → 0.5.0

package/src/editor/client/arrange/store.ts

@@ -0,0 +1,335 @@
+/**
+ * Arrange pages (notes/2026-10-25-arrange-pages.md): the screen's state and actions, one
+ * per editor (`arrangeFor(editor)`), read by the stage (ArrangeStage.tsx) and the pane's
+ * level (pane/levels/ArrangeLevel.tsx). Nothing is saved until Apply (Decision 15): the
+ * state starts again from the listing each time the screen opens, and a reload does too.
+ *
+ *   arrange.state          { mode, orig, tree, drag, naming, renaming, collapsed, … }
+ *   arrange.plan()         what it means (model.ts → makePlan), worked out once per tree
+ *   arrange.drop(id, t) / newGroup() / rename… / remove(id)
+ *   arrange.review() / back() / apply()
+ *   arrange.leave(go?)     asks first when there are changes (the leave dialog), then goes
+ *
+ * Apply (Decision 10): this tab's unsent edits to what moves go first (as Change address…),
+ * then one POST of the plan's request. A refusal re-reads the listing, re-plans the same
+ * arrangement on it and shows the review again, naming what changed; a lock refusal names
+ * the person and the document.
+ */
+import { isOrderedCollection, listingStamp } from '../../../page-order.ts';
+import { SETTINGS_PATH } from '../../../reserved.ts';
+import type { Editor } from '../editor.ts';
+import { closeDialog, openDialog } from '../documents/dialogs.tsx';
+import { createStore, type Store } from '../state/store.ts';
+import { docId, ENDPOINTS, TAB_HEADER, type ArrangeRequest, type DocRef, type LockRefusal, type Person } from '../../types.ts';
+import { addGroup, buildTree, dropNode, indexTree, locate, makePlan, nameCheck, rebase, removeNode, renameGroup, type ArrangeNode, type ArrangeSite, type DropTarget, type Plan } from './model.ts';
+
+export type ArrangeNote =
+	| { kind: 'lock'; person: Person | null; error: string }
+	| { kind: 'underneath'; lines: string[]; clashes: string[] }
+	| { kind: 'refused'; error: string }
+	| { kind: 'failed'; error: string };
+
+export interface ArrangeState {
+	/** Arranging, the review, or the review while Apply runs. */
+	mode: 'arrange' | 'review' | 'applying';
+	/** The tree as the listing had it when the screen opened (or at the last re-plan), and as arranged. */
+	orig: ArrangeNode[];
+	tree: ArrangeNode[];
+	/** Mid-drag: the row and where it would land (null: nowhere). */
+	drag: { id: string; target: DropTarget | null } | null;
+	/** New group, being named; Rename… on a group, inline. */
+	naming: { value: string } | null;
+	renaming: { id: string; value: string } | null;
+	/** Rows whose rows under them are hidden (the screen's twisties). */
+	collapsed: string[];
+	/** Holders whose documents the review shows one by one. */
+	openHeld: string[];
+	/** "Leave redirects from the old addresses" (Decision 3). */
+	tick: boolean;
+	note: ArrangeNote | null;
+	/** After a re-plan: rows and held documents added since the screen opened. */
+	added: string[];
+	addedDocs: string[];
+	/** New groups made so far (their ids). */
+	made: number;
+	/** The row an entry of the review points at while hovered (washed on the screen). */
+	linked: string | null;
+}
+
+export interface Arrange {
+	state: Store<ArrangeState>;
+	site: ArrangeSite;
+	plan(): Plan;
+	/** Why Review… is off, as text and bold parts in turn; null when it's on. */
+	blocked(): string[] | null;
+	reset(): void;
+	setDrag(drag: ArrangeState['drag']): void;
+	drop(id: string, target: DropTarget): void;
+	newGroup(): void;
+	setNaming(value: string | null): void;
+	confirmNaming(): void;
+	startRename(id: string): void;
+	setRenaming(value: string | null): void;
+	confirmRename(): void;
+	remove(id: string): void;
+	toggleCollapsed(id: string): void;
+	toggleHeld(id: string): void;
+	setLinked(id: string | null): void;
+	setTick(tick: boolean): void;
+	review(): void;
+	back(): void;
+	apply(): Promise<void>;
+	/** Leave the screen (Cancel, Back, the trail): asks first when anything is arranged. */
+	leave(go?: () => void): void;
+}
+
+const all = new WeakMap<Editor, Arrange>();
+const clone = <T>(x: T): T => JSON.parse(JSON.stringify(x)) as T;
+
+/** The collection the screen arranges (`pages`): the one the saved order is for, by the server's rule (page-order.ts). */
+export function arrangeSite(editor: Pick<Editor, 'site'>): ArrangeSite {
+	const pages = editor.site.collections.find(isOrderedCollection);
+	return {
+		collection: pages?.name ?? 'pages',
+		base: pages?.urlBase ?? '/',
+		home: editor.site.home.collection === pages?.name ? editor.site.home.path : 'index',
+		collections: editor.site.collections,
+		codeRoutes: editor.site.codeRoutes,
+	};
+}
+
+export function arrangeFor(editor: Editor): Arrange {
+	const had = all.get(editor);
+	if (had) return had;
+	const site = arrangeSite(editor);
+	const start = (): ArrangeState => {
+		const orig = buildTree(site, editor.documents.get());
+		return { mode: 'arrange', orig, tree: clone(orig), drag: null, naming: null, renaming: null, collapsed: [], openHeld: [], tick: true, note: null, added: [], addedDocs: [], made: 0, linked: null };
+	};
+	const state = createStore<ArrangeState>(start());
+	let cached: { orig: ArrangeNode[]; tree: ArrangeNode[]; waiting: unknown; plan: Plan } | null = null;
+	const plan = () => {
+		const { orig, tree } = state.get();
+		const waiting = editor.liveState.get().status?.waiting;
+		if (cached && cached.orig === orig && cached.tree === tree && cached.waiting === waiting) return cached.plan;
+		// Made since the last Publish, or moved since and already redirected: no live address there to leave a redirect from.
+		const pending = (collection: string, path: string) => (waiting ?? []).some((w) => w.collection === collection && w.path === path && (w.change === 'new' || !!w.movedFrom));
+		cached = { orig, tree, waiting, plan: makePlan(site, orig, tree, { pending }) };
+		return cached.plan;
+	};
+	/** A change to the tree, on a copy (the plan is worked out again from it). */
+	const change = (edit: (tree: ArrangeNode[]) => void, patch: Partial<ArrangeState> = {}) => {
+		const tree = clone(state.get().tree);
+		edit(tree);
+		state.update({ tree, ...patch });
+	};
+	const parentOf = (id: string) => locate(state.get().tree, id)?.parentId ?? null;
+	const goToDocuments = () => {
+		void editor.openDocument(editor.doc.get().ref, { history: 'push' }).then(() => editor.goTo('documents'));
+	};
+
+	const arrange: Arrange = {
+		state,
+		site,
+		plan,
+		blocked() {
+			const s = state.get();
+			if (s.naming) return ['Finish naming the new group first.'];
+			if (s.renaming) return [`Finish renaming ${locate(s.tree, s.renaming.id)?.node.label ?? 'the group'} first.`];
+			const p = plan();
+			if (p.emptyFresh.length) return ['', p.emptyFresh[0]!.label, ' is empty: add a page to it or remove it.'];
+			if (!p.any) return ['Nothing to review yet.'];
+			return null;
+		},
+		reset() {
+			cached = null;
+			state.set(start());
+		},
+		setDrag(drag) {
+			state.update({ drag });
+		},
+		drop(id, target) {
+			if (target.kind === 'refused') return state.update({ drag: null });
+			change((tree) => dropNode(tree, id, target), { drag: null });
+		},
+		newGroup() {
+			state.update({ naming: { value: '' }, renaming: null });
+		},
+		setNaming(value) {
+			state.update({ naming: value === null ? null : { value } });
+		},
+		confirmNaming() {
+			const s = state.get();
+			if (!s.naming) return;
+			const c = nameCheck(site, s.tree, s.naming.value, null, null);
+			if (c.bad) return;
+			// A group named like a page at the top level is that page (Decision 8): nothing to add.
+			if (c.merge) return state.update({ naming: null });
+			change((tree) => addGroup(tree, s.naming!.value, s.made + 1), { naming: null, made: s.made + 1 });
+		},
+		startRename(id) {
+			const node = locate(state.get().tree, id)?.node;
+			if (node) state.update({ renaming: { id, value: node.label }, naming: null });
+		},
+		setRenaming(value) {
+			const r = state.get().renaming;
+			state.update({ renaming: value === null || !r ? null : { id: r.id, value } });
+		},
+		confirmRename() {
+			const s = state.get();
+			if (!s.renaming) return;
+			const { id, value } = s.renaming;
+			const c = nameCheck(site, s.tree, value, parentOf(id), id);
+			if (c.bad) return;
+			change((tree) => renameGroup(tree, id, value, c.merge ?? null), { renaming: null });
+		},
+		remove(id) {
+			change((tree) => removeNode(tree, id));
+		},
+		toggleCollapsed(id) {
+			const c = state.get().collapsed;
+			state.update({ collapsed: c.includes(id) ? c.filter((x) => x !== id) : [...c, id] });
+		},
+		toggleHeld(id) {
+			const o = state.get().openHeld;
+			state.update({ openHeld: o.includes(id) ? o.filter((x) => x !== id) : [...o, id] });
+		},
+		setLinked(linked) {
+			state.update({ linked });
+		},
+		setTick(tick) {
+			state.update({ tick });
+		},
+		review() {
+			if (arrange.blocked()) return;
+			state.update({ mode: 'review', note: null, drag: null });
+		},
+		back() {
+			if (state.get().mode === 'applying') return;
+			state.update({ mode: 'arrange', note: null, added: [], addedDocs: [] });
+		},
+		async apply() {
+			const s = state.get();
+			const p = plan();
+			if (s.mode !== 'review' || (s.note?.kind === 'underneath' && s.note.clashes.length)) return;
+			state.update({ mode: 'applying', note: null });
+			const refused = (note: ArrangeNote) => state.update({ mode: 'review', note });
+			// This tab's unsent edits to what moves (and to Site Settings, which the order rides) go first.
+			const refs: DocRef[] = [...movingRefs(site, p), { collection: 'settings', path: SETTINGS_PATH }];
+			for (const r of refs) {
+				const id = docId(r);
+				let flushed = true;
+				await editor.keeper?.flush(id).catch(() => (flushed = false));
+				if (!flushed || editor.keeper?.dirty(id)) {
+					const what = editor.documents.get().find((d) => d.collection === r.collection && d.path === r.path)?.label ?? r.path;
+					return refused({ kind: 'refused', error: `${what} has changes that haven't been saved yet, so nothing can move. Sort those out first (Use mine or Discard mine, or sign in again), then apply again.` });
+				}
+			}
+			const body: ArrangeRequest = { moves: p.moves, order: p.order, expect: expected(site, p), ...(p.live && !s.tick ? { redirect: false } : {}) };
+			const answer = await post(editor, body);
+			if (!answer.ok) {
+				if (answer.code === 'locked') return refused({ kind: 'lock', person: answer.lock?.person ?? null, error: answer.error });
+				if (answer.status === 0 || answer.status >= 500 || answer.status === 401) return refused({ kind: 'failed', error: answer.error });
+				// Something changed underneath (Decision 10): the same arrangement on the listing as it is now.
+				await editor.refreshDocuments().catch(() => undefined);
+				const now = state.get();
+				const r = rebase(site, now.orig, now.tree, editor.documents.get());
+				const holders = [...indexTree(r.tree).values()].filter((x) => x.node.holds?.docs.some((d) => r.addedDocs.includes(d.path))).map((x) => x.node.id);
+				state.update({ orig: r.orig, tree: r.tree, added: r.added, addedDocs: r.addedDocs, openHeld: [...new Set([...now.openHeld, ...holders])] });
+				return refused(r.notes.length || r.clashes.length ? { kind: 'underneath', lines: r.notes, clashes: r.clashes } : { kind: 'refused', error: answer.error });
+			}
+			for (const r of refs) editor.keeper?.discard(docId(r));
+			await editor.refreshDocuments().catch(() => undefined);
+			// The document under the screen goes with its page when it moved.
+			const open = editor.doc.get().ref;
+			const to = open.collection === site.collection ? newPathOf(p, open.path) : null;
+			const total = p.total;
+			const later = editor.mode === 'live' ? (total === 1 ? ' It goes live at the next Publish.' : ' They go live at the next Publish.') : '';
+			const text = total ? `Applied: ${p.lead} ${total === 1 ? 'has a new address' : 'have new addresses'}.${later}` : 'Applied: the Pages tree’s new order is saved.';
+			arrange.reset();
+			await editor.openDocument(to ? { collection: open.collection, path: to } : open, { history: 'push' });
+			editor.goTo('documents');
+			editor.toast(text, 'check');
+			editor.announce(text);
+		},
+		leave(go = goToDocuments) {
+			if (state.get().mode === 'applying') return;
+			const proceed = () => {
+				arrange.reset();
+				go();
+			};
+			if (!plan().any) return proceed();
+			openDialog(editor, {
+				kind: 'arrange-leave',
+				go: () => {
+					closeDialog(editor);
+					proceed();
+				},
+			});
+		},
+	};
+	editor.arrangeGuard = {
+		ask(go) {
+			if (editor.view.get().level !== 'arrange' || !plan().any) {
+				if (editor.view.get().level === 'arrange') arrange.reset();
+				return false;
+			}
+			arrange.leave(go);
+			return true;
+		},
+		up() {
+			const s = state.get();
+			if (s.naming || s.renaming) return;
+			if (s.mode === 'review') arrange.back();
+			else if (s.mode === 'arrange') arrange.leave();
+		},
+	};
+	// Each time the screen opens, it starts from the listing as it is (Decision 15).
+	editor.view.subscribe((next, previous) => {
+		if (next.level === 'arrange' && previous.level !== 'arrange') arrange.reset();
+	});
+	all.set(editor, arrange);
+	return arrange;
+}
+
+/** Every document whose address the plan changes, by its path now: the pages, and the held documents that go with them. */
+function movingRefs(site: ArrangeSite, p: Plan): DocRef[] {
+	const out: DocRef[] = [];
+	for (const id of p.moved) out.push({ collection: site.collection, path: p.orig.get(id)!.path });
+	for (const h of p.heldMoved) for (const d of h.docs) out.push({ collection: h.collection, path: d.path });
+	return out;
+}
+
+/**
+ * Decision 10: the listing the review was planned on, as the server checks it at Apply
+ * (`ArrangeRequest.expect`): every page's path, and each moving holder's documents'.
+ */
+function expected(site: ArrangeSite, p: Plan): Record<string, string> {
+	const pages = [...p.orig.values()].filter((x) => x.node.kind === 'page').map((x) => x.path);
+	const out: Record<string, string> = { [site.collection]: listingStamp(pages) };
+	for (const h of p.heldMoved) out[h.collection] = listingStamp(h.docs.map((d) => d.path));
+	return out;
+}
+
+/** Where a page of the arranged collection is after the plan (its path now, if it moves). */
+function newPathOf(p: Plan, path: string): string | null {
+	for (const [id, y] of p.orig) if (y.path === path && p.now.has(id) && p.now.get(id)!.path !== path) return p.now.get(id)!.path;
+	return null;
+}
+
+type Answer = { ok: true } | { ok: false; status: number; error: string; code: string | null; lock: LockRefusal['lock'] | null };
+
+async function post(editor: Editor, body: ArrangeRequest): Promise<Answer> {
+	const headers: Record<string, string> = { 'Content-Type': 'application/json', Accept: 'application/json' };
+	if (editor.liveSession) headers[TAB_HEADER] = editor.liveSession.tab;
+	let response: Response;
+	try {
+		response = await fetch(ENDPOINTS.arrange, { method: 'POST', headers, body: JSON.stringify(body) });
+	} catch {
+		return { ok: false, status: 0, error: "The server can't be reached. Nothing was applied; try again in a moment.", code: 'offline', lock: null };
+	}
+	const said = (await response.json().catch(() => ({}))) as Partial<LockRefusal> & { error?: string; code?: string };
+	if (response.status === 401 && editor.liveSession) editor.liveState.update({ signedOut: said as never });
+	if (!response.ok) return { ok: false, status: response.status, error: said.error ?? `The server said no (${response.status}).`, code: said.code ?? null, lock: said.lock ?? null };
+	return { ok: true };
+}

package/src/editor/client/documents/actions.ts

@@ -212,8 +212,8 @@ export interface InsideOption {
  * New page's "Inside" (Decision 11): the top level, then every group and every page, at
  * any depth, in tree order. A page with nothing under it yet is offered too, so a page can
  * go under it (Urban Return, 2026-10-24); Home isn't, since no address goes under `/index/`.
- * At each level, what already holds pages comes first (as folders come first in a file
- * list), so the site's shape is at the top while the rest are a scroll or a search away.
+ * At each level, the Pages tree's order (arrange pages, Decision 19): `documents` is the
+ * listing, already in that order (Home, the saved order, then what holds pages, then A–Z).
  */
 export function insideOptions(collection: Pick<EditorAnyCollection, 'name' | 'urlBase'>, documents: readonly ListedDocument[]): InsideOption[] {
 	const base = collection.urlBase ?? '/';
@@ -227,11 +227,22 @@ export function insideOptions(collection: Pick<EditorAnyCollection, 'name' | 'ur
 	const labelOf = (path: string) => docs.find((d) => d.path === path)?.label ?? titleCase(path.split('/').pop()!);
 	const holds = (path: string) => docs.some((d) => d.path.startsWith(`${path}/`));
 	const parentOf = (path: string) => (path.includes('/') ? path.slice(0, path.lastIndexOf('/')) : '');
+	// Arrange pages (Decision 19): the tree's order, as the listing gives it (content.ts → pageTree,
+	// page-order.ts's rule): a folder sits where its page, or its first page down, is listed.
+	const first = new Map<string, number>();
+	docs.forEach((d, i) => {
+		const parts = d.path.split('/');
+		for (let n = 1; n <= parts.length; n++) {
+			const at = parts.slice(0, n).join('/');
+			if (!first.has(at)) first.set(at, i);
+		}
+	});
+	const rank = (path: string) => first.get(path) ?? Number.MAX_SAFE_INTEGER;
 	const children = new Map<string, string[]>();
 	for (const f of folders) children.set(parentOf(f), [...(children.get(parentOf(f)) ?? []), f]);
 	const out: InsideOption[] = [{ path: '', label: 'Top level', name: 'Top level', depth: 0, page: false, holds: true, base }];
 	const walk = (parent: string) => {
-		const kids = (children.get(parent) ?? []).sort((a, b) => Number(holds(b)) - Number(holds(a)) || a.localeCompare(b));
+		const kids = (children.get(parent) ?? []).sort((a, b) => rank(a) - rank(b) || a.localeCompare(b));
 		for (const path of kids) {
 			const parts = path.split('/');
 			out.push({

package/src/editor/client/documents/dialogs.tsx

@@ -44,7 +44,9 @@ export type Dialog =
 	/** M6 Decision 9: a submission's Delete…, permanent, so it asks first (the mockup's #submission-delete). */
 	| { kind: 'sub-delete'; id: string; who: string; files: number }
 	/** M6c G4 Decision 9: Replace… on a file in the library (its key). */
-	| { kind: 'replace'; key: string };
+	| { kind: 'replace'; key: string }
+	/** Arrange pages (Decision 15): leaving the screen with something arranged; `go` leaves, dropping it. */
+	| { kind: 'arrange-leave'; go: () => void };
 
 const dialogs = new WeakMap<Editor, Store<Dialog | null>>();
 
@@ -81,13 +83,21 @@ export function DocumentDialogs() {
 			return <DeleteSubmission key={dialog.id} {...dialog} />;
 		case 'replace':
 			return <ReplaceDialog key={dialog.key} fileKey={dialog.key} />;
+		case 'arrange-leave':
+			return <LeaveArrange go={dialog.go} />;
 	}
 }
 
 /** The dialog frame: the scrim, focus on its first control, Esc closing it alone, focus back where it was. */
-export function Frame(props: { alert?: boolean; label: string; describedBy?: string; children: ReactNode }) {
+/**
+ * `returnTo`: where focus goes when the dialog closes and no control opened it (the browser's
+ * Back, say, leaves it on the page body); otherwise it goes back to the control that did.
+ */
+export function Frame(props: { alert?: boolean; label: string; describedBy?: string; returnTo?: () => HTMLElement | null; children: ReactNode }) {
 	const editor = useEditor();
 	const box = useRef<HTMLDivElement>(null);
+	const returnTo = useRef(props.returnTo);
+	returnTo.current = props.returnTo;
 	useEffect(() => {
 		const before = document.activeElement as HTMLElement | null;
 		const first =
@@ -119,7 +129,8 @@ export function Frame(props: { alert?: boolean; label: string; describedBy?: str
 		window.addEventListener('keydown', onKey, true);
 		return () => {
 			window.removeEventListener('keydown', onKey, true);
-			if (before?.isConnected) before.focus({ preventScroll: true });
+			const opener = before?.isConnected && before !== document.body ? before : (returnTo.current?.() ?? null);
+			if (opener?.isConnected) opener.focus({ preventScroll: true });
 		};
 	}, [editor]);
 	return (
@@ -769,6 +780,25 @@ function DeleteSubmission({ id, who, files }: { id: string; who: string; files:
 }
 
 /** A shared block that pages still use can't be deleted (Decision 8): where it's used, each a way there. */
+/** Arrange pages (Decision 15; the mockup's #leave): what's arranged isn't saved anywhere, so leaving asks first. */
+function LeaveArrange({ go }: { go: () => void }) {
+	const editor = useEditor();
+	return (
+		<Frame label="arrange-leave" returnTo={() => document.querySelector<HTMLElement>('[data-pane-level="arrange"] [data-act="cancel"]')}>
+			<h2 id="dlg-h">Leave without applying?</h2>
+			<p>What you’ve arranged isn’t saved anywhere: leave now and it’s gone. Nothing on the site has changed.</p>
+			<div className="acts">
+				<button type="button" className="btn" data-act="leave-stay" onClick={() => closeDialog(editor)}>
+					Keep arranging
+				</button>
+				<button type="button" className="btn ink" data-act="leave-go" onClick={go}>
+					Leave without applying
+				</button>
+			</div>
+		</Frame>
+	);
+}
+
 function InUse({ docRef, usedOn }: { docRef: DocRef; usedOn?: CreateDeleteRefusal['usedOn'] }) {
 	const editor = useEditor();
 	const documents = useStore(editor.documents);

package/src/editor/client/editor.ts

@@ -30,7 +30,7 @@
  *   editor.editHere() / useMine() / discardMine() / publish() / tryAgain() /
  *   dismissNotice(id) / signOut() / signInAgain()
  */
-import { addressOf, inboxAddress, inboxFromAddress, refFromAddress } from '../addresses.ts';
+import { ARRANGE_ADDRESS, addressOf, inboxAddress, inboxFromAddress, isArrangeAddress, refFromAddress } from '../addresses.ts';
 import { heldBases } from '../../held.ts';
 import {
 	docId,
@@ -64,7 +64,7 @@ import { createKeeper, type HeldView, type Keeper, type KeepStatus } from './sta
 import { createLiveSession, tabId, type LiveSession, type LiveState } from './state/live.ts';
 import { createStore, type Store } from './state/store.ts';
 
-export type PaneLevel = 'documents' | 'collection' | 'document' | 'block' | 'media' | 'submissions';
+export type PaneLevel = 'documents' | 'collection' | 'document' | 'block' | 'media' | 'submissions' | 'arrange';
 
 /**
  * M5b: Choose… (or Replace…, or a list's Add image) opened the library as a picker for
@@ -248,6 +248,18 @@ export interface Editor {
 	 * coming from elsewhere, replaced within the inbox.
 	 */
 	openInbox(id?: string | null, options?: { history?: 'push' | 'replace' | 'none' }): void;
+	/**
+	 * Arrange pages (Decisions 2, 15, 16): the arrange screen in the preview's place, its level
+	 * in the pane, at `/admin/arrange` (pushed when coming from elsewhere). It starts from the
+	 * listing as it is each time (client/arrange/store.ts).
+	 */
+	openArrange(options?: { history?: 'push' | 'replace' | 'none' }): void;
+	/**
+	 * Arrange pages (Decision 15): the screen's say when the tab would leave it, set by
+	 * client/arrange/store.ts. `ask(go)` returns true when it took over (anything arranged:
+	 * it asks first, then calls `go`); `up()` is Esc there. Null until the screen is first shown.
+	 */
+	arrangeGuard: { ask(go: () => void): boolean; up(): void } | null;
 
 	openDocument(ref: DocRef, options?: { history?: 'push' | 'replace' | 'none' }): Promise<void>;
 	openBlock(key: string, field?: string | null, options?: { picked?: boolean }): void;
@@ -344,6 +356,8 @@ export function createEditor(props: AdminProps, options: { client: boolean }): E
 	const submissions = createStore<SubmissionsSetup>(props.submissions ?? { unread: 0 });
 	// M6: /admin/submissions[/<id>] opens on the inbox, with Home under it.
 	if (props.inbox) view.update({ level: 'submissions', inbox: { id: props.inbox.id } });
+	// Arrange pages: /admin/arrange opens on the screen, with Home under it.
+	if (props.arrange) view.update({ level: 'arrange' });
 
 	// Live mode (M4): the poll and the server calls; a tab id that lasts the tab's life.
 	const tab = liveProps ? (options.client ? tabId() : 'server') : null;
@@ -589,7 +603,8 @@ export function createEditor(props: AdminProps, options: { client: boolean }): E
 
 	function setTitle() {
 		if (typeof document === 'undefined') return;
-		const what = view.get().level === 'submissions' ? 'Submissions' : doc.get().document.title || doc.get().entry.label;
+		const level = view.get().level;
+		const what = level === 'submissions' ? 'Submissions' : level === 'arrange' ? 'Arrange pages' : doc.get().document.title || doc.get().entry.label;
 		document.title = `${what} · ${brand.get().name}`;
 	}
 
@@ -618,7 +633,20 @@ export function createEditor(props: AdminProps, options: { client: boolean }): E
 		submissions,
 		inboxFirst: props.inboxFirst ?? null,
 
+		arrangeGuard: null,
+
+		openArrange({ history = 'push' } = {}) {
+			view.update({ level: 'arrange', inbox: null, media: null, collection: null, block: null, field: null, picked: false, pop: null });
+			if (history !== 'none' && typeof window !== 'undefined' && location.pathname !== ARRANGE_ADDRESS) {
+				if (history === 'push') window.history.pushState({ caracms: 'arrange' }, '', ARRANGE_ADDRESS);
+				else window.history.replaceState({ caracms: 'arrange' }, '', ARRANGE_ADDRESS);
+			}
+			setTitle();
+		},
+
 		openInbox(id = null, { history } = {}) {
+			// Leaving the arrange screen with something arranged asks first (Decision 15).
+			if (editor.arrangeGuard?.ask(() => editor.openInbox(id, { history }))) return;
 			const before = view.get();
 			const within = before.level === 'submissions';
 			view.update({ level: 'submissions', inbox: { id }, block: null, field: null, picked: false, pop: null, media: null });
@@ -642,6 +670,7 @@ export function createEditor(props: AdminProps, options: { client: boolean }): E
 		},
 
 		async openDocument(ref, { history = 'push' } = {}) {
+			if (editor.arrangeGuard?.ask(() => void editor.openDocument(ref, { history }))) return;
 			const current = doc.get().ref;
 			if (sameDoc(ref, current) && !view.get().opening) {
 				view.update({ level: 'document', block: null, field: null, picked: false, pop: null, inbox: null });
@@ -707,6 +736,11 @@ export function createEditor(props: AdminProps, options: { client: boolean }): E
 
 		goUp() {
 			const { level, media, inbox } = view.get();
+			// Arrange pages: the review → arranging; arranging → leave (asking first when anything is arranged).
+			if (level === 'arrange') {
+				editor.arrangeGuard?.up();
+				return true;
+			}
 			const { kind } = doc.get().document;
 			// M6: the inbox: an open submission → the list; the list → documents.
 			if (level === 'submissions') {
@@ -982,7 +1016,10 @@ export function createEditor(props: AdminProps, options: { client: boolean }): E
 					});
 			};
 			const waitingKey = (st: LiveState) => (st.status?.waiting ?? []).map((w) => `${w.file}:${w.change}`).sort().join('\n');
-			if (liveSession) stops.push(liveState.subscribe((next, previous) => next.status && previous.status && waitingKey(next) !== waitingKey(previous) && refresh()));
+			// Arrange pages (Decision 18): an order-only Apply elsewhere changes no waiting key when Site Settings was
+			// already waiting, so the saved order's stamp is watched too.
+			const orderKey = (st: LiveState) => st.status?.pageOrderStamp ?? '';
+			if (liveSession) stops.push(liveState.subscribe((next, previous) => next.status && previous.status && (waitingKey(next) !== waitingKey(previous) || orderKey(next) !== orderKey(previous)) && refresh()));
 			stops.push(keep.subscribe((next, previous) => next.state === 'kept' && previous.state !== 'kept' && refresh()));
 
 			// The cookie follows the sidebar's per-browser state (Decision 20).
@@ -991,9 +1028,23 @@ export function createEditor(props: AdminProps, options: { client: boolean }): E
 
 			// Addresses (Decision 19): the address names the open document; back and forward open theirs.
 			// M6: the inbox's own address (`/admin/submissions[/<id>]`) stays as it is.
-			const canonical = view.get().level === 'submissions' ? inboxAddress(view.get().inbox?.id ?? null) : addressOf(doc.get().ref, site.home);
+			const canonical = view.get().level === 'submissions' ? inboxAddress(view.get().inbox?.id ?? null) : view.get().level === 'arrange' ? ARRANGE_ADDRESS : addressOf(doc.get().ref, site.home);
 			if (location.pathname !== canonical) history.replaceState({ caracms: id }, '', canonical + location.search);
 			const onPopState = () => {
+				if (isArrangeAddress(location.pathname)) {
+					editor.openArrange({ history: 'none' });
+					return;
+				}
+				// Back from the arrange screen with something arranged: it stays, and asks first (Decision 15).
+				if (view.get().level === 'arrange' && editor.arrangeGuard) {
+					// The screen's entry is put back while it asks; leaving steps back off it again, so the
+					// history is as a plain Back leaves it (the arrangement is gone by then, so it doesn't ask twice).
+					const asked = editor.arrangeGuard.ask(() => history.back());
+					if (asked) {
+						history.pushState({ caracms: 'arrange' }, '', ARRANGE_ADDRESS);
+						return;
+					}
+				}
 				const inbox = inboxFromAddress(location.pathname);
 				if (inbox && inbox !== 'bad') {
 					editor.openInbox(inbox.id, { history: 'none' });

package/src/editor/client/pane/Pane.tsx

@@ -17,6 +17,7 @@ import { DocumentLevel } from './levels/DocumentLevel.tsx';
 import { DocumentsLevel } from './levels/DocumentsLevel.tsx';
 import { MediaLevel } from './levels/MediaLevel.tsx';
 import { SubmissionsLevel } from './levels/SubmissionsLevel.tsx';
+import { ArrangeLevel } from './levels/ArrangeLevel.tsx';
 
 export const LEVELS: Record<PaneLevel, ComponentType> = {
 	documents: DocumentsLevel,
@@ -27,6 +28,8 @@ export const LEVELS: Record<PaneLevel, ComponentType> = {
 	media: MediaLevel,
 	// M6: the inbox (Site-wide → Submissions).
 	submissions: SubmissionsLevel,
+	// Arrange pages: the screen's controls, then its review (Decision 16).
+	arrange: ArrangeLevel,
 };
 
 /**