@broberg/lens-daemon 0.0.0-stage → 0.1.0

package/src/record-run.ts

@@ -0,0 +1,427 @@
+// F312.25 — ONE recording implementation, reachable through TWO doors.
+//
+// This was the body of `app.post('/lens/record')` in index.ts and nothing else.
+// It moved out unchanged (only the Hono response wrappers became plain values)
+// so the MCP verb and the HTTP route cannot drift: F095.15 is this repo's
+// precedent — a rule present through move_card and absent through update_card,
+// correct-looking from either side, and it took a peer repo to notice.
+//
+// The alternative was a second handler in mcp.ts that "does the same thing".
+// It would have been right on the day it was written.
+
+import { readFile, writeFile, mkdtemp, rm } from 'node:fs/promises';
+import * as nodePath from 'node:path';
+import { tmpdir } from 'node:os';
+import { loadManifest } from './manifest.ts';
+import { recordSurface, scrollUpBy } from './record.ts';
+import { defects, measureExercise } from './motion-probe.ts';
+import { cutFrames } from './frames.ts';
+import { authPrepare, type AuthConfig } from './auth/index.ts';
+
+export type RecordDeps = {
+  config: { port: number; sandbox_roots?: string[] };
+  storage: { put(key: string, bytes: Uint8Array | Buffer): Promise<unknown> };
+};
+
+/** Every knob the recorder takes. Kept as one type so the MCP schema and the
+ *  HTTP route describe the same call rather than two overlapping ones. */
+export type RecordRequest = Record<string, unknown>;
+
+export async function runRecord(raw: RecordRequest, deps: RecordDeps) {
+  const { config, storage: lensStorage } = deps;
+  const body = raw as {
+    project?: string;
+    url?: string;
+    seconds?: number;
+    selector?: string;
+    row_attr?: string;
+    interval_ms?: number;
+    min_delta_px?: number;
+    viewport?: { width: number; height: number };
+    reduced_motion?: 'reduce' | 'no-preference';
+    local_path?: string;
+    auth?: unknown;
+    fps?: number;
+    /** Cut a dense burst around each finding, at this fps. 0 disables. */
+    burst_fps?: number;
+    /** F312.5 — testid PREFIX of a field to focus and type into throughout. */
+    type_into?: string;
+    /**
+     * F312.9 — SEND A MESSAGE INTO THE CHAT EVERY N MS WHILE RECORDING.
+     *
+     * Christian, and he is right that it should have been obvious: a recording of
+     * a stream that never moves proves nothing, and waiting for one to move by
+     * luck is not an experiment. Two 120s runs of the same build gave 4 findings
+     * and then 0 — the second window was simply quiet, and the exercise check
+     * (F312.8) correctly refused to call it a result.
+     *
+     * The generator removes the luck: the run produces its own traffic, at a
+     * fixed cadence, so every recording is comparable to every other one.
+     */
+    send_every_ms?: number;
+    /** F312.10 — scroll UP this far before watching: HIS situation, not the bottom. */
+    scroll_up_px?: number;
+    /** F312.11 — ms after each generated send to put the view BACK up. */
+    rescroll_after_ms?: number;
+    /** F312.13 — send from a SECOND tab, so the watched one never sends at all. */
+    traffic_tab?: boolean;
+    /**
+     * F312.16 — FEED THE SESSION, not the page. Christian's correction, and it
+     * closes the last hole in the experiment: a message typed into the composer
+     * is the page's OWN echo, and a second browser tab's messages were measured
+     * never arriving at all (3 sends, 0 landings). Neither is what he complains
+     * about, which is the AGENT writing while he sits still. Driving the tmux
+     * pane makes the agent produce genuine streamed output, and the watched tab
+     * does nothing but read.
+     */
+    feed_tmux?: string;
+    feed_every_ms?: number;
+    /** F312.20 — press controls DURING the recording, so "does this button do
+     *  what it claims" becomes a reading instead of an argument. A SEQUENCE,
+     *  because the interesting questions are two-step: leave a tab and come
+     *  back, open a thing and close it. One click can only ask half of those. */
+    clicks?: { testid: string; at_ms: number }[];
+    /** F312.21 — seed the chat's open-tab set so a tab SWITCH can be driven. */
+    seed_tabs?: { session: string; channel?: string; label?: string }[];
+  };
+  if (!body.url) return { ok: false as const, status: 400, error: 'url required' };
+  const project = body.project ?? 'lens';
+  try {
+    let auth = body.auth as AuthConfig | undefined;
+    if (!auth && body.local_path) {
+      try {
+        auth = loadManifest(body.local_path, config.sandbox_roots ?? []).auth as AuthConfig | undefined;
+      } catch {
+        auth = undefined; // no manifest → an anonymous recording, said by omission
+      }
+    }
+    const runId = crypto.randomUUID();
+    // F312.16 — what we FED, with UTC send times, kept beside what the probe SAW.
+    // Declared BEFORE the run because the feeder closure below writes to it.
+    const feedLog: { marker: string; sentAt: number; error?: string }[] = [];
+    // F312.20 — what we PRESSED and whether the press landed at all.
+    const clickLog: { testid: string; at_ms: number; pressed: boolean }[] = [];
+    const result = await recordSurface({
+      url: body.url,
+      // F312.5 — put the caret in a field and KEEP TYPING while we watch. The
+      // worst version of this defect is the one where the ground moves
+      // mid-sentence, and it cannot be reproduced by a browser sitting still.
+      // F312.9 — the traffic generator. Runs WHILE the probe watches, and its
+      // sends deliberately do NOT stamp the driver clock: a message arriving is
+      // exactly the event under test, so a move it causes must stay reportable.
+      // F312.20 — press a control mid-recording. The click is NOT driver-stamped:
+      // pressing Now is the user asking to be moved, so the move it causes must
+      // stay fully reportable — and the ledger then says whether the app obeyed,
+      // refused, or never heard the press at all. Those are three different
+      // answers and a screenshot gives none of them.
+      ...(body.clicks && body.clicks.length > 0
+        ? {
+            during: async (page: import('playwright').Page, seconds: number) => {
+              const end = seconds * 1000;
+              let now = 0;
+              for (const c of [...body.clicks!].sort((a, b) => a.at_ms - b.at_ms)) {
+                const at = Math.min(Math.max(500, c.at_ms), end - 200);
+                if (at > now) await page.waitForTimeout(at - now);
+                now = at;
+                const ok = await page
+                  .locator(`[data-testid="${c.testid}"]`)
+                  .first()
+                  .click({ timeout: 5000 })
+                  .then(() => true)
+                  .catch(() => false);
+                // A press that never landed and a press the app refused are
+                // different answers; the second is a finding and the first is a
+                // broken test. Recorded, never inferred.
+                clickLog.push({ testid: c.testid, at_ms: at, pressed: ok });
+              }
+              await page.waitForTimeout(Math.max(0, end - now));
+            },
+          }
+        : {}),
+      // F312.16 — the tmux feeder. Drives the AGENT, then the agent's own output
+      // streams into the watched tab. Nothing is typed into the page.
+      ...(body.feed_tmux
+        ? {
+            during: async (page: import('playwright').Page, seconds: number) => {
+              // The pane name comes over the wire, so it is validated rather than
+              // interpolated on trust — session:window.pane and nothing else.
+              const pane = body.feed_tmux!;
+              if (!/^[A-Za-z0-9_-]{1,64}:\d{1,3}\.\d{1,3}$/.test(pane)) {
+                feedLog.push({ marker: 'invalid-target', sentAt: Date.now(), error: pane.slice(0, 40) });
+                await page.waitForTimeout(seconds * 1000);
+                return;
+              }
+              const every = Math.max(3000, body.feed_every_ms ?? 8000);
+              const end = Date.now() + seconds * 1000;
+              let n = 0;
+              while (Date.now() < end) {
+                await page.waitForTimeout(every);
+                if (Date.now() >= end) break;
+                n += 1;
+                const marker = `LENSPROBE-${runId.slice(0, 6)}-${n}`;
+                const sentAt = Date.now();
+                try {
+                  const { spawn } = await import('node:child_process');
+                  await new Promise<void>((resolve) => {
+                    const t = spawn('tmux', [
+                      'send-keys',
+                      '-t',
+                      pane,
+                      `${marker} — automatisk måletrafik fra Lens Video. Svar KUN med: ${marker} ok`,
+                      'Enter',
+                    ]);
+                    t.on('error', () => resolve());
+                    t.on('close', () => resolve());
+                  });
+                  feedLog.push({ marker, sentAt });
+                } catch (e) {
+                  feedLog.push({
+                    marker,
+                    sentAt,
+                    error: e instanceof Error ? e.message.slice(0, 120) : String(e).slice(0, 120),
+                  });
+                }
+              }
+            },
+          }
+        : {}),
+      ...(body.send_every_ms && body.send_every_ms > 0
+        ? {
+            during: async (page: import('playwright').Page, seconds: number) => {
+              const every = Math.max(2000, body.send_every_ms!);
+              const end = Date.now() + seconds * 1000;
+              let n = 0;
+              // F312.13 — THE SENDER MUST NOT BE THE WATCHED TAB.
+              //
+              // Sending is itself a fair reason to snap to the bottom, and the
+              // owner's complaint is the opposite case: he sits STILL, the agent
+              // writes, and the view moves. A generator that sends from the tab
+              // being measured can never show that — measured 6 Sept, every
+              // remaining move landed within 600ms of its own send, i.e. inside
+              // the snap he asked for. Sending from a second tab in the same
+              // browser context puts real traffic on the channel while the
+              // watched tab does nothing but read.
+              // F312.13 — COUNT THE SENDS. "0 content events" cannot otherwise be
+              // told apart from "the generator never managed to send anything",
+              // and the second reads as a clean result while proving nothing.
+              const sendTally = { attempted: 0, sent: 0, failed: 0, lastError: null as string | null };
+              (globalThis as { __lensSends?: typeof sendTally }).__lensSends = sendTally;
+              const sender = body.traffic_tab && body.url ? await page.context().newPage() : page;
+              if (sender !== page) {
+                // Follow the WATCHED tab's own address, not the one we were given.
+                // The app writes the picked edge/session/channel into the URL once
+                // it has resolved them, so copying it puts both tabs on the same
+                // conversation. Measured 6 Sept: two tabs opened on a bare /chat
+                // each picked their own channel — 3 sends, 0 arrivals, and the run
+                // reported "the surface did not move".
+                await sender.goto(page.url(), { waitUntil: 'domcontentloaded', timeout: 30_000 });
+                await sender.waitForTimeout(3500);
+                await page.bringToFront();
+              }
+              while (Date.now() < end) {
+                await page.waitForTimeout(every);
+                if (Date.now() >= end) break;
+                n += 1;
+                sendTally.attempted += 1;
+                try {
+                  // FOCUS, never CLICK. A pointerdown stamps the probe's
+                  // scroll-intent clock, so clicking the composer made the
+                  // generator label its own arrivals as "he scrolled" — measured:
+                  // 13 of 15 moves misattributed that way.
+                  const box = sender.locator('[data-testid="chat-send-task-input"]').first();
+                  await box.focus({ timeout: 4000 });
+                  await box.fill(`lens-video probe ${n} — ${'x'.repeat(40 + ((n * 17) % 400))}`);
+                  await sender.keyboard.press('Meta+Enter').catch(() => {});
+                  await sender.locator('[data-testid="chat-send-task-btn"]').first().dispatchEvent('click').catch(() => {});
+                  if (sender !== page) await page.bringToFront();
+                  // F312.11 — THE DISCRIMINATOR. Pressing send is itself a fair
+                  // reason to go to the bottom, so a run that only sends can
+                  // never tell "content arrived and moved me" apart from "I sent
+                  // and it followed". Putting the view back up mid-stream — and
+                  // stamping it as the driver's own — makes every later move in
+                  // that window an answer to the question actually being asked.
+                  if (body.rescroll_after_ms && body.scroll_up_px) {
+                    await page.waitForTimeout(body.rescroll_after_ms);
+                    await scrollUpBy(page, body.selector ?? null, body.scroll_up_px);
+                  }
+                  // 'sent' means the COMPOSER CLEARED — an exception-free run of
+                  // the locators proves the elements existed, not that a message
+                  // left. That distinction is the same false green this whole
+                  // feature exists to remove.
+                  const cleared = await box.inputValue().then((v) => v === '').catch(() => false);
+                  if (cleared) sendTally.sent += 1;
+                  else {
+                    sendTally.failed += 1;
+                    sendTally.lastError = 'composer did not clear — the message never left';
+                  }
+                } catch (e) {
+                  // A send that fails must not end the recording — but it MUST be
+                  // COUNTED, or a run that sent nothing looks like a surface that
+                  // did not move. Measured 6 Sept: a second-tab generator sent
+                  // zero messages and the run reported "0 content events", which
+                  // reads as a result and was an instrument failure.
+                  sendTally.failed += 1;
+                  sendTally.lastError = e instanceof Error ? e.message.slice(0, 200) : String(e).slice(0, 200);
+                }
+              }
+            },
+          }
+        : {}),
+      ...(body.type_into
+        ? {
+            before: async (page: import('playwright').Page) => {
+              const el = page.locator(`[data-testid^="${body.type_into}"]`).first();
+              await el.click({ timeout: 8000 }).catch(() => {});
+            },
+            during: async (page: import('playwright').Page, seconds: number) => {
+              const el = page.locator(`[data-testid^="${body.type_into}"]`).first();
+              const end = Date.now() + seconds * 1000;
+              while (Date.now() < end) {
+                await el.type('svar ', { delay: 120 }).catch(() => {});
+              }
+            },
+          }
+        : {}),
+      seconds: Math.min(300, Math.max(1, body.seconds ?? 30)),
+      ...(body.seed_tabs && body.seed_tabs.length > 0 ? { seedTabs: body.seed_tabs } : {}),
+      ...(body.scroll_up_px ? { scrollUpPx: body.scroll_up_px } : {}),
+      ...(body.selector ? { selector: body.selector } : {}),
+      ...(body.row_attr ? { rowAttr: body.row_attr } : {}),
+      ...(body.interval_ms ? { intervalMs: body.interval_ms } : {}),
+      ...(body.min_delta_px != null ? { minDeltaPx: body.min_delta_px } : {}),
+      ...(body.viewport ? { viewport: body.viewport } : {}),
+      ...(body.reduced_motion ? { reducedMotion: body.reduced_motion } : {}),
+      ...(auth ? { prepareContext: authPrepare(auth, process.env) } : {}),
+    });
+
+    let videoUrl: string | null = null;
+    if (result.video) {
+      const key = `${project}/recordings/${runId}/run.webm`;
+      await lensStorage.put(key, result.video);
+      videoUrl = `http://127.0.0.1:${config.port}/lens/artifact?key=${encodeURIComponent(key)}`;
+    }
+
+    // Frames are DERIVED and cut only when there is a video to cut. ffmpeg missing
+    // degrades to "video, no stills" — it never fails the run, because the probe
+    // timeline is the primary result and it is already in hand.
+    const frames: { t: number; url: string; near_finding?: number }[] = [];
+    let framesUnavailable: string | null = null;
+    if (result.video) {
+      const dir = await mkdtemp(nodePath.join(tmpdir(), 'lens-frames-'));
+      const vid = nodePath.join(dir, 'run.webm');
+      await writeFile(vid, result.video);
+      const cuts: { t: number; file: string; near?: number }[] = [];
+      const sparse = await cutFrames(vid, nodePath.join(dir, 'sparse'), { fps: body.fps ?? 2 });
+      if (sparse.unavailable) framesUnavailable = sparse.unavailable;
+      cuts.push(...sparse.frames.map((f) => ({ t: f.t, file: f.file })));
+      const burstFps = body.burst_fps ?? 12;
+      if (burstFps > 0 && !sparse.unavailable) {
+        for (const [i, f] of result.findings.slice(0, 3).entries()) {
+          const from = Math.max(0, f.t - 700);
+          const b = await cutFrames(vid, nodePath.join(dir, `burst-${i}`), {
+            fps: burstFps,
+            fromMs: from,
+            durationMs: 1600,
+          });
+          cuts.push(...b.frames.map((x) => ({ t: x.t, file: x.file, near: i })));
+        }
+      }
+      for (const cut of cuts) {
+        const key = `${project}/recordings/${runId}/f-${String(cut.t).padStart(7, '0')}${cut.near != null ? `-b${cut.near}` : ''}.png`;
+        await lensStorage.put(key, await readFile(cut.file));
+        frames.push({
+          t: cut.t,
+          url: `http://127.0.0.1:${config.port}/lens/artifact?key=${encodeURIComponent(key)}`,
+          ...(cut.near != null ? { near_finding: cut.near } : {}),
+        });
+      }
+      await rm(dir, { recursive: true, force: true }).catch(() => {});
+    }
+
+    return {
+      ok: true as const,
+      status: 200,
+      run_id: runId,
+      duration_ms: result.durationMs,
+      watched: result.watched,
+      probe_error: result.probeError,
+      samples: result.samples.length,
+      // F312.8 — a zero finding is only a RESULT if the surface was exercised.
+      // Two identical runs of the same build gave 4 findings then 0, because the
+      // second window was quiet. Never let that read as "fixed".
+      exercise: measureExercise(result.samples),
+      // F312.18 — false means the run proves NOTHING. Zero findings from a blind
+      // camera and zero from a fixed product are the same number; this is the
+      // only thing that separates them.
+      detector_alive: result.detectorAlive,
+      self_test: result.selfTest,
+      seed: result.seed,
+      clicks: clickLog,
+      // F312.19 — the headline number. A move nobody caused AND the reader could
+      // SEE. Every finding is still returned below; this is what "is it broken"
+      // means, so a reader does not have to know to filter.
+      defect_count: defects(result.findings).length,
+      // What the GENERATOR managed, kept separate from what the SURFACE did.
+      sends: (globalThis as { __lensSends?: unknown }).__lensSends ?? null,
+      // F312.16 — SENT vs LANDED, per marker. `landed_ms` is null when a fed
+      // message never reached the screen at all, which is a different and much
+      // worse answer than a slow one — and the pair is the only way to tell them
+      // apart. Times are UTC epoch ms; latency_ms is what the reader waited.
+      feed: feedLog.map((f) => {
+        const seen = result.markers[f.marker];
+        return {
+          marker: f.marker,
+          sent_at_utc: new Date(f.sentAt).toISOString(),
+          landed_ms: seen ?? null,
+          latency_ms: seen == null ? null : Math.max(0, result.probeStartedAt + seen - f.sentAt),
+          ...(f.error ? { error: f.error } : {}),
+        };
+      }),
+      // F312.12 — the page's own account of who moved the view. Line an entry up
+      // with a finding's at_ms and the call site stops being an argument.
+      ledger: result.ledger,
+      // The finding carries WHAT moved and WHEN — never merely that something did.
+      findings: result.findings.map((f, i) => ({
+        index: i,
+        at_ms: f.t,
+        from: f.from,
+        to: f.to,
+        delta: f.delta,
+        direction: f.delta < 0 ? 'backwards' : 'forwards',
+        first_row_before: f.firstRowBefore,
+        first_row_after: f.firstRowAfter,
+        content_changed: f.contentChanged,
+        // F312.7 — the discriminator: did the browser CLAMP him because the
+        // content above shrank, or did something actively move him?
+        clamped: f.clamped,
+        // F312.14 — how far the PICTURE moved. 0 with a large delta means the
+        // anchor held his message still while content shifted around it.
+        visible_shift: f.visibleShift,
+        // F312.23 — the second, independent read on the same move: where HIS row
+        // sat versus where the app promised to hold it. `visible_shift` goes null
+        // on exactly the big jumps that matter; this does not.
+        anchor_drift_before: f.anchorDriftBefore,
+        anchor_drift_after: f.anchorDriftAfter,
+        anchor_state_before: f.anchorStateBefore,
+        anchor_state_after: f.anchorStateAfter,
+        // F312.24 — 0 means the layout was rigid and the VIEW moved; a number
+        // means the ground moved under him. Same visible_shift either way.
+        layout_spread: f.layoutSpread,
+        rows_before: f.rowsBefore,
+        rows_after: f.rowsAfter,
+        first_row_y_before: f.firstRowYBefore,
+        first_row_y_after: f.firstRowYAfter,
+        max_before: f.maxBefore,
+        max_after: f.maxAfter,
+        cause: f.cause,
+        since_input: f.sinceInput,
+        while_typing: f.whileTyping,
+      })),
+      video_url: videoUrl,
+      frames,
+      ...(framesUnavailable ? { frames_unavailable: framesUnavailable } : {}),
+    };
+  } catch (err) {
+    return { ok: false as const, status: 400, error: err instanceof Error ? err.message : String(err) };
+  }
+}