Add repeatable marketing screenshot generation

[shaunandrews]

Related issues

• None.

How AI was used in this PR

This proof of concept was designed, implemented, and exercised with Codex. The agent inspected the Agentic UI, built the deterministic capture harness and synthetic fixtures, added tests and documentation, ran capture matrices, and visually reviewed both light and dark output. Human direction set the marketing goals and corrected the important compositions: more sites, narrower chat/wider preview, sidebar/no-sidebar variants, preview/no-preview variants, longer conversations, focused composer copy, square site icons, compact conversation exports, and the missing Settings control.

Reviewers should validate the architecture, fixture content, and visual choices rather than treating AI-generated implementation as inherently merge-ready.

Executive summary

This draft adds a repeatable system for generating Studio Agentic UI screenshots for landing pages, documentation, app stores, Pressable, Automattic for Agencies, and similar marketing surfaces.

It renders production UI components against deterministic synthetic data, exposes named scenarios plus layout/presentation controls, captures exact-size PNGs in light and dark themes, validates every run, and writes a manifest and standalone contact sheet for review. Bulk generated output is intentionally ignored by Git; this PR checks in only the curated examples below, and approved exports can be copied wherever the marketing team needs them.

Example output

These are deterministic synthetic captures generated from the committed PR head. The broad matrix and compact export completed with zero diagnostics.

Generated contact sheet

The generated contact sheet collects eight wide scenarios in light and dark and links each thumbnail to its exact-size PNG.

Representative states

Multi-site overview · light Populated site sidebar with the core management actions.	Focused composer · light A new agent session with seeded draft copy and suggested tasks.
Working agent + preview · dark A narrow conversation panel leaves room for the live site preview.	Long conversation · compact light The 900 × 600 logical window export with sidebar and preview hidden.
Connected-site controls · dark Studio, Preview, Live, and Settings controls for a connected site.	Responsive preview · light Desktop and mobile versions shown together for comparison.

Proposed Changes

• Adds a marketing-only Agentic UI build and capture workflow that does not read personal Studio data.
• Provides ten reusable UI scenarios covering setup, site management, connected-site controls, selective sync, responsive preview, and agent conversations at several stages.
• Uses eight fictional sites and a polished same-origin Meridian Coffee preview so captures remain stable, private, and free of outside network dependencies.
• Makes sidebar state/width, preview state/ratio, composer content/focus, conversation framing, theme, and output dimensions controllable from the capture CLI.
• Includes presets for quick smoke checks, compact 2× desktop exports, wide 2× exports, and 4K store assets.
• Produces exact-dimension PNGs, manifest metadata, diagnostics, and a standalone contact sheet.
• Freezes time, timezone, locale-sensitive inputs, randomness, and animation; blocks non-loopback requests and fails on console, page, image, request, readiness, or PNG-dimension errors.
• Keeps fixture site icons square and fixes the blank-email User menu fallback so the Settings icon appears reliably.

Agent-first workflow

The intended workflow is for a marketer or engineer to describe the desired compositions and let an agent run the mechanical parts: checkout, build, capture, inspect, iterate, and collect approved PNGs.

A useful prompt is:

Check out the add-marketing-screenshot-system branch, install dependencies if needed, and read tools/marketing-screenshots/README.md. Generate the requested Studio marketing screenshots with synthetic data only. Capture both light and dark unless told otherwise, inspect contact-sheet.html, report any manifest diagnostics, and iterate on scenario/panel/presentation options until the compositions look right. Do not commit generated artifacts or use personal Studio data. Copy only the approved flat PNG set to the requested destination.

The agent should:

1. Check out the branch and install dependencies.
2. Run the top-level screenshot command so the marketing target is rebuilt from the current checkout.
3. Open the generated contact sheet and inspect light/dark variants.
4. Adjust scenario selection, sizes, panels, composer copy, or conversation framing through CLI flags.
5. Re-run only the affected combinations.
6. Confirm manifest diagnostics are empty and copy the approved PNGs to the delivery folder.

Checkout, build, and use

git fetch origin add-marketing-screenshot-system
git switch --create add-marketing-screenshot-system --track origin/add-marketing-screenshot-system
npm install

Run the default smoke export:

npm run screenshots:marketing

Generate the conversation set at both wide and compact desktop sizes:

npm run screenshots:marketing -- \
  --scenario agent-new-session,agent-working-preview,agent-complete-preview,agent-long-conversation \
  --theme light,dark \
  --preset raw-wide-2x,raw-compact-2x \
  --output artifacts/marketing-screenshots/conversations

