Asset Pipeline

Tools

• python <plugin>/mcp/assets/assets.py webp <image> [quality] — any raster → webp beside it (Pillow). Run on EVERY raster an agent adds to public/.
• python <plugin>/mcp/assets/assets.py frames <video> [fps] — mp4 → webp frame sequence (needs ffmpeg; missing → tell the user the one-line install, continue with other work).
• python <plugin>/mcp/assets/assets.py cut <image> [tol=32] — flat background → transparent webp (samples the corner color; raise tol for gradients/noise).
• All record asset_manifest rows. Serve only webp to browsers.

Transparency & icons (no model can do this — we do)

NO image model (Gemini, Imagen, DALL·E) outputs a real alpha channel. The recipe: generate the mark on a FLAT background (the logo prompt below already forces this), then assets.py cut strips it locally — free, offline, zero credentials. Photos / complex subjects: pip install rembg, then rembg i in.png out.png (local U2Net model, also key-free).

Scrollytelling recipe (the storytelling primitive)

1. Storyboard scroll beats first: entry, 2–4 transitions, resolution, and the content pinned beside each beat. Motion supports the story; it is not a decorative loop.
2. Get one continuous 5–8 second source clip (user-provided in workspace/references/video/, or generate below). Locked camera direction, constant motion, and no cuts produce clean bidirectional scrubbing.
3. assets.py frames video.mp4 24 → video_frames/frame_0001.webp …. Produce desktop and mobile crops when composition cannot safely center-crop.
4. Copy frames to public/frames/<name>/; use templates/ScrollScrub.tsx. It loads a small window around scroll position, favors scroll direction, evicts distant frames, caps DPR, and draws cover-fit through one canvas.
5. Ship a meaningful poster. Reduced-motion, save-data, low-memory devices, failed decoding, and no JavaScript receive that poster and the complete narrative as ordinary semantic HTML.
6. Keep headings, copy, links, and calls to action outside canvas/WebGL so they remain selectable, accessible, indexable, and stable before frames arrive.
7. Design-law still applies: one cinematic sequence per page. Run web-quality checks for overflow, reduced motion, accessibility, metadata, and SEO.

Frame delivery is progressive. Load frame zero immediately, then a bounded forward/backward chunk near the target. Never create every Image at mount for a long sequence. Use immutable, content-hashed frame URLs with long cache headers; do not lazy-load the poster or first frame. Decode before draw, render at most once per animation frame, and recalculate canvas size through ResizeObserver, not layout reads on every scroll event.

AI video generation — the ladder (never exit on missing credentials)

Omni = gemini-omni-flash-preview, Google's text→video model (Veo 3.1 is the fallback family). Don't hand-roll the REST calls — the ladder is implemented:

python <plugin>/mcp/assets/video.py "a slow orbit around a matte black cube"
# or: from video import generate; rung, detail = generate(subject, out="hero.mp4")

Verify every generation — measure, don't eyeball

python <plugin>/mcp/assets/verify.py hero.mp4 "#10B981" --audio

Prints accent coverage % and mean audio dB, exits nonzero on failure. Run it on every generated video before showing the user. Two real defects shipped because nobody measured: a file with a valid AAC stream that was silent (mean −91 dB — "has audio" is not "is audible"), and a Veo clip whose prompt demanded one accent while the frame read 90% emerald against the ≤10% budget. Rewriting the colour rule three ways brought it to 1.8%, then 0.7% — but only measuring proved it. Report the number, never an adjective.

Audio — silence is a choice, not a default to inherit

Veo 3+ generates synced audio natively (its headline feature over Veo 2). Two things must agree or you get silence:

generate("a machine room", audio="low industrial hum, distant servos")

This sets generateAudio: true in the request and writes the soundscape into the prompt. Setting only the prompt does nothing — the API param governs.

audio=False (the default) is correct only for scroll-scrubbed scrollytelling, where the browser never plays the file. For a hero, demo, or social video, ask the user — do not inherit silence from the scrollytelling recipe below. That inheritance shipped silent Veo 3 output for exactly this reason.

generate() returns (rung, detail). Rungs 1–2 wrote the mp4 and detail is the model that served it. Rung 3 means detail IS the paste-prompt — that is a success path, not a failure: show it to the user and keep working. An expired key falls through to the next rung instead of raising.

Credentials live in the project .env (gitignored — verify), written at bootstrap. Standard var names above (they match gcloud/Vertex conventions). Never store keys in the SQLite store or any committed file.

The paste-prompt (rung 3 — write it FOR the user, filled in)

Generate a short video for a website scroll animation. Audio: none — silent scroll-scrubbed footage. (For a hero/social video instead, replace this line with the soundscape you want.) Subject: <one concrete scene — object, environment, mood>. Style: premium industrial minimalism; near-monochrome palette on a dark #0A0A0B background with a single <accent color> accent; soft studio lighting; no on-screen text, no logos, no people (unless specified). Camera: one continuous slow <push-in | orbit | pan>, locked horizon, absolutely no cuts. Motion: smooth, constant speed throughout — this will be scrubbed by scroll, so no speed ramps, no flicker. Specs: 5–8 seconds, 16:9, highest detail.

