mixdog 1.3.0 → 1.3.2

package/src/runtime/memory/lib/embedding-model-files.mjs

@@ -1,10 +1,12 @@
 // Embedding model files in the transformers.js cache layout
 // (<cache>/<model id>/<path>), so copies that library already downloaded are
 // reused; a missing file is fetched from the Hugging Face Hub once.
-import { createWriteStream, existsSync, mkdirSync, renameSync, rmSync } from 'node:fs';
+import { createWriteStream, existsSync, mkdirSync, readFileSync, renameSync, rmSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
+import { parseJsonText } from '../../shared/atomic-file.mjs';
+import { fileHasData } from '../../shared/file-has-data.mjs';
 
 const HUB = 'https://huggingface.co';
 
@@ -17,7 +19,8 @@ async function download(modelId, file, target, { optional = false } = {}) {
   mkdirSync(dirname(target), { recursive: true });
   const partial = `${target}.${process.pid}.part`;
   try {
-    await pipeline(Readable.fromWeb(res.body), createWriteStream(partial));
+    // flush: fsync before close, so the renamed file cannot be all NUL after a crash.
+    await pipeline(Readable.fromWeb(res.body), createWriteStream(partial, { flush: true }));
     renameSync(partial, target);
   } catch (error) {
     rmSync(partial, { force: true });
@@ -26,19 +29,39 @@ async function download(modelId, file, target, { optional = false } = {}) {
   return true;
 }
 
-/** Local path of `file`, downloading it first when absent. */
+// A cached file that holds no data (empty, NUL-filled by a crash) or, for
+// JSON, does not parse is not present: it is fetched again.
+function cachedFileUsable(target) {
+  if (!fileHasData(target)) return false;
+  if (!target.endsWith('.json')) return true;
+  try {
+    parseJsonText(readFileSync(target, 'utf8'));
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Local path of `file`, downloading it first when absent or damaged. */
 export async function ensureModelFile(cacheDir, modelId, file) {
   const target = join(cacheDir, ...modelId.split('/'), ...file.split('/'));
-  if (!existsSync(target)) await download(modelId, file, target);
+  if (!cachedFileUsable(target)) await download(modelId, file, target);
   return target;
 }
 
 /** Local path of an ONNX graph; a graph published with external weights gets them alongside. */
 export async function ensureModelGraph(cacheDir, modelId, file) {
   const target = join(cacheDir, ...modelId.split('/'), ...file.split('/'));
-  if (!existsSync(target)) {
-    await download(modelId, file, target);
-    await download(modelId, `${file}_data`, `${target}_data`, { optional: true });
+  const weights = `${target}_data`;
+  const graphPresent = fileHasData(target);
+  // The weights are checked on their own: an external-weights file a crash
+  // left empty or NUL-filled is fetched again even when the graph is intact.
+  // They are fetched before the graph, so a cached graph implies its weights
+  // finished downloading; a weights file that is absent stays absent (graphs
+  // without external data have none).
+  if (!graphPresent || (existsSync(weights) && !fileHasData(weights))) {
+    await download(modelId, `${file}_data`, weights, { optional: true });
   }
+  if (!graphPresent) await download(modelId, file, target);
   return target;
 }

package/src/runtime/memory/lib/ingest/transcript-tail.mjs

@@ -2,10 +2,10 @@
 // One incremental read of a transcript file: the bytes past the persisted
 // offset, split into complete JSONL lines, stored as conversation rows. The
 // persisted boundary only advances past lines that were fully consumed (parsed
-// + inserted or intentionally skipped); a malformed trailing line (mid-write
-// partial) or a transient insert error stops the walk and leaves the boundary
-// untouched so the next sweep retries from the same position instead of
-// silently consuming the line forever.
+// + inserted or intentionally skipped); a transient insert error stops the walk
+// and leaves the boundary untouched so the next sweep retries from the same
+// position instead of silently consuming the line forever. A complete line
+// that is not JSON (crash damage) is skipped, never a permanent stop.
 import fs from 'node:fs';
 import path from 'node:path';
 import { cwdFromTranscriptPath, transcriptRowFromLine } from './transcript-rows.mjs';
@@ -73,8 +73,12 @@ export async function ingestTranscriptTail({ db, transcriptPath, cwd, offsets, r
   const boundary = { bytes: tail.bytes, lineIndex: tail.lineIndex, generation: tail.generation };
   let index = tail.lineIndex;
   let count = 0;
-  for (const { line, consumedBytes } of completeLines(tail.text)) {
-    if (!line) {
+  for (const { line: rawLine, consumedBytes } of completeLines(tail.text)) {
+    // A crash leaves a run of NUL bytes where data never reached disk, and the
+    // resumed writer appends after it. A raw NUL is never valid JSON, so drop
+    // them and keep the record that follows.
+    const line = rawLine.includes('\0') ? rawLine.replaceAll('\0', '') : rawLine;
+    if (!line.trim()) {
       boundary.bytes += consumedBytes;
       continue;
     }
@@ -82,7 +86,12 @@ export async function ingestTranscriptTail({ db, transcriptPath, cwd, offsets, r
     try {
       parsed = JSON.parse(line);
     } catch {
-      break; // malformed line: do not advance past it; retry on next sweep
+      // The line is complete (a half-written one has no newline yet and is not
+      // yielded), so it can never become valid: skip it for good, or it would
+      // block every line after it.
+      log(`[transcript-watch] skipped a damaged line in ${path.basename(transcriptPath)}\n`);
+      boundary.bytes += consumedBytes;
+      continue;
     }
     index += 1;
     const row = transcriptRowFromLine(parsed);

package/src/runtime/memory/lib/pg/process.mjs

@@ -26,6 +26,7 @@ import { readdir, readFile, rm, stat } from 'node:fs/promises';
 import { join } from 'node:path';
 import { execFile, spawn, spawnSync } from 'node:child_process';
 import { createConnection, createServer } from 'node:net';
+import { holdsNoData, writeFileAtomicSync } from '../../../shared/atomic-file.mjs';
 import { isPidAlive } from '../../../shared/pid-liveness.mjs';
 import { runChild } from './run-child.mjs';
 
@@ -180,9 +181,12 @@ function stripPlatformInvalidLines(conf) {
 function ensureConfV2(pgdataDir) {
   const confPath = join(pgdataDir, 'postgresql.conf');
   if (!existsSync(confPath)) return false;
-  const original = readFileSync(confPath, 'utf8');
+  // A conf a crash left empty or NUL-filled cannot be parsed by PostgreSQL; the
+  // defaults plus the overrides appended below are a working config.
+  const text = readFileSync(confPath, 'utf8');
+  const original = holdsNoData(text) ? '' : text;
   let conf = stripPlatformInvalidLines(original);
-  let changed = conf !== original;
+  let changed = conf !== text;
   if (!conf.includes(MIXDOG_CONF_V2_MARKER)) {
     conf += buildV2Block();
     changed = true;
@@ -196,7 +200,7 @@ function ensureConfV2(pgdataDir) {
     changed = true;
   }
   if (!changed) return false;
-  writeFileSync(confPath, conf);
+  writeFileAtomicSync(confPath, conf, { backup: true });
   return true;
 }
 
@@ -350,7 +354,7 @@ async function initClusterIfNeeded({ runtimeDir, pgdataDir, env }) {
   const confPath = join(pgdataDir, 'postgresql.conf');
   try {
     const existing = readFileSync(confPath, 'utf8');
-    writeFileSync(confPath, existing + freshClusterConfAppend());
+    writeFileAtomicSync(confPath, existing + freshClusterConfAppend());
   } catch (e) {
     __mixdogMemoryLog(`[pg-process] postgresql.conf append failed: ${e?.message}\n`);
   }

package/src/runtime/memory/lib/project-id-resolver.mjs

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
 import { explicitSessionCwd } from '../../shared/user-cwd.mjs';
+import { holdsNoData } from '../../shared/atomic-file.mjs';
 
 /** @type {Map<string, string|null>} */
 const cache = new Map();
@@ -51,7 +52,10 @@ export function resolveProjectId(cwd) {
   const idFile = join(mixdogRoot, '.mixdog', 'project.id');
   let content;
   try {
-    content = readFileSync(idFile, 'utf8').trim();
+    const raw = readFileSync(idFile, 'utf8');
+    // A crash can leave the marker NUL-filled; trim() keeps NULs, so it would
+    // otherwise become the project id. No data means no marker (COMMON).
+    content = holdsNoData(raw) ? '' : raw.trim();
   } catch {
     // TOCTOU: the file vanished between findProjectIdRoot's existsSync and
     // this read. Treat as no marker; do not cache so a transient miss can

package/src/runtime/memory/lib/runtime-fetcher.mjs

@@ -34,6 +34,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'nod
 import { fileURLToPath } from 'node:url';
 import { runChild } from './pg/run-child.mjs';
 import { renameWithRetrySync, writeFileAtomicSync, writeJsonAtomicSync } from '../../shared/atomic-file.mjs';
+import { fileHasData } from '../../shared/file-has-data.mjs';
 import { downloadToFileWithRetry } from '../../shared/bounded-download.mjs';
 import { platformKey, platformKeyCandidates, verifySha256File } from '../../shared/native-asset.mjs';
 
@@ -497,8 +498,12 @@ function cachedRuntimeDir(runtimeBaseDir, version, sha256) {
 }
 
 // The asset digest stamped into a complete runtime tree, '' when absent.
+// A tree whose postgres executable holds no data (a crash after the extract
+// left it NUL-filled) is not complete, whatever its stamp says.
 function readRuntimeStamp(verDir) {
   try {
+    const postgres = join(verDir, 'bin', process.platform === 'win32' ? 'postgres.exe' : 'postgres');
+    if (existsSync(postgres) && !fileHasData(postgres)) return '';
     return readFileSync(join(verDir, '.version-sha256'), 'utf8').trim();
   } catch {
     return '';
@@ -588,7 +593,7 @@ async function installRuntimeVersion({ runtimeBaseDir, url, sha256, size, versio
     }
 
     // Stamp sha256 inside staging dir.
-    writeFileSync(join(stagingDir, '.version-sha256'), sha256);
+    writeFileAtomicSync(join(stagingDir, '.version-sha256'), sha256);
     normalizeBinExecBit(stagingDir);
 
     // Atomic swap:

package/src/runtime/office/core/journal.mjs

@@ -1,7 +1,7 @@
-import { mkdir, readFile, readdir, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { mkdir, readFile, readdir, rm, stat } from 'node:fs/promises';
 import { homedir } from 'node:os';
 import { join, resolve } from 'node:path';
-import { randomUUID } from 'node:crypto';
+import { parseJsonText, writeJsonAtomicAsync } from '../../shared/atomic-file.mjs';
 
 const RETENTION_MS = 30 * 24 * 60 * 60 * 1000;
 
@@ -18,17 +18,8 @@ function journalPath(id, dataDir) {
 }
 
 export async function writeOfficeJournal(record, dataDir = '') {
-  const directory = officeJournalDirectory(dataDir);
-  await mkdir(directory, { recursive: true });
   const target = journalPath(record.id, dataDir);
-  const temporary = join(directory, `.${record.id}.${randomUUID()}.tmp`);
-  await writeFile(temporary, `${JSON.stringify(record, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
-  try {
-    await rename(temporary, target);
-  } catch {
-    await rm(target, { force: true });
-    await rename(temporary, target);
-  }
+  await writeJsonAtomicAsync(target, record);
   return target;
 }
 
@@ -38,9 +29,11 @@ export async function removeOfficeJournal(id, dataDir = '') {
 
 export async function readOfficeJournal(id, dataDir = '') {
   try {
-    return JSON.parse(await readFile(journalPath(id, dataDir), 'utf8'));
+    return parseJsonText(await readFile(journalPath(id, dataDir), 'utf8'));
   } catch (error) {
-    if (error?.code === 'ENOENT') return null;
+    // A journal a crash left empty or NUL-filled records nothing to recover;
+    // it stays on disk for the retention sweep and never blocks the caller.
+    if (error?.code === 'ENOENT' || error instanceof SyntaxError) return null;
     throw error;
   }
 }

package/src/runtime/office/design/library/design-library-core.mjs

@@ -1,5 +1,5 @@
-import { randomUUID } from 'node:crypto';
-import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
+import { writeJsonAtomicAsync } from '../../../shared/atomic-file.mjs';
 import { delimiter, dirname, isAbsolute, join, resolve, win32 } from 'node:path';
 import { homedir } from 'node:os';
 import { fileURLToPath } from 'node:url';
@@ -126,20 +126,8 @@ export async function readJson(path, fallback = null) {
 }
 
 export async function writeJsonAtomic(path, value) {
-  await mkdir(dirname(path), { recursive: true });
-  const temporary = join(dirname(path), `.${randomUUID()}.tmp`);
-  await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, {
-    encoding: 'utf8',
-    mode: 0o600,
-  });
-  try {
-    await rename(temporary, path);
-  } catch {
-    await rm(path, { force: true });
-    await rename(temporary, path);
-  } finally {
-    await rm(temporary, { force: true }).catch(() => {});
-  }
+  // Durable atomic replace; the replaced version stays as <file>.bak.
+  await writeJsonAtomicAsync(path, value, { backup: true });
 }
 
 function resolveConfigPath(path, base) {

package/src/runtime/office/pdf/ocr-engine-worker.mjs

@@ -0,0 +1,37 @@
+// The OCR engine's own thread. Starting the engine includes the first-use
+// download of each language's data and gives no handle until it finishes, so
+// it runs here, where ending this thread ends the engine and the download with
+// it (ocr-engine.mjs).
+import { createRequire } from 'node:module';
+import { mkdir } from 'node:fs/promises';
+import { parentPort, workerData } from 'node:worker_threads';
+
+const require = createRequire(import.meta.url);
+const { languages, cachePath, langPath } = workerData;
+
+let engine = null;
+try {
+  await mkdir(cachePath, { recursive: true });
+  const tesseract = require('tesseract.js');
+  engine = await tesseract.createWorker(languages, tesseract.OEM.LSTM_ONLY, {
+    cachePath,
+    gzip: true,
+    ...(langPath ? { langPath } : {}),
+  });
+} catch (error) {
+  parentPort.postMessage({ startError: String(error?.message || error) });
+}
+
+if (engine) {
+  // One page at a time, in arrival order: the engine itself is serial.
+  parentPort.on('message', async ({ id, image, output }) => {
+    try {
+      const input = typeof image === 'string' ? image : Buffer.from(image.buffer, image.byteOffset, image.byteLength);
+      const recognized = await engine.recognize(input, {}, output || { text: true });
+      parentPort.postMessage({ id, data: recognized.data });
+    } catch (error) {
+      parentPort.postMessage({ id, error: String(error?.message || error) });
+    }
+  });
+  parentPort.postMessage({ ready: true });
+}

package/src/runtime/office/pdf/ocr-engine.mjs

@@ -0,0 +1,146 @@
+// One OCR engine per language set and cache, on a thread of its own so that a
+// stalled start (the first-use language download) or a cancelled page can be
+// ended at once: ending the thread ends the engine and its download. Callers
+// arriving while it starts share that start; the engine ends when the last
+// caller releases it.
+import { Worker } from 'node:worker_threads';
+import { workerExecArgv } from '../../shared/worker-exec-argv.mjs';
+
+const ENGINE_URL = new URL('./ocr-engine-worker.mjs', import.meta.url);
+
+/** The start includes the first-use download; without network it fails or hangs. */
+export const OCR_ENGINE_START_TIMEOUT_MS = 90_000;
+
+const engines = new Map();
+
+const cancelledError = () => new Error('PDF OCR was cancelled');
+const unavailableError = (message) => Object.assign(new Error(message), { code: 'OCR_UNAVAILABLE' });
+
+const defaultSpawn = (url, options) => new Worker(url, options);
+
+/** How many engine threads are running (for diagnostics and tests). */
+export function liveOcrEngines() {
+  return engines.size;
+}
+
+// Ends the engine: its thread, its start and every page it still owes.
+function closeEngine(entry, error) {
+  if (entry.closed) return;
+  entry.closed = true;
+  entry.error = error;
+  clearTimeout(entry.timer);
+  if (engines.get(entry.key) === entry) engines.delete(entry.key);
+  entry.failStart(error);
+  const jobs = [...entry.jobs.values()];
+  entry.jobs.clear();
+  for (const job of jobs) job.reject(error);
+  void entry.thread.terminate().catch(() => {});
+}
+
+function startEngine(key, { languages, cachePath, langPath, timeoutMs, spawn }) {
+  const entry = { key, holders: 0, jobs: new Map(), nextJob: 0, closed: false, error: null };
+  entry.started = new Promise((resolve, reject) => {
+    entry.markStarted = resolve;
+    entry.failStart = reject;
+  });
+  entry.started.catch(() => {});
+  entry.thread = spawn(ENGINE_URL, {
+    execArgv: workerExecArgv(),
+    workerData: { languages, cachePath, langPath: langPath || null },
+  });
+  entry.timer = setTimeout(
+    () => closeEngine(entry, unavailableError('OCR language data did not load in time (it downloads on first use)')),
+    timeoutMs
+  );
+  entry.timer.unref?.();
+  entry.thread.on('message', (message) => {
+    if (message?.ready) {
+      clearTimeout(entry.timer);
+      entry.markStarted();
+      return;
+    }
+    if (message?.startError) {
+      closeEngine(entry, unavailableError(`OCR could not start: ${message.startError}`));
+      return;
+    }
+    const job = entry.jobs.get(message?.id);
+    if (!job) return;
+    entry.jobs.delete(message.id);
+    if (message.error) job.reject(new Error(`OCR failed: ${message.error}`));
+    else job.resolve(message.data);
+  });
+  entry.thread.on('error', (error) => closeEngine(entry, error));
+  entry.thread.on('exit', (code) => closeEngine(entry, new Error(`OCR engine stopped (exit ${code})`)));
+  engines.set(key, entry);
+  return entry;
+}
+
+// `promise`, or a cancellation as soon as `signal` aborts.
+function untilAborted(promise, signal) {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.reject(cancelledError());
+  return new Promise((resolve, reject) => {
+    const onAbort = () => reject(cancelledError());
+    signal.addEventListener('abort', onAbort, { once: true });
+    promise.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
+  });
+}
+
+function recognizeOn(entry, image, { output, signal } = {}) {
+  if (entry.closed) return Promise.reject(entry.error);
+  if (signal?.aborted) return Promise.reject(cancelledError());
+  const id = ++entry.nextJob;
+  const answer = new Promise((resolve, reject) => {
+    entry.jobs.set(id, { resolve, reject });
+  });
+  entry.thread.postMessage({ id, image, output: output || null });
+  if (!signal) return answer;
+  return new Promise((resolve, reject) => {
+    const onAbort = () => {
+      entry.jobs.delete(id);
+      // A page in recognition cannot be stopped inside the engine: the engine
+      // ends with it unless another caller still uses it, which then gets the
+      // page's (discarded) answer before its own.
+      if (entry.holders <= 1) closeEngine(entry, cancelledError());
+      reject(cancelledError());
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+    answer.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort));
+  });
+}
+
+/**
+ * The engine for `languages` ("eng+kor") with its data cached at `cachePath`,
+ * started on first use. Resolves `{ recognize(image, { output, signal }),
+ * release() }` once it is ready; the caller releases it when done. Rejects
+ * with code OCR_UNAVAILABLE when it does not start within `timeoutMs`, and
+ * with a cancellation when `signal` aborts, ending the start if no one else
+ * waits on it.
+ */
+export async function acquireOcrEngine({
+  languages,
+  cachePath,
+  langPath = null,
+  signal = null,
+  timeoutMs = OCR_ENGINE_START_TIMEOUT_MS,
+  spawn = defaultSpawn,
+}) {
+  if (signal?.aborted) throw cancelledError();
+  const key = `${cachePath}\0${languages}\0${langPath || ''}`;
+  const entry = engines.get(key) || startEngine(key, { languages, cachePath, langPath, timeoutMs, spawn });
+  entry.holders += 1;
+  let released = false;
+  const release = () => {
+    if (released) return;
+    released = true;
+    entry.holders -= 1;
+    if (entry.holders <= 0) closeEngine(entry, new Error('OCR engine released'));
+  };
+  try {
+    await untilAborted(entry.started, signal);
+  } catch (error) {
+    release();
+    throw error;
+  }
+  return { recognize: (image, options) => recognizeOn(entry, image, options), release };
+}

package/src/runtime/office/pdf/pdf-ocr.mjs

@@ -1,15 +1,18 @@
 // PDF OCR: tesseract TSV/block parsing, readiness probe and the ocr operation.
 import { createRequire } from 'node:module';
-import { mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
+import { readFile, readdir, rm, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
 import { PDFDocument, rgb } from 'pdf-lib';
 import { SAVE_OPTIONS } from './pdf-draw.mjs';
 import { embedDocumentFont, fontCovers } from './pdf-fonts.mjs';
-import { renderPdfPages } from './pdf-render.mjs';
+import { PDF_RENDER_MAX_EXPLICIT_PAGES, renderPdfPages } from './pdf-render.mjs';
 import { selectedPages } from './pdf-document.mjs';
+import { acquireOcrEngine } from './ocr-engine.mjs';
 
 const require = createRequire(import.meta.url);
 
+const DEFAULT_MIN_CONFIDENCE = 40;
+
 // The engine's own column order. Tesseract writes this table with a header
 // row through its command line and without one through the worker API, so the
 // reader accepts both: taking the first data row as a header dropped that word
@@ -208,7 +211,7 @@ export async function pdfOcrReadiness(dataDir) {
 
 // Renders and recognizes one page; the rendered image path is recorded on
 // `temporaryImages` for cleanup.
-async function recognizePage(worker, path, pageNumber, operation, signal, temporaryImages) {
+async function recognizePage(engine, path, pageNumber, operation, signal, temporaryImages) {
   const rendered = await renderPdfPages(path, {
     pages: [pageNumber],
     maxWidth: Math.max(1200, Math.min(3200, Number(operation.maxWidth) || 2400)),
@@ -216,13 +219,13 @@ async function recognizePage(worker, path, pageNumber, operation, signal, tempor
   });
   const image = rendered.images[0];
   temporaryImages.push(image.path);
-  const recognized = await worker.recognize(image.path, {}, { text: true, tsv: true, blocks: true });
-  const lines = ocrTextLines(recognized.data.tsv, recognized.data.text);
-  const minConfidence = Number(operation.minConfidence ?? 40);
-  const words = (lines.length ? lines.flatMap((line) => line.words) : parseOcrBlocks(recognized.data.blocks)).filter(
+  const recognized = await engine.recognize(image.path, { output: { text: true, tsv: true, blocks: true }, signal });
+  const lines = ocrTextLines(recognized.tsv, recognized.text);
+  const minConfidence = Number(operation.minConfidence ?? DEFAULT_MIN_CONFIDENCE);
+  const words = (lines.length ? lines.flatMap((line) => line.words) : parseOcrBlocks(recognized.blocks)).filter(
     (word) => word.confidence >= minConfidence
   );
-  return { pageNumber, image, lines, words, text: recognized.data.text || '' };
+  return { pageNumber, image, lines, words, text: recognized.text || '' };
 }
 
 // One font for all the recognized text: Helvetica when it is Latin, an
@@ -285,18 +288,15 @@ function placeRecognizedText(document, { pageNumber, image, lines, words }, font
   }
 }
 
-async function createOcrWorker(operation, dataDir) {
+// The shared engine for the operation's languages (ocr-engine.mjs): it starts
+// on its own thread, so a stalled first-use download or a cancellation ends
+// it at once.
+async function openOcrEngine(operation, dataDir, signal) {
   const languages = Array.isArray(operation.languages)
     ? operation.languages.map(String).join('+')
     : String(operation.languages || 'eng+kor');
-  const cachePath = ocrCachePath(dataDir);
-  await mkdir(cachePath, { recursive: true });
-  const tesseract = require('tesseract.js');
-  const worker = await tesseract.createWorker(languages, tesseract.OEM.LSTM_ONLY, {
-    cachePath,
-    gzip: true,
-  });
-  return { worker, languages };
+  const engine = await acquireOcrEngine({ languages, cachePath: ocrCachePath(dataDir), signal });
+  return { engine, languages };
 }
 
 function ocrResult(operation, { pages, languages, text, tally, fontPath, embedded }) {
@@ -318,6 +318,36 @@ function ocrResult(operation, { pages, languages, text, tally, fontPath, embedde
   };
 }
 
+/**
+ * Read-only OCR: the recognized text of `pages` (1-based) of the PDF at
+ * `path`, as `[{ page, text }]`. Pages are rendered in memory and nothing is
+ * written next to the PDF or into it. Throws when the engine or its language
+ * data is unavailable (no network on first use).
+ */
+export async function recognizePdfPageTexts(path, pages, { dataDir, signal = null, languages } = {}) {
+  const { engine } = await openOcrEngine({ languages }, dataDir, signal);
+  const out = [];
+  try {
+    for (let offset = 0; offset < pages.length; offset += PDF_RENDER_MAX_EXPLICIT_PAGES) {
+      if (signal?.aborted) throw new Error('PDF OCR was cancelled');
+      const rendered = await renderPdfPages(path, {
+        pages: pages.slice(offset, offset + PDF_RENDER_MAX_EXPLICIT_PAGES),
+        maxWidth: 2000,
+        signal,
+        writeImages: false,
+      });
+      for (const image of rendered.images) {
+        if (signal?.aborted) throw new Error('PDF OCR was cancelled');
+        const recognized = await engine.recognize(Buffer.from(image.data, 'base64'), { signal });
+        out.push({ page: image.page, text: String(recognized?.text || '').trim() });
+      }
+    }
+    return out;
+  } finally {
+    engine.release();
+  }
+}
+
 export async function ocrPdf(path, operation, { dataDir, signal = null } = {}) {
   const source = await readFile(path);
   const document = await PDFDocument.load(source, {
@@ -325,7 +355,7 @@ export async function ocrPdf(path, operation, { dataDir, signal = null } = {}) {
     updateMetadata: false,
   });
   const pages = selectedPages(document.getPageCount(), operation.pages || (operation.page ? [operation.page] : null));
-  const { worker, languages } = await createOcrWorker(operation, dataDir);
+  const { engine, languages } = await openOcrEngine(operation, dataDir, signal);
   const tally = { wordCount: 0, skippedWords: 0, totalConfidence: 0 };
   let text = '';
   const temporaryImages = [];
@@ -335,19 +365,19 @@ export async function ocrPdf(path, operation, { dataDir, signal = null } = {}) {
     // it produced.
     for (const pageNumber of pages) {
       if (signal?.aborted) throw new Error('PDF OCR was cancelled');
-      const recognized = await recognizePage(worker, path, pageNumber, operation, signal, temporaryImages);
+      const recognized = await recognizePage(engine, path, pageNumber, operation, signal, temporaryImages);
       recognizedPages.push(recognized);
       text += `${text ? '\n\n' : ''}--- Page ${pageNumber} ---\n${recognized.text}`;
     }
     const { font, fontPath, embedded } = await selectOcrFont(document, operation, recognizedPages);
-    const minConfidence = Number(operation.minConfidence ?? 40);
+    const minConfidence = Number(operation.minConfidence ?? DEFAULT_MIN_CONFIDENCE);
     for (const entry of recognizedPages) placeRecognizedText(document, entry, font, minConfidence, tally);
     if (tally.wordCount > 0) {
       await writeFile(path, await document.save(SAVE_OPTIONS));
     }
     return ocrResult(operation, { pages, languages, text, tally, fontPath, embedded });
   } finally {
-    await worker.terminate().catch(() => {});
+    engine.release();
     for (const image of temporaryImages) await rm(image, { force: true }).catch(() => {});
   }
 }