Remix Graphic Ad From Reference

remix-graphic-ad-from-reference

Purpose

Given one reference ad image + a target product + new copy, produce a finished static ad that keeps the reference's layout and composition but swaps the product and words for the new brand. This powers the app's "pick a Pinterest ad you like → get the same ad for your product" flow.

It does not invent layouts and it does not regenerate the whole scene from scratch. It reads the reference, then recreates it with GPT Image 2:

• GPT Image 2 (edit the reference) — ALWAYS use this as the generator. Run it in image-edit mode on the reference itself to preserve the layout/composition and swap in the new product + copy. This is the engine for EVERY remix (premium look). FAL slug fal-ai/gpt-image-1/edit-image.
• HTML overlay (goose-graphics) — NOT a generation engine. It is only an optional FINISHING step: if GPT bakes garbled/misspelled copy, overlay crisp text on top of the GPT output. Never use it as the primary generator — a remix must always be generated by GPT Image 2.

Inputs

Brand grounding — read the kit, never improvise (do this before generating)

The brand context comes from get_brand_kit (structured): colors (palette hex), typography, products[] (with imageUrls + name/description), screenshotUrls, and referenceImages[] (each tagged with productName + kind: "product" | "website_screenshot"). Read the full kit, not a preview.

Palette — by style_source (default template)

Default to template. Use brand ONLY when the user explicitly asks (e.g. "use/match my brand colours", "make it on-brand"). Do NOT switch to brand on your own judgment — keeping the reference's look is the expected default.

• template (default): keep the reference ad's colours/theme; the brand contributes only its product image, logo, and copy/voice — NOT its colours.
• brand (only on explicit user request): recolour the layout to the brand kit's colors (primary/accent/bg/text).
• NEVER invent a colour. Every colour in the output must come from EITHER the reference (template) OR the kit's documented colors (brand). Do not pull an accent off the logo, a mascot, a product, or "what looks nice." If style_source: brand but the kit has no palette, fall back to template (don't guess). This is the #1 off-brand failure.

Which image to feature — select from the kit, send ONLY the relevant one(s)

