create-imessage-mockup

name	create-imessage-mockup
description	Render pixel-accurate iMessage screenshot mockups (DM or group) from a thread JSON. Supports minimal, with-keyboard, and full iPhone 15 Pro frame variants. Outputs HTML + PNG.

create-imessage-mockup

Generate iMessage screenshots that look like real iOS captures — correct bubbles with tails, typing indicators, timestamps, "Delivered" captions, group avatars + sender names, keyboard chrome, and an optional iPhone 15 Pro bezel with Dynamic Island and status bar.

Purpose

Turn a structured thread JSON into a believable iMessage screenshot — first as standalone HTML (generate.js + templates/chat.css), then rasterized to PNG with headless Chromium (screenshot.js/render.js via Playwright). It is the atom you reach for when an ad, social post, or video scene needs a fake-but-convincing iOS message capture.

What it gets right, grounded in the renderer:

• Bubble runs and tails — blue sent bubbles (right) and gray received bubbles (left), with a curved tear-drop tail drawn only on the last bubble of each consecutive sender run (isLastOfRun in generate.js).
• Dark-themed iOS chrome — theme: "dark" flips the page to the iOS dark conversation look; the status bar, Dynamic Island, and keyboard match iPhone 15 Pro.
• Group affordances — group threads (mode: "group") add per-sender colored avatar circles, sender names above the first bubble of a run, and a 4-tile group-header badge.
• Beats for storyboards — timestamp pills, a static-but-mid-animation typing three-dot bubble, attachment cards, and "Delivered"/"Read" captions let you stage individual frames of a conversation.
• Three crops — --minimal (bubbles only), --with-keyboard (header + iOS keyboard), and --with-iphone-frame (full bezel + Dynamic Island + status bar over a gradient backdrop).

The atom embeds no LLM — it is deterministic. The orchestrating agent is responsible for composing the thread JSON; the renderer only draws exactly what the JSON says.

When to use

• Need a fake iMessage screenshot for an ad, social post, video scene, or product mockup.
• Want a side-by-side hero image showing a conversation in an iPhone frame.
• Need a typing indicator or "Delivered" beat for a video storyboard.

If you're rendering programmatic graphic frames more broadly (cards, posters, infographics), use create-goose-graphics instead.

Inputs

The skill is deterministic — it does not embed an LLM. To translate a free-form prompt into a thread, the orchestrating agent (you) composes a JSON file matching the schema below, then invokes the renderer.

Thread JSON schema

{
  "mode": "dm" | "group",
  "title": "Karaoke Crew",
  "participants": [
    { "id": "me",    "name": "Me",    "self": true },
    { "id": "sarah", "name": "Sarah", "color": "#FF9500", "initials": "S" }
  ],
  "messages": [
    { "type": "timestamp", "label": "iMessage\nToday 9:41 AM" },
    { "type": "timestamp", "bold": "Sat, Jan 2", "light": "11:07" },
    { "type": "text",      "from": "sarah", "text": "Did we crash it?" },
    { "type": "text",      "from": "me",    "text": "Couldn't withstand our friendship", "delivered": true, "read": false },
    { "type": "typing",    "from": "sarah" }
  ],
  "keyboard": { "leftIcon": "plus" }
}

• mode — dm or group. If omitted, auto-detected from the participant count.
• participants[].self: true marks the user (sent bubbles, no avatar).
• participants[].color is the avatar background; defaults from a 6-color palette.
• participants[].initials defaults to the first letter of name.
• messages[]:
  • timestamp — centered pill. Use label (newline-separated bold/light) or explicit bold and light fields.
  • text — text bubble. delivered: true on the last sent bubble in a run renders the "Delivered" caption (or "Read" if read: true).
  • typing — animated three-dot bubble (rendered as a static mid-animation frame for screenshot determinism).
• keyboard.leftIcon — "plus" (default) or "camera".

CLI

node render.js --thread examples/group-with-frame.json --with-iphone-frame
node render.js --thread examples/dm-with-keyboard.json --with-keyboard
node render.js --thread examples/dm-minimal.json       --minimal
node render.js --thread my-thread.json --with-keyboard --output ./my-exports/ --name nightout

