proctolog 0.1.0

data/public/review-drafts.js

@@ -0,0 +1,949 @@
+// The owner's choices on the decisions of a burst. The desk keeps them, in
+// choices.json beside the marks, and every page starts from what it kept. This
+// browser holds a copy as well: it carries a choice across tabs at once, and
+// through a moment when the desk does not answer.
+
+import { isPrNumber, prNumber } from "./pr-number.js";
+import { toast } from "./toast.js";
+
+const tools = document.querySelector("[data-review-draft]");
+const { repository, burst } = tools.dataset;
+const address = `/bursts/${encodeURIComponent(burst)}/choices`;
+export const inventory = JSON.parse(
+	document.querySelector("#decision-inventory").textContent,
+);
+const current = new Map(inventory.map((decision) => [decision.id, decision]));
+const storageKey = `proctolog:burst:v1:${repository}:${burst}`;
+// Where this browser kept its copy before bursts had their name: read when
+// the new key holds nothing yet, never written.
+const earlierKey = `proctolog:review:v1:${repository}:${burst}`;
+// The pull requests of the part a page is focused on, which is all a
+// handover from it carries; none when the page shows the whole burst.
+export const part = tools.dataset.partPrs?.split(" ").map(prNumber);
+export const inPart = (pr) => !part || part.includes(pr);
+export const labels = {
+	leave: "Leave as is",
+	question: "Ask a question",
+	change: "Suggest a change",
+	later: "Leave for later",
+};
+// What a saved choice is called once it is made.
+const saidOf = {
+	leave: "Left as is",
+	question: "Question saved",
+	change: "Change saved",
+	later: "Left for later",
+};
+// A desk from before bursts had their name reads `review`: both are written.
+const owned = (data) => Object.assign(data, { burst, review: burst });
+const blank = () =>
+	owned({
+		version: 1,
+		repository,
+		choices: [],
+		pending: [],
+	});
+let state = blank();
+// Whether the desk took the last writing, and whether this browser keeps its copy.
+let kept = true;
+let mirrored = true;
+let rounds;
+export const draftsState = () => state;
+export const registerRounds = (adapter) => {
+	rounds = adapter;
+	changed();
+};
+
+export const announce = (message) => {
+	const text =
+		kept || mirrored
+			? message
+			: `${message} The desk did not answer and this browser keeps nothing: these choices are only in this tab. Back them up before leaving.`;
+	tools.querySelector("[data-draft-message]").textContent = text;
+	toast(text);
+};
+
+const validEntry = (entry) =>
+	entry &&
+	Object.hasOwn(labels, entry.kind) &&
+	typeof entry.text === "string" &&
+	entry.decision &&
+	typeof entry.decision.id === "string" &&
+	isPrNumber(entry.decision.pr) &&
+	["text", "lead", "head", "description", "branch"].every(
+		(key) => typeof entry.decision[key] === "string",
+	) &&
+	(entry.savedAt === undefined || typeof entry.savedAt === "string") &&
+	(entry.decision.key === undefined ||
+		(typeof entry.decision.key === "string" &&
+			/^[\w.-]+$/.test(entry.decision.key))) &&
+	(entry.requestId === undefined || typeof entry.requestId === "string") &&
+	(entry.batch === undefined || typeof entry.batch === "string") &&
+	(entry.grade === undefined ||
+		["blocking", "non_blocking"].includes(entry.grade));
+
+const validRequest = (item) =>
+	item &&
+	typeof item.id === "string" &&
+	typeof item.text === "string" &&
+	["leave", "question", "change", "later", "remark", "rule"].includes(
+		item.kind,
+	) &&
+	item.source &&
+	typeof item.source.kind === "string" &&
+	(item.source.kind !== "code" ||
+		(item.source.anchor && typeof item.source.anchor.path === "string"));
+
+const validate = (data) => {
+	if (
+		data?.version !== 1 ||
+		data.repository !== repository ||
+		(data.burst ?? data.review) !== burst ||
+		!Array.isArray(data.choices) ||
+		!Array.isArray(data.pending) ||
+		![...data.choices, ...data.pending].every(validEntry) ||
+		data.choices.some(
+			(entry) => entry.kind !== "leave" && !entry.text.trim(),
+		) ||
+		new Set(data.choices.map((entry) => entry.decision.id)).size !==
+			data.choices.length ||
+		new Set(data.pending.map((entry) => entry.decision.id)).size !==
+			data.pending.length ||
+		(data.requests !== undefined &&
+			(!Array.isArray(data.requests) || !data.requests.every(validRequest))) ||
+		(data.batches !== undefined &&
+			(!Array.isArray(data.batches) ||
+				!data.batches.every(
+					(batch) =>
+						typeof batch.id === "string" &&
+						Array.isArray(batch.items) &&
+						batch.items.every(validRequest) &&
+						(batch.heads === undefined ||
+							(batch.heads &&
+								typeof batch.heads === "object" &&
+								!Array.isArray(batch.heads) &&
+								Object.values(batch.heads).every(
+									(head) =>
+										head &&
+										typeof head.head === "string" &&
+										(head.descriptionText === undefined ||
+											typeof head.descriptionText === "string"),
+								))),
+				))) ||
+		(data.responses !== undefined &&
+			(!Array.isArray(data.responses) ||
+				!data.responses.every(
+					(report) =>
+						report &&
+						typeof report.id === "string" &&
+						typeof report.batchId === "string" &&
+						typeof report.createdAt === "string" &&
+						Array.isArray(report.results),
+				))) ||
+		(data.feedback !== undefined &&
+			(!data.feedback ||
+				typeof data.feedback !== "object" ||
+				Array.isArray(data.feedback)))
+	)
+		throw new Error("This is not a choices backup for this burst.");
+	return data;
+};
+
+const revisionOf = (data) => data?.revision || 0;
+
+// This browser's copy, or nothing when it has none it can read. One that is
+// there and cannot be read is never written over: it is left for a recovery
+// by hand.
+let unreadable = false;
+const mirror = () => {
+	try {
+		const saved =
+			localStorage.getItem(storageKey) ?? localStorage.getItem(earlierKey);
+		return saved ? validate(JSON.parse(saved)) : undefined;
+	} catch {
+		mirrored = false;
+		unreadable = true;
+		return undefined;
+	}
+};
+
+const writeMirror = () => {
+	if (unreadable) return;
+	try {
+		localStorage.setItem(storageKey, JSON.stringify(state));
+		mirrored = true;
+	} catch {
+		mirrored = false;
+	}
+};
+
+// What the desk kept when it rendered this page.
+const fromDesk = () => {
+	try {
+		const document_ = JSON.parse(
+			document.querySelector("#burst-choices")?.textContent || "null",
+		);
+		return document_ ? validate(document_) : undefined;
+	} catch {
+		return undefined;
+	}
+};
+
+// Sends the whole of it to the desk, one writing at a time: a change made
+// while one is on its way goes with the next. Each change waits in `unsent`
+// until the desk took it, so that when another page wrote first, it can be
+// made again on top of theirs rather than lost.
+let sending;
+let queued = false;
+let later;
+let unsent = [];
+const send = () => {
+	clearTimeout(later);
+	later = undefined;
+	if (sending) {
+		queued = true;
+		return sending;
+	}
+	const body = JSON.stringify(state);
+	const carried = unsent;
+	unsent = [];
+	sending = fetch(address, {
+		method: "PUT",
+		headers: {
+			"Content-Type": "application/json",
+			Accept: "application/json",
+			"X-CSRF-Token":
+				document.querySelector('meta[name="csrf-token"]')?.content ?? "",
+		},
+		body,
+		// A small writing outlives the page that sent it; a large one cannot.
+		keepalive: body.length < 60000,
+	})
+		.then(async (response) => {
+			if (response.status === 409) {
+				const theirs = (await response.json()).document;
+				unsent = [...carried, ...unsent];
+				if (revisionOf(theirs) < revisionOf(state)) return;
+				state = reconcile(validate(theirs));
+				for (const mutate of unsent) mutate(state);
+				owned(state);
+				state.revision = revisionOf(theirs) + 1;
+				writeMirror();
+				changed();
+				queued = true;
+				announce(
+					"Another page of this burst saved choices while this one was open, so this page now shows them too. What you just did here is kept on top of them.",
+				);
+			} else if (!response.ok) {
+				throw new Error(`the desk answered ${response.status}`);
+			}
+			kept = true;
+		})
+		.catch((error) => {
+			unsent = [...carried, ...unsent];
+			const first = kept;
+			kept = false;
+			if (first || !mirrored)
+				announce(
+					`Not saved to the desk (${error.message}).${mirrored ? " This browser keeps your choices and sends them when the desk answers." : ""}`,
+				);
+		})
+		.finally(() => {
+			sending = undefined;
+			if (queued) {
+				queued = false;
+				send();
+			}
+		});
+	return sending;
+};
+
+// Resolves once the desk has what this page has: a page waits for it before
+// it goes to another that counts the choices.
+export const settled = async () => {
+	if (later) send();
+	while (sending) await sending;
+};
+globalThis.proctologSettled = settled;
+
+const decisionIdentity = (entry) => {
+	const matches = inventory.filter(
+		(item) =>
+			item.pr === entry.decision.pr &&
+			item.lead === entry.decision.lead &&
+			item.text === entry.decision.text,
+	);
+	const key =
+		entry.decision.key || (matches.length === 1 ? matches[0].key : undefined);
+	return JSON.stringify(
+		key
+			? [entry.decision.pr, key]
+			: [entry.decision.pr, entry.decision.lead, entry.decision.text],
+	);
+};
+const reconcile = (data) => {
+	for (const field of ["choices", "pending"]) {
+		const claimed = new Set();
+		for (const entry of data[field]) {
+			entry.requestId ||= `${field === "choices" ? "choice" : "draft"}:${entry.decision.id}:${entry.savedAt || "legacy"}`;
+			const matches = inventory.filter(
+				(item) =>
+					item.pr === entry.decision.pr &&
+					(entry.decision.key
+						? item.key === entry.decision.key
+						: item.lead === entry.decision.lead &&
+							item.text === entry.decision.text),
+			);
+			const match =
+				matches.length === 1 && !claimed.has(matches[0].id)
+					? matches[0]
+					: undefined;
+			if (match) claimed.add(match.id);
+			entry.decision = {
+				...entry.decision,
+				...(match
+					? { id: match.id, position: match.position, key: match.key }
+					: { id: `missing:${entry.requestId}` }),
+			};
+		}
+	}
+	return data;
+};
+
+// One set of choices with another laid over it, as a backup is restored: a
+// choice or a draft of `over` takes the place of the one on the same decision,
+// and the records of what was handed over and what came back are joined, never
+// rewritten.
+const merged = (base, over) => {
+	const result = structuredClone(base);
+	for (const field of ["choices", "pending"]) {
+		const entries = new Map(
+			result[field].map((entry) => [decisionIdentity(entry), entry]),
+		);
+		for (const entry of over[field])
+			entries.set(decisionIdentity(entry), entry);
+		result[field] = [...entries.values()];
+	}
+	for (const field of ["batches", "responses", "requests"]) {
+		const entries = new Map(
+			(result[field] || []).map((entry) => [entry.id, entry]),
+		);
+		for (const entry of over[field] || []) {
+			if (
+				entries.has(entry.id) &&
+				JSON.stringify(entries.get(entry.id)) !== JSON.stringify(entry)
+			)
+				throw new Error(
+					`The backup changes an existing ${field} record: ${entry.id}`,
+				);
+			entries.set(entry.id, entry);
+		}
+		result[field] = [...entries.values()];
+	}
+	result.feedback = { ...(result.feedback || {}) };
+	for (const [id, entry] of Object.entries(over.feedback || {})) {
+		const existing = result.feedback[id];
+		if (!existing || Date.parse(entry.at) > Date.parse(existing.at))
+			result.feedback[id] = entry;
+	}
+	return reconcile(result);
+};
+
+export const choiceFor = (id) =>
+	state.choices.find((entry) => entry.decision.id === id);
+export const pendingFor = (id) =>
+	state.pending.find((entry) => entry.decision.id === id);
+// A decision's words without its theme marker, which is no part of them:
+// naming or mending a theme never reopens a choice.
+const bare = (text) => text.replace(/\s*<!-- proctolog:theme [\w-]+ -->/g, "");
+
+// A choice left with every other non-blocking decision at once. It was made
+// on less attention than one made by itself, so it stands only while its
+// decision reads as it did and is still non-blocking.
+export const leftInBulk = (entry) => !!entry.batch && !!entry.grade;
+
+// Why a choice no longer stands, or nothing while it does: "Words changed",
+// "Promoted to blocking", "Pictures changed". The desk counts by the same
+// rules (Choices#current? in choices.rb), so the page and the pane agree.
+export const reopened = (entry) => {
+	if (
+		rounds?.isChoiceClosed?.(entry) ||
+		rounds?.isActivePR?.(entry.decision.pr) === false
+	)
+		return "";
+	return wordsMoved(entry) || (picturesMoved(entry) ? "Pictures changed" : "");
+};
+
+// Each picture a choice was made on, matched by name with those its
+// decision rests on now: changed, added, removed, the same, or unverified
+// while its pixels are not known, then or now. A choice made before
+// pictures were recorded has none to hold it to.
+export const picturesSince = (entry) => {
+	const was = entry.decision.pictures;
+	const now = current.get(entry.decision.id)?.pictures;
+	if (!was || !now) return [];
+	const names = [...new Set([...was, ...now].map(({ name }) => name))];
+	return names.map((name) => {
+		const before = was.find((picture) => picture.name === name);
+		const after = now.find((picture) => picture.name === name);
+		return { name, before, after, said: compared(before, after) };
+	});
+};
+const compared = (before, after) => {
+	if (!before) return "added";
+	if (!after) return "removed";
+	if (!before.signature || !after.signature) return "unverified";
+	return before.signature === after.signature ? "same" : "changed";
+};
+const picturesMoved = (entry) =>
+	picturesSince(entry).some(({ said }) =>
+		["changed", "added", "removed"].includes(said),
+	);
+
+// Its words, theme markers aside. One the owner made by itself that kept
+// its reference through a rewrite stands; one left with every non-blocking
+// decision at once stands only while its words are the same and its
+// decision is still non-blocking.
+const wordsMoved = (entry) => {
+	const at = current.get(entry.decision.id);
+	const reads = (item) =>
+		item?.pr === entry.decision.pr &&
+		item.lead === entry.decision.lead &&
+		bare(item.text) === bare(entry.decision.text);
+	const matching = inventory.filter(reads);
+	const latest = reads(at)
+		? at
+		: matching.length === 1
+			? matching[0]
+			: undefined;
+	if (leftInBulk(entry)) {
+		if (!latest) return "Words changed";
+		return entry.grade === "non_blocking" && latest.grade === "blocking"
+			? "Promoted to blocking"
+			: "";
+	}
+	if (entry.kind === "leave" && at?.key && at.key === entry.decision.key)
+		return "";
+	return latest ? "" : "Words changed";
+};
+export const stale = (entry) => !!reopened(entry);
+
+// A decision is reviewed once the owner chose on its present words. One that
+// is ticked on GitHub is not asked again either, and is counted apart.
+export const chosen = (item) => {
+	const saved = choiceFor(item.id);
+	return !!saved && !stale(saved);
+};
+export const reviewed = (item) => chosen(item) || !!item.ticked;
+
+const plural = (count, one, many = `${one}s`) =>
+	`${count} ${count === 1 ? one : many}`;
+
+// How far the decisions are, over the burst, over one pull request, or over
+// several: those of a part.
+export const progress = (pr) => {
+	const of = (number) => pr === undefined || [pr].flat().includes(number);
+	const items = inventory.filter((item) => of(item.pr));
+	const mine = (entry) => of(entry.decision.pr);
+	const picked = items.filter(chosen).length;
+	const ticked = items.filter((item) => !chosen(item) && item.ticked).length;
+	return {
+		total: items.length,
+		chosen: picked,
+		ticked,
+		left: items.length - picked - ticked,
+		drafts: state.pending.filter(mine).length,
+		again: state.choices.filter(
+			(entry) =>
+				mine(entry) &&
+				!entry.decision.id.startsWith("missing:") &&
+				stale(entry),
+		).length,
+		retained: state.choices.filter(
+			(entry) => mine(entry) && entry.decision.id.startsWith("missing:"),
+		).length,
+		saved: state.choices.filter(mine).length,
+	};
+};
+export const scope = tools.dataset.pr ? prNumber(tools.dataset.pr) : undefined;
+
+const changed = () => {
+	const now = progress(scope);
+	tools.querySelector("[data-draft-summary]").textContent = [
+		`${plural(now.saved, "choice")} saved`,
+		`${now.left} to review`,
+		`${now.ticked} ticked on GitHub`,
+		`${now.again} need review again`,
+		plural(now.drafts, "unfinished draft"),
+		...(now.retained
+			? [`${plural(now.retained, "earlier choice")} retained`]
+			: []),
+	].join(" · ");
+	tools.querySelector("[data-progress]").replaceChildren(...progressLine(now));
+	side();
+	document.dispatchEvent(new CustomEvent("drafts-changed"));
+};
+
+// The pane at the left counts the same choices: its rows follow them as they
+// are made, in the marks the server wrote them with.
+const side = () => {
+	const count = (number) => number.toLocaleString("en-US");
+	for (const row of document.querySelectorAll("[data-side-pr]")) {
+		const now = progress(prNumber(row.dataset.sidePr));
+		if (!now.total) continue;
+		const done = now.chosen + now.ticked;
+		row.querySelector("[data-side-mark]").textContent = !now.left
+			? "x"
+			: done
+				? "~"
+				: "";
+		row.querySelector("[data-side-fraction]").textContent =
+			`${done}/${now.total}`;
+	}
+	const overall = document.querySelector("[data-side-overall]");
+	if (!overall || !inventory.length) return;
+	const all = progress();
+	// Focused on a part, what is left in it against the burst, over its own bar.
+	const part = overall.dataset.partPrs?.split(" ").map(Number);
+	const shown = part ? progress(part) : all;
+	overall.querySelector("span").textContent = part
+		? `${count(shown.left)} / ${count(all.left)} decisions left, part / burst`
+		: `${count(all.chosen + all.ticked)} of ${count(all.total)} decisions reviewed`;
+	overall.querySelector("meter").value = shown.chosen + shown.ticked;
+};
+
+// The one line a page leads with: how many are reviewed of how many, a bar,
+// and only what else is not nought.
+const progressLine = (now) => {
+	const said = (tag, text, className) =>
+		Object.assign(document.createElement(tag), {
+			textContent: text,
+			className: className ?? "",
+		});
+	if (!now.total)
+		return [
+			said(
+				"span",
+				scope ? "No decisions on this pull request" : "No decisions",
+			),
+		];
+	const done = now.chosen + now.ticked;
+	const bar = Object.assign(document.createElement("meter"), {
+		max: now.total,
+		value: done,
+	});
+	return [
+		said("strong", `${done} of ${now.total} reviewed`),
+		bar,
+		...[
+			[now.left, `${now.left} to review`, "left"],
+			[now.ticked, `${now.ticked} ticked on GitHub`],
+			[now.again, `${now.again} to review again`, "again"],
+			[now.drafts, plural(now.drafts, "unfinished draft"), "again"],
+		]
+			.filter(([count]) => count)
+			.map(([, text, className]) => said("span", text, className)),
+	];
+};
+
+// Every change goes to this browser's copy at once and to the desk right
+// after; `soon` lets the letters of a draft go together.
+const persist = (mutate, { soon = false } = {}) => {
+	const theirs = mirror();
+	if (revisionOf(theirs) > revisionOf(state)) state = reconcile(theirs);
+	mutate(state);
+	unsent.push(mutate);
+	owned(state);
+	state.revision = revisionOf(state) + 1;
+	writeMirror();
+	if (soon) later ??= setTimeout(send, 500);
+	else send();
+	changed();
+};
+export const updateDrafts = persist;
+
+// Where the cursor rests is this browser's own business: it is not worth a
+// writing to the desk each time it moves.
+const cursorKey = `${storageKey}:cursor`;
+export const rememberCursor = (id) => {
+	try {
+		localStorage.setItem(cursorKey, id);
+	} catch {
+		// A browser that keeps nothing starts each page at its first decision.
+	}
+};
+export const cursor = () => {
+	try {
+		return (
+			localStorage.getItem(cursorKey) ??
+			localStorage.getItem(`${earlierKey}:cursor`) ??
+			state.cursor
+		);
+	} catch {
+		return state.cursor;
+	}
+};
+
+// An unfinished answer, kept as it is typed. One with nothing in it is not a
+// draft: opening an editor and closing it again leaves no trace.
+export const draft = (id, kind, text) => {
+	if (!text.trim() && !pendingFor(id)) return;
+	persist(
+		(data) => {
+			const previous = data.pending.find((entry) => entry.decision.id === id);
+			data.pending = data.pending.filter((entry) => entry.decision.id !== id);
+			if (!text.trim()) return;
+			data.pending.push({
+				decision: current.get(id),
+				kind,
+				text,
+				requestId: previous?.requestId || `draft:${id}:${crypto.randomUUID()}`,
+			});
+		},
+		{ soon: true },
+	);
+};
+
+// Each step u can take back: how to put back what it changed, what to say
+// once it is, and the decision to return to. A choice touches one decision,
+// a gesture several; a rule touches the rule alone.
+const undo = [];
+const remember = (ids) => {
+	const was = ids.map((id) => ({
+		choice: choiceFor(id),
+		pending: pendingFor(id),
+	}));
+	undo.push({
+		at: ids[0],
+		said:
+			ids.length > 1
+				? `${plural(ids.length, "choice")} taken back.`
+				: "Last choice undone.",
+		restore: (data) => {
+			withoutThese(data, ids);
+			for (const { choice, pending } of was) {
+				if (choice) data.choices.push(choice);
+				if (pending) data.pending.push(pending);
+			}
+		},
+	});
+};
+const withoutThese = (data, ids) => {
+	data.choices = data.choices.filter(
+		(entry) => !ids.includes(entry.decision.id),
+	);
+	data.pending = data.pending.filter(
+		(entry) => !ids.includes(entry.decision.id),
+	);
+};
+
+export const saveChoice = (id, kind, text = "") => {
+	if (!Object.hasOwn(labels, kind) || (kind !== "leave" && !text.trim()))
+		return false;
+	remember([id]);
+	persist((data) => {
+		withoutThese(data, [id]);
+		data.choices.push({
+			requestId: `choice:${id}:${crypto.randomUUID()}`,
+			decision: current.get(id),
+			kind,
+			text: text.trim(),
+			savedAt: new Date().toISOString(),
+		});
+	});
+	announce(`${saidOf[kind]} · u undoes it`);
+	return true;
+};
+
+// Leaves these decisions as they are in one gesture: each gets a choice of
+// its own, all under one batch, which records the grade each had then, and
+// u takes them back together.
+export const leaveInBulk = (ids) => {
+	if (!ids.length) return false;
+	const batch = `bulk:${crypto.randomUUID()}`;
+	const savedAt = new Date().toISOString();
+	remember(ids);
+	persist((data) => {
+		withoutThese(data, ids);
+		for (const id of ids)
+			data.choices.push({
+				requestId: `choice:${id}:${crypto.randomUUID()}`,
+				decision: current.get(id),
+				kind: "leave",
+				text: "",
+				savedAt,
+				batch,
+				grade: current.get(id).grade,
+			});
+	});
+	return true;
+};
+
+// One answer given to several decisions: each gets a choice of its own, all
+// under one batch, so u takes them back together and a handover carries the
+// answer out once in each part it touches. Each stands or reopens alone.
+export const saveTogether = (ids, kind, text = "") => {
+	if (!Object.hasOwn(labels, kind) || (kind !== "leave" && !text.trim()))
+		return false;
+	const batch = `together:${crypto.randomUUID()}`;
+	const savedAt = new Date().toISOString();
+	remember(ids);
+	persist((data) => {
+		withoutThese(data, ids);
+		for (const id of ids)
+			data.choices.push({
+				requestId: `choice:${id}:${crypto.randomUUID()}`,
+				decision: current.get(id),
+				kind,
+				text: text.trim(),
+				savedAt,
+				batch,
+			});
+	});
+	announce(
+		`${saidOf[kind]}, one answer for ${plural(ids.length, "decision")} · u undoes it`,
+	);
+	return true;
+};
+
+// How many other decisions a choice was answered with, when it was one of
+// several given one answer.
+export const answeredWith = (entry) =>
+	entry.batch?.startsWith("together:")
+		? state.choices.filter(
+				(other) => other !== entry && other.batch === entry.batch,
+			).length
+		: 0;
+
+export const clearChoice = (id) => {
+	remember([id]);
+	persist((data) => withoutThese(data, [id]));
+};
+
+// Takes back the last step; answers the first decision it touched.
+export const undoChoice = () => {
+	const previous = undo.pop();
+	if (!previous) {
+		toast("Nothing to undo on this page.");
+		return;
+	}
+	persist(previous.restore);
+	announce(previous.said);
+	return previous.at;
+};
+
+// The rule made of a choice, while it stands: one for a choice made by
+// itself, one for all those given in one gesture.
+export const ruleFor = (entry) =>
+	(state.requests || []).find(
+		(item) =>
+			item.kind === "rule" &&
+			!item.withdrawn &&
+			(entry.batch
+				? item.source.batch === entry.batch
+				: item.source.choice === entry.requestId),
+	);
+
+// The rule as the agent last had it, once a handover carried it.
+const lastSent = (id) =>
+	(state.batches || [])
+		.flatMap((batch) => batch.items)
+		.findLast((item) => item.id === id);
+
+// Makes an answer a rule the agent records, or rewrites the one made of it:
+// a request of its own, so that the agent's answer to the rule never
+// answers the choice. One the agent has already says which line it replaces.
+export const saveRule = (entry, text) => {
+	const line = text.replace(/\s+/g, " ").trim();
+	if (!line) return false;
+	const rule = ruleFor(entry);
+	const id = rule?.id ?? `rule:${crypto.randomUUID()}`;
+	const sent = lastSent(id)?.text;
+	undo.push({
+		at: entry.decision.id,
+		said: rule ? "Rule put back as it was." : "Rule taken back.",
+		restore: (data) => {
+			data.requests = (data.requests || []).filter((item) => item.id !== id);
+			if (rule) data.requests.push(rule);
+		},
+	});
+	persist((data) => {
+		const together = entry.batch
+			? data.choices.filter((other) => other.batch === entry.batch)
+			: [entry];
+		data.requests = [
+			...(data.requests || []).filter((item) => item.id !== id),
+			{
+				id,
+				pr: entry.decision.pr,
+				kind: "rule",
+				text: line,
+				source: {
+					kind: "rule",
+					choice: entry.requestId,
+					...(entry.batch ? { batch: entry.batch } : {}),
+					decisions: together.map(({ decision }) => ({
+						id: decision.id,
+						pr: decision.pr,
+						lead: decision.lead,
+					})),
+				},
+				...(sent && sent !== line ? { replaces: sent } : {}),
+			},
+		];
+	});
+	announce(`${rule ? "Rule rewritten" : "Rule made"} · u undoes it`);
+	return true;
+};
+
+const download = (text, name, type) => {
+	const url = URL.createObjectURL(new Blob([text], { type }));
+	const link = document.createElement("a");
+	link.href = url;
+	link.download = name;
+	link.click();
+	setTimeout(() => URL.revokeObjectURL(url), 1000);
+};
+
+// The desk writes the handover as a folder, out of the choices it keeps,
+// where a new session in the Claude app can read it; `preview` answers
+// what it would write, file by file, and writes nothing.
+const post = async (path, body = {}) => {
+	const focus = tools.dataset.part
+		? `?part=${encodeURIComponent(tools.dataset.part)}`
+		: "";
+	const response = await fetch(
+		`/bursts/${encodeURIComponent(burst)}/${path}${focus}`,
+		{
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				"X-CSRF-Token":
+					document.querySelector('meta[name="csrf-token"]')?.content ?? "",
+			},
+			body: JSON.stringify(body),
+		},
+	);
+	if (!response.ok) throw new Error(`the desk answered ${response.status}`);
+	return response;
+};
+
+export const previewHandover = async () =>
+	(await post("prompt/preview")).text();
+
+// `again` takes back what an agent took and never answered: the desk holds
+// it back otherwise, so that two agents never do the same work.
+let handingOver = false;
+export const handOver = async ({ again = false } = {}) => {
+	if (handingOver) return;
+	handingOver = true;
+	const button = tools.querySelector("[data-hand-over]");
+	button.disabled = true;
+	try {
+		announce("Collecting code comments and responses…");
+		await rounds.refresh();
+		await settled();
+		const { file, session, prompt, requests, withAgent } = await (
+			await post("prompt", { again: again === true })
+		).json();
+		// The batch the desk wrote becomes this page's, so its answer is known.
+		await rounds.refresh();
+		Object.assign(tools.querySelector("[data-new-session]"), {
+			href: session,
+			title: file,
+			hidden: false,
+		});
+		// A handover of the whole burst takes in what it holds now: what joined
+		// or left it is no longer news, and what left with choices has been
+		// handed over. A handover of one part leaves the rest as it was.
+		if (!part)
+			fetch(`/bursts/${encodeURIComponent(burst)}/membership/handed_over`, {
+				method: "POST",
+				headers: {
+					"X-CSRF-Token":
+						document.querySelector('meta[name="csrf-token"]')?.content ?? "",
+				},
+			}).catch(() => {});
+		const copied = await navigator.clipboard
+			?.writeText(prompt)
+			.then(() => true)
+			.catch(() => false);
+		announce(
+			`Handover written, ${plural(requests, "request")}: ${file}. “Open a new session with it” starts one in the Claude app that reads it${copied ? ", and its prompt is on the clipboard" : ""}.${withAgent ? ` ${plural(withAgent, "request")} still with an agent that has not answered ${withAgent === 1 ? "was" : "were"} left out: Returned work can hand them over again.` : ""}`,
+		);
+	} catch (error) {
+		announce(
+			`The handover could not be written: ${error.message}. Your browser choices are still here.`,
+		);
+	} finally {
+		handingOver = false;
+		button.disabled = false;
+	}
+};
+
+tools.querySelector("[data-hand-over]").addEventListener("click", handOver);
+tools.querySelector("[data-download-choices]").addEventListener("click", () => {
+	download(
+		JSON.stringify(state, null, 2),
+		`proctolog-${burst}-choices.json`,
+		"application/json",
+	);
+});
+tools
+	.querySelector("[data-import-choices]")
+	.addEventListener("change", async (event) => {
+		const file = event.target.files[0];
+		if (!file) return;
+		try {
+			const restored = merged(state, validate(JSON.parse(await file.text())));
+			persist((data) => Object.assign(data, restored));
+			undo.length = 0;
+			announce("Choices restored. Changed PRs still need review again.");
+		} catch (error) {
+			announce(`Choices could not be restored: ${error.message}`);
+		} finally {
+			event.target.value = "";
+		}
+	});
+
+// Another tab wrote: this one follows it.
+window.addEventListener("storage", (event) => {
+	if (event.key !== storageKey) return;
+	const theirs = mirror();
+	if (revisionOf(theirs) <= revisionOf(state)) return;
+	state = reconcile(theirs);
+	changed();
+});
+
+// A page starts from what the desk kept, unless this browser is ahead of it:
+// a choice made while the desk was away, or made before the desk kept choices
+// at all. Those from before are merged into the desk's once, like a backup.
+const begin = () => {
+	const desk = fromDesk();
+	const here = mirror();
+	const ahead = here && (!desk || revisionOf(here) > revisionOf(desk));
+	const before = here && desk && !here.revision;
+	try {
+		state = reconcile(
+			before ? merged(desk, here) : ahead ? here : desk || blank(),
+		);
+	} catch (error) {
+		// What this browser held stays where it is, for a backup to be made of it by hand.
+		state = reconcile(desk);
+		changed();
+		announce(
+			`This browser's earlier choices could not be joined with the desk's (${error.message}). They are still in this browser's storage; the desk's are shown.`,
+		);
+		return;
+	}
+	if (before) state.revision = revisionOf(desk) + 1;
+	else if (ahead) state.revision = Math.max(revisionOf(here), 1);
+	if (here || desk) writeMirror();
+	if (before || ahead) send();
+	changed();
+	if (unreadable)
+		announce(
+			"What this browser had saved for this burst could not be read, and was left as it is. The desk's choices are shown, and new ones are saved to the desk.",
+		);
+};
+begin();