@broberg/lens-daemon 0.0.0-stage → 0.1.0

package/src/ensure-chromium.ts

@@ -0,0 +1,118 @@
+// lens-gap 019efc0e — the daemon self-provisions its OWN pinned Chromium.
+//
+// Why this exists: the daemon pins playwright (see apps/agent/package.json) to a
+// specific build revision (e.g. chromium-1223) and resolves the browser under its
+// OWN PLAYWRIGHT_BROWSERS_PATH. An operator who runs an ambient
+// `npx/bunx playwright install chromium` installs whatever revision THAT
+// playwright resolves — a different revision/path than the daemon expects — so
+// captures still fail with a vague "not installed" (the exact trap that cost the
+// cb-2 operator time: install ran, daemon still red). The fix: the daemon installs
+// from its OWN pinned playwright CLI, inheriting its OWN env, so it lands exactly
+// the revision + path it looks in. Manual install becomes unnecessary.
+
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { chromium } from 'playwright';
+
+export interface ChromiumExpectation {
+  installed: boolean;
+  /** Absolute path the daemon's pinned playwright resolves the chromium binary to. */
+  execPath: string | null;
+  /** The browsers root the daemon reads (PLAYWRIGHT_BROWSERS_PATH, or the OS default). */
+  browsersPath: string;
+  /** The pinned build-revision folder (e.g. "chromium-1223"), parsed from execPath. */
+  revision: string | null;
+}
+
+const DEFAULT_BROWSERS_PATH = '~/Library/Caches/ms-playwright (macOS default)';
+
+/** What Chromium does the daemon expect, and is it on disk? Pure + cheap:
+ *  executablePath() only COMPUTES the path; it does not check the binary exists. */
+export function chromiumExpectation(): ChromiumExpectation {
+  let execPath: string | null = null;
+  try {
+    execPath = chromium.executablePath();
+  } catch {
+    execPath = null;
+  }
+  const installed = Boolean(execPath) && existsSync(execPath as string);
+  const revision = execPath?.match(/chromium[_-][0-9]+/)?.[0] ?? null;
+  return {
+    installed,
+    execPath,
+    browsersPath: process.env.PLAYWRIGHT_BROWSERS_PATH || DEFAULT_BROWSERS_PATH,
+    revision,
+  };
+}
+
+/** The caller-actionable reason a capture can't run — names the EXACT revision +
+ *  path THIS daemon looks in, not a generic command that may install elsewhere. */
+export function chromiumGapReason(exp: ChromiumExpectation): string {
+  const rev = exp.revision ? ` (${exp.revision})` : '';
+  return (
+    `Chromium${rev} not installed where this daemon looks. ` +
+    `Expected binary: ${exp.execPath ?? '(unresolved)'} · browsers root: ${exp.browsersPath}. ` +
+    `The daemon is self-provisioning it now (its own pinned playwright → matching revision) — ` +
+    `retry the capture in ~30s. To install manually, run from the cardmem repo root: ` +
+    `bunx playwright install chromium`
+  );
+}
+
+// Single in-flight install — never spawn two concurrent ~150MB downloads. A
+// failed install resets so a later trigger can retry, but it never loops itself.
+let inFlight: Promise<{ ok: boolean; error?: string }> | null = null;
+
+/** Resolve the daemon's OWN pinned playwright CLI entry. `playwright/cli.js` is
+ *  the package's bin but is NOT in its `exports` map (ERR_PACKAGE_PATH_NOT_EXPORTED),
+ *  so resolve via package.json (which IS exported) + join the sibling cli.js. */
+function resolvePlaywrightCli(): string {
+  const require = createRequire(import.meta.url);
+  const pkgJson = require.resolve('playwright/package.json');
+  return join(dirname(pkgJson), 'cli.js');
+}
+
+/** Ensure the daemon's pinned Chromium is on disk, installing it via the daemon's
+ *  OWN playwright CLI (inherits env → exact revision + path). Idempotent + deduped;
+ *  resolves immediately when already installed. Never throws. */
+export function ensureChromium(): Promise<{
+  ok: boolean;
+  error?: string;
+  alreadyInstalled?: boolean;
+}> {
+  const exp = chromiumExpectation();
+  if (exp.installed) return Promise.resolve({ ok: true, alreadyInstalled: true });
+  if (inFlight) return inFlight;
+
+  inFlight = new Promise<{ ok: boolean; error?: string }>((resolve) => {
+    let cliPath: string;
+    try {
+      cliPath = resolvePlaywrightCli();
+    } catch (err) {
+      resolve({
+        ok: false,
+        error: `cannot resolve playwright CLI: ${err instanceof Error ? err.message : String(err)}`,
+      });
+      return;
+    }
+    console.log(
+      `[lens] Chromium missing (${exp.revision ?? '?'}, expected ${exp.execPath}) — self-provisioning via ${cliPath} …`,
+    );
+    const child = spawn(process.execPath, [cliPath, 'install', 'chromium'], {
+      stdio: 'inherit',
+      env: process.env,
+    });
+    child.on('error', (err) => resolve({ ok: false, error: err.message }));
+    child.on('exit', (code) => {
+      const ok = code === 0 && chromiumExpectation().installed;
+      if (ok) console.log('[lens] Chromium self-provisioned ✓');
+      else console.warn(`[lens] Chromium self-provision failed (exit ${code})`);
+      resolve(ok ? { ok: true } : { ok: false, error: `playwright install exited ${code}` });
+    });
+  }).finally(() => {
+    inFlight = null;
+  });
+
+  return inFlight;
+}

