caracms 0.3.4 → 0.5.0

package/src/cli/validate.ts

@@ -24,7 +24,8 @@
 import { readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { ResolvedCollection, ResolvedSite } from '../config.ts';
-import { codeRouteAt, codeRouteMessage, shadowingMessage, shadowingRoutes, type CodeRoute } from '../code-routes.ts';
+import { codeRouteAt, codeRouteMessage, leftBehindMessage, leftBehindRoutes, shadowingMessage, shadowingRoutes, type CodeRoute } from '../code-routes.ts';
+import { heldBases } from '../held.ts';
 import { pagesRoutes, readCodeRoutes, srcDirOf } from '../code-routes-disk.ts';
 import { listDocuments, type DocumentEntry } from '../content.ts';
 import { own } from '../document.ts';
@@ -32,7 +33,9 @@ import { fieldWarnings, parseDay, richTextOptions, type Field, type Fields, type
 import { measureLockup } from '../measure.ts';
 import { isFileKey } from '../files.ts';
 import { readRichText } from '../rich-text.ts';
-import { savedForm } from '../serialize.ts';
+import { applyKeyedEdits, savedForm } from '../serialize.ts';
+import { isOrderedCollection, prunedOrder, unknownOrderEntries } from '../page-order.ts';
+import { SITE_SETTINGS_FILE } from '../reserved.ts';
 import { SCHEMA_KEY, schemaRef } from '../schema-key.ts';
 import { sameAddress } from '../slug.ts';
 import { hiddenDocuments, hiddenPages } from '../links.ts';
@@ -308,9 +311,10 @@ function checkDocument(c: Context, collection: ResolvedCollection, raw: unknown)
 	if (raw.title !== undefined && typeof raw.title !== 'string') error(c, 'title', `Expected text (a string), found ${what(raw.title)}.`);
 	switch (collection.kind) {
 		case 'sections': {
-			checkFields(c, own, raw, '', `a ${collection.label} page`, 0, [SCHEMA_KEY, 'title', 'hidden', 'blocks', 'seo']);
+			checkFields(c, own, raw, '', `a ${collection.label} page`, 0, [SCHEMA_KEY, 'title', 'hidden', 'holds', 'blocks', 'seo']);
 			// M9 Decision 7.
 			if (raw.hidden !== undefined && raw.hidden !== true) error(c, 'hidden', `Expected true (hidden from the site) or no "hidden" at all, found ${what(raw.hidden)}.`);
+			if (raw.holds !== undefined) checkHolds(c, collection, raw.holds);
 			if (!Object.hasOwn(raw, 'blocks')) error(c, 'blocks', 'This page has no "blocks". Every page has a list of blocks, even an empty one ([]).');
 			else if (!Array.isArray(raw.blocks)) error(c, 'blocks', `Expected a list of blocks, found ${what(raw.blocks)}.`);
 			else raw.blocks.forEach((b, i) => checkBlock(c, b, at('blocks', i), collection));
@@ -318,16 +322,19 @@ function checkDocument(c: Context, collection: ResolvedCollection, raw: unknown)
 			return;
 		}
 		case 'fields':
-			checkFields(c, own, raw, '', `a ${collection.label} document`, 0, [SCHEMA_KEY, 'title', 'seo']);
+			checkFields(c, own, raw, '', `a ${collection.label} document`, 0, [SCHEMA_KEY, 'title', 'seo', 'holds']);
+			if (raw.holds !== undefined) error(c, 'holds', HOLDS_ON_A_PAGE);
 			checkSeo(c, raw.seo, 'seo');
 			return;
 		case 'shared':
-			unknownKeys(c, raw, [SCHEMA_KEY, 'title', 'block'], '', 'a shared block');
+			unknownKeys(c, raw, [SCHEMA_KEY, 'title', 'block', 'holds'], '', 'a shared block');
+			if (raw.holds !== undefined) error(c, 'holds', HOLDS_ON_A_PAGE);
 			if (!Object.hasOwn(raw, 'block')) error(c, 'block', 'This shared block has no "block".');
 			else checkBlock(c, raw.block, 'block', null);
 			return;
 		case 'settings': {
-			checkFields(c, own, raw, '', 'Site Settings', 0, [SCHEMA_KEY, 'title', 'editors', 'brand', 'seo', 'googleTag', 'formRecipients', 'redirects']);
+			checkFields(c, own, raw, '', 'Site Settings', 0, [SCHEMA_KEY, 'title', 'editors', 'brand', 'seo', 'googleTag', 'formRecipients', 'redirects', 'pageOrder', 'holds']);
+			if (raw.holds !== undefined) error(c, 'holds', HOLDS_ON_A_PAGE);
 			if (raw.editors !== undefined && !strings(raw.editors)) error(c, 'editors', `Expected a list of email addresses, found ${what(raw.editors)}.`);
 			if (raw.brand !== undefined) {
 				if (!isObject(raw.brand)) error(c, 'brand', `Expected { "name", "accent", "logo", "icon" }, found ${what(raw.brand)}.`);
@@ -349,11 +356,31 @@ function checkDocument(c: Context, collection: ResolvedCollection, raw: unknown)
 			if (raw.redirects !== undefined && !(Array.isArray(raw.redirects) && raw.redirects.every((r) => isObject(r) && typeof r.from === 'string' && typeof r.to === 'string'))) {
 				error(c, 'redirects', 'Expected a list of { "from": "/old", "to": "/new" }.');
 			}
+			if (raw.pageOrder !== undefined && !(isObject(raw.pageOrder) && Object.values(raw.pageOrder).every(strings))) {
+				error(c, 'pageOrder', 'Expected { "<parent path>": ["slug", …] }.');
+			}
 			return;
 		}
 	}
 }
 
+/** Collections under pages (Decision 13): `"holds"` on anything but a page. */
+const HOLDS_ON_A_PAGE = '"holds" is for a page: it says which collection\'s documents sit under the page\'s address. Only a page of the collection that collection\'s heldBy names can hold one. Take it out.';
+
+/**
+ * Decision 13: a page's `"holds"` names a collection whose `heldBy` is this page's collection.
+ * Home holding one, and two pages holding one, are the collection's problems (held.ts), reported on their files by validateSite.
+ */
+function checkHolds(c: Context, collection: ResolvedCollection, holds: unknown) {
+	if (typeof holds !== 'string') return error(c, 'holds', `Expected a collection's key (text), like "journal", found ${what(holds)}.`);
+	const held = own(c.site.collections, holds);
+	if (!held || !held.heldBy) {
+		const heldOnes = Object.values(c.site.collections).filter((h) => h.heldBy === collection.name).map((h) => `"${h.name}"`);
+		return error(c, 'holds', `"holds" names "${holds}", which isn't a collection a page holds${heldOnes.length ? ` (a ${collection.label} page can hold ${heldOnes.join(' or ')})` : ''}. A collection is held when its config says heldBy: '${collection.name}'.`);
+	}
+	if (held.heldBy !== collection.name) error(c, 'holds', `${held.label} is held by a page of ${c.site.collections[held.heldBy]?.label ?? held.heldBy} (its heldBy), not of ${collection.label}. Move "holds" to a page there.`);
+}
+
 /** Every finding for the site's content. `codeRoutes`: the site's own (default: read from its src/pages). */
 export async function validateSite(site: Site, codeRoutes: readonly CodeRoute[] = readCodeRoutes(site.root, srcDirOf(site.root), Object.values(site.collections))): Promise<Report> {
 	const report: Report = { errors: [], warnings: [] };
@@ -373,10 +400,25 @@ export async function validateSite(site: Site, codeRoutes: readonly CodeRoute[]
 	}
 
 	// A second route with parameters at a collection's base hides its documents (code-routes.ts → one per base).
-	for (const s of shadowingRoutes(pagesRoutes(site.root, srcDirOf(site.root)), Object.values(site.collections))) {
+	const routes = pagesRoutes(site.root, srcDirOf(site.root));
+	for (const s of shadowingRoutes(routes, Object.values(site.collections))) {
 		report.errors.push({ file: s.route.file, path: '', message: shadowingMessage(s) });
 	}
 
+	// Collections under pages (Decision 13): a held collection with no addresses, its sentence on each file it names.
+	const bases = heldBases(site.collections, entries);
+	const held: { name: string; label: string; base: string; holder: string }[] = [];
+	for (const base of Object.values(bases)) {
+		const collection = site.collections[base.collection]!;
+		if (base.base && base.holder) held.push({ name: collection.name, label: collection.label, base: base.base, holder: base.holder.label });
+		if (!base.problem) continue;
+		const holders = entries.filter((e) => e.collection === collection.heldBy && e.holds === collection.name).map((e) => e.file);
+		for (const file of holders.length ? holders : [collection.folder]) report.errors.push({ file, path: holders.length ? 'holds' : '', message: base.problem });
+	}
+	// Decision 14: a route left at a held base serves those addresses ahead of the catch-all.
+	const leftBehind = leftBehindRoutes(routes, held);
+	for (const left of leftBehind) report.errors.push({ file: left.route.file, path: '', message: leftBehindMessage(left) });
+
 	const urls = new Map<string, DocumentEntry>();
 	for (const entry of entries) {
 		const c: Context = { file: entry.file, site, report, warningContext, exists };
@@ -399,13 +441,30 @@ export async function validateSite(site: Site, codeRoutes: readonly CodeRoute[]
 		if (isObject(raw) && raw[SCHEMA_KEY] === undefined) warning(c, '', `This file has no "$schema" (${JSON.stringify(schemaRef(collection, entry.file))}). \`caracms validate --fix\` adds it.`);
 		const saved = savedForm(text, collection, site);
 		if (saved !== null && saved !== text) warning(c, '', REFORMAT_MESSAGE);
-		if (entry.url !== null && collection.urlBase !== null) {
+		if (entry.url !== null) {
 			const route = codeRouteAt(entry.url, codeRoutes);
-			if (route) error(c, '', `${codeRouteMessage(entry.url, route)} Delete ${route.file} if this document replaces it, or move the document.`);
+			// A route left at a held base is reported once, on the route (above), not on every document under it.
+			if (route && !leftBehind.some((l) => l.route.file === route.file)) error(c, '', `${codeRouteMessage(entry.url, route)} Delete ${route.file} if this document replaces it, or move the document.`);
 			const same = sameAddress(entry.url);
 			const first = urls.get(same);
-			if (first) error(c, '', `${first.file} is at ${entry.url} too. Two documents can't share an address: move one.`);
-			else urls.set(same, entry);
+			if (first) {
+				// Decision 8: a clash is an error on both files (each names the other).
+				error(c, '', `${first.file} is at ${entry.url} too. Two documents can't share an address: move one.`);
+				report.errors.push({ file: first.file, path: '', message: `${entry.file} is at ${entry.url} too. Two documents can't share an address: move one.` });
+			} else urls.set(same, entry);
+		}
+	}
+
+	// Arrange pages (Decision 6): a saved order's entry that names no page or group (the reader ignores it).
+	const order = savedOrderOf(site);
+	if (order) {
+		for (const u of unknownOrderEntries(order, orderedPaths(site, entries))) {
+			const where = u.key === '' ? 'the top level' : `/${u.key}`;
+			report.warnings.push({
+				file: SITE_SETTINGS_FILE,
+				path: `pageOrder[${JSON.stringify(u.key)}]`,
+				message: u.slug === null ? `The Pages tree's order names ${where}, where there are no pages. \`caracms validate --fix\` prunes it.` : `The Pages tree's order names "${u.slug}" in ${where}, where there's no page or group by that name. \`caracms validate --fix\` prunes it.`,
+			});
 		}
 	}
 
@@ -419,6 +478,38 @@ export async function validateSite(site: Site, codeRoutes: readonly CodeRoute[]
 	return report;
 }
 
+/** The Pages collection's paths (page-order.ts → isOrderedCollection). */
+const orderedPaths = (site: Pick<ResolvedSite, 'collections'>, entries: readonly DocumentEntry[]) =>
+	entries.filter((e) => isOrderedCollection(site.collections[e.collection]!)).map((e) => e.path);
+
+/** Site Settings' `pageOrder` as the file has it, or null (no file, no key, or it doesn't parse). */
+function savedOrderOf(site: Pick<ResolvedSite, 'root'>): Record<string, string[]> | null {
+	try {
+		const raw = JSON.parse(readFileSync(join(site.root, SITE_SETTINGS_FILE), 'utf8')) as unknown;
+		const order = isObject(raw) ? raw.pageOrder : undefined;
+		if (!isObject(order) || !Object.values(order).every(strings)) return null;
+		return order as Record<string, string[]>;
+	} catch {
+		return null;
+	}
+}
+
+/** Arrange pages (Decision 6): `--fix` takes the saved order's entries that name nothing out of Site Settings. Returns how many went. */
+export async function prunePageOrder(site: Pick<ResolvedSite, 'root' | 'collections' | 'blocks'>): Promise<number> {
+	const order = savedOrderOf(site);
+	const settings = Object.values(site.collections).find((c) => c.kind === 'settings');
+	if (!order || !settings) return 0;
+	const { order: kept, pruned } = prunedOrder(order, orderedPaths(site, await listDocuments(site)));
+	if (pruned === 0) return 0;
+	const file = join(site.root, SITE_SETTINGS_FILE);
+	const text = readFileSync(file, 'utf8');
+	const raw = JSON.parse(text) as Record<string, unknown>;
+	writeFileSync(file, applyKeyedEdits(text, { title: typeof raw.title === 'string' ? raw.title : '', data: { pageOrder: kept } }, settings));
+	return pruned;
+}
+
+const pruneReport = (n: number) => (n ? `caracms validate --fix:\n  pruned ${n} page-order ${n === 1 ? 'entry' : 'entries'} (${SITE_SETTINGS_FILE})\n` : '');
+
 const REFORMAT_MESSAGE = "This file isn't laid out the way the editor saves it (two-space JSON, a trailing newline), so the editor's next save would reformat it and mix the two. `caracms validate --fix` rewrites it the editor's way, changing no values.";
 
 /**
@@ -463,7 +554,7 @@ export function formatReport(report: Report): string {
 export async function command(root: string, options: { fix?: boolean; json?: boolean } = {}): Promise<{ code: number; out: string; err?: string }> {
 	const site = await loadSite(root);
 	let fixed = '';
-	if (options.fix) fixed = schemasReport(await runSchemas(site)) + reformatReport(await reformatContent(site));
+	if (options.fix) fixed = schemasReport(await runSchemas(site)) + reformatReport(await reformatContent(site)) + pruneReport(await prunePageOrder(site));
 	const report = await validateSite(site);
 	const code = report.errors.length ? 1 : 0;
 	if (options.json) return { code, out: `${JSON.stringify(report, null, 2)}\n`, err: options.fix ? fixed : undefined };

package/src/code-routes.ts

@@ -108,6 +108,32 @@ export function codeRoutesFrom(routes: readonly CodeRoute[], collections: readon
 	return routes.filter((r) => shadowing.has(r) || !(r.dynamic && bases.has(sameAddress(r.url))));
 }
 
+/**
+ * Collections under pages (Decision 14): the prefix collections whose base has a route with
+ * parameters of its own (`tags/[slug].astro`), which the catch-all's reader leaves to that route,
+ * so no address is built twice. Never a collection at `/` (its own route is the catch-all) or a
+ * held one (its documents are always the catch-all's).
+ */
+export function ownRoutedCollections<C extends { name: string; urlBase: string | null; heldBy?: string | null }>(routes: readonly CodeRoute[], collections: readonly C[]): C[] {
+	return collections.filter((c) => c.urlBase !== null && !c.heldBy && sameAddress(c.urlBase) !== '/' && routes.some((r) => r.dynamic && sameAddress(r.url) === sameAddress(c.urlBase!)));
+}
+
+/** A route with parameters left at a held collection's resolved base (Decision 14): it serves those addresses ahead of the catch-all. */
+export interface LeftBehindRoute {
+	route: CodeRoute;
+	/** The held collection's label, its resolved base, and its holder's label. */
+	collection: { name: string; label: string; base: string; holder: string };
+}
+
+/** Every route with parameters whose static prefix is a held collection's resolved base (`journal/[slug].astro` after the switch). */
+export function leftBehindRoutes(routes: readonly CodeRoute[], held: readonly LeftBehindRoute['collection'][]): LeftBehindRoute[] {
+	return held.flatMap((collection) => routes.filter((r) => r.dynamic && sameAddress(r.url) === sameAddress(collection.base)).map((route) => ({ route, collection })));
+}
+
+/** validate's and the dev log's sentence for a route left at a held base (Decision 14). */
+export const leftBehindMessage = (l: LeftBehindRoute): string =>
+	`${l.route.file} serves ${l.collection.base}…, where the ${l.collection.holder} page's ${l.collection.label} documents are now. Delete it: the catch-all serves them.`;
+
 /** validate's sentence for a route that shadows a collection's documents. */
 export const shadowingMessage = (s: ShadowingRoute<{ name: string; urlBase: string | null }>): string =>
 	`${s.route.file} is a second route with parameters at the ${s.collection.name} collection's address (${s.collection.urlBase}), beside its own ${s.own.file}. Astro ranks it first, so it serves the addresses of that collection's documents and hides them. Move it under a folder of its own, or delete it if the documents replace it.`;

package/src/components/Head.astro

@@ -14,7 +14,7 @@
 import { join } from 'node:path';
 import { site } from 'virtual:caracms/config';
 import { build } from 'virtual:caracms/public';
-import { documentUrl } from '../content.ts';
+import { documentAddress } from '../content.ts';
 import type { PageProps } from '../document.ts';
 import { googleTagSnippet, headOf, withoutHtml } from '../head.ts';
 import { readMediaConfig } from '../media.ts';
@@ -30,17 +30,17 @@ const listPage = !preview && Number.isInteger(Astro.props.listPage) && Astro.pro
 const settingsText = await renderSourceOf(Astro.locals).readText(join(site.root, SITE_SETTINGS_FILE));
 // A public page's path is its own address; a preview's is the document's: the page component's
 // `path` when it's passed on, else the GET's `?path=` (for the home page's title).
-const previewPath = () => {
+const previewPath = async () => {
 	if (Astro.props.path !== undefined) return Astro.props.path;
-	const c = Object.hasOwn(site.collections, collection) ? site.collections[collection]! : null;
 	const path = Astro.url.searchParams.get('path');
-	return c && path ? documentUrl(c, path) : null;
+	// Collections under pages: a held document's address is its holder's + its slug.
+	return path ? documentAddress(site, collection, path, renderSourceOf(Astro.locals)) : null;
 };
 const head = headOf({
 	document,
 	settingsText,
 	// A public page's own address, without a `build.format: 'file'` prerender's `.html` (head.ts).
-	path: preview ? previewPath() : withoutHtml(Astro.url.pathname),
+	path: preview ? await previewPath() : withoutHtml(Astro.url.pathname),
 	siteUrl: preview ? null : build.siteUrl,
 	media: readMediaConfig(),
 	tagAllowed: build.production && !preview,

package/src/components/RenderDocument.astro

@@ -28,7 +28,7 @@
  */
 import { Page } from 'virtual:caracms/page';
 import { site } from 'virtual:caracms/config';
-import { documentUrl } from '../content.ts';
+import { documentAddress } from '../content.ts';
 import { own, type AnyDocument, type PageProps } from '../document.ts';
 import { documentPath } from '../head.ts';
 import { documentReader, renderFields, renderSourceOf, settingsRenderData } from '../read.ts';
@@ -52,10 +52,10 @@ const reader = documentReader(site, source);
 const data = fields && values ? await renderFields(fields, values, reader) : {};
 const settings = await settingsRenderData(site, source, reader);
 const previewOf = Astro.props.previewPath ?? Astro.url.searchParams.get('path');
-const ownCollection = own(site.collections, collection);
 const path = documentPath({
 	preview,
-	previewUrl: preview && ownCollection && previewOf ? documentUrl(ownCollection, previewOf) : null,
+	// Collections under pages: a held document's address is its holder's + its slug, read through the render's source.
+	previewUrl: preview && previewOf ? await documentAddress(site, collection, previewOf, source) : null,
 	pathname: Astro.url.pathname,
 	listPage,
 });

package/src/components/sitemap.xml.ts

@@ -1,7 +1,8 @@
 /**
  * `/sitemap.xml` (M6 Decision 12), prerendered at build from `SITE_URL` (Astro's `site`).
- * Every document with a URL: Pages, nested ones included, and every collection with a
- * `urlBase`, as absolute URLs on the site's address. One file, no index (a site's
+ * Every document with a URL: Pages, nested ones included, every collection with a
+ * `urlBase`, and every held one at its holder's address (collections under pages), as
+ * absolute URLs on the site's address. One file, no index (a site's
  * sitemap is small). Injected only when the address is known, so a build without
  * `SITE_URL` has no sitemap.
  */
@@ -19,9 +20,9 @@ const xml = (s: string) => s.replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&
 export async function sitemapUrls(siteUrl: string): Promise<string[]> {
 	const urls: string[] = [];
 	for (const collection of siteCollections(site)) {
-		if (collection.urlBase === null) continue;
+		if (collection.urlBase === null && !collection.heldBy) continue;
 		for (const entry of await listDocuments(site, collection.name)) {
-			// M9 Decision 7: a hidden page (or one under it) isn't on the site.
+			// M9 Decision 7: a hidden page (or one under it, or held by it) isn't on the site.
 			if (entry.warning || entry.url === null || entry.hidden) continue;
 			urls.push(`${siteUrl}${entry.url.split('/').map((p) => encodeURIComponent(p)).join('/')}`);
 		}

package/src/config.ts

@@ -41,8 +41,17 @@ export interface SectionsCollectionConfig {
 	kind: 'sections';
 	/** The folder holding the collection's content files, relative to the site's root. */
 	folder: string;
-	/** The URL the collection's documents live under: `/` for Pages, `/journal/` for a journal. */
-	urlBase: string;
+	/** The URL the collection's documents live under: `/` for Pages, `/tags/` for tags. Leave it out for a collection a page holds (`heldBy`). */
+	urlBase?: string;
+	/**
+	 * Collections under pages (Decision 2): the documents' address follows a page instead of a
+	 * prefix in code. Names the nested section builder (`'pages'`) one of whose pages holds this
+	 * collection: that page's file says `"holds": "<this collection>"`, and the documents are at
+	 * the page's address + `/` + their slug (`/journal/<slug>`), wherever the page moves. Not
+	 * with `urlBase`, and the collection is flat. Until a page holds it, its documents have no
+	 * addresses (`caracms validate` says why).
+	 */
+	heldBy?: string;
 	/**
 	 * Pages' rule (Decision 8): documents nest in folders and the file's path is the
 	 * URL; `index.json` at the top of the folder is `urlBase` itself, and an
@@ -105,6 +114,15 @@ export interface FieldsCollectionConfig<F extends Fields = Fields> {
 	 * in the page component, as a shared block's own preview is.
 	 */
 	urlBase?: string;
+	/**
+	 * Collections under pages (Decision 2): the documents' address follows a page instead of a
+	 * prefix in code. Names the nested section builder (`'pages'`) one of whose pages holds this
+	 * collection: that page's file says `"holds": "<this collection>"`, and the documents are at
+	 * the page's address + `/` + their slug (`/journal/<slug>`), wherever the page moves. Not
+	 * with `urlBase`, and the collection is flat. Until a page holds it, its documents have no
+	 * addresses (`caracms validate` says why).
+	 */
+	heldBy?: string;
 	/** Every document's fields, in the form's order. `title` is every document's own, so it can't be one of them. */
 	fields: F;
 	/**
@@ -267,8 +285,14 @@ export interface ResolvedCollection {
 	folder: string;
 	/** Absolute. */
 	dir: string;
-	/** Always starts and ends with `/`. Null for the reserved collections, and a fields collection with no pages of its own (M6c G1). */
+	/**
+	 * Always starts and ends with `/`. Null for the reserved collections, and a fields collection with no pages of its own (M6c G1).
+	 * A held collection's (`heldBy`) is null here, in the config, and its holder's address + `/` once a listing resolves it
+	 * (held.ts → withHeldBases); every caller that has a listing uses the resolved one.
+	 */
 	urlBase: string | null;
+	/** Collections under pages (Decision 2): the nested section builder whose page holds this collection; absent when none does. */
+	heldBy?: string;
 	nested: boolean;
 	/**
 	 * A fields collection's fields (labelled); a section builder's page fields (M6c G2,
@@ -347,6 +371,12 @@ export interface ResolvedSite {
 	 * integration at setup (and by the commands). Absent before then: nothing is reserved.
 	 */
 	codeRoutes?: CodeRoute[];
+	/**
+	 * Collections under pages (Decision 14): every route in `src/pages/`, the collections' own
+	 * included, read with `codeRoutes`. The catch-all's reader (content.ts → addressedDocuments)
+	 * leaves out a prefix collection with its own route, and logs a route left at a held base.
+	 */
+	pageRoutes?: CodeRoute[];
 }
 
 export class CaracmsConfigError extends Error {
@@ -419,12 +449,20 @@ export function resolveSite(config: SiteConfig, root: string): ResolvedSite {
 		if (c.kind !== 'sections' && c.kind !== 'fields') fail(`collection "${name}": kind must be 'sections' or 'fields' (got ${JSON.stringify((c as { kind?: unknown }).kind)}).`);
 		if (!c.folder) fail(`collection "${name}": folder is required.`);
 		const dir = claimFolder(name, c.folder);
+		// Collections under pages (Decision 2): a page holds it, so its address comes from the content, never a urlBase too.
+		const heldBy = (c as { heldBy?: unknown }).heldBy;
+		if (heldBy !== undefined) {
+			if (typeof heldBy !== 'string' || heldBy === '') fail(`collection "${name}": heldBy must name the collection whose page holds it, like 'pages'.`);
+			if (c.urlBase !== undefined) fail(`collection "${name}": it has both urlBase ('${c.urlBase}') and heldBy ('${heldBy}'). Its address comes from one: a prefix in code (urlBase) or the page that holds it (heldBy). Take one out.`);
+			if ((c as { nested?: unknown }).nested) fail(`collection "${name}": a collection a page holds is flat (its documents are at the page's address + their slug), so it can't be "nested".`);
+		}
 		// M6c (G1): a list-of-fields collection may have no pages of its own (no urlBase).
-		const pageless = c.kind === 'fields' && c.urlBase === undefined;
-		if (!pageless && (typeof c.urlBase !== 'string' || !c.urlBase.startsWith('/'))) {
-			fail(c.urlBase === undefined ? `collection "${name}": a section builder needs a urlBase, like '/' or '/journal/' (its documents are pages there).` : `collection "${name}": urlBase must start with "/".`);
+		const pageless = c.kind === 'fields' && c.urlBase === undefined && heldBy === undefined;
+		if (!pageless && heldBy === undefined && (typeof c.urlBase !== 'string' || !c.urlBase.startsWith('/'))) {
+			fail(c.urlBase === undefined ? `collection "${name}": a section builder needs a urlBase, like '/' or '/tags/', or heldBy: 'pages' when a page holds it (its documents are pages there).` : `collection "${name}": urlBase must start with "/".`);
 		}
-		const urlBase = pageless ? null : c.urlBase!.endsWith('/') ? c.urlBase! : `${c.urlBase}/`;
+		const urlBase = pageless || heldBy !== undefined ? null : c.urlBase!.endsWith('/') ? c.urlBase! : `${c.urlBase}/`;
+		const held = heldBy !== undefined ? { heldBy: heldBy as string } : {};
 		const label = c.label ?? titleCase(name);
 		if (c.kind === 'fields') {
 			if ((c as { nested?: unknown }).nested) fail(`collection "${name}": a list-of-fields collection is flat (one level of slugs under its urlBase); "nested" is for section builders.`);
@@ -432,7 +470,7 @@ export function resolveSite(config: SiteConfig, root: string): ResolvedSite {
 			mustExist(c.component, `collection "${name}": component`);
 			if (!c.fields || typeof c.fields !== 'object') fail(`collection "${name}": fields is required.`);
 			fieldsCollections.push([name, c]);
-			collections[name] = { name, label, kind: 'fields', folder: c.folder, dir, urlBase, nested: false, fields: {}, component: abs(c.component), columns: null };
+			collections[name] = { name, label, kind: 'fields', folder: c.folder, dir, urlBase, ...held, nested: false, fields: {}, component: abs(c.component), columns: null };
 		} else {
 			if (c.columns !== undefined && c.nested) fail(`collection "${name}": columns are for the editor's table of a flat collection; a nested one (Pages) is a tree.`);
 			if (c.sort !== undefined && c.nested) fail(`collection "${name}": sort is for the editor's table of a flat collection; a nested one (Pages) is a tree.`);
@@ -441,10 +479,16 @@ export function resolveSite(config: SiteConfig, root: string): ResolvedSite {
 				if (!c.fields || typeof c.fields !== 'object' || Array.isArray(c.fields)) fail(`collection "${name}": fields must be an object of fields, like { side: select({ options: ['left', 'right'] }) }.`);
 				pageFieldCollections.push([name, c.fields]);
 			}
-			collections[name] = { name, label, kind: 'sections', folder: c.folder, dir, urlBase, nested: c.nested ?? false, fields: null, component: null, columns: null };
+			collections[name] = { name, label, kind: 'sections', folder: c.folder, dir, urlBase, ...held, nested: c.nested ?? false, fields: null, component: null, columns: null };
 		}
 	}
 	if (Object.keys(collections).length === 0) fail('declare at least one collection.');
+	// Decision 6: a holder is a page of a nested section builder (Pages), whose slugs are addresses.
+	for (const c of Object.values(collections)) {
+		if (c.heldBy === undefined) continue;
+		const by = Object.hasOwn(collections, c.heldBy) ? collections[c.heldBy]! : fail(`collection "${c.name}": heldBy names "${c.heldBy}", which isn't one of the site's collections (${Object.keys(collections).join(', ')}).`);
+		if (by.kind !== 'sections' || !by.nested || by.urlBase === null) fail(`collection "${c.name}": heldBy names "${c.heldBy}", which isn't a nested section builder (like Pages), so none of its documents can hold a collection.`);
+	}
 	const ownCollections = { ...collections };
 
 	const settingsFolder = SITE_SETTINGS_FILE.slice(0, SITE_SETTINGS_FILE.lastIndexOf('/'));
@@ -475,8 +519,10 @@ export function resolveSite(config: SiteConfig, root: string): ResolvedSite {
 			validateField(field, `${where}: field "${key}"`, fieldCheck(where));
 		}
 		const columns = checkColumns(where, c.columns, c.fields, fail);
-		if (c.urlBase === undefined && columns?.includes('address')) fail(`${where}: its documents have no pages of their own (no urlBase), so there's no 'address' column.`);
-		const sort = checkSort(where, c.sort, columns ?? DEFAULT_COLUMNS.filter((k) => k !== 'address' || c.urlBase !== undefined), c.fields, fail);
+		// A held collection (heldBy) has addresses too, once a page holds it (Contracts → Config).
+		const addressed = c.urlBase !== undefined || c.heldBy !== undefined;
+		if (!addressed && columns?.includes('address')) fail(`${where}: its documents have no pages of their own (no urlBase), so there's no 'address' column.`);
+		const sort = checkSort(where, c.sort, columns ?? DEFAULT_COLUMNS.filter((k) => k !== 'address' || addressed), c.fields, fail);
 		collections[name] = { ...collections[name]!, fields: withLabels(c.fields), columns, sort };
 	}
 	// M6c (G2): a section builder's page fields, beside `title`, `blocks` and `seo` in the file.

package/src/content-schema.ts

@@ -126,13 +126,16 @@ function document(collection: ResolvedCollection, properties: Record<string, Sch
 }
 
 /** A collection's schema (`schemas/<collection>.schema.json`, or the reserved two's names). */
-export function collectionSchema(site: Pick<ResolvedSite, 'blocks'>, collection: ResolvedCollection): Schema {
+export function collectionSchema(site: Pick<ResolvedSite, 'blocks'> & Partial<Pick<ResolvedSite, 'collections'>>, collection: ResolvedCollection): Schema {
 	const own = Object.fromEntries(Object.entries(collection.fields ?? {}).map(([key, f]) => [key, fieldSchema(f)]));
 	switch (collection.kind) {
 		case 'sections':
 			// M9 Decision 7: `hidden: true` keeps the page off the site; absent, it's shown.
 			const hidden: Schema = { description: 'Hidden from the site: not served, not in the sitemap, still edited in /admin.', const: true };
-			return document(collection, { hidden, ...own, blocks: { type: 'array', items: { anyOf: [{ $ref: '#/$defs/shared' }, anyBlock(site)] } }, seo }, ['title', 'blocks'], { shared: sharedEntry, ...blockDefs(site) });
+			// Collections under pages (Decision 5): a page of a collection some collection's heldBy names may hold one of them.
+			const holdable = Object.values(site.collections ?? {}).filter((c) => c.heldBy === collection.name).map((c) => c.name);
+			const holds: Schema | null = holdable.length ? { description: 'The collection this page holds: its documents are at this page\'s address + their slug.', enum: holdable } : null;
+			return document(collection, { hidden, ...(holds ? { holds } : {}), ...own, blocks: { type: 'array', items: { anyOf: [{ $ref: '#/$defs/shared' }, anyBlock(site)] } }, seo }, ['title', 'blocks'], { shared: sharedEntry, ...blockDefs(site) });
 		case 'fields':
 			return document(collection, { ...own, seo }, ['title']);
 		case 'shared':
@@ -147,6 +150,7 @@ export function collectionSchema(site: Pick<ResolvedSite, 'blocks'>, collection:
 					googleTag: string,
 					formRecipients: { type: 'object', additionalProperties: strings },
 					redirects: { type: 'array', items: closed({ from: string, to: string }, ['from', 'to']) },
+					pageOrder: { type: 'object', additionalProperties: strings, description: "The Pages tree's order in the editor: a parent's path (\"\" for the top level) → its children's slugs. Written by Arrange pages." },
 					...own,
 				},
 				['title'],