caracms 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,257 @@
+/**
+ * Live mode's connection to the server (M4 Decisions 9, 11 and 13): the status poll
+ * and the calls the bar and the pane make (Publish, Try again, history, a notice's
+ * Dismiss, Edit here, Sign out). Local mode never makes one (M3's editor).
+ *
+ * - **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.
+ * - **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.
+ * - **Signed out**: any 401 (`SignedOutError`) sets `signedOut`; the next poll that
+ *   answers 200 clears it (signing in from another tab brings the session back).
+ */
+import { ENDPOINTS, TAB_HEADER, type HistoryResponse, type LiveProps, type LockRefusal, type LockResponse, type PublishResponse, type SignedOutError, type StatusResponse, type TryAgainResponse } from '../../types.ts';
+import { createStore, type Store } from './store.ts';
+
+/**
+ * Decision 13: every 5 s while the tab is visible. (The spec's Open questions may
+ * shorten it to 3 s while someone else is on the same document; not done unless
+ * Rich says so.)
+ */
+export const POLL_MS = 5000;
+
+/** Where sign out goes (Phase 3's route): `{ ok, location }` to a JSON request. */
+export const SIGN_OUT = '/admin/login/signout';
+
+export interface LiveState {
+	/** The last status the server gave (the page's own, from the server, until the first poll). */
+	status: StatusResponse | null;
+	/** The last poll got an answer. False while the server can't be reached (a deploy, say). */
+	reachable: boolean;
+	/** The session ended (a 401), until a poll answers 200 again. */
+	signedOut: SignedOutError | null;
+	/** This tab's own poll has answered: the page's first status had no tab, so its locks of yours can't say which tab. */
+	polled: boolean;
+	/** Which poll this answer came from (they're numbered as they start). */
+	seq: number;
+}
+
+export interface LiveSession {
+	readonly tab: string;
+	readonly state: Store<LiveState>;
+	/** How many polls have started: a lock answer newer than this outranks the poll in flight. */
+	started(): number;
+	poll(): Promise<void>;
+	/** Browser only: the poll loop and the visibility listener. Returns a stop. */
+	start(): () => void;
+	/** The server's answer, or why it didn't publish (a non-200, or the server out of reach): a failure is never shown as published. */
+	publish(): Promise<{ ok: true; body: PublishResponse } | { ok: false; error: string }>;
+	tryAgain(): Promise<TryAgainResponse>;
+	history(): Promise<HistoryResponse | null>;
+	dismiss(id: string): Promise<void>;
+	/** Edit here: take the open document's lock (moves your own at once). */
+	take(file: string): Promise<{ ok: true; lock: LockResponse } | { ok: false; refusal: LockRefusal | null }>;
+	/** Take over: move anyone's lock on the document to this tab (their autosave is committed first). */
+	takeOver(file: string): Promise<{ ok: true; lock: LockResponse } | { ok: false }>;
+	/** Someone typed, clicked or scrolled in this tab: each poll says how long ago (the lock's idle rule). */
+	active(): void;
+	signOut(): Promise<string>;
+}
+
+export interface LiveOptions {
+	fetch: typeof fetch;
+	props: LiveProps;
+	tab: string;
+	/** The open document's file, named by every poll. */
+	openFile: () => string | null;
+	now?: () => number;
+	setTimer?: (fn: () => void, ms: number) => unknown;
+	clearTimer?: (timer: unknown) => void;
+	log?: (message: string) => void;
+}
+
+/** The tab's id: kept for the tab's life in sessionStorage, so a reload is the same tab (its lock stays its own). */
+export function tabId(): string {
+	const make = () => (typeof crypto !== 'undefined' && 'randomUUID' in crypto ? crypto.randomUUID() : `t${Date.now().toString(36)}${Math.random().toString(36).slice(2)}`);
+	try {
+		const s = window.sessionStorage;
+		let id = s.getItem('caracms:tab');
+		if (!id) s.setItem('caracms:tab', (id = make()));
+		return id;
+	} catch {
+		return make();
+	}
+}
+
+/** What counts as someone using the tab, in the editor and in the previews (the lock's idle rule). */
+export const ACTIVITY_EVENTS = ['keydown', 'pointerdown', 'wheel', 'input'] as const;
+
+export function createLiveSession(options: LiveOptions): LiveSession {
+	const setTimer = options.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+	const clearTimer = options.clearTimer ?? ((t) => clearTimeout(t as ReturnType<typeof setTimeout>));
+	const log = options.log ?? ((message) => console.warn(`[caracms] ${message}`));
+	const state = createStore<LiveState>({ status: options.props.status, reachable: true, signedOut: null, polled: false, seq: 0 });
+	let seq = 0;
+	const now = options.now ?? (() => Date.now());
+	let lastInput = now();
+	let inFlight: Promise<void> | null = null;
+	let again = false;
+
+	const headers = (json: boolean): Record<string, string> => ({ Accept: 'application/json', [TAB_HEADER]: options.tab, ...(json ? { 'Content-Type': 'application/json' } : {}) });
+
+	/** A call to an editor route: the answer's body, or null when the server couldn't be reached. A 401 marks the session ended. */
+	async function call<T>(path: string, init: { method?: string; body?: unknown } = {}): Promise<{ status: number; body: T } | null> {
+		try {
+			const response = await options.fetch(path, {
+				method: init.method ?? 'GET',
+				headers: headers(init.body !== undefined),
+				body: init.body === undefined ? undefined : JSON.stringify(init.body),
+			});
+			const body = (await response.json().catch(() => ({}))) as T;
+			if (response.status === 401) {
+				const b = body as unknown as Partial<SignedOutError>;
+				state.update({ signedOut: { error: b.error ?? 'signed-out', code: 'signed-out', reason: b.reason === 'removed' ? 'removed' : 'signed-out', signIn: b.signIn ?? '/admin/login' }, reachable: true });
+			}
+			return { status: response.status, body };
+		} catch (error) {
+			log(`${path}: ${error instanceof Error ? error.message : String(error)}`);
+			return null;
+		}
+	}
+
+	async function pollOnce(): Promise<void> {
+		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))) });
+		const answer = await call<StatusResponse>(`${ENDPOINTS.status}?${query}`);
+		if (!answer) {
+			state.update({ reachable: false });
+			return;
+		}
+		if (answer.status === 200 && answer.body && (answer.body as StatusResponse).mode === 'live') {
+			state.set((s) => ({ ...s, status: answer.body, reachable: true, signedOut: null, polled: true, seq: mine }));
+		} else if (answer.status === 401) {
+			// call() marked it.
+		} else if (answer.status >= 500 || answer.status === 404) {
+			// 503 unavailable (Redis), a deploy's gap, or the route not there yet: the server isn't answering for now.
+			state.update({ reachable: false });
+		}
+	}
+
+	async function poll(): Promise<void> {
+		if (inFlight) {
+			again = true;
+			return inFlight;
+		}
+		inFlight = (async () => {
+			try {
+				do {
+					again = false;
+					await pollOnce();
+				} while (again);
+			} finally {
+				inFlight = null;
+			}
+		})();
+		return inFlight;
+	}
+
+	const session: LiveSession = {
+		tab: options.tab,
+		state,
+		started: () => seq,
+		poll,
+		start() {
+			let timer: unknown = null;
+			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';
+			const loop = (g: number) => {
+				if (stopped || g !== generation) return;
+				timer = setTimer(async () => {
+					timer = null;
+					if (g !== generation) return;
+					if (visible()) await poll();
+					loop(g);
+				}, options.props.pollMs ?? POLL_MS);
+			};
+			const restart = () => {
+				const g = ++generation;
+				if (timer !== null) clearTimer(timer);
+				timer = null;
+				void poll().finally(() => loop(g));
+			};
+			// Visible again: at once (Decision 13). The lock is re-taken by that poll if nobody else has it (Decision 9).
+			const onVisible = () => {
+				if (!visible()) return;
+				lastInput = now(); // coming back to the tab counts as using it
+				restart();
+			};
+			const onActivity = () => {
+				lastInput = now();
+			};
+			document.addEventListener('visibilitychange', onVisible);
+			for (const type of ACTIVITY_EVENTS) document.addEventListener(type, onActivity, { capture: true, passive: true });
+			restart();
+			return () => {
+				stopped = true;
+				if (timer !== null) clearTimer(timer);
+				document.removeEventListener('visibilitychange', onVisible);
+				for (const type of ACTIVITY_EVENTS) document.removeEventListener(type, onActivity, { capture: true });
+			};
+		},
+		async publish() {
+			const answer = await call<PublishResponse>(ENDPOINTS.publish, { method: 'POST', body: {} });
+			void poll();
+			if (!answer) return { ok: false, error: "The server couldn't be reached." };
+			if (answer.status !== 200 || !answer.body?.publish) {
+				const said = (answer.body as unknown as { error?: unknown } | null)?.error;
+				return { ok: false, error: typeof said === 'string' && said ? said : `The server answered ${answer.status}.` };
+			}
+			state.set((s) => (s.status ? { ...s, status: { ...s.status, publish: answer.body.publish } } : s));
+			return { ok: true, body: answer.body };
+		},
+		async tryAgain() {
+			const answer = await call<TryAgainResponse>(ENDPOINTS.tryAgain, { method: 'POST', body: {} });
+			void poll();
+			if (!answer) return { ok: false, error: "Couldn't reach the server." };
+			return answer.body;
+		},
+		async history() {
+			const answer = await call<HistoryResponse>(ENDPOINTS.history);
+			return answer && answer.status === 200 ? answer.body : null;
+		},
+		async dismiss(id) {
+			// Gone at once; the server agrees on the next poll.
+			state.set((s) => (s.status ? { ...s, status: { ...s.status, notices: s.status.notices.filter((n) => n.id !== id) } } : s));
+			await call(ENDPOINTS.notice, { method: 'POST', body: { id } });
+		},
+		active() {
+			lastInput = now();
+		},
+		async takeOver(file) {
+			const answer = await call<LockResponse>(ENDPOINTS.lock, { method: 'POST', body: { file, action: 'take-over' } });
+			void poll();
+			return answer?.status === 200 ? { ok: true, lock: answer.body } : { ok: false };
+		},
+		async take(file) {
+			const answer = await call<LockResponse | LockRefusal>(ENDPOINTS.lock, { method: 'POST', body: { file, action: 'take' } });
+			if (answer?.status === 200) return { ok: true, lock: answer.body as LockResponse };
+			return { ok: false, refusal: answer?.status === 409 ? (answer.body as LockRefusal) : null };
+		},
+		async signOut() {
+			try {
+				const response = await options.fetch(SIGN_OUT, { method: 'POST', headers: { Accept: 'application/json' } });
+				const body = (await response.json().catch(() => ({}))) as { location?: string };
+				return body.location ?? '/admin/login';
+			} catch {
+				return '/admin/login';
+			}
+		},
+	};
+	return session;
+}

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

