caracms 0.1.0 → 0.2.0

package/src/block-runs.ts

@@ -0,0 +1,84 @@
+/**
+ * Runs of blocks (M9 Decision 9): the page component tells `<Blocks>` which neighbouring
+ * blocks go together and what's drawn round them, such as a band holding cards, each card
+ * holding several blocks (a Tina template's About page).
+ *
+ *   <Blocks document={document} collection={collection} preview={preview} wrap={cardRuns} />
+ *
+ *   // The page component's own rule, from the blocks' data:
+ *   const cardRuns: WrapBlocks = (blocks) => …[{ from: 2, to: 6, component: Band, runs: [
+ *     { from: 2, to: 4, component: Card, props: { id: 'story' } },
+ *     { from: 5, to: 6, component: Card, props: { id: 'team' } },
+ *   ] }];
+ *
+ * - `wrap` gets the blocks that render, in order: each one's document index, type and render
+ *   data (what its component gets as `block`), so the rule can read a field (`card`, `anchor`).
+ * - A run is `from`..`to`, document indices, inclusive: everything between renders inside it,
+ *   a skipped block's preview marker included. Its `component` is drawn round the run with
+ *   `props`, the blocks in its default slot. `runs` are runs inside it (the cards in a band),
+ *   each within it.
+ * - Runs are in order and don't overlap. A rule that breaks that is a mistake in the site's
+ *   code, so the render stops with a sentence saying which runs.
+ * - Nothing about each block changes: its index, its context (`index`, `first`, `h1Field`,
+ *   `eager`), its markers in a preview, so it's selected, typed into and morphed there as
+ *   anywhere else. A wrapper carries no markers: it's the site's markup.
+ */
+
+/** A block as `wrap` sees it. */
+export interface WrapBlock {
+	/** Its index in the document (the editor's index, `cms.index`). */
+	index: number;
+	type: string;
+	/** Its render data: what its component gets as `block`. */
+	data: Record<string, unknown>;
+}
+
+/** A run of blocks and what's drawn round it. */
+export interface BlockRun {
+	/** The first block's document index. */
+	from: number;
+	/** The last block's document index (inclusive). */
+	to: number;
+	/** An Astro component (or any component Astro renders): the run goes in its default slot. */
+	component: unknown;
+	props?: Record<string, unknown>;
+	/** Runs inside this one, each within `from`..`to`. */
+	runs?: readonly BlockRun[];
+}
+
+/** The page component's rule: the runs, from the blocks that render. */
+export type WrapBlocks = (blocks: readonly WrapBlock[]) => readonly BlockRun[];
+
+/** What `<Blocks>` draws, as a tree: an entry (by document index), or a run holding more. */
+export type RunNode = { kind: 'entry'; index: number } | { kind: 'run'; component: unknown; props: Record<string, unknown>; children: RunNode[] };
+
+const named = (run: BlockRun) => `the run ${run.from}–${run.to}`;
+
+/**
+ * The document's entries (`indices`, in order: every block the render has an entry for)
+ * grouped by `runs`. Throws on runs out of order, overlapping, outside their parent, or
+ * with `from` after `to`.
+ */
+export function runTree(indices: readonly number[], runs: readonly BlockRun[]): RunNode[] {
+	const place = (within: readonly number[], level: readonly BlockRun[], parent: BlockRun | null): RunNode[] => {
+		let previous: BlockRun | null = null;
+		for (const run of level) {
+			if (!Number.isInteger(run.from) || !Number.isInteger(run.to) || run.from > run.to) throw new Error(`<Blocks wrap>: ${named(run)} needs whole-number indices with from at or before to.`);
+			if (!run.component) throw new Error(`<Blocks wrap>: ${named(run)} has no component to draw round it.`);
+			if (previous && run.from <= previous.to) throw new Error(`<Blocks wrap>: ${named(run)} starts before ${named(previous)} ends. Runs are in document order and don't overlap.`);
+			if (parent && (run.from < parent.from || run.to > parent.to)) throw new Error(`<Blocks wrap>: ${named(run)} isn't inside ${named(parent)}, which holds it.`);
+			previous = run;
+		}
+		const out: RunNode[] = [];
+		let i = 0;
+		for (const run of level) {
+			while (i < within.length && within[i]! < run.from) out.push({ kind: 'entry', index: within[i++]! });
+			const inside: number[] = [];
+			while (i < within.length && within[i]! <= run.to) inside.push(within[i++]!);
+			out.push({ kind: 'run', component: run.component, props: run.props ?? {}, children: place(inside, run.runs ?? [], run) });
+		}
+		while (i < within.length) out.push({ kind: 'entry', index: within[i++]! });
+		return out;
+	};
+	return place(indices, runs, null);
+}

