caracms 0.8.0 → 0.8.2

package/README.md

@@ -10,8 +10,17 @@ is, under the MIT license.
 
 ## Start
 
-caracms goes into an existing Astro site (Astro 7, on Node 22.12 or later). From the
-site's root, in a clean git checkout, install it and commit the install:
+Two steps: create an Astro site, then add caracms to it with `npx caracms init`.
+(`npm create caracms` says the same.)
+
+**1. Create the Astro site** (Astro 7, on Node 22.12 or later), or use one you have:
+
+```sh
+npm create astro@latest
+```
+
+**2. In it, add caracms.** From the site's root, in a clean git checkout, install it and
+commit the install:
 
 ```sh
 npm install caracms --save-exact
@@ -321,6 +330,18 @@ site, signs every commit, and isn't tied to a person. Use it for anyone running
 a handful of sites, or a repo that requires signed commits. Install it on the site's repo
 only, with the same permissions as the token.
 
+**Protect `drafts` from deletion.** It holds every change saved since the last Publish,
+and to a branch tidy-up it looks like any stale branch. In the repo's Settings → Rules →
+Rulesets, add a branch ruleset that targets `drafts` and turns on "Restrict deletions"
+only (leave "Block force pushes" off: Publish moves `drafts` with a forced update). If
+`drafts` goes anyway, the next start makes it again from the last commit the server
+recorded, while GitHub still has that commit; when it can't, the editor says what was lost.
+
+**Roll the site back with `git revert`, never a force-push.** A revert is a new commit on
+`main`, which `drafts` takes in like any push; resetting `main` to an older commit and
+force-pushing leaves the rolled-back content waiting in the editor, so the next Publish puts
+it back (the editor warns everyone when it sees one).
+
 ### CaraCMS Cloud
 
 #### Where the site runs: `services`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "caracms",
-  "version": "0.8.0",
+  "version": "0.8.2",
   "description": "A visual CMS for Astro sites, with content in git.",
   "license": "MIT",
   "type": "module",

package/skills/caracms-hosting/SKILL.md

@@ -233,7 +233,7 @@ are CaraCMS's; keys and the repo are the team's.
 | "That site key was revoked. Make a new one in app.caracms.com." (`revoked_key`) | Make a new labelled key for that place (host, laptop, staging), set it where the old one was (the host's variable or `.env`), redeploy or restart. Don't reuse another place's key. |
 | "That site key isn't one we know." (`unknown_key`) | A mistyped or truncated key, a key for a deleted site, or `CARACMS_CLOUD_URL` pointing at another cloud. Check the variable's value has no stray quotes or spaces, unset `CARACMS_CLOUD_URL`, else make a new key. |
 | "The caracms GitHub App isn't installed on <repo>, or that repo doesn't exist. Install the App on it: <link>" (`app_not_installed`) | Install the App from the link on that repo only. The cloud refreshes its record of the install only when the site's page in app.caracms.com opens (or a repo is linked, or the site mints a token), so open the site's page there, then run `init --cloud` again: it shows "App installed". The next visit to `/admin` tries again. If it is installed, the repo linked in app.caracms.com is the wrong one: the team fixes it there (a changed repo reaches the site at its next start). |
-| "This site has no GitHub repo in CaraCMS Cloud yet. Ask CaraCMS to set one." (`no_repo`; what `/admin` shows. `POST /v1/github/token` answers it as "A team owner can pick one in app.caracms.com.") | A team owner links the repo in app.caracms.com, then the App goes on it. The site still builds meanwhile. |
+| "This site has no GitHub repo in CaraCMS Cloud yet. A team owner can pick one in app.caracms.com." (`no_repo`; what `/admin` shows) | A team owner links the repo in app.caracms.com, then the App goes on it. The site still builds meanwhile. |
 | "CaraCMS Cloud couldn't be reached, so the site can't be built. Try again in a minute." (`unreachable`) | Retry the build. A running site keeps serving. If it persists, tell the person; don't switch the mode. |
 | "This site runs on CaraCMS Cloud (caracms.config.ts), but CARACMS_CLOUD_KEY isn't set. Make a key for it in app.caracms.com." | Not the cloud refusing: the key is missing where the site is built or runs (section 1). Expected during the move's steps 2–3. |
 

package/src/body.ts

@@ -0,0 +1,55 @@
+/**
+ * Reading a request's body under a cap (caracms-cloud adversarial review, finding 10). The
+ * bytes are counted as they're read and the read stops the moment they pass the cap,
+ * whatever `Content-Length` said or whether it was sent at all (a chunked body has none),
+ * so no route buffers more than its cap plus one chunk. A `Content-Length` over the cap is
+ * refused before a byte is read. The media upload and the forms endpoint read this way
+ * (M5b Decision 6); so do the webhook, sign-in and every editor write route since finding 10.
+ */
+
+export interface CappedBody {
+	ok: true;
+	bytes: Uint8Array;
+}
+export interface OverCap {
+	ok: false;
+	/** The size, when the request said it (Content-Length); null when the read was stopped without knowing. */
+	size: number | null;
+}
+
+/** Read a request's body, stopping as soon as it passes `cap` bytes. */
+export async function readCapped(request: Request, cap: number): Promise<CappedBody | OverCap> {
+	const declared = Number(request.headers.get('content-length') ?? NaN);
+	const said = Number.isFinite(declared) && declared >= 0 ? declared : null;
+	if (said !== null && said > cap) {
+		await request.body?.cancel().catch(() => {});
+		return { ok: false, size: said };
+	}
+	const reader = request.body?.getReader();
+	if (!reader) return { ok: true, bytes: new Uint8Array(0) };
+	const chunks: Uint8Array[] = [];
+	let total = 0;
+	for (;;) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		total += value.byteLength;
+		if (total > cap) {
+			await reader.cancel().catch(() => {});
+			return { ok: false, size: said !== null && said > total ? said : null };
+		}
+		chunks.push(value);
+	}
+	const bytes = new Uint8Array(total);
+	let at = 0;
+	for (const c of chunks) {
+		bytes.set(c, at);
+		at += c.byteLength;
+	}
+	return { ok: true, bytes };
+}
+
+/** The body as UTF-8 text, or null when it passes `cap` bytes (the route answers its own 413). */
+export async function readCappedText(request: Request, cap: number): Promise<string | null> {
+	const read = await readCapped(request, cap);
+	return read.ok ? new TextDecoder().decode(read.bytes) : null;
+}

package/src/cli/validate.ts

@@ -424,7 +424,7 @@ export async function validateSite(site: Site, codeRoutes: readonly CodeRoute[]
 		const c: Context = { file: entry.file, site, report, warningContext, exists };
 		const collection = site.collections[entry.collection]!;
 		if (entry.warning) {
-			if (entry.warning.code === 'no-title') error(c, 'title', 'This document has no "title", so the editor can\'t open it. Add one.');
+			if (entry.warning.code === 'no-title') error(c, 'title', 'This document has no "title", so it has no page on the site. Add one.');
 			else error(c, '', entry.warning.message);
 			if (entry.warning.code !== 'no-title') continue;
 		}

package/src/cloud-middleware.ts

@@ -14,7 +14,12 @@
  *
  * `cloudSettingsForBuild()` is the build's start (`astro:build:start`): the same fetch, and
  * a refusal or an unreachable cloud **fails the build** with the cloud's sentence or the
- * package's own. The build ignores `github.repo`: a site with no repo linked still builds.
+ * package's own. A refusal fails it at once; an unreachable cloud (no answer, a timeout, an
+ * answer that isn't the API's, such as a 502 page) is tried again with growing waits for
+ * about three minutes first (`BUILD_RETRY_WAITS_MS`, `BUILD_RETRY_WINDOW_MS`), one log line
+ * per wait, since a Convex blip during a Publish's deploy would otherwise leave the site
+ * unchanged. Only the build retries: the server's first request keeps one try and `RETRY_MS`.
+ * The build ignores `github.repo`: a site with no repo linked still builds.
  * The key beside the site's own forms and email variables fails it too (caracms-cloud M4
  * Decision 22), whether or not the media is the cloud's.
  *
@@ -68,11 +73,42 @@ export const onRequest: MiddlewareHandler = async (_context, next) => {
 	return next();
 };
 
+/** The build's waits between tries at an unreachable cloud, in order; the last repeats while the window lasts. */
+export const BUILD_RETRY_WAITS_MS = [5_000, 10_000, 20_000, 40_000, 60_000];
+/** No wait starts that would end more than this long after the first try began. */
+export const BUILD_RETRY_WINDOW_MS = 210_000;
+
+/** The build's clock, its waits and its log line (tests). */
+export interface BuildRetry {
+	now?: () => number;
+	wait?: (ms: number) => Promise<void>;
+	log?: (line: string) => void;
+}
+
+/** The settings for the build: an unreachable cloud is tried again within the window; a refusal is thrown at once. */
+async function loadForBuild(connection: Parameters<typeof loadCloudSettings>[0], retry: BuildRetry) {
+	const { now = Date.now, wait = (ms) => new Promise<void>((done) => setTimeout(done, ms)), log = (line) => console.warn(line) } = retry;
+	const end = now() + BUILD_RETRY_WINDOW_MS;
+	for (let tries = 1; ; tries++) {
+		try {
+			return await loadCloudSettings(connection);
+		} catch (error) {
+			if (isCloudRefusal(error) && error.error !== 'unreachable') throw error;
+			const ms = BUILD_RETRY_WAITS_MS[Math.min(tries, BUILD_RETRY_WAITS_MS.length) - 1]!;
+			if (now() + ms > end) throw error;
+			const what = isCloudRefusal(error) && error.detail ? ` (${error.detail})` : '';
+			const at = new Date(now() + ms).toISOString().slice(11, 19);
+			log(`[caracms] CaraCMS Cloud couldn't be reached for the build's settings${what}, try ${tries}; trying again in ${ms / 1000} s, at ${at} UTC.`);
+			await wait(ms);
+		}
+	}
+}
+
 /**
  * The build's start: the settings, or an Error with the sentence that fails the build. Nothing for a site off the cloud.
  * `services` is the config's (the integration passes it: this runs outside the bundle, where the build's defines don't reach).
  */
-export async function cloudSettingsForBuild(env: Env = process.env, services: Services | null = null): Promise<void> {
+export async function cloudSettingsForBuild(env: Env = process.env, services: Services | null = null, retry: BuildRetry = {}): Promise<void> {
 	env = servicesEnv(env, services);
 	if (services === 'cloud' && !env.CARACMS_CLOUD_KEY?.trim()) throw new Error(`caracms: ${CLOUD_KEY_MISSING_PROBLEM}`);
 	// caracms-cloud M4 Decision 22: the key with the site's own forms and email variables fails the build too.
@@ -86,7 +122,7 @@ export async function cloudSettingsForBuild(env: Env = process.env, services: Se
 	if (cloud.problems.length || forms.length) throw new Error(`caracms: ${[...cloud.problems, ...forms].join(' ')}`);
 	let settings;
 	try {
-		settings = await loadCloudSettings(cloud.connection);
+		settings = await loadForBuild(cloud.connection, retry);
 	} catch (error) {
 		const message = isCloudRefusal(error) && error.error !== 'unreachable' ? error.message : CLOUD_UNREACHABLE_BUILD;
 		throw new Error(`caracms: ${message}`);

package/src/content.ts

@@ -43,6 +43,7 @@ import { leftBehindMessage, leftBehindRoutes, ownRoutedCollections } from './cod
 import { sameAddress } from './slug.ts';
 import { byLabel, isOrderedCollection, orderSiblings, parsePageOrder, type PageOrder } from './page-order.ts';
 import { SITE_SETTINGS_FILE } from './reserved.ts';
+import { documentProblems } from './document-problems.ts';
 
 // Posts and tags, Decision 14: a route's reader on the disk (read.ts).
 export { contentReader } from './read.ts';
@@ -360,19 +361,25 @@ function hideChildren(entries: DocumentEntry[]): void {
  * Read one document. Throws DocumentError: 'not-found', 'bad-path',
  * 'unknown-collection', or the listing's warning codes ('invalid-json',
  * 'no-title', 'nested-index') for a file that can't be opened.
+ *
+ * `untitled: true` is the editor's read (caracms-cloud adversarial review, finding 15): a
+ * document with no title opens, its entry still warned, so the title can be put back there.
+ * Everything that renders the site reads without it, so such a document has no page there.
  */
 export async function readDocument(
 	site: Pick<ResolvedSite, 'collections' | 'root' | 'blocks'>,
 	collectionName: string,
 	path: string,
 	source: ContentSource = diskSource,
+	options: { untitled?: boolean } = {},
 ): Promise<ReadDocument> {
 	const file = resolveDocumentFile(site, collectionName, path);
 	const collection = site.collections[collectionName]!;
 	const text = await source.readText(file);
 	if (text === null) throw new DocumentError('not-found', `${collection.label}: no document "${path}".`);
 	const { entry, document } = inspect(site, collection, path, text);
-	if (entry.warning || !document) throw new DocumentError(entry.warning!.code, entry.warning!.message);
+	const opens = !entry.warning || (options.untitled === true && entry.warning.code === 'no-title');
+	if (!opens || !document) throw new DocumentError(entry.warning!.code, entry.warning!.message);
 	if (collection.heldBy) {
 		const held = await heldBaseOf(site, collection.name, source);
 		if (held) placeHeld(entry, held);
@@ -429,11 +436,13 @@ function inspect(
 	} catch (error) {
 		return warn('invalid-json', `This file isn't valid JSON (${error instanceof Error ? error.message : String(error)}).`);
 	}