package/src/export.ts

@@ -0,0 +1,256 @@
+// F074.63 — lens_export: HTML → a vector PDF, where text stays text.
+//
+// Raised by fd-sundhed with a customer deadline: information material for
+// Aalborg Kommune lives as an HTML mockup, and the municipality's own graphic
+// designer has to be able to correct the text. The only path before this was
+// lens_capture PNGs stitched into a PDF — the owner opened that in Illustrator
+// and counted ONE <Linked File> and ZERO text objects. It is a picture of a
+// document, so nothing in it can be edited.
+//
+// It could not be rescued with more pixels either: `scale` is capped by the
+// daemon's pixel limit (scale 8 on A3 → "Input image exceeds pixel limit",
+// ~16M px), which puts the ceiling at 257 DPI against a 300 DPI print spec. A
+// vector PDF has no resolution at all, so that constraint does not get pushed
+// back — it stops existing.
+//
+// This is deliberately the CAPTURE pipeline with one terminal call changed:
+// withPage → navigateAndAct → settle, then page.pdf() instead of
+// page.screenshot(). A second navigation/auth implementation would drift from
+// capture() the first time either was touched.
+import type { Page } from 'playwright';
+import { withPage } from './browser.ts';
+import { navigateAndAct, resolvePrepareContext, settleForShot, type CaptureOptions } from './capture.ts';
+import { collectFn } from '@broberg/lens-svg';
+import { paperMm, serializeSvg, lintSvg, PAPER_SIZES, type SvgNode } from '@broberg/lens-svg';
+
+export type ExportFormat = 'pdf' | 'svg';
+
+/** Which CSS media the page is rendered as.
+ *
+ *  This is the single most likely way an export ships looking broken while
+ *  being technically correct. Playwright's page.pdf() renders PRINT media, so a
+ *  page designed for screen can lose its entire layout to an @media print rule
+ *  — and nothing errors, so the caller gets a confident, wrong PDF. We default
+ *  to 'screen' so the caller gets what they SEE unless they ask otherwise. */
+export type ExportMedia = 'screen' | 'print';
+
+export interface ExportMargin {
+  top?: string;
+  right?: string;
+  bottom?: string;
+  left?: string;
+}
+
+export interface ExportOptions
+  extends Omit<CaptureOptions, 'mode' | 'critic' | 'criticVisionModel'> {
+  /** F074.64 — SVG only: export ONE surface, not the whole mockup document. A
+   *  print job is one sheet; a mockup page holds five. Ignored by the PDF path,
+   *  which has no element mode. */
+  selector?: string;
+  /** Which match to take when the selector hits several — a bifold folder has two
+   *  sheets under one class. Default 0. */
+  selectorIndex?: number;
+  format?: ExportFormat;
+  /** Paper size — 'A3', 'A4', 'Letter', … Passed to Playwright's `format`. */
+  pageSize?: string;
+  landscape?: boolean;
+  /** Default TRUE, deliberately against Playwright's own default of false:
+   *  with backgrounds off, every background colour and image disappears and an
+   *  A3 poster comes out white — a silently ruined deliverable that still
+   *  reports success. */
+  printBackground?: boolean;
+  margin?: ExportMargin;
+  media?: ExportMedia;
+}
+
+export interface ExportResult {
+  bytes: Buffer;
+  /** F074.64 — what the SVG path could and could not represent. Null for PDF. */
+  svg?: {
+    counts: { text: number; rect: number; image: number; unsupported: number };
+    unsupported: Array<{ reason: string; locator: string }>;
+    lint: { outOfBounds: Array<{ what: string; detail: string }>; malformed: string[] };
+  } | null;
+  format: ExportFormat;
+  pageSize: string;
+  landscape: boolean;
+  media: ExportMedia;
+  printBackground: boolean;
+  title: string;
+  finalUrl: string;
+  pageErrors: string[];
+  durationMs: number;
+}
+
+/** page.pdf() exists on Chromium ONLY. Firefox and WebKit do not implement it.
+ *
+ *  This throws rather than degrading, and the reason matters: falling back to a
+ *  screenshot would hand back EXACTLY the bitmap this whole card exists to
+ *  replace, wearing a .pdf extension — the worst available outcome, because it
+ *  would look like the fix had landed. */
+export function assertEngineCanExport(engine: string | undefined | null): void {
+  const e = (engine ?? 'chromium').toLowerCase();
+  if (e !== 'chromium') {
+    throw new Error(
+      `lens_export requires engine:'chromium' — PDF generation is a Chromium-only capability ` +
+        `and ${e} cannot do it. Refusing rather than returning a screenshot renamed .pdf, ` +
+        `which is the un-editable bitmap this tool exists to replace.`,
+    );
+  }
+}
+
+/** The `%PDF-` magic. Cheap, and it separates "we wrote bytes" from "we wrote a
+ *  PDF" — two different claims. */
+export function looksLikePdf(bytes: Buffer): boolean {
+  return bytes.length > 5 && bytes.subarray(0, 5).toString('latin1') === '%PDF-';
+}
+
+/** Read the FIRST /MediaBox out of a PDF, in PostScript points (1/72").
+ *
+ *  Chromium emits page dictionaries in cleartext, so this needs no parser and no
+ *  dependency. Returns null when it cannot find one — a null must be reported as
+ *  "not measured", never defaulted to a plausible size, or an assertion on page
+ *  geometry would pass on a PDF whose geometry was never read. */
+export function readMediaBox(bytes: Buffer): { widthPt: number; heightPt: number } | null {
+  const m = bytes
+    .toString('latin1')
+    .match(/\/MediaBox\s*\[\s*(-?[\d.]+)\s+(-?[\d.]+)\s+(-?[\d.]+)\s+(-?[\d.]+)\s*\]/);
+  if (!m) return null;
+  const w = Number(m[3]) - Number(m[1]);
+  const h = Number(m[4]) - Number(m[2]);
+  if (!Number.isFinite(w) || !Number.isFinite(h) || w <= 0 || h <= 0) return null;
+  return { widthPt: w, heightPt: h };
+}
+
+/** Points → millimetres, for comparing against a paper size a human named. */
+export function ptToMm(pt: number): number {
+  return (pt / 72) * 25.4;
+}
+
+/** The resolved defaults, as a PURE function.
+ *
+ *  Split out of exportPage so the defaults can be SEALED without launching a
+ *  browser. Two of them deviate from what the library would do on its own —
+ *  printBackground true (Playwright says false) and media 'screen' (page.pdf()
+ *  renders print) — and both deviations are invisible when wrong: the poster
+ *  comes out white, or laid out by a print stylesheet, and the export still
+ *  reports success. A default that only lives inside a call nothing can reach
+ *  without Chromium is a default a library upgrade can quietly take back. */
+export interface ResolvedExportOptions {
+  format: ExportFormat;
+  media: ExportMedia;
+  pageSize: string;
+  landscape: boolean;
+  printBackground: boolean;
+}
+
+export function resolveExportOptions(opts: Partial<ExportOptions> = {}): ResolvedExportOptions {
+  return {
+    format: opts.format ?? 'pdf',
+    media: opts.media ?? 'screen',
+    pageSize: opts.pageSize ?? 'A4',
+    landscape: opts.landscape ?? false,
+    printBackground: opts.printBackground ?? true,
+  };
+}
+
+export async function exportPage(opts: ExportOptions): Promise<ExportResult> {
+  const startedAt = Date.now();
+  assertEngineCanExport(opts.engine);
+
+  const { format, media, pageSize, landscape, printBackground } = resolveExportOptions(opts);
+
+  return withPage(
+    {
+      engine: 'chromium',
+      viewport: opts.viewport,
+      deviceScaleFactor: opts.deviceScaleFactor,
+      prepareContext: resolvePrepareContext(opts),
+    },
+    async (page: Page) => {
+      const pageErrors: string[] = [];
+      page.on('pageerror', (err) => pageErrors.push(err.message));
+
+      await navigateAndAct(page, opts as CaptureOptions);
+      // The same settle the screenshot path uses (fonts, images, animations) —
+      // a PDF taken mid-webfont-swap renders in the fallback face, which is a
+      // silent visual regression a designer WILL notice and we would not.
+      await settleForShot(page);
+
+      // Must come before pdf(): page.pdf() renders print media unless the page
+      // has been told otherwise.
+      await page.emulateMedia({ media });
+
+      const title = await page.title();
+      const finalUrl = page.url();
+
+      // F074.64 — SVG is read from the LIVE DOM, before anything becomes a PDF.
+      // By PDF time a heading is a run of glyphs with a coordinate per letter;
+      // here it is still one element with one string, one font and one box.
+      if (format === 'svg') {
+        const paper = paperMm(pageSize, landscape);
+        if (!paper) {
+          throw new Error(
+            `lens_export format:'svg' needs a known paper size to emit millimetres; ` +
+              `'${pageSize}' is not one of ${Object.keys(PAPER_SIZES).join(', ')}. ` +
+              `A pixel-unit SVG is a screenshot with editable text, so this refuses ` +
+              `rather than guessing the physical size of the page.`,
+          );
+        }
+        const collected = (await page.evaluate(collectFn(opts.selector ?? null, opts.selectorIndex ?? 0))) as {
+          nodes: SvgNode[];
+          pageWidthPx: number;
+          pageHeightPx: number;
+        };
+        // The page's own rendered width IS the paper width — that is what the
+        // caller laid the mockup out to. Everything else scales from it.
+        const pxPerMm = collected.pageWidthPx / paper.widthMm;
+        const out = serializeSvg(collected.nodes, paper, pxPerMm);
+        const lint = lintSvg(out.svg, collected.nodes, paper, pxPerMm);
+        return {
+          bytes: Buffer.from(out.svg, 'utf8'),
+          svg: {
+            counts: out.counts,
+            // F074.66 — everything EXCEPT the internal discriminator, rather than a
+            // hand-written field list. The list version silently dropped `count` the
+            // moment the collector started producing it, which is this card's own
+            // defect one layer further out: the report is assembled correctly and a
+            // boundary quietly narrows it.
+            unsupported: out.unsupported.map(({ kind: _kind, ...rest }) => rest),
+            lint,
+          },
+          format,
+          pageSize,
+          landscape,
+          media,
+          printBackground,
+          title,
+          finalUrl,
+          pageErrors,
+          durationMs: Date.now() - startedAt,
+        };
+      }
+
+      const bytes = await page.pdf({
+        format: pageSize,
+        landscape,
+        printBackground,
+        ...(opts.margin ? { margin: opts.margin } : {}),
+      });
+
+      return {
+        bytes,
+        svg: null,
+        format,
+        pageSize,
+        landscape,
+        media,
+        printBackground,
+        title,
+        finalUrl,
+        pageErrors,
+        durationMs: Date.now() - startedAt,
+      };
+    },
+  );
+}

