papilot 0.0.0-stage → 0.1.0

package/src/server/main.ts

@@ -0,0 +1,202 @@
+import Fastify from 'fastify';
+import { registerFrontend } from './frontend.ts';
+import compress from '@fastify/compress';
+import fs from 'node:fs';
+import path from 'node:path';
+import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { Store } from './store.ts';
+import { Workspace } from './workspace.ts';
+import { ROOT, DATA, PORT, PUBLIC_ORIGIN, OWNER } from './paths.ts';
+import { reviewClient, allowedReviewRoute, rewriteReviewHtml, rewriteReviewJson, confirmedReviewResponse, annotateReviewState } from './review.ts';
+import { authorize } from './security.ts';
+import { fullPaperPdf } from './pdf.ts';
+import { Manuscripts, annotationTask, gitCommit, gitDiff, gitRemote, gitStatus } from './manuscript.ts';
+import type { AgentId } from '../shared.ts';
+
+const store = new Store(path.join(DATA, 'papilot.sqlite'));
+const workspace = new Workspace(store);
+const manuscripts = new Manuscripts();
+const app = Fastify({ logger: false, bodyLimit: 1024 * 1024 });
+const csrf = randomBytes(32).toString('base64url');
+const equals = (a: string, b: string) => { const x = Buffer.from(a), y = Buffer.from(b); return x.length === y.length && timingSafeEqual(x, y); };
+await app.register(compress);
+app.addHook('onRequest', async (request, reply) => {
+  reply.header('X-Content-Type-Options', 'nosniff').header('Referrer-Policy', 'same-origin').header('X-Frame-Options', 'SAMEORIGIN').header('Cache-Control', 'no-store');
+  const denied = authorize(request.headers, request.raw.socket.remoteAddress, PORT, PUBLIC_ORIGIN, OWNER);
+  if (denied) return reply.code(403).send({ error: denied });
+  if (request.method === 'POST' && !request.url.startsWith('/review/') && !equals(String(request.headers['x-papilot-token'] || ''), csrf)) return reply.code(403).send({ error: 'This page has expired. Refresh it and try again.' });
+});
+app.setErrorHandler((error, _request, reply) => { reply.code((error as any).statusCode || 400).send({ error: (error as Error).message }); });
+app.get('/api/health', () => ({ ok: true, name: 'Papilot', version: '0.1.0' }));
+app.get('/api/state', () => ({ ...workspace.snapshot(), csrf }));
+app.get('/api/events', (request, reply) => {
+  reply.hijack();
+  reply.raw.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache, no-transform', Connection: 'keep-alive', 'X-Accel-Buffering': 'no' });
+  reply.raw.write('event: change\ndata: {}\n\n');
+  let timer: NodeJS.Timeout | undefined;
+  const change = () => { timer ??= setTimeout(() => { timer = undefined; reply.raw.write('event: change\ndata: {}\n\n'); }, 400); };
+  workspace.on('change', change);
+  const heartbeat = setInterval(() => reply.raw.write(': heartbeat\n\n'), 15000);
+  reply.raw.on('close', () => { clearInterval(heartbeat); if (timer) clearTimeout(timer); workspace.off('change', change); });
+});
+app.post('/api/reconnect', async () => { await workspace.connect(); return workspace.runtime; });
+// Codex names reasoning efforts with short lowercase words (low, medium, xhigh).
+const agent = (value: unknown): AgentId => value === 'claude' || value === 'antigravity' ? value : 'codex';
+const effort = (value: unknown) => typeof value === 'string' && /^[a-z]{1,16}$/.test(value) ? value : undefined;
+const string = (value: unknown, name: string, max = 20000) => { if (typeof value !== 'string' || !value.trim() || value.length > max) throw new Error(`${name} is required and must be no longer than ${max} characters.`); return value.trim(); };
+app.post('/api/projects', async request => { const b = request.body as any; return workspace.addProject(string(b.path, 'Repository path', 4000), b.name ? string(b.name, 'Paper name', 120) : undefined); });
+app.post<{ Params: { id: string } }>('/api/projects/:id/rename', request => workspace.renameProject(request.params.id, string((request.body as any).name, 'Paper name', 120)));
+app.post('/api/tasks', async request => {
+  const b = request.body as any;
+  return workspace.createTask({ id: string(b.id, 'Task ID', 64), projectId: string(b.projectId, 'Paper ID', 64), title: string(b.title, 'Task title', 120), instructions: string(b.instructions, 'Instructions'), agent: agent(b.agent), model: typeof b.model === 'string' ? b.model : undefined, effort: effort(b.effort) });
+});
+app.get<{ Params: { id: string } }>('/api/tasks/:id/items', request => { store.task(request.params.id); return { items: store.items(request.params.id) }; });
+app.get<{ Params: { id: string }; Querystring: { round?: string; version?: string; download?: string } }>('/api/tasks/:id/pdf', async (request, reply) => {
+  const task = store.task(request.params.id), project = store.project(task.projectId);
+  const round = request.query.round === undefined ? task.review?.round : Number(request.query.round);
+  const side = request.query.version || 'after';
+  if (!round || !Number.isSafeInteger(round) || round < 1 || (side !== 'before' && side !== 'after')) return reply.code(400).send({ error: 'Select an existing review round and either the before or after PDF.' });
+  const pdf = await fullPaperPdf(project.path, task.name, round, side);
+  const filename = `papilot-${task.name}-r${round}-${side}.pdf`;
+  return reply.type('application/pdf').header('Content-Disposition', `${request.query.download === '1' ? 'attachment' : 'inline'}; filename="${filename}"`).sendFile(path.basename(pdf), path.dirname(pdf), { cacheControl: false });
+});
+app.post<{ Params: { id: string } }>('/api/tasks/:id/messages', async request => {
+  const b = request.body as any;
+  return workspace.enqueue(request.params.id, string(b.text, 'Revision instructions'), string(b.requestKey, 'Request ID', 100), true);
+});
+app.post<{ Params: { id: string } }>('/api/tasks/:id/rename', request => workspace.renameTask(request.params.id, string((request.body as any).title, 'Task title', 120)));
+app.post<{ Params: { id: string } }>('/api/tasks/:id/interrupt', request => workspace.interrupt(request.params.id).then(() => ({ ok: true })));
+app.post<{ Params: { id: string } }>('/api/tasks/:id/delete', request => {
+  if ((request.body as any)?.confirm !== true) throw new Error('Confirm permanent task deletion before continuing.');
+  return workspace.deleteTask(request.params.id);
+});
+app.post<{ Params: { id: string } }>('/api/tasks/:id/reconcile', request => workspace.reconcile(request.params.id));
+app.post<{ Params: { id: string } }>('/api/tasks/:id/publish', request => {
+  const task = store.task(request.params.id); if (['running', 'waiting_input', 'building'].includes(task.status)) throw new Error('This task is busy. Wait for it to finish or pause it first.');
+  void workspace.publish(task.id); return { ok: true };
+});
+// The manuscript preview compiles each paper's working tree and reports its Git status.
+app.get<{ Params: { id: string } }>('/api/projects/:id/manuscript', 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', request => gitStatus(store.project(request.params.id).path));
+// Git writes to one repository run one at a time; each returns the new status.
+const gitQueue = new Map<string, Promise<unknown>>();
+function serialGit<T>(projectId: string, work: () => Promise<T>) {
+  const run = (gitQueue.get(projectId) || Promise.resolve()).catch(() => {}).then(work);
+  gitQueue.set(projectId, run);
+  return run.finally(() => { if (gitQueue.get(projectId) === run) gitQueue.delete(projectId); });
+}
+app.get<{ Params: { id: string }; Querystring: { path?: string } }>('/api/projects/:id/git/diff', request => gitDiff(store.project(request.params.id).path, string(request.query.path, 'File path', 4096)));
+app.post<{ Params: { id: string } }>('/api/projects/:id/git/commit', 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, async () => ({ commit: await gitCommit(project.path, message, paths), git: await gitStatus(project.path) }));
+});
+app.post<{ Params: { id: string; action: string } }>('/api/projects/:id/git/:action', request => {
+  const project = store.project(request.params.id), action = request.params.action;
+  if (action !== 'fetch' && action !== 'pull' && action !== 'push') throw Object.assign(new Error('Unknown Git action.'), { statusCode: 404 });
+  return serialGit(project.id, async () => { await gitRemote(project.path, action); return { git: await gitStatus(project.path) }; });
+});
+app.post<{ Params: { id: string } }>('/api/projects/:id/manuscript', async request => ({ ...(await manuscripts.state(request.params.id, store.project(request.params.id).path, true)), annotations: store.annotations(request.params.id).filter(note => !note.taskId) }));
+// Notes marked on the manuscript PDF become one agent task when sent.
+app.post<{ Params: { id: string } }>('/api/projects/:id/annotations', async request => {
+  const project = store.project(request.params.id), b = request.body as any;
+  const isRect = (value: unknown): value is [number, number, number, number] => Array.isArray(value) && value.length === 4 && value.every(v => typeof v === 'number' && v >= 0 && v <= 1) && value[2] > value[0] && value[3] > value[1];
+  if (!isRect(b.rect)) throw new Error('Select text or mark a region on the page first.');
+  const rects = Array.isArray(b.rects) ? b.rects.slice(0, 80).filter(isRect) : [];
+  const comment = string(b.comment, 'Note', 4000), key = string(b.key, 'Preview key', 64), page = Number(b.page);
+  const selected = typeof b.quote === 'string' ? b.quote.slice(0, 2000) : '';
+  const { quote, source } = await manuscripts.locate(project.id, key, page, b.rect, rects, selected);
+  return store.saveAnnotation({ id: randomUUID(), projectId: project.id, key, page, rect: b.rect, ...(rects.length ? { rects } : {}), comment, quote, source, createdAt: Date.now() });
+});
+app.post<{ Params: { id: string; note: string } }>('/api/projects/:id/annotations/:note/delete', request => { store.deleteAnnotation(store.project(request.params.id).id, request.params.note); return { ok: true }; });
+app.post<{ Params: { id: string } }>('/api/projects/:id/annotations/send', async request => {
+  const project = store.project(request.params.id), b = request.body as any, id = string(b.id, 'Task ID', 64);
+  const existing = store.tasks().find(task => task.id === id);
+  if (existing) return existing;
+  const notes = store.annotations(project.id).filter(note => !note.taskId);
+  if (!notes.length) throw new Error('Mark a region on the PDF and add a note first.');
+  const { title, instructions } = annotationTask(notes);
+  const task = await workspace.createTask({ id, projectId: project.id, title, instructions, agent: agent(b.agent), model: typeof b.model === 'string' ? b.model : undefined, effort: effort(b.effort) });
+  for (const note of notes) store.saveAnnotation({ ...note, taskId: task.id });
+  return task;
+});
+// Exact word places for the PDF view's selection layer; immutable per build key.
+app.get<{ Params: { id: string }; Querystring: { key?: string; page?: string } }>('/api/projects/:id/manuscript/words', async (request, reply) => {
+  const project = store.project(request.params.id);
+  const words = await manuscripts.words(project.id, String(request.query.key || ''), Number(request.query.page));
+  return reply.header('Cache-Control', 'private, max-age=31536000, immutable').send(words);
+});
+app.get<{ Params: { id: string }; Querystring: { key?: string; download?: string } }>('/api/projects/:id/manuscript.pdf', (request, reply) => {
+  const project = store.project(request.params.id), pdf = manuscripts.pdf(project.id, String(request.query.key || ''));
+  const name = (project.name.replace(/[^\w.-]+/g, '-').replace(/^-+|-+$/g, '') || 'manuscript') + '.pdf';
+  // Each key names one immutable build, so the viewer can cache and range-read it.
+  return reply.type('application/pdf').header('Content-Disposition', `${request.query.download === '1' ? 'attachment' : 'inline'}; filename="${name}"`).header('Cache-Control', 'private, max-age=31536000, immutable').sendFile(path.basename(pdf), path.dirname(pdf), { cacheControl: false });
+});
+app.post<{ Params: { id: string } }>('/api/requests/:id', request => { workspace.answer(request.params.id, request.body as any); return { ok: true }; });
+
+app.route<{ Params: { projectId: string; '*': string } }>({
+  method: ['GET', 'POST'], url: '/review/:projectId/*', handler: async (request, reply) => {
+    const project = store.project(request.params.projectId);
+    const route = '/' + request.params['*'];
+    if (route.includes('..') || !allowedReviewRoute(route, request.method)) return reply.code(404).send({ error: 'Review resource not found.' });
+    const client = await reviewClient(project.path);
+    if (request.method === 'POST') {
+      if (!equals(String(request.headers['x-review-token'] || ''), client.token)) return reply.code(403).send({ error: 'This review page has expired. Refresh it and try again.' });
+    }
+    const reviewTask = request.method === 'POST' ? store.tasks().find(t => t.projectId === project.id && t.name === route.split('/')[3]) : undefined;
+    const writesFiles = route.endsWith('/undo') || (route.endsWith('/decide') && (request.body as any)?.action !== 'comment');
+    if (request.method === 'POST' && writesFiles) string((request.body as any)?.id, 'Review action ID', 80);
+    const forward = async () => {
+      const search = new URL(request.url, 'http://localhost').search;
+      const response = await fetch(client.url + route + search, {
+        method: request.method, headers: { 'Content-Type': 'application/json', 'X-Review-Token': client.token },
+        ...(request.method === 'POST' ? { body: JSON.stringify(request.body) } : {}),
+        signal: AbortSignal.timeout(120000), redirect: 'error',
+      });
+      reply.code(response.status);
+      const type = response.headers.get('content-type') || 'application/octet-stream';
+      const prefix = `/review/${project.id}`;
+      if (type.includes('application/json')) {
+        const value = await response.json();
+        if (reviewTask && writesFiles && !confirmedReviewResponse(response.status, value, reviewTask.name)) throw new Error('The review engine could not confirm this action. Select Check status before continuing.');
+        if (!response.ok && request.method === 'POST' && (value as any).error) {
+          const task = store.tasks().find(t => t.projectId === project.id && t.name === route.split('/')[3]);
+          if (task) store.updateTask(task.id, { error: 'Review action failed: ' + (value as any).error });
+        }
+        if (response.ok && request.method === 'POST') {
+          const task = store.tasks().find(t => t.projectId === project.id && t.name === route.split('/')[3]);
+          if (task) {
+            store.updateTask(task.id, { error: null });
+            await workspace.refresh(task.id);
+          }
+        }
+        return rewriteReviewJson(value, prefix);
+      }
+      if (reviewTask && writesFiles) throw new Error('The review engine returned an unexpected response. Select Check status before continuing.');
+      reply.type(type);
+      if (type.includes('text/html')) return rewriteReviewHtml(await response.text(), prefix);
+      const cache = response.headers.get('cache-control'); if (cache && route.startsWith('/files/')) reply.header('Cache-Control', cache);
+      if (route.startsWith('/assets/')) reply.header('Cache-Control', 'private, max-age=31536000, immutable');
+      return Buffer.from(await response.arrayBuffer());
+    };
+    if (request.method === 'POST' && !reviewTask) throw new Error('This review task does not belong to this workspace.');
+    const result = await (reviewTask ? workspace.reviewWrite(reviewTask.id, writesFiles, forward, writesFiles ? { route, body: request.body as Record<string, unknown> } : undefined) : forward());
+    return annotateReviewState(result, store.tasks().filter(task => task.projectId === project.id));
+  },
+});
+
+if (fs.existsSync(path.join(ROOT, 'dist/index.html'))) {
+  await registerFrontend(app, path.join(ROOT, 'dist'));
+} else app.get('/', (_request, reply) => reply.type('text/plain').send('Papilot: run npm run build, then restart the server.'));
+
+await app.listen({ host: '127.0.0.1', port: PORT });
+store.recover();
+console.log(`Papilot is running at http://127.0.0.1:${PORT}${PUBLIC_ORIGIN ? `\nRemote: ${PUBLIC_ORIGIN}` : ''}`);
+void workspace.connect();
+for (const task of store.tasks().filter(t => t.status === 'building')) { store.updateTask(task.id, { status: 'interrupted', error: 'The server restarted during the PDF build. Check the review and rebuild it if needed.' }); void workspace.refresh(task.id); }
+let shuttingDown = false;
+for (const signal of ['SIGINT', 'SIGTERM']) process.on(signal, () => {
+  if (shuttingDown) return; shuttingDown = true; workspace.close();
+  void app.close().finally(() => { store.close(); process.exit(0); });
+  setTimeout(() => process.exit(0), 2500).unref();
+});

