Skip to content

end to end app store screenshot creation using AI

Fix blank device screens in exports at the source

Parth Jadhav33aca0318bc2
diff --git a/skills/app-store-screenshots/template/src/components/editor/screenshot-editor.tsx b/skills/app-store-screenshots/template/src/components/editor/screenshot-editor.tsx
index 1c6df2f..9dd4da5 100644
--- a/skills/app-store-screenshots/template/src/components/editor/screenshot-editor.tsx
+++ b/skills/app-store-screenshots/template/src/components/editor/screenshot-editor.tsx
@@ -1,7 +1,6 @@
"use client";
import * as React from "react";
import JSZip from "jszip";
-import { toPng } from "html-to-image";
import { Toaster, toast } from "sonner";
import {
getExportSizes,
@@ -11,6 +10,7 @@ import {
} from "@/lib/constants";
import { detectPlatform, nid } from "@/lib/defaults";
import { isBuiltInElementId, isTextElementId, textElementKey } from "@/lib/elements";
+import { renderSlide } from "@/lib/export-render";
import { preloadImages } from "@/lib/image-cache";
import { resolveScreenshot, writeLocalized } from "@/lib/locale";
import { useProject } from "@/lib/storage";
@@ -417,42 +417,50 @@ export function ScreenshotEditor() {
const platform = detectPlatform(state.device);
const zip = new JSZip();
const totalUnits = sizes.length * locales.length * currentSlides.length;
- let unit = 0;
+ const totalRenders = locales.length * currentSlides.length;
+ let render = 0;
let okCount = 0;
let failed = 0;
const errors: string[] = [];
+ const incomplete: string[] = [];
+ // Render each slide once per locale at canvas resolution, then scale that
+ // one render to every export size. The sizes are all scalings of the same
+ // design, so re-rendering the DOM per size only added time.
for (const locale of locales) {
setExportLocaleOverride(locale);
await waitForPaint();
- for (const size of sizes) {
- for (let i = 0; i < currentSlides.length; i++) {
- const slide = currentSlides[i];
- unit += 1;
- setExporting(`${unit}/${totalUnits}`);
- setExportSlideIndex(i);
- await waitForPaint();
- const el = exportRef.current;
- if (!el) {
- failed += 1;
- errors.push(`${locale} ${size.w}×${size.h} screen ${i + 1}: render target missing`);
- continue;
- }
- try {
- const dataUrl = await captureSlide(el, cW, cH, size.w, size.h);
- const base64 = dataUrl.split(",")[1] || "";
- const filename = `${String(i + 1).padStart(2, "0")}-${slide.layout}.png`;
+ for (let i = 0; i < currentSlides.length; i++) {
+ const slide = currentSlides[i];
+ render += 1;
+ setExporting(`${render}/${totalRenders}`);
+ setExportSlideIndex(i);
+ await waitForPaint();
+ const el = exportRef.current;
+ if (!el) {
+ failed += sizes.length;
+ errors.push(`${locale} screen ${i + 1}: render target missing`);
+ continue;
+ }
+ const filename = `${String(i + 1).padStart(2, "0")}-${slide.layout}.png`;
+ let written = 0;
+ try {
+ const rendered = await captureSlide(el, cW, cH);
+ if (rendered.missingImages > 0) incomplete.push(`${locale} screen ${i + 1}`);
+ for (const size of sizes) {
+ const base64 = rendered.toPng(size.w, size.h).split(",")[1] || "";
const path = `${platform}/${state.device}/${size.w}x${size.h}/${locale}/${filename}`;
zip.file(path, base64, { base64: true });
- okCount += 1;
- } catch (e) {
- failed += 1;
- const msg = e instanceof Error ? e.message : String(e);
- errors.push(`${locale} ${size.w}×${size.h} screen ${i + 1}: ${msg}`);
- console.error("Export failed", { slideId: slide.id, locale, size }, e);
+ written += 1;
}
+ } catch (e) {
+ const msg = e instanceof Error ? e.message : String(e);
+ errors.push(`${locale} screen ${i + 1}: ${msg}`);
+ console.error("Export failed", { slideId: slide.id, locale }, e);
}
+ okCount += written;
+ failed += sizes.length - written;
}
}
@@ -475,6 +483,13 @@ export function ScreenshotEditor() {
}
}
+ if (incomplete.length > 0) {
+ toast.warning("Some screenshots may be missing from the export", {
+ description: `${incomplete.slice(0, 3).join(", ")}${incomplete.length > 3 ? "…" : ""}: a screenshot never finished rendering. Check those files, or export again.`,
+ duration: 12000,
+ });
+ }
+
const summary = `${locales.length} locale${locales.length === 1 ? "" : "s"} × ${sizes.length} size${sizes.length === 1 ? "" : "s"}`;
if (failed === 0) {
toast.success(`Exported ${okCount} PNGs (${summary})`);
@@ -489,16 +504,10 @@ export function ScreenshotEditor() {
}
}
- async function captureSlide(
- el: HTMLElement,
- sourceW: number,
- sourceH: number,
- exportW: number,
- exportH: number,
- ) {
- // html-to-image needs the node at (0,0). Let the library scale the source
- // canvas into the requested output dimensions; CSS transforms leave
- // transparent gutters when export aspect ratios differ by a few pixels.
+ async function captureSlide(el: HTMLElement, sourceW: number, sourceH: number) {
+ // html-to-image needs the node at (0,0) and untransformed. Each export size
+ // is a scaled draw of this one render, so aspect ratios that differ by a few
+ // pixels are stretched rather than leaving transparent gutters.
const prev = {
left: el.style.left,
top: el.style.top,
@@ -514,16 +523,7 @@ export function ScreenshotEditor() {
el.style.transformOrigin = "top left";
el.style.zIndex = "-1";
try {
- const dataUrl = await toPng(el, {
- width: sourceW,
- height: sourceH,
- canvasWidth: exportW,
- canvasHeight: exportH,
- pixelRatio: 1,
- cacheBust: false,
- backgroundColor: "#ffffff",
- });
- return dataUrl;
+ return await renderSlide(el, sourceW, sourceH);
} finally {
el.style.left = prev.left || "-99999px";
el.style.top = prev.top || "0px";
diff --git a/skills/app-store-screenshots/template/src/lib/export-render.ts b/skills/app-store-screenshots/template/src/lib/export-render.ts
new file mode 100644
index 0000000..07684c7
--- /dev/null
+++ b/skills/app-store-screenshots/template/src/lib/export-render.ts
@@ -0,0 +1,177 @@
+"use client";
+// Rasterises one export slide to PNG.
+//
+// WHY THIS IS NOT JUST `toPng(node)`
+// ----------------------------------
+// html-to-image serialises the node into an SVG <foreignObject>, loads that SVG
+// as an image and draws it to a canvas exactly once. WebKit (Safari, and any
+// WebKit-based browser) decodes the <img> data URLs *nested inside* an SVG
+// image asynchronously, kicked off by the first paint. That single draw can
+// therefore capture the headline, background and CSS device frame while every
+// screenshot is still blank, with no error. Whether it wins the race depends on
+// image size and machine load, so a different slide failed on each export and a
+// 4K render could fail where 1080p passed. Chrome paints nested data URLs on the
+// first draw, which is why the bug looked intermittent.
+//
+// THE FIX
+// -------
+// 1. Embed only the images inside the captured slide. A connected deck renders
+// every screen side by side; embedding all of them made each SVG N× larger.
+// 2. Render a baseline with every image blanked, so we know what each image's
+// region looks like when the image is missing.
+// 3. Draw the real SVG repeatedly until every visible image region differs from
+// that baseline and two consecutive draws are identical. Only then export.
+// If an image never shows up within the timeout, report it instead of
+// silently shipping a blank device.
+import { toSvg } from "html-to-image";
+
+const SETTLE_POLL_MS = 50;
+const SETTLE_TIMEOUT_MS = 8000;
+const FINGERPRINT_SIZE = 12;
+const BLANK_GIF = "data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7";
+const SVG_PREFIX = "data:image/svg+xml;charset=utf-8,";
+
+type Box = { x: number; y: number; w: number; h: number };
+
+export type RenderedSlide = {
+ /** Draw the settled slide at the given export size and return a PNG data URL. */
+ toPng: (w: number, h: number) => string;
+ /** Visible images that never appeared in the render. 0 when all is well. */
+ missingImages: number;
+};
+
+const nextFrame = () => new Promise<void>((resolve) => requestAnimationFrame(() => resolve()));
+const sleep = (ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms));
+
+function loadImage(src: string): Promise<HTMLImageElement> {
+ return new Promise((resolve, reject) => {
+ const image = new Image();
+ image.onload = () => {
+ image.decode().then(
+ () => resolve(image),
+ () => resolve(image),
+ );
+ };
+ image.onerror = () => reject(new Error("Couldn't load the rendered slide"));
+ image.src = src;
+ });
+}
+
+function intersects(a: DOMRect, b: DOMRect) {
+ return a.right > b.left && a.left < b.right && a.bottom > b.top && a.top < b.bottom;
+}
+
+// Same SVG with every <img> pointed at a transparent pixel: what each image
+// region looks like when that image failed to paint.
+function blankImages(svg: string) {
+ if (!svg.startsWith(SVG_PREFIX)) return null;
+ const markup = decodeURIComponent(svg.slice(SVG_PREFIX.length));
+ const blanked = markup.replace(/(<img\b[^>]*?\bsrc=")[^"]*(")/g, `$1${BLANK_GIF}$2`);
+ return SVG_PREFIX + encodeURIComponent(blanked);
+}
+
+function createContext(width: number, height: number, readBack = false) {
+ const canvas = document.createElement("canvas");
+ canvas.width = width;
+ canvas.height = height;
+ const ctx = canvas.getContext("2d", readBack ? { willReadFrequently: true } : undefined);
+ if (!ctx) throw new Error("Canvas 2D context unavailable");
+ return { canvas, ctx };
+}
+
+// Downsampled pixels of each box: cheap to compare, sensitive to "is it there".
+function fingerprint(source: HTMLCanvasElement, boxes: Box[], scratch: CanvasRenderingContext2D) {
+ return boxes.map((b) => {
+ scratch.clearRect(0, 0, FINGERPRINT_SIZE, FINGERPRINT_SIZE);
+ scratch.drawImage(source, b.x, b.y, b.w, b.h, 0, 0, FINGERPRINT_SIZE, FINGERPRINT_SIZE);
+ return scratch.getImageData(0, 0, FINGERPRINT_SIZE, FINGERPRINT_SIZE).data.join(",");
+ });
+}
+
+export async function renderSlide(
+ el: HTMLElement,
+ width: number,
+ height: number,
+ backgroundColor = "#ffffff",
+): Promise<RenderedSlide> {
+ const root = el.getBoundingClientRect();
+ const sx = width / (root.width || width);
+ const sy = height / (root.height || height);
+ const isVisible = (node: Element) => intersects(node.getBoundingClientRect(), root);
+
+ const visible = Array.from(el.querySelectorAll("img")).filter(
+ (image) => !!image.getAttribute("src") && isVisible(image),
+ );
+ await Promise.all(visible.map((image) => image.decode().catch(() => undefined)));
+
+ // Inner 60% of each visible image, in canvas pixels. The inset keeps bezels,
+ // rounded corners and overlapping frames out of the comparison.
+ const boxes: Box[] = visible
+ .map((image) => {
+ const r = image.getBoundingClientRect();
+ const left = Math.max(r.left, root.left);
+ const top = Math.max(r.top, root.top);
+ const w = (Math.min(r.right, root.right) - left) * sx;
+ const h = (Math.min(r.bottom, root.bottom) - top) * sy;
+ return { x: (left - root.left) * sx + w * 0.2, y: (top - root.top) * sy + h * 0.2, w: w * 0.6, h: h * 0.6 };
+ })
+ .filter((b) => b.w >= 2 && b.h >= 2);
+
+ const svg = await toSvg(el, {
+ width,
+ height,
+ cacheBust: false,
+ backgroundColor,
+ filter: (node) => !(node instanceof HTMLImageElement) || isVisible(node),
+ });
+
+ const { canvas, ctx } = createContext(width, height);
+ const { ctx: scratch } = createContext(FINGERPRINT_SIZE, FINGERPRINT_SIZE, true);
+ const draw = (image: HTMLImageElement) => {
+ ctx.fillStyle = backgroundColor;
+ ctx.fillRect(0, 0, width, height);
+ ctx.drawImage(image, 0, 0, width, height);
+ };
+
+ let missingImages = 0;
+ const blankSvg = boxes.length > 0 ? blankImages(svg) : null;
+ if (blankSvg) {
+ draw(await loadImage(blankSvg));
+ const baseline = fingerprint(canvas, boxes, scratch);
+ const image = await loadImage(svg);
+ let prev: string[] | null = null;
+ let painted: boolean[] = boxes.map(() => false);
+ const deadline = performance.now() + SETTLE_TIMEOUT_MS;
+ for (;;) {
+ draw(image);
+ const cur = fingerprint(canvas, boxes, scratch);
+ painted = cur.map((fp, i) => fp !== baseline[i]);
+ const stable = prev !== null && cur.every((fp, i) => fp === prev![i]);
+ if ((stable && painted.every(Boolean)) || performance.now() > deadline) break;
+ prev = cur;
+ await nextFrame();
+ await sleep(SETTLE_POLL_MS);
+ }
+ missingImages = painted.filter((p) => !p).length;
+ } else {
+ draw(await loadImage(svg));
+ }
+
+ return {
+ missingImages,
+ toPng: (w, h) => {
+ if (w === width && h === height) return canvas.toDataURL("image/png");
+ const { canvas: out, ctx: octx } = createContext(w, h);
+ octx.imageSmoothingEnabled = true;
+ octx.imageSmoothingQuality = "high";
+ // Cover, not stretch: some slots differ from the canvas aspect by a few
+ // percent (Apple Watch 422×514 → 312×390), and stretching would squash
+ // the device frame. Cover trims the same few pixels off the edges instead.
+ const scale = Math.max(w / width, h / height);
+ const dw = width * scale;
+ const dh = height * scale;
+ octx.drawImage(canvas, (w - dw) / 2, (h - dh) / 2, dw, dh);
+ return out.toDataURL("image/png");
+ },
+ };
+}
diff --git a/skills/app-store-screenshots/verify-export b/skills/app-store-screenshots/verify-export
deleted file mode 100755
index 0ebd876..0000000
--- a/skills/app-store-screenshots/verify-export
+++ /dev/null
@@ -1,136 +0,0 @@
-#!/usr/bin/env python3
-"""
-verify-export — catch silently dropped screenshots in an export bundle.
-
-WHY THIS EXISTS
----------------
-The exporter intermittently produces a slide with the device frame, headline and
-background rendered perfectly and the SCREENSHOT INSIDE THE DEVICE MISSING. It
-does not error, and the on-canvas editor preview is always correct because that
-is ordinary DOM rendering and never touches the export path.
-
-Observed 18 Aug 2026 across repeated exports of one five-slide deck:
- - a different slide failed on each run
- - the SAME slide dropped at 3840x2160 while rendering correctly at 1920x1080
- in the SAME run, which rules out the source image and the layout
-Root cause is not established. Treat every export as suspect.
-
-WHAT THIS DOES
---------------
-1. Counts unique colours per exported PNG. A dropped screenshot collapses a
- device region full of album art into a flat dark rectangle, which costs tens
- of thousands of colours. The split is not subtle -- measured examples:
- dropped: 3,609 / 4,157 / 4,357
- intact: 31,787 ... 292,699
- Files are compared against their same-size siblings, not a fixed threshold.
-2. Writes one contact sheet per size, so "look at every slide" is one glance
- instead of ten file-opens. THE SHEET IS THE POINT -- a missing screenshot is
- unmissable beside its populated siblings and easy to miss one file at a time.
-
-DO NOT REPLACE THE VISUAL CHECK WITH A NUMBER. Two automated detectors were
-tried during that session -- mean brightness, then colourfulness -- and BOTH
-gave false readings in both directions: a dark lyrics slide read as "empty", a
-purple gradient background read as "has content". One of them passed a broken
-file. The colour count here is a triage aid to tell you where to look. Look.
-
-USAGE
- verify-export <export-dir>
- e.g. verify-export ~/Claude/Streamphile/screenshots-deck/export
-
-CONTACT SHEETS ARE DERIVED AND DELIBERATELY NOT TRACKED. They are regenerated
-on every run. Never read a sheet you did not just generate: a sheet left over
-from an earlier export will happily show a good slide next to a file that has
-since been re-exported and broken, which is worse than having no sheet at all.
-If you are looking at a sheet, re-run this first.
-
-Exits non-zero if any file looks dropped.
-"""
-import sys
-import pathlib
-from collections import defaultdict
-
-try:
- from PIL import Image
-except ImportError:
- sys.exit("Pillow required: pip install pillow")
-
-# A file is suspect when its colour count falls this far below the median of its
-# same-size siblings. Ratio-based, so it adapts to decks of any visual density.
-SUSPECT_RATIO = 0.15
-# Floor for a lone file with no siblings to compare against.
-ABSOLUTE_FLOOR = 15000
-# Contact sheets are written here, and excluded from scanning.
-SHEET_DIR = "_contact-sheets"
-
-
-def unique_colours(path):
- im = Image.open(path).convert("RGB")
- return len(im.getcolors(maxcolors=4_000_000) or [])
-
-
-def main():
- if len(sys.argv) != 2:
- sys.exit(__doc__.strip().split("USAGE")[-1].strip())
-
- root = pathlib.Path(sys.argv[1]).expanduser()
- if not root.is_dir():
- sys.exit(f"not a directory: {root}")
-
- # Skip our own contact sheets, or a second run scans its own output and
- # reports the sheets as a bogus extra "size" group.
- pngs = sorted(
- f for f in root.rglob("*.png")
- if SHEET_DIR not in f.parts and not f.name.startswith("contact-sheet-")
- )
- if not pngs:
- sys.exit(f"no PNGs under {root}")
-
- # Group by parent directory — one group per size/locale.
- groups = defaultdict(list)
- for p in pngs:
- groups[p.parent].append(p)
-
- suspect = []
- for parent in sorted(groups):
- files = sorted(groups[parent])
- counts = {f: unique_colours(f) for f in files}
- ordered = sorted(counts.values())
- median = ordered[len(ordered) // 2]
- rel = parent.relative_to(root)
- print(f"--- {rel} ({len(files)} files, median {median:,} colours)")
- for f in files:
- n = counts[f]
- bad = n < ABSOLUTE_FLOOR and n < median * SUSPECT_RATIO
- if bad:
- suspect.append(f)
- print(f" {f.name:30s} {n:9,} {'** LOOKS DROPPED **' if bad else 'ok'}")
-
- # Contact sheet for this group.
- w, h = 560, 315
- sheet = Image.new("RGB", (w, h * len(files)), (18, 18, 18))
- for i, f in enumerate(files):
- sheet.paste(Image.open(f).convert("RGB").resize((w, h)), (0, i * h))
- sheet_dir = root / SHEET_DIR
- sheet_dir.mkdir(exist_ok=True)
- out = sheet_dir / f"{str(rel).replace('/', '-')}.png"
- sheet.save(out)
- print(f" -> contact sheet: {out}")
- print()
-
- if suspect:
- print(f"{len(suspect)} file(s) look dropped — re-export and re-check:")
- for f in suspect:
- print(f" {f}")
- print("\nRe-exporting reshuffles which slide fails, so assemble the deck")
- print("from whichever renders come out clean across runs.")
- return 1
-
- print("No dropped screenshots detected.")
- print("NOW OPEN THE CONTACT SHEETS AND LOOK. The count is triage, not proof.")
- print("(Sheets were just regenerated. Never read one you did not just make —")
- print(" a stale sheet can show a good slide for a file that has since broken.)")
- return 0
-
-
-if __name__ == "__main__":
- sys.exit(main())