@kubohiroya/turbowarp-plus-editor-git 0.12.0 → 0.13.0

package/README.ja.md

@@ -16,6 +16,8 @@ Node.js 26 で `npm ci` と `npm test` を実行します。Vite でライブラ
 
 ## Smart HTTP アダプター
 
+`test/smart-http-fixture.js` は、`git-http-backend` を IPv4 のループバックで動かす検証用のフィクスチャです。Node.js の標準モジュールだけを使い、利用側のブラウザーテストが同じ版を使えるよう配布物に含めます。
+
 `@kubohiroya/turbowarp-plus-editor-git/smart-http` の `createGitSmartHttp` に、Git 設定から選んだ GitHub の HTTPS リモート、信頼済みの接続先（`mode` と `proxyOrigin`）、現在のプロキシセッションか `null` を返す関数を渡します。auth パッケージの `GitAuthProvider` を使えます。Git パッケージは必要なセッションの型だけを構造的に参照するため、読み取り専用パネルとアダプターは auth パッケージと独立してインストールできます。
 
 ```ts
@@ -112,6 +114,19 @@ const diffFile = new Blob([patch], {type: 'text/x-diff'});
 
 どちらかの版を作品として読めないときは理由を示し、`fallback` を表示します。`fallback` がなければエラーだけを示します。
 
+### 比べてから選ぶダイアログ
+
+`openProjectComparison(document, options)` は、見出しの付いた複数の比較を 1 つのモーダルに並べ、利用者に操作を選んでもらいます。各 `sections` は `ProjectSourceComparison` と同じ `before`・`after` を取ります。選ばれた `actions` の `id` で解決し、閉じるか Escape では `null` で解決します。最初の操作にフォーカスを置くので、失われるものが少ない操作を先に並べます。作品フォルダは、未保存の編集があるときに「あなたの未保存の編集」と「フォルダでの変更」を並べるのに使います。
+
+```ts
+const choice = await openProjectComparison(document, {
+    title: '外部の変更と未保存の編集',
+    sections: [{title: 'あなたの未保存の編集', before: base, after: edited}, {title: 'フォルダでの変更', before: base, after: disk}],
+    actions: [{id: 'keep', label: '編集を残す'}, {id: 'discard', label: '編集を破棄してフォルダから読み込む'}],
+    renderBlock, locale: 'ja'
+});
+```
+
 ## 公開
 
 npm への公開は `.github/workflows/release.yml` が行う。`package.json` の版と同じ `v<版>` のタグを

package/README.md

@@ -16,6 +16,8 @@ The panel structure and local Git approach were informed by [duff](https://githu
 
 ## Smart HTTP adapter
 
+`test/smart-http-fixture.js` runs `git-http-backend` on the IPv4 loopback for tests. It uses only Node.js built-in modules and ships in the package so browser tests of a host use the fixture of the same version.
+
 Import `createGitSmartHttp` from `@kubohiroya/turbowarp-plus-editor-git/smart-http`. Pass the selected GitHub HTTPS remote from Git config, a trusted connection (`mode` and `proxyOrigin`), and a function that returns the current proxy session or `null`. A `GitAuthProvider` from the auth package satisfies this contract. The Git package uses the session fields structurally, so the read-only panel and the adapter can be installed independently of the auth package.
 
 ```ts
@@ -35,6 +37,19 @@ Each receive-pack POST carries a new UUID v4 in `Git-Push-Id`. A browser replay
 
 When the Editor host supplies connection settings, the Local Git panel offers fetch, fast-forward pull and push for the current branch and its existing GitHub HTTPS `origin`. Authorize push when connecting to enable the explicit push action. Fetch updates Git metadata. Pull requires a stopped project, a clean worktree, and regular non-executable files. Pull stages the changes, rechecks the local state, and then applies them. Reopen the project from the panel after a successful pull.
 
+## Comparing before choosing
+
+`openProjectComparison(document, options)` lays several titled comparisons of `project.source.json` texts in one modal and asks the user to choose an action. Each of `sections` takes the same `before` and `after` as `ProjectSourceComparison`. The promise resolves with the chosen action's `id`, or with `null` when the dialog is closed or Escape is pressed. The first action receives focus, so list the one that loses the least first. The project folder uses it to show "Your unsaved edits" next to "Changes in the folder" before replacing unsaved edits.
+
+```ts
+const choice = await openProjectComparison(document, {
+    title: 'External changes and your unsaved edits',
+    sections: [{title: 'Your unsaved edits', before: base, after: edited}, {title: 'Changes in the folder', before: base, after: disk}],
+    actions: [{id: 'keep', label: 'Keep My Edits'}, {id: 'discard', label: 'Discard Edits and Load from Folder'}],
+    renderBlock
+});
+```
+
 ## Release
 
 `.github/workflows/release.yml` publishes to npm. Push a `v<version>` tag that names the

package/dist/index.d.ts

@@ -6,6 +6,8 @@ export { createEditorBlockLocator } from './editor-block-locator.js';
 export { createScratchBlocksDiffRenderer } from './scratch-block-diff-renderer.js';
 export type { ScratchBlockDiffRendererOptions, ScratchBlocksPort } from './scratch-block-diff-renderer.js';
 export { openRepository, createReadOnlyFs, GitPanelError } from './repository.js';