@@ -0,0 +1,42 @@
+/**
+ * The fields a block of the open document has (M5a Phase 5): a block's schema in a
+ * section builder or a shared block, or, for the one block a fields document or Site
+ * Settings is held as (document-store.ts), its collection's fields. Pure, so the
+ * overlays, the page's typing and the driver read the same thing.
+ */
+import { EDITORS_FIELD, own } from '../../../document.ts';
+import type { Fields } from '../../../fields.ts';
+import type { EditorDocument, EditorSite } from '../../types.ts';
+
+
+/** The fields of a fields document's collection, or of Site Settings (the site's own `settings.fields`). */
+export function formFields(site: Pick<EditorSite, 'collections'>, collection: string): Fields {
+	return site.collections.find((c) => c.name === collection)?.fields ?? {};
+}
+
+/** The block types `collection`'s pages offer (config.ts `blocks`): null for every block. */
+export function offeredBlocks(site: Pick<EditorSite, 'collections'>, collection: string): readonly string[] | null {
+	return site.collections.find((c) => c.name === collection)?.blocks ?? null;
+}
+
+/** Whether `collection`'s pages offer blocks of `type` (always, when it names none). */
+export function offersBlock(site: Pick<EditorSite, 'collections'>, collection: string, type: string): boolean {
+	const offered = offeredBlocks(site, collection);
+	return !offered || offered.includes(type);
+}
+
+/**
+ * The fields the block `blockType` has in a document of `kind` from `collection`: a
+ * form's (fields, settings) are its collection's; a block's are its type's schema.
+ */
+export function fieldsOfBlock(
+	site: Pick<EditorSite, 'blocks' | 'collections'>,
+	document: Pick<EditorDocument, 'kind'>,
+	collection: string,
+	block: { type: string; known: boolean },
+): Fields {
+	if (document.kind === 'fields') return formFields(site, collection);
+	if (document.kind === 'settings') return { editors: EDITORS_FIELD, ...formFields(site, collection) };
+	if (!block.known) return {};
+	return own(site.blocks, block.type)?.fields ?? {};
+}

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

