DEV Community: Mohammed Abdul Mubeen Khan

How do you test a screenshot API when every failure returns 200 OK?

Mohammed Abdul Mubeen Khan — Tue, 29 Sep 2026 13:00:00 +0000

Most test suites answer the question "did it work?". A screenshot renderer makes that question almost useless, because the interesting failures all return 200 OK with an image attached.

A cookie wall is a valid PNG. So is a page captured mid-paint, a blank white frame from a bot wall, and a captcha. Every one of those passes a status-code check, passes a "is the response an image?" check, and passes a "is the file bigger than zero bytes?" check. Then it sits in someone's pipeline for a month.

So the benchmark behind Screenshotlineis built around a different question: which pages surprised me this time? This post is how that works, because the shape of it applies to anything that scrapes, renders or crawls the real web.

Every page carries a claim, written before the run

The suite is 202 real sites across 15 categories: news, shops, SaaS, docs, government, education, finance, WebGL and visualisation, TLS edge cases, HTTP semantics, and 13 languages in 10 scripts. Each entry looks like this:

['nyt', 'https://www.nytimes.com/', 'Fides consent banner injected after networkidle'],

and each page is tagged in advance with what I claim my own product should do:

ok: this must work. A failure here is a bug.
known-hard: I expect a bot wall or a block. A failure here is information, not a regression.

That tag converts a run from a score into a set of predictions that can be wrong, which is the version that teaches you something. The runner prints the two kinds of broken prediction under a heading I actually read:

  BUGS - expected to work, failed (0):
  Expected hard, but worked (14) - verify the image is real content, not a bot wall

A page that was supposed to work and didn't is a bug. A page that was supposed to be hard and passed means something changed. Maybe my renderer got better, maybe the site dropped a defence, maybe my own test URL has rotted.

A pass on a hard page means nothing until you look

This is the rule that cost me the most to learn. There are three completely different things behind a 200 on a page I marked known-hard, and only one is a success:

A login wall is what any logged-out visitor sees. Capturing it is correct. facebook, instagram, quora.
A captcha is a challenge shown only to suspected bots. Capturing it is a failure dressed as a pass. walmart, wsj.
A 404 means the URL in my own suite died. amazon, where an ASIN went away and I was quietly benchmarking a "product not found" page.

No automatic check tells those apart. I tried. A text heuristic scored wsj as "looks real" on zero extracted characters, because the page around the challenge was full of navigation and footer text.

So when the runner says 14 known-hard pages returned something, I open all 14. The last time: 11 were genuinely the real page, 2 were captchas, and 1 was that dead URL. That is a result I can publish. "14 of 20 hard pages passed" is not.

It is also why I will never quote a single headline percentage that mixes the two groups together. The honest version has two numbers: of the 182 pages marked ok, all 182 capture correctly; of the 20 marked known-hard, 14 returned something and each one was checked by eye.

Blank frames fail the run

The suite's sharpest rule is about blank captures, because that is the worst thing this product can do: return a 200 that a customer's pipeline files as a success while the image shows nothing.

Some pages really are blank for everyone: a bot wall that serves an empty document, or an IP block. Those are marked blankOk in the suite file, one page at a time, after I have looked. A blank frame on any other page fails the whole run:

if (unexpectedBlank.length) {
  console.log(` FAILED: ${unexpectedBlank.length} unexpected blank capture(s).`);
  process.exitCode = 1;
}

The non-zero exit is deliberate. Without it, a script or a CI job that only checks the status code would let a silent blank regression through, which is precisely the class of failure the suite exists to catch.

The report also separates "blank, and known to be" from "blank, and new". The first list is context. The second is a stop-everything.

File size is not quality, in either direction

The tempting shortcut is to compare byte counts: bigger image, better capture. It is wrong both ways, and I have been fooled in both directions.

Removing a consent modal makes a capture smaller. A full-screen dark overlay compresses into a lot of bytes. The better picture is the lighter one.

Collapsing blocked ad slots makes it bigger. On france24.com, collapsing the empty slots took a capture from 122 KB to 234 KB of actual content, because real content moved up into the frame.

A larger competitor capture can still be worse. One competitor's france24 image was bigger than mine and blurry, because it was taken mid-paint.

And some pages simply swing. nytimes.com moves between 80 KB and 650 KB depending on how much of its skeleton has hydrated. That is page timing, not a renderer bug, and delay is the parameter for it.

Which leaves the same conclusion as everywhere else in this project: open the image.

To make that bearable across 202 pages and several providers, the runner writes every capture to disk and a second script builds one HTML page with every provider's version of every URL side by side. Ten minutes of scrolling tells you more than any metric I have found.

What the suite is not

It is not a scoreboard, and the pass rate is the least useful line it prints. Any suite can be made to look perfect by lowering its expectations, and a benchmark whose numbers only ever improve is measuring the author's optimism.

It is not stable across machines. Several of these sites block datacenter IP ranges, so a page that passes from my laptop may fail from a cloud host. I'd rather know that before a customer discovers it: it is why the hosted API's p50 (about 7.1s, single region) is measured separately from the benchmark machine's 5.7s rather than reusing the nicer number.

It is not a competitor takedown. I run the same 202 URLs against other providers because side-by-side images are how I find the pages where I am worse. The honest result of the last head-to-head, on 18 news front pages: we captured 18/18, ScreenshotOne 17/18, and their median was faster than ours, 5.6s against 6.0s. Publishing the part that flatters you and quietly dropping the rest is how benchmarks became a genre people don't trust.

If you are building something similar

The parts worth stealing, in order of how much they saved me:

Write the expectation next to the URL, before you run anything. A test that can only pass or fail tells you less than one that can surprise you.
Make the silent failure loud. Decide what "wrong but successful" looks like in your domain, detect it, and let it fail the run with a non-zero exit.
Keep a category that you expect to fail. It stops you from tuning the suite until it is green and keeps the hard cases in view.
Look at the output with your own eyes, on a schedule. Not because automation is bad, but because the failures that matter are the ones your checks were not built to see.

The suite lives in bench/ in the repo: the runner, the 202 URLs with their tags and notes, and the comparison page builder. It runs against a local instance, so if you self-host you can point it at your own and see what your hardware does with the same pages.

The Cryptid Field Office: an AI triages sightings, a person signs off

Mohammed Abdul Mubeen Khan — Fri, 25 Sep 2026 11:07:12 +0000

This is a submission for the Sanity Challenge, Path Two: Vibe-Code Something Strange

What I Built

The Cryptid Field Office: a deadpan government bureau that takes every unexplained sighting seriously. Cryptids, lights over the desert, a figure on the stairs, a jinn in the storeroom, a lodge that is on no property register. You file a report. An AI Field Investigator reads it, scores it and decides where it goes. A person signs off on anything unclear. Every case ends in a stamp: CLASSIFIED, DEBUNKED or INCONCLUSIVE.

It is silly on the surface and serious underneath. Take away the Bigfoot and it is a report-triage pipeline: public intake, AI screening, linking related reports, a human decision, and an audit trail. Swap the creatures for potholes and you have a city 311 system. The same pattern runs bug trackers, insurance claims and fraud review. That was the point: something strange, built on something real.

It has three surfaces on one Sanity content lake:

	What it is	Who uses it
Public site (Next.js)	Case map and files, a four-step report form, a live "your report is being triaged" page, and a public Director's Desk	Anyone. No login.
Case Board (Sanity App SDK)	A live corkboard: drag case photos around, pull a red pin from one card onto another to draw a string, approve or reject the AI's suggested links, fire workflow actions	Bureau staff
Studio	Custom desk, status badges, a map location picker, and the official Workflows plugin	Editors

