Puppeteer screenshot feature by tintinthong · Pull Request #4634 · cardstack/boxel

tintinthong · 2026-05-04T12:12:31Z

Card Screenshot Infrastructure

End-to-end screenshot capture for any Boxel card. Open the new
Screenshot Card Demo in the experiments realm, link a card, pick
isolated or embedded, click Take Screenshot — a fully-painted
PNG is rendered through the existing Puppeteer prerender pool, written
into the card's own realm under Screenshots/, and shown inline.

What's in the PR

Phase 1 — Prerender API. POST /_screenshot-card on the
realm-server. Queue-backed, mirroring /_run-command. Returns base64
PNG + dimensions.
Phase 2 — Host command. ScreenshotCardCommand callable
in-process or via /_run-command. Writes the PNG to the card's realm
via WriteBinaryFileCommand. Hard-fails if the caller can't write
there.
Phase 3 — Demo card. ScreenshotCardDemo in
packages/experiments-realm — the harness that drives the full flow
with one button.

Phase 4 (wiring into listing-create) lives in a separate repo / PR.

How to test

Bring up the standard local-dev matrix (realm-server,
prerender-server, prerender-manager, worker, host).
In the experiments realm, create a Screenshot Card Demo
instance.
Link a card (e.g. Author/alice-enwunder or
ImageDefPlayground/mango-demo).
Edit the Format field — pick isolated or embedded from the
dropdown.
Click Take Screenshot.

Expected: the result section appears with a realm URL and an inline
PNG preview that fully shows the card content — no spinners, no empty
image placeholders. The file lands at
packages/experiments-realm/Screenshots/<slug>-<uuid8>.png.

If you want to hit the API directly:

curl -X POST http://localhost:4201/_screenshot-card \
  -H "Authorization: Bearer $REALM_SERVER_JWT" \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{"data":{"type":"screenshot-card","attributes":{
        "realmURL":"http://localhost:4201/experiments/",
        "cardId":"http://localhost:4201/experiments/Author/alice-enwunder",
        "format":"isolated"}}}' \
  | jq -r '.data.attributes.base64' | base64 -d > /tmp/card.png && open /tmp/card.png

format must be "isolated" or "embedded". runAs is derived from
the JWT.

Automated tests

cd packages/realm-server
TEST_MODULES="screenshot-card-test.ts,prerender-proxy-test.ts" \
  npx qunit --require ts-node/register/transpile-only tests/index.ts

TEST_MODULES="server-endpoints/run-command-endpoint-test.ts,server-endpoints/screenshot-card-endpoint-test.ts" \
  pnpm run test

10/10 each. The server-endpoints test must run alongside another
server-endpoints test (shares cached realm setup).

Notes for reviewers

Settle + image-paint waits — captureScreenshot in
packages/realm-server/prerender/utils.ts calls
__waitForRenderLoadStability() (existing) and a new
waitForImagePaint() that waits for <img> elements, CSS
background-image URLs, and document.fonts.ready before capture.
Without the second wait, avatars and thumbnails would be missing in
the PNG.
Three forwarding layers — realm-server (/_screenshot-card),
prerender-manager (/prerender-screenshot proxy), prerender-server
(/prerender-screenshot route). Easy to forget the manager.
Output is imageDefUrl: string, not linksTo(ImageDef) — we
tried the cleaner relationship form, but the framework's
link-resolution lifecycle on a freshly-written PNG took a path the
auth service worker didn't cover (manifested as "Missing
Authorization header"). Plain <img src=URL> goes through the SW
reliably (same path that makes ImageDefPlayground/mango.png
render). Cleaner relationship is a follow-up.
Permission policy — ScreenshotCardCommand writes the PNG into
the card's own realm. If the caller lacks write access there it
throws; no silent fallback.
Concurrency group on the queue is screenshot:<realmURL>,
mirroring command:<realmURL> for run-command.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b9812a8af5

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-05-04T12:18:34Z

+export type ScreenshotPrerenderArgs = {
+  realm: string;
+  url: string;
+  auth: string;
+  format: 'isolated' | 'embedded';
+};


Thread screenshot priority through prerender call chain

/_screenshot-card enqueues with userInitiatedPriority, but the screenshot prerender API drops that signal because ScreenshotPrerenderArgs has no priority field (and the task call therefore cannot forward jobInfo.priority). In busy environments (for example while indexer traffic is active), screenshot renders will compete at default priority and can be delayed behind background work, unlike runCommand which explicitly forwards priority to prerender queues.