Flags

Flag	Effect
--thread <path>	(required) JSON file matching the schema above
--prompt "<brief>"	prints the schema and exits — agent must compose a thread.json and re-invoke
--minimal	bubbles + timestamps only (no header, no keyboard, no frame)
--with-keyboard	bubbles + iOS keyboard chrome (default)
--with-iphone-frame	full iPhone 15 Pro bezel + Dynamic Island + status bar + soft gradient backdrop
--dm / --group	force chat mode (otherwise auto-detected from participants)
--name <slug>	override the output folder slug
--output <dir>	parent dir for the dated output folder; default ./imessage-mockup-exports/

Frame flags are mutually exclusive.

Output

<output>/<YYYY-MM-DD>-<slug>/
  index.html       # full standalone HTML
  screenshot.png   # rendered PNG (DPR 3, "Retina")
  thread.json      # copy of the input for reproducibility

Default <output> is ./imessage-mockup-exports/ in the cwd.

Workflow

1. Receive a prompt or existing thread JSON.
2. If only a prompt was given: compose a thread.json matching the schema, save it.
3. Run node render.js --thread <path> [flag].
4. Open the resulting PNG to verify the layout. If something looks wrong (clipping, wrong tail side, missing avatar), edit the thread JSON or the relevant template under templates/ and re-render.

Setup (one-time)

cd skills/atoms/messaging/create-imessage-mockup
npm install
npx playwright install chromium

Files