• Physical-product brand: the hero is the brand's product. Pick from referenceImages where productName matches the slot's product and kind is "product" (hero = that product's imageUrls[0]). Send only that product's image(s) for the slot — not all reference images.
• SaaS / software / app brand (brandType ∈ saas/software/service/app/platform, or remix_mode: ui): the hero is the brand's app UI — use referenceImages with kind: "website_screenshot" (i.e. screenshotUrls). NEVER insert a physical product or a mascot for a SaaS ad. If there is no screenshot, rebrand the existing UI (recolor/logo/copy).
• Don't substitute a mascot/logo for the product unless the brand genuinely has no product/app image and the layout's product slot can't be filled — and if so, say so to the user, don't silently swap.

Composed Atoms

• goose-graphics (skills/design/composites/goose-graphics) — renders the HTML-overlay path to PNG via the goose-graphics Playwright pipeline.
• create-image-gpt-image-fal (skills/ads/capabilities/create-image-gpt-image-fal) — GPT Image 2, run in edit mode on the reference for the photographic path.
• product-photoshoot — OPTIONAL: when no clean product render exists, generate one through the GooseWorks Product Photos workflow, ask before spending credits, and use only a result the user approves.

Workflow

Phase 0 — Get the spec (use remix_spec if it exists; analyze only if it doesn't)

If the template carries a remix_spec (every library template does), DO NOT re-analyze the image. Read it directly:

• remix_spec.slot_map.text_slots → the text fields to replace (each has id, role, and the reference's current text). Map the brand's copy_changes onto these slots by id/role.
• remix_spec.slot_map.product_images_needed + product_slots → how many brand product images to ask for and where each goes. Cut each out with scripts/cutout_product.py.
• remix_spec.slot_map.logo_slots / decorations → logo placement + arrows/badges to reproduce.
• remix_spec.gen_prompt → the ready, real-product-locked GPT prompt (fill its {{placeholders}}).
• remix_spec.remix_engine → the engine to use (skip Phase 1 routing).

Only if there is no remix_spec (a brand-new, un-tagged reference): view it at full res and write a one-paragraph anatomy (background, product placement, every text zone, palette, font) — i.e. produce a remix_spec on the fly. Prefer running the template through the triage tagger first so this is cached.

Phase 0.5 — Author the copy (agent auto-writes; user can revise)

If copy_changes is supplied, use it. Otherwise the agent writes it — read the brand pack (voice/tone, value-props, never-say) and map onto remix_spec.slot_map.text_slots: one on-brand line per slot, matching each slot's role and keeping length close to the reference's current text so it fits the layout. Respect never-say / no-competitor / no-unverifiable-claims. Write one line for every text slot the reference has (no more, no fewer) — these fill the gen_prompt {{text_slots}} block. Add no text the reference doesn't have, drop none it does; if an area has no text in the reference, add none. The output is an exact copy of the reference differing only in product, theme/colour, and the words. Versioning: show the drafted copy; on user feedback, regenerate a v2 (re-author the copy → re-render) rather than editing pixels. Keep each version.

Phase 1 — Engine (ALWAYS GPT Image 2)

Always generate with GPT Image 2 (fal-ai/gpt-image-1/edit-image, edit-the-reference mode) — go straight to Phase 2B. Do NOT use the HTML-overlay path as the generator, and ignore remix_spec.remix_engine even if it says html — every remix is generated by GPT Image 2 (this is a billed FAL generation via the proxy). Phase 2A (HTML/goose-graphics) is ONLY an optional text-overlay finishing step if GPT bakes wrong copy.

Phase 2A — HTML-overlay (OPTIONAL text-overlay finishing only — NOT the generator)

1. Cut the product out to a transparent PNG with scripts/cutout_product.py (handles palette-transparency renders and white/solid backgrounds via edge flood-fill — preserves interior white logos).
2. Build one index.html from assets/overlay-template.html: reproduce the reference's background, place the cutout, lay the new copy in the same zones. Arrows = inline SVG; scalloped seals = inline JS (template has both). Use the brand font (Google Fonts) + palette.
3. Render via create-goose-graphics / the goose-graphics screenshot pipeline: node <goose-graphics>/screenshot/screenshot.js --format <canvas> --input index.html --output render.png --font-delay 1500. Map aspect→canvas: 1080×1080→carousel, 1080×1350→poster, 1080×1920→story. 2:3 (1080×1620) has NO goose-graphics preset → render at poster (1080×1350, nearest) or a standalone 2:3 Playwright canvas; don't hand-edit the vendored renderer.

Phase 2B — GPT Image 2 path (EDIT the reference, do not regenerate)

1. Run GPT Image 2 in image-edit mode with the reference ad as the base + the product render — prompt it to keep the reference's layout, background, camera, lighting, and signature element exactly and only (a) replace the product with the attached one (match its label/logo exactly) and (b) clear the original text. ⚠️ Never generate grounded on the product alone — that invents a generic new scene and discards the reference's composition.
2. Text: either let GPT render the new SHORT copy, or have it leave clean space and add copy via the HTML overlay. Never stack an HTML text layer on output that already has baked text — one source.
3. --aspect_ratio 3:4 (or nearest), --quality high --resolution 2k. If the model returns a small image (long edge < ~1080px), upscale to ≥2k before shipping — AI-path baked text softens at low res (a known tradeoff vs the HTML path, which is natively 2×/crisp). GPT edit slug: fal-ai/gpt-image-1/edit-image (image_urls[]); it caps ~1536px long edge, so upscale to ≥2k via fal-ai/esrgan.
4. Fidelity gate (3 checks, all must pass): (a) signature element/layout preserved; (b) EVERY instance of the source product is replaced and NO source/competitor brand name, logo, or label survives anywhere in frame (diff full-res output vs reference — a partial swap that leaves a competitor bottle is a brand/ compliance hazard); (c) output is full-res (long edge ≥ ~2000px) and baked text is sharp. If any fails: re-roll GPT on the original reference, or (for text-only failures) overlay the text via goose-graphics on top of the GPT image. Reject only if GPT can't preserve the layout at all — never swap to HTML as the generator.