Skip to content

end to end app store screenshot creation using AI

feat: add Style Lab, Scene Playground and magnifier to the editor

Parth Jadhavd77ba93b0be6
diff --git a/README.md b/README.md
index db87b3f..366001d 100644
--- a/README.md
+++ b/README.md
@@ -26,6 +26,9 @@ Example screenshots generated with this skill were accepted for [Bloom Coffee Sh
- **Screen sidebar** - add, select, and drag-to-reorder screens with live thumbnails.
- **Inspector** - edit layout, labels, headlines, screenshots, element stacking, and transforms from the right panel. A **Copy ideas** menu next to the headline drops in a proven formula to rewrite.
- **Theme picker** - switch palette presets from the toolbar, including one preset per named style.
+- **Style Lab** - see four complete looks for your deck side by side (palette, type, layout rhythm and scene), keep the parts you like with Colors/Type/Layout/Scene locks, shuffle or remix the rest, save favourites, apply one as a single undoable edit, and export a comparison image.
+- **Scene Playground** - restyle every screen at once: backdrops (gradient, solid, aurora, spotlight, grid, dots, ruled) that can flow across the whole strip, decorations, device shadow, glow and 3D tilt, and headline weight, case and alignment.
+- **Magnifier** - add a loupe to any screen that zooms into one detail of its screenshot; aim it on a thumbnail, set the zoom and shape, and drag it anywhere.
- **Platform switcher** - iOS, Mac, and Android tabs keep every deck side by side while sharing the same editor workflow.
- **Device selector** - iPhone, iPad, Apple TV, Apple Watch, and CarPlay under iOS; Android phone, Android tablets, and the feature graphic under Android. The Mac tab is a single 16:10 Mac deck.
- **Autosave** - writes to disk through `/api/project`, mirrors to `localStorage`, and detects newer disk revisions before overwriting work from another tab or agent. Failed saves can be retried; unsaved edits trigger a warning before leaving.
@@ -161,7 +164,8 @@ The template README inside `skills/app-store-screenshots/template/README.md` doc
3. Run the dev server and open the editor.
4. Use the sidebar to organize screens and the inspector to edit copy, layouts, screenshots, and elements.
5. Choose Connected or Isolated mode depending on whether elements should cross screen boundaries.
-6. Click **Export bundle** to download store-ready PNGs.
+6. Open **Style Lab** to compare complete looks, or **Scene** to tune backdrop, depth and headline style by hand.
+7. Click **Export bundle** to download store-ready PNGs.
Uploaded files are saved under `public/screenshots/uploaded/`, and the canonical deck state is saved in `app-store-screenshots.json`. Commit both to make the deck reproducible after a fresh clone.
@@ -210,7 +214,7 @@ Screenshots are designed at the largest size for each device and scaled down for
## Project State
-- `app-store-screenshots.json` is the source of truth for app name, active platform, active device, locales, theme, connected-canvas mode, slides, screenshot paths, and transforms.
+- `app-store-screenshots.json` is the source of truth for app name, active platform, active device, locales, theme, connected-canvas mode, scene, saved Style Lab looks, slides, screenshot paths, magnifiers, and transforms.
- Runtime uploads are written to `public/screenshots/uploaded/<hash>.png`.
- The editor reads `localStorage` first for fast paint, then reconciles with the project file.
- Older project files are migrated to schema v2 on load while keeping legacy decks isolated unless connected mode was already enabled.
diff --git a/skills/app-store-screenshots/SKILL.md b/skills/app-store-screenshots/SKILL.md
index cc6e50b..130db91 100644
--- a/skills/app-store-screenshots/SKILL.md
+++ b/skills/app-store-screenshots/SKILL.md
@@ -219,7 +219,7 @@ function migrateSlide(slide, used) {
const rawTransforms = slide.transforms && typeof slide.transforms === "object" ? slide.transforms : {};
for (const [id, transform] of Object.entries(rawTransforms)) {
const cleaned = cleanTransform(transform);
- if (["caption", "device", "deviceSecondary"].includes(id) && cleaned) transforms[id] = cleaned;
+ if (["caption", "device", "deviceSecondary", "callout"].includes(id) && cleaned) transforms[id] = cleaned;
}
const textIds = new Set();
const textElements = Array.isArray(slide.textElements)
@@ -261,6 +261,8 @@ function migrateSlide(slide, used) {
...(Object.keys(transforms).length ? { transforms } : { transforms: undefined }),
...(textElements && textElements.length ? { textElements } : { textElements: undefined }),
...(imageElements && imageElements.length ? { imageElements } : { imageElements: undefined }),
+ // The editor clamps magnifier values on load; only a non-object would be rejected.
+ callout: slide.callout && typeof slide.callout === "object" && !Array.isArray(slide.callout) ? slide.callout : undefined,
};
}
@@ -451,6 +453,8 @@ If the user provided headlines, edit `app-store-screenshots.json` to set:
- `appIcon` — public path of the app icon (e.g. `"/app-icon.png"` after copying it to `public/app-icon.png`). The Play Store feature graphic shows it; blank uses the app's initial. The icon can also be picked in the feature-graphic inspector.
- `connectedCanvas` (`true` for new connected decks; migrated legacy decks should stay `false` until the user opts in)
- Starter slides per device with the user's `label` + `headline` + screenshot paths
+- Optional `scene` for the whole project: `{ backdrop: "gradient"|"solid"|"aurora"|"spotlight"|"grid"|"dots"|"lines", span: boolean, decoration: "blobs"|"rings"|"sparkles"|"none", shadow: 0–100, glow: 0–100, tilt: -30–30, headlineWeight: 300–900, headlineCase: "as-typed"|"upper", captionAlign: "auto"|"left"|"center" }`. Omit it for the classic gradient + blobs look. Pick values that match the chosen style (e.g. `spotlight` + glow for dark pro styles, `lines` + left-aligned serif for editorial); the user can refine it in the editor's **Scene** popover or compare whole looks in **Style Lab**.
+- Optional per-slide `callout: { focusX: 0–1, focusY: 0–1, zoom: 1.5–5, shape: "circle"|"rounded" }` to magnify one detail of the primary screenshot. It sits over the device's upper right unless `transforms.callout` places it.
- Optional per-slide `typography: { labelScale, headlineScale, appNameScale }` (0.5–2, default 1) when one headline is much longer or shorter than the rest of the deck. `appNameScale` only applies to the feature graphic, where `headlineScale` sizes the tagline.
Otherwise, leave the defaults — the user can rewrite copy in the editor.
diff --git a/skills/app-store-screenshots/template/README.md b/skills/app-store-screenshots/template/README.md
index aa22bca..b765fe5 100644
--- a/skills/app-store-screenshots/template/README.md
+++ b/skills/app-store-screenshots/template/README.md
@@ -15,6 +15,7 @@ bun dev # http://localhost:3000
- **Connected canvas editor** (`src/components/editor/`) — every screen sits on one horizontal canvas, so phones, captions, and other elements can be dragged across screen boundaries and exported as split crops when Connected mode is enabled.
- **Screen controls** — drag-to-reorder screens, click-to-edit text, screenshot drop targets, per-screen layout switcher, dark/light toggle.
+- **Style Lab and Scene Playground** — compare complete looks for a deck and restyle every screen's backdrop, depth and headline at once. See [Style Lab](#style-lab) and [Scene Playground](#scene-playground).
- **Image overlays, fonts, backgrounds and undo** — PNG/JPG overlay elements, a live screenshot font menu (with font import), per-screen custom backgrounds, and toolbar Undo/Redo. See [Editor controls](#editor-controls).
- **Device frames** (`src/components/editor/device-frames.tsx`) — iPhone (PNG mockup), iPad, Apple TV, Apple Watch, CarPlay head unit, Mac window, Android phone, Android tablet (portrait + landscape), feature graphic.
- **Auto-save (git-trackable)** — every change is persisted within ~600ms to **`app-store-screenshots.json`** at the project root (via `/api/project`) **and** mirrored to `localStorage` as an instant-paint cache. Commit `app-store-screenshots.json` and you can `git clone` to another machine and resume exactly where you left off.
@@ -65,6 +66,32 @@ The toolbar font menu sets the typeface of the screenshot canvas and exports (no
In the inspector's **Elements** card, click **Image**, then **Pick** (or drop) a PNG/JPG. Uploads go through `/api/upload` into `public/screenshots/uploaded/`, like screenshots. The first image sizes the overlay frame to its aspect ratio; after that you can drag, resize, rotate (canvas handle or slider), restack, choose **Fill frame** (crop) or **Whole image**, and fade one edge into the background. In Connected mode overlays can cross screen edges like other elements. Overlays are saved per screen as `imageElements`, and the exporter waits for them to paint just like device screenshots. The Play Store feature graphic has a fixed icon + name + tagline layout, so it doesn't take overlays or text elements.
+### Style Lab
+
+**Style Lab** in the toolbar opens four complete looks for the open deck, each from a different direction (Editorial, Playful, Cinematic, Minimal on first open; Swiss Bold, Dreamy, Vintage Poster and Panorama join on **Shuffle**). A look sets the theme, which screens are inverted, the font, headline weight/case/alignment/size, each screen's layout, and the scene. Your current deck is pinned at the top for before/after comparison. Copy and screenshots never change.
+
+- **Keep** locks (Colors, Type, Layout, Scene) hold that part of your deck in every look; Shuffle and **Remix** (another take on one direction) only vary what is unlocked.
+- **Apply** writes the look as one undo step. Changing layout resets that screen's built-in placements (headline, devices, magnifier) to the layout defaults; lock **Layout** to keep hand-placed elements. Phones and portrait tablets get new layouts; landscape, TV, Watch, CarPlay and Mac decks keep theirs.
+- **Save** stars a look into `savedLooks` in the project file, listed under **Saved looks** next time.
+- **Export comparison** downloads one PNG with your deck and all four looks.
+
+Looks come from seeded generators in `src/lib/style-lab.ts`, so the same shuffle always yields the same looks. Add a direction there to extend the lab.
+
+### Scene Playground
+
+**Scene** in the toolbar edits the project-wide `scene`, live on the canvas:
+
+- **Backdrop** — gradient (classic), solid, aurora, spotlight, grid, dots or ruled lines, in the theme's colours. **Flow across screens** lays the backdrop art and decorations out over the whole strip so they cross the seams; each screen still keeps its own base colour, and exports are crops of the same layout.
+- **Decoration** — blobs, rings, sparkles or none.
+- **Device depth** — drop shadow, accent glow and a 3D tilt (−30° to 30°) for every device.
+- **Headline** — weight, as-typed or UPPER case, and Auto/Left/Center alignment.
+
+**Surprise me** rolls a new backdrop and depth; the reset arrow returns to the classic look. A project without `scene` renders exactly as before.
+
+### Magnifier
+
+In the inspector, **Magnifier → Add** places a loupe over the device. Click or drag on the thumbnail (or use arrow keys) to aim it; the ring shows how much of the screenshot the lens covers. **Zoom** is relative to how large the screenshot appears on the device (1.5–5×), and the lens can be a circle or rounded square. Drag, resize, rotate and restack it like any element. It's saved per screen as `callout` plus `transforms.callout`, and is unavailable on no-device layouts and the feature graphic.
+
### Undo and redo
The toolbar arrows, `⌘Z` / `Ctrl+Z` and `⇧⌘Z` / `Ctrl+Shift+Z` (or `Ctrl+Y`) step through the last 50 edits of the session: copy, layouts, element moves, text sizes, backgrounds, fonts, themes, overlays and resets. Rapid changes (typing, dragging a slider) collapse into one step. Switching platform, device, orientation or locale isn't an edit, so it doesn't use up an undo step; undoing an edit takes you back to the deck it was made on. While a text field is focused the shortcuts undo that field's typing instead. History resets on reload.
diff --git a/skills/app-store-screenshots/template/docs/testing/e2e.md b/skills/app-store-screenshots/template/docs/testing/e2e.md
index 79ca0af..a61e048 100644
--- a/skills/app-store-screenshots/template/docs/testing/e2e.md
+++ b/skills/app-store-screenshots/template/docs/testing/e2e.md
@@ -15,7 +15,7 @@ bun run test:e2e
SCREENSHOTS_E2E_PRODUCTION=1 bun run test:e2e
```
-`bun run test:e2e` runs 26 tests: 23 tests that directly drive/inspect the product with Tester Army, plus three tests that run 56 existing regression groups (35 browser/export, 12 UI, nine API). Nested loops cover every advertised device size, layout, orientation, theme and built-in font. Counts refer to test/group definitions, not every loop iteration.
+`bun run test:e2e` runs 37 tests: 34 tests that directly drive/inspect the product with Tester Army (23 in `tests/editor.e2e.ts`, 11 for Style Lab, Scene Playground and the magnifier in `tests/scene-style-lab.e2e.ts`), plus three tests that run 56 existing regression groups (35 browser/export, 12 UI, nine API). Nested loops cover every advertised device size, layout, orientation, theme and built-in font. Counts refer to test/group definitions, not every loop iteration.
For one direct regression:
@@ -71,6 +71,9 @@ Use the default output directory for this suite's ZIP-content checks; the publis
| Export lock, progress, failure and fallback | Harness editor becomes inert immediately through ZIP completion, downloads once, unlocks; missing/corrupt/stalled assets/font fail with actionable messages; failing/silent/throwing workers use inline encoder; encoding failure is observed safely. |
| Narrow viewport, touch, keyboard access | Direct 390px layout and keyboard reordering; UI harness 390–1440px screenshots/layout, scrollable inspector, touch actions without hover, keyboard canvas image focus and Fit active screen recentering. |
| API inputs, origin, limits, asset serving and migration | Direct invalid project/no mutation, stale conflict, corrupt image/font and foreign origins; API harness exact JSON type/origin, request byte limits including chunked upload, concurrent atomic uploads, runtime filename/traversal rejection and legacy migration. Root repository reads the live skill migration; standalone scaffold uses the bundled recipe fixture. |
+| Scene Playground | Direct backdrop/flow/decoration/tilt/case edits render on every screen, persist, undo/redo as one step and reset to the classic scene; ZIP test decodes a tilted, glowing, spotlit export at exact size; a flowing spotlight deck is checked for equal brightness on every exported screen. |
+| Style Lab looks, locks, saved looks, comparison | Direct four-look listing, Apply as one undo step keeping copy and layouts restorable, Colors/Layout locks across Shuffle, all-locked disables Shuffle, per-screen headline sizes survive a look, the Apply toast's Undo refuses to revert a later edit, saved looks survive reload/apply/remove, comparison PNG download is a real tall PNG. |
+| Magnifier | Direct add, keyboard focus, zoom, shape, remove; ZIP export with a magnifier; partial callouts accepted by the API and completed; malformed scene/savedLooks/callout rejected; out-of-range values clamped on load. |
| Reset and cancel reset | Harness reset-all preserves app/theme/locales, editor confirmation allows cancellation; structural reset has separate undo boundary. |
## Bugs fixed and evidence
diff --git a/skills/app-store-screenshots/template/src/components/editor/callout-controls.tsx b/skills/app-store-screenshots/template/src/components/editor/callout-controls.tsx
new file mode 100644
index 0000000..b55fc90
--- /dev/null
+++ b/skills/app-store-screenshots/template/src/components/editor/callout-controls.tsx
@@ -0,0 +1,232 @@
+"use client";
+import * as React from "react";
+import { Circle, Search, Square, Trash2 } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { Label } from "@/components/ui/label";
+import { img } from "@/lib/image-cache";
+import { resolveScreenshot } from "@/lib/locale";
+import { CALLOUT_ZOOM_MAX, CALLOUT_ZOOM_MIN, DEFAULT_CALLOUT } from "@/lib/scene";
+import { cn } from "@/lib/utils";
+import type { Callout, Device, ElementId, Orientation, Slide } from "@/lib/types";
+import { getElementTransform, SCREEN_WIDTH_FRACTION } from "./slide-canvas";
+
+/** Inspector section for the per-screen magnified callout ("Magnifier"). */
+export function CalloutControls({
+ slide,
+ device,
+ orientation,
+ locale,
+ available,
+ onChange,
+ onSelectElement,
+}: {
+ slide: Slide;
+ device: Device;
+ orientation: Orientation;
+ locale: string;
+ available: boolean;
+ onChange: (patch: Partial<Slide>) => void;
+ onSelectElement: (id: ElementId | null) => void;
+}) {
+ const callout = slide.callout;
+ const screenshot = img(resolveScreenshot(slide.screenshot, locale));
+
+ function patch(next: Partial<Callout>) {
+ if (!callout) return;
+ const merged = { ...callout, ...next };
+ const saved = slide.transforms?.callout;
+ // A circle is always round: square up a frame that was stretched as a rounded rect.
+ if (next.shape === "circle" && saved && saved.width !== saved.height) {
+ const size = Math.min(saved.width, saved.height);
+ onChange({ callout: merged, transforms: { ...slide.transforms, callout: { ...saved, width: size, height: size } } });
+ return;
+ }
+ onChange({ callout: merged });
+ }
+
+ if (!available) return null;
+
+ // Share of the screenshot's width the lens actually shows, for the picker ring.
+ const lensW = getElementTransform(slide, device, orientation, "callout")?.width;
+ const deviceW = getElementTransform(slide, device, orientation, "device")?.width;
+ const coverage = callout && lensW && deviceW ? Math.min(1, lensW / (deviceW * SCREEN_WIDTH_FRACTION * callout.zoom)) : 0.3;
+
+ if (!callout) {
+ return (
+ <div className="flex items-center justify-between gap-2 rounded-md border bg-muted/30 p-3">
+ <div className="min-w-0">
+ <Label className="text-xs font-semibold">Magnifier</Label>
+ <p className="text-[11px] text-muted-foreground">Zoom into one detail of the screenshot.</p>
+ </div>
+ <Button
+ type="button"
+ variant="outline"
+ size="sm"
+ className="h-7 shrink-0 px-2 text-xs"
+ onClick={() => {
+ onChange({ callout: { ...DEFAULT_CALLOUT } });
+ onSelectElement("callout");
+ }}
+ >
+ <Search className="h-3.5 w-3.5" />
+ Add
+ </Button>
+ </div>
+ );
+ }
+
+ return (
+ <div className="space-y-3 rounded-md border bg-muted/30 p-3">
+ <div className="flex items-center justify-between gap-2">
+ <Label className="text-xs font-semibold">Magnifier</Label>
+ <Button
+ type="button"
+ variant="ghost"
+ size="icon"
+ className="h-6 w-6 hover:text-destructive"
+ aria-label="Remove magnifier"
+ title="Remove magnifier"
+ onClick={() => {
+ const { callout: _removed, ...rest } = slide.transforms || {};
+ onChange({ callout: undefined, transforms: Object.keys(rest).length ? rest : undefined });
+ onSelectElement(null);
+ }}
+ >
+ <Trash2 className="h-3.5 w-3.5" />
+ </Button>
+ </div>
+
+ <FocusPicker
+ src={screenshot}
+ x={callout.focusX}
+ y={callout.focusY}
+ coverage={coverage}
+ round={callout.shape === "circle"}
+ onChange={(focusX, focusY) => patch({ focusX, focusY })}
+ />
+
+ <div className="space-y-1">
+ <div className="flex items-center justify-between">
+ <Label className="text-[11px] text-muted-foreground">Zoom</Label>
+ <span className="text-[11px] tabular-nums text-muted-foreground">{callout.zoom.toFixed(1)}×</span>
+ </div>
+ <input
+ type="range"
+ min={CALLOUT_ZOOM_MIN}
+ max={CALLOUT_ZOOM_MAX}
+ step={0.1}
+ value={callout.zoom}
+ onChange={(e) => patch({ zoom: Number(e.target.value) })}
+ className="w-full"
+ aria-label="Magnifier zoom"
+ aria-valuetext={`${callout.zoom.toFixed(1)} times`}
+ />
+ </div>
+
+ <div className="grid grid-cols-2 gap-1" role="radiogroup" aria-label="Magnifier shape">
+ {(["circle", "rounded"] as const).map((shape) => (
+ <Button
+ key={shape}
+ type="button"
+ role="radio"
+ aria-checked={callout.shape === shape}
+ variant={callout.shape === shape ? "secondary" : "outline"}
+ size="sm"
+ className="h-7 gap-1.5 text-xs"
+ onClick={() => patch({ shape })}
+ >
+ {shape === "circle" ? <Circle className="h-3.5 w-3.5" /> : <Square className="h-3.5 w-3.5" />}
+ {shape === "circle" ? "Circle" : "Rounded"}
+ </Button>
+ ))}
+ </div>
+ </div>
+ );
+}
+
+const KEY_STEP = 0.02;
+
+function FocusPicker({
+ src,
+ x,
+ y,
+ coverage,
+ round,
+ onChange,
+}: {
+ src: string;
+ x: number;
+ y: number;
+ coverage: number;
+ round: boolean;
+ onChange: (x: number, y: number) => void;
+}) {
+ const ref = React.useRef<HTMLDivElement>(null);
+ const clamp = (v: number) => Math.min(1, Math.max(0, v));
+
+ function fromPointer(e: React.PointerEvent) {
+ const box = ref.current?.getBoundingClientRect();
+ if (!box || !box.width || !box.height) return;
+ onChange(
+ Math.round(clamp((e.clientX - box.left) / box.width) * 1000) / 1000,
+ Math.round(clamp((e.clientY - box.top) / box.height) * 1000) / 1000,
+ );
+ }
+
+ return (
+ <div className="space-y-1">
+ <Label className="text-[11px] text-muted-foreground">Focus — click or drag on the screenshot</Label>
+ <div
+ ref={ref}
+ role="slider"
+ tabIndex={0}
+ aria-label="Magnifier focus"
+ aria-valuemin={0}
+ aria-valuemax={100}
+ aria-valuenow={Math.round(y * 100)}
+ aria-valuetext={`${Math.round(x * 100)}% across, ${Math.round(y * 100)}% down`}
+ className={cn(
+ "relative mx-auto w-24 cursor-crosshair touch-none select-none overflow-hidden rounded-md border bg-neutral-900 outline-none focus-visible:ring-2 focus-visible:ring-ring",
+ !src && "aspect-[9/19.5]",
+ )}
+ onPointerDown={(e) => {
+ e.currentTarget.setPointerCapture(e.pointerId);
+ fromPointer(e);
+ }}
+ onPointerMove={(e) => {
+ if (e.currentTarget.hasPointerCapture(e.pointerId)) fromPointer(e);
+ }}
+ onKeyDown={(e) => {
+ const step = e.shiftKey ? KEY_STEP * 5 : KEY_STEP;
+ const moves: Record<string, [number, number]> = {
+ ArrowLeft: [-step, 0],
+ ArrowRight: [step, 0],
+ ArrowUp: [0, -step],
+ ArrowDown: [0, step],
+ };
+ const move = moves[e.key];
+ if (!move) return;
+ e.preventDefault();
+ e.stopPropagation();
+ onChange(clamp(x + move[0]), clamp(y + move[1]));
+ }}
+ >
+ {src ? (
+ <img src={src} alt="" draggable={false} className="block w-full" />
+ ) : (
+ <span className="absolute inset-0 flex items-center justify-center p-2 text-center text-[10px] text-neutral-400">
+ Add a screenshot first
+ </span>
+ )}
+ <span
+ aria-hidden
+ className={cn(
+ "pointer-events-none absolute aspect-square -translate-x-1/2 -translate-y-1/2 border-2 border-white bg-white/10 shadow-[0_0_0_1px_rgba(0,0,0,0.55),0_0_0_999px_rgba(0,0,0,0.35)]",
+ round ? "rounded-full" : "rounded-[14%]",
+ )}
+ style={{ left: `${x * 100}%`, top: `${y * 100}%`, width: `${coverage * 100}%` }}
+ />
+ </div>
+ </div>
+ );
+}
diff --git a/skills/app-store-screenshots/template/src/components/editor/inspector.tsx b/skills/app-store-screenshots/template/src/components/editor/inspector.tsx
index e3505bb..fc10c7f 100644
--- a/skills/app-store-screenshots/template/src/components/editor/inspector.tsx
+++ b/skills/app-store-screenshots/template/src/components/editor/inspector.tsx
@@ -75,7 +75,8 @@ import type {
} from "@/lib/types";
import { BackgroundControls } from "./background-controls";
import { ScreenshotPicker } from "./screenshot-picker";
-import { getCanvas, getElementTransform } from "./slide-canvas";
+import { CalloutControls } from "./callout-controls";
+import { calloutAvailable, getCanvas, getElementTransform } from "./slide-canvas";
type Props = {
slide: Slide;
@@ -96,6 +97,7 @@ const ELEMENT_LABEL: Record<BuiltInElementId, string> = {
caption: "Headline",
device: "Device",
deviceSecondary: "Back device",
+ callout: "Magnifier",
};
export function Inspector({
@@ -230,6 +232,16 @@ export function Inspector({
</div>
)}
+ <CalloutControls
+ slide={slide}
+ device={device}
+ orientation={orientation}
+ locale={locale}
+ available={calloutAvailable(slide, device)}
+ onChange={onChange}
+ onSelectElement={onSelectElement}
+ />
+
{!isFeatureGraphic && (
<ElementTransformControls
slide={slide}
@@ -321,6 +333,7 @@ function ElementTransformControls({
const present: ElementId[] = ["caption"];
if (slide.layout !== "no-device") present.push("device");
if (slide.layout === "two-devices") present.push("deviceSecondary");
+ if (slide.callout && calloutAvailable(slide, device)) present.push("callout");
for (const element of slide.textElements || []) present.push(toTextElementId(element.id));
for (const element of slide.imageElements || []) present.push(toImageElementId(element.id));
@@ -1145,5 +1158,6 @@ function defaultZ(id: ElementId): number {
if (isImageElementId(id)) return 5;
if (id === "deviceSecondary") return 2;
if (id === "device") return 3;
+ if (id === "callout") return 5;
return 4; // caption on top
}
diff --git a/skills/app-store-screenshots/template/src/components/editor/preview-stage.tsx b/skills/app-store-screenshots/template/src/components/editor/preview-stage.tsx
index 71634d5..e4038a5 100644
--- a/skills/app-store-screenshots/template/src/components/editor/preview-stage.tsx
+++ b/skills/app-store-screenshots/template/src/components/editor/preview-stage.tsx
@@ -8,6 +8,7 @@ import type {
ElementId,
ElementTransform,
Orientation,
+ Scene,
SelectedElement,
Slide,
Theme,
@@ -25,6 +26,7 @@ type Props = {
appIcon?: string;
fontFamily: string;
connectedCanvas: boolean;
+ scene?: Scene;
selectedElement: SelectedElement | null;
onActiveSlideChange: (id: string) => void;
onLabelChange: (slide: Slide, v: string) => void;
@@ -47,6 +49,7 @@ export function PreviewStage({
appIcon,
fontFamily,
connectedCanvas,
+ scene,
selectedElement,
onActiveSlideChange,
onLabelChange,
@@ -146,6 +149,7 @@ export function PreviewStage({
appIcon={appIcon}
fontFamily={fontFamily}
connectedCanvas={connectedCanvas}
+ scene={scene}
editable
previewScale={scale}
selectedElement={selectedElement}
diff --git a/skills/app-store-screenshots/template/src/components/editor/scene-layers.tsx b/skills/app-store-screenshots/template/src/components/editor/scene-layers.tsx
new file mode 100644
index 0000000..39d151c
--- /dev/null
+++ b/skills/app-store-screenshots/template/src/components/editor/scene-layers.tsx
@@ -0,0 +1,431 @@
+"use client";
+// Visual layers driven by the deck-wide Scene (lib/scene.ts): backdrops,
+// decorations, device depth and the magnified callout. Everything here is
+// plain DOM/CSS or inline SVG so html-to-image exports it exactly as previewed.
+import * as React from "react";
+import { img } from "@/lib/image-cache";
+import type { Callout, Scene, Theme } from "@/lib/types";
+
+// ---------- Colour helpers ----------
+
+export function shade(hex: string, percent: number) {
+ const c = hex.replace("#", "");
+ const num = parseInt(c.length === 3 ? c.split("").map((x) => x + x).join("") : c, 16);
+ const amt = Math.round((255 * percent) / 100);
+ const ch = (shift: number) => Math.max(0, Math.min(255, ((num >> shift) & 0xff) + amt));
+ return `#${((ch(16) << 16) | (ch(8) << 8) | ch(0)).toString(16).padStart(6, "0")}`;
+}
+
+function alpha(hex: string, a: number) {
+ const c = hex.replace("#", "");
+ const full = c.length === 3 ? c.split("").map((x) => x + x).join("") : c;
+ const num = parseInt(full, 16);
+ if (!Number.isFinite(num)) return `rgba(0,0,0,${a})`;
+ return `rgba(${(num >> 16) & 0xff}, ${(num >> 8) & 0xff}, ${num & 0xff}, ${Math.max(0, Math.min(1, a))})`;
+}
+
+// Deterministic 0–1 noise so decorations sit in the same place in the editor,
+// thumbnails and every export.
+function hash01(n: number) {
+ const x = Math.sin(n * 127.1 + 311.7) * 43758.5453;
+ return x - Math.floor(x);
+}
+
+// ---------- Backdrop ----------
+
+type BackdropProps = {
+ scene: Scene;
+ theme: Theme;
+ cW: number;
+ cH: number;
+ /** Position of this screen in the strip and the strip length. */
+ index: number;
+ count: number;
+ base: string;
+ fg: string;
+ accent: string;
+ dark: boolean;
+ /** Theme's inverted background (not a custom colour); matches the classic gradient depth. */
+ inverted: boolean;
+ /** The slide's own `inverted` flag; the classic blobs key their opacity off it. */
+ blobsInverted?: boolean;
+};
+
+/**
+ * One screen's backdrop. With `scene.span`, the art layer is laid out across
+ * the whole strip and this screen shows its slice, so shapes flow over seams.
+ * The base colour stays per screen, so inverted and custom-colour screens keep
+ * their own background.
+ */
+export function SceneBackdrop(props: BackdropProps) {
+ const { scene, cW, cH, index, count, base } = props;
+ const span = scene.span && count > 1;
+ const stripW = span ? cW * count : cW;
+ const offset = span ? -index * cW : 0;
+ const baseFill =
+ scene.backdrop === "gradient"
+ ? `linear-gradient(160deg, ${base} 0%, ${shade(base, props.inverted ? -8 : -6)} 100%)`
+ : base;
+ return (
+ <div aria-hidden style={{ position: "absolute", inset: 0, overflow: "hidden", background: baseFill, pointerEvents: "none" }}>
+ <div
+ data-scene-art={scene.backdrop}
+ style={{
+ position: "absolute",
+ left: offset,
+ top: 0,
+ width: stripW,
+ height: cH,
+ background: backdropArt(props, stripW, span),
+ }}
+ />
+ {scene.backdrop === "spotlight" && (
+ <div
+ style={{
+ position: "absolute",
+ inset: 0,
+ background: `radial-gradient(ellipse ${cW * 0.75}px ${cH * 0.62}px at ${cW / 2}px ${cH * 0.45}px, transparent 55%, rgba(0,0,0,${props.dark ? 0.45 : 0.16}) 100%)`,
+ }}
+ />
+ )}
+ <SceneDecor {...props} stripW={stripW} offset={offset} span={span} />
+ </div>
+ );
+}
+
+function backdropArt(p: BackdropProps, stripW: number, span: boolean): string | undefined {
+ const { cW, cH, fg, accent, dark, theme } = p;
+ const second = theme.accentAlt && theme.accentAlt !== accent ? theme.accentAlt : theme.muted;
+ const unit = Math.min(cW, cH);
+ switch (p.scene.backdrop) {
+ case "gradient":
+ return span
+ ? `linear-gradient(100deg, transparent 0%, ${alpha(accent, 0.16)} 28%, transparent 52%, ${alpha(accent, 0.12)} 78%, transparent 100%)`
+ : undefined;
+ case "solid":
+ return undefined;
+ case "aurora": {
+ // A row of soft colour pools; spanning decks get one per ~0.7 screens so
+ // pools straddle the seams.
+ const pools = Math.max(2, Math.round((stripW / cW) * (span ? 1.4 : 2)));
+ const layers: string[] = [];
+ for (let i = 0; i < pools; i++) {
+ const x = ((i + 0.5) / pools) * stripW + (hash01(i + 3) - 0.5) * cW * 0.25;
+ const y = (i % 2 === 0 ? 0.18 : 0.78) * cH + (hash01(i + 11) - 0.5) * cH * 0.12;
+ const color = [accent, second, fg][i % 3];
+ const strength = i % 3 === 2 ? 0.12 : dark ? 0.55 : 0.42;
+ const r = cW * (0.75 + hash01(i + 5) * 0.35);
+ layers.push(`radial-gradient(circle at ${x}px ${y}px, ${alpha(color, strength)} 0px, transparent ${r}px)`);
+ }
+ return layers.join(", ");
+ }
+ case "spotlight": {
+ const lights: string[] = [];
+ const screens = Math.round(stripW / cW);
+ for (let i = 0; i < screens; i++) {
+ const x = span ? (i + 0.5 + (i % 2 === 0 ? -0.32 : 0.32)) * cW : cW * 0.5;
+ const light = dark ? alpha(accent, 0.42) : "rgba(255,255,255,0.75)";
+ lights.push(`radial-gradient(ellipse ${cW * 0.7}px ${cH * 0.45}px at ${x}px ${cH * 0.12}px, ${light} 0px, transparent 100%)`);
+ }
+ // The vignette is a separate, unshifted layer (see SceneBackdrop) so
+ // every screen gets its own dark corners even when the lights span.
+ return lights.join(", ");
+ }
+ case "grid": {
+ const g = Math.round(unit * 0.08);
+ const line = alpha(fg, dark ? 0.1 : 0.08);
+ const w = Math.max(1, Math.round(unit * 0.0016));
+ return [
+ `radial-gradient(ellipse ${cW * 0.8}px ${cH * 0.4}px at ${stripW / 2}px ${cH * 0.55}px, ${alpha(accent, 0.18)} 0px, transparent 100%)`,
+ `repeating-linear-gradient(90deg, ${line} 0px, ${line} ${w}px, transparent ${w}px, transparent ${g}px)`,
+ `repeating-linear-gradient(0deg, ${line} 0px, ${line} ${w}px, transparent ${w}px, transparent ${g}px)`,
+ ].join(", ");
+ }
+ case "dots": {
+ const g = Math.round(unit * 0.055);
+ const dot = alpha(fg, dark ? 0.2 : 0.14);
+ const r = Math.max(1.5, unit * 0.0045);
+ return [
+ `radial-gradient(circle at ${g / 2}px ${g / 2}px, ${dot} 0px, ${dot} ${r}px, transparent ${r + 0.8}px)`,
+ ].join(", ") + ` 0 0 / ${g}px ${g}px`;
+ }
+ case "lines": {
+ const g = Math.round(unit * 0.06);
+ const line = alpha(fg, dark ? 0.1 : 0.09);
+ const w = Math.max(1, Math.round(unit * 0.0016));
+ return `repeating-linear-gradient(180deg, transparent 0px, transparent ${g - w}px, ${line} ${g - w}px, ${line} ${g}px)`;
+ }
+ }
+}
+
+function SceneDecor({
+ scene,
+ cW,
+ cH,
+ accent,
+ dark,
+ inverted,
+ blobsInverted,
+ index,
+ count,
+ stripW,
+ offset,
+ span,
+}: BackdropProps & { stripW: number; offset: number; span: boolean }) {
+ if (scene.decoration === "none") return null;
+ const screens = Math.max(1, Math.round(stripW / cW));
+ // Spanning decks centre shapes on the seams between screens.
+ const anchors: { x: number; y: number; k: number }[] = [];
+ if (span) {
+ for (let i = 0; i <= count; i++) {
+ anchors.push({ x: i * cW, y: (i % 2 === 0 ? 0.12 : 0.86) * cH, k: i });
+ }
+ } else {
+ anchors.push({ x: -0.05 * cW, y: 0.06 * cH, k: 0 });
+ anchors.push({ x: 0.98 * cW, y: 0.9 * cH, k: 1 });
+ }
+
+ if (scene.decoration === "blobs" && !span) {
+ // The classic pair, exactly as decks rendered before scenes existed.
+ return (
+ <>
+ {[
+ { left: -0.15, top: -0.1, size: 0.55, opacity: (blobsInverted ?? inverted) ? 0.25 : 0.32 },
+ { left: 0.7, top: 0.75, size: 0.45, opacity: (blobsInverted ?? inverted) ? 0.18 : 0.25 },
+ ].map((b, i) => (
+ <div
+ key={i}
+ style={{
+ position: "absolute",
+ left: b.left * cW,
+ top: b.top * cH,
+ width: b.size * cW,
+ height: b.size * cW,
+ background: accent,
+ borderRadius: "50%",
+ filter: `blur(${cW * 0.06}px)`,
+ opacity: b.opacity,
+ }}
+ />
+ ))}
+ </>
+ );
+ }
+
+ if (scene.decoration === "blobs") {
+ return (
+ <div style={{ position: "absolute", left: offset, top: 0, width: stripW, height: cH }}>
+ {anchors.map(({ x, y, k }) => {
+ const size = cW * (k % 2 === 0 ? 0.55 : 0.45);
+ return (
+ <div
+ key={k}
+ style={{
+ position: "absolute",
+ left: x - size / 2,
+ top: y - size / 2,
+ width: size,
+ height: size,
+ borderRadius: "50%",
+ background: accent,
+ filter: `blur(${cW * 0.06}px)`,
+ opacity: dark ? (k % 2 === 0 ? 0.25 : 0.18) : k % 2 === 0 ? 0.32 : 0.25,
+ }}
+ />
+ );
+ })}
+ </div>
+ );
+ }
+
+ if (scene.decoration === "rings") {
+ const stroke = Math.max(2, cW * 0.004);
+ return (
+ <svg
+ width={stripW}
+ height={cH}
+ viewBox={`0 0 ${stripW} ${cH}`}
+ style={{ position: "absolute", left: offset, top: 0, overflow: "visible" }}
+ >
+ {anchors.map(({ x, y, k }) =>
+ [0.22, 0.32, 0.42].map((r, j) => (
+ <circle
+ key={`${k}-${j}`}
+ cx={x}
+ cy={y}
+ r={cW * r}
+ fill="none"
+ stroke={accent}
+ strokeWidth={stroke}
+ opacity={dark ? 0.32 - j * 0.07 : 0.4 - j * 0.09}
+ />
+ )),
+ )}
+ </svg>
+ );
+ }
+
+ // Sparkles: four-point stars scattered with a fixed seed per screen.
+ const stars: { x: number; y: number; s: number; o: number }[] = [];
+ for (let i = 0; i < screens; i++) {
+ for (let j = 0; j < 5; j++) {
+ // Isolated screens each get their own scatter rather than a repeat.
+ const n = (span ? i : index) * 7 + j;
+ const yBand = j % 2 === 0 ? 0.04 + hash01(n + 1) * 0.26 : 0.62 + hash01(n + 2) * 0.32;
+ stars.push({
+ x: (i + 0.06 + hash01(n + 3) * 0.88) * cW,
+ y: yBand * cH,
+ s: cW * (0.025 + hash01(n + 4) * 0.045),
+ o: 0.45 + hash01(n + 5) * 0.45,
+ });
+ }
+ }
+ return (
+ <svg
+ width={stripW}
+ height={cH}
+ viewBox={`0 0 ${stripW} ${cH}`}
+ style={{ position: "absolute", left: offset, top: 0, overflow: "visible" }}
+ >
+ {stars.map(({ x, y, s, o }, i) => (
+ <path
+ key={i}
+ d={`M ${x} ${y - s} Q ${x} ${y} ${x + s} ${y} Q ${x} ${y} ${x} ${y + s} Q ${x} ${y} ${x - s} ${y} Q ${x} ${y} ${x} ${y - s} Z`}
+ fill={accent}
+ opacity={dark ? o : o * 0.85}
+ />
+ ))}
+ </svg>
+ );
+}
+
+// ---------- Device depth ----------
+
+/** Shadow, glow and 3D tilt around a device frame. Classic scenes render the frame untouched. */
+export function DeviceDepth({
+ scene,
+ cW,
+ accent,
+ children,
+}: {
+ scene: Scene;
+ cW: number;
+ accent: string;
+ children: React.ReactNode;
+}) {
+ if (!scene.shadow && !scene.glow && !scene.tilt) return <>{children}</>;
+ const s = scene.shadow / 100;
+ const g = scene.glow / 100;
+ return (
+ <div style={{ position: "relative", width: "100%", height: "100%" }}>
+ {g > 0 && (
+ <div
+ aria-hidden
+ style={{
+ position: "absolute",
+ inset: "-14% -38%",
+ background: `radial-gradient(closest-side, ${alpha(accent, 0.95 * g)} 0%, ${alpha(accent, 0.42 * g)} 55%, transparent 100%)`,
+ pointerEvents: "none",
+ }}
+ />
+ )}
+ <div
+ style={{
+ position: "relative",
+ width: "100%",
+ height: "100%",
+ filter: s > 0
+ ? `drop-shadow(0 ${cW * 0.03 * s}px ${cW * 0.045 * s}px rgba(0,0,0,${0.12 + 0.33 * s}))`
+ : undefined,
+ }}
+ >
+ <div
+ style={{
+ width: "100%",
+ height: "100%",
+ transform: scene.tilt
+ ? `perspective(${cW * 2.6}px) rotateY(${scene.tilt}deg) rotateX(${Math.abs(scene.tilt) * 0.22}deg)`
+ : undefined,
+ transformOrigin: "center center",
+ }}
+ >
+ {children}
+ </div>
+ </div>
+ </div>
+ );
+}
+
+// ---------- Magnified callout ----------
+
+/**
+ * A loupe showing part of the screenshot at `zoom`× the size it appears on the
+ * device. `screenWidth` is the device's on-canvas screen width in canvas px.
+ */
+export function CalloutLoupe({
+ callout,
+ src,
+ screenWidth,
+ cW,
+ accent,
+ hideEmpty,
+}: {
+ callout: Callout;
+ src: string;
+ screenWidth: number;
+ cW: number;
+ accent: string;
+ hideEmpty?: boolean;
+}) {
+ const resolved = img(src);
+ const border = Math.max(3, cW * 0.009);
+ // An export without a screenshot shouldn't ship an empty lens.
+ if (!resolved && hideEmpty) return null;
+ return (
+ <div
+ style={{
+ position: "relative",
+ width: "100%",
+ height: "100%",
+ borderRadius: callout.shape === "circle" ? "50%" : "14%",
+ overflow: "hidden",
+ background: "#0f0f12",
+ boxShadow: `0 0 0 ${border}px #ffffff, 0 ${cW * 0.025}px ${cW * 0.06}px rgba(0,0,0,0.32)`,
+ }}
+ >
+ {resolved ? (
+ <img
+ src={resolved}
+ alt=""
+ draggable={false}
+ style={{
+ position: "absolute",
+ left: "50%",
+ top: "50%",
+ width: screenWidth * callout.zoom,
+ maxWidth: "none",
+ height: "auto",
+ transform: `translate(${-callout.focusX * 100}%, ${-callout.focusY * 100}%)`,
+ }}
+ />
+ ) : hideEmpty ? null : (
+ <div
+ style={{
+ position: "absolute",
+ inset: 0,
+ display: "flex",
+ alignItems: "center",
+ justifyContent: "center",
+ color: "rgba(255,255,255,0.7)",
+ fontSize: cW * 0.03,
+ fontWeight: 600,
+ textAlign: "center",
+ background: `radial-gradient(circle, ${alpha(accent, 0.45)} 0%, #0f0f12 75%)`,
+ }}
+ >
+ Add a screenshot
+ </div>
+ )}
+ </div>
+ );
+}
diff --git a/skills/app-store-screenshots/template/src/components/editor/scene-playground.tsx b/skills/app-store-screenshots/template/src/components/editor/scene-playground.tsx
new file mode 100644
index 0000000..4ef6499
--- /dev/null
+++ b/skills/app-store-screenshots/template/src/components/editor/scene-playground.tsx
@@ -0,0 +1,333 @@
+"use client";
+import * as React from "react";
+import { Dices, Layers, RotateCcw } from "lucide-react";
+import { Button } from "@/components/ui/button";
+import { Label } from "@/components/ui/label";
+import { Popover, PopoverContent, PopoverTrigger } from "@/components/ui/popover";
+import { relativeLuminance } from "@/lib/contrast";
+import { BACKDROPS, DECORATIONS, DEFAULT_SCENE, TILT_LIMIT, sameScene, sceneOf } from "@/lib/scene";
+import { DIRECTIONS, generateLook } from "@/lib/style-lab";
+import { cn } from "@/lib/utils";
+import type { Scene, Theme } from "@/lib/types";
+import { SceneBackdrop } from "./scene-layers";
+
+const TILE_W = 72;
+const TILE_H = 48;
+
+/** Toolbar popover that edits the deck-wide scene live on the canvas. */
+export function ScenePlayground({
+ scene: rawScene,
+ theme,
+ disabled,
+ onChange,
+}: {
+ scene: Scene | undefined;
+ theme: Theme;
+ disabled?: boolean;
+ onChange: (scene: Scene | undefined) => void;
+}) {
+ const scene = sceneOf(rawScene);
+ const classic = sameScene(scene, DEFAULT_SCENE);
+ const surprises = React.useRef(0);
+
+ function patch(next: Partial<Scene>) {
+ const merged = { ...scene, ...next };
+ onChange(sameScene(merged, DEFAULT_SCENE) ? undefined : merged);
+ }
+
+ function surprise() {
+ surprises.current += 1;
+ const seed = Math.floor(Math.random() * 1e6) + surprises.current;
+ const direction = DIRECTIONS[seed % DIRECTIONS.length];
+ const next = generateLook(direction.id, seed).scene;
+ // Surprise the stage, not the copy: headline styling stays as set.
+ patch({
+ backdrop: next.backdrop,
+ span: next.span,
+ decoration: next.decoration,
+ shadow: next.shadow,
+ glow: next.glow,
+ tilt: next.tilt,
+ });
+ }
+
+ return (
+ <Popover>
+ <PopoverTrigger asChild>
+ <Button
+ type="button"
+ variant={classic ? "outline" : "secondary"}
+ size="sm"
+ className="h-8 gap-1.5 px-2 text-xs"
+ disabled={disabled}
+ title="Scene: backdrop, decoration, depth and headline style for every screen"
+ >
+ <Layers className="h-3.5 w-3.5" />
+ Scene
+ </Button>
+ </PopoverTrigger>
+ <PopoverContent className="max-h-[min(80vh,640px)] w-[22rem] overflow-y-auto" aria-label="Scene">
+ <div className="mb-3 flex items-center justify-between gap-2">
+ <div>
+ <h2 className="text-sm font-semibold">Scene</h2>
+ <p className="text-[11px] text-muted-foreground">Applies to every screen in this project.</p>
+ </div>
+ <div className="flex items-center gap-1">
+ <Button type="button" variant="outline" size="sm" className="h-7 gap-1 px-2 text-xs" onClick={surprise}>
+ <Dices className="h-3.5 w-3.5" />
+ Surprise me
+ </Button>
+ <Button
+ type="button"
+ variant="ghost"
+ size="icon"
+ className="h-7 w-7"
+ onClick={() => onChange(undefined)}
+ disabled={classic}
+ title="Back to the classic scene"
+ aria-label="Reset scene"
+ >
+ <RotateCcw className="h-3.5 w-3.5" />
+ </Button>
+ </div>
+ </div>
+
+ <Section title="Backdrop">
+ <TileGroup label="Backdrop">
+ {BACKDROPS.map((b) => (
+ <Tile key={b.id} name={b.name} checked={scene.backdrop === b.id} onSelect={() => patch({ backdrop: b.id })}>
+ <Swatch theme={theme} scene={{ ...scene, backdrop: b.id, decoration: "none", span: false }} />
+ </Tile>
+ ))}
+ </TileGroup>
+ <label className="mt-2 flex cursor-pointer items-start gap-2 text-xs">
+ <input
+ type="checkbox"
+ className="mt-0.5"
+ checked={scene.span}
+ onChange={(e) => patch({ span: e.target.checked })}
+ />
+ <span>
+ <span className="font-medium">Flow across screens</span>
+ <span className="block text-[11px] text-muted-foreground">
+ One continuous backdrop over the whole strip, so shapes cross the seams.
+ </span>
+ </span>
+ </label>
+ </Section>
+
+ <Section title="Decoration">
+ <TileGroup label="Decoration">
+ {DECORATIONS.map((d) => (
+ <Tile key={d.id} name={d.name} checked={scene.decoration === d.id} onSelect={() => patch({ decoration: d.id })}>
+ <Swatch theme={theme} scene={{ ...scene, backdrop: "solid", decoration: d.id, span: false }} />
+ </Tile>
+ ))}
+ </TileGroup>
+ </Section>
+
+ <Section title="Device depth">
+ <Slider label="Shadow" value={scene.shadow} min={0} max={100} unit="%" onChange={(shadow) => patch({ shadow })} />
+ <Slider label="Glow" value={scene.glow} min={0} max={100} unit="%" onChange={(glow) => patch({ glow })} />
+ <Slider label="Tilt" value={scene.tilt} min={-TILT_LIMIT} max={TILT_LIMIT} unit="°" onChange={(tilt) => patch({ tilt })} />
+ </Section>
+
+ <Section title="Headline">
+ <Slider
+ label="Weight"
+ value={scene.headlineWeight}
+ min={300}
+ max={900}
+ step={100}
+ onChange={(headlineWeight) => patch({ headlineWeight })}
+ reset={DEFAULT_SCENE.headlineWeight}
+ />
+ <Slider
+ label="Size"
+ value={Math.round(scene.headlineScale * 100)}
+ min={50}
+ max={200}
+ step={5}
+ unit="%"
+ onChange={(pct) => patch({ headlineScale: pct / 100 })}
+ reset={100}
+ />
+ <div className="grid grid-cols-2 gap-2">
+ <Segmented
+ label="Case"
+ value={scene.headlineCase}
+ options={[
+ { id: "as-typed", name: "As typed" },
+ { id: "upper", name: "UPPER" },
+ ]}
+ onChange={(headlineCase) => patch({ headlineCase })}
+ />
+ <Segmented
+ label="Align"
+ value={scene.captionAlign}
+ options={[
+ { id: "auto", name: "Auto" },
+ { id: "left", name: "Left" },
+ { id: "center", name: "Center" },
+ ]}
+ onChange={(captionAlign) => patch({ captionAlign })}
+ />
+ </div>
+ </Section>
+ </PopoverContent>
+ </Popover>
+ );
+}
+
+function Section({ title, children }: { title: string; children: React.ReactNode }) {
+ return (
+ <section className="space-y-2 border-t pt-3 first-of-type:border-t-0 first-of-type:pt-0 [&+&]:mt-3">
+ <h3 className="text-[11px] font-semibold uppercase tracking-wide text-muted-foreground">{title}</h3>
+ {children}
+ </section>
+ );
+}
+
+function TileGroup({ label, children }: { label: string; children: React.ReactNode }) {
+ return (
+ <div role="radiogroup" aria-label={label} className="grid grid-cols-4 gap-1.5">
+ {children}
+ </div>
+ );
+}
+
+function Tile({
+ name,
+ checked,
+ onSelect,
+ children,
+}: {
+ name: string;
+ checked: boolean;
+ onSelect: () => void;
+ children: React.ReactNode;
+}) {
+ return (
+ <button
+ type="button"
+ role="radio"
+ aria-checked={checked}
+ aria-label={name}
+ onClick={onSelect}
+ className={cn(
+ "group flex flex-col items-center gap-1 rounded-md p-1 text-[10px] outline-none transition-colors hover:bg-accent focus-visible:ring-2 focus-visible:ring-ring",
+ checked && "bg-accent",
+ )}
+ >
+ <span
+ className={cn(
+ "relative block overflow-hidden rounded ring-1 ring-black/10",
+ checked && "ring-2 ring-primary",
+ )}
+ style={{ width: TILE_W, height: TILE_H }}
+ >
+ {children}
+ </span>
+ <span className={cn("text-muted-foreground", checked && "font-medium text-foreground")}>{name}</span>
+ </button>
+ );
+}
+
+// A real backdrop rendered at tile size, in the deck's own theme colours.
+function Swatch({ theme, scene }: { theme: Theme; scene: Scene }) {
+ return (
+ <SceneBackdrop
+ scene={scene}
+ theme={theme}
+ cW={TILE_W}
+ cH={TILE_H}
+ index={0}
+ count={1}
+ base={theme.bg}
+ fg={theme.fg}
+ accent={theme.accent}
+ dark={(relativeLuminance(theme.bg) ?? 1) < 0.18}
+ inverted={false}
+ />
+ );
+}
+
+function Slider({
+ label,
+ value,
+ min,
+ max,
+ step = 1,
+ unit = "",
+ reset = 0,
+ onChange,
+}: {
+ label: string;
+ value: number;
+ min: number;
+ max: number;
+ step?: number;
+ unit?: string;
+ reset?: number;
+ onChange: (value: number) => void;
+}) {
+ return (
+ <div className="space-y-0.5">
+ <div className="flex items-center justify-between">
+ <Label className="text-[11px] text-muted-foreground">{label}</Label>
+ <span className="text-[11px] tabular-nums text-muted-foreground">
+ {value}
+ {unit}
+ </span>
+ </div>
+ <input
+ type="range"
+ min={min}
+ max={max}
+ step={step}
+ value={value}
+ onChange={(e) => onChange(Number(e.target.value))}
+ onDoubleClick={() => onChange(reset)}
+ className="w-full"
+ aria-label={label}
+ aria-valuetext={`${value}${unit}`}
+ title="Double-click to reset"
+ />
+ </div>
+ );
+}
+
+function Segmented<T extends string>({
+ label,
+ value,
+ options,
+ onChange,
+}: {
+ label: string;
+ value: T;
+ options: { id: T; name: string }[];
+ onChange: (value: T) => void;
+}) {
+ return (
+ <div className="space-y-1">
+ <Label className="text-[11px] text-muted-foreground">{label}</Label>
+ <div role="radiogroup" aria-label={label} className="flex rounded-md border p-0.5">
+ {options.map((o) => (
+ <button
+ key={o.id}
+ type="button"
+ role="radio"
+ aria-checked={value === o.id}
+ onClick={() => onChange(o.id)}
+ className={cn(
+ "flex-1 rounded px-1.5 py-1 text-[11px] outline-none focus-visible:ring-2 focus-visible:ring-ring",
+ value === o.id ? "bg-secondary font-medium text-foreground shadow-sm" : "text-muted-foreground hover:text-foreground",
+ )}
+ >
+ {o.name}
+ </button>
+ ))}
+ </div>
+ </div>
+ );
+}
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 1c0b738..93c914a 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
@@ -33,6 +33,7 @@ import { Inspector } from "./inspector";
import { PreviewStage } from "./preview-stage";
import { Sidebar } from "./sidebar";
import { DeckCanvas, getCanvas } from "./slide-canvas";
+import { StyleLab } from "./style-lab";
import { Toolbar } from "./toolbar";
export function ScreenshotEditor() {
@@ -47,6 +48,10 @@ export function ScreenshotEditor() {
const exportInProgress = React.useRef(false);
const [exportProject, setExportProject] = React.useState<ProjectState | null>(null);
const exportRef = React.useRef<HTMLDivElement | null>(null);
+ const [styleLabOpen, setStyleLabOpen] = React.useState(false);
+ // The latest committed project, for actions that must check nothing changed since.
+ const latestState = React.useRef(state);
+ latestState.current = state;
const currentSlides = state.slidesByDevice[state.device] || [];
const activeSlide =
@@ -668,6 +673,9 @@ export function ScreenshotEditor() {
setThemeId={(v) => setState((p) => ({ ...p, themeId: v }))}
connectedCanvas={state.connectedCanvas}
setConnectedCanvas={(v) => setState((p) => ({ ...p, connectedCanvas: v }))}
+ scene={state.scene}
+ setScene={(scene) => setState((p) => ({ ...p, scene }))}
+ onOpenStyleLab={() => setStyleLabOpen(true)}
fontId={fontId}
setFontId={(v) => setState((p) => ({ ...p, fontId: v }))}
importedFont={state.importedFont}
@@ -714,6 +722,7 @@ export function ScreenshotEditor() {
appIcon={state.appIcon}
fontFamily={fontFamily}
connectedCanvas={state.connectedCanvas}
+ scene={state.scene}
disabled={busy}
onReorder={reorderSlides}
onSelect={setActiveSlideId}
@@ -736,6 +745,7 @@ export function ScreenshotEditor() {
appIcon={state.appIcon}
fontFamily={fontFamily}
connectedCanvas={state.connectedCanvas}
+ scene={state.scene}
selectedElement={selectedElement}
onActiveSlideChange={setActiveSlideId}
onLabelChange={(slide, v) => patchLocalized(slide, "label", v)}
@@ -783,6 +793,31 @@ export function ScreenshotEditor() {
</aside>
</div>
+ <StyleLab
+ open={styleLabOpen}
+ onOpenChange={setStyleLabOpen}
+ state={state}
+ onApply={(next, look) => {
+ setState(next, { coalesce: false });
+ setSelectedElement(null);
+ toast.success(`Applied ${look.name}`, {
+ action: {
+ label: "Undo",
+ onClick: () => {
+ // Only undo the look itself, never an edit made after it.
+ if (latestState.current === next) undo();
+ else toast("Use the toolbar Undo", { description: "You've edited the deck since applying this look." });
+ },
+ },
+ duration: 8000,
+ });
+ }}
+ onSavedLooksChange={(savedLooks) =>
+ // A look library, not a deck edit: keep it out of undo history.
+ setState((p) => ({ ...p, savedLooks: savedLooks.length ? savedLooks : undefined }), { history: false })
+ }
+ />
+
{/* Off-screen export container — full-resolution canvases for html-to-image. */}
<div
aria-hidden
@@ -824,6 +859,7 @@ export function ScreenshotEditor() {
appIcon={exportState.appIcon}
fontFamily={SCREENSHOT_FONTS[exportState.fontId || DEFAULT_SCREENSHOT_FONT_ID].family}
connectedCanvas={exportState.connectedCanvas}
+ scene={exportState.scene}
hideEmpty
/>
</div>
diff --git a/skills/app-store-screenshots/template/src/components/editor/sidebar.tsx b/skills/app-store-screenshots/template/src/components/editor/sidebar.tsx
index 4214b4e..6690d5d 100644
--- a/skills/app-store-screenshots/template/src/components/editor/sidebar.tsx
+++ b/skills/app-store-screenshots/template/src/components/editor/sidebar.tsx
@@ -17,7 +17,7 @@ import {
} from "@dnd-kit/sortable";
import { Plus } from "lucide-react";
import { Button } from "@/components/ui/button";
-import type { Device, Orientation, Slide, Theme } from "@/lib/types";
+import type { Device, Orientation, Scene, Slide, Theme } from "@/lib/types";
import { newSlide } from "@/lib/defaults";
import { SlideThumb } from "./slide-thumb";
@@ -32,6 +32,7 @@ type Props = {
appIcon?: string;
fontFamily?: string;
connectedCanvas: boolean;
+ scene?: Scene;
disabled?: boolean;
onReorder: (next: Slide[]) => void;
onSelect: (id: string) => void;
@@ -51,6 +52,7 @@ export function Sidebar({
appIcon,
fontFamily,
connectedCanvas,
+ scene,
disabled,
onReorder,
onSelect,
@@ -100,6 +102,7 @@ export function Sidebar({
appIcon={appIcon}
fontFamily={fontFamily}
connectedCanvas={connectedCanvas}
+ scene={scene}
onSelect={() => onSelect(slide.id)}
onDelete={() => onDelete(slide.id)}
onDuplicate={() => onDuplicate(slide.id)}
diff --git a/skills/app-store-screenshots/template/src/components/editor/slide-canvas.tsx b/skills/app-store-screenshots/template/src/components/editor/slide-canvas.tsx
index 9f70d7e..931f430 100644
--- a/skills/app-store-screenshots/template/src/components/editor/slide-canvas.tsx
+++ b/skills/app-store-screenshots/template/src/components/editor/slide-canvas.tsx
@@ -9,6 +9,7 @@ import type {
ElementTransform,
ImageElement,
Orientation,
+ Scene,
SelectedElement,
Slide,
TextElement,
@@ -35,8 +36,9 @@ import {
import { imageElementKey, isImageElementId, toImageElementId, toTextElementId } from "@/lib/elements";
import { img } from "@/lib/image-cache";
import { pickText, resolveScreenshot } from "@/lib/locale";
-import { slideColors } from "@/lib/contrast";
+import { relativeLuminance, slideColors } from "@/lib/contrast";
import { defaultTextElementFontSize, slideFontScales } from "@/lib/typography";
+import { sceneOf } from "@/lib/scene";
import {
AndroidPhone,
AppleTV,
@@ -49,6 +51,7 @@ import {
Phone,
} from "./device-frames";
import { ImageElementCanvas } from "./image-element-canvas";
+import { CalloutLoupe, DeviceDepth, SceneBackdrop, shade } from "./scene-layers";
type FrameComp = React.ComponentType<{
src: string;
@@ -137,6 +140,10 @@ type Props = {
previewScale?: number;
/** When true, suppress the "Drop a screenshot here" placeholder. Used for export. */
hideEmpty?: boolean;
+ scene?: Scene;
+ /** Where this screen sits in the full deck, for backdrops that span the strip. */
+ stripIndex?: number;
+ stripCount?: number;
};
type DeckEditHandlers = {
@@ -165,6 +172,10 @@ type DeckCanvasProps = {
previewScale?: number;
hideEmpty?: boolean;
showGuides?: boolean;
+ scene?: Scene;
+ /** When `slides` is a slice of a longer deck: its first index and the deck length. */
+ stripStart?: number;
+ stripCount?: number;
};
// ---------- Editable text helpers ----------
@@ -262,6 +273,7 @@ function Caption({
edit,
align = "center",
inverted,
+ scene,
onFocus,
}: {
cW: number;
@@ -273,6 +285,7 @@ function Caption({
edit?: EditHandlers;
align?: "center" | "left";
inverted?: boolean;
+ scene: Scene;
onFocus?: () => void;
}) {
const { fg, accent } = slideColors(theme, { inverted, backgroundColor: slide.backgroundColor });
@@ -309,10 +322,11 @@ function Caption({
onFocus={onFocus}
placeholder="Headline goes here"
style={{
- fontSize: unit * 0.092 * headlineScale,
- fontWeight: 700,
+ fontSize: unit * 0.092 * headlineScale * scene.headlineScale,
+ fontWeight: scene.headlineWeight,
lineHeight: 0.96,
- letterSpacing: -unit * 0.001 * headlineScale,
+ letterSpacing: (scene.headlineCase === "upper" ? unit * 0.0015 : -unit * 0.001) * headlineScale,
+ textTransform: scene.headlineCase === "upper" ? "uppercase" : undefined,
color: fg,
}}
/>
@@ -320,31 +334,6 @@ function Caption({
);
}
-// ---------- Background ----------
-
-function backgroundFor(theme: Theme, inverted?: boolean, customColor?: string) {
- if (customColor) {
- return `linear-gradient(160deg, ${customColor} 0%, ${shade(customColor, -6)} 100%)`;
- }
- if (inverted) {
- return `linear-gradient(160deg, ${theme.bgAlt} 0%, ${shade(theme.bgAlt, -8)} 100%)`;
- }
- return `linear-gradient(160deg, ${theme.bg} 0%, ${shade(theme.bg, -6)} 100%)`;
-}
-
-function shade(hex: string, percent: number) {
- const c = hex.replace("#", "");
- const num = parseInt(c.length === 3 ? c.split("").map((x) => x + x).join("") : c, 16);
- let r = (num >> 16) & 0xff;
- let g = (num >> 8) & 0xff;
- let b = num & 0xff;
- const amt = Math.round((255 * percent) / 100);
- r = Math.max(0, Math.min(255, r + amt));
- g = Math.max(0, Math.min(255, g + amt));
- b = Math.max(0, Math.min(255, b + amt));
- return `#${((r << 16) | (g << 8) | b).toString(16).padStart(6, "0")}`;
-}
-
// ---------- Decorative blob ----------
function Blob({
@@ -387,6 +376,7 @@ type LayoutRects = {
caption?: Rect & { align?: "center" | "left" };
device?: Rect;
deviceSecondary?: Rect;
+ callout?: Rect;
};
function getDefaultRects(
@@ -523,9 +513,29 @@ function getSlideGeometry(slide: Slide, device: Device, orientation: Orientation
slide.layout, cW, cH, frameAspect, fwFrac, fwSmallFrac,
CONTAINED_DEVICES.has(device),
);
+ if (slide.callout && defaults.device) defaults.callout = defaultCalloutRect(defaults.device, cW, cH);
return { cW, cH, Frame, frameAspect, defaults };
}
+// The loupe starts overlapping the device's upper right, inside the screen.
+function defaultCalloutRect(device: Rect, cW: number, cH: number): Rect {
+ const size = Math.min(cW, cH) * 0.44;
+ return {
+ x: Math.min(cW - size - cW * 0.04, device.x + device.width * 0.58),
+ y: Math.max(cH * 0.04, Math.min(cH - size * 1.04, device.y + device.height * 0.16)),
+ width: size,
+ height: size,
+ };
+}
+
+// Share of a frame's width taken by its screen. Close enough for every frame
+// that the callout's zoom reads as "× the size it appears on the device".
+export const SCREEN_WIDTH_FRACTION = 0.9;
+
+export function calloutAvailable(slide: Slide, device: Device) {
+ return device !== "feature-graphic" && slide.layout !== "no-device" && slide.layout !== "feature-graphic";
+}
+
export function getElementTransform(
slide: Slide,
device: Device,
@@ -558,6 +568,7 @@ export function getElementTransform(
function defaultElementZ(id: BuiltInElementId): number {
if (id === "deviceSecondary") return 2;
if (id === "device") return 3;
+ if (id === "callout") return 5;
return 4;
}
@@ -577,8 +588,12 @@ export function SlideCanvas({
selectedElementId = null,
previewScale = 1,
hideEmpty,
+ scene: rawScene,
+ stripIndex = 0,
+ stripCount = 1,
}: Props) {
const { cW, cH } = getCanvas(device, orientation);
+ const scene = sceneOf(rawScene);
if (slide.layout === "feature-graphic" || device === "feature-graphic") {
return (
@@ -614,9 +629,10 @@ export function SlideCanvas({
fontFamily,
}}
>
- <SlideBackground slide={slide} cW={cW} cH={cH} theme={theme} />
+ <SlideBackground slide={slide} cW={cW} cH={cH} theme={theme} scene={scene} index={stripIndex} count={stripCount} />
<SlideElements
slide={slide}
+ scene={scene}
device={device}
orientation={orientation}
theme={theme}
@@ -654,8 +670,12 @@ export function DeckCanvas({
previewScale = 1,
hideEmpty,
showGuides = false,
+ scene: rawScene,
+ stripStart = 0,
+ stripCount,
}: DeckCanvasProps) {
const { cW, cH } = getCanvas(device, orientation);
+ const scene = sceneOf(rawScene);
const totalW = Math.max(1, slides.length) * cW;
return (
@@ -723,7 +743,7 @@ export function DeckCanvas({
overflow: "hidden",
}}
>
- <SlideBackground slide={slide} cW={cW} cH={cH} theme={theme} />
+ <SlideBackground slide={slide} cW={cW} cH={cH} theme={theme} scene={scene} index={stripStart + index} count={stripCount ?? slides.length} />
{showGuides && <ScreenGuide cW={cW} cH={cH} index={index} active={active} />}
</div>
);
@@ -750,6 +770,7 @@ export function DeckCanvas({
<SlideElements
key={`${slide.id}-elements`}
slide={slide}
+ scene={scene}
device={device}
orientation={orientation}
theme={theme}
@@ -791,29 +812,49 @@ function SlideBackground({
cW,
cH,
theme,
+ scene,
+ index,
+ count,
}: {
slide: Slide;
cW: number;
cH: number;
theme: Theme;
+ scene: Scene;
+ index: number;
+ count: number;
}) {
const inverted = !!slide.inverted;
+ const colors = slideColors(theme, slide);
return (
<div
style={{
position: "absolute",
inset: 0,
overflow: "hidden",
- background: backgroundFor(theme, inverted, slide.backgroundColor),
- color: slideColors(theme, slide).fg,
+ color: colors.fg,
}}
>
- <Blob cW={cW} color={theme.accent} x={-15} y={-10} size={55} opacity={inverted ? 0.25 : 0.32} />
- <Blob cW={cW} color={theme.accent} x={70} y={75} size={45} opacity={inverted ? 0.18 : 0.25} />
+ <SceneBackdrop
+ scene={scene}
+ theme={theme}
+ cW={cW}
+ cH={cH}
+ index={index}
+ count={count}
+ base={slide.backgroundColor || (inverted ? theme.bgAlt : theme.bg)}
+ fg={colors.fg}
+ accent={theme.accent}
+ dark={isDark(slide.backgroundColor || (inverted ? theme.bgAlt : theme.bg))}
+ inverted={inverted && !slide.backgroundColor}
+ blobsInverted={inverted}
+ />
</div>
);
}
+const isDark = (hex: string) => (relativeLuminance(hex) ?? 1) < 0.18;
+
function ScreenGuide({
cW,
cH,
@@ -957,6 +998,7 @@ function FeatureGraphicCanvas({
function SlideElements({
slide,
+ scene,
device,
orientation,
theme,
@@ -972,6 +1014,7 @@ function SlideElements({
allowCrossScreen,
}: {
slide: Slide;
+ scene: Scene;
device: Device;
orientation: Orientation;
theme: Theme;
@@ -994,6 +1037,9 @@ function SlideElements({
const captionRect = rectFor("caption", slide, defaults);
const deviceRect = rectFor("device", slide, defaults);
const secondaryRect = rectFor("deviceSecondary", slide, defaults);
+ const calloutRect = slide.callout && deviceRect && calloutAvailable(slide, device)
+ ? rectFor("callout", slide, defaults)
+ : undefined;
function toGlobal(rect: Rect): Rect {
return { ...rect, x: rect.x + screenX };
@@ -1017,8 +1063,9 @@ function SlideElements({
locale={locale}
editable={editable}
edit={edit}
- align={captionRect.align || "center"}
+ align={scene.captionAlign === "auto" ? captionRect.align || "center" : scene.captionAlign}
inverted={inverted}
+ scene={scene}
onFocus={() => edit?.onSelectElement?.("caption")}
/>
);
@@ -1080,10 +1127,49 @@ function SlideElements({
selected={selectedElementId === id}
onSelect={() => edit?.onSelectElement?.(id)}
>
- <Frame
- src={src}
+ <DeviceDepth scene={scene} cW={cW} accent={theme.accent}>
+ <Frame
+ src={src}
+ hideEmpty={hideEmpty}
+ style={{ width: "100%", height: "100%", ...extraStyle }}
+ />
+ </DeviceDepth>
+ </Movable>
+ );
+ }
+
+ function renderCallout(rect: Rect, deviceWidth: number) {
+ const callout = slide.callout!;
+ const saved = slide.transforms?.callout;
+ const rotation = saved?.rotation ?? 0;
+ const zIndex = saved?.zIndex ?? defaultElementZ("callout");
+ return (
+ <Movable
+ rect={toGlobal(rect)}
+ boundsW={boundsW}
+ boundsH={boundsH}
+ editable={editable}
+ previewScale={previewScale}
+ rotation={rotation}
+ onChange={(t) =>
+ edit?.onElementChange?.(
+ "callout",
+ toLocal({ ...t, rotation: t.rotation ?? rotation, zIndex: t.zIndex ?? zIndex }),
+ )
+ }
+ lockAspectRatio={callout.shape === "circle" ? 1 : undefined}
+ zIndex={zIndex}
+ allowOverflow
+ selected={selectedElementId === "callout"}
+ onSelect={() => edit?.onSelectElement?.("callout")}
+ >
+ <CalloutLoupe
+ callout={callout}
+ src={screenshot}
+ screenWidth={deviceWidth * SCREEN_WIDTH_FRACTION}
+ cW={cW}
+ accent={theme.accent}
hideEmpty={hideEmpty}
- style={{ width: "100%", height: "100%", ...extraStyle }}
/>
</Movable>
);
@@ -1201,6 +1287,7 @@ function SlideElements({
)}
{deviceRect && renderDevice("device", deviceRect, screenshot)}
{renderCaption()}
+ {calloutRect && deviceRect && renderCallout(calloutRect, deviceRect.width)}
{(slide.imageElements || []).map(renderImageElement)}
{(slide.textElements || []).map(renderTextElement)}
</>
diff --git a/skills/app-store-screenshots/template/src/components/editor/slide-thumb.tsx b/skills/app-store-screenshots/template/src/components/editor/slide-thumb.tsx
index c47f621..9316e6f 100644
--- a/skills/app-store-screenshots/template/src/components/editor/slide-thumb.tsx
+++ b/skills/app-store-screenshots/template/src/components/editor/slide-thumb.tsx
@@ -6,7 +6,7 @@ import { Copy, GripVertical, Trash2 } from "lucide-react";
import { Button } from "@/components/ui/button";
import { LAYOUT_LABEL } from "@/lib/constants";
import { pickText } from "@/lib/locale";
-import type { Device, Orientation, Slide, Theme } from "@/lib/types";
+import type { Device, Orientation, Scene, Slide, Theme } from "@/lib/types";
import { cn } from "@/lib/utils";
import { DeckCanvas, SlideCanvas, getCanvas } from "./slide-canvas";
@@ -23,6 +23,7 @@ type Props = {
appIcon?: string;
fontFamily?: string;
connectedCanvas: boolean;
+ scene?: Scene;
onSelect: () => void;
onDelete: () => void;
onDuplicate: () => void;
@@ -44,6 +45,7 @@ export function SlideThumb({
appIcon,
fontFamily,
connectedCanvas,
+ scene,
onSelect,
onDelete,
onDuplicate,
@@ -121,6 +123,9 @@ export function SlideThumb({
fontFamily={fontFamily}
connectedCanvas
editable={false}
+ scene={scene}
+ stripStart={start}
+ stripCount={slides.length}
/>
) : (
<SlideCanvas
@@ -133,6 +138,9 @@ export function SlideThumb({
appIcon={appIcon}
fontFamily={fontFamily}
editable={false}
+ scene={scene}
+ stripIndex={index}
+ stripCount={slides.length}
/>
)}
</div>
diff --git a/skills/app-store-screenshots/template/src/components/editor/style-lab.tsx b/skills/app-store-screenshots/template/src/components/editor/style-lab.tsx
new file mode 100644
index 0000000..c96dea7
--- /dev/null
+++ b/skills/app-store-screenshots/template/src/components/editor/style-lab.tsx
@@ -0,0 +1,469 @@
+"use client";
+import * as React from "react";
+import { createPortal } from "react-dom";
+import { Check, Dices, Download, FlaskConical, Lock, LockOpen, Shuffle, Star, Trash2 } from "lucide-react";
+import { toast } from "sonner";
+import { Button } from "@/components/ui/button";
+import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle } from "@/components/ui/dialog";
+import { DEVICE_LABEL, SCREENSHOT_FONTS, THEMES, themeById } from "@/lib/constants";
+import { renderSlide } from "@/lib/export-render";
+import { BACKDROPS, DECORATIONS } from "@/lib/scene";
+import {
+ LOCK_LABEL,
+ NO_LOCKS,
+ applyLook,
+ canRearrange,
+ currentLook,
+ directionName,
+ generateLook,
+ pickDirections,
+ savedLookId,
+ withLocks,
+ type LockKey,
+ type Locks,
+} from "@/lib/style-lab";
+import { cn } from "@/lib/utils";
+import type { Look, ProjectState } from "@/lib/types";
+import { DeckCanvas, getCanvas } from "./slide-canvas";
+
+type Slot = { direction: string; seed: number };
+
+const PREVIEW_MIN_H = 160;
+const PREVIEW_MAX_H = 440;
+// Card padding + border inside the scrolling list.
+const ROW_CHROME_W = 28;
+
+function slotsFor(round: number): Slot[] {
+ return pickDirections(round).map((direction, i) => ({ direction, seed: round * 16 + i + 1 }));
+}
+
+export function StyleLab({
+ open,
+ onOpenChange,
+ state,
+ onApply,
+ onSavedLooksChange,
+}: {
+ open: boolean;
+ onOpenChange: (open: boolean) => void;
+ state: ProjectState;
+ onApply: (next: ProjectState, look: Look) => void;
+ onSavedLooksChange: (looks: Look[]) => void;
+}) {
+ const [locks, setLocks] = React.useState<Locks>(NO_LOCKS);
+ const [round, setRound] = React.useState(0);
+ const [slots, setSlots] = React.useState<Slot[]>(() => slotsFor(0));
+ const [exporting, setExporting] = React.useState(false);
+ const boardRef = React.useRef<HTMLDivElement>(null);
+ const [listWidth, setListWidth] = React.useState(0);
+ const listObserver = React.useRef<ResizeObserver | null>(null);
+ // Callback ref: the list only exists while the dialog is open.
+ const listRef = React.useCallback((node: HTMLDivElement | null) => {
+ listObserver.current?.disconnect();
+ if (!node) return;
+ const observer = new ResizeObserver(([entry]) => setListWidth(entry.contentRect.width));
+ observer.observe(node);
+ listObserver.current = observer;
+ }, []);
+
+ const slides = state.slidesByDevice[state.device] || [];
+ const rearrange = canRearrange(state.device, state.orientation);
+ const saved = state.savedLooks || [];
+ const base = React.useMemo(() => currentLook(state), [state]);
+ const looks = React.useMemo(
+ () => slots.map((slot) => withLocks(generateLook(slot.direction, slot.seed), base, locks)),
+ [slots, base, locks],
+ );
+ // Size every deck preview so the whole strip fits the row without scrolling.
+ const { cW, cH } = getCanvas(state.device, state.orientation);
+ const previewH = Math.round(
+ Math.max(
+ PREVIEW_MIN_H,
+ Math.min(PREVIEW_MAX_H, (listWidth - ROW_CHROME_W) / (Math.max(1, slides.length) * (cW / cH))),
+ ),
+ ) || PREVIEW_MIN_H;
+ const allLocked = (Object.keys(locks) as LockKey[]).every((key) => locks[key] || (key === "layout" && !rearrange));
+
+ function shuffle() {
+ const next = round + 1;
+ setRound(next);
+ setSlots(slotsFor(next));
+ }
+
+ function remix(index: number) {
+ setSlots((prev) => prev.map((slot, i) => (i === index ? { ...slot, seed: slot.seed + 1009 } : slot)));
+ }
+
+ function apply(look: Look) {
+ onApply(applyLook(state, look, locks), look);
+ onOpenChange(false);
+ }
+
+ function toggleSaved(look: Look) {
+ const existing = saved.find((s) => s.id === look.id);
+ if (existing) {
+ onSavedLooksChange(saved.filter((s) => s.id !== look.id));
+ return;
+ }
+ onSavedLooksChange([...saved, { ...look, id: savedLookId(look, saved) }]);
+ toast.success("Look saved", { description: "Find it under Saved looks in Style Lab." });
+ }
+
+ async function exportComparison() {
+ if (exporting) return;
+ setExporting(true);
+ try {
+ // Let the board mount and lay out before capturing it.
+ await new Promise<void>((resolve) => requestAnimationFrame(() => requestAnimationFrame(() => resolve())));
+ await document.fonts?.ready;
+ const el = boardRef.current;
+ if (!el) throw new Error("Comparison board did not render");
+ const w = el.offsetWidth;
+ const h = el.offsetHeight;
+ const rendered = await renderSlide(el, w, h, "#F4F3EF");
+ const png = await rendered.toPng(w, h);
+ const url = URL.createObjectURL(new Blob([png as BlobPart], { type: "image/png" }));
+ const a = document.createElement("a");
+ a.href = url;
+ a.download = `${slug(state.appName)}-style-lab.png`;
+ a.click();
+ setTimeout(() => URL.revokeObjectURL(url), 5000);
+ toast.success("Comparison image exported");
+ } catch (error) {
+ toast.error("Couldn't export the comparison", {
+ description: error instanceof Error ? error.message : String(error),
+ });
+ } finally {
+ setExporting(false);
+ }
+ }
+
+ const rows: { key: string; title: string; look: Look; current?: boolean }[] = [
+ { key: "current", title: "Current", look: base, current: true },
+ ...looks.map((look, i) => ({ key: `slot-${i}`, title: look.name, look })),
+ ];
+
+ return (
+ <Dialog open={open} onOpenChange={(next) => !exporting && onOpenChange(next)}>
+ <DialogContent className="flex h-[92vh] max-w-[min(1240px,96vw)] flex-col gap-0 p-0">
+ <DialogHeader className="space-y-1 border-b px-5 pb-3 pt-4 text-left">
+ <DialogTitle className="flex items-center gap-2">
+ <FlaskConical className="h-4 w-4" /> Style Lab
+ </DialogTitle>
+ <DialogDescription>
+ Four complete looks for your {DEVICE_LABEL[state.device]} deck. Lock what you like, shuffle the rest, apply
+ one. Your screenshots and copy stay as they are.
+ </DialogDescription>
+ </DialogHeader>
+
+ <div className="flex flex-wrap items-center gap-2 border-b px-5 py-2.5">
+ <span className="text-xs font-medium text-muted-foreground">Keep</span>
+ {(Object.keys(LOCK_LABEL) as LockKey[]).map((key) => {
+ const unavailable = key === "layout" && !rearrange;
+ const on = locks[key] || unavailable;
+ return (
+ <Button
+ key={key}
+ type="button"
+ size="sm"
+ variant={on ? "secondary" : "outline"}
+ className="h-7 gap-1.5 px-2.5 text-xs"
+ aria-pressed={on}
+ disabled={unavailable}
+ title={unavailable ? "This device keeps its own layouts" : `${LOCK_LABEL[key].hint}. ${on ? "Kept from your deck." : "Varies between looks."}`}
+ onClick={() => setLocks((prev) => ({ ...prev, [key]: !prev[key] }))}
+ >
+ {on ? <Lock className="h-3 w-3" /> : <LockOpen className="h-3 w-3" />}
+ {LOCK_LABEL[key].name}
+ </Button>
+ );
+ })}
+ <div className="ml-auto flex items-center gap-2">
+ <Button
+ type="button"
+ size="sm"
+ variant="outline"
+ className="h-8 gap-1.5"
+ onClick={() => void exportComparison()}
+ disabled={exporting || slides.length === 0}
+ title="Download one image comparing your deck with these looks"
+ >
+ <Download className="h-3.5 w-3.5" />
+ {exporting ? "Exporting…" : "Export comparison"}
+ </Button>
+ <Button
+ type="button"
+ size="sm"
+ className="h-8 gap-1.5"
+ onClick={shuffle}
+ disabled={allLocked}
+ title={allLocked ? "Unlock something to shuffle it" : "Four new looks"}
+ >
+ <Shuffle className="h-3.5 w-3.5" />
+ Shuffle
+ </Button>
+ </div>
+ </div>
+
+ <div ref={listRef} className="min-h-0 flex-1 space-y-3 overflow-y-auto bg-muted/30 px-5 py-4" data-testid="style-lab-looks">
+ {slides.length === 0 ? (
+ <p className="py-16 text-center text-sm text-muted-foreground">Add a screen to try looks on it.</p>
+ ) : (
+ <>
+ {rows.map((row, i) => (
+ <LookRow
+ key={row.key}
+ title={row.title}
+ look={row.look}
+ project={row.current ? state : applyLook(state, row.look, locks)}
+ height={previewH}
+ current={row.current}
+ actions={
+ row.current ? (
+ <span className="text-[11px] text-muted-foreground">Your deck now</span>
+ ) : (
+ <>
+ <Button
+ type="button"
+ size="sm"
+ variant="ghost"
+ className="h-7 gap-1 px-2 text-xs"
+ onClick={() => remix(i - 1)}
+ aria-label={`Remix ${row.title}`}
+ title="Another take on this direction"
+ >
+ <Dices className="h-3.5 w-3.5" />
+ Remix
+ </Button>
+ <SaveButton saved={saved.some((s) => s.id === row.look.id)} onClick={() => toggleSaved(row.look)} name={row.title} />
+ <Button
+ type="button"
+ size="sm"
+ className="h-7 gap-1 px-2.5 text-xs"
+ onClick={() => apply(row.look)}
+ aria-label={`Apply ${row.title}`}
+ >
+ <Check className="h-3.5 w-3.5" />
+ Apply
+ </Button>
+ </>
+ )
+ }
+ />
+ ))}
+
+ {saved.length > 0 && (
+ <div className="space-y-3 pt-3">
+ <h3 className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">Saved looks</h3>
+ {saved.map((look) => (
+ <LookRow
+ key={`saved-${look.id}`}
+ title={look.name}
+ look={look}
+ project={applyLook(state, look, locks)}
+ height={previewH}
+ actions={
+ <>
+ <Button
+ type="button"
+ size="sm"
+ variant="ghost"
+ className="h-7 w-7 p-0 hover:text-destructive"
+ onClick={() => onSavedLooksChange(saved.filter((s) => s.id !== look.id))}
+ aria-label={`Remove saved look ${look.name}`}
+ title="Remove from saved looks"
+ >
+ <Trash2 className="h-3.5 w-3.5" />
+ </Button>
+ <Button
+ type="button"
+ size="sm"
+ className="h-7 gap-1 px-2.5 text-xs"
+ onClick={() => apply(look)}
+ aria-label={`Apply saved look ${look.name}`}
+ >
+ <Check className="h-3.5 w-3.5" />
+ Apply
+ </Button>
+ </>
+ }
+ />
+ ))}
+ </div>
+ )}
+ </>
+ )}
+ </div>
+ </DialogContent>
+ {exporting &&
+ createPortal(
+ <ComparisonBoard
+ ref={boardRef}
+ appName={state.appName}
+ rows={rows.map((row) => ({
+ title: row.current ? "Current" : row.title,
+ project: row.current ? state : applyLook(state, row.look, locks),
+ }))}
+ />,
+ document.body,
+ )}
+ </Dialog>
+ );
+}
+
+function SaveButton({ saved, onClick, name }: { saved: boolean; onClick: () => void; name: string }) {
+ return (
+ <Button
+ type="button"
+ size="sm"
+ variant="ghost"
+ className="h-7 gap-1 px-2 text-xs"
+ onClick={onClick}
+ aria-pressed={saved}
+ aria-label={`${saved ? "Unsave" : "Save"} ${name}`}
+ title={saved ? "Remove from saved looks" : "Keep this look for later"}
+ >
+ <Star className={cn("h-3.5 w-3.5", saved && "fill-amber-400 text-amber-500")} />
+ {saved ? "Saved" : "Save"}
+ </Button>
+ );
+}
+
+function describe(look: Look) {
+ const font = SCREENSHOT_FONTS[look.fontId]?.name.replace(" (default)", "") ?? look.fontId;
+ const backdrop = BACKDROPS.find((b) => b.id === look.scene.backdrop)?.name ?? look.scene.backdrop;
+ const decoration = DECORATIONS.find((d) => d.id === look.scene.decoration)?.name;
+ return [
+ THEMES[look.themeId]?.name,
+ font,
+ `${backdrop}${look.scene.span ? " (flowing)" : ""}`,
+ look.scene.decoration !== "none" ? decoration : null,
+ look.scene.tilt ? `${look.scene.tilt}° tilt` : null,
+ look.scene.headlineCase === "upper" ? "Uppercase" : null,
+ ].filter(Boolean).join(" · ");
+}
+
+function LookRow({
+ title,
+ look,
+ project,
+ height,
+ current,
+ actions,
+}: {
+ title: string;
+ look: Look;
+ project: ProjectState;
+ height: number;
+ current?: boolean;
+ actions: React.ReactNode;
+}) {
+ return (
+ <section
+ aria-label={title}
+ className={cn("rounded-lg border bg-card p-3 shadow-sm", current && "border-dashed bg-card/60")}
+ >
+ <div className="mb-2 flex flex-wrap items-center justify-between gap-2">
+ <div className="min-w-0">
+ <div className="flex items-center gap-2">
+ <h3 className="truncate text-sm font-semibold">{title}</h3>
+ {!current && look.direction && (
+ <span className="rounded-full bg-muted px-2 py-0.5 text-[10px] font-medium text-muted-foreground">
+ {directionName(look.direction)}
+ </span>
+ )}
+ </div>
+ <p className="truncate text-[11px] text-muted-foreground">{describe(look)}</p>
+ </div>
+ <div className="flex shrink-0 items-center gap-1">{actions}</div>
+ </div>
+ <div className="overflow-x-auto">
+ <DeckPreview project={project} height={height} />
+ </div>
+ </section>
+ );
+}
+
+function fontFamilyOf(project: ProjectState) {
+ return SCREENSHOT_FONTS[project.fontId || "template-default"].family;
+}
+
+/** A whole deck, scaled to `height`, exactly as the export would render it. */
+function DeckPreview({ project, height }: { project: ProjectState; height: number }) {
+ const slides = project.slidesByDevice[project.device] || [];
+ const { cW, cH } = getCanvas(project.device, project.orientation);
+ const scale = height / cH;
+ return (
+ <div
+ className="relative overflow-hidden rounded-md"
+ style={{ width: slides.length * cW * scale, height }}
+ aria-hidden
+ >
+ <div style={{ position: "absolute", left: 0, top: 0, transformOrigin: "top left", transform: `scale(${scale})` }}>
+ <DeckCanvas
+ slides={slides}
+ device={project.device}
+ orientation={project.orientation}
+ theme={themeById(project.themeId)}
+ locale={project.locale}
+ appName={project.appName}
+ appIcon={project.appIcon}
+ fontFamily={fontFamilyOf(project)}
+ connectedCanvas={project.connectedCanvas}
+ scene={project.scene}
+ hideEmpty
+ />
+ </div>
+ </div>
+ );
+}
+
+const BOARD_ROW_H = 520;
+const BOARD_PAD = 72;
+const BOARD_MAX_W = 12000;
+
+// Offscreen board captured for "Export comparison". Lives at the page origin
+// (behind the app) because html-to-image needs an untransformed node.
+const ComparisonBoard = React.forwardRef<
+ HTMLDivElement,
+ { appName: string; rows: { title: string; project: ProjectState }[] }
+>(function ComparisonBoard({ appName, rows }, ref) {
+ const first = rows[0].project;
+ const { cW, cH } = getCanvas(first.device, first.orientation);
+ const count = (first.slidesByDevice[first.device] || []).length;
+ // Stay well under Safari's canvas limit for long or landscape decks.
+ const rowH = Math.min(BOARD_ROW_H, Math.floor((BOARD_MAX_W - BOARD_PAD * 2) / Math.max(1, count) / (cW / cH)));
+ const stripW = Math.ceil(count * cW * (rowH / cH));
+ const width = Math.max(stripW, 960) + BOARD_PAD * 2;
+ return (
+ <div
+ ref={ref}
+ aria-hidden
+ style={{
+ position: "fixed",
+ left: 0,
+ top: 0,
+ zIndex: -1,
+ pointerEvents: "none",
+ width,
+ padding: BOARD_PAD,
+ background: "#F4F3EF",
+ color: "#141413",
+ fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif',
+ }}
+ >
+ <div style={{ fontSize: 22, letterSpacing: 2, textTransform: "uppercase", opacity: 0.55, fontWeight: 600 }}>Style Lab</div>
+ <div style={{ fontSize: 56, fontWeight: 700, marginTop: 6, marginBottom: 40 }}>{appName || "My App"}</div>
+ {rows.map((row) => (
+ <div key={row.title} style={{ marginBottom: 44 }}>
+ <div style={{ fontSize: 26, fontWeight: 600, marginBottom: 14 }}>{row.title}</div>
+ <DeckPreview project={row.project} height={rowH} />
+ </div>
+ ))}
+ </div>
+ );
+});
+
+function slug(s: string) {
+ return s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/(^-|-$)/g, "") || "screenshots";
+}
diff --git a/skills/app-store-screenshots/template/src/components/editor/toolbar.tsx b/skills/app-store-screenshots/template/src/components/editor/toolbar.tsx
index 74edfd1..ad8f54b 100644
--- a/skills/app-store-screenshots/template/src/components/editor/toolbar.tsx
+++ b/skills/app-store-screenshots/template/src/components/editor/toolbar.tsx
@@ -1,6 +1,6 @@
"use client";
import * as React from "react";
-import { AlertTriangle, Check, Cloud, Download, Redo2, RotateCcw, Undo2, UnfoldHorizontal, Upload } from "lucide-react";
+import { AlertTriangle, Check, Cloud, Download, FlaskConical, Redo2, RotateCcw, Undo2, UnfoldHorizontal, Upload } from "lucide-react";
import { Button } from "@/components/ui/button";
import {
Dialog,
@@ -29,8 +29,9 @@ import {
themeById,
} from "@/lib/constants";
import { detectPlatform } from "@/lib/defaults";
-import type { Device, ImportedFont, Orientation, Platform, ScreenshotFontId, Theme } from "@/lib/types";
+import type { Device, ImportedFont, Orientation, Platform, Scene, ScreenshotFontId, Theme } from "@/lib/types";
import { FontImporter, type FontImporterHandle } from "./font-importer";
+import { ScenePlayground } from "./scene-playground";
const IMPORT_FONT_ACTION = "__import-font__";
@@ -41,6 +42,9 @@ type Props = {
setThemeId: (v: string) => void;
connectedCanvas: boolean;
setConnectedCanvas: (v: boolean) => void;
+ scene: Scene | undefined;
+ setScene: (scene: Scene | undefined) => void;
+ onOpenStyleLab: () => void;
fontId: ScreenshotFontId;
setFontId: (v: ScreenshotFontId) => void;
importedFont?: ImportedFont;
@@ -130,6 +134,20 @@ export function Toolbar(props: Props) {
{props.connectedCanvas ? "Connected" : "Isolated"}
</Button>
+ <Button
+ type="button"
+ variant="outline"
+ size="sm"
+ className="h-8 gap-1.5 px-2 text-xs"
+ onClick={props.onOpenStyleLab}
+ disabled={props.busy}
+ title="Style Lab: try complete looks for this deck side by side"
+ >
+ <FlaskConical className="h-3.5 w-3.5" />
+ Style Lab
+ </Button>
+ <ScenePlayground scene={props.scene} theme={activeTheme} disabled={props.busy} onChange={props.setScene} />
+
<Select value={activeTheme.id} onValueChange={props.setThemeId} disabled={props.busy}>
<SelectTrigger className="h-8 w-40 text-xs" title="Theme" aria-label="Theme">
<SelectValue>
diff --git a/skills/app-store-screenshots/template/src/components/ui/popover.tsx b/skills/app-store-screenshots/template/src/components/ui/popover.tsx
new file mode 100644
index 0000000..9e0f8c8
--- /dev/null
+++ b/skills/app-store-screenshots/template/src/components/ui/popover.tsx
@@ -0,0 +1,28 @@
+"use client";
+import * as React from "react";
+import * as PopoverPrimitive from "@radix-ui/react-popover";
+import { cn } from "@/lib/utils";
+
+const Popover = PopoverPrimitive.Root;
+const PopoverTrigger = PopoverPrimitive.Trigger;
+
+const PopoverContent = React.forwardRef<
+ React.ElementRef<typeof PopoverPrimitive.Content>,
+ React.ComponentPropsWithoutRef<typeof PopoverPrimitive.Content>
+>(({ className, align = "start", sideOffset = 6, ...props }, ref) => (
+ <PopoverPrimitive.Portal>
+ <PopoverPrimitive.Content
+ ref={ref}
+ align={align}
+ sideOffset={sideOffset}
+ className={cn(
+ "z-50 rounded-lg border bg-popover p-3 text-popover-foreground shadow-lg outline-none data-[state=open]:animate-in data-[state=closed]:animate-out data-[state=closed]:fade-out-0 data-[state=open]:fade-in-0",
+ className,
+ )}
+ {...props}
+ />
+ </PopoverPrimitive.Portal>
+));
+PopoverContent.displayName = PopoverPrimitive.Content.displayName;
+
+export { Popover, PopoverTrigger, PopoverContent };
diff --git a/skills/app-store-screenshots/template/src/lib/elements.ts b/skills/app-store-screenshots/template/src/lib/elements.ts
index 4e71d15..7e752a4 100644
--- a/skills/app-store-screenshots/template/src/lib/elements.ts
+++ b/skills/app-store-screenshots/template/src/lib/elements.ts
@@ -4,6 +4,7 @@ export const BUILT_IN_ELEMENT_IDS: BuiltInElementId[] = [
"caption",
"device",
"deviceSecondary",
+ "callout",
];
export const TEXT_ELEMENT_PREFIX = "text:";
diff --git a/skills/app-store-screenshots/template/src/lib/project-validation.ts b/skills/app-store-screenshots/template/src/lib/project-validation.ts
index 30bb4a5..b69b091 100644
--- a/skills/app-store-screenshots/template/src/lib/project-validation.ts
+++ b/skills/app-store-screenshots/template/src/lib/project-validation.ts
@@ -28,6 +28,10 @@ export function projectValidationError(value: unknown): string | null {
if (value.locales !== undefined && (!Array.isArray(value.locales) ||
value.locales.some(locale => typeof locale !== "string" || !/^[a-zA-Z0-9]+(?:[-_][a-zA-Z0-9]+)*$/.test(locale)) ||
new Set(value.locales).size !== value.locales.length)) return "locales must be a list of unique locale codes";
+ if (value.scene !== undefined && !record(value.scene)) return "scene must be an object";
+ if (value.savedLooks !== undefined && (!Array.isArray(value.savedLooks) || value.savedLooks.some(look => !record(look)))) {
+ return "savedLooks must be a list of looks";
+ }
for (const [device, slides] of Object.entries(value.slidesByDevice)) {
if (!Object.hasOwn(DEVICE_LABEL, device)) return `Unknown deck device: ${device}`;
if (!Array.isArray(slides)) return `${device} deck must be an array`;
@@ -43,8 +47,11 @@ export function projectValidationError(value: unknown): string | null {
}
if (!localized(slide.label) || !localized(slide.headline)) return `${device}: copy must be text or a locale-to-text object`;
if (slide.inverted !== undefined && typeof slide.inverted !== "boolean") return `${device}: inverted must be a boolean`;
+ // Missing or out-of-range magnifier values are defaulted and clamped on load.
+ if (slide.callout !== undefined && (!record(slide.callout) ||
+ [slide.callout.focusX, slide.callout.focusY, slide.callout.zoom].some(n => n !== undefined && !finite(n)))) return `${device}: invalid callout`;
if (slide.transforms !== undefined && (!record(slide.transforms) || Object.entries(slide.transforms).some(([key, value]) =>
- !["caption", "device", "deviceSecondary"].includes(key) || !transform(value)))) return `${device}: invalid element transform`;
+ !["caption", "device", "deviceSecondary", "callout"].includes(key) || !transform(value)))) return `${device}: invalid element transform`;
for (const key of ["textElements", "imageElements"] as const) {
const elements = slide[key];
if (elements === undefined) continue;
diff --git a/skills/app-store-screenshots/template/src/lib/scene.ts b/skills/app-store-screenshots/template/src/lib/scene.ts
new file mode 100644
index 0000000..d5d964a
--- /dev/null
+++ b/skills/app-store-screenshots/template/src/lib/scene.ts
@@ -0,0 +1,114 @@
+import { SCREENSHOT_FONTS, THEMES } from "./constants";
+import type { Callout, Look, Scene, SceneBackdrop, SceneDecoration, ScreenshotFontId, SlideLayout } from "./types";
+
+// The classic look every deck had before scenes existed. A project without a
+// `scene` renders exactly like this, so older decks don't shift.
+export const DEFAULT_SCENE: Scene = {
+ backdrop: "gradient",
+ span: false,
+ decoration: "blobs",
+ shadow: 0,
+ glow: 0,
+ tilt: 0,
+ headlineWeight: 700,
+ headlineScale: 1,
+ headlineCase: "as-typed",
+ captionAlign: "auto",
+};
+
+export const BACKDROPS: { id: SceneBackdrop; name: string }[] = [
+ { id: "gradient", name: "Gradient" },
+ { id: "solid", name: "Solid" },
+ { id: "aurora", name: "Aurora" },
+ { id: "spotlight", name: "Spotlight" },
+ { id: "grid", name: "Grid" },
+ { id: "dots", name: "Dots" },
+ { id: "lines", name: "Ruled" },
+];
+
+export const DECORATIONS: { id: SceneDecoration; name: string }[] = [
+ { id: "blobs", name: "Blobs" },
+ { id: "rings", name: "Rings" },
+ { id: "sparkles", name: "Sparkles" },
+ { id: "none", name: "None" },
+];
+
+export const TILT_LIMIT = 30;
+export const CALLOUT_ZOOM_MIN = 1.5;
+export const CALLOUT_ZOOM_MAX = 5;
+export const DEFAULT_CALLOUT: Callout = { focusX: 0.5, focusY: 0.32, zoom: 2, shape: "circle" };
+
+const BACKDROP_IDS = new Set(BACKDROPS.map((b) => b.id));
+const DECORATION_IDS = new Set(DECORATIONS.map((d) => d.id));
+const LAYOUTS: ReadonlySet<SlideLayout> = new Set([
+ "hero", "device-bottom", "device-top", "two-devices", "no-device", "split-landscape", "feature-graphic",
+]);
+
+const record = (value: unknown): value is Record<string, unknown> =>
+ !!value && typeof value === "object" && !Array.isArray(value);
+
+function clampNumber(value: unknown, min: number, max: number, fallback: number) {
+ if (typeof value !== "number" || !Number.isFinite(value)) return fallback;
+ return Math.min(max, Math.max(min, value));
+}
+
+export function sceneOf(scene: Scene | undefined): Scene {
+ return scene ?? DEFAULT_SCENE;
+}
+
+/** Normalise a scene from disk or a script; unknown values fall back to the classic look. */
+export function cleanScene(value: unknown): Scene | undefined {
+ if (!record(value)) return undefined;
+ return {
+ backdrop: BACKDROP_IDS.has(value.backdrop as SceneBackdrop) ? (value.backdrop as SceneBackdrop) : DEFAULT_SCENE.backdrop,
+ span: value.span === true,
+ decoration: DECORATION_IDS.has(value.decoration as SceneDecoration)
+ ? (value.decoration as SceneDecoration)
+ : DEFAULT_SCENE.decoration,
+ shadow: Math.round(clampNumber(value.shadow, 0, 100, DEFAULT_SCENE.shadow)),
+ glow: Math.round(clampNumber(value.glow, 0, 100, DEFAULT_SCENE.glow)),
+ tilt: Math.round(clampNumber(value.tilt, -TILT_LIMIT, TILT_LIMIT, DEFAULT_SCENE.tilt)),
+ headlineWeight: Math.round(clampNumber(value.headlineWeight, 300, 900, DEFAULT_SCENE.headlineWeight) / 100) * 100,
+ headlineScale: Math.round(clampNumber(value.headlineScale, 0.5, 2, DEFAULT_SCENE.headlineScale) * 20) / 20,
+ headlineCase: value.headlineCase === "upper" ? "upper" : "as-typed",
+ captionAlign: value.captionAlign === "left" || value.captionAlign === "center" ? value.captionAlign : "auto",
+ };
+}
+
+export function cleanCallout(value: unknown): Callout | undefined {
+ if (!record(value)) return undefined;
+ return {
+ focusX: clampNumber(value.focusX, 0, 1, DEFAULT_CALLOUT.focusX),
+ focusY: clampNumber(value.focusY, 0, 1, DEFAULT_CALLOUT.focusY),
+ zoom: clampNumber(value.zoom, CALLOUT_ZOOM_MIN, CALLOUT_ZOOM_MAX, DEFAULT_CALLOUT.zoom),
+ shape: value.shape === "rounded" ? "rounded" : "circle",
+ };
+}
+
+export function cleanLook(value: unknown): Look | undefined {
+ if (!record(value) || typeof value.id !== "string" || !value.id.trim()) return undefined;
+ const scene = cleanScene(value.scene);
+ if (!scene) return undefined;
+ const layouts = Array.isArray(value.layouts)
+ ? value.layouts.filter((layout): layout is SlideLayout => LAYOUTS.has(layout as SlideLayout))
+ : [];
+ return {
+ id: value.id,
+ name: typeof value.name === "string" && value.name.trim() ? value.name : "Saved look",
+ direction: typeof value.direction === "string" ? value.direction : "",
+ themeId: typeof value.themeId === "string" && THEMES[value.themeId] ? value.themeId : "clean-light",
+ fontId:
+ typeof value.fontId === "string" && Object.hasOwn(SCREENSHOT_FONTS, value.fontId)
+ ? (value.fontId as ScreenshotFontId)
+ : "template-default",
+ scene,
+ layouts: layouts.length > 0 ? layouts : ["hero"],
+ inverted: Array.isArray(value.inverted) && value.inverted.length > 0
+ ? value.inverted.map((item) => item === true)
+ : [false],
+ };
+}
+
+export function sameScene(a: Scene, b: Scene) {
+ return (Object.keys(DEFAULT_SCENE) as (keyof Scene)[]).every((key) => a[key] === b[key]);
+}
diff --git a/skills/app-store-screenshots/template/src/lib/storage.ts b/skills/app-store-screenshots/template/src/lib/storage.ts
index d97988e..4bf7824 100644
--- a/skills/app-store-screenshots/template/src/lib/storage.ts
+++ b/skills/app-store-screenshots/template/src/lib/storage.ts
@@ -6,8 +6,9 @@ import { cleanImportedFont } from "./clean-imported-font";
import { DEFAULT_PROJECT } from "./defaults";
import { coerceLocalized } from "./locale";
import { projectValidationError } from "./project-validation";
+import { cleanCallout, cleanLook, cleanScene } from "./scene";
import { cleanTypography } from "./typography";
-import type { Device, ElementTransform, ImageElement, ProjectState, ScreenshotFontId, Slide, TextElement } from "./types";
+import type { Device, ElementTransform, ImageElement, Look, ProjectState, ScreenshotFontId, Slide, TextElement } from "./types";
const HISTORY_LIMIT = 50;
// Coalesce rapid edits (typing, slider drags) into a single undo step.
@@ -112,6 +113,7 @@ function migrateSlide(slide: Slide): Slide {
const imageElements = Array.isArray(slide.imageElements)
? slide.imageElements.map(cleanImageElement).filter((image): image is ImageElement => !!image)
: undefined;
+ const callout = cleanCallout(slide.callout);
return {
...slide,
@@ -122,6 +124,7 @@ function migrateSlide(slide: Slide): Slide {
...(transforms && Object.keys(transforms).length > 0 ? { transforms } : { transforms: undefined }),
...(textElements && textElements.length > 0 ? { textElements } : { textElements: undefined }),
...(imageElements && imageElements.length > 0 ? { imageElements } : { imageElements: undefined }),
+ ...(callout ? { callout } : { callout: undefined }),
};
}
@@ -137,6 +140,10 @@ function mergeWithDefaults(parsed: Partial<ProjectState>): ProjectState {
? parsed.themeId
: DEFAULT_PROJECT.themeId;
const importedFont = cleanImportedFont(parsed.importedFont);
+ const scene = cleanScene(parsed.scene);
+ const savedLooks = Array.isArray(parsed.savedLooks)
+ ? parsed.savedLooks.map(cleanLook).filter((look): look is Look => !!look)
+ : [];
const fontId = cleanFontId(parsed.fontId, !!importedFont);
const slidesByDevice = parsed.slidesByDevice
? Object.fromEntries(
@@ -162,6 +169,8 @@ function mergeWithDefaults(parsed: Partial<ProjectState>): ProjectState {
themeId,
fontId,
...(importedFont ? { importedFont } : { importedFont: undefined }),
+ ...(scene ? { scene } : { scene: undefined }),
+ ...(savedLooks.length > 0 ? { savedLooks } : { savedLooks: undefined }),
connectedCanvas,
slidesByDevice: {
...DEFAULT_PROJECT.slidesByDevice,
diff --git a/skills/app-store-screenshots/template/src/lib/style-lab.ts b/skills/app-store-screenshots/template/src/lib/style-lab.ts
new file mode 100644
index 0000000..54769cb
--- /dev/null
+++ b/skills/app-store-screenshots/template/src/lib/style-lab.ts
@@ -0,0 +1,337 @@
+// Style Lab: generates complete looks for a deck (palette, type, layout rhythm
+// and scene), keeps locked parts from the current deck, and applies a look as
+// one undoable edit. Generation is seeded, so the same seed always produces
+// the same four looks.
+import { SCREENSHOT_FONTS, THEMES, supportsLandscape } from "./constants";
+import { DEFAULT_SCENE, sameScene, sceneOf } from "./scene";
+import type { Device, Look, ProjectState, Scene, ScreenshotFontId, Slide, SlideLayout } from "./types";
+
+export type LockKey = "palette" | "type" | "layout" | "scene";
+export type Locks = Record<LockKey, boolean>;
+export const NO_LOCKS: Locks = { palette: false, type: false, layout: false, scene: false };
+
+export const LOCK_LABEL: Record<LockKey, { name: string; hint: string }> = {
+ palette: { name: "Colors", hint: "Theme and which screens are inverted" },
+ type: { name: "Type", hint: "Font, headline weight, case, alignment and size" },
+ layout: { name: "Layout", hint: "Device placement on each screen" },
+ scene: { name: "Scene", hint: "Backdrop, decoration, shadow, glow and tilt" },
+};
+
+type Rng = () => number;
+
+// mulberry32: tiny, fast and good enough for picking design options.
+function rng(seed: number): Rng {
+ let a = seed >>> 0;
+ return () => {
+ a = (a + 0x6d2b79f5) >>> 0;
+ let t = a;
+ t = Math.imul(t ^ (t >>> 15), t | 1);
+ t ^= t + Math.imul(t ^ (t >>> 7), t | 61);
+ return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+ };
+}
+
+const pick = <T>(r: Rng, items: readonly T[]): T => items[Math.floor(r() * items.length) % items.length];
+const between = (r: Rng, min: number, max: number) => Math.round(min + r() * (max - min));
+const signed = (r: Rng, min: number, max: number) => (r() < 0.5 ? -1 : 1) * between(r, min, max);
+
+type Direction = {
+ id: string;
+ name: string;
+ themes: string[];
+ fonts: ScreenshotFontId[];
+ layouts: SlideLayout[][];
+ inverted: boolean[][];
+ headlineScale: [number, number];
+ scene: (r: Rng) => Omit<Scene, "headlineScale">;
+};
+
+export const DIRECTIONS: Direction[] = [
+ {
+ id: "editorial",
+ name: "Editorial",
+ themes: ["warm-editorial", "magazine-cover-editorial", "bloom-roast", "quiet-japandi", "hand-drawn-editorial-tasks"],
+ fonts: ["baskerville", "palatino", "template-serif"],
+ layouts: [["device-bottom", "hero"], ["hero", "device-bottom", "device-top"]],
+ inverted: [[false, false, true], [false]],
+ headlineScale: [0.95, 1.1],
+ scene: (r) => ({
+ backdrop: pick(r, ["lines", "solid", "gradient"] as const),
+ span: false,
+ decoration: pick(r, ["none", "rings"] as const),
+ shadow: between(r, 25, 45),
+ glow: 0,
+ tilt: 0,
+ headlineWeight: pick(r, [500, 600]),
+ headlineCase: "as-typed",
+ captionAlign: "left",
+ }),
+ },
+ {
+ id: "playful",
+ name: "Playful",
+ themes: ["candy-pop-social", "toybox-primary", "paper-sticker-skeuomorphic", "retro-rubberhose-mascot", "dreamy-pastel-couples"],
+ fonts: ["futura", "avenir-next", "template-default"],
+ layouts: [["hero", "two-devices", "device-top"], ["device-bottom", "device-top"]],
+ inverted: [[false], [false, true]],
+ headlineScale: [1.05, 1.2],
+ scene: (r) => ({
+ backdrop: pick(r, ["dots", "gradient", "aurora"] as const),
+ span: r() < 0.5,
+ decoration: pick(r, ["sparkles", "blobs"] as const),
+ shadow: between(r, 40, 60),
+ glow: between(r, 10, 30),
+ tilt: signed(r, 8, 16),
+ headlineWeight: pick(r, [800, 900]),
+ headlineCase: "as-typed",
+ captionAlign: "center",
+ }),
+ },
+ {
+ id: "cinematic",
+ name: "Cinematic",
+ themes: ["midnight-glow-pro", "neon-athletic-night", "dark-bold", "moody-curated-dating", "glossy-3d-kbeauty-creator"],
+ fonts: ["helvetica-neue", "system-sans", "avenir-next"],
+ layouts: [["hero"], ["hero", "device-bottom"]],
+ inverted: [[false]],
+ headlineScale: [0.9, 1],
+ scene: (r) => ({
+ backdrop: pick(r, ["spotlight", "aurora"] as const),
+ span: r() < 0.4,
+ decoration: pick(r, ["none", "rings"] as const),
+ shadow: between(r, 60, 85),
+ glow: between(r, 45, 80),
+ tilt: r() < 0.35 ? 0 : signed(r, 8, 18),
+ headlineWeight: pick(r, [700, 800]),
+ headlineCase: pick(r, ["upper", "as-typed"] as const),
+ captionAlign: "center",
+ }),
+ },
+ {
+ id: "minimal",
+ name: "Minimal",
+ themes: ["clean-light", "quiet-japandi", "swiss-grid-bold", "ocean-fresh", "bento-keynote-grid"],
+ fonts: ["helvetica-neue", "system-sans", "optima", "template-default"],
+ layouts: [["device-bottom"], ["device-bottom", "device-top"]],
+ inverted: [[false]],
+ headlineScale: [0.9, 1],
+ scene: (r) => ({
+ backdrop: pick(r, ["solid", "grid"] as const),
+ span: false,
+ decoration: "none",
+ shadow: between(r, 15, 30),
+ glow: 0,
+ tilt: 0,
+ headlineWeight: pick(r, [600, 700]),
+ headlineCase: "as-typed",
+ captionAlign: pick(r, ["center", "left"] as const),
+ }),
+ },
+ {
+ id: "dreamy",
+ name: "Dreamy",
+ themes: ["dreamy-pastel-couples", "liquid-glass-aurora", "soft-clay-wellness", "ocean-fresh"],
+ fonts: ["avenir-next", "optima", "palatino"],
+ layouts: [["hero", "device-top"], ["hero"]],
+ inverted: [[false]],
+ headlineScale: [1, 1.1],
+ scene: (r) => ({
+ backdrop: "aurora",
+ span: true,
+ decoration: pick(r, ["blobs", "sparkles"] as const),
+ shadow: between(r, 30, 50),
+ glow: between(r, 30, 60),
+ tilt: signed(r, 6, 12),
+ headlineWeight: pick(r, [600, 700]),
+ headlineCase: "as-typed",
+ captionAlign: "center",
+ }),
+ },
+ {
+ id: "swiss",
+ name: "Swiss Bold",
+ themes: ["swiss-grid-bold", "bento-keynote-grid", "risograph-zine", "neon-athletic-night"],
+ fonts: ["helvetica-neue", "futura"],
+ layouts: [["device-bottom", "device-top"]],
+ inverted: [[false, true], [false, false, true]],
+ headlineScale: [0.85, 0.95],
+ scene: (r) => ({
+ backdrop: "grid",
+ span: r() < 0.5,
+ decoration: pick(r, ["none", "rings"] as const),
+ shadow: between(r, 30, 50),
+ glow: 0,
+ tilt: r() < 0.5 ? 0 : signed(r, 8, 12),
+ headlineWeight: 900,
+ headlineCase: "upper",
+ captionAlign: "left",
+ }),
+ },
+ {
+ id: "poster",
+ name: "Vintage Poster",
+ themes: ["vintage-travel-poster", "risograph-zine", "hand-drawn-editorial-tasks", "warm-editorial"],
+ fonts: ["american-typewriter", "futura", "baskerville"],
+ layouts: [["hero", "device-top"]],
+ inverted: [[false, false, true]],
+ headlineScale: [0.9, 1.05],
+ scene: (r) => ({
+ backdrop: pick(r, ["lines", "dots"] as const),
+ span: false,
+ decoration: pick(r, ["rings", "sparkles"] as const),
+ shadow: between(r, 35, 55),
+ glow: 0,
+ tilt: r() < 0.5 ? 0 : signed(r, 4, 8),
+ headlineWeight: pick(r, [700, 800]),
+ headlineCase: "upper",
+ captionAlign: "center",
+ }),
+ },
+ {
+ id: "panorama",
+ name: "Panorama",
+ themes: ["ocean-fresh", "liquid-glass-aurora", "midnight-glow-pro", "candy-pop-social", "bloom-roast"],
+ fonts: ["system-sans", "avenir-next", "template-default"],
+ layouts: [["hero", "device-bottom"], ["device-bottom", "hero", "device-top"]],
+ inverted: [[false]],
+ headlineScale: [1, 1.1],
+ scene: (r) => ({
+ backdrop: pick(r, ["aurora", "gradient"] as const),
+ span: true,
+ decoration: pick(r, ["blobs", "rings"] as const),
+ shadow: between(r, 40, 60),
+ glow: between(r, 15, 40),
+ tilt: signed(r, 10, 20),
+ headlineWeight: pick(r, [700, 800]),
+ headlineCase: "as-typed",
+ captionAlign: "center",
+ }),
+ },
+];
+
+/** The four directions a fresh Style Lab opens with: clearly different from each other. */
+export const STARTER_DIRECTIONS = ["editorial", "playful", "cinematic", "minimal"];
+
+export function directionName(id: string) {
+ return DIRECTIONS.find((d) => d.id === id)?.name ?? "Custom";
+}
+
+/** One look from a direction, fully determined by the seed. */
+export function generateLook(directionId: string, seed: number): Look {
+ const direction = DIRECTIONS.find((d) => d.id === directionId) ?? DIRECTIONS[0];
+ const r = rng(seed * 7919 + direction.id.length * 104729);
+ const themeId = pick(r, direction.themes.filter((id) => !!THEMES[id]));
+ const [lo, hi] = direction.headlineScale;
+ return {
+ id: `${direction.id}-${seed}`,
+ name: `${direction.name} · ${THEMES[themeId]?.name ?? themeId}`,
+ direction: direction.id,
+ themeId,
+ fontId: pick(r, direction.fonts.filter((id) => Object.hasOwn(SCREENSHOT_FONTS, id))),
+ scene: { ...direction.scene(r), headlineScale: Math.round((lo + r() * (hi - lo)) * 20) / 20 },
+ layouts: pick(r, direction.layouts),
+ inverted: pick(r, direction.inverted),
+ };
+}
+
+/** `count` different directions for one shuffle, starting with the starter set. */
+export function pickDirections(seed: number, count = 4): string[] {
+ if (seed === 0) return STARTER_DIRECTIONS.slice(0, count);
+ const r = rng(seed * 31 + 7);
+ const pool = DIRECTIONS.map((d) => d.id);
+ for (let i = pool.length - 1; i > 0; i--) {
+ const j = Math.floor(r() * (i + 1));
+ [pool[i], pool[j]] = [pool[j], pool[i]];
+ }
+ return pool.slice(0, count);
+}
+
+/** The deck as it is now, expressed as a look. */
+export function currentLook(state: ProjectState): Look {
+ const slides = state.slidesByDevice[state.device] || [];
+ return {
+ id: "current",
+ name: "Current",
+ direction: "current",
+ themeId: state.themeId,
+ fontId: state.fontId ?? "template-default",
+ scene: sceneOf(state.scene),
+ layouts: slides.length ? slides.map((s) => s.layout) : ["hero"],
+ inverted: slides.length ? slides.map((s) => !!s.inverted) : [false],
+ };
+}
+
+const TYPE_SCENE_KEYS = ["headlineWeight", "headlineScale", "headlineCase", "captionAlign"] as const;
+
+/** Replace every locked part of `look` with the same part of `base`. */
+export function withLocks(look: Look, base: Look, locks: Locks): Look {
+ const scene: Scene = { ...look.scene };
+ if (locks.scene) {
+ for (const key of Object.keys(DEFAULT_SCENE) as (keyof Scene)[]) {
+ if (!(TYPE_SCENE_KEYS as readonly string[]).includes(key)) (scene as Record<string, unknown>)[key] = base.scene[key];
+ }
+ }
+ if (locks.type) for (const key of TYPE_SCENE_KEYS) (scene as Record<string, unknown>)[key] = base.scene[key];
+ return {
+ ...look,
+ themeId: locks.palette ? base.themeId : look.themeId,
+ inverted: locks.palette ? base.inverted : look.inverted,
+ fontId: locks.type ? base.fontId : look.fontId,
+ layouts: locks.layout ? base.layouts : look.layouts,
+ scene,
+ };
+}
+
+// Phones and portrait tablets have the full set of portrait layouts. Landscape
+// canvases, watches and the Play banner keep their own layouts.
+export function canRearrange(device: Device, orientation: ProjectState["orientation"]) {
+ if (device === "iphone" || device === "android" || device === "ipad") return true;
+ if (device === "android-7" || device === "android-10") return orientation === "portrait" || !supportsLandscape(device);
+ return false;
+}
+
+function restyleSlide(slide: Slide, index: number, look: Look, locks: Locks, rearrange: boolean): Slide {
+ let next: Slide = { ...slide };
+ if (!locks.palette) {
+ next.inverted = look.inverted[index % look.inverted.length] || undefined;
+ next.backgroundColor = undefined;
+ }
+ if (!locks.layout && rearrange && slide.layout !== "no-device" && slide.layout !== "feature-graphic") {
+ let layout = look.layouts[index % look.layouts.length];
+ // A back device without its own screenshot would just repeat the front one.
+ if (layout === "two-devices" && !slide.screenshotSecondary) layout = "hero";
+ if (layout === "no-device" || layout === "feature-graphic" || layout === "split-landscape") layout = slide.layout;
+ // Fresh layout = fresh default placement, so the look reads as designed.
+ const { caption: _c, device: _d, deviceSecondary: _s, callout: _m, ...kept } = slide.transforms || {};
+ next = { ...next, layout, transforms: Object.keys(kept).length ? kept : undefined };
+ }
+ return next;
+}
+
+/** The project with `look` applied to the open deck. Locked parts stay as they are. */
+export function applyLook(state: ProjectState, look: Look, locks: Locks = NO_LOCKS): ProjectState {
+ const slides = state.slidesByDevice[state.device] || [];
+ const rearrange = canRearrange(state.device, state.orientation);
+ const base = currentLook(state);
+ const merged = withLocks(look, base, locks);
+ // An imported font only exists on the machine that imported it.
+ const fontId = merged.fontId === "self-hosted" && !state.importedFont ? state.fontId : merged.fontId;
+ const scene = merged.scene;
+ return {
+ ...state,
+ themeId: merged.themeId,
+ fontId,
+ scene: sameScene(scene, DEFAULT_SCENE) ? undefined : scene,
+ slidesByDevice: {
+ ...state.slidesByDevice,
+ [state.device]: slides.map((slide, i) => restyleSlide(slide, i, merged, locks, rearrange)),
+ },
+ };
+}
+
+/** Look id unique within the saved list. */
+export function savedLookId(look: Look, saved: Look[]) {
+ let id = look.id === "current" ? `look-${Date.now().toString(36)}` : look.id;
+ while (saved.some((s) => s.id === id)) id = `${id}-${Math.floor(Math.random() * 1e4)}`;
+ return id;
+}
diff --git a/skills/app-store-screenshots/template/src/lib/types.ts b/skills/app-store-screenshots/template/src/lib/types.ts
index 6df454c..63102db 100644
--- a/skills/app-store-screenshots/template/src/lib/types.ts
+++ b/skills/app-store-screenshots/template/src/lib/types.ts
@@ -34,7 +34,7 @@ export type ElementTransform = {
zIndex?: number;
};
-export type BuiltInElementId = "caption" | "device" | "deviceSecondary";
+export type BuiltInElementId = "caption" | "device" | "deviceSecondary" | "callout";
export type TextElementId = `text:${string}`;
export type ImageElementId = `image:${string}`;
export type ElementId = BuiltInElementId | TextElementId | ImageElementId;
@@ -80,6 +80,16 @@ export type ImageElement = {
};
};
+/** Magnified loupe of the primary screenshot, placed by transforms.callout. */
+export type Callout = {
+ /** Point of the screenshot to magnify, as 0–1 fractions of its width/height. */
+ focusX: number;
+ focusY: number;
+ /** Magnification relative to the callout's own width (1.5–5). */
+ zoom: number;
+ shape: "circle" | "rounded";
+};
+
export type Slide = {
id: string;
layout: SlideLayout;
@@ -95,6 +105,7 @@ export type Slide = {
transforms?: Partial<Record<BuiltInElementId, ElementTransform>>;
textElements?: TextElement[];
imageElements?: ImageElement[];
+ callout?: Callout;
};
export type ThemeId =
@@ -155,6 +166,45 @@ export type Theme = {
muted: string;
};
+// ---------- Scene (deck-wide composition, see lib/scene.ts) ----------
+
+export type SceneBackdrop = "gradient" | "solid" | "aurora" | "spotlight" | "grid" | "dots" | "lines";
+export type SceneDecoration = "blobs" | "rings" | "sparkles" | "none";
+
+export type Scene = {
+ backdrop: SceneBackdrop;
+ /** Lay the backdrop art out across the whole strip so it flows between screens. */
+ span: boolean;
+ decoration: SceneDecoration;
+ /** Device drop shadow strength, 0–100. */
+ shadow: number;
+ /** Accent-coloured light behind each device, 0–100. */
+ glow: number;
+ /** 3D turn of every device in degrees, -30–30. */
+ tilt: number;
+ /** Headline weight, 300–900. */
+ headlineWeight: number;
+ /** Deck-wide multiplier on every headline's size (0.5–2), on top of per-screen sizes. */
+ headlineScale: number;
+ headlineCase: "as-typed" | "upper";
+ /** "auto" keeps each layout's own alignment. */
+ captionAlign: "auto" | "left" | "center";
+};
+
+/** A complete look saved from Style Lab: palette, type, layout rhythm and scene. */
+export type Look = {
+ id: string;
+ name: string;
+ direction: string;
+ themeId: string;
+ fontId: ScreenshotFontId;
+ scene: Scene;
+ /** Layouts applied in order, repeating across the deck. */
+ layouts: SlideLayout[];
+ /** Screens (by position, repeating) that use the inverted background. */
+ inverted: boolean[];
+};
+
export type ProjectState = {
schemaVersion?: number;
appName: string;
@@ -172,4 +222,8 @@ export type ProjectState = {
// Per-device slide decks so platform switching preserves work
slidesByDevice: Record<Device, Slide[]>;
appIcon?: string; // path under /public (e.g. /app-icon.png)
+ /** Deck-wide composition. Absent = the classic gradient + blobs look. */
+ scene?: Scene;
+ /** Looks starred in Style Lab. */
+ savedLooks?: Look[];
};
diff --git a/skills/app-store-screenshots/template/tests/harness/migration-fixture.cjs b/skills/app-store-screenshots/template/tests/harness/migration-fixture.cjs
index 8747bdb..8a3601c 100644
--- a/skills/app-store-screenshots/template/tests/harness/migration-fixture.cjs
+++ b/skills/app-store-screenshots/template/tests/harness/migration-fixture.cjs
@@ -84,7 +84,7 @@ function migrateSlide(slide, used) {
const rawTransforms = slide.transforms && typeof slide.transforms === "object" ? slide.transforms : {};
for (const [id, transform] of Object.entries(rawTransforms)) {
const cleaned = cleanTransform(transform);
- if (["caption", "device", "deviceSecondary"].includes(id) && cleaned) transforms[id] = cleaned;
+ if (["caption", "device", "deviceSecondary", "callout"].includes(id) && cleaned) transforms[id] = cleaned;
}
const textIds = new Set();
const textElements = Array.isArray(slide.textElements)
@@ -126,6 +126,8 @@ function migrateSlide(slide, used) {
...(Object.keys(transforms).length ? { transforms } : { transforms: undefined }),
...(textElements && textElements.length ? { textElements } : { textElements: undefined }),
...(imageElements && imageElements.length ? { imageElements } : { imageElements: undefined }),
+ // The editor clamps magnifier values on load; only a non-object would be rejected.
+ callout: slide.callout && typeof slide.callout === "object" && !Array.isArray(slide.callout) ? slide.callout : undefined,
};
}
diff --git a/skills/app-store-screenshots/template/tests/scene-style-lab.e2e.ts b/skills/app-store-screenshots/template/tests/scene-style-lab.e2e.ts
new file mode 100644
index 0000000..2ea0ea2
--- /dev/null
+++ b/skills/app-store-screenshots/template/tests/scene-style-lab.e2e.ts
@@ -0,0 +1,253 @@
+import { test } from '@e2e-dev/web';
+import type { Browser } from '@e2e-dev/web';
+import { expect } from 'e2e';
+import { readFile, readdir, stat } from 'node:fs/promises';
+import JSZip from 'jszip';
+import sharp from 'sharp';
+
+type State = Record<string, any>;
+const screen = (id: string, layout = 'device-bottom') => ({ id, layout, screenshot: '', label: { en: 'FEATURE' }, headline: { en: id } });
+const deck = (extra: State = {}): State => ({
+ schemaVersion: 2, appName: 'Scene Army', themeId: 'clean-light', connectedCanvas: true, locales: ['en'], locale: 'en',
+ device: 'iphone', orientation: 'portrait', slidesByDevice: { iphone: [screen('One', 'hero'), screen('Two'), screen('Three')] }, ...extra,
+});
+
+// Serves the project from memory and exposes the latest saved state.
+async function mock(browser: Browser, initial = deck()) {
+ const store = { state: initial };
+ await browser.route('**/api/project', async route => {
+ if (route.request.method === 'POST') store.state = JSON.parse(route.request.postData!);
+ await route.fulfill({ json: { ok: true, state: store.state }, headers: { etag: '"mock"' } });
+ });
+ return store;
+}
+
+// Autosave is debounced; retry an assertion on the saved state until it holds.
+async function eventually(check: () => unknown | Promise<unknown>, timeout = 10_000) {
+ const deadline = Date.now() + timeout;
+ for (;;) {
+ try { await check(); return; } catch (error) {
+ if (Date.now() > deadline) throw error;
+ await new Promise(resolve => setTimeout(resolve, 200));
+ }
+ }
+}
+
+// Downloads in the same minute share a name across tests; take the newest.
+async function zipFrom(path: string) {
+ const matches = (await readdir('.e2e/artifacts', { recursive: true })).filter(file => file.endsWith(path));
+ await expect(matches.length).toBeGreaterThan(0);
+ const dated = await Promise.all(matches.map(async file => ({ file, at: (await stat(`.e2e/artifacts/${file}`)).mtimeMs })));
+ dated.sort((a, b) => b.at - a.at);
+ return readFile(`.e2e/artifacts/${dated[0].file}`);
+}
+
+test('scene playground restyles every screen, persists and undoes', async ({ app, browser, screen: ui }) => {
+ const store = await mock(browser); await app.open('/');
+ await ui.getByRole('button', 'Scene', { exact: true }).tap();
+ await ui.getByRole('radio', 'Grid', { exact: true }).tap();
+ await ui.getByRole('checkbox', /Flow across screens/).check();
+ await ui.getByRole('radio', 'Rings', { exact: true }).tap();
+ await ui.getByRole('slider', 'Tilt', { exact: true }).fill('12');
+ await ui.getByRole('radio', 'UPPER', { exact: true }).tap();
+ await expect(ui.getByRole('radio', 'Grid', { exact: true })).toHaveAttribute('aria-checked', 'true');
+ await eventually(async () => {
+ await expect(store.state.scene).toMatchObject({ backdrop: 'grid', span: true, decoration: 'rings', tilt: 12, headlineCase: 'upper' });
+ });
+ // Every screen in the main canvas renders the scene's backdrop art.
+ await expect(browser.locator('main [data-scene-art="grid"]')).toHaveCount(3);
+ await browser.keyboard.press('Escape');
+ // Rapid scene tweaks are one undo step, like slider drags elsewhere.
+ await browser.locator('button[aria-label="Undo"]').first().tap();
+ await eventually(() => expect(store.state.scene).toBeUndefined());
+ await browser.locator('button[aria-label="Redo"]').tap();
+ await eventually(() => expect(store.state.scene?.headlineCase).toBe('upper'));
+ await ui.getByRole('button', 'Scene', { exact: true }).tap();
+ await ui.getByRole('button', 'Reset scene', { exact: true }).tap();
+ await eventually(async () => {
+ await expect(store.state.scene).toBeUndefined();
+ });
+ await expect(browser.locator('main [data-scene-art="gradient"]')).toHaveCount(3);
+});
+
+test('style lab shows four looks and applies one as a single undo step', async ({ app, browser, screen: ui }) => {
+ const store = await mock(browser); await app.open('/');
+ await ui.getByRole('button', 'Style Lab', { exact: true }).tap();
+ const looks = browser.locator('[data-testid="style-lab-looks"] > section');
+ await expect(looks).toHaveCount(5);
+ await expect(looks.nth(0)).toContainText('Current');
+ await expect(ui.getByRole('button', /^Apply /)).toHaveCount(4);
+ await ui.getByRole('button', /^Apply Editorial/).tap();
+ await expect(ui.getByText(/^Applied Editorial/)).toBeVisible();
+ await eventually(async () => {
+ await expect(store.state.themeId).not.toBe('clean-light');
+ await expect(store.state.scene.captionAlign).toBe('left');
+ await expect(store.state.slidesByDevice.iphone.map((s: State) => s.headline.en)).toEqual(['One', 'Two', 'Three']);
+ });
+ await browser.locator('button[title^="Undo ("]').tap();
+ await eventually(async () => {
+ await expect(store.state.themeId).toBe('clean-light');
+ await expect(store.state.scene).toBeUndefined();
+ await expect(store.state.slidesByDevice.iphone.map((s: State) => s.layout)).toEqual(['hero', 'device-bottom', 'device-bottom']);
+ });
+});
+
+test('style lab locks keep colors and layout while shuffling the rest', async ({ app, browser, screen: ui }) => {
+ const store = await mock(browser, deck({ themeId: 'ocean-fresh' })); await app.open('/');
+ await ui.getByRole('button', 'Style Lab', { exact: true }).tap();
+ await ui.getByRole('button', 'Colors', { exact: true }).tap();
+ await ui.getByRole('button', 'Layout', { exact: true }).tap();
+ await expect(ui.getByRole('button', 'Colors', { exact: true })).toHaveAttribute('aria-pressed', 'true');
+ await ui.getByRole('button', 'Shuffle', { exact: true }).tap();
+ // Every look now reports the locked palette.
+ const rows = browser.locator('[data-testid="style-lab-looks"] > section');
+ for (let i = 1; i < 5; i++) await expect(rows.nth(i)).toContainText('Ocean Fresh ·');
+ await ui.getByRole('button', /^Apply /).first().tap();
+ await eventually(async () => {
+ await expect(store.state.themeId).toBe('ocean-fresh');
+ await expect(store.state.slidesByDevice.iphone.map((s: State) => s.layout)).toEqual(['hero', 'device-bottom', 'device-bottom']);
+ });
+ // Locking everything leaves nothing to shuffle.
+ await ui.getByRole('button', 'Style Lab', { exact: true }).tap();
+ await ui.getByRole('button', 'Type', { exact: true }).tap();
+ await ui.getByRole('button', 'Scene', { exact: true }).last().tap();
+ await expect(ui.getByRole('button', 'Shuffle', { exact: true })).toBeDisabled();
+});
+
+test('saved looks persist across reloads and can be applied or removed', async ({ app, browser, screen: ui }) => {
+ const store = await mock(browser); await app.open('/');
+ await ui.getByRole('button', 'Style Lab', { exact: true }).tap();
+ await ui.getByRole('button', /^Save Playful/).tap();
+ await expect(ui.getByRole('button', /^Unsave Playful/)).toHaveAttribute('aria-pressed', 'true');
+ await eventually(async () => {
+ await expect(store.state.savedLooks).toHaveLength(1);
+ });
+ await browser.reload();
+ await ui.getByRole('button', 'Style Lab', { exact: true }).tap();
+ await expect(ui.getByText('Saved looks', { exact: true })).toBeVisible();
+ await ui.getByRole('button', /^Apply saved look Playful/).tap();
+ await eventually(async () => {
+ await expect(store.state.scene.headlineWeight).toBeGreaterThanOrEqual(800);
+ });
+ await ui.getByRole('button', 'Style Lab', { exact: true }).tap();
+ await ui.getByRole('button', /^Remove saved look Playful/).tap();
+ await eventually(async () => {
+ await expect(store.state.savedLooks).toBeUndefined();
+ });
+});
+
+test('style lab exports a comparison image of every look', async ({ app, browser, screen: ui }) => {
+ await mock(browser); await app.open('/');
+ await ui.getByRole('button', 'Style Lab', { exact: true }).tap();
+ const download = await browser.waitForDownload(() => ui.getByRole('button', 'Export comparison', { exact: true }).tap(), { timeout: 120_000 });
+ await expect(download.path.endsWith('scene-army-style-lab.png')).toBe(true);
+ const bytes = await zipFrom(download.path);
+ const meta = await sharp(bytes).metadata();
+ await expect(meta.format).toBe('png');
+ await expect(meta.width!).toBeGreaterThan(900);
+ await expect(meta.height!).toBeGreaterThan(meta.width!);
+ await expect(ui.getByText('Comparison image exported', { exact: true })).toBeVisible();
+});
+
+test('magnifier can be added, aimed, zoomed and removed', async ({ app, browser, screen: ui }) => {
+ const store = await mock(browser); await app.open('/');
+ await ui.getByRole('button', 'Add', { exact: true }).tap();
+ const focus = ui.getByRole('slider', 'Magnifier focus', { exact: true });
+ await expect(focus).toBeVisible();
+ await focus.tap();
+ await browser.keyboard.press('ArrowRight');
+ await ui.getByRole('slider', 'Magnifier zoom', { exact: true }).fill('3.5');
+ await ui.getByRole('radio', 'Rounded', { exact: true }).tap();
+ await eventually(async () => {
+ const callout = store.state.slidesByDevice.iphone[0].callout;
+ await expect(callout).toMatchObject({ zoom: 3.5, shape: 'rounded' });
+ await expect(callout.focusX).toBeGreaterThan(0.5);
+ });
+ await ui.getByRole('button', 'Remove magnifier', { exact: true }).tap();
+ await eventually(async () => {
+ await expect(store.state.slidesByDevice.iphone[0].callout).toBeUndefined();
+ });
+ await expect(ui.getByRole('slider', 'Magnifier focus', { exact: true })).toHaveCount(0);
+});
+
+test('scene and magnifier export into the ZIP at exact sizes', async ({ app, browser, screen: ui }) => {
+ const scene = { backdrop: 'spotlight', span: true, decoration: 'sparkles', shadow: 70, glow: 60, tilt: -16, headlineWeight: 800, headlineCase: 'upper', captionAlign: 'left' };
+ const slides = [{ ...screen('One', 'hero'), callout: { focusX: 0.5, focusY: 0.3, zoom: 2, shape: 'circle' } }, screen('Two')];
+ await mock(browser, deck({ scene, slidesByDevice: { iphone: slides } })); await app.open('/');
+ const download = await browser.waitForDownload(() => ui.getByRole('button', 'Export bundle', { exact: true }).tap(), { timeout: 120_000 });
+ const zip = await JSZip.loadAsync(await zipFrom(download.path));
+ const pngs = Object.values(zip.files).filter(file => file.name.endsWith('.png'));
+ await expect(pngs).toHaveLength(8);
+ const hero = pngs.find(file => file.name.includes('/1320x2868/en/01-hero.png'))!;
+ const bytes = await hero.async('nodebuffer');
+ await expect(bytes.readUInt32BE(16)).toBe(1320); await expect(bytes.readUInt32BE(20)).toBe(2868);
+ await expect(bytes[25]).toBe(2);
+ const stats = await sharp(bytes).stats();
+ await expect(stats.channels.every(channel => channel.stdev > 3)).toBe(true);
+});
+
+test('project API rejects malformed scene data and the editor cleans out-of-range values', async ({ app, browser, screen: ui }) => {
+ const endpoint = new URL('/api/project', app.baseUrl);
+ const post = (body: State) => fetch(endpoint, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body) });
+ await expect((await post(deck({ scene: 'neon' }))).status).toBe(400);
+ await expect((await post(deck({ savedLooks: {} }))).status).toBe(400);
+ await expect((await post(deck({ slidesByDevice: { iphone: [{ ...screen('One'), callout: { focusX: 'left', focusY: 0, zoom: 2 } }] } }))).status).toBe(400);
+ const store = await mock(browser, deck({
+ scene: { backdrop: 'lava', tilt: 99, shadow: -5, headlineWeight: 1200 },
+ savedLooks: [{ id: 'kept', scene: {}, themeId: 'nope' }, { id: '' }],
+ slidesByDevice: { iphone: [{ ...screen('One'), callout: { focusX: 4, focusY: -1, zoom: 50, shape: 'blob' } }] },
+ }));
+ await app.open('/');
+ await ui.getByRole('textbox', 'App name').fill('Cleaned');
+ await eventually(async () => {
+ await expect(store.state.scene).toMatchObject({ backdrop: 'gradient', tilt: 30, shadow: 0, headlineWeight: 900 });
+ await expect(store.state.savedLooks).toHaveLength(1);
+ await expect(store.state.savedLooks[0].themeId).toBe('clean-light');
+ await expect(store.state.slidesByDevice.iphone[0].callout).toEqual({ focusX: 1, focusY: 0, zoom: 5, shape: 'circle' });
+ });
+});
+
+test('flowing spotlight lights every screen the same', async ({ app, browser, screen: ui }) => {
+ const scene = { backdrop: 'spotlight', span: true, decoration: 'none', shadow: 0, glow: 0, tilt: 0, headlineWeight: 700, headlineCase: 'as-typed', captionAlign: 'auto' };
+ const slides = ['A', 'B', 'C'].map(id => ({ ...screen(id, 'no-device'), headline: { en: '' }, label: { en: '' } }));
+ await mock(browser, deck({ scene, slidesByDevice: { iphone: slides } })); await app.open('/');
+ const download = await browser.waitForDownload(() => ui.getByRole('button', 'Export bundle', { exact: true }).tap(), { timeout: 120_000 });
+ const zip = await JSZip.loadAsync(await zipFrom(download.path));
+ const means: number[] = [];
+ for (const n of ['01', '02', '03']) {
+ const file = Object.values(zip.files).find(f => f.name.endsWith(`/1320x2868/en/${n}-no-device.png`))!;
+ const stats = await sharp(await file.async('nodebuffer')).stats();
+ means.push(stats.channels.slice(0, 3).reduce((sum, c) => sum + c.mean, 0) / 3);
+ }
+ // A strip-wide vignette used to leave screens 2+ under a flat dark wash.
+ await expect(Math.abs(means[1] - means[0])).toBeLessThan(8);
+ await expect(Math.abs(means[2] - means[0])).toBeLessThan(8);
+});
+
+test('looks keep per-screen headline sizes and the toast undo never reverts a later edit', async ({ app, browser, screen: ui }) => {
+ const slides = [{ ...screen('Long headline here', 'hero'), typography: { headlineScale: 0.7 } }, screen('Two')];
+ const store = await mock(browser, deck({ slidesByDevice: { iphone: slides } })); await app.open('/');
+ await ui.getByRole('button', 'Style Lab', { exact: true }).tap();
+ await ui.getByRole('button', /^Apply Playful/).tap();
+ await eventually(async () => {
+ await expect(store.state.slidesByDevice.iphone[0].typography).toEqual({ headlineScale: 0.7 });
+ await expect(store.state.scene.headlineScale).toBeGreaterThan(1);
+ });
+ await ui.getByRole('textbox', 'App name').fill('Edited after look');
+ await browser.locator('[data-sonner-toast] button[data-button]').first().tap();
+ await expect(ui.getByText('Use the toolbar Undo', { exact: true })).toBeVisible();
+ await eventually(async () => {
+ await expect(store.state.appName).toBe('Edited after look');
+ await expect(store.state.scene.headlineScale).toBeGreaterThan(1);
+ });
+});
+
+test('a magnifier with only some values is accepted and completed', async ({ app }) => {
+ const endpoint = new URL('/api/project', app.baseUrl);
+ const original = (await (await fetch(endpoint)).json()).state;
+ try {
+ const partial = deck({ slidesByDevice: { iphone: [{ ...screen('One'), callout: { focusX: 0.4 }, transforms: { callout: { x: 10, y: 20, width: 300, height: 300 } } }] } });
+ const response = await fetch(endpoint, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(partial) });
+ await expect(response.status).toBe(200);
+ } finally { await fetch(endpoint, { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(original) }); }
+});