caracms 0.3.4 → 0.5.0

package/src/page-order.ts

@@ -0,0 +1,253 @@
+/**
+ * The Pages tree's saved order (arrange pages, Decisions 6, 7 and 19). Browser-safe: no
+ * node or disk imports, so the editor's client uses the same rules as the server.
+ *
+ * - **`PageOrder`** is Site Settings' `pageOrder`: a parent's path (`""` for the top level)
+ *   → its children's slugs, pages and groups alike, in order. Absent means "the rule".
+ * - **The order of one level** (`orderSiblings`, Decision 7): Home first, always; then the
+ *   siblings the saved list names, in that order (an unknown slug is ignored); then the
+ *   unlisted ones, those with pages or a held collection under them first, then A–Z by
+ *   label (content.ts's collator).
+ * - **After moves** (`orderAfterMoves`, Decision 6): a moved page's slug leaves its old
+ *   parent's list and goes at the end of its new parent's (when that level has a saved
+ *   list; with none, the rule places it); every key at or under a moved path is re-keyed,
+ *   at any depth; a group renamed (every page under it moving to the same place under a new
+ *   folder) changes its key and its slug in place; a list left empty is dropped.
+ * - **The Apply's merge** (`arrangedOrder`): the re-keyed saved order, then the request's
+ *   own lists replacing those keys.
+ * - **The stamp** (`pageOrderStamp`, Decision 18): a short hash of the order, so another
+ *   tab sees an order-only change on its next poll.
+ */
+
+/** Site Settings' `pageOrder`: parent path (`""` is the top level) → its children's slugs in order. */
+export type PageOrder = Record<string, string[]>;
+
+/** One path that changes: a page's (or a group's folder's) path in the Pages collection, before → after. */
+export interface PathChange {
+	from: string;
+	to: string;
+}
+
+/** The collection the saved order is for: the nested section builder at `/` (Pages). */
+export function isOrderedCollection(collection: { nested?: boolean; urlBase: string | null }): boolean {
+	return !!collection.nested && collection.urlBase === '/';
+}
+
+/** A path's parent (`''` at the top level). */
+export const parentOf = (path: string): string => (path.includes('/') ? path.slice(0, path.lastIndexOf('/')) : '');
+/** A path's last part. */
+export const slugOf = (path: string): string => path.slice(path.lastIndexOf('/') + 1);
+const isHome = (path: string) => path === 'index' || path.endsWith('/index');
+const under = (path: string, folder: string) => path === folder || path.startsWith(`${folder}/`);
+
+const collator = new Intl.Collator('en', { sensitivity: 'base', numeric: true });
+/** A–Z by label, then by path (content.ts's order). */
+export function byLabel(a: { label: string; path: string }, b: { label: string; path: string }): number {
+	return collator.compare(a.label, b.label) || collator.compare(a.path, b.path);
+}
+
+/**
+ * One level of the tree in order (Decision 7): Home first; then the siblings `saved` names,
+ * in its order; then the rest, those `filled` (pages or a held collection under them) first,
+ * then A–Z by label. `saved` undefined: the rule alone.
+ */
+export function orderSiblings<T extends { path: string; label: string }>(items: readonly T[], saved: readonly string[] | undefined, filled: (item: T) => boolean): T[] {
+	const rank = new Map<string, number>();
+	(saved ?? []).forEach((slug, i) => {
+		if (!rank.has(slug)) rank.set(slug, i);
+	});
+	return [...items].sort((a, b) => {
+		const ha = isHome(a.path);
+		const hb = isHome(b.path);
+		if (ha !== hb) return ha ? -1 : 1;
+		const ra = rank.get(slugOf(a.path));
+		const rb = rank.get(slugOf(b.path));
+		if (ra !== undefined || rb !== undefined) {
+			if (ra === undefined) return 1;
+			if (rb === undefined) return -1;
+			if (ra !== rb) return ra - rb;
+		}
+		const fa = filled(a);
+		const fb = filled(b);
+		if (fa !== fb) return fa ? -1 : 1;
+		return byLabel(a, b);
+	});
+}
+
+/** `pageOrder` as read from a file: an object of string lists; anything else dropped, each list without repeats, empty lists left out. */
+export function parsePageOrder(raw: unknown): PageOrder {
+	if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return {};
+	const out: PageOrder = {};
+	for (const [key, list] of Object.entries(raw as Record<string, unknown>)) {
+		if (!Array.isArray(list)) continue;
+		const slugs = [...new Set(list.filter((s): s is string => typeof s === 'string' && s !== ''))];
+		if (slugs.length) out[key] = slugs;
+	}
+	return out;
+}
+
+/** The order without its empty lists (and without repeats in a list). */
+function tidy(order: PageOrder): PageOrder {
+	const out: PageOrder = {};
+	for (const [key, list] of Object.entries(order)) {
+		const slugs = [...new Set(list)];
+		if (slugs.length) out[key] = slugs;
+	}
+	return out;
+}
+
+/**
+ * The groups the moves rename: a folder with no page of its own (in `pathsBefore`, the Pages
+ * collection's paths before the moves) all of whose pages move to the same place under one
+ * new folder that's free once the moves land (a swap is fine). Topmost only.
+ */
+export function groupRenames(pathsBefore: readonly string[], moves: readonly PathChange[]): PathChange[] {
+	const pages = new Set(pathsBefore);
+	const moving = new Map(moves.map((m) => [m.from, m.to]));
+	const folders = new Set<string>();
+	for (const p of pathsBefore) {
+		const parts = p.split('/');
+		for (let i = 1; i < parts.length; i++) folders.add(parts.slice(0, i).join('/'));
+	}
+	const renames: PathChange[] = [];
+	for (const group of [...folders].filter((f) => !pages.has(f)).sort((a, b) => a.split('/').length - b.split('/').length)) {
+		if (renames.some((r) => under(group, r.from))) continue;
+		const inside = pathsBefore.filter((p) => p.startsWith(`${group}/`));
+		let to: string | null = null;
+		const same = inside.every((p) => {
+			const target = moving.get(p);
+			const rest = p.slice(group.length);
+			if (target === undefined || !target.endsWith(rest)) return false;
+			const folder = target.slice(0, target.length - rest.length);
+			if (to === null) to = folder;
+			return folder === to;
+		});
+		if (!same || to === null || to === '' || to === group || under(to, group)) continue;
+		const into = to as string;
+		// The new folder is free once the moves land: whatever's there now moves away.
+		if (pathsBefore.some((p) => under(p, into) && !moving.has(p))) continue;
+		renames.push({ from: group, to: into });
+	}
+	return renames;
+}
+
+/**
+ * The saved order once these moves land (Decision 6). `moves`: every page path that changes
+ * (Change address…'s or an Apply's, expanded: the pages under a moved page included);
+ * `pathsBefore`: the Pages collection's paths before them, for the groups they rename.
+ */
+export function orderAfterMoves(order: PageOrder, moves: readonly PathChange[], pathsBefore: readonly string[] = []): PageOrder {
+	const all = [...moves.filter((m) => m.from !== m.to), ...groupRenames(pathsBefore, moves)].sort((a, b) => a.from.split('/').length - b.from.split('/').length);
+	// The moves that aren't carried by a move above them: those change a list.
+	const units: PathChange[] = [];
+	for (const m of all) {
+		if (units.some((u) => u.from === m.from)) continue;
+		const carried = units.some((u) => m.from.startsWith(`${u.from}/`) && m.to === u.to + m.from.slice(u.from.length));
+		if (!carried) units.push(m);
+	}
+	if (units.length === 0) return tidy(order);
+	const rekey = (path: string) => {
+		let best: PathChange | null = null;
+		for (const u of units) if (under(path, u.from) && (!best || u.from.length > best.from.length)) best = u;
+		return best ? best.to + path.slice(best.from.length) : path;
+	};
+	const out: PageOrder = {};
+	for (const [key, list] of Object.entries(order)) {
+		const into = (out[rekey(key)] ??= []);
+		for (const slug of list) if (!into.includes(slug)) into.push(slug);
+	}
+	// Each unit's place in its old list, marked first, so a swap's slugs can't meet.
+	const marks = units.map((_, i) => `\u0000${i}`);
+	units.forEach((u, i) => {
+		const list = out[rekey(parentOf(u.from))];
+		const at = list ? list.indexOf(slugOf(u.from)) : -1;
+		if (at >= 0) list![at] = marks[i]!;
+	});
+	units.forEach((u, i) => {
+		const oldKey = rekey(parentOf(u.from));
+		const newKey = parentOf(u.to);
+		const slug = slugOf(u.to);
+		const old = out[oldKey];
+		const at = old ? old.indexOf(marks[i]!) : -1;
+		if (oldKey === newKey) {
+			// Renamed in place (a group rename, or a page's own slug): it keeps its place.
+			if (at >= 0) {
+				if (old!.includes(slug)) old!.splice(at, 1);
+				else old![at] = slug;
+			}
+			return;
+		}
+		if (at >= 0) old!.splice(at, 1);
+		const into = out[newKey];
+		if (into && !into.includes(slug)) into.push(slug);
+	});
+	for (const list of Object.values(out)) for (let i = list.length - 1; i >= 0; i--) if (list[i]!.startsWith('\u0000')) list.splice(i, 1);
+	return tidy(out);
+}
+
+/** The Apply's order (Contracts): the saved order re-keyed after the moves, then the request's lists replacing those keys, empty lists dropped. */
+export function arrangedOrder(saved: PageOrder, requested: PageOrder, moves: readonly PathChange[], pathsBefore: readonly string[] = []): PageOrder {
+	return tidy({ ...orderAfterMoves(saved, moves, pathsBefore), ...requested });
+}
+
+/** The saved order's entries that name nothing: a key that's no page or group, or a slug that's no child of its key. `paths`: the Pages collection's paths. */
+export function unknownOrderEntries(order: PageOrder, paths: readonly string[]): { key: string; slug: string | null }[] {
+	const known = new Set<string>(['']);
+	for (const p of paths) {
+		const parts = p.split('/');
+		for (let i = 1; i <= parts.length; i++) known.add(parts.slice(0, i).join('/'));
+	}
+	const out: { key: string; slug: string | null }[] = [];
+	for (const [key, list] of Object.entries(order)) {
+		if (!known.has(key)) {
+			out.push({ key, slug: null });
+			continue;
+		}
+		for (const slug of list) if (!known.has(key === '' ? slug : `${key}/${slug}`)) out.push({ key, slug });
+	}
+	return out;
+}
+
+/** The order without the entries `unknownOrderEntries` finds, and how many slugs went. */
+export function prunedOrder(order: PageOrder, paths: readonly string[]): { order: PageOrder; pruned: number } {
+	const unknown = unknownOrderEntries(order, paths);
+	if (unknown.length === 0) return { order, pruned: 0 };
+	const out: PageOrder = {};
+	let pruned = 0;
+	for (const [key, list] of Object.entries(order)) {
+		if (unknown.some((u) => u.key === key && u.slug === null)) {
+			pruned += list.length;
+			continue;
+		}
+		const kept = list.filter((slug) => !unknown.some((u) => u.key === key && u.slug === slug));
+		pruned += list.length - kept.length;
+		if (kept.length) out[key] = kept;
+	}
+	return { order: out, pruned };
+}
+
+/** FNV-1a over a text, in base 36. */
+function fnv(text: string): string {
+	let hash = 0x811c9dc5;
+	for (let i = 0; i < text.length; i++) {
+		hash ^= text.charCodeAt(i);
+		hash = Math.imul(hash, 0x01000193) >>> 0;
+	}
+	return hash.toString(36);
+}
+
+/**
+ * Decision 10: a short hash of a collection's document paths, sorted (FNV-1a), so the Apply
+ * can tell the listing it was planned on from the one it lands on (`ArrangeRequest.expect`).
+ */
+export function listingStamp(paths: readonly string[]): string {
+	return fnv(JSON.stringify([...paths].sort()));
+}
+
+/** Decision 18: a short hash of the order (FNV-1a over its keys in order); `""` when there's none. */
+export function pageOrderStamp(order: PageOrder | null | undefined): string {
+	if (!order) return '';
+	const keys = Object.keys(order).sort();
+	if (keys.length === 0) return '';
+	return fnv(JSON.stringify(keys.map((k) => [k, order[k]])));
+}

