Generate Page Builder Thumbnails
Overview
The Studio insert menu shows a grid of block previews. This skill regenerates
that whole set: render every block on a throwaway page, screenshot each one,
and write the result to each block's thumbnail.png.
Read CLAUDE.md → "Page Builder Pattern" first — the paths below are
load-bearing.
How thumbnails actually work here
The source of truth is one thumbnail.png per block, co-located with it:
packages/sanity-blocks/src/<kebab-block>/thumbnail.png ← write this
↓ pnpm --filter studio sync-thumbnails (also runs on postinstall)
apps/studio/static/thumbnails/preview-<kebab-block>.png ← generated, do not editpackages/sanity-blocks/scripts/sync-thumbnails.ts deletes every
preview-*.png in the target directory and re-copies from the block folders.
Anything you hand-write into apps/studio/static/thumbnails/ is gone at the next
install.
Format is fixed by previewImageUrl in
apps/studio/schemaTypes/definitions/pagebuilder.ts, which camelCase→kebab-cases
the schema name and appends .png:
- PNG, not WebP — a
.webpfile 404s and the tile renders empty - 1200×800, matching every existing thumbnail
- filename is the block's directory name (kebab-case:
feature-cards-icon), not the schema type name (featureCardsIcon)
Prerequisites
Playwright MCP is configured. Run a Playwright MCP tool (e.g.
browser_navigate) to verify. It is not committed to this repo, so a fresh clone will not have it. If unavailable, STOP and ask the user:"This skill drives the browser through the Playwright MCP server. Please run this and restart Claude Code:"
claude mcp add playwright -- npx @playwright/mcp@latestDo NOT proceed until the user confirms it is available.
Image tooling.
ffmpegorsharpfor the resize. Check first:command -v ffmpeg.The dev server is running on :3000. Check with
curl -sI localhost:3000. If it isn't, ask before startingpnpm dev:web— don't auto-launch.Sanity credentials, to look at dataset images:
NEXT_PUBLIC_SANITY_PROJECT_ID/NEXT_PUBLIC_SANITY_DATASETandSANITY_API_READ_TOKEN, fromapps/web/.env.local(or.env). Step 3b additionally needsSANITY_API_WRITE_TOKEN— check it is non-empty before uploading, or the POST goes out with an empty bearer and fails confusingly.
Step 1: Discover the blocks
The block list is blockSchemas in
packages/sanity-blocks/src/sanity-blocks.ts — ten at the time of writing. Each
entry maps to a directory packages/sanity-blocks/src/<kebab>/ containing
<kebab>.schema.ts, <kebab>.groq.ts, index.tsx, and thumbnail.png.
For each block, record:
- the directory name (this is the output filename)
- the exported component name — not derivable from the folder (
cta→CTABlock,feature-cards-icon→FeatureCardsWithIcon,hero→HeroBlock). Copy the import block at the top ofapps/web/src/components/pagebuilder.tsx; it already imports all ten with the right specifiers. - which fields carry images or video — read this from
<kebab>.groq.ts, not the schema. The projection is what the component actually receives (see Step 2).
Step 2: Read the components and their GROQ
The render layer is packages/sanity-blocks/src/<kebab>/index.tsx, imported by
apps/web/src/components/pagebuilder.tsx. Read the props of each.
Images are the trap. Components take SanityImageData from
internal/sanity-image, which is what imageFields in
internal/groq-fragments.ts projects:
image: {
// a REAL asset id from Step 3 — this placeholder fails the regex below
// and renders blank, which is the very failure this gate is about
id: "image-<hash>-1200x800-jpg", // asset._ref, flattened to a string
alt: "Placeholder image",
preview: null, // lqip, optional
hotspot: null,
crop: null,
}A raw { _type: "image", asset: { _type: "reference", _ref } } renders
nothing — resolveAssetId rejects it. What passes is an id matching
/^image-[a-zA-Z0-9]+-\d+x\d+-\w+$/, in
packages/sanity-blocks/src/internal/sanity-image.tsx. A leading drafts. is
stripped, so draft asset ids are safe.
Same for video: read the muxVideoFields fragment, don't invent the shape —
and note the hero does not take a plain video (Step 4).
</HARD-GATE>
Step 3: Get image asset ids
Blocks with image fields need a real asset id or they screenshot blank.
3a. Use what's already in the dataset. Query it:
ENV_FILE=$(ls apps/web/.env.local apps/web/.env 2>/dev/null | head -1)
[ -n "$ENV_FILE" ] || { echo "no apps/web/.env.local or .env"; exit 1; }
set -a; source "$ENV_FILE"; set +a
PROJECT_ID=$NEXT_PUBLIC_SANITY_PROJECT_ID
DATASET=$NEXT_PUBLIC_SANITY_DATASET
curl -s -G "https://$PROJECT_ID.api.sanity.io/v2024-01-01/data/query/$DATASET" \
-H "Authorization: Bearer $SANITY_API_READ_TOKEN" \
--data-urlencode 'query=*[_type == "sanity.imageAsset" && !(_id in path("drafts.**"))][0...20]{ _id, originalFilename, metadata { dimensions } }'Ask for 10–20, not 5 — you want options. The drafts.** exclusion matters:
_id sorts drafts.* ahead of image-*, so without it the first ten rows are
draft assets.
Every shell here is a fresh one — re-run the source line in each command
block, or $PROJECT_ID is empty and the URL silently malforms.
This one is a template, not copy-pasteable — substitute {hash}, {w},
{h} and {ext} from the asset's _id. Note the -f: without it a wrong
substitution exits 0 and writes an 87-byte JSON error you will mistake for an
image.
curl -fsS -o "/tmp/preview-<hash>.<ext>" \
"https://cdn.sanity.io/images/$PROJECT_ID/$DATASET/<hash>-<w>x<h>.<ext>?w=400"Read each file to actually see it. Reject anything carrying a third-party mark
— except for the logo blocks: logo-cloud and cta.usedByTeams exist to
show third-party logos, so real brand marks are the correct content there.
</HARD-GATE>
Pick 5–8 varied subjects and spread them across blocks deliberately — one image repeated down the whole grid is a red flag.
3b. Only if the dataset has none, upload placeholders — and ask first, it writes to their dataset:
[ -n "$SANITY_API_WRITE_TOKEN" ] || { echo "SANITY_API_WRITE_TOKEN unset"; exit 1; }
curl -L -o /tmp/placeholder-landscape.jpg "https://picsum.photos/seed/thumb-land/1600/1200"
curl -s -X POST "https://$PROJECT_ID.api.sanity.io/v2024-01-01/assets/images/$DATASET" \
-H "Authorization: Bearer $SANITY_API_WRITE_TOKEN" \
-H "Content-Type: image/jpeg" \
--data-binary @/tmp/placeholder-landscape.jpgThe response's _id (image-<hash>-1600x1200-jpg) is what goes in id. Offer
to delete them in Step 7.
Step 4: Build the preview page
Create apps/web/src/app/thumbnails/page.tsx, importing block components
directly from @workspace/sanity-blocks/<kebab>/index — not through
PageBuilder, which needs Visual Editing context.
Wrap each block so the screenshot step can find it. Use the directory name, since that's the output filename:
<div data-block="feature-cards-icon">
<FeatureCardsWithIcon {...mock} />
</div>Mock data rules:
Contextual copy, not lorem ipsum — a hero gets a real headline, a FAQ gets plausible questions. These are what editors browse.
Rich text is Portable Text, never a plain string:
[{ _type: "block", _key: "k1", style: "normal", markDefs: [], children: [{ _type: "span", _key: "s1", text: "…", marks: [] }] }]Images use the flattened shape from Step 2's gate.
No array item needs
_type— these are plain typed interfaces (FeatureCard,LogoCloudLogo,ShowcaseGridItem), not discriminated unions. Give every item a unique_keyanyway (required onShowcaseGridItemandLogoCloudLogo, optional on the rest), and noteFaqItemneeds a required_idas well as its optional_key.video-featuretakesvideo: { asset: { playbackId, policy: "public", status: "ready", … } }, or renders its copy with no video.The hero is different, and getting it wrong blanks the most prominent tile.
videois not a video — it is a light/dark variant object, each variant carryingmediaTypeplus a poster or a Mux/webm source (hero/hero-video.tsx,HeroVideoData). With no poster and no Mux still it renders nothing, so a full-viewport blank. Give both variants a poster:video={{ light: { mediaType: "sanity", poster: img(POSTER_ID, "…") }, dark: { mediaType: "sanity", poster: img(POSTER_ID, "…") }, }}Don't reach for
as anyor@ts-expect-error. The page type-checks clean if you read the interfaces, and silencing the checker hides exactly the shape mistakes Step 2 warns about — wrong image shape,FaqItemmissing_id— which fail by rendering blank, not by erroring.Don't put a background colour on the wrappers — it adds noise to every tile.
Step 5: Screenshot each block
Use the Playwright MCP tools in sequence:
- Set the viewport —
browser_resizeto 1440×900. - Navigate —
browser_navigatetohttp://localhost:3000/thumbnails. - Wait for render — let the network settle before touching anything.
There is no browser_emulate_media tool, and media emulation alone is not
enough here: the site runs next-themes with attribute="class" and
defaultTheme="system" (apps/web/src/components/providers.tsx), so the theme
is a class on <html> backed by localStorage. Media emulation only wins when no
theme is stored.
The reliable route is to set it directly, then reload:
browser_evaluate: () => {
localStorage.setItem("theme", "light"); // or "dark"
location.reload();
}Then pad to match in Step 6.
</HARD-GATE>
The hero also draws its own lg:fixed strip, #hero-fold
(hero/index.tsx), which stitches into tall captures exactly like the header
does and is not matched by the chrome selector.
Easy to miss, because it only affects some blocks: one shorter than the
viewport captures clean, since the header sits outside the element bounds. One
taller is stitched by scrolling, so the header rides along and bakes in
across the middle of the image — cta at 765px was clean, showcase-grid
at 1402px had the navbar through the centre.
Inject once after navigating, and again after any reload:
browser_evaluate: () => {
const s = document.createElement("style");
s.textContent =
"header,footer,nextjs-portal,#hero-fold{display:none !important}";
document.head.appendChild(s);
}nextjs-portal is the Next dev indicator.
</HARD-GATE>
Then, for each block:
scroll
[data-block="<kebab>"]into view (this is also what loads its images — they areloading="lazy")wait for that block's images to actually decode, rather than guessing a delay:
browser_evaluate: target: [data-block="<kebab>"] element: "the <kebab> block" function: (element) => { const imgs = [...element.querySelectorAll("img")]; return { total: imgs.length, loaded: imgs.filter((i) => i.complete && i.naturalWidth > 0).length, }; }The one-argument form receives the resolved element named by
target— you cannot pass it a selector string, so query relative toelementrather than reaching fordocument.It returns counts, not a boolean, because
.every()is true for a block with no images at all — which is exactly the blank capture you are trying to catch. Comparetotalagainst the images your mock gave that block: equal and fullyloadedmeans go;total: 0on a block you gave images to means the id was rejected (Step 2's gate), not that it is ready.Poll until
loaded === total, and stop with an error after a few seconds — a block that never loads should fail loudly, not screenshot blank. This is not theoretical: on a real runshowcase-gridreported{total: 6, loaded: 2}immediately after the page settled.browser_take_screenshotscoped to that element — pass the selector astarget(it accepts a snapshot ref or a unique selector) plus a humanelementdescription, andfilename.playwright-mcp/<kebab>-raw.png. Do not setfullPage; it cannot combine with an element screenshot.
- a bare
<kebab>-raw.pngwrites to the repo root, dropping ten untracked PNGs next topackage.json. Verified: it reports success and litters the repo. - an absolute path outside those roots is rejected:
File access denied: … is outside allowed roots./tmp/thumbnails/…does not work. .playwright-mcp/<kebab>-raw.pngis accepted and is already gitignored-by- cleanup in Step 7.</HARD-GATE>
Then move them where Step 6 expects:
mkdir -p /tmp/thumbnails && mv .playwright-mcp/*-raw.png /tmp/thumbnails/Sanity-check the captures before processing. A mean-luminance read spots an empty one faster than opening ten files:
for f in /tmp/thumbnails/*-raw.png; do
printf "%-24s %s\n" "$(basename "$f" -raw.png)" \
"$(ffmpeg -hide_banner -i "$f" -vf signalstats,metadata=print:key=lavfi.signalstats.YAVG \
-f null - 2>&1 | grep -o 'YAVG=[0-9.]*' | head -1)"
doneA capture sitting at the bare background value — ~19 dark, ~230 light — is empty. Look at any that do before processing.
Step 6: Process and place
Target: 1200×800 PNG, full block width preserved.
<HARD-GATE> Do not `fit: 'cover'` or centre-crop. Blocks render 1440px wide; a cover-crop zooms in and clips the sides, cutting off titles and dropping cards. Scale width to 1200 first, then crop height from the top, padding if short. </HARD-GATE>Pad with the background of the theme you captured in — white for light,
black for dark. Padding and capture must agree or every short block gets a
band across it. Read it rather than assuming:
browser_evaluate: () => getComputedStyle(document.body).backgroundColor.
export PAD=white # must match Step 5's colour scheme; exported so sharp sees it too
for f in /tmp/thumbnails/*-raw.png; do
name=$(basename "$f" -raw.png)
out="packages/sanity-blocks/src/${name}/thumbnail.png"
ffmpeg -y -loglevel error -i "$f" \
-vf "scale=1200:-1:flags=lanczos,crop=1200:min(ih\,800):0:0,pad=1200:800:0:(oh-ih)/2:$PAD" \
"$out" || { echo "convert failed: $name"; exit 1; }
[ -s "$out" ] || { echo "no output: $out"; exit 1; }
doneStop on the first failure rather than pressing on — sync-thumbnails copies
whatever is on disk, so a half-finished run silently republishes stale tiles.
Two shapes need checking afterwards:
- Blocks much taller than 3:2 (
showcase-grid,video-feature,herorun 1000–1400px) lose their lower half to the crop — the hero's headline can end mid-word. Usually fine; the tile only has to be recognisable. - Thin strips (
logo-cloudis ~72px) become a band floating in centred padding — the command already centres it. Accept it, or capture that block with some surrounding space.
sharp equivalent, if ffmpeg isn't around. require('sharp') fails from the
repo root — it exists only transitively under node_modules/.pnpm/, so this
needs an install first, and unlike the ffmpeg version it is not wired into a
loop:
export PAD=white
for f in /tmp/thumbnails/*-raw.png; do
name=$(basename "$f" -raw.png)
IN="$f" OUT="packages/sanity-blocks/src/${name}/thumbnail.png" node -e "
const sharp = require('sharp');
const PAD = process.env.PAD || 'white';
(async () => {
const buf = await sharp(process.env.IN).resize(1200, null).toBuffer();
const { height } = await sharp(buf).metadata();
const top = Math.floor((800 - height) / 2);
const pipeline = height >= 800
? sharp(buf).extract({ left: 0, top: 0, width: 1200, height: 800 })
: sharp(buf).extend({ top, bottom: 800 - height - top, background: PAD });
await pipeline.png().toFile(process.env.OUT);
})();
" || { echo "convert failed: $name"; exit 1; }
doneThen sync and check the Studio menu:
pnpm --filter studio sync-thumbnailsThere is no schema step. insertMenu.views is already wired in
definitions/pagebuilder.ts and derives from blockSchemas, so a block with a
thumbnail.png appears automatically. There are no insertMenu.groups in this
repo — don't add them unasked.
Step 7: Clean up
rm -rf apps/web/src/app/thumbnails/ # the preview page — dead code, regenerate when needed
rm -rf /tmp/thumbnails/ # raw screenshots
rm -rf .playwright-mcp/ # only if a browser tool created itIf you uploaded placeholders in 3b, ask whether to delete them from the dataset. If you used existing assets, nothing to undo.
Leave behind only the modified packages/sanity-blocks/src/*/thumbnail.png
files and their synced copies under apps/studio/static/thumbnails/.
Common Mistakes
| Mistake | Fix |
|---|---|
Writing to apps/studio/static/thumbnails/ |
Generated dir — sync-thumbnails wipes it. Write packages/sanity-blocks/src/<block>/thumbnail.png |
| WebP output | previewImageUrl builds a .png path — WebP 404s and the tile is blank |
| camelCase filename | Use the kebab-case directory name (feature-cards-icon), not the schema type (featureCardsIcon) |
| Raw image refs in mock data | Blocks take projected { id, alt, preview, hotspot, crop } — { asset: { _ref } } renders nothing |
Cropping with fit: cover |
Scale width to 1200 first, then crop/pad height |
| Preview page as a server component | Must be "use client" — function props can't cross the RSC boundary |
Adding insertMenu config |
Already wired and generated from blockSchemas — nothing to add |
| Letting the browser pick the colour scheme | A fresh Playwright Chromium renders light, a dev session renders dark — pin it, and pad to match |
| Layout chrome baked into tall tiles | The sticky header (z-40) stitches into the middle of any block taller than the viewport — hide header,footer,nextjs-portal first |
| Screenshotting before scrolling | Images are loading="lazy" — a block only loads its images once scrolled into view |
| Hardcoding the pad colour | Pad with the captured theme's background, or the tile gets a glaring band |
Missing _key on mock array items |
No item needs _type. _key is required on ShowcaseGridItem/LogoCloudLogo, optional elsewhere; FaqItem also needs a required _id |
| Rich text as a plain string | Portable Text block format only |
Going through PageBuilder |
Import block components directly — PageBuilder needs Visual Editing context |
| Grabbing the first landscape asset | View candidates first — it's often a partner logo |
| Uploading to the dataset unasked | Check for existing assets, then ask |
Leaving app/thumbnails/ behind |
Delete it — dead code, and this skill regenerates it |
| Generic placeholder copy | Write contextual text; editors browse these tiles |
Red Flags — stop if you notice these
- You're about to write a
.webp, or write anything intoapps/studio/static/thumbnails/— stop, wrong format and wrong directory - Your mock image is
{ asset: { _ref: … } }— stop, that renders blank here - You're adding
insertMenuconfig topagebuilder.ts— stop, it's generated - You're about to
fit: 'cover'— stop, it clips wide blocks - The preview page has no
"use client"— stop, it will crash - Image areas are blank on a capture — stop, fix before processing (check you scrolled the block into view first; the images are lazy)
- You haven't pinned the colour scheme — stop, the tiles won't match Studio
- You haven't hidden
header/footer/nextjs-portal— stop, the navbar bakes into tall tiles - You're uploading to someone's dataset without asking — stop