@myrtilleio/redline 0.1.0

package/src/shots.js

@@ -0,0 +1,311 @@
+// Screenshots of feedback items, taken with a headless Chrome driven over the
+// DevTools protocol (Node's built-in WebSocket; no dependencies). The page loads
+// through Redline itself, so the overlay's "shot mode" can restore the item's
+// page state, draw its mark or apply its proposed edit/variant, and report the
+// area to crop.
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { MOBILE, isGuarded, wantsBaseline, wantsMobileBaseline } from './guards.js';
+
+const CANDIDATES = [
+  process.env.CHROME_PATH,
+  '/usr/bin/chromium',
+  '/usr/bin/chromium-browser',
+  '/usr/bin/google-chrome',
+  '/usr/bin/google-chrome-stable',
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+];
+
+export function findChrome() {
+  return CANDIDATES.find((p) => p && existsSync(p)) || null;
+}
+
+class Browser {
+  static async launch(executable) {
+    const profile = await mkdtemp(join(tmpdir(), 'redline-chrome-'));
+    const proc = spawn(
+      executable,
+      ['--headless=new', '--remote-debugging-port=0', `--user-data-dir=${profile}`, '--no-first-run', '--no-default-browser-check',
+        '--hide-scrollbars', '--mute-audio', '--disable-gpu',
+        // Pages keep their own pace (clocks, carousels) instead of a throttled background tab's.
+        '--disable-background-timer-throttling', '--disable-renderer-backgrounding', '--disable-backgrounding-occluded-windows',
+        // Chrome refuses to start as root with its sandbox on (containers, CI).
+        ...(process.getuid?.() === 0 ? ['--no-sandbox'] : []), 'about:blank'],
+      { stdio: ['ignore', 'ignore', 'pipe'] },
+    );
+    const wsUrl = await new Promise((ok, fail) => {
+      let buf = '';
+      const timer = setTimeout(() => fail(new Error('Chrome did not start')), 15000);
+      proc.stderr.on('data', (d) => {
+        buf += d;
+        const m = /DevTools listening on (ws:\/\/\S+)/.exec(buf);
+        if (m) {
+          clearTimeout(timer);
+          ok(m[1]);
+        }
+      });
+      proc.on('exit', () => fail(new Error('Chrome exited during startup')));
+    });
+    const ws = new WebSocket(wsUrl);
+    await new Promise((ok, fail) => {
+      ws.onopen = ok;
+      ws.onerror = () => fail(new Error('could not connect to Chrome'));
+    });
+    return new Browser(proc, ws, profile);
+  }
+
+  constructor(proc, ws, profile) {
+    this.proc = proc;
+    this.ws = ws;
+    this.profile = profile;
+    this.nextId = 1;
+    this.pending = new Map();
+    this.listeners = new Set();
+    ws.onmessage = (e) => {
+      const msg = JSON.parse(e.data);
+      if (msg.id && this.pending.has(msg.id)) {
+        const { ok, fail } = this.pending.get(msg.id);
+        this.pending.delete(msg.id);
+        msg.error ? fail(new Error(msg.error.message)) : ok(msg.result);
+      } else for (const l of this.listeners) l(msg);
+    };
+    // If Chrome goes away, nothing waits for it forever.
+    ws.onclose = () => {
+      this.closed = true;
+      for (const { fail } of this.pending.values()) fail(new Error('Chrome went away'));
+      this.pending.clear();
+    };
+  }
+
+  send(method, params = {}, sessionId, timeout = 30000) {
+    if (this.closed) return Promise.reject(new Error('Chrome went away'));
+    const id = this.nextId++;
+    this.ws.send(JSON.stringify({ id, method, params, sessionId }));
+    return new Promise((ok, fail) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        fail(new Error(`Chrome did not answer ${method}`));
+      }, timeout);
+      this.pending.set(id, { ok: (v) => (clearTimeout(timer), ok(v)), fail: (e) => (clearTimeout(timer), fail(e)) });
+    });
+  }
+
+  waitFor(method, sessionId, timeout) {
+    return new Promise((ok) => {
+      const timer = setTimeout(() => done(null), timeout);
+      const listener = (msg) => msg.method === method && msg.sessionId === sessionId && done(msg.params);
+      const done = (v) => {
+        clearTimeout(timer);
+        this.listeners.delete(listener);
+        ok(v);
+      };
+      this.listeners.add(listener);
+    });
+  }
+
+  async close() {
+    try {
+      this.ws.close();
+    } catch {}
+    this.proc.kill();
+    await new Promise((ok) => (this.proc.exitCode !== null ? ok() : this.proc.once('exit', ok)));
+    await rm(this.profile, { recursive: true, force: true }).catch(() => {});
+  }
+}
+
+const sigOf = (v) => JSON.stringify(v);
+
+/**
+ * The screenshots an item should have, each with a signature of what it depicts:
+ * the page as the reviewer saw it, their proposed edit, each agent option, the
+ * result once resolved, and for approvals, the guard's baseline and its check
+ * after each round (`ctx.checkAt`: when the last round came back).
+ */
+export function wantedShots(a, ctx = {}) {
+  const want = {};
+  if (a.status !== 'resolved') want.before = sigOf([a.target && a.target.selector, a.stroke && a.stroke.paths && a.stroke.paths.length]);
+  // The same moment and framing without the mark: what Review lays over the page as "before".
+  if (a.status !== 'resolved') want.plain = want.before;
+  if (a.edits && a.status !== 'resolved') want.proposed = sigOf(a.edits);
+  for (const v of a.variants || []) want['variant-' + v.key] = sigOf(v);
+  // Once per resolution (a reopened item's next fix is a new one), not per edit of the item.
+  if (a.status === 'resolved') want.after = sigOf([a.resolution, (a.history || []).length, a.afterTarget]);
+  if (wantsBaseline(a)) want['guard-base'] = sigOf(['base', a.accepted ? 'accepted' : 'kept']);
+  if (wantsMobileBaseline(a)) want[`guard-base@${MOBILE}`] = sigOf(['base', MOBILE, a.accepted ? 'accepted' : 'kept']);
+  // Checked once per round, at each width, against a baseline taken before that round came back.
+  if (isGuarded(a) && ctx.checkAt) {
+    const base = a.guard && a.guard.base;
+    const mobile = a.guard && a.guard.mobile && a.guard.mobile.base;
+    if (base && base.at < ctx.checkAt) want['guard-now'] = sigOf(['check', ctx.checkAt]);
+    if (mobile && mobile.at < ctx.checkAt) want[`guard-now@${MOBILE}`] = sigOf(['check', MOBILE, ctx.checkAt]);
+  }
+  return want;
+}
+
+/** What the guards compare against: when the agent last closed a round. */
+export function checkContext(rounds) {
+  const last = [...((rounds && rounds.rounds) || [])].reverse().find((r) => r.returnedAt);
+  return { checkAt: last ? last.returnedAt : null };
+}
+
+export class ShotService {
+  /**
+   * @param {object} o
+   * @param {import('./store.js').Store} o.store
+   * @param {() => string} o.baseUrl  origin of the Redline server, e.g. http://127.0.0.1:4545
+   * @param {(key: string, a: object) => void} [o.onShot]  called after each saved shot
+   */
+  constructor({ store, baseUrl, onShot = () => {}, log = () => {}, chrome = findChrome() }) {
+    this.store = store;
+    this.baseUrl = baseUrl;
+    this.onShot = onShot;
+    this.log = log;
+    this.chrome = typeof WebSocket === 'function' ? chrome : null;
+    this.queue = [];
+    this.running = false;
+    this.browser = null;
+    this.idle = null;
+  }
+
+  get available() {
+    return !!this.chrome;
+  }
+
+  /** Queue a shot; `key` is before | proposed | after | variant-A… Duplicates collapse. */
+  schedule(id, key, sig) {
+    if (!this.available) return;
+    this.queue = this.queue.filter((j) => !(j.id === id && j.key === key));
+    this.queue.push({ id, key, sig });
+    this.run();
+  }
+
+  /** Queue whatever shots the items are missing, or that no longer match them. */
+  reconcile(list, ctx) {
+    for (const a of list) {
+      for (const [key, sig] of Object.entries(wantedShots(a, ctx))) {
+        const same = (j) => j && j.id === a.id && j.key === key && j.sig === sig;
+        if ((a.shotSigs || {})[key] !== sig && !this.queue.some(same) && !same(this.current)) {
+          this.schedule(a.id, key, sig);
+        }
+      }
+    }
+  }
+
+  async run() {
+    if (this.running) return;
+    this.running = true;
+    clearTimeout(this.idle);
+    try {
+      while (this.queue.length) {
+        const job = (this.current = this.queue.shift());
+        try {
+          await this.capture(job.id, job.key, job.sig);
+        } catch (err) {
+          this.log(`screenshot ${job.id} ${job.key} failed: ${err.message}`);
+        }
+      }
+      this.current = null;
+    } finally {
+      this.running = false;
+      // Keep Chrome warm between bursts of feedback, then let it go.
+      this.armIdle();
+    }
+  }
+
+  /**
+   * Photograph item `id` for `key` (before | after | … | guard-base | guard-now, with
+   * "@390" for a phone width) and record it. `dry`: record nothing, write no file,
+   * just return what the page reported ({ fp, box, … }), or null if the element is gone.
+   */
+  async capture(id, key, sig = '', { dry = false } = {}) {
+    const a = await this.store.get(id);
+    if (!a) return null;
+    // Queued a while ago: skip it if the item moved on (a "before" of an item that is fixed by now).
+    if (!key.startsWith('guard-') && sig && wantedShots(a)[key] !== sig) return null;
+    const [kind, at] = key.split('@');
+    const width = at ? Number(at) : 0;
+    clearTimeout(this.idle); // not while a capture is on
+    // One Chrome, however many captures start at once.
+    if (!this.browser) {
+      this.launching ??= Browser.launch(this.chrome).then((browser) => (this.browser = browser)).finally(() => (this.launching = null));
+      await this.launching;
+    }
+    const b = this.browser;
+    const { targetId } = await b.send('Target.createTarget', { url: 'about:blank' });
+    const { sessionId } = await b.send('Target.attachToTarget', { targetId, flatten: true });
+    this.inflight = (this.inflight || 0) + 1;
+    try {
+      const w = width || Math.round(a.viewport?.w || 1280), h = width ? 844 : Math.round(a.viewport?.h || 800);
+      await b.send('Emulation.setDeviceMetricsOverride', { width: w, height: h, deviceScaleFactor: 1, mobile: w < 768 }, sessionId);
+      await b.send('Page.enable', {}, sessionId);
+      await b.send('Page.addScriptToEvaluateOnNewDocument', { source: `window.__REDLINE_SHOT__ = ${JSON.stringify({ id, key })};` }, sessionId);
+      const loaded = b.waitFor('Page.loadEventFired', sessionId, 20000);
+      await b.send('Page.navigate', { url: this.baseUrl() + a.page + (a.url || '') }, sessionId);
+      await loaded;
+      const { result } = await b.send(
+        'Runtime.evaluate',
+        {
+          expression: `new Promise((done) => {
+            const give = setTimeout(() => done(null), 15000);
+            const wait = () => window.__redlineShotReady ? window.__redlineShotReady.then((r) => { clearTimeout(give); done(r); }) : setTimeout(wait, 50);
+            wait();
+          })`,
+          awaitPromise: true,
+          returnByValue: true,
+        },
+        sessionId,
+      );
+      const found = result && result.value;
+      if (dry) return found || null;
+      if (!found) {
+        // An approval that can't be found anymore is itself a finding; one that isn't
+        // shown at phone width simply isn't guarded there.
+        if (kind === 'guard-now') this.onShot(key, await this.store.setGuardCheck(id, null, null, sig, width));
+        else if (kind === 'guard-base' && width) return this.store.setGuardBase(id, null, null, sig, null, width);
+        throw new Error('page did not get ready (is the element still there?)');
+      }
+      const { fp, box, ...clip } = found;
+      const shot = await b.send(
+        'Page.captureScreenshot',
+        { format: 'png', clip: { ...clip, scale: 1 }, captureBeyondViewport: true },
+        sessionId,
+      );
+      await mkdir(join(this.store.dir, 'shots'), { recursive: true });
+      const file = `shots/${id}-${key.replace('@', '-at')}.png`;
+      await writeFile(join(this.store.dir, file), Buffer.from(shot.data, 'base64'));
+      const updated = kind === 'guard-base' ? await this.store.setGuardBase(id, file, fp, sig, box, width)
+        : kind === 'guard-now' ? await this.store.setGuardCheck(id, file, fp, sig, width)
+        : await this.store.setShot(id, key, file, sig, box);
+      this.onShot(key, updated);
+      return file;
+    } finally {
+      await b.send('Target.closeTarget', { targetId }).catch(() => {});
+      this.inflight--;
+      if (!this.running) this.armIdle();
+    }
+  }
+
+  // One idle timer at a time: a stray one would close Chrome under a capture.
+  armIdle() {
+    clearTimeout(this.idle);
+    this.idle = setTimeout(() => !this.running && !this.inflight && this.stopBrowser(), 60000);
+    this.idle.unref?.();
+  }
+
+  async stopBrowser() {
+    const b = this.browser;
+    this.browser = null;
+    if (b) await b.close();
+  }
+
+  async close() {
+    clearTimeout(this.idle);
+    this.queue = [];
+    await this.stopBrowser();
+  }
+}