package/src/redirects.ts

@@ -1,11 +1,12 @@
 /**
  * Redirects (pre-M7 item 8): Site Settings' `redirects`, a list of `{ from, to }`
  * site addresses. Changing a document's address adds one, from the old address to
- * the new; the package serves them as 301s on the public site (redirect-middleware.ts).
+ * the new, unless it's asked not to (move.ts); the package serves them as 301s on the public site (redirect-middleware.ts).
  * Browser-safe (no imports beyond links.ts): the Redirects section reads them too.
  *
  *   parseRedirects(raw)                        the list as the file holds it, cleaned
  *   redirectsAfterMove(list, from, to, add)    the list once a document moves
+ *   redirectsAfterMoves(list, moves, homes?)   the list once several move at once (swaps, chains)
  *   redirectFor(list, pathname)                where a request for `pathname` goes, or null
  *
  * - **Both ends are `/paths`**, without a trailing slash (`/` stays `/`). An entry that
@@ -64,6 +65,68 @@ export function redirectsAfterMove(list: readonly Redirect[], from: string, to:
 	return next;
 }
 
+/**
+ * A document's live address (the one the public site served at the last Publish) and
+ * where it is once the plan has landed: live mode's documents moved since the last Publish
+ * (autosaves.ts → `recordAddresses`). `redirectsAfterMoves` adds `live → now` when a move
+ * in the plan vacates `live`.
+ */
+export interface LiveHome {
+	live: string;
+	now: string;
+}
+
+/** The homes whose live address a move in the plan vacates and no document then takes: each adds `live → now`. */
+function strandedHomes(moves: readonly { from: string; to: string }[], homes: readonly LiveHome[]): Redirect[] {
+	const taken = (address: string) => moves.some((m) => same(m.to, address));
+	const out: Redirect[] = [];
+	for (const h of homes) {
+		if (same(h.live, h.now) || taken(h.live) || !moves.some((m) => same(m.from, h.live))) continue;
+		if (out.some((r) => same(r.from, h.live))) continue;
+		out.push({ from: h.live, to: h.now });
+	}
+	return out;
+}
+
+/**
+ * The list once several documents move at once (the many-move engine): every move is
+ * taken against the list before the plan, so a swap or a chain comes out as its
+ * documents end up. Entries to an old address go to that document's new one (chains
+ * collapse, one step: `X → A` becomes `X → B` when A moves to B); an entry from an
+ * address a document now occupies goes (a page is there); and, per move with `add`,
+ * `from → to` is added, unless another document now sits at `from` (in a swap neither
+ * is added). With no address both vacated and taken, this is `redirectsAfterMove` per
+ * move, in order.
+ *
+ * `homes` (live mode, and only when the move leaves redirects): when a move vacates an
+ * address that is another document's live address (a chain before a Publish left that
+ * document without a redirect from it, since a document sat there), `live → now` is added
+ * too, replacing any entry from that address, so the public site's old address still
+ * finds its document after the Publish.
+ */
+export function redirectsAfterMoves(list: readonly Redirect[], moves: readonly { from: string; to: string; add: boolean }[], homes: readonly LiveHome[] = []): Redirect[] {
+	const taken = (address: string) => moves.some((m) => same(m.to, address));
+	const stranded = strandedHomes(moves, homes);
+	const replaced = (address: string) => moves.some((m) => m.add && same(m.from, address)) || stranded.some((r) => same(r.from, address));
+	const next = list
+		.filter((r) => !taken(r.from) && !replaced(r.from))
+		.map((r) => {
+			const m = moves.find((m) => same(r.to, m.from));
+			return m ? { from: r.from, to: m.to } : r;
+		})
+		.filter((r) => !same(r.from, r.to));
+	for (const r of redirectsAddedBy(moves, homes)) next.push(r);
+	return next;
+}
+
+/** The redirects a plan adds (`redirectsAfterMoves`): one per move with `add`, unless another document now sits at its old address, and one per stranded live address (`homes`). */
+export function redirectsAddedBy(moves: readonly { from: string; to: string; add: boolean }[], homes: readonly LiveHome[] = []): Redirect[] {
+	const taken = (address: string) => moves.some((m) => same(m.to, address));
+	const added = moves.filter((m) => m.add && !same(m.from, m.to) && !taken(m.from)).map((m) => ({ from: m.from, to: m.to }));
+	for (const r of strandedHomes(moves, homes)) if (!added.some((a) => same(a.from, r.from))) added.push(r);
+	return added;
+}
+
 /** Where a request for `pathname` goes, or null. Matched without a trailing slash; letter case counts, as it does for pages. */
 export function redirectFor(list: readonly Redirect[], pathname: string): string | null {
 	let path: string;

package/src/relink.ts

@@ -145,17 +145,47 @@ function fieldAt(site: Pick<ResolvedSite, 'blocks'>, collection: Pick<ResolvedCo
 	return field ? { field, rest } : null;
 }
 
-/** A string at `rest` inside a field's value, with its links to the old address rewritten; null when it isn't a link there or doesn't point there. */
-function relinkIn(field: Field, rest: Segment[], value: string, move: AddressMove): string | null {
+/**
+ * Several moves at once (collections under pages, Decision 9: a page and everything under
+ * it): each link is matched against the addresses as they were, once, so a swap stays a
+ * swap and a link is never moved twice.
+ */
+interface MoveIndex {
+	href: HrefRewrite;
+	ref: (collection: string, path: string) => string | null;
+}
+
+function indexMoves(moves: readonly AddressMove[]): MoveIndex {
+	const byUrl = new Map<string, AddressMove>();
+	const byPath = new Map<string, AddressMove>();
+	for (const m of moves) {
+		const url = normaliseAddress(m.fromUrl);
+		if (m.fromUrl !== m.toUrl && !byUrl.has(url)) byUrl.set(url, m);
+		// A held document keeps its path when its holder moves (check 18: references to it never change).
+		const key = `${m.collection}\u0000${m.fromPath}`;
+		if (m.fromPath !== m.toPath && !byPath.has(key)) byPath.set(key, m);
+	}
+	return {
+		href: (href) => {
+			const path = internalLinkPath(href);
+			const move = path === null ? undefined : byUrl.get(path);
+			return move ? relinkHref(href, move) : null;
+		},
+		ref: (collection, path) => byPath.get(`${collection}\u0000${path}`)?.toPath ?? null,
+	};
+}
+
+/** A string at `rest` inside a field's value, with its links to the old addresses rewritten; null when it isn't a link there or doesn't point at one. */
+function relinkIn(field: Field, rest: Segment[], value: string, moves: MoveIndex): string | null {
 	switch (field.kind) {
 		case 'link':
-			return rest.length === 1 && rest[0] === 'href' ? relinkHref(value, move) : null;
+			return rest.length === 1 && rest[0] === 'href' ? moves.href(value) : null;
 		case 'buttons':
-			return rest.length === 2 && typeof rest[0] === 'number' && rest[1] === 'href' ? relinkHref(value, move) : null;
+			return rest.length === 2 && typeof rest[0] === 'number' && rest[1] === 'href' ? moves.href(value) : null;
 		case 'richText':
-			return relinkRichText(value, move);
+			return rewriteRichText(value, moves.href)?.text ?? null;
 		case 'reference':
-			return rest.length === 0 && field.to === move.collection && value.trim() === move.fromPath ? move.toPath : null;
+			return rest.length === 0 && field.to ? moves.ref(field.to, value.trim()) : null;
 		default:
 			return null;
 	}
@@ -217,17 +247,18 @@ function splice(text: string, edits: { start: number; end: number; text: string
 /**
  * The file's text with every link and reference to the moved document pointing at
  * its new address (or path); `text` itself when nothing points there. `collection` is
- * the file's own collection (for its schema).
+ * the file's own collection (for its schema). Several moves are applied at once.
  */
 export function relinkText(
 	text: string,
-	move: AddressMove,
+	move: AddressMove | readonly AddressMove[],
 	site: Pick<ResolvedSite, 'blocks'>,
 	collection: Pick<ResolvedCollection, 'kind' | 'fields'>,
 ): { text: string; links: number } {
 	const edits: { start: number; end: number; text: string }[] = [];
+	const moves = indexMoves(Array.isArray(move) ? move : [move as AddressMove]);
 	const ok = fieldStrings(text, site, collection, (field, rest, value, node) => {
-		const next = relinkIn(field, rest, value, move);
+		const next = relinkIn(field, rest, value, moves);
 		if (next !== null && next !== value) edits.push({ start: node.start, end: node.end, text: JSON.stringify(next) });
 	});
 	if (!ok || edits.length === 0) return { text, links: 0 };

package/src/reserved.ts

@@ -19,6 +19,7 @@ export const RESERVED_COLLECTIONS = ['shared', 'settings'] as const;
  * The keys of Site Settings the package owns (Decision 10); the site's own
  * `settings.fields` can't use them. M6 adds the search and sharing defaults, the
  * Google tag and the form emails' recipients (M6 Decision 14); pre-M7 item 8, the
- * redirects (redirects.ts).
+ * redirects (redirects.ts); arrange pages (Decision 6), the Pages tree's saved order
+ * (page-order.ts), which only the arrange screen writes.
  */
-export const SETTINGS_KEYS = ['title', 'editors', 'brand', 'seo', 'googleTag', 'formRecipients', 'redirects'] as const;
+export const SETTINGS_KEYS = ['title', 'editors', 'brand', 'seo', 'googleTag', 'formRecipients', 'redirects', 'pageOrder'] as const;

package/src/serialize.ts

@@ -57,6 +57,7 @@ import {
 import { fieldToJson, isEmptyValue, parseField, type Field, type Fields } from './fields.ts';
 import { mediaLine } from './media-value.ts';
 import { parseRedirects } from './redirects.ts';
+import { parsePageOrder } from './page-order.ts';
 import { member, parseSource, slice, type ArrayNode, type JsonNode, type MemberNode, type ObjectNode, type ParsedSource } from './json-source.ts';
 import { isEmptySeo, parseFormRecipients, parseGoogleTag, parseSeo, seoText, type Seo } from './seo.ts';
 import { SCHEMA_KEY } from './schema-key.ts';
@@ -242,7 +243,7 @@ export function applyEdits(base: string | null, edited: SiteDocument, site: Pick
 	}
 	if (fieldTexts.size) {
 		const next = parseSource(out);
-		if (next.root.kind === 'object') out = spliceKeys(next, next.root, fieldTexts, ['title', 'hidden', ...Object.keys(fields)]);
+		if (next.root.kind === 'object') out = spliceKeys(next, next.root, fieldTexts, ['title', 'hidden', 'holds', ...Object.keys(fields)]);
 	}
 	return withTrailingNewline(out);
 }
@@ -384,6 +385,18 @@ const redirectsCodec: KeyCodec = {
 	removeWhenEmpty: true,
 };
 
+/** Arrange pages (Decision 6): the saved order, one parent's list per line. */
+const pageOrderCodec: KeyCodec = {
+	parse: parsePageOrder,
+	text: (v, depth) => {
+		const entries = Object.entries(parsePageOrder(v));
+		if (entries.length === 0) return '{}';
+		return `{\n${entries.map(([k, list]) => `${pad(depth + 1)}${JSON.stringify(k)}: [${list.map((s) => JSON.stringify(s)).join(', ')}]`).join(',\n')}\n${pad(depth)}}`;
+	},
+	empty: (v) => Object.keys(parsePageOrder(v)).length === 0,
+	removeWhenEmpty: true,
+};
+
 const fieldCodec = (field: Field): KeyCodec => ({
 	parse: (raw) => parseField(field, raw),
 	text: (value, depth) => fieldText(field, value, depth),
@@ -419,6 +432,7 @@ function codecsFor(collection: Pick<ResolvedCollection, 'kind' | 'fields'>): Map
 		codecs.set('googleTag', googleTagCodec);
 		codecs.set('formRecipients', recipientsCodec);
 		codecs.set('redirects', redirectsCodec);
+		codecs.set('pageOrder', pageOrderCodec);
 	}
 	for (const [key, field] of Object.entries(collection.fields ?? ({} as Fields))) codecs.set(key, fieldCodec(field));
 	return codecs;
@@ -692,6 +706,9 @@ export function savedForm(text: string, collection: Pick<ResolvedCollection, 'ki
 		// brandCodec: logo and icon on one line each; redirectsCodec: one redirect per line.
 		keys.set('brand', { kind: 'object', keys: new Map([['logo', INLINE], ['icon', INLINE]]) });
 		keys.set('redirects', { kind: 'list', item: INLINE });
+		// pageOrderCodec: one parent's list per line.
+		const order = (raw as Record<string, unknown>).pageOrder;
+		if (order && typeof order === 'object' && !Array.isArray(order)) keys.set('pageOrder', { kind: 'object', keys: new Map(Object.keys(order).map((k) => [k, INLINE])) });
 	}
 	return `${layout(raw, { kind: 'object', keys }, 0)}\n`;
 }

package/src/slug.ts

@@ -17,7 +17,9 @@
  *   or null: under the editor's own `/admin` or `/_caracms`, or the library's files'
  *   `/files` (M6c Decision 3, served by files-route.ts); strictly below another
  *   collection's non-root `urlBase` (exactly at it is allowed: the Work page at
- *   `/work`); or another document's address already, in any collection.
+ *   `/work`), unless a page holds that collection (collections under pages, Decision 6:
+ *   pages may sit under a holder beside its documents); or another document's address
+ *   already, in any collection, held documents included (Decision 8), naming it.
  */
 import { codeRouteAt, codeRouteMessage, type CodeRoute } from './code-routes.ts';
 
@@ -56,8 +58,10 @@ export const INDEX_MESSAGE = '"index" is kept for Home, so it can\'t be an addre
 export interface AddressCollection {
 	name: string;
 	label: string;
-	/** Starts and ends with `/`; null for collections with no pages (shared blocks, Site Settings). */
+	/** Starts and ends with `/`; null for collections with no pages (shared blocks, Site Settings). A held collection's is its resolved base (held.ts). */
 	urlBase: string | null;
+	/** Collections under pages: set on a collection a page holds, whose base doesn't refuse pages below it (Decision 6). */
+	heldBy?: string | null;
 }
 
 /** What `addressProblem` needs of a document. */
@@ -65,6 +69,8 @@ export interface AddressDocument {
 	collection: string;
 	path: string;
 	url: string | null;
+	/** What the editor lists it as: `address-taken` names a document of another collection by it (Decision 8). */
+	label?: string;
 }
 
 export type AddressProblemCode = 'reserved-address' | 'below-collection' | 'address-taken';
@@ -105,7 +111,7 @@ export function addressProblem(
 	const route = codeRouteAt(url, codeRoutes);
 	if (route) return { code: 'reserved-address', message: codeRouteMessage(url, route) };
 	for (const other of collections) {
-		if (other.name === collection || other.urlBase === null) continue;
+		if (other.name === collection || other.urlBase === null || other.heldBy) continue;
 		const base = sameAddress(other.urlBase);
 		if (base === '/') continue;
 		if (at.startsWith(`${base}/`)) {
@@ -116,6 +122,11 @@ export function addressProblem(
 		}
 	}
 	const taken = documents.find((d) => d.url !== null && sameAddress(d.url) === at);
-	if (taken) return { code: 'address-taken', message: `There's already a page at ${url}.` };
+	if (taken) {
+		// Decision 8: a held document and a page can't share an address either way; the other is named.
+		const other = taken.collection !== collection ? collections.find((c) => c.name === taken.collection) : undefined;
+		const named = other && taken.label ? `: “${taken.label}” in ${other.label}` : '';
+		return { code: 'address-taken', message: `There's already a page at ${url}${named}.` };
+	}
 	return null;
 }