@ryanyahya/opendoc 0.4.0

package/src/server/projects.ts

@@ -0,0 +1,187 @@
+import { constants, lstatSync, readFileSync, unlinkSync } from 'node:fs';
+import { lstat, mkdir, open, readFile, realpath, unlink } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { setTimeout } from 'node:timers/promises';
+import { readTheme } from './themes';
+import { emptyProjects, type Project, type ProjectsManifest } from '../shared/projects';
+import { atomicWrite } from './files';
+import { documentEntry, validId } from './render';
+
+export class ProjectError extends Error {
+  constructor(message: string, public status: 400 | 404 | 409 = 400) { super(message); this.name = 'ProjectError'; }
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === 'object' && !Array.isArray(value));
+}
+
+/** A terminated CLI must not leave all later project changes permanently busy. */
+function releaseDeadProjectLock(lock: string) {
+  try {
+    const before = lstatSync(lock);
+    if (!before.isFile() || before.isSymbolicLink() || before.size > 128) return;
+    let pid: number | undefined;
+    try { pid = (JSON.parse(readFileSync(lock, 'utf8')) as { pid?: number } | null)?.pid; }
+    catch (error) { if (!(error instanceof SyntaxError)) throw error; }
+    if (Number.isSafeInteger(pid) && pid! > 0) {
+      try { process.kill(pid!, 0); return; }
+      catch (error) { if ((error as NodeJS.ErrnoException).code !== 'ESRCH') return; }
+    } else if (Date.now() - before.mtimeMs < 30_000) return;
+    const current = lstatSync(lock);
+    if (current.dev === before.dev && current.ino === before.ino && current.mtimeMs === before.mtimeMs) unlinkSync(lock);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+  }
+}
+function projectName(value: unknown) {
+  if (typeof value !== 'string' || !value.trim() || value.trim().length > 120 || /[\u0000-\u001f\u007f\u2028\u2029]/u.test(value)) throw new ProjectError('Give the project a name of 120 characters or fewer, on one line.');
+  return value.trim();
+}
+export async function selectedTheme(root: string, value: unknown): Promise<string | null> {
+  if (value === null || value === undefined) return null;
+  if (typeof value !== 'string' || !validId(value)) throw new ProjectError('Choose an available theme.');
+  try { await readTheme(root, value); } catch { throw new ProjectError('Choose an available theme.'); }
+  return value;
+}
+
+function parseManifest(value: unknown): ProjectsManifest {
+  const invalid = () => new ProjectError('projects.json is invalid. Ask your agent to repair it; no project data was replaced.');
+  if (!record(value) || value.version !== 1 || !Array.isArray(value.projects) || !record(value.assignments) || Object.keys(value).some(key => !['version', 'projects', 'assignments', 'names', 'formats'].includes(key))) throw invalid();
+  const ids = new Set<string>();
+  const projects = value.projects.map((entry): Project => {
+    if (!record(entry) || typeof entry.id !== 'string' || !validId(entry.id) || entry.id.length > 80 || ids.has(entry.id) || Object.keys(entry).some(key => !['id', 'name', 'defaultTheme'].includes(key))) throw invalid();
+    ids.add(entry.id);
+    // Keep a removed custom theme readable. Creation will ask for an available replacement.
+    if (entry.defaultTheme !== null && (typeof entry.defaultTheme !== 'string' || !entry.defaultTheme.trim())) throw invalid();
+    return { id: entry.id, name: projectName(entry.name), defaultTheme: entry.defaultTheme as string | null };
+  });
+  const assignments: Record<string, string> = {};
+  for (const [id, projectId] of Object.entries(value.assignments)) {
+    if (!validId(id) || id.length > 80 || typeof projectId !== 'string' || !ids.has(projectId)) throw invalid();
+    assignments[id] = projectId;
+  }
+  const names: Record<string, string> = {};
+  if (value.names !== undefined) {
+    if (!record(value.names)) throw invalid();
+    for (const [id, name] of Object.entries(value.names)) {
+      if (!validId(id) || id.length > 80) throw invalid();
+      names[id] = documentDisplayName(name);
+    }
+  }
+  const formats: NonNullable<ProjectsManifest['formats']> = {};
+  if (value.formats !== undefined) {
+    if (!record(value.formats)) throw invalid();
+    for (const [id, format] of Object.entries(value.formats)) {
+      if (!validId(id) || id.length > 80 || !['document', 'presentation'].includes(format as string)) throw invalid();
+      formats[id] = format as 'document' | 'presentation';
+    }
+  }
+  return { version: 1, projects, assignments, ...(value.names === undefined ? {} : { names }), ...(value.formats === undefined ? {} : { formats }) };
+}
+
+export function documentDisplayName(value: unknown) {
+  if (typeof value !== 'string' || !value.trim() || value.trim().length > 160 || /[\u0000-\u001f\u007f\u2028\u2029]/u.test(value)) throw new ProjectError('Give the document a name of 160 characters or fewer, on one line.');
+  return value.trim();
+}
+
+async function manifestFile(root: string) {
+  const file = resolve(await realpath(root), 'projects.json');
+  const info = await lstat(file).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+  if (info && (!info.isFile() || info.isSymbolicLink() || info.size > 1_000_000)) throw new ProjectError('projects.json must be a regular local file smaller than 1 MB.');
+  return { file, exists: Boolean(info) };
+}
+
+export async function readProjects(root: string): Promise<ProjectsManifest> {
+  const { file, exists } = await manifestFile(root);
+  if (!exists) return emptyProjects();
+  try { return parseManifest(JSON.parse(await readFile(file, 'utf8'))); }
+  catch (error) {
+    if (error instanceof ProjectError) throw error;
+    throw new ProjectError('Could not read projects.json. Ask your agent to repair it; no project data was replaced.');
+  }
+}
+
+/** Serialize browser and CLI changes, including document publication and its assignment. */
+export async function withProjects<T>(root: string, change: (manifest: ProjectsManifest, save: () => Promise<void>) => Promise<T>): Promise<T> {
+  const workspace = await realpath(root);
+  const runtime = resolve(workspace, '.opendoc');
+  await mkdir(runtime, { recursive: true });
+  const lock = resolve(runtime, 'projects.lock');
+  let handle;
+  const started = Date.now();
+  while (!handle) {
+    try { handle = await open(lock, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== 'EEXIST') throw error;
+      releaseDeadProjectLock(lock);
+      if (Date.now() - started > 5000) throw new ProjectError('Project files are busy. Try again when the other operation finishes.', 409);
+      await setTimeout(25);
+    }
+  }
+  try {
+    await handle.writeFile(JSON.stringify({ pid: process.pid }));
+    const manifest = await readProjects(workspace);
+    return await change(manifest, async () => {
+      const { file } = await manifestFile(workspace);
+      await atomicWrite(file, `${JSON.stringify(parseManifest(manifest), null, 2)}\n`);
+    });
+  } finally { await handle.close(); await unlink(lock); }
+}
+
+export function requireProject(manifest: ProjectsManifest, id: unknown): Project {
+  if (typeof id !== 'string' || !validId(id)) throw new ProjectError('Choose a project before creating a document.');
+  const project = manifest.projects.find(project => project.id === id);
+  if (!project) throw new ProjectError('This project no longer exists. Choose another project.', 404);
+  return project;
+}
+
+export async function createProject(root: string, input: unknown): Promise<Project> {
+  if (!record(input) || Object.keys(input).some(key => !['name', 'id', 'defaultTheme'].includes(key))) throw new ProjectError('Provide a project name and an optional default theme.');
+  const name = projectName(input.name);
+  const defaultTheme = await selectedTheme(root, input.defaultTheme);
+  const derived = name.normalize('NFKD').replace(/\p{M}/gu, '').toLowerCase().replace(/[’']/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '').slice(0, 80).replace(/-$/, '') || 'new-project';
+  const id = input.id ?? derived;
+  if (typeof id !== 'string' || !validId(id) || id.length > 80) throw new ProjectError('Use a project ID with lowercase letters, numbers, and single hyphens, up to 80 characters.');
+  return withProjects(root, async (manifest, save) => {
+    if (manifest.projects.some(project => project.id === id || project.name.toLowerCase() === name.toLowerCase())) throw new ProjectError('A project with this name or ID already exists. Choose another name.', 409);
+    const project = { id, name, defaultTheme };
+    manifest.projects.push(project); await save(); return project;
+  });
+}
+
+export async function updateProject(root: string, id: string, input: unknown): Promise<Project> {
+  if (!record(input) || !Object.keys(input).length || Object.keys(input).some(key => !['name', 'defaultTheme'].includes(key))) throw new ProjectError('Provide a project name or default theme.');
+  return withProjects(root, async (manifest, save) => {
+    const project = requireProject(manifest, id);
+    if (input.name !== undefined) {
+      const name = projectName(input.name);
+      if (manifest.projects.some(other => other.id !== id && other.name.toLowerCase() === name.toLowerCase())) throw new ProjectError('A project with this name already exists.', 409);
+      project.name = name;
+    }
+    if (Object.hasOwn(input, 'defaultTheme')) project.defaultTheme = await selectedTheme(root, input.defaultTheme);
+    await save(); return project;
+  });
+}
+
+export async function assignProject(root: string, documentId: string, projectId: unknown) {
+  return withProjects(root, async (manifest, save) => {
+    const project = requireProject(manifest, projectId);
+    await documentEntry(root, documentId);
+    manifest.assignments[documentId] = project.id;
+    await save(); return { id: documentId, projectId: project.id };
+  });
+}
+
+export async function deleteProject(root: string, id: string) {
+  return withProjects(root, async (manifest, save) => {
+    requireProject(manifest, id);
+    for (const [documentId, projectId] of Object.entries(manifest.assignments)) {
+      if (projectId !== id) continue;
+      const exists = await lstat(resolve(root, 'documents', documentId)).catch(error => { if (error.code === 'ENOENT') return null; throw error; });
+      if (exists) throw new ProjectError('Move this project’s documents to another project before deleting it.', 409);
+      delete manifest.assignments[documentId];
+    }
+    manifest.projects = manifest.projects.filter(project => project.id !== id);
+    await save();
+  });
+}

package/src/server/render-error.ts

@@ -0,0 +1,9 @@
+import type { ReviewIssue } from '../shared/types';
+
+/** Preserve actionable layout diagnostics across the isolated render process. */
+export class RenderFailure extends Error {
+  constructor(message: string, readonly issues: ReviewIssue[] = []) {
+    super(message);
+    this.name = 'RenderFailure';
+  }
+}

package/src/server/render-source.ts

@@ -0,0 +1,24 @@
+import { writeFile, unlink } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { randomUUID } from 'node:crypto';
+import { resolveAllSources } from '../rendering/resolve-sources';
+import { renderPdfWithLayout } from '@formepdf/core';
+import type { FormeDocument } from '@formepdf/react';
+import { bundleSourceOverrides, type SourceOverride } from './source-overrides';
+
+/** One serialization and asset resolution supplies both the PDF and editable exports. */
+export async function renderDocumentSource(source: string, entry: string, overrides = new Map<string, SourceOverride>()) {
+  const directory = dirname(entry);
+  const code = await bundleSourceOverrides(`${source}\nexport { serialize as __serialize } from '@formepdf/react';`, entry, overrides);
+  const temporary = resolve(directory, `.forme-render-${randomUUID()}.mjs`);
+  await writeFile(temporary, code, { flag: 'wx' });
+  let doc: FormeDocument;
+  try {
+    const module = await import(pathToFileURL(temporary).href);
+    doc = module.__serialize(module.default());
+  } finally { await unlink(temporary); }
+  await resolveAllSources(doc as unknown as Record<string, unknown>, directory);
+  const result = await renderPdfWithLayout(JSON.stringify(doc));
+  return { ...result, doc, warnings: [] as string[] };
+}

package/src/server/render.ts

@@ -0,0 +1,48 @@
+import { fork } from 'node:child_process';
+import { mkdir, readFile, realpath, rm } from 'node:fs/promises';
+import { resolve, relative, sep } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { RenderFailure } from './render-error';
+import type { RenderArtifact, ReviewIssue } from '../shared/types';
+import type { SourceOverride } from './source-overrides';
+import { runtimeResolve, runtimeSource } from '../runtime/paths';
+
+export function validId(id: string) { return /^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(id); }
+export async function documentEntry(root: string, id: string) {
+  if (!validId(id)) throw new Error('Invalid document ID.');
+  const docsRoot = await realpath(resolve(root, 'documents'));
+  const path = await realpath(resolve(docsRoot, id, 'index.tsx'));
+  const rel = relative(docsRoot, path);
+  if (rel.startsWith(`..${sep}`) || rel === '..' || resolve(docsRoot, rel) !== path) throw new Error('Document path is outside this workspace.');
+  return path;
+}
+
+export async function renderOnce(root: string, id: string, timeoutMs = 30_000, sourceOverrides?: SourceOverride[]): Promise<{ artifact: RenderArtifact; directory: string }> {
+  const entry = await documentEntry(root, id);
+  return renderEntry(root, entry, id, timeoutMs, sourceOverrides);
+}
+
+/** Render another workspace entry through the same isolated PDF worker. */
+export async function renderEntry(root: string, entry: string, label: string, timeoutMs = 30_000, sourceOverrides?: SourceOverride[]): Promise<{ artifact: RenderArtifact; directory: string }> {
+  const directory = resolve(root, '.opendoc/renders', `${label}-${randomUUID()}`);
+  await mkdir(directory, { recursive: true });
+  try {
+    await new Promise<void>((accept, reject) => {
+      const child = fork(runtimeSource('server/worker.ts'), [entry, directory, ...(sourceOverrides ? ['--source-overrides'] : [])], {
+        cwd: root, execArgv: ['--import', runtimeResolve('tsx')], stdio: ['ignore', 'ignore', 'pipe', 'ipc'],
+      });
+      let stderr = '', failure: string | undefined, issues: ReviewIssue[] = [], signaled = false;
+      child.stderr?.on('data', data => { stderr = (stderr + data.toString()).slice(-8000); });
+      const timer = setTimeout(() => { failure = `Rendering timed out after ${timeoutMs / 1000} seconds.`; child.kill('SIGKILL'); }, timeoutMs);
+      child.on('message', (message: { ok: boolean; error?: string; issues?: ReviewIssue[] }) => { signaled = message.ok; if (!message.ok) { failure = message.error; issues = message.issues ?? []; } });
+      child.on('error', error => { clearTimeout(timer); reject(error); });
+      child.on('exit', code => {
+        clearTimeout(timer);
+        if (code === 0 && signaled && !failure) accept();
+        else reject(new RenderFailure(failure || stderr || `Render worker exited unexpectedly (${code ?? 'signal'}).`, issues));
+      });
+      if (sourceOverrides) child.send({ sourceOverrides });
+    });
+    return { artifact: JSON.parse(await readFile(resolve(directory, 'artifact.json'), 'utf8')), directory };
+  } catch (error) { await rm(directory, { recursive: true, force: true }); throw error; }
+}

package/src/server/review-cli.ts

@@ -0,0 +1,40 @@
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { parseArgs } from 'node:util';
+import { reviewTarget, type ReviewTarget } from './review';
+import { validId } from './render';
+
+export const reviewUsage = 'Usage: npx opendoc review <document-id> [--json]\n       npx opendoc review --theme <id> [--json]\n       npx opendoc review --template <id> [--json]';
+
+export function parseReviewArgs(args: string[]) {
+  const { values, positionals, tokens } = parseArgs({ args: args[0] === '--' ? args.slice(1) : args, allowPositionals: true, tokens: true, options: {
+    json: { type: 'boolean' }, help: { type: 'boolean', short: 'h' }, theme: { type: 'string' }, template: { type: 'string' },
+  } });
+  if (values.help) return { help: true as const, json: values.json };
+  if (positionals.length + tokens.filter(token => token.kind === 'option' && (token.name === 'theme' || token.name === 'template')).length !== 1) throw new Error(reviewUsage);
+  const target: ReviewTarget = values.theme !== undefined ? { kind: 'theme', id: values.theme } : values.template !== undefined ? { kind: 'template', id: values.template } : { kind: 'document', id: positionals[0] };
+  if (!validId(target.id)) throw new Error(reviewUsage);
+  return { help: false as const, json: values.json, target };
+}
+
+export async function runReviewCli(args: string[], root = process.cwd()): Promise<void> {
+  const options = parseReviewArgs(args);
+  if (options.help) { console.log(options.json ? JSON.stringify({ usage: reviewUsage }, null, 2) : reviewUsage); return; }
+  const result = await reviewTarget(root, options.target);
+  if (options.json) console.log(JSON.stringify(result, null, 2));
+  else if (result.status === 'ready') {
+    console.log(`Prepared ${result.pageCount} pages for review: ${result.outputs.review}\nPDF: ${result.outputs.pdf}\nInspect every page image and check the content before delivery; visual and factual review are still required.`);
+    if (result.warning) console.error(result.warning);
+  } else console.error(`${result.id}: ${result.error}\n${result.previousOutputRetained ? 'Previous review artifacts retained.' : 'No review artifacts were published.'}`);
+  if (result.status === 'error') process.exitCode = 1;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+  try { await runReviewCli(process.argv.slice(2)); }
+  catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (process.argv.includes('--json')) console.log(JSON.stringify({ status: 'error', error: message }, null, 2));
+    else console.error(message);
+    process.exitCode = 1;
+  }
+}

package/src/server/review.ts

@@ -0,0 +1,161 @@
+import { lstat, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { lstatSync, readdirSync, renameSync } from 'node:fs';
+import { createHash, randomUUID } from 'node:crypto';
+import { dirname, resolve, sep } from 'node:path';
+import { createCanvas } from '@napi-rs/canvas';
+import { getDocument } from 'pdfjs-dist/legacy/build/pdf.mjs';
+import type { BlockInfo, DocumentFormat, RenderArtifact, ReviewIssue } from '../shared/types';
+import { runtimeResolve } from '../runtime/paths';
+import { captureEntryExportInputs, captureExportInputs } from './export-inputs';
+import { ExportChangedError, outputFolder } from './export-file';
+import { renderOnce, validId } from './render';
+import { RenderFailure } from './render-error';
+import { ThemeCatalog, themeFile } from './themes';
+import { TemplateCatalog, templateFile } from './templates';
+
+export interface ReviewTarget { kind: 'document' | 'theme' | 'template'; id: string }
+export interface ReviewPage {
+  page: number; width: number; height: number; image: string; text: string;
+  blockIds: string[]; issues: ReviewIssue[];
+}
+export interface ReviewReport extends ReviewTarget {
+  version: 1; status: 'ready'; hash: string; format: DocumentFormat; renderedAt: string; pageCount: number;
+  visualReview: 'required'; factualReview: 'required';
+  outputs: { directory: string; pdf: string; text: string; review: string };
+  pages: ReviewPage[]; issues: ReviewIssue[]; blocks: BlockInfo[]; warning?: string;
+}
+export interface ReviewError extends ReviewTarget {
+  status: 'error'; error: string; issues: ReviewIssue[]; updated: false; previousOutputRetained: boolean;
+}
+export type ReviewResult = ReviewReport | ReviewError;
+const collections = { document: 'documents', theme: 'themes', template: 'templates' } as const;
+
+/** Prepare one render for review. Neither this path nor the catalog paths inspect GUI state. */
+export async function reviewTarget(root: string, target: ReviewTarget, options: { renderTimeoutMs?: number } = {}): Promise<ReviewResult> {
+  const { id, kind } = target;
+  if (!validId(id) || !Object.hasOwn(collections, kind)) throw new Error('Choose a valid document, theme, or template ID.');
+  let cleanup: (() => Promise<void>) | undefined;
+  try {
+    let artifact: RenderArtifact, bytes: Uint8Array, unchanged: () => boolean;
+    if (kind === 'document') {
+      unchanged = await captureExportInputs(root, id);
+      const rendered = await renderOnce(root, id, options.renderTimeoutMs);
+      cleanup = () => rm(rendered.directory, { recursive: true, force: true });
+      artifact = rendered.artifact;
+      bytes = await readFile(resolve(rendered.directory, 'document.pdf'));
+    } else {
+      const entry = kind === 'theme' ? await themeFile(root, id, 'preview.tsx') : await templateFile(root, id, 'preview.tsx');
+      unchanged = await captureEntryExportInputs(root, entry);
+      // Catalogs validate their guides, definitions, theme identities, and format before returning a specimen.
+      const catalog = kind === 'theme' ? new ThemeCatalog(root) : new TemplateCatalog(root);
+      cleanup = () => catalog.close();
+      const preview = await catalog.preview(id);
+      if (!preview.artifact) throw new RenderFailure(preview.error ?? 'Specimen rendering failed.', preview.issues);
+      artifact = preview.artifact;
+      bytes = await catalog.pdf(id, artifact.hash);
+    }
+    if (!unchanged()) throw new ExportChangedError();
+    const report = await publishReview(root, target, artifact, bytes, unchanged);
+    try { await cleanup?.(); cleanup = undefined; }
+    catch (error) { report.warning = `Review artifacts were saved, but temporary render cleanup failed: ${message(error)}`; }
+    return report;
+  } catch (error) {
+    const prior = resolve(root, 'output/reviews', collections[kind], id, 'review.json');
+    const previousOutputRetained = await lstat(prior).then(info => info.isFile() && !info.isSymbolicLink(), () => false);
+    return { ...target, status: 'error', error: message(error), issues: error instanceof RenderFailure ? error.issues : [], updated: false, previousOutputRetained };
+  } finally { await cleanup?.().catch(() => {}); }
+}
+
+function message(error: unknown) { return error instanceof Error ? error.message : String(error); }
+
+/** Review files are user-accessible while a new set is prepared; preserve concurrent additions and edits. */
+function reviewFilesStamp(directory: string) {
+  return JSON.stringify(readdirSync(directory).sort().map(name => {
+    const info = lstatSync(resolve(directory, name), { bigint: true });
+    if (!info.isFile() || info.isSymbolicLink() || !/^(?:document\.(?:pdf|txt)|review\.json|page-\d{3,}\.(?:png|txt))$/.test(name)) throw new Error('The review destination contains other files. Move them before creating this review.');
+    return [name, `${info.dev}:${info.ino}:${info.mode}:${info.size}:${info.mtimeNs}:${info.ctimeNs}`];
+  }));
+}
+
+/** Rasterize and extract text from the exact PDF bytes, then publish the complete set together. */
+export async function publishReview(root: string, target: ReviewTarget, artifact: RenderArtifact, bytes: Uint8Array, isCurrent: () => boolean): Promise<ReviewReport> {
+  if (!validId(target.id) || !Object.hasOwn(collections, target.kind)) throw new Error('Invalid review target.');
+  if (createHash('sha256').update(bytes).digest('hex') !== artifact.hash) throw new Error('Review PDF bytes do not match their render artifact.');
+  const folder = await outputFolder(root, ['reviews', collections[target.kind]]);
+  const parents = [resolve(root, 'output'), resolve(root, 'output/reviews'), folder].map(path => ({ path, info: lstatSync(path) }));
+  const directory = resolve(folder, target.id);
+  const previous = await lstat(directory).catch(error => { if (error.code === 'ENOENT') return undefined; throw error; });
+  let previousFiles: string | undefined;
+  if (previous) {
+    if (!previous.isDirectory() || previous.isSymbolicLink()) throw new Error('The review destination must be a regular local directory.');
+    previousFiles = reviewFilesStamp(directory);
+    const manifest = resolve(directory, 'review.json');
+    const manifestInfo = await lstat(manifest).catch(() => undefined);
+    const prior = manifestInfo?.isFile() && !manifestInfo.isSymbolicLink() ? await readFile(manifest, 'utf8').then(JSON.parse).catch(() => undefined) : undefined;
+    if (prior?.version !== 1 || prior.id !== target.id || prior.kind !== target.kind) throw new Error('The review destination contains other files. Move them before creating this review.');
+  }
+  const temporary = resolve(folder, `.${target.id}-${randomUUID()}.tmp`);
+  const backup = resolve(folder, `.${target.id}-${randomUUID()}.previous`);
+  await mkdir(temporary);
+  let published = false, retained = false;
+  const report: ReviewReport = {
+    version: 1, status: 'ready', ...target, hash: artifact.hash, format: artifact.format ?? 'document', renderedAt: artifact.renderedAt,
+    pageCount: artifact.pages.length, visualReview: 'required', factualReview: 'required',
+    outputs: { directory, pdf: resolve(directory, 'document.pdf'), text: resolve(directory, 'document.txt'), review: resolve(directory, 'review.json') },
+    pages: [], issues: artifact.issues ?? [], blocks: Object.values(artifact.blocks),
+  };
+  try {
+    const pdfjs = dirname(runtimeResolve('pdfjs-dist/package.json'));
+    const loading = getDocument({
+      data: new Uint8Array(bytes), useSystemFonts: false, verbosity: 0,
+      standardFontDataUrl: resolve(pdfjs, 'standard_fonts') + sep,
+      cMapUrl: resolve(pdfjs, 'cmaps') + sep, cMapPacked: true, wasmUrl: resolve(pdfjs, 'wasm') + sep,
+    });
+    const texts: string[] = [];
+    try {
+      const pdf = await loading.promise;
+      if (pdf.numPages !== artifact.pages.length) throw new Error('The PDF page count does not match its render artifact.');
+      for (let number = 1; number <= pdf.numPages; number++) {
+        const page = await pdf.getPage(number);
+        const name = `page-${String(number).padStart(3, '0')}`;
+        const content = await page.getTextContent();
+        const text = content.items.map(item => 'str' in item ? item.str + (item.hasEOL ? '\n' : ' ') : '').join('').trim() + '\n';
+        const viewport = page.getViewport({ scale: 1.5 });
+        const canvas = createCanvas(Math.ceil(viewport.width), Math.ceil(viewport.height));
+        try {
+          await page.render({ canvas: canvas as unknown as HTMLCanvasElement, canvasContext: canvas.getContext('2d') as unknown as CanvasRenderingContext2D, viewport }).promise;
+          await writeFile(resolve(temporary, `${name}.png`), await canvas.encode('png'));
+        } finally { canvas.width = 0; canvas.height = 0; }
+        await writeFile(resolve(temporary, `${name}.txt`), text);
+        texts.push(text);
+        const info = artifact.pages[number - 1];
+        report.pages.push({ page: number, width: info.width, height: info.height, image: resolve(directory, `${name}.png`), text: resolve(directory, `${name}.txt`), blockIds: [...new Set(info.fragments.map(fragment => fragment.id))], issues: report.issues.filter(issue => issue.page === number) });
+        page.cleanup();
+      }
+    } finally { await loading.destroy(); }
+    await writeFile(resolve(temporary, 'document.pdf'), bytes);
+    await writeFile(resolve(temporary, 'document.txt'), texts.join('\n\f\n'));
+    await writeFile(resolve(temporary, 'review.json'), JSON.stringify(report, null, 2) + '\n');
+    // No event-loop turn may separate freshness and publication. A failed rename restores the old set.
+    if (!isCurrent()) throw new ExportChangedError();
+    for (const { path, info: expected } of parents) {
+      const info = lstatSync(path);
+      if (!info.isDirectory() || info.isSymbolicLink() || info.ino !== expected.ino || info.dev !== expected.dev) throw new Error('The review output folder changed during preparation.');
+    }
+    const current = (() => { try { return lstatSync(directory); } catch (error) { if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined; throw error; } })();
+    if (current?.ino !== previous?.ino || current?.dev !== previous?.dev) throw new Error('The review destination changed during preparation. Retry after the other review finishes.');
+    if (previousFiles !== undefined) {
+      let unchanged = false;
+      try { unchanged = reviewFilesStamp(directory) === previousFiles; } catch { /* A new file or link is a concurrent edit too. */ }
+      if (!unchanged) throw new Error('The review files changed during preparation. Your existing files were retained; retry after edits finish.');
+    }
+    if (previous) { renameSync(directory, backup); retained = true; }
+    try { renameSync(temporary, directory); published = true; }
+    catch (error) { if (retained) { renameSync(backup, directory); retained = false; } throw error; }
+    if (retained) {
+      try { await rm(backup, { recursive: true, force: true }); retained = false; }
+      catch (error) { report.warning = `Review artifacts were saved; the prior review remains at ${backup}: ${message(error)}`; }
+    }
+    return report;
+  } finally { if (!published) await rm(temporary, { recursive: true, force: true }); }
+}

package/src/server/selection.ts

@@ -0,0 +1,23 @@
+import type { DocumentSelection } from '../shared/selection';
+
+/** Keep observed UI context small and typed; it is not an instruction to the agent. */
+export function readSelection(input: unknown, blockId: string | null): DocumentSelection | null {
+  if (input == null) return null;
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('Invalid selection.');
+  const value = input as DocumentSelection;
+  if (!blockId || value.blockId !== blockId) throw new Error('The selection does not match the active block.');
+  // The user can scroll elsewhere while keeping a phrase selected.
+  if (!Number.isInteger(value.page) || value.page < 1) throw new Error('Invalid selection page.');
+  if (value.targetId !== undefined && (typeof value.targetId !== 'string' || !value.targetId || value.targetId.length > 1000)) throw new Error('Invalid selected field.');
+  if ((value.start !== undefined || value.end !== undefined) && (!value.targetId || !Number.isInteger(value.start) || !Number.isInteger(value.end) || value.start! < 0 || value.end! <= value.start!)) throw new Error('Invalid selected text range.');
+  if (value.quote !== undefined && (typeof value.quote !== 'string' || value.quote.length > 8000)) throw new Error('Selected text is too long. Select a shorter passage.');
+  if (value.renderHash !== undefined && (typeof value.renderHash !== 'string' || value.renderHash.length > 128)) throw new Error('Invalid selection version.');
+  if (value.revision !== undefined && (!Number.isInteger(value.revision) || value.revision < 0)) throw new Error('Invalid selection revision.');
+  return { blockId, page: value.page,
+    ...(value.targetId === undefined ? {} : { targetId: value.targetId }),
+    ...(value.start === undefined ? {} : { start: value.start, end: value.end }),
+    ...(value.quote === undefined ? {} : { quote: value.quote }),
+    ...(value.renderHash === undefined ? {} : { renderHash: value.renderHash }),
+    ...(value.revision === undefined ? {} : { revision: value.revision }),
+  };
+}

package/src/server/source-overrides.ts

@@ -0,0 +1,97 @@
+import { build, type Plugin } from 'esbuild';
+import { dirname } from 'node:path';
+import { realpath } from 'node:fs/promises';
+import { isBuiltin } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import type { TextSourceValue } from '../shared/selection';
+import { textSourceBindingId } from './text-source';
+import { runtimeResolve, runtimeSource } from '../runtime/paths';
+
+const authoringModules: Record<string, string> = {
+  opendoc: 'document/index.tsx',
+  'opendoc/themes': 'themes/index.ts',
+  'opendoc/assets': 'assets/index.ts',
+  'opendoc/template': 'template/index.ts',
+};
+
+/** Keep the authoring runtime in one bundle and installed dependencies in one Node instance. */
+export function authoringResolutionPlugin(): Plugin {
+  return { name: 'opendoc-installed-runtime', setup(builder) {
+    builder.onResolve({ filter: /^[^./]/ }, args => {
+      if (authoringModules[args.path]) return { path: runtimeSource(authoringModules[args.path]) };
+      if (isBuiltin(args.path)) return { path: args.path, external: true };
+      if (args.path.startsWith('file:')) return { path: args.path, external: true };
+      try { return { path: pathToFileURL(runtimeResolve(args.path)).href, external: true }; }
+      catch (error) {
+        // Additional packages authored in a workspace still use esbuild's normal resolution.
+        if (['MODULE_NOT_FOUND', 'ERR_MODULE_NOT_FOUND'].includes((error as NodeJS.ErrnoException).code ?? '')) return undefined;
+        throw error;
+      }
+    });
+  } };
+}
+
+/** Trusted candidates assembled from renderer-issued bindings, never client paths. */
+export interface SourceOverride {
+  file: string;
+  contents: string;
+  originalDigest: string;
+  replacements: { start: number; end: number; tokenLength: number; value: string }[];
+}
+
+/** Keep the authored identity while candidate tokens and all following offsets move. */
+export function originalBinding(source: TextSourceValue | undefined, override: SourceOverride | undefined) {
+  if (!source || !override) return source;
+  let delta = 0;
+  for (const replacement of override.replacements) {
+    const start = replacement.start + delta, end = start + replacement.tokenLength;
+    if (source.start >= start && source.end <= end && source.value === replacement.value) {
+      return { ...source, bindingId: textSourceBindingId(source.file, override.originalDigest, replacement.start, replacement.end) };
+    }
+    if (source.end <= start) break;
+    if (source.start < end) return { ...source, bindingId: undefined };
+    delta += replacement.tokenLength - (replacement.end - replacement.start);
+  }
+  return { ...source, bindingId: textSourceBindingId(source.file, override.originalDigest, source.start - delta, source.end - delta) };
+}
+
+/**
+ * Bundle authored code once, preserving Forme's JSX source-map contract for
+ * original sources and drafts. Installed packages never depend on workspace hoisting.
+ */
+export async function bundleSourceOverrides(source: string, entry: string, overrides: Map<string, SourceOverride>) {
+  const used = new Set<string>();
+  const result = await build({
+    stdin: { contents: source, resolveDir: dirname(entry), sourcefile: '.opendoc-entry.tsx', loader: 'tsx' },
+    absWorkingDir: dirname(entry), bundle: true, write: false, format: 'esm', platform: 'node', target: 'node20',
+    jsx: 'automatic', jsxDev: true, jsxImportSource: 'react',
+    logLevel: 'silent', plugins: [{ name: 'opendoc-draft-sources', setup(builder) {
+      builder.onResolve({ filter: /^(?:react|opendoc)\/jsx-dev-runtime$/ }, () => ({ path: 'opendoc-jsx-source', namespace: 'opendoc-jsx-source' }));
+      builder.onLoad({ filter: /.*/, namespace: 'opendoc-jsx-source' }, () => ({
+        loader: 'js', resolveDir: dirname(entry), contents: `
+          import { jsx, Fragment } from 'react/jsx-runtime';
+          import { resolve, isAbsolute } from 'node:path';
+          export { Fragment };
+          globalThis.__formeSourceMap ??= new WeakMap();
+          export function jsxDEV(type, props, key, staticChildren, source) {
+            const element = jsx(type, props, key);
+            if (source?.fileName) globalThis.__formeSourceMap.set(element, {
+              file: isAbsolute(source.fileName) ? source.fileName : resolve(${JSON.stringify(dirname(entry))}, source.fileName),
+              line: source.lineNumber, column: source.columnNumber,
+            });
+            return element;
+          }
+        `,
+      }));
+      builder.onLoad({ filter: /\.(?:tsx?|json)$/ }, async args => {
+        const path = await realpath(args.path);
+        const override = overrides.get(path);
+        if (!override) return undefined;
+        used.add(path);
+        return { contents: override.contents, loader: path.endsWith('.json') ? 'json' : path.endsWith('.tsx') ? 'tsx' : 'ts', resolveDir: dirname(path) };
+      });
+    } }, authoringResolutionPlugin()],
+  }).catch(error => { throw new Error(`Build error: ${error instanceof Error ? error.message : String(error)}`, { cause: error }); });
+  if ([...overrides.keys()].some(file => !used.has(file))) throw new Error('An edited source is no longer used by this document. Refresh the document before saving.');
+  return result.outputFiles[0].text;
+}