@@ -0,0 +1,39 @@
+/**
+ * A tiny observable value: the editor's state containers are built on it, and
+ * React reads them with `useStore` (context.tsx → useSyncExternalStore). Values are
+ * replaced, never mutated, so a snapshot is stable until the next `set`.
+ */
+export interface Store<T> {
+	get(): T;
+	set(next: T | ((previous: T) => T)): void;
+	/** Merge into an object value. */
+	update(patch: Partial<T>): void;
+	subscribe(listener: (value: T, previous: T) => void): () => void;
+}
+
+export function createStore<T>(initial: T): Store<T> {
+	let value = initial;
+	const listeners = new Set<(value: T, previous: T) => void>();
+	const store: Store<T> = {
+		get: () => value,
+		set(next) {
+			const previous = value;
+			value = typeof next === 'function' ? (next as (p: T) => T)(previous) : next;
+			if (Object.is(value, previous)) return;
+			for (const listener of [...listeners]) listener(value, previous);
+		},
+		update(patch) {
+			store.set((previous) => {
+				for (const key of Object.keys(patch) as (keyof T)[]) {
+					if (!Object.is(previous[key], patch[key])) return { ...previous, ...patch };
+				}
+				return previous;
+			});
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => listeners.delete(listener);
+		},
+	};
+	return store;
+}

