caracms 0.3.4 → 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/collections/CollectionTable.tsx

@@ -28,7 +28,7 @@ import { useEditor, useStore } from '../context.tsx';
 import type { Editor } from '../editor.ts';
 import { createStore, type Store } from '../state/store.ts';
 import { Icon } from '../shell/Icons.tsx';
-import { docIcon } from '../nav/DocRow.tsx';
+import { docIcon, hiddenTitle } from '../nav/DocRow.tsx';
 import { DocMarksView } from '../live/marks.tsx';
 import { when } from '../live/format.ts';
 import { openDialog } from '../documents/dialogs.tsx';
@@ -378,6 +378,14 @@ function Row(props: { doc: ListedDocument; columns: readonly TableColumn[]; curr
 										<span className="sr">, can't be opened: {doc.warning.message}</span>
 									</span>
 								) : null}
+								{/* M9 Decision 7, collections under pages (Decision 11): hidden, or hidden with the page that holds it, named. */}
+								{/* The sidebar's mark: the word, small and grey; the page that hides it on hover and to a screen reader. */}
+								{doc.hidden ? (
+									<span className="hmark" data-mark="hidden" title={hiddenTitle(doc, editor.documents.get())}>
+										Hidden
+										{doc.hiddenBy ? <span className="sr">: {hiddenTitle(doc, editor.documents.get())}</span> : null}
+									</span>
+								) : null}
 								{editor.mode === 'live' ? <DocMarksView file={doc.file} /> : <span data-slot="presence" hidden />}
 							</span>
 							{props.extra ? <span className="ct-extra">{props.extra}</span> : null}

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

@@ -70,31 +70,76 @@ export async function deleteDocument(editor: Editor, ref: DocRef, title: string)
 /**
  * Change a document's address (pre-M7 item 8). Its unsent edits go first (the move
  * carries them), then the document opens at its new address in place of the old one,
- * and the list is read again (other documents' links changed too).
+ * and the list is read again (other documents' links changed too). `redirect` false: no
+ * redirect from the old address.
  */
