Skip to content

Commit e0dc255

Browse files
fix(capture,audio,docs): defects found running product-launch-video end to end (#2892)
* fix(capture,audio): three defects found running product-launch-video end to end Found while running the full product-launch-video workflow twice against a real site (linear.app) to verify PRs #2880/#2881/#2882. All three are independent of those PRs. **Scraped SVGs were unusable as files.** `assetDownloader` wrote an inline `<svg>`'s `outerHTML` straight to `assets/svgs/*.svg`. An inline SVG inherits its namespace from the HTML parser, so `outerHTML` omits `xmlns` — valid pasted back into HTML, but not a standalone document, and `<img src="logo-abc.svg">` renders a broken-image icon. That is exactly how these assets get consumed. `toStandaloneSvg` now declares the namespace on the way to disk (plus `xmlns:xlink`, but only when an `xlink:` attribute is actually used). The filename hash moved to the bytes that land on disk so it still cannot drift from content. **`sfx: none` became a cue named "none".** `fetch-sfx` split the storyboard's `sfx:` list and dropped only empty strings, so the absence marker reached the engine as a real cue that could not resolve. The absence spellings are part of the storyboard vocabulary; drop them. **`bgm_pending` was lost translating neutral meta to product-launch meta.** A detached Lyria/MusicGen generate leaves `bgm: null, bgm_pending: true` until the track lands. `toProductLaunchMeta` returned only `{bgm, voices, sfx}`, so "not ready yet" became indistinguishable from "silent by design" — and because `fetch-sfx` rewrites `audio_meta.json` from the sidecar, a still-generating bed was snapshotted away with nothing to signal it. The flag now survives, and `fetch-sfx` warns when it snapshots a pending bed instead of leaving a silent film that the storyboard claims has music. Not included, deliberately: `assemble-index.mjs` rewrites `index.html` wholesale and so discards the block `transitions.mjs inject` wrote, meaning any Step 6 rework silently loses transitions. Fixing that means deciding whether assemble preserves an injected block or inject becomes re-appliable — it touches both scripts and the Step 5/6 ordering in SKILL.md, so it deserves its own change. Validation: `node --test skills/product-launch-video/scripts/audio.test.mjs` (13 pass, 5 new) · `vitest run src/capture` (85 pass, 5 new) · `bun run lint:skills` · oxlint/oxfmt clean · `tsc --noEmit` clean * 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 * docs(product-launch-video): point the scroll shot at the plate, make handoff fields binding Two follow-ups from the same end-to-end runs, now that #2880 and #2881 have landed and their sentences exist to edit. **The scroll shot pointed at an artifact that did not exist.** #2881 said "use a 2x full-page capture and animate the viewport over it". Neither half held: capture emitted no full-page image, and 2x on a long marketing page passes Chrome's 16384px screenshot cap precisely on the pages that most want a scroll shot. Both runs watched the agent go looking, not find it, and improvise — once by re-capturing 2x strips per section, once by using the native 1920x1080 tiles full-bleed. This PR's capture commit adds the 1x plate, so the sentence can now name something real: the plate, its absence on pages too tall to capture in one piece, the tile fallback, and why pushing in past 1:1 still wants a region capture of its own. **A constant field was being read as an absent one.** #2880 asks for x/y, scale, opacity and direction/speed on every handoff. Across two runs on the same model, `opacity` went 0/12 then 12/12 — when the value never changes, leaving it out is a reasonable reading of the instruction. But downstream an omission and "there is no handoff here" are the same thing, so the field set has to be stated as binding even when constant. Same clause added to the worker's side of the contract. Validation: `bun run lint:skills` * fix(capture,audio): close the three contract gaps raised in review Review on #2892 (Rames, Magi) found the fixes correct inside the changed files but incomplete at the contract level. All three hold up against source; two of the three were reachable in production, and the plate one was self-inflicted by this PR. **The plate guard checked a stale height.** `scrollHeight` was measured before the scroll traversal and handed to the guard, but the plate is deliberately shot *after* it so lazy content has loaded — and lazy loading grows the document. The guard's input therefore read low on exactly the long pages it exists for, letting the check pass and a clipped plate through, undetectable downstream because the skill only teaches the tile fallback when the file is *absent*. `captureFullPagePlate` now measures the height itself at call time, and verifies what Chrome actually produced by reading the PNG's IHDR before writing, since the capture can trigger another round of loading. Over the cap, nothing is emitted. **Assembly dropped the flag again.** `bgm_pending` survived into `audio_meta.json` but `assemble-index.mjs` rebuilt its audio object from three named keys, so at the step that actually builds the film "not ready yet" still looked like "silent by design" — this PR's own framing of the defect, one layer further down. The flag rides along now, and a pending bed with no file raises an anomaly instead of quietly assembling a silent cut against a storyboard that promises music. **The sibling adapters had both audio bugs, and there were two of them.** The review named `faceless-explainer`; `pr-to-video` carries the same file. Its own test asserts the two are byte-identical ("intentionally identical across the reusing skills"), so fixing one alone broke that test — which is what caught the second copy. Both now carry the absence-sentinel filter and the surviving `bgm_pending`, and `faceless-explainer` gets the same five regression tests. Also from review (Miga): the sticky-restore in `finally` is wrapped, so a page that broke mid-capture cannot replace the real error with a cleanup one. Validation: `vitest run src/capture` — 95 pass (5 new) · product-launch audio 13 pass · faceless-explainer audio 10 pass (5 new, incl. the byte-identity contract) · `bun run lint:skills` · oxlint/oxfmt clean · `tsc --noEmit` clean * fix(capture,audio): meet the two review asks I under-delivered on Follow-up to 194fb69. Re-read Magi's review body rather than working from the summary, and two of the three blockers were addressed in spirit but not to the letter. **The plate probed before neutralisation, not after.** 194fb69 moved the measurement off the caller's stale value and into the function, but took it before forcing fixed/sticky elements to `static`. The review called this out specifically and is right: dropping those elements back into flow grows the document, so the probe could still read under the cap on a page that is over it once neutralised. The probe now runs after neutralisation and before the shot, inside the same `try` so restoration still happens on the early return. Added the exact case asked for — initial height under the cap, final height over it — asserting no screenshot is taken, no file is written, and the page is still handed back unmodified. **Assembly warned where the review asked it to refuse.** An anomaly in a list is not enforcement: assemble is re-run on Step 6 rework, long after the audio step's warning scrolled past, and a warning still lets a silent film out the door over a snapshot whose own JSON says the bed is generating. `assemble-index.mjs` now dies on `bgm_pending && !bgm`, with `--allow-pending-bgm` as the deliberate escape for previewing mid-generate. Pinned with three tests in a new `assemble-index.test.mjs`: refusal writes no index.html, the escape assembles and says so, and a film that is silent *by design* still assembles untouched — the distinction the flag exists to make. Validation: `vitest run src/capture` — 96 pass (6 new) · product-launch audio 13 pass · assemble-index 3 pass (new file) · faceless-explainer audio 10 pass · `bun run lint:skills` · oxlint/oxfmt clean · `tsc --noEmit` clean * fix(audio): carry the bgm_pending gate into the sibling assemblers The remaining blocker, and one this PR created: the previous commit made all three copies of the audio adapter *emit* bgm_pending, but only product-launch-video's assembler *reads* it. So faceless-explainer and pr-to-video would do exactly what this PR set out to stop — parse an audio_meta.json that says the bed is still generating and assemble the silent film without a word. Producer fixed in three places, consumer in one, is worse than neither: before this PR there was no flag to drop. Both siblings now get the same three changes product-launch-video got — the flag carried through the audio object, `die` on `bgm_pending && !bgm`, and `--allow-pending-bgm` as the deliberate escape — plus the same three tests: refusal writes no index.html, the escape assembles and says so, and a film that is silent *by design* still assembles untouched. That last one is the one worth having; it proves the flag restored a distinction rather than just adding a gate. Applied as three separate patches rather than a file copy: these assemblers have diverged (pr-to-video validates a bare `<template>` fragment where product-launch takes a `<div>` root, which its fixture reflects). `music-to-video` has the fourth copy of this assembler and is deliberately untouched: it has no audio producer, and its assembler reads `{ voices: [] }` with no bgm path at all, so the flag can never reach it. Validation: product-launch / faceless-explainer / pr-to-video assemble-index — 3 pass each · product-launch audio 13 pass · faceless-explainer audio 10 pass · `vitest run src/capture` 96 pass · `bun run lint:skills` · oxlint/oxfmt clean · `tsc --noEmit` clean
1 parent 065293e commit e0dc255

18 files changed

Lines changed: 879 additions & 22 deletions

‎packages/cli/src/capture/assetDownloader.test.ts‎

Lines changed: 37 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
import { afterEach, describe, expect, it, vi } from "vitest";
2-
import { isPrivateUrl, safeFetch } from "./assetDownloader.js";
2+
import { isPrivateUrl, safeFetch, toStandaloneSvg } from "./assetDownloader.js";
33

44
describe("isPrivateUrl — SSRF denylist (security: F-003)", () => {
55
it("blocks loopback, private, and metadata IPv4", () => {
@@ -91,3 +91,39 @@ describe("safeFetch — re-validates the denylist on every redirect hop (securit
9191
expect(fetchMock).not.toHaveBeenCalled();
9292
});
9393
});
94+
95+
describe("toStandaloneSvg — scraped inline SVGs must survive as .svg files", () => {
96+
it("adds the SVG namespace that outerHTML omits for inline SVG", () => {
97+
const inline = '<svg viewBox="0 0 24 24"><path d="M0 0h24v24H0z"/></svg>';
98+
const out = toStandaloneSvg(inline);
99+
expect(out).toContain('xmlns="http://www.w3.org/2000/svg"');
100+
// Nothing else may change — the path geometry is the brand mark.
101+
expect(out).toContain('<path d="M0 0h24v24H0z"/>');
102+
expect(out.endsWith("</svg>")).toBe(true);
103+
});
104+
105+
it("leaves an SVG that already declares xmlns untouched", () => {
106+
const already = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 8 8"><rect/></svg>';
107+
expect(toStandaloneSvg(already)).toBe(already);
108+
});
109+
110+
it("declares xmlns:xlink only when an xlink: attribute is actually used", () => {
111+
const withXlink = '<svg viewBox="0 0 8 8"><use xlink:href="#a"/></svg>';
112+
expect(toStandaloneSvg(withXlink)).toContain('xmlns:xlink="http://www.w3.org/1999/xlink"');
113+
const without = '<svg viewBox="0 0 8 8"><use href="#a"/></svg>';
114+
expect(toStandaloneSvg(without)).not.toContain("xmlns:xlink");
115+
});
116+
117+
it("is idempotent and preserves attributes on the root", () => {
118+
const inline = '<svg class="logo" width="120" height="24" fill="currentColor"><g/></svg>';
119+
const once = toStandaloneSvg(inline);
120+
expect(toStandaloneSvg(once)).toBe(once);
121+
for (const attr of ['class="logo"', 'width="120"', 'height="24"', 'fill="currentColor"']) {
122+
expect(once).toContain(attr);
123+
}
124+
});
125+
126+
it("returns non-SVG input unchanged rather than corrupting it", () => {
127+
expect(toStandaloneSvg("<div>not an svg</div>")).toBe("<div>not an svg</div>");
128+
});
129+
});

‎packages/cli/src/capture/assetDownloader.ts‎

Lines changed: 30 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,32 @@ function svgContentHashSlug(svgSource: string | Buffer, isLogo: boolean): string
1717
return isLogo ? `logo-${hash}` : `svg-${hash}`;
1818
}
1919

20+
/**
21+
* Make a scraped inline `<svg>` usable as a standalone `.svg` file.
22+
*
23+
* An inline SVG in an HTML document inherits the SVG namespace from the parser, so the DOM's
24+
* `outerHTML` does not serialize `xmlns`. That string is fine pasted back into HTML but is NOT
25+
* a valid standalone document: `<img src="logo-abc123.svg">` renders a broken-image icon, which
26+
* is how these assets are actually consumed downstream. Declare the namespaces on the way to disk.
27+
*
28+
* `xlink:href` is deprecated but still emitted by plenty of sites; an undeclared `xlink:` prefix
29+
* is a parse error in a standalone document, so declare that too — but only when it is used.
30+
*/
31+
export function toStandaloneSvg(outerHTML: string): string {
32+
const open = outerHTML.match(/<svg\b[^>]*>/i);
33+
if (!open) return outerHTML;
34+
const original = open[0];
35+
let tag = original;
36+
const add: string[] = [];
37+
if (!/\sxmlns\s*=/i.test(tag)) add.push('xmlns="http://www.w3.org/2000/svg"');
38+
if (/\sxlink:[a-z-]+\s*=/i.test(outerHTML) && !/\sxmlns:xlink\s*=/i.test(tag)) {
39+
add.push('xmlns:xlink="http://www.w3.org/1999/xlink"');
40+
}
41+
if (!add.length) return outerHTML;
42+
tag = tag.replace(/^<svg\b/i, `<svg ${add.join(" ")}`);
43+
return outerHTML.replace(original, tag);
44+
}
45+
2046
export async function downloadAssets(
2147
tokens: DesignTokens,
2248
outputDir: string,
@@ -34,7 +60,9 @@ export async function downloadAssets(
3460
for (let i = 0; i < tokens.svgs.length && i < 30; i++) {
3561
const svg = tokens.svgs[i]!;
3662
if (!svg.outerHTML || svg.outerHTML.length < 50) continue;
37-
const slug = svgContentHashSlug(svg.outerHTML, !!svg.isLogo);
63+
// Hash the bytes that actually land on disk, so the filename still can't drift from content.
64+
const svgFile = toStandaloneSvg(svg.outerHTML);
65+
const slug = svgContentHashSlug(svgFile, !!svg.isLogo);
3866
let finalSlug = slug;
3967
let suffix = 2;
4068
while (usedSvgNames.has(finalSlug)) {
@@ -45,7 +73,7 @@ export async function downloadAssets(
4573
const name = `${finalSlug}.svg`;
4674
const localPath = `assets/svgs/${name}`;
4775
try {
48-
writeFileSync(join(outputDir, localPath), svg.outerHTML, "utf-8");
76+
writeFileSync(join(outputDir, localPath), svgFile, "utf-8");
4977
assets.push({ url: "", localPath, type: "svg" });
5078
} catch {
5179
/* skip */
Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
import { describe, expect, it, vi } from "vitest";
2+
import { existsSync, mkdtempSync, readFileSync } from "node:fs";
3+
import { tmpdir } from "node:os";
4+
import { join } from "node:path";
5+
import type { Page } from "puppeteer-core";
6+
import { captureFullPagePlate, MAX_PLATE_HEIGHT_PX, pngHeight } from "./screenshotCapture.js";
7+
8+
// A real 1920x800 PNG header, so the produced-height guard sees something valid.
9+
function pngBuffer(height: number, width = 1920): Buffer {
10+
const buf = Buffer.alloc(24);
11+
Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]).copy(buf, 0);
12+
buf.writeUInt32BE(13, 8);
13+
buf.write("IHDR", 12, "ascii");
14+
buf.writeUInt32BE(width, 16);
15+
buf.writeUInt32BE(height, 20);
16+
return buf;
17+
}
18+
19+
// The mocks declare their parameters so `mock.calls[i][0]` is a real slot — a zero-arg
20+
// vi.fn() types its call tuple as [] and indexing it is a compile error.
21+
// `docHeight` is what the in-function measurement returns; the plate reads the page height
22+
// itself now rather than trusting a value the caller measured before scrolling.
23+
function fakePage(
24+
{ docHeight = 8000, plateHeight = 8000 }: { docHeight?: number; plateHeight?: number } = {},
25+
overrides: Record<string, unknown> = {},
26+
) {
27+
const evaluate = vi.fn(async (script?: unknown) =>
28+
String(script).includes("scrollHeight") ? docHeight : undefined,
29+
);
30+
const screenshot = vi.fn(async (_opts?: unknown) => pngBuffer(plateHeight));
31+
return { page: { evaluate, screenshot, ...overrides } as unknown as Page, evaluate, screenshot };
32+
}
33+
34+
describe("captureFullPagePlate — the scroll shot's plate", () => {
35+
it("writes one full-page png and returns its relative path", async () => {
36+
const dir = mkdtempSync(join(tmpdir(), "hf-plate-"));
37+
const { page, screenshot } = fakePage({ docHeight: 10962, plateHeight: 10962 });
38+
39+
const out = await captureFullPagePlate(page, dir);
40+
41+
expect(out).toBe("screenshots/full-page.png");
42+
expect(screenshot).toHaveBeenCalledWith({ type: "png", fullPage: true });
43+
expect(pngHeight(readFileSync(join(dir, "full-page.png")))).toBe(10962);
44+
});
45+
46+
it("stays 1x: it never touches the viewport's deviceScaleFactor", async () => {
47+
const dir = mkdtempSync(join(tmpdir(), "hf-plate-"));
48+
const setViewport = vi.fn(async () => undefined);
49+
const { page } = fakePage({}, { setViewport });
50+
51+
await captureFullPagePlate(page, dir);
52+
53+
// A 2x plate would exceed the cap on exactly the long pages that want a scroll shot.
54+
expect(setViewport).not.toHaveBeenCalled();
55+
});
56+
57+
it("skips a page taller than Chrome can capture, instead of writing a clipped plate", async () => {
58+
const dir = mkdtempSync(join(tmpdir(), "hf-plate-"));
59+
const { page, screenshot } = fakePage({ docHeight: MAX_PLATE_HEIGHT_PX + 1 });
60+
61+
const out = await captureFullPagePlate(page, dir);
62+
63+
expect(out).toBeNull();
64+
expect(screenshot).not.toHaveBeenCalled();
65+
expect(existsSync(join(dir, "full-page.png"))).toBe(false);
66+
});
67+
68+
it("neutralises sticky/fixed chrome for the shot and restores it afterwards", async () => {
69+
const dir = mkdtempSync(join(tmpdir(), "hf-plate-"));
70+
const { page, evaluate, screenshot } = fakePage();
71+
72+
await captureFullPagePlate(page, dir);
73+
74+
const scripts = evaluate.mock.calls.map((c) => String(c[0]));
75+
// neutralise, height probe, restore — the probe sits after neutralisation because
76+
// forcing fixed/sticky to `static` puts those elements back in flow and grows the page.
77+
expect(scripts).toHaveLength(3);
78+
expect(scripts[0]).toContain("'fixed'");
79+
expect(scripts[0]).toContain("'sticky'");
80+
expect(scripts[0]).toContain("data-hf-plate-position");
81+
expect(scripts[1]).toContain("scrollHeight");
82+
// Then hand the page back unchanged: the caller keeps reading the DOM after this.
83+
expect(scripts[2]).toContain("removeAttribute");
84+
expect(scripts[2]).toContain("data-hf-plate-position");
85+
expect(evaluate.mock.invocationCallOrder[1]).toBeLessThan(
86+
screenshot.mock.invocationCallOrder[0]!,
87+
);
88+
expect(screenshot.mock.invocationCallOrder[0]).toBeLessThan(
89+
evaluate.mock.invocationCallOrder[2]!,
90+
);
91+
});
92+
93+
it("restores the page even when the screenshot throws", async () => {
94+
const dir = mkdtempSync(join(tmpdir(), "hf-plate-"));
95+
const screenshot = vi.fn(async (_opts?: unknown) => {
96+
throw new Error("capture failed");
97+
});
98+
const { page, evaluate } = fakePage({}, { screenshot });
99+
100+
await expect(captureFullPagePlate(page, dir)).rejects.toThrow("capture failed");
101+
// A page left with every sticky element forced static would corrupt the extraction
102+
// passes that run after this one.
103+
expect(String(evaluate.mock.calls.at(-1)?.[0])).toContain("removeAttribute");
104+
});
105+
});
106+
107+
describe("captureFullPagePlate — guards against a silently clipped plate", () => {
108+
it("measures the height itself, after lazy content has grown the page", async () => {
109+
const dir = mkdtempSync(join(tmpdir(), "hf-plate-"));
110+
// A page that measured 9000 before scrolling but is 20000 once lazy images land: the
111+
// pre-scroll number would have passed the guard and emitted a clipped plate.
112+
const { page, screenshot } = fakePage({ docHeight: 20000 });
113+
114+
expect(await captureFullPagePlate(page, dir)).toBeNull();
115+
expect(screenshot).not.toHaveBeenCalled();
116+
});
117+
118+
it("discards a plate Chrome clipped, even when the measurement passed", async () => {
119+
const dir = mkdtempSync(join(tmpdir(), "hf-plate-"));
120+
// Measurement said 16000, but the capture itself triggered more loading and came back
121+
// over the cap. Emitting it would be undetectable downstream.
122+
const { page } = fakePage({ docHeight: 16000, plateHeight: MAX_PLATE_HEIGHT_PX + 500 });
123+
124+
expect(await captureFullPagePlate(page, dir)).toBeNull();
125+
expect(existsSync(join(dir, "full-page.png"))).toBe(false);
126+
});
127+
128+
it("survives a restore that throws — the real error is what propagates", async () => {
129+
const dir = mkdtempSync(join(tmpdir(), "hf-plate-"));
130+
let call = 0;
131+
const evaluate = vi.fn(async (script?: unknown) => {
132+
call++;
133+
if (String(script).includes("scrollHeight")) return 8000;
134+
if (String(script).includes("removeAttribute")) throw new Error("page crashed");
135+
return undefined;
136+
});
137+
const screenshot = vi.fn(async (_opts?: unknown) => {
138+
throw new Error("capture failed");
139+
});
140+
const page = { evaluate, screenshot } as unknown as Page;
141+
142+
// Without the try/catch in `finally`, "page crashed" would mask "capture failed".
143+
await expect(captureFullPagePlate(page, dir)).rejects.toThrow("capture failed");
144+
expect(call).toBeGreaterThanOrEqual(3);
145+
});
146+
});
147+
148+
describe("pngHeight", () => {
149+
it("reads the height out of the IHDR chunk", () => {
150+
expect(pngHeight(pngBuffer(10962))).toBe(10962);
151+
});
152+
153+
it("returns null for anything that is not a PNG", () => {
154+
expect(pngHeight(Buffer.from("not a png at all, definitely not"))).toBeNull();
155+
expect(pngHeight(Buffer.alloc(4))).toBeNull();
156+
});
157+
});
158+
159+
describe("captureFullPagePlate — the guard sees the post-neutralisation page (Magi's case)", () => {
160+
it("skips when the initial height is under the cap but the final height is over it", async () => {
161+
const dir = mkdtempSync(join(tmpdir(), "hf-plate-"));
162+
// Pre-traversal the page measured 9000. Lazy content and un-fixing the sticky header push
163+
// it over the cap by the time the plate would be shot. Probing before either step would
164+
// have passed the guard and emitted a clipped plate.
165+
let neutralised = false;
166+
const evaluate = vi.fn(async (script?: unknown) => {
167+
const src = String(script);
168+
if (src.includes("'sticky'")) {
169+
neutralised = true;
170+
return undefined;
171+
}
172+
if (src.includes("scrollHeight")) return neutralised ? 20000 : 9000;
173+
return undefined;
174+
});
175+
const screenshot = vi.fn(async (_opts?: unknown) => pngBuffer(20000));
176+
const page = { evaluate, screenshot } as unknown as Page;
177+
178+
expect(await captureFullPagePlate(page, dir)).toBeNull();
179+
expect(screenshot).not.toHaveBeenCalled();
180+
expect(existsSync(join(dir, "full-page.png"))).toBe(false);
181+
// Bailing out early must still hand the page back unmodified.
182+
expect(String(evaluate.mock.calls.at(-1)?.[0])).toContain("removeAttribute");
183+
});
184+
});

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

Lines changed: 93 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,92 @@ import { join } from "node:path";
2121
* elements — screenshots show the page in its natural browsing state with
2222
* scroll-triggered animations fired.
2323
*/
24+
/**
25+
* Chrome caps a screenshot at 16384px per side (Skia's max texture dimension); past that the
26+
* capture comes back clipped or fails outright. Long marketing pages do reach this.
27+
*/
28+
export const MAX_PLATE_HEIGHT_PX = 16384;
29+
30+
/**
31+
* Pixel height Chrome actually produced, read from the PNG's IHDR chunk: 8-byte signature,
32+
* then 4 length + 4 type + 4 width + 4 height. Null when the buffer isn't a PNG.
33+
*/
34+
export function pngHeight(buf: Uint8Array): number | null {
35+
// Byte math rather than Buffer helpers: page.screenshot() resolves to a Uint8Array.
36+
if (buf.length < 24) return null;
37+
if (buf[12] !== 0x49 || buf[13] !== 0x48 || buf[14] !== 0x44 || buf[15] !== 0x52) return null; // "IHDR"
38+
return ((buf[20]! << 24) | (buf[21]! << 16) | (buf[22]! << 8) | buf[23]!) >>> 0;
39+
}
40+
41+
/**
42+
* One tall image of the whole document — the plate a scroll shot slides its viewport over.
43+
*
44+
* This is deliberately 1x. A 2x plate is what you'd want for pushing in without softening
45+
* text, but doubling a long marketing page blows past `MAX_PLATE_HEIGHT_PX` exactly on the
46+
* pages that most want a scroll shot; a frame that needs 2x should capture its own region
47+
* instead. At 1x a 1920-wide plate is pixel-exact for a 1920x1080 viewport travelling down it.
48+
*
49+
* Two things have to be true for the plate to be usable, and both are why the earlier
50+
* `full-page.png` was worth removing rather than keeping as-is:
51+
* · It must be taken AFTER the scroll traversal, so lazy images have loaded and
52+
* scroll-triggered reveals have fired. A plate shot on arrival is full of blank bands.
53+
* · Sticky/fixed chrome has to be neutralised first. `fullPage` bakes a fixed header in at
54+
* one position, so a nav ends up frozen across the middle of the plate. The viewport
55+
* shots keep sticky on purpose (natural browsing state); the plate cannot.
56+
*
57+
* Returns the relative path, or null when the page is too tall to capture in one piece.
58+
*/
59+
export async function captureFullPagePlate(
60+
page: Page,
61+
screenshotsDir: string,
62+
): Promise<string | null> {
63+
// Record the inline value before overwriting so the page is handed back unchanged — the
64+
// caller keeps using it (asset extraction, DOM reads) after this returns.
65+
await page.evaluate(
66+
`document.querySelectorAll('*').forEach((el) => {
67+
const p = getComputedStyle(el).position;
68+
if (p === 'fixed' || p === 'sticky') {
69+
el.setAttribute('data-hf-plate-position', el.style.position || '');
70+
el.style.position = 'static';
71+
}
72+
})`,
73+
);
74+
try {
75+
// Measured here — after the caller's scroll traversal AND after neutralisation — never
76+
// taken from the caller. Both steps grow the document: lazy content loads as the page is
77+
// scrolled, and forcing fixed/sticky elements to `static` drops them back into flow. A
78+
// height read before either one is low on exactly the long pages this guard exists for,
79+
// which would pass the check and let a clipped plate through.
80+
const docHeight = (await page.evaluate(
81+
`Math.max(document.body.scrollHeight, document.documentElement.scrollHeight)`,
82+
)) as number;
83+
if (docHeight > MAX_PLATE_HEIGHT_PX) return null;
84+
85+
const buffer = await page.screenshot({ type: "png", fullPage: true });
86+
// Confirm what Chrome produced instead of trusting the measurement: the capture itself can
87+
// trigger another round of lazy loading. A clipped plate is undetectable downstream — the
88+
// skill only teaches the tile fallback when the file is *absent* — so emit nothing rather
89+
// than something silently wrong.
90+
const produced = pngHeight(buffer);
91+
if (produced != null && produced > MAX_PLATE_HEIGHT_PX) return null;
92+
writeFileSync(join(screenshotsDir, "full-page.png"), buffer);
93+
return "screenshots/full-page.png";
94+
} finally {
95+
// A page that broke mid-capture will fail this too; letting that escape would replace the
96+
// real error with a cleanup one. Nothing to restore if the page is already gone.
97+
try {
98+
await page.evaluate(
99+
`document.querySelectorAll('[data-hf-plate-position]').forEach((el) => {
100+
el.style.position = el.getAttribute('data-hf-plate-position');
101+
el.removeAttribute('data-hf-plate-position');
102+
})`,
103+
);
104+
} catch {
105+
/* page unusable — the restore is moot */
106+
}
107+
}
108+
}
109+
24110
export async function captureScrollScreenshots(page: Page, outputDir: string): Promise<string[]> {
25111
const screenshotsDir = join(outputDir, "screenshots");
26112
mkdirSync(screenshotsDir, { recursive: true });
@@ -151,7 +237,13 @@ export async function captureScrollScreenshots(page: Page, outputDir: string): P
151237
await page.evaluate(`window.scrollTo(0, 0)`);
152238
await new Promise((r) => setTimeout(r, 200));
153239

154-
// full-page.png removed — 1/8 agents read it, contact sheet covers the same content
240+
// The scroll plate, last: everything above has loaded the page and fired its reveals, which
241+
// is the only state a full-page shot is worth taking in. (An earlier full-page.png was
242+
// dropped because 1/8 agents read it and the contact sheet covered the same ground — that
243+
// was about it as a *comprehension* artifact. The scroll shot is a different consumer: it
244+
// needs one continuous plate, which no set of viewport tiles can substitute for.)
245+
const plate = await captureFullPagePlate(page, screenshotsDir);
246+
if (plate) filePaths.push(plate);
155247
} catch {
156248
/* scroll screenshots are non-critical */
157249
}

0 commit comments

Comments
 (0)