caracms 0.3.4 → 0.4.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';
@@ -308,9 +309,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 +320,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', '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)}.`);
@@ -354,6 +359,23 @@ function checkDocument(c: Context, collection: ResolvedCollection, raw: unknown)
 	}
 }
 
+/** 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 +395,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 +436,17 @@ 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);
 		}
 	}
 

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':

package/src/content.ts

@@ -36,6 +36,9 @@ import { isBuiltInColumn } from './columns.ts';
 import { fieldsCover, sectionsCover, type CardCover } from './cards.ts';
 import { own, parseAnyDocument, type AnyDocument, type DocumentKind } from './document.ts';
 import { parseSource } from './json-source.ts';
+import { hasHeld, heldBases, type HeldBase } from './held.ts';
+import { leftBehindMessage, leftBehindRoutes, ownRoutedCollections } from './code-routes.ts';
+import { sameAddress } from './slug.ts';
 
 // Posts and tags, Decision 14: a route's reader on the disk (read.ts).
 export { contentReader } from './read.ts';
@@ -79,6 +82,16 @@ export interface DocumentEntry {
 	 */
 	hidden?: true;
 	hiddenBy?: string;
+	/**
+	 * Collections under pages (Decision 11): set when `hiddenBy` is a page of another collection,
+	 * the page that holds this document's collection (`pages`). Absent: `hiddenBy` is in this one.
+	 */
+	hiddenByCollection?: string;
+	/**
+	 * Collections under pages (Decision 5): a page's `"holds"`, the collection it holds (held.ts).
+	 * Read from a file that can't be opened too, as far as it can be, so a broken holder is named.
+	 */
+	holds?: string;
 	/** A section builder's shared-block entries, by shared block path, in block order, once each (Decision 8). Absent otherwise. */
 	uses?: string[];
 	/** A shared block: its block's type (`''` when it has none). Absent otherwise. */
@@ -220,13 +233,17 @@ export function resolveDocumentFile(site: Pick<ResolvedSite, 'collections'>, col
 	return file;
 }
 
-/** Every document in one collection, or in all of them (in config order), with warnings, in the editor's order. */
+/**
+ * Every document in one collection, in several (in the order given), or in all of them (in
+ * config order), with warnings, in the editor's order. A held collection's documents have
+ * their resolved addresses (held.ts), whichever collections are listed.
+ */
 export async function listDocuments(
 	site: Pick<ResolvedSite, 'collections' | 'root' | 'blocks'>,
-	collectionName?: string,
+	collectionName?: string | readonly string[],
 	source: ContentSource = diskSource,
 ): Promise<DocumentEntry[]> {
-	const names = collectionName ? [collectionName] : Object.keys(site.collections);
+	const names = collectionName === undefined ? Object.keys(site.collections) : typeof collectionName === 'string' ? [collectionName] : [...collectionName];
 	const all: DocumentEntry[] = [];
 	for (const name of names) {
 		const collection = own(site.collections, name);
@@ -236,7 +253,20 @@ export async function listDocuments(
 		if (collection.nested) hideChildren(entries);
 		all.push(...(collection.nested ? flattenTree(pageTree(entries)) : entries.sort(byLabel)));
 	}
-	if (!collectionName) {
+	// Collections under pages (Decision 7): a held collection's addresses come from its holder's listing.
+	const held = names.map((n) => site.collections[n]!).filter((c) => c.heldBy);
+	if (held.length) {
+		const holding: DocumentEntry[] = [];
+		for (const by of new Set(held.map((c) => c.heldBy!))) {
+			holding.push(...(names.includes(by) ? all.filter((e) => e.collection === by) : await listDocuments(site, by, source)));
+		}
+		const bases = heldBases(site.collections, holding);
+		for (const entry of all) {
+			const base = own(bases, entry.collection);
+			if (base) placeHeld(entry, base);
+		}
+	}
+	if (collectionName === undefined) {
 		// Decision 8's "used on": every document whose block list has an entry for the shared block.
 		for (const entry of all) {
 			if (entry.kind !== 'shared') continue;
@@ -246,6 +276,44 @@ export async function listDocuments(
 	return all;
 }
 
+/** A held document's address and hidden mark from its collection's resolved base (held.ts). */
+function placeHeld(entry: DocumentEntry, held: HeldBase): void {
+	entry.url = held.base === null ? null : held.base + entry.path;
+	// Decision 11: a hidden holder hides its documents, as a hidden page hides the pages under it.
+	if (held.hidden && held.holder) {
+		entry.hidden = true;
+		entry.hiddenBy = held.holder.path;
+		entry.hiddenByCollection = held.holder.collection;
+	}
+}
+
+/** A held collection's resolved base, from its holder collection's listing through `source`. */
+export async function heldBaseOf(site: Pick<ResolvedSite, 'collections' | 'root' | 'blocks'>, collectionName: string, source: ContentSource = diskSource): Promise<HeldBase | null> {
+	const collection = own(site.collections, collectionName);
+	if (!collection?.heldBy) return null;
+	return heldBases({ [collection.name]: collection }, await listDocuments(site, collection.heldBy, source))[collection.name] ?? null;
+}
+
+/** Every held collection's resolved base (held.ts), from the listings of the collections that hold them; `{}` on a site with none. */
+export async function heldBasesOf(site: Pick<ResolvedSite, 'collections' | 'root' | 'blocks'>, source: ContentSource = diskSource): Promise<Record<string, HeldBase>> {
+	if (!hasHeld(site.collections)) return {};
+	const by = [...new Set(Object.values(site.collections).flatMap((c) => (c.heldBy ? [c.heldBy] : [])))];
+	const holding = (await Promise.all(by.map((name) => listDocuments(site, name, source)))).flat();
+	return heldBases(site.collections, holding);
+}
+
+/**
+ * A document's public address as its listing gives it: `documentUrl` for a collection with a
+ * prefix, the holder's address + `/` + the path for a held one (null while it isn't held).
+ */
+export async function documentAddress(site: Pick<ResolvedSite, 'collections' | 'root' | 'blocks'>, collectionName: string, path: string, source: ContentSource = diskSource): Promise<string | null> {
+	const collection = own(site.collections, collectionName);
+	if (!collection) return null;
+	if (!collection.heldBy) return documentUrl(collection, path);
+	const held = await heldBaseOf(site, collectionName, source);
+	return held?.base ? held.base + path : null;
+}
+
 /** M9 Decision 7: a hidden page's children are hidden with it; `hiddenBy` names the topmost hidden page above. */
 function hideChildren(entries: DocumentEntry[]): void {
 	const hidden = new Set(entries.filter((e) => e.hidden).map((e) => e.path));
@@ -279,6 +347,10 @@ export async function readDocument(
 	if (text === null) throw new DocumentError('not-found', `${collection.label}: no document "${path}".`);
 	const { entry, document } = inspect(site, collection, path, text);
 	if (entry.warning || !document) throw new DocumentError(entry.warning!.code, entry.warning!.message);
+	if (collection.heldBy) {
+		const held = await heldBaseOf(site, collection.name, source);
+		if (held) placeHeld(entry, held);
+	}
 	return { entry, text, document };
 }
 
@@ -312,10 +384,12 @@ function inspect(
 		url: documentUrl(collection, path),
 	};
 	const fileLabel = titleCase(path.split('/').pop()!);
-	const warn = (code: WarningCode, message: string, title = '') => ({
-		entry: { ...base, title, label: title || fileLabel, warning: { code, message } },
-		document: null,
-	});
+	// Decision 13: a broken holder is named, so its `"holds"` is read from the text as far as it can be.
+	const holdsIn = () => (collection.kind === 'sections' ? /"holds"\s*:\s*"([^"\\]*)"/.exec(text)?.[1] : undefined);
+	const warn = (code: WarningCode, message: string, title = '') => {
+		const holds = holdsIn();
+		return { entry: { ...base, title, label: title || fileLabel, warning: { code, message }, ...(holds !== undefined ? { holds } : {}) }, document: null };
+	};
 
 	if (collection.nested && path.endsWith('/index')) {
 		const parent = path.slice(0, -'/index'.length);
@@ -336,6 +410,7 @@ function inspect(
 	const entry: DocumentEntry = { ...base, title, label: title, warning: null };
 	// M9 Decision 7: the home page is never hidden.
 	if ((document.kind === undefined || document.kind === 'sections') && document.hidden && path !== 'index') entry.hidden = true;
+	if ((document.kind === undefined || document.kind === 'sections') && document.holds !== undefined) entry.holds = document.holds;
 	if (document.kind === undefined || document.kind === 'sections') {
 		entry.uses = [...new Set(document.blocks.flatMap((b) => (b.shared !== undefined ? [b.shared] : [])))];
 	} else if (document.kind === 'shared') {
@@ -422,3 +497,68 @@ const collator = new Intl.Collator('en', { sensitivity: 'base', numeric: true })
 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);
 }
+
+// ── The catch-all's reader (collections under pages, Decision 14) ────────────────
+
+/** A public page the site's catch-all serves: its collection, its path there, and its address. */
+export interface AddressedDocument {
+	collection: string;
+	path: string;
+	/** `/`, `/about`, `/journal/a-day-on-the-ferry`: no trailing slash, as the listing gives it. */
+	url: string;
+}
+
+/** What the reader reads: the site, and the routes in its `src/pages/` (the integration sets `pageRoutes`). */
+type CatchAllSite = Pick<ResolvedSite, 'collections' | 'root' | 'blocks'> & Partial<Pick<ResolvedSite, 'pageRoutes'>>;
+
+const logged = new Set<string>();
+/** The build's and dev's log, once per sentence per process (Decision 13: logged, never a failed build). */
+function logOnce(message: string): void {
+	if (logged.has(message)) return;
+	logged.add(message);
+	console.warn(`[caracms] ${message}`);
+}
+
+/**
+ * Every public page of every collection with an address, for the site's one catch-all route
+ * (`src/pages/[...path].astro`'s `getStaticPaths`): Pages, every held collection's documents at
+ * their holder's address, and every prefix collection's (`/tags/<slug>`), in config order then
+ * the editor's. Left out: a file that can't be opened, a hidden page (and the documents of a
+ * hidden holder), a held collection no page holds, and a prefix collection whose base has its
+ * own route (`src/pages/tags/[slug].astro`), which that route serves. A holder problem or a
+ * route left at a held base is logged once (`caracms validate` reports both as errors).
+ * `source`: where the files come from (the disk by default, as a build reads them).
+ */
+export async function addressedDocuments(site: CatchAllSite, source: ContentSource = diskSource): Promise<AddressedDocument[]> {
+	const collections = Object.values(site.collections);
+	const routes = site.pageRoutes ?? [];
+	const ownRouted = new Set(ownRoutedCollections(routes, collections).map((c) => c.name));
+	const names = collections.filter((c) => (c.urlBase !== null || c.heldBy) && !ownRouted.has(c.name)).map((c) => c.name);
+	const entries = await listDocuments(site, names, source);
+	if (hasHeld(site.collections)) {
+		const held: { name: string; label: string; base: string; holder: string }[] = [];
+		for (const base of Object.values(await heldBasesOf(site, source))) {
+			if (base.problem) logOnce(base.problem);
+			const c = site.collections[base.collection]!;
+			if (base.base && base.holder) held.push({ name: c.name, label: c.label, base: base.base, holder: base.holder.label });
+		}
+		for (const left of leftBehindRoutes(routes, held)) logOnce(leftBehindMessage(left));
+	}
+	return entries.filter((e): e is DocumentEntry & { url: string } => e.url !== null && !e.warning && !e.hidden).map(({ collection, path, url }) => ({ collection, path, url }));
+}
+
+/**
+ * The document a request's path is (`/journal/a-day-on-the-ferry`, with or without a trailing
+ * slash, URL-encoded or not), for a catch-all that renders on demand; null when no public page
+ * is there (`addressedDocuments` says which are).
+ */
+export async function documentAt(site: CatchAllSite, pathname: string, source: ContentSource = diskSource): Promise<{ collection: string; path: string } | null> {
+	let at: string;
+	try {
+		at = sameAddress(decodeURIComponent(pathname));
+	} catch {
+		return null;
+	}
+	const found = (await addressedDocuments(site, source)).find((d) => sameAddress(d.url) === at);
+	return found ? { collection: found.collection, path: found.path } : null;
+}

package/src/document.ts

@@ -67,6 +67,13 @@ export interface SiteDocument {
 	 * the key out of the file. The home page (`index`) can't be hidden (content.ts reads it as shown).
 	 */
 	hidden?: boolean;
+	/**
+	 * Collections under pages (Decision 5): the collection this page holds (the file's
+	 * top-level `"holds"`, after `title` and `hidden`): its documents are at this page's
+	 * address + `/` + their slug (held.ts). Edited in the file only, never by the editor,
+	 * whose saves keep it where it is.
+	 */
+	holds?: string;
 	/**
 	 * M6c (G2): the page fields' parsed values, keyed by field, every field of the
 	 * collection's `fields` present (the file's top-level keys after `title`). Present
@@ -225,6 +232,7 @@ export function parseDocument(raw: unknown, site: Pick<ResolvedSite, 'blocks'>):
 		blocks: rawBlocks.map((b, index) => parseBlock(b, index, site)),
 		...seoOf(doc),
 		...(doc.hidden === true ? { hidden: true } : {}),
+		...(typeof doc.holds === 'string' ? { holds: doc.holds } : {}),
 	};
 }