caracms 0.1.0 → 0.2.0

package/src/live/backend.ts

@@ -26,7 +26,10 @@ export interface Heads {
 	drafts: Head;
 }
 
-export type Branch = 'main' | 'drafts';
+import type { Branch, BranchNames } from './branches.ts';
+import { DEFAULT_BRANCHES } from './branches.ts';
+
+export { DEFAULT_BRANCHES, type Branch, type BranchNames };
 
 export interface CommitSummary {
 	sha: string;
@@ -111,6 +114,8 @@ export class MissingBranchError extends Error {
 export interface GitBackend {
 	readonly tracker: Tracker;
 	readonly name: 'github' | 'memory';
+	/** The ref name behind each role. */
+	readonly branches: Readonly<BranchNames>;
 	/** Both heads, in one request. Throws MissingBranchError. */
 	readHeads(): Promise<Heads>;
 	createBranch(branch: Branch, sha: string): Promise<void>;
@@ -144,11 +149,11 @@ export function isStaleGraphQL(errors: { type?: string; message?: string }[]): b
 
 // ── GitHub ────────────────────────────────────────────────────────────────────
 
-const HEADS_QUERY = `query($owner: String!, $name: String!) {
+const HEADS_QUERY = `query($owner: String!, $name: String!, $main: String!, $drafts: String!) {
   repository(owner: $owner, name: $name) {
     id
-    main: ref(qualifiedName: "refs/heads/main") { target { oid ... on Commit { tree { oid } } } }
-    drafts: ref(qualifiedName: "refs/heads/drafts") { target { oid ... on Commit { tree { oid } } } }
+    main: ref(qualifiedName: $main) { target { oid ... on Commit { tree { oid } } } }
+    drafts: ref(qualifiedName: $drafts) { target { oid ... on Commit { tree { oid } } } }
   }
 }`;
 
@@ -168,10 +173,16 @@ const COMPARE_FILE_CAP = 300;
 export class GitHubBackend implements GitBackend {
 	readonly name = 'github';
 	readonly gh: GitHubClient;
+	readonly branches: Readonly<BranchNames>;
 	private repoId = '';
 
-	constructor(gh: GitHubClient) {
+	constructor(gh: GitHubClient, branches: Readonly<BranchNames> = DEFAULT_BRANCHES) {
 		this.gh = gh;
+		this.branches = branches;
+	}
+	/** `refs/heads/<name>` for a role. */
+	private qualified(branch: Branch) {
+		return `refs/heads/${this.branches[branch]}`;
 	}
 	get tracker() {
 		return this.gh.tracker;
@@ -180,7 +191,7 @@ export class GitHubBackend implements GitBackend {
 	async readHeads(): Promise<Heads> {
 		const d = await this.gh.graphql<{ repository: { id: string; main: RefNode; drafts: RefNode } }>(
 			HEADS_QUERY,
-			{ owner: this.gh.owner, name: this.gh.repo },
+			{ owner: this.gh.owner, name: this.gh.repo, main: this.qualified('main'), drafts: this.qualified('drafts') },
 			'readHeads',
 		);
 		this.repoId = d.repository.id;
@@ -192,7 +203,7 @@ export class GitHubBackend implements GitBackend {
 	}
 
 	async createBranch(branch: Branch, sha: string) {
-		await this.gh.rest('POST', this.gh.repoPath('/git/refs'), { ref: `refs/heads/${branch}`, sha });
+		await this.gh.rest('POST', this.gh.repoPath('/git/refs'), { ref: this.qualified(branch), sha });
 	}
 
 	async readArchive(commit: string, keep: (path: string) => boolean) {
@@ -253,7 +264,7 @@ export class GitHubBackend implements GitBackend {
 				COMMIT_ON_BRANCH,
 				{
 					input: {
-						branch: { repositoryNameWithOwner: this.gh.nameWithOwner, branchName: branch },
+						branch: { repositoryNameWithOwner: this.gh.nameWithOwner, branchName: this.branches[branch] },
 						expectedHeadOid: expectedHead,
 						message: { headline, body },
 						fileChanges: {
@@ -295,7 +306,7 @@ export class GitHubBackend implements GitBackend {
 				{
 					input: {
 						repositoryId: this.repoId,
-						refUpdates: updates.map((u) => ({ name: `refs/heads/${u.branch}`, beforeOid: u.before, afterOid: u.after, force: u.force })),
+						refUpdates: updates.map((u) => ({ name: this.qualified(u.branch), beforeOid: u.before, afterOid: u.after, force: u.force })),
 					},
 				},
 				'updateRefs',
@@ -309,7 +320,7 @@ export class GitHubBackend implements GitBackend {
 	async listCommits(branch: Branch, count: number) {
 		const list = await this.gh.rest<{ sha: string; parents: { sha: string }[]; commit: { message: string; committer: { date: string } } }[]>(
 			'GET',
-			this.gh.repoPath(`/commits?sha=${branch}&per_page=${Math.min(100, count)}`),
+			this.gh.repoPath(`/commits?sha=${encodeURIComponent(this.branches[branch])}&per_page=${Math.min(100, count)}`),
 		);
 		return list.map((k) => ({ sha: k.sha, parents: k.parents.map((p) => p.sha), message: k.commit.message, date: k.commit.committer.date }));
 	}
@@ -395,6 +406,7 @@ export const blobSha = (contents: string) => {
 export class MemoryBackend implements GitBackend {
 	readonly name = 'memory';
 	readonly tracker: Tracker;
+	readonly branches: Readonly<BranchNames>;
 	/** Deployments, newest last; tests push to it. */
 	deployments: MemoryDeployment[] = [];
 	/** Called before each recorded request, with its endpoint: tests inject races here. */
@@ -404,12 +416,18 @@ export class MemoryBackend implements GitBackend {
 	private blobs = new Map<string, string>();
 	private trees = new Map<string, MemTree>();
 	private commits = new Map<string, MemCommit>();
-	refs = new Map<Branch, string>();
+	/** Every ref, by its name (not its role): a test can seed a branch caracms mustn't touch. */
+	refs = new Map<string, string>();
 	private n = 0;
 
-	constructor(tracker = new Tracker(), options: { now?: () => number } = {}) {
+	constructor(tracker = new Tracker(), options: { now?: () => number; branches?: Readonly<BranchNames> } = {}) {
 		this.tracker = tracker;
 		this.now = options.now ?? Date.now;
+		this.branches = options.branches ?? DEFAULT_BRANCHES;
+	}
+	/** The ref name behind a role. */
+	private ref(branch: Branch) {
+		return this.branches[branch];
 	}
 
 	private async rec(endpoint: string, creating: boolean, status = 200) {
@@ -464,7 +482,7 @@ export class MemoryBackend implements GitBackend {
 		return c;
 	}
 	private head(branch: Branch): Head {
-		const c = this.refs.get(branch);
+		const c = this.refs.get(this.ref(branch));
 		if (!c) throw new MissingBranchError(branch);
 		return { commit: c, tree: this.commit(c).tree };
 	}
@@ -479,12 +497,12 @@ export class MemoryBackend implements GitBackend {
 
 	// Test helpers (not part of GitBackend; record no requests).
 
-	/** Start the repo: one parentless commit with these files on `main` (and `drafts`, if asked). */
+	/** Start the repo: one parentless commit with these files on the main branch (and the drafts branch, if asked). */
 	seed(files: FileWrite[], options: { drafts?: boolean } = {}): string {
 		const tree = this.putTree(new Map(files.map((f) => [f.path, { sha: this.blob(f.contents), mode: '100644' }])));
 		const seed = this.putCommit(tree, [], 'Seed');
-		this.refs.set('main', seed);
-		if (options.drafts) this.refs.set('drafts', seed);
+		this.refs.set(this.ref('main'), seed);
+		if (options.drafts) this.refs.set(this.ref('drafts'), seed);
 		return seed;
 	}
 
@@ -497,7 +515,7 @@ export class MemoryBackend implements GitBackend {
 			else t.set(path, { sha: this.blob(contents), mode: '100644' });
 		}
 		const c = this.putCommit(this.putTree(t), [head.commit], message);
-		this.refs.set(branch, c);
+		this.refs.set(this.ref(branch), c);
 		return c;
 	}
 
@@ -530,9 +548,9 @@ export class MemoryBackend implements GitBackend {
 
 	async createBranch(branch: Branch, sha: string) {
 		await this.rec('POST /git/refs', true);
-		if (this.refs.has(branch)) throw new HttpError(422, 'Reference already exists', null);
+		if (this.refs.has(this.ref(branch))) throw new HttpError(422, 'Reference already exists', null);
 		this.commit(sha);
-		this.refs.set(branch, sha);
+		this.refs.set(this.ref(branch), sha);
 	}
 
 	async readArchive(commit: string, keep: (path: string) => boolean) {
@@ -574,14 +592,14 @@ export class MemoryBackend implements GitBackend {
 
 	async commitOnBranch(branch: Branch, expectedHead: string, additions: FileWrite[], deletions: string[], headline: string, body: string) {
 		await this.rec('graphql createCommitOnBranch', true);
-		const cur = this.refs.get(branch);
+		const cur = this.refs.get(this.ref(branch));
 		if (cur !== expectedHead) throw new StaleHeadError(`Expected branch to point to "${expectedHead}" but it did not. Pull and try again.`);
 		const t = new Map(this.trees.get(this.commit(cur).tree)!);
 		for (const f of additions) t.set(f.path, { sha: this.blob(f.contents), mode: '100644' });
 		for (const p of deletions) t.delete(p);
 		const tree = this.putTree(t);
 		const c = this.putCommit(tree, [cur], body ? `${headline}\n\n${body}` : headline);
-		this.refs.set(branch, c);
+		this.refs.set(this.ref(branch), c);
 		return { commit: c, tree };
 	}
 
@@ -606,10 +624,10 @@ export class MemoryBackend implements GitBackend {
 		await this.rec('graphql updateRefs', true);
 		for (const u of updates) {
 			// GitHub's answer here is a generic error, not a typed one (M1 → G6 (a)).
-			if (this.refs.get(u.branch) !== u.before) throw new GraphQLError([{ message: 'Something went wrong while executing your query.' }]);
+			if (this.refs.get(this.ref(u.branch)) !== u.before) throw new GraphQLError([{ message: 'Something went wrong while executing your query.' }]);
 			if (!u.force && !this.isAncestor(u.before, u.after)) throw new GraphQLError([{ message: 'Something went wrong while executing your query.' }]);
 		}
-		for (const u of updates) this.refs.set(u.branch, u.after); // all or nothing
+		for (const u of updates) this.refs.set(this.ref(u.branch), u.after); // all or nothing
 	}
 
 	async listCommits(branch: Branch, count: number) {

package/src/live/branches.ts

@@ -0,0 +1,19 @@
+/**
+ * The ref names behind each branch role (M9 Decision 6). `main` is what's published
+ * (and deployed); `drafts` is where autosaves land. `CARACMS_MAIN_BRANCH` and
+ * `CARACMS_DRAFTS_BRANCH` name them (mode.ts), defaulting to `main` and `drafts`.
+ * With both named, a branch called `main` is never read or moved.
+ *
+ * Only the backends (backend.ts) turn a role into a name; everything above them speaks
+ * in roles. No imports here, so mode.ts can read it without the backends.
+ */
+
+/** A branch's role, not its name. */
+export type Branch = 'main' | 'drafts';
+
+export interface BranchNames {
+	main: string;
+	drafts: string;
+}
+
+export const DEFAULT_BRANCHES: Readonly<BranchNames> = Object.freeze({ main: 'main', drafts: 'drafts' });

package/src/live/mode.ts

@@ -15,6 +15,7 @@
  * This only reads; it doesn't wire anything (Phase 2 switches the routes on it,
  * Phase 3 guards with it).
  */
+import { DEFAULT_BRANCHES, type BranchNames } from './branches.ts';
 import { DEFAULT_TIMINGS, type LiveTimings } from './timings.ts';
 
 export interface LiveSettings {
@@ -38,6 +39,12 @@ export interface LiveSettings {
 	runningCommit: string | null;
 	/** Dev only: CARACMS_TIMINGS, a JSON object of LiveTimings to shorten (Decision 2). */
 	timings: LiveTimings;
+	/**
+	 * CARACMS_MAIN_BRANCH and CARACMS_DRAFTS_BRANCH (M9 Decision 6): the refs Publish and
+	 * autosave move, `main` and `drafts` unset. readMode always fills it; missing (a test's
+	 * settings) means the defaults.
+	 */
+	branches?: BranchNames;
 	production: boolean;
 }
 
@@ -97,6 +104,8 @@ export function readMode(env: Env = process.env, production = env.NODE_ENV === '
 		else timings = { ...timings, ...parseTimings(rawTimings, problems) };
 	}
 
+	const branches = readBranches(get, problems);
+
 	if (missing.length || problems.length) return { kind: 'unconfigured', missing, problems };
 	return {
 		kind: 'live',
@@ -113,11 +122,48 @@ export function readMode(env: Env = process.env, production = env.NODE_ENV === '
 			backup: user && password ? { user, password } : null,
 			runningCommit: get('CARACMS_RUNNING_COMMIT') ?? get('RAILWAY_GIT_COMMIT_SHA'),
 			timings,
+			branches,
 			production,
 		},
 	};
 }
 
+/**
+ * The branch names (M9 Decision 6). Both set or neither (one alone would leave the other
+ * at its default, so a site meant to keep off `main` would still publish to it). Each must
+ * be a plain branch name, the two must differ, and autosaves never go to a branch called
+ * `main` under another name (that's the branch the settings exist to keep still).
+ */
+function readBranches(get: (name: string) => string | null, problems: string[]): BranchNames {
+	const main = get('CARACMS_MAIN_BRANCH');
+	const drafts = get('CARACMS_DRAFTS_BRANCH');
+	if ((main === null) !== (drafts === null)) {
+		problems.push(`CARACMS_MAIN_BRANCH and CARACMS_DRAFTS_BRANCH must be set together (only ${main === null ? 'CARACMS_DRAFTS_BRANCH' : 'CARACMS_MAIN_BRANCH'} is set), or neither for main and drafts.`);
+	}
+	const branches: BranchNames = {
+		main: get('CARACMS_MAIN_BRANCH') ?? DEFAULT_BRANCHES.main,
+		drafts: get('CARACMS_DRAFTS_BRANCH') ?? DEFAULT_BRANCHES.drafts,
+	};
+	for (const [name, value] of [
+		['CARACMS_MAIN_BRANCH', branches.main],
+		['CARACMS_DRAFTS_BRANCH', branches.drafts],
+	] as const) {
+		if (!isBranchName(value)) problems.push(`${name} must be a branch name, like port-caracms (got "${value}").`);
+	}
+	if (branches.main === branches.drafts) problems.push(`CARACMS_MAIN_BRANCH and CARACMS_DRAFTS_BRANCH must differ (both are "${branches.main}").`);
+	else if (branches.drafts === 'main') problems.push('CARACMS_DRAFTS_BRANCH can\'t be main: autosaves would land on main.');
+	return branches;
+}
+
+/** A plain branch name: no `refs/` prefix, nothing git refuses in a ref. */
+function isBranchName(name: string): boolean {
+	return (
+		/^[A-Za-z0-9._/-]+$/.test(name) &&
+		!name.startsWith('refs/') &&
+		!/^[-/.]|[/.]$|\.\.|\/\/|\/\.|\.lock$|\.lock\//.test(name)
+	);
+}
+
 /** The repo: GITHUB_REPO overrides Railway's own variables (Decision 3). */
 function readRepo(env: Env, problems: string[]): { owner: string; repo: string } | null {
 	const override = env.GITHUB_REPO?.trim();

package/src/live/runtime.ts

@@ -19,6 +19,7 @@ import { readdir, readFile } from 'node:fs/promises';
 import { join, relative, sep } from 'node:path';
 import { repoPrefix, type ResolvedSite } from '../config.ts';
 import { GitHubBackend, MemoryBackend, type FileWrite, type GitBackend } from './backend.ts';
+import { DEFAULT_BRANCHES } from './branches.ts';
 import { GitHubClient, Tracker } from './github.ts';
 import { LiveGit, SITE_SETTINGS_FILE } from './git.ts';
 import type { LiveSettings } from './mode.ts';
@@ -62,16 +63,18 @@ export async function createLiveRuntime(options: RuntimeOptions): Promise<LiveRu
 			if (settings.production || process.env.NODE_ENV === 'production') {
 				throw new Error('caracms: the in-memory GitHub (CARACMS_GITHUB=memory) is refused in production.');
 			}
-			const memory = new MemoryBackend(new Tracker(now), { now });
+			const memory = new MemoryBackend(new Tracker(now), { now, branches: settings.branches });
 			memory.seed(await siteFiles(site));
 			log('live mode on the in-memory GitHub, seeded from the site\'s files on disk (CARACMS_GITHUB=memory)');
 			backend = memory;
 		} else {
 			const tracker = new Tracker(now);
 			const { appId, privateKey, owner, repo } = settings.github;
-			backend = new GitHubBackend(new GitHubClient({ appId, privateKey, owner, repo, now }, tracker));
+			backend = new GitHubBackend(new GitHubClient({ appId, privateKey, owner, repo, now }, tracker), settings.branches);
 		}
 	}
+	const { main, drafts } = backend.branches;
+	if (main !== DEFAULT_BRANCHES.main || drafts !== DEFAULT_BRANCHES.drafts) log(`publishing to ${main}, autosaving to ${drafts} (CARACMS_MAIN_BRANCH, CARACMS_DRAFTS_BRANCH)`);
 	const redis = options.redis ?? (settings.redisUrl ? connectRedis(settings.redisUrl, { log }) : memoryRedis({ now }));
 	if (!options.redis && !settings.redisUrl) log('no REDIS_URL: using the in-memory Redis stand-in (dev only)');
 	const git = new LiveGit({

package/src/media.ts

@@ -12,7 +12,8 @@
  *   is refused (403).
  * - A gravity goes only on a `fill` (a `fit` crops nothing; a gravity there would only
  *   make a second URL for the same file). Quality 80. WebP, always in the URL (never
- *   imgproxy's auto-format: Railway's CDN ignores `Vary: Accept`).
+ *   imgproxy's auto-format: Railway's CDN ignores `Vary: Accept`); `@png` when the
+ *   media field says `format: 'png'` (M9 Decision 8).
  * - Sides are rounded and capped at 4000 (imgproxy's `IMGPROXY_MAX_RESULT_DIMENSION`).
  * - GIFs and SVGs pass through: `/<sig>/plain/s3://<bucket>/<key>`, no resize, no
  *   format, still signed (a GIF resize drops its animation; an SVG is sharp at any size).
@@ -23,6 +24,7 @@
  * fixed test key and salt and a test bucket, and is refused on a production server.
  */
 import { createHmac } from 'node:crypto';
+import type { ImageFormat } from './fields.ts';
 import type { RenderImage } from './media-value.ts';
 
 /** The srcset width ladder every fluid image draws from (Decision 2). 1920 at the top: imgproxy doesn't upscale. */
@@ -30,8 +32,8 @@ export const IMAGE_WIDTHS: readonly number[] = [160, 320, 480, 640, 960, 1280, 1
 /** imgproxy's IMGPROXY_MAX_RESULT_DIMENSION: a side is never asked for above it. */
 export const IMAGE_MAX_DIMENSION = 4000;
 export const IMAGE_QUALITY = 80;
-/** Pinned in every resized URL. */
-export const IMAGE_FORMAT = 'webp';
+/** Pinned in every resized URL, unless the media field asks for PNG (M9 Decision 8). */
+export const IMAGE_FORMAT: ImageFormat = 'webp';
 /** Fixed mode's densities (Decision 4: 1×, 2×, 3×). */
 export const IMAGE_DENSITIES: readonly number[] = [1, 2, 3];
 
@@ -141,6 +143,8 @@ export interface ImageUrlOptions {
 	resize?: 'fit' | 'fill';
 	/** The focal point, fractions; used only on a `fill`. */
 	focal?: readonly [number, number] | null;
+	/** Default: WebP (M9 Decision 8). */
+	format?: ImageFormat;
 }
 
 /**
@@ -154,7 +158,7 @@ export function imageUrl(settings: MediaSettings, key: string, options: ImageUrl
 	if (!width && !height) throw new Error(`An image URL needs a width or a height (${key}).`);
 	const resize = options.resize ?? (width && height ? 'fill' : 'fit');
 	const gravity = resize === 'fill' && options.focal ? `/g:fp:${options.focal[0]}:${options.focal[1]}` : '';
-	return signed(settings, `/rs:${resize}:${width}:${height}${gravity}/q:${IMAGE_QUALITY}/plain/${sourceOf(settings, key)}@${IMAGE_FORMAT}`);
+	return signed(settings, `/rs:${resize}:${width}:${height}${gravity}/q:${IMAGE_QUALITY}/plain/${sourceOf(settings, key)}@${options.format ?? IMAGE_FORMAT}`);
 }
 
 /** A slot's part of the ladder: every rung from `min` to `max`, inclusive. */
@@ -184,6 +188,7 @@ export interface FluidOptions {
 	ratio?: number;
 	minWidth?: number;
 	maxWidth?: number;
+	format?: ImageFormat;
 }
 
 export interface FixedOptions {
@@ -192,6 +197,7 @@ export interface FixedOptions {
 	height?: number;
 	fit?: 'cover' | 'contain';
 	densities?: readonly number[];
+	format?: ImageFormat;
 }
 
 const naturalHeight = (image: Pick<RenderImage, 'w' | 'h'>, width: number) => (image.w && image.h ? Math.round((width * image.h) / image.w) : undefined);
@@ -213,7 +219,9 @@ export function fluidImage(settings: MediaSettings, image: Pick<RenderImage, 'ke
 	};
 	if (!isResizable(image.key)) return { src: imageUrl(settings, image.key), ...dims(image.w ?? undefined) };
 	const at = (w: number) =>
-		options.ratio ? imageUrl(settings, image.key, { width: w, height: Math.round(w / options.ratio), focal: image.focal }) : imageUrl(settings, image.key, { width: w });
+		options.ratio
+			? imageUrl(settings, image.key, { width: w, height: Math.round(w / options.ratio), focal: image.focal, format: options.format })
+			: imageUrl(settings, image.key, { width: w, format: options.format });
 	return {
 		src: at(top),
 		srcset: widths.map((w) => `${at(w)} ${w}w`).join(', '),
@@ -231,7 +239,7 @@ export function fixedImage(settings: MediaSettings, image: Pick<RenderImage, 'ke
 	if (!isResizable(image.key)) return { src: imageUrl(settings, image.key), ...dims };
 	const both = !!width && !!height;
 	const resize = both && options.fit !== 'contain' ? 'fill' : 'fit';
-	const at = (d: number) => imageUrl(settings, image.key, { width: width ? width * d : 0, height: height ? height * d : 0, resize, focal: image.focal });
+	const at = (d: number) => imageUrl(settings, image.key, { width: width ? width * d : 0, height: height ? height * d : 0, resize, focal: image.focal, format: options.format });
 	const densities = options.densities ?? IMAGE_DENSITIES;
 	return { src: at(densities[0] ?? 1), srcset: densities.map((d) => `${at(d)} ${d}x`).join(', '), ...dims };
 }

package/src/read.ts

@@ -140,7 +140,8 @@ export function documentReader(site: Site, source: ContentSource): DocumentReade
 			let found = lists.get(collection);
 			if (!found) {
 				found = listDocuments(site, collection, source).then(async (listed) => {
-					const read = await Promise.all(listed.filter((e) => !e.warning).map((e) => reader.document(collection, e.path)));
+					// M9 Decision 7: a hidden page isn't on the site, so a listing of its collection leaves it out.
+					const read = await Promise.all(listed.filter((e) => !e.warning && !e.hidden).map((e) => reader.document(collection, e.path)));
 					return read.filter((r): r is ReadEntry => r !== null);
 				});
 				lists.set(collection, found);

package/src/rich-text.ts

@@ -69,12 +69,19 @@ export interface RichTextOptions {
 	headings: readonly HeadingKind[];
 	/** Whether the field allows links. */
 	links: boolean;
+	/**
+	 * M9 Decision 11: a heading rich-text field. Paragraphs and bold only: a list's items
+	 * read as paragraphs (a `disallowed-kind` issue) and italic is dropped (`italic-off`).
+	 * Such a field also has no headings and no links.
+	 */
+	heading?: boolean;
 }
 
 /** Something the reader changed or couldn't read, for the field's warning. `block` is the stored entry's index. */
 export type RichTextIssue =
 	| { code: 'disallowed-kind'; block: number; kind: string }
 	| { code: 'link-off'; block: number }
+	| { code: 'italic-off'; block: number }
 	| { code: 'unreadable'; block: number };
 
 // ── Runs ──────────────────────────────────────────────────────────────────────
@@ -480,10 +487,12 @@ const LIST_KINDS = new Set<string>(['ul', 'ol']);
 const allowedText = (kind: string, options: RichTextOptions): TextKind =>
 	kind === 'p' || ((kind === 'h2' || kind === 'h3') && options.headings.includes(kind)) ? (kind as TextKind) : 'p';
 
-/** Read one unit, applying `links` (off: hrefs dropped, with a flag). */
-function unit(runs: TextRun[], options: RichTextOptions): { runs: TextRun[]; droppedLink: boolean } {
+/** Read one unit, applying `links` (off: hrefs dropped, with a flag) and a heading field's no italic (M9 Decision 11). */
+function unit(runs: TextRun[], options: RichTextOptions): { runs: TextRun[]; droppedLink: boolean; droppedItalic: boolean } {
 	const droppedLink = !options.links && runs.some((r) => r.href !== undefined);
-	return { runs: trimRuns(normaliseRuns(runs, { links: options.links })), droppedLink };
+	const droppedItalic = !!options.heading && runs.some((r) => r.italic);
+	const plain = droppedItalic ? runs.map(({ italic: _, ...r }) => r) : runs;
+	return { runs: trimRuns(normaliseRuns(plain, { links: options.links })), droppedLink, droppedItalic };
 }
 
 /** A plain string as rich text: its characters literal, one paragraph per blank-line chunk, single newlines as breaks. */
@@ -550,14 +559,17 @@ export function readRichText(raw: unknown, options: RichTextOptions): { value: R
 			}
 		}
 
-		if (!list && !(TEXT_KINDS.has(kind) && allowedText(kind, options) === kind)) {
+		if ((!list || options.heading) && !(TEXT_KINDS.has(kind) && allowedText(kind, options) === kind)) {
 			issues.push({ code: 'disallowed-kind', block: index, kind });
 		}
 		const read = units.map((u) => unit(u, options));
 		if (read.some((u) => u.droppedLink)) issues.push({ code: 'link-off', block: index });
+		if (read.some((u) => u.droppedItalic)) issues.push({ code: 'italic-off', block: index });
 		const kept = read.map((u) => u.runs).filter((runs) => runs.length > 0);
 		if (kept.length === 0) return;
-		if (list) value.push({ kind: kind as ListKind, items: kept });
+		// M9 Decision 11: a heading field has no lists; each item is a line of its own.
+		if (list && options.heading) for (const runs of kept) value.push({ kind: 'p', runs });
+		else if (list) value.push({ kind: kind as ListKind, items: kept });
 		else value.push({ kind: allowedText(kind, options), runs: kept[0]! });
 	});
 	return { value, issues };
@@ -647,6 +659,19 @@ export function inlineHtml(runs: readonly TextRun[], options: RichTextHtmlOption
 		.join('');
 }
 
+/**
+ * A heading rich-text field's value as the inside of its heading tag (M9 Decision 11):
+ * each paragraph's inline runs, the paragraphs joined by `<br>`; never a `<p>`.
+ */
+export function richHeadingHtml(value: RichTextValue, options: RichTextHtmlOptions = {}): string {
+	return value.flatMap((block) => ('runs' in block ? [block.runs] : block.items)).map((runs) => inlineHtml(runs, options)).join('<br>');
+}
+
+/** A value's plain text, one line per paragraph or item (breaks inside one as `\n`): what reads a rich heading as text. */
+export function richTextPlain(value: RichTextValue): string {
+	return value.flatMap((block) => ('runs' in block ? [block.runs] : block.items)).map(runsText).join('\n');
+}
+
 /**
  * A value as semantic HTML with no classes: `<p>`, `<h2>`, `<h3>`, `<ul>`/`<ol>`
  * with `<li>`. A heading with a break renders as Text's multi-line heading does,

package/src/serialize.ts

@@ -169,6 +169,8 @@ export function applyEdits(base: string | null, edited: SiteDocument, site: Pick
 		}
 		members.push(['blocks', arrayText(blocks, 1)]);
 		if (!isEmptySeo(seo)) members.push(['seo', seoText(seo, 1)]);
+		// M9 Decision 7: `hidden` right after `title` (where the Tina script writes it).
+		if (edited.hidden) members.splice(1, 0, ['hidden', 'true']);
 		return `${objectText(members, 0)}\n`;
 	}
 
@@ -222,6 +224,9 @@ export function applyEdits(base: string | null, edited: SiteDocument, site: Pick
 			if (!same(value, parseField(field, raw[key]))) fieldTexts.set(key, fieldText(field, value, 1));
 		}
 	}
+	// M9 Decision 7: `hidden` per edit: absent, untouched; true adds it after `title`; false takes it out.
+	const hiddenEdit = edited.hidden === undefined || edited.hidden === (read.hidden === true) ? null : edited.hidden;
+	if (hiddenEdit !== null) fieldTexts.set('hidden', 'true');
 	if (!titleChanged && !blocksChanged && !seo && fieldTexts.size === 0) return base;
 
 	const replacements = new Map<string, string>();
@@ -231,9 +236,13 @@ export function applyEdits(base: string | null, edited: SiteDocument, site: Pick
 
 	let out = replacements.size ? replaceTopLevel(source, root, replacements) : source.text;
 	if (seo && !seo.text) out = removeTopLevel(out, 'seo');
+	if (hiddenEdit === false) {
+		fieldTexts.delete('hidden');
+		out = removeTopLevel(out, 'hidden');
+	}
 	if (fieldTexts.size) {
 		const next = parseSource(out);
-		if (next.root.kind === 'object') out = spliceKeys(next, next.root, fieldTexts, ['title', ...Object.keys(fields)]);
+		if (next.root.kind === 'object') out = spliceKeys(next, next.root, fieldTexts, ['title', 'hidden', ...Object.keys(fields)]);
 	}
 	return withTrailingNewline(out);
 }