feat(capture): re-add the full-page plate a scroll shot needs, at 1x

`product-launch-video` tells a scroll shot to animate a viewport over a full-page
capture. No such file existed: capture emits 15 viewport-sized scroll-position
tiles, and a plate is not substitutable by tiles — a viewport travelling down one
continuous image is the whole point.

An earlier `full-page.png` was dropped in 62b5517 because 1/8 agents read it and
the contact sheet covered the same ground. That measured it as a *comprehension*
artifact, on an eval where nothing was building scroll shots. The scroll shot is a
different consumer, so this brings the plate back — but not as it was, because two
things have to hold for it to be worth having:

- **Taken last.** After the scroll traversal, so lazy images have loaded and
  scroll-triggered reveals have fired. A plate shot on arrival is full of blank
  bands, which is a good reason for an agent to look once and never again.
- **Sticky chrome neutralised.** `fullPage` bakes a fixed header in at one
  position, freezing a nav across the middle of the plate. The viewport tiles keep
  sticky on purpose (natural browsing state); the plate cannot. Positions are
  recorded and restored in a `finally`, so the extraction passes that run afterwards
  see an unmodified DOM.

**1x, deliberately.** 2x is what you'd want to push in without softening text, but
doubling a long marketing page passes Chrome's 16384px screenshot cap precisely on
the pages that most want a scroll shot (linear.app: 10962 CSS px → 21924 at 2x). At
1x a 1920-wide plate is pixel-exact for a 1920x1080 viewport. A frame that needs
headroom captures its own region at 2x instead. Pages over the cap get no plate
rather than a silently clipped one, and the caller falls back to the tiles.

Validation: `vitest run src/capture` — 90 pass (5 new) · oxlint/oxfmt clean ·
`tsc --noEmit` clean

Author: WaterrrForever

packages/cli/src/capture/screenshotCapture.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, it, vi } from "vitest";
+import { existsSync, mkdtempSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Page } from "puppeteer-core";
+import { captureFullPagePlate, MAX_PLATE_HEIGHT_PX } from "./screenshotCapture.js";
+
+// The mocks declare their parameters so `mock.calls[i][0]` is a real slot — a zero-arg
+// vi.fn() types its call tuple as [] and indexing it is a compile error.
+function fakePage(overrides: Record<string, unknown> = {}) {
+  const evaluate = vi.fn(async (_script?: unknown) => undefined);
+  const screenshot = vi.fn(async (_opts?: unknown) => Buffer.from("PNG-BYTES"));
+  return { page: { evaluate, screenshot, ...overrides } as unknown as Page, evaluate, screenshot };
+}
+
+describe("captureFullPagePlate — the scroll shot's plate", () => {
+  it("writes one full-page png and returns its relative path", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "hf-plate-"));
+    const { page, screenshot } = fakePage();
+
+    const out = await captureFullPagePlate(page, dir, 10962);
+
+    expect(out).toBe("screenshots/full-page.png");
+    expect(screenshot).toHaveBeenCalledWith({ type: "png", fullPage: true });
+    expect(readFileSync(join(dir, "full-page.png"), "utf8")).toBe("PNG-BYTES");
+  });
+
+  it("stays 1x: it never touches the viewport's deviceScaleFactor", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "hf-plate-"));
+    const setViewport = vi.fn(async () => undefined);
+    const { page } = fakePage({ setViewport });
+
+    await captureFullPagePlate(page, dir, 4000);
+
+    // A 2x plate would exceed the cap on exactly the long pages that want a scroll shot.
+    expect(setViewport).not.toHaveBeenCalled();
+  });
+
+  it("skips a page taller than Chrome can capture, instead of writing a clipped plate", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "hf-plate-"));
+    const { page, screenshot } = fakePage();
+
+    const out = await captureFullPagePlate(page, dir, MAX_PLATE_HEIGHT_PX + 1);
+
+    expect(out).toBeNull();
+    expect(screenshot).not.toHaveBeenCalled();
+    expect(existsSync(join(dir, "full-page.png"))).toBe(false);
+  });
+
+  it("neutralises sticky/fixed chrome for the shot and restores it afterwards", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "hf-plate-"));
+    const { page, evaluate, screenshot } = fakePage();
+
+    await captureFullPagePlate(page, dir, 8000);
+
+    const scripts = evaluate.mock.calls.map((c) => String(c[0]));
+    expect(scripts).toHaveLength(2);
+    // Neutralise first — a fixed header would otherwise bake in mid-plate.
+    expect(scripts[0]).toContain("'fixed'");
+    expect(scripts[0]).toContain("'sticky'");
+    expect(scripts[0]).toContain("data-hf-plate-position");
+    // Then hand the page back unchanged: the caller keeps reading the DOM after this.
+    expect(scripts[1]).toContain("removeAttribute");
+    expect(scripts[1]).toContain("data-hf-plate-position");
+    expect(evaluate.mock.invocationCallOrder[0]).toBeLessThan(
+      screenshot.mock.invocationCallOrder[0]!,
+    );
+    expect(screenshot.mock.invocationCallOrder[0]).toBeLessThan(
+      evaluate.mock.invocationCallOrder[1]!,
+    );
+  });
+
+  it("restores the page even when the screenshot throws", async () => {
+    const dir = mkdtempSync(join(tmpdir(), "hf-plate-"));
+    const screenshot = vi.fn(async (_opts?: unknown) => {
+      throw new Error("capture failed");
+    });
+    const { page, evaluate } = fakePage({ screenshot });
+
+    await expect(captureFullPagePlate(page, dir, 8000)).rejects.toThrow("capture failed");
+    // A page left with every sticky element forced static would corrupt the extraction
+    // passes that run after this one.
+    expect(String(evaluate.mock.calls.at(-1)?.[0])).toContain("removeAttribute");
+  });
+});