+export { openProjectComparison } from './project-comparison.js';
+export type { ProjectComparisonAction, ProjectComparisonOptions, ProjectComparisonSection } from './project-comparison.js';
 export type { Repository, Snapshot, FileChange, FileDiff } from './repository.js';
 export interface GitHost {
     connectionSettings?: GitConnectionSettings;

package/dist/index.js

@@ -1,4 +1,4 @@
-import { _ as useCostumeImage, a as gitHubRepositoryFromOrigin, b as parseProjectSource, g as useAssetImage, i as createGitHubPullRequests, l as organizeProjectChanges, n as createScratchBlocksDiffLocator, o as ProjectSourceComparison, r as PullRequestError, s as ProjectSourceReview, t as createScratchBlocksDiffRenderer, u as projectPropertyLabel } from "./scratch-block-diff-renderer-e_drVlHE.js";
+import { S as parseProjectSource, a as PullRequestError, c as ProjectSourceComparison, d as organizeProjectChanges, f as projectPropertyLabel, i as createScratchBlocksDiffLocator, l as ProjectSourceReview, n as openProjectComparison, o as createGitHubPullRequests, r as createScratchBlocksDiffRenderer, s as gitHubRepositoryFromOrigin, v as useAssetImage, y as useCostumeImage } from "./project-comparison-D1rHzlCw.js";
 import { n as init_objectSpread2, r as __commonJSMin, t as _objectSpread2$1 } from "./objectSpread2-Dkd68nJH.js";
 import { i as createReadOnlyFs, r as GitPanelError, t as openRepository } from "./repository-CtvWYPQ8.js";
 import * as m from "react";
@@ -3557,6 +3557,8 @@ function GitPanel({ vm, document, host, controller }) {
 	const alive = useRef(true);
 	const opening = useRef(false);
 	const dialog = useRef(null);
+	const shownRef = useRef(false);
+	const deferred = useRef(false);
 	const reviewing = useRef(review);
 	reviewing.current = review;
 	const handled = useRef(null);
@@ -3582,6 +3584,11 @@ function GitPanel({ vm, document, host, controller }) {
 		} catch (error) {
 			if (epoch.current !== ticket) return;
 			const code = error instanceof GitPanelError ? error.code : "failed";
+			if (automatic && code === "changed") {
+				handled.current = null;
+				setState((previous) => _objectSpread2$1(_objectSpread2$1({}, previous), {}, { busy: false }));
+				return;
+			}
 			const message = labels[code] || labels.failed;
 			setState((previous) => _objectSpread2$1(_objectSpread2$1({}, previous), {}, {
 				error: automatic && previous.error ? previous.error : message,
@@ -3590,6 +3597,7 @@ function GitPanel({ vm, document, host, controller }) {
 			}));
 		} finally {
 			running.current = false;
+			if (epoch.current !== ticket && !refreshPending.current && alive.current) setState((previous) => _objectSpread2$1(_objectSpread2$1({}, previous), {}, { busy: false }));
 			if (automatic) {
 				background.current = null;
 				settle();
@@ -3632,20 +3640,29 @@ function GitPanel({ vm, document, host, controller }) {
 	};
 	controller.refresh = async (automatic = false) => {
 		if (!alive.current || !current.current.repository) return;
+		if (!shownRef.current) {
+			deferred.current = true;
+			return;
+		}
 		if (running.current) {
 			if (!automatic) refreshPending.current = true;
 			return;
 		}
 		await run(async () => {
 			const { repository, project } = current.current;
-			const snapshot = await repository.read(project !== null && project !== void 0 ? project : "");
-			return {
-				snapshot,
-				changes: snapshot.changes,
-				selected: null,
-				diff: null,
-				commit: null
-			};
+			for (let attempt = 1;; attempt++) try {
+				const snapshot = await repository.read(project !== null && project !== void 0 ? project : "");
+				return {
+					snapshot,
+					changes: snapshot.changes,
+					selected: null,
+					diff: null,
+					commit: null
+				};
+			} catch (error) {
+				if (!(error instanceof GitPanelError && error.code === "changed") || attempt >= 5) throw error;
+				await new Promise((resolve) => setTimeout(resolve, 200 * attempt));
+			}
 		}, automatic);
 	};
 	useEffect(() => {
@@ -3662,7 +3679,7 @@ function GitPanel({ vm, document, host, controller }) {
 					selected: null,
 					diff: null,
 					commit: null,
-					busy: false
+					busy: running.current
 				}));
 				queueMicrotask(() => void controller.refresh());
 			}
@@ -3675,6 +3692,13 @@ function GitPanel({ vm, document, host, controller }) {
 			unsubscribe === null || unsubscribe === void 0 || unsubscribe();
 		};
 	}, [host]);
+	useEffect(() => {
+		shownRef.current = shown;
+		if (shown && deferred.current) {
+			deferred.current = false;
+			controller.refresh();
+		}
+	}, [shown]);
 	useEffect(() => {
 		const repository = state.repository;
 		if (!shown || !repository) return;
@@ -3683,7 +3707,8 @@ function GitPanel({ vm, document, host, controller }) {
 		let checking = false;
 		const check = async () => {
 			const { snapshot } = current.current;
-			if (stopped || checking || running.current || document.visibilityState === "hidden" || !snapshot || current.current.repository !== repository) return;
+			const hidden = !dialog.current || !dialog.current.getClientRects().length;
+			if (stopped || checking || running.current || document.visibilityState === "hidden" || hidden || !snapshot || current.current.repository !== repository) return;
 			checking = true;
 			try {
 				const probe = await repository.probe(snapshot.scope);
@@ -3978,6 +4003,7 @@ function GitPanel({ vm, document, host, controller }) {
 	}) : /* @__PURE__ */ React.createElement("p", null, labels.select))));
 	if (slot) return createPortal(/* @__PURE__ */ React.createElement("div", {
 		className: "twgit-panel twgit-panel-tab",
+		ref: dialog,
 		role: "region",
 		"aria-label": labels.title
 	}, content), slot.element);
@@ -4039,4 +4065,4 @@ function renderGitMenu(createElement, { vm, locale = "en", MenuItem, MenuSection
 		}
 	}, labelsFor(locale).menu));
 }
