Create Imessage Mockup

Superseded: the video kit now does this with the phone-chat part, version 1.1.4, in the parts folder of this repository. Every phone-chat style is a style file that draws the same screen frame by frame from the plan's scenes, with the original sounds, in the kit's browser. This atom stays, unchanged in behaviour, for skills outside the kit until they move; its scripts still run.

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

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/ads/capabilities/create-imessage-mockup
npm install
npx playwright install chromium

Files

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.