papilot 0.4.0 → 0.5.0

package/dist/index.html

@@ -8,6 +8,6 @@
   document.documentElement.dataset.theme = dark ? 'dark' : 'light';
   document.querySelector('meta[name="theme-color"]').content = dark ? '#26272b' : '#ffffff';
 })();
-</script><style>html{--lightningcss-light:initial;--lightningcss-dark: ;color-scheme:light;background:#fff}html[data-theme=dark]{--lightningcss-light: ;--lightningcss-dark:initial;color-scheme:dark;background:#26272b}</style>  <script type="module" crossorigin src="/assets/index-DTScOfwx.js"></script>
-  <link rel="stylesheet" crossorigin href="/assets/index-BB0zC0wj.css">
+</script><style>html{--lightningcss-light:initial;--lightningcss-dark: ;color-scheme:light;background:#fff}html[data-theme=dark]{--lightningcss-light: ;--lightningcss-dark:initial;color-scheme:dark;background:#26272b}</style>  <script type="module" crossorigin src="/assets/index-BqX4tIMz.js"></script>
+  <link rel="stylesheet" crossorigin href="/assets/index-C0hHDQdZ.css">
 </head><body><div id="root"></div></body></html>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "papilot",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "A Cursor-like workspace for your papers: annotate and review PDFs directly without ever touching LaTeX.",
   "keywords": [
     "latex",

package/src/server/app.ts

@@ -1,5 +1,7 @@
 import Fastify from 'fastify';
 import compress from '@fastify/compress';
+import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { registerFrontend } from './frontend.ts';
@@ -7,7 +9,8 @@ import type { Store } from './store.ts';
 import type { Workspace } from './workspace.ts';
 import { reviewClient, allowedReviewRoute, rewriteReviewHtml, rewriteReviewJson, confirmedReviewResponse, annotateReviewState } from './review.ts';
 import { fullPaperPdf } from './pdf.ts';
-import { type Manuscripts, annotationTask, gitAbortMerge, gitCommit, gitDiff, gitFinishMerge, gitIgnore, gitRemote, gitStatus } from './manuscript.ts';
+import { type ChangeAction, Changes } from './changes.ts';
+import { type Manuscripts, annotationTask, gitAbortMerge, gitCommit, gitDiff, gitFinishMerge, gitIgnore, gitRemote, gitStage, gitStatus } from './manuscript.ts';
 import { findSkill, listedSkill, loadSkills } from './skills.ts';
 import { type Accounts, deviceLabel } from './accounts.ts';
 import { type Listener, Limiter, SESSION_COOKIE, author, clientAddress, cookie, equals, guard, viewerInfo, visibleSnapshot } from './access.ts';
@@ -25,7 +28,7 @@ export function gitQueue() {
 }
 
 export interface AppOptions {
-  listener: Listener; store: Store; workspace: Workspace; manuscripts: Manuscripts; accounts: Accounts;
+  listener: Listener; store: Store; workspace: Workspace; manuscripts: Manuscripts; accounts: Accounts; changes?: Changes;
   csrf: string; serialGit: ReturnType<typeof gitQueue>; dist: string | null; version: string;
   connectReview?: typeof reviewClient;
 }
@@ -34,6 +37,7 @@ export interface AppOptions {
 // the account one for the public URL. Both serve the same workspace.
 export async function buildApp(options: AppOptions) {
   const { listener, store, workspace, manuscripts, accounts, serialGit } = options, connectReview = options.connectReview || reviewClient;
+  const changes = options.changes || new Changes(fs.mkdtempSync(path.join(os.tmpdir(), 'papilot-changes-')));
   // A public request must arrive in full within a minute; held-open bodies tie up nothing.
   const app = Fastify({ logger: false, bodyLimit: 1024 * 1024, ...(listener.kind === 'account' ? { requestTimeout: 60000 } : {}) });
   const { csrfFor } = guard(app, { listener, accounts, store, csrf: options.csrf, request: id => workspace.requests.get(id) });
@@ -126,17 +130,28 @@ export async function buildApp(options: AppOptions) {
   app.get<{ Params: { id: string } }>('/api/projects/:id/manuscript', project(), async request => ({ ...(await manuscripts.state(request.params.id, store.project(request.params.id).path)), annotations: store.annotations(request.params.id).filter(note => !note.taskId) }));
   app.get<{ Params: { id: string } }>('/api/projects/:id/git', project(), request => gitStatus(store.project(request.params.id).path));
   app.get<{ Params: { id: string }; Querystring: { path?: string } }>('/api/projects/:id/git/diff', project(), request => gitDiff(store.project(request.params.id).path, string(request.query.path, 'File path', 4096)));
+  const paths = (value: unknown): string[] => Array.isArray(value) ? value.filter((p: unknown): p is string => typeof p === 'string').slice(0, 5000) : [];
   app.post<{ Params: { id: string } }>('/api/projects/:id/git/commit', project(), request => {
     const project = store.project(request.params.id), b = request.body as any;
-    const message = string(b.message, 'Commit message', 5000), paths = Array.isArray(b.paths) ? b.paths.filter((p: unknown) => typeof p === 'string').slice(0, 5000) : [];
-    return serialGit(project.id, () => workspace.exclusiveCommit(project.id, async () => ({ commit: await gitCommit(project.path, message, paths), git: await gitStatus(project.path) })));
+    const message = string(b.message, 'Commit message', 5000), chosen = b.staged === true ? null : paths(b.paths);
+    let pushError: string | undefined;
+    return serialGit(project.id, () => workspace.exclusiveCommit(project.id, async () => {
+      const commit = await gitCommit(project.path, message, chosen);
+      // The commit stands even when the push fails; the author can push again.
+      if (b.push === true) try { await gitRemote(project.path, 'push'); } catch (error) { pushError = (error as Error).message; }
+      return { commit, git: await gitStatus(project.path), ...(pushError ? { pushError } : {}) };
+    }));
+  });
+  // The Git panel's checkboxes stage or unstage whole files.
+  app.post<{ Params: { id: string } }>('/api/projects/:id/git/stage', project(), request => {
+    const project = store.project(request.params.id), b = request.body as any;
+    return serialGit(project.id, async () => ({ git: await gitStage(project.path, paths(b.paths), b.stage !== false) }));
   });
-  const paths = (value: unknown): string[] => Array.isArray(value) ? value.filter((p: unknown): p is string => typeof p === 'string').slice(0, 5000) : [];
   // An agent writes a commit message for the chosen files, or a fresh one
   // instead of the message it already wrote for them; nothing is written.
   app.post<{ Params: { id: string } }>('/api/projects/:id/git/message', project(), request => {
     const b = request.body as any;
-    return workspace.commitMessage(store.project(request.params.id).id, paths(b.paths), { agent: b.agent === undefined ? undefined : agent(b.agent), fresh: b.fresh === true });
+    return workspace.commitMessage(store.project(request.params.id).id, paths(b.paths), { agent: b.agent === undefined ? undefined : agent(b.agent), fresh: b.fresh === true, staged: b.staged === true });
   });
   // A merge in progress is resolved by an agent, committed, or abandoned.
   app.post<{ Params: { id: string } }>('/api/projects/:id/git/resolve', project(), request => {
@@ -239,6 +254,38 @@ export async function buildApp(options: AppOptions) {
     });
   }
 
+  // The review viewer also shows a paper's uncommitted changes against its
+  // last commit. Papilot answers those routes itself, ahead of the engine's
+  // below, and the viewer posts with Papilot's token. Staging writes the
+  // index; reverting writes files, so it waits for review actions and commits.
+  const changesAccess = { config: { access: { project: 'projectId' }, csrf: false as const } };
+  const changesToken = (request: { headers: Record<string, unknown>; viewer?: Parameters<typeof csrfFor>[0] }) => {
+    if (!equals(String(request.headers['x-review-token'] || ''), csrfFor(request.viewer!))) throw Object.assign(new Error('This page has expired. Refresh it and try again.'), { statusCode: 403 });
+  };
+  const CHANGE_ACTIONS: Record<string, ChangeAction> = { accept: 'stage', unstage: 'unstage', reject: 'revert' };
+  app.get<{ Params: { projectId: string }; Querystring: { round?: string } }>('/review/:projectId/api/changes/state', changesAccess, request => {
+    const project = store.project(request.params.projectId), round = Number(request.query.round);
+    return changes.state(project.id, project.path, csrfFor(request.viewer!), Number.isSafeInteger(round) && round > 0 ? round : undefined);
+  });
+  app.get<{ Params: { projectId: string; number: string } }>('/review/:projectId/api/changes/rounds/:number', changesAccess, request => changes.detail(store.project(request.params.projectId).id, Number(request.params.number)));
+  app.get<{ Params: { projectId: string; number: string; file: string } }>('/review/:projectId/changes/files/:number/:file', changesAccess, (request, reply) => {
+    const file = changes.file(store.project(request.params.projectId).id, Number(request.params.number), request.params.file);
+    return reply.header('Cache-Control', 'private, max-age=31536000, immutable').type(file.endsWith('.svg') ? 'image/svg+xml' : 'image/png').send(fs.createReadStream(file));
+  });
+  app.post<{ Params: { projectId: string } }>('/review/:projectId/api/changes/decide', changesAccess, request => {
+    changesToken(request);
+    const project = store.project(request.params.projectId), b = request.body as any, action = CHANGE_ACTIONS[String(b?.action)];
+    if (!action) throw new Error('Choose stage, unstage or revert.');
+    const ids = Array.isArray(b.changes) ? b.changes.filter((id: unknown): id is string => typeof id === 'string').slice(0, 2000) : [];
+    const act = () => changes.act(project.id, project.path, csrfFor(request.viewer!), action, Number(b.round), ids);
+    return serialGit(project.id, () => action === 'revert' ? workspace.exclusiveCommit(project.id, act) : act());
+  });
+  app.post<{ Params: { projectId: string } }>('/review/:projectId/api/changes/undo', changesAccess, request => {
+    changesToken(request);
+    const project = store.project(request.params.projectId), id = string((request.body as any)?.id, 'Revert ID', 80);
+    return serialGit(project.id, () => workspace.exclusiveCommit(project.id, () => changes.undo(project.id, project.path, csrfFor(request.viewer!), id)));
+  });
+
   app.route<{ Params: { projectId: string; '*': string } }>({
     // The review page posts with the review engine's token rather than Papilot's.
     method: ['GET', 'POST'], url: '/review/:projectId/*', config: { access: { project: 'projectId' }, csrf: false }, handler: async (request, reply) => {

package/src/server/changes.ts

@@ -0,0 +1,295 @@
+import { createHash, randomUUID } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { DATA, ENGINE } from './paths.ts';
+import { mergeInProgress, workingTree } from './manuscript.ts';
+import { ignorePattern } from '../commit.ts';
+
+// The manuscript's uncommitted changes as a PDF comparison: the last commit
+// against the working tree, rendered by the review engine like a task's round
+// and shown in its viewer. Each change can be staged or unstaged in the real
+// index, or reverted on disk; a revert can be undone. A commit then takes what
+// is staged, so one set of edits can become several commits.
+
+type Op = ['equal' | 'replace' | 'insert' | 'delete', number, number, number, number];
+export interface Unit { id: string; file: string; status: 'added' | 'deleted' | 'modified'; kind: string; whole_file: boolean; ops: Op[]; old_start: number; old_end: number; new_start: number; new_end: number; old_text: string; new_text: string; truncated: boolean }
+type Decision = 'pending' | 'accepted' | 'rejected' | 'commented';
+export type ChangeAction = 'stage' | 'unstage' | 'revert';
+interface Round { number: number; before: string; after: string; units: Unit[]; folder: string; warnings: string[]; decisions: Record<string, Decision> }
+interface Job { key: string; phase: 'build' | 'render'; status: 'running' | 'failed'; created: number; error?: string; details?: string[]; log?: string }
+interface Snapshot { before: string | null; after: string }
+interface Entry { mode: string; sha: string }
+interface Revert { id: string; files: { path: string; disk: Buffer | null; written: Buffer | null; index: Entry | null; indexAfter: Entry | null }[]; signatures: string[] }
+interface Comparison { rounds: Round[]; job: Job | null; next: number; undo: Revert | null; reverted: Set<string>; snapshot?: { at: number; value: Promise<Snapshot> }; current?: { key: string; units: Unit[] } }
+
+const conflict = (message: string) => Object.assign(new Error(message), { statusCode: 409 });
+
+async function engine() {
+  const load = (file: string) => import(pathToFileURL(path.join(ENGINE, file)).href);
+  const [{ Builder, BuildError }, { Repo }, { loadProject, isFigure }, { diffUnits, revertUnits, splitLines, textOf }, { opcodes }, { render }] = await Promise.all(
+    ['src/core/build.ts', 'src/core/git.ts', 'src/core/config.ts', 'src/core/changes.ts', 'src/core/diff.ts', 'src/core/publish.ts'].map(load));
+  return { Builder, BuildError, Repo, loadProject, isFigure, diffUnits, revertUnits, splitLines, textOf, opcodes, render } as {
+    Builder: any; BuildError: any; Repo: any; loadProject: (root: string) => any; isFigure: (project: any, file: string) => boolean;
+    diffUnits: (repo: any, before: string, after: string, isFigure: (file: string) => boolean) => Unit[];
+    revertUnits: (old: Buffer | null, next: Buffer | null, units: Unit[]) => Buffer | null;
+    splitLines: (text: string) => string[]; textOf: (data: Buffer | null) => string | null;
+    opcodes: (a: string[], b: string[]) => Op[]; render: (output: string, request: unknown) => Promise<void>;
+  };
+}
+
+// A change is the same change in a later comparison when it replaces the same
+// committed lines with the same text; reverting another change leaves both.
+export const signature = (unit: Unit) => createHash('sha256').update(JSON.stringify([unit.file, unit.status, unit.old_start, unit.old_end, unit.old_text, unit.new_text])).digest('hex').slice(0, 24);
+
+// Where a change sits in the committed file and in the working file, as line ranges.
+const headRange = (unit: Unit): [number, number] => [unit.ops[0][1], unit.ops[unit.ops.length - 1][2]];
+const workRange = (unit: Unit): [number, number] => [unit.ops[0][3], unit.ops[unit.ops.length - 1][4]];
+// Two line ranges meet when they overlap, or when one is empty and sits inside or at the edge of the other.
+const meets = ([a, b]: [number, number], [c, d]: [number, number]) => a === b || c === d ? a <= d && c <= b : a < d && c < b;
+
+// The index's lines with one change's working-tree lines staged: every
+// difference between the index and the working file inside the change.
+export function stageLines(index: string[], work: string[], range: [number, number], opcodes: (a: string[], b: string[]) => Op[]) {
+  const result = [...index];
+  for (const [tag, i, j, x, y] of opcodes(index, work).reverse()) if (tag !== 'equal' && meets([x, y], range)) result.splice(i, j - i, ...work.slice(x, y));
+  return result;
+}
+// The index's lines with one change unstaged: the committed lines back in its place.
+export function unstageLines(head: string[], index: string[], range: [number, number], opcodes: (a: string[], b: string[]) => Op[]) {
+  const result = [...index];
+  for (const [tag, i, j, x, y] of opcodes(head, index).reverse()) if (tag !== 'equal' && meets([i, j], range)) result.splice(x, y - x, ...head.slice(i, j));
+  return result;
+}
+// A change is staged when the index already has the working tree's text there.
+export const stagedLines = (index: string[], work: string[], range: [number, number], opcodes: (a: string[], b: string[]) => Op[]) =>
+  !opcodes(index, work).some(([tag, , , x, y]) => tag !== 'equal' && meets([x, y], range));
+
+// A path's index entry, if it has one.
+function indexEntry(repo: any, file: string): Entry | null {
+  const [mode, sha] = repo.text(['ls-files', '-s', '-z', '--', file]).split(/\s+/);
+  return sha ? { mode, sha } : null;
+}
+const same = (a: Buffer | null, b: Buffer | null) => a === null || b === null ? a === b : a.equals(b);
+const readBytes = (file: string) => { try { return fs.readFileSync(file); } catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null; throw error; } };
+
+export class Changes {
+  private comparisons = new Map<string, Comparison>();
+  constructor(private dir = path.join(DATA, 'changes')) { fs.rmSync(dir, { recursive: true, force: true }); }
+
+  private comparison(projectId: string) {
+    let comparison = this.comparisons.get(projectId);
+    if (!comparison) this.comparisons.set(projectId, comparison = { rounds: [], job: null, next: 1, undo: null, reverted: new Set() });
+    return comparison;
+  }
+
+  // The last commit's tree and the working tree, read at most once a second.
+  private snapshot(projectId: string, root: string, fresh = false): Promise<Snapshot> {
+    const comparison = this.comparison(projectId);
+    if (!fresh && comparison.snapshot && Date.now() - comparison.snapshot.at < 1000) return comparison.snapshot.value;
+    const value = (async () => {
+      const { Repo } = await engine(), repo = new Repo(root);
+      return { before: repo.hasHead() ? repo.treeId('HEAD') : null, after: await workingTree(root) };
+    })();
+    comparison.snapshot = { at: Date.now(), value };
+    value.catch(() => { if (comparison.snapshot?.value === value) comparison.snapshot = undefined; });
+    return value;
+  }
+
+  // The changes between the two trees, leaving out untracked build output,
+  // which the Git panel offers to ignore.
+  private async units(projectId: string, root: string, snapshot: Snapshot) {
+    const comparison = this.comparison(projectId), key = `${snapshot.before}:${snapshot.after}`;
+    if (comparison.current?.key === key) return comparison.current.units;
+    const { Repo, loadProject, isFigure, diffUnits } = await engine(), project = loadProject(root);
+    const units = diffUnits(new Repo(root), snapshot.before!, snapshot.after, file => isFigure(project, file)).filter(unit => !(unit.status === 'added' && ignorePattern(unit.file)));
+    comparison.current = { key, units };
+    return units;
+  }
+
+  // Which of the current changes are staged, read from the index.
+  private async staged(root: string, snapshot: Snapshot, units: Unit[]) {
+    const { Repo, splitLines, textOf, opcodes } = await engine(), repo = new Repo(root);
+    const files = [...new Set(units.map(unit => unit.file))];
+    const work = repo.blobs(snapshot.after, files), index = repo.blobs('', files);
+    const staged = new Set<string>();
+    for (const unit of units) {
+      const ready = unit.whole_file ? same(index[unit.file], work[unit.file])
+        : index[unit.file] !== null && stagedLines(splitLines(textOf(index[unit.file]) ?? ''), splitLines(textOf(work[unit.file]) ?? ''), workRange(unit), opcodes);
+      if (ready) staged.add(unit.id);
+    }
+    return staged;
+  }
+
+  // Compile both trees once the working tree or the last commit changes, and
+  // render their comparison. The previous comparison stays readable meanwhile.
+  private schedule(projectId: string, root: string, snapshot: Snapshot) {
+    const comparison = this.comparison(projectId), latest = comparison.rounds.at(-1), key = `${snapshot.before}:${snapshot.after}`;
+    if (!snapshot.before || (latest && `${latest.before}:${latest.after}` === key) || comparison.job?.status === 'running' || comparison.job?.key === key) return;
+    const job: Job = { key, phase: 'build', status: 'running', created: Date.now() };
+    comparison.job = job;
+    void (async () => {
+      const { Builder, BuildError, Repo, loadProject, render } = await engine();
+      const project = loadProject(root), repo = new Repo(root), number = comparison.next++;
+      const units = await this.units(projectId, root, snapshot), folder = path.join(this.dir, projectId, String(number));
+      let warnings: string[] = [];
+      fs.rmSync(folder, { recursive: true, force: true }); fs.mkdirSync(folder, { recursive: true });
+      if (units.length) {
+        const builder = new Builder(project, repo);
+        const build = async (tree: string, what: string) => {
+          try { return await builder.build(tree, ['full']); }
+          catch (error) { throw error instanceof BuildError ? Object.assign(new Error(what), { details: (error as any).details, log: (error as any).log }) : error; }
+        };
+        const old = await build(snapshot.before!, 'The last commit could not be compiled.'), next = await build(snapshot.after, 'The working tree could not be compiled.');
+        job.phase = 'render';
+        await render(folder, { main: project.main, source_dir: project.source_dir, figures: project.figures, old, new: next, units });
+        warnings = next.warnings.filter((warning: string) => !old.warnings.includes(warning));
+      } else fs.writeFileSync(path.join(folder, 'round.json'), JSON.stringify({ units: {}, sections: [], loose: [] }));
+      comparison.rounds.push({ number, before: snapshot.before!, after: snapshot.after, units, folder, warnings, decisions: {} });
+      // The viewer may still show the round before; older ones go.
+      for (const old of comparison.rounds.splice(0, Math.max(0, comparison.rounds.length - 3))) fs.rmSync(old.folder, { recursive: true, force: true });
+      if (comparison.job === job) comparison.job = null;
+    })().catch(error => {
+      const detail = error as { message?: string; details?: string[]; log?: string };
+      Object.assign(job, { status: 'failed', error: detail.message || 'The comparison could not be built.', details: detail.details || [], ...(detail.log ? { log: detail.log } : {}) });
+    });
+  }
+
+  // What the viewer polls, in the review engine's page state shape: the
+  // latest comparison, and for the round it shows, which changes are staged
+  // (accepted), unstaged (pending), reverted (rejected) or edited since.
+  async state(projectId: string, root: string, csrf: string, number?: number) {
+    const comparison = this.comparison(projectId), snapshot = await this.snapshot(projectId, root);
+    this.schedule(projectId, root, snapshot);
+    const latest = comparison.rounds.at(-1) ?? null, round = comparison.rounds.find(item => item.number === number) ?? latest;
+    let decisionLock: string | null = mergeInProgress(root) ? 'Finish or abort the merge in the Git panel before staging or reverting changes.' : null;
+    if (round && snapshot.before && round.before === snapshot.before) {
+      const units = await this.units(projectId, root, snapshot), staged = await this.staged(root, snapshot, units);
+      const current = new Map(units.map(unit => [signature(unit), unit]));
+      round.decisions = Object.fromEntries(round.units.map(unit => {
+        const key = signature(unit), found = current.get(key);
+        return [unit.id, found ? (staged.has(found.id) ? 'accepted' : 'pending') : comparison.reverted.has(key) ? 'rejected' : 'commented'];
+      }));
+    } else if (round) decisionLock ??= 'The last commit changed. The comparison is being updated.';
+    const job = comparison.job, decisions = round?.decisions ?? {}, values = Object.values(decisions);
+    const building = job?.status === 'running' && (!latest || job.key !== `${latest.before}:${latest.after}`);
+    const undo = comparison.undo && round ? round.units.filter(unit => comparison.undo!.signatures.includes(signature(unit))).map(unit => unit.id) : [];
+    return {
+      csrf, task: 'changes', title: 'Uncommitted changes', closed: false, decisionLock, commentLock: null,
+      state: !snapshot.before ? 'build_failed' : building || (!latest && job?.status !== 'failed') ? 'building' : job?.status === 'failed' ? 'build_failed' : values.includes('pending') ? 'reviewing' : 'done',
+      latest: latest?.number ?? null, round: round?.number ?? null, revision: round?.after ?? null,
+      decisions, comments: {},
+      undo: comparison.undo ? { id: comparison.undo.id, kind: 'reject', changes: undo } : null,
+      job: !snapshot.before ? { id: 'changes', status: 'failed', phase: 'build', created: 0, ahead: 0, error: 'This repository has no commits yet. Commit once to compare later changes in the PDF.' }
+        : job ? { id: job.key, status: job.status === 'running' ? 'running' : 'failed', phase: job.phase, created: job.created, ahead: 0, ...(job.error ? { error: job.error, details: job.details, log: job.log } : {}) } : null,
+    };
+  }
+
+  detail(projectId: string, number: number) {
+    const round = this.comparison(projectId).rounds.find(item => item.number === number);
+    if (!round) throw Object.assign(new Error('This comparison is out of date. Refresh the page.'), { statusCode: 404 });
+    let render: { units: Record<string, object>; sections: unknown[]; loose: unknown[] } = { units: {}, sections: [], loose: [] };
+    try { render = JSON.parse(fs.readFileSync(path.join(round.folder, 'round.json'), 'utf8')); } catch { /* An empty comparison has no render. */ }
+    return {
+      task: 'changes', round: round.number, before: round.before, after: round.after,
+      units: round.units.map(unit => ({ ...unit, ...render.units[unit.id] })), sections: render.sections, loose: render.loose,
+      warnings: round.warnings, files: `/review/${projectId}/changes/files/${round.number}/`,
+    };
+  }
+
+  file(projectId: string, number: number, name: string) {
+    const round = this.comparison(projectId).rounds.find(item => item.number === number);
+    const file = round && /^[\w.-]+\.(svg|png)$/.test(name) ? path.join(round.folder, name) : '';
+    if (!file || !fs.existsSync(file)) throw Object.assign(new Error('No such file.'), { statusCode: 404 });
+    return file;
+  }
+
+  // The chosen changes of a round the viewer shows, found again among the
+  // changes on disk now. Each must still be there exactly as shown.
+  private async chosen(projectId: string, root: string, number: number, ids: string[]) {
+    const comparison = this.comparison(projectId), round = comparison.rounds.find(item => item.number === number);
+    if (!round) throw conflict('This comparison is out of date. Wait for it to update.');
+    const snapshot = await this.snapshot(projectId, root, true);
+    if (round.before !== snapshot.before) throw conflict('The last commit changed. Wait for the comparison to update.');
+    if (mergeInProgress(root)) throw conflict('Finish or abort the merge in the Git panel before staging or reverting changes.');
+    const current = new Map((await this.units(projectId, root, snapshot)).map(unit => [signature(unit), unit]));
+    const units = ids.map(id => {
+      const shown = round.units.find(unit => unit.id === id);
+      const found = shown && current.get(signature(shown));
+      if (!found) throw conflict(shown ? `${shown.file} changed since this comparison. Wait for it to update.` : 'Select a change from this comparison.');
+      return found;
+    });
+    if (!units.length) throw new Error('Select at least one change.');
+    return { comparison, snapshot, units };
+  }
+
+  // Stage or unstage writes the index only; revert writes the files too, and
+  // keeps what it replaced for undo.
+  async act(projectId: string, root: string, csrf: string, action: ChangeAction, number: number, ids: string[]) {
+    const { comparison, snapshot, units } = await this.chosen(projectId, root, number, ids);
+    const { Repo, splitLines, textOf, opcodes, revertUnits } = await engine(), repo = new Repo(root);
+    const files = [...new Set(units.map(unit => unit.file))];
+    const head = repo.blobs(snapshot.before, files), work = repo.blobs(snapshot.after, files), index = repo.blobs('', files);
+    const lines = (data: Buffer | null) => splitLines(textOf(data) ?? '');
+    const entry = (file: string) => indexEntry(repo, file);
+    const writeIndex = (file: string, text: string[]) => {
+      const mode = entry(file)?.mode || repo.mode(snapshot.before, file) || '100644';
+      repo.run(['update-index', '--add', '--cacheinfo', `${mode},${repo.hashObject(Buffer.from(text.join('')))},${file}`]);
+    };
+    const unstage = (file: string, part: Unit[]) => {
+      if (part.some(unit => unit.whole_file)) { repo.run(['reset', '-q', 'HEAD', '--', file]); return; }
+      if (index[file] === null) return;
+      let next = lines(index[file]);
+      for (const unit of part) next = unstageLines(lines(head[file]), next, headRange(unit), opcodes);
+      if (next.join('') !== lines(index[file]).join('')) writeIndex(file, next);
+    };
+    const revert: Revert = { id: randomUUID(), files: [], signatures: units.map(signature) };
+    for (const file of files) {
+      const part = units.filter(unit => unit.file === file), whole = part.some(unit => unit.whole_file);
+      if (action === 'stage') {
+        if (whole) repo.run(['add', '-A', '--', file]);
+        else {
+          let next = index[file] === null ? lines(head[file]) : lines(index[file]);
+          for (const unit of part) next = stageLines(next, lines(work[file]), workRange(unit), opcodes);
+          writeIndex(file, next);
+        }
+      } else if (action === 'unstage') unstage(file, part);
+      else {
+        const absolute = path.join(root, file), disk = readBytes(absolute), before = entry(file);
+        if (!same(disk, work[file])) throw conflict(`${file} changed on disk since this comparison. Wait for it to update.`);
+        const stat = fs.lstatSync(absolute, { throwIfNoEntry: false });
+        if (stat && !stat.isFile()) throw new Error(`${file} is not a regular file, so it cannot be reverted here.`);
+        if (head[file] === null) { repo.run(['rm', '--cached', '-q', '--ignore-unmatch', '--', file]); fs.rmSync(absolute, { force: true }); }
+        else if (whole) repo.run(['checkout', 'HEAD', '--', file]);
+        else { fs.writeFileSync(absolute, revertUnits(head[file], work[file], part)!); unstage(file, part); }
+        revert.files.push({ path: file, disk, written: readBytes(absolute), index: before, indexAfter: entry(file) });
+      }
+    }
+    if (action === 'revert') { comparison.undo = revert; revert.signatures.forEach(key => comparison.reverted.add(key)); }
+    comparison.snapshot = undefined;
+    return this.state(projectId, root, csrf, number);
+  }
+
+  // Undo puts back what the last revert replaced, unless a file changed since.
+  async undo(projectId: string, root: string, csrf: string, id: string) {
+    const comparison = this.comparison(projectId), revert = comparison.undo;
+    if (!revert || revert.id !== id) throw conflict('There is no revert to undo.');
+    const { Repo } = await engine(), repo = new Repo(root);
+    for (const file of revert.files) if (!same(readBytes(path.join(root, file.path)), file.written)) throw conflict(`${file.path} changed after the revert, so it was not restored.`);
+    for (const file of revert.files) {
+      const absolute = path.join(root, file.path);
+      if (file.disk === null) fs.rmSync(absolute, { force: true });
+      else { fs.mkdirSync(path.dirname(absolute), { recursive: true }); fs.writeFileSync(absolute, file.disk); }
+      const now = indexEntry(repo, file.path);
+      if (now?.sha === file.indexAfter?.sha && now?.mode === file.indexAfter?.mode) {
+        if (file.index) repo.run(['update-index', '--add', '--cacheinfo', `${file.index.mode},${file.index.sha},${file.path}`]);
+        else if (now) repo.run(['update-index', '--force-remove', '--', file.path]);
+      }
+    }
+    comparison.undo = null;
+    revert.signatures.forEach(key => comparison.reverted.delete(key));
+    comparison.snapshot = undefined;
+    const latest = comparison.rounds.at(-1);
+    return { ...(await this.state(projectId, root, csrf)), restored: latest ? latest.units.filter(unit => revert.signatures.includes(signature(unit))).map(unit => unit.id) : [] };
+  }
+}

package/src/server/main.ts

@@ -7,6 +7,7 @@ import { Accounts } from './accounts.ts';
 import { ROOT, DATA, PORT, PUBLIC_ORIGIN, OWNER, VERSION, ACCOUNT_ORIGIN, ACCOUNT_PORT } from './paths.ts';
 import { accountHsts, accountProblem } from './security.ts';
 import { Manuscripts } from './manuscript.ts';
+import { Changes } from './changes.ts';
 import { buildApp, gitQueue } from './app.ts';
 
 const problem = accountProblem(ACCOUNT_ORIGIN, ACCOUNT_PORT, PORT, PUBLIC_ORIGIN);
@@ -15,7 +16,7 @@ const store = new Store(path.join(DATA, 'papilot.sqlite'));
 const workspace = new Workspace(store);
 const accounts = new Accounts(store, ACCOUNT_ORIGIN || null);
 const shared = {
-  store, workspace, accounts, manuscripts: new Manuscripts(), csrf: randomBytes(32).toString('base64url'), serialGit: gitQueue(),
+  store, workspace, accounts, manuscripts: new Manuscripts(), changes: new Changes(), csrf: randomBytes(32).toString('base64url'), serialGit: gitQueue(),
   dist: fs.existsSync(path.join(ROOT, 'dist/index.html')) ? path.join(ROOT, 'dist') : null, version: VERSION,
 };
 const apps = [await buildApp({ ...shared, listener: { kind: 'local', port: PORT, publicOrigin: PUBLIC_ORIGIN, owner: OWNER } })];

package/src/server/manuscript.ts

@@ -37,14 +37,15 @@ export function parseStatus(output: string, numstat: string): Omit<GitStatus, 'h
     if (field.startsWith('# branch.head ')) status.branch = field.slice(14) === '(detached)' ? null : field.slice(14);
     else if (field.startsWith('# branch.upstream ')) status.upstream = field.slice(18);
     else if (field.startsWith('# branch.ab ')) { const [ahead, behind] = field.slice(12).split(' '); status.ahead = Number(ahead); status.behind = -Number(behind); }
-    else if (field.startsWith('? ')) status.files.push({ path: field.slice(2), status: '?', staged: false });
+    else if (field.startsWith('? ')) status.files.push({ path: field.slice(2), status: '?', staged: false, unstaged: true });
     else if (/^[12u] /.test(field)) {
       const parts = field.split(' '), xy = parts[1], kind = field[0];
       const file = parts.slice(kind === '1' ? 8 : kind === '2' ? 9 : 10).join(' ');
       // A rename or copy is followed by its original path.
       const from = kind === '2' ? fields[++i] : undefined;
       const code = kind === 'u' ? 'U' : xy[1] !== '.' ? xy[1] : xy[0];
-      status.files.push({ path: file, status: code, staged: xy[0] !== '.', lines: lines.get(file), ...(from ? { from } : {}) });
+      // X is the index against HEAD, Y the working tree against the index.
+      status.files.push({ path: file, status: code, staged: xy[0] !== '.', unstaged: xy[1] !== '.', lines: lines.get(file), ...(from ? { from } : {}) });
     }
   }
   return status;
@@ -91,23 +92,26 @@ export async function gitDiff(root: string, file: string) {
   const diff = await fileDiff(root, entry);
   return { path: file, diff: diff.slice(0, DIFF_LIMIT), truncated: diff.length > DIFF_LIMIT };
 }
-function fileDiff(root: string, entry: GitFile) {
+// A file's diff against HEAD, or with staged, what its index holds.
+function fileDiff(root: string, entry: GitFile, staged = false) {
+  const names = ['--', ...(entry.from ? [entry.from] : []), entry.path];
+  if (staged) return git(root, ['diff', '--cached', '--no-color', '--find-renames', ...names], literal);
   return entry.status === '?'
     // `git diff --no-index` exits with 1 when the files differ.
     ? exec('git', ['diff', '--no-index', '--no-color', '--', '/dev/null', entry.path], { cwd: root, maxBuffer: 64 * 1024 * 1024 }).then(r => r.stdout, (e: { stdout?: string }) => e.stdout || '')
-    : git(root, ['diff', '--no-color', '--find-renames', 'HEAD', '--', ...(entry.from ? [entry.from] : []), entry.path], literal);
+    : git(root, ['diff', '--no-color', '--find-renames', 'HEAD', ...names], literal);
 }
 
-// What a commit message is written from: the chosen files' diffs, each
-// shortened so that a large change still fits, and the repository's recent
-// commit subjects, whose style and language the message follows.
-export async function commitChanges(root: string, paths: string[]) {
-  const files = (await gitStatus(root)).files.filter(item => paths.includes(item.path));
-  if (!files.length) throw new Error('Select at least one changed file.');
+// What a commit message is written from: the chosen files' diffs, or what is
+// staged in them, each shortened so that a large change still fits, and the
+// repository's recent commit subjects, whose style and language the message follows.
+export async function commitChanges(root: string, paths: string[], staged = false) {
+  const files = (await gitStatus(root)).files.filter(item => paths.includes(item.path) && (!staged || item.staged));
+  if (!files.length) throw new Error(staged ? 'Stage at least one change.' : 'Select at least one changed file.');
   let patch = '';
   for (const [index, file] of files.entries()) {
     if (patch.length > 40_000) { patch += `\n[${files.length - index} more changed files are not shown.]\n`; break; }
-    const diff = await fileDiff(root, file);
+    const diff = await fileDiff(root, file, staged);
     patch += diff.length > 8_000 ? `${diff.slice(0, 8_000)}\n[The rest of this file's diff is not shown.]\n` : diff;
   }
   const recent = (await git(root, ['log', '-8', '--format=%s']).catch(() => '')).split('\n').filter(Boolean);
@@ -128,11 +132,29 @@ export async function gitIgnore(root: string, paths: string[]) {
   return gitStatus(root);
 }
 
-// Commit exactly the chosen files as they are on disk. Changes staged
-// elsewhere for other files stay staged and out of this commit.
-export async function gitCommit(root: string, message: string, paths: string[]) {
+// Stage or unstage whole files, as the Git panel's checkboxes do. A rename
+// moves with both of its paths.
+export async function gitStage(root: string, paths: string[], stage: boolean) {
   const status = await gitStatus(root), files = status.files.filter(item => paths.includes(item.path));
+  if (status.merging) throw new Error('Finish or abort the merge before staging other changes.');
+  if (!files.length) throw new Error('Select at least one changed file.');
+  const names = [...new Set(files.flatMap(item => item.from ? [item.from, item.path] : [item.path]))];
+  if (stage) await gitAction(root, ['add', '-A', '--', ...names]);
+  else await gitAction(root, status.head ? ['reset', '-q', 'HEAD', '--', ...names] : ['rm', '-r', '-q', '--cached', '--ignore-unmatch', '--', ...names]);
+  return gitStatus(root);
+}
+
+// Commit what is staged, or with paths, exactly those files as they are on
+// disk; changes staged for other files then stay staged and out of the commit.
+export async function gitCommit(root: string, message: string, paths: string[] | null) {
+  const status = await gitStatus(root);
   if (status.merging) throw new Error('Finish or abort the merge before committing other changes.');
+  if (!paths) {
+    if (!status.files.some(item => item.staged)) throw new Error('Stage at least one change to commit.');
+    await gitAction(root, ['commit', '-m', message]);
+    return (await git(root, ['rev-parse', '--short', 'HEAD'])).trim();
+  }
+  const files = status.files.filter(item => paths.includes(item.path));
   if (!files.length) throw new Error('Select at least one changed file to commit.');
   if (files.some(item => item.status === 'U')) throw new Error('Resolve the merge conflicts in the selected files before committing.');
   // A rename is already staged, so only its new path is added; the commit

package/src/server/workspace.ts

@@ -580,9 +580,9 @@ ${this.agentOf(task) === 'antigravity' ? 'Shell commands are not available to yo
   // generate button: one read-only turn on the agent's small model, with the
   // lightest reasoning it offers. The same changes get the message already
   // written, or being written, for them unless the author asks for a fresh one.
-  async commitMessage(projectId: string, paths: string[], choice: { agent?: AgentId; fresh?: boolean } = {}) {
+  async commitMessage(projectId: string, paths: string[], choice: { agent?: AgentId; fresh?: boolean; staged?: boolean } = {}) {
     const project = this.store.project(projectId), { id, model } = this.helper(choice, 'write a commit message', true);
-    const { files, patch, recent } = await commitChanges(project.path, paths);
+    const { files, patch, recent } = await commitChanges(project.path, paths, choice.staged);
     const tasks = this.store.tasks().filter(task => task.projectId === projectId && task.review?.files?.some(file => paths.includes(file))).map(task => task.title);
     const prompt = [
       recent.length ? `Recent commit subjects in this repository:\n${recent.map(subject => `- ${subject}`).join('\n')}` : 'This repository has no commits yet.',

package/src/shared.ts

@@ -45,7 +45,8 @@ export interface Person { id: string; name: string; role: 'owner' | 'member'; jo
 // A passkey or a signed-in browser session, either of which the owner can revoke.
 export interface Device { id: string; kind: 'passkey' | 'session'; label: string; createdAt: number; lastUsedAt: number | null }
 export interface People { origin: string | null; people: Person[] }
-export interface GitFile { path: string; status: string; staged: boolean; lines?: [number, number]; from?: string }
+// staged: the index has changes to this file; unstaged: the working tree has more.
+export interface GitFile { path: string; status: string; staged: boolean; unstaged: boolean; lines?: [number, number]; from?: string }
 // merging is a merge in progress, with the files whose conflict markers remain.
 export interface GitStatus { branch: string | null; upstream: string | null; ahead: number; behind: number; files: GitFile[]; head: { hash: string; subject: string; date: number } | null; remote?: boolean; merging?: { message: string; conflicts: string[] } | null }
 export interface GitDiff { path: string; diff: string; truncated: boolean }