-export { GitPanelError, createEditorBlockLocator, createReadOnlyFs, createScratchBlocksDiffLocator, createScratchBlocksDiffRenderer, mountGitPanel, openRepository, renderGitMenu };
+export { GitPanelError, createEditorBlockLocator, createReadOnlyFs, createScratchBlocksDiffLocator, createScratchBlocksDiffRenderer, mountGitPanel, openProjectComparison, openRepository, renderGitMenu };

package/dist/{scratch-block-diff-renderer-e_drVlHE.js → project-comparison-D1rHzlCw.js}

@@ -1,6 +1,7 @@
 import { n as init_objectSpread2, t as _objectSpread2 } from "./objectSpread2-Dkd68nJH.js";
 import { a as createTwoFilesPatch, i as isAssetName, n as assetsDirectoryParts, o as hasOnlyUnixLineEndings, r as folderSettingsLimit, s as hasOnlyWinLineEndings, t as assetLimit } from "./project-asset-paths-KV715791.js";
 import React, { useEffect, useMemo, useRef, useState } from "react";
+import { render, unmountComponentAtNode } from "react-dom";
 // node_modules/diff/libesm/patch/line-endings.js
 function unixToWin(patch) {
 	if (Array.isArray(patch)) return patch.map((p) => unixToWin(p));
@@ -2414,4 +2415,81 @@ function createScratchBlocksDiffRenderer(options) {
 		};
 	};
 }
-export { useCostumeImage as _, gitHubRepositoryFromOrigin as a, parseProjectSource as b, assetFileName as c, compareProjectForReview as d, BlockPreview as f, useAssetImage as g, currentCostume as h, createGitHubPullRequests as i, organizeProjectChanges as l, usePreviewSync as m, createScratchBlocksDiffLocator as n, ProjectSourceComparison as o, createPreviewSync as p, PullRequestError as r, ProjectSourceReview as s, createScratchBlocksDiffRenderer as t, projectPropertyLabel as u, compareProjectBlocks as v, readProjectSourceDiff as x, createProjectSourceDiff as y };
+// src/project-comparison.tsx
+init_objectSpread2();
+var focusable = "button:not(:disabled), input:not(:disabled), select:not(:disabled), a[href], summary, [tabindex=\"0\"]";
+/** A modal that lays project comparisons side by side in sections and asks the user to choose an action. */
+function ProjectComparisonDialog({ title, description, notes = [], sections, actions, closeLabel = "Close", renderBlock, locale = "en", onChoose }) {
+	const dialog = useRef(null);
+	const first = useRef(null);
+	useEffect(() => {
+		var _dialog$current, _ref, _first$current;
+		const previous = (_dialog$current = dialog.current) === null || _dialog$current === void 0 ? void 0 : _dialog$current.ownerDocument.activeElement;
+		(_ref = (_first$current = first.current) !== null && _first$current !== void 0 ? _first$current : dialog.current) === null || _ref === void 0 || _ref.focus();
+		return () => {
+			if (previous === null || previous === void 0 ? void 0 : previous.isConnected) previous.focus();
+		};
+	}, []);
+	const keyDown = (event) => {
+		if (event.key === "Escape") {
+			event.stopPropagation();
+			onChoose(null);
+			return;
+		}
+		if (event.key !== "Tab") return;
+		const items = [...event.currentTarget.querySelectorAll(focusable)].filter((item) => item.getClientRects().length > 0);
+		const start = items[0], end = items[items.length - 1];
+		const active = event.currentTarget.ownerDocument.activeElement;
+		if (event.shiftKey && (active === start || active === event.currentTarget)) {
+			event.preventDefault();
+			end === null || end === void 0 || end.focus();
+		} else if (!event.shiftKey && active === end) {
+			event.preventDefault();
+			start === null || start === void 0 || start.focus();
+		}
+	};
+	return /* @__PURE__ */ React.createElement("div", { className: "twgit-backdrop" }, /* @__PURE__ */ React.createElement("div", {
+		className: "twgit-panel twgit-comparison",
+		ref: dialog,
+		tabIndex: -1,
+		role: "dialog",
+		"aria-modal": "true",
+		"aria-label": title,
+		onKeyDown: keyDown
+	}, /* @__PURE__ */ React.createElement("header", null, /* @__PURE__ */ React.createElement("h2", null, title), /* @__PURE__ */ React.createElement("button", {
+		type: "button",
+		onClick: () => onChoose(null)
+	}, closeLabel)), /* @__PURE__ */ React.createElement("div", { className: "twgit-comparison-body" }, description && /* @__PURE__ */ React.createElement("p", null, description), notes.map((note) => /* @__PURE__ */ React.createElement("p", {
+		key: note,
+		role: "note"
+	}, note)), sections.map((section) => /* @__PURE__ */ React.createElement("section", {
+		key: section.title,
+		"aria-label": section.title,
+		"data-twgit-comparison": ""
+	}, /* @__PURE__ */ React.createElement("h3", null, section.title), /* @__PURE__ */ React.createElement(ProjectSourceComparison, {
+		before: section.before,
+		after: section.after,
+		renderBlock,
+		locale
+	})))), /* @__PURE__ */ React.createElement("footer", { className: "twgit-comparison-actions" }, actions.map((action, index) => /* @__PURE__ */ React.createElement("button", {
+		key: action.id,
+		type: "button",
+		ref: index === 0 ? first : void 0,
+		"data-twgit-action": action.id,
+		onClick: () => onChoose(action.id)
+	}, action.label)))));
+}
+/** Shows {@link ProjectComparisonDialog} and resolves with the chosen action's id, or `null` when it is closed. */
+function openProjectComparison(document, options) {
+	const root = document.createElement("div");
+	document.body.append(root);
+	return new Promise((resolve) => {
+		const choose = (action) => {
+			unmountComponentAtNode(root);
+			root.remove();
+			resolve(action);
+		};
+		render(/* @__PURE__ */ React.createElement(ProjectComparisonDialog, _objectSpread2(_objectSpread2({}, options), {}, { onChoose: choose })), root);
+	});
+}
+export { readProjectSourceDiff as C, parseProjectSource as S, currentCostume as _, PullRequestError as a, compareProjectBlocks as b, ProjectSourceComparison as c, organizeProjectChanges as d, projectPropertyLabel as f, usePreviewSync as g, createPreviewSync as h, createScratchBlocksDiffLocator as i, ProjectSourceReview as l, BlockPreview as m, openProjectComparison as n, createGitHubPullRequests as o, compareProjectForReview as p, createScratchBlocksDiffRenderer as r, gitHubRepositoryFromOrigin as s, ProjectComparisonDialog as t, assetFileName as u, useAssetImage as v, createProjectSourceDiff as x, useCostumeImage as y };