The part I am proudest of: the agent and a person move a case through exactly the same workflow actions. The AI triages a report, a visitor on the Director's Desk opens an investigation, and a staff member closes it from the Case Board, and all three are the same fireAction on the same instance, recorded in one audit trail.

Demo

Live site (no login needed): https://cryptid-field-office-mubeen9.vercel.app

Try it in about a minute:

File a report. Describe something, drop a pin, optionally attach a photo. About 15 seconds after you submit, the Field Investigator has read it and a stamp lands on your case.
Open the Director's Desk and decide a case that needs a person.
Open the resulting case file: memo, evidence, red strings to related cases, and the timeline showing who did what ("Agent", "Visitor Director", "Bureau").

The Studio and Case Board need a Sanity login, so the video and screenshots below show them. The Director's Desk gives you the same workflow power without one.

The video shows the whole loop, from a public report to a stamp, and it is the only place to see the Case Board and Studio without a Sanity login.

Code

https://github.com/MAMubeenKhan/cfo

The repo includes PLAN.md (the full runbook I had Claude write before any code) and BUILDLOG.md (an honest day-by-day log, including everything that broke).

My Build Process

Tools: Claude Code (Opus 5.5 for planning, Sonnet 5 for most building), the official sanity-best-practices agent skill, Playwright, axe-core and Lighthouse for testing. I am non-technical; I directed, Claude built.

The idea (and the prompt that mattered most)

My first prompt was the challenge page pasted in, plus: "give me options on what we should make and tell me what is best and why." Claude scored four ideas against the four judging criteria and both bonuses and recommended the cryptid bureau, because a case moving from triage to a verdict is exactly the "agent moves it forward, a person approves it" pattern, and a red-string board is a natural App SDK app.

My honest worry was: "won't it be weird and silly and make me a joke?" Claude's answer became the design rule for the whole project: play it deadpan. The humour lives in the bureaucracy (case numbers, stamps, memos), never in the subject. A silly idea with a real workflow reads as clever; a silly idea with three screens reads as a joke.

Then I kept pushing the scope: "include UFOs, aliens, Area 51", then "ghosts, jinn, spirits and occult", then "secret cults and societies." That created a real design question I want to be upfront about, because it shaped the code:

Jinn are part of real religious belief. So the bureau's humour must never touch them. Rules that ended up in code, not just in copy: faith-related reports are never auto-closed; the AI prompt forbids ruling on belief or calling a witness mistaken; the final filing step refuses an agent "debunked" stamp on a faith-sensitive case even if everything upstream failed; and a human closing one must tick an extra confirmation.
Every secret society is invented. No real group, religion or person appears anywhere.
Reports suggesting distress or coercion force human review and show a calm banner.

The plan-first prompt

Before writing code I asked for "an end to end plan so a new session doesn't have to do any planning, including edge cases, no tests until completion, only one comprehensive test at the end." Claude read the Workflows and App SDK docs, checked real package versions, and wrote a ~500-line runbook. Three mid-flight prompts shaped it: "it should be attractive with good UX and highly polished", "as per current standards" (this became a WCAG 2.2 AA, Core Web Vitals, dark-mode, reduced-motion spec), and my memory file (a memory.md Claude reads at every session start and appends lessons to).

Sanity features I used

Content model: 8 document types (case, subject, region, witness, connection, board pin, settings, counter) and 5 object types. Typed evidence union (photo, footprint, sound, testimony), geopoints, references, and a first-class connection document with provenance and confidence: the red strings. Witnesses are anonymous codenames with a credibility score computed across their cases.
Studio customisation: status-queue desk structure, category and restricted-site lists, badges (status, plausibility P0-100, hidden), delete removed for cases (it would orphan their workflow instance), and a MapLibre location picker replacing the default geopoint input (which needs a Google Maps key).
Workflows (0.35, early access): the case-lifecycle definition: five stages, five automated effects, human actions for the Director and Investigator. It passed sanity-workflows deploy --check on the first attempt. I then ran all 30 seeded cases through the real engine using the same actions a person fires, and asserted the stage histogram matched the plan exactly.
Functions: a document Function fires when a workflow instance gains unclaimed effects and runs the AI handlers in Sanity's cloud, and a daily Scheduled Function sweeps stale claims and re-evaluates open cases.
Agent Actions: the Field Investigator and the Cross-Referencer both call client.agent.action.prompt.
App SDK: the Case Board (useQuery streams, useWorkflowEngine, useWorkflowSession, @sanity/workflow-diagram).

Where it got stuck, and how we corrected course

I would rather show the dead ends than pretend there were none.

A big Bash command silently applied nothing (twice): long heredocs containing an apostrophe failed with "unexpected EOF". The lesson, saved to memory: write files with the file tool, one call per file.
Half-installed packages: an interrupted npm install left a half-extracted zod, which made every Sanity CLI command fail with MODULE_NOT_FOUND, then made a second install fail with Invalid Version:. Fix: delete node_modules and the lockfile, install fresh, in the background. On this network installs took 10 to 25 minutes.
The skill corrected the plan. I installed Sanity's sanity-best-practices skill and it caught that @sanity/icons v5 has no root exports (every icon imports from its own path). My draft compiled and would have failed at bundle time.
Permissions: my API token could deploy the Studio and Functions but not an App SDK app (missing an organisation-level grant) and could not create the organisation stack that Scheduled Functions need. I did not work around it: I shipped without the daily backup job and wrote a repair command instead, deployed the Case Board from my own login, and later, once I was logged in, created the organisation stack, moved both Functions onto it and retired the old one.
Vercel served 404 for everything: the CLI created the project with no framework preset, so the build passed but the edge served nothing. One API call to set framework: nextjs and a redeploy fixed it. Deployment Protection was also putting a login in front of the site.
The AI was too harsh. In the live test, a credible sighting with a photo and a footprint scored 68, just under the 70 "investigate" bar. I added a scoring guide to the prompt ("a submitted photo or footprint counts as physical evidence"; "vague is not false: when in doubt, score 20-49 so a person can look") and redeployed. The same report then opened an investigation, and the Cross-Referencer proposed 3 real related files.
Things the live test found that no type-checker would have: a missing case returned HTTP 200 (a soft 404) because of a page-wide loading skeleton; the map threw "Worker failed to load" because MapLibre 6's worker files can't be bundled by Next; the map opened on Scotland instead of framing all cases; my evidence photos were bad at first sight (a footprint that looked like a snowman, a triangle invisible on a dark sky), which I only caught by looking at them.
My first rate limiter was useless, and only a live test showed it. I had built it in server memory and even documented it as a known limit. Then I filed eight reports at once from one connection with the limit set to five: all eight went through, because serverless hosting spreads requests over many servers. I rebuilt it as counters stored in Sanity as private documents (an id with a dot in it is unreadable to the public). The same test then accepted five and refused three, and an anonymous query for those counters returns nothing.
Vercel blocked a deployment once I started committing to git: the CLI attached my commit author, which was not on the Vercel team. Deploying from a copy of the folder without git history fixes it (scripts/deploy-web.sh).
Recording the demo video found three more bugs. Watching my own screen recording, the red strings on the Case Board were grey and hair-thin: React Flow's stylesheet loads later and beat mine, so I raised the selector's specificity. The Studio's map input was blank: MapLibre 6 needs a worker URL in every host, not only the Next site, so I serve the worker from the Studio's static folder. And demo cases I had hidden were still appearing as "related files" on public pages, so the query now drops a connection if either end is hidden.
Speed: the case page scored 57 on a throttled phone because a 290 KB map library loaded below the fold. Mounting the map only when it scrolls into view took it to 93. Accessibility is 100 on every page; the search-engine score stays near 66 only because Vercel adds a noindex header to its free addresses.