package/src/editor/fonts/OFL-GeistMono.txt

@@ -0,0 +1,93 @@
+Copyright 2024 The Geist Project Authors (https://github.com/vercel/geist-font.git) GeistMono-Italic[wght].ttf: Copyright 2024 The Geist Project Authors (https://github.com/vercel/geist-font.git)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/src/editor/fonts/OFL-InstrumentSans.txt

@@ -0,0 +1,93 @@
+Copyright 2022 The Instrument Sans Project Authors (https://github.com/Instrument/instrument-sans) InstrumentSans-Italic[wdth,wght].ttf: Copyright 2022 The Instrument Sans Project Authors (https://github.com/Instrument/instrument-sans)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/src/editor/middleware.ts

@@ -0,0 +1,62 @@
+/**
+ * The unconfigured server's answer (M4 Decision 1): a production server missing a
+ * required variable still serves the public site, while `/admin` and `/_caracms/*`
+ * answer 503 with a plain sentence naming what's missing (logged once, server/mode.ts).
+ *
+ * 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,
+ * `/_caracms/form` (M6 Decision 5): the form is part of the public site, which works
+ * without the editor.
+ *
+ * It also marks the preview route's pages (M8 review): a 200 HTML answer to the preview's GET
+ * gets `data-caracms-preview` on its `<html>` (types.ts → PREVIEW_MARK), the one sign the
+ * driver has that a frame loaded a preview and not an error page. The site's page component
+ * writes the `<html>`, so the route itself can't. Everything else, a POST's render included
+ * (only its body is morphed), passes untouched.
+ */
+import type { MiddlewareHandler } from 'astro';
+import { isFormEndpoint } from '../live/auth/guard.ts';
+import { unconfiguredMessage } from '../live/mode.ts';
+import { editorMode } from './server/mode.ts';
+import { ENDPOINTS, PREVIEW_MARK } from './types.ts';
+
+/** `html` with the preview's mark on its `<html>` (one is added after the doctype when the page has none). */
+export function markPreviewHtml(html: string): string {
+	if (/<html\b/i.test(html)) return html.replace(/<html\b/i, `<html ${PREVIEW_MARK}`);
+	const doctype = /^\s*<!doctype[^>]*>/i.exec(html)?.[0] ?? '';
+	return `${doctype}<html ${PREVIEW_MARK}>${html.slice(doctype.length)}`;
+}
+
+async function markPreview(response: Response): Promise<Response> {
+	if (response.status !== 200 || !/^text\/html/i.test(response.headers.get('Content-Type') ?? '')) return response;
+	const headers = new Headers(response.headers);
+	headers.delete('Content-Length');
+	return new Response(markPreviewHtml(await response.text()), { status: response.status, statusText: response.statusText, headers });
+}
+
+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();
+	const mode = editorMode();
+	if (mode.kind !== 'unconfigured') {
+		if (context.url.pathname !== ENDPOINTS.preview || context.request.method !== 'GET') return next();
+		return (async () => markPreview(await next()))();
+	}
+	const message = unconfiguredMessage(mode);
+	const api = context.url.pathname.startsWith('/_caracms/');
+	const escape = (s: string) => s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]!);
+	return Promise.resolve(
+		api
+			? new Response(JSON.stringify({ error: message, code: 'unconfigured' }), {
+					status: 503,
+					headers: { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' },
+				})
+			: new Response(`<!doctype html><meta charset="utf-8"><meta name="robots" content="noindex"><title>Editor not set up</title><p>${escape(message)}</p>`, {
+					status: 503,
+					headers: { 'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store' },
+				}),
+	);
+};