package/dist/project-comparison.d.ts

@@ -0,0 +1,31 @@
+import React from 'react';
+import type { ProjectBlockRenderer } from './scratch-block-diff-renderer.js';
+/** One comparison of two project.source.json texts, shown under its own heading. */
+export interface ProjectComparisonSection {
+    title: string;
+    before: string | null;
+    after: string | null;
+}
+export interface ProjectComparisonAction {
+    id: string;
+    label: string;
+}
+export interface ProjectComparisonOptions {
+    title: string;
+    description?: string;
+    /** Notes shown after the description, such as edits the comparison cannot show. */
+    notes?: readonly string[];
+    sections: readonly ProjectComparisonSection[];
+    /** The first action is the one the dialog focuses. Closing the dialog or pressing Escape chooses none. */
+    actions: readonly ProjectComparisonAction[];
+    closeLabel?: string;
+    renderBlock: ProjectBlockRenderer;
+    locale?: string;
+}
+export interface ProjectComparisonDialogProps extends ProjectComparisonOptions {
+    onChoose(action: string | null): void;
+}
+/** A modal that lays project comparisons side by side in sections and asks the user to choose an action. */
+export declare function ProjectComparisonDialog({ title, description, notes, sections, actions, closeLabel, renderBlock, locale, onChoose }: ProjectComparisonDialogProps): React.JSX.Element;
+/** Shows {@link ProjectComparisonDialog} and resolves with the chosen action's id, or `null` when it is closed. */
+export declare function openProjectComparison(document: Document, options: ProjectComparisonOptions): Promise<string | null>;

package/dist/project-source-diff.d.ts

@@ -4,6 +4,8 @@ import type { ProjectBlockRenderer } from './scratch-block-diff-renderer.js';
 import './project-source-diff.css';
 export { createGitHubPullRequests, gitHubRepositoryFromOrigin } from './github-pull-requests.js';
 export { ProjectSourceComparison, ProjectSourceReview } from './project-source-review.js';
+export { ProjectComparisonDialog, openProjectComparison } from './project-comparison.js';
+export type { ProjectComparisonAction, ProjectComparisonDialogProps, ProjectComparisonOptions, ProjectComparisonSection } from './project-comparison.js';
 export type { ProjectSourceComparisonProps, ProjectSourceReviewFile, ProjectSourceReviewProps } from './project-source-review.js';
 export { createScratchBlocksDiffLocator } from './block-diff-location.js';
 export type { ProjectBlockLocation, ProjectBlockLocator, ScratchBlockLocationWorkspace } from './block-diff-location.js';

package/dist/project-source-diff.js

@@ -1,4 +1,4 @@
-import { a as gitHubRepositoryFromOrigin, c as assetFileName, d as compareProjectForReview, f as BlockPreview, h as currentCostume, i as createGitHubPullRequests, l as organizeProjectChanges, m as usePreviewSync, n as createScratchBlocksDiffLocator, o as ProjectSourceComparison, p as createPreviewSync, s as ProjectSourceReview, t as createScratchBlocksDiffRenderer, u as projectPropertyLabel, v as compareProjectBlocks, x as readProjectSourceDiff, y as createProjectSourceDiff } from "./scratch-block-diff-renderer-e_drVlHE.js";
+import { C as readProjectSourceDiff, _ as currentCostume, b as compareProjectBlocks, c as ProjectSourceComparison, d as organizeProjectChanges, f as projectPropertyLabel, g as usePreviewSync, h as createPreviewSync, i as createScratchBlocksDiffLocator, l as ProjectSourceReview, m as BlockPreview, n as openProjectComparison, o as createGitHubPullRequests, p as compareProjectForReview, r as createScratchBlocksDiffRenderer, s as gitHubRepositoryFromOrigin, t as ProjectComparisonDialog, u as assetFileName, x as createProjectSourceDiff } from "./project-comparison-D1rHzlCw.js";
 import { n as init_objectSpread2, t as _objectSpread2 } from "./objectSpread2-Dkd68nJH.js";
 import React, { useEffect, useMemo, useRef, useState } from "react";
 // src/project-source-diff.tsx
@@ -169,4 +169,4 @@ function ProjectSourceBlockDiff({ patch, beforeSource, renderBlock, locateBlock,
 		})
 	}, labels.more));
 }
-export { ProjectSourceBlockDiff, ProjectSourceComparison, ProjectSourceReview, assetFileName, compareProjectForReview, createGitHubPullRequests, createPreviewSync, createProjectSourceDiff, createScratchBlocksDiffLocator, createScratchBlocksDiffRenderer, currentCostume, gitHubRepositoryFromOrigin, organizeProjectChanges, projectPropertyLabel };
+export { ProjectComparisonDialog, ProjectSourceBlockDiff, ProjectSourceComparison, ProjectSourceReview, assetFileName, compareProjectForReview, createGitHubPullRequests, createPreviewSync, createProjectSourceDiff, createScratchBlocksDiffLocator, createScratchBlocksDiffRenderer, currentCostume, gitHubRepositoryFromOrigin, openProjectComparison, organizeProjectChanges, projectPropertyLabel };

