create-pmos 0.133.0 → 0.135.0

package/workspace/lib/notes-live-guard.js

@@ -0,0 +1,117 @@
+'use strict';
+/* notes-live-guard.js — what the live transcript must not keep (notes-recording-reliability). Pure functions, no I/O.
+ *
+ *   stripEcho(mic, meetingLines) → the microphone line's text without the meeting's words, or '' when nothing of its own is left
+ *   repeats(text, previous) → true when a cut only says again what the line before it said
+ *   onceEach(text) → the text with a sentence repeated back to back kept once
+ *   looksForeign(text, reported) → true when a cut that should be English came back in another language
+ *
+ * ECHO. On speakers the remote voice also reaches the microphone, so the microphone's cut holds the meeting's words a second
+ * time. lib/notes-final.js drops such lines after Stop (dropEcho); this is the same rule, live: a run of ECHO_RUN or more words
+ * that a meeting line overlapping in time also holds (and that is at least half of that line) is taken out of the microphone line, and what is left is dropped when it
+ * still overlaps the meeting line by ECHO_OVERLAP of its length with ECHO_WORDS of its words the same (dropEcho's numbers).
+ * The PM's own words on the microphone stay.
+ *
+ * REPETITION. Whisper repeats itself, more so when the previous line is in its prompt (no longer passed). A cut whose words are
+ * the previous line's words, or end it, adds nothing. A short reply ("Yes.") said again later is kept: a short line counts
+ * as a repeat only within REPEAT_MS.
+ *
+ * LANGUAGE (decision 8 of the console3 feedback plan: accented English is always English). A cut is foreign when the engine
+ * says another language, when most of its letters are not Latin, or when most of its words are Indonesian function words.
+ */
+const ECHO_OVERLAP = 0.5;
+const ECHO_WORDS = 0.5;
+const ECHO_RUN = 4;
+const ECHO_SLACK_MS = 1500;
+const REPEAT_MS = 15000;
+
+const norm = (w) => String(w || '').toLowerCase().replace(/[^\p{L}\p{N}']/gu, '');
+const tokens = (text) => String(text || '').split(/\s+/).filter(Boolean);
+const wordsOf = (t) => new Set(String(t || '').toLowerCase().match(/[\p{L}\p{N}']{3,}/gu) || []);
+function sameWords(a, b) {
+  const x = wordsOf(a); const y = wordsOf(b);
+  if (!x.size || !y.size) return 0;
+  let both = 0; for (const w of x) if (y.has(w)) both++;
+  return both / Math.min(x.size, y.size);
+}
+/** The longest run of words the two token lists share, as { at, len } in `a`. */
+function longestRun(a, b) {
+  let best = { at: 0, len: 0 };
+  for (let i = 0; i < a.length; i++) {
+    for (let j = 0; j < b.length; j++) {
+      let k = 0;
+      while (i + k < a.length && j + k < b.length && a[i + k] && a[i + k] === b[j + k]) k++;
+      if (k > best.len) best = { at: i, len: k };
+    }
+  }
+  return best;
+}
+const overlapMs = (a, b) => Math.min(a.end, b.end) - Math.max(a.t, b.t);
+
+/** `mic` and each meeting line: { t, end, text }. → the microphone text that is the PM's own. */
+function stripEcho(mic, meetingLines) {
+  const near = (meetingLines || []).filter((g) => overlapMs({ t: mic.t - ECHO_SLACK_MS, end: mic.end + ECHO_SLACK_MS }, g) > 0);
+  if (!near.length) return String(mic.text || '').trim();
+  let toks = tokens(mic.text);
+  for (const g of near) {
+    const theirs = tokens(g.text).map(norm);
+    const need = theirs.filter(Boolean).length * ECHO_WORDS;
+    // the runs of ECHO_RUN words or more this meeting line shares with the microphone line; they are echo together when they
+    // cover at least half of the meeting line: an echo repeats most of what the remote speaker said, a PM quoting a phrase does not.
+    // A microphone line that is wholly the meeting's words goes, however short.
+    let work = toks.slice(); const cuts = []; let covered = 0;
+    for (;;) {
+      const mine = work.map(norm);
+      const r = longestRun(mine, theirs);
+      const whole = r.len && r.len >= mine.filter(Boolean).length && !cuts.length;
+      if (!r.len || (!whole && r.len < ECHO_RUN)) break;
+      covered += r.len; cuts.push(r);
+      work = work.slice(0, r.at).concat(new Array(r.len).fill('')).concat(work.slice(r.at + r.len));
+      if (whole) { covered = Infinity; break; }
+    }
+    if (cuts.length && covered >= need) toks = work.filter(Boolean);
+    if (!toks.length) return '';
+  }
+  const left = toks.join(' ').replace(/^[\s,.;:!?…-]+/, '').trim();
+  if (!/[\p{L}\p{N}]/u.test(left)) return '';
+  const len = Math.max(1, mic.end - mic.t);
+  if (near.some((g) => overlapMs(mic, g) / len >= ECHO_OVERLAP && sameWords(left, g.text) >= ECHO_WORDS)) return '';
+  return left;
+}
+
+/** Does `text` only repeat `previous` ({ text, t }) of the same source? `t` is the new cut's time. */
+function repeats(text, previous, t = 0) {
+  if (!previous || !previous.text) return false;
+  const a = tokens(text).map(norm).filter(Boolean); const b = tokens(previous.text).map(norm).filter(Boolean);
+  if (!a.length || a.length > b.length) return false;
+  const tail = b.slice(b.length - a.length);
+  if (a.join(' ') !== tail.join(' ')) return false;
+  return a.length >= 3 || Math.abs(t - (previous.t || 0)) <= REPEAT_MS;
+}
+
+/** A sentence said twice or more back to back inside one cut is kept once. */
+function onceEach(text) {
+  const parts = String(text || '').match(/[^.!?…]+[.!?…]*\s*/g);
+  if (!parts || parts.length < 2) return String(text || '').trim();
+  const out = [];
+  for (const p of parts) { const k = tokens(p).map(norm).join(' '); if (out.length && k && k === tokens(out[out.length - 1]).map(norm).join(' ')) continue; out.push(p); }
+  return out.join('').trim();
+}
+
+const ID_WORDS = new Set(['yang', 'dan', 'di', 'ini', 'itu', 'tidak', 'dengan', 'untuk', 'ada', 'saya', 'kita', 'kami', 'akan', 'sudah', 'belum', 'juga',
+  'dari', 'ke', 'karena', 'jadi', 'bisa', 'apa', 'kalau', 'tapi', 'atau', 'nya', 'lagi', 'harus', 'sama', 'mau', 'gak', 'nggak', 'ya', 'kamu', 'mereka', 'dia', 'pada', 'dalam', 'seperti', 'lebih', 'masih', 'aja', 'saja']);
+/** Did a cut that should be English come back in another language? `reported` is the engine's language name, when it says one. */
+function looksForeign(text, reported) {
+  const t = String(text || '');
+  if (reported && !/^(en|english)$/i.test(String(reported).trim())) return true;
+  const letters = t.match(/\p{L}/gu) || [];
+  if (letters.length) {
+    const latin = letters.filter((c) => /\p{Script=Latin}/u.test(c)).length;
+    if (latin / letters.length < 0.7) return true;
+  }
+  const ws = (t.toLowerCase().match(/[a-z]+/g) || []);
+  if (ws.length >= 4 && ws.filter((w) => ID_WORDS.has(w)).length / ws.length >= 0.3) return true;
+  return false;
+}
+
+module.exports = { stripEcho, repeats, onceEach, looksForeign, sameWords, ECHO_OVERLAP, ECHO_WORDS, ECHO_RUN, REPEAT_MS };

package/workspace/lib/notes-replay.js

@@ -0,0 +1,125 @@
+'use strict';
+/* notes-replay.js — notes-live-settle Run 1: what a replayed meeting shows, and what a settle tier would cost on this machine.
+ *
+ *   words(text) → [word]                     lower case, letters and digits only
+ *   overlap(a, b) → 0..1                     the share of the shorter line's words that the other line also has
+ *   duplicates(lines, { repeatMs, echoMs }) → [{ kind, a, b, overlap }]   lines said twice: `repeat` (one source, close together)
+ *                                            or `echo` (the microphone and the meeting, at the same moment)
+ *   lag(seen) → { median_ms, p90_ms, max_ms, n }   how long after its audio a live line appeared
+ *   createSettleMeter({ transcribe, windowMs?, pauseMs?, now? }) → { feed(source, pcm), idle(), report(elapsedMs) }
+ *
+ * WHY. The PM reported duplicated audio and a duplicated transcript (notes-recording-reliability). That fix was measured on a
+ * scripted fixture; bin/notes-replay.js plays a real kept meeting through the live path again, and this module says what came out.
+ * The plan's near-realtime correction (console3 feedback plan 3.1, "settle tier") is built only if this machine keeps up: at each
+ * settle point the last WINDOW_MS of a source is transcribed again with the final pass's engine. The meter does that while the
+ * replay runs and measures the share of the meeting's time the engine was busy (`busy_share`, the real-time factor of the settle
+ * tier). The plan's gate: under 0.5, and no settle point skipped because the engine was still busy.
+ *
+ * WHAT IT NEVER DOES. It stores nothing and makes no request; `transcribe` is lib/notes-final.js transcribeClip, local.
+ */
+const whisper = require('./notes-whisper.js');
+
+const RATE = whisper.RATE;
+const REPEAT_MS = 15000;       // a line said again by the same source within this time is a repeat
+const ECHO_MS = 5000;          // a microphone line and a meeting line this close are the same moment
+const MIN_OVERLAP = 0.8;
+const MIN_WORDS = 3;           // a shorter line ("Yes.") said twice is a conversation, not a duplicate, unless it is the same text
+const WINDOW_MS = 30000;       // the plan's 20 to 40 s
+const PAUSE_MS = 1500;         // the plan's settle point: a pause of 1.5 s
+const GATE = 0.5;
+
+const words = (text) => String(text || '').toLowerCase().match(/[\p{L}\p{N}']+/gu) || [];
+function overlap(a, b) {
+  const wa = words(a); const wb = words(b);
+  if (!wa.length || !wb.length) return 0;
+  const [short, long] = wa.length <= wb.length ? [wa, wb] : [wb, wa];
+  const bag = new Map(); for (const w of long) bag.set(w, (bag.get(w) || 0) + 1);
+  let hit = 0; for (const w of short) { const c = bag.get(w) || 0; if (c) { hit++; bag.set(w, c - 1); } }
+  return hit / short.length;
+}
+const endOf = (l) => (Number.isFinite(l.t_end) ? l.t_end : l.t);
+
+/** Lines said twice. `lines` are transcript lines { t, t_end?, text, source }, in any order; dropped lines are left out. */
+function duplicates(lines, { repeatMs = REPEAT_MS, echoMs = ECHO_MS } = {}) {
+  const ls = (lines || []).filter((l) => l && !l.dropped && Number.isFinite(l.t) && words(l.text).length).slice().sort((x, y) => x.t - y.t);
+  const out = [];
+  for (let i = 0; i < ls.length; i++) {
+    for (let j = i + 1; j < ls.length && ls[j].t - endOf(ls[i]) <= Math.max(repeatMs, echoMs); j++) {
+      const a = ls[i]; const b = ls[j];
+      const same = words(a.text).join(' ') === words(b.text).join(' ');
+      const o = overlap(a.text, b.text);
+      const long = Math.min(words(a.text).length, words(b.text).length) >= MIN_WORDS;
+      if (!(same || (long && o >= MIN_OVERLAP))) continue;
+      const gap = b.t - endOf(a);
+      if (a.source === b.source && gap <= repeatMs) out.push({ kind: 'repeat', a, b, overlap: Math.round(o * 100) / 100 });
+      else if (a.source !== b.source && gap <= echoMs) out.push({ kind: 'echo', a, b, overlap: Math.round(o * 100) / 100 });
+    }
+  }
+  return out;
+}
+
+const pct = (xs, q) => { if (!xs.length) return null; const s = xs.slice().sort((x, y) => x - y); return s[Math.min(s.length - 1, Math.floor((s.length - 1) * q))]; };
+/** `seen` is [{ late_ms }], one per live line: how long after the end of its audio the line appeared. */
+function lag(seen) {
+  const xs = (seen || []).map((s) => s.late_ms).filter(Number.isFinite);
+  return { n: xs.length, median_ms: pct(xs, 0.5), p90_ms: pct(xs, 0.9), max_ms: xs.length ? Math.max(...xs) : null };
+}
+
+/**
+ * The settle tier, measured. `feed` is called with each one-second chunk of a source as it is replayed.
+ * A settle point is a pause of PAUSE_MS after speech, or the other source starting to speak; at a settle point the last WINDOW_MS of
+ * that source goes to `transcribe(pcm)`. One run at a time: a settle point that comes while the engine is busy is skipped and counted.
+ */
+function createSettleMeter({ transcribe, windowMs = WINDOW_MS, pauseMs = PAUSE_MS, now = Date.now } = {}) {
+  const st = new Map();    // source → { buf: [Buffer], bytes, voiced: bool, quietMs, floor: [rms] }
+  const runs = []; let skipped = 0; let points = 0; let busy = null; let busyMs = 0; let engine = null; const errors = [];
+  let lastVoiced = null;
+  const keep = Math.round(windowMs * RATE / 1000) * 2;
+  const of = (source) => { if (!st.has(source)) st.set(source, { buf: [], bytes: 0, voiced: false, quietMs: 0, floor: [] }); return st.get(source); };
+  function point(source) {
+    points++;
+    if (busy) { skipped++; return; }
+    const s = of(source);
+    const pcm = Buffer.concat(s.buf).subarray(-keep);
+    const audioMs = (pcm.length / 2 / RATE) * 1000;
+    const began = now();
+    let started; try { started = Promise.resolve(transcribe(pcm)); } catch (e) { started = Promise.reject(e); }
+    busy = started.then((r) => {
+      const took = now() - began; busyMs += took;
+      if (r && r.ok) { engine = r.engine || engine; runs.push({ source, audio_ms: Math.round(audioMs), took_ms: took }); } else errors.push(String((r && r.error) || 'no answer').slice(0, 200));
+    }, (e) => { busyMs += now() - began; errors.push(String((e && e.message) || e).slice(0, 200)); }).finally(() => { busy = null; });
+  }
+  return {
+    feed(source, pcm) {
+      const s = of(source);
+      s.buf.push(pcm); s.bytes += pcm.length;
+      while (s.bytes - s.buf[0].length >= keep) s.bytes -= s.buf.shift().length;
+      // a 100 ms frame is speech above three times the quiet of the last minute before it (its 10th percentile), and never below
+      // 180; until five seconds were heard, above 180
+      for (const v of whisper.levels(pcm)) {
+        const q = s.floor.length >= 50 ? pct(s.floor.filter((x) => x > 0), 0.1) || 0 : 0;
+        s.floor.push(v); if (s.floor.length > 600) s.floor.shift();
+        const voiced = v > Math.max(180, q * 3);
+        if (voiced) {
+          if (lastVoiced && lastVoiced !== source && of(lastVoiced).voiced) { of(lastVoiced).voiced = false; point(lastVoiced); }
+          s.voiced = true; s.quietMs = 0; lastVoiced = source;
+        } else if (s.voiced) {
+          s.quietMs += 100;
+          if (s.quietMs >= pauseMs) { s.voiced = false; point(source); }
+        }
+      }
+    },
+    idle() { return busy || Promise.resolve(); },
+    report(elapsedMs) {
+      const rtf = runs.map((r) => r.took_ms / Math.max(1, r.audio_ms));
+      const share = elapsedMs > 0 ? busyMs / elapsedMs : null;
+      const keepsUp = share !== null && share < GATE && skipped === 0 && runs.length > 0;
+      return { engine, points, runs: runs.length, skipped, errors: errors.slice(0, 5), busy_ms: busyMs, elapsed_ms: elapsedMs,
+        busy_share: share === null ? null : Math.round(share * 1000) / 1000,
+        window_rtf_median: rtf.length ? Math.round(pct(rtf, 0.5) * 1000) / 1000 : null, window_rtf_p90: rtf.length ? Math.round(pct(rtf, 0.9) * 1000) / 1000 : null,
+        gate: GATE, keeps_up: keepsUp };
+    },
+  };
+}
+
+module.exports = { words, overlap, duplicates, lag, createSettleMeter, REPEAT_MS, ECHO_MS, WINDOW_MS, PAUSE_MS, GATE };

package/workspace/lib/notes-screen.js

@@ -0,0 +1,180 @@
+'use strict';
+/* notes-screen.js — the screenshots a note keeps of the screen the PM shared in the meeting (notes-screen-capture). Local only.
+ *
+ *   add(runtimeDir, { id, t, buf, w, h }) → { ok, frame } | { ok: false, status, error }   keep one shot at meeting time t (ms)
+ *   list(runtimeDir, id) → [{ t, file, w, h, bytes, why?, text? }]   sorted by t; empty when the note has none
+ *   serve(req, res, runtimeDir, id, t)        the shot at t as its image, cached for good; 404 JSON when there is none
+ *   remove(runtimeDir, id) → boolean          delete the note's screenshots
+ *   getOn(runtimeDir) · setOn(runtimeDir, bool)   "Capture the shared screen", on by default, for this machine
+ *   ocrDetect({ env? }) → { bin } | null      the tesseract the PM installed
+ *   ocrIdle() → Promise                       resolves when the text queue is empty (tests)
+ *
+ * WHAT IT KEEPS. A folder next to the note's audio, `<runtime>/notes/recordings/<id>.screen/`: one image file per shot, named by
+ * its meeting time in milliseconds (`000123456.jpg`), and `index.json`, an array of { t, file, w, h, bytes, why?, text? } sorted by t,
+ * written whole through a temporary file and renamed, so a stop in the middle never leaves half an index. A shot at the same
+ * time as an earlier one replaces it. A note keeps at most MAX_SHOTS shots or MAX_BYTES bytes; a shot past either is refused
+ * with 409 and a plain sentence, and the shots already kept stay.
+ *
+ * WHICH BYTES. Only a JPEG, a PNG or a WebP, found by the file's first bytes and not by what the page says it is, and at most
+ * MAX_SHOT_BYTES each. The page sends a JPEG (public/pm), so a shot is far under the limit.
+ *
+ * ON-SCREEN TEXT. When tesseract is on this machine (PMOS_TESSERACT names it, else the PATH and where Homebrew puts it), each
+ * kept shot is read for its text, one at a time and in the background, and the text is added to that shot's row in the index.
+ * A failed or timed-out read leaves the shot with no text and is not an error. Without tesseract nothing is read.
+ *
+ * WHAT IT NEVER DOES. It sends nothing and opens no network module. The only program it runs is the tesseract the PM installed,
+ * on a file in the note's own folder, with no shell and a time limit. The routes (lib/routes-notes.js) keep no shot for a private
+ * note, for a note that is not listening, or when the PM switched capturing off, and delete the folder when a note is made
+ * private or deleted.
+ */
+const fs = require('fs');
+const path = require('path');
+const { execFile } = require('child_process');
+
+const MAX_SHOT_BYTES = 2 * 1024 * 1024;
+const MAX_SHOTS = 2000;
+const MAX_BYTES = 500 * 1024 * 1024;
+const MAX_T = 999999999;                    // the file name holds nine digits of milliseconds
+const OCR_TIMEOUT_MS = 30000;
+const OCR_MAX_CHARS = 4000;
+const ID_RE = /^n-[0-9a-z]{4,16}-[0-9a-f]{4}$/;
+const FILE_RE = /^\d{9}\.(jpg|png|webp)$/;
+const TYPES = { jpg: 'image/jpeg', png: 'image/png', webp: 'image/webp' };
+
+const dirOf = (runtimeDir, id) => path.join(runtimeDir, 'notes', 'recordings', id + '.screen');
+const indexOf = (runtimeDir, id) => path.join(dirOf(runtimeDir, id), 'index.json');
+const settingsFile = (runtimeDir) => path.join(runtimeDir, 'notes', 'screen-settings.json');
+
+function readSettings(runtimeDir) { try { const s = JSON.parse(fs.readFileSync(settingsFile(runtimeDir), 'utf8')); return s && typeof s === 'object' ? s : {}; } catch { return {}; } }
+function writeAtomic(file, text) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = file + '.' + process.pid + '.tmp';
+  fs.writeFileSync(tmp, text, { mode: 0o600 });
+  fs.renameSync(tmp, file);
+}
+/** "Capture the shared screen": on until the PM turns it off, for this machine. */
+function getOn(runtimeDir) { return readSettings(runtimeDir).on !== false; }
+function setOn(runtimeDir, on) {
+  if (typeof on !== 'boolean') return { ok: false, error: 'say screen: true or screen: false' };
+  writeAtomic(settingsFile(runtimeDir), JSON.stringify({ ...readSettings(runtimeDir), on }));
+  return { ok: true, on };
+}
+
+/** The image type the first bytes name: 'jpg' | 'png' | 'webp' | null. */
+function kindOf(buf) {
+  if (!Buffer.isBuffer(buf) || buf.length < 12) return null;
+  if (buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) return 'jpg';
+  if (buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47) return 'png';
+  if (buf.toString('latin1', 0, 4) === 'RIFF' && buf.toString('latin1', 8, 12) === 'WEBP') return 'webp';
+  return null;
+}
+
+function readIndex(runtimeDir, id) {
+  try {
+    const a = JSON.parse(fs.readFileSync(indexOf(runtimeDir, id), 'utf8'));
+    if (!Array.isArray(a)) return [];
+    return a.filter((f) => f && Number.isFinite(f.t) && typeof f.file === 'string' && FILE_RE.test(f.file)).sort((x, y) => x.t - y.t);
+  } catch { return []; }
+}
+const writeIndex = (runtimeDir, id, rows) => writeAtomic(indexOf(runtimeDir, id), JSON.stringify(rows));
+const dimension = (n) => (Number.isFinite(Number(n)) && Number(n) > 0 ? Math.min(20000, Math.round(Number(n))) : 0);
+
+/** Keep one shot. `t` is the meeting time in ms, `buf` the image bytes, `w` and `h` its size in pixels. */
+function add(runtimeDir, { id, t, buf, w, h, why } = {}) {
+  if (!ID_RE.test(String(id || ''))) return { ok: false, status: 400, error: 'no such note' };
+  const time = typeof t === 'number' ? t : NaN;
+  if (!Number.isFinite(time) || time < 0 || time > MAX_T) return { ok: false, status: 400, error: 'a screenshot needs its meeting time' };
+  const at = Math.round(time);
+  if (!Buffer.isBuffer(buf) || !buf.length) return { ok: false, status: 400, error: 'there is no picture to keep' };
+  if (buf.length > MAX_SHOT_BYTES) return { ok: false, status: 413, error: 'that screenshot is larger than 2 MB' };
+  const kind = kindOf(buf);
+  if (!kind) return { ok: false, status: 400, error: 'a screenshot must be a JPEG, PNG or WebP picture' };
+  const rows = readIndex(runtimeDir, id);
+  const old = rows.find((f) => f.t === at);
+  const others = rows.filter((f) => f !== old);
+  if (others.length >= MAX_SHOTS) return { ok: false, status: 409, error: 'this note already keeps ' + MAX_SHOTS + ' screenshots, the most it holds' };
+  if (others.reduce((n, f) => n + (f.bytes || 0), 0) + buf.length > MAX_BYTES) return { ok: false, status: 409, error: 'this note\'s screenshots have reached 500 MB, the most it holds' };
+  const file = String(at).padStart(9, '0') + '.' + kind;
+  const dir = dirOf(runtimeDir, id);
+  fs.mkdirSync(dir, { recursive: true });
+  const target = path.join(dir, file);
+  const tmp = target + '.' + process.pid + '.tmp';
+  fs.writeFileSync(tmp, buf, { mode: 0o600 });
+  fs.renameSync(tmp, target);
+  if (old && old.file !== file) { try { fs.unlinkSync(path.join(dir, old.file)); } catch { /* none */ } }
+  const frame = { t: at, file, w: dimension(w), h: dimension(h), bytes: buf.length };
+  // why the page kept it (the screen changed, a line pointed at it, a highlight): plain words, kept short
+  const reason = typeof why === 'string' ? why.replace(/\s+/g, ' ').trim().slice(0, 120) : '';
+  if (reason) frame.why = reason;
+  writeIndex(runtimeDir, id, others.concat([frame]).sort((x, y) => x.t - y.t));
+  queueOcr(runtimeDir, id, frame);
+  return { ok: true, frame };
+}
+
+function list(runtimeDir, id) {
+  if (!ID_RE.test(String(id || ''))) return [];
+  return readIndex(runtimeDir, id);
+}
+
+/** The shot at meeting time `t` as its image. A shot is never changed once kept, so the browser may keep it for good. */
+function serve(req, res, runtimeDir, id, t) {
+  const miss = () => { res.writeHead(404, { 'Content-Type': 'application/json' }); res.end(JSON.stringify({ ok: false, error: 'this note has no screenshot at that time' })); };
+  if (!ID_RE.test(String(id || '')) || t === null || t === undefined || t === '' || !Number.isFinite(Number(t))) return miss();
+  const at = Math.round(Number(t));
+  const f = readIndex(runtimeDir, id).find((x) => x.t === at);
+  if (!f) return miss();
+  const file = path.join(dirOf(runtimeDir, id), f.file);
+  let size;
+  try { size = fs.statSync(file).size; } catch { return miss(); }
+  res.writeHead(200, { 'Content-Type': TYPES[path.extname(f.file).slice(1)] || 'application/octet-stream', 'Content-Length': size, 'Cache-Control': 'private, max-age=31536000, immutable' });
+  if (req.method === 'HEAD') { res.end(); return; }
+  fs.createReadStream(file).on('error', () => res.end()).pipe(res);
+}
+
+/** Delete the note's screenshots. True when a folder was there. */
+function remove(runtimeDir, id) {
+  if (!ID_RE.test(String(id || ''))) return false;
+  const dir = dirOf(runtimeDir, id);
+  const had = fs.existsSync(dir);
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* best effort */ }
+  return had;
+}
+
+/* ── on-screen text ──────────────────────────────────────────────────────────────────────────────── */
+const isExec = (f) => { try { fs.accessSync(f, fs.constants.X_OK); return fs.statSync(f).isFile(); } catch { return false; } };
+/** The tesseract on this machine: PMOS_TESSERACT, else the PATH, else where Homebrew puts it. */
+function ocrDetect({ env = process.env, fallbacks = ['/opt/homebrew/bin', '/usr/local/bin'] } = {}) {
+  const named = env.PMOS_TESSERACT;
+  if (named) return isExec(named) ? { bin: named } : null;
+  for (const d of String(env.PATH || '').split(path.delimiter).concat(fallbacks)) { if (!d) continue; const f = path.join(d, 'tesseract'); if (isExec(f)) return { bin: f }; }
+  return null;
+}
+const tidy = (s) => String(s || '').replace(/\s+/g, ' ').trim().slice(0, OCR_MAX_CHARS);
+
+let queue = Promise.resolve();
+let waiting = 0;
+function queueOcr(runtimeDir, id, frame) {
+  const found = ocrDetect();
+  if (!found) return;
+  waiting++;
+  queue = queue.then(() => readText(found.bin, runtimeDir, id, frame)).catch(() => {}).then(() => { waiting--; });
+}
+function readText(bin, runtimeDir, id, frame) {
+  const file = path.join(dirOf(runtimeDir, id), frame.file);
+  return new Promise((resolve) => {
+    execFile(bin, [file, 'stdout'], { timeout: OCR_TIMEOUT_MS, windowsHide: true, maxBuffer: 4 * 1024 * 1024 }, (err, stdout) => {
+      const text = err ? '' : tidy(stdout);
+      if (text) {
+        // patch the row only if the same shot is still there (it may have been replaced or deleted while it was read)
+        const rows = readIndex(runtimeDir, id);
+        const row = rows.find((f) => f.t === frame.t && f.file === frame.file && f.bytes === frame.bytes);
+        if (row) { row.text = text; try { writeIndex(runtimeDir, id, rows); } catch { /* the folder went away */ } }
+      }
+      resolve();
+    });
+  });
+}
+/** Resolves when every text read queued so far has ended. */
+function ocrIdle() { return queue.then(() => (waiting > 0 ? ocrIdle() : undefined)); }
+
+module.exports = { add, list, serve, remove, getOn, setOn, ocrDetect, ocrIdle, kindOf, MAX_SHOT_BYTES, MAX_SHOTS, MAX_BYTES };