Generate a targeted preview composition with explicit panel sizing:

npm run screenshots:marketing -- \
  --scenario agent-complete-preview \
  --theme light,dark \
  --preset raw-wide-2x,store-4k \
  --preview-width-ratio 0.6 \
  --sidebar-width 320 \
  --output artifacts/marketing-screenshots/review

List scenarios, themes, and presets with:

npm run screenshots:marketing -- --list
npm run screenshots:marketing -- --help

When no output path is supplied, the runner writes to artifacts/marketing-screenshots/<commit>/. Each run contains PNGs, manifest.json, and contact-sheet.html. For fast iteration against an already-built target, use npm run screenshots:marketing:capture with the same flags.

How it works

1. The top-level command builds a marketing-only Vite entry for the Agentic UI.
2. A named scenario loads production React components through a synthetic connector and deterministic fixture catalog.
3. The scenario applies its default route, theme, panel layout, composer state, conversation anchor, and any semantic UI interactions.
4. The page reports ready only after its route, data, fonts, images, and preview frames have settled.
5. The runner opens a fresh Chromium context for each scenario × theme × preset combination, applies optional CLI overrides, and captures the exact requested dimensions.
6. The runner validates browser/runtime errors, network isolation, image readiness, UI diagnostics, and PNG dimensions.
7. It emits a machine-readable manifest plus an easy-to-scan standalone contact sheet.

The fixture path is intentionally separate from normal app startup. It does not load local sites, authentication, or personal configuration, and the embedded preview stays on the loopback server.

Review guide

Please review carefully:

• Whether a marketing-only build is the right isolation boundary.
• Whether the synthetic connector fails loudly enough when the production UI contract changes.
• Whether the scenario names, content, and visual compositions represent the product accurately.
• Whether readiness, determinism, network blocking, and diagnostic checks are sufficient.
• Whether the CLI flags and presets are understandable for agent-driven iteration.
• The small blank-email User menu fallback used to make Settings visible in captures.

Reasonable to skim initially:

• The long static Meridian Coffee preview fixture.
• Individual synthetic conversation copy once the marketing direction is accepted.
• Contact-sheet and manifest formatting covered by focused tests.

Bulk generated output remains ignored. The diff includes only the seven curated synthetic documentation examples shown above.

Known tradeoffs and follow-ups

• These are simulated browser-renderer captures, not genuine native macOS, Windows, or Linux windows. Native shell/chrome capture can be added as a separate tier once the compositions are approved.
• The site preview is a deterministic fixture rather than a live WordPress Playground site, which favors repeatability and speed over backend fidelity.
• This draft does not publish to a DAM or run captures in CI.
• The full workspace typecheck is currently blocked locally by an existing duplicate incompatible ignore package type mismatch in apps/studio/src/ipc-handlers.ts. Focused typechecks for the Agentic UI and screenshot tool pass.

Testing Instructions

Build and focused validation completed:

npm -w @studio/ui run typecheck
npx tsc -p tools/marketing-screenshots/tsconfig.json --noEmit
npm test -- apps/ui/src/marketing/index.test.ts
npm test -- apps/ui/src/components/user-menu/index.test.tsx
npx vitest run --config tools/marketing-screenshots/vitest.config.ts
npm -w @studio/ui run build:marketing
git diff --check

Results:

• Agentic UI marketing tests: 13 passed.
• User menu tests: 4 passed.
• Screenshot runner tests: 25 passed.
• Marketing build and both focused typechecks passed.
• Wide light/dark scenario matrix captured at 2880 × 1800 with zero diagnostics.
• Conversation scenarios captured in light/dark at both 2880 × 1800 and 1800 × 1200 with zero diagnostics.
• Visual review covered square site icons, the dark Settings icon, narrower chat/wider preview, focused composer content, long conversations, preview/no-preview, and sidebar/no-sidebar states.

To review manually, run one of the commands above and open the generated contact-sheet.html. Check every requested state in both light and dark, then confirm manifest.json has no diagnostics.

Pre-merge Checklist

• Checked the marketing target for TypeScript, React, browser console, page, request, image, readiness, and PNG-dimension errors.
• Verified the changed UI in light and dark themes.
• Kept bulk generated assets and all personal data out of the commit; only the seven curated synthetic examples above are included.
• Resolve or independently confirm the existing full-workspace ignore package type mismatch before merge.
• Agree on the long-term architecture and content direction for this proof of concept.