package/src/server/manuscript.ts

@@ -0,0 +1,337 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { EventEmitter } from 'node:events';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { pathToFileURL } from 'node:url';
+import { ENGINE } from './paths.ts';
+import type { Annotation, GitStatus, ManuscriptBuild } from '../shared.ts';
+import { notesInstructions } from '../notes.ts';
+
+type Rect = [number, number, number, number];
+
+const exec = promisify(execFile);
+async function git(root: string, args: string[], env: NodeJS.ProcessEnv = {}) {
+  return (await exec('git', args, { cwd: root, env: { ...process.env, ...env }, maxBuffer: 64 * 1024 * 1024 })).stdout;
+}
+
+// Porcelain v2 keeps paths with spaces intact under -z and reports branch,
+// upstream and ahead/behind counts without a second command.
+export function parseStatus(output: string, numstat: string): Omit<GitStatus, 'head'> {
+  const lines = new Map<string, [number, number]>();
+  const stats = numstat.split('\0');
+  for (let i = 0; i < stats.length; i++) {
+    const [added, deleted, file] = stats[i].split('\t');
+    if (!added) continue;
+    // A rename lists an empty path followed by the old and new paths.
+    const target = file || (i += 2, stats[i]);
+    if (target && added !== '-') lines.set(target, [Number(added), Number(deleted)]);
+  }
+  const status: Omit<GitStatus, 'head'> = { branch: null, upstream: null, ahead: 0, behind: 0, files: [] };
+  const fields = output.split('\0');
+  for (let i = 0; i < fields.length; i++) {
+    const field = fields[i];
+    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 (/^[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 } : {}) });
+    }
+  }
+  return status;
+}
+
+export async function gitStatus(root: string): Promise<GitStatus> {
+  const [status, numstat, head, remotes] = await Promise.all([
+    git(root, ['status', '--porcelain=v2', '--branch', '-z', '--untracked-files=all']),
+    git(root, ['diff', '--numstat', '-z', 'HEAD']).catch(() => ''),
+    git(root, ['log', '-1', '--format=%h%x00%s%x00%ct']).catch(() => ''),
+    git(root, ['remote']).catch(() => ''),
+  ]);
+  const [hash, subject, time] = head.trim().split('\0');
+  return { ...parseStatus(status, numstat), head: hash ? { hash, subject, date: Number(time) * 1000 } : null, remote: Boolean(remotes.trim()) };
+}
+
+// Paths from the browser are matched against the changed files, and Git reads
+// them literally, so a name cannot act as a pathspec pattern.
+const literal = { GIT_LITERAL_PATHSPECS: '1' };
+const DIFF_LIMIT = 400_000;
+
+// One changed file's diff against HEAD; an untracked file shows as all new.
+export async function gitDiff(root: string, file: string) {
+  const entry = (await gitStatus(root)).files.find(item => item.path === file);
+  if (!entry) throw Object.assign(new Error('That file has no uncommitted changes.'), { statusCode: 404 });
+  const diff = entry.status === '?'
+    // `git diff --no-index` exits with 1 when the files differ.
+    ? await exec('git', ['diff', '--no-index', '--no-color', '--', '/dev/null', file], { cwd: root, maxBuffer: 64 * 1024 * 1024 }).then(r => r.stdout, (e: { stdout?: string }) => e.stdout || '')
+    : await git(root, ['diff', '--no-color', '--find-renames', 'HEAD', '--', ...(entry.from ? [entry.from] : []), file], literal);
+  return { path: file, diff: diff.slice(0, DIFF_LIMIT), truncated: diff.length > DIFF_LIMIT };
+}
+
+// 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[]) {
+  const files = (await gitStatus(root)).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
+  // names the old path too, so the removal is part of it.
+  await gitAction(root, ['add', '-A', '--', ...files.map(item => item.path)]);
+  await gitAction(root, ['commit', '--only', '-m', message, '--', ...new Set(files.flatMap(item => item.from ? [item.from, item.path] : [item.path]))]);
+  return (await git(root, ['rev-parse', '--short', 'HEAD'])).trim();
+}
+
+// Fetch, fast-forward pull and push use the host's Git credentials. Nothing
+// may prompt, so a missing credential fails instead of hanging.
+export async function gitRemote(root: string, action: 'fetch' | 'pull' | 'push') {
+  const status = await gitStatus(root);
+  if (!status.remote) throw new Error('This repository has no remote.');
+  if (action === 'fetch') await gitAction(root, ['fetch', '--prune'], 120_000);
+  else if (action === 'pull') {
+    if (!status.upstream) throw new Error('This branch does not track a remote branch yet.');
+    await gitAction(root, ['pull', '--ff-only'], 120_000);
+  } else if (status.upstream) await gitAction(root, ['push'], 120_000);
+  else {
+    if (!status.branch) throw new Error('Check out a branch before pushing.');
+    const remotes = (await git(root, ['remote'])).split('\n').filter(Boolean);
+    await gitAction(root, ['push', '-u', remotes.includes('origin') ? 'origin' : remotes[0], status.branch], 120_000);
+  }
+}
+
+// Git's own message, without the usage noise, becomes the error the user sees.
+async function gitAction(root: string, args: string[], timeout = 60_000) {
+  try { return (await exec('git', args, { cwd: root, timeout, env: { ...process.env, ...literal, GIT_TERMINAL_PROMPT: '0' }, maxBuffer: 64 * 1024 * 1024 })).stdout; }
+  catch (error) {
+    const e = error as { stderr?: string; stdout?: string; killed?: boolean; message: string };
+    const detail = (e.stderr || e.stdout || '').split('\n').map(line => line.trim()).filter(line => line && !/^(hint|To |From ):?/.test(line)).slice(-4).join(' ');
+    throw new Error(e.killed ? `git ${args[0]} timed out.` : detail || e.message);
+  }
+}
+
+// The preview shows the manuscript as it is on disk, including accepted but
+// uncommitted review changes. A temporary index records it as a Git tree
+// without touching the real index, branches or files.
+export async function workingTree(root: string) {
+  const folder = fs.mkdtempSync(path.join(os.tmpdir(), 'papilot-index-')), env = { GIT_INDEX_FILE: path.join(folder, 'index') };
+  try {
+    await git(root, ['read-tree', 'HEAD'], env);
+    await git(root, ['add', '-A'], env);
+    return (await git(root, ['write-tree'], env)).trim();
+  } finally { fs.rmSync(folder, { recursive: true, force: true }); }
+}
+
+async function engine() {
+  const [{ Builder }, { Repo }, { loadProject }, { mupdf, PdfDocument, containsCenter }] = await Promise.all([
+    import(pathToFileURL(path.join(ENGINE, 'src/core/build.ts')).href),
+    import(pathToFileURL(path.join(ENGINE, 'src/core/git.ts')).href),
+    import(pathToFileURL(path.join(ENGINE, 'src/core/config.ts')).href),
+    import(pathToFileURL(path.join(ENGINE, 'src/render/pdf.ts')).href),
+  ]);
+  return { Builder, Repo, loadProject, mupdf, PdfDocument, containsCenter };
+}
+
+// `synctex edit` maps a PDF position (big points from the top-left corner) to
+// the source file and line that produced it.
+export function parseSynctex(output: string) {
+  const input = /^Input:(.*)$/m.exec(output)?.[1], line = Number(/^Line:(\d+)$/m.exec(output)?.[1]);
+  return input && line > 0 ? { input: path.normalize(input), line } : null;
+}
+
+// One task for every pending note, quoting the marked text and its source so
+// the agent can find each place without guessing.
+export function annotationTask(notes: Annotation[]) {
+  const first = notes[0].comment.split('\n').find(line => line.trim())?.trim() || 'Address a PDF note';
+  const title = notes.length === 1 ? (first.length > 80 ? first.slice(0, 79).replace(/\s+\S*$/, '') + '…' : first) : `Address ${notes.length} PDF notes`;
+  return { title, instructions: notesInstructions(notes) };
+}
+
+// The LaTeX the marked region came from, read from the exact tree that was
+// compiled. Long ranges keep their first lines.
+// Where one end of a selection sits in its printed line: the line's letters and
+// the index of the marked letter among them.
+export interface Anchor { line: string; at: number }
+const letters = (text: string) => text.normalize('NFKC').toLowerCase().replace(/[^\p{L}\p{N}]+/gu, '');
+
+// The printed line around a marked character, for settleLines.
+export function anchor(chars: { text: string }[], index: number, end: boolean): Anchor | null {
+  const line = letters(chars.map(c => c.text).join(''));
+  if (!line) return null;
+  const at = end ? letters(chars.slice(0, index + 1).map(c => c.text).join('')).length - 1 : letters(chars.slice(0, index).map(c => c.text).join('')).length;
+  return { line, at: Math.min(Math.max(at, 0), line.length - 1) };
+}
+
+// SyncTeX records spaces and boxes rather than characters, so a word that
+// starts a printed line is often credited to the source line before it, whose
+// line break made the space. Settle each end of the selection by finding its
+// printed line among the source lines around SyncTeX's answer; text that does
+// not match, such as formulas, keeps SyncTeX's lines.
+export function settleLines(source: string[], [start, end]: [number, number], first: Anchor | null, last: Anchor | null): [number, number] {
+  const low = Math.max(1, start - 4), high = Math.min(source.length, end + 4);
+  let text = '';
+  const owner: number[] = [];
+  for (let number = low; number <= high; number++) {
+    const plain = letters(source[number - 1].replace(/(^|[^\\])%.*$/, '$1').replace(/\\[a-zA-Z@]+\*?/g, ' '));
+    text += plain; owner.push(...Array<number>(plain.length).fill(number));
+  }
+  const distance = (line: number) => Math.max(0, start - line, line - end);
+  const locate = (mark: Anchor | null) => {
+    if (!mark) return null;
+    // The whole printed line pins the place best; shorter context around the
+    // mark still matches when part of the line does not appear in the source.
+    for (const reach of [Infinity, 24, 10]) {
+      const from = Math.max(0, mark.at - reach), needle = mark.line.slice(from, mark.at + reach + 1);
+      let best: number | null = null;
+      for (let index = text.indexOf(needle); index >= 0; index = text.indexOf(needle, index + 1)) {
+        const line = owner[index + mark.at - from];
+        if (best === null || distance(line) < distance(best)) best = line;
+      }
+      if (best !== null) return best;
+    }
+    return null;
+  };
+  const from = locate(first) ?? start, to = locate(last) ?? end;
+  return from <= to ? [from, to] : [start, end];
+}
+
+export function sourceExcerpt(file: string, [start, end]: [number, number], limit = 20) {
+  if (!fs.existsSync(file)) return undefined;
+  const lines = fs.readFileSync(file, 'utf8').split('\n').slice(start - 1, end).map(line => line.trimEnd());
+  return (lines.length > limit ? [...lines.slice(0, limit), '…'] : lines).join('\n');
+}
+
+// Every word on a page with its exact place, for the PDF view's selection
+// layer: [text, left, baseline, font size, width, ends a line], in points from
+// the page's top left. pdf.js lays a whole line out in a stand-in font and
+// drifts from the printed words mid-line; per-word runs cannot drift.
+export async function pdfWords(pdf: string, page: number) {
+  const { PdfDocument } = await engine();
+  const document = new PdfDocument(pdf);
+  try {
+    if (!Number.isInteger(page) || page < 0 || page >= document.length) throw Object.assign(new Error('That page is not part of the manuscript.'), { statusCode: 400 });
+    const raw = document.raw.loadPage(page), [x0, y0, x1, y1] = raw.getBounds();
+    const words: { text: string; left: number; right: number; baseline: number; size: number; eol: boolean }[] = [];
+    let word: (typeof words)[number] | null = null;
+    const text = raw.toStructuredText('preserve-whitespace');
+    text.walk({
+      beginLine: () => { word = null; },
+      onChar: (c: string, origin: [number, number], _font: unknown, size: number, quad: number[]) => {
+        if (/\s/u.test(c)) { word = null; return; }
+        const left = Math.min(quad[0], quad[2], quad[4], quad[6]) - x0, right = Math.max(quad[0], quad[2], quad[4], quad[6]) - x0;
+        if (!word) { word = { text: '', left, right, baseline: origin[1] - y0, size, eol: false }; words.push(word); }
+        word.text += c; word.right = Math.max(word.right, right);
+      },
+      endLine: () => { if (words.length) words[words.length - 1].eol = true; },
+    });
+    text.destroy(); raw.destroy();
+    const round = (value: number) => Math.round(value * 100) / 100;
+    return { width: round(x1 - x0), height: round(y1 - y0), words: words.map(w => [w.text, round(w.left), round(w.baseline), round(w.size), round(w.right - w.left), w.eol ? 1 : 0] as [string, number, number, number, number, number]) };
+  } finally { document.close(); }
+}
+
+interface Build { tree: string; status: ManuscriptBuild['status']; key?: string; pdf?: string; root?: string; sourceDir?: string; pages?: [number, number][]; builtAt?: number; error?: string }
+
+export class Manuscripts extends EventEmitter {
+  private builds = new Map<string, Build>();
+
+  async state(projectId: string, root: string, rebuild = false): Promise<{ git: GitStatus; build: ManuscriptBuild }> {
+    const [status, tree] = await Promise.all([gitStatus(root), workingTree(root)]);
+    let build = this.builds.get(projectId);
+    if (!build || (build.status !== 'building' && (build.tree !== tree || (rebuild && build.status === 'failed')))) build = this.start(projectId, root, tree, build);
+    const { status: state, key, pages, builtAt, error } = build;
+    return { git: status, build: { status: state, key, pages, builtAt, error, current: build.tree === tree && state === 'ready' } };
+  }
+
+  // Keep the previous pages visible while a newer working tree compiles.
+  private start(projectId: string, root: string, tree: string, previous?: Build) {
+    const build: Build = { tree, status: 'building', key: previous?.key, pdf: previous?.pdf, pages: previous?.pages, builtAt: previous?.builtAt };
+    this.builds.set(projectId, build);
+    void (async () => {
+      try {
+        const { Builder, Repo, loadProject, mupdf } = await engine();
+        const project = loadProject(root), result = await new Builder(project, new Repo(root)).build(tree, ['full']);
+        const document = mupdf.Document.openDocument(fs.readFileSync(result.pdf), 'application/pdf');
+        const pages: [number, number][] = [];
+        for (let i = 0; i < document.countPages(); i++) { const [x0, y0, x1, y1] = document.loadPage(i).getBounds(); pages.push([Math.round(x1 - x0), Math.round(y1 - y0)]); }
+        document.destroy?.();
+        const key = createHash('sha256').update(result.key + result.pdf).digest('hex').slice(0, 16);
+        if (this.builds.get(projectId) !== build) return;
+        Object.assign(build, { status: 'ready', key, pdf: result.pdf, root: result.root, sourceDir: project.source_dir || '', pages, builtAt: Date.now(), error: undefined });
+      } catch (error) {
+        if (this.builds.get(projectId) !== build) return;
+        const detail = error as { message?: string; details?: string[] };
+        Object.assign(build, { status: 'failed', error: [detail.message, ...(detail.details || [])].filter(Boolean).join('\n') || 'The manuscript could not be compiled.' });
+      }
+      this.emit('change', projectId);
+    })();
+    return build;
+  }
+
+  pdf(projectId: string, key: string) {
+    const build = this.builds.get(projectId);
+    if (!build?.pdf || build.key !== key) throw Object.assign(new Error('This manuscript preview is out of date. Refresh it and try again.'), { statusCode: 404 });
+    return build.pdf;
+  }
+
+  // A note keeps the text under the marked region and its LaTeX source, so it
+  // stays meaningful after the manuscript changes and the preview recompiles.
+  // A text selection arrives as one rectangle per line plus the selected text;
+  // a marked region arrives as one rectangle.
+  // Word places for the PDF view's selection layer, cached per build and page.
+  private wordCache = new Map<string, Awaited<ReturnType<typeof pdfWords>>>();
+  async words(projectId: string, key: string, page: number) {
+    const cacheKey = `${projectId}:${key}:${page}`, cached = this.wordCache.get(cacheKey);
+    if (cached) return cached;
+    const result = await pdfWords(this.pdf(projectId, key), page);
+    if (this.wordCache.size > 200) this.wordCache.delete(this.wordCache.keys().next().value!);
+    this.wordCache.set(cacheKey, result);
+    return result;
+  }
+
+  async locate(projectId: string, key: string, page: number, rect: Rect, rects: Rect[] = [], selected = '') {
+    const pdf = this.pdf(projectId, key), build = this.builds.get(projectId)!;
+    const { PdfDocument, containsCenter } = await engine();
+    const document = new PdfDocument(pdf);
+    try {
+      if (!Number.isInteger(page) || page < 0 || page >= document.length) throw Object.assign(new Error('That page is not part of the manuscript.'), { statusCode: 400 });
+      const current = document.page(page), [x0, y0, x1, y1] = current.bounds, width = x1 - x0, height = y1 - y0;
+      const toPage = (r: Rect) => [x0 + r[0] * width, y0 + r[1] * height, x0 + r[2] * width, y0 + r[3] * height];
+      const clips = (rects.length ? rects : [rect]).map(toPage);
+      const quote = (selected || clips.map(clip => current.text(clip)).join(' ')).replace(/\uFFFD/g, '').replace(/\s+/g, ' ').trim().slice(0, 600);
+      // Ask SyncTeX about the first and last marked character of every line, so
+      // the source range covers the whole selection rather than its first line.
+      const points: [number, number][] = [], centre = (r: number[]): [number, number] => [(r[0] + r[2]) / 2, (r[1] + r[3]) / 2];
+      let first: Anchor | null = null, last: Anchor | null = null;
+      for (const line of current.lines as { chars: { text: string; rect: number[] }[] }[]) {
+        const marked = line.chars.flatMap((c, index) => clips.some(clip => containsCenter(clip, c.rect)) ? [index] : []);
+        if (!marked.length) continue;
+        if (!first && !last) first = anchor(line.chars, marked[0], false);
+        last = anchor(line.chars, marked[marked.length - 1], true);
+        if (points.length >= 24) continue;
+        points.push(centre(line.chars[marked[0]].rect));
+        if (marked.length > 1) points.push(centre(line.chars[marked[marked.length - 1]].rect));
+      }
+      if (!points.length) points.push(...clips.slice(0, 12).map(centre));
+      const hits = (await Promise.all(points.map(([x, y]) => exec('synctex', ['edit', '-o', `${page + 1}:${(x - x0).toFixed(1)}:${(y - y0).toFixed(1)}:${pdf}`]).then(r => parseSynctex(r.stdout), () => null)))).filter(hit => hit !== null);
+      const files = new Map<string, { input: string; lines: number[] }>();
+      for (const hit of hits) {
+        const relative = path.relative(build.root || path.dirname(hit.input), hit.input);
+        const file = path.posix.join(build.sourceDir || '', (relative.startsWith('..') ? path.basename(hit.input) : relative).split(path.sep).join('/'));
+        files.set(file, { input: hit.input, lines: [...(files.get(file)?.lines || []), hit.line] });
+      }
+      const [file, found] = [...files].sort((a, b) => b[1].lines.length - a[1].lines.length)[0] || [];
+      if (!file || !found) return { quote, source: null };
+      const source = fs.existsSync(found.input) ? fs.readFileSync(found.input, 'utf8').split('\n') : [];
+      const lines = settleLines(source, [Math.min(...found.lines), Math.max(...found.lines)], first, last);
+      return { quote, source: { file, lines, excerpt: sourceExcerpt(found.input, lines) } };
+    } finally { document.close(); }
+  }
+
+}