packages/cli/src/capture/screenshotCapture.ts

@@ -21,6 +21,62 @@ import { join } from "node:path";
  * elements — screenshots show the page in its natural browsing state with
  * scroll-triggered animations fired.
  */
+/**
+ * Chrome caps a screenshot at 16384px per side (Skia's max texture dimension); past that the
+ * capture comes back clipped or fails outright. Long marketing pages do reach this.
+ */
+export const MAX_PLATE_HEIGHT_PX = 16384;
+
+/**
+ * One tall image of the whole document — the plate a scroll shot slides its viewport over.
+ *
+ * This is deliberately 1x. A 2x plate is what you'd want for pushing in without softening
+ * text, but doubling a long marketing page blows past `MAX_PLATE_HEIGHT_PX` exactly on the
+ * pages that most want a scroll shot; a frame that needs 2x should capture its own region
+ * instead. At 1x a 1920-wide plate is pixel-exact for a 1920x1080 viewport travelling down it.
+ *
+ * Two things have to be true for the plate to be usable, and both are why the earlier
+ * `full-page.png` was worth removing rather than keeping as-is:
+ *  · It must be taken AFTER the scroll traversal, so lazy images have loaded and
+ *    scroll-triggered reveals have fired. A plate shot on arrival is full of blank bands.
+ *  · Sticky/fixed chrome has to be neutralised first. `fullPage` bakes a fixed header in at
+ *    one position, so a nav ends up frozen across the middle of the plate. The viewport
+ *    shots keep sticky on purpose (natural browsing state); the plate cannot.
+ *
+ * Returns the relative path, or null when the page is too tall to capture in one piece.
+ */
+export async function captureFullPagePlate(
+  page: Page,
+  screenshotsDir: string,
+  scrollHeight: number,
+): Promise<string | null> {
+  if (scrollHeight > MAX_PLATE_HEIGHT_PX) return null;
+
+  // Record the inline value before overwriting so the page is handed back unchanged — the
+  // caller keeps using it (asset extraction, DOM reads) after this returns.
+  await page.evaluate(
+    `document.querySelectorAll('*').forEach((el) => {
+      const p = getComputedStyle(el).position;
+      if (p === 'fixed' || p === 'sticky') {
+        el.setAttribute('data-hf-plate-position', el.style.position || '');
+        el.style.position = 'static';
+      }
+    })`,
+  );
+  try {
+    const buffer = await page.screenshot({ type: "png", fullPage: true });
+    writeFileSync(join(screenshotsDir, "full-page.png"), buffer);
+    return "screenshots/full-page.png";
+  } finally {
+    await page.evaluate(
+      `document.querySelectorAll('[data-hf-plate-position]').forEach((el) => {
+        el.style.position = el.getAttribute('data-hf-plate-position');
+        el.removeAttribute('data-hf-plate-position');
+      })`,
+    );
+  }
+}
+
 export async function captureScrollScreenshots(page: Page, outputDir: string): Promise<string[]> {
   const screenshotsDir = join(outputDir, "screenshots");
   mkdirSync(screenshotsDir, { recursive: true });
@@ -151,7 +207,13 @@ export async function captureScrollScreenshots(page: Page, outputDir: string): P
     await page.evaluate(`window.scrollTo(0, 0)`);
     await new Promise((r) => setTimeout(r, 200));
 
-    // full-page.png removed — 1/8 agents read it, contact sheet covers the same content
+    // The scroll plate, last: everything above has loaded the page and fired its reveals, which
+    // is the only state a full-page shot is worth taking in. (An earlier full-page.png was
+    // dropped because 1/8 agents read it and the contact sheet covered the same ground — that
+    // was about it as a *comprehension* artifact. The scroll shot is a different consumer: it
+    // needs one continuous plate, which no set of viewport tiles can substitute for.)
+    const plate = await captureFullPagePlate(page, screenshotsDir, scrollHeight);
+    if (plate) filePaths.push(plate);
   } catch {
     /* scroll screenshots are non-critical */
   }