@moritzwilksch/diffle 0.1.7 → 0.1.9

package/dist/server/main.js

@@ -11,6 +11,7 @@ import { copyFile, lstat, mkdir, mkdtemp, open, readFile, readlink, realpath, re
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { homedir, hostname, tmpdir } from "node:os";
 import { createServer } from "node:http";
+import { getAssetKeys, getRawAsset, isSea } from "node:sea";
 import { Http2ServerRequest, constants as constants$1 } from "http2";
 import { Readable } from "stream";
 import crypto from "crypto";
@@ -3951,7 +3952,7 @@ function generateCompletion(program, { shell, executable = program.name() }) {
 }
 //#endregion
 //#region package.json
-var version$1 = "0.1.7";
+var version$1 = "0.1.9";
 //#endregion
 //#region src/server/comments/anchor.ts
 function splitLines(contents) {
@@ -4198,6 +4199,7 @@ var GitRepo = class GitRepo {
 			new: next
 		};
 	}
+	/** A commit's hash, abbreviation and full message; null when `rev` names no commit. */
 	async commitInfo(rev) {
 		let sha;
 		try {
@@ -4221,6 +4223,66 @@ var GitRepo = class GitRepo {
 			message: output.slice(separator + 1).trimEnd()
 		};
 	}
+	/**
+	* `sha`'s first parent, and the commit toward HEAD whose first parent it is. The
+	* child is null at HEAD, on an unborn branch, or when `sha` is off HEAD's
+	* first-parent line, e.g. on a merged side branch.
+	*/
+	async commitNeighbours(sha) {
+		const [parent, list] = await Promise.all([this.resolve(`${sha}^`).catch((e) => {
+			if (e instanceof GitError && e.code === 1) return null;
+			throw e;
+		}), this.text([
+			"rev-list",
+			"--first-parent",
+			"--ancestry-path",
+			"--parents",
+			`${sha}..HEAD`,
+			"--"
+		]).catch(() => "")]);
+		const [child, firstParent] = list.trim().split("\n").pop()?.split(" ") ?? [];
+		return {
+			parent,
+			child: child && firstParent === sha ? child : null
+		};
+	}
+	/** The commits a revision range such as `a..b` or `c^!` selects, oldest first: the newest `limit`, and the total. */
+	async rangeCommits(range, limit) {
+		const [count, log] = await Promise.all([this.text([
+			"rev-list",
+			"--count",
+			"--end-of-options",
+			range,
+			"--"
+		]), this.text([
+			"log",
+			"-z",
+			"--no-show-signature",
+			"--reverse",
+			`--max-count=${limit}`,
+			"--format=%H%x00%h%x00%an%x00%ae%x00%at%x00%B",
+			"--end-of-options",
+			range,
+			"--"
+		])]);
+		const fields = log.split("\0");
+		const list = [];
+		for (let i = 0; i + 5 < fields.length; i += 6) {
+			const [sha = "", short = "", author = "", email = "", time = "", message = ""] = fields.slice(i, i + 6);
+			list.push({
+				sha,
+				short,
+				message: message.trimEnd(),
+				author,
+				email,
+				date: Number(time) * 1e3
+			});
+		}
+		return {
+			list,
+			total: Number(count.trim())
+		};
+	}
 	/** The empty tree under the repository's hash algorithm: the old side of an unborn branch. */
 	async emptyTree() {
 		return (await this.text([
@@ -4369,7 +4431,7 @@ var GitRepo = class GitRepo {
 	}
 	/**
 	* Changed files between two revs, or a rev and the worktree (incl. untracked).
-	* One diff call yields status, line counts and, against a commit, the new-side
+	* One diff call yields status, line counts and, against a commit, each side's
 	* blob; the worktree's blobs are hashed from disk.
 	*/
 	async numstat(oldRev, newRev) {
@@ -4395,6 +4457,7 @@ var GitRepo = class GitRepo {
 				deletions: 0,
 				binary: false,
 				blob: "",
+				oldBlob: "",
 				generated: false
 			};
 			const st = await lstat(resolve(this.root, path)).catch(() => null);
@@ -4411,44 +4474,68 @@ var GitRepo = class GitRepo {
 			return file;
 		});
 		const all = [...files, ...extra].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
-		if (newRev === "worktree") await this.hashWorktree(all.filter((f) => f.status !== "D"));
+		if (newRev === "worktree") {
+			const present = all.filter((f) => f.status !== "D");
+			(await this.hashWorktree(present)).forEach((sha, i) => present[i].blob = sha);
+		}
+		if (reverse) {
+			const present = all.filter((f) => f.status !== "A");
+			const entries = present.map((f) => ({
+				path: f.oldPath ?? f.path,
+				submodule: f.submodule
+			}));
+			(await this.hashWorktree(entries)).forEach((sha, i) => present[i].oldBlob = sha);
+		}
 		return all;
 	}
 	/**
-	* Sets `blob` to what git would store for each worktree entry: the file's
+	* What git would store for each worktree entry, in order: the file's
 	* blob, a symlink's target blob, a submodule's checked-out commit. Regular
 	* files go to one `hash-object --stdin-paths` call; everything else is hashed
 	* on its own, so a gitlink, a broken link or an unreadable path never fails
 	* the batch. A path containing a newline cannot ride the stdin list either.
-	* A path that cannot be hashed keeps an empty blob.
+	* A path that cannot be hashed gets an empty blob.
 	*/
 	async hashWorktree(files) {
+		const shas = files.map(() => "");
 		const regular = [];
-		await mapLimit(files, READ_CONCURRENCY$1, async (f) => {
-			f.blob = "";
-			if (f.submodule) {
-				f.blob = await this.submoduleHead(f.path);
+		await mapLimit([...files.keys()], READ_CONCURRENCY$1, async (i) => {
+			const { path, submodule } = files[i];
+			if (submodule) {
+				shas[i] = await this.submoduleHead(path);
 				return;
 			}
-			const st = await lstat(resolve(this.root, f.path)).catch(() => null);
-			if (st?.isSymbolicLink()) f.blob = blobSha(Buffer.from(await readlink(resolve(this.root, f.path)), "utf8"));
-			else if (st?.isFile()) regular.push(f);
+			const st = await lstat(resolve(this.root, path)).catch(() => null);
+			if (st?.isSymbolicLink()) shas[i] = blobSha(Buffer.from(await readlink(resolve(this.root, path)), "utf8"));
+			else if (st?.isFile()) regular.push(i);
 		});
-		const batch = regular.filter((f) => !f.path.includes("\n"));
-		const single = regular.filter((f) => f.path.includes("\n"));
+		const batch = regular.filter((i) => !files[i].path.includes("\n"));
+		const single = regular.filter((i) => files[i].path.includes("\n"));
 		if (batch.length) try {
-			const shas = (await this.text(["hash-object", "--stdin-paths"], { input: batch.map((f) => f.path).join("\n") + "\n" })).trim().split("\n");
-			batch.forEach((f, i) => f.blob = shas[i] ?? "");
+			const lines = (await this.text(["hash-object", "--stdin-paths"], { input: batch.map((i) => files[i].path).join("\n") + "\n" })).trim().split("\n");
+			batch.forEach((i, j) => shas[i] = lines[j] ?? "");
 		} catch {
 			single.push(...batch);
 		}
-		await mapLimit(single, READ_CONCURRENCY$1, async (f) => {
-			f.blob = await this.text([
+		await mapLimit(single, READ_CONCURRENCY$1, async (i) => {
+			shas[i] = await this.text([
 				"hash-object",
 				"--",
-				f.path
+				files[i].path
 			]).then((s) => s.trim()).catch(() => "");
 		});
+		return shas;
+	}
+	/**
+	* What git would store for `content` at worktree `path`, its clean filters applied: equals the
+	* snapshot's blob for a worktree file whose bytes are still the snapshot's.
+	*/
+	async hashObject(content, path) {
+		return (await this.text([
+			"hash-object",
+			"--stdin",
+			`--path=${path}`
+		], { input: content })).trim();
 	}
 	/** The commit a checked-out submodule is at, or '' if it is not a repository. */
 	async submoduleHead(path) {
@@ -5048,8 +5135,8 @@ function splitZ(buf) {
 * `-z -M --raw --no-abbrev --numstat`: the raw records come first, then the numstat records,
 * each path-terminated by NUL. Raw: ":mode mode sha sha X\0path\0", renames and
 * copies "R100\0old\0new\0". Numstat: "add\tdel\tpath\0", renames "add\tdel\t\0old\0new\0".
-* Binary files count as "-\t-". The dst sha is the new-side blob against a
-* commit; against the worktree it is zeros and the caller hashes the file.
+* Binary files count as "-\t-". The src and dst shas are each side's blob
+* against a commit; against the worktree, or where a side is absent, they are zeros.
 * Mode 160000 on either side marks a gitlink, which no file operation may touch.
 */
 function parseRawNumstat(buf) {
@@ -5057,7 +5144,7 @@ function parseRawNumstat(buf) {
 	const byPath = /* @__PURE__ */ new Map();
 	let i = 0;
 	for (; i < parts.length && parts[i].startsWith(":"); i++) {
-		const [srcMode = "", dstMode = "", , dstSha = "", code = ""] = parts[i].split(" ");
+		const [srcMode = "", dstMode = "", srcSha = "", dstSha = "", code = ""] = parts[i].split(" ");
 		const status = code[0];
 		const oldPath = status === "R" || status === "C" ? parts[++i] : void 0;
 		const path = parts[++i];
@@ -5068,6 +5155,7 @@ function parseRawNumstat(buf) {
 			deletions: 0,
 			binary: false,
 			blob: /^0+$/.test(dstSha) ? "" : dstSha,
+			oldBlob: /^0+$/.test(srcSha) ? "" : srcSha,
 			generated: false
 		};
 		if (oldPath != null) file.oldPath = oldPath;
@@ -12073,14 +12161,26 @@ const ModeRequestSchema = discriminatedUnion("kind", [
 	object({
 		kind: literal("revspec"),
 		args: string().array()
+	}),
+	object({
+		kind: literal("focus"),
+		commit: string().nullable()
 	})
 ]);
-/** A comparison; both endpoints accept a Git revision or "worktree". */
-const ModeSpecSchema = object({
+/**
+* How the old side is derived: `old` itself, merge-base(old, new) with worktree
+* taken as HEAD, or new's first parent (the empty tree for a root commit).
+*/
+const ComparisonBaseSchema = _enum([
+	"direct",
+	"merge-base",
+	"parent"
+]);
+/** A comparison; both endpoints accept a Git revision or "worktree". Under `parent`, both name the one commit. */
+const ComparisonSchema = object({
 	old: string(),
 	new: string(),
-	/** Compare merge-base(old, new) to new; worktree uses HEAD for the merge base. */
-	mergeBase: boolean(),
+	base: ComparisonBaseSchema,
 	live: _enum([
 		"worktree",
 		"refs",
@@ -12089,10 +12189,18 @@ const ModeSpecSchema = object({
 	/** Fixed when the comparison is entered; discovery never changes comment storage. */
 	commentKey: string()
 });
-/** Display comparison endpoints with branch names instead of internal ref namespaces. */
+const ModeSpecSchema = ComparisonSchema.extend({ 
+/** Set while one commit of a range is focused: the range, whose commits the snapshot keeps listing. */
+within: ComparisonSchema.optional() });
+/**
+* Display comparison endpoints with branch names instead of internal ref namespaces; a single commit as
+* `<sha>^!`, or as `<range> @ <sha>` when focused within a range.
+*/
 function comparisonLabel(mode) {
+	if (mode.within) return `${comparisonLabel(mode.within)} @ ${mode.new.slice(0, 7)}`;
+	if (mode.base === "parent") return `${mode.new.slice(0, 7)}^!`;
 	const name = (rev) => rev.replace(/^refs\/diffle\/[^/]+\/\d+\/(?:base|head)\//, "").replace(/^refs\/(?:heads|remotes)\//, "");
-	return `${name(mode.old)}${mode.mergeBase ? "..." : ".."}${name(mode.new)}`;
+	return `${name(mode.old)}${mode.base === "merge-base" ? "..." : ".."}${name(mode.new)}`;
 }
 const GithubPullRequestSchema = object({
 	repository: string(),
@@ -12135,11 +12243,39 @@ const ChangedFileSchema = object({
 	binary: boolean(),
 	/** New-side blob sha. '' for deletions. Keys the viewed state. */
 	blob: string(),
+	/** Old-side blob sha. '' for additions. A worktree side's blob, like `blob`, is '' when the file cannot be hashed. */
+	oldBlob: string(),
 	/** The `linguist-generated` gitattribute, a path pattern or a content sniff said this file is generated. Feeds auto-collapse and risk ranking. */
 	generated: boolean(),
 	/** A gitlink (mode 160000): `blob` is the recorded commit, the patch shows the commit-id change, and there is no file to open. */
 	submodule: literal(true).optional()
 });
+const CommitInfoSchema = object({
+	sha: string(),
+	short: string(),
+	message: string()
+});
+/** A single reviewed commit and its neighbours along HEAD's first-parent history, for stepping through it. */
+const ReviewedCommitSchema = CommitInfoSchema.extend({
+	/** First parent; null for a root commit. */
+	parent: string().nullable(),
+	/** The commit whose first parent this is, toward HEAD; null at HEAD or off HEAD's first-parent line. */
+	child: string().nullable()
+});
+/**
+* The commits a comparison spans: old..new, with the worktree taken as HEAD, or the one commit under `parent`.
+* A focused commit lists its range's.
+*/
+const RangeCommitsSchema = object({
+	/** Oldest first; the newest MAX_RANGE_COMMITS when there are more. */
+	list: CommitInfoSchema.extend({
+		author: string(),
+		email: string(),
+		/** Author date, epoch milliseconds. */
+		date: number()
+	}).array(),
+	total: number()
+});
 object({
 	root: string(),
 	mode: ModeSpecSchema,
@@ -12154,7 +12290,10 @@ object({
 	context: number(),
 	changed: ChangedFileSchema.array(),
 	/** All paths on the new side: the new commit's tree, or index ∪ untracked for the worktree. Sorted. */
-	tree: string().array()
+	tree: string().array(),
+	/** The reviewed commit when the comparison is a single commit against its parent; otherwise null. */
+	commit: ReviewedCommitSchema.nullable(),
+	commits: RangeCommitsSchema
 });
 /** Body of `POST /api/patch`: the changed files whose patches to return, concatenated. Unknown paths are skipped. */
 const PatchRequestSchema = object({ paths: string().array().max(200) });
@@ -12251,11 +12390,6 @@ const ViewedEntrySchema = object({
 	blob: string(),
 	viewed: boolean()
 });
-const CommitInfoSchema = object({
-	sha: string(),
-	short: string(),
-	message: string()
-});
 object({
 	old: CommitInfoSchema.nullable(),
 	new: CommitInfoSchema.nullable()
@@ -12498,6 +12632,21 @@ const FileQuerySchema = object({
 	path: string().min(1),
 	rev: SideSchema
 });
+/**
+* `GET /api/image`: one side of a file as image bytes. The server answers 404 unless `key` is that side's
+* `imageKey` in its current snapshot, the bytes are still the ones the key names, and they are a raster image.
+*/
+const ImageQuerySchema = FileQuerySchema.extend({ key: string().min(1) });
+/**
+* Names the bytes of one side of `path`, or null when the side has no name: a changed file's blob on that
+* side, else the commit of a side that is one, since an unchanged path is alike on both. What a key names
+* never changes, so an image served under it may be cached for good.
+*/
+function imageKey(snap, path, side) {
+	const file = snap.changed.find((f) => f.path === path);
+	if (file) return (side === "new" ? file.blob : file.oldBlob) || null;
+	return [snap.newSha, snap.oldSha].find((rev) => rev !== "worktree") ?? null;
+}
 const offsetSchema = string().regex(/^[0-9]+$/).transform(Number).pipe(number().int().nonnegative());
 const LastCommitsQuerySchema = object({
 	oldOffset: offsetSchema,
@@ -14001,6 +14150,7 @@ const WORKTREE = "worktree";
 *   "a..b"   → a vs b
 *   "a...b"  → merge-base(a, b) vs b
 *   "a" "b"  → a vs b
+*   "a^!"    → a vs its first parent: the one commit, as git show shows it
 * Empty sides default to HEAD. Either side accepts "worktree" for the uncommitted
 * tree; a merge base against it is taken against HEAD, the commit it sits on.
 */
@@ -14009,34 +14159,45 @@ function parseRevspec(args) {
 	if (args.length === 2) {
 		const [a, b] = args;
 		if (a.includes("..") || b.includes("..")) throw new RevspecError("cannot combine \"..\" with two revisions");
+		if (a.endsWith("^!") || b.endsWith("^!")) throw new RevspecError("cannot combine \"^!\" with two revisions");
 		return {
 			old: a,
 			new: b,
-			mergeBase: false
+			base: "direct"
 		};
 	}
 	const arg = args[0];
+	if (arg.endsWith("^!")) {
+		const commit = arg.slice(0, -2) || "HEAD";
+		if (commit.includes("..")) throw new RevspecError("cannot combine \"^!\" with \"..\"");
+		if (commit === WORKTREE) throw new RevspecError("the worktree is not a commit");
+		return {
+			old: commit,
+			new: commit,
+			base: "parent"
+		};
+	}
 	const three = arg.indexOf("...");
 	if (three !== -1) return {
 		old: arg.slice(0, three) || "HEAD",
 		new: arg.slice(three + 3) || "HEAD",
-		mergeBase: true
+		base: "merge-base"
 	};
 	const two = arg.indexOf("..");
 	if (two !== -1) return {
 		old: arg.slice(0, two) || "HEAD",
 		new: arg.slice(two + 2) || "HEAD",
-		mergeBase: false
+		base: "direct"
 	};
 	if (arg === WORKTREE) return {
 		old: "HEAD",
 		new: WORKTREE,
-		mergeBase: false
+		base: "direct"
 	};
 	return {
 		old: arg,
 		new: "HEAD",
-		mergeBase: true
+		base: "merge-base"
 	};
 }
 var RevspecError = class extends Error {};
@@ -16766,7 +16927,7 @@ const LOOPBACK = /* @__PURE__ */ new Set([
 	"::1",
 	"localhost"
 ]);
-const HINT = "if a reverse proxy sent it, trust that origin with --allowed-origin";
+const UNCONFIGURED = "if a reverse proxy sent it, trust that origin with --allowed-origin";
 /**
 * Restricts API and WebSocket requests to local hosts and the configured public origin.
 * Proxies may preserve the public Host or rewrite it to an allowed upstream Host.
@@ -16780,15 +16941,16 @@ function requestGuard(bindHost, names = ownNames(), allowedOrigin) {
 		...names.map((n) => n.toLowerCase())
 	]);
 	const publicHost = allowedOrigin == null ? void 0 : new URL(allowedOrigin).host;
+	const hint = allowedOrigin == null ? UNCONFIGURED : `allowed origin is "${allowedOrigin}"`;
 	return ({ host, origin }) => {
 		if (!host) return "missing Host header";
 		const name = hostnameOf(host).toLowerCase();
 		const localHost = loopback ? LOOPBACK.has(name) : isIP(name) !== 0 || allowed.has(name);
 		const proxyHost = publicHost != null && host.toLowerCase() === publicHost;
-		if (!localHost && !proxyHost) return `forbidden Host "${host}"; ${HINT}`;
+		if (!localHost && !proxyHost) return `forbidden Host "${host}"; ${hint}`;
 		if (origin == null || allowedOrigin != null && origin === allowedOrigin) return null;
 		if (!proxyHost && parseHost(origin) === host) return null;
-		return `forbidden Origin "${origin}" for Host "${host}"; ${HINT}`;
+		return `forbidden Origin "${origin}" for Host "${host}"; ${hint}`;
 	};
 }
 /** The host of a syntactically valid origin; undefined for `null` and other non-URLs. */
@@ -17285,6 +17447,67 @@ function migrateV1(v1) {
 	};
 }
 //#endregion
+//#region src/server/image.ts
+/** Leading bytes of the raster formats browsers display; `null` matches any byte. */
+const SIGNATURES = [
+	["image/png", [
+		137,
+		80,
+		78,
+		71,
+		13,
+		10,
+		26,
+		10
+	]],
+	["image/jpeg", [
+		255,
+		216,
+		255
+	]],
+	["image/gif", ascii("GIF8")],
+	["image/webp", [
+		...ascii("RIFF"),
+		null,
+		null,
+		null,
+		null,
+		...ascii("WEBP")
+	]],
+	["image/avif", [
+		null,
+		null,
+		null,
+		null,
+		...ascii("ftypavif")
+	]],
+	["image/avif", [
+		null,
+		null,
+		null,
+		null,
+		...ascii("ftypavis")
+	]],
+	["image/bmp", ascii("BM")],
+	["image/x-icon", [
+		0,
+		0,
+		1,
+		0
+	]]
+];
+function ascii(s) {
+	return [...s].map((ch) => ch.charCodeAt(0));
+}
+/**
+* The media type of a raster image, read from its leading bytes; null for anything else. The
+* extension is not consulted: only bytes that are an image get served as one.
+*/
+function imageType(buf) {
+	for (const [type, magic] of SIGNATURES) if (buf.length >= magic.length && magic.every((b, i) => b == null || buf[i] === b)) return type;
+	return null;
+}
+//#endregion
 //#region src/server/routes.ts
 /** Invalid JSON is a request error; failures after parsing still propagate. */
 async function readJson(c) {
@@ -17350,6 +17573,18 @@ function createApi(deps) {
 		};
 		return c.json(body);
 	});
+	app.get("/api/image", async (c) => {
+		const { path, rev, key } = ImageQuerySchema.parse(c.req.query());
+		const buf = await session.readImage(await session.snapshotter.current(), path, rev, key);
+		const type = buf && imageType(buf);
+		if (!type) return c.json({ error: "no image under that key" }, 404);
+		return c.body(new Uint8Array(buf), 200, {
+			"content-type": type,
+			"cache-control": "private, max-age=31536000, immutable",
+			"x-content-type-options": "nosniff",
+			"cross-origin-resource-policy": "same-origin"
+		});
+	});
 	app.get("/api/search", async (c) => {
 		const query = SearchQuerySchema.parse(c.req.query());
 		const { q, scope } = query;
@@ -17588,7 +17823,8 @@ var Server = class {
 		app.use("/api/*", compress());
 		app.route("/", createApi(this.deps));
 		app.all("/api/*", (c) => c.json({ error: "API endpoint not found. Restart diffle to load the latest server." }, 404));
-		if (!this.opts.dev) {
+		if (!this.opts.dev && isSea()) app.get("*", serveEmbedded);
+		else if (!this.opts.dev) {
 			const clientDir = resolveClientDir();
 			app.use("*", serveStatic({ root: clientDir }));
 			app.get("*", serveStatic({
@@ -17675,7 +17911,14 @@ function resolveClientDir() {
 	return join(projectRoot(), "dist", "client");
 }
 function hasClientBuild() {
-	return existsSync(join(resolveClientDir(), "index.html"));
+	return isSea() || existsSync(join(resolveClientDir(), "index.html"));
+}
+const embedded = isSea() ? new Set(getAssetKeys()) : /* @__PURE__ */ new Set();
+function serveEmbedded(c) {
+	const path = c.req.path.slice(1);
+	const key = embedded.has(path) ? path : "index.html";
+	const type = getMimeType(key) ?? "application/octet-stream";
+	return c.body(new Uint8Array(getRawAsset(key)), 200, { "content-type": type });
 }
 //#endregion
 //#region src/server/github/pulls.ts
@@ -18190,17 +18433,19 @@ function describe(skipped) {
 *   A--B--C  main
 *       \--D--E  HEAD
 *
-*   old       new       mergeBase   oldSha      newSha     live
-*   main      HEAD      false       C           E          refs
-*   main      HEAD      true        B           E          refs
-*   HEAD      worktree  false       E           worktree   worktree
-*   worktree  HEAD      false       worktree    E          worktree
-*   main      worktree  true        B           worktree   worktree
-*   <C hash>  <E hash>  false       C           E          none
+*   old       new       base        oldSha      newSha     live
+*   main      HEAD      direct      C           E          refs
+*   main      HEAD      merge-base  B           E          refs
+*   HEAD      worktree  direct      E           worktree   worktree
+*   worktree  HEAD      direct      worktree    E          worktree
+*   main      worktree  merge-base  B           worktree   worktree
+*   <C hash>  <E hash>  direct      C           E          none
+*   <E hash>  <E hash>  parent      D           E          none
 *
-* mergeBase replaces only the old endpoint with the common ancestor, using
-* HEAD for any worktree input. live is "worktree" if either input is worktree,
-* "none" if both inputs are pinned hashes, and "refs" otherwise.
+* merge-base replaces only the old endpoint with the common ancestor, using
+* HEAD for any worktree input; parent replaces it with new's first parent, or
+* the empty tree for a root commit. live is "worktree" if either input is
+* worktree, "none" if both inputs are pinned hashes, and "refs" otherwise.
 *
 * In an unborn repository, HEAD compared directly with worktree resolves to
 * the empty tree. Invalid revisions or missing merge bases throw RevspecError.
@@ -18212,14 +18457,14 @@ async function resolveComparison(repo, comparison) {
 		try {
 			return await repo.resolve(rev);
 		} catch (e) {
-			if (!comparison.mergeBase && rev === "HEAD" && endpoints.includes("worktree") && e instanceof GitError && e.code === 1) return repo.emptyTree();
+			if (comparison.base === "direct" && rev === "HEAD" && endpoints.includes("worktree") && e instanceof GitError && e.code === 1) return repo.emptyTree();
 			if (e instanceof GitError) throw new RevspecError(`unknown revision: ${rev}`);
 			throw e;
 		}
 	};
 	const [old, next] = await Promise.all([resolve(comparison.old), resolve(comparison.new)]);
 	let oldSha = old;
-	if (comparison.mergeBase) {
+	if (comparison.base === "merge-base") {
 		const [a, b] = await Promise.all([old === "worktree" ? resolve("HEAD") : old, next === "worktree" ? resolve("HEAD") : next]);
 		try {
 			oldSha = await repo.mergeBase(a, b);
@@ -18228,6 +18473,13 @@ async function resolveComparison(repo, comparison) {
 			throw e;
 		}
 	}
+	if (comparison.base === "parent") {
+		if (next === "worktree") throw new RevspecError("the worktree is not a commit");
+		oldSha = await repo.resolve(`${next}^`).catch((e) => {
+			if (e instanceof GitError && e.code === 1) return repo.emptyTree();
+			throw e;
+		});
+	}
 	const pinned = (rev, sha) => rev.length >= 7 && sha.startsWith(rev.toLowerCase());
 	return {
 		oldSha,
@@ -18241,8 +18493,18 @@ async function resolveReview(req, repo, github) {
 	const parsed = req.kind === "working" ? {
 		old: "HEAD",
 		new: "worktree",
-		mergeBase: false
+		base: "direct"
 	} : parseRevspec(req.args);
+	if (parsed.base === "parent") {
+		const { newSha: sha } = await resolveComparison(repo, parsed);
+		return { mode: {
+			old: sha,
+			new: sha,
+			base: "parent",
+			live: "none",
+			commentKey: `commit:${sha}`
+		} };
+	}
 	const { oldSha, newSha, live } = await resolveComparison(repo, parsed);
 	return { mode: {
 		...parsed,
@@ -18252,19 +18514,21 @@ async function resolveReview(req, repo, github) {
 }
 /**
 * Branch identities keep review state stable across pushes and local branch aliases.
+* Keys read like the comparison, with ... for a merge base and .. otherwise.
 * For origin = github.com/o/r and HEAD on feat tracking origin/feat:
-*   origin/main...HEAD → branches:["o/r:main","o/r:feat",true]
-*   origin/main..HEAD  → branches:["o/r:main","o/r:feat",false]
+*   origin/main...HEAD → range:o/r:main...o/r:feat
+*   origin/main..HEAD  → range:o/r:main..o/r:feat
 * The matching explicit PR uses the first key too. If feat tracks a fork,
 * its identity becomes e.g. "contributor/r:feat", keeping forks distinct.
 *
 * Without a GitHub upstream, branches use full refs:
-*   main...feat → branches:["refs/heads/main","refs/heads/feat",true]
+*   main...feat → range:refs/heads/main...refs/heads/feat
 * Non-branch endpoints use their resolved hash or literal "worktree":
-*   main..worktree → branches:["refs/heads/main","worktree",false]
-* If neither endpoint is a branch, the key is revspec:<oldSha>..<newSha>.
+*   main..worktree → range:refs/heads/main..worktree
+*   <C>..<E>       → range:<C hash>..<E hash>
 * Hash placeholders denote full resolved hashes, with oldSha already adjusted
-* for mergeBase. The working command bypasses this helper and uses "working".
+* for the merge base. The working command bypasses this helper and uses
+* "working"; a single commit uses "commit:<hash>".
 */
 async function commentKey(repo, comparison, oldSha, newSha) {
 	const remotes = await repo.remotes();
@@ -18278,14 +18542,10 @@ async function commentKey(repo, comparison, oldSha, newSha) {
 		return repo.branchRef(rev);
 	};
 	const [old, next] = await Promise.all([identity(comparison.old), identity(comparison.new)]);
-	return old || next ? branchKey(old ?? oldSha, next ?? newSha, comparison.mergeBase) : `revspec:${oldSha}..${newSha}`;
+	return rangeKey(old ?? oldSha, next ?? newSha, comparison.base === "merge-base");
 }
-function branchKey(old, next, mergeBase) {
-	return `branches:${JSON.stringify([
-		old,
-		next,
-		mergeBase
-	])}`;
+function rangeKey(old, next, mergeBase) {
+	return `range:${old}${mergeBase ? "..." : ".."}${next}`;
 }
 /**
 * A GitHub pull request, as GitHub shows it: merge-base(base tip, head) vs head.
@@ -18304,16 +18564,16 @@ async function resolvePr(req, repo, github) {
 	await resolveComparison(repo, {
 		old: base,
 		new: head,
-		mergeBase: true
+		base: "merge-base"
 	});
 	return {
 		prUrl: pr.url,
 		mode: {
 			old: base,
 			new: head,
-			mergeBase: true,
+			base: "merge-base",
 			live: "none",
-			commentKey: branchKey(`${pr.repository.toLowerCase()}:${pr.baseRefName}`, `${pr.headRepository?.toLowerCase() ?? `deleted:${pr.url}`}:${pr.headRefName}`, true)
+			commentKey: rangeKey(`${pr.repository.toLowerCase()}:${pr.baseRefName}`, `${pr.headRepository?.toLowerCase() ?? `deleted:${pr.url}`}:${pr.headRefName}`, true)
 		}
 	};
 }
@@ -18462,7 +18722,12 @@ var Snapshotter = class {
 	}
 	async compute(version) {
 		const [{ oldSha, newSha }, headSha] = await Promise.all([resolveComparison(this.repo, this.mode), this.repo.resolve("HEAD").catch(() => "")]);
-		const [tracked, changed] = await Promise.all([newSha === "worktree" ? Promise.all([this.repo.lsFiles(), this.repo.untracked()]).then((lists) => lists.flat().filter((p) => !p.endsWith("/"))) : this.repo.lsTree(newSha), this.repo.numstat(oldSha, newSha)]);
+		const [tracked, changed, commit, commits] = await Promise.all([
+			newSha === "worktree" ? Promise.all([this.repo.lsFiles(), this.repo.untracked()]).then((lists) => lists.flat().filter((p) => !p.endsWith("/"))) : this.repo.lsTree(newSha),
+			this.repo.numstat(oldSha, newSha),
+			this.mode.base === "parent" ? this.reviewedCommit(newSha) : null,
+			this.rangeCommits(oldSha, newSha, headSha)
+		]);
 		await this.fillGenerated(changed, newSha);
 		const tree = new Set(tracked);
 		for (const f of changed) {
@@ -18479,11 +18744,36 @@ var Snapshotter = class {
 			headSha,
 			context: this.context,
 			changed,
-			tree: [...tree].sort()
+			tree: [...tree].sort(),
+			commit,
+			commits
 		};
 		for (const f of changed.slice(0, PREWARM)) this.patchFor(snap, f).catch(() => {});
 		return snap;
 	}
+	async reviewedCommit(sha) {
+		const [info, neighbours] = await Promise.all([this.repo.commitInfo(sha), this.repo.commitNeighbours(sha)]);
+		return info && {
+			...info,
+			...neighbours
+		};
+	}
+	async rangeCommits(oldSha, newSha, headSha) {
+		if (this.mode.within) {
+			const range = await resolveComparison(this.repo, this.mode.within);
+			return this.spanned(range.oldSha, range.newSha, headSha);
+		}
+		if (this.mode.base === "parent") return this.repo.rangeCommits(`${newSha}^!`, 250);
+		return this.spanned(oldSha, newSha, headSha);
+	}
+	spanned(oldSha, newSha, headSha) {
+		const [from, to] = [oldSha, newSha].map((sha) => sha === "worktree" ? headSha : sha);
+		if (!from || !to || from === to) return Promise.resolve({
+			list: [],
+			total: 0
+		});
+		return this.repo.rangeCommits(`${from}..${to}`, 250);
+	}
 	/**
 	* Sets `generated` on each non-binary changed file. A `linguist-generated`
 	* gitattribute on the new side decides outright, as on GitHub; otherwise a
@@ -18634,10 +18924,17 @@ var Session = class {
 			console.error("[diffle] snapshot listener failed:", e);
 		}
 	}
-	/** First mode. Rejects `ready()` on failure so early requests error out. */
-	async start(req) {
+	/**
+	* Resolves a request into a review without activating it, so a caller can reject
+	* invalid input before serving. Queued, so `close()` waits for a PR fetch.
+	*/
+	resolve(req) {
+		return this.run(() => resolveReview(req, this.repo, this.opts.github));
+	}
+	/** First mode, from `resolve`. Rejects `ready()` on failure so early requests error out. */
+	async start(review) {
 		try {
-			const snap = await this.enter(req);
+			const snap = await this.run(() => this.activate(review));
 			this.resolveReady();
 			return snap;
 		} catch (e) {
@@ -18647,7 +18944,7 @@ var Session = class {
 	}
 	/** Switch modes at runtime. Broadcasts a snapshot bump on success. */
 	async switchMode(req) {
-		const snap = await this.enter(req);
+		const snap = await this.run(async () => this.activate(req.kind === "focus" ? await this.focus(req.commit) : await resolveReview(req, this.repo, this.opts.github)));
 		this.hub.broadcast({
 			type: "snapshot",
 			version: snap.version
@@ -18655,6 +18952,33 @@ var Session = class {
 		return snap;
 	}
 	/**
+	* Focuses `commit`, by hash or short hash, of the active range's listed commits, or with null returns to
+	* the range. A focused commit keeps its own comments, as when entered alone, and the range's PR identity.
+	*/
+	async focus(commit) {
+		const a = this.require();
+		const { within, ...self } = a.mode;
+		if (!within && self.base === "parent") throw new RevspecError("a single commit has no commits to focus");
+		const range = within ?? self;
+		if (commit === null) return {
+			mode: range,
+			prUrl: a.prUrl
+		};
+		const sha = (await a.snapshotter.current()).commits.list.find((c) => c.sha === commit || c.short === commit)?.sha;
+		if (!sha) throw new RevspecError(`not a listed commit of ${comparisonLabel(range)}: ${commit}`);
+		return {
+			prUrl: a.prUrl,
+			mode: {
+				old: sha,
+				new: sha,
+				base: "parent",
+				live: range.live === "none" ? "none" : "refs",
+				commentKey: `commit:${sha}`,
+				within: range
+			}
+		};
+	}
+	/**
 	* Runs `fn` after every earlier mutation settled. The only way to touch
 	* `active`, `version` or `opts.context`.
 	*/
@@ -18663,11 +18987,7 @@ var Session = class {
 		this.queue = r.catch(() => {});
 		return r;
 	}
-	enter(req) {
-		return this.run(() => this.transition(req));
-	}
-	async transition(req) {
-		const { mode, prUrl } = await resolveReview(req, this.repo, this.opts.github);
+	async activate({ mode, prUrl }) {
 		const snapshotter = new Snapshotter(this.repo, mode, ++this.version, this.opts.context);
 		const [comments, snap] = await Promise.all([CommentStore.open(this.repo.gitDir, mode.commentKey), snapshotter.current()]);
 		const next = {
@@ -18760,6 +19080,18 @@ var Session = class {
 		if (side === "new") return snap.newSha === "worktree" ? this.repo.readWorktree(target) : this.repo.show(snap.newSha, target);
 		return snap.oldSha === "worktree" ? this.repo.readWorktree(target) : this.repo.show(snap.oldSha, target);
 	}
+	/**
+	* The bytes `key` names on one side of `path`, or null unless `key` is that side's `imageKey` in `snap`.
+	* A worktree file that changed since `snap` reads as null too, so a key never serves other bytes.
+	*/
+	async readImage(snap, path, side, key) {
+		if (key !== imageKey(snap, path, side)) return null;
+		if (!snap.changed.some((f) => f.path === path)) return this.readSide(snap, path, key === snap.newSha ? "new" : "old");
+		const buf = await this.readSide(snap, path, side);
+		if (buf == null || (side === "new" ? snap.newSha : snap.oldSha) !== "worktree") return buf;
+		const target = sidePath(this.readablePaths(snap), path, side);
+		return target != null && await this.repo.hashObject(buf, target) === key ? buf : null;
+	}
 	/** Whether `readSide` would find `path` on `side`: the allowlist alone, no read. */
 	hasSide(snap, path, side) {
 		return sidePath(this.readablePaths(snap), path, side) != null;
@@ -22763,6 +23095,7 @@ Shorthands (in place of <revs>):
   working                  same as HEAD..worktree: uncommitted changes, staged and untracked included
   pr [number|url]          a GitHub pull request: its base...head, fetched if needed
                            (without an argument: the pull request for this branch)
+  show [rev]               same as <rev>^!: one commit against its first parent, pinned (default: HEAD)
 
 Revisions follow git diff, except that a lone one compares from the merge base:
   diffle main              same as main...HEAD: what this branch added since it left main
@@ -22770,6 +23103,7 @@ Revisions follow git diff, except that a lone one compares from the merge base:
   diffle main..feat        main vs feat
   diffle main...feat       what feat added since it left main
   diffle main..worktree    main vs the uncommitted tree ("worktree" works on either side)
+  diffle a1b2c3d^!         the commit a1b2c3d alone, like git show
 
 Without revisions, diffle compares HEAD..worktree.
 
@@ -22782,6 +23116,10 @@ Ctrl+C always stops it.`).action(async (revs, _o, cmd) => {
 	}, cmd.optsWithGlobals());
 });
 program.command("working", { hidden: true }).summary("same as HEAD..worktree").description("Same as `diffle HEAD..worktree`: uncommitted changes, staged and untracked files included.").action(async (_o, cmd) => run({ kind: "working" }, cmd.optsWithGlobals()));
+program.command("show", { hidden: true }).argument("[rev]", "the commit to review", "HEAD").summary("one commit").description("Same as `diffle <rev>^!`: one commit against its first parent, as git show shows it.").action(async (rev, _o, cmd) => run({
+	kind: "revspec",
+	args: [`${rev}^!`]
+}, cmd.optsWithGlobals()));
 program.command("pr", { hidden: true }).argument("[pr]", "pull request number or url; default: the pull request for this branch").summary("a GitHub pull request").description("A GitHub pull request, as GitHub shows it: merge-base(base, head) vs head.").action(async (pr, _o, cmd) => run({
 	kind: "pr",
 	pr
@@ -22917,6 +23255,9 @@ async function serve(req, opts, repo, closeRepo, config, github, timing) {
 	process.on("SIGTERM", shutdown);
 	stopBrowserWatch = watchBrowserLifetime(hub, opts.open && !opts.keepAlive, shutdown);
 	try {
+		const review = await session.resolve(req);
+		timing.mark("resolve");
+		if (closing) return;
 		const url = await server.listen();
 		timing.mark("listen");
 		if (opts.open) {
@@ -22928,7 +23269,7 @@ async function serve(req, opts, repo, closeRepo, config, github, timing) {
 		console.error(`📂 ${c.dim("repo")} ${repo.root}`);
 		if (github.client) console.error(`🐙 ${c.dim("github")} ${c.dim(`token from ${github.source}`)}`);
 		else console.error(`🐙 ${c.dim("github")} ${c.dim("off: no token in GITHUB_TOKEN, GH_TOKEN or gh auth token")}`);
-		const snap = await session.start(req);
+		const snap = await session.start(review);
 		timing.mark("snapshot");
 		const n = snap.changed.length;
 		const adds = snap.changed.reduce((a, f) => a + f.additions, 0);