package/src/editor/routes/_live.ts

@@ -0,0 +1,26 @@
+/**
+ * Live mode's routes (M4 Phase 2) share this: each is one handler on the process's live
+ * editor (../../live/editor.ts), given the signed-in person from `locals`. In local
+ * mode they answer 404 `{ code: 'not-live' }`: M3's editor has no status, locks or
+ * Publish (Decision 1).
+ */
+import type { APIRoute } from 'astro';
+import { site } from 'virtual:caracms/config';
+import type { LiveEditor } from '../../live/editor.ts';
+import { personOf } from '../../live/locals.ts';
+import { liveEditorOf } from '../server/mode.ts';
+
+type Name = 'status' | 'lock' | 'publish' | 'history' | 'tryAgain' | 'notice';
+
+export const liveRoute =
+	(name: Name): APIRoute =>
+	async ({ request, locals }) => {
+		const live: LiveEditor | null = await liveEditorOf(site);
+		if (!live) {
+			return new Response(JSON.stringify({ error: 'This route is for live mode; the editor is in local mode here.', code: 'not-live' }), {
+				status: 404,
+				headers: { 'Content-Type': 'application/json; charset=utf-8', 'Cache-Control': 'no-store' },
+			});
+		}
+		return live[name](request, personOf(locals));
+	};