caracms 0.1.0 → 0.3.0

package/src/editor/client/state/keeper.ts

@@ -2,8 +2,11 @@
  * Keeping: getting the editor's copy of each document to the server (M3 Decisions 5
  * and 6; M4 Decisions 4, 9 and 11).
  *
- * - **About a second after the last change**, the whole document is POSTed to the
- *   write route with the base it was made against: `{ file, base, document }`
+ * - **About a second after the last change** (local mode), the whole document is POSTed to the
+ *   write route with the base it was made against: `{ file, base, document }`. Live mode
+ *   (Redis diet Decision 10, `holds`): at once while the tab doesn't hold the document's
+ *   lock and no write for it is in flight; otherwise 3 s after the last change, at most
+ *   15 s after the first change not yet sent
  *   (server/write.ts). One write per document in flight; a change made meanwhile
  *   goes in the next one. In live mode every write carries the tab's id
  *   (`X-Caracms-Tab`) and its place in the tab's order (`X-Caracms-Seq`, rising, from
@@ -116,7 +119,7 @@ export interface KeeperOptions {
 	storage: KeeperStorage | null;
 	/** Storage keys are `caracms:unsent:<storageKey>:<docId>`, so two sites on one dev port don't mix. */
 	storageKey: string;
-	/** ms after the last change. Default 1000. */
+	/** ms after the last change. Default 1000 (local mode; live mode's timing is `holds`'s, below). */
 	delay?: number;
 	setTimer?: (fn: () => void, ms: number) => unknown;
 	clearTimer?: (timer: unknown) => void;
@@ -145,6 +148,20 @@ export interface KeeperOptions {
 	onSignedOut?: (body: SignedOutError) => void;
 	/** Who is signed in, for the re-send rule ("your own commits"). */
 	you?: () => Person | null;
+	/**
+	 * Redis diet Decision 10: whether this tab holds the document's lock (a write for it
+	 * was Kept, or a poll says so). Given, live mode's timing applies: a change goes at
+	 * once while the document isn't held and no write for it is in flight (that write
+	 * takes the lock); otherwise `keepDelay` after the last change, and never later than
+	 * `keepCap` after the first change not yet sent. Absent: `delay` after the last change.
+	 */
+	holds?: (file: string) => boolean;
+	/** Decision 10: ms after the last change, once held. Default 3000. */
+	keepDelay?: number;
+	/** Decision 10: …and at most this long after the first change not yet sent. Default 15000. */
+	keepCap?: number;
+	/** A write for this file was Kept (the server has it, and the write took or kept the lock). */
+	onKept?: (file: string) => void;
 }
 
 /** A held record the editor may need to look at again: once the lock lapses, or the session is back. */
@@ -223,6 +240,9 @@ interface Record {
 	by: Person | null;
 	elsewhere: boolean;
 	timer: unknown;
+	/** Live timing: when the last change came, and the first change not yet sent (null: none). */
+	lastChange: number;
+	firstUnsent: number | null;
 }
 
 const PREFIX = 'caracms:unsent:';
@@ -309,6 +329,7 @@ export function createKeeper(options: KeeperOptions): Keeper {
 	const clearTimer = options.clearTimer ?? ((t) => clearTimeout(t as ReturnType<typeof setTimeout>));
 	const log = options.log ?? ((message) => console.warn(`[caracms] ${message}`));
 	const now = options.now ?? Date.now;
+	const live = options.holds ? { holds: options.holds, delay: options.keepDelay ?? 3000, cap: options.keepCap ?? 15_000 } : null;
 	const prefix = `${PREFIX}${options.storageKey}:`;
 	const records = new Map<string, Record>();
 	let offline = false;
@@ -394,7 +415,7 @@ export function createKeeper(options: KeeperOptions): Keeper {
 	const record = (id: string, file: string, fileVersion: string): Record => {
 		let r = records.get(id);
 		if (!r) {
-			r = { id, file, base: '', document: null, fileVersion, revision: 0, written: 0, inFlight: false, failure: null, refusal: null, by: null, elsewhere: false, timer: null };
+			r = { id, file, base: '', document: null, fileVersion, revision: 0, written: 0, inFlight: false, failure: null, refusal: null, by: null, elsewhere: false, timer: null, lastChange: 0, firstUnsent: null };
 			records.set(id, r);
 		}
 		return r;
@@ -402,6 +423,12 @@ export function createKeeper(options: KeeperOptions): Keeper {
 	const stash = (r: Record) => {
 		if (r.document) storage.set(r.id, { v: 1, file: r.file, base: r.base, document: r.document, fileVersion: r.fileVersion });
 	};
+	/** Decision 10 (live): ms until the change waiting goes, once the document is held: the delay after the last change, capped from the first unsent one. */
+	const due = (r: Record) => {
+		if (!live) return delay;
+		const at = Math.min(r.lastChange + live.delay, (r.firstUnsent ?? r.lastChange) + live.cap);
+		return Math.max(0, at - now());
+	};
 	const schedule = (r: Record, ms = delay) => {
 		if (r.timer !== null) clearTimer(r.timer);
 		r.timer = setTimer(() => {
@@ -447,6 +474,9 @@ export function createKeeper(options: KeeperOptions): Keeper {
 		if (!dirty(r) || !r.document) return;
 		if (r.inFlight) return; // the change waits; it's sent when this write returns
 		const revision = r.revision;
+		// Every change so far goes in this write; the cap counts again from the next one.
+		const firstUnsent = r.firstUnsent;
+		r.firstUnsent = null;
 		r.inFlight = true;
 		refresh();
 		let ok = false;
@@ -470,6 +500,7 @@ export function createKeeper(options: KeeperOptions): Keeper {
 			r.elsewhere = false;
 			if (typeof body.version === 'string') r.fileVersion = body.version;
 			r.written = Math.max(r.written, revision);
+			options.onKept?.(r.file);
 			if (dirty(r)) stash(r); // newer edits wait: they're now against the version just written
 			else storage.remove(r.id);
 		} catch (error) {
@@ -505,6 +536,8 @@ export function createKeeper(options: KeeperOptions): Keeper {
 			}
 		} finally {
 			r.inFlight = false;
+			// Not sent after all: the cap still counts from the earliest change waiting.
+			if (!ok && firstUnsent !== null) r.firstUnsent = Math.min(firstUnsent, r.firstUnsent ?? firstUnsent);
 			if (ok && !offline) {
 				stopRetry();
 				// Live mode: the server is back, so whatever else couldn't reach it goes now.
@@ -514,7 +547,12 @@ export function createKeeper(options: KeeperOptions): Keeper {
 			refresh();
 		}
 		// A change that came in during the write goes out now, unless its own timer is still running.
-		if (ok && dirty(r) && r.timer === null && !r.failure) void send(r);
+		// Live mode (Decision 10): it waits by the same rule as any change to a held document.
+		if (ok && dirty(r) && r.timer === null && !r.failure) {
+			const ms = live ? due(r) : 0;
+			if (ms > 0) schedule(r, ms);
+			else void send(r);
+		}
 	}
 
 	function adopt(id: string, stored: StoredUnsent): Record {
@@ -561,8 +599,15 @@ export function createKeeper(options: KeeperOptions): Keeper {
 			r.base = edit.base;
 			r.document = edit.document;
 			r.revision += 1;
+			const t = now();
+			r.lastChange = t;
+			if (r.firstUnsent === null) r.firstUnsent = t;
 			stash(r);
-			if (!r.failure || !WAITS.has(r.failure)) schedule(r);
+			if (!r.failure || !WAITS.has(r.failure)) {
+				// Decision 10: the first write to a document goes at once, since it's what takes the lock.
+				if (live && !r.inFlight && !live.holds(r.file)) schedule(r, 0);
+				else schedule(r, due(r));
+			}
 			// After a failed write (unreachable or refused), the next change retries everything waiting.
 			for (const other of records.values()) if (other !== r && other.failure && !WAITS.has(other.failure) && dirty(other)) schedule(other, 0);
 			refresh();

package/src/editor/client/state/live.ts

@@ -6,6 +6,12 @@
  * - **The poll**: `GET /_caracms/status?file=<the open document>` every `POLL_MS`
  *   while the tab is visible, and at once when it becomes visible again. It carries
  *   the tab's id, so it's also the lock's heartbeat and the tab's presence.
+ * - **Idle tabs slow down** (Redis diet Decision 8): a visible tab with no input for
+ *   `idleSlowAfterMs` polls every `slowPollMs`; any input, becoming visible, or a poll
+ *   answer showing someone else's lock on the open document (another person or another
+ *   tab) brings it back to `pollMs` at once. Each poll says how long until the next
+ *   (`interval`), so the server holds the tab's presence that long (Decision 9); the
+ *   next poll never comes later than the interval it sent.
  * - **Last-known data**: a poll that can't reach the server (a deploy replacing it,
  *   which Publish causes) keeps the last status and says `reachable: false`. Nothing
  *   is lost and nothing shows as an error; the next answer brings it back.
@@ -22,6 +28,10 @@ import { createStore, type Store } from './store.ts';
  */
 export const POLL_MS = 5000;
 
+/** Redis diet Decision 8's defaults, for a page whose props don't carry the live timings. */
+export const IDLE_SLOW_AFTER_MS = 2 * 60_000;
+export const SLOW_POLL_MS = 30_000;
+
 /** Where sign out goes (Phase 3's route): `{ ok, location }` to a JSON request. */
 export const SIGN_OUT = '/admin/login/signout';
 
@@ -98,6 +108,25 @@ export function createLiveSession(options: LiveOptions): LiveSession {
 	let lastInput = now();
 	let inFlight: Promise<void> | null = null;
 	let again = false;
+	const pollMs = options.props.pollMs ?? POLL_MS;
+	const slowPollMs = options.props.slowPollMs ?? SLOW_POLL_MS;
+	const idleSlowAfterMs = options.props.idleSlowAfterMs ?? IDLE_SLOW_AFTER_MS;
+	/** The interval the last poll sent: the next one comes no later (the server holds presence from it). */
+	let sentInterval = pollMs;
+	/** Set by start(): input while the loop runs slow brings it back to `pollMs` at once. */
+	let onInput: (() => void) | null = null;
+	const visible = () => typeof document === 'undefined' || document.visibilityState !== 'hidden';
+	/** Decision 8: the open document's lock is someone else's (another person, or another tab). */
+	const othersLock = () => {
+		const lock = state.get().status?.open?.lock;
+		return !!lock && lock.mine !== 'this-tab';
+	};
+	/** How long until the next poll, as things stand. */
+	const interval = () => (visible() && now() - lastInput >= idleSlowAfterMs && !othersLock() ? slowPollMs : pollMs);
+	const used = () => {
+		lastInput = now();
+		onInput?.();
+	};
 
 	const headers = (json: boolean): Record<string, string> => ({ Accept: 'application/json', [TAB_HEADER]: options.tab, ...(json ? { 'Content-Type': 'application/json' } : {}) });
 
@@ -125,7 +154,9 @@ export function createLiveSession(options: LiveOptions): LiveSession {
 		const mine = ++seq;
 		const file = options.openFile();
 		// `input`: ms since someone used this tab. The server stops renewing an idle tab's lock.
-		const query = new URLSearchParams({ ...(file ? { file } : {}), input: String(Math.max(0, Math.round(now() - lastInput))) });
+		// `interval`: ms until this tab's next poll (Redis diet Contracts): the server holds its presence from it.
+		sentInterval = interval();
+		const query = new URLSearchParams({ ...(file ? { file } : {}), input: String(Math.max(0, Math.round(now() - lastInput))), interval: String(sentInterval) });
 		const answer = await call<StatusResponse>(`${ENDPOINTS.status}?${query}`);
 		if (!answer) {
 			state.update({ reachable: false });
@@ -169,17 +200,22 @@ export function createLiveSession(options: LiveOptions): LiveSession {
 			let stopped = false;
 			/** One loop at a time: a restart starts a new generation, and the old one stops at its next turn. */
 			let generation = 0;
-			const visible = () => typeof document === 'undefined' || document.visibilityState !== 'hidden';
+			/** Whether the timer now running is a slow one (input then restarts at once). */
+			let slow = false;
 			const loop = (g: number) => {
 				if (stopped || g !== generation) return;
+				// Never later than the last poll said; sooner when the answer showed someone else's lock.
+				const ms = Math.min(sentInterval, interval());
+				slow = ms > pollMs;
 				timer = setTimer(async () => {
 					timer = null;
 					if (g !== generation) return;
 					if (visible()) await poll();
 					loop(g);
-				}, options.props.pollMs ?? POLL_MS);
+				}, ms);
 			};
 			const restart = () => {
+				slow = false;
 				const g = ++generation;
 				if (timer !== null) clearTimer(timer);
 				timer = null;
@@ -191,14 +227,17 @@ export function createLiveSession(options: LiveOptions): LiveSession {
 				lastInput = now(); // coming back to the tab counts as using it
 				restart();
 			};
-			const onActivity = () => {
-				lastInput = now();
+			const onActivity = () => used();
+			// Decision 8: input on a slowed tab polls now, and the loop is back to `pollMs`.
+			onInput = () => {
+				if (slow && !stopped) restart();
 			};
 			document.addEventListener('visibilitychange', onVisible);
 			for (const type of ACTIVITY_EVENTS) document.addEventListener(type, onActivity, { capture: true, passive: true });
 			restart();
 			return () => {
 				stopped = true;
+				onInput = null;
 				if (timer !== null) clearTimer(timer);
 				document.removeEventListener('visibilitychange', onVisible);
 				for (const type of ACTIVITY_EVENTS) document.removeEventListener(type, onActivity, { capture: true });
@@ -231,7 +270,7 @@ export function createLiveSession(options: LiveOptions): LiveSession {
 			await call(ENDPOINTS.notice, { method: 'POST', body: { id } });
 		},
 		active() {
-			lastInput = now();
+			used();
 		},
 		async takeOver(file) {
 			const answer = await call<LockResponse>(ENDPOINTS.lock, { method: 'POST', body: { file, action: 'take-over' } });

package/src/editor/middleware.ts

@@ -5,7 +5,7 @@
  *
  * Registered first (`addMiddleware({ order: 'pre' })` in ../index.ts), so it runs
  * before Phase 3's sign-in guard, which then only ever sees local or live mode.
- * Every other path passes straight through, and so does the public form endpoint,
+ * Every other path passes straight through, and so does a POST to the public form endpoint,
  * `/_caracms/form` (M6 Decision 5): the form is part of the public site, which works
  * without the editor.
  *
@@ -39,7 +39,8 @@ export const isEditorPath = (pathname: string) =>
 	(pathname === '/admin' || pathname.startsWith('/admin/') || pathname.startsWith('/_caracms/')) && !isFormEndpoint(pathname);
 
 export const onRequest: MiddlewareHandler = (context, next) => {
-	if (!isEditorPath(context.url.pathname)) return next();
+	// The form endpoint's POST is public; any other method to it is as unavailable as the rest (guard.ts's let-through is POST-only).
+	if (!isEditorPath(context.url.pathname) && !(isFormEndpoint(context.url.pathname) && context.request.method !== 'POST')) return next();
 	const mode = editorMode();
 	if (mode.kind !== 'unconfigured') {
 		if (context.url.pathname !== ENDPOINTS.preview || context.request.method !== 'GET') return next();

package/src/editor/routes/try-again.ts

@@ -1,5 +1,6 @@
 /**
- * POST /_caracms/try-again: redeploy a failed publish through Railway (Decision 12).
+ * POST /_caracms/try-again: redeploy a failed (or slow) publish through the redeployer:
+ * Railway's API or a deploy hook (M4 Decision 12; runs-anywhere Decision 11).
  * Live mode only (M4 Phase 2); the handler is ../../live/editor.ts → `tryAgain`. Shapes: ../types.ts.
  */
 import { liveRoute } from './_live.ts';

package/src/editor/server/admin-props.ts

@@ -109,7 +109,8 @@ async function liveProps(site: ResolvedSite, url: URL, file: string, person: Per
 	} catch (error) {
 		console.warn(`[caracms] /admin couldn't read the status for its first paint (${error instanceof Error ? error.message : String(error)}); the first poll fills it`);
 	}
-	return { you: person, status, pollMs: mode.settings.timings.pollMs };
+	const t = mode.settings.timings;
+	return { you: person, status, pollMs: t.pollMs, idleSlowAfterMs: t.idleSlowAfterMs, slowPollMs: t.slowPollMs, keepDelayMs: t.keepDelayMs, keepCapMs: t.keepCapMs };
 }
 
 /**

package/src/editor/server/mode.ts

@@ -1,7 +1,7 @@
 /**
  * The editor's mode at run time (M4 Decision 1), and the drafts store it implies.
  *
- * - `editorMode()`: `readMode(process.env, isProductionServer())`, read once per
+ * - `editorMode()`: `readMode(process.env, isProductionServer(), bakedAtBuild())`, read once per
  *   process. **A production server is the build**, not `NODE_ENV`: the integration
  *   sets `__CARACMS_PRODUCTION__` (a Vite define) to `command !== 'dev'`, so the
  *   built server is always live mode (or unconfigured), and `astro dev` is local
@@ -14,16 +14,26 @@
  */
 import type { ResolvedSite } from '../../config.ts';
 import { liveEditor, type LiveEditor } from '../../live/editor.ts';
-import { readMode, unconfiguredMessage, type Mode } from '../../live/mode.ts';
+import { readMode, unconfiguredMessage, type Baked, type Mode } from '../../live/mode.ts';
 import { localDraftsStore, type DraftsStore } from './drafts-store.ts';
 
 declare const __CARACMS_PRODUCTION__: boolean | undefined;
+declare const __CARACMS_SITE__: string | null | undefined;
+declare const __CARACMS_BUILD_COMMIT__: string | null | undefined;
 
 /** True in the built server (`astro build`), false under `astro dev` and in plain Node (tests). */
 export function isProductionServer(): boolean {
 	return typeof __CARACMS_PRODUCTION__ === 'boolean' ? __CARACMS_PRODUCTION__ : false;
 }
 
+/** The site's address and the commit the build baked in (runs-anywhere Decisions 7 and 9); empty in plain Node (tests). */
+export function bakedAtBuild(): Baked {
+	return {
+		site: typeof __CARACMS_SITE__ === 'string' ? __CARACMS_SITE__ : null,
+		commit: typeof __CARACMS_BUILD_COMMIT__ === 'string' ? __CARACMS_BUILD_COMMIT__ : null,
+	};
+}
+
 const SHARED = Symbol.for('caracms.editorMode');
 type Shared = { [SHARED]?: Mode };
 
@@ -31,7 +41,7 @@ type Shared = { [SHARED]?: Mode };
 export function editorMode(): Mode {
 	const g = globalThis as Shared;
 	if (!g[SHARED]) {
-		const mode = readMode(process.env, isProductionServer());
+		const mode = readMode(process.env, isProductionServer(), bakedAtBuild());
 		if (mode.kind === 'unconfigured') console.error(`[caracms] ${unconfiguredMessage(mode)} The public site is served; /admin answers 503.`);
 		g[SHARED] = mode;
 	}

package/src/editor/styles/editor.css

@@ -215,6 +215,8 @@ details.fgroup[open]>summary .i{rotate:90deg}
 details.fgroup>.in{padding:0 var(--space-4) var(--space-2)}
 details.fgroup>summary .wmark{margin-left:var(--space-1)}
 details.fgroup>summary .wmark .i{margin-left:0;rotate:none}
+/* M9 Decision 7: the page's "Hidden from the site" switch, between its page fields and Search and sharing. */
+.page-hidden{margin-top:var(--space-4)}
 /* A group field (group()): Page details' section, among a form's fields; inside a list item it keeps to the item's width. */
 details.fgroup.group-field{margin-block:var(--space-3)}
 details.fgroup.group-field+details.fgroup.group-field{margin-top:calc(-1 * var(--space-3))}

package/src/editor/styles/levels/live.css

@@ -6,5 +6,5 @@
 .mk{display:contents}
 fieldset.ro-fields{display:contents;margin:0;padding:0;border:0;min-width:0}
 .note .acts .why{flex-basis:100%;margin:0;font-size:var(--text-xs);color:var(--text-subtle)}
-/* Failed with no Railway token (a state M4 adds): Publish is off, so it takes the off ink, not the failure's red (1.9:1 on the off fill). */
+/* Failed (or taking longer than usual) with no redeployer (a state M4 adds): Publish is off, so it takes the off ink, not the failure's red (1.9:1 on the off fill). */
 .pub.fail .pb.off{color:var(--bar-off-text)}

package/src/editor/types.ts

@@ -205,6 +205,14 @@ export interface LiveProps {
 	status: StatusResponse | null;
 	/** How often the tab polls (live timings' `pollMs`: POLL_MS, shorter only in tests). */
 	pollMs?: number;
+	/** Redis diet Decision 8: a visible tab with no input this long polls at `slowPollMs` (live timings'; absent: 2 minutes). */
+	idleSlowAfterMs?: number;
+	/** Redis diet Decision 8: an idle tab's poll interval (absent: 30 s). */
+	slowPollMs?: number;
+	/** Redis diet Decision 10: once the tab holds the document, a keep goes this long after the last change (absent: 3 s). */
+	keepDelayMs?: number;
+	/** Redis diet Decision 10: …and never later than this after the first change not yet sent (absent: 15 s). */
+	keepCapMs?: number;
 }
 
 /** A block in the editor: a DocumentBlock plus a key that stays with it through moves (never written). */
@@ -235,6 +243,8 @@ export interface EditorDocument {
 	 * has page fields. Set through `setField(PAGE_SCOPE, …)` (document-store.ts).
 	 */
 	data?: Record<string, unknown>;
+	/** M9 Decision 7: a section builder hidden from the site; absent when the file isn't. Set through `setHidden`. */
+	hidden?: boolean;
 }
 
 /** The preview widths (M2 Decision 3): each iframe at its true width. */
@@ -429,17 +439,21 @@ export interface PublishRecordView {
 }
 
 export interface PublishView {
-	/** `none`: nothing published since the record began. */
-	state: 'none' | 'publishing' | 'live' | 'failed';
+	/**
+	 * `none`: nothing published since the record began. `slow` (runs-anywhere Decision 10):
+	 * still not live 15 minutes after it was made or last tried again, with no failure
+	 * known: "taking longer than usual. It may have failed."
+	 */
+	state: 'none' | 'publishing' | 'live' | 'failed' | 'slow';
 	/** A Publish is running now (committing, or moving the refs), before any record. */
 	running: boolean;
 	record: PublishRecordView | null;
 	/** Live only because there's no deploy pipeline (Decision 12). */
 	assumed: boolean;
-	/** Failed, and Try again can redeploy. */
+	/** Failed or slow, and Try again can redeploy. */
 	canTryAgain: boolean;
-	/** CARACMS_RAILWAY_TOKEN is set. Failed with no token: "a developer can redeploy from Railway". */
-	hasToken: boolean;
+	/** A redeployer is set (a deploy hook, or Railway's token). Failed with none: "A developer can redeploy it" (runs-anywhere Decision 11). */
+	hasRedeployer: boolean;
 }
 
 /** GET /_caracms/status?file=<open document's file> (Decision 13). */
@@ -468,6 +482,13 @@ export interface StatusResponse {
 	presence: PresenceView[];
 	notices: NoticeView[];
 	publish: PublishView;
+	/**
+	 * Runs-anywhere Decision 5: what's wrong with the site's GitHub access, for every
+	 * person, while it holds (not dismissable, unlike `notices`): a refused credential, a
+	 * missing permission, or a token expiring within 14 days. `message` names the fix,
+	 * for the developer it's forwarded to. Null when nothing is wrong.
+	 */
+	githubAccess: { kind: 'refused' | 'permission' | 'expiring'; title: string; message: string } | null;
 	/**
 	 * The brand as committed in Site Settings (M5a Decision 10: read from `drafts`, never
 	 * an autosave), so the chrome picks up a change on the next poll with no reload.
@@ -498,7 +519,7 @@ export interface HistoryEntryView {
 	at: string;
 	titles: string[];
 	files: string[];
-	state: 'publishing' | 'live' | 'failed';
+	state: 'publishing' | 'live' | 'failed' | 'slow';
 }
 /** GET /_caracms/history. */
 export interface HistoryResponse {

package/src/fields.ts

@@ -7,6 +7,7 @@
  *
  *   text()                     one line
  *   text({ multiline: true })  several lines; a break is stored as `\n` (the line-break rule)
+ *   text({ lines: true })      several lines, each drawn as its own element (M9 Decision 10)
  *   text({ max: 200 })         M6: a soft limit, counted in the editor and amber past it (nothing refused)
  *   lockup({ style })          display text set as lines, optionally with phone lines (Decisions 10–11)
  *   select({ options })        one of a fixed list
@@ -24,7 +25,7 @@
  *
  * M5b (Decision 3) adds:
  *
- *   media({ only?, play? })          an image `{ key, alt, … }` or a Mux clip `{ video, play, … }` (media-value.ts)
+ *   media({ only?, play?, format? }) an image `{ key, alt, … }` or a Mux clip `{ video, play, … }` (media-value.ts)
  *
  * M6c adds `help` (G8: plain text under the field in the sidebar) to every helper, and
  * `link({ addressOnly: true })` (G9): `{ "href" }`, a link with no words of its own.
@@ -47,9 +48,9 @@
  */
 import { fileAddress, fileKeyOf, fileTypeOf, isFileKey } from './files.ts';
 import { codeRouteAt, type CodeRoute } from './code-routes.ts';
-import { internalLinkPath, isLinkHref, missingLinkTarget, validateLink } from './links.ts';
+import { hiddenLinkTarget, hiddenReferenceTarget, internalLinkPath, isLinkHref, missingLinkTarget, validateLink } from './links.ts';
 import { MISSING_ALT_MESSAGE, mediaKind, mediaToJson, parseMedia, renderMedia, type MediaOnly, type MediaValue, type RenderMedia } from './media-value.ts';
-import { readRichText, richTextHrefs, serializeRichText, type HeadingKind, type RichTextValue } from './rich-text.ts';
+import { readRichText, richTextHrefs, serializeRichText, type HeadingKind, type RichTextOptions, type RichTextValue } from './rich-text.ts';
 
 export type { RichTextValue } from './rich-text.ts';
 export type { ClipValue, ImageValue, MediaOnly, MediaValue, PlayAs, RenderClip, RenderImage, RenderMedia } from './media-value.ts';
@@ -80,7 +81,12 @@ export interface TextField extends FieldBase {
 	 * M6: a soft limit (the Form block's intro, Decision 17): the editor counts the
 	 * characters and turns amber past it. Nothing is refused: it's kept as written.
 	 */
-	max?: number;
+	max?: number;	/**
+	 * M9 Decision 10: the lines rendering. Each typed line draws as its own element (Text's
+	 * `lineClass`), blank lines draw nothing, and a single line draws unwrapped. Always
+	 * multiline: a break is still stored as `\n`.
+	 */
+	lines?: true;
 }
 
 export interface LockupField extends FieldBase {
@@ -108,6 +114,12 @@ export interface RichTextField extends FieldBase {
 	headings: readonly HeadingKind[];
 	/** Links allowed (default true). */
 	links: boolean;
+	/**
+	 * M9 Decision 11: the block's heading, typed on the page with bold and line breaks only.
+	 * It can hold the page's `h1` (M3 Decision 16) and draws inside its heading tag, its
+	 * paragraphs as lines joined by `<br>`. No headings, no links, no lists, no italic.
+	 */
+	heading?: true;
 }
 
 export interface LinkField extends FieldBase {
@@ -200,14 +212,19 @@ export interface ReferenceField extends FieldBase {
 /**
  * A media slot (M5b Decision 3): an image or a Mux clip. `only` limits it to one
  * kind (a value of the other is kept and warned); `play: 'loop'` makes it loop-only
- * (the hero): any clip in it renders as a loop.
+ * (the hero): any clip in it renders as a loop. `format: 'png'` serves its images as
+ * PNG instead of WebP (M9 Decision 8: WebP smears flat artwork).
  */
 export interface MediaField extends FieldBase {
 	kind: 'media';
 	only?: MediaOnly;
 	play?: 'loop';
+	format?: ImageFormat;
 }
 
+/** The format a resized image is served in (M9 Decision 8). WebP unless a media field asks for PNG. */
+export type ImageFormat = 'webp' | 'png';
+
 export type Field =
 	| TextField
 	| LockupField
@@ -288,9 +305,10 @@ export type BlockData<F extends Fields> = { [K in keyof F]: FieldValue<F[K]> };
 
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
-export function text(options: { label?: string; help?: string; multiline?: boolean; heading?: boolean; max?: number } = {}): TextField {
-	const field: TextField = { kind: 'text', label: options.label, multiline: options.multiline ?? false, heading: options.heading ?? false };
+export function text(options: { label?: string; help?: string; multiline?: boolean; heading?: boolean; max?: number; lines?: boolean } = {}): TextField {
+	const field: TextField = { kind: 'text', label: options.label, multiline: options.multiline ?? options.lines ?? false, heading: options.heading ?? false };
 	if (options.max !== undefined) field.max = options.max;
+	if (options.lines) field.lines = true;
 	return withHelp(field, options);
 }
 
@@ -316,9 +334,14 @@ export function select<const V extends string>(options: {
 	return withHelp({ kind: 'select', label: options.label, options: list, default: fallback }, options);
 }
 
-/** Rich text (Decision 3). `headings`: `['h2']` or `['h2', 'h3']`, off by default. `links`: on by default. */
-export function richText(options: { label?: string; help?: string; headings?: readonly HeadingKind[]; links?: boolean } = {}): RichTextField {
-	return withHelp({ kind: 'richText', label: options.label, headings: [...(options.headings ?? [])], links: options.links ?? true }, options);
+/**
+ * Rich text (Decision 3). `headings`: `['h2']` or `['h2', 'h3']`, off by default. `links`: on by default.
+ * `heading: true` (M9 Decision 11): the block's heading, bold and line breaks only (links off).
+ */
+export function richText(options: { label?: string; help?: string; headings?: readonly HeadingKind[]; links?: boolean; heading?: boolean } = {}): RichTextField {
+	const field: RichTextField = { kind: 'richText', label: options.label, headings: [...(options.headings ?? [])], links: options.links ?? !options.heading };
+	if (options.heading) field.heading = true;
+	return withHelp(field, options);
 }
 
 /**
@@ -399,12 +422,14 @@ export function group<const F extends Fields>(fields: F, options: { label?: stri
 
 /**
  * An image or a clip (M5b Decision 3). `only: 'image'` or `'video'` takes one kind;
- * `play: 'loop'` makes the slot loop-only (a clip in it always plays as a loop).
+ * `play: 'loop'` makes the slot loop-only (a clip in it always plays as a loop);
+ * `format: 'png'` serves its images as PNG (M9 Decision 8).
  */
-export function media(options: { label?: string; help?: string; only?: MediaOnly; play?: 'loop' } = {}): MediaField {
+export function media(options: { label?: string; help?: string; only?: MediaOnly; play?: 'loop'; format?: ImageFormat } = {}): MediaField {
 	const field: MediaField = { kind: 'media', label: options.label };
 	if (options.only !== undefined) field.only = options.only;
 	if (options.play !== undefined) field.play = options.play;
+	if (options.format !== undefined) field.format = options.format;
 	return withHelp(field, options);
 }
 
@@ -444,7 +469,7 @@ export function parseDay(value: unknown): string | null {
 	return at.getUTCFullYear() === y && at.getUTCMonth() === mo - 1 && at.getUTCDate() === d ? m[0]! : null;
 }
 
-const richTextOptions = (field: RichTextField) => ({ headings: field.headings, links: field.links });
+export const richTextOptions = (field: RichTextField): RichTextOptions => ({ headings: field.headings, links: field.links, ...(field.heading ? { heading: true } : {}) });
 
 function parseButton(field: ButtonsField, raw: Record<string, unknown>): ButtonValue {
 	const style = typeof raw.style === 'string' && field.styles.some((o) => o.value === raw.style) ? raw.style : field.styles[0]!.value;
@@ -732,12 +757,18 @@ export type FieldWarningCode =
 	| 'disallowed-kind'
 	/** Rich text: a link where the field has links off, shown as its text. */
 	| 'link-off'
+	/** Rich text: italic in a heading rich-text field (M9 Decision 11), shown as plain text. */
+	| 'italic-off'
 	/** A value (or a rich-text entry) the field can't read: shown as empty, kept until the field is edited. */
 	| 'unreadable'
 	/** A link that fails the link rule (Decision 4): shown as text. */
 	| 'link-rule'
 	/** An internal link to a path no document has (Decision 4). */
 	| 'link-missing'
+	/** M9 Decision 7: an internal link to a page hidden from the site. */
+	| 'link-hidden'
+	/** M9 Decision 7: a reference to a page hidden from the site (a warning, as `link-hidden` is). */
+	| 'reference-hidden'
 	/** A link or button with only one of its label and its link: shows nothing. */
 	| 'half-link'
 	/** More buttons than the field's `max`: the extra ones don't show. */
@@ -782,6 +813,13 @@ export interface WarningContext {
 	 * address under it, since which ones it builds isn't known from its file name.
 	 */
 	codeRoutes?: readonly CodeRoute[];
+	/** M9 Decision 7: hidden pages, their address (normalised) to their name. A link to one warns. */
+	hiddenPages?: ReadonlyMap<string, string>;
+	/**
+	 * M9 Decision 7: hidden documents, `collection/path` to their name and address (links.ts
+	 * `hiddenDocuments`). A reference to one warns.
+	 */
+	hiddenDocuments?: ReadonlyMap<string, { label: string; url: string | null }>;
 }
 
 const join = (base: string, part: string | number) => (base === '' ? String(part) : `${base}.${part}`);
@@ -804,6 +842,11 @@ function hrefWarnings(href: string, path: string, context: WarningContext, out:
 	if (context.addresses) {
 		const target = internalLinkPath(href);
 		if (target !== null && codeRouteAt(target, context.codeRoutes)) return;
+		const hidden = context.hiddenPages && hiddenLinkTarget(href, context.hiddenPages);
+		if (hidden) {
+			out.push({ path, code: 'link-hidden', message: hidden });
+			return;
+		}
 		const missing = missingLinkTarget(href, context.addresses);
 		if (missing) out.push({ path, code: 'link-missing', message: missing });
 	}
@@ -834,6 +877,8 @@ export function fieldWarnings(field: Field, raw: unknown, context: WarningContex
 						code: 'disallowed-kind',
 						message: `${issue.kind === 'h1' ? 'An h1' : `A${/^[aeiouh]/i.test(issue.kind) ? 'n' : ''} ${issue.kind}`} isn't allowed in this field, so it shows as a paragraph.`,
 					});
+				} else if (issue.code === 'italic-off') {
+					out.push({ path: at, code: 'italic-off', message: 'This heading takes bold only, so italic here shows as plain text.' });
 				} else if (issue.code === 'link-off') {
 					out.push({
 						path: at,
@@ -898,6 +943,9 @@ export function fieldWarnings(field: Field, raw: unknown, context: WarningContex
 			const v = parseField(field, raw) as string | null;
 			if (v !== null && context.documentExists && !context.documentExists(field.to, v)) {
 				out.push({ path, code: 'missing-reference', message: `This points at "${v}", which isn't in ${titleCase(field.to)} any more.` });
+			} else if (v !== null && context.hiddenDocuments) {
+				const message = hiddenReferenceTarget(field.to, v, context.hiddenDocuments);
+				if (message) out.push({ path, code: 'reference-hidden', message });
 			}
 			break;
 		}
@@ -987,12 +1035,12 @@ export const isKeyPath = (path: string) => path !== '' && !splitPath(path).some(
 
 /**
  * The fields that can hold the page's heading (M3 Decision 16: a lockup, or a text
- * field marked `heading`), as paths, in the order they're tried: the top-level ones in
+ * or rich-text field marked `heading`, M9 Decision 11), as paths, in the order they're tried: the top-level ones in
  * schema order, then those inside groups (`left.heading`), groups in schema order. A
  * top-level heading always comes before a group's.
  */
 export function headingPaths(fields: Fields): string[] {
-	const isHeading = (field: Field) => (field.kind === 'lockup' || field.kind === 'text') && !!field.heading;
+	const isHeading = (field: Field) => (field.kind === 'lockup' || field.kind === 'text' || field.kind === 'richText') && !!field.heading;
 	const top = Object.entries(fields).filter(([, f]) => isHeading(f)).map(([key]) => key);
 	const grouped = Object.entries(fields).flatMap(([key, f]) => (f.kind === 'group' ? Object.entries(f.fields).filter(([, g]) => isHeading(g)).map(([sub]) => `${key}.${sub}`) : []));
 	return [...top, ...grouped];