The App SDK and Workflows, honestly

Workflows is a library, not a service: it acts only when your code calls it. That felt unfamiliar for a day, then clicked. Defining the process as data next to the content, with conditions in GROQ, made "the agent and a person use the same transitions" almost free. The cookbook matched the installed types closely, which is rare for a 0.x release. A deterministic instance ID (prod.wf-instance.<caseId>) made starting a case idempotent.
App SDK hooks stayed live without any polling code of my own, and the workflow session gave me the action list, the definition and the history for the diagram in one object. The one rule I obeyed carefully: never edit a workflow instance document directly.

What is honestly not there

No CAPTCHA. Abuse is limited by a durable rate limit (5 reports an hour per visitor, 40 overall), a honeypot, a minimum fill time, and a daily AI budget with a kill switch in Bureau settings.
The Case Board is desktop-only, by design.
Not tested: two people using the Case Board at the same moment (the live sync is Sanity's, and I only tried it alone); a real screen reader (I ran axe-core, which scored 100, and did a keyboard-only pass, but I did not listen to it); and the daily sweeper's first scheduled run, which was due after I wrote this.
The AI can be wrong. Code, not the model, picks the route, but a very low score (under 20) still auto-debunks an ordinary case. The safety net is narrower than "a person sees everything": faith, distress and coercion flags always force human review, and every automated step is written to the case's audit log so a person can find and reverse it.

Sanity Project Details

Project ID: cyh4xyo1 · Dataset: production (public)
Sample query: https://cyh4xyo1.api.sanity.io/v2026-09-01/data/query/production?query=*[_type=="case"][0...5]{caseNumber,title,category,status}
Studio: https://cryptid-field-office.sanity.studio/ (needs a Sanity login)
Schema highlights: case (workflow subject with a status mirror), connection (red strings with provenance), witness (anonymous, credibility computed across cases), subject (six categories), region (a restricted flag drives the Area 51 banner and redactions).

Agent Session

Vibe-coding a cryptid bureau on Sanity: the key moments

You

https://dev.to/challenges/sanity-2026-09-16

<pasted_content id="a237">
DEV Community
Create Post
Edit
Preview

Upload Cover ImageNo file chosenUse a ratio of 1000:420 for best results.
🍌 Generate Image
Cover Video Link
New post title here...

Add up to 4 tagsMaximum 4 selections
Selected items:

devchallenge

sanitychallenge

sanity

ai

Bold CTRL + B
Italic CTRL + I
Link CTRL + K
Ordered list
Unordered list
Heading
Quote
Code
Code block
Embed CTRL + SHIFT + K
No file chosenUpload image

This is a submission for the Sanity Challenge, Path Two: Vibe-Code Something Strange

What I Built

Demo

Code

My Build Process

Sanity Project Details

Agent Session

Publishing Tips
Ensure your post has a cover image set to make the most of the home feed and social media platforms.
Share your post on social media platforms or with your co-workers or local communities.
Ask people to leave questions for you in the comments. It's a great way to spark additional discussion describing personally why you wrote it or why people might find it helpful.
Publish
Save Draft
AI Disclosure
Advanced Options
</pasted_content id="a237">

<pasted_content id="a237">
Path Two: Vibe-Code Something Strange
Prompt your way to a working app. Any AI-native IDE, Next.js or Astro on the front, Sanity behind it.

This one is judged on the build as much as the result. How deep did you get into Sanity's features? Did you customize the interface? Build a new component to turn videos into gifs? Create a workflow that kicks off an external API call? A rough app with an honest writeup beats a [... 4497 characters omitted for upload size ...] the entry that received the highest number of positive reactions on their DEV post to determine the winner.

How will I know if I won?
Winners will be announced in a DEV post on the winner announcement date noted in our key dates section.

When will I receive my DEV badge?
Both participation and winner badges will be awarded, in most cases, the same day as the winner announcement.

When will I receive my prizes?
The DEV Team will contact you via the email associated with your DEV profile within, at most, 10 business days of the announcement date to share the details of claiming your prizes.

What steps do I need to take to receive my cash prize?
The winner (including each member of a team) may be required to sign and return an affidavit of eligibility and publicity/liability release, and provide any additional tax filing information (such as a W-9, social security number or Federal tax ID number) within seven (7) business days following the date of your first email notification.

Sanity Challenge Rules
NO PURCHASE NECESSARY. Open only to 18+. Contest entry period ends October 4, 2026 at 11:59 PM PDT. Contest is void where prohibited or restricted by law or regulation. All entries must be submitted during the contest period. For Official Rules, see Sanity Challenge Contest Rules and General Contest Official Rules.
</pasted_content id="a237">

. So, let's make something and win this challenge. You give me options on what we should make and tell me what is best for this and why

Agent

Checked the challenge page plus Sanity's Workflows and App SDK docs. Now I'm writing up the options and a recommended build plan.

Agent

I haven't built anything yet. Here's what I've got so far, then tell me what you'd like to clarify.

What wins this path: judges score four things: an honest build write-up, a working app, a well-designed schema, and creativity. The bonus is for going past the Studio: an App SDK app (a custom real-time interface) or Workflows, where a draft moves through set stages that both an agent and a person can advance. Sanity only launched Workflows on Sep 14 and it's early access, so few entrants will use it well. That's our best edge. The deadline is Oct 4, 10 days from now.

Options:

Idea	Workflow fit	App SDK fit	Schema	Strangeness
A. Cryptid Field Office: a bureau processing Bigfoot/Mothman sighting reports	Natural	Natural	Rich	High
B. Exquisite Corpse Gazette: surreal newspaper written in turns	Good	Good	Medium	Medium
C. Dream Patent Office: dreams filed as patents	Good	Medium	Medium	High
D. Fridge Court: leftovers put on trial	Good	Weak	Thin	High

My pick is A, the Cryptid Field Office. It's the only idea where both bonuses come straight out of the premise:
- Workflows: a sighting report moves Reported → an AI "Field Investigator" triages it → human review if flagged → verdict. The agent and a person press the same buttons, which is what the judges asked for.
- App SDK: a live red-string conspiracy board. Dragging a string between two sightings creates a real link between those records, and you can approve a case from the board.
- Schema: sightings, creatures, witnesses (with a credibility score across cases), typed evidence, map locations and connections. That gives us plenty to say about why the data had to be structured.
- Demo: a public Next.js map of sightings that judges can use without logging in.

One risk: Workflows needs early-access sign-up. If we don't have access by day 2, we model the workflow ourselves as Sanity documents, and the write-up says so honestly.

What would you like to clarify? It could be the ideas, the stack, what accounts you have (Sanity, Vercel, an Anthropic API key), or something else.

Sources:
- DEV Sanity Challenge
- Sanity Workflows cookbook
- AI content pipeline recipe
- App SDK intro
- Everything NYC 2026 recap

You

if i chose cryptid field office, won't it be weird and silly and will it be acceptable and won't it make me a joke in there?

Agent

It's a fair worry, but I don't think it will make you look like a joke. Here's why.

1. The brief asks for strange. The path is literally called "Vibe-Code Something Strange", and creativity is one of the four judging criteria. The judges will read dozens of blog templates and "AI content helper" apps. A playful premise done well stands out. A safe idea done well blends in.

2. People laugh at weak engineering, not at a funny theme. A silly idea with three screens and a thin write-up looks like a joke. A silly idea with a real workflow, an agent handing cases to a human, a live App SDK board and a carefully designed schema looks like someone who's good enough to have fun. The theme is the costume. The engineering is what gets judged.

3. It's a serious system in disguise. Take out the cryptids and what's left is a report-triage pipeline: the public files reports, an AI screens them, related reports get linked, a human makes the final call, and there's an audit trail. That's how pothole reports, bug trackers, insurance claims and fraud flags work. The write-up can say so outright: "Swap Bigfoot for potholes and this is a city 311 system." Judges see the fun and the real-world pattern, and that's a strong combination.

4. Tone is our choice. It doesn't have to be goofy. I'd play it deadpan: a dry government-bureau look with case numbers, "CLASSIFIED" stamps and formal language, taken completely seriously. It's in the spirit of the SCP Foundation or The X-Files. Humour that plays it straight comes across as clever, not silly.

If you'd still feel uncomfortable putting your name on it, that matters. You'll be the one posting it and answering comments. The same engineering can wear a more serious costume.

You

first, write end to end plan on how to implement this so if i start a new session and give the file to claude, it should not have to do planning of any kind, you get how planned I want this to be? including edge cases etc as we are short on time, also mention in the plan, no tests during implementation until completion. only one comprehensive test after completion. also, make a memory.md file and read it before starting any task, It should hold my preferences and lessons learnt in current and past sessions. After each task, if I corrected you or you learned something worth keeping, add one short dated and timed line to memory.md. Do not rewrite old lines.

Agent

Where the plan is

It's saved in one file:

[REDACTED]\.claude\plans\https-dev-to-challenges-sanity-2026-09-1-optimized-plum.md

Once you approve it, the first thing the build does is copy it into your project folder as [REDACTED]\sanity\PLAN.md. Any new Claude session can be given that file and start building straight away, with no re-planning. It covers every step, the exact commands, the problems that could come up and what to do about each one, the design rules, the rule of one full test at the very end, and exactly which small steps you'll need to do yourself.

About memory.md: you already have one at [REDACTED]\.claude\memory.md, and it's loaded automatically at the start of every session. So I won't create a second one. I'm not allowed to change files until you approve the plan, so it's the plan's first step to add today's new preferences to that file: fully detailed plans, a polished UI, and simple explanations for you.

What we're building, in plain words

We're building a website that pretends to be a serious government office for Bigfoot sightings. It's called the Cryptid Field Office.

What a visitor can do:
1. Report a sighting. They fill in a short form: what they saw, where (by pinning it on a map), when, and an optional photo.
2. Watch an AI "investigator" read it in about 30 seconds. It gives the report a believability score out of 100 and writes a short, dry office memo about it.
3. See the report sorted automatically:
- Obviously fake → stamped "DEBUNKED" right away.
- Unclear → sent to a human "Director" to decide.
- Believable → opened as an investigation. A second AI then looks for similar sightings nearby and links them with red strings, like a detective's wall.
4. Browse every case on a map, and open any case to read its full file.
5. Play the Director. A visitor page lets anyone approve or reject waiting cases, so the judges can try the whole thing without logging in.

What you (as staff) get: a private "Case Board". It's a digital corkboard where case cards are pinned and red strings connect related sightings. Your team can drag cards, draw strings and make decisions, and everyone sees changes instantly.

Why a joke idea is a smart entry: under the costume, this is a real system. It's the same one cities use for pothole complaints and companies use for customer claims: people report, AI screens, a human decides, and everything is recorded. The judges asked for exactly this ("an agent moves it forward, a person approves it"), and we use both of Sanity's newest features that they said they especially want to see.

How it will look: it'll be polished and modern, styled like old government files: paper colours, typewriter-style case numbers, ink stamps that "thump" onto the page, and a dark mode. It'll work well on phones and follow current accessibility standards.

What you'll need to do yourself (I'll walk you through each with exact clicks): log in to Sanity once, create a Vercel account, paste one secret key into a file, click through the Vercel setup, record a 2–3 minute screen video, and publish the post on DEV. I'll do everything else.