-	const title = (raw as { title?: unknown } | null)?.title;
-	if (typeof title !== 'string' || title.trim() === '') {
-		return warn('no-title', 'This file has no title, so it can’t be opened. Add a "title".');
-	}
-	const entry: DocumentEntry = { ...base, title, label: title, warning: null };
+	// caracms-cloud adversarial review, finding 15: a blank title keeps the document off the site
+	// (the listing's warning), but it's still read, columns and all, so the editor can open it
+	// and put one back.
+	const untitled = documentProblems(raw).length > 0;
+	const title = untitled ? '' : (raw as { title: string }).title;
+	const warning: DocumentWarning | null = untitled ? { code: 'no-title', message: 'This has no title, so it isn’t on the site. Open it to add one.' } : null;
+	const entry: DocumentEntry = { ...base, title, label: title || fileLabel, warning };
 	// M9 Decision 7: the home page is never hidden.
 	if ((document.kind === undefined || document.kind === 'sections') && document.hidden && path !== 'index') entry.hidden = entry.hiddenSelf = true;
 	if ((document.kind === undefined || document.kind === 'sections') && document.holds !== undefined) entry.holds = document.holds;

package/src/document-problems.ts

@@ -0,0 +1,48 @@
+/**
+ * What makes a document one the reader won't open (caracms-cloud adversarial review,
+ * finding 15), said the way the editor says it. One rule for three places, so they never
+ * disagree: content.ts → `inspect` (the listing's "no title" warning), the editor's note on
+ * the field while it's typed, and Publish, which holds a document like this back (it stays
+ * waiting) and publishes the rest (live/git.ts → `publish`).
+ *
+ * Today that's the title: every kind of document needs one that isn't blank. Fields have no
+ * "required" of their own, and a field's value of the wrong shape parses as empty, never
+ * refused (document.ts → `parseAnyDocument`), so nothing else makes a document unreadable.
+ * A file that isn't JSON can't be read at all; only a hand edit makes one.
+ *
+ * Browser-safe: the editor imports it.
+ */
+
+export interface DocumentProblem {
+	/** Where it is: `title`, or `''` for the whole file. */
+	path: string;
+	/** The note on the field, in its own words: "This needs a title." */
+	note: string;
+	/** Why Publish held it back, after "<title> wasn't published: ": "its title is empty". */
+	reason: string;
+}
+
+export const NO_TITLE: DocumentProblem = { path: 'title', note: 'This needs a title.', reason: 'its title is empty' };
+const NOT_JSON: DocumentProblem = { path: '', note: "This file isn't valid JSON.", reason: "its file isn't valid JSON" };
+
+/** A document's problems, from its plain value (a file's, or the editor's own). Empty: the reader opens it. */
+export function documentProblems(document: unknown): DocumentProblem[] {
+	const title = document && typeof document === 'object' && !Array.isArray(document) ? (document as { title?: unknown }).title : undefined;
+	return typeof title === 'string' && title.trim() !== '' ? [] : [NO_TITLE];
+}
+
+/** A file's problems, from its text. */
+export function textProblems(text: string): DocumentProblem[] {
+	let value: unknown;
+	try {
+		value = JSON.parse(text);
+	} catch {
+		return [NOT_JSON];
+	}
+	return documentProblems(value);
+}
+
+/** "About wasn't published: its title is empty." */
+export function heldBackSentence(title: string, reason: string): string {
+	return `${title} wasn't published: ${reason}.`;
+}