package/dist/style.css

@@ -179,4 +179,8 @@
 .twgit-git-details > .twgit-connection-body { left: auto; right: 0; }
 /* In a layout tab the panel fills the tab and leaves the Editor beside it. */
 .twgit-panel.twgit-panel-tab { width: 100%; height: 100%; border: 0; border-radius: 0; box-shadow: none; }
+.twgit-comparison-body { flex: 1; overflow: auto; padding: 12px 16px; }
+.twgit-comparison-body > p { margin: 0 0 8px; }
+.twgit-comparison-body > section { margin-top: 16px; }
+.twgit-comparison-actions { display: flex; gap: 8px; justify-content: flex-end; padding: 10px 16px; border-top: 1px solid GrayText; }
 /*$vite$:1*/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubohiroya/turbowarp-plus-editor-git",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Read-only local Git panel for TurboWarp Plus Editor",
   "type": "module",
   "license": "MPL-2.0",
@@ -36,6 +36,7 @@
     "tsconfig.json",
     "README.ja.md",
     "THIRD_PARTY_NOTICES.md",
+    "test/smart-http-fixture.js",
     "README.md",
     "LICENSE"
   ],

package/src/index.tsx

@@ -22,6 +22,8 @@ export {createScratchBlocksDiffRenderer} from './scratch-block-diff-renderer.js'
 export type {ScratchBlockDiffRendererOptions, ScratchBlocksPort} from './scratch-block-diff-renderer.js';
 
 export {openRepository, createReadOnlyFs, GitPanelError} from './repository.js';