Useful? React with 👍 / 👎.

Copilot

Pull request overview

Adds the Phase 1 backend plumbing for a queue-backed “screenshot a card render” flow, wiring realm-server → queue/worker → prerender-server → Puppeteer page.screenshot() and returning a JSON:API envelope containing base64 PNG output.

Changes:

Introduces a new screenshot-card queue job + worker task that checks permissions and calls prerenderer.prerenderScreenshot(...).
Adds a new realm-server endpoint POST /_screenshot-card plus tests for request validation and handler/job wiring.
Extends the prerender-server with a /prerender-screenshot route and Puppeteer capture implementation.

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/runtime-common/worker.ts	Registers the new `screenshot-card` job type with the worker queue.
packages/runtime-common/tasks/screenshot-card.ts	Implements the worker task: permission checks + calls `prerenderer.prerenderScreenshot`.
packages/runtime-common/tasks/index.ts	Exports the new screenshot task.
packages/runtime-common/jobs/screenshot-card.ts	Adds the enqueue helper + timeout/concurrency group for screenshot jobs.
packages/runtime-common/index.ts	Introduces screenshot prerender request/response types and extends the `Prerenderer` interface.
packages/realm-server/routes.ts	Wires `POST /_screenshot-card` into the realm-server router behind JWT middleware.
packages/realm-server/handlers/handle-screenshot-card.ts	Implements the endpoint handler: validates JSON:API body, enqueues job, returns result.
packages/realm-server/prerender/utils.ts	Adds Puppeteer capture helper `captureScreenshot()` (settle + screenshot + error detection).
packages/realm-server/prerender/render-runner.ts	Adds `captureScreenshotAttempt` to drive the screenshot render flow on a pooled page.
packages/realm-server/prerender/prerenderer.ts	Exposes `prerenderScreenshot()` on the prerender-server’s local `Prerenderer` implementation.
packages/realm-server/prerender/prerender-app.ts	Adds `/prerender-screenshot` route parsing + dispatch to `prerenderer.prerenderScreenshot`.
packages/realm-server/prerender/remote-prerenderer.ts	Adds remote client support for calling `/prerender-screenshot`.
packages/realm-server/tests/screenshot-card-test.ts	Adds handler-level tests that assert the job enqueue shape and response forwarding.
packages/realm-server/tests/server-endpoints/screenshot-card-endpoint-test.ts	Adds endpoint validation tests (auth required, required attrs, invalid JSON/format).
packages/realm-server/tests/index.ts	Registers the new tests in the realm-server test suite.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

+    let result = await prerenderer.prerenderScreenshot({
+      realm: normalizedRealmURL,
+      url: cardId,
+      auth,
+      format,
+    });