package/src/editor/client/collections/CollectionGrid.tsx

@@ -19,7 +19,7 @@ import { docIcon } from '../nav/DocRow.tsx';
 import { Avatar, DocMarksView } from '../live/marks.tsx';
 import { displayName } from '../live/format.ts';
 import { fmtDur } from '../fields/MediaField.tsx';
-import { docId, type CardPicture, type EditorAnyCollection, type ListedDocument } from '../../types.ts';
+import { docId, warnedWords, type CardPicture, type EditorAnyCollection, type ListedDocument } from '../../types.ts';
 import { ratioValue } from '../../../cards.ts';
 import { cellText, type RefIndex, type TableColumn } from './table.ts';
 
@@ -76,7 +76,7 @@ function Card(props: { doc: ListedDocument; collection: EditorAnyCollection; cap
 						{doc.warning ? (
 							<span className="wmark" data-warning={doc.warning.code} title={doc.warning.message}>
 								<Icon name="warn" size="xs" />
-								<span className="sr">, can't be opened: {doc.warning.message}</span>
+								<span className="sr">{warnedWords(doc)}: {doc.warning.message}</span>
 							</span>
 						) : null}
 						{live ? <DocMarksView file={doc.file} compact lock={false} /> : null}

package/src/editor/client/collections/CollectionTable.tsx

@@ -34,7 +34,7 @@ import { when } from '../live/format.ts';
 import { openDialog } from '../documents/dialogs.tsx';
 import { PAGELESS_SUB, singular } from '../documents/actions.ts';
 import { usedOnLine } from '../block-list/summary.ts';
-import { docId, type EditorAnyCollection, type ListedDocument } from '../../types.ts';
+import { docId, opensInEditor, warnedWords, type EditorAnyCollection, type ListedDocument } from '../../types.ts';
 import { captionColumns, cellText, cellValue, defaultView, filterable, MISSING, nextSort, orderOptions, orderValue, refIndex, refParts, sortable, tableColumns, viewRows, type FilterValue, type RefIndex, type TableColumn, type TableView } from './table.ts';
 import { useCollection } from '../fields/ReferenceField.tsx';
 import { CollectionGrid } from './CollectionGrid.tsx';
@@ -83,7 +83,7 @@ export function useViewMode(collection: EditorAnyCollection): ViewMode {
 }
 
 const openDoc = (editor: Editor, doc: ListedDocument) => {
-	if (doc.warning) {
+	if (doc.warning && !opensInEditor(doc)) {
 		editor.announce(`${doc.label} can't be opened. ${doc.warning.message}`);
 		return;
 	}
@@ -375,7 +375,7 @@ function Row(props: { doc: ListedDocument; columns: readonly TableColumn[]; curr
 								{doc.warning ? (
 									<span className="wmark" data-warning={doc.warning.code} title={doc.warning.message}>
 										<Icon name="warn" size="xs" />
-										<span className="sr">, can't be opened: {doc.warning.message}</span>
+										<span className="sr">{warnedWords(doc)}: {doc.warning.message}</span>
 									</span>
 								) : null}
 								{/* M9 Decision 7, collections under pages (Decision 11): hidden, or hidden with the page that holds it, named. */}

package/src/editor/client/documents/DocMenu.tsx

@@ -11,15 +11,24 @@
  * study, a journal entry), off for Home or a collection's top page and while someone
  * else is editing it.
  *
+ * Discard changes (live mode): **Discard changes…** (or Discard this new page…) while the
+ * document is waiting to publish, which opens the confirmation; off, with the reason, while
+ * someone else is editing it.
+ *
  * M6c (G1): a document with no page of its own (a shared block, a fields collection
  * with no `urlBase`) has neither View on the live site nor Change address…, only Delete.
+ *
+ * `TitleNote` (caracms-cloud adversarial review, finding 15): a page or a shared block with
+ * no title says so at the top of its level, with Rename… beside it (a case study's title is
+ * the first field of its form, which says so itself: FormLevel.tsx → TitleField).
  */
 import { useEffect, useRef, useState, type KeyboardEvent } from 'react';
 import { useEditor, useStore } from '../context.tsx';
 import { displayName } from '../live/format.ts';
 import { Icon } from '../shell/Icons.tsx';
+import { NO_TITLE } from '../../../document-problems.ts';
 import { docId, sameDoc } from '../../types.ts';
-import { singular } from './actions.ts';
+import { discardWording, singular } from './actions.ts';
 import { openDialog } from './dialogs.tsx';
 
 export function DocMenu({ label }: { label: string }) {
@@ -54,6 +63,8 @@ export function DocMenu({ label }: { label: string }) {
 	const shared = collection.kind === 'shared';
 	const noPage = collection.urlBase === null;
 	const pending = (waiting ?? []).find((w) => w.collection === ref.collection && w.path === ref.path && w.change === 'new');
+	// Discard changes: this document is waiting to publish.
+	const waitingHere = (waiting ?? []).find((w) => w.file === entry.file) ?? null;
 	const isNew = !!pending;
 	const listed = documents.find((d) => docId(d) === docId(ref));
 	const home = sameDoc(ref, editor.site.home);
@@ -145,6 +156,25 @@ export function DocMenu({ label }: { label: string }) {
 							<hr />
 						</>
 					)}
+					{waitingHere ? (
+						<>
+							<button
+								type="button"
+								role="menuitem"
+								data-act="discard-document"
+								disabled={!!holder}
+								onClick={() => (setOpen(false), openDialog(editor, { kind: 'discard', file: waitingHere.file }))}
+							>
+								<Icon name="undo" />
+								{discardWording(waitingHere, editor.you, shared ? 'shared block' : singular(collection)).menu}
+							</button>
+							{holder ? (
+								<div className="why" data-why="discard">
+									{holder} is editing it.
+								</div>
+							) : null}
+						</>
+					) : null}
 					<button type="button" role="menuitem" className="danger" data-act="delete-document" disabled={!!why} onClick={remove}>
 						<Icon name="trash" />
 						Delete {shared ? 'shared block' : singular(collection)}…
@@ -159,3 +189,28 @@ export function DocMenu({ label }: { label: string }) {
 		</div>
 	);
 }
+
+/**
+ * The open document has no title (blanked, or read that way from its file): it's kept as it
+ * is, isn't on the site, and Publish holds it back until it has one. Renaming it gives it one.
+ */
+export function TitleNote() {
+	const editor = useEditor();
+	const untitled = useStore(editor.doc.state, (s) => s.document.title.trim() === '');
+	const readOnly = useStore(editor.access, (a) => a.readOnly);
+	if (!untitled) return null;
+	return (
+		<div className="note warn tight" role="status" data-note="no-title">
+			<Icon name="warn" />
+			<div>
+				<b>{NO_TITLE.note}</b>
+				<p>Until it has one, it isn't on the site and Publish leaves it waiting.</p>
+				<div className="acts">
+					<button type="button" className="btn sm" data-act="rename-untitled" disabled={readOnly} onClick={() => openDialog(editor, { kind: 'rename' })}>
+						Rename…
+					</button>
+				</div>
+			</div>
+		</div>
+	);
+}

package/src/editor/client/documents/actions.ts

@@ -13,7 +13,8 @@
 import { titleCase } from '../../../fields.ts';
 import { RESERVED_SLUG, slugify } from '../../../slug.ts';
 import type { Editor } from '../editor.ts';
-import { docId, ENDPOINTS, MEDIA_ENDPOINTS, TAB_HEADER, sameDoc, type CreateDeleteRefusal, type CreateRequest, type CreateResponse, type DeleteResponse, type DocRef, type MoveResponse, type EditorAnyCollection, type ListedDocument, type ReplaceFileResponse } from '../../types.ts';
+import { displayName } from '../../../live/messages.ts';
+import { docId, ENDPOINTS, MEDIA_ENDPOINTS, TAB_HEADER, sameDoc, type CreateDeleteRefusal, type CreateRequest, type CreateResponse, type DeleteResponse, type DocRef, type MoveResponse, type EditorAnyCollection, type ListedDocument, type Person, type ReplaceFileResponse, type WaitingView } from '../../types.ts';
 
 export type Refused = { ok: false; status: number; error: string; code: string | null; usedOn: CreateDeleteRefusal['usedOn'] | null };
 
@@ -274,3 +275,31 @@ export function andList(names: readonly string[]): string {
 
 /** An address part from what's typed, by the name rule (slug.ts). */
 export const partFrom = (typed: string) => slugify(typed);
+
+/**
+ * Discard changes' words (the waiting list's Discard…, the document menu's item, the
+ * confirmation), from the waiting entry: who else changed it is named ("…including Ann's?").
+ */
+export function discardWording(
+	item: Pick<WaitingView, 'title' | 'change' | 'editors' | 'movedFrom'>,
+	you: Person | null,
+	noun: string,
+): { heading: string; body: string; confirm: string; menu: string } {
+	const others = item.editors.filter((e) => !you || e.person.email.toLowerCase() !== you.email.toLowerCase()).map((e) => `${displayName(e.person)}'s`);
+	const names = others.length < 2 ? others.join('') : `${others.slice(0, -1).join(', ')} and ${others.at(-1)}`;
+	// A moved document waits as new on its new file; it's the move that goes.
+	if (item.change === 'new' && !item.movedFrom) {
+		return {
+			heading: names ? `Discard this new ${noun}, including ${names} changes?` : `Discard this new ${noun}?`,
+			body: `${item.title} isn't on the live site yet, so it's removed.`,
+			confirm: `Discard this new ${noun}`,
+			menu: `Discard this new ${noun}…`,
+		};
+	}
+	return {
+		heading: names ? `Discard the unpublished changes to ${item.title}, including ${names}?` : `Discard the unpublished changes to ${item.title}?`,
+		body: item.movedFrom ? `It goes back to ${item.movedFrom}, as it is on the live site.` : item.change === 'deleted' ? 'It comes back, as it is on the live site.' : "It goes back to what's live.",
+		confirm: 'Discard changes',
+		menu: 'Discard changes…',
+	};
+}

package/src/editor/client/documents/dialogs.tsx

@@ -11,6 +11,7 @@
  *   openDialog(editor, { kind: 'move', ref })                       Change address… (pre-M7 item 8)
  *   openDialog(editor, { kind: 'rename' })                          Rename… on the open document
  *   openDialog(editor, { kind: 'replace', key })                    Replace… on a file (M6c G4, media/ReplaceDialog.tsx)
+ *   openDialog(editor, { kind: 'discard', file })                   Discard changes… (live mode: back to what's live)
  *
  * Esc closes the dialog only (the editor's own Esc, going up a level, doesn't run).
  * Addresses are shown before creating, made by slug.ts as the server makes them, and
@@ -28,7 +29,7 @@ import { Icon } from '../shell/Icons.tsx';
 import { createStore, type Store } from '../state/store.ts';
 import type { CreateDeleteRefusal, DocRef, ListedDocument } from '../../types.ts';
 import { INSIDE_CLOSE, InsidePicker } from './InsidePicker.tsx';
-import { addressFor, addressesMoving, andList, createDocument, deleteDocument, insideOptions, moveDocument, pagesUnder, singular } from './actions.ts';
+import { addressFor, addressesMoving, andList, createDocument, deleteDocument, discardWording, insideOptions, moveDocument, pagesUnder, singular } from './actions.ts';
 import { filesLabel, inboxFor } from '../inbox/store.ts';
 import { ReplaceDialog } from '../media/ReplaceDialog.tsx';
 
@@ -46,7 +47,9 @@ export type Dialog =
 	/** M6c G4 Decision 9: Replace… on a file in the library (its key). */
 	| { kind: 'replace'; key: string }
 	/** Arrange pages (Decision 15): leaving the screen with something arranged; `go` leaves, dropping it. */
-	| { kind: 'arrange-leave'; go: () => void };
+	| { kind: 'arrange-leave'; go: () => void }
+	/** Discard changes (live mode): a waiting document, by its file, back to what's live. */
+	| { kind: 'discard'; file: string };
 
 const dialogs = new WeakMap<Editor, Store<Dialog | null>>();
 
@@ -85,6 +88,8 @@ export function DocumentDialogs() {
 			return <ReplaceDialog key={dialog.key} fileKey={dialog.key} />;
 		case 'arrange-leave':
 			return <LeaveArrange go={dialog.go} />;
+		case 'discard':
+			return <DiscardChanges key={dialog.file} file={dialog.file} />;
 	}
 }
 
@@ -517,12 +522,14 @@ function MoveDocument({ docRef }: { docRef: DocRef }) {
  */
 function RenameDocument() {
 	const editor = useEditor();
+	const title = useStore(editor.doc.state, (s) => s.document.title);
 	const current = useStore(editor.doc.state, (s) => s.document.title || s.entry.label);
 	// Taken by someone else, signed out or deleted since the menu opened: setTitle would do nothing.
 	const readOnly = useStore(editor.access, (a) => a.readOnly);
 	const [name, setName] = useState(current);
 	const next = name.replace(/\s+/g, ' ').trim();
-	const blocked = !next || next === current || readOnly;
+	// Finding 15: a document with no title may take the name it's listed by as its title.
+	const blocked = !next || next === title || readOnly;
 	const confirm = () => {
 		if (blocked) return;
 		editor.doc.setTitle(next);
@@ -641,6 +648,57 @@ function NewShared() {
 	);
 }
 
+// ── Discard changes ──────────────────────────────────────────────────────────
+
+/**
+ * Discard changes (live mode): asks first, naming anyone else whose changes go too, then puts
+ * the document back to what's live (editor.discardChanges). The server's sentence when it
+ * refuses (someone editing it now, a Publish running). Gone from the waiting list meanwhile:
+ * it closes.
+ */
+function DiscardChanges({ file }: { file: string }) {
+	const editor = useEditor();
+	const item = useStore(editor.liveState, (s) => s.status?.waiting.find((w) => w.file === file) ?? null);
+	const you = useStore(editor.liveState, (s) => s.status?.you ?? null);
+	const [error, setError] = useState<string | null>(null);
+	const [busy, setBusy] = useState(false);
+	const [seen] = useState(item);
+	const shown = item ?? (busy ? seen : null);
+	useEffect(() => {
+		if (!shown) closeDialog(editor);
+	}, [shown, editor]);
+	if (!shown) return null;
+	const collection = editor.site.collections.find((c) => c.name === shown.collection);
+	const noun = collection?.kind === 'shared' ? 'shared block' : collection ? singular(collection) : 'page';
+	const words = discardWording(shown, you ?? editor.you, noun);
+	const confirm = async () => {
+		setBusy(true);
+		setError(null);
+		const answer = await editor.discardChanges(shown);
+		setBusy(false);
+		if (answer.ok) closeDialog(editor);
+		else setError(answer.error);
+	};
+	return (
+		<Frame alert label="discard" describedBy="dlg-d">
+			<div className="icon-h" style={{ background: 'var(--status-danger-wash)', color: 'var(--status-danger)' }}>
+				<Icon name="undo" />
+			</div>
+			<h2 id="dlg-h">{words.heading}</h2>
+			<p id="dlg-d">{words.body}</p>
+			<Err id="discard-err" text={error} />
+			<div className="acts">
+				<button type="button" className="btn" onClick={() => closeDialog(editor)}>
+					Cancel
+				</button>
+				<button type="button" className="btn danger" data-act="confirm-discard" disabled={busy} onClick={() => void confirm()}>
+					{words.confirm}
+				</button>
+			</div>
+		</Frame>
+	);
+}
+
 // ── Delete ───────────────────────────────────────────────────────────────────
 
 function DeleteDocument({ docRef }: { docRef: DocRef }) {