+export {openProjectComparison} from './project-comparison.js';
+export type {ProjectComparisonAction, ProjectComparisonOptions, ProjectComparisonSection} from './project-comparison.js';
 export type {Repository, Snapshot, FileChange, FileDiff} from './repository.js';
 
 export interface GitHost {
@@ -93,6 +95,9 @@ function GitPanel({vm, document, host, controller}: {vm: object; document: Docum
     const alive = useRef(true);
     const opening = useRef(false);
     const dialog = useRef<HTMLDivElement>(null);
+    // A closed panel reads nothing; a refresh asked while it is closed waits until it opens again.
+    const shownRef = useRef(false);
+    const deferred = useRef(false);
     const reviewing = useRef(review);
     reviewing.current = review;
     // The last fingerprint acted on, so a failing read or an open diff is not retried on every check.
@@ -115,10 +120,20 @@ function GitPanel({vm, document, host, controller}: {vm: object; document: Docum
         } catch (error) {
             if (epoch.current !== ticket) return;
             const code = error instanceof GitPanelError ? error.code : 'failed';
+            // A background read that met another tool still writing tries again on the next check, without an alert.
+            if (automatic && code === 'changed') {
+                handled.current = null;
+                setState(previous => ({...previous, busy: false}));
+                return;
+            }
             const message = labels[code as keyof typeof labels] || labels.failed;
             setState(previous => ({...previous, error: automatic && previous.error ? previous.error : message, busy: false, diff: null}));
         } finally {
             running.current = false;
+            // A result dropped by a newer load still ends the busy state, unless a refresh follows at once.
+            if (epoch.current !== ticket && !refreshPending.current && alive.current) {
+                setState(previous => ({...previous, busy: false}));
+            }
             if (automatic) {background.current = null; settle();}
             if (refreshPending.current) {
                 refreshPending.current = false;
@@ -143,14 +158,26 @@ function GitPanel({vm, document, host, controller}: {vm: object; document: Docum
     };
     controller.refresh = async (automatic = false) => {
         if (!alive.current || !current.current.repository) return;
+        if (!shownRef.current) {
+            deferred.current = true;
+            return;
+        }
         if (running.current) {
             if (!automatic) refreshPending.current = true;
             return;
         }
         await run(async () => {
             const {repository, project} = current.current;
-            const snapshot = await repository!.read(project ?? '');
-            return {snapshot, changes: snapshot.changes, selected: null, diff: null, commit: null};
+            // A save or a Git command may still be finishing its writes; read again briefly before reporting a change.
+            for (let attempt = 1; ; attempt++) {
+                try {
+                    const snapshot = await repository!.read(project ?? '');
+                    return {snapshot, changes: snapshot.changes, selected: null, diff: null, commit: null};
+                } catch (error) {
+                    if (!(error instanceof GitPanelError && error.code === 'changed') || attempt >= 5) throw error;
+                    await new Promise(resolve => setTimeout(resolve, 200 * attempt));
+                }
+            }
         }, automatic);
     };
     useEffect(() => {
@@ -159,13 +186,21 @@ function GitPanel({vm, document, host, controller}: {vm: object; document: Docum
             setDirty(host.isProjectDirty());
             if (event === 'loaded' && !opening.current) {
                 epoch.current++;
+                // An operation still running stays busy; its end, or the refresh queued after it, clears the flag.
                 setState(previous => ({...previous, project: null, snapshot: null, changes: [],
-                    selected: null, diff: null, commit: null, busy: false}));
+                    selected: null, diff: null, commit: null, busy: running.current}));
                 queueMicrotask(() => void controller.refresh());
             }
         });
         return () => {alive.current = false; epoch.current++; remoteRequest.current?.abort(); unsubscribe?.();};
     }, [host]);
+    useEffect(() => {
+        shownRef.current = shown;
+        if (shown && deferred.current) {
+            deferred.current = false;
+            void controller.refresh();
+        }
+    }, [shown]);
     // While the panel is open, notice Git commands, agents and editors that change the repository outside the Editor.
     useEffect(() => {
         const repository = state.repository;
@@ -175,7 +210,9 @@ function GitPanel({vm, document, host, controller}: {vm: object; document: Docum
         let checking = false;
         const check = async () => {
             const {snapshot} = current.current;
-            if (stopped || checking || running.current || document.visibilityState === 'hidden' ||
+            // A tab behind another one has no boxes; it reads again when it is shown.
+            const hidden = !dialog.current || !dialog.current.getClientRects().length;
+            if (stopped || checking || running.current || document.visibilityState === 'hidden' || hidden ||
                 !snapshot || current.current.repository !== repository) return;
             checking = true;
             try {
@@ -409,7 +446,7 @@ function GitPanel({vm, document, host, controller}: {vm: object; document: Docum
             </div>}
     </>;
     // In a tab the Editor stays usable beside the panel, so there is no backdrop, focus trap or Escape to close.
-    if (slot) return createPortal(<div className="twgit-panel twgit-panel-tab" role="region" aria-label={labels.title}>{content}</div>,
+    if (slot) return createPortal(<div className="twgit-panel twgit-panel-tab" ref={dialog} role="region" aria-label={labels.title}>{content}</div>,
         slot.element);
     return <div className="twgit-backdrop">
         <div className="twgit-panel" ref={dialog} tabIndex={-1} role="dialog" aria-modal="true" aria-label={labels.title}

package/src/project-comparison.tsx

@@ -0,0 +1,88 @@
+import React, {useEffect, useRef} from 'react';
+import {render, unmountComponentAtNode} from 'react-dom';
+import {ProjectSourceComparison} from './project-source-review.js';
+import type {ProjectBlockRenderer} from './scratch-block-diff-renderer.js';
+
+/** One comparison of two project.source.json texts, shown under its own heading. */
+export interface ProjectComparisonSection {
+    title: string;
+    before: string | null;
+    after: string | null;
+}
+export interface ProjectComparisonAction {
+    id: string;
+    label: string;
+}
+export interface ProjectComparisonOptions {
+    title: string;
+    description?: string;
+    /** Notes shown after the description, such as edits the comparison cannot show. */
+    notes?: readonly string[];
+    sections: readonly ProjectComparisonSection[];
+    /** The first action is the one the dialog focuses. Closing the dialog or pressing Escape chooses none. */
+    actions: readonly ProjectComparisonAction[];
+    closeLabel?: string;
+    renderBlock: ProjectBlockRenderer;
+    locale?: string;
+}
+export interface ProjectComparisonDialogProps extends ProjectComparisonOptions {
+    onChoose(action: string | null): void;
+}
+
+const focusable = 'button:not(:disabled), input:not(:disabled), select:not(:disabled), a[href], summary, [tabindex="0"]';
+
+/** A modal that lays project comparisons side by side in sections and asks the user to choose an action. */
+export function ProjectComparisonDialog({title, description, notes = [], sections, actions, closeLabel = 'Close',
+    renderBlock, locale = 'en', onChoose}: ProjectComparisonDialogProps) {
+    const dialog = useRef<HTMLDivElement>(null);
+    const first = useRef<HTMLButtonElement>(null);
+    useEffect(() => {
+        const previous = dialog.current?.ownerDocument.activeElement as HTMLElement | null;
+        (first.current ?? dialog.current)?.focus();
+        return () => {if (previous?.isConnected) previous.focus();};
+    }, []);
+    const keyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
+        if (event.key === 'Escape') {event.stopPropagation(); onChoose(null); return;}
+        if (event.key !== 'Tab') return;
+        const items = [...event.currentTarget.querySelectorAll<HTMLElement>(focusable)].filter(item => item.getClientRects().length > 0);
+        const start = items[0], end = items[items.length - 1];
+        const active = event.currentTarget.ownerDocument.activeElement;
+        if (event.shiftKey && (active === start || active === event.currentTarget)) {event.preventDefault(); end?.focus();}
+        else if (!event.shiftKey && active === end) {event.preventDefault(); start?.focus();}
+    };
+    return <div className="twgit-backdrop">
+        <div className="twgit-panel twgit-comparison" ref={dialog} tabIndex={-1} role="dialog" aria-modal="true"
+            aria-label={title} onKeyDown={keyDown}>
+            <header>
+                <h2>{title}</h2>
+                <button type="button" onClick={() => onChoose(null)}>{closeLabel}</button>
+            </header>
+            <div className="twgit-comparison-body">
+                {description && <p>{description}</p>}
+                {notes.map(note => <p key={note} role="note">{note}</p>)}
+                {sections.map(section => <section key={section.title} aria-label={section.title} data-twgit-comparison="">
+                    <h3>{section.title}</h3>
+                    <ProjectSourceComparison before={section.before} after={section.after} renderBlock={renderBlock} locale={locale}/>
+                </section>)}
+            </div>
+            <footer className="twgit-comparison-actions">
+                {actions.map((action, index) => <button key={action.id} type="button" ref={index === 0 ? first : undefined}
+                    data-twgit-action={action.id} onClick={() => onChoose(action.id)}>{action.label}</button>)}
+            </footer>
+        </div>
+    </div>;
+}
+
+/** Shows {@link ProjectComparisonDialog} and resolves with the chosen action's id, or `null` when it is closed. */
+export function openProjectComparison(document: Document, options: ProjectComparisonOptions): Promise<string | null> {
+    const root = document.createElement('div');
+    document.body.append(root);
+    return new Promise(resolve => {
+        const choose = (action: string | null) => {
+            unmountComponentAtNode(root);
+            root.remove();
+            resolve(action);
+        };
+        render(<ProjectComparisonDialog {...options} onChoose={choose}/>, root);
+    });
+}

package/src/project-source-diff.tsx

@@ -9,6 +9,8 @@ import './project-source-diff.css';
 
 export {createGitHubPullRequests, gitHubRepositoryFromOrigin} from './github-pull-requests.js';
 export {ProjectSourceComparison, ProjectSourceReview} from './project-source-review.js';
+export {ProjectComparisonDialog, openProjectComparison} from './project-comparison.js';
+export type {ProjectComparisonAction, ProjectComparisonDialogProps, ProjectComparisonOptions, ProjectComparisonSection} from './project-comparison.js';
 export type {ProjectSourceComparisonProps, ProjectSourceReviewFile, ProjectSourceReviewProps} from './project-source-review.js';
 
 export {createScratchBlocksDiffLocator} from './block-diff-location.js';

package/src/style.css

@@ -57,3 +57,7 @@
 .twgit-git-details > .twgit-connection-body { left: auto; right: 0; }
 /* In a layout tab the panel fills the tab and leaves the Editor beside it. */
 .twgit-panel.twgit-panel-tab { width: 100%; height: 100%; border: 0; border-radius: 0; box-shadow: none; }
+.twgit-comparison-body { flex: 1; overflow: auto; padding: 12px 16px; }
+.twgit-comparison-body > p { margin: 0 0 8px; }
+.twgit-comparison-body > section { margin-top: 16px; }
+.twgit-comparison-actions { display: flex; gap: 8px; justify-content: flex-end; padding: 10px 16px; border-top: 1px solid GrayText; }

package/test/smart-http-fixture.js

@@ -0,0 +1,178 @@
+import {execFileSync} from 'node:child_process';
+import {createServer} from 'node:http';
+import {once} from 'node:events';
+import {randomUUID} from 'node:crypto';
+import {mkdtemp, mkdir, rm, writeFile} from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+
+// Git's detached auto maintenance can repack loose objects while the code under test is reading them.
+const gitEnv = {...process.env, GIT_CONFIG_NOSYSTEM: '1', GIT_CONFIG_GLOBAL: '/dev/null', GIT_CONFIG_COUNT: '2',
+    GIT_CONFIG_KEY_0: 'maintenance.auto', GIT_CONFIG_VALUE_0: 'false', GIT_CONFIG_KEY_1: 'gc.auto', GIT_CONFIG_VALUE_1: '0'};
+const backend = join(execFileSync('git', ['--exec-path'], {encoding: 'utf8'}).trim(), 'git-http-backend');
+export const remote = 'https://github.com/fixture/work.git';
+export const readDiscovery = '/info/refs?service=git-upload-pack';
+export const writeDiscovery = '/info/refs?service=git-receive-pack';
+const routePrefix = '/v1/git/fixture/work.git';
+const maxBody = 1024 * 1024;
+const pushIdPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
+
+export function git(dir, ...args) {
+    return execFileSync('git', args, {cwd: dir, encoding: 'utf8', env: gitEnv, stdio: ['ignore', 'pipe', 'pipe']}).trim();
+}
+
+export function commit(dir, message) {
+    git(dir, 'add', 'project.txt');
+    git(dir, '-c', 'user.name=Fixture', '-c', 'user.email=fixture@example.invalid', 'commit', '-qm', message);
+    return git(dir, 'rev-parse', 'HEAD');
+}
+
+export async function startFixture(t) {
+    const root = await mkdtemp(join(tmpdir(), 'tw-git-http-'));
+    t.after(() => rm(root, {recursive: true, force: true}));
+    await mkdir(join(root, 'fixture'));
+    const bare = join(root, 'fixture/work.git');
+    const seed = join(root, 'seed');
+    const client = join(root, 'client');
+    git(root, 'init', '-q', '--bare', '-b', 'main', bare);
+    git(bare, 'config', 'http.receivepack', 'true');
+    git(root, 'init', '-q', '-b', 'main', seed);
+    await writeFile(join(seed, 'project.txt'), 'initial\n');
+    commit(seed, 'initial');
+    git(seed, 'push', bare, 'main');
+    git(root, 'clone', '-q', bare, client);
+    git(client, 'remote', 'set-url', 'origin', remote);
+    git(client, 'config', 'http.corsProxy', 'https://rejected.example.invalid');
+
+    const origins = new Set(['https://editor.example.invalid']);
+    const sessions = new Map([
+        ['fixture-read', {write: false, mode: 'desktop'}],
+        ['fixture-write', {write: true, mode: 'desktop'}],
+        ['fixture-expired', {expires: true}],
+        ['fixture-cloudflare', {write: true, mode: 'cloudflare'}]
+    ]);
+    const requests = [];
+    const upstream = [];
+    const pushIds = new WeakMap();
+    const fixture = {root, bare, seed, client, origins, sessions, requests, upstream, redirect: false, dropPush: false};
+    const reply = (res, status, code) => {
+        res.writeHead(status, {'Content-Type': 'application/json'});
+        res.end(JSON.stringify({code, requestId: randomUUID()}));
+    };
+
+    async function handle(req, res) {
+        const {url, method, headers} = req;
+        requests.push({url, method, headers});
+        if (headers.host !== new URL(fixture.origin).host || req.socket.remoteAddress !== '127.0.0.1' ||
+            !origins.has(headers.origin)) return reply(res, 403, 'FORBIDDEN');
+
+        res.setHeader('Access-Control-Allow-Origin', headers.origin);
+        res.setHeader('Vary', 'Origin, Access-Control-Request-Method, Access-Control-Request-Headers');
+        res.setHeader('Cache-Control', 'no-store');
+        const effectiveMethod = method === 'OPTIONS' ? headers['access-control-request-method'] : method;
+        const path = url.startsWith(routePrefix + '/') ? url.slice(routePrefix.length) : '';
+        const service = ['git-upload-pack', 'git-receive-pack'].find(service =>
+            (effectiveMethod === 'GET' && path === '/info/refs?service=' + service) ||
+            (effectiveMethod === 'POST' && path === '/' + service));
+        if (!service) return reply(res, 400, 'BAD_REQUEST');
+        const push = effectiveMethod === 'POST' && service === 'git-receive-pack';
+        const requestType = 'application/x-' + service + '-request';
+        if (method === 'OPTIONS') {
+            const allowed = effectiveMethod === 'GET' ? ['authorization'] : ['authorization', 'content-type'];
+            if (push) allowed.push('git-push-id');
+            const asked = (headers['access-control-request-headers'] ?? '').toLowerCase().split(',').map(name => name.trim());
+            if (asked.some(name => !allowed.includes(name))) return reply(res, 403, 'FORBIDDEN');
+            res.writeHead(204, {'Access-Control-Allow-Methods': effectiveMethod, 'Access-Control-Allow-Headers': allowed.join(', ')});
+            return res.end();
+        }
+        const session = headers.authorization?.startsWith('Bearer ') && sessions.get(headers.authorization.slice(7));
+        if (!session) return reply(res, 401, 'SESSION_REQUIRED');
+        if (session.expires) return reply(res, 401, 'SESSION_EXPIRED');
+        if (session.mode !== 'desktop' || (service === 'git-receive-pack' && !session.write)) return reply(res, 403, 'FORBIDDEN');
+        if (fixture.redirect) {
+            if (fixture.redirect === 'upstream') return reply(res, 409, 'REDIRECT_REJECTED');
+            res.writeHead(307, {Location: fixture.origin + '/redirect-target'});
+            return res.end();
+        }
+
+        let input;
+        if (method === 'POST') {
+            if (headers['content-type'] !== requestType) return reply(res, 400, 'BAD_REQUEST');
+            if (!/^\d+$/u.test(headers['content-length'] ?? '')) return reply(res, 411, 'LENGTH_REQUIRED');
+            const expected = Number(headers['content-length']);
+            if (expected > maxBody) return reply(res, 413, 'PAYLOAD_TOO_LARGE');
+            let size = 0;
+            const chunks = [];
+            for await (const chunk of req) {
+                size += chunk.length;
+                if (size > expected) return reply(res, 400, 'BAD_REQUEST');
+                chunks.push(chunk);
+            }
+            if (size !== expected) return reply(res, 400, 'BAD_REQUEST');
+            input = Buffer.concat(chunks);
+        }
+        const pushId = headers['git-push-id'];
+        if (push ? !pushIdPattern.test(pushId ?? '') || req.headersDistinct['git-push-id']?.length !== 1 :
+            pushId !== undefined) return reply(res, 400, 'BAD_REQUEST');
+        if (push) {
+            let claimed = pushIds.get(session);
+            if (!claimed) {
+                claimed = new Set();
+                pushIds.set(session, claimed);
+            }
+            if (claimed.has(pushId)) return reply(res, 409, 'PUSH_DUPLICATE');
+            claimed.add(pushId);
+        }
+
+        const [pathInfo, query = ''] = ('/fixture/work.git' + path).split('?');
+        // Model the credential boundary and invoke Git's CGI backend locally.
+        const authorization = 'Basic ' + Buffer.from('x-access-token:fixture-upstream-token').toString('base64');
+        upstream.push({method, path: pathInfo, query, authorization});
+        const output = execFileSync(backend, [], {
+            input,
+            env: {...gitEnv, GIT_PROJECT_ROOT: root, GIT_HTTP_EXPORT_ALL: '1', REQUEST_METHOD: method,
+                PATH_INFO: pathInfo, QUERY_STRING: query, REMOTE_USER: 'fixture-user',
+                CONTENT_TYPE: headers['content-type'] ?? '', CONTENT_LENGTH: headers['content-length'] ?? '0'}
+        });
+        const dropPush = fixture.dropPush && method === 'POST' && service === 'git-receive-pack';
+        if (dropPush && fixture.dropPush !== 'after-headers') {
+            res.destroy();
+            return;
+        }
+        const end = output.indexOf('\r\n\r\n');
+        if (end < 0) throw new Error('Git CGI response had no header boundary');
+        const lines = output.subarray(0, end).toString().split('\r\n');
+        const statusLine = lines.find(line => line.startsWith('Status: '));
+        const contentType = lines.find(line => line.startsWith('Content-Type: '));
+        if (contentType) res.setHeader('Content-Type', contentType.slice(14));
+        if (dropPush) {
+            res.setHeader('Content-Length', output.length - end - 3);
+            res.setHeader('Connection', 'close');
+        }
+        res.writeHead(statusLine ? Number(statusLine.slice(8, 11)) : 200);
+        res.end(output.subarray(end + 4));
+    }
+
+    const server = createServer((req, res) => {
+        handle(req, res).catch(() => {
+            if (!res.headersSent) reply(res, 502, 'UPSTREAM_FAILURE');
+            else res.destroy();
+        });
+    });
+    server.listen(0, '127.0.0.1');
+    await once(server, 'listening');
+    t.after(() => new Promise(resolve => {server.close(resolve); server.closeAllConnections();}));
+    fixture.origin = 'http://127.0.0.1:' + server.address().port;
+    return fixture;
+}
+
+export const proxyPath = path => routePrefix + path;
+
+export function adapterOptions(fixture, bearer = 'fixture-write') {
+    const connection = {mode: 'desktop', proxyOrigin: fixture.origin};
+    return {
+        remote, connection,
+        getSession: async () => ({connection, bearer, expiresAt: Date.now() + 60_000}),
+        fetch: (url, init) => fetch(url, {...init, headers: {...Object.fromEntries(init.headers), Origin: 'https://editor.example.invalid'}})
+    };
+}