Timeline: building Sep 25 – Oct 1, the one full test on Oct 2, and writing and publishing the post on Oct 3. That leaves Oct 4 as a spare day before the deadline.

You

carryon but i think we should also include ufos and aliens, area 51 etc

Switched to claude-sonnet-5

Agent

Good call. UFOs, aliens and Area 51 fit the "Department of Unexplained Sightings" idea, and they open up better material. UFO reports can be explained by Venus, satellites or aircraft, which suits an AI investigator, and Area 51 gives us a redacted-document look. Nothing is seeded yet, so changing the schema now costs almost nothing.

The change: "Creature" becomes a broader Subject (cryptid, UFO craft, extraterrestrial, folklore, misidentified). Cases get a category, and regions can be flagged restricted (Area 51 and similar).

You

also, ghosts, jinn, spirits and occult sightings

You

even occult secret cults and societies

Agent

Two fixes before checking: my "restricted regions" filter query was malformed, and the map picker still needs attaching to the location field.

Agent

I'll validate the definition offline. The --check option contacts nothing and only tests whether the engine accepts my process map.

Agent

The workflow passes validation on the first try. I'll deploy it to your dataset now, so any dataset-level problem shows up early.

Agent

The workflow, the AI handlers and the cloud automation are built and running. The Studio is redeployed at https://cryptid-field-office.sanity.studio/ with the workflow plugin, so refresh it. Cases now have real stages, and the thumbnails show on the list. I haven't looked at it in a browser myself.

The workflow works end to end. All 30 sample cases ran through the real engine, using the same actions a person would use. They landed exactly where planned: 8 classified, 9 debunked, 4 inconclusive, 5 under investigation, 4 waiting for the Director. Each case's log, verdict and witness credibility updated correctly.
The faith rule held. None of the three spirit and jinn cases was debunked. Two safeguards enforce this in code, so the AI can't override it.
The cloud automation is live. A Sanity Function now runs the AI investigator automatically whenever a new report arrives.
The AI works on your plan. I checked that Sanity's built-in AI is available, so you don't need a separate AI account.

One honest cut: I dropped the daily backup-repair job. Sanity only allows it at the organisation level, and the token I have doesn't permit that. I added a command that does the same repair on demand, so it costs us nothing. You can lift that limit yourself if you want it: it's a permission on your Sanity organisation.

One open question: I've only tested that the AI responds. How good its scoring is on real reports gets tested in the final pass. If it turns out weak, I can switch to Claude, which needs an Anthropic API key from you.

Still owed: nothing is committed or pushed to cfo, and the old token is still in this chat's record, so please replace it before publishing.

Next is the public website: the map, the case files, the "file a report" form, and the live stamp that lands when the AI finishes. This is the part judges will see first, so it gets the most design effort. Shall I go ahead?

Agent

The build itself succeeded, but the site is being served as if it were a plain static folder. I'll check the project's framework setting.

Agent

The framework wasn't set, so Vercel didn't know this was a Next.js app. I'll set it and redeploy.

Agent

While the website redeploys, I'll redeploy the Case Board with the corrected link, using your login.

Agent

The site is redeployed and the map worker file is being served. I'll rerun the screenshots to confirm the fixes, then run the first real report through the site.

Agent

The AI's updated instructions are live. Now the website with the skip-link fix, and then I'll re-file the credible report to see whether the calibration helped.

Agent

The calibration worked: the same credible report now goes straight to investigation. Now the Director's Desk test on two of the earlier test cases.

Agent