package/src/fill.ts

@@ -0,0 +1,149 @@
+// F213.7 — a fill that cannot prove its own write is not a write.
+//
+// sanne measured this against a React-controlled <textarea> on a live surface: the
+// first fill lost its FIRST character, a second fill landed IN FRONT of the old value
+// (`ABCDEF-1234IDLERTIDIG-…`), and fill("") did not clear the field. All three
+// returned SUCCESS, because Playwright's fill() resolves when it has driven the
+// element — nothing asks the element what it now holds.
+//
+// WHY THAT IS CRITICAL RATHER THAN ANNOYING: cardmem shipped a hard rule to 29 repos
+// saying a save is only proven by READING THE VALUE BACK, and that you must also prove
+// the field can be EMPTY. `fill("")` silently not clearing is exactly that negative
+// control — so the instrument the fleet was told to verify saves with could not run
+// the half of the check that catches the worst failure.
+//
+// MEASURED BEFORE WRITING ANY OF THIS (the card blocked on it): NO layer translates
+// the verb `fill` into the engine's `type`/pressSequentially. All four executors call
+// Playwright's fill() directly — flow.ts, capture-session.ts, capture.ts, and
+// @broberg/lens-engine's own flow. So the read-back is deliberately
+// FRAMEWORK-AGNOSTIC and CAUSE-AGNOSTIC: it does not try to detect React, and it does
+// not depend on knowing which layer misbehaves. It asserts the only thing that
+// matters — after we drove the element, does it hold what we asked for?
+//
+// ────────────────────────────────────────────────────────────────────────────────────
+// THE REACH OF THIS GUARD — read this before trusting a green fill (F213.8).
+//
+// It asks the ELEMENT. The element is not the APPLICATION. A green read-back proves the
+// DOM node holds your value; it does NOT prove the page received it.
+//
+// sanne measured exactly that gap the day this shipped (lens-gap 01a01491):
+//
+//     fillSelector input[type=time] = 07:15  →  element.value === '07:15'   ← green here
+//     the app's own state                    →  still '10:00'
+//     the save request body                  →  still '10:00'
+//     the file on disk after a reload        →  still '10:00'
+//
+// The page had finished painting ~1.5–2s before its scripts began listening, and the
+// change never arrived afterwards (checked for 8s — it does not settle). Browsers render
+// form controls themselves, so the value is there to read back whether or not anything
+// is listening. Playwright's actionability checks do not cover it either: visible,
+// enabled, stable, unobscured — "the application is listening" is not on that list.
+//
+// So: a green fill means "the field holds it", never "the write landed". To prove the
+// latter, assert on what the APP did — the request it sent, the row it stored, the value
+// after a reload.
+//
+// ── F213.8 SHIPPED THE GUARD FOR THE OTHER HALF: `waitForReady` ─────────────────────
+//
+// Put it BEFORE the first interaction and the flow waits until something is actually
+// registered for input/change on the target's propagation path — not a fixed sleep,
+// and no framework detection:
+//
+//     { type: 'waitForReady', testid: 'start-time' }
+//     { type: 'fill',         testid: 'start-time', value: '07:15' }
+//
+// MEASURED on a page that starts listening 3s after paint (input-only listener, the
+// React-controlled shape):
+//
+//     without the gate  element 07:15 · app state 10:00   ← green fill, write LOST
+//     with the gate     element 07:15 · app state 07:15   ← gate waited 3039ms
+//     already listening gate returned in 35ms             ← not a blanket delay
+//
+// IT DOES NOT REPLACE THIS READ-BACK, and neither replaces asserting on the stored row.
+// Three different questions: waitForReady asks "can the app hear me", the read-back asks
+// "does the field hold it", and only the app's own request/row/reload answers "did the
+// write land". A flow that needs the last one still has to ask for it.
+//
+// TWO ACCIDENTAL PROTECTIONS FOUND WHILE MEASURING — do not rely on either. `click`'s
+// actionability work (sanne, #21295) and, on an `<input type=time>`, a late `change`
+// fired on blur AFTER hydration both rescue an early write by luck. They are why this
+// defect looks intermittent, and why the first fixture for it silently passed.
+// ────────────────────────────────────────────────────────────────────────────────────
+
+/**
+ * The minimal shape this needs. Deliberately structural rather than Playwright's
+ * concrete `Locator`: capture-session drives a narrow duck-typed page so its runner
+ * stays unit-testable with a fake, and a concrete type here would have forced a cast
+ * at exactly the call site the read-back is meant to protect.
+ */
+export interface FillableLocator {
+  fill(value: string, opts?: { timeout?: number }): Promise<void>;
+  focus(opts?: { timeout?: number }): Promise<void>;
+  press(key: string, opts?: { timeout?: number }): Promise<void>;
+  evaluate<R>(fn: (el: HTMLElement) => R, arg?: unknown, opts?: { timeout?: number }): Promise<R>;
+}
+
+/** How much of a value to show in an error before truncating. */
+const SHOWN = 120;
+
+function show(s: string): string {
+  return s.length <= SHOWN ? JSON.stringify(s) : `${JSON.stringify(s.slice(0, SHOWN))}… (${s.length} chars)`;
+}
+
+/**
+ * The message a caller has to be able to fix their flow FROM — so it names BOTH
+ * strings. "the field did not match" sends them to the source; "expected X, holds
+ * XY" shows them the corruption itself.
+ */
+export function fillMismatchMessage(want: string, got: string): string {
+  // ORDER MATTERS, and getting it wrong is how the most important message goes
+  // missing: EVERY string `startsWith('')`, so with the prefix test first the
+  // clear-refused case could never be reached — and that is precisely the fleet
+  // save-rule's negative control. The empty cases are therefore checked FIRST.
+  const extra =
+    want === '' && got !== ''
+      ? ' — the field refused to clear'
+      : want !== '' && got === ''
+        ? ' — the element is empty; the write did not land'
+        : got.startsWith(want) && got.length > want.length
+          ? ` — the element kept ${show(got.slice(want.length))} behind it`
+          : got.endsWith(want) && got.length > want.length
+            ? ` — the element kept ${show(got.slice(0, got.length - want.length))} in front of it`
+            : '';
+  return `fill did not land: expected ${show(want)}, element holds ${show(got)}${extra}`;
+}
+
+/** Read what the element ACTUALLY holds — input/textarea/select and contenteditable. */
+export async function readElementValue(loc: FillableLocator, timeout: number): Promise<string> {
+  return loc.evaluate((el) => {
+    const e = el as HTMLElement & { value?: unknown };
+    if (e.isContentEditable) return e.textContent ?? '';
+    return typeof e.value === 'string' ? e.value : (e.textContent ?? '');
+  }, undefined, { timeout });
+}
+
+/**
+ * Fill, then PROVE it. On a mismatch, clear explicitly (select-all → Delete) and fill
+ * again — that recovers the shapes where fill() alone does not land — then read back
+ * once more and THROW if it still differs.
+ *
+ * The retry deliberately re-uses fill() rather than pressSequentially: typing
+ * character-by-character is the mechanism suspected of dropping the first character
+ * and writing at a caret that sits at position 0, so recovering with it would risk
+ * trading one silent corruption for another. And whatever the retry does, the final
+ * read-back stands in front of the caller — this function cannot return on a value it
+ * has not verified.
+ */
+export async function fillAndVerify(loc: FillableLocator, want: string, timeout: number): Promise<void> {
+  await loc.fill(want, { timeout });
+  if ((await readElementValue(loc, timeout)) === want) return;
+
+  // Explicit clear, for the shapes where fill() did not replace what was there.
+  await loc.focus({ timeout });
+  await loc.press('ControlOrMeta+a', { timeout });
+  await loc.press('Delete', { timeout });
+  if (want !== '') await loc.fill(want, { timeout });
+
+  const got = await readElementValue(loc, timeout);
+  if (got !== want) throw new Error(fillMismatchMessage(want, got));
+}