+    let rawAffinityValue = attrs.affinityValue;
+    let rawFormat = attrs.format;
+    let renderOptions = parseRenderOptions(attrs);
+    let formatIsValid = rawFormat === 'isolated' || rawFormat === 'embedded';
+    let missing = missingAttrs([
+      { value: rawUrl, name: 'url' },
+      { value: rawRealm, name: 'realm' },
+      { value: rawAuth, name: 'auth' },
+      {
+        value: rawAffinityType === 'realm' ? rawAffinityType : undefined,
+        name: 'affinityType',
+      },
+      { value: rawAffinityValue, name: 'affinityValue' },
+      {
+        value: formatIsValid ? rawFormat : undefined,
+        name: 'format',
+      },
+    ]);
+    return {
+      args:
+        missing.length > 0
+          ? undefined
+          : {
+              affinityType: 'realm',
+              affinityValue: rawAffinityValue as string,
+              realm: rawRealm as string,
+              url: rawUrl as string,
+              auth: rawAuth as string,
+              format: rawFormat as 'isolated' | 'embedded',
+              renderOptions,
+            },


habdelra · 2026-05-04T16:03:48Z

+    const { page, reused, launchMs, waits, pageId, release } =
+      await this.#getPageForAffinity(affinityKey, auth, 'file', signal);
+    const poolInfo: PoolInfo = {


this is a new capability. in order to make sure that your prerender requests are prioritized above background reindexing, you should thread thru the job priority. this should already be happening for commands, modules, and indexing. so use those examples.

github-actions · 2026-05-04T12:50:51Z

Preview deployments

Host staging preview

Host production preview

Host Test Results

1 files ± 0 1 suites ±0 3h 57m 19s ⏱️ + 1h 56m 15s
2 564 tests + 1 2 538 ✅ - 10 15 💤 ± 0 0 ❌ ± 0 11 🔥 +11
5 166 runs +2 584 5 114 ✅ +2 547 30 💤 +15 11 ❌ +11 11 🔥 +11

Results for commit 42f73fc. ± Comparison against earlier commit f11f64b.

For more details on these errors, see this check.

Realm Server Test Results

1 files ± 0 1 suites ±0 18m 3s ⏱️ -9s
1 238 tests +22 1 238 ✅ +22 0 💤 ±0 0 ❌ ±0
1 316 runs +22 1 316 ✅ +22 0 💤 ±0 0 ❌ ±0

Results for commit 42f73fc. ± Comparison against earlier commit f11f64b.

habdelra · 2026-05-04T15:31:06Z

so one thing that concerns me is that lives live totally outside of our prerendering load handling mechanism. which means that this has the ability to starve chrome tabs from the rest of the system and unwind all the perf work that I'm doing right now. We need to incorporate this into our our prerender queuing and admission system. you can use this ticket for reference https://linear.app/cardstack/issue/CS-10976/create-prerendering-prioritization

UPDATE: you are actually getting the page correctly that respects the queuing and perf considerations

habdelra · 2026-05-04T15:36:39Z

Also, I know that this is triggered from a command, but it seems like this could really benefit from realm affinity such that you don't land on a cold loader or a cold store when you are trying to take a snapshot. i don't think (at least today) that the user auth for the realm affinity would be different than the user auth for the user affinity when you are doing a screenshot, since for private realms the only user that can access the realm is the user that created it. so this is probably ok. for in the future when we have shared realms this is probably not quite right...

habdelra · 2026-05-04T16:02:28Z

+    );
+
+    const { page, reused, launchMs, waits, pageId, release } =
+      await this.#getPageForAffinity(


ah, nvm about my comment about not using the queue. this is the correct way to get a page that is mindful of the prerender queue 👍

infrastructure for screenshot feature

b9812a8

chatgpt-codex-connector Bot reviewed May 4, 2026

View reviewed changes

tintinthong requested a review from Copilot May 4, 2026 12:19

tintinthong added 2 commits May 4, 2026 20:20

fix lint

c9e4785

add command

8cdb9af

Copilot started reviewing on behalf of tintinthong May 4, 2026 12:23 View session

add card demo

fcf2983

Copilot AI reviewed May 4, 2026

View reviewed changes

tintinthong changed the title ~~infrastructure for screenshot feature~~ Puppeteer screenshot feature May 4, 2026

tintinthong added 2 commits May 4, 2026 22:21

add an example to run inside of experiments

7d1940e

fix copilot review comments

f11f64b

habdelra reviewed May 4, 2026

View reviewed changes

habdelra approved these changes May 4, 2026

View reviewed changes

fix lint

42f73fc

tintinthong merged commit 471cf57 into main May 5, 2026
99 of 102 checks passed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Puppeteer screenshot feature#4634

Puppeteer screenshot feature#4634
tintinthong merged 7 commits intomainfrom
screenshot-feature

tintinthong commented May 4, 2026 •

edited

Loading

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot May 4, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

habdelra May 4, 2026

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 4, 2026 •

edited

Loading

Uh oh!

habdelra commented May 4, 2026 •

edited

Loading

Uh oh!

habdelra commented May 4, 2026 •

edited

Loading

Uh oh!

habdelra May 4, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

tintinthong commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Card Screenshot Infrastructure

What's in the PR

How to test

Automated tests

Notes for reviewers

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot May 4, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

habdelra May 4, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

github-actions Bot commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Preview deployments

Host Test Results

Realm Server Test Results

Uh oh!

habdelra commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

habdelra commented May 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

habdelra May 4, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

tintinthong commented May 4, 2026 •

edited

Loading

github-actions Bot commented May 4, 2026 •

edited

Loading

habdelra commented May 4, 2026 •

edited

Loading

habdelra commented May 4, 2026 •

edited

Loading