@broberg/lens-daemon 0.0.0-stage → 0.1.0

package/src/capture.ts

@@ -0,0 +1,348 @@
+// F074.1 — Lens capture core.
+//
+// Stateless toward the project: give it a URL + a command, get back a
+// screenshot (+ metadata). Three modes:
+//   - viewport : the visible 1280×800 (default) window
+//   - fullPage : the entire scrollable page
+//   - element  : crop to a single [data-testid] (the preferred, stable mode)
+//
+// Element mode takes a FULL-PAGE screenshot then Sharp-crops to the element's
+// bounding box with Math.round on the float coords. This avoids the cms
+// pitfall where getBoundingClientRect() floats handed straight to an image
+// crop throw "extract_area: bad extract area" — and avoids Playwright's
+// locator.screenshot() re-scroll jitter that makes element shots non-
+// deterministic for pixel-diffing.
+//
+// F074.2 extracts navigateAndAct() + takeShot() so verify.ts can reuse the
+// exact same page lifecycle (one page visit → screenshot AND assert AND
+// console/network) without duplicating navigation logic.
+
+import sharp from 'sharp';
+import type { Page } from 'playwright';
+import { withPage, type WithPageOptions, type LensEngine } from './browser.ts';
+import { authPrepare, type AuthConfig } from './auth/index.ts';
+import { runCritic, type CriticMode, type CriticReport } from './critic.ts';
+import type { VisionModelKey } from './critic-vision.ts';
+import { fillAndVerify } from './fill.ts';
+import { storagePayload, type StorageSeed } from './seed-storage.ts';
+
+export type CaptureMode = 'viewport' | 'fullPage' | 'element';
+
+export interface CaptureAction {
+  type: 'click' | 'fill' | 'scrollTo' | 'waitFor';
+  /** CSS selector — a [data-testid="…"] is preferred (the strict contract). */
+  selector?: string;
+  /** Value for `fill`. */
+  value?: string;
+  /** Per-action timeout (ms). Default 5000. */
+  timeout?: number;
+}
+
+export interface CaptureOptions {
+  url: string;
+  mode?: CaptureMode;
+  /** Required for `element` mode. Prefer `[data-testid="…"]`. */
+  selector?: string;
+  /** F098.9 — engine to drive (chromium default; webkit/firefox for cross-engine bugs). */
+  engine?: LensEngine;
+  viewport?: { width: number; height: number };
+  deviceScaleFactor?: number;
+  /** F098.6 — navigation settle strategy. Default 'domcontentloaded': fires once
+   *  the HTML is parsed, BEFORE sub-resources — so a live-data / streaming /
+   *  canvas SPA where the `load` event never fires (a never-finishing request,
+   *  long-poll, video, rAF-driven asset) can't hang `goto` to its timeout.
+   *  Content readiness is handled by the explicit `waitFor` gate below. A static
+   *  surface that genuinely needs the full load can override with 'load'. */
+  waitUntil?: 'load' | 'domcontentloaded' | 'commit';
+  /** Wait gate after navigation + actions: a selector to wait for, or ms to sleep. */
+  waitFor?: string | number;
+  /** Pre-capture interactions (click/fill/scrollTo/waitFor), run in order. */
+  actions?: CaptureAction[];
+  /** F074.69 — load an unpacked browser extension and capture its OWN pages.
+   *  Write the url as `extension://popup.html`; the generated id is substituted
+   *  after the browser reports it, because a caller cannot know it in advance. */
+  extension?: { path: string };
+  /** Navigation + overall timeout (ms). Default 30000. */
+  timeoutMs?: number;
+  /** F074.4 hook — inject auth into the context before the page loads.
+   *  Lower-level than `auth`; set directly only in-process. */
+  prepareContext?: WithPageOptions['prepareContext'];
+  /** F074.4 — declarative auth pre-step (storageState | cookieJwt). The
+   *  secret is resolved from the daemon env by name, never carried here. */
+  auth?: AuthConfig;
+  /** F074.97 — localStorage/sessionStorage written BEFORE the first navigation,
+   *  so a bug that only exists in SAVED CLIENT STATE (a restored tab strip, a
+   *  remembered filter, a dismissed banner, a seven-day-old timestamp) can be
+   *  photographed instead of only unit-fixtured. Scoped to this url's own origin;
+   *  omitted registers no init script at all. */
+  storage?: StorageSeed;
+  /** F126.4 — composition critic to run on the captured surface. 'off' (default)
+   *  = none; 'dom' = free geometry; 'vision' = metered model; 'both'. Geometry is
+   *  always safe to run; vision is gated by the caller (the F095 gate reads the
+   *  project's composition_critic.vision setting). */
+  critic?: CriticMode;
+  /** F126.4 — vision model for the critic's vision pass ('haiku' default | 'sonnet').
+   *  Only used when critic includes vision; the gate sets it from the project's
+   *  composition_critic.vision_model setting. */
+  criticVisionModel?: VisionModelKey;
+}
+
+/** Pick the context-preparation callback: an explicit prepareContext wins,
+ *  else the declarative `auth` adapter, else none. */
+export function resolvePrepareContext(opts: {
+  prepareContext?: WithPageOptions['prepareContext'];
+  auth?: AuthConfig;
+}): WithPageOptions['prepareContext'] {
+  return opts.prepareContext ?? authPrepare(opts.auth);
+}
+
+export interface Shot {
+  screenshot: Buffer;
+  width: number;
+  height: number;
+  /** Element box (element mode only), rounded to the integer crop applied. */
+  elementBox: { x: number; y: number; width: number; height: number } | null;
+}
+
+export interface CaptureResult extends Shot {
+  url: string;
+  mode: CaptureMode;
+  selector: string | null;
+  title: string;
+  /** Final URL after any redirects. */
+  finalUrl: string;
+  /** Uncaught page errors observed during the capture (reported, non-fatal). */
+  pageErrors: string[];
+  durationMs: number;
+  /** F126.4 — composition-critic findings, when a critic was requested. */
+  critic: CriticReport | null;
+  /** F074.69 — the loaded extension and the id Chromium generated for it, so a
+   *  caller can cite the surface it photographed. Null on an ordinary capture. */
+  extension: { id: string; path: string } | null;
+}
+
+export async function runActions(page: Page, actions: CaptureAction[]): Promise<void> {
+  for (const a of actions) {
+    const timeout = a.timeout ?? 5000;
+    switch (a.type) {
+      case 'click':
+        if (!a.selector) throw new Error('action "click" requires a selector');
+        await page.locator(a.selector).first().click({ timeout });
+        break;
+      case 'fill':
+        if (!a.selector) throw new Error('action "fill" requires a selector');
+        // F213.7 — the card named capture-session; this is the THIRD executor of the
+        // same verb and would have kept the defect alive on the capture path.
+        await fillAndVerify(page.locator(a.selector).first(), a.value ?? '', timeout);
+        break;
+      case 'scrollTo':
+        if (!a.selector) throw new Error('action "scrollTo" requires a selector');
+        await page.locator(a.selector).first().scrollIntoViewIfNeeded({ timeout });
+        break;
+      case 'waitFor':
+        if (!a.selector) throw new Error('action "waitFor" requires a selector');
+        await page.locator(a.selector).first().waitFor({ state: 'visible', timeout });
+        break;
+      default:
+        throw new Error(`unknown action type: ${(a as CaptureAction).type}`);
+    }
+  }
+}
+
+/** Navigate + run pre-capture actions + apply the wait gate. Shared by
+ *  capture() and verify() so the page lifecycle is identical. */
+export async function navigateAndAct(page: Page, opts: CaptureOptions): Promise<void> {
+  const timeoutMs = opts.timeoutMs ?? 30_000;
+  // F098.6 — default 'domcontentloaded', NOT 'load' (and never 'networkidle').
+  // 'networkidle' never settles on an SPA with a persistent SSE/websocket
+  // (cardmem's authed routes open EventSource). 'load' ALSO hangs on live-data
+  // pages where a sub-resource never finishes (media archive, video, long-poll,
+  // canvas rAF) — it blocked the daemon fleet-wide (upmetrics/trail, 2026-06-05).
+  // 'domcontentloaded' fires once the HTML is parsed; the explicit `waitFor`
+  // gate below + document.fonts.ready handle content readiness. Override
+  // per-surface with waitUntil:'load' for a static page that needs it.
+  await page.goto(opts.url, { waitUntil: opts.waitUntil ?? 'domcontentloaded', timeout: timeoutMs });
+  if (opts.actions?.length) await runActions(page, opts.actions);
+  if (typeof opts.waitFor === 'number') {
+    await page.waitForTimeout(opts.waitFor);
+  } else if (typeof opts.waitFor === 'string') {
+    // A numeric string ("800") is an ms timeout that the MCP boundary stringified,
+    // NOT a CSS selector — an all-digits string is never a valid selector and
+    // would throw "parsing css selector 800". Treat it as page.waitForTimeout.
+    const trimmed = opts.waitFor.trim();
+    if (/^\d+$/.test(trimmed)) {
+      await page.waitForTimeout(Number(trimmed));
+    } else {
+      await page.locator(opts.waitFor).first().waitFor({ state: 'visible', timeout: timeoutMs });
+    }
+  }
+  await settleForShot(page);
+}
+
+/** F094.7 + F255.3 — everything that must finish before a frame is worth photographing.
+ *  Extracted so FLOW screenshots run it too: they used to call takeShot() directly, so a
+ *  step fired right after a click photographed the page mid-transition. On the F249
+ *  mockups list that meant a just-ticked checkbox (transition: background 0.12s) was
+ *  captured still white while the DOM said checked — a picture that made a working
+ *  feature look broken, which is worse than no picture at all. */
+export async function settleForShot(page: Page): Promise<void> {
+  // Wait for web fonts to finish loading before any screenshot, so the baseline and a
+  // later capture always render text with the SAME font. A FOUT (fallback font rendered
+  // at capture time) otherwise yields a large, false text-diff on identical content.
+  await page.evaluate(async () => {
+    await document.fonts.ready;
+    // Let CSS transitions/animations SETTLE before the shot. A drawer with a
+    // 240ms slide-in would otherwise be captured mid-slide (translateX
+    // off-screen) → a false "closed" screenshot (components, 2026-06-10). Wait
+    // for FINITE animations to finish, but cap the wait so an INFINITE one
+    // (spinner, looping rAF-less CSS) can't hang the capture, then a couple
+    // rAF frames so the final committed frame is painted.
+    const anims = (document.getAnimations?.() ?? []).filter((a) => {
+      const iters = a.effect?.getComputedTiming?.().iterations;
+      return iters !== Infinity;
+    });
+    await Promise.race([
+      Promise.all(anims.map((a) => a.finished.catch(() => {}))),
+      new Promise((r) => setTimeout(r, 600)),
+    ]);
+    await new Promise<void>((r) => requestAnimationFrame(() => requestAnimationFrame(() => r())));
+  }).catch(() => {});
+  await page.waitForTimeout(120);
+}
+
+/** F255.2 — the element crop, as pure arithmetic so it can be tested without a browser.
+ *  `box` is the element's rect in DOCUMENT css-pixels plus the page's devicePixelRatio;
+ *  `img` is the full-page shot's real pixel size. The shot is in DEVICE pixels, so a
+ *  scale:2 capture needs the css rect multiplied by 2 before cropping. Everything is
+ *  clamped inside the image so a rect that ends past the bottom edge still yields a valid
+ *  (if shorter) crop instead of throwing inside Sharp. */
+export function cropRect(
+  box: { x: number; y: number; width: number; height: number; dpr?: number },
+  img: { width?: number; height?: number },
+): { left: number; top: number; width: number; height: number } {
+  const dpr = box.dpr && box.dpr > 0 ? box.dpr : 1;
+  const imgW = img.width ?? 0;
+  const imgH = img.height ?? 0;
+  const left = Math.max(0, Math.min(Math.round(box.x * dpr), Math.max(0, imgW - 1)));
+  const top = Math.max(0, Math.min(Math.round(box.y * dpr), Math.max(0, imgH - 1)));
+  const width = Math.max(1, Math.min(Math.round(box.width * dpr), imgW - left));
+  const height = Math.max(1, Math.min(Math.round(box.height * dpr), imgH - top));
+  return { left, top, width, height };
+}
+
+/** Take the screenshot per mode. Element mode = full-page shot Sharp-cropped
+ *  to the rounded bounding box (the cms float-coord pitfall fix). */
+export async function takeShot(
+  page: Page,
+  mode: CaptureMode,
+  selector: string | null,
+  timeoutMs: number,
+): Promise<Shot> {
+  if (mode === 'element') {
+    if (!selector) throw new Error('element mode requires a selector (prefer [data-testid="…"])');
+    const locator = page.locator(selector).first();
+    await locator.waitFor({ state: 'visible', timeout: timeoutMs });
+    await locator.scrollIntoViewIfNeeded({ timeout: timeoutMs });
+    // F255.2 — read the rect in DOCUMENT coordinates, not viewport coordinates.
+    // The shot below is fullPage (document space) while Playwright's boundingBox()
+    // is relative to the VIEWPORT, so cropping the one with the other photographed
+    // whatever happened to be scrolled into that spot: three far-apart elements on
+    // a long page all came back as md5-identical pictures of the top of the page
+    // (fd-sundhed, 2026-07-18). Adding the scroll offset makes the two spaces agree.
+    // devicePixelRatio is read in the same call because a scale:2 capture renders a
+    // 2× PNG while the rect stays CSS pixels — the crop must be scaled to match.
+    const box = await locator.evaluate((el) => {
+      const r = el.getBoundingClientRect();
+      return {
+        x: r.left + window.scrollX,
+        y: r.top + window.scrollY,
+        width: r.width,
+        height: r.height,
+        dpr: window.devicePixelRatio || 1,
+      };
+    });
+    if (!box || box.width === 0 || box.height === 0) {
+      throw new Error(`element not visible / has no box: ${selector}`);
+    }
+
+    const full = await page.screenshot({ fullPage: true });
+    const crop = cropRect(box, await sharp(full).metadata());
+    const screenshot = await sharp(full).extract(crop).png().toBuffer();
+    return {
+      screenshot,
+      width: crop.width,
+      height: crop.height,
+      elementBox: { x: crop.left, y: crop.top, width: crop.width, height: crop.height },
+    };
+  }
+
+  const screenshot = await page.screenshot({ fullPage: mode === 'fullPage' });
+  const meta = await sharp(screenshot).metadata();
+  return { screenshot, width: meta.width ?? 0, height: meta.height ?? 0, elementBox: null };
+}
+
+/** F074.69 — rewrite the `extension://` shorthand once the id is known.
+ *
+ *  Exported for test, and deliberately strict about the failure: asking for an
+ *  extension url WITHOUT loading an extension is a mistake that would otherwise
+ *  produce a navigation error deep inside Chromium and read as a flaky capture. */
+export function resolveExtensionUrl(url: string, id: string | undefined): string {
+  if (!url.startsWith('extension://')) return url;
+  if (!id) {
+    throw new Error(
+      'an extension:// url needs an extension to resolve against — pass extension:{path:"…"} ' +
+        'so Lens can load it and read back the id Chromium generates.',
+    );
+  }
+  return `chrome-extension://${id}/${url.slice('extension://'.length)}`;
+}
+
+export async function capture(opts: CaptureOptions): Promise<CaptureResult> {
+  const startedAt = Date.now();
+  const mode: CaptureMode = opts.mode ?? 'viewport';
+  const timeoutMs = opts.timeoutMs ?? 30_000;
+  if (mode === 'element' && !opts.selector) {
+    throw new Error('element mode requires a selector (prefer [data-testid="…"])');
+  }
+
+  return withPage(
+    {
+      engine: opts.engine,
+      viewport: opts.viewport,
+      deviceScaleFactor: opts.deviceScaleFactor,
+      prepareContext: resolvePrepareContext(opts),
+      seedStorage: storagePayload(opts.storage, opts.url),
+      extension: opts.extension,
+    },
+    async (page, _context, extension) => {
+      const pageErrors: string[] = [];
+      page.on('pageerror', (err) => pageErrors.push(err.message));
+
+      // F074.69 — `extension://popup.html` becomes `chrome-extension://<id>/popup.html`
+      // only once the browser has told us the id. Substituting here rather than
+      // asking the caller for it is the point: the id is generated at load time,
+      // so a manuscript that hardcoded one would work until it did not.
+      await navigateAndAct(page, { ...opts, url: resolveExtensionUrl(opts.url, extension?.id) });
+      const title = await page.title();
+      const finalUrl = page.url();
+      const shot = await takeShot(page, mode, opts.selector ?? null, timeoutMs);
+      const critic =
+        opts.critic && opts.critic !== 'off'
+          ? await runCritic(page, shot.screenshot, opts.critic, opts.criticVisionModel)
+          : null;
+
+      return {
+        url: opts.url,
+        mode,
+        selector: opts.selector ?? null,
+        ...shot,
+        title,
+        finalUrl,
+        pageErrors,
+        durationMs: Date.now() - startedAt,
+        critic,
+        extension: extension ?? null,
+      };
+    },
+  );
+}