Picking up where we left off. My notes list two open items: the mobile speed of case pages (57 out of 100) and the search-engine score (about 66). I'll start with the exact reasons Lighthouse gave for the search-engine score.

Agent

The deploy failed. I'll look at the actual error rather than guess.

Agent

"Not authorized" means the command-line login to Vercel isn't active in this session. I'll check.

Agent

The Vercel command line is now signed in as a different account (mamubeenkhan-6376) from the one that owns the project (mubeen9). I'll see which teams this login can access.

Agent

The login is fine: same account, same team. The failure may have been a hiccup, so I'll retry the deploy with the team named explicitly.

Agent

Deployed. Now I'll re-measure speed on phone and desktop.

Agent

Deployed. Now a quick check that the deferred map still appears when you scroll to it on a phone, and a re-measure of the home page.

Agent

Testing turned up two things worth fixing, and both are fixed and deployed. Most of the untested items pass.

Passed
- Keyboard only: the skip link works and every one of the 44 tab stops on the home page shows a visible focus ring. I filed a complete report with the keyboard alone, choosing the category with arrow keys and the place with the search box.
- Reduced motion: nothing animates.
- Place search down: a clear message appears and you can still drop a pin and continue.
- Firefox: clean.
- Safari's engine: pages, maps and the form work. It logs one harmless message about a cancelled background request.

Found and fixed: the report limiter was useless.
I filed eight reports at once from one connection, with the limit set to 5 per hour, and all eight went through. The counter lived in each server's memory, and Vercel runs many servers at once. I rebuilt it so the counts live in Sanity as hidden records that visitors can't read. It now allows 5 per hour per person and 40 per hour overall. I reran the test: 5 accepted, 3 refused, and an anonymous check finds none of the hidden records. The daily repair job now also tidies old counters.

One more snag: Vercel blocked a deploy. Now that the code is in git, Vercel refused it because the commit author isn't on your Vercel team. I added scripts/deploy-web.sh, which deploys from a copy without git history. I also cleared the counters and hid the 20 new test reports, so you can film without being limited.

Still can't test without you
- Two people on the Case Board at once. To try it, open the Case Board in two browser windows and drag a card in one.
- A real screen reader.
- The daily repair job, which first runs tomorrow at 04:00 UTC.

Everything is committed and pushed to your private cfo repo.

About the video: I'd suggest the hybrid plan. I record the public-website part automatically with on-screen captions, and you record only the Case Board and Studio clips (about 30 seconds) plus a voice-over. Or you record everything yourself from the shot list. Which do you prefer?

Agent

Tiles load fine here (only aborted prefetches). Checking what it rendered.

Agent

The public map renders fine. The blank one is the Studio input, which likely lacks the worker setup that MapLibre 6 needs. I'll check its code.

Agent

CORS is open on the Studio host. Deploying the Studio with the CLI login.

Agent

Deployed and served. I'll reload the Studio tab in Chrome and check the map.

Agent

That F5 went to VS Code instead of Chrome, because VS Code had focus. It looks harmless, but I'll stop driving your screen blind. I'll log the findings, then hand back.

You

video is good, just make the strings more visible and red, they are hardly visible

Agent

The strings on the Case Board are thin and greyish in the recording. I'll look at how they're styled.

Agent

The CSS already asks for red, but React Flow's own stylesheet (grey, 1 px) is winning over it. I'll raise the specificity, thicken the strings and make them a stronger red.

Agent

The type-check passes. My stronger selector would also override the reduced-motion rule, so I'll fix that too, then deploy the Case Board.

Reading a web page as Markdown, from inside the browser

Mohammed Abdul Mubeen Khan — Tue, 22 Sep 2026 13:00:00 +0000

Screenshotline takes screenshots of web pages. It also returns the same page as Markdown, from the same render, and that second endpoint gets more use than I expected when I built it.

The reason is simple. A screenshot is for a person. If the thing reading the page is a script or a model, handing it a PNG is the wrong shape: it has to run OCR or a vision model to recover text that was sitting in a DOM a moment earlier. That is slower, lossier and more expensive than just giving it the text.

So /extract runs the identical pipeline as /take and returns Markdown instead of pixels. Everything that makes the picture correct — the adaptive settle, the consent sweep, the collapsed ad slots, the scroll that triggers lazy images — makes the text correct for exactly the same reasons.

This post is about the part I got wrong first: where the extraction should happen.

Parse the DOM, not a copy of it

The obvious approach is to pull the HTML out of the browser and run it through a good server-side library. Readability to find the article, Turndown to convert it. Both are better than anything I would write at handling edge cases.

I went the other way: a dependency-free walker that runs inside the page, via page.evaluate, on the DOM that is already rendered. Not because the libraries are bad, but because by the time we are extracting, the browser has already done work that a serialised copy throws away.

Here is the clearest example. On danluu.com, the list of posts is written like this, with no whitespace at all between the elements:

<d>09/26</d><a href="...">Some post title</a>

<d> is not a real element, and the page styles it as a 4em flex item. Read the markup as text and you get 09/26Some post title. Read the computed layout and you can see the browser gives <d> a box, so there is a visual gap, so the text needs a space:

const LAID_OUT = /^(block|flex|grid|table|list-item|flow-root|table-cell|inline-block|inline-flex)/;
const laidOut = (el) => {
  const style = styleOf(el);
  return style ? LAID_OUT.test(style.display) : false;
};

Any unknown element the browser lays out as a box gets a space around its contents. That rule only exists because the extraction can ask the browser what it actually did.

Three more things come free in the same place:

Hidden content stays out. display: none, visibility: hidden and opacity: 0 are computed values. A tab panel that isn't open, or a mobile menu that only exists at narrow widths, would otherwise be indistinguishable from real content in the markup.

Shadow roots are reachable. innerText and querySelectorAll do not cross a shadow boundary, so a site built out of web components extracts as an empty document. Walking into open shadow roots is a few lines:

const childNodesOf = (node) => {
  const shadow = node.shadowRoot;
  if (shadow) return [...shadow.childNodes, ...node.childNodes];
  return [...node.childNodes];
};

Closed roots are unreachable by design, and nothing can be done about those. The same blind spot once hid a full-page consent modal from the screenshot sweep on dw.com, so it is worth knowing about in both directions.

The consent banner is already gone. By extraction time the sweep has removed it, and ad slots that were blocked have been collapsed and marked, so the walker can skip them by attribute. Nothing has to recognise a cookie wall twice.

The text arrives later than the page does

This is the part people underestimate, and it has nothing to do with Markdown.

timesofindia.indiatimes.com returns 446 characters of text if you extract after a 5-second settle, and 48,755 if you wait 15. Both responses are a clean 200. Nothing in either one says "this page wasn't finished".

That is why the extractor reuses the render pipeline's settle budget instead of grabbing text as soon as the DOM is ready: the budget keeps waiting while the page's text is still growing and stops early once there is plainly enough. A Markdown endpoint with a fixed 3-second wait would look fast and quietly return a header and a spinner on every heavy news site.

The same logic protects the sweep. The consent heuristic refuses to remove any element carrying more than 1,500 characters of text, because on france24.com it was eating about 1,200 characters of actual article.

Markdown that survives real pages

A few structural decisions, each from a page that broke the naive version.