-export async function moveDocument(editor: Editor, ref: DocRef, to: string, title: string): Promise<{ ok: true; body: MoveResponse } | Refused> {
-	const id = docId(ref);
-	const open = sameDoc(editor.doc.get().ref, ref);
+export async function moveDocument(editor: Editor, ref: DocRef, to: string, title: string, redirect = true): Promise<{ ok: true; body: MoveResponse } | Refused> {
+	// Everything under it moves with it (collections under pages, Decision 9): each of those documents' unsent edits too.
+	const moving = addressesMoving(editor.site?.collections ?? [], ref, to, editor.documents?.get() ?? []).map((m) => ({ collection: m.doc.collection, path: m.doc.path }));
+	const refs = moving.some((m) => sameDoc(m, ref)) ? moving : [ref, ...moving];
 	// Nothing moves while the keeper still holds edits the server hasn't got (a held conflict, a
 	// signed-out session, a refused write): the move would discard them.
-	let flushed = true;
-	await editor.keeper?.flush(id).catch(() => {
-		flushed = false;
-	});
-	if (!flushed || editor.keeper?.dirty(id)) {
-		return { ok: false, status: 0, error: `${title} has changes that haven't been saved yet, so its address can't change. Sort those out first (Use mine or Discard mine, or sign in again), then try again.`, code: 'unsent', usedOn: null };
+	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 = sameDoc(r, ref) ? title : (editor.documents?.get().find((d) => sameDoc(d, r))?.label ?? r.path);
+			return { ok: false, status: 0, error: `${what} has changes that haven't been saved yet, so ${sameDoc(r, ref) ? 'its' : `${title}'s`} address can't change. Sort those out first (Use mine or Discard mine, or sign in again), then try again.`, code: 'unsent', usedOn: null };
+		}
 	}
-	const answer = await post<MoveResponse>(editor, ENDPOINTS.move, { collection: ref.collection, path: ref.path, to });
+	const answer = await post<MoveResponse>(editor, ENDPOINTS.move, { collection: ref.collection, path: ref.path, to, ...(redirect ? {} : { redirect: false }) });
 	if (!answer.ok) return answer;
-	editor.keeper?.discard(id);
-	await editor.refreshDocuments().catch(() => undefined);
-	if (open) await editor.openDocument({ collection: answer.body.collection, path: answer.body.path }, { history: 'replace' });
 	const { url, from } = answer.body;
-	editor.toast(`Moved ${title} to ${url}.`, 'check');
-	editor.announce(`Moved ${title} from ${from.url} to ${url}.`);
+	const moved = answer.body.moved ?? [];
+	for (const r of refs) editor.keeper?.discard(docId(r));
+	await editor.refreshDocuments().catch(() => undefined);
+	// The open document goes with it when it's under it.
+	const openRef = editor.doc.get().ref;
+	const opened = sameDoc(openRef, ref) ? { collection: answer.body.collection, from: ref.path, to: answer.body.path } : moved.find((m) => m.collection === openRef.collection && m.from === openRef.path);
+	if (opened && opened.from !== opened.to) await editor.openDocument({ collection: opened.collection, path: opened.to }, { history: 'replace' });
+	else if (opened) await editor.reloadOpen();
+	const more = Math.max(moved.length - 1, 0);
+	editor.toast(more ? `Moved ${title} to ${url}, with ${more} more under it.` : `Moved ${title} to ${url}.`, 'check');
+	editor.announce(more ? `Moved ${title} from ${from.url} to ${url}, and ${more} more addresses under it.` : `Moved ${title} from ${from.url} to ${url}.`);
 	return answer;
 }
 
+/** One address Change address… changes (collections under pages, Decision 9). */
+export interface AddressChange {
+	doc: ListedDocument;
+	/** Its new address; null while the new path isn't one yet. */
+	toUrl: string | null;
+	/** A document of a collection a page in the move holds (its file stays; only its address changes). */
+	held: boolean;
+}
+
+/**
+ * Every address Change address… on `ref` changes once it's at `to` (Decision 9): the
+ * document, the pages under it at any depth, and the documents of each collection held by
+ * it or a page under it. move.ts → `movesUnder` and `planMoves` work out the same, so the
+ * dialog lists them before asking.
+ */
+export function addressesMoving(collections: readonly EditorAnyCollection[], ref: DocRef, to: string, documents: readonly ListedDocument[]): AddressChange[] {
+	const collection = collections.find((c) => c.name === ref.collection);
+	const root = documents.find((d) => d.collection === ref.collection && d.path === ref.path);
+	if (!collection || !root) return [];
+	const newPath = (path: string) => (path === ref.path ? to : `${to}${path.slice(ref.path.length)}`);
+	const pages = [root, ...(collection.nested ? pagesUnder(collection.name, ref.path, documents) : [])];
+	const out: AddressChange[] = pages.map((d) => ({ doc: d, toUrl: addressFor(collection, newPath(d.path)), held: false }));
+	for (const held of collections) {
+		const holder = held.holder;
+		if (!held.heldBy || !holder || holder.collection !== ref.collection) continue;
+		if (holder.path !== ref.path && !holder.path.startsWith(`${ref.path}/`)) continue;
+		const holderUrl = addressFor(collection, newPath(holder.path));
+		const base = holderUrl === null ? null : `${holderUrl.replace(/\/+$/, '')}/`;
+		for (const d of documents) if (d.collection === held.name && d.url !== null && !d.warning) out.push({ doc: d, toUrl: base === null ? null : base + d.path, held: true });
+	}
+	return out;
+}
+
 /**
  * M6c G4 (Decision 9): Replace… on a file. Every unsent edit in this tab goes first, and
  * nothing is replaced while any is still held (a conflict, a refusal, a signed-out
@@ -167,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 ?? '/';
@@ -182,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({