/render-imessage-chat

name: render-imessage-chat
description: Render a configurable iMessage conversation inside a properly framed phone, then a brand end card. Uses the original send/receive sounds and a shared frame timeline for text, typing, scrolling and sound. Free local Playwright + ffmpeg assembly; optional image/music generation belongs to separate gated capabilities.
status: superseded
version: "2.1.2"
superseded_by: phone-chat@1.2.0

> **Superseded:** the video kit now does this with the phone-chat part, version 1.2.0, 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.

Human version

Make a texting-story ad with the chosen contact names and phone time, a proportional phone, an inset Dynamic Island and the original iMessage sounds. The brand, story and background can change. Images are optional and can appear anywhere in the conversation; product links and music are optional too.

This rebuild preserves the shell and sounds from the approved Dermwise Goa build. It fixes missing identity binding, the island touching the screen edge, light-mode header colors, early/missing group names and capture timing drift. Every movie frame and sound cue uses the same timeline; browser startup cannot trim the beginning or ending. No paid API is needed to render or repair the UI.

On a 9:16 canvas the phone now sits clear of the TikTok/Reels controls by default: the newest message, including the punchline, always stays above the bottom caption band and left of the button rail (`safe_area`).

---

Agent version

Read [the reference and authoring rules](references/imessage-reference.md). The calling recipe supplies NEW names, copy, brand facts and real assets. `scripts/config.example.json` is a fictional, runnable example, never defaults.

Choices and bindings

• Relationship, contact names and group title → `thread.participants`, `thread.title`.
• Displayed phone time → `thread.clock`, preserving the user's chosen text.
• Story, tone and language → `thread.messages`. Casual spelling and emojis are allowed.
• Chat images → zero or more `attachment` entries at their authored positions in

`thread.messages`; either participant may send them. Never reorder by type.

• Theme → `theme: "dark" | "light"`.
• Background → optional local `background_image`; neutral when absent.
• Hardware → `dynamic_island: true | false`; true floats inside the screen.
• Music → optional existing bed passed to `render.sh --music`; no bed means SFX only.

Exactly one participant is `self:true`. A DM has two participants; its header reads the other participant's `name` and derives the first initial unless supplied. A group requires a title and named contacts. Missing names fail before capture. There is no demo-name fallback. Changing the config changes the visible name. When a name changes, update any derived initials too. Keep explicit user-supplied initials only when they still match the requested identity.

Run

Requires Node 18+, Python 3, ffmpeg with libx264, ffprobe and Playwright Chromium. Install dependencies in the fetched **scripts folder**, then launch/close that script's own Chromium before any optional paid image/music call. Preserve its cwd, NODE_PATH and PLAYWRIGHT_BROWSERS_PATH. `gooseworks doctor --renderer-script "/absolute/path/scripts/record-chat.js"` can check that runtime. If unavailable, use a bounded free `createRequire(actualScript)` launch/close probe (15-second launch timeout, 20-second whole-process limit). Cache presence alone is not proof.

cd scripts
npm ci
# Install Chromium only if the free launch probe says it is missing:
# npx playwright install chromium
node record-chat.js --config /absolute/path/config.json --out-dir /absolute/path/working/preview --preview-only
bash render.sh --config /absolute/path/config.json --out /absolute/path/finals/master-final.mp4
# Optional: append --music /absolute/path/bed.mp3

Preview produces `chat.html`, `chat-preview.png` and `master-chat.safe-area.json`; the HTML exposes `window.__renderAt(seconds)` and `window.__safeAreaReport()` (canvas-pixel boxes of the newest row and any `data-safe-keep` sheet or dialog) for frame inspection. Full render keeps those, `master-chat.mp4`, `.timeline.json`, `.sfx.json`, the end-card HTML/PNG/MP4 and the finished master. The recorder checks the safe area on every output frame and fails on a violation. `check-render.py` verifies dimensions, audio stream, frame count, complete ending and the safe-area report; `python3 scripts/check-render.py --safe-area <work>/master-chat.safe-area.json` checks a preview alone. Review the ACTUAL master after every repair; these technical checks do not establish creative acceptance.

Individual `record-chat.js`, `render-end-card.js` and `stitch.sh` commands remain available. `render.sh` produces the 1080×1920 recipe master. The chat recorder also supports even preview dimensions; the phone must fit with a margin.

Config contract

• Inline `thread` or `thread_path`. Relative files resolve against config.json.
• Unique message IDs and valid `from` participants. Types: text, typing, timestamp,

attachment, tapback. Reactions target an earlier message ID and carry an emoji. Typing immediately precedes a received text/attachment from the same person. Self messages type in the composer, including complete emoji graphemes.

• Short messages read best. Longer words wrap; real overflow fails preflight.
• Optional attachment: `src` local image/data URI, `presentation:"photo"` for a

photo or `"rich-link"` for image + flush meta card + title/domain/chevron. Optional `dwell_sec` overrides its default 3.6-second reading hold. Text-only chats need no images. One or several attachments can come first, between any messages or last; preserv