Tell the user: paste into the Gemini app, download the mp4, drop it in workspace/references/video/, then run Atelier build to continue — the pipeline handles frames automatically. If Gemini refuses, simplify the Subject line (concrete object, neutral scene) and retry once.

Image generation — pick the model by job (same credential ladder)

gemini-2.5-flash-image is legacy — never use it in new work. For storytelling, offer the user the Lite option explicitly: a 20–30 frame storyboard costs ~$1 and lands in under a minute, then regenerate only the keeper frames on the default model.

Cloudflare Workers AI — sibling image route (verified, not a replacement)

Third image-gen option alongside the Gemini ladder above, when the project has Cloudflare credentials (CLOUDFLARE_API_TOKEN, CLOUDFLARE_ACCOUNT_ID — same rule as Gemini: project .env, gitignored, never in the SQLite store or a commit). Two distinct routes live under the SAME endpoint family — verify which one before promising "free":

1. Native Workers AI models (@cf/...) — free, runs on Cloudflare's own compute. POST /client/v4/accounts/{account}/ai/run/{model} — these models take multipart/form-data, even for a text-only prompt (a JSON body 400s with a generic AiError: Invalid input, no matter how correct the JSON looks — this is the one gotcha that burns an agent's first two attempts). Verified working: @cf/black-forest-labs/flux-2-klein-9b returns a base64 JPEG synchronously, no billing required.

   curl --request POST \
     --url "https://api.cloudflare.com/client/v4/accounts/$CLOUDFLARE_ACCOUNT_ID/ai/run/@cf/black-forest-labs/flux-2-klein-9b" \
     --header "Authorization: Bearer $CLOUDFLARE_API_TOKEN" \
     --form "prompt=<subject>" --form "width=1024" --form "height=1024"
   # response: {"result":{"image":"<base64 JPEG>"}}

   No native alpha/transparency on this route — pipe the decoded output through the same assets.py cut step as Gemini output.
2. BYOK-proxied models (openai/gpt-image-2, etc.) — billed, NOT free. POST /client/v4/accounts/{account}/ai/run (model in the JSON body, not the URL) with {"model":"openai/gpt-image-2","input":{...}}. This one DOES support background:"transparent" + output_format:"webp" natively (skips the cut step entirely) — but it 402s with "Insufficient balance; add money to your gateway or use BYOK" (code 2021) on an unfunded account. Only use it once the user confirms the AI Gateway has credit or an OpenAI key is linked — never assume it's free because it lives under /ai/run next to the native models. Full input params: prompt (required), size (1024x1024/1024x1536/1536x1024/auto), quality (low/medium/high/auto), background (transparent/opaque/auto), output_format (png/webp/jpeg), images (array of base64/data-URI inputs, 1-16, for edits/composites).
3. No Cloudflare credentials, or user prefers the ChatGPT UI directly — same underlying model as route 2, so the same params apply as plain English in the prompt: state the size, "transparent background", and "export as PNG" explicitly; ChatGPT's UI has no size/quality controls, the model reads them from prose.

Route 1 is the default recommendation (free, no gate) for icon/tile-scale batches; keep Gemini as the default for finals needing 4K or heavy text rendering, since Cloudflare's native catalog doesn't match gemini-3.1-flash-image's resolution ceiling.

Logo & brand-mark generation (same ladder, image models)

When a project needs a logo/mark: rung 1–2 call the Gemini image models above with the same credentials (GOOGLE_API_KEY, or Vertex with service-account creds); rung 3 emit the universal prompt below for ANY platform (Gemini app, ChatGPT/DALL·E, Midjourney). Always generate light + dark variants, convert to webp, and check crispness at 16px. The mark must obey design-law: flat vector look, hairline geometry, near-monochrome + the project's ONE accent — never gradients, 3D, or mascots.

Universal logo prompt (fill the brackets, works on every platform):

Minimal geometric logo mark for "<NAME>", a premium <what it does> company. Concept: <one visual idea tied to what the company means — e.g. "a loop whose final segment resolves into a filled square: iteration reaching done">. Style: Swiss / International Typographic Style, flat vector, thin hairline strokes of consistent 1.5px optical weight like an architectural schematic, generous negative space; no gradients, no 3D, no shadows, no mascots, no extra glyphs. Colors: ink-black strokes on off-white #FAFAF8 with exactly ONE small filled element in <ACCENT HEX>. Must stay crisp at 16px favicon size. Second variant: dark mode — off-white #F5F5F3 strokes on near-black #0A0A0B, same accent element. Optional lockup: wordmark "<NAME>" in a grotesk sans, weight 500–600, all caps, +6–8% letter-spacing.

If the output has clutter, append: "absolutely no background texture, no reflections — mark and wordmark only," and retry once. Host integration: read the runtime contract for plugin/project paths, host command names and capabilities. Explicit user instructions and repository conventions take precedence over these defaults.