package/src/cli/validate.ts

@@ -28,13 +28,14 @@ import { codeRouteAt, codeRouteMessage, shadowingMessage, shadowingRoutes, type
 import { pagesRoutes, readCodeRoutes, srcDirOf } from '../code-routes-disk.ts';
 import { listDocuments, type DocumentEntry } from '../content.ts';
 import { own } from '../document.ts';
-import { fieldWarnings, parseDay, type Field, type Fields, type WarningContext } from '../fields.ts';
+import { fieldWarnings, parseDay, richTextOptions, type Field, type Fields, type WarningContext } from '../fields.ts';
 import { measureLockup } from '../measure.ts';
 import { isFileKey } from '../files.ts';
 import { readRichText } from '../rich-text.ts';
 import { savedForm } from '../serialize.ts';
 import { SCHEMA_KEY, schemaRef } from '../schema-key.ts';
 import { sameAddress } from '../slug.ts';
+import { hiddenDocuments, hiddenPages } from '../links.ts';
 import { runSchemas, schemaFileChanges, schemasReport } from './schemas.ts';
 import { jsonFilesUnder, loadSite } from './site.ts';
 
@@ -133,7 +134,7 @@ function checkValue(c: Context, field: Field, raw: unknown, path: string, inList
 		case 'richText': {
 			if (typeof raw !== 'string' && !Array.isArray(raw)) return wrong('rich text: a list of { "p": "…" } entries, or a string');
 			// The grammar (rich-text.ts): what the reader couldn't read is lost on the next save.
-			const { issues } = readRichText(raw, { headings: field.headings, links: field.links });
+			const { issues } = readRichText(raw, richTextOptions(field));
 			for (const issue of issues) {
 				if (issue.code !== 'unreadable') continue;
 				const allowed = ['p', ...field.headings, 'ul', 'ol'];
@@ -270,7 +271,7 @@ function editorWarnings(c: Context, field: Field, raw: unknown, path: string) {
 		const p = fromDotted(path, w.path);
 		if (w.code === 'unreadable' || w.code === 'missing-reference') continue;
 		// Rich text outside the field's grammar (an h1, a heading or a link the field doesn't take) is an error: Decision 15.
-		if (w.code === 'disallowed-kind' || w.code === 'link-off') error(c, p, w.message);
+		if (w.code === 'disallowed-kind' || w.code === 'link-off' || w.code === 'italic-off') error(c, p, w.message);
 		else warning(c, p, w.message);
 	}
 }
@@ -307,7 +308,9 @@ 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', 'blocks', 'seo']);
+			checkFields(c, own, raw, '', `a ${collection.label} page`, 0, [SCHEMA_KEY, 'title', 'hidden', '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 (!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));
@@ -357,7 +360,7 @@ export async function validateSite(site: Site, codeRoutes: readonly CodeRoute[]
 	const entries = await listDocuments(site);
 	const ids = new Set(entries.map((e) => `${e.collection}\0${e.path}`));
 	const exists = (collection: string, path: string) => ids.has(`${collection}\0${path}`);
-	const warningContext: WarningContext = { addresses: entries.map((e) => e.url), documentExists: exists, codeRoutes };
+	const warningContext: WarningContext = { addresses: entries.map((e) => e.url), documentExists: exists, codeRoutes, hiddenPages: hiddenPages(entries), hiddenDocuments: hiddenDocuments(entries) };
 
 	// Files in no collection: under content/ and every collection's folder.
 	const listed = new Set(entries.map((e) => e.file));
@@ -391,6 +394,8 @@ export async function validateSite(site: Site, codeRoutes: readonly CodeRoute[]
 		}
 		const raw = JSON.parse(text) as unknown;
 		checkDocument(c, collection, raw);
+		// M9 Decision 7: as in Tina, the home page can't be hidden (content.ts reads it as shown).
+		if (collection.kind === 'sections' && entry.path === 'index' && isObject(raw) && raw.hidden === true) warning(c, 'hidden', 'The home page can’t be hidden, so it’s shown. Remove "hidden".');
 		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);

package/src/components/BlockRunTree.astro

@@ -0,0 +1,45 @@
+---
+/**
+ * `<Blocks>`'s own renderer for runs of blocks (M9 Decision 9; block-runs.ts): each entry
+ * as `<Blocks>` draws it (the block's component, or a skipped block's preview marker), and
+ * each run as its component round its own entries and runs, recursively. Internal: a site
+ * uses `<Blocks wrap={…}>`.
+ */
+import type { RunNode } from '../block-runs.ts';
+import type { BlockContext } from '../document.ts';
+import { skippedMarker } from '../skipped.ts';
+
+export interface RunItem {
+	Component: ((props: any) => any) | undefined;
+	data: Record<string, unknown> | null;
+	cms: BlockContext | null;
+	skipped: { type: string; shared?: string } | null;
+}
+
+interface Props {
+	nodes: RunNode[];
+	items: ReadonlyMap<number, RunItem>;
+	preview: boolean;
+}
+
+const { nodes, items, preview } = Astro.props;
+---
+
+{
+	nodes.map((node) => {
+		if (node.kind === 'run') {
+			const Wrapper = node.component as (props: any) => any;
+			return (
+				<Wrapper {...node.props}>
+					<Astro.self nodes={node.children} items={items} preview={preview} />
+				</Wrapper>
+			);
+		}
+		const item = items.get(node.index);
+		if (!item) return null;
+		const { Component, data, cms, skipped } = item;
+		if (Component && cms) return <Component block={data} cms={cms} />;
+		// As in Blocks.astro: a comment, so the site's sibling CSS matches across it.
+		return preview && skipped ? <Fragment set:html={skippedMarker(node.index, skipped)} /> : null;
+	})
+}

package/src/components/Blocks.astro

@@ -37,6 +37,12 @@
  *   component passes on the `listPage` it gets, 1 when it doesn't).
  * - The context is computed here, per render, and passed down as props: no module
  *   state, so concurrent preview renders can't leak into each other.
+ * - **Runs of blocks** (M9 Decision 9): `wrap` is the page component's rule for which
+ *   neighbouring blocks go together and what's drawn round them (a band of cards, each
+ *   card several blocks). It gets the blocks that render (`{ index, type, data }`) and
+ *   returns runs, `{ from, to, component, props?, runs? }` (block-runs.ts). Each block in a
+ *   run keeps its index, context, markers, selection and morph, exactly as outside one.
+ *   A section builder's (or a shared block's) blocks only.
  */
 import { blocks } from 'virtual:caracms/blocks';
 import { components } from 'virtual:caracms/collections';
@@ -45,6 +51,8 @@ import { blockContexts, documentKind, fieldsHeading, own, type BlockContext, typ
 import { firstImagePath } from '../fields.ts';
 import { documentReader, renderFields, renderSourceOf, resolveShared } from '../read.ts';
 import { skippedMarker } from '../skipped.ts';
+import { runTree, type RunNode, type WrapBlocks } from '../block-runs.ts';
+import BlockRunTree from './BlockRunTree.astro';
 
 interface Props {
 	document: PageDocument;
@@ -53,9 +61,11 @@ interface Props {
 	preview?: boolean;
 	/** Posts and tags, Decision 12: the page of a paged listing (the page component's `listPage`); 1 by default. */
 	listPage?: number;
+	/** M9 Decision 9: which runs of blocks go together, and what's drawn round each (block-runs.ts). */
+	wrap?: WrapBlocks;
 }
 
-const { document, collection, preview = false } = Astro.props;
+const { document, collection, preview = false, wrap } = Astro.props;
 // A preview is always page 1; anything that isn't a whole number from 1 reads as 1.
 const listPage = !preview && Number.isInteger(Astro.props.listPage) && Astro.props.listPage! >= 1 ? Astro.props.listPage! : 1;
 const read = documentReader(site, renderSourceOf(Astro.locals));
@@ -71,6 +81,7 @@ interface Item {
 let items: Item[] = [];
 let empty = false;
 let body: { Component: (props: any) => any; props: Record<string, unknown> } | null = null;
+let tree: RunNode[] | null = null;
 
 if (kind === 'fields') {
 	const c = collection ? own(site.collections, collection) : undefined;
@@ -106,11 +117,19 @@ if (kind === 'fields') {
 		}),
 	);
 	empty = page.blocks.length === 0;
+	if (wrap) {
+		const rendered = items.filter((it) => it.Component && it.cms).map((it) => ({ index: it.index, type: it.cms!.type, data: it.data! }));
+		const runs = wrap(rendered);
+		if (runs.length) tree = runTree(items.map((it) => it.index), runs);
+	}
 }
+const byIndex = new Map(items.map((it) => [it.index, it]));
 ---
 
 {body && <body.Component {...body.props} />}
+{tree && <BlockRunTree nodes={tree} items={byIndex} preview={preview} />}
 {
+	!tree &&
 	items.map(({ index, Component, data, cms, skipped }) => {
 		if (Component && cms) return <Component block={data} cms={cms} />;
 		// A comment, not an element: the site's sibling CSS (`+`, `:has(+ …)`) matches across it as on the public page.

package/src/components/Form.astro

@@ -24,10 +24,30 @@
  * editor can send it, and a click falls through to the block.
  *
  * An id that isn't one of the site's forms renders nothing (and says so in a preview).
+ *
+ * **A site that draws its own look** (M9 port friction 10) has these hooks, each optional;
+ * left out, the form renders exactly as above:
+ *
+ * - `class` and any other attribute (`data-*`, `id`, `aria-*`…) go on the `<form>`;
+ *   the ones the form sets itself (`action`, `method`, `enctype`, `inert`, its own
+ *   `data-caracms-*`, `data-max-*`, `data-file-kinds`, `data-thanks`, `data-failed`) can't be replaced;
+ * - `submitClass`: classes on the submit button, beside `cms-form-submit`;
+ * - `thanks`: the line after a send (default "Thanks, we'll be in touch shortly.");
+ *   `failed`: the line when a send fails without the endpoint's own sentence
+ *   (default "Something went wrong. Please email us directly.");
+ * - `errors`: the error line by field type (`{ email: 'Please check your email.' }`),
+ *   in place of the package's wording; a field's own `error` in the config still wins;
+ * - `actions`: wrap the submit button and the status line in `<div class="cms-form-actions">`,
+ *   so site CSS can lay them out in a row;
+ * - `labelPlaceholders`: a text, email, tel or textarea field with no `placeholder` of its
+ *   own uses its label as one (the `<label>` stays in the markup).
+ *
+ * A textarea's height is its field's `rows` in the config (default 6).
  */
 import { site } from 'virtual:caracms/config';
 import { build } from 'virtual:caracms/public';
-import { cleanReturn, FILE_ACCEPT, FILE_KINDS, HONEYPOT, MAX_FILE_BYTES, MAX_FILES, type ResolvedFormField } from '../forms/rules.ts';
+import { cleanReturn, FILE_ACCEPT, FILE_KINDS, HONEYPOT, MAX_FILE_BYTES, MAX_FILES, PLACEHOLDER_TYPES, type FormFieldType, type ResolvedFormField } from '../forms/rules.ts';
+import { passThrough } from './attributes.ts';
 
 interface Props {
 	/** The form's id in the site's config. */
@@ -36,10 +56,40 @@ interface Props {
 	preview?: boolean;
 	/** The submit button's text. Default "Send". */
 	submit?: string;
+	/** Classes on the `<form>`, beside `cms-form`. */
 	class?: string;
+	/** Classes on the submit button, beside `cms-form-submit`. */
+	submitClass?: string;
+	/** The line after a send. Default "Thanks, we'll be in touch shortly." */
+	thanks?: string;
+	/** The line when a send fails and the endpoint gave no sentence of its own. Default "Something went wrong. Please email us directly." */
+	failed?: string;
+	/** The error line by field type, in place of the package's wording. A field's own `error` (config) still wins. */
+	errors?: Partial<Record<FormFieldType, string>>;
+	/** Wrap the submit button and the status line in `<div class="cms-form-actions">`. */
+	actions?: boolean;
+	/** A field that takes a placeholder and sets none uses its label as one. */
+	labelPlaceholders?: boolean;
+	/** Anything else (`data-*`, `id`, `aria-*`…) goes on the `<form>`. */
+	[attribute: string]: unknown;
 }
 
-const { form: id, preview = false, submit = 'Send', class: className } = Astro.props;
+const {
+	form: id,
+	preview = false,
+	submit = 'Send',
+	class: className,
+	submitClass,
+	thanks,
+	failed,
+	errors,
+	actions = false,
+	labelPlaceholders = false,
+	...given
+} = Astro.props;
+// The form's own attributes stay its own: a pass-through can't replace them.
+const OWN = new Set(['action', 'method', 'enctype', 'inert', 'data-max-files', 'data-max-bytes', 'data-file-kinds', 'data-thanks', 'data-failed']);
+const rest = passThrough(Object.fromEntries(Object.entries(given).filter(([name]) => !OWN.has(name.toLowerCase()) && !name.toLowerCase().startsWith('data-caracms-'))));
 const form = Object.hasOwn(site.forms, id) ? site.forms[id]! : null;
 const files = form?.fields.some((f) => f.type === 'files') ?? false;
 const back = cleanReturn(preview ? '/' : Astro.url.pathname);
@@ -54,6 +104,8 @@ const DEFAULT_ERROR: Record<ResolvedFormField['type'], string> = {
 	select: 'Please choose one.',
 	files: 'Please attach a file.',
 };
+const placeholderOf = (f: ResolvedFormField) => f.placeholder ?? (labelPlaceholders && PLACEHOLDER_TYPES.includes(f.type) ? f.label : undefined);
+const errorOf = (f: ResolvedFormField) => f.error || errors?.[f.type] || DEFAULT_ERROR[f.type];
 const described = (f: ResolvedFormField) =>
 	[f.prefix ? `${fieldId(f.name)}-prefix` : '', f.help ? `${fieldId(f.name)}-help` : '', `${fieldId(f.name)}-error`].filter(Boolean).join(' ');
 ---
@@ -61,6 +113,7 @@ const described = (f: ResolvedFormField) =>
 {
 	form ? (
 		<form
+			{...rest}
 			class:list={['cms-form', className]}
 			action="/_caracms/form"
 			method="post"
@@ -69,6 +122,8 @@ const described = (f: ResolvedFormField) =>
 			data-max-files={files ? MAX_FILES : undefined}
 			data-max-bytes={files ? MAX_FILE_BYTES : undefined}
 			data-file-kinds={files ? FILE_KINDS : undefined}
+			data-thanks={thanks || undefined}
+			data-failed={failed || undefined}
 			inert={preview || undefined}
 		>
 			<input type="hidden" name="form" value={id} />
@@ -86,7 +141,7 @@ const described = (f: ResolvedFormField) =>
 						{f.optional && <span class="cms-form-optional"> (optional)</span>}
 					</label>
 					{f.type === 'textarea' ? (
-						<textarea id={fieldId(f.name)} name={f.name} rows="6" required={!f.optional} autocomplete={f.autocomplete} placeholder={f.placeholder} aria-describedby={described(f)} />
+						<textarea id={fieldId(f.name)} name={f.name} rows={String(f.rows ?? 6)} required={!f.optional} autocomplete={f.autocomplete} placeholder={placeholderOf(f)} aria-describedby={described(f)} />
 					) : f.type === 'select' ? (
 						<select id={fieldId(f.name)} name={f.name} required={!f.optional} autocomplete={f.autocomplete} aria-describedby={described(f)}>
 							<option value="">Choose…</option>
@@ -104,10 +159,10 @@ const described = (f: ResolvedFormField) =>
 							<span class="cms-form-prefix" id={`${fieldId(f.name)}-prefix`}>
 								{f.prefix}
 							</span>
-							<input id={fieldId(f.name)} type={f.type} name={f.name} required={!f.optional} autocomplete={f.autocomplete} placeholder={f.placeholder} aria-describedby={described(f)} />
+							<input id={fieldId(f.name)} type={f.type} name={f.name} required={!f.optional} autocomplete={f.autocomplete} placeholder={placeholderOf(f)} aria-describedby={described(f)} />
 						</div>
 					) : (
-						<input id={fieldId(f.name)} type={f.type} name={f.name} required={!f.optional} autocomplete={f.autocomplete} placeholder={f.placeholder} aria-describedby={described(f)} />
+						<input id={fieldId(f.name)} type={f.type} name={f.name} required={!f.optional} autocomplete={f.autocomplete} placeholder={placeholderOf(f)} aria-describedby={described(f)} />
 					)}
 					{f.help && (
 						<p class="cms-form-help" id={`${fieldId(f.name)}-help`}>
@@ -115,15 +170,26 @@ const described = (f: ResolvedFormField) =>
 						</p>
 					)}
 					<p class="cms-form-error" id={`${fieldId(f.name)}-error`}>
-						{f.error || DEFAULT_ERROR[f.type]}
+						{errorOf(f)}
 					</p>
 				</div>
 			))}
 			{turnstileKey && <div class="cms-form-turnstile" data-caracms-turnstile data-sitekey={turnstileKey} />}
-			<button type="submit" class="cms-form-submit">
-				{submit}
-			</button>
-			<p class="cms-form-status" role="status" aria-live="polite" data-caracms-form-status />
+			{actions ? (
+				<div class="cms-form-actions">
+					<button type="submit" class:list={['cms-form-submit', submitClass]}>
+						{submit}
+					</button>
+					<p class="cms-form-status" role="status" aria-live="polite" data-caracms-form-status />
+				</div>
+			) : (
+				<>
+					<button type="submit" class:list={['cms-form-submit', submitClass]}>
+						{submit}
+					</button>
+					<p class="cms-form-status" role="status" aria-live="polite" data-caracms-form-status />
+				</>
+			)}
 		</form>
 	) : preview ? (
 		<p class="cms-form-missing">There's no form "{id}" in the site's config.</p>

package/src/components/Head.astro

@@ -45,6 +45,7 @@ const head = headOf({
 	tagAllowed: build.production && !preview,
 	listPage,
 	titleSeparator: site.titleSeparator,
+	titleFallback: site.titleFallback,
 });
 ---
 

package/src/components/Media.astro

@@ -19,12 +19,21 @@
  *   source matches and only the poster shows.
  * - **A player**: MediaPlayer.astro (its poster and a "Play video: {name}" button);
  *   only it carries a script, so a page with no player has none.
+ * - **PNG** (M9 Decision 8): a field declared `media({ format: 'png' })` gets `@png`
+ *   URLs at every width; every other image is WebP.
  * - **Loading** (Decision 4): eager in the first two rendered blocks (`cms.eager`),
  *   `fetchpriority="high"` only on the image at `cms.priority`; lazy otherwise. Props
  *   override both.
  * - **Preview markers**: `data-cms-field="<path>" data-cms-kind="media"` on the element,
  *   preview renders only, when `field` is given (a dotted path into a list works).
  *   Without `field` (a card showing another document's cover) there's no marker.
+ * - **An empty slot** (M9 port friction, item 12): nothing for visitors. In a preview, with
+ *   `field`, a placeholder carrying the markers, so the slot can be clicked on the page
+ *   (it selects the field, as a placed image does): a `<span>` (valid inside a `<p>` or a
+ *   link) with the caller's `class`, at `ratio` when given (else the fixed `width`/`height`,
+ *   else at least 6rem square), drawn as a dashed box in the text's own colour. So a block
+ *   that wants its empty slot clickable calls `<Media>` even when the value is empty
+ *   (`{(block.media || cms.preview) && <Media … />}`); the visitors' page is unchanged.
  * - **Without the media variables** (Decision 5): a preview (and `astro dev`) renders an
  *   image slot as nothing; a build throws the one sentence naming them.
  *
@@ -51,6 +60,8 @@ const markers = cms.preview && field ? { 'data-cms-field': field, 'data-cms-kind
 const load = loading ?? (cms.eager ? 'eager' : 'lazy');
 const priority = fetchpriority ?? (field && cms.priority === field ? 'high' : undefined);
 const fixed = width !== undefined || height !== undefined;
+// M9 Decision 8: the field's own format (PNG for flat artwork), WebP otherwise.
+const format = descriptor?.format;
 
 let img: (ReturnType<typeof fluidImage> & { alt: string; style?: string }) | null = null;
 if (media?.kind === 'image') {
@@ -61,14 +72,29 @@ if (media?.kind === 'image') {
 		if (!cms.preview && isProductionBuild() && !failedOnce()) throw new Error(`caracms: ${mediaUnsetMessage(config)}`);
 	} else {
 		if (!fixed && !sizes) throw new Error(`<Media>: a fluid image needs \`sizes\` (${cms.collection ? `collection "${cms.collection}"` : `block "${cms.type}"`}${field ? `, field "${field}"` : ''}).`);
-		const built = fixed ? fixedImage(config.settings, media, { width, height, fit }) : fluidImage(config.settings, media, { sizes: sizes!, ratio, minWidth, maxWidth });
+		const built = fixed ? fixedImage(config.settings, media, { width, height, fit, format }) : fluidImage(config.settings, media, { sizes: sizes!, ratio, minWidth, maxWidth, format });
 		const styles = media.position ? [`object-position: ${media.position}`, style].filter(Boolean).join('; ') : style;
 		img = { ...built, alt: media.alt, style: styles };
 	}
 }
 const clip = media?.kind === 'video' ? media : null;
+// An empty slot in a preview: something to click (see above). Never in the public render.
+const placeholderStyle = cms.preview && field && !media ? emptySlotStyle({ ratio, width, height, style }) : null;
+
+function emptySlotStyle(size: { ratio?: number; width?: number; height?: number; style?: string }): string {
+	const box =
+		size.ratio !== undefined
+			? [`aspect-ratio: ${size.ratio}`, 'min-width: 6rem']
+			: size.width !== undefined || size.height !== undefined
+				? [size.width !== undefined ? `width: ${size.width}px` : 'min-width: 6rem', size.height !== undefined ? `height: ${size.height}px` : 'min-height: 6rem']
+				: ['min-width: 6rem', 'min-height: 6rem'];
+	const look = ['background: color-mix(in srgb, currentColor 6%, transparent)', 'outline: 1.5px dashed color-mix(in srgb, currentColor 40%, transparent)', 'outline-offset: -1.5px', 'cursor: pointer'];
+	return ['display: block', 'box-sizing: border-box', ...box, size.style, ...look].filter(Boolean).join('; ');
+}
 ---
 
+{placeholderStyle !== null && <span class={className} style={placeholderStyle} aria-hidden="true" data-cms-placeholder="" {...rest} {...markers} />}
+
 {
 	img && (
 		<img

package/src/components/RichText.astro

@@ -10,7 +10,7 @@
  *   joined by `<br>`.
  * - A kind the field doesn't allow renders as `<p>`, and a link where the field
  *   has links off as its text (the field warns; rich-text.ts reads them so).
- * - The blocks sit in one wrapper element, `as` (default `div`), which takes
+ * - The blocks sit in one wrapper element, `as` (default `div`; a heading field's below), which takes
  *   `class` and any other attribute. Public render: nothing at all for an empty value.
  * - Preview render only (M3 Decision 17): the wrapper is always there, with
  *   `data-cms-field="<path>" data-cms-kind="richText"`. A top-level field is typed
@@ -21,12 +21,18 @@
  *   (`items.0.body`) is edited in the sidebar only, so it has no tabindex. The public
  *   render has none of these.
  * - `field` is the field's key, or a dotted path into a list (Decision 16).
+ * - **A heading field** (`richText({ heading: true })`, M9 Decision 11): the element is
+ *   `as`, or `h1` when it holds the page's first heading and `h2` otherwise (as Text's
+ *   heading), and inside it each paragraph's runs, the paragraphs joined by `<br>`: no
+ *   `<p>`. Bold is `<strong>`, so the site styles it (`h1 strong { … }`).
+ *
+ *     <RichText cms={cms} field="statement" value={block.statement} class="board-statement" />
  */
 import { site } from 'virtual:caracms/config';
 import type { HTMLTag } from 'astro/types';
 import type { BlockContext } from '../document.ts';
 import { parseField } from '../fields.ts';
-import { richTextHtml, type RichTextValue } from '../rich-text.ts';
+import { richHeadingHtml, richTextHtml, type RichTextValue } from '../rich-text.ts';
 import { isTypedOnPage, requireField } from './descriptor.ts';
 import { passThrough } from './attributes.ts';
 
@@ -39,12 +45,14 @@ interface Props {
 	[attribute: string]: unknown;
 }
 
-const { cms, field, value, as: Tag = 'div', class: className, ...given } = Astro.props;
+const { cms, field, value, as, class: className, ...given } = Astro.props;
 // M8 trial (item 4): a bare attribute stays bare, false is none (attributes.ts).
 const rest = passThrough(given);
 const descriptor = requireField(site, cms, field, 'richText', 'RichText');
+const Tag = as ?? (descriptor.heading ? (cms.h1Field === field ? 'h1' : 'h2') : 'div');
 // Re-read through the field, so a value from anywhere renders by the field's rules.
-const html = richTextHtml(parseField(descriptor, value) as RichTextValue, { fileLinks: true });
+const parsed = parseField(descriptor, value) as RichTextValue;
+const html = descriptor.heading ? richHeadingHtml(parsed) : richTextHtml(parsed, { fileLinks: true });
 const markers = cms.preview ? { 'data-cms-field': field, 'data-cms-kind': 'richText', ...(isTypedOnPage(field) ? { tabindex: '0' } : {}) } : {};
 ---
 

package/src/components/Text.astro

@@ -16,6 +16,14 @@
  *   `<Text cms={cms} field={`credits.${i}.name`} value={credit.name} />` in the
  *   block's own loop. The marker carries the path. Text inside a list is edited in
  *   the sidebar (Decision 13), so a nested path is never `contenteditable`.
+ * - **The lines rendering** (M9 Decision 10), for a field declared `text({ lines: true })`:
+ *   each line is drawn trimmed and blank lines draw nothing; with one line left it's drawn unwrapped; with more, each
+ *   line is a `<span>` with `lineClass` (Share's `block text-balance`), and no `<br>`.
+ *   In a preview each span also carries `data-cms-line`, so the text read back from the
+ *   page (preview/field-text.ts) starts a new line at each, and the element carries
+ *   `data-cms-lines` (and `data-cms-line-class`), so a sidebar edit is drawn the same way.
+ *
+ *     <Text cms={cms} field="heading" value={block.heading} lineClass="block text-balance" />
  */
 import { site } from 'virtual:caracms/config';
 import type { HTMLTag } from 'astro/types';
@@ -29,16 +37,25 @@ interface Props {
 	value: string;
 	as?: HTMLTag;
 	class?: string;
+	/** The lines rendering's class on each line's `<span>` (M9 Decision 10). */
+	lineClass?: string;
 	/** Anything else (such as the caller's scoped-style attribute) goes on the element. */
 	[attribute: string]: unknown;
 }
 
-const { cms, field, value, as, class: className, ...given } = Astro.props;
+const { cms, field, value, as, class: className, lineClass, ...given } = Astro.props;
 // M8 trial (item 4): a bare attribute stays bare, false is none (attributes.ts).
 const rest = passThrough(given);
 const descriptor = requireField(site, cms, field, 'text', 'Text');
 const Tag = as ?? (descriptor.heading ? (cms.h1Field === field ? 'h1' : 'h2') : 'p');
-const lines = value ? (descriptor.multiline ? value.split('\n') : [value]) : [];
+const typed = value ? (descriptor.multiline ? value.split('\n') : [value]) : [];
+// M9 Decision 10: blank lines draw nothing, and two or more lines are a span each.
+// Each line is drawn trimmed, as Tina's toLines() did (port friction 7); the stored value keeps its spaces.
+const lines = descriptor.lines ? typed.map((line) => line.trim()).filter((line) => line !== '') : typed;
+const spans = descriptor.lines && lines.length > 1;
+const lineMarker = cms.preview ? { 'data-cms-line': '' } : {};
+// The preview writes a sidebar edit back as these lines (preview/field-text.ts → writeFieldText).
+const linesMarkers = cms.preview && descriptor.lines ? { 'data-cms-lines': '', ...(lineClass ? { 'data-cms-line-class': lineClass } : {}) } : {};
 const markers = cms.preview
 	? { 'data-cms-field': field, 'data-cms-kind': 'text', ...(isTypedOnPage(field) ? { contenteditable: 'plaintext-only' } : {}) }
 	: {};
@@ -46,13 +63,19 @@ const markers = cms.preview
 
 {
 	(lines.length > 0 || cms.preview) && (
-		<Tag class={className} {...rest} {...markers}>
-			{lines.map((line, i) => (
-				<>
-					{i > 0 && <br />}
-					{line}
-				</>
-			))}
+		<Tag class={className} {...rest} {...markers} {...linesMarkers}>
+			{spans
+				? lines.map((line) => (
+						<span class={lineClass} {...lineMarker}>
+							{line}
+						</span>
+					))
+				: lines.map((line, i) => (
+						<>
+							{i > 0 && <br />}
+							{line}
+						</>
+					))}
 		</Tag>
 	)
 }

package/src/components/form-client.ts

@@ -3,7 +3,8 @@
  * (Form.astro carries it). It enhances a form that already works without it:
  *
  * - submits with `fetch` (`Accept: application/json`), shows "Sending…", then the
- *   thanks line, or the endpoint's own sentence when it gave one;
+ *   thanks line, or the endpoint's own sentence when it gave one (the thanks and the
+ *   failure lines are the form's `data-thanks` / `data-failed` when Form.astro was given them);
  * - makes a files field's picks add up: each pick is added to the files already chosen
  *   (the real list kept in a `DataTransfer` and given back to `input.files`, so the fetch
  *   and a plain submit both send every one), the same name and size never twice, listed
@@ -126,6 +127,8 @@ function enhance(form: HTMLFormElement): void {
 	if (!status) return;
 	const submit = form.querySelector<HTMLButtonElement>('button[type="submit"]');
 	const widget = form.querySelector<HTMLElement>('[data-caracms-turnstile]');
+	const thanks = form.dataset.thanks || THANKS;
+	const failedLine = form.dataset.failed || FAILED;
 	const say = (text: string, failed: boolean) => {
 		status.textContent = text;
 		status.classList.toggle('cms-form-failed', failed);
@@ -145,7 +148,7 @@ function enhance(form: HTMLFormElement): void {
 		if (tooMuch) return say(tooMuch, true);
 		submit?.setAttribute('disabled', '');
 		say('Sending…', false);
-		let failure = FAILED;
+		let failure = failedLine;
 		try {
 			const res = await fetch(form.action, { method: 'POST', headers: { Accept: 'application/json' }, body: new FormData(form) });
 			if (!res.ok) {
@@ -154,7 +157,7 @@ function enhance(form: HTMLFormElement): void {
 				throw new Error(String(res.status));
 			}
 			form.reset();
-			say(THANKS, false);
+			say(thanks, false);
 		} catch {
 			say(failure, true);
 		} finally {
@@ -167,7 +170,7 @@ function enhance(form: HTMLFormElement): void {
 	// The no-JS path lands back here with ?sent=1.
 	const params = new URLSearchParams(location.search);
 	if (params.get('sent') === '1') {
-		say(THANKS, false);
+		say(thanks, false);
 		params.delete('sent');
 		const rest = params.toString();
 		history.replaceState(null, '', `${location.pathname}${rest ? `?${rest}` : ''}${location.hash}`);

package/src/components/sitemap.xml.ts

@@ -21,7 +21,8 @@ export async function sitemapUrls(siteUrl: string): Promise<string[]> {
 	for (const collection of siteCollections(site)) {
 		if (collection.urlBase === null) continue;
 		for (const entry of await listDocuments(site, collection.name)) {
-			if (entry.warning || entry.url === null) continue;
+			// M9 Decision 7: a hidden page (or one under 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('/')}`);
 		}
 	}