Prompt Generator

What is the Prompt Generator?

The Prompt Generator is an admin tool for building the JSON prompts that drive merch AI art generation. The merch pipeline embeds a user's selfie into a template image (typically containing a placeholder humanoid figure, e.g. a green doll). The prompt tells the image model how to perform that replacement — which element to swap, what to infer from the selfie, and what must stay untouched.

Building such a prompt is iterative. The Prompt Generator supports the full loop in one dialog:

1. Generate JSON description — Gemini analyzes the template image and produces a structured JSON description (composition, subjects, style, colors, notable elements).
2. Adapt prompt for selfie — describe the element to replace (the Fan location text, e.g. "the green humanoid figure") and AI rewrites every reference to that element's identity into "infer from the selfie" instructions, adds a top-level task field, and preserves everything else (pose, apparel, background, style).
3. Run Generation — one-off test render with the first corpus selfie (the "female influencer") to see what the prompt produces. Nothing is persisted to run history.
4. Refine — iterate using Add IMPORTANT (append fixed instructions to an IMPORTANT array) or Adapt with AI (free-form rewrite, e.g. "make the image more contrastive").
5. Save to prompt — write the result back to the host form (benchmark prompt or design AI Prompt).

Where to Access

The dialog (90vw × 90vh) opens from two places:

Editor

The prompt is edited in two synchronized modes:

• JSON mode (default) — interactive tree view (@uiw/react-json-view). Single-click a value to edit it inline, click keys to rename, hover for add/delete icons. The + icon opens a chooser (String / Array / Object). Typing [] / {...} as a value converts it to a real nested container.
• Plain text mode — raw textarea. If the text isn't valid JSON, a Format as JSON with AI button restructures it.

All edits keep the underlying prompt text in sync, so Save to prompt always saves exactly what is shown.

IMPORTANT instruction library

Add IMPORTANT appends instructions to the prompt's IMPORTANT array (created on first use). Instructions are saved to a global library (shared across all admins) so common rules — e.g. "keep the ethnicity of the selfie" — can be reused in every prompt:

• The dialog lists saved instructions with checkboxes; select any plus optionally type a new one.
• New instructions are persisted automatically (duplicates skipped via unique index).
• Hover a saved instruction to reveal a delete ✕ (with confirmation) that removes it from the library.

Test generation parameters

Run Generation uses the host's currently selected parameters when set, otherwise the defaults:

The output runs through the production pipeline (generate → center-crop → overlay) and is uploaded to merch/benchmark/preview/ on S3.

Architecture

packages/merch-benchmark/client/ (@zooly/merch-benchmark-client)
  components/prompt-generator-dialog.tsx
    Decoupled component — host injects its admin API caller (PromptGeneratorApi)
    Exported: PromptGeneratorDialog, PromptGeneratorApi, PromptPreviewParams

packages/merch-benchmark/srv/ (@zooly/merch-benchmark-srv)
  describe-template.ts      Template image → JSON description (Gemini vision)
  adapt-prompt-selfie.ts    Rewrite element references → "infer from selfie"
  refine-prompt.ts          Free-form AI rewrite of the whole prompt
  format-prompt-json.ts     Plain text → valid JSON structure
  preview-generation.ts     One-off test render (no DB rows)

Hosts:
  benchmark dashboard-page.tsx   passes the benchmark client's adminApi
  design-config-editor.tsx       passes the merch-admin client's adminApi

All AI text operations use Gemini 3.5 Flash (google/gemini-3.5-flash) via the AI gateway; test renders use the regular image model catalog.

API Endpoints

All under /api/merch/admin/benchmark/, admin-only, CORS-enabled:

Database

In the design builder, the Fan location text is stored in the design's configJson.fanLocationText field.