Link-wrapped headings. Most news front pages are built as a card where an <a> wraps an <h2>. Emitted in the obvious order, that becomes [# Headline](url), which is neither a heading nor a link. So a heading inside a link is hoisted back out and the link goes inside it:

const heading = raw.match(/^\s*(#{1,6})\s/);
if (heading) return `\n\n${heading[1]} [${text}](${href})\n\n`;

Relative URLs are resolved against document.baseURI, for links and for images, because a Markdown document that leaves the page behind needs absolute links. data: image sources are dropped rather than inlined — a base64 blob is not useful to a reader and can be enormous.

Tables become pipe tables , with | inside a cell escaped. Lists keep their nesting, and continuation lines are indented to line up under the marker, so a multi-line list item does not break out of its list.

Page furniture is dropped, but carefully. With strip_chrome on, which is the default, nav, header, footer, aside, the matching ARIA roles and aria-hidden="true" are removed. Then there is a check that matters more than the rule itself:

let md = render();
if (options.stripChrome && md.replace(/\s/g, '').length < 200) {
  // Stripping took the page with it.
  for (const [el] of stripped) el.removeAttribute('data-screenshotline-hidden');
  md = childNodesOf(root).map((n) => walk(n, { depth: 0 })).join('');
}

Plenty of real sites put their only content inside an <aside> or hang it off a <nav>. If stripping the furniture empties the document, the whole thing is rendered again with the furniture left in. Returning a stub because the page's markup was unusual is worse than returning something slightly noisy.

There is a related lesson from the screenshot side. The consent sweep once ate apnews.com's entire site header — 1,022 links and two <nav> elements — because a trending headline said "Girl Scout cookies" and the keyword test matched_cookies_. Structural rules ("a consent banner is never the site's navigation") hold up where keyword rules do not.

Using it

# Markdown, as text
curl "https://api.screenshotline.com/extract?url=https://example.com" \
  -H "X-Access-Key: $KEY"

# Or JSON, with the title and character count
curl "https://api.screenshotline.com/extract?url=https://example.com&response=json" \
  -H "X-Access-Key: $KEY"

strip_chrome=false keeps the navigation. max_chars=20000 truncates and appends a [truncated] marker, which is handy when the text is going into a context window. The blocking options (block_ads, block_cookie_banners, block_chats, block_popups) work the same as for a screenshot. X-Text-Length on the response tells you how much text came back without parsing the body.

For agents there is a hosted MCP server with the same two operations, screenshot and read_page:

claude mcp add --transport http screenshotline \
  https://api.screenshotline.com/mcp --header "X-Access-Key: $KEY"

What this is not

It is not a readability clone. It does not try to find the one true article and throw everything else away, because a front page, a docs page and a product listing are all legitimate things to read and none of them has an article in the middle. It strips furniture, keeps structure, and leaves the judgement to whatever is reading.

It does no summarising, and no cleverness beyond the DOM. There is no model in this path at all — which I mention because "web page to Markdown for LLMs" usually implies one.

And it does not get past bot walls. If a page shows a captcha, you get the captcha's text, and a blank page is flagged in a response header instead of being returned as a success.

The code is one file, src/extract.js, about 250 lines, no dependencies: read it here. The hosted API has 500 free renders a month and no card, and the whole thing self-hosts with Docker.

Self-hosting a screenshot API with Docker, and what it will cost you

Mohammed Abdul Mubeen Khan — Thu, 17 Sep 2026 13:00:00 +0000

Screenshotline is a screenshot API, and it is open source. The renderer behind the hosted API is the same code that's in the repo, with nothing held back. So you can run the whole thing yourself.

The repo already has a short self-hosting guide. This is the longer version, with the reasons. Most lines in the compose file are there because something went wrong without them, and knowing what went wrong is how you tell which ones you can change.

Should you self-host at all?

First, a plain answer to the question most people are really asking.

Self-host when your screenshots have to stay on your own infrastructure, when you want to read the code before you trust it, or when you need to capture pages that only exist on your internal network.

Don't self-host just to save money at low volume. The hosted free tier is 500 renders a month with no card. Above that, a small VPS costs less per month than a paid plan, but the server isn't the real cost. Your time is: keeping Chrome up to date, noticing when renders start failing, and debugging a page that wedged the browser at 2am. If you'd rather not own that, the hosted API is the same renderer run by someone else.

If you're still here, let's run it.

Step 1: run it

git clone https://github.com/MAMubeenKhan/screenshotline.git
cd screenshotline
docker compose up -d

curl -o out.png "http://localhost:3000/take?url=https://example.com"

That's the whole setup. /take returns the image bytes directly, with no JSON wrapper, so the same URL also works inside an <img src>.

Then open out.png. Don't settle for checking that curl exited cleanly or that the file isn't empty. The failure this project spends most of its code on is a 200 OK with the wrong picture in it, and a file size can't tell you that. Only looking can.

Step 2: understand the compose file

Here are the parts that matter, and why each one is there.

init: true

Reaps zombie Chrome processes. When Chrome crashes mid-render, its child processes are orphaned. Inside a container, PID 1 is supposed to reap orphans, and if PID 1 is your Node process, nothing does. They sit there as <defunct> while the pool believes those slots are free. Throughput slowly collapses with no obvious cause. The Dockerfile already runs tini as PID 1, so init: true is redundant. It's harmless, and it makes the requirement explicit in the file people actually read.

shm_size: "1gb"

Chrome uses /dev/shm for shared memory, and Docker's default is 64 MB. That's not enough for image-heavy pages. The renderer also passes --disable-dev-shm-usage. Either fix works on its own, and having both does no harm.

volumes:
  - cache:/app/.cache
  - data:/app/.data

Two volumes, and only one of them matters. The cache can be thrown away and refilled. /app/.data holds the SQLite database with accounts, API key hashes and usage counters, and it's only used if you turn on BILLING_ENABLED. If that volume is missing, a redeploy silently deletes everything. The app then comes back up healthy and empty, which is the worst way for it to fail.

security_opt:
  - no-new-privileges:true
deploy:
  resources:
    limits:
      memory: 3g

The renderer runs untrusted pages, so treat it that way. Chrome runs as a non-root user inside the image. The memory limit means a runaway browser gets killed inside the container, not somewhere on the rest of your machine.

Step 3: size the pool

Everything is configured with environment variables. These four decide how the server behaves under load:

POOL_SIZE=2 # concurrent renders, one browser each
MAX_RENDERS_PER_BROWSER=50 # recycle a browser after this many renders
MAX_BROWSER_AGE_MS=1800000 # ...or after 30 minutes, whichever comes first
RENDER_TIMEOUT_MS=30000 # wall-clock ceiling; then the browser is killed

POOL_SIZE is the number of Chrome instances, and each one renders a single page at a time. One CPU core handles a pool of 1 comfortably. Give it 2 cores for a pool of 2. Past that, you're mostly buying memory.

The recycling settings exist because Chrome doesn't give memory back across navigations. A browser that has rendered a few hundred pages is much bigger than a fresh one. In an early five-minute load test with four browsers recycling every 25 renders, memory rose from 1,344 MB to a peak of 1,619 MB and ended at 1,150 MB. That was 817 renders with zero failures. The graph was a sawtooth, not a slope, and the sawtooth is what you want to see. If you raise MAX_RENDERS_PER_BROWSER a long way, expect the slope instead.

RENDER_TIMEOUT_MS is enforced by killing the browser, not by asking it to stop. A page that blocks its own main thread also blocks page.close(), so the polite way out hangs as well. Pages that do this are uncommon but real, and without a hard ceiling one of them takes a pool slot with it.

A good starting point is 2 GB of RAM and a pool of 2. After that, change one number at a time and watch memory while you do.

Step 4: lock it down

With no configuration, the API runs in open mode: anyone who can reach port 3000 can render anything. That's fine on your laptop, and a bad idea anywhere else.

Set access keys. They're comma-separated, and clients send one as an X-Access-Key header or as ?access_key=:

ACCESS_KEYS=key-for-app-one,key-for-app-two

Sign URLs that appear in public HTML. The main reason to return raw image bytes is so you can write <img src="https://screenshots.example.com/take?url=...">. But a key in that URL can be read by anyone who views the page source, and then they can use your server. Signed URLs solve this: set SIGNING_SECRET, and the server accepts a request carrying an HMAC-SHA256 of its own sorted query parameters. Changing any parameter, including the target URL, breaks the signature.

import crypto from 'node:crypto';

function signedUrl(base, params, secret) {
  const query = Object.keys(params)
    .sort()
    .map((k) => `${encodeURIComponent(k)}=${encodeURIComponent(String(params[k]))}`)
    .join('&');
  const signature = crypto.createHmac('sha256', secret).update(query).digest('hex');
  return `${base}?${query}&signature=${signature}`;
}

signedUrl('https://screenshots.example.com/take',
  { url: 'https://example.com', full_page: 'true' }, process.env.SIGNING_SECRET);

The repo also has a command-line version: node tools/sign.js "https://example.com" full_page=true. Once every URL you publish is signed, set REQUIRE_SIGNATURE=true so unsigned requests are refused outright.

Leave ALLOW_PRIVATE_HOSTS off, unless you have a reason and have isolated the server. By default the renderer refuses private and reserved addresses: localhost, the RFC 1918 ranges, and the cloud metadata address 169.254.169.254. It checks again after every redirect, so a public URL that redirects inward is refused too. Without that check, a screenshot API is a very convenient way to read your cloud credentials.

If internal dashboards are your whole reason for self-hosting, that flag is what you need. But turning it on lets the renderer reach everything on its network. So it must not also be reachable from the internet, and it should sit on a network segment where "everything" means very little.

A known gap: DNS rebinding. The renderer resolves the hostname to check it, and then Chrome resolves it again on its own. A DNS record that changes between those two lookups can get past the check. Literal private IPs are refused for every subresource, but a hostname that resolves to one is only checked at navigation. It's documented in SECURITY.md rather than ignored. It's also another reason to run the renderer where there's nothing worth reaching.

Step 5: HTTPS with Caddy

Don't expose the Node process directly. Put Caddy in front of it and it gets and renews certificates on its own:

screenshots.example.com {
    reverse_proxy app:3000 {
        transport http {
            read_timeout 120s
            write_timeout 120s
        }
    }
}

Two details here matter more than they look.

The long timeouts. A slow page can legitimately take 30 seconds to render. If the proxy gives up first, the client sees a vague 502 instead of the app's own clear render_timeout error. The proxy's timeout should always be longer than the app's.

transport has to be nested inside reverse_proxy. Written as a sibling directive, Caddy refuses to start. Under restart: unless-stopped, that becomes a restart loop with nothing on screen to tell you. Run caddy validate before every restart.

Caddy also needs your DNS records pointing at the server before it first starts, because Let's Encrypt checks domain ownership by connecting back to the machine.

Step 6: know when it breaks

There are two health endpoints, and they answer different questions.

/healthz says the process is answering. It stays green while Chrome is broken, so on its own it will tell you everything is fine during an outage.
/healthz/render actually renders a page and returns 503 if that fails. So it doesn't become a free renderer, it does at most one real render a minute, and every other call gets the last result.

Point your uptime monitor at /healthz/render. And run the monitor somewhere other than the server itself. A status check on the same box goes down with the box, and you only find out once the box is back.

Every capture also carries response headers worth logging. X-Render-Ms gives the render time. X-Upstream-Status is the status code the target page returned. X-Blank-Suspected is set when the capture looks blank, judged from both the page's DOM and how little the encoded image weighs per pixel. Pass fail_on_blank=true to turn that into an error instead of an image.

The 202-site benchmark I use for every change is in the repo under bench/, along with the smoke tests. Run them after upgrading, then look at the images they write. A suite that counts a captcha as a successful capture is exactly the kind of failure it exists to catch.

What you don't get by self-hosting

To be clear about what the repo is: it's the renderer, the API, the cache, and the optional accounts and billing code. What the hosted version adds is operational: a warm pool, a shared cache, updates, and someone else watching it. It doesn't have extra rendering features.

Things neither version does, on purpose: video capture, proxy rotation, getting past captchas, and async jobs with webhooks. If a site shows a bot wall, you get a picture of the bot wall. If it's blank, the header tells you.

It's licensed AGPL-3.0. You can run it, modify it, and self-host it freely. If you offer a modified version to other people over a network, you have to publish your changes. Calling the API from your own application doesn't make that application AGPL.

If you run it and something doesn't work on a clean machine, please open an issue. The compose file working the first time is a promise, and a broken promise is a bug. If you'd rather not run it at all, the hosted version has 500 free renders a month and doesn't need a card.

Six things that break when you run headless Chrome at scale

Mohammed Abdul Mubeen Khan — Mon, 14 Sep 2026 13:00:00 +0000

Taking one screenshot with Puppeteer is twenty minutes of work. Taking a few million is a different job entirely.

I found that out building Screenshotline, a screenshot API. What surprised me was not how much broke. It was how little of it looked broken. Almost nothing crashed. The failures were a 200 OK with the wrong picture in it — a cookie wall, a half-loaded page, a grey hole, a blank white frame — which a pipeline records as a success and nobody notices for a month.

So I built a benchmark of 202 real websites — news sites, shops, SaaS sites, docs, government pages, sites in other languages and scripts — and ran every change against it. The failures were consistent enough to be worth writing down. Here are the six that cost the most, each with the fix and the actual code, and then the bug that was worse than all of them.

1. Consent banners arrive after the page settles

The symptom. Your screenshot is a cookie wall, even though you remove cookie banners.

Why it happens. The obvious approach is a sweep at capture time: find the consent dialog, remove it, take the picture. But many sites inject the banner late — after the page has loaded, sometimes after the network has gone quiet. nytimes.com is one. A sweep that runs at capture time is simply too early, and it loses that race every time.

The fix. Don't sweep once. Install a watcher before any of the page's own scripts run, and keep sweeping every time the DOM changes:

await page.evaluateOnNewDocument(COOKIE_OBSERVER_SCRIPT);

where the script is, in part:

const schedule = () => {
  if (scheduled) return;
  scheduled = setTimeout(run, 50);
};

const start = () => {
  if (!document.documentElement) return requestAnimationFrame(start);
  new MutationObserver(schedule).observe(document.documentElement, {
    childList: true,
    subtree: true,
  });
  run();
};

The 50ms debounce matters: a busy page mutates its DOM thousands of times, and sweeping on every mutation would be pure waste.

One more thing that took a while to find: some consent managers render inside a shadow root, and querySelectorAll does not cross a shadow boundary. On dw.com the sweep was looking straight past a full-page modal. The sweep now walks open shadow roots too.

2. Pages that never go network-idle

The symptom. Timeouts on pages that load perfectly well in your browser.

Why it happens. networkidle2 — wait until there are no more than two network connections for half a second — is the obvious default, and it is wrong for the real web. Plenty of sites hold a connection open forever for analytics beacons, long-polling or ad refresh. They painted seconds ago; they will never be "idle". Across the
benchmark, waiting for it caused 18 hard timeouts. Waiting for load instead gave a median of 23 seconds, because 16 of the 20 SaaS pages in the su

The fix. Navigate to domcontentloaded, then spend one bounded settle budget on the things that actually affect the picture — load if it comes soonages and video in view decoding — and capture when the budget runs out:

response = await page.goto(options.url, { waitUntil: options.waitUntil });
// ...
const deadline = Math.min(
  Date.now() + options.settle,
  startedAt + options.timeout - 6000,
);

The second line of that Math.min is a lesson on its own: the settle budget has to leave room for the capture inside the overall timeout, or a page that takes 24 seconds to navigate settles its way straight past a 30-second ceiling.

A fixed budget still can't serve both a static page and a heavy news homepage. timesofindia.indiatimes.com returned 446 characters of text with a 5-second settle and 48,755 with 15 seconds — and the short version came back as a clean 200. So the settle has an adaptive tail: it keeps waiting while the page's text is still
growing, and stops early once there is plainly enough of it.

3. Pages that wedge their own main thread

The symptom. A single page times out, and takes a browser down with it.

Why it happens. When a page blocks its main thread, everything you ask of it hangs: page.evaluate, page.screenshot, and even page.close(). Nons own. vercel.com did this in the benchmark: the document was complete at 3.6 seconds, then four JavaScript chunks stayed in flight forever and the pagestopped answering anything. One stuck page burns the whole render budget.

I blamed this on concurrency for longer than I'd like to admit. Then I ran the page on its own, with nothing else happening, and watched it hang there too.

The fix. Every wait gets its own ceiling. Anything you ask the page for is optional — a measurement, a sweep — so time it out and carry on with what is already on screen:

function atMost(promise, ms) {
  return Promise.race([
    promise.catch(() => null),
    new Promise((resolve) => setTimeout(() => resolve(null), ms)),
  ]);
}

function evaluateAtMost(page, script, ms, fallback = null) {
  return atMost(page.evaluate(script), ms).then((v) => (v === null ? fallback : v));
}

And a page that misses one deadline has almost always stopped answering for good, so after the first miss, stop asking — every further timed-out call ishole has a wall-clock ceiling, and when it fires the browser process is killed, not politely closed: close() waits on the very thing that hung.

4. Blocked ads leave a hole

The symptom. You block ads, and the screenshot has a big grey rectangle pushing the real content below the fold.

Why it happens. Blocking the ad request stops the ad. It does not give back the space: the page reserved that slot's height before the ad arrived, a

The fix. After the page has settled, find ad containers that are still empty and collapse them. The part that matters is not collapsing anything rea— whole class-name tokens, never substrings, because a substring match on "ad" eats header, shadow, download and gradient:

for (const token of raw.split(/[^a-z0-9]+/)) {
  if (!token) continue;
  if (AD_TOKENS.has(token)) return true;
  for (const p of AD_PREFIXES) if (token.startsWith(p)) return true;
}

and a slot is only collapsed if it has no text, nothing painted inside it, and is not large enough to be the page itself. It runs after the settle, sohouse ad is left alone. On france24.com this took the capture from 122KB to 234KB of actual content.

(A caution about that number: file size is a bad proxy for quality in both directions. Removing a consent modal makes a capture smaller, and one compere was blurry because it was taken mid-paint. Open the image. Always open the image.)

5. The blank capture

The symptom. None, which is the problem. A bot wall or a page that needs JavaScript you blocked renders a blank white frame, the API returns 200, an success.

The fix. Detect it, and say so in a response header. Neither signal is trustworthy alone. An empty DOM flags legitimately sparse pages (badssl.com iackground), and low bytes-per-pixel flags anything simple. So both have to agree:

const domBlank = content.textLength < 20 && content.images === 0 && content.elements < 15;
const visuallyBlank = calibrated && bytesPerPixel < 0.008 && content.textLength < 400;
const blankSuspected =
  detectorApplies &&
  options.format !== 'pdf' &&
  (visuallyBlank || (domBlank && (!calibrated || bytesPerPixel < 0.03)));

Two details in there each came from a real mistake. detectorApplies is false for a successful response that isn't HTML: Chrome's own JSON or image viewer is legitimately sparse, and a JSON endpoint was being flagged as a blank capture. And calibrated restricts the pixel signal to the configuration its thresholds were measured on
— a PNG of a normal viewport — because bytes-per-pixel measures the encoding as much as the page. A 3840×4320 capture of a small page is mostly white wrong, and a quality-1 JPEG is tiny whatever it shows.

Honest reporting also meant going through every "hard" page that passed by hand. Of the 20 pages the suite marks as known-hard, 14 returned something.uinely the real page, 2 were captchas that a naive count would have scored as wins, and 1 was a dead URL in my own test suite.

6. Zombie Chrome

The symptom. Throughput slowly collapses and memory climbs, with no obvious cause.

Why it happens. When Chrome crashes mid-render, its child processes are orphaned. Inside a container, whatever is PID 1 is supposed to reap orphans rocess, nothing does. They sit as <defunct> entries forever, while your pool believes those slots are free.

The fix is one line, and it cost me an afternoon to find:

ENTRYPOINT ["/usr/bin/tini", "--"]

(docker run --init, or init: true in Compose, does the same.) Pair it with recycling each browser after a fixed number of renders, because Chrome dos navigations.

The bug that had no symptom

Two things I got wrong are worth more than the list above.

The consent-banner heuristic ate apnews.com's entire site header one day. Its trending strip carried the headline "Girl Scout cookies". The keyword testn-word test — looking for buttons like "OK" and "Accept" — matched ok inside c-o-ok-i-e-s, because I had not put word boundaries in the regex. One word in a news headline passed both tests, and the sweep removed a header containing 1,022 links and two <nav> elements. The fix that actually holds is structural rather than lexical: a consent banner is never the site's navigation.

Then, fixing that, I introduced something worse.

The scripts that run inside the page are built as JavaScript template literals — backtick strings — so they can be injected with evaluateOnNewDocument. Inside a template literal, a lone \b is not a word boundary. It is an escape sequence, and it collapses into a single backspace character, U+0008. So my new, correct-looking
regex:

const SWEEP_BODY = `
  const ACTIONS = /\b(accept|agree|reject|allow|ok)\b/i;
`;

compiled, inside the page, into a regex that matched a backspace, which never appears on a web page. It matched nothing. The whole consent heuristic wass. Every test passed. Every page still rendered. The apnews header "survived" my new guard only because the heuristic had stopped removing anything atall.

Inside a template literal, every backslash has to be doubled:

const ACTIONS = /\\b(accept|agree|reject|allow|manage|continue|got it|ok|okay)\\b/i;

and \b is not the only one: \f, \v and \0 collapse the same way, and \s quietly becomes the letter s. There is now a test that scans every script we inject for control characters — shown here with escapes, because the real test file contains the characters themselves:

const collapsed = /[\x00\x08\x0B\x0C]/;
for (const [name, src] of Object.entries(scripts)) {
  const at = src.search(collapsed);
  assert(at === -1, `${name} contains a control character at ${at}`);
}

That test is the only reason this class of bug is visible at all. Nothing else in the system could have noticed: the code was valid, the pages rendered, and the output was merely wrong.

What I'd tell someone starting

Screenshotline's benchmark numbers today: of the 182 pages in the suite that should work, all 182 capture correctly, with a median of 5.7 seconds on the benchmark machine. The other 20 are named as hard, and the ones that return something are checked by eye.

If you need screenshots at volume, you can absolutely build this yourself — every fix above is a few dozen lines. But you will own this list, and the list grows. That is the whole case for an API.

Screenshotline is open source (AGPL-3.0): the renderer that runs the hosted API is the same code, with nothing held back. If you'd rather someone else's pager went off, the hosted version has 500 free renders a month and no card.