package/src/server/paths.ts

@@ -0,0 +1,10 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+export const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+export const DATA = path.resolve(process.env.PAPILOT_DATA || path.join(ROOT, '.papilot'));
+export const ENGINE = path.resolve(process.env.PAPILOT_REVIEW_ENGINE || path.join(ROOT, 'vendor/latex-review'));
+export const PORT = Number(process.env.PAPILOT_PORT || 4317);
+export const PUBLIC_ORIGIN = process.env.PAPILOT_PUBLIC_ORIGIN || '';
+export const OWNER = process.env.PAPILOT_TAILSCALE_LOGIN || '';
+export const CODEX = process.env.PAPILOT_CODEX_BIN || (fs.existsSync(path.join(ROOT, 'node_modules/.bin/codex')) ? path.join(ROOT, 'node_modules/.bin/codex') : 'codex');

package/src/server/pdf.ts

@@ -0,0 +1,27 @@
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { ENGINE } from './paths.ts';
+import { reviewClient, taskRoute } from './review.ts';
+
+const pending = new Map<string, Promise<string>>();
+
+export async function fullPaperPdf(root: string, name: string, round: number, side: 'before' | 'after'): Promise<string> {
+  const key = JSON.stringify([root, name, round, side]);
+  const existing = pending.get(key);
+  if (existing) return existing;
+  const build = (async () => {
+    const client = await reviewClient(root);
+    const detail = await client.get<{ before: string; after: string }>(`${taskRoute(name)}/rounds/${round}`);
+    const [{ Builder }, { Repo }, { loadProject }] = await Promise.all([
+      import(pathToFileURL(path.join(ENGINE, 'src/core/build.ts')).href),
+      import(pathToFileURL(path.join(ENGINE, 'src/core/git.ts')).href),
+      import(pathToFileURL(path.join(ENGINE, 'src/core/config.ts')).href),
+    ]);
+    // A diff can use a partial build; explicitly compile the entire immutable
+    // round revision here. The engine reuses its normal full-build cache.
+    const result = await new Builder(loadProject(root), new Repo(root)).build(detail[side], ['full']);
+    return result.pdf as string;
+  })();
+  pending.set(key, build);
+  try { return await build; } finally { if (pending.get(key) === build) pending.delete(key); }
+}