caracms 0.4.0 → 0.5.0

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

@@ -0,0 +1,659 @@
+/**
+ * Arrange pages (notes/2026-10-25-arrange-pages.md): the screen's model. Pure and
+ * browser-safe, so the screen, its review and the unit tests agree.
+ *
+ * - **The tree** (`buildTree`): the Pages listing as nodes, in the listing's order (the
+ *   server's order rule, Decision 7), a folder with no page of its own as a group just
+ *   before its first child (as nav/tree.ts does), each held collection on its page.
+ *   A node's `id` is its path as listed (a page and the folder of its pages are one node),
+ *   or `new:<n>` for a group made on the screen. The id never changes while arranging, so
+ *   the tree as it was (`orig`) and as it is now (`tree`) line up by id.
+ * - **The plan** (`makePlan`): what the arrangement means, worked out from the two trees:
+ *   the Apply's request (roots only, and the full child list of every level that changed:
+ *   the spec's Contracts → "Apply request"), the review's old → new list (Decisions 3, 12,
+ *   14, 21), and the pane's list of changes.
+ * - **The checks** (`checkDrop`, `nameCheck`): a drop or a name refused on the screen, at
+ *   the drop (Decision 8), Home taking nothing (Decision 13), a held collection's row
+ *   taking nothing (Decision 12), a group's name by the new-page rules (Decision 17).
+ * - **Re-planning** (`rebase`, Decision 10): the same arrangement on a fresh listing, after
+ *   the server refused an Apply, with what changed underneath named.
+ */
+import { titleCase } from '../../../fields.ts';
+import { documentsNoun } from '../../../held.ts';
+import { INDEX_MESSAGE, NO_ADDRESS_MESSAGE, RESERVED_SLUG, addressProblem, slugify, type AddressCollection } from '../../../slug.ts';
+import type { CodeRoute } from '../../../code-routes.ts';
+import type { ListedDocument } from '../../types.ts';
+import { andList, singular } from '../documents/actions.ts';
+
+/** A collection a page holds, as its row on the screen shows it (Decision 12). */
+export interface HeldRow {
+	collection: string;
+	label: string;
+	icon: string;
+	/** Its word for one document and for several: "case study", "case studies". */
+	one: string;
+	many: string;
+	/** Every document in it, hidden ones included (as the sidebar counts them). */
+	docs: { path: string; url: string | null }[];
+}
+
+export interface ArrangeNode {
+	/** Its path as listed, or `new:<n>` for a group made here. Constant while arranging. */
+	id: string;
+	kind: 'page' | 'group';
+	slug: string;
+	label: string;
+	/** A page's own "hidden" (M9), not one it has from a page above it. */
+	hidden: boolean;
+	holds: HeldRow | null;
+	kids: ArrangeNode[];
+	/** A group made on this screen (Decision 17). */
+	fresh?: boolean;
+	/** Groups this page took in (Decision 8): dropped beside one with its slug, or one renamed to its slug. */
+	joined?: { label: string; how: 'drop' | 'name' }[];
+}
+
+/** What the model needs of the site. */
+export interface ArrangeSite {
+	/** The nested collection being arranged (`pages`). */
+	collection: string;
+	/** Its `urlBase` (`/`). */
+	base: string;
+	/** Home's path (`index`). */
+	home: string;
+	collections: readonly (AddressCollection & { kind?: string; heldBy?: string | null; holder?: { collection: string; path: string } | null; nested?: boolean })[];
+	codeRoutes?: readonly CodeRoute[];
+}
+
+export interface Placed {
+	node: ArrangeNode;
+	/** The parent's id; null at the top level. */
+	parent: string | null;
+	/** Its path in this tree. */
+	path: string;
+	/** Hidden on the site: its own flag, or a page above it hidden. */
+	hidden: boolean;
+	depth: number;
+}
+
+const parentOf = (path: string) => (path.includes('/') ? path.slice(0, path.lastIndexOf('/')) : '');
+export const plural = (n: number, one: string, many: string) => `${n} ${n === 1 ? one : many}`;
+const clone = <T>(x: T): T => JSON.parse(JSON.stringify(x)) as T;
+
+/** The tree from the listing, in its order (the server's order rule). */
+export function buildTree(site: ArrangeSite, documents: readonly ListedDocument[]): ArrangeNode[] {
+	const docs = documents.filter((d) => d.collection === site.collection);
+	const byPath = new Map<string, ArrangeNode>();
+	const top: ArrangeNode[] = [];
+	const place = (path: string, node: ArrangeNode) => {
+		byPath.set(path, node);
+		const parent = parentOf(path);
+		(parent ? ensure(parent).kids : top).push(node);
+	};
+	const ensure = (path: string): ArrangeNode => {
+		const had = byPath.get(path);
+		if (had) return had;
+		const slug = path.slice(path.lastIndexOf('/') + 1);
+		const group: ArrangeNode = { id: path, kind: 'group', slug, label: titleCase(slug), hidden: false, holds: null, kids: [] };
+		place(path, group);
+		return group;
+	};
+	for (const d of docs) {
+		const slug = d.path.slice(d.path.lastIndexOf('/') + 1);
+		const had = byPath.get(d.path);
+		const own = { kind: 'page' as const, label: d.label, hidden: !!d.hiddenSelf };
+		if (had) Object.assign(had, own);
+		else place(d.path, { id: d.path, slug, holds: null, kids: [], ...own });
+	}
+	for (const c of site.collections) {
+		if (c.heldBy !== site.collection || c.holder?.collection !== site.collection) continue;
+		const holder = byPath.get(c.holder.path);
+		if (!holder || holder.kind !== 'page') continue;
+		holder.holds = {
+			collection: c.name,
+			label: c.label,
+			icon: c.kind === 'fields' ? 'case' : 'journal',
+			one: singular({ kind: 'sections', nested: false, label: c.label }),
+			many: documentsNoun(c.label),
+			docs: documents.filter((d) => d.collection === c.name).map((d) => ({ path: d.path, url: d.url })),
+		};
+	}
+	return top;
+}
+
+export function indexTree(tree: readonly ArrangeNode[]): Map<string, Placed> {
+	const out = new Map<string, Placed>();
+	const walk = (nodes: readonly ArrangeNode[], parent: string | null, pp: string, hidden: boolean, depth: number) => {
+		for (const node of nodes) {
+			const path = pp ? `${pp}/${node.slug}` : node.slug;
+			const h = hidden || (node.kind === 'page' && node.hidden);
+			out.set(node.id, { node, parent, path, hidden: h, depth });
+			walk(node.kids, node.id, path, h, depth + 1);
+		}
+	};
+	walk(tree, null, '', false, 0);
+	return out;
+}
+
+/** A row's public address: `/about/team`, Home `/`, a group `/services/`. */
+export function addressAt(site: Pick<ArrangeSite, 'base' | 'home'>, kind: ArrangeNode['kind'], path: string): string {
+	if (kind === 'group') return `${site.base}${path}/`;
+	return path === site.home ? site.base : `${site.base}${path}`;
+}
+
+export function locate(tree: ArrangeNode[], id: string, parentId: string | null = null): { list: ArrangeNode[]; i: number; node: ArrangeNode; parentId: string | null } | null {
+	for (let i = 0; i < tree.length; i++) {
+		const node = tree[i]!;
+		if (node.id === id) return { list: tree, i, node, parentId };
+		const found = locate(node.kids, id, node.id);
+		if (found) return found;
+	}
+	return null;
+}
+
+export const countPages = (nodes: readonly ArrangeNode[]): number => nodes.reduce((k, n) => k + (n.kind === 'page' ? 1 : 0) + countPages(n.kids), 0);
+/** A group with no page anywhere under it (only groups that go, or nothing): it goes too, or, new, it's empty. */
+export const pageless = (node: ArrangeNode): boolean => node.kind === 'group' && countPages(node.kids) === 0;
+export const countGroups = (nodes: readonly ArrangeNode[]): number => nodes.reduce((k, n) => k + (n.kind === 'group' ? 1 : 0) + countGroups(n.kids), 0);
+
+// ── Changing the tree (each on a clone the store then keeps) ────────────────────
+
+/** Move `id` into `parentId` (null: the top level), before `beforeId` (null: at the end). */
+export function moveNode(tree: ArrangeNode[], id: string, parentId: string | null, beforeId: string | null): void {
+	const s = locate(tree, id);
+	if (!s) return;
+	s.list.splice(s.i, 1);
+	const list = parentId ? locate(tree, parentId)?.node.kids : tree;
+	if (!list) return void s.list.splice(s.i, 0, s.node);
+	let at = beforeId ? list.findIndex((x) => x.id === beforeId) : -1;
+	if (at < 0) at = list.length;
+	list.splice(at, 0, s.node);
+}
+
+/** A drop that landed: a move, or (Decision 8) a page taking the place of a group with its slug, the group's pages under it. */
+export function dropNode(tree: ArrangeNode[], id: string, target: Exclude<DropTarget, { kind: 'refused' }>): void {
+	if (!target.merge) return moveNode(tree, id, target.parentId, target.beforeId);
+	const s = locate(tree, id);
+	const g = locate(tree, target.merge);
+	if (!s || !g) return;
+	s.list.splice(s.i, 1);
+	const at = g.list.indexOf(g.node);
+	s.node.kids = [...s.node.kids, ...g.node.kids];
+	s.node.joined = [...(s.node.joined ?? []), ...(g.node.joined ?? []), { label: g.node.label, how: 'drop' }];
+	g.list.splice(at, 1, s.node);
+}
+
+/** New group (Decision 17): at the end of the top level. Returns its id. */
+export function addGroup(tree: ArrangeNode[], label: string, n: number): string {
+	const id = `new:${n}`;
+	tree.push({ id, kind: 'group', slug: slugify(label), label: label.trim(), hidden: false, holds: null, kids: [], fresh: true });
+	return id;
+}
+
+/** Rename… on a group; a name that's a sibling page's slug puts the group's pages under that page (Decision 8). */
+export function renameGroup(tree: ArrangeNode[], id: string, label: string, merge: string | null): void {
+	const g = locate(tree, id);
+	if (!g) return;
+	if (merge) {
+		const page = locate(tree, merge)?.node;
+		if (!page) return;
+		g.list.splice(g.i, 1);
+		page.kids = [...page.kids, ...g.node.kids];
+		page.joined = [...(page.joined ?? []), { label: g.node.label, how: 'name' }];
+		return;
+	}
+	g.node.label = label.trim();
+	g.node.slug = slugify(label);
+}
+
+export function removeNode(tree: ArrangeNode[], id: string): void {
+	const s = locate(tree, id);
+	if (s) s.list.splice(s.i, 1);
+}
+
+// ── Checks ─────────────────────────────────────────────────────────────────────
+
+export type DropTarget =
+	| {
+			kind: 'beside' | 'inside';
+			/** Where it lands: the parent's id (null: the top level), and the sibling it goes before (null: last). */
+			parentId: string | null;
+			beforeId: string | null;
+			/** The row the marker is drawn against, and which edge (beside). */
+			rowId: string;
+			edge?: 'top' | 'bottom';
+			depth: number;
+			/** A page dropped beside a group with its slug: the group it becomes the page of (Decision 8). */
+			merge?: string;
+			/** Only the order changes (same parent, no merge). */
+			same?: boolean;
+			/** The level it lands in, for the marker's tag: "Top level", "In About", "Inside Company". */
+			tag?: string;
+	  }
+	| { kind: 'refused'; rowId: string; reason: string };
+
+/**
+ * Whether a drop lands, given where the pointer is (`target` without `merge`, `same` or
+ * `tag`), or why not: a page beside a page with its slug, a group beside anything with its
+ * slug, a page into its own pages, an address a page can't have (reserved, a code route,
+ * under another collection, a held document's).
+ */
+export function checkDrop(site: ArrangeSite, tree: ArrangeNode[], documents: readonly ListedDocument[], srcId: string, target: DropTarget): DropTarget {
+	if (target.kind === 'refused') return target;
+	const src = locate(tree, srcId);
+	if (!src) return { kind: 'refused', rowId: target.rowId, reason: 'That row has gone' };
+	const index = indexTree(tree);
+	const t = { ...target };
+	const refuse = (reason: string): DropTarget => ({ kind: 'refused', rowId: t.rowId, reason });
+	if (t.parentId) {
+		const p = index.get(t.parentId);
+		if (!p) return refuse('That row has gone');
+		if (p.path === site.home) return refuse('Home takes no pages');
+		if (t.parentId === srcId || p.path.startsWith(`${index.get(srcId)!.path}/`)) return refuse(`${src.node.label} can’t go inside itself`);
+	}
+	const list = t.parentId ? index.get(t.parentId)!.node.kids : tree;
+	const same = list.find((k) => k.id !== srcId && k.slug === src.node.slug);
+	if (same) {
+		if (same.kind === 'page' || src.node.kind === 'group') return refuse(`There’s already a ${same.kind} called ${same.label} here`);
+		const clash = src.node.kids.find((k) => same.kids.some((g) => g.slug === k.slug));
+		if (clash) return refuse(`There’s already a page called ${clash.label} in ${same.label}`);
+		t.merge = same.id;
+	}
+	t.same = src.parentId === t.parentId && !t.merge;
+	const label = (id: string) => index.get(id)?.node.label ?? '';
+	t.tag = t.kind === 'inside' ? `Inside ${label(t.parentId!)}` : t.parentId ? `In ${label(t.parentId)}` : 'Top level';
+	if (!t.same && !t.merge && src.node.kind === 'page') {
+		const pp = t.parentId ? `${index.get(t.parentId)!.path}/` : '';
+		const url = addressAt(site, 'page', `${pp}${src.node.slug}`);
+		const moving = new Set<string>();
+		for (const [, x] of indexTree([src.node])) if (x.node.kind === 'page') moving.add(x.node.id);
+		const others = documents.filter((d) => !(d.collection === site.collection && moving.has(d.path)));
+		const problem = addressProblem(url, site.collection, site.collections, others, site.codeRoutes);
+		if (problem) return refuse(problem.message.replace(/\.$/, ''));
+	}
+	return t;
+}
+
+export interface NameCheck {
+	slug: string;
+	/** Can't be added (empty, or refused). */
+	bad: boolean;
+	err?: string;
+	/** A sibling page with this slug: the group's pages go under it (Decision 8). */
+	merge?: string;
+	info?: string;
+}
+
+/** A group's name (New group, Rename…) by the new-page rules (Decision 17), among `list`, its siblings. */
+export function nameCheck(site: ArrangeSite, tree: ArrangeNode[], value: string, parentId: string | null, selfId: string | null): NameCheck {
+	const slug = slugify(value || '');
+	if (!value.trim()) return { slug, bad: true };
+	if (!slug) return { slug, bad: true, err: NO_ADDRESS_MESSAGE };
+	if (slug === RESERVED_SLUG) return { slug, bad: true, err: INDEX_MESSAGE };
+	const index = indexTree(tree);
+	const list = parentId ? (index.get(parentId)?.node.kids ?? []) : tree;
+	const same = list.find((k) => k.id !== selfId && k.slug === slug);
+	if (same?.kind === 'group') return { slug, bad: true, err: `There’s already a group called ${same.label} here.` };
+	if (same?.kind === 'page') return { slug, bad: false, merge: same.id, info: `There’s a page called ${same.label} here, so this joins it: what you put in goes under ${same.label}.` };
+	const pp = parentId ? `${index.get(parentId)!.path}/` : '';
+	const problem = addressProblem(addressAt(site, 'page', `${pp}${slug}`), site.collection, site.collections, [], site.codeRoutes);
+	if (problem) return { slug, bad: true, err: problem.message };
+	return { slug, bad: false };
+}
+
+// ── The plan ───────────────────────────────────────────────────────────────────
+
+export type Entry =
+	| { t: 'move' | 'carried'; id: string; label: string; from: string; to: string; ind: number; vis: 'hidden' | 'shown' | null }
+	| { t: 'held'; id: string; holder: string; held: HeldRow; from: string; to: string; base: string; ind: number }
+	| { t: 'newgroup'; id: string; label: string; empty: boolean; ind: number }
+	| { t: 'rename' | 'groupmove'; id: string; label: string; from: string; to: string; dest: string | null; fromA: string; toA: string; ind: number }
+	| { t: 'gone'; id: string; label: string; ind: number }
+	| { t: 'joined'; id: string; label: string; into: string; how: 'drop' | 'name'; ind: number };
+
+/** One line in the pane's list of changes: an icon and its words (with the names to set in bold). */
+export interface Change {
+	icon: string;
+	/** Text and bold parts in turn: `['', 'About', ' moves into ', 'Company', '']`, even indexes plain. */
+	parts: string[];
+	muted?: boolean;
+}
+
+export interface ApplyMove {
+	collection: string;
+	fromPath: string;
+	toPath: string;
+}
+
+export interface Plan {
+	orig: Map<string, Placed>;
+	now: Map<string, Placed>;
+	/** The Apply's request (Contracts): roots only, and the full child list of every level that changed. */
+	moves: ApplyMove[];
+	order: Record<string, string[]>;
+	entries: Entry[];
+	changes: Change[];
+	/** The levels whose order changed (a parent's id; null for the top level). */
+	reorders: (string | null)[];
+	/** Pages whose address changes, and the held collections that go with them. */
+	moved: string[];
+	heldMoved: HeldRow[];
+	emptyFresh: ArrangeNode[];
+	gone: string[];
+	/** Anything to apply. */
+	any: boolean;
+	/** No address changes: only the order (Decision 21). */
+	orderOnly: boolean;
+	/** At least one changed address was live (the tick shows, Decision 3). */
+	live: boolean;
+	/** "3 pages and 24 journal entries" and its verb. */
+	lead: string;
+	verb: 'changes' | 'change';
+	total: number;
+}
+
+export interface PlanOptions {
+	/** Made since the last Publish, or moved since and already redirected: no live address to leave a redirect from. */
+	pending?: (collection: string, path: string) => boolean;
+}
+
+export function makePlan(site: ArrangeSite, origTree: readonly ArrangeNode[], tree: readonly ArrangeNode[], options: PlanOptions = {}): Plan {
+	const o = indexTree(origTree);
+	const n = indexTree(tree);
+	const addr = (x: Placed) => addressAt(site, x.node.kind, x.path);
+	const moved: string[] = [];
+	const heldMoved: HeldRow[] = [];
+	for (const [id, x] of n) {
+		const y = o.get(id);
+		if (!y || x.node.kind !== 'page' || y.node.kind !== 'page') continue;
+		if (y.path !== x.path) {
+			moved.push(id);
+			if (x.node.holds) heldMoved.push(x.node.holds);
+		}
+	}
+	const fresh = [...n.values()].filter((x) => x.node.fresh);
+	const emptyFresh = fresh.filter((x) => pageless(x.node)).map((x) => x.node);
+	const gone = [...o.values()].filter((y) => y.node.kind === 'group' && n.has(y.node.id) && pageless(n.get(y.node.id)!.node)).map((y) => y.node.id);
+	const groupsMoved = [...n.values()].filter((x) => x.node.kind === 'group' && o.has(x.node.id) && o.get(x.node.id)!.path !== x.path);
+	const joined = [...n.values()].filter((x) => x.node.joined?.length);
+
+	// The levels whose order changed among the rows that were and still are there.
+	const reorders: (string | null)[] = [];
+	for (const p of [null, ...n.keys()]) {
+		if (p && !o.has(p)) continue;
+		const oldKids = (p ? o.get(p)!.node.kids : origTree).map((k) => k.id).filter((id) => n.get(id)?.parent === p);
+		const newKids = (p ? n.get(p)!.node.kids : tree).map((k) => k.id).filter((id) => oldKids.includes(id));
+		if (oldKids.join('\n') !== newKids.join('\n')) reorders.push(p);
+	}
+
+	// The request's roots: each page whose path changes and isn't carried by a root above it.
+	const moves: ApplyMove[] = [];
+	for (const [id, x] of n) {
+		const y = o.get(id);
+		if (!y || x.node.kind !== 'page' || y.node.kind !== 'page' || y.path === x.path) continue;
+		const carried = moves.some((m) => y.path.startsWith(`${m.fromPath}/`) && x.path === `${m.toPath}${y.path.slice(m.fromPath.length)}`);
+		if (!carried) moves.push({ collection: site.collection, fromPath: y.path, toPath: x.path });
+	}
+
+	// The request's order: the full child list of every level whose children or order changed, keyed by its path after
+	// the moves. Also a level where a row gained or lost what's under it, since the rule (Decision 7) would move it.
+	// Home is always first, so it's never listed; a group that goes has no key.
+	const order: Record<string, string[]> = {};
+	// A group with no page left under it goes (its folder can't exist), so it isn't listed: one holding only
+	// groups that go too.
+	const slugs = (kids: readonly ArrangeNode[]) => kids.filter((k) => !pageless(k)).map((k) => k.slug).filter((s) => s !== site.home);
+	const holdsSome = (k: ArrangeNode) => countPages(k.kids) > 0 || !!k.holds;
+	const levelChanged = (before: readonly ArrangeNode[] | null, after: readonly ArrangeNode[]) => {
+		if (!before) return after.length > 0;
+		if (slugs(before).join('\n') !== slugs(after).join('\n')) return true;
+		return after.some((k) => {
+			const was = o.get(k.id)?.node;
+			return !!was && holdsSome(was) !== holdsSome(k);
+		});
+	};
+	if (levelChanged(origTree, tree)) order[''] = slugs(tree);
+	for (const [id, x] of n) {
+		if (x.path === site.home) continue;
+		if (pageless(x.node)) continue;
+		const before = o.get(id)?.node;
+		if (levelChanged(before ? before.kids : null, x.node.kids)) order[x.path] = slugs(x.node.kids);
+	}
+
+	// The review's list, top to bottom in the new tree: each root, then what it carries.
+	const entries: Entry[] = [];
+	const isRoot = (id: string) => o.get(id)!.parent !== n.get(id)!.parent;
+	const visOf = (x: Placed, y: Placed) => (y.hidden !== x.hidden ? (x.hidden ? 'hidden' : 'shown') : null);
+	const pushPage = (node: ArrangeNode, ind: number) => {
+		const x = n.get(node.id)!;
+		const y = o.get(node.id)!;
+		entries.push({ t: isRoot(node.id) ? 'move' : 'carried', id: node.id, label: node.label, from: addr(y), to: addr(x), ind, vis: visOf(x, y) });
+		if (node.holds) entries.push({ t: 'held', id: node.id, holder: node.label, held: node.holds, from: `${addr(y).replace(/\/$/, '')}/…`, to: `${addr(x).replace(/\/$/, '')}/…`, base: addr(x).replace(/\/$/, ''), ind: ind + 1 });
+	};
+	const pushJoined = (node: ArrangeNode, ind: number) => {
+		for (const j of node.joined ?? []) entries.push({ t: 'joined', id: node.id, label: j.label, into: node.label, how: j.how, ind });
+	};
+	const carried = (nodes: readonly ArrangeNode[], ind: number) => {
+		for (const k of nodes) {
+			const y = o.get(k.id);
+			if (k.kind === 'page') {
+				if (y?.node.kind === 'page' && y.path !== n.get(k.id)!.path) pushPage(k, ind);
+				carried(k.kids, ind + 1);
+			} else carried(k.kids, ind);
+		}
+	};
+	const walk = (nodes: readonly ArrangeNode[], ind: number) => {
+		for (const node of nodes) {
+			const x = n.get(node.id)!;
+			const y = o.get(node.id);
+			if (node.kind === 'group') {
+				if (!y || node.fresh) {
+					entries.push({ t: 'newgroup', id: node.id, label: node.label, empty: pageless(node), ind });
+					walk(node.kids, ind + 1);
+					continue;
+				}
+				if (y.path !== x.path) {
+					const renamed = y.node.slug !== node.slug;
+					entries.push({ t: renamed ? 'rename' : 'groupmove', id: node.id, from: y.node.label, to: node.label, label: node.label, dest: x.parent ? n.get(x.parent)!.node.label : null, fromA: addr(y), toA: addr(x), ind });
+					carried(node.kids, ind + 1);
+					continue;
+				}
+				walk(node.kids, ind);
+				continue;
+			}
+			if (y && y.node.kind === 'page' && y.path !== x.path) {
+				pushPage(node, ind);
+				pushJoined(node, ind + 1);
+				carried(node.kids, ind + 1);
+				continue;
+			}
+			pushJoined(node, ind);
+			walk(node.kids, ind);
+		}
+	};
+	walk(tree, 0);
+	for (const g of gone) {
+		const gp = addr(o.get(g)!);
+		let last = -1;
+		entries.forEach((e, i) => {
+			if ('from' in e && typeof e.from === 'string' && e.from.startsWith(gp)) last = i;
+		});
+		const at = last < 0 ? entries.length : last + 1;
+		entries.splice(at, 0, { t: 'gone', id: g, label: o.get(g)!.node.label, ind: last < 0 ? 0 : entries[last]!.ind });
+	}
+
+	const parts: string[] = [];
+	if (moved.length) parts.push(plural(moved.length, 'page', 'pages'));
+	for (const h of heldMoved) parts.push(plural(h.docs.length, h.one, h.many));
+	const total = moved.length + heldMoved.reduce((k, h) => k + h.docs.length, 0);
+	const pending = options.pending ?? (() => false);
+	const live =
+		moved.some((id) => !pending(site.collection, o.get(id)!.path)) ||
+		heldMoved.some((h) => h.docs.some((d) => d.url !== null && !pending(h.collection, d.path)));
+	const any = moved.length > 0 || fresh.length > 0 || gone.length > 0 || groupsMoved.length > 0 || reorders.length > 0 || joined.length > 0 || Object.keys(order).length > 0;
+	const plan: Plan = {
+		orig: o,
+		now: n,
+		moves,
+		order,
+		entries,
+		changes: [],
+		reorders,
+		moved,
+		heldMoved,
+		emptyFresh,
+		gone,
+		any,
+		orderOnly: !moved.length && !entries.length,
+		live,
+		lead: andList(parts),
+		verb: total === 1 ? 'changes' : 'change',
+		total,
+	};
+	plan.changes = changesOf(plan);
+	return plan;
+}
+
+/** The pane's list (the mockup's changeItems): what's been arranged so far, in words. */
+function changesOf(plan: Plan): Change[] {
+	const n = plan.now;
+	const nameOf = (id: string) => n.get(id)?.node.label ?? '';
+	const withWhat = (node: ArrangeNode) => {
+		const bits: string[] = [];
+		if (node.holds) bits.push(`its ${plural(node.holds.docs.length, node.holds.one, node.holds.many)}`);
+		const k = countPages(node.kids);
+		if (k === 1) bits.push(node.kids.find((c) => c.kind === 'page')?.label ?? 'its page');
+		else if (k > 1) bits.push(`its ${k} pages`);
+		return bits.length ? `, with ${andList(bits)}` : '';
+	};
+	const out: Change[] = [];
+	for (const e of plan.entries) {
+		if (e.t === 'newgroup') out.push({ icon: 'folder', parts: ['', e.label, ` is a new group${e.empty ? ', still empty' : ''}`] });
+		else if (e.t === 'rename') out.push({ icon: 'pencil', parts: ['', e.from, ' is renamed ', e.to, ''] });
+		else if (e.t === 'groupmove') out.push({ icon: 'arrow-r', parts: e.dest ? ['', e.label, ' moves into ', e.dest, ''] : ['', e.label, ' moves to the top level'] });
+		else if (e.t === 'move') {
+			const x = n.get(e.id)!;
+			const tail = `${withWhat(x.node)}${e.vis === 'hidden' ? ', and will be hidden' : e.vis === 'shown' ? ', and will be shown' : ''}`;
+			out.push({ icon: 'arrow-r', parts: x.parent ? ['', e.label, ' moves into ', nameOf(x.parent), tail] : ['', e.label, ` moves to the top level${tail}`] });
+		} else if (e.t === 'gone') out.push({ icon: 'folder', muted: true, parts: ['', e.label, ' goes: no pages left in it'] });
+		else if (e.t === 'joined') out.push({ icon: 'folder', parts: e.how === 'drop' ? ['', e.into, ' becomes ', e.label, '’s own page'] : ['', e.label, ' joins ', e.into, ': its pages go under it'] });
+	}
+	for (const p of plan.reorders) out.push({ icon: 'list', parts: p ? ['The order changes in ', nameOf(p), ''] : ['The order changes at the top level'] });
+	return out;
+}
+
+/** "at the top level and in About": where the order changes. */
+export function whereOrder(plan: Plan): string {
+	return andList(plan.reorders.map((p) => (p ? `in ${plan.now.get(p)?.node.label ?? ''}` : 'at the top level')));
+}
+
+// ── Re-planning on a fresh listing (Decision 10) ───────────────────────────────
+
+export interface Rebased {
+	orig: ArrangeNode[];
+	tree: ArrangeNode[];
+	/** What changed underneath, one sentence each: "Kiln & Co. was added under Services since you opened this." */
+	notes: string[];
+	/** Rows added since, marked in the review. */
+	added: string[];
+	/** Held documents added since (their paths), marked in the open disclosure. */
+	addedDocs: string[];
+	/** Two rows that would land at one address: the arrangement can't be applied as it is. */
+	clashes: string[];
+}
+
+/**
+ * The same arrangement on a fresh listing: rows that went are taken out (what the person
+ * moved under them stays, in their place), rows added since go where the listing has them
+ * (under the same row as on the site, which may since have moved or been renamed on the
+ * screen), names, hidden marks and held documents are the listing's.
+ */
+export function rebase(site: ArrangeSite, oldOrig: readonly ArrangeNode[], tree: readonly ArrangeNode[], documents: readonly ListedDocument[]): Rebased {
+	const orig = buildTree(site, documents);
+	const was = indexTree(oldOrig);
+	const fresh = indexTree(orig);
+	const next = clone(tree) as ArrangeNode[];
+	const notes: string[] = [];
+	const added: string[] = [];
+	const addedDocs: string[] = [];
+	const addr = (kind: ArrangeNode['kind'], path: string) => addressAt(site, kind, path);
+
+	// Gone since: taken out, keeping in their place whatever the person put under them.
+	for (const [id, y] of was) {
+		if (fresh.has(id)) continue;
+		const at = locate(next, id);
+		if (!at) continue;
+		if (y.node.kind === 'page') notes.push(`${y.node.label} was deleted since you opened this.`);
+		const keep = at.node.kids.filter((k) => !(was.has(k.id) && !fresh.has(k.id)));
+		at.list.splice(at.i, 1, ...keep);
+	}
+	// Still there: the listing's name, hidden mark, kind and held documents.
+	for (const [id, f] of fresh) {
+		const y = was.get(id);
+		const at = locate(next, id);
+		if (!y || !at) continue;
+		const node = at.node;
+		if (y.node.kind !== f.node.kind) {
+			if (f.node.kind === 'page') {
+				notes.push(`${f.node.label} was made at ${addr('page', f.path)} since you opened this.`);
+				added.push(id);
+			} else notes.push(`${y.node.label} was deleted since you opened this; its pages stay, as a group.`);
+		}
+		node.kind = f.node.kind;
+		if (f.node.kind === 'page' || !node.label) node.label = f.node.label;
+		node.hidden = f.node.hidden;
+		const before = y.node.holds?.docs ?? [];
+		const after = f.node.holds?.docs ?? [];
+		node.holds = f.node.holds ? clone(f.node.holds) : null;
+		if (f.node.holds && y.node.holds) {
+			const newOnes = after.filter((d) => !before.some((b) => b.path === d.path));
+			const lost = before.filter((b) => !after.some((d) => d.path === b.path)).length;
+			const h = f.node.holds;
+			if (newOnes.length) {
+				addedDocs.push(...newOnes.map((d) => d.path));
+				notes.push(`${f.node.label} has ${newOnes.length === 1 ? `a new ${h.one}` : `${newOnes.length} new ${h.many}`} since you opened this, so ${plural(after.length, h.one, h.many)} move with it.`);
+			}
+			if (lost) notes.push(`${plural(lost, h.one, h.many)} under ${f.node.label} ${lost === 1 ? 'was' : 'were'} deleted since you opened this.`);
+		}
+	}
+	// Added since: under the same row as on the site, at the end.
+	for (const [id, f] of fresh) {
+		if (was.has(id) || locate(next, id)) continue;
+		const pp = parentOf(f.path);
+		const nowIndex = indexTree(next);
+		let list: ArrangeNode[] = next;
+		let under = '';
+		if (pp) {
+			const holder = locate(next, pp)?.node ?? [...nowIndex.values()].find((x) => x.path === pp)?.node;
+			if (holder) {
+				list = holder.kids;
+				under = holder.label;
+			}
+		}
+		if (f.node.kind === 'group') {
+			// A folder made by a page added in it: one already on the screen at that address takes its pages.
+			const there = [...nowIndex.values()].find((x) => x.path === f.path);
+			if (there) continue;
+			list.push({ ...clone(f.node), kids: [] });
+			continue;
+		}
+		list.push({ ...clone(f.node), kids: [] });
+		added.push(id);
+		notes.push(`${f.node.label} was added ${under ? `under ${under}` : 'at the top level'} since you opened this.`);
+	}
+	// Two rows at one address: the person has to arrange it again.
+	const clashes: string[] = [];
+	const scan = (nodes: readonly ArrangeNode[], pp: string) => {
+		const seen = new Map<string, ArrangeNode>();
+		for (const k of nodes) {
+			const other = seen.get(k.slug);
+			if (other) {
+				const [a, b] = added.includes(k.id) ? [k, other] : [other, k];
+				const path = pp ? `${pp}/${k.slug}` : k.slug;
+				clashes.push(`${a.label} ${added.includes(a.id) ? 'was added at' : 'is at'} ${addr(a.kind, path)}, where ${b.label} would go. Go back and move one of them.`);
+			} else seen.set(k.slug, k);
+			scan(k.kids, pp ? `${pp}/${k.slug}` : k.slug);
+		}
+	};
+	scan(next, '');
+	return { orig, tree: next, notes, added, addedDocs, clashes };
+}