# FlatRender — Premium Template Toolchain (stop-motion · paper-cut · premium)

From the `premium-video-toolchain` research sweep (6 finders). Goal: raise template
quality beyond hand-coded art, for a **Persian-first paid SaaS** that renders
**editable** templates to MP4 server-side, on **Remotion + After Effects** engines.

## The diagnosis
The quality cap isn't the engines — it's the AI **hand-authoring the art in code** at
render time. Clean vector motion is what code does well; stop-motion / paper-cut live
on **texture, handmade imperfection, real shadows, layered materials** — artist/asset
driven. Fix = **change where the artistry comes from**, keep the editable layer in code.

## The load-bearing constraint: Iran access is the dominant filter (not quality)
Every frontier AI tool is **OFAC-blocked at signup AND payment** — US (Runway, Sora,
Veo, Luma, Pika, Kaiber) *and* Chinese (Kling, Seedance). The aggregators (fal.ai,
Replicate) are US/Stripe-billed → same wall. There is **no direct payable-from-Iran
path to any hosted model.** Two viable routes:
- **Self-host open weights** → zero OFAC exposure (nothing paid to a US co. at render). The ONLY thing that can sit in the **live, on-demand server render**.
- **Acquire-once via a non-Iran intermediary** → batch-generate clips → **vendor the MP4** under the existing `assets.json` licence firewall (the *output* licence is perpetual; the *service* access is not). Exactly the asset/audio-library pattern.

## The architecture (this is the whole answer)
An AI clip is **never the template** — it's **moving wallpaper**. Three layers:
```
L1  BACKDROP   baked AI clip / textured render / Lottie  (no editable text)
L2  EDITABLE   text · logo · colours · images  → Remotion inputProps / AE bind.jsx
L3  RENDER     composite → MP4 (Remotion OffthreadVideo or Three VideoTexture; AE footage layer)
```
Rules: bake backdrops at the comp's fps/aspect; keep them **dark/low-contrast/abstract** so editable type stays legible; **colour lives in the overlay, not the AI footage**. This is how premium + editability coexist — and it maps onto our two engines directly.

## Per style — the recommended approach
| Style | Approach | Tools |
|---|---|---|
| **Stop-motion** | Frame-step ("on twos" / posterizeTime / reduced fps) + per-frame jitter + paper/grain overlay. Pika's first/last-frame keying is "stop-motion-native". | **Remotion code (free)** · Blender (grease pencil / sim) · Pika (acquire-once) · Wan 2.2 LoRA |
| **Paper-cut** | Layered Z-planes + **real cast shadows** + depth in @remotion/three; CC0 paper **normal/displacement maps**; SVG feTurbulence for organic edges. | **@remotion/three (free)** · ambientCG / Poly Haven (CC0) · Recraft (paper-cut image gen) |
| **Premium motion** | A shared **finish pass** (film grain + DOF + bloom + **LUT colour grade**) + **HDRI lighting** + artist **Lottie** + custom illustration. | **@react-three/postprocessing (free)** · Poly Haven HDRI · **@remotion/lottie** · FLUX+LoRA |

## The tool stack (priority order)
**Free + Iran-safe (do first — biggest ROI, zero licensing/OFAC risk, in our engine):**
1. **`@remotion/lottie`** + **`@remotion/paths`** — artist-made Lottie animations + path morphing. (lottie still NOT installed — flagged repeatedly.)
2. **Craft primitives** — a reusable kit: frame-stepping, jitter, paper-cut planes+shadows, grain.
3. **`@react-three/postprocessing` finish pass** — grain/DOF/bloom/vignette + LUT. One shared component lifts *everything*.
4. **CC0 PBR textures + HDRI** — ambientCG, Poly Haven (paper, cardboard, fabric, light leaks, lighting).

**Self-host (Iran-safe, GPU needed — the live-render upgrade):**
5. **FLUX + LoRA** (image) / **SDXL** — generate style-locked per-scene illustration; LoRA locks a paper-cut/clay/brand style. Permissive licences, runs offline.
6. **Wan 2.2** (Alibaba, **Apache-2.0**, video, ~RTX 4090) — **the only video model that can be in the live pipeline from Iran**; I2V from your own style still; LoRA-trainable.
7. **Blender** (free) — grease pencil 2D, paper-cut rigs, stop-motion sims; render → backdrop.

**Acquire-once via non-Iran intermediary (premium hero clips only, vendor the MP4):**
8. **Kling** (best stylized I2V from a still) · **Seedance 2.0** (best multi-ref consistency — up to 9 refs) · **Pika** (keyframe stop-motion). Paid plans grant commercial use; vendor outputs + ledger them. (Kling retains a backdoor licence to your generated content — fine for backdrops.)

**Reference-only / blocked:** Adobe Firefly, OpenAI/Sora (OFAC + payment); Envato/Storyblocks AE packs (redistribution/competing-service clauses + payment).

## Consistency lever (critical for multi-scene)
**Image-to-video + reference images**, not text-to-video — animate *your* style-locked still so the model never reinvents the look. **LoRA** training locks a character/style across scenes. Seed every scene from the same reference.

## Trends to ride (2025–2026)
Craft revival (stop-motion/paper-cut **as luxury**) · the **baked-backdrop + editable-overlay** pattern · **I2V + reference** for consistency · **self-hosted open weights** (sovereignty + Iran) · **LoRA + seed** style-lock · a **centralized finish pass**.

## Phased plan
- **P0** — install `@remotion/lottie` + `@remotion/paths`. (free, immediate)
- **P1** — build the **craft-primitives kit** (frame-step, jitter, paper-cut planes, grain). (free)
- **P2** — a shared **FinishPass** (postprocessing + LUT). (free)
- **P3** — vendor **CC0 PBR textures + HDRI** (ambientCG / Poly Haven). (free, VPN fetch)
- **P4** — curate + vendor **Lottie / asset packs** behind the licence gate.
- **P5** — stand up **FLUX + LoRA** self-host for style-locked illustration. (GPU)
- **P6** — the **backdrop architecture** end-to-end (AI/asset clip → editable AE/Remotion overlay → render cache).
- **P7** — self-host **Wan 2.2** (video) + **Blender** (stop-motion/paper-cut sims). (GPU)

**Bottom line:** P0–P3 are free, Iran-safe, in our existing Remotion engine, and raise
quality immediately. The AI tier (P5–P7) is a **self-hosted-weights** play because of
OFAC — Wan 2.2 + FLUX are the sovereignty path; hosted models are acquire-once-and-vendor.