File	Purpose
render.js	CLI entry — parses flags, generates HTML, takes screenshot, writes outputs
generate.js	Thread JSON → standalone HTML page
screenshot.js	HTML → PNG via Playwright (chromium headless)
templates/chat.css	All visual styling (bubbles, tails, keyboard, iPhone frame)
templates/icons.js	Inline SVG icons (plus, camera, mic, signal, wifi, battery, chevron)
examples/*.json	6 reference threads exercising every flag combination
tests/run-all.sh	Render every example into tests/output/ for visual review

Testing

bash tests/run-all.sh
# inspect tests/output/<case>/<date-slug>/screenshot.png

The 6 cases cover: dm-minimal, dm-with-keyboard, dm-with-typing (camera-keyboard variant), dm-with-frame, group-with-frame, group-minimal.

Implementation pitfalls — do not re-introduce these bugs

These are mistakes that have already been made and fixed. If you modify the templates, do not undo them.

Bubble tail painting order

The iMessage tail in templates/chat.css is drawn with two pseudo-elements that both sit behind the bubble's background (z-index: -1 inside an isolation: isolate stacking context on .bubble):

• ::before is the colored bulge that extends past the tail-side edge.
• ::after is the page-color cutout that overlaps the bulge from outside, with a rounded corner that "carves" the tear-drop curve.

This works because ::after paints on top of ::before (later in source order = higher in paint order). In the overlap region the cutout wins, leaving only the curved tail tip of the bulge visible.

Do not swap these roles. If ::after is used for the bulge and ::before for the cutout, the cutout paints behind the bulge, so it does nothing — and the tail renders as a chunky rectangle with one rounded corner, not a curved tear-drop. This is how tails initially looked broken.

Do not remove isolation: isolate from .bubble without replacing it with another stacking-context trigger (z-index: 0, transform, etc.). Without a stacking context, z-index: -1 on the pseudo-elements will push them behind the page background, not just behind the bubble's own background, and the tail disappears entirely.

Tail vs. avatar overlap (group chats)

.avatar-slot has z-index: 3 and position: relative so it paints on top of the bubble next to it. This is required: without it, the bubble's tail (which extends ~7px to the left of the bubble for received messages) overlaps the avatar circle.

The avatar is a sibling of the bubble in the .row flex container, not a child of the bubble. The bubble's isolation: isolate does not contain it, so this stacking still works.

"Last bubble in a run" rule

Tails appear only on the last consecutive bubble from the same sender. Adding a tail to every bubble (or the first instead of the last) does not match iOS. The logic in generate.js walks the message list and sets isLastOfRun based on whether the next message is from the same from; do not change that without checking iOS reference screenshots.

Screenshot viewport

Modes use fullPage: true with a small initial viewport height (100px). This is intentional: Playwright extends the viewport to fit content but never shrinks it, so a small initial height + fullPage produces a tightly-cropped screenshot. Do not raise the viewport height to "make sure the screenshot fits" — that creates dead vertical space below the content.

The with-iphone-frame mode uses a fixed viewport (525×980) with fullPage: false because the frame itself defines the visible area; here we want the viewport to bound the screenshot to a single phone-sized rect.

Known limitations

• Image avatars not supported in v1 — only colored circle initials. Add an avatarUrl field and update templates/chat.css if needed.
• Typing animation is static — captured as a mid-animation frame. The HTML itself does animate; only the PNG is frozen.
• No tapback reactions in v1 — schema reserves {type: "reaction", target: <index>, kind: "heart"|...} but the renderer ignores it for now.
• Emoji rendering depends on system fonts — Chromium ships with Noto Color Emoji on Linux/macOS; emoji should render but visually differ slightly from Apple Color Emoji.

Quality Checks

Before treating a render as final, verify against the iOS look:

• Output manifest — the output folder contains index.html, screenshot.png, and a copied thread.json (written by render.js).
• PNG dimensions — minimal and with-keyboard are 750px wide × DPR 3 = 2250px wide, with height growing to fit content (fullPage: true). with-iphone-frame is the fixed phone rect: 525×980 × DPR 3 = 1575×2940. Confirm with sips -g pixelWidth -g pixelHeight <png> (macOS) or any image tool.
• Bubble sides + tails — sent (self) bubbles hug the right and are blue; received bubbles hug the left and are gray. A tail appears only on the last bubble of each sender run — never on the middle bubbles, never on the first-of-run.
• Group rendering — in group threads each received run shows the sender's name above its first bubble and a colored avatar circle beside its last bubble; the group header shows up to 4 avatar tiles plus the title.
• Captions — the final sent bubble in a run with delivered: true shows a "Delivered" caption ("Read" if read: true), and only that bubble.
• Frame chrome (framed mode) — Dynamic Island is centered at the top, the status bar reads 9:41 with signal/wifi/battery, and the phone sits on the soft gradient backdrop.
• Typing / emoji / link beats — typing renders three dots in a received bubble; emoji-only messages render enlarged; [[link:CODE]] markers render as an underlined iOS link-detector span.
• No renderer errors — the process exits 0 and prints the ✓ <png path> line.

The canonical visual review is bash tests/run-all.sh, which renders all six example fixtures into tests/output/ for side-by-side inspection.

Failure Modes

Known ways this atom breaks, and what they look like:

• Dependencies not installed — screenshot.js exits with playwright not installed. Run npm install in the skill directory. Fix: run the one-time npm install + npx playwright install chromium from Setup.
• Missing --thread — render.js prints help and exits non-zero; --prompt alone prints the schema and exits 2 by design (the agent must compose a thread.json and re-invoke). The atom never invents a conversation on its own.
• Bad thread JSON — invalid JSON throws on JSON.parse; a from that doesn't match any participant id yields a bubble with no avatar/name (in groups) because the participant lookup misses. Keep messages[].from in sync with participants[].id.
• Broken bubble tails — swapping the ::before/::after roles or removing isolation: isolate from .bubble in templates/chat.css makes tails render as a chunky rectangle or vanish entirely (see Implementation pitfalls). Do not re-introduce.
• Tail / avatar overlap in groups — dropping the z-index: 3 / position: relative on .avatar-slot lets a received bubble's tail bleed over the avatar circle.
• Dead vertical space — raising the small initial viewport height for minimal/with-keyboard defeats the fullPage tight-crop and leaves empty space below the content.
• Mutually exclusive frame flags — passing more than one of --minimal / --with-keyboard / --with-iphone-frame is ambiguous; the last one parsed wins. Pass exactly one.
• Emoji/font drift — emoji render via the system emoji font (Noto on Linux/macOS), so glyphs differ slightly from Apple Color Emoji; this is a fidelity limit, not a crash.