feat(payment): admin-editable ZarinPal settings + in-panel test payment

Lets the broker's ZarinPal merchant / sandbox / amount-unit be set from Admin → درگاه پرداخت (persisted in payment.settings) instead of env + redeploy, and adds a per-app "test payment" button that mints a real ZarinPal StartPay link straight from the panel — no site wiring needed. - migration 33_payment_settings.sql: singleton payment.settings + a transactions.is_test column. (33, not 32 — 32 is content_render_engine.) - broker read-path precedence: per-client override > DB settings > env. - POST /v1/admin/clients/:id/test-payment + GET/PUT /v1/admin/settings. - admin UI: «تنظیمات زرین‌پال» tab + «پرداخت آزمایشی» button. Adversarial-review fixes (2 confirmed HIGH): - do NOT pre-seed the settings row — a seeded sandbox=TRUE default would override a production ZARINPAL_SANDBOX=false env and silently route real payments to sandbox.zarinpal.com until an admin untouched the toggle. No row → env governs until an admin saves. - test transactions are tagged is_test and the webhook dispatcher skips them, so an admin smoke-test can never notify (or credit) a real client, regardless of metadata. Broker-authoritative, not consumer-dependent. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
fix(payment): send result redirects to the frontend + add /payment/result page
2026-06-26 00:47:10 +03:30 · 2026-06-25 13:17:21 +03:30 · 2026-06-25 12:46:53 +03:30 · 2026-06-25 12:11:27 +03:30 · 2026-06-25 11:31:56 +03:30 · 2026-06-25 10:51:12 +03:30
2339 changed files with 925728 additions and 749 deletions
@@ -0,0 +1,89 @@
 ---
 name: flat-artist
 description: >-
  The master entry point and professional motion-design persona for creating FlatRender video
  templates with Remotion + Three.js. INVOKE THIS FIRST whenever you start, design, build, review,
  or seed a FlatRender template — or whenever "Flat Artist", "flatrender template", "بساز/طراحی قالب",
  a new logo reveal / promo / greeting / intro, or any template work is mentioned. It activates the
  whole template-creation skill suite (design, animation, characters, aspect ratios, composition,
  color/SVG, fonts, hooks, transitions, effects, music, SFX, assets, SEO) as ONE professional
  pipeline and tells you which sub-skill to apply at each step, to a Renderforest / After-Effects
  quality bar. Persian-first.
 ---
 # Flat Artist — the FlatRender template studio
 You are **Flat Artist**: a professional motion-design artist building FlatRender templates to a
 Renderforest / After-Effects bar. When this skill is active, you ALWAYS work the full pipeline below
 and apply the sub-skills — never ship "basic". Stack: `services/remotion/` (Remotion 4 +
 `@remotion/three`, R3F v9, `gl="angle"`). Persian (fa) is canonical; English mirrors it 1:1.
 ## How to use this skill
 This skill BUNDLES the whole suite: every sub-skill is a folder beside this file, at
 `<skill-name>/SKILL.md` (relative to this `flat-artist/SKILL.md`). You don't invoke them as
 separate skills — you **read the bundled file** for the phase you're on and apply it.
 1. Read this file's pipeline + rules.
 2. At each phase, open the bundled sub-skill at **`<skill-name>/SKILL.md`** (e.g. `motion-design-principles/SKILL.md`) and apply it.
 3. The deep R&D reference is **`references/design-motion-rnd.md`** (bundled here — trends, craft, asset pipeline, masterpiece + platform playbook); consult it for art direction and the masterpiece bar.
 ## Non-negotiable rules (apply on EVERY template)
 - **Pure frames:** animate ONLY off `useCurrentFrame()`. Never `useFrame` (R3F), `Math.random()`, `Date.now()`, `setState`/`useEffect`-driven motion. Determinism via `rand(i)` (`lib/anim.ts`).
 - **3D:** `@remotion/three` only; reuse `lib/three-kit.tsx` (StudioEnv/Lights/Floor/Effects, Confetti3D); drive camera/objects from `frame`.
 - **Three real aspects:** 16:9 / 1:1 / 9:16 must **re-flow, never letterbox**. Design tall-first; branch layout with `useLayout()` + `pick(wide,square,tall)` (`lib/aspect.ts`). Verify by rendering a still in ALL THREE.
 - **Persian-first:** `FONT` (Vazirmatn), `direction:"rtl"`; split kinetic text by **word, not char**; preserve ZWNJ; Persian numerals where apt.
 - **Recolorable:** every themeable color comes from `colorSchema` props (accent/secondary/background/text in `lib/branding.ts`) — no hardcoded hex on editable elements.
 - **Editable = a prop + a seeded element:** text/logo/image keys MUST equal the Zod schema field; seed via `scripts/seed_remotion_templates.py`.
 - **Vendored assets (Iran iron rule):** every asset committed into `services/remotion/public/` + `staticFile()`; NEVER a CDN URL at render. License firewall (CC0/commercial-ok, tracked in `assets.json`).
 - **Finish it:** a masterpiece = the 8 layers below, not one big move. Render → LOOK → refine.
 ## The pipeline (work in order; read the bundled skill named at each step)
 | # | Phase | Apply skill |
 |---|---|---|
 | 0 | **Scope & storyboard** — pick the template TYPE/pattern; confirm a storyboard with the user before building anything character- or scene-heavy | `remotion-template-catalog/SKILL.md` |
 | 1 | **Art direction** — choose ONE coherent style + palette from current trends | `remotion-design-styles/SKILL.md` + R&D report |
 | 2 | **Hook** — design the scroll-stopping first 1–3s (it's the cover frame) | `video-hooks/SKILL.md` |
 | 3 | **Characters** (if any) — build/rig from SVG or 3D primitives | `remotion-character-design/SKILL.md` |
 | 4 | **Build the composition** — lib helpers + `three-kit` for 3D | (this skill) |
 | 5 | **Motion** — easing/timing/stagger/secondary motion (the foundation) | `motion-design-principles/SKILL.md` |
 | 6 | **Kinetic type** — animate the hero/caption text (Persian word-split) | `kinetic-typography/SKILL.md` |
 | 7 | **Transitions** — scene-to-scene choreography, seamless | `scene-transitions/SKILL.md` |
 | 8 | **Effects** — grain, bokeh, light-leaks, sparkles, glow, vignette (deterministic) | `particles-and-effects/SKILL.md` |
 | 9 | **Aspect re-flow** — make it truly fit 16:9/1:1/9:16 | `remotion-aspect-ratios/SKILL.md` |
 | 10 | **Composition & elements** — hierarchy, logo/image/copy, reveal pacing | `remotion-template-composition/SKILL.md` |
 | 11 | **Color / live recolor** — wire color props + SVG color preview | `remotion-svg-colors/SKILL.md` |
 | 12 | **Fonts** — pick Persian-first type by role | `persian-fonts/SKILL.md` |
 | 13 | **Assets / footage** — source, license, prepare, composite | `asset-sourcing/SKILL.md` |
 | 14 | **Music + SFX** — beat-sync reveals, place SFX, duck | `remotion-music-picker/SKILL.md` + `remotion-sound-effects/SKILL.md` |
 | 15 | **QA — masterpiece gate** — the 8 layers + pre-ship checklist (below) | (this skill) |
 | 16 | **SEO & taxonomy** — category, tags, keywords, slug, copy, related | `flatrender-template-seo/SKILL.md` |
 | 17 | **Ship** — render 3 thumbnails + preview, seed, deploy (copy assets into the running container + restart so Next re-scans `public/`) | (this skill) |
 ## The masterpiece bar (8 production-value layers — finish ALL)
 1. Sound design + beat-sync (hero on a downbeat; whoosh/thump/sparkle/riser; ducking; silence before the hero hit).
 2. Micro-detail (no linear easing; overshoot & settle; 2–5f staggered entrances; secondary motion; anticipation).
 3. Design system (one type scale, one spacing rhythm, constrained palette, consistent radii/strokes/elevation).
 4. Depth & lighting (parallax layers, one consistent light direction, atmospheric bg blur, rim light on hero).
 5. Color grade (one unifying grade over the whole comp; user hex still passes through it).
 6. Pacing/rhythm (vary cut length, build to a climax, trim ruthlessly).
 7. A clear hero moment (one peak with the biggest motion + strongest hit).
 8. Finishing texture (subtle grain, gentle vignette, 1–2px chromatic aberration at impacts, tiny continuous camera drift, motion blur on fast elements).
 ## Pre-ship checklist (if you can't tick it, it's not done)
 - [ ] No linear easing; staggered entrances; ≥1 overshoot-and-settle; nothing pops on/off without a transition.
 - [ ] Verified in 16:9 / 1:1 / 9:16 (re-flowed, not letterboxed); long Persian text doesn't crop; short text doesn't look empty.
 - [ ] Hook lands in the first 1–2s; first frame works as the cover.
 - [ ] One unmistakable hero moment; consistent light direction + a unifying grade.
 - [ ] Subtle grain/vignette; frame feels alive; (audio: beat-synced + ducked if present).
 - [ ] All editable fields (text/logo/image/colors) swap without breaking layout; colors from props.
 - [ ] Clean render at target res (no flicker/z-fighting/font fallback); assets vendored + licensed.
 - [ ] Category/tags/keywords/slug + fa+en copy set (`flatrender-template-seo/SKILL.md`).
 ## Project map
 - Compositions: `services/remotion/src/compositions/`, registered in `src/templates.tsx` (`TemplateDef`, all 3 aspects).
 - Helpers: `lib/anim.ts`, `lib/aspect.ts` (`useLayout`/`pick`), `lib/branding.ts` (`colorSchema`/`BRAND`), `lib/fonts.ts` (`FONT`), `lib/three-kit.tsx`.
 - Seed: `scripts/seed_remotion_templates.py` (containers/projects/scenes/colors + `MEDIA` for image fields).
 - Render checks: `npx remotion still src/index.ts "<Comp>-16x9|1x1|9x16" out/x.png --frame=NN`.
 - Bundled here: each sub-skill at `<name>/SKILL.md`; the deep R&D at `references/design-motion-rnd.md`.
 Bundled sub-skills (read each at its `SKILL.md`): `remotion-template-catalog/SKILL.md`, `remotion-design-styles/SKILL.md`, `video-hooks/SKILL.md`, `remotion-character-design/SKILL.md`, `motion-design-principles/SKILL.md`, `kinetic-typography/SKILL.md`, `scene-transitions/SKILL.md`, `particles-and-effects/SKILL.md`, `remotion-aspect-ratios/SKILL.md`, `remotion-template-composition/SKILL.md`, `remotion-svg-colors/SKILL.md`, `persian-fonts/SKILL.md`, `asset-sourcing/SKILL.md`, `remotion-music-picker/SKILL.md`, `remotion-sound-effects/SKILL.md`, `flatrender-template-seo/SKILL.md`.
@@ -0,0 +1,95 @@
 ---
 name: asset-sourcing
 description: How to source, license, AI-generate, prepare, and organize royalty-free assets (footage, images, textures, HDRIs, GLTF/GLB, icons, illustrations) for FlatRender Remotion templates — Iran-aware (geo-blocks), vendored-only, license-firewalled. Use when a template needs real media, when downloading/committing assets into public/, when grading/masking/looping footage or compositing it via Video/OffthreadVideo/Img/staticFile + Ken-Burns, or when generating bespoke assets with local AI models.
 ---
 # Asset sourcing for templates
 Project: `services/remotion/`. Helpers: `src/lib/anim.ts` (`hexToRgba`, `mixHex`, `rand`), `src/lib/aspect.ts` (`useLayout` → `isWide/isSquare/isTall`, `vmin`, `unit`), `src/lib/branding.ts` (`colorSchema`, `BRAND`), `src/lib/fonts.ts` (`FONT` = Vazirmatn, RTL), `src/lib/three-kit.tsx` (`StudioEnv/Lights/Floor/Effects`, `Confetti3D`). Render is **headless Chrome in Docker** — every value derives from `useCurrentFrame()` (never `Math.random`/`Date.now`/`useFrame`; use `rand(i)`).
 ## The Iron Rule — vendor everything
 The Iran environment punishes runtime dependencies. **Download once (VPN if needed), commit into `public/`, reference with `staticFile()`.** Never put `https://…` in a shipped template — a geo-block or flaky tunnel kills the render mid-frame. Mirror npm/NuGet/Docker via Nexus (`mirror.soroushasadi.com`); asset *binaries* are sourced by hand. **Record the license at acquisition time, not later.** `public/` today holds only `fonts/` — you build the rest.
 ## License taxonomy (know cold — this is the firewall)
 | Class | Examples | Ship? |
 |---|---|---|
 | CC0 / Public Domain / Pixabay / Pexels / Unsplash | Poly Haven, ambientCG, Kenney, Mixkit | ✅ free, no credit — **default target** |
 | CC-BY | many Sketchfab, Bensound | ⚠️ ship only with a tracked on-screen/end-card credit |
 | CC-BY-SA | some Wikimedia | ❌ share-alike can infect our proprietary template |
 | CC-BY-NC | "free for personal" tiers | ❌ we are a **paid** product = commercial |
 | Editorial / rights-managed | news/celebrity stock | ❌ |
 | Paid stock | Envato, Adobe, Shutterstock | ✅ per license — **keep the receipt/PDF** |
 No license row = unknown license = **do not ship**.
 ## Sourcing map (CC0 / no-attribution first) + Iran access
 | Type | Best CC0 sources | Commit to | Iran access |
 |---|---|---|---|
 | Footage (H.264 MP4, right-sized) | Pexels Video, Pixabay Video, Mixkit, Coverr, Videvo (filter CC0) | `public/footage/{nature,business,abstract}/` | Pixabay/Mixkit/Coverr OK; Pexels VPN-ish |
 | Images | Pexels, Pixabay, Unsplash, StockSnap, Burst | `public/images/` | Pixabay OK; Pexels/Unsplash VPN-ish |
 | Textures / overlays | Poly Haven, ambientCG; grain/light-leak/dust CC0 clips | `public/textures/`, `public/overlays/` | OK |
 | HDRIs (1k–2k for render speed) | Poly Haven, ambientCG | `public/hdri/` | OK |
 | 3D (**prefer GLB** over glTF+textures) | Poly Haven Models, Kenney, Khronos glTF samples, Sketchfab (check each) | `public/models/` | Poly Haven OK; Sketchfab VPN-ish |
 | Icons (bundle via Nexus npm, **never CDN**) | Lucide, Tabler, Heroicons, Phosphor | npm dep | npm via Nexus OK |
 | Illustrations (recolorable **SVG**) | unDraw, Open Peeps, Humaaans | `public/illustrations/` | OK |
 For Persian/Iran imagery search English terms ("Tehran", "Iranian food") + self-shot/local stock. **Sanction-blocked at account/payment: Adobe Stock, Envato** — use a foreign account/partner or skip. **Mitigation: do one batched "asset run" over a stable tunnel, commit binaries, render never touches the open internet again.** Draco-compress GLBs (`gltf-pipeline -i in.glb -o out.glb -d`), keep low-poly for headless render speed.
 ## AI-generated assets — when it's right
 - **Use when:** the asset doesn't exist as stock (specific Persian cultural scene, branded mascot), you need consistency across a template set (reference-image control), or it beats a 5-site license hunt.
 - **Don't when:** clean CC0 already exists, you need photographic authenticity, or a free tier's **commercial license is unclear** (watermarks / non-commercial = legal landmine for a paid product).
 - **Iran-pragmatic:** self-host open models — **HunyuanVideo 1.5** (~RTX 4090, no geo-block/payment/watermark) for video; **FLUX/SDXL** locally for image/texture/illustration. Hosted SaaS (Runway, Kling) only when local quality falls short and a VPN+foreign-account path exists. **Always record prompt + tool + plan-tier + date** in the asset's `.license.txt` sidecar.
 ## Preparing footage in Remotion (composite, grade, mask, loop)
 **Primitives:** `<OffthreadVideo>` = default for **all** video in a render (FFmpeg extraction, deterministic, no seek drift). `<Video>` = preview only. `<Img>` over raw `<img>` (waits for load → no half-loaded frames). `staticFile()` for every vendored asset.
 ```tsx
 import { OffthreadVideo, Img, staticFile, useCurrentFrame, interpolate, Easing } from "remotion";
 import { useLayout } from "./lib/aspect";
 const frame = useCurrentFrame();
 const L = useLayout();
 // Ken-Burns: overscan ≥1 so no edges reveal; cover + center crops cleanly in all 3 aspects.
 const scale = interpolate(frame, [0, 150], [1.08, 1.2], { extrapolateRight: "clamp" });
 const ty = interpolate(frame, [0, 150], [0, L.vmin(-30)], { easing: Easing.out(Easing.cubic), extrapolateRight: "clamp" });
 <OffthreadVideo
  src={staticFile("footage/nature/forest-loop.mp4")}
  style={{ width: "100%", height: "100%", objectFit: "cover",
           transform: `scale(${scale}) translateY(${ty}px)`,
           filter: "contrast(1.08) saturate(1.15) brightness(0.96)" }} // grade
 />
 ```
 | Job | Pattern |
 |---|---|
 | **Color grade** | per-layer CSS `filter` (`contrast/saturate/brightness/hue-rotate`); build a shared `lib/grades.ts` (`warm`, `teal-orange`, `mono`, `filmic`) so palette can drive `hue-rotate`/`saturate`. Heavy grade → pre-grade in DaVinci Resolve (free), then commit. |
 | **Masking / keying** | no native keyer — pre-key in Resolve/AE, export **alpha** (ProRes 4444 or WebM/VP9 alpha), then `<OffthreadVideo>`. Shape masks via CSS `maskImage`/`clipPath` + `hexToRgba` gradients, or SVG `<mask>`. |
 | **Seamless loop** | source loop-designed clips (Coverr/Mixkit) or mirror-pingpong; `<OffthreadVideo loop>` once first/last frames match; crossfade-to-self with overlapping `<Sequence>` for imperfect footage. |
 | **Overlays (cheap "authentic" layer)** | stack grayscale-on-black/white clips: **screen** for light-leaks/bokeh/dust, **overlay/soft-light** for grain, **multiply** for vignettes/paper. Keep palette-independent. **Animated grain must move** — offset `background-position` per frame or jitter SVG `feTurbulence` `seed`. |
 | **Per-aspect crop** | `objectFit:"cover"` + center-safe framing; branch focal point on `L.isWide/isSquare/isTall` (or the proposed `L.pick(wide,square,tall)`) so the subject never crops out. |
 HDRIs/GLBs: feed `staticFile("hdri/…")` into `three-kit`'s `StudioEnv`; load models with `useGLTF(staticFile("models/…glb"))`, idle-bob with `Math.sin(frame/fps)` (driven by `useCurrentFrame`, **not** `useFrame`).
 ## Library structure + attribution firewall
 Create under `public/`: `footage/{nature,business,abstract}/`, `overlays/`, `images/`, `textures/`, `hdri/`, `models/`, `icons/`, `illustrations/`, plus **`assets.json`** + **`ASSETS.md`**. Lowercase-kebab names, no spaces. Every asset gets one `assets.json` row **at download time**:
 ```json
 { "file": "footage/nature/forest-loop.mp4", "source": "Pexels",
  "url": "https://www.pexels.com/video/...", "author": "Name",
  "license": "Pexels", "attribution_required": false, "commercial_ok": true,
  "acquired": "2026-06-21", "notes": "1080p H.264, loops clean" }
 ```
 Sidecar `.license.txt` next to AI assets (prompt + tool + date) and paid receipts. A **CI validation script** asserts every file in the media folders has a matching row with `commercial_ok:true`, else fails the build — this is the firewall. `ASSETS.md` is the generated human/legal-readable table. `attribution_required:true` must surface a credit on a shippable surface (end-card/footer). If the repo bloats, move large media to MinIO (already in stack) with a `predeploy` sync into `public/` — but present at render time.
 ## Checklist (before committing an asset / shipping a template)
 - [ ] Vendored in `public/…` and referenced via `staticFile()` — **no external URL** anywhere in the template.
 - [ ] `assets.json` row added with `commercial_ok:true`; `.license.txt`/receipt for AI/paid; CC-BY credits surfaced.
 - [ ] Right-sized (don't ship 4K into a 1080p comp); video is H.264 MP4 played via `<OffthreadVideo>`; images via `<Img>`.
 - [ ] GLB (not glTF+loose textures), Draco-compressed, low-poly; HDRI 1k–2k.
 - [ ] Footage graded through `lib/grades.ts`; overlay grain/light-leak **moves** per frame; loops are seamless.
 - [ ] Ken-Burns overscans (start scale ≥ 1.05) and `objectFit:cover` crops cleanly in 16:9 / 1:1 / 9:16 with subject in frame.
 - [ ] Re-render twice → identical (deterministic; nothing pulled from network/random/date).
 Related: `../remotion-design-styles/SKILL.md`, `../remotion-template-composition/SKILL.md`, `../remotion-aspect-ratios/SKILL.md`, `../remotion-character-design/SKILL.md`, `../remotion-svg-colors/SKILL.md`, `../remotion-music-picker/SKILL.md`, `../remotion-sound-effects/SKILL.md`, `../persian-fonts/SKILL.md`, `../flatrender-template-seo/SKILL.md`.
@@ -0,0 +1,171 @@
 ---
 name: flatrender-template-seo
 description: >-
  Classifies and merchandises a FlatRender video template when an admin or developer creates or
  publishes it. Decides the single primary category, the faceted tags, the SEO title/description/
  keywords/slug, the Persian-first presentation copy, and the related-templates set — every choice
  driven by the template's actual design, editable content, and usability. Use whenever creating,
  editing, publishing, or seeding a template (project_container) and you must fill category_ids,
  tag_ids, keywords, slug, description, news_text, or write its catalog/detail copy. Persian (fa) is
  the source of truth; English (en) mirrors it 1:1.
 ---
 # FlatRender Template SEO & Taxonomy
 Decide a template's category, tags, SEO, presentation copy, and related set — grounded in what the
 template *actually is*, not what you wish it ranked for. **fa is canonical; en mirrors it.**
 ## When to use
 - An admin creates/edits a template in `TemplatesAdmin.tsx`, or you set fields on `content.project_containers`.
 - You run/extend `scripts/seed_remotion_templates.py` (which currently leaves SEO + taxonomy EMPTY — see below).
 - You publish (`is_published = true`) and need the template to be findable and well-presented.
 Cross-reference: `../remotion-template-catalog/SKILL.md` (template TYPE → pattern), `../remotion-template-composition/SKILL.md`
 (what's editable, used to write "what you can customize"), `../persian-fonts/SKILL.md` (RTL copy & Persian numerals).
 ## The real data model (use these exact names — do not invent fields)
 Template = `content.project_containers`. Admin sets via `TemplatesAdmin.tsx` → `POST/PUT /v1/templates`
 (`Create/UpdateContainerRequest`). Settable, SEO/taxonomy-relevant fields:
 | Purpose | Admin label | form key | DTO | DB column |
 |---|---|---|---|---|
 | Name (→ H1) | نام | `name` | `Name` | `name` |
 | Slug | اسلاگ | `slug` | `Slug` | `slug` (CITEXT UNIQUE) |
 | Description / presentation copy | توضیحات | `description` | `Description` | `description` |
 | Keywords (opaque free text) | کلمات کلیدی (سئو) | `keywords` | `Keywords` | `keywords` (TEXT) |
 | Announcement (NOT seo) | متن خبر | `news_text` | `NewsText` | `news_text` |
 | Categories (M2M) | دسته‌بندی‌ها | `category_ids[]` | `CategoryIds` | `container_categories` |
 | Tags (M2M) | برچسب‌ها | `tag_ids[]` | `TagIds` | `container_tags` |
 | Primary mode | حالت اصلی | `primary_mode` | `PrimaryMode` | `primary_mode` enum |
 **Hard constraints from the platform (work within these):**
 - **No `meta_title` / `meta_description` on a template.** The only SEO string on a container is `keywords`.
  Per-page `meta_title`/`meta_description`/`meta_keywords`/`bot_follow` exist ONLY on `content.categories`
  (and on `blogs`). Workaround: put the page's discoverable meta intent into `keywords`; pack the human
  title/description into `name` + `description`; lift the rest of the meta from the **assigned category's**
  `meta_*` fields (so choose the category deliberately — its SEO is inherited).
 - **The public detail page emits title-only metadata** (`templates/[id]/page.tsx` → `{ title: "${name} — FlatRender" }`),
  and the public mapper (`admin-api.ts` `containerToAdminProject`) DROPS `keywords`, `coverImageUrl`→OG, and
  hardcodes `categoryName: undefined`. So today your `keywords`/category never reach the public `<head>`.
  Still fill them: they power the backend list filters and are the fix-point when the frontend SEO gap is closed.
  When you can, also fix the mapper to surface `keywords` + cover OG; otherwise flag it.
 - **No related-templates table/column/endpoint exists.** "Related" is computed by re-querying
  `GET /v1/templates?categoryId={guid}` or `?tagSlug={slug}` and excluding the current template.
  There is no precomputed set — pick the category/tags such that this query returns good neighbors.
 - **Tags are not shown anywhere in the templates UI** today, and the list page ignores the real DB
  categories: the sidebar is ~12 hardcoded buckets (11 real categories + `"all"`), and because the
  public mapper hardcodes `categoryName: undefined`, every template defaults to `"social"`. Tags/categories
  still matter for the backend filters and future UI — set them correctly regardless.
 - `demo_script_tag` exists in DB + DTO but is NOT in the admin form — you cannot set it there.
 - Categories are a tree (`parent_id`); `GET /v1/categories` only eager-loads one child level. Keep the
  primary set flat (8–12). Tags have `applies_to_mode`; categories do not.
 ## Step-by-step decision process
 Run this for every template, in order. Each step feeds the next.
 **0. Read the design + content + usability.** What does it output (format)? What's editable (text/colors/
 logo/images/music — from `../remotion-template-composition/SKILL.md`)? Who hires it and when? 2D or 3D (real Remotion
 build: SVG vs `@remotion/three`)? Which aspects exist (16:9 / 1:1 / 9:16 child projects)?
 **1. Category — pick exactly ONE primary.** Category = the *output format*, never the occasion/industry.
 Test: which single shelf would a user expect this on? If the answer is a format (logo reveal, story, slideshow)
 it's the category; if it's when/why/who (Nowruz, real estate, teens) that's a TAG. Use the flat set:
 اینترو و لوگو / Intro & Logo · استوری و ریلز / Story & Reels · پست شبکه اجتماعی / Social Post ·
 تبلیغ و پروموشن / Promo & Ad · اسلایدشو / Slideshow · معرفی محصول / Product Showcase ·
 دعوت‌نامه و مناسبت / Invitation & Event · تیتراژ و زیرنویس / Titles & Lower-thirds ·
 ارائه و اینفوگرافیک / Presentation & Infographic · یوتیوب و اینترو کانال / YouTube & Channel.
 No "Other"; no category with <5 templates. → set `category_ids` (the primary first; its `sort` = index 0).
 **2. Tags — 6–12, from a controlled fa↔en vocabulary**, each TRUE of this design, across facets:
 use-case · occasion · industry · style/aesthetic · aspect ratio · color/mood · 2D-3D · audience.
 Empty facets are fine — don't invent tags. Aspect ratio is a TAG (one template, three outputs), never a
 separate catalog entry. Tag 3D only if it really renders 3D. Reuse existing `content.tags` (match by
 `slug`/`latin_name`); create a new tag only as a deliberate dictionary edit. → set `tag_ids`.
 **3. SEO title / description / keywords / slug.**
 - **Title** (lives in `name`): `{Template Name} | {Category} {use/occasion}`. Keep the keyword in the
  first ~30 chars (Persian runs long); brand is appended by the layout, don't double it.
 - **Description** (lives in `description`, also reused as presentation copy): benefit + what + how-to-edit +
  soft CTA. fa 120–155 / en 120–158 chars. One natural keyword, no stuffing.
 - **Keywords** (lives in `keywords`): how Iranians actually search — «قالب آماده», «ساخت/دانلود استوری»,
  «تیزر تبلیغاتی», «اینترو لوگو» — include loanword + Persian spelling both ways (استوری/Story, اینترو/Intro).
  1 primary + 2–3 secondaries. Note: `keywords` is an opaque free-text column — the platform does NOT
  tokenize, split, index, or search on it (no comma parsing anywhere in form or backend). Commas are
  purely an authoring convention for human readability; write it however reads cleanest.
 - **Slug** (`slug`): the slugifier KEEPS Persian (no transliteration). Prefer a curated **latin/transliterated**
  keyword slug for shareable URLs (Persian slugs become `%D9%82...` when copied). Lowercase, hyphenated, short,
  keyword-bearing. Never change a published slug.
 **4. Presentation copy** (write into `description`; structure it so it doubles as SEO + usability):
 H1 = human Persian `name` → one-line benefit hook → "این قالب برای چیست؟" (use-case+occasion+audience) →
 "چه چیزهایی قابل تغییر است؟" (bullet the REAL editable fields — don't claim editable music if there's none) →
 "چطور بسازم؟" (انتخاب → ویرایش متن/رنگ → دانلود) → spec strip (aspects, duration, 2D/3D). Benefit before
 feature; second person; every claim true of THIS template.
 **5. Related set** (caller-computed; pick category/tags so this works). Query
 `GET /v1/templates?categoryId=...` then `?tagSlug=...`; rank occasion > category+use-case > style > industry;
 show 6–8; **exclude this template's own aspect siblings** (dedupe by template id); cap same-style clones;
 label pack-mates «از همین مجموعه».
 ## fa / en parity & RTL rules
 - Fill fa first, then en as a faithful mirror. Two self-consistent pages — never a Persian page with an
  English title. Same template id; localized labels resolve per current locale.
 - Persian uses Vazirmatn / RTL (see `../persian-fonts/SKILL.md`); use Persian digits in user-facing copy; don't fight the
  `[dir="rtl"]` block. Tag/category *slugs* stay latin for stability; *display names* are localized.
 - hreflang fa↔en + x-default is the right target even though the detail page doesn't emit it yet — flag the gap.
 ## Worked examples
 **A. Nowruz 3D greeting (تبریک نوروز سه‌بعدی)**
 - Category: `دعوت‌نامه و مناسبت / Invitation & Event`.
 - Tags: occasion=نوروز/Nowruz · use-case=تبریک/greeting · style=لاکچری/luxury · 2D-3D=سه‌بعدی/3D ·
  aspect=۹:۱۶,۱:۱,۱۶:۹ · color=طلایی/gold · audience=کسب‌وکار کوچک/small business.
 - name (fa): «قالب تبریک نوروز سه‌بعدی | مناسبت و تبریک»  · (en): "Nowruz 3D Greeting Template | Invitation & Event"
 - description (fa): «کارت تبریک نوروزی سه‌بعدی و لاکچری؛ نام برند، متن تبریک و رنگ طلایی را در چند دقیقه شخصی‌سازی کن و ویدیوی آماده انتشار بساز.»
 - keywords: `قالب تبریک نوروز, تبریک عید, نوروز سه بعدی, دانلود کارت تبریک, Nowruz greeting`
 - slug: `nowruz-3d-greeting` · Related: other نوروز items first, then Invitation & Event + greeting.
 **B. Instagram sale promo (پروموشن فروش ویژه اینستاگرام)**
 - Category: `استوری و ریلز / Story & Reels` (output is a 9:16 vertical — format wins over "sale").
 - Tags: use-case=فروش ویژه/flash sale · industry=فروشگاه آنلاین/e-shop · style=نئون/neon · aspect=عمودی ۹:۱۶/vertical ·
  color=انرژیک/energetic · audience=فروشگاه/store · 2D.
 - name (fa): «قالب استوری فروش ویژه | استوری و ریلز» · (en): "Flash-Sale Story Template | Story & Reels"
 - description (fa): «قالب آماده استوری برای اعلام تخفیف و فروش ویژه؛ متن، قیمت، رنگ و لوگوی فروشگاهت را جایگزین کن و استوری حرفه‌ای ۹:۱۶ بساز.»
 - keywords: `قالب استوری فروش, تخفیف اینستاگرام, ساخت استوری تبلیغاتی, دانلود قالب استوری, flash sale reels`
 - slug: `instagram-flash-sale-story` · Related: same use-case (flash sale) across categories, then Story & Reels.
 **C. Corporate logo reveal (لوگو موشن شرکتی)**
 - Category: `اینترو و لوگو / Intro & Logo`.
 - Tags: use-case=معرفی برند/brand intro · style=مینیمال/minimal · audience=شرکتی/corporate ·
  aspect=۱۶:۹,۱:۱,۹:۱۶ · color=آبی/blue · 2D (or 3D only if it truly is).
 - name (fa): «قالب لوگو موشن شرکتی | اینترو و لوگو» · (en): "Corporate Logo Reveal Template | Intro & Logo"
 - description (fa): «اینترو حرفه‌ای برای نمایش لوگوی شرکت؛ لوگو، نام برند و رنگ سازمانی را وارد کن و یک اینترو تمیز و مینیمال بساز.»
 - keywords: `لوگو موشن, اینترو لوگو, ساخت اینترو, لوگو موشن شرکتی, logo motion intro`
 - slug: `corporate-logo-reveal` · Related: other Intro & Logo + brand-intro use-case.
 ## Where each value goes
 - **Admin UI** (`TemplatesAdmin.tsx`): name→`name`, slug→`slug`, presentation copy→`description`,
  SEO keywords→`keywords`, categories→`category_ids` (multi-select chips), tags→`tag_ids`, mode→`primary_mode`.
  Saves via `/api/admin/resource/templates` → `/v1/templates`.
 - **Categories/Tags** are managed on their own admin pages (`admin-resources.tsx` → `/v1/categories`, `/v1/tags`);
  category-level `meta_title`/`meta_description`/`meta_keywords`/`bot_follow` live there — set them once per category.
 - **Seeder** (`scripts/seed_remotion_templates.py`): currently SETS only `name/slug/description/image/demo*/
  is_published/primary_mode/sort` and inserts ZERO `container_categories` / `container_tags` and NO `keywords`.
  To seed SEO+taxonomy: add `keywords` to the `project_containers` INSERT, and add INSERTs into
  `content.container_categories` (with `sort` = index) and `content.container_tags`. Otherwise each seeded
  template ships with no keywords, no category, no tags — invisible to backend category/tag filters until an
  admin opens it and assigns them.
 ## Final checklist
 - [ ] Exactly ONE primary category, format-based, from the flat set → `category_ids` (primary at index 0).
 - [ ] 6–12 tags, controlled fa↔en vocab, each true of the design, across facets; aspect is a tag → `tag_ids`.
 - [ ] `name` carries the SEO title (keyword in first ~30 chars; no doubled brand).
 - [ ] `description` = benefit→for-what→customize(real fields)→how-to→specs; doubles as the meta description.
 - [ ] `keywords` = 1 primary + 2–3 secondary, loanword + Persian spelling (free text — commas are just an authoring convention, not parsed).
 - [ ] `slug` = curated latin keyword slug, stable, never changed after publish.
 - [ ] fa filled first, en a 1:1 mirror; Persian digits + RTL in copy.
 - [ ] Related works via category/tag query; own aspect siblings excluded.
 - [ ] Gaps flagged: no template `meta_*`, public mapper drops `keywords`/cover OG/category, no related table,
      no hreflang on detail page — note these where relevant rather than pretending they're set.
@@ -0,0 +1,95 @@
 ---
 name: kinetic-typography
 description: How to build animated-text systems for FlatRender Remotion templates — word/line/char reveals, mask wipes, typewriter, scale-pops, highlight sweeps, text-on-path, and number counters — Persian/RTL-aware and reusable. Use whenever a template's hero, caption, quote, title, price, or any text is the thing that moves. Persian is the priority; split by WORD, never by character.
 ---
 # Kinetic typography (animated text systems)
 Type is a first-class motion element here, not a label. A masterpiece text shot is ~5 layers: the right split, eased per-unit timing, a hold sized to a real read, legibility over the background, and a single hero word. Amateurs stop at "the text fades in."
 ## The one rule
 Every value is a pure function of `useCurrentFrame()`. **Never** `useFrame`, `Math.random()`, `Date.now()`, `setState`, or `useEffect`-driven motion — the headless renderer samples frames out of order. For "random" jitter use `rand(seed)` from `lib/anim.ts`. Drive timing off `useVideoConfig().fps`; define `const sec = (s: number) => Math.round(s * fps)` — never hardcode `30`.
 ## Persian / RTL — get this right first (it's an Iran-facing product)
 - **Split by WORD, not character.** Persian script is connected/cursive — splitting on chars shatters letterforms and joins. Latin char-reveals are fine; Persian is word- or line-only. A safe split is `text.split(/\s+/).filter(Boolean)` — this **preserves ZWNJ** (نیم‌فاصله, `‌`) inside words like «می‌شود» because ZWNJ is not whitespace. Never `.split("")` or `.replace(/‌/g, …)` on Persian.
 - Every text node: `fontFamily: FONT` (Vazirmatn, from `lib/fonts.ts`), `direction: "rtl"`, align right or center. The existing `KineticQuote.tsx` hardcodes Georgia/serif + pixel sizes + no RTL — **do not copy that**; it's a Latin-only relic.
 - Persian needs weight (headings 700–900) and `lineHeight: 1.4–1.6`. Numerals: pick Persian (۱۲۳ via `toLocaleString('fa-IR')`) or Latin and stay consistent; prices/years are usually Persian digits. See `../persian-fonts/SKILL.md`.
 - For RTL word reveals, the wrapping container does the ordering — keep `flexWrap: "wrap"` + `direction: "rtl"` and let words flow; don't manually reverse the array.
 ## Size & position from layout tokens, never pixels
 Read `useLayout()` from `lib/aspect.ts`: `vmin(n)`, `unit`, `isWide/isSquare/isTall`. Hero type ≈ `vmin(80–110)`, body ≈ `vmin(28–40)`. Tune timing/scale per aspect — wider reads faster (tighter stagger), tall reads slower (looser). Add this `pick` helper to `Layout` (per R&D Tier-0) and use it:
 ```ts
 const pick = <T,>(w: T, s: T, t: T) => (L.isWide ? w : L.isSquare ? s : t);
 const stagger = pick(2, 3, 4); // frames between units
 ```
 ## Animation patterns (all driven by `frame - start`)
 | Pattern | Recipe | Persian-safe? |
 |---|---|---|
 | **Word reveal** (default) | split words; per word `start = i*stagger`; `spring({frame: frame-start, fps})` → `translateY(vmin)` + `opacity` | ✅ word-split |
 | **Line reveal** | wrap by line in `<Sequence>`s; each line springs up behind a `clip-path` edge | ✅ |
 | **Char reveal / scatter** | split chars, per-char delay; rotate/scale in | ❌ Latin only |
 | **Mask wipe** | `clipPath: inset(0 ${100-p}% 0 0)` (RTL: wipe from right → `0 0 0 ${100-p}%`); `p = interpolate(frame,[a,b],[0,100],{extrapolateRight:"clamp", easing: Easing.out(Easing.cubic)})` | ✅ |
 | **Typewriter** | `text.slice(0, Math.floor(interpolate(frame,[a,b],[0, words.length])))` joined — **slice by WORD for Persian**, by char only for Latin; add a blinking caret `frame % sec(0.8) < sec(0.4)` | ✅ word-slice |
 | **Scale-pop ("ta-da")** | `scale = spring({config:{damping:12,mass:0.6,stiffness:180}})` or `Easing.bezier(0.34,1.56,0.64,1)` overshoot→settle | ✅ |
 | **Highlight sweep** | gradient bar/`background-clip:text` shifting `background-position` per frame, or an accent rect growing under a key word | ✅ |
 | **Text-on-path** | SVG `<textPath href="#p">`; animate `startOffset` by frame — Latin/numeric only (RTL on a path is unreliable) | ❌ |
 | **Number counter** | `Math.round(interpolate(frame,[a,b],[0, target],{extrapolateRight:"clamp", easing: Easing.out(Easing.cubic)}))` then `toLocaleString('fa-IR')` | ✅ (format fa) |
 | **Variable-weight pulse** | Vazirmatn ships a variable axis: `fontVariationSettings: \`'wght' ${interpolate(frame,[a,b],[300,900])}\`` (needs the variable woff2 registered in `fonts.ts`) | ✅ |
 ### Reusable word-reveal component (the workhorse — Persian-correct, aspect-aware)
 ```tsx
 const RevealText: React.FC<{ text: string; start: number; color: string }> = ({ text, start, color }) => {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();
  const L = useLayout();
  const pick = <T,>(w: T, s: T, t: T) => (L.isWide ? w : L.isSquare ? s : t);
  const stagger = pick(2, 3, 4);
  const words = text.split(/\s+/).filter(Boolean); // keeps ZWNJ
  return (
    <div style={{ display: "flex", flexWrap: "wrap", justifyContent: "center",
      direction: "rtl", fontFamily: FONT, fontWeight: 800, fontSize: L.vmin(96),
      lineHeight: 1.4, color, gap: `0 ${L.vmin(18)}px`, maxWidth: "86%",
      textShadow: `0 ${L.vmin(2)}px ${L.vmin(20)}px rgba(0,0,0,.6)` }}>
      {words.map((w, i) => {
        const s = spring({ frame: frame - start - i * stagger, fps,
          config: { damping: 16, mass: 0.7, stiffness: 120 } });
        return (
          <span key={i} style={{ display: "inline-block", opacity: s,
            transform: `translateY(${interpolate(s, [0, 1], [L.vmin(28), 0])}px)` }}>
            {w}
          </span>
        );
      })}
    </div>
  );
 };
 ```
 Follow-through upgrade: give a trailing accent word a *looser* spring (`damping: 6`) so it settles last.
 ## Easing & spring (linear is the sound of an amateur)
 - Entrances → **ease-out** default (`Easing.out(Easing.cubic)`); hero titles → `Easing.bezier(0.16,1,0.3,1)`. Exits → **ease-in, sharper than the entrance**. Snappy pop → back bezier `(0.34,1.56,0.64,1)`.
 - `interpolate` for exact marks — **always `extrapolateLeft/Right: "clamp"`** (forgetting it is the #1 drift bug). `spring` for organic feel. Combine: `interpolate(spring(...), [0,1], [vmin(28), 0])`.
 - Spring cheats: clean reveal `{damping:200,mass:0.5,stiffness:200}` · default pop `{damping:12,mass:0.6,stiffness:180}` · bouncy `{damping:8,mass:1,stiffness:120}` · trailing wobble `{damping:6,mass:1,stiffness:80}`.
 ## Timing budgets (@ whatever `fps` is)
 Micro pop 8–14f · word stagger 2–4f · standard reveal 18–28f · hero entrance 28–40f · **hold = a comfortable read** (≥ `sec(0.7)` per text element before the next competes). Cut frames before adding them — over-animating reads as amateur. Anticipation: dip below start before launch (`interpolate(frame,[0,6,30],[0,-0.12,1])`).
 ## Legibility over busy / 3D / video backgrounds
 - Scrim or `textShadow: 0 0 vmin(20) rgba(0,0,0,.7)`, or a semi-transparent panel behind text.
 - Gradient text: `WebkitBackgroundClip: "text"`, transparent fill, plus a `drop-shadow` for edge separation.
 - Colors come from `colorSchema` props (`accentColor/secondaryColor/backgroundColor/textColor` via `lib/branding.ts`) — pass user hex through `mixHex`/`hexToRgba` so a garish value doesn't break the look. Never hardcode `#fff`.
 - Captions (TikTok/Reels/Shorts) = high-contrast white/yellow + black outline, lower-middle third, inside the tightest safe zone. See `../remotion-aspect-ratios/SKILL.md`.
 ## Checklist
 - [ ] Persian text split by WORD; ZWNJ preserved; `direction:"rtl"` + `fontFamily: FONT`.
 - [ ] All sizes via `vmin`/`unit`; timing/stagger via `pick(...)` per aspect — verified in 16:9, 1:1, 9:16.
 - [ ] No linear easing; ≥1 overshoot-and-settle; staggered, not all on frame 0.
 - [ ] Every `interpolate` clamps both ends; no `useFrame`/`random`/`Date.now`; `fps` not `30`.
 - [ ] Numbers formatted (`fa-IR`) and consistent; counter eases out.
 - [ ] Legible over the background (scrim/shadow); colors from props.
 - [ ] A real hold sized to reading; longest Persian string doesn't overflow, shortest doesn't look empty.
 - [ ] Re-render twice → identical pixels (deterministic).
 Related: `../remotion-template-composition/SKILL.md`, `../persian-fonts/SKILL.md`, `../remotion-aspect-ratios/SKILL.md`, `../remotion-design-styles/SKILL.md`, `../remotion-svg-colors/SKILL.md`, `../remotion-sound-effects/SKILL.md`, `../remotion-music-picker/SKILL.md`, `../flatrender-template-seo/SKILL.md`.
@@ -0,0 +1,167 @@
 ---
 name: motion-design-principles
 description: The foundation motion-craft reference for FlatRender Remotion templates — easing curves and when to reach for each, timing & spacing, the 12 animation principles applied to Remotion, anticipation/overshoot/follow-through/settle, staggering & choreography, secondary motion, spring() vs interpolate(), and the blocking→timing→polish workflow. Use whenever animating ANY element in a template, reviewing motion quality, or deciding how something should enter, move, or leave. Read this BEFORE writing animation code.
 ---
 # Motion design principles (the FlatRender craft floor)
 Project: `services/remotion/` (Remotion 4 + `@remotion/three`, R3F v9, `gl="angle"`). Three aspects (16:9 / 1:1 / 9:16), Persian-first (Vazirmatn, RTL). Helpers: `src/lib/anim.ts` (`hexToRgba`, `mixHex`, `rand`), `src/lib/aspect.ts` (`useLayout` → `isWide/isSquare/isTall`, `vmin`, `unit`, `pick`), `src/lib/branding.ts` (`colorSchema`, `BRAND`), `src/lib/fonts.ts` (`FONT` = Vazirmatn), `src/lib/three-kit.tsx` (`StudioEnv/Lights/Floor/Effects`, `Confetti3D`).
 **Linear motion is the sound of an amateur. Almost nothing in a FlatRender template should move at a constant rate.** This skill is the floor every template stands on.
 ## The one rule everything hangs on
 A Remotion frame is **pure**: `frame → pixels`, sampled at an arbitrary `t` (the After Effects mental model — a keyframe graph read at time `t`). The renderer samples frames **out of order and in parallel**.
 - Derive every value from `useCurrentFrame()`. If a value can't be, it doesn't belong in the render.
 - **Never** `useFrame` (R3F), `Math.random()`, `Date.now()`, `setState`, or `useEffect`-driven motion. For "randomness" use `rand(seed)` from `anim.ts`.
 - **Never hardcode 30fps.** `const { fps } = useVideoConfig(); const sec = (s: number) => Math.round(s * fps);`
 ## `spring()` vs `interpolate()` — pick deliberately
 | | `interpolate()` | `spring()` |
 |---|---|---|
 | Who authors the curve | **you** (explicit easing) | **physics** (mass/damping/stiffness) |
 | Reach for it when | a value must hit an exact mark on an exact frame — storyboard reveals, crossfades, value remaps, color/blur sweeps | organic entrances, pops, bounces, anything that should "feel" alive |
 | The trap | forgetting `extrapolate*: "clamp"` → elements drift off-screen / opacity goes negative | trying to land a value on an exact frame |
 **Always combine them** — spring drives the *feel* (0→1), interpolate *remaps* it to real px/units in the layout's own scale:
 ```tsx
 const L = useLayout();
 const p = spring({ frame: frame - start, fps, config: { mass: 0.6, damping: 12, stiffness: 180 } });
 const y = interpolate(p, [0, 1], [L.vmin(80), 0]);              // remap into layout units
 const opacity = interpolate(p, [0, 1], [0, 1], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
 ```
 ### Spring config cheat-sheet
 Lower `damping` = more overshoot · higher `mass` = heavier/slower · higher `stiffness` = faster snap.
 | Feel | mass | damping | stiffness | Use for |
 |---|--:|--:|--:|---|
 | Snappy, no overshoot | 0.5 | 200 | 200 | Clean UI / logo reveals |
 | **Natural pop (default)** | 0.6 | 12 | 180 | Cards, badges, icons |
 | Bouncy / playful | 1 | 8 | 120 | Kids, birthday, mascots |
 | Heavy / weighty | 2.5 | 26 | 90 | Big titles, 3D objects landing |
 | Loose wobble (follow-through) | 1 | 6 | 80 | Secondary / trailing parts |
 ## Easing cheat-sheet (`import { Easing } from "remotion"`)
 | Situation | Curve | Why |
 |---|---|---|
 | **Entrances (default)** | `Easing.out(Easing.cubic)` | things arrive and decelerate |
 | Hero title entrance | `Easing.out(Easing.quint)` or `Easing.bezier(0.16, 1, 0.3, 1)` | dramatic deceleration |
 | **Exits** | `Easing.in(Easing.cubic)` — **always sharper than the entrance** | things leave faster than they arrive |
 | A→B on-screen move / camera | `Easing.inOut(Easing.cubic)` | smooth both ends |
 | "Ta-da" overshoot | `Easing.bezier(0.34, 1.56, 0.64, 1)` | snappy pop past target |
 | Wind-up / anticipation | `Easing.bezier(0.36, 0, 0.66, -0.56)` | dips below before launch |
 | **Linear ONLY** | `Easing.linear` | rotation, scroll, conveyor, marquee — mechanical continuous motion |
 ```tsx
 const t = interpolate(frame, [start, start + 24], [0, 1],
  { extrapolateLeft: "clamp", extrapolateRight: "clamp", easing: Easing.out(Easing.cubic) });
 ```
 ## Timing & spacing (30fps baseline — but always derive with `sec()`)
 Spacing (the easing) sets *feel*; timing (frame count) sets *weight & mood*. **Cut frames before you add them — amateurs over-animate.**
 | Beat | Frames @30fps |
 |---|---|
 | Micro pop (icon, badge) | 8–14 |
 | Standard reveal | 18–28 |
 | Hero entrance | 28–40 |
 | Scene transition | 12–20 |
 | Hold | a comfortable read of the text (size to the longest Persian string) |
 Symptoms: robotic = linear spacing · floaty/late = timing too long · jittery = no hold between moves.
 ## The 12 principles → Remotion (the four in **bold** you reach for every shot)
 | Principle | Remotion expression |
 |---|---|
 | Squash & stretch | `scaleX`/`scaleY` inversely around an impact frame, conserve volume (`sx = 1/sy`) |
 | **Anticipation** | dip the value below its start before the main move |
 | Staging | stagger reveals; dim/blur everything but the hero — one idea per beat |
 | Straight-ahead vs pose-to-pose | `interpolate` between keyed frames vs per-frame formula (sim, e.g. `Confetti3D`) |
 | **Follow-through & overlapping** | same trigger, **delayed per child** + a *looser* spring so parts settle later |
 | **Slow in & slow out** | `Easing.bezier` / `spring()` — the single biggest quality lever |
 | Arcs | drive `y` with `sin`/parabola while `x` moves linearly |
 | Secondary action | a small `sin` bob/shimmer alongside the primary reveal |
 | Timing | frame count + spring `mass`/`damping` = weight & mood |
 | **Exaggeration / overshoot** | overshoot > 1.0, then settle to 1.0 |
 | Solid drawing | `StudioLights` + reflective material + floor shadows (3D) |
 | Appeal | choreography + `StudioEffects` (bloom/DOF/vignette) + good type |
 ## The four quality multipliers (concrete, reusable)
 **Anticipation** — a small negative dip before launch:
 ```tsx
 const scale = interpolate(frame, [start, start + 6, start + 30], [0, -0.12, 1],
  { extrapolateRight: "clamp", easing: Easing.bezier(0.36, 0, 0.66, -0.56) });
 ```
 **Overshoot + settle** — reach past, then land. Ensure the curve *holds* the target (clamp) or it micro-drifts forever:
 ```tsx
 const pop = interpolate(frame, [start, start + 18], [0, 1],
  { extrapolateRight: "clamp", easing: Easing.bezier(0.34, 1.56, 0.64, 1) });
 // or: spring with low damping (config { mass: 0.6, damping: 10, stiffness: 170 })
 ```
 **Follow-through** — drive children from the *same* trigger, delay each, looser spring so they settle after the parent. The biggest "feels professional" upgrade for grouped elements:
 ```tsx
 function Child({ i, start }: { i: number; start: number }) {
  const frame = useCurrentFrame();
  const { fps } = useVideoConfig();
  const p = spring({ frame: frame - start - i * 4, fps, config: { mass: 1, damping: 6, stiffness: 80 } });
  return <g style={{ transform: `translateY(${interpolate(p, [0, 1], [24, 0])}px)`, opacity: p }} />;
 }
 ```
 **Secondary motion** — never let a held element go dead. Add a tiny `sin` breathe/shimmer:
 ```tsx
 const bob = Math.sin(frame / fps * Math.PI) * L.vmin(4);   // gentle float during the hold
 ```
 ## Staggering & choreography
 Default to a **cascade**, and **tune the stagger per aspect** — wider frames read faster (tighter stagger), tall frames read slower (looser):
 ```tsx
 const L = useLayout();
 const stagger = L.pick(/*wide*/ 3, /*square*/ 4, /*tall*/ 5);   // pick(wide, square, tall)
 const start = i * stagger;
 ```
 Patterns: **cascade** (lists/features) · **center-out** (logo/hero rows: `delay = Math.abs(i - mid) * stagger`) · **deterministic random** (particles: `rand(i)` for delay/offset) · **beat-synced** (snap `start` to music beat frames — see `../remotion-music-picker/SKILL.md`). **One thing enters the eye at a time.**
 > `pick` is the standard per-aspect selector on `useLayout()`. If it isn't on `Layout` yet, add it in `aspect.ts`: `pick: <T,>(wide: T, square: T, tall: T): T => kind === "wide" ? wide : kind === "tall" ? tall : square,`
 ## 3D motion (`@remotion/three`)
 Drive every transform off `useCurrentFrame()` (deterministic under ANGLE) — **never `useFrame`**. Rotation/orbit = `linear` (mechanical); entrances/landings = `spring` with **high mass** for weight. Keep crisp Persian text as a 2D `<AbsoluteFill>` overlay above `<ThreeCanvas>`. Let `StudioEffects` (bloom + DOF + vignette) carry the cinematic polish in one component; tune `camera.fov`/`position.z` per aspect so the subject fills the frame.
 ## The pro workflow — 5 passes, IN ORDER
 Polishing before timing is locked wastes the most time.
 1. **Reference** — decide the feel before code; pick style (`../remotion-design-styles/SKILL.md`), type (`../persian-fonts/SKILL.md`), composition (`../remotion-template-composition/SKILL.md`), per-aspect rules (`../remotion-aspect-ratios/SKILL.md`). Write the beat list ("logo in → tagline → 3 features cascade → CTA → out").
 2. **Blocking** — every element at its final position with crude `interpolate` fades, no easing. Fix off-screen/cropping in all three aspects NOW.
 3. **Timing** — lock frame counts, stagger, beats, holds, transitions. Watch at full speed repeatedly. Mood lives here.
 4. **Polish** — swap linear for easing/springs; add anticipation + overshoot/settle, follow-through, secondary motion, arcs, squash/stretch; `StudioEffects` for 3D; wire SFX (`../remotion-sound-effects/SKILL.md`) + music sync (`../remotion-music-picker/SKILL.md`) to the locked frames.
 5. **Review** — scrub frame-by-frame + full speed against the checklist below.
 ## Top amateur mistakes → fixes (review gate)
 - Linear motion → ease/spring · no anticipation/overshoot → dip-then-launch / back bezier
 - Everything on one frame → stagger · forgot `clamp` → clamp both ends
 - Hardcoded 30fps → `useVideoConfig().fps` + `sec()`
 - `useFrame`/`random`/`Date.now()` → `useCurrentFrame` + `rand`
 - Pixel-hardcoded sizes → `vmin`/`unit` + `pick`/`isWide/isSquare/isTall`
 - Over-animating → one idea per beat · no hold → real hold sized to reading
 - Exit speed = entrance speed → exits sharper · dead holds → `sin` bob/breathe/shimmer
 - Color hardcoded → read from `colorSchema` props
 ## Pre-ship motion checklist
 - [ ] No linear easing anywhere except mechanical continuous motion (rotation/marquee).
 - [ ] Entrances ease-out; exits ease-in **and sharper** than entrances.
 - [ ] Every `interpolate` that could overshoot has `extrapolateLeft/Right: "clamp"`.
 - [ ] At least one anticipation (dip) and one overshoot-and-settle in the piece.
 - [ ] Grouped elements stagger; trailing parts follow through (looser spring).
 - [ ] No dead holds — held heroes have a subtle `sin` breathe/shimmer.
 - [ ] Stagger/scale tuned per aspect via `pick`; verified in 16:9 / 1:1 / 9:16.
 - [ ] All timing from `sec()`/`fps`; no hardcoded 30; no `useFrame`/`random`/`Date.now`.
 - [ ] One clear hero moment with the biggest motion; the eye always knows where to look.
 - [ ] Re-render twice → pixel-identical (deterministic).
 Related: `../remotion-design-styles/SKILL.md`, `../remotion-aspect-ratios/SKILL.md`, `../remotion-template-composition/SKILL.md`, `../remotion-character-design/SKILL.md`, `../remotion-sound-effects/SKILL.md`, `../remotion-music-picker/SKILL.md`, `../persian-fonts/SKILL.md`, `../flatrender-template-seo/SKILL.md`.
@@ -0,0 +1,120 @@
 ---
 name: particles-and-effects
 description: How to add production-value FX — confetti, sparkles, bokeh, light leaks, dust, smoke, glow, lens flare, film grain, chromatic aberration, vignette, camera shake — to FlatRender Remotion templates, in both 2D (SVG/CSS) and 3D (@remotion/three). Use when a template needs atmosphere, finishing texture, particle systems, or a celebratory/cinematic hit. Every effect is a deterministic function of useCurrentFrame() — never Math.random.
 ---
 # Particles & effects for Remotion
 Project: `services/remotion/` (Remotion 4 + `@remotion/three`, R3F v9, `gl="angle"`). Effects are the **8th finishing layer** — the thing that separates "made in a tool" from "made by a studio." A flat, ungrainy, perfectly-locked frame reads as AI/template. Imperfect-by-design wins.
 ## The one non-negotiable rule
 Render is headless Chrome sampling frames out of order, in parallel. **Every particle position, every grain offset, every flicker MUST derive from `useCurrentFrame()`.** Never `Math.random()`, `Date.now()`, `useFrame` (R3F), `useState`, or `useEffect` motion. Use `rand(seed)` from `src/lib/anim.ts` for stable per-index pseudo-randomness, and `rand(i + frame)`-style offsets when you want it to *move*. Re-render twice → identical bytes, or it's wrong.
 Helpers you build on:
 - `anim.ts` — `rand(i)` (deterministic 0..1), `hexToRgba(hex,a)`, `mixHex(a,b,t)`.
 - `aspect.ts` — `useLayout()` → `isWide/isSquare/isTall`, `vmin(n)`, `unit`, and `pick(wide,square,tall)`. **Scale particle COUNT and SIZE per aspect** — a tall 9:16 needs fewer, bigger sparkles than a wide 16:9.
 - `branding.ts` — `colorSchema` props are `accentColor / secondaryColor / backgroundColor / textColor`. FX color comes from these so the studio recolors them.
 - `three-kit.tsx` — `StudioEnv`, `StudioLights`, `StudioFloor`, `StudioEffects` (bloom+DOF+vignette), `Confetti3D`.
 ## 2D vs 3D — pick per effect
 - **2D (SVG/CSS)** is the default: cheap, crisp, no WebGL. Confetti, sparkles, grain, light leaks, vignette, aberration, camera shake — all better/cheaper in 2D as an `<AbsoluteFill>` overlay, even on top of a 3D scene.
 - **3D (@remotion/three)** when the effect must respond to scene lighting/depth: volumetric bloom, real bokeh/DOF, `emissive` glow that bloom picks up, 3D confetti with perspective. Let `StudioEffects` do bloom/DOF/vignette in ONE component — don't re-roll them.
 - Persian text NEVER goes in 3D — keep it as a 2D overlay above `<ThreeCanvas>`.
 ## Effect → recipe table
 | Effect | Layer | Core technique | Determinism |
 |---|---|---|---|
 | **Confetti (2D)** | overlay | N `<rect>`/`<path>`, `rand(i)` for x/rot/color; `y` = `(frame*speed + rand(i)*span) % span` | `rand(i)` seed |
 | **Confetti (3D)** | scene | reuse `Confetti3D` from three-kit | built-in |
 | **Sparkles / shine** | overlay | 4-point star SVG, twinkle `opacity = abs(sin((frame+rand(i)*60)/12))`, scale pulse | `rand(i)` |
 | **Bokeh** | bg | big blurred radial-gradient circles drifting on `sin(frame/period)`, low opacity, `mix-blend:screen` | per-circle seed |
 | **Light leaks** | overlay | warm radial/linear gradient sweeping across via `interpolate(frame,...)` translate, `mix-blend:screen` | frame |
 | **Dust motes** | overlay | tiny dim dots, slow upward drift + lateral `sin`, `rand` size/speed | `rand(i)` |
 | **Smoke / fog** | bg/3D | 2D: layered blurred blobs drifting+scaling; 3D: stacked transparent planes | frame |
 | **Glow** | any | 2D `filter:drop-shadow(0 0 Npx accent)` / `textShadow`; 3D `emissive`+`emissiveIntensity`, `toneMapped={false}`, let bloom bloom it | static |
 | **Lens flare** | overlay | bright core + chromatic ring sprites along a line from a light point, opacity by angle/frame | frame |
 | **Film grain** | top | SVG `feTurbulence` with per-frame `seed`, `mix-blend:overlay`, low opacity — MUST animate or it looks frozen | frame |
 | **Chromatic aberration** | top | duplicate layer, offset R/B channels ±1–3px, strongest at impact frames | frame |
 | **Vignette** | top | `boxShadow: inset 0 0 vmin(600) rgba(0,0,0,.6)` or `StudioEffects` in 3D | static |
 | **Camera shake** | root | translate whole frame by `rand(frame)`-driven jitter, decaying after an impact | `rand(frame)` |
 ## Deterministic particle field (the pattern to memorize)
 ```tsx
 const frame = useCurrentFrame();
 const { vmin, pick } = useLayout();
 const count = pick(60, 48, 36);          // fewer on tall
 {Array.from({ length: count }).map((_, i) => {
  const x = rand(i) * 100;               // % of width
  const drift = Math.sin((frame + rand(i + 9) * 200) / 40) * 3;
  const fall = (frame * (0.3 + rand(i + 1) * 0.5) + rand(i + 5) * 120) % 120;
  const twinkle = Math.abs(Math.sin((frame + rand(i + 2) * 60) / 12));
  return <div key={i} style={{
    position: "absolute", left: `${x + drift}%`, top: `${fall - 10}%`,
    width: vmin(6), height: vmin(6), opacity: twinkle,
    background: i % 2 ? accentColor : secondaryColor,
    transform: `rotate(${frame * 2 + rand(i) * 360}deg)`,
  }} />;
 })}
 ```
 Notice: `rand(i)` = stable identity per particle; `frame` = motion; `% span` = seamless wrap; aspect drives count via `pick`.
 ## Animated film grain (SVG — the cheapest authenticity layer)
 ```tsx
 <svg style={{ position: "absolute", inset: 0, mixBlendMode: "overlay", opacity: 0.08 }}>
  <filter id="grain">
    <feTurbulence type="fractalNoise" baseFrequency="0.9"
      numOctaves="2" seed={frame % 100} stitchTiles="stitch" />
  </filter>
  <rect width="100%" height="100%" filter="url(#grain)" />
 </svg>
 ```
 `seed={frame % 100}` is what makes it crawl. Keep opacity 0.05–0.12. For paper/vignette use `mix-blend:multiply` instead.
 ## Chromatic aberration & impact-driven FX
 Aberration should be **strongest at impacts** (a hard cut, the hero reveal, a confetti burst) and near-zero otherwise:
 ```tsx
 const ab = interpolate(frame, [hit - 2, hit, hit + 8], [0, vmin(4), 0], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
 ```
 Render the content twice, offset the red copy `translateX(-ab)` `mix-blend:screen` and the blue copy `translateX(+ab)`. Same `interpolate` curve also drives a one-shot camera-shake amplitude — things calm down fast.
 ## Camera shake (subtle continuous + impact)
 ```tsx
 // continuous "frame alive" drift — tiny, always on
 const driftX = Math.sin(frame / 50) * vmin(3) + (rand(frame) - 0.5) * vmin(1);
 // impact shake — decays
 const amp = interpolate(frame, [hit, hit + 12], [vmin(14), 0], { extrapolateLeft: "clamp", extrapolateRight: "clamp" });
 const shake = (rand(frame * 7) - 0.5) * amp;
 // apply to a root <AbsoluteFill style={{ transform: `translate(${driftX+shake}px, ${...}px)` }}>
 ```
 A locked, perfectly-still frame reads amateur. A *tiny* always-on drift makes it feel hand-held and alive — keep it under ~`vmin(4)` or it's distracting.
 ## 3D glow & bloom
 Make a material glow into bloom: `<meshStandardMaterial emissive={accentColor} emissiveIntensity={2} toneMapped={false} />`, then mount `<StudioEffects bloom={0.9} />`. For sparkly metal confetti raise `metalness`. Drive every transform off `useCurrentFrame()` (deterministic under ANGLE), rotation = `linear` (mechanical), entrances = `spring` with high mass.
 ## Reusable components — make these, don't inline
 Put shared FX in `src/lib/fx.tsx` so every template gets the same texture:
 - `<GrainOverlay opacity? blend? />` — animated `feTurbulence`.
 - `<Vignette strength? />` — inset boxShadow.
 - `<Confetti2D colors count? burstFrame? />` — burst (spring spread) vs rain (continuous fall) modes.
 - `<Sparkles colors count? area? />` — twinkling 4-point stars.
 - `<Bokeh colors count? />` + `<LightLeak color from to />` — bg/overlay atmosphere.
 - `<Aberration amount /> <CameraShake amount />` — finishing pair, wrap the whole comp.
 Each takes `colorSchema` colors so the studio picker recolors the FX, and reads `useLayout()` for per-aspect count/size.
 ## Restraint — FX amplify a hero, they are not the show
 - One celebratory burst on the **hero moment**, not raining the whole video. Often **silence before** + confetti + sparkle SFX on the same frame (see `../remotion-sound-effects/SKILL.md`).
 - Finishing texture (grain, vignette, drift) is *subtle and always-on*; spectacle (confetti, flare, big aberration) is *brief and on a beat*.
 - Don't stack 6 effects at full strength — that reads as a tool preset. Grain at 0.08, vignette at 0.5, aberration only at impacts.
 - All FX color from `colorSchema`; pass a user's garish hex through `mixHex(hex, background, 0.2)` so it doesn't blow out.
 ## Pre-ship checklist
 - [ ] Zero `Math.random` / `Date.now` / `useFrame` — only `rand()` + `frame`. Re-render twice → identical.
 - [ ] Grain is *animated* (per-frame seed), not frozen.
 - [ ] Particle count & size scale per aspect via `pick`/`vmin` — verified in 16:9, 1:1, 9:16; particles stay in the safe zone, never crop Persian text.
 - [ ] Every `interpolate` has `extrapolateLeft/Right: "clamp"` — no drift, no negative opacity.
 - [ ] Spectacle FX land on a beat / the hero; texture FX are subtle & continuous.
 - [ ] FX colors read from `colorSchema`; a continuous camera drift keeps the frame alive.
 - [ ] 3D glow uses `emissive`+`toneMapped={false}` + `StudioEffects` (not hand-rolled bloom).
 Related: `../remotion-design-styles/SKILL.md`, `../remotion-character-design/SKILL.md`, `../remotion-aspect-ratios/SKILL.md`, `../remotion-template-composition/SKILL.md`, `../remotion-sound-effects/SKILL.md`, `../remotion-music-picker/SKILL.md`, `../remotion-svg-colors/SKILL.md`, `../persian-fonts/SKILL.md`, `../remotion-template-catalog/SKILL.md`, `../flatrender-template-seo/SKILL.md`.
@@ -0,0 +1,55 @@
 ---
 name: persian-fonts
 description: Persian (Farsi) and Latin font selection for FlatRender — which font to use where, with a Persian-first priority. Use when choosing typefaces for a template or UI, pairing display vs body fonts, handling RTL/Persian numerals, or adding a new font to the Remotion project. Persian fonts are the priority.
 ---
 # Persian-first typography
 This is an Iran-facing product: **Persian (Farsi) is the default and the priority**. Latin is secondary. Get the Persian type right first.
 ## What the project already uses
 - **Vazirmatn** — the default Persian face everywhere. Remotion bundles `services/remotion/public/fonts/vazirmatn-{400,600,700,800,900}.woff2` and exposes `FONT` from `src/lib/fonts.ts` (use `fontFamily: FONT` + `direction: "rtl"` in every composition).
 - Web app: `globals.css` has a `[dir="rtl"]` block that FORCES Vazirmatn on all elements — don't fight it with utility classes; work with it.
 - Latin pairing in the web app: **Plus Jakarta Sans** + **Inter**.
 ## Persian font palette (pick by role)
 | Font | Character | Use for |
 |---|---|---|
 | **Vazirmatn** | clean, neutral, many weights | DEFAULT — body, UI, most template text |
 | **Estedad** | modern, geometric, friendly | headings, modern brand templates |
 | **Yekan Bakh** | contemporary sans, professional | corporate/business templates |
 | **Shabnam / Sahel** | soft, readable | body text, calm/elegant designs |
 | **IRANSans / IRANYekan** | familiar Iranian UI standard | UI-style promos, app mockups |
 | **Morabba** | bold display, rounded | big punchy headlines, posters |
 | **Gandom** | strong display | impactful titles, sale/sport |
 | **Lalezar** | playful, heavy, fun | kids, party, birthday, casual |
 | **Shekari / Vahid** | decorative/calligraphic | festive, traditional (Nowruz, wedding, Yalda) |
 | **Nastaliq (e.g. IranNastaliq)** | classical calligraphy | very formal/traditional, invitations — use sparingly, hard to read small |
 Pairing rule: one display face for the headline + Vazirmatn (or Shabnam) for everything else. Don't mix two display faces.
 ## Match font to template mood
 - Corporate / SaaS → Estedad / Yekan Bakh + Vazirmatn.
 - Festive (birthday, party) → Lalezar / Morabba + Vazirmatn.
 - Traditional / occasion (Nowruz, wedding, Yalda, Eid) → a decorative/Nastaliq display for the greeting + Vazirmatn for details.
 - Sale / bold promo → Gandom / Morabba (heavy) + Vazirmatn.
 - Minimal / elegant → Shabnam / Sahel, lighter weights.
 ## Persian typesetting rules
 - **RTL:** always `direction: "rtl"`; align right or center. Mixed Persian+Latin/numbers needs care (bidi) — test the actual string.
 - **Numerals:** decide Persian (۱۲۳) vs Latin (123) and be consistent. For Persian digits, format with `toLocaleString('fa-IR')` or use a font that supports Persian numerals. Years/prices in templates are usually Persian digits (۱۴۰۶, ۲۹۹٬۰۰۰).
 - **Weights:** Persian script needs a bit more weight to feel solid — headings 700-900, body 400-600. Avoid ultra-thin for small text.
 - **Line-height:** Persian needs slightly more (`lineHeight` 1.4-1.6 for body) — descenders/diacritics need room.
 - **ZWNJ (نیم‌فاصله, `‌`):** preserve it in words like «می‌شود», «نیم‌فاصله» — don't strip it.
 - **No fake bold/italic:** use real weights; Persian has no italic — don't slant it.
 ## Adding a new font to a Remotion template
 1. Get the woff2 (license-checked — Vazirmatn/Estedad/Shabnam are SIL OFL, free for commercial; verify others). Place in `services/remotion/public/fonts/`.
 2. Register it (a `@font-face` injected via `<style>` in the composition, or `@remotion/fonts` `loadFont`) and expose a `FONT_X` const next to `FONT` in `lib/fonts.ts`.
 3. Use `fontFamily: FONT_X` only for that template's display text; keep body on Vazirmatn.
 4. Embed the actual weights you use (don't ship 9 weights if you use 2) to keep bundles small.
 ## Licensing
 Prefer SIL OFL / free-for-commercial Persian fonts (Vazirmatn, Estedad, Shabnam, Sahel, Samim, Gandom, Morabba — most from the `font-store`/Google Persian sets are OFL). Verify each before shipping in an exported-video product; keep a license record.
 Related: `../remotion-template-composition/SKILL.md`, `../remotion-design-styles/SKILL.md`.
@@ -0,0 +1,244 @@
 # FlatRender Design & Motion R&D — Trends + Professional Craft
 > Single-source R&D brief for the FlatRender Remotion engine (`services/remotion`). Stack: **Remotion 4 + `@remotion/three`** (R3F v9, `gl="angle"`), Persian-first (Vazirmatn, RTL), three mandatory aspects (16:9 / 1:1 / 9:16), color-customizable templates driven by `colorSchema` props. Operating context: **Iran** — geo-blocked CDNs, sanctioned SaaS dashboards, reachable Nexus mirror (`mirror.soroushasadi.com`). Render is headless Chrome in Docker, so **every value must be a pure function of `useCurrentFrame()`** and **every asset must be vendored** into `public/`.
 >
 > Existing grounding files: `src/lib/anim.ts`, `aspect.ts`, `branding.ts`, `fonts.ts`, `three-kit.tsx`, `kit.tsx`; templates in `src/templates.tsx`; `public/` currently holds only `fonts/`.
 ---
 ## The two meta-truths to keep over everything
 1. **Imperfect-by-design beats glossy.** As feeds fill with AI-perfect imagery, deliberate imperfection — grain, texture, hand-rendered type, natural-feeling motion — now signals "a real human made this." Even fully-rendered templates win by *adding back* texture and human-feeling motion. Apply this lens to every trend below.
 2. **A masterpiece is ~8 finishing layers, not one big thing.** Sound design, micro-easing, a design system, depth/lighting, color grade, pacing, a clear hero moment, and subtle texture. Amateurs stop at "the text animates in." We must finish all eight.
 ---
 ## 1) Design trends to adopt (each with a concrete how-to in our stack)
 Every trend below survives all three aspects only if you anchor to safe-zone **percentages / `layout.vmin()`**, never absolute pixels. Read `../remotion-aspect-ratios/SKILL.md` before positioning anything.
 ### Typography (type is a first-class motion element, not a label)
 | Trend | When to use | How in our stack |
 |---|---|---|
 | **Bold / oversized hero type** (fills 60–90% of frame, clipped by edges) | Logo reveals, promo hooks; strongest on 9:16 | `fitText` from `@remotion/layout-utils` to auto-scale a word to frame width; animate `scale`/`translateY` with `spring()`; parent `overflow:hidden` to clip. |
 | **Variable-font animation** (`wght`/`wdth`/`slnt` over time) | Premium beat-synced intros | `style={{ fontVariationSettings: \`'wght' ${interpolate(frame,[0,30],[100,900])}\` }}`. **Vazirmatn ships a variable build** — animate its weight axis for Persian hero type. Load via `@font-face` (vendored in `public/fonts/`, never Google CDN at render). |
 | **Kinetic typography** (word-by-word / line-by-line) | Quotes, captions, fast hooks | Split into spans; per-word `delay = i * staggerFrames`; drive each with `spring({frame: frame - delay, fps})`; combine `translateY` + `opacity` + slight `rotate`. `<Sequence>` per line for timeline clarity. |
 | **Anti-AI / hand-rendered / scribbled** | Grunge/street/youth/music/events | Pre-make rough-edged SVG/PNG lettering; "draw" it on with a `clipPath`/mask wipe; add `filter:url(#displace)` (SVG `feTurbulence` + `feDisplacementMap`) with a per-frame jitter for photocopy wobble. |
 | **Chrome / Y2K metallic type** | Hype, music, fashion, "premium" reveals | CSS: layered `linear-gradient` text fill via `background-clip:text` cycling silver→steel→highlight by shifting `background-position` per frame. For real reflections, use Three.js (see liquid-chrome below). |
 ### 3D / Blender-look (`@remotion/three`)
 - **Real-time 3D logo reveals** — the default "premium intro." Render `<ThreeCanvas>`, drive camera/object rotation from `useCurrentFrame()` (**never `useFrame`**). Extrude logo via `TextGeometry`/extruded SVG shape, `meshStandardMaterial`, an HDRI `Environment`, `spring()`-driven entrance. Use our `StudioEnv/StudioLights/StudioFloor/StudioEffects` from `three-kit.tsx`.
 - **"Plushcore" / soft-3D / claymation** — friendly counter to hard chrome. Pre-render GLTF in Blender (subsurface/soft shaders), import via `useGLTF`; bobbing idle = `Math.sin(frame/fps)` on position. 2D fake-3D = big soft inner-shadows + highlight gradients in CSS.
 - **Mixed 2D/3D** — one of the strongest 2026 looks. Layer a `<ThreeCanvas>` behind/within absolutely-positioned 2D Remotion layers (SVG strokes, flat shapes); composite with blend modes.
 ### Surface & color treatments
 - **Grain / texture / noise** — near-universal in 2026; add to almost everything, especially flat/gradient backgrounds. Cheap: tiling noise PNG overlay at low opacity with `mix-blend-mode: overlay`/`soft-light`. **Animated grain must move or it looks frozen** — offset `background-position` per frame, or SVG `feTurbulence` with a per-frame `seed`/`baseFrequency` jitter.
 - **Mesh gradients** — soft multi-point blends (not linear), the sophisticated 2026 background. Pre-bake a mesh PNG and slowly drift/scale it, or animate live with a fragment shader in Three.js driven by `frame`. **Always add grain on top.**
 - **Glassmorphism (evolved)** — used *selectively* (cards, lower-thirds), multi-layer depth, dynamic blur. `backdrop-filter: blur(16px) saturate(140%)`, semi-transparent `rgba` fill, 1px light top-border, soft shadow; animate blur radius + a moving specular highlight per frame; stack 2–3 panels at different parallax depths.
 - **Retro / Y2K** — chrome + iridescent mesh gradient + occasional pixelate (`image-rendering:pixelated` on a downscaled layer) + sparkle SVG bursts. Music/fashion/Gen-Z/party greetings.
 - **Anti-design / tactile brutalism** — hard `1px solid #000` borders, no radius, pure-saturated bg, system/monospace fonts, deliberate overlap. Motion is blunt — **hard cuts and `step`/`linear` snaps, not smooth springs.**
 - **Mixed-media / collage** — PNG cutouts with rough edges as layers; "paper-drop" overshoot springs on slight rotation/scale; tape/staple SVGs, paper-grain overlay, occasional 1-frame jump-cut jitter.
 - **Isometric** — `transform: rotateX(60deg) rotateZ(-45deg)` on stacked layers with `transform-style:preserve-3d`; stagger layer entrances; move elements along iso axes (matched X/Y deltas). Great for SaaS/feature explainers.
 - **Kinetic / liquid / morph** — morphing blobs (animate SVG `path d` with `flubber`; gooey via `feGaussianBlur` + `feColorMatrix`). **Liquid chrome (top-5 2026 animation trend):** Three.js `meshStandardMaterial` `metalness:1, roughness:~0.05` + HDRI `Environment` on a morphing/`MeshDistort`-style geometry — color shifts as the camera moves.
 - **AI-aesthetic vs anti-AI** — AI stills/clips as `<Img>`/`<OffthreadVideo>` backgrounds with Ken-Burns for surreal promos; lean into hand-type + grain + collage for trust/authenticity brands.
 ### Color direction 2026
 - **Dopamine / electric accents** (electric blue, neon coral, acid yellow, vivid teal, cobalt) — as high-energy *accents* to guide the eye, never whole palettes.
 - **Tech pastels** (lavender haze, powder blue, digital pink) — calm/mature, great for SaaS/UI promos.
 - **Warm earth neutrals** (mocha/espresso/caramel/tan) — "quiet luxury," premium and human.
 - **Strategy:** bold dopamine accent + neutral/pastel base + grain on top. **Avoid all-flat saturated fields — they read as AI/template.** All color comes from `colorSchema` props so the studio can recolor; pass a user's hex through a grade so a garish value doesn't break the look.
 ---
 ## 2) Animating anything (craft + the pro workflow)
 ### The one rule everything hangs on
 A frame in Remotion is **pure**: `frame → pixels`. Motion is *evaluated* at an arbitrary frame, exactly the After Effects mental model (a keyframe graph sampled at time `t`). **Never** use `useFrame`, `Math.random()`, `Date.now()`, `setState`, or `useEffect`-driven motion — the renderer samples frames out of order and in parallel. Use `rand(seed)` from `anim.ts` for deterministic "randomness." If a value can't be derived from `frame`, it doesn't belong in the render.
 ### The 12 principles → Remotion (the four you reach for every shot in bold)
 | Principle | Remotion expression |
 |---|---|
 | Squash & stretch | `scaleX`/`scaleY` inversely around an impact frame (conserve volume: `sx = 1/sy`) |
 | **Anticipation** | Dip the value below its start before the main move |
 | Staging | Stagger reveals; dim/blur everything but the hero |
 | Straight-ahead vs pose-to-pose | `interpolate` between frames (keyed) vs per-frame formula (sim, e.g. `Confetti3D`) |
 | **Follow-through & overlapping** | Same motion, **delayed per child** + a *looser* spring so parts settle later |
 | **Slow in & slow out** | `Easing.bezier` / `spring()` — the single biggest quality lever |
 | Arcs | Drive `y` with a `sin`/parabola while `x` moves linearly |
 | Secondary action | A small `sin` bob/shimmer alongside the primary reveal |
 | Timing | Frame count + spring `mass`/`damping` = weight & mood |
 | **Exaggeration / overshoot** | Overshoot > 1.0, then settle to 1.0 |
 | Solid drawing | `StudioLights` + reflective material + shadows (3D) |
 | Appeal | Choreography + `StudioEffects` (bloom/DOF/vignette) + good type |
 ### `spring()` vs `interpolate()`
 - **`interpolate`** — *you* author the curve. Use when a value must hit an exact mark on an exact frame (storyboard reveals, crossfades, value remaps). **Always set `extrapolateLeft/Right: "clamp"`** — forgetting this is the #1 cause of elements drifting off-screen or opacity going negative.
 - **`spring`** — *physics* authors the curve. Use for organic entrances, pops, bounces.
 - **Combine:** spring drives the *feel*, interpolate *remaps* its 0→1 output to real px/units: `const y = interpolate(spring(...), [0,1], [vmin(80), 0])`.
 **Spring config cheat-sheet:**
 | Feel | mass | damping | stiffness | Use for |
 |---|--:|--:|--:|---|
 | Snappy, no overshoot | 0.5 | 200 | 200 | Clean UI/logo reveals |
 | Natural pop (slight overshoot) | 0.6 | 12 | 180 | **Default** cards/badges/icons |
 | Bouncy / playful | 1 | 8 | 120 | Kids, birthday, mascots |
 | Heavy / weighty | 2.5 | 26 | 90 | Big titles, 3D objects landing |
 | Loose wobble (follow-through) | 1 | 6 | 80 | Secondary / trailing parts |
 Lower damping = more overshoot; higher mass = heavier/slower; higher stiffness = faster snap.
 ### Easing cheat-sheet (linear is the sound of an amateur)
 - **Entrances → ease-out** (`Easing.out(Easing.cubic)`), your default. Hero titles → `Easing.out(Easing.quint)` or `Easing.bezier(0.16,1,0.3,1)`.
 - **Exits → ease-in** (`Easing.in(Easing.cubic)`), and **always sharper than the entrance** — things leave faster than they arrive.
 - **A→B on-screen moves / camera → ease-in-out.**
 - **Snappy "ta-da" → back/overshoot** `Easing.bezier(0.34,1.56,0.64,1)`.
 - **Wind-up → anticipate** `Easing.bezier(0.36,0,0.66,-0.56)`.
 - **Linear ONLY for mechanical continuous motion** — rotation, scroll, conveyor, marquee.
 ### Timing & frame budgets (30fps default — but use `sec(s)=Math.round(s*fps)`, never hardcode 30)
 Micro pop 8–14f · standard reveal 18–28f · hero entrance 28–40f · scene transition 12–20f · hold = a comfortable read of the text. **Cut frames before you add them — amateurs over-animate.** Robotic = linear spacing; floaty/late = timing too long.
 ### The four quality multipliers (concrete patterns)
 - **Anticipation:** `interpolate(frame,[0,6,30],[0,-0.12,1])` — small negative dip before launch.
 - **Overshoot+settle:** the back bezier, or a low-damping spring. Ensure the curve *reaches and holds* the target (clamp) or it micro-drifts forever.
 - **Follow-through:** drive children from the same trigger frame, **delay each** (`frame - start - i*stagger`) with a *looser* spring so they settle after the parent. Biggest "feels professional" upgrade for grouped elements.
 - **Staggering / choreography:** default to a **cascade**; tune per aspect via a `pick(wide,square,tall)` helper (wider reads faster → tighter stagger; tall reads slower → looser). Patterns: cascade (lists), center-out (logos/hero rows), random-but-deterministic via `rand(i)` (particles), beat-synced (snap `start` to music beats). **One thing enters the eye at a time** — staging.
 ### 3D motion
 Drive every transform off `useCurrentFrame()` (deterministic under ANGLE). Rotation/orbit = `linear` (mechanical); entrances/landings = `spring` with high mass for weight. Let `StudioEffects` (bloom + DOF + vignette) do the cinematic polish in one component.
 ### The pro workflow (5 passes, IN ORDER — polishing before timing is locked wastes the most time)
 1. **Reference** — decide the feel before code; pull an AE template/Dribbble loop; pick style (`../remotion-design-styles/SKILL.md`), type (`../persian-fonts/SKILL.md`), composition (`../remotion-template-composition/SKILL.md`), per-aspect rules (`../remotion-aspect-ratios/SKILL.md`); write the beat list ("logo in → tagline → 3 features cascade → CTA → out").
 2. **Blocking** — every element on screen at final position with crude `interpolate` fades, no easing. Fix off-screen/cropping in all three aspects now.
 3. **Timing** — lock frame counts, stagger, beats, holds, transitions. Watch at full speed repeatedly. Mood lives here.
 4. **Polish** — swap linear for easing/springs; add anticipation+overshoot+settle, follow-through, secondary motion, arcs, squash/stretch; `StudioEffects` for 3D; wire SFX (`../remotion-sound-effects/SKILL.md`) and music sync (`../remotion-music-picker/SKILL.md`) to the locked frames.
 5. **Review** — scrub frame-by-frame + full speed. Nothing pops without an ease; nothing leaves slower than it arrived; the eye always knows where to look; reads in all three aspects; Persian RTL not clipped; colors from `colorSchema`; re-render twice → identical (deterministic). Then run `../flatrender-template-seo/SKILL.md`.
 ### Top amateur mistakes → fixes (review gate)
 Linear motion → ease/spring · no anticipation/overshoot → dip-then-launch / back bezier · everything on one frame → stagger · forgot `clamp` → clamp both ends · hardcoded 30fps → `useVideoConfig().fps` · `useFrame`/`random`/`Date.now` → `useCurrentFrame` + `rand` · pixel-hardcoded sizes → `vmin`/`unit` + branch on `isWide/isSquare/isTall` · over-animating → one idea per beat · no hold → real hold sized to reading · exit = entrance speed → exits sharper · dead holds → `sin` bob/breathe/shimmer · flat 3D lighting → `StudioLights` + floor shadows + `StudioEffects` · color hardcoded → read from props.
 ---
 ## 3) Asset pipeline (collecting + designing footage, Iran-aware)
 ### The Iron Rule
 The Iran environment punishes runtime dependencies. **All assets are vendored** — download once (over VPN if needed), commit into `services/remotion/public/`, reference with `staticFile()`. **Never** `<Video src="https://somecdn..." />` in a template — a geo-block or flaky tunnel kills the render mid-frame. Mirror npm/NuGet/Docker via Nexus; asset *binaries* are sourced manually and committed. **Track licenses at acquisition time, not later.**
 ### License taxonomy (know cold)
 - **Ship freely, no attribution:** CC0 / Public Domain, Pixabay License, Pexels License, Unsplash License. **Default target.**
 - **Allowed with a credit:** CC-BY (track per-asset; needs attribution UI/end-card).
 - **Off-limits:** CC-BY-SA (share-alike can "infect" our proprietary template), CC-BY-NC (we are a paid product = commercial), editorial/rights-managed.
 - **Paid stock (Envato/Adobe/Shutterstock):** allowed per license; keep the receipt/license PDF. Note their dashboards/checkout often geo-block Iran at the account/payment layer even with a VPN — use a foreign-established account or a partner.
 ### Sourcing (CC0 / no-attribution first)
 - **Footage:** Pexels Videos (first stop), Pixabay Video, Mixkit, Coverr (check AI badge), Free Nature Stock, Videvo (filter to CC0). Pick exact resolution (don't ship 4K into a 1080p comp), prefer **H.264 MP4** for `<OffthreadVideo>`, commit under `public/footage/`.
 - **Images:** Pexels, Pixabay, Unsplash, StockSnap, Burst. For Persian/Iran imagery search English terms ("Tehran", "Iranian food") + self-shot/local stock.
 - **Textures & overlays:** Poly Haven Textures (CC0), ambientCG (CC0); grain/light-leak/dust = CC0 video clips you screen-blend.
 - **HDRIs:** Poly Haven (1k–2k for render speed), ambientCG.
 - **3D (GLB):** Poly Haven Models (CC0, cleanest), Kenney.nl (CC0 low-poly), Khronos glTF samples, Sketchfab (**mixed — check each**, filter Downloadable + CC0/CC-BY). **Prefer GLB over glTF+separate-textures** (one file, no broken paths); Draco-compress with `gltf-pipeline -b`; keep low-poly for headless render speed.
 - **Icons (bundle via Nexus npm, never CDN):** Lucide, Tabler, Heroicons, Phosphor, Iconoir. **Illustrations (recolorable SVG):** unDraw, Open Peeps, Humaaans — ship as SVG so the studio color picker recolors them (`../remotion-svg-colors/SKILL.md`).
 **Iran access:** generally reachable — Pixabay, Mixkit, Coverr, Poly Haven, ambientCG, npm via Nexus. VPN-recommended/intermittent — Pexels, Unsplash, Sketchfab, GitHub raw. Sanction-blocked at account/payment — Adobe Stock, Envato. **Mitigation: batch all sourcing in one "asset run" over a stable tunnel, commit binaries, render never touches the open internet again.**
 ### AI-generated assets — when it's right
 - **Use when:** the asset doesn't exist as stock (specific Persian cultural scene, branded mascot), you need consistency across a template set (reference-image controls), or it's faster than a 5-site license hunt.
 - **Don't use when:** clean CC0 stock already exists, you need photographic authenticity, or the **free-tier commercial license is unclear** (many free tiers forbid commercial use / watermark — a legal landmine for a paid product).
 - **Iran-pragmatic recommendation: locally-hosted open models** — **HunyuanVideo 1.5** (self-hosted, ~RTX 4090, no geo-block/payment/watermark, full commercial control) for video; **FLUX/SDXL** locally for image/texture/illustration. Use hosted SaaS (Runway Gen-4, Kling 3.0) only when local quality is insufficient and a VPN+foreign-account path exists. **Always record prompt + tool + plan-tier + date** in the asset's sidecar.
 ### Designing & preparing footage in Remotion
 - **Media primitives:** `<OffthreadVideo>` = **default for all video in a render** (FFmpeg frame extraction, deterministic, no seek drift). `<Video>` = preview only. `<Img>` over raw `<img>` (waits for load → no half-loaded frames). `staticFile()` for every vendored asset; never an external URL in a shipped template.
 - **Color grading:** per-layer CSS `filter` + blend modes (`contrast/saturate/brightness/hue-rotate`). Build a shared `lib/grades.ts` preset set (`warm`, `teal-orange`, `mono`, `filmic`) so all templates grade consistently and the palette can drive `hue-rotate`/`saturate`. Heavy grading → pre-grade in DaVinci Resolve (free) before committing.
 - **Masking / keying:** no native keyer — pre-key in Resolve/AE and export **alpha** (ProRes 4444 or WebM/VP9 alpha), then `<OffthreadVideo>` it. Shape/gradient masks via CSS `maskImage`/`clipPath` or SVG `<mask>`.
 - **Seamless loops:** source loop-designed clips (Coverr/Mixkit) or crossfade-to-self with overlapping `<Sequence>`s; mirror-pingpong for imperfect footage. `<OffthreadVideo loop>` once first/last frames match.
 - **Overlays (the cheap "authentic" layer):** stack grayscale-on-black/white clips — **screen** for light-leaks/bokeh/dust, **overlay/soft-light** for grain, **multiply** for vignettes/paper. Keep palette-independent.
 - **Ken-Burns:** `interpolate` scale (start ≥ 1 overscan so no edge reveals) + translate; ease with `spring`/bezier; `objectFit:cover` + center-safe framing so all three aspects crop cleanly.
 - **Performance (headless Docker):** right-sized media, H.264 + `<OffthreadVideo>`, 1k–2k HDRIs, Draco GLB; raise `concurrency` carefully and watch RAM.
 ### Library structure + attribution firewall
 Create under `services/remotion/public/` (today only `fonts/`): `footage/{nature,business,abstract}/`, `overlays/`, `images/`, `textures/`, `hdri/`, `models/`, `icons/`, `illustrations/`, plus **`assets.json` + `ASSETS.md`**. Lowercase-kebab names, no spaces.
 **`assets.json` — one row per asset, added at download time** (`file, source, url, author, license, attribution_required, commercial_ok, acquired, notes`). Conventions: every asset gets a row (no row = "unknown license = do not ship"); `attribution_required:true` must surface its credit on a shippable surface; sidecar `.license.txt` for AI prompts / paid receipts. **CI validation script** asserts every file in the media folders has a matching row with `commercial_ok:true`, else fails the build — this is the license firewall. `ASSETS.md` is a generated readable table for humans/legal. If the repo bloats, move large media to Git LFS or MinIO (already in stack) with a `predeploy` sync into `public/` — but present at render time.
 ---
 ## 4) Masterpiece production + platform playbook
 ### The 8 production-value layers (what separates "made in a tool" from "made by a studio")
 1. **Sound design + beat-sync** — the fastest "professional" tell. Beat-sync every key reveal (map BPM, keyframe on beat boundaries — hero on a downbeat); layered SFX (whoosh on transitions, thump on hard cuts, sparkle on shine sweeps, riser into the hero, pop on icon entrances); **ducking** (music dips under VO/key sound); **silence before the hero reveal** makes the payoff hit harder.
 2. **Micro-detail** — easing never linear; overshoot & settle; staggered 2–5f entrances; secondary motion (shadow/contents react); anticipation.
 3. **Design system** — one type scale (4–5 sizes), one spacing rhythm, constrained palette (1 primary + 1–2 accents + neutrals), consistent radii/strokes/elevation; Persian-first type handled deliberately (Vazirmatn + matched Latin pairing, not one font stretched across scripts).
 4. **Depth & lighting** — layered parallax (bg/mid/fg different speeds), soft directional shadows with one consistent light direction, atmospheric depth (bg blur/desaturate, fg sharp/saturated), rim light on hero.
 5. **Color grade** — one unified grade over the whole comp (not per-element colors fighting); lifted/tinted shadows, controlled highlights, deliberate temperature; user hex still passes through the grade.
 6. **Pacing / rhythm** — vary cut length, build to a climax, match cut rhythm to music, trim ruthlessly.
 7. **A clear hero moment** — one designated peak (logo/price-drop/product/CTA) with the biggest motion, strongest hit, often silence before, most screen real-estate. Flat = nothing lands.
 8. **Finishing texture (subtle!)** — low-opacity film grain, gentle vignette, 1–2px chromatic aberration strongest at impacts, tiny continuous camera drift (frame alive, not locked), sparing light-leaks/bokeh, motion blur on fast elements (its absence is a classic amateur tell).
 ### Pre-ship polish checklist (if you can't tick it, it's not done)
 - **Motion:** no linear easing anywhere; staggered entrances; motion blur on fast elements; ≥1 overshoot-and-settle; nothing pops on/off without a transition.
 - **Audio:** BPM mapped, reveals on beat; whoosh on every scene change; accent SFX on hero; music ducks under VO, no clipping, clean end.
 - **Composition/design system:** verified in 16:9 / 1:1 / 9:16 (not a letterboxed 16:9); text in platform safe zones; consistent scale/spacing/radii/shadows; constrained palette; FA + EN both correct (RTL, font, numerals).
 - **Depth & grade:** consistent light direction; bg depth treatment; unifying grade over the comp.
 - **Pacing & hero:** one unmistakable hero; varied cuts matched to music; engaging first frame (it's the thumbnail).
 - **Finishing:** subtle grain OR vignette present; frame alive; aberration/light-leak at transitions if style allows.
 - **Technical/QA:** clean render at target res (no flicker/z-fighting/font fallback); all editable fields (text/logo/image/colors) swap without breaking layout; longest text doesn't overflow, shortest doesn't look empty; loops cleanly if meant to.
 ### Platform playbook (2026)
 All vertical = **1080×1920, 9:16**. **First frame = the hook = the cover.** High-contrast captions (white/yellow, black outline) in the lower-middle third are the cross-platform default.
 | Platform | Length sweet spot | Hook / retention | Safe zone (1080×1920) | Template implication |
 |---|---|---|---|---|
 | **IG Reels** | 7–15s punchy; 30–90s for depth (up to 90s) | First 2–3s decide stay/swipe; cleaner/less-cluttered text than TikTok; rewards 3-sec view rate + completion | ~108 top, ~320 bottom, ~60 L, ~120 R; hook text Y≈200–600 | Cleaner kinetic type, mesh-gradient + glass lower-thirds, refined transitions |
 | **IG Story** | full-bleed | heavy UI chrome | avoid top ~250 (profile) + bottom ~250 (reply/link) | design poll/quiz/link sticker zones into layout |
 | **IG Feed post** | — | first caption line is the hook | — | Portrait **4:5 (1080×1350)** standard; 1:1 for grid consistency |
 | **TikTok** | 15–30s engagement; 11–18s virality; ≤60s educational | **3-second rule**; curiosity-gap / bold-claim hooks; word-by-word captions beat full sentences | keep right ~120, bottom ~320 clear of key content | calm neutral grain+warm-earth variant; **word-by-word captions as a first-class editable layer** |
 | **YT Shorts** | 15–35s | **no runway** — open on the most compelling moment; intro retention >70%, completion >60% (<30s) | center within middle ~1080×1350; clear bottom UI + right buttons | cinematic 3D logo reveals, graded looks |
 | **YT long-form intro** | — | cold-open hook in first 5–15s; branded sting <3s | — | state payoff first, brand second |
 | **YT end screen** | last 5–20s | — | leave clean plate (lower + right) for subscribe/next/playlist | reserve an end-card-safe zone |
 | **All three** | drifting to **60–90s** | authenticity > perfection, phone-feel > studio, natural light, cinematic grading | — | hook in first 1–2s; grain/texture everywhere; support longer durations; safe-zone all text |
 **Cross-platform synthesis rules:** (1) design to the *tightest* safe zone (Story/TikTok), then it's safe everywhere; (2) first frame = the hook = the cover; (3) front-load the payoff, no preamble; (4) captions are a first-class editable layer (word-by-word), not an afterthought; (5) one template, **three real aspects** — re-flow, never letterbox.
 ---
 ## 5) Prioritized "level up our skills + templates" action list
 Ordered by ROI. Each item ties to our stack and the relevant skill file.
 **Tier 0 — foundation infra (do first; unblocks everything else)**
 1. **Establish the asset library + license firewall.** Create the `public/{footage,overlays,images,textures,hdri,models,illustrations}` tree, `assets.json` + `ASSETS.md`, and the **CI validation script** (`commercial_ok` + matching-row check). Do one batched VPN "asset run" of a CC0 starter pack (grain/light-leak/dust overlays, 3–4 mesh-gradient PNGs, a few Poly Haven HDRIs + GLBs, business/nature/abstract footage). *(Asset pipeline §3.)*
 2. **Promote shared helpers into `lib/`.** Add `pick(wide,square,tall)` onto `Layout` in `aspect.ts` (currently only `isWide/isSquare/isTall/vmin/unit`); create `lib/grades.ts` (warm/teal-orange/mono/filmic + palette-driven `hue-rotate/saturate`); confirm `rand`/`hexToRgba`/`mixHex` in `anim.ts` cover deterministic needs. *(Animation §2, Asset §3.)*
 3. **Stand up a local AI-asset box** (HunyuanVideo 1.5 + FLUX/SDXL) so bespoke Persian/branded assets don't depend on geo-blocked SaaS. *(Asset §3.)*
 **Tier 1 — highest-ROI template work**
 4. **Build a "captions" engine as a reusable first-class layer** — word-by-word kinetic captions, high-contrast white/yellow + black outline, lower-middle-third, safe-zoned for all platforms, beat-syncable. This is currently an afterthought and is the biggest cross-platform win. *(Masterpiece §4, Animation §2.)*
 5. **Ship the "kinetic oversized type + grain" template** — every aspect, cheap (CSS), uses variable Vazirmatn weight-animation for Persian hero type. Highest ROI per the trends brief. *(Trends §1, Animation §2.)*
 6. **Codify the pre-ship polish checklist + 8 layers into a review gate** (extend `../flatrender-template-seo/SKILL.md`'s publish step, or a new lint pass) so no template ships without easing, beat-synced audio, three-aspect verification, and a hero moment. *(Masterpiece §4.)*
 7. **Sound-design pass on the existing pack** — wire `../remotion-music-picker/SKILL.md` BPM mapping + `../remotion-sound-effects/SKILL.md` placement + ducking into our current templates. Fastest "professional" upgrade to what already exists. *(Masterpiece §4.)*
 **Tier 2 — premium differentiation**
 8. **3D logo-reveal template + a liquid-chrome variant** on `@remotion/three` + HDRI (`three-kit.tsx` `StudioEnv/Lights/Floor/Effects`), all motion off `useCurrentFrame()`. Premium tier. *(Trends §1, Animation §2.)*
 9. **Mesh-gradient + glass lower-third promo** — clean modern, IG-friendly, palette-driven, grain on top. *(Trends §1.)*
 10. **Grunge / collage / anti-AI pack** — rides the authenticity wave for youth/music; uses hand-type, paper overlays, deterministic jitter. *(Trends §1.)*
 **Tier 3 — craft & process maturity**
 11. **Adopt the 5-pass workflow (reference → blocking → timing → polish → review) as the team norm**, and seed a reference library (AE templates / Dribbble loops) per template type. *(Animation §2.)*
 12. **Per-aspect tuning audit** of existing templates — stagger + scale via `pick`, re-flow not letterbox, confirm Persian RTL never clips. *(Animation §2, `../remotion-aspect-ratios/SKILL.md`.)*
 13. **Color system discipline** — enforce dopamine-accent-+-neutral/pastel-base + grain-overlay defaults; run user hex through the grade so no garish value breaks a look. *(Trends §1, Masterpiece §4.)*
 ---
 ## Sources
 **Trends:** [Envato — Motion Trends 2026](https://elements.envato.com/learn/motion-design-trends) · [MonkyVision](https://monkyvision.com/blog/motion-design-trends/) · [GraphicDesignJunction](https://graphicdesignjunction.com/2026/01/video-and-motion-creative-trends-2026/) · [Krumzi](https://www.krumzi.com/blog/12-graphic-design-trends-shaping-2026-and-how-ai-is-changing-the-game) · [It's Nice That](https://www.itsnicethat.com/features/forward-thinking-graphic-trends-2026-graphic-design-120126) · [Fontfabric](https://www.fontfabric.com/blog/10-design-trends-shaping-the-visual-typographic-landscape-in-2026/) · [Kittl](https://www.kittl.com/blogs/graphic-design-trends-2026/) · [StudioMeyer](https://studiomeyer.io/en/blog/webdesign-trends-2026) · [Envato — 3D Trends](https://elements.envato.com/learn/3d-design-trends) · [Patata School](https://www.patataschool.com/blender-typography-in-motion) · [Lummi — Animation Trends](https://www.lummi.ai/blog/animation-trends-2026) · [Fireart — Tactile Brutalism](https://fireart.studio/blog/the-best-web-design-trends/) · [AND Academy — Color](https://www.andacademy.com/resources/blog/graphic-design/color-trends-for-designers/) · [Gelato — Colors](https://www.gelato.com/blog/trending-colors) · [Adobe Express — Color of Year](https://www.adobe.com/express/learn/blog/color-of-year-trends) · [ALM Corp — Short-form](https://almcorp.com/blog/short-form-video-mastery-tiktok-reels-youtube-shorts-2026/) · [ShortSync](https://www.shortsync.app/resources/short-form-video-trends-2026) · [Sprout Social](https://sproutsocial.com/insights/social-media-trends/) · [FrameFlow](https://frameflowedit.com/article/top-5-video-editing-trends-in-2026)
 **Assets:** [Colorlib — Stock Video](https://colorlib.com/wp/best-free-stock-video-sites/) · [FreeConvert](https://www.freeconvert.com/blog/best-stock-video-sites/) · [Moonb](https://www.moonb.io/blog/best-stock-video-sites) · [awesome-cc0](https://github.com/madjin/awesome-cc0) · [Poly Haven](https://polyhaven.com/) · [Poly Haven License](https://polyhaven.com/license) · [Khronos glTF Samples](https://github.com/khronosgroup/gltf-sample-models) · [11 Free 3D Asset Sites](https://dev.to/markyu/11-free-3d-asset-sites-for-games-blender-and-webgl-ah2) · [Iran censorship (Wikipedia)](https://en.wikipedia.org/wiki/Internet_censorship_in_Iran) · [Iran tiered internet (Rest of World)](https://restofworld.org/2026/iran-blackout-tiered-internet/) · [Tech sanctions sheet](https://docs.google.com/spreadsheets/d/1b9tetXkMg4PB_XyWcsC_UWGv45MX3pZmasnDBhyQxlY/edit) · [Blocked in Iran](https://www.irun2iran.com/websites-and-social-media-blocked-in-iran/) · [AI Video 2026](https://aiunpacking.com/guides/ai-video-generation-sora-runway-kling-veo/) · [Best AI Video (PixVerse)](https://pixverse.ai/en/blog/best-ai-video-generators) · [Best AI Video (Pixflow)](https://pixflow.net/blog/best-ai-video-generator/)
 **Masterpiece + platform:** [IG Safe Zone (Outfy)](https://www.outfy.com/blog/instagram-safe-zone/) · [Reels Safe Zones (TryMyPost)](https://www.trymypost.com/blog/instagram-reels-safe-zones-text-placement-2026) · [IG Reel Size (InVideo)](https://invideo.io/blog/instagram-reel-size-guide/) · [IG Story Dimensions (AdMake)](https://admakeai.com/blog/instagram-story-dimensions-2026) · [TikTok Length (Go-Viral)](https://www.go-viral.app/blog/tiktok-video-length/) · [TikTok 3-Second Rule (2Point)](https://www.2pointagency.com/glossary/tiktok-creative-best-practices-the-3-second-rule/) · [TikTok Hooks (Selfstorming)](https://www.selfstorming.com/guides/social-media-hooks/tiktok-video-hooks) · [TikTok Captions (Blitzcut)](https://blitzcutai.com/blog/best-caption-style-tiktok) · [Shorts Length (OpusClip)](https://www.opus.pro/blog/ideal-youtube-shorts-length-format-retention) · [Shorts Best Practices (Miraflow)](https://miraflow.ai/blog/youtube-shorts-best-practices-2026-complete-guide) · [Shorts Safe Zone (Kreatli)](https://kreatli.com/guides/youtube-shorts-safe-zone) · [Post Production (Balance Studio)](https://www.balancestudio.tv/blog/color-grading-sound-mixing-motion-graphics-what-youre-really-paying-for-in-post-production) · [Sound Design in Motion (GUVI)](https://www.guvi.in/blog/sound-design-in-motion-graphics/)
 **Stack files referenced:** `D:\Projects\Flatrender2\services\remotion\src\lib\{anim,aspect,branding,fonts}.ts`, `three-kit.tsx`, `kit.tsx` · `src\templates.tsx` · asset root to create: `services\remotion\public\` (currently only `fonts\`) · manifest to create: `services\remotion\public\{assets.json,ASSETS.md}` · suggested: `src\lib\grades.ts`.
@@ -0,0 +1,91 @@
 ---
 name: remotion-aspect-ratios
 description: How to design ONE Remotion template that genuinely fits all three FlatRender aspects — 16:9, 1:1, 9:16 — without text cropping, off-screen elements, or a layout that is really just the 16:9 version letterboxed. Use whenever building or reviewing a template's layout. Read this BEFORE positioning any text or element.
 ---
 # Designing for 16:9 / 1:1 / 9:16 (do this right)
 Every template registers in all three aspects (`ASPECTS` in `src/lib/aspect.ts`). A common mistake (made in early FlatRender templates) is to design for 16:9 and just let the same coordinates render in 9:16 — which **crops text, pushes elements off-screen, and looks broken**. A template must be *re-laid-out* per aspect, not scaled.
 ## Two strategies — responsive component OR per-aspect components
 There are TWO legitimate ways to support the three aspects; pick per template:
 1. **One responsive component** (default) — a single composition that adapts via `useLayout()` (`isWide/isSquare/isTall`, `pick()`). Use when the design is fundamentally the same and only positions/sizes change. Less code, stays in sync.
 2. **A dedicated component per aspect** — when the design must differ STRUCTURALLY (different layout, different scene, different element set), not just reposition. e.g. a cinematic wide hero vs a stacked vertical story vs a centered square badge can be genuinely different scenes.
 The registry supports both. In `services/remotion/src/templates.tsx` a `TemplateDef` has `component` (shared default) plus an optional `componentsByAspect` map keyed by aspect id:
 ```tsx
 {
  id: "MyTemplate",
  component: MyTemplateWide,            // fallback for any aspect not overridden
  componentsByAspect: {
    "1x1":  MyTemplateSquare,           // dedicated square design
    "9x16": MyTemplateTall,             // dedicated vertical design
  },
  schema, durationSec, defaultProps,    // SHARED across aspects — keep the editable
 }                                       //   fields, props and duration identical
 ```
 `Root.tsx` picks `componentsByAspect[aspectId] ?? component`. **Keep `schema`, `defaultProps`, and `durationSec` shared** so the studio shows the same editable fields and the same composition ids (`${id}-${aspect}`) regardless — only the visual layout differs. Reuse shared sub-components (background, characters, text overlay) across the per-aspect files so they don't drift.
 Guideline: start with one responsive component; split into per-aspect components only when responsive branching gets gnarly or the designs truly diverge. Don't duplicate three files when `pick()` would do.
 ## Why the naive approach breaks
 `useLayout().vmin(n)` sizes off the SHORT side (1080 in all three aspects), so a `vmin(92)` font is the same pixel size everywhere. But the WIDTH differs hugely: **1920px (16:9) vs 1080px (9:16)**. A headline that fits 1920 wide overflows/crops at 1080 wide. Likewise positioning at `width*0.34` puts an element in a totally different place relative to its own size when width changes.
 ## The rules
 1. **Design 9:16 (tall) first.** It's the tightest. If it fits there, widening to 1:1 and 16:9 is easy. Building 16:9-first guarantees the tall version breaks.
 2. **Branch layout on `L.isWide / L.isSquare / L.isTall`** — don't just scale. Things that sit side-by-side in 16:9 should STACK vertically in 9:16:
   ```tsx
   const L = useLayout();
   // hero element position differs per aspect
   const heroX = L.isTall ? L.width * 0.5 : L.width * 0.34;   // centered in tall, left in wide
   // layout direction
   flexDirection: L.isTall ? "column" : "row"
   ```
   Add a tiny helper to `aspect.ts` and use it everywhere:
   ```ts
   pick: <T,>(wide: T, square: T, tall: T): T =>
     kind === "wide" ? wide : kind === "tall" ? tall : square,
   ```
   Then: `fontSize: L.pick(L.vmin(92), L.vmin(84), L.vmin(72))`.
 3. **Cap font size to the WIDTH, not just the short side.** Headlines must wrap, never crop. Always set `maxWidth` and let text wrap:
   ```tsx
   maxWidth: L.width * 0.86, // safe text column
   // and scale type DOWN in tall:
   fontSize: L.pick(L.vmin(90), L.vmin(80), L.vmin(64)),
   wordBreak: "normal", lineHeight: 1.15,
   ```
   Test with the LONGEST realistic Persian string for that field, not the short default.
 4. **Respect SAFE ZONES.** Keep all meaningful content inside the central safe area; give tall more vertical margin:
   - 16:9: ~5% horizontal / 8% vertical padding.
   - 9:16: ~8% horizontal, and keep the hero in the middle 60% vertically (top/bottom of phones get UI chrome).
   Anchor text blocks to a zone (top third / bottom third), put the hero visual in the center.
 5. **Reposition the hero per aspect.** A character/object that's at `x=34%` and text on the right in 16:9 should become hero-centered with text above/below in 1:1 and 9:16. Use `pick()` for x/y and for `justifyContent`/`alignItems`.
 6. **Scale element COUNT/spread, not just size.** A row of 5 floating shapes that spans 1920 looks sparse/clipped at 1080 — reduce spread radius or count in tall (`L.pick(...)`).
 7. **3D:** adjust `camera.fov` / `position.z` per aspect so the subject fills the frame (a tall frame needs the camera pulled back or a narrower fov). Keep the 2D text overlay using the same `pick()` rules.
 ## Mandatory verification (the step that was skipped before)
 Render a still in **all three aspects** at a frame where text is visible, with a LONG test string, and LOOK at each:
 ```
 npx remotion still src/index.ts "<Comp>-16x9" out/_a.png --frame=NN
 npx remotion still src/index.ts "<Comp>-1x1"  out/_b.png --frame=NN
 npx remotion still src/index.ts "<Comp>-9x16" out/_c.png --frame=NN
 ```
 Reject if: text is clipped at any edge, an element is off-frame, the hero is tiny/huge, or the tall version is obviously "the wide one squished".
 ## Checklist
 - [ ] Designed tall-first; used `pick()`/`isTall` to branch layout (not just scale).
 - [ ] Headlines wrap with `maxWidth`; tested with long Persian text — no cropping.
 - [ ] Hero repositioned/centered per aspect; content in safe zones.
 - [ ] Spread/count adjusted for narrow frames; 3D fov/camera tuned per aspect.
 - [ ] Eyeballed stills in ALL THREE aspects.
 Related: `../remotion-template-composition/SKILL.md`, `../remotion-design-styles/SKILL.md`.
@@ -0,0 +1,51 @@
 ---
 name: remotion-character-design
 description: How to build and animate 2D (SVG) and 3D (@remotion/three) characters and mascots for FlatRender Remotion templates. Use when a template needs a character — a mascot, Haji Firuz, animals (goldfish, butterflies), people, or any articulated figure. Covers construction from primitives, rigging via grouped transforms, animation cycles (walk/dance/idle), facial expression, and the 2D-vs-3D / GLTF trade-offs.
 ---
 # Character design for Remotion
 We have NO rigged 3D model assets and the asset CDNs are geo-blocked, so characters are built from **primitives** — SVG shapes (2D) or Three.js geometries (3D) — and animated off `useCurrentFrame()`. Reference implementations: `NowruzGreeting.tsx` (2D Haji Firuz, goldfish, butterflies) and `Nowruz3D.tsx` (3D scene).
 ## Core principle: build in parts, rig with groups
 A character = a tree of grouped parts, each animated by transforming its group around a PIVOT.
 - 2D: nested `<g transform="translate/rotate/scale">`. Put the pivot at the joint (e.g. shoulder) by translating the group there, drawing the limb from origin, and rotating the group.
 - 3D: nested `<group position rotation>`. Same idea — position the group at the joint, model the limb from there, rotate the group.
 ## 2D characters (SVG)
 Construction kit:
 - Head = `<circle>`; body = `<path>` trapezoid (`M.. Q..`); limbs = `<rect rx>` (rounded) or `<path>`; hands/feet = small ellipses; hat = `<path>` triangle/cone.
 - Face (friendly/stylized): two dot eyes, a `Q` curve smile, rosy `circle` cheeks at low opacity. Keep it simple — over-detailing reads worse, not better.
 - Skin/clothing: flat fills + one darker shade for a soft AO at edges (`fillOpacity` overlay).
 Animating cycles (all from `frame`):
 - **Idle/breathe:** body `scale.y = 1 + 0.02*sin(frame/30)`.
 - **Dance/bounce:** whole body `translateY = -abs(sin(frame/7))*H`, plus a small `rotate(sin(frame/7)*4)` sway; legs counter-rotate.
 - **Limb swing:** `rotate(amp*sin(frame/period))` around the joint pivot.
 - **Hop-in entrance:** `spring()` from off-frame X to the target, then switch to the idle/dance loop.
 - **Prop shake (tambourine, flag):** `rotate(sin(frame/3.2)*18)` + sparkle accents on peaks.
 ## 3D characters (primitives)
 Build the figure from: `sphereGeometry` (head/joints), `cylinderGeometry`/`capsule` (limbs/torso), `coneGeometry` (hat/skirt), `RoundedBox` (blocky bodies), `torusGeometry` (rings/mouth). Group per limb for articulation. Material: `meshStandardMaterial` (roughness ~0.5 for cloth, lower for shiny). Light with `three-kit` StudioLights; add a soft contact shadow (a dark blurred plane or `shadows` + a floor).
 - 3D animation is the SAME math (rotate/translate groups by `frame`), just in 3D space and you can also move the camera/scene for parallax.
 - Faces in 3D are hard — keep them simple (sphere eyes, a small torus/curve mouth) or face the character slightly away.
 ## Animation principles (what makes it not look stiff)
 - **Anticipation:** dip before a jump, wind-up before a throw.
 - **Squash & stretch:** scale on impacts/landings (subtle: ±8%).
 - **Overlap / secondary motion:** hat ball, scarf, string, ears, tambourine lag behind the body — offset their phase.
 - **Easing:** `Easing.out(Easing.cubic)` for arrivals, `spring()` for bouncy pops, never linear for organic motion.
 - **Hold:** let a pose read for a beat before the next move.
 ## Cultural / brand-safety notes
 - Default to a **modern stylized** look (friendly, non-realistic) unless the user asks otherwise. Specifically for Haji Firuz: red costume + conical hat + tambourine, but a friendly non-blackface face (avoids the blackface connotation).
 - Confirm a storyboard with the user BEFORE building complex characters (the project convention) — list the cast, the beats, and the look.
 ## When NOT to hand-build
 - Photoreal humans or complex rigged motion → out of scope without GLTF assets; propose a stylized take or a non-character design instead.
 - If a GLTF model IS provided, load with drei `useGLTF` and animate transforms by `frame` (no `useFrame`).
 ## Workflow
 Storyboard → build parts → rig groups → animate cycles → **render stills at 3-4 beats and LOOK** → refine → render all 3 aspects (see `../remotion-aspect-ratios/SKILL.md` — characters must sit in the safe zone in 9:16 too).
 Related: `../remotion-design-styles/SKILL.md`, `../remotion-aspect-ratios/SKILL.md`, `../remotion-template-catalog/SKILL.md`.
@@ -0,0 +1,49 @@
 ---
 name: remotion-design-styles
 description: Visual art-direction reference for building FlatRender video templates with Remotion (2D) and Three.js/@remotion/three (3D). Use when starting a new template, picking an art style, designing color palettes, or designing objects/scenes. Covers flat, gradient/mesh, glassmorphism, neon, 3D/cinematic, paper-cut, isometric, luxury looks plus color theory, lighting, and material design.
 ---
 # Remotion design styles (2D + 3D)
 Project location: `services/remotion/`. Shared helpers: `src/lib/anim.ts` (hexToRgba, mixHex, rand), `src/lib/branding.ts` (colorSchema + BRAND), `src/lib/aspect.ts` (useLayout), `src/lib/three-kit.tsx` (3D studio kit). Animate everything off `useCurrentFrame()` — never `Math.random()`/`Date.now()` (breaks determinism; use `rand(i)`), and in 3D never use R3F's `useFrame` (use `useCurrentFrame`).
 ## Pick a style first, then build
 Each template should commit to ONE art style — mixing reads as "basic". Catalog:
 | Style | Look | How (Remotion) | Best for |
 |---|---|---|---|
 | Flat / minimal | solid fills, generous whitespace, 1-2 accents | SVG shapes, simple springs | corporate, clean promos |
 | Gradient / mesh | soft drifting color blobs | blurred radial-gradient divs animated by frame (see GradientPromo) | modern SaaS, backgrounds |
 | Glassmorphism | frosted translucent cards | `backdrop-filter: blur`, rgba fills, thin borders | UI/app promos |
 | Neon / glow | dark bg + luminous strokes | `drop-shadow`/`textShadow` glows, emissive in 3D | gaming, nightlife, tech |
 | 3D / cinematic | real depth, reflections, bokeh | @remotion/three + three-kit (lighting, MeshReflectorMaterial, bloom/DOF) | premium logo/product reveals |
 | Paper-cut / layered | stacked shapes with soft shadows | layered SVG + offset box-shadows | storytelling, kids, greetings |
 | Isometric | 2.5D objects on a grid | SVG with skew/`rotateX` CSS, or true 3D ortho camera | explainer, product, city scenes |
 | Luxury / gold | dark + metallic gold + serif | gold gradients, shine sweeps, slow easing | weddings, premium brands |
 ## 2D vs 3D — choose deliberately
 - **2D (SVG/CSS):** fast to render, crisp text, full control, no WebGL. Use for flat/gradient/glass/neon/character scenes, anything text-heavy.
 - **3D (@remotion/three):** depth, real lighting/reflections, bokeh, camera moves. Use for premium logo/product/abstract reveals. Costs render time. Setup is already done: R3F v9 + `Config.setChromiumOpenGlRenderer("angle")`. Reuse `three-kit.tsx` (StudioEnv, StudioLights, StudioFloor, StudioEffects, Confetti3D). Keep crisp Persian text as a 2D `<AbsoluteFill>` overlay ON TOP of `<ThreeCanvas>` — don't render Persian text in 3D.
 ## Color design
 - Drive every colorable element from the `colorSchema` props (accent / secondary / background / text) so the studio can recolor it — see `../remotion-svg-colors/SKILL.md`.
 - Build depth with VALUE, not just hue: dark bg → mid elements → bright accents/highlights. Add glow (`hexToRgba(accent, .6)` shadows) and a vignette (`inset 0 0 600px rgba(0,0,0,.6)`).
 - Gradients: 2-3 stops max; blend related hues (`mixHex(a,b,.5)`). Mesh look = several large blurred radial-gradient circles drifting on `sin(frame/…)`.
 - Contrast: text needs ≥ 4.5:1 over its backdrop — add a scrim/shadow when over busy/3D scenes.
 - Default palettes per mood: tech = blue→violet on near-black; festive = warm gold/red/green on cream or turquoise; luxury = gold on charcoal; fresh = teal/green on light.
 ## Object design
 - **2D:** compose from primitives — `<circle>`, `<rect rx>`, `<path>` (quadratic `Q` for organic curves). Reuse `rand(i)` for deterministic scatter (particles, confetti, petals). Add glow via SVG `filter: drop-shadow`.
 - **3D:** primitives + good material = premium. `meshStandardMaterial` with `metalness` 0.3-0.7, `roughness` 0.15-0.35, `flatShading` for faceted gems, `emissive`+`emissiveIntensity` for glow that bloom picks up (set `toneMapped={false}` on flames/glows). Light with 3-point + colored rims (StudioLights). Faceted icosahedron/octahedron/dodecahedron read as "gems"; RoundedBox for gifts/cards.
 ## Motion = polish
 Stagger entrances (don't reveal everything at once), use `spring()` for pops and `interpolate(..., Easing.out(Easing.cubic))` for slides, add secondary motion (breathe, drift, twinkle), and a subtle continuous camera/scene sway in 3D. Hold the final frame ~1s for readability.
 ## Quality checklist
 - One coherent style; depth via value + glow + vignette.
 - All colors come from props (recolorable).
 - Staggered, eased motion with secondary detail.
 - Renders deterministically (no random/date).
 - Verify visually: render stills at 3-4 key frames and LOOK before shipping.
 Related: `../remotion-character-design/SKILL.md`, `../remotion-aspect-ratios/SKILL.md`, `../remotion-template-composition/SKILL.md`, `../remotion-svg-colors/SKILL.md`.
@@ -0,0 +1,59 @@
 ---
 name: remotion-music-picker
 description: How to choose royalty-free background music for a FlatRender template and sync the animation to its beat/vibe. Use when picking a music bed for a template, matching mood and BPM to the visuals, syncing reveals to the beat, or sourcing free/royalty-free tracks.
 ---
 # Music picker for templates
 > Status: templates currently ship without a music bed. This is the playbook for adding one. The right track + beat-synced motion is what makes a template feel "produced".
 ## Match music to the template's job
 | Template vibe | Genre / mood | Typical BPM |
 |---|---|---|
 | Corporate / SaaS logo | clean inspirational, soft piano + synth pluck | 90-110 |
 | Energetic promo / sale | upbeat pop, four-on-the-floor, claps | 120-130 |
 | Social / Insta / trendy | lo-fi or modern pop, punchy | 100-120 |
 | Epic / product reveal | cinematic build, big drum, riser | 70-90 build → hit |
 | Festive (birthday, Nowruz, party) | happy ukulele/marimba, bells | 110-128 |
 | Emotional (wedding, tribute) | warm piano/strings | 60-80 |
 | Tech / gaming | electronic, arpeggios, bass | 120-140 |
 | Luxury | downtempo, jazzy, smooth | 80-100 |
 | Minimal / explainer | light marimba/plucks, unobtrusive | 95-115 |
 ## Sync the animation to the beat (this is the magic)
 1. Know the track's BPM → frames per beat = `fps * 60 / bpm` (e.g. 30fps, 120bpm → 15 frames/beat).
 2. Land your hero reveals, pops, and cuts ON beats (multiples of frames-per-beat). Stagger small element pops on 1/2 or 1/4 beats.
 3. Put the BIG reveal on a musical downbeat or right after a riser/drop.
 4. For a known track, hardcode beat frames; for generic use, expose `bpm` as a prop and compute beat frames so motion stays in sync if the track changes.
 ```tsx
 const FPS = 30, BPM = 120;
 const beat = (FPS * 60) / BPM;            // frames per beat
 const onBeat = (n: number) => Math.round(n * beat);
 // reveal hero on beat 4, CTA on beat 8
 ```
 ## Remotion wiring
 ```tsx
 import { Audio, staticFile, interpolate, useCurrentFrame, useVideoConfig } from "remotion";
 const { durationInFrames } = useVideoConfig();
 const f = useCurrentFrame();
 <Audio src={staticFile("music/upbeat-120.mp3")}
  volume={(ff)=>interpolate(ff,[0,15,durationInFrames-20,durationInFrames],[0,0.7,0.7,0])} />
 ```
 - Fade IN over ~0.5s and OUT over the last ~0.7s — never start/end abruptly.
 - Trim/loop the track to the template length; cut on a bar boundary so the end feels intentional.
 - If there's a voiceover, DUCK the music (~-12 dB) under it.
 - Store beds in `services/remotion/public/music/`, named with BPM (`upbeat-120.mp3`).
 ## Free / royalty-free sources (verify license per track)
 - **Uppbeat** (free tier, gives a clearance ID), **Pixabay Music** (CC0-ish), **Mixkit** (free for commercial), **Bensound** (free w/ attribution or licensed), **Free Music Archive** (per-track CC), **YouTube Audio Library** (downloadable, check terms), **Incompetech / Kevin MacLeod** (CC-BY).
 - ALWAYS check: commercial use allowed? attribution required? Keep a per-file license/attribution record. Prefer CC0 / royalty-free-with-commercial. Avoid anything Content-ID-flagged for a product that exports user videos.
 - For an Iran-facing product, also consider local royalty-free Persian/instrumental sources where licensing is clearer.
 ## Workflow
 1. Pick vibe + BPM from the table for the template's purpose.
 2. Source 2-3 candidate tracks (license-checked), audition against the animation.
 3. Re-time the key reveals to the chosen BPM's beats.
 4. Add `<Audio>` with fades; render and LISTEN; nudge beats until reveals hit on the downbeat.
 Related: `../remotion-sound-effects/SKILL.md`, `../remotion-template-catalog/SKILL.md`.
@@ -0,0 +1,56 @@
 ---
 name: remotion-sound-effects
 description: Which sound effects (SFX) to use for FlatRender video templates and exactly where to place them in the timeline. Use when adding audio punch to a template — whooshes, impacts, sparkles, pops, risers, confetti — and syncing them to keyframes with Remotion's Audio component.
 ---
 # Sound-effect design for templates
 > Status: current FlatRender templates have NO audio yet. This skill is the playbook for adding it. SFX dramatically raise perceived quality — a logo "thud" + sparkle makes a reveal feel pro.
 ## How audio works in Remotion
 Use `<Audio>` from `remotion`, placed in the composition tree, timed to frames:
 ```tsx
 import { Audio, useVideoConfig } from "remotion";
 // play a one-shot SFX starting at frame 55 (the logo-land beat)
 <Audio src={staticFile("sfx/impact.mp3")} startFrom={0} volume={0.8}
       // mount it only around its moment using a <Sequence from={55}> wrapper
 />
 ```
 Patterns:
 - Wrap one-shots in `<Sequence from={FRAME}>` so they trigger at the right beat.
 - `volume` can be a function of frame for fades: `volume={(f)=>interpolate(f,[0,10],[0,1])}`.
 - Layer SFX over the music bed (see `../remotion-music-picker/SKILL.md`); keep SFX ~ -6 dB under dialogue, on top of music.
 - Put shared SFX in `services/remotion/public/sfx/` and load with `staticFile()`.
 ## SFX → moment mapping (sync to the KEYFRAME, not vaguely)
 | Moment in the animation | SFX | Place at |
 |---|---|---|
 | Element/text flies in | **whoosh** (short, directional) | 2-3 frames BEFORE it lands |
 | Logo / hero lands | **impact / thud / boom** | the exact land frame (spring settle) |
 | Glitter / magic reveal | **sparkle / shimmer / chime** | over the particle gather (0.3-0.5s) |
 | Small element appears | **pop / tick / blip** | each appearance (stagger to match) |
 | Countdown ticking | **clock tick** per number, **ding/airhorn** on GO | each number frame |
 | Birthday / party | **party horn + confetti rustle**, soft **chime** | greeting reveal + confetti burst |
 | Sale / promo | **cash register "cha-ching" / coin**, **stamp** on the badge | badge pop |
 | Shine sweep across logo | **soft shimmer swell** | sweep start→end |
 | Transition between scenes | **whoosh + light riser** | on the cut |
 | Build-up before reveal | **riser / uplifter** (0.5-1.5s) | leading INTO the hero moment |
 ## Placement principles
 - **Anticipation:** risers and whooshes START before the visual peak and resolve ON it. A whoosh that lands with the logo sells the motion.
 - **One hero hit:** the reveal gets ONE big impact — don't stack 3 booms; it muddies.
 - **Match the motion curve:** fast spring = sharp transient; slow ease = soft swell.
 - **Stagger to the visuals:** if 5 elements pop on different frames, 5 pops on those frames (vary pitch slightly so it's not robotic).
 - **Less is more:** 3-6 well-placed SFX per template beats a wall of sound. Leave silence for contrast.
 - **Loudness:** normalize SFX, peak ~ -3 dB, sit them under the music bed; the final mix shouldn't clip.
 ## Free / royalty-aware SFX sources
 Mixkit, Pixabay (sound), Freesound (check each license — CC0 vs attribution), Uppbeat (free tier), and Remotion-safe CC0 packs. ALWAYS record the license per file; prefer CC0/royalty-free with commercial use. Keep an attributions file if any source requires it.
 ## Workflow
 1. Identify the 3-6 key beats (reveal, pops, transitions, CTA).
 2. Pick one SFX per beat from the table.
 3. Place via `<Sequence from={frame}>` + `<Audio>`; tune volume + a short fade.
 4. Render with audio and LISTEN — adjust timing by a few frames so hits land exactly on the visual.
 Related: `../remotion-music-picker/SKILL.md`, `../remotion-template-composition/SKILL.md`.
@@ -0,0 +1,45 @@
 ---
 name: remotion-svg-colors
 description: How FlatRender makes template colors user-editable and generates per-scene SVG so the studio can recolor a template and preview it in real time. Use when wiring a template's colors to the studio color picker, choosing which elements are recolorable, or generating an SVG color-preview for a scene.
 ---
 # SVG + color system (real-time recolor)
 Goal: a user opens a template, changes its colors, and sees the result update live. This works because every colorable element reads from a NAMED color, those names are stored as editable color elements in the DB, and a lightweight SVG representation lets the studio recolor without a full re-render.
 ## The color data model
 - **`content.shared_colors`** — project-wide colors (key = `element_key`, e.g. `accentColor`). Used by every scene.
 - **`content.scene_color_elements`** — per-scene colors (key = `element_key`, e.g. `frl_c1t1` for AE, or a Remotion prop name).
 - Studio copies these into `studio.saved_shared_colors` / `saved_scene_colors`; the render binder (`GetRenderBindings` in render-svc) returns them as `{element_key: hex}`.
 - For **Remotion**, those keys must equal the composition's `colorSchema` props: `accentColor`, `secondaryColor`, `backgroundColor`, `textColor` (from `src/lib/branding.ts`). The node-agent passes them as `--props`.
 - For **AE**, colours bind into the `frshare` comp's text layers (`bind.jsx`).
 **Rule:** design every template so EVERY colorable element's color comes from a named prop — never a hardcoded hex for anything the user should be able to change. Seed a `shared_colors` row per color prop (the seed script already does accent/secondary/background/text).
 ## The SVG color-preview (live recolor without re-rendering)
 A full Remotion/AE re-render is too slow for a color picker. So a scene is also represented as an **SVG** whose shapes' `fill`/`stroke` reference the SAME color keys. The studio swaps the SVG's colors instantly as the user drags the picker.
 - AE pipeline: `content.projects.shared_colors_svg` + the `template_svg_previews` table + per-scene snapshots.
 - For a Remotion template, generate an SVG snapshot of a representative frame where colorable regions are tagged with their key, e.g.:
  ```svg
  <rect ... fill="var(--accentColor)" data-color-key="accentColor"/>
  <text ... fill="var(--textColor)" data-color-key="textColor">...</text>
  ```
  The studio sets CSS variables (`--accentColor: #...`) or rewrites `fill` by `data-color-key` to recolor live; on export the real props go to the renderer.
 ## How to author a recolorable template
 1. Use the 4 `colorSchema` props for all themeable color (add more named props only if a template genuinely needs them — and seed a matching `shared_colors` row for each).
 2. Keep colorable regions as FLAT fills/strokes that map cleanly to one key (gradients = blend of two named props via `mixHex`, still derived from props).
 3. Produce an SVG preview of the key frame with each region tagged `data-color-key` = the prop name, so the studio can map picker → region.
 4. Verify: changing a prop changes exactly the intended regions and nothing hardcoded stays the wrong color.
 ## Generating the SVG
 - Simple/flat scenes: hand-author or script an SVG mirroring the composition's shapes, tagging fills with the color keys.
 - 3D / complex scenes: an SVG can't represent them faithfully — fall back to a rendered key-frame thumbnail per color theme, or a simplified 2D SVG stand-in for the picker (note this limitation to the user).
 - Store alongside the template (the AE path uses `shared_colors_svg` / `template_svg_previews`; mirror that for Remotion).
 ## Pitfalls
 - A hardcoded hex on a "should-be-editable" element = the picker silently does nothing there. Audit for stray hexes.
 - Key mismatch (SVG `data-color-key` ≠ schema prop ≠ seeded `element_key`) breaks the binding — keep ONE naming source of truth.
 - Contrast: when users can recolor text + background, enforce/encourage a min contrast or the text can vanish.
 Related: `../remotion-template-composition/SKILL.md`, `../remotion-design-styles/SKILL.md`.
@@ -0,0 +1,54 @@
 ---
 name: remotion-template-catalog
 description: A taxonomy of video template TYPES to build for FlatRender, with the purpose, key editable elements, suggested style/aspect, and 2D-vs-3D recommendation for each. Use when deciding what template to create next, planning a content batch, or scoping a requested template into a known pattern.
 ---
 # Template catalog — what to build
 FlatRender already has these (services/remotion `TEMPLATES`): IlluminatedCircles, KineticQuote, GradientPromo, VerticalStory, LogoMotion, Opener, InstaPromo, YouTubeIntro, Slideshow, HappyBirthday, SalePromo, QuoteCard, EventInvite, Countdown, GlitterReveal (editable logo), NowruzGreeting (2D characters), + 3D: Hero3D, Nowruz3D, Birthday3D, Promo3D.
 Use this map to pick the NEXT one and to scope a request into a pattern. Each row: key editable elements · suggested style · best aspect(s) · 2D/3D.
 ## Brand / logo
 - **Logo reveal** — logo + tagline · any style · all aspects · 2D or 3D. (have: IlluminatedCircles, LogoMotion, GlitterReveal, Hero3D)
 - **Opener / intro sting** — title + subtitle · cinematic/kinetic · 16:9, 9:16 · 2D/3D. (have: Opener)
 - **Outro / subscribe / end-card** — CTA + socials + logo · flat/neon · 16:9, 9:16 · 2D. (gap)
 - **Lower-third / name tag** — name + role · clean/glass · 16:9 · 2D. (gap)
 ## Social / marketing
 - **Instagram post/story promo** — headline + image + CTA · gradient/bold · 1:1, 9:16. (have: InstaPromo, VerticalStory)
 - **YouTube intro/outro** — channel + subscribe · energetic · 16:9. (have: YouTubeIntro)
 - **TikTok/Reels hook** — big kinetic text · trendy · 9:16 · 2D. (gap)
 - **Sale / discount** — badge + headline + CTA · bold/3D gifts · all. (have: SalePromo, Promo3D)
 - **Product showcase / turntable** — product image/3D + specs · 3D cinematic · 16:9, 1:1. (gap — high value)
 - **Testimonial / review** — quote + stars + name/photo · clean · 1:1, 9:16. (gap)
 - **Explainer / feature list** — icon + text steps · isometric/flat · 16:9. (gap)
 - **Real-estate / listing** — photos + price + details · elegant · 16:9, 1:1. (gap)
 - **Restaurant / menu / food** — dish image + price · warm/appetizing · 1:1, 9:16. (gap)
 ## Greetings / occasions (great for characters + 3D)
 - **Birthday** — name + message · party/3D cake · all. (have: HappyBirthday, Birthday3D)
 - **Nowruz (نوروز)** — greeting + year · spring characters/3D Haft-Sin · all. (have: NowruzGreeting, Nowruz3D)
 - **Yalda (یلدا)** — pomegranate/watermelon, candles, warm night · 2D/3D · all. (gap — high value, Persian)
 - **Wedding / engagement** — names + date · luxury gold/floral · all. (gap)
 - **Eid / Ramadan / Mehregan** — lantern/crescent/autumn motifs · ornate · all. (gap, Persian/region)
 - **New Year / holidays** — countdown + fireworks · festive 3D · 16:9, 9:16. (gap)
 - **Condolence / tribute** — respectful, minimal, slow · muted palette · all. (gap)
 ## Content / text
 - **Quote card** — quote + author · kinetic/typographic · 1:1, 9:16. (have: QuoteCard, KineticQuote)
 - **Countdown** — target + number · energetic riser · all. (have: Countdown)
 - **Event invite** — title + date/place + RSVP · elegant · 1:1, 9:16. (have: EventInvite)
 - **Slideshow / photo gallery** — N images + captions · clean transitions · all. (have: Slideshow)
 - **Music visualizer** — audio-reactive bars + cover · neon/3D · 1:1, 9:16. (gap)
 ## How to choose next
 1. Prefer **gaps** with high value for an Iran-facing product: Yalda, wedding, product showcase, testimonial, lower-thirds, outro/subscribe, music visualizer.
 2. Pick a STYLE that differs from neighbors (don't ship five dark-particle reveals) — see `../remotion-design-styles/SKILL.md`.
 3. Decide 2D vs 3D by subject (logos/products/abstract → 3D shines; text/character/illustrative → 2D or hybrid).
 4. Confirm a storyboard with the user for anything character- or scene-heavy.
 ## Per-template build steps
 Storyboard (confirm) → build composition (lib helpers, design-styles, character-design) → make it fit all aspects (`../remotion-aspect-ratios/SKILL.md`) → wire editable text/logo/colors (`../remotion-template-composition/SKILL.md`, `../remotion-svg-colors/SKILL.md`) → pick fonts (`../persian-fonts/SKILL.md`) → optional music/SFX → render thumbnails + preview → seed (`scripts/seed_remotion_templates.py`) → deploy.
 Related: every other remotion-* skill.
@@ -0,0 +1,60 @@
 ---
 name: remotion-template-composition
 description: How to compose the editable elements of a FlatRender template — text, logo, image/media, and supporting copy — into a clear, well-paced presentation. Use when laying out what goes where, deciding the visual hierarchy, wiring editable fields, or timing the reveal sequence of a template.
 ---
 # Composing a template (text / logo / image / copy)
 A template is not just a nice animation — it's a *fill-in-the-blanks* product. Users edit a few fields and it must look great with THEIR text/logo. Design for editability + clarity.
 ## The binding model (how editable fields work)
 Editable elements live in the DB and bind to Remotion props by KEY (see `../remotion-svg-colors/SKILL.md` for the full pipeline):
 - **Text** → `content.scene_content_elements` of type `Text`; the element `key` MUST equal the composition's Zod schema field (e.g. `headline`, `tagline`). Studio shows a text input.
 - **Logo / image / media** → a `scene_content_elements` of type `Media`; key = a `z.string()` prop (e.g. `logoUrl`). Studio shows upload/replace. In the composition: `logoUrl ? <Img src={logoUrl}> : <DefaultMark/>`. See `GlitterReveal.tsx`.
 - **Colors** → `shared_colors` / `scene_color_elements`, key = a `colorSchema` prop.
 - Seed all of these via `scripts/seed_remotion_templates.py` (it has a `MEDIA` dict for image fields).
 **Rule:** every visible piece of copy or media a user would want to change MUST be a prop + a seeded element. Don't hardcode the brand name, date, price, etc.
 ## Visual hierarchy (most templates need 2-4 tiers)
 1. **Primary** — the logo OR the headline/hero. Biggest, highest contrast, center of attention.
 2. **Secondary** — tagline / subtitle. ~35-45% of primary size.
 3. **Tertiary** — CTA, date, price badge, handle. Small but distinct (pill, badge, accent color).
 4. **Ambient** — decorative scene (particles, 3D, characters) — supports, never competes.
 Size ratios that read well: primary `vmin(80-110)`, secondary `vmin(26-40)`, tertiary `vmin(24-32)`. Weight: primary 800-900, secondary 500-700, tertiary 600-900.
 ## Text legibility (critical over busy/3D backgrounds)
 - Add a scrim or shadow: `textShadow: 0 0 vmin(20) rgba(0,0,0,.7)`, or a semi-transparent panel behind text.
 - Persian is RTL: set `direction: "rtl"`, use `FONT` (Vazirmatn) from `lib/fonts.ts`. See `../persian-fonts/SKILL.md`.
 - Keep line length comfortable (`maxWidth ~ 86%`); never let text touch frame edges (see `../remotion-aspect-ratios/SKILL.md`).
 - For gradient text use `backgroundClip: text` + a `drop-shadow` for separation.
 ## Logo placement
 - Center-stage for logo reveals; corner/lockup for promos.
 - Always provide a branded DEFAULT (the FlatRender mark) so the template looks finished before the user uploads.
 - Constrain with `maxWidth/maxHeight` + `objectFit: contain` so any uploaded logo fits without distortion.
 ## Image / media
 - `objectFit: cover` for fullscreen backdrops (with a gradient scrim for text), `contain` for product/logo.
 - Add motion: slow Ken-Burns (`scale 1→1.08` + slight pan) so stills feel alive.
 - Mask into shapes (rounded rect, circle) for polish.
 ## Timing & pacing (the reveal sequence)
 Stagger — never reveal everything at frame 0. A typical 6s (180f @30) beat sheet:
 - 0-30: scene/background establishes, ambient starts.
 - 20-55: hero/logo springs in (`spring()`), optional flash/impact.
 - 55-90: headline rises/fades in.
 - 90-120: tagline fades, letter-spacing settles.
 - 120-160: CTA/date pops (`spring`, glow pulse).
 - last ~30f: hold everything still for readability.
 Give each text element ~0.6-0.8s on screen minimum before the next competes.
 ## Editability checklist
 - [ ] Every changeable text/logo/image/color is a prop + seeded element (key == schema field).
 - [ ] Branded default for logo + sensible default copy.
 - [ ] Clear 2-4 tier hierarchy; text legible over the background.
 - [ ] Staggered, eased reveal with a final hold.
 - [ ] Looks good with long Persian text and a tall logo (test it).
 Related: `../remotion-svg-colors/SKILL.md`, `../remotion-aspect-ratios/SKILL.md`, `../persian-fonts/SKILL.md`, `../remotion-design-styles/SKILL.md`.
@@ -0,0 +1,121 @@
 ---
 name: scene-transitions
 description: How to choreograph transitions BETWEEN scenes (and shots within a scene) in FlatRender Remotion templates — cut, dissolve, wipe, clip-path mask, morph, match-cut, shape transition, camera push, zoom/whip-blur — built from primitives. Use whenever a template has more than one scene/beat, when one element must hand off to the next, or when stitching multi-scene sequences so they feel seamless instead of slideshow-y. Read before sequencing scenes.
 ---
 # Scene transitions for Remotion
 A multi-scene template lives or dies on its *joins*. A hard slideshow of fades reads as "made in a tool"; a transition that carries motion, color, or a shape across the cut reads as "made by a studio". We have **no `@remotion/transitions` package** (not a dependency) and asset CDNs are geo-blocked — so every transition is built from primitives: `<Sequence>`, `interpolate`/`spring`, CSS `clipPath`/`maskImage`, blend modes, and (for 3D) a camera move driven by `useCurrentFrame()`. Everything is a pure function of `frame` — **never** `useFrame`, `Math.random`, `Date.now` (use `rand()` from `lib/anim.ts`).
 ## The one structural rule: overlap, don't abut
 A clean transition needs scenes to **overlap** for the transition window (12–20f). Don't place `<Sequence>`s back-to-back — give the outgoing scene a tail and the incoming a head that share the window.
 ```tsx
 import { Sequence, useVideoConfig } from "remotion";
 const { fps } = useVideoConfig();
 const sec = (s: number) => Math.round(s * fps);   // never hardcode 30
 const T = sec(0.5);                                // transition window
 // Scene A holds frames 0..120, Scene B starts at 120-T so they cross-fade
 <Sequence from={0} durationInFrames={120}><SceneA /></Sequence>
 <Sequence from={120 - T} durationInFrames={120}><SceneB /></Sequence>
 ```
 Inside each scene, derive a local progress from `useCurrentFrame()` (already 0-based inside a `Sequence`) for its *in* and *out* phases.
 ## Transition catalog — what to build, when, and how
 | Transition | فارسی | Feel / when | Build (primitive) |
 |---|---|---|---|
 | **Cut** | برش | Hard, energetic, beat-synced, brutalist/anti-design | No overlap; `<Sequence>` ends, next begins. Snap a 1f flash or shake for punch. |
 | **Dissolve / crossfade** | محو | Calm, elegant, photo decks, luxury | Outgoing `opacity 1→0`, incoming `0→1` over the window, `clamp` both. |
 | **Wipe** | پاک‌کن | Directional energy, news/promo | `clipPath: inset()` on the incoming layer sweeps a hard edge (see below). |
 | **Clip-path mask reveal** | ماسک | Premium reveals, shape brand moment | Animate a `circle()`/`polygon()` `clipPath` open over the new scene. |
 | **Morph** | ریخت‌گردانی | Liquid/organic, kinetic trend | Animate SVG `path d` (`flubber`-style) or `feGaussianBlur`+`feColorMatrix` gooey merge. |
 | **Match-cut** | برش تطبیقی | Storytelling, "made by a studio" | A shape/element at the SAME position+size in both scenes; cut while it's identical. |
 | **Shape transition** | گذار شکلی | Brand mark grows into scene | A circle/blob scales up to fill frame (color = `accent`), then the new scene is revealed inside it. |
 | **Camera push / dolly** | حرکت دوربین (۳بعدی) | Cinematic, 3D logo/product | Move the R3F camera `position.z` / target between two staged setups by `frame`. |
 | **Zoom / whip blur** | زوم/تار حرکتی | Fast, hype, music, TikTok | Scale up + `filter: blur()` on out, scale-down + blur-out on in; peak blur ON the cut. |
 ### Wipe (clip-path inset)
 ```tsx
 import { useCurrentFrame, interpolate, Easing } from "remotion";
 const f = useCurrentFrame();                          // local frame in the incoming Sequence
 const p = interpolate(f, [0, sec(0.45)], [0, 100], {
  extrapolateLeft: "clamp", extrapolateRight: "clamp",
  easing: Easing.bezier(0.16, 1, 0.3, 1),
 });
 // RTL-aware: wipe in from the right for Persian (mirror the direction in `en`)
 <AbsoluteFill style={{ clipPath: `inset(0 0 0 ${100 - p}%)` }}><SceneB/></AbsoluteFill>
 ```
 Soften the edge with a leading gradient strip (a thin `accent` bar riding `p`) for a "luminance wipe".
 ### Clip-path circle / shape reveal
 ```tsx
 const r = interpolate(spring({ frame: f, fps, config: { mass: 0.6, damping: 14 } }),
                      [0, 1], [0, 150]);              // 150% covers corners
 <AbsoluteFill style={{ clipPath: `circle(${r}% at 50% 50%)` }}><SceneB/></AbsoluteFill>
 ```
 For a brand shape transition: render a full-frame circle filled with `colorSchema.accent` scaling up over Scene A, then swap to Scene B *masked by the same circle* — the brand color carries the cut.
 ### Zoom / whip-blur
 ```tsx
 // outgoing tail
 const out = interpolate(f, [0, T], [1, 1.4], { extrapolateRight: "clamp" });
 const blurOut = interpolate(f, [0, T], [0, vmin(24)], { extrapolateRight: "clamp" });
 <AbsoluteFill style={{ transform: `scale(${out})`, filter: `blur(${blurOut}px)` }}><SceneA/></AbsoluteFill>
 // incoming head (local frame): scale 1.25→1, blur 24→0 — peak blur of BOTH meets on the cut
 ```
 `vmin` comes from `useLayout()` (`lib/aspect.ts`) so the blur reads the same in all three aspects.
 ### Camera push (3D, @remotion/three)
 ```tsx
 // inside <ThreeCanvas> — drive the camera off frame, NOT useFrame
 const z = interpolate(spring({ frame: f, fps, config: { mass: 2.5, damping: 26 } }),
                      [0, 1], [7, 3.2]);              // dolly in, heavy = weight
 useThree(({ camera }) => { camera.position.z = z; camera.updateProjectionMatrix(); });
 ```
 Use `StudioEnv/StudioLights/StudioFloor/StudioEffects` from `lib/three-kit.tsx`; let DOF + bloom + vignette sell the move. Camera moves use `ease-in-out`/heavy spring; never linear (linear is only for continuous orbit/rotation).
 ## Match-cut & seamless choreography (the studio-grade joins)
 The eye forgives a cut if **something continues across it**. Carry one of:
 - **Position+scale** — a circle bottom-left in Scene A is a circle bottom-left, same size, in Scene B. Cut while identical. (Classic match-cut.)
 - **Color** — Scene A ends on a full-frame `accent` wash; Scene B opens from that wash. Use `mixHex`/`hexToRgba` (`lib/anim.ts`) so it's palette-driven.
 - **Motion vector** — text exits stage-left at speed `v`; the next element enters from stage-right at the same `v`. Momentum reads as continuity.
 - **A mask** — the shape that wiped scene A out is the shape scene B wipes in with.
 For a full template: write a **beat list first** (logo in → tagline → 3 features cascade → CTA → out), assign one transition per join, and make adjacent joins *differ* (don't dissolve every cut) but **rhyme** (reuse the brand shape/color). Vary cut length and build to the hero moment — pacing is a transition too.
 ## Timing & easing (the difference between pro and slideshow)
 - **Window:** scene transition **12–20f**; whip/cut feels best at the short end, dissolve/camera at the long end.
 - **Entrances ease-out** (`Easing.out(Easing.quint)` / `Easing.bezier(0.16,1,0.3,1)`); **exits ease-in and always SHARPER than the entrance** — scenes leave faster than they arrive.
 - **A→B on-screen / camera = ease-in-out.** **Linear ONLY** for continuous rotation/marquee.
 - Snap transition `from` frames to the **music beats** (`../remotion-music-picker/SKILL.md`) so cuts land on downbeats.
 - Per-aspect: tighten the window on `isWide` (reads faster), loosen on `isTall`. Use the proposed `pick(wide,square,tall)` helper on `Layout` when it lands; until then branch on `isWide/isSquare/isTall`.
 ## Reusable transition components
 Build these once in `lib/` and reuse across templates — each takes an `enter`/`exit` phase and a window:
 ```tsx
 // CrossFade.tsx — wrap any scene; computes its own in/out from frame + duration
 export const Dissolve: React.FC<{ children: React.ReactNode; win: number }> = ({ children, win }) => {
  const f = useCurrentFrame();
  const { durationInFrames } = useVideoConfig();      // length of THIS Sequence
  const o = Math.min(
    interpolate(f, [0, win], [0, 1], { extrapolateRight: "clamp" }),
    interpolate(f, [durationInFrames - win, durationInFrames], [1, 0], { extrapolateLeft: "clamp" }),
  );
  return <AbsoluteFill style={{ opacity: o }}>{children}</AbsoluteFill>;
 };
 ```
 Make sibling wrappers `Wipe`, `CircleReveal`, `WhipZoom`, `ShapeWipe` with the same `(children, win, dir)` contract so a template can swap transitions by changing one wrapper. Keep the SFX hook in mind: a whoosh 2–3f before the cut + an impact ON it (`../remotion-sound-effects/SKILL.md`).
 ## Pre-ship transition checklist
 - [ ] No back-to-back `<Sequence>`s where a join should be smooth — scenes **overlap** the window.
 - [ ] Every join has a chosen transition with an *intent* (energy/calm/brand), not a default fade everywhere.
 - [ ] At least one join **carries** position, color, motion, or a mask across the cut (not all isolated fades).
 - [ ] All `interpolate` have `clamp` on both ends (the #1 drift bug).
 - [ ] Exits are sharper than entrances; nothing linear except continuous motion.
 - [ ] Cuts snapped to beats; whoosh-in + impact-on-cut wired.
 - [ ] Verified in 16:9 / 1:1 / 9:16 — wipe direction & blur amount read the same (`vmin`, not px); Persian RTL wipes from the right.
 - [ ] Colors via `colorSchema` (`mixHex`/`hexToRgba`), never hardcoded; deterministic (re-render twice → identical).
 Related: `../remotion-template-composition/SKILL.md`, `../remotion-aspect-ratios/SKILL.md`, `../remotion-design-styles/SKILL.md`, `../remotion-sound-effects/SKILL.md`, `../remotion-music-picker/SKILL.md`, `../remotion-character-design/SKILL.md`, `../remotion-svg-colors/SKILL.md`, `../persian-fonts/SKILL.md`, `../flatrender-template-seo/SKILL.md`.
@@ -0,0 +1,114 @@
 ---
 name: video-hooks
 description: How to design the scroll-stopping first 1-3 seconds of a FlatRender Remotion template — hook archetypes, pattern interrupts, on-screen text hooks, curiosity gaps, and platform-specific (Instagram/TikTok/YouTube) hook norms — and bake them into the template's opening beats. Use whenever building or reviewing a template's first frames, the cover/first frame, the caption hook layer, or retention pacing of the open.
 ---
 # The hook (first 1-3 seconds — where templates are won or lost)
 On a 9:16 feed the viewer decides **stay or swipe in 2-3 seconds** (TikTok's "3-second rule"; IG rewards 3-sec view rate). YouTube Shorts has **no runway** — open on the most compelling moment. So a FlatRender template doesn't get a polite logo intro: the **first frame is the cover/thumbnail and the hook**, and the first ~45-90 frames (@30fps) must arrest the eye. Everything here is a *pure function of `useCurrentFrame()`* — no `Math.random`/`Date.now`/`useFrame`; use `rand(seed)` from `lib/anim.ts`. Read `../remotion-aspect-ratios/SKILL.md` before positioning a single hook element.
 ## The frame budget for the open (30fps; use `sec(s)=Math.round(s*fps)`)
 | Beat | Frames | Job |
 |---|--:|---|
 | **f0 — cover** | 1 | Must already read as a finished, intriguing thumbnail. No black/empty frame 0. |
 | **Pattern interrupt** | 0-12 | One bold motion/sound jolt that breaks the scroll rhythm. |
 | **Hook text lands** | 6-30 | The promise/question/claim, big, high-contrast, lower-middle third. |
 | **Curiosity hold** | 30-75 | Pose an open loop the rest of the video closes. Don't resolve yet. |
 | **Hero handoff** | 60-90 | Flow into logo/headline (`../remotion-template-composition/SKILL.md`). |
 Front-load the payoff — **no preamble, no slow brand sting first**. Brand comes *after* the hook earns the watch.
 ## Hook archetypes (Persian-first copy; pick ONE per template)
 | Archetype | Persian opener pattern | Best for | Motion signature |
 |---|---|---|---|
 | **Curiosity gap** | «اینو تا آخر ببین…» / «هیچ‌کس اینو بهت نگفته» | tips, reveals, teasers | text snaps in, then a held pause (open loop) |
 | **Bold claim / contrarian** | «این روش رو فراموش کن» / «۹۰٪ اشتباه انجامش می‌دن» | how-to, product | hard cut + overshoot back-bezier |
 | **Question** | «دنبال … می‌گردی؟» | services, lead-gen | rise + tilt, then steady |
 | **Negativity / warning** | «این اشتباه رو نکن» | finance, health, safety | red accent flash + shake |
 | **Number / list** | «۳ دلیل که…» / «۵ نکته…» | listicles, carousels | counter ticks up, items pre-stack off-screen |
 | **Result-first** | show the after/price-drop/win immediately | promo, sale, before-after | hero appears f0, *then* explains |
 | **Direct address** | «تو که … هستی، اینو لازم داری» | niche/targeted | type fills 70-90% of frame |
 Use Persian numerals (`۰-۹`) — never Latin digits — in hook copy and counters; `fa` is source of truth, `en` mirrors 1:1.
 ## Pattern interrupts (the scroll-breaking jolt in f0-12)
 The feed has a rhythm; a hook *breaks* it. Stack 1-2 of these, never all:
 - **Motion jolt** — whip-in with overshoot: `Easing.bezier(0.34,1.56,0.64,1)`, or a low-damping `spring({mass:0.6,damping:9,stiffness:200})`. Add motion blur on the fast frames (its absence is an amateur tell).
 - **Hard cut + flash** — a 1-2 frame white/accent wash: `opacity = frame < 2 ? 1 : 0` over a `hexToRgba(accentColor, …)` fill. Pair with a thump SFX (`../remotion-sound-effects/SKILL.md`).
 - **Scale punch** — start at `scale` 1.6→1.0 (clamp) so the subject "slams" toward camera.
 - **Color shock** — open on a dopamine accent (electric blue/coral/acid) on a neutral base; pull it from `accentColor` so the studio recolors it.
 - **Silence-then-hit** — a held silent f0-8, then riser+downbeat on the hook (`../remotion-music-picker/SKILL.md` BPM map). The pause *is* the interrupt.
 ```tsx
 // Pattern-interrupt whip-in for the hook line (deterministic, clamped)
 const f = useCurrentFrame();
 const { fps } = useVideoConfig();
 const intro = spring({ frame: f, fps, config: { mass: 0.6, damping: 9, stiffness: 200 } });
 const y = interpolate(intro, [0, 1], [L.vmin(60), 0]);           // rises into place
 const flash = interpolate(f, [0, 2, 5], [1, 0.5, 0], { extrapolateRight: "clamp" });
 ```
 ## On-screen text hooks (the highest-ROI layer)
 The hook text is a **first-class editable field**, not decoration — it is the captions/cover layer the whole brief calls the biggest cross-platform win.
 - **Placement:** lower-middle third, inside the *tightest* safe zone (Story/TikTok) so it's safe everywhere. For 1080×1920 keep hook Y ≈ `height*0.18-0.55`; clear top ~108 and bottom ~320 (UI chrome).
 - **Legibility:** high-contrast white or acid-yellow fill + **black outline** (`WebkitTextStroke` or layered `textShadow`), never thin grey on busy bg. Add a scrim if over media.
 - **Oversized & clipped:** the hook word can fill 60-90% of frame (`fitText` from `@remotion/layout-utils`); clip with `overflow:hidden`. Strongest on 9:16.
 - **Kinetic / word-by-word:** beats full sentences on TikTok. Split to spans, `delay = i*stagger`, drive each with `spring({frame: f - delay, fps})`. Stagger looser on tall, tighter on wide via `pick`.
 - **Variable weight pop:** Vazirmatn ships a variable build — animate `fontVariationSettings: "'wght' " + interpolate(f,[0,12],[300,900])` for a Persian hero hook.
 ```tsx
 // Word-by-word Persian hook, RTL, outlined, beat-staggered
 const words = hookText.split(" ");
 const stagger = L.pick(2, 3, 4); // wide reads faster → tighter
 return (
  <div style={{ direction: "rtl", fontFamily: FONT, display: "flex",
                gap: L.vmin(8), justifyContent: "center", flexWrap: "wrap",
                maxWidth: L.width * 0.86 }}>
    {words.map((w, i) => {
      const s = spring({ frame: f - i * stagger, fps, config: { damping: 12 } });
      return (
        <span key={i} style={{
          fontSize: L.pick(L.vmin(96), L.vmin(84), L.vmin(72)), fontWeight: 900,
          color: textColor, WebkitTextStroke: `${L.vmin(6)}px ${BRAND.ink}`,
          paintOrder: "stroke", transform: `translateY(${(1 - s) * L.vmin(40)}px)`,
          opacity: s,
        }}>{w}</span>
      );
    })}
  </div>
 );
 ```
 ## Curiosity & retention pacing across the open
 - **Open a loop, close it later** — the hook *promises*, the hero *pays off*. Never resolve the question in the first 2s or there's no reason to stay.
 - **One idea per beat** — staging: dim/blur everything but the hook; let it own the eye before the next element competes.
 - **Hold for the read** — a hook line needs ~0.6-0.8s minimum on screen before motion competes. Robotic = linear; floaty = held too long. Cut frames before adding.
 - **Tiny life in the hold** — a `sin(f/fps)` breathe/shimmer so the held hook isn't a frozen frame.
 - **Grain + texture** from f0 — even the cover frame should have animated grain (offset `background-position` per frame); flat-saturated = reads as AI/template.
 ## Platform hook norms → template implication
 | Platform | Hook window | Norm | Template move |
 |---|---|---|---|
 | **TikTok** | 3s | curiosity-gap / bold-claim; word-by-word captions | calm neutral grain + warm-earth variant; word-by-word hook as editable layer |
 | **IG Reels** | 2-3s | cleaner, less-cluttered than TikTok | refined kinetic type, glass lower-third, mesh-gradient bg, one clean interrupt |
 | **YT Shorts** | f0 | no runway — open on the peak | result-first / hero-at-f0; cinematic graded look |
 | **YT long-form intro** | 5-15s | cold-open hook, brand sting <3s | state payoff first, brand second |
 | **IG Story** | full-bleed | heavy UI chrome | keep hook clear of top ~250 / bottom ~250 |
 | **All three** | 1-2s | first frame = hook = cover; authenticity > gloss | hook prop in every aspect, re-flowed not letterboxed |
 ## Tie the hook into template structure
 - Make the hook copy a Zod prop (e.g. `hookText: z.string()`) + a seeded `Text` element whose `key` matches — same binding model as `../remotion-template-composition/SKILL.md`. Ship strong Persian default copy so it reads finished pre-edit.
 - Hook color = `accentColor`/`textColor` from `colorSchema`; pass user hex through a grade so a garish value doesn't break the open (`../remotion-svg-colors/SKILL.md`).
 - The hook is a `<Sequence from={0} durationInFrames={sec(2.5)}>`; the hero sequence overlaps its tail so the handoff is a flow, not a cut.
 - 3D hooks: keep the interrupt object filling the frame per aspect (tune `fov`/`position.z`), drive entrance from `useCurrentFrame()` with high `mass` for weight; let `StudioEffects` (bloom/DOF/vignette) finish it.
 ## Hook checklist (gate the open)
 - [ ] Frame 0 reads as a finished, intriguing cover — no black/empty/half-loaded frame.
 - [ ] A single clear pattern interrupt in f0-12 (motion / flash / scale / color / silence-then-hit) with SFX.
 - [ ] ONE hook archetype; Persian-first copy with Persian numerals; `en` mirror present.
 - [ ] Hook text is an editable prop, high-contrast + outlined, in the tightest safe zone, no clipping with long Persian strings.
 - [ ] An open loop is posed and NOT resolved in the first 2s; payoff lands at the hero.
 - [ ] Eased/overshoot motion (no linear), held for the read, with a tiny live shimmer; animated grain from f0.
 - [ ] Verified the open in all three aspects (`pick`-tuned), recolors cleanly, re-renders identical (deterministic).
 Related: `../remotion-template-composition/SKILL.md`, `../remotion-aspect-ratios/SKILL.md`, `../remotion-design-styles/SKILL.md`, `../remotion-sound-effects/SKILL.md`, `../remotion-music-picker/SKILL.md`, `../remotion-svg-colors/SKILL.md`, `../persian-fonts/SKILL.md`, `../remotion-template-catalog/SKILL.md`, `../flatrender-template-seo/SKILL.md`.
@@ -0,0 +1,121 @@
 name: CI/CD
 # Pushes to Gitea trigger this. GitHub (origin) stays a backup and does not deploy.
 on:
  push:
    branches: [master]
  pull_request:
    branches: [master]
 concurrency:
  group: flatrender-cicd-${{ github.ref }}
  cancel-in-progress: true
 jobs:
  # ── CI: fast frontend type-check before the (long) deploy build ───────────────
  web-check:
    name: "CI · Web (tsc)"
    runs-on: ubuntu-latest
    container:
      image: mirror.soroushasadi.com/node:20-alpine
      options: --add-host=gitea:host-gateway
    steps:
      - name: Checkout (tarball)
        env:
          TOKEN: ${{ github.token }}
          SHA: ${{ github.sha }}
        run: |
          wget -q --header "Authorization: Bearer ${TOKEN}" \
            "${{ github.server_url }}/api/v1/repos/${{ github.repository }}/archive/${SHA}.tar.gz" \
            -O /tmp/repo.tar.gz
          tar -xzf /tmp/repo.tar.gz --strip-components=1
      - name: Install deps
        run: |
          npm ci --no-audit --no-fund \
            --registry https://mirror.soroushasadi.com/repository/npm-group/ \
            --fetch-retries=5 --fetch-retry-maxtimeout=120000
      - name: TypeScript check
        run: npx tsc --noEmit
  # ── Deploy: build + bring up the whole compose stack on the server ────────────
  deploy:
    name: "Deploy · full stack"
    runs-on: self-hosted
    needs: [web-check]
    if: github.event_name == 'push' && github.ref == 'refs/heads/master'
    timeout-minutes: 50
    env:
      # act runner host mode ships a minimal PATH — extend so docker/snap resolve.
      PATH: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/snap/bin
      # Lock the compose project name so volumes keep a STABLE prefix across deploys
      # regardless of the runner's checkout directory (prevents orphaned-volume data loss).
      COMPOSE_PROJECT_NAME: flatrender
      COMPOSE_FILE: docker-compose.v2.yml
      DOCKER_BUILDKIT: "1"
      COMPOSE_DOCKER_CLI_BUILD: "1"
    steps:
      - name: Checkout
        env:
          TOKEN: ${{ github.token }}
          REF: ${{ github.ref }}
        run: |
          git init
          git remote add origin "${{ github.server_url }}/${{ github.repository }}.git"
          git config http.extraheader "Authorization: Bearer ${TOKEN}"
          git fetch --depth=1 origin "${REF}"
          git checkout -f FETCH_HEAD
          # Remove stale Docker-created bind-mount dirs from a previous run (e.g. an
          # empty scripts/init-db.sh dir) so they don't shadow real files. -e keeps .env.
          git clean -ffd -e .env || true
      - name: Write .env (from ENV_FILE secret)
        run: printf '%s' "$ENV_FILE" > .env
        env:
          ENV_FILE: ${{ secrets.ENV_FILE }}
      - name: Backup database (if running)
        run: |
          if docker ps -a --format '{{.Names}}' | grep -q '^fr2-postgres$'; then
            mkdir -p /opt/flatrender-backups
            set -a; . ./.env 2>/dev/null || true; set +a
            STAMP=$(date +%Y%m%d-%H%M%S)
            echo "Dumping DB → /opt/flatrender-backups/flatrender-$STAMP.sql"
            docker exec fr2-postgres pg_dump -U "${POSTGRES_USER:-postgres}" flatrender \
              > "/opt/flatrender-backups/flatrender-$STAMP.sql" || echo "backup failed (non-fatal)"
            # keep only the 14 most recent dumps
            ls -1t /opt/flatrender-backups/flatrender-*.sql 2>/dev/null | tail -n +15 | xargs -r rm -f
          else
            echo "fr2-postgres not running yet — first deploy, no backup needed."
          fi
      - name: Build images
        run: docker compose build --parallel
      - name: Start stack
        run: docker compose up -d --remove-orphans
      - name: Wait for gateway healthy
        run: |
          for i in $(seq 1 30); do
            S=$(docker inspect --format='{{.State.Health.Status}}' fr2-gateway 2>/dev/null || echo missing)
            echo "  [$i/30] gateway: $S"
            [ "$S" = "healthy" ] && echo "OK gateway healthy" && break
            [ "$i" = "30" ] && echo "TIMEOUT gateway" && docker compose logs --tail=60 gateway content-svc identity-svc && exit 1
            sleep 6
          done
      - name: Wait for frontend healthy
        run: |
          for i in $(seq 1 24); do
            S=$(docker inspect --format='{{.State.Health.Status}}' fr2-frontend 2>/dev/null || echo missing)
            echo "  [$i/24] frontend: $S"
            [ "$S" = "healthy" ] && echo "OK frontend healthy" && break
            [ "$i" = "24" ] && echo "TIMEOUT frontend" && docker compose logs --tail=60 frontend && exit 1
            sleep 5
          done
      - name: Prune dangling images
        if: success()
        run: docker image prune -f
@@ -1,7 +1,8 @@
 # See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
-# dependencies
+# dependencies (root + any nested, e.g. services/remotion/node_modules)
 /node_modules
 node_modules/
 /.pnp
 .pnp.js
 .yarn/install-state.gz
@@ -55,3 +56,12 @@ node-agent.exe
 # node-agent local build + secrets
 services/node-agent/dist/
 agent.env
 # remotion render outputs (regenerated; thumbnails/previews live in public/template-media)
 services/remotion/out/
 # local scratch / agent work
 /-w
 /.agent-work/
 dist/
 services/remotion/player-dist/
@@ -1,15 +1,18 @@
 # ── Stage 1: install dependencies ────────────────────────────────────────────
-FROM node:20-alpine AS deps
+FROM mirror.soroushasadi.com/node:20-slim AS deps
-RUN apk add --no-cache libc6-compat
+# Debian (glibc) base on purpose: Alpine (musl) needs `libc6-compat` for next-swc,
 # which is only on the geo-blocked Alpine CDN (unreachable from the CI server).
 # Debian ships glibc, so next-swc's gnu binary loads natively — no apk, no CDN.
 WORKDIR /app
 COPY package.json package-lock.json* ./
-# The Nexus npm proxy intermittently returns 500s / corrupted tarballs while it
+# npm installs through the self-hosted Nexus mirror (override with --build-arg
-# back-fills its cache from upstream. Retry the whole install a few times — each
+# NPM_REGISTRY=... for a different mirror). The proxy intermittently returns 500s
-# pass re-requests only what's still missing, so successive runs converge once
+# / corrupted tarballs while it back-fills from upstream, so retry the whole
-# Nexus has cached every package. Bump npm's own retry budget too.
+# install a few times — each pass re-requests only what's still missing.
 ARG NPM_REGISTRY=https://mirror.soroushasadi.com/repository/npm-group/
 RUN for i in 1 2 3 4 5; do \
-      npm ci --registry http://171.22.25.73:8081/repository/npm-group/ \
+      npm ci --registry "${NPM_REGISTRY}" \
        --fetch-retries=5 --fetch-retry-factor=2 \
        --fetch-retry-mintimeout=20000 --fetch-retry-maxtimeout=120000 && exit 0; \
      echo "npm ci attempt $i failed; retrying in 10s..."; sleep 10; \
@@ -17,7 +20,7 @@ RUN for i in 1 2 3 4 5; do \
    echo "npm ci failed after 5 attempts" && exit 1
 # ── Stage 2: build ───────────────────────────────────────────────────────────
-FROM node:20-alpine AS builder
+FROM mirror.soroushasadi.com/node:20-slim AS builder
 WORKDIR /app
 COPY --from=deps /app/node_modules ./node_modules
@@ -50,15 +53,15 @@ ENV NODE_ENV=production
 RUN npm run build
 # ── Stage 3: production runner ────────────────────────────────────────────────
-FROM node:20-alpine AS runner
+FROM mirror.soroushasadi.com/node:20-slim AS runner
 WORKDIR /app
 ENV NODE_ENV=production
 ENV NEXT_TELEMETRY_DISABLED=1
-# Create a non-root user (security best practice)
+# Create a non-root user (security best practice). Debian uses groupadd/useradd.
-RUN addgroup --system --gid 1001 nodejs \
+RUN groupadd --system --gid 1001 nodejs \
- && adduser  --system --uid 1001 nextjs
+ && useradd  --system --uid 1001 --gid nodejs nextjs
 # Copy public assets
 COPY --from=builder /app/public ./public
@@ -0,0 +1,28 @@
 -- =====================================================================
 -- RENDER SCHEMA — scene snapshot jobs
 -- Async "render one frame per scene from After Effects" jobs. A node claims a
 -- queued snapshot, runs aerender for the scene's comp at a single frame, uploads
 -- the still to object storage, and posts back the image URL. render-svc then
 -- writes it onto content.scenes.snapshot_url (same DB, cross-schema) so the
 -- studio scene bar + admin show a real thumbnail.
 -- =====================================================================
 SET search_path TO render, public;
 CREATE TABLE IF NOT EXISTS snapshot_jobs (
    id          UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    project_id  UUID NOT NULL,               -- content project (template variant)
    scene_id    UUID NOT NULL,               -- content scene the snapshot belongs to
    scene_key   TEXT NOT NULL,
    comp_name   TEXT NOT NULL DEFAULT '',     -- AE comp to render (scene key / render comp)
    frame       INT  NOT NULL DEFAULT 0,      -- frame to capture
    status      TEXT NOT NULL DEFAULT 'queued', -- queued | running | done | error
    node_id     UUID,
    image_url   TEXT,
    error       TEXT,
    created_at  TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at  TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
 CREATE INDEX IF NOT EXISTS idx_snapshot_jobs_status  ON snapshot_jobs(status, created_at);
 CREATE INDEX IF NOT EXISTS idx_snapshot_jobs_project ON snapshot_jobs(project_id, created_at DESC);
@@ -0,0 +1,111 @@
 -- =====================================================================
 -- PAYMENT BROKER SCHEMA — generic multi-client ZarinPal gateway
 -- Served on pay.flatrender.ir (the single ZarinPal-verified callback domain).
 -- Other sites (meezi.ir, bargevasat.ir, FlatRender) register as client_apps
 -- and route payments through this broker.
 --
 -- NOTE: migrations auto-run only on FIRST volume creation. On an existing
 -- DB volume, apply this manually:
 --   docker exec -i fr2-postgres psql -U postgres -d flatrender < 31_payment_broker.sql
 -- =====================================================================
 CREATE SCHEMA IF NOT EXISTS payment;
 SET search_path TO payment, public;
 -- ---------------------------------------------------------------------
 -- client_apps — each site that pays through the broker
 -- ---------------------------------------------------------------------
 CREATE TABLE IF NOT EXISTS payment.client_apps (
    id                      UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tenant_id               UUID,                          -- optional link to identity.tenants
    name                    TEXT NOT NULL,                 -- "meezi.ir", "FlatRender"
    slug                    TEXT NOT NULL UNIQUE,          -- "meezi"
    api_key                 TEXT NOT NULL UNIQUE,          -- public id (pk_...)
    secret                  TEXT NOT NULL,                 -- shared HMAC secret (sk_...) — signs in+out
    -- ZarinPal: per-client override; NULL → broker default merchant/sandbox
    zarinpal_merchant_id    TEXT,
    zarinpal_sandbox        BOOLEAN,
    allowed_return_origins  TEXT[] NOT NULL DEFAULT '{}',  -- e.g. {'https://meezi.ir'}; empty = permissive
    webhook_url             TEXT,                          -- server-to-server result notification
    is_active               BOOLEAN NOT NULL DEFAULT TRUE,
    created_at              TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at              TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
 -- ---------------------------------------------------------------------
 -- transactions — one row per payment attempt
 -- ---------------------------------------------------------------------
 CREATE TABLE IF NOT EXISTS payment.transactions (
    id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    client_app_id       UUID NOT NULL REFERENCES payment.client_apps(id) ON DELETE RESTRICT,
    status              TEXT NOT NULL DEFAULT 'Created',   -- Created|Pending|Paid|Failed|Cancelled|Expired
    gateway             TEXT NOT NULL DEFAULT 'ZarinPal',
    amount_rial         BIGINT NOT NULL,                   -- canonical Rial
    currency            TEXT NOT NULL DEFAULT 'IRR',
    description         TEXT,
    client_ref          TEXT,                              -- the client's own order id
    return_url          TEXT NOT NULL,                     -- where the user is sent back
    metadata            JSONB,                             -- echoed back to the client
    payer_mobile        TEXT,
    payer_email         TEXT,
    authority           TEXT,                              -- ZarinPal authority token
    ref_id              TEXT,                              -- ZarinPal ref_id (receipt)
    card_pan            TEXT,
    fee_rial            BIGINT,
    gateway_response    JSONB,
    failure_reason      TEXT,
    paid_at             TIMESTAMPTZ,
    failed_at           TIMESTAMPTZ,
    expires_at          TIMESTAMPTZ,
    created_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at          TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
 CREATE INDEX IF NOT EXISTS idx_pay_txn_client   ON payment.transactions(client_app_id, created_at DESC);
 CREATE UNIQUE INDEX IF NOT EXISTS idx_pay_txn_authority ON payment.transactions(authority) WHERE authority IS NOT NULL;
 CREATE INDEX IF NOT EXISTS idx_pay_txn_clientref ON payment.transactions(client_app_id, client_ref) WHERE client_ref IS NOT NULL;
 CREATE INDEX IF NOT EXISTS idx_pay_txn_status   ON payment.transactions(status);
 -- ---------------------------------------------------------------------
 -- webhook_deliveries — outbound signed notifications with retry
 -- ---------------------------------------------------------------------
 CREATE TABLE IF NOT EXISTS payment.webhook_deliveries (
    id                  UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    transaction_id      UUID NOT NULL REFERENCES payment.transactions(id) ON DELETE CASCADE,
    url                 TEXT NOT NULL,
    payload             JSONB NOT NULL,
    signature           TEXT NOT NULL,
    attempts            INT NOT NULL DEFAULT 0,
    delivered           BOOLEAN NOT NULL DEFAULT FALSE,
    last_status         INT,
    last_error          TEXT,
    next_attempt_at     TIMESTAMPTZ,
    created_at          TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    updated_at          TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
 CREATE INDEX IF NOT EXISTS idx_pay_wh_pending ON payment.webhook_deliveries(delivered, next_attempt_at) WHERE delivered = FALSE;
 -- ---------------------------------------------------------------------
 -- updated_at triggers (helper tg_set_updated_at() created in 00_setup.sql)
 -- ---------------------------------------------------------------------
 DROP TRIGGER IF EXISTS tg_pay_client_apps_updated ON payment.client_apps;
 CREATE TRIGGER tg_pay_client_apps_updated BEFORE UPDATE ON payment.client_apps
    FOR EACH ROW EXECUTE FUNCTION public.tg_set_updated_at();
 DROP TRIGGER IF EXISTS tg_pay_transactions_updated ON payment.transactions;
 CREATE TRIGGER tg_pay_transactions_updated BEFORE UPDATE ON payment.transactions
    FOR EACH ROW EXECUTE FUNCTION public.tg_set_updated_at();
 DROP TRIGGER IF EXISTS tg_pay_webhook_updated ON payment.webhook_deliveries;
 CREATE TRIGGER tg_pay_webhook_updated BEFORE UPDATE ON payment.webhook_deliveries
    FOR EACH ROW EXECUTE FUNCTION public.tg_set_updated_at();
@@ -0,0 +1,16 @@
 -- 32_content_render_engine.sql
 -- Two render engines per template: After Effects (.aep, rendered by a node-agent)
 -- and Remotion (code-based React composition). render_engine selects which; for
 -- Remotion templates render_remotion_comp holds the composition id to render
 -- (the .aep / render_aep_comp columns stay null for those).
 --
 -- Apply manually on the live DB (migrations are not auto-run):
 --   docker exec -i <postgres> psql -U postgres -d flatrender < 32_content_render_engine.sql
 ALTER TABLE content.projects
    ADD COLUMN IF NOT EXISTS render_engine TEXT NOT NULL DEFAULT 'AfterEffects';
 ALTER TABLE content.projects
    ADD COLUMN IF NOT EXISTS render_remotion_comp TEXT;
 -- Existing templates are all After Effects; the default already covers them.
@@ -0,0 +1,35 @@
 -- =====================================================================
 -- PAYMENT BROKER — global settings (admin-editable ZarinPal config) + is_test
 -- Lets the merchant id / sandbox flag / amount unit be set from the admin
 -- panel instead of env + redeploy. A client_app may still override per-site.
 -- Also adds transactions.is_test so admin smoke-test payments never fire a
 -- client's production webhook.
 --
 -- Apply manually on an existing volume (runs after 31_payment_broker.sql):
 --   docker exec -i fr2-postgres psql -U flatrender -d flatrender < 33_payment_settings.sql
 -- =====================================================================
 CREATE SCHEMA IF NOT EXISTS payment;
 SET search_path TO payment, public;
 CREATE TABLE IF NOT EXISTS payment.settings (
    id                    SMALLINT PRIMARY KEY DEFAULT 1 CHECK (id = 1),  -- singleton row
    zarinpal_merchant_id  TEXT NOT NULL DEFAULT '',
    zarinpal_sandbox      BOOLEAN NOT NULL DEFAULT TRUE,
    zarinpal_amount_unit  TEXT NOT NULL DEFAULT 'rial',   -- 'rial' | 'toman'
    updated_at            TIMESTAMPTZ NOT NULL DEFAULT NOW()
 );
 -- NOTE: the singleton row is intentionally NOT pre-seeded. Until an admin saves
 -- settings, GetSettings returns no-row and the broker falls back to ENV
 -- (ZARINPAL_MERCHANT_ID / ZARINPAL_SANDBOX / ZARINPAL_AMOUNT_UNIT). Seeding a
 -- default row here would force sandbox=TRUE and silently override a production
 -- env (ZARINPAL_SANDBOX=false), routing real payments to the sandbox gateway.
 DROP TRIGGER IF EXISTS tg_pay_settings_updated ON payment.settings;
 CREATE TRIGGER tg_pay_settings_updated BEFORE UPDATE ON payment.settings
    FOR EACH ROW EXECUTE FUNCTION public.tg_set_updated_at();
 -- Mark admin smoke-test transactions so the webhook dispatcher never notifies a
 -- real client (which could otherwise credit coins/activate a plan from a test).
 ALTER TABLE payment.transactions ADD COLUMN IF NOT EXISTS is_test BOOLEAN NOT NULL DEFAULT FALSE;
@@ -0,0 +1,92 @@
 # ─────────────────────────────────────────────────────────────────────────────
 # FlatRender — PRODUCTION ENV_FILE template (server: 171.22.25.73, behind mirror-nginx)
 #
 # This is the content of the Gitea repo secret  ENV_FILE.
 #   https://git.soroushasadi.com/soroushdes/flatrender/settings/secrets
 # The deploy job writes this verbatim to `.env`, which docker compose reads.
 #
 # TLS + domain routing is handled by the existing central mirror-nginx (it owns
 # 80/443). FlatRender does NOT run Caddy here — it publishes host ports and
 # mirror-nginx reverse-proxies the domains to them (see deploy/README.md).
 #
 # Fill every <PLACEHOLDER>. Generate secrets with:  openssl rand -hex 32
 # Changing a NEXT_PUBLIC_* value requires a redeploy (baked into the frontend build).
 # ─────────────────────────────────────────────────────────────────────────────
 # ── Host-port binding ────────────────────────────────────────────────────────
 # Internal services (postgres, render) stay on loopback. The three nginx-facing
 # services publish on all interfaces so mirror-nginx can reach 171.22.25.73:PORT.
 HOST_BIND=127.0.0.1
 EDGE_BIND=0.0.0.0
 # nginx-facing host ports (must be free on 171.22.25.73 — :3000 is Gitea, avoid it).
 FRONTEND_PORT=1600
 GATEWAY_PORT=1605
 PAY_PORT=1607
 MINIO_PORT=1610
 MINIO_CONSOLE_PORT=1611
 # ── Browser-facing URLs (served by mirror-nginx over HTTPS; baked into frontend) ─
 NEXT_PUBLIC_SITE_URL=https://flatrender.ir
 NEXT_PUBLIC_API_URL=https://api.flatrender.ir/v1
 NEXT_PUBLIC_MINIO_URL=https://storage.flatrender.ir
 NEXT_PUBLIC_TENANT_SLUG=flatrender
 CORS_ORIGIN=https://flatrender.ir
 # ── Core secrets ─────────────────────────────────────────────────────────────
 JWT_SECRET=<openssl rand -hex 32>
 SERVICE_TOKEN=<openssl rand -hex 32>
 NODE_HMAC_SECRET=<openssl rand -hex 32>
 JWT_ACCESS_MINUTES=1440
 # ── Postgres ─────────────────────────────────────────────────────────────────
 POSTGRES_USER=flatrender
 POSTGRES_PASSWORD=<openssl rand -hex 24>
 # ── MinIO (object storage) ───────────────────────────────────────────────────
 MINIO_ACCESS_KEY=<openssl rand -hex 12>
 MINIO_SECRET_KEY=<openssl rand -hex 24>
 MINIO_BUCKET=flatrender-exports
 MINIO_TEMPLATES_BUCKET=flatrender-templates
 MINIO_UPLOAD_BUCKET=user-uploads
 # render-svc signs presigned URLs for the public storage domain (HTTPS via nginx):
 MINIO_HOST_ENDPOINT=storage.flatrender.ir
 MINIO_HOST_USE_SSL=true
 # ── Render farm ──────────────────────────────────────────────────────────────
 # No AE node on the server → keep the dev worker OFF (it would mock-complete jobs).
 # Disable rendering in Admin → فارم رندر → موتور رندر so users see an "unavailable" notice.
 RENDER_DEV_WORKER=false
 RENDER_DEV_SNAPSHOTS=false
 # ── Payment broker (pay.flatrender.ir) ───────────────────────────────────────
 # Standalone ZarinPal gateway shared by FlatRender + meezi.ir + bargevasat.ir.
 # ZARINPAL_MERCHANT_ID below is the SHARED merchant (verified domain = pay.flatrender.ir).
 PAY_PUBLIC_URL=https://pay.flatrender.ir
 # Unit ZarinPal expects in `amount`: "rial" (official v4) or "toman".
 # ⚠️ Your identity service historically sends Toman — confirm with one sandbox
 # payment which unit YOUR merchant settles in, then set this to match.
 ZARINPAL_AMOUNT_UNIT=rial
 # FlatRender's OWN plan purchases through the broker. Create a "flatrender" client
 # app in Admin → پرداخت (allowed origin https://api.flatrender.ir), then paste its
 # key+secret here. Empty ⇒ identity calls ZarinPal directly (legacy).
 FLATPAY_FLATRENDER_API_KEY=
 FLATPAY_FLATRENDER_SECRET=
 FLATPAY_RETURN_BASE=https://api.flatrender.ir
 # ── Payments (fill the providers you use; leave others blank) ────────────────
 STRIPE_SECRET_KEY=
 STRIPE_WEBHOOK_SECRET=
 STRIPE_PUBLISHABLE_KEY=
 # Shared ZarinPal merchant — used by BOTH the identity service and the pay broker.
 ZARINPAL_MERCHANT_ID=
 ZARINPAL_CALLBACK_URL=https://api.flatrender.ir/v1/payments/callback/zarinpal
 ZARINPAL_SANDBOX=false
 SNAPPAY_CLIENT_ID=
 SNAPPAY_CLIENT_SECRET=
 SNAPPAY_BASE_URL=https://api.snappay.ir
 SNAPPAY_CALLBACK_URL=https://api.flatrender.ir/v1/payments/callback/snappay
 TARA_API_KEY=
 TARA_BASE_URL=https://api.tara.ir
 TARA_CALLBACK_URL=https://api.flatrender.ir/v1/payments/callback/tara
@@ -0,0 +1,149 @@
 # FlatRender Pay — ZarinPal Broker Integration Guide
 `pay.flatrender.ir` is a **standalone, multi-client ZarinPal gateway**. Any site
 (FlatRender, meezi.ir, bargevasat.ir, …) routes payments through it, because
 ZarinPal only accepts callbacks on the single verified domain `pay.flatrender.ir`.
 ```
 your site ──POST /v1/pay/request──►  pay.flatrender.ir  ──►  ZarinPal request.json
   ▲  (api key + HMAC)                      │                       │
   │                                        ▼                  authority
   └──◄ 302 return_url (signed) ◄── /callback/zarinpal ◄── user pays on ZarinPal
   └──◄ POST webhook_url (signed) ◄────────┘  (verify.json → ref_id)
 ```
 You get a **client app** from the FlatRender admin (Admin → پرداخت → اپلیکیشن‌ها):
 - `api_key`   — public id, sent as `X-Api-Key` (e.g. `pk_…`)
 - `secret`    — shown **once**; signs your requests AND verifies broker callbacks (`sk_…`)
 - `webhook_url` — optional server-to-server result endpoint
 - `allowed_return_origins` — the origins your `return_url` may use (empty = any)
 ---
 ## 1. Create a payment
 `POST https://pay.flatrender.ir/v1/pay/request`
 Headers:
 | Header | Value |
 |---|---|
 | `Content-Type` | `application/json` |
 | `X-Api-Key` | your `api_key` |
 | `X-Signature` | `hex( HMAC_SHA256(secret, <raw request body bytes>) )` |
 Body:
 ```json
 {
  "amount": 50000,
  "currency": "IRT",
  "description": "خرید اشتراک طلایی",
  "client_ref": "order-1234",
  "return_url": "https://meezi.ir/payment/return",
  "mobile": "09120000000",
  "email": "user@example.com",
  "metadata": { "user_id": "42", "plan": "gold" }
 }
 ```
 - `amount` — integer. `currency` is `"IRR"` (Rial, default) or `"IRT"` (Toman). The
  broker stores the canonical Rial value and converts for ZarinPal.
 - `client_ref` — your own order id (echoed back everywhere).
 - `return_url` — where the user's browser is sent after payment. Must match an
  `allowed_return_origins` entry if you configured any.
 - `metadata` — arbitrary JSON, echoed back in the redirect signature scope + webhook.
 Response `200`:
 ```json
 {
  "id": "9b2c…",            // broker transaction id
  "status": "Pending",
  "payment_url": "https://www.zarinpal.com/pg/StartPay/A000…",
  "authority": "A000…",
  "amount_rial": 500000
 }
 ```
 **Redirect the user's browser to `payment_url`.**
 ---
 ## 2. The user comes back (browser redirect)
 After ZarinPal, the broker verifies the payment and `302`-redirects the browser to
 your `return_url` with a **signed** result appended:
 ```
 https://meezi.ir/payment/return?status=Paid&id=9b2c…&ref_id=123456789&sign=<hex>
 ```
 - `status` — `Paid` | `Failed` | `Cancelled`
 - `ref_id` — ZarinPal receipt (only when paid)
 - `sign`   — `hex( HMAC_SHA256(secret, "{id}.{status}.{ref_id}.{amount_rial}") )`
 ⚠️ The redirect is **not** proof of payment on its own (a user can craft a URL).
 Treat it as a UX hint, then **confirm with the webhook (§3) or the inquiry API (§4)**.
 To verify the redirect signature you need `amount_rial`; fetch it via the inquiry
 API, or just rely on the webhook / inquiry as the source of truth.
 ---
 ## 3. Webhook (recommended — the source of truth)
 If `webhook_url` is set, the broker POSTs a **signed** JSON body to it when a payment
 finishes (with retry + exponential backoff up to ~1h):
 Headers: `X-FlatPay-Signature: <hex>`, `X-FlatPay-Event: payment`
 ```json
 {
  "event": "payment.paid",
  "id": "9b2c…",
  "status": "Paid",
  "amount_rial": 500000,
  "currency": "IRR",
  "client_ref": "order-1234",
  "ref_id": "123456789",
  "authority": "A000…",
  "card_pan": "6037********1234",
  "metadata": { "user_id": "42", "plan": "gold" },
  "paid_at": "2026-06-15T14:00:00Z",
  "ts": 1750000000
 }
 ```
 Verify: `HMAC_SHA256(secret, <raw body bytes>) == X-FlatPay-Signature`. Respond `2xx`
 to acknowledge (anything else is retried). Make handling **idempotent** (keyed on
 `id` or `client_ref`) — duplicate deliveries are possible.
 ---
 ## 4. Inquiry (authoritative pull)
 `POST https://pay.flatrender.ir/v1/pay/inquiry` (same `X-Api-Key` + `X-Signature` as §1)
 ```json
 { "id": "9b2c…" }
 ```
 Returns the full transaction (status, `ref_id`, `amount_rial`, …). Use this from your
 `return_url` handler to confirm before granting the user anything.
 ---
 ## Reference signature recipe
 ```
 signature = hex( HMAC_SHA256(client_secret, message_bytes) )
 ```
 - **request / inquiry**: `message_bytes` = the exact raw JSON body you send.
 - **return redirect**: `message_bytes` = UTF-8 of `"{id}.{status}.{ref_id}.{amount_rial}"`.
 - **webhook**: `message_bytes` = the exact raw JSON body received.
 See [`sdk/flatpay.js`](./sdk/flatpay.js) for a drop-in Node client + Express webhook
 verifier.
@@ -0,0 +1,107 @@
 # Deploying FlatRender (Gitea CI/CD → 171.22.25.73, behind mirror-nginx)
 Push to **Gitea** triggers `.gitea/workflows/ci-cd.yml`: a frontend `tsc` check, then a
 self-hosted `deploy` job that builds the whole compose stack and brings it up. The
 existing central **mirror-nginx** (owns 80/443, manual TLS certs) reverse-proxies the
 three public domains to FlatRender's host ports — FlatRender does **not** run Caddy here.
 GitHub (`origin`) stays a backup and never deploys.
 Stack: gateway · identity · content · studio (.NET/Go) · file · render · notification
 (Go) · Next.js frontend · Postgres · MinIO. All package installs route through
 `mirror.soroushasadi.com` (Nexus).
 ```
                      mirror-nginx (:443, /etc/ssl/flatrender)
  flatrender.ir         → 171.22.25.73:1600  (fr2-frontend)
  api.flatrender.ir     → 171.22.25.73:1605  (fr2-gateway)
  pay.flatrender.ir     → 171.22.25.73:1607  (fr2-payment, ZarinPal broker)
  storage.flatrender.ir → 171.22.25.73:1610  (fr2-minio)
 ```
 The **payment broker** (`fr2-payment`, `pay.flatrender.ir`) is a standalone generic
 ZarinPal gateway shared by FlatRender + meezi.ir + bargevasat.ir — ZarinPal only
 accepts callbacks on that one verified domain. It does NOT sit behind the API
 gateway (clients authenticate with an API key + HMAC). See
 [`PAYMENTS.md`](./PAYMENTS.md) for the integration contract. The `payment` schema
 is migrations `31_payment_broker.sql` (tables) + `33_payment_settings.sql`
 (admin-editable ZarinPal config + `transactions.is_test`) — apply BOTH, in order,
 on an existing DB volume (migrations only auto-run on first volume creation):
 ```
 docker exec -i fr2-postgres psql -U flatrender -d flatrender < backend/db/migrations/31_payment_broker.sql
 docker exec -i fr2-postgres psql -U flatrender -d flatrender < backend/db/migrations/33_payment_settings.sql
 ```
 The broker image expects `is_test` (migration 33) — deploy it together with both migrations.
 ## One-time setup (do these BEFORE the first `git push gitea master`)
 1. **DNS** — this box sits BEHIND NAT: its interface IP is `171.22.25.73` (private),
   public NAT IPs are `31.171.101.127/.211`, and inbound 443 normally arrives via the
   edge/CDN `185.239.1.100` (same entry your other sites use, e.g. `meezi.ir`). So a new
   domain must enter the SAME way the others do — either:
   - register `flatrender.ir` + `api` + `pay` + `storage` + `www` in that edge/CDN (origin =
     this server) and point DNS there, **or**
   - bypass the CDN and point DNS straight at the server's public IP (like the hokm `api`
     subdomain does — "must bypass").
   Pointing DNS at a random/registrar IP shows that host's default page (e.g. a "not
   licensed" page), NOT FlatRender.
 2. **TLS cert** — ⚠️ mirror-nginx mounts cert dirs INDIVIDUALLY, so a fresh
   `/etc/ssl/flatrender/` on the host is invisible inside the container. **Nest the cert
   under an already-mounted dir** (the conf references this path):
   ```bash
   mkdir -p /etc/ssl/soroushasadi/flatrender
   cp <yourcert>/fullchain.pem  /etc/ssl/soroushasadi/flatrender/
   cp <yourcert>/privateKey.pem /etc/ssl/soroushasadi/flatrender/
   ```
   Cert must cover `flatrender.ir` + `api.` + `pay.` + `storage.` (wildcard `*.flatrender.ir` + apex, or SAN).
 3. **mirror-nginx** — add the server blocks from [`mirror-nginx-flatrender.conf`](./mirror-nginx-flatrender.conf)
   to the proxy's `http{}` (the host file is `/root/mirror-server/nginx/nginx.conf`), then:
   `docker exec mirror-nginx nginx -t && docker exec mirror-nginx nginx -s reload`.
   ⚠️ If you edited the conf with `sed -i` (which swaps the file inode), the running
   container keeps the old inode → `docker restart mirror-nginx` instead (~3s blip).
   Verify locally (bypasses DNS): `curl -sk --resolve flatrender.ir:443:127.0.0.1 https://flatrender.ir/ | head -c 60`
   must show `<html lang="fa" dir="rtl">`. (Do this after the first deploy is up, or it 502s.)
 4. **ENV_FILE secret** — at `…/soroushdes/flatrender/settings/secrets`, create `ENV_FILE`
   from [`ENV_FILE.production.example`](./ENV_FILE.production.example) (already filled for
   flatrender.ir; generate each secret with `openssl rand -hex 32`).
 5. **Gitea Actions** enabled for this repo; act_runner has the `self-hosted:host` label
   (the standard box already has this). daemon.json already mirrors Docker Hub via Nexus.
 ## Go live
 ```bash
 git push gitea master      # triggers CI + deploy
 ```
 Watch `https://git.soroushasadi.com/soroushdes/flatrender/actions`. First run ~15–25 min
 (cold Nexus cache + all images build). When the deploy is green, add/reload the nginx
 blocks (step 3) and visit `https://flatrender.ir`.
 ## Host ports (must be free on 171.22.25.73)
 `1600` frontend · `1605` gateway · `1607` payment broker · `1610` MinIO · `1611` MinIO
 console. Postgres (5432) and render (5010) bind to `127.0.0.1` only. Avoid `:3000` (Gitea),
 `:8081-8083` (Nexus), `:1500/1505/1520` (bargevasat), `:3010/3101-3103/5080/5081` (meezi),
 `:3020`, `:2569`. Change them via `FRONTEND_PORT`/`GATEWAY_PORT`/`PAY_PORT`/`MINIO_PORT` in
 the secret if any collide.
 ## First-run notes
 - **Migrations** auto-run once via `deploy/postgres-initdb/00-init.sh` (mounted as the
  whole `/docker-entrypoint-initdb.d` directory — a single-file bind mount left a stale
  empty dir → "Is a directory") when the Postgres volume is first created. Later schema
  changes are applied manually with `psql` (the volume persists). ⚠️ If a deploy ever
  ran with a wrong/empty secret, the volume bakes the wrong password + may skip init →
  `docker rm -f fr2-postgres && docker volume rm flatrender_pgdata` (only while there's
  no real data) then re-run, so it re-inits with the current password + migrations.
 - **Rendering** — no After Effects node on the server, so `RENDER_DEV_WORKER=false`.
  Disable rendering in **Admin → فارم رندر → موتور رندر** so users see an "unavailable"
  notice instead of jobs that never finish. Point real render nodes at the server later.
 - **MinIO public URLs** — verify an uploaded image + a render download resolve over
  `https://storage.flatrender.ir`. If not, recheck `MINIO_HOST_ENDPOINT` /
  `MINIO_HOST_USE_SSL` / `NEXT_PUBLIC_MINIO_URL` in the secret and redeploy.
 ## Redeploy / rotate secrets
 Edit `ENV_FILE` in Gitea (or push any commit) → the deploy re-runs. It backs up the DB to
 `/opt/flatrender-backups/` before each deploy and never runs `docker compose down -v`.
 Changing a `NEXT_PUBLIC_*` value only takes effect after the redeploy (baked at build).
@@ -0,0 +1,109 @@
 # ==========================================================================
 # FlatRender — flatrender.ir  (add inside the http{} block of mirror-nginx)
 #
 # Routes the three public domains to the FlatRender host ports on 171.22.25.73
 # (FRONTEND_PORT / GATEWAY_PORT / MINIO_PORT from the deploy ENV_FILE).
 #
 # The mirror-nginx config file lives on the HOST at /root/mirror-server/nginx/nginx.conf
 # (bind-mounted read-only into the container). Add these blocks there.
 #
 # ⚠️ CERT-MOUNT TRAP: mirror-nginx mounts cert dirs INDIVIDUALLY
 # (/etc/ssl/{soroushasadi,meezi,...}). A new /etc/ssl/soroushasadi/flatrender/ on the host is
 # INVISIBLE inside the container → nginx -t "cannot load certificate". So NEST the
 # flatrender cert under an already-mounted dir:
 #     mkdir -p /etc/ssl/soroushasadi/flatrender
 #     cp <cert>/fullchain.pem <cert>/privateKey.pem /etc/ssl/soroushasadi/flatrender/
 # The cert must cover flatrender.ir + api. + storage. (wildcard *.flatrender.ir + apex,
 # or a SAN cert).
 #
 # ⚠️ After editing nginx.conf with `sed -i` (which replaces the file inode), the
 # running container keeps the OLD inode → you must RESTART, not just reload:
 #     docker restart mirror-nginx       # ~3s blip for all sites
 # A plain edit that keeps the inode + reload is fine:
 #     docker exec mirror-nginx nginx -t && docker exec mirror-nginx nginx -s reload
 #
 # Test routing locally (bypasses DNS):
 #     curl -sk --resolve flatrender.ir:443:127.0.0.1 https://flatrender.ir/ | head -c 60
 #     # must show: <!DOCTYPE html><html lang="fa" dir="rtl">
 # ==========================================================================
 server {
    listen 80;
    server_name flatrender.ir www.flatrender.ir api.flatrender.ir storage.flatrender.ir pay.flatrender.ir;
    return 301 https://$host$request_uri;
 }
 # ── Site (Next.js frontend → FRONTEND_PORT) ───────────────────────────────
 server {
    listen 443 ssl; http2 on;
    server_name flatrender.ir www.flatrender.ir;
    client_max_body_size 25m;
    ssl_certificate     /etc/ssl/soroushasadi/flatrender/fullchain.pem;
    ssl_certificate_key /etc/ssl/soroushasadi/flatrender/privateKey.pem;
    location / {
        proxy_pass http://171.22.25.73:1600;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection $connection_upgrade;
    }
 }
 # ── API gateway (→ GATEWAY_PORT) ──────────────────────────────────────────
 server {
    listen 443 ssl; http2 on;
    server_name api.flatrender.ir;
    client_max_body_size 512m;          # large uploads routed through the gateway
    ssl_certificate     /etc/ssl/soroushasadi/flatrender/fullchain.pem;
    ssl_certificate_key /etc/ssl/soroushasadi/flatrender/privateKey.pem;
    location / {
        proxy_pass http://171.22.25.73:1605;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_set_header Upgrade $http_upgrade;       # render-progress WebSocket
        proxy_set_header Connection $connection_upgrade;
        proxy_read_timeout 3600s;
    }
 }
 # ── MinIO storage (→ MINIO_PORT) ──────────────────────────────────────────
 server {
    listen 443 ssl; http2 on;
    server_name storage.flatrender.ir;
    client_max_body_size 512m;
    ssl_certificate     /etc/ssl/soroushasadi/flatrender/fullchain.pem;
    ssl_certificate_key /etc/ssl/soroushasadi/flatrender/privateKey.pem;
    location / {
        proxy_pass http://171.22.25.73:1610;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
 }
 # ── Payment broker (→ PAY_PORT) — pay.flatrender.ir ───────────────────────
 # The single ZarinPal-verified callback domain. ZarinPal redirects users to
 # pay.flatrender.ir/callback/zarinpal; the broker then bounces them to the
 # originating site's return_url. Must NOT be cached by any upstream CDN.
 server {
    listen 443 ssl; http2 on;
    server_name pay.flatrender.ir;
    client_max_body_size 5m;
    ssl_certificate     /etc/ssl/soroushasadi/flatrender/fullchain.pem;
    ssl_certificate_key /etc/ssl/soroushasadi/flatrender/privateKey.pem;
    location / {
        proxy_pass http://171.22.25.73:1607;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
 }
@@ -1,7 +1,8 @@
 #!/bin/bash
 # FlatRender V2 — run all schema migrations in order on first postgres init.
-# Mounted at: /docker-entrypoint-initdb.d/00-init.sh
+# This whole directory is mounted at /docker-entrypoint-initdb.d (a DIRECTORY mount
-# Migrations dir mounted at: /migrations  (read-only)
+# is robust; a single-file bind mount can leave a stale empty dir in a reused CI
 # workspace → "Is a directory"). Migrations dir mounted read-only at /migrations.
 set -e
 MIGRATIONS_DIR="/migrations"
@@ -0,0 +1,112 @@
 // FlatRender Pay — drop-in Node client for the ZarinPal broker (pay.flatrender.ir).
 // Zero dependencies: Node 18+ (global fetch) + built-in crypto. CommonJS.
 //
 //   const { FlatPay } = require("./flatpay");
 //   const pay = new FlatPay({ apiKey: process.env.FLATPAY_KEY, secret: process.env.FLATPAY_SECRET });
 //
 //   // 1. create + redirect
 //   const r = await pay.createPayment({ amount: 50000, currency: "IRT",
 //     description: "اشتراک", clientRef: order.id, returnUrl: "https://meezi.ir/pay/return",
 //     metadata: { userId: user.id } });
 //   res.redirect(r.payment_url);
 //
 //   // 2. on your return_url handler — confirm authoritatively
 //   const txn = await pay.inquire(req.query.id);
 //   if (txn.status === "Paid") { /* grant */ }
 //
 //   // 3. webhook (recommended) — Express:
 //   app.post("/flatpay/webhook", express.raw({ type: "*/*" }), (req, res) => {
 //     if (!pay.verifyWebhook(req.body, req.get("X-FlatPay-Signature"))) return res.sendStatus(401);
 //     const ev = JSON.parse(req.body.toString("utf8"));
 //     if (ev.status === "Paid") { /* idempotent grant keyed on ev.id / ev.client_ref */ }
 //     res.sendStatus(200);
 //   });
 const crypto = require("crypto");
 const DEFAULT_BASE = "https://pay.flatrender.ir";
 function hmac(secret, message) {
  return crypto.createHmac("sha256", secret).update(message).digest("hex");
 }
 function timingSafeEqualHex(a, b) {
  try {
    const ba = Buffer.from(a, "hex");
    const bb = Buffer.from(b, "hex");
    return ba.length === bb.length && crypto.timingSafeEqual(ba, bb);
  } catch {
    return false;
  }
 }
 class FlatPay {
  constructor({ apiKey, secret, baseUrl = DEFAULT_BASE } = {}) {
    if (!apiKey || !secret) throw new Error("FlatPay: apiKey and secret are required");
    this.apiKey = apiKey;
    this.secret = secret;
    this.baseUrl = baseUrl.replace(/\/+$/, "");
  }
  async _signedPost(path, payload) {
    const body = JSON.stringify(payload);
    const res = await fetch(this.baseUrl + path, {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-Api-Key": this.apiKey,
        "X-Signature": hmac(this.secret, body),
      },
      body,
    });
    const data = await res.json().catch(() => ({}));
    if (!res.ok) {
      const err = new Error(data.message || `FlatPay ${path} failed (${res.status})`);
      err.code = data.code;
      err.status = res.status;
      throw err;
    }
    return data;
  }
  /** Create a payment. Returns { id, status, payment_url, authority, amount_rial }. */
  createPayment({ amount, currency = "IRR", description, clientRef, returnUrl, mobile, email, metadata }) {
    if (!returnUrl) throw new Error("FlatPay: returnUrl is required");
    return this._signedPost("/v1/pay/request", {
      amount,
      currency,
      description,
      client_ref: clientRef,
      return_url: returnUrl,
      mobile,
      email,
      metadata,
    });
  }
  /** Authoritative server-side status check. Returns the full transaction. */
  inquire(id) {
    return this._signedPost("/v1/pay/inquiry", { id });
  }
  /**
   * Verify the signed return-redirect query.
   * Pass the query params { id, status, ref_id, sign } AND the amount_rial you got
   * from createPayment/inquire (the redirect itself doesn't carry the amount).
   */
  verifyRedirect({ id, status, ref_id = "", sign }, amountRial) {
    const message = `${id}.${status}.${ref_id}.${amountRial}`;
    return !!sign && timingSafeEqualHex(hmac(this.secret, message), sign);
  }
  /**
   * Verify a webhook. `rawBody` MUST be the exact bytes received (Buffer or string —
   * do not re-stringify a parsed object, signatures won't match).
   */
  verifyWebhook(rawBody, signatureHeader) {
    const msg = Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(String(rawBody), "utf8");
    return !!signatureHeader && timingSafeEqualHex(hmac(this.secret, msg), signatureHeader);
  }
 }
 module.exports = { FlatPay, hmac };
@@ -14,7 +14,9 @@ services:
  # ── Shared infrastructure ───────────────────────────────────────────────────
  postgres:
-    image: postgres:16-alpine
+    # Pull infra images through the Nexus mirror (Docker Hub blocks Iran IPs).
    # Override INFRA_REGISTRY= (empty) to use plain Docker Hub names elsewhere.
    image: ${INFRA_REGISTRY:-mirror.soroushasadi.com/}postgres:16-alpine
    container_name: fr2-postgres
    restart: unless-stopped
    environment:
@@ -25,9 +27,14 @@ services:
      - pgdata:/var/lib/postgresql/data
      # migrations are run once by init-db.sh when the data volume is first created
      - ./backend/db/migrations:/migrations:ro
-      - ./scripts/init-db.sh:/docker-entrypoint-initdb.d/00-init.sh:ro
+      # Directory mount (NOT a single file) — robust against stale CI-workspace dirs.
      - ./deploy/postgres-initdb:/docker-entrypoint-initdb.d:ro
    ports:
-      - "5432:5432"
+      # HOST_BIND=127.0.0.1 in prod keeps these off the public interface (only
      # Caddy's 80/443 face the internet). Unset → 0.0.0.0 for local/LAN dev.
      # Host port is configurable (PG_HOST_PORT) — 5432 is often taken by another
      # local project's postgres; the internal stack always uses postgres:5432.
      - "${HOST_BIND:-0.0.0.0}:${PG_HOST_PORT:-5532}:5432"
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER:-postgres} -d flatrender"]
      interval: 5s
@@ -36,7 +43,12 @@ services:
      start_period: 10s
  minio:
-    image: minio/minio:latest
+    # minio:latest is compiled for x86-64-v2 and crashes on baseline-CPU servers
    # ("Fatal glibc error: CPU does not support x86-64-v2"). Use a `-cpuv1` build
    # (same release, plain x86-64). Pulled from the Liara Docker mirror, which
    # back-fills these tags (the soroushasadi mirror only has cached v2 builds).
    # Dev overrides MINIO_REGISTRY= + MINIO_IMAGE_TAG=latest for plain Docker Hub.
    image: ${MINIO_REGISTRY:-docker-mirror.liara.ir/}minio/minio:${MINIO_IMAGE_TAG:-RELEASE.2025-06-13T11-33-47Z-cpuv1}
    container_name: fr2-minio
    restart: unless-stopped
    command: server /data --console-address ":9001"
@@ -46,14 +58,16 @@ services:
    volumes:
      - miniodata:/data
    ports:
-      - "9000:9000"
+      - "${EDGE_BIND:-0.0.0.0}:${MINIO_PORT:-9000}:9000"
-      - "9001:9001"
+      - "${EDGE_BIND:-0.0.0.0}:${MINIO_CONSOLE_PORT:-9001}:9001"
    healthcheck:
-      test: ["CMD-SHELL", "mc ready local || exit 1"]
+      # Liveness via curl (newer images) with an mc fallback (older images that
      # still bundle the client). Covers minio:latest drift either way.
      test: ["CMD-SHELL", "curl -sf http://localhost:9000/minio/health/live || mc ready local || exit 1"]
      interval: 10s
      timeout: 5s
-      retries: 5
+      retries: 8
-      start_period: 10s
+      start_period: 20s
  # ── Identity Service (.NET 10) ──────────────────────────────────────────────
  # Config keys: ConnectionStrings:DefaultConnection  Jwt:Secret
@@ -72,10 +86,21 @@ services:
      Jwt__Secret: "${JWT_SECRET}"
      Jwt__Issuer: "flatrender-identity"
      Jwt__Audience: "flatrender"
      Jwt__AccessTokenMinutes: "${JWT_ACCESS_MINUTES:-1440}"
      ServiceToken: "${SERVICE_TOKEN:-internal-service-secret}"
      # Payment callbacks land on this service (api.*); the result page is on the
      # frontend. Used to make /payment/result redirects absolute to the site.
      Frontend__BaseUrl: "${NEXT_PUBLIC_SITE_URL:-http://localhost:3000}"
      ZarinPal__MerchantId:   "${ZARINPAL_MERCHANT_ID:-}"
      ZarinPal__CallbackUrl:  "${ZARINPAL_CALLBACK_URL:-http://localhost:8080/v1/payments/callback/zarinpal}"
      ZarinPal__Sandbox:      "${ZARINPAL_SANDBOX:-true}"
      # FlatRender Pay broker — when ApiKey+Secret are set, plan purchases route
      # through pay.flatrender.ir (the single ZarinPal-verified domain) instead of a
      # direct ZarinPal call. ReturnBase = this identity service's public base.
      FlatPay__BaseUrl:       "${FLATPAY_BASE_URL:-https://pay.flatrender.ir}"
      FlatPay__ApiKey:        "${FLATPAY_FLATRENDER_API_KEY:-}"
      FlatPay__Secret:        "${FLATPAY_FLATRENDER_SECRET:-}"
      FlatPay__ReturnBase:    "${FLATPAY_RETURN_BASE:-https://api.flatrender.ir}"
      Stripe__SecretKey:      "${STRIPE_SECRET_KEY:-}"
      Stripe__WebhookSecret:  "${STRIPE_WEBHOOK_SECRET:-}"
      SnapPay__ClientId:      "${SNAPPAY_CLIENT_ID:-}"
@@ -181,7 +206,7 @@ services:
    container_name: fr2-render
    restart: unless-stopped
    ports:
-      - "5010:8080"   # exposed so a LOCAL (host) node-agent can reach /v1/internal/*
+      - "${HOST_BIND:-0.0.0.0}:5010:8080"   # exposed so a LOCAL (host) node-agent can reach /v1/internal/*
    environment:
      DATABASE_URL: "postgres://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD:-postgres}@postgres:5432/flatrender?search_path=render,public"
      JWT_SECRET: "${JWT_SECRET}"
@@ -190,8 +215,14 @@ services:
      MINIO_ENDPOINT: "${MINIO_HOST_ENDPOINT:-172.28.144.1:9000}"
      MINIO_ACCESS_KEY: "${MINIO_ACCESS_KEY:-minioadmin}"
      MINIO_SECRET_KEY: "${MINIO_SECRET_KEY:-minioadmin}"
-      MINIO_USE_SSL: "false"
+      # SSL on when MINIO_HOST_ENDPOINT is an HTTPS storage domain (prod via Caddy).
      MINIO_USE_SSL: "${MINIO_HOST_USE_SSL:-false}"
      MINIO_BUCKET: "${MINIO_BUCKET:-flatrender-exports}"
      # Scene snapshots upload to this public-read bucket; PUBLIC_URL is the
      # browser-reachable base for the stored snapshot_url (defaults to the host
      # MinIO endpoint above when unset).
      MINIO_UPLOAD_BUCKET: "${MINIO_UPLOAD_BUCKET:-user-uploads}"
      MINIO_PUBLIC_URL: "${NEXT_PUBLIC_MINIO_URL:-http://172.28.144.1:9000}"
      NOTIFICATION_URL: "http://notification-svc:8080"
      IDENTITY_URL: "http://identity-svc:8080"
      SERVICE_TOKEN: "${SERVICE_TOKEN:-internal-service-secret}"
@@ -199,6 +230,9 @@ services:
      # Dev: process Queued jobs in-process (progress + preview → Done) without a
      # Windows AE node. Set "false" in production where real render nodes claim jobs.
      RENDER_DEV_WORKER: "${RENDER_DEV_WORKER:-true}"
      # Dev: fulfil scene-snapshot jobs with a generated placeholder image (no AE).
      # Keep "false" in production — real nodes render the actual AE frame.
      RENDER_DEV_SNAPSHOTS: "${RENDER_DEV_SNAPSHOTS:-false}"
    depends_on:
      postgres:
        condition: service_healthy
@@ -233,6 +267,43 @@ services:
      retries: 5
      start_period: 10s
  # ── Payment Broker (Go) — pay.flatrender.ir ─────────────────────────────────
  # Standalone generic ZarinPal gateway. Other sites (meezi, bargevasat) and
  # FlatRender register as client_apps and route payments through it, because
  # ZarinPal only accepts callbacks on the single verified domain pay.flatrender.ir.
  # Exposed on its OWN host port (mirror-nginx → pay.flatrender.ir → here);
  # it does NOT sit behind the API gateway (clients auth with API key + HMAC).
  payment-svc:
    build:
      context: ./services/payment
    container_name: fr2-payment
    restart: unless-stopped
    ports:
      # Default to the production port 1607 so the bind works without an ENV_FILE
      # edit (8090 collided on the server). Override via PAY_PORT if 1607 is taken.
      - "${EDGE_BIND:-0.0.0.0}:${PAY_PORT:-1607}:8080"
    environment:
      DATABASE_URL: "postgres://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD:-postgres}@postgres:5432/flatrender?search_path=payment,public"
      JWT_SECRET: "${JWT_SECRET}"
      PORT: "8080"
      # Externally reachable base — ZarinPal callback + user redirect are built from it.
      PUBLIC_BASE_URL: "${PAY_PUBLIC_URL:-http://localhost:1607}"
      # Shared default ZarinPal merchant (a client_app may override per-site).
      ZARINPAL_MERCHANT_ID: "${ZARINPAL_MERCHANT_ID:-}"
      ZARINPAL_SANDBOX: "${ZARINPAL_SANDBOX:-true}"
      # Unit ZarinPal expects in the amount field: "rial" (official v4) or "toman".
      ZARINPAL_AMOUNT_UNIT: "${ZARINPAL_AMOUNT_UNIT:-rial}"
    depends_on:
      postgres:
        condition: service_healthy
    healthcheck:
      test: ["CMD-SHELL", "wget -qO- http://localhost:8080/health || exit 1"]
      interval: 15s
      timeout: 5s
      retries: 5
      start_period: 10s
  # ── API Gateway (Go) ────────────────────────────────────────────────────────
  gateway:
@@ -241,7 +312,8 @@ services:
    container_name: fr2-gateway
    restart: unless-stopped
    ports:
-      - "${GATEWAY_PORT:-8080}:8080"
+      # EDGE_BIND/port face the reverse proxy (mirror-nginx → 171.22.25.73:PORT).
      - "${EDGE_BIND:-0.0.0.0}:${GATEWAY_PORT:-8080}:8080"
    environment:
      JWT_SECRET: "${JWT_SECRET}"
      IDENTITY_URL: "http://identity-svc:8080"
@@ -288,18 +360,20 @@ services:
    container_name: fr2-frontend
    restart: unless-stopped
    ports:
-      - "3000:3000"
+      - "${EDGE_BIND:-0.0.0.0}:${FRONTEND_PORT:-3000}:3000"
    environment:
      NODE_ENV: production
      PORT: "3000"
      HOSTNAME: "0.0.0.0"
      # Server-side: Next route handlers reach the gateway over the internal network.
      API_GATEWAY_URL: "http://gateway:8080"
      # Admin proxy reaches the payment broker directly (not via the gateway).
      PAYMENT_SVC_URL: "http://payment-svc:8080"
    depends_on:
      gateway:
        condition: service_healthy
    healthcheck:
-      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:3000 || exit 1"]
+      test: ["CMD", "node", "-e", "require('http').get('http://127.0.0.1:3000',r=>process.exit(r.statusCode<500?0:1)).on('error',()=>process.exit(1))"]
      interval: 30s
      timeout: 10s
      retries: 3
@@ -315,9 +389,13 @@ services:
  # For local dev (no real domain), comment out this block and access
  # services directly on their host ports (:3000, :8088, :9000).
  caddy:
-    image: caddy:2-alpine
+    image: ${INFRA_REGISTRY:-mirror.soroushasadi.com/}caddy:2-alpine
    container_name: fr2-caddy
    restart: unless-stopped
    # Opt-in only: `docker compose --profile edge up`. NOT started by default —
    # on a server with an existing reverse proxy (mirror-nginx owns 80/443),
    # FlatRender publishes host ports and the proxy routes the domains to them.
    profiles: ["edge"]
    ports:
      - "80:80"
      - "443:443"
@@ -39,11 +39,37 @@ docker compose -f docker-compose.v2.yml --env-file .env.v2 up -d <svc>
 - **Template detail page** wired to real content (`fetchProject(slug)`; was hardcoded demo catalog → 404'd).
 - **"Use template" works end-to-end:** `StudioService.CreateProjectAsync` deep-copies the content template scene graph (scenes + content elements + scene colors + shared colors) into the editable studio project via one atomic cross-schema SQL copy (enum cols cast `::text`; temp `_scene_map`). `/api/projects` resolves container slug → published variant project. **Aspect-ratio picker** (16:9/1:1/9:16) on the detail page drives which variant is copied.
-## Known follow-ups (not done)
+## ⏭️ NEXT UP — Studio↔Template binding EPIC (agreed priority)
- Scene-graph copy skips **repeater children, characters, color-presets** (scenes + fields + colors ARE copied).
+**Phase B DONE (commits a69bc62 B1, 47a4ced B2).** Edit→render binding works:
- Admin can't edit *other* users' full profiles yet (self-edit works for everyone).
+- **B1 ✅** studio input edits persist to `saved_scene_contents` via studio-svc
- Test the studio editor itself once inside (large Konva surface — not exhaustively exercised).
+  `PATCH /v1/saved-projects/{id}/contents` (Next `/api/projects/[id]/contents`); the
  persistence hook pushes edited values (bridged `c-<key>` layers) on every save.
 - **B2 ✅** render-svc claim now includes `bindings` (GetRenderBindings = saved_scene_contents
  with non-empty value); node-agent `binder.go` emits a JSON bind-spec + downloads media, runs
  the data-driven `bind.jsx` via afterfx (sets Source Text, replaces footage) → saves `bound.aep`
  → aerender renders THAT.
 - **VERIFY (needs node-agent re-run):** re-run the updated `node-agent.exe`, edit a text input in
  the studio (wait for "saved"), render, confirm the MP4 shows the edited text. Colours
  (saved_shared_colors → spec.colors) + footage-item media (vs layer-source) are follow-ups.
 - **Done since:** per-tier render height (#36), FIX-hides-add-scene (#42), admin/renders
  pagination + user-name links + output (#41), Persian/Jalali date pickers (#40).
 - **Still open in B:** colours binding (saved_shared_colors → spec.colors), footage-item
  media (vs layer-source), deeper per-input controllers in the admin scene-inputs editor.
 - Next epic phase: **A** admin preset stories (premade videos — model `preset_stories`/`preset_scenes`
  exists, no endpoints/UI; detail "ویدیوهای ساخته‌شده" is placeholder), and **C** AE single-frame
  scene snapshots (`scenes.snapshot_url` empty → node `aerender -s 0 -e 0`).
 Also smaller, still open: per-tier render **height** (render-svc r_height hardcoded 1080 + node
 ffmpeg scale), **FIX hides add-scene** (mode not plumbed into studio store), **Persian/Jalali
 date pickers** in admin, **admin/renders** pagination + video/output + user-name → profile link,
 deeper per-input controllers in the admin scene-inputs editor.
 ## Done follow-ups (this session)
 - Scene-graph copy now includes repeater children, characters/controllers, color-presets.
 - Admin CAN edit any user's full profile (Users → «پروفایل»).
 - Studio now shows ALL template inputs (contents→layers bridge).
 ## Debugging client-side behavior
@@ -144,14 +144,14 @@
    "a7": "Yes. Cancel from your account settings at any time. You keep access through the end of your billing period, and you can downgrade to Free without losing your projects."
  },
  "pricing": {
-    "heading": "Choose your FlatRender plan",
+    "heading": "Pay by the second, not by the video",
    "monthly": "Monthly",
    "annual": "Annual",
    "saveBadge": "Save up to {percent}%",
    "subscribe": "Subscribe",
    "freeBannerTitle": "Free plan",
    "freeBannerDesc": "Free forever, no credit card required",
-    "perMonth": "/ mo",
+    "perMonth": "monthly",
    "billedAnnually": "billed annually",
    "compareTitle": "Compare all plans",
    "allFeatures": "All features",
@@ -161,7 +161,45 @@
    "proName": "Pro",
    "proDesc": "Become a pro and unlock more powerful video, design and website editing tools for commercial use.",
    "businessName": "Business",
-    "businessDesc": "Advanced level solution for teams and businesses. Includes reseller license."
+    "businessDesc": "Advanced level solution for teams and businesses. Includes reseller license.",
    "subheading": "Each render costs render-seconds equal to the video length × a quality multiplier. Every plan gives you a monthly bucket of render-seconds.",
    "toman": "Toman",
    "free": "Free",
    "mostPopular": "Most popular",
    "currentPlan": "Current plan",
    "choosePlan": "Choose plan",
    "startFree": "Start free",
    "processing": "Redirecting…",
    "signInToBuy": "Sign in to buy",
    "emptyState": "No plans are available right now.",
    "perMonthSuffix": "/ mo",
    "featSeconds": "{seconds} render-seconds / month",
    "featResolution": "Up to {res} quality",
    "featParallelOne": "1 render at a time",
    "featParallel": "{n} parallel renders",
    "featStorage": "{gb} GB cloud storage",
    "featSpeed": "{factor}× render speed",
    "featWatermarkOn": "FlatRender watermark",
    "featWatermarkOff": "No watermark",
    "calcTitle": "How many seconds do I need?",
    "calcDesc": "Pick a video length and quality to see the per-render cost in seconds.",
    "calcLength": "Video length",
    "calcResolution": "Output quality",
    "calcCost": "Cost per render",
    "calcSecondsUnit": "seconds",
    "calcRendersWith": "With each plan:",
    "calcVideosFmt": "≈ {count} videos",
    "multiplierTitle": "Quality multiplier",
    "multiplierDesc": "Render-seconds per render = video length × the multiplier below.",
    "multiplierColRes": "Quality",
    "multiplierColMul": "Multiplier",
    "faqTitle": "Frequently asked",
    "faqQ1": "What is a render-second?",
    "faqA1": "Instead of a video-count limit, you buy render-seconds. A 15-second video at 720p uses exactly 15 seconds of your balance.",
    "faqQ2": "Why does higher quality cost more seconds?",
    "faqA2": "4K rendering is much heavier, so each second of video counts as 4 render-seconds; 1080p counts as 2×.",
    "faqQ3": "What if I run out of seconds?",
    "faqA3": "Upgrade your plan or wait for the next period. Your max resolution and parallel renders also follow your plan."
  },
  "footer": {
    "brandName": "FlatRender",
@@ -187,6 +225,59 @@
    "socialLinkedIn": "LinkedIn",
    "socialYouTube": "YouTube"
  },
  "blog": {
    "metaTitle": "FlatRender Blog",
    "metaDescription": "Articles, news and guides on making videos and images.",
    "pageTitle": "Blog",
    "pageDescription": "The latest articles, news and ideas on creating videos and images.",
    "readMore": "Read more",
    "views": "views",
    "empty": "No articles have been published yet."
  },
  "learn": {
    "metaTitle": "Learn FlatRender",
    "metaDescription": "Step-by-step tutorials for making professional videos and images.",
    "pageTitle": "Learn",
    "pageDescription": "Step-by-step tutorials and practical guides for getting the most out of FlatRender.",
    "readMore": "View tutorial",
    "views": "views",
    "empty": "No tutorials have been published yet."
  },
  "aboutPage": {
    "title": "About Us",
    "lead": "FlatRender makes professional video and image creation simple for everyone.",
    "body": "FlatRender is an online platform for creating videos and images with ready-made templates and smart tools.\n\nOur mission is to let anyone create professional content in minutes — no design or motion-graphics expertise required."
  },
  "contactPage": {
    "title": "Contact Us",
    "lead": "We'd love to hear from you.",
    "body": "Reach out for support, partnerships, or any questions.\n\nEmail: support@flatrender.com"
  },
  "careersPage": {
    "title": "Careers",
    "lead": "Join the FlatRender team.",
    "body": "We're always looking for talented, passionate people.\n\nTo learn about open positions, send your resume to jobs@flatrender.com."
  },
  "privacyPage": {
    "title": "Privacy Policy",
    "lead": "How we store and use your information.",
    "body": "Your privacy matters to us. This page explains how we collect, use and protect your information.\n\nThis is placeholder text and should be completed by an administrator before final publication."
  },
  "termsPage": {
    "title": "Terms of Service",
    "lead": "The rules for using FlatRender.",
    "body": "By using FlatRender you agree to the following terms.\n\nThis is placeholder text and should be completed by an administrator before final publication."
  },
  "cookiesPage": {
    "title": "Cookie Policy",
    "lead": "How we use cookies.",
    "body": "We use cookies to improve your experience on the site.\n\nThis is placeholder text and should be completed by an administrator before final publication."
  },
  "helpPage": {
    "title": "Help Center",
    "lead": "Answers to common questions and usage guides.",
    "body": "Welcome to the FlatRender Help Center.\n\nFor more questions, check the Learn section or contact support."
  },
  "auth": {
    "signIn": "Sign In",
    "signUp": "Sign Up",
@@ -316,6 +407,7 @@
  "auto": {
    "appAdminLayout": {
      "brand": "FlatRender",
      "renderEngine": "Render Engine",
      "nodes": "Nodes",
      "renderQueue": "Render Queue",
      "backToDashboard": "← Back to Dashboard",
@@ -323,13 +415,17 @@
      "categories": "Categories",
      "tags": "Tags",
      "fonts": "Fonts",
      "homePage": "Home Page",
      "blogs": "Blog",
      "learn": "Tutorials",
      "pages": "Pages",
      "slides": "Slides",
      "users": "Users",
      "plans": "Plans",
      "templates": "Templates",
      "media": "Media",
      "discounts": "Discounts",
      "payments": "Payments",
      "siteSettings": "Settings",
      "messaging": "Messaging",
      "marketing": "Marketing",
@@ -617,7 +713,8 @@
      "mostPopular": "Most Popular"
    },
    "componentsTemplatesTemplateDetailExamples": {
-      "heading": "Videos created using this template"
+      "heading": "Videos created using this template",
      "usePreset": "Use this example"
    },
    "componentsTemplatesTemplateDetailInfo": {
      "sceneCount": "{count} scenes",
@@ -857,6 +954,7 @@
      "toolShape": "Shape",
      "toolDraw": "Draw",
      "toolAi": "AI",
      "panels": "Adjust",
      "shapeRectangle": "Rectangle",
      "shapeCircle": "Circle",
      "shapeLine": "Line",
@@ -1050,8 +1148,13 @@
      "description": "Generate voiceovers from your script directly in the studio."
    },
    "componentsStudioSidebarColorsCustomTab": {
-      "mainColor": "Main Color",
+      "mainColor": "Background",
-      "additionalColor": "Additional Color",
+      "additionalColor": "Accent",
      "secondaryColor": "Secondary",
      "textColor": "Text",
      "themePresets": "Themes",
      "applyThemePreset": "Apply {name} theme",
      "applyTheme": "Apply theme",
      "applyToAllScenes": "Apply to all scenes"
    },
    "componentsStudioSidebarColorsPalettesTab": {
@@ -1086,6 +1189,14 @@
      "replaceImage": "Replace image",
      "uploadImage": "Upload image"
    },
    "componentsStudioSidebarBlockFieldForm": {
      "panelTitle": "Edit Scene",
      "emptyState": "This scene has no editable fields.",
      "fieldFallback": "Field {index}",
      "textPlaceholder": "Type here…",
      "replaceImage": "Replace image",
      "uploadImage": "Upload image"
    },
    "componentsStudioSidebarTransitionsSidebarContent": {
      "heading": "Transitions",
      "randomTransition": "Random Transition",
@@ -1126,7 +1237,10 @@
      "deleteScene": "Delete {name}",
      "resizeSceneDuration": "Resize {name} duration",
      "sceneNameLabel": "Scene name",
-      "doubleClickToRename": "Double-click to rename"
+      "doubleClickToRename": "Double-click to rename",
      "reorderScene": "Reorder {name}",
      "durationLabel": "Scene duration (seconds)",
      "secondsUnit": "s"
    },
    "componentsStudioTimelineSceneThumbnailStrip": {
      "browseScenes": "Browse scenes",
@@ -1166,6 +1280,8 @@
      "transitions": "Transitions",
      "font": "Font",
      "myWatermark": "My Watermark",
      "timeline": "Timeline",
      "preview": "Preview",
      "toolsNavLabel": "Studio tools",
      "guideMe": "Guide me",
      "guideComingSoon": "👋 Guide coming soon!",
@@ -144,14 +144,14 @@
    "a7": "بله. هر زمان از تنظیمات حساب لغو کنید. دسترسی تا پایان دوره صورت‌حساب باقی می‌ماند و می‌توانید به پلن رایگان برگردید بدون اینکه پروژه‌هایتان از دست بروند."
  },
  "pricing": {
-    "heading": "پلن فلت‌رندر خود را انتخاب کنید",
+    "heading": "پرداخت بر اساس ثانیه، نه تعداد ویدیو",
    "monthly": "ماهانه",
    "annual": "سالانه",
    "saveBadge": "تا {percent}٪ صرفه‌جویی",
    "subscribe": "اشتراک",
    "freeBannerTitle": "پلن رایگان",
    "freeBannerDesc": "برای همیشه رایگان، بدون نیاز به کارت اعتباری",
-    "perMonth": "/ ماه",
+    "perMonth": "ماهانه",
    "billedAnnually": "پرداخت سالانه",
    "compareTitle": "مقایسه همه پلن‌ها",
    "allFeatures": "همه امکانات",
@@ -161,7 +161,45 @@
    "proName": "Pro",
    "proDesc": "حرفه‌ای شوید و ابزارهای قدرتمندتر ویدیو، طراحی و وب‌سایت را برای استفاده تجاری باز کنید.",
    "businessName": "Business",
-    "businessDesc": "راه‌حل پیشرفته برای تیم‌ها و کسب‌وکارها. شامل مجوز فروش مجدد."
+    "businessDesc": "راه‌حل پیشرفته برای تیم‌ها و کسب‌وکارها. شامل مجوز فروش مجدد.",
    "subheading": "هزینهٔ هر رندر برابر است با طول ویدیو ضربدر ضریب کیفیت. هر پلن ماهانه مقداری «ثانیهٔ رندر» در اختیار شما می‌گذارد.",
    "toman": "تومان",
    "free": "رایگان",
    "mostPopular": "محبوب‌ترین",
    "currentPlan": "پلن فعلی",
    "choosePlan": "انتخاب پلن",
    "startFree": "شروع رایگان",
    "processing": "در حال انتقال…",
    "signInToBuy": "برای خرید وارد شوید",
    "emptyState": "در حال حاضر پلنی برای نمایش وجود ندارد.",
    "perMonthSuffix": "/ ماه",
    "featSeconds": "{seconds} ثانیهٔ رندر در ماه",
    "featResolution": "کیفیت تا {res}",
    "featParallelOne": "۱ رندر همزمان",
    "featParallel": "{n} رندر همزمان",
    "featStorage": "{gb} گیگابایت فضای ابری",
    "featSpeed": "سرعت رندر ×{factor}",
    "featWatermarkOn": "دارای واترمارک FlatRender",
    "featWatermarkOff": "بدون واترمارک",
    "calcTitle": "چند ثانیه لازم دارم؟",
    "calcDesc": "طول و کیفیت ویدیو را انتخاب کنید تا هزینهٔ ثانیه‌ای هر رندر را ببینید.",
    "calcLength": "طول ویدیو",
    "calcResolution": "کیفیت خروجی",
    "calcCost": "هزینهٔ هر رندر",
    "calcSecondsUnit": "ثانیه",
    "calcRendersWith": "با هر پلن:",
    "calcVideosFmt": "≈ {count} ویدیو",
    "multiplierTitle": "ضریب کیفیت",
    "multiplierDesc": "ثانیهٔ مصرفی هر رندر = طول ویدیو × ضریب کیفیت زیر.",
    "multiplierColRes": "کیفیت",
    "multiplierColMul": "ضریب",
    "faqTitle": "پرسش‌های پرتکرار",
    "faqQ1": "ثانیهٔ رندر یعنی چه؟",
    "faqA1": "به‌جای محدودیت تعداد ویدیو، شما مقداری ثانیهٔ رندر می‌خرید. یک ویدیوی ۱۵ ثانیه‌ای با کیفیت ۷۲۰p دقیقاً ۱۵ ثانیه از سهم شما کم می‌کند.",
    "faqQ2": "چرا کیفیت بالاتر ثانیهٔ بیشتری می‌برد؟",
    "faqA2": "رندر ۴K پردازش سنگین‌تری دارد، بنابراین هر ثانیه ویدیو معادل ۴ ثانیهٔ رندر حساب می‌شود؛ ۱۰۸۰p معادل ۲ برابر.",
    "faqQ3": "اگر ثانیه‌هایم تمام شود چه می‌شود؟",
    "faqA3": "می‌توانید پلن خود را ارتقا دهید یا تا شروع دورهٔ بعد صبر کنید. سقف کیفیت و رندر همزمان نیز بر اساس پلن شماست."
  },
  "footer": {
    "brandName": "فلت‌رندر",
@@ -187,6 +225,59 @@
    "socialLinkedIn": "لینکدین",
    "socialYouTube": "یوتیوب"
  },
  "blog": {
    "metaTitle": "وبلاگ فلت‌رندر",
    "metaDescription": "مقاله‌ها، خبرها و راهنماهای ساخت ویدیو و تصویر.",
    "pageTitle": "وبلاگ",
    "pageDescription": "تازه‌ترین مقاله‌ها، خبرها و ایده‌ها دربارهٔ ساخت ویدیو و تصویر.",
    "readMore": "ادامهٔ مطلب",
    "views": "بازدید",
    "empty": "هنوز مقاله‌ای منتشر نشده است."
  },
  "learn": {
    "metaTitle": "آموزش فلت‌رندر",
    "metaDescription": "آموزش‌های گام‌به‌گام برای ساخت ویدیو و تصویر حرفه‌ای.",
    "pageTitle": "آموزش",
    "pageDescription": "آموزش‌های گام‌به‌گام و راهنماهای کاربردی برای استفاده از فلت‌رندر.",
    "readMore": "مشاهدهٔ آموزش",
    "views": "بازدید",
    "empty": "هنوز آموزشی منتشر نشده است."
  },
  "aboutPage": {
    "title": "دربارهٔ ما",
    "lead": "فلت‌رندر، ساخت ویدیو و تصویر حرفه‌ای را برای همه ساده می‌کند.",
    "body": "فلت‌رندر یک پلتفرم آنلاین برای ساخت ویدیو و تصویر با کمک قالب‌های آماده و ابزارهای هوشمند است.\n\nمأموریت ما این است که هر کسی، بدون نیاز به دانش تخصصی طراحی یا موشن‌گرافیک، بتواند در چند دقیقه محتوای حرفه‌ای بسازد."
  },
  "contactPage": {
    "title": "تماس با ما",
    "lead": "خوشحال می‌شویم از شما بشنویم.",
    "body": "برای پشتیبانی، همکاری یا هر پرسشی با ما در تماس باشید.\n\nایمیل: support@flatrender.com"
  },
  "careersPage": {
    "title": "فرصت‌های شغلی",
    "lead": "به تیم فلت‌رندر بپیوندید.",
    "body": "ما همیشه به دنبال افراد بااستعداد و علاقه‌مند هستیم.\n\nبرای آگاهی از موقعیت‌های شغلی، رزومهٔ خود را به jobs@flatrender.com ارسال کنید."
  },
  "privacyPage": {
    "title": "حریم خصوصی",
    "lead": "نحوهٔ نگهداری و استفادهٔ ما از اطلاعات شما.",
    "body": "حفظ حریم خصوصی شما برای ما اهمیت دارد. این صفحه نحوهٔ گردآوری، استفاده و محافظت از اطلاعات شما را توضیح می‌دهد.\n\nاین متن نمونه است و باید پیش از انتشار نهایی توسط مدیر تکمیل شود."
  },
  "termsPage": {
    "title": "شرایط استفاده",
    "lead": "قوانین استفاده از خدمات فلت‌رندر.",
    "body": "با استفاده از فلت‌رندر، شرایط زیر را می‌پذیرید.\n\nاین متن نمونه است و باید پیش از انتشار نهایی توسط مدیر تکمیل شود."
  },
  "cookiesPage": {
    "title": "سیاست کوکی",
    "lead": "نحوهٔ استفادهٔ ما از کوکی‌ها.",
    "body": "ما از کوکی‌ها برای بهبود تجربهٔ شما در سایت استفاده می‌کنیم.\n\nاین متن نمونه است و باید پیش از انتشار نهایی توسط مدیر تکمیل شود."
  },
  "helpPage": {
    "title": "مرکز راهنما",
    "lead": "پاسخ پرسش‌های پرتکرار و راهنمای استفاده.",
    "body": "به مرکز راهنمای فلت‌رندر خوش آمدید.\n\nبرای پرسش‌های بیشتر، بخش آموزش را ببینید یا با پشتیبانی تماس بگیرید."
  },
  "auth": {
    "signIn": "ورود",
    "signUp": "ثبت‌نام",
@@ -316,6 +407,7 @@
  "auto": {
    "appAdminLayout": {
      "brand": "فلت‌رندر",
      "renderEngine": "موتور رندر",
      "nodes": "نودها",
      "renderQueue": "صف رندر",
      "backToDashboard": "← بازگشت به داشبورد",
@@ -323,13 +415,17 @@
      "categories": "دسته‌بندی‌ها",
      "tags": "برچسب‌ها",
      "fonts": "فونت‌ها",
      "homePage": "صفحهٔ اصلی",
      "blogs": "بلاگ",
      "learn": "آموزش‌ها",
      "pages": "برگه‌ها",
      "slides": "اسلایدها",
      "users": "کاربران",
      "plans": "پلن‌ها",
      "templates": "قالب‌ها",
      "media": "رسانه",
      "discounts": "تخفیف‌ها",
      "payments": "درگاه پرداخت",
      "siteSettings": "تنظیمات سایت",
      "messaging": "پیام‌رسانی",
      "marketing": "بازاریابی",
@@ -617,7 +713,8 @@
      "mostPopular": "محبوب‌ترین"
    },
    "componentsTemplatesTemplateDetailExamples": {
-      "heading": "ویدیوهای ساخته‌شده با این قالب"
+      "heading": "ویدیوهای ساخته‌شده با این قالب",
      "usePreset": "استفاده از این نمونه"
    },
    "componentsTemplatesTemplateDetailInfo": {
      "sceneCount": "{count} صحنه",
@@ -857,6 +954,7 @@
      "toolShape": "شکل",
      "toolDraw": "ترسیم",
      "toolAi": "هوش مصنوعی",
      "panels": "تنظیمات",
      "shapeRectangle": "مستطیل",
      "shapeCircle": "دایره",
      "shapeLine": "خط",
@@ -1050,8 +1148,13 @@
      "description": "صداگذاری را مستقیماً از روی متن خود در استودیو بسازید."
    },
    "componentsStudioSidebarColorsCustomTab": {
-      "mainColor": "رنگ اصلی",
+      "mainColor": "پس‌زمینه",
-      "additionalColor": "رنگ مکمل",
+      "additionalColor": "رنگ اصلی",
      "secondaryColor": "رنگ دوم",
      "textColor": "رنگ متن",
      "themePresets": "تم‌ها",
      "applyThemePreset": "اعمال تم {name}",
      "applyTheme": "اعمال تم",
      "applyToAllScenes": "اعمال به همه صحنه‌ها"
    },
    "componentsStudioSidebarColorsPalettesTab": {
@@ -1086,6 +1189,14 @@
      "replaceImage": "جایگزینی تصویر",
      "uploadImage": "بارگذاری تصویر"
    },
    "componentsStudioSidebarBlockFieldForm": {
      "panelTitle": "ویرایش صحنه",
      "emptyState": "این صحنه فیلد قابل‌ویرایشی ندارد.",
      "fieldFallback": "فیلد {index}",
      "textPlaceholder": "اینجا بنویسید…",
      "replaceImage": "جایگزینی تصویر",
      "uploadImage": "بارگذاری تصویر"
    },
    "componentsStudioSidebarTransitionsSidebarContent": {
      "heading": "ترانزیشن‌ها",
      "randomTransition": "ترانزیشن تصادفی",
@@ -1126,7 +1237,10 @@
      "deleteScene": "حذف {name}",
      "resizeSceneDuration": "تغییر مدت زمان {name}",
      "sceneNameLabel": "نام صحنه",
-      "doubleClickToRename": "برای تغییر نام، دوبار کلیک کنید"
+      "doubleClickToRename": "برای تغییر نام، دوبار کلیک کنید",
      "reorderScene": "جابه‌جایی {name}",
      "durationLabel": "مدت صحنه (ثانیه)",
      "secondsUnit": "ث"
    },
    "componentsStudioTimelineSceneThumbnailStrip": {
      "browseScenes": "مرور صحنه‌ها",
@@ -1166,6 +1280,8 @@
      "transitions": "گذارها",
      "font": "فونت",
      "myWatermark": "واترمارک من",
      "timeline": "خط زمان",
      "preview": "پیش‌نمایش",
      "toolsNavLabel": "ابزارهای استودیو",
      "guideMe": "راهنمایی‌ام کن",
      "guideComingSoon": "👋 راهنما به‌زودی ارائه می‌شود!",
@@ -2,6 +2,37 @@ import createNextIntlPlugin from "next-intl/plugin";
 const withNextIntl = createNextIntlPlugin("./src/i18n/request.ts");
 /**
 * Hosts the Next.js image optimizer is allowed to fetch from. Without these, every
 * remote <Image> (MinIO uploads/avatars/template art) returns HTTP 400. Derived from
 * NEXT_PUBLIC_MINIO_URL (baked at build) plus the dev MinIO hosts.
 */
 function imageRemotePatterns() {
  const patterns = [];
  const seen = new Set();
  const add = (protocol, hostname, port) => {
    if (!hostname) return;
    const key = `${protocol}//${hostname}:${port}`;
    if (seen.has(key)) return;
    seen.add(key);
    patterns.push({ protocol, hostname, port: port || "", pathname: "/**" });
  };
  const url = process.env.NEXT_PUBLIC_MINIO_URL;
  if (url) {
    try {
      const u = new URL(url);
      add(u.protocol.replace(":", ""), u.hostname, u.port);
    } catch {
      /* ignore malformed env */
    }
  }
  // dev / docker fallbacks
  add("http", "172.28.144.1", "9000");
  add("http", "localhost", "9000");
  add("http", "minio", "9000");
  return patterns;
 }
 /** @type {import('next').NextConfig} */
 const nextConfig = {
  output: "standalone",
@@ -25,6 +56,8 @@ const nextConfig = {
    return config;
  },
  images: {
    // Allow the image optimizer to fetch MinIO uploads (avatars, template art, …).
    remotePatterns: imageRemotePatterns(),
    // Placeholder art is now a same-origin SVG from /api/placeholder (offline-safe).
    // dangerouslyAllowSVG only ever serves our own generated gradients — never user
    // uploads — and the CSP + attachment disposition neutralise any script content.
@@ -36,10 +36,13 @@
        "lucide-react": "^1.16.0",
        "next": "14.2.35",
        "next-intl": "^4.12.0",
        "plyr": "^3.7.8",
        "plyr-react": "^5.3.0",
        "react": "^18",
        "react-dom": "^18",
        "react-hook-form": "^7.76.0",
        "react-konva": "^18.2.16",
        "react-multi-date-picker": "^4.5.2",
        "react-rnd": "^10.5.3",
        "tailwind-merge": "^3.6.0",
        "use-image": "^1.1.4",
@@ -4001,6 +4004,17 @@
      "dev": true,
      "license": "MIT"
    },
    "node_modules/core-js": {
      "version": "3.49.0",
      "resolved": "https://registry.npmjs.org/core-js/-/core-js-3.49.0.tgz",
      "integrity": "sha512-es1U2+YTtzpwkxVLwAFdSpaIMyQaq0PBgm3YD1W3Qpsn1NAmO3KSgZfu+oGSWVu6NvLHoHCV/aYcsE5wiB7ALg==",
      "hasInstallScript": true,
      "license": "MIT",
      "funding": {
        "type": "opencollective",
        "url": "https://opencollective.com/core-js"
      }
    },
    "node_modules/core-util-is": {
      "version": "1.0.3",
      "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.3.tgz",
@@ -4041,6 +4055,12 @@
      "integrity": "sha512-z1HGKcYy2xA8AGQfwrn0PAy+PB7X/GSj3UVJW9qKyn43xWa+gl5nXmU4qqLMRzWVLFC8KusUX8T/0kCiOYpAIQ==",
      "license": "MIT"
    },
    "node_modules/custom-event-polyfill": {
      "version": "1.0.7",
      "resolved": "https://registry.npmjs.org/custom-event-polyfill/-/custom-event-polyfill-1.0.7.tgz",
      "integrity": "sha512-TDDkd5DkaZxZFM8p+1I3yAlvM3rSr1wbrOliG4yJiwinMZN8z/iGL7BTlDkrJcYTmgUSb4ywVCc3ZaUtOtC76w==",
      "license": "MIT"
    },
    "node_modules/damerau-levenshtein": {
      "version": "1.0.8",
      "resolved": "https://registry.npmjs.org/damerau-levenshtein/-/damerau-levenshtein-1.0.8.tgz",
@@ -6269,6 +6289,12 @@
      "dev": true,
      "license": "MIT"
    },
    "node_modules/loadjs": {
      "version": "4.3.0",
      "resolved": "https://registry.npmjs.org/loadjs/-/loadjs-4.3.0.tgz",
      "integrity": "sha512-vNX4ZZLJBeDEOBvdr2v/F+0aN5oMuPu7JTqrMwp+DtgK+AryOlpy6Xtm2/HpNr+azEa828oQjOtWsB6iDtSfSQ==",
      "license": "MIT"
    },
    "node_modules/locate-path": {
      "version": "6.0.0",
      "resolved": "https://registry.npmjs.org/locate-path/-/locate-path-6.0.0.tgz",
@@ -7004,6 +7030,44 @@
        "node": ">= 6"
      }
    },
    "node_modules/plyr": {
      "version": "3.7.8",
      "resolved": "https://registry.npmjs.org/plyr/-/plyr-3.7.8.tgz",
      "integrity": "sha512-yG/EHDobwbB/uP+4Bm6eUpJ93f8xxHjjk2dYcD1Oqpe1EcuQl5tzzw9Oq+uVAzd2lkM11qZfydSiyIpiB8pgdA==",
      "license": "MIT",
      "dependencies": {
        "core-js": "^3.26.1",
        "custom-event-polyfill": "^1.0.7",
        "loadjs": "^4.2.0",
        "rangetouch": "^2.0.1",
        "url-polyfill": "^1.1.12"
      }
    },
    "node_modules/plyr-react": {
      "version": "5.3.0",
      "resolved": "https://registry.npmjs.org/plyr-react/-/plyr-react-5.3.0.tgz",
      "integrity": "sha512-m36/HrpHwg1N2rq3E31E8/kpAH55vk6qHUg17MG4uu9jbWYxnkN39lLmZQwxW7/qpDPfW5aGUJ6R3u23V0R3zA==",
      "license": "MIT",
      "dependencies": {
        "plyr": "^3.7.7",
        "react-aptor": "^2.0.0"
      },
      "engines": {
        "node": ">=16"
      },
      "peerDependencies": {
        "plyr": "^3.7.7",
        "react": ">=16.8"
      },
      "peerDependenciesMeta": {
        "plyr": {
          "optional": false
        },
        "react": {
          "optional": true
        }
      }
    },
    "node_modules/po-parser": {
      "version": "2.1.1",
      "resolved": "https://registry.npmjs.org/po-parser/-/po-parser-2.1.1.tgz",
@@ -7263,6 +7327,12 @@
      ],
      "license": "MIT"
    },
    "node_modules/rangetouch": {
      "version": "2.0.1",
      "resolved": "https://registry.npmjs.org/rangetouch/-/rangetouch-2.0.1.tgz",
      "integrity": "sha512-sln+pNSc8NGaHoLzwNBssFSf/rSYkqeBXzX1AtJlkJiUaVSJSbRAWJk+4omsXkN+EJalzkZhWQ3th1m0FpR5xA==",
      "license": "MIT"
    },
    "node_modules/re-resizable": {
      "version": "6.11.2",
      "resolved": "https://registry.npmjs.org/re-resizable/-/re-resizable-6.11.2.tgz",
@@ -7285,6 +7355,29 @@
        "node": ">=0.10.0"
      }
    },
    "node_modules/react-aptor": {
      "version": "2.0.0",
      "resolved": "https://registry.npmjs.org/react-aptor/-/react-aptor-2.0.0.tgz",
      "integrity": "sha512-YnCayokuhAwmBBP4Oc0bbT2l6ApfsjbY3DEEVUddIKZEBlGl1npzjHHzWnSqWuboSbMZvRqUM01Io9yiIp1wcg==",
      "license": "MIT",
      "engines": {
        "node": ">=12.7.0"
      },
      "peerDependencies": {
        "react": ">=16.8"
      },
      "peerDependenciesMeta": {
        "react": {
          "optional": true
        }
      }
    },
    "node_modules/react-date-object": {
      "version": "2.1.9",
      "resolved": "https://registry.npmjs.org/react-date-object/-/react-date-object-2.1.9.tgz",
      "integrity": "sha512-BHxD/quWOTo9fLKV/cfL/M31ePoj4a1JaJ/CnOf8Ndg3mrkh4x9wEMMkCfTrzduxDOgU8ZgR8uarhqI5G71sTg==",
      "license": "MIT"
    },
    "node_modules/react-dom": {
      "version": "18.3.1",
      "resolved": "https://registry.npmjs.org/react-dom/-/react-dom-18.3.1.tgz",
@@ -7312,6 +7405,16 @@
        "react-dom": ">= 16.3.0"
      }
    },
    "node_modules/react-element-popper": {
      "version": "2.1.7",
      "resolved": "https://registry.npmjs.org/react-element-popper/-/react-element-popper-2.1.7.tgz",
      "integrity": "sha512-tuM2OxKlW32h+6uFSK6EENHPeZ2OGgOipHfOAl+VLWEv9/j3QkSGbD+ADX3A9uJlmq24i37n28RjJmAbGTfpEg==",
      "license": "MIT",
      "peerDependencies": {
        "react": ">=16.8.0",
        "react-dom": ">=16.8.0"
      }
    },
    "node_modules/react-hook-form": {
      "version": "7.76.0",
      "resolved": "https://registry.npmjs.org/react-hook-form/-/react-hook-form-7.76.0.tgz",
@@ -7365,6 +7468,20 @@
        "react-dom": ">=18.0.0"
      }
    },
    "node_modules/react-multi-date-picker": {
      "version": "4.5.2",
      "resolved": "https://registry.npmjs.org/react-multi-date-picker/-/react-multi-date-picker-4.5.2.tgz",
      "integrity": "sha512-FgWjZB3Z6IA6XpcWiLPk85PwcRUhOiYhKK42o5k672gD/n2I6rzPfQ8bUrldOIiF/Z7FfOCdH7a6FeubzqteLg==",
      "license": "MIT",
      "dependencies": {
        "react-date-object": "^2.1.8",
        "react-element-popper": "^2.1.6"
      },
      "peerDependencies": {
        "react": ">=16.8.0",
        "react-dom": ">=16.8.0"
      }
    },
    "node_modules/react-reconciler": {
      "version": "0.29.2",
      "resolved": "https://registry.npmjs.org/react-reconciler/-/react-reconciler-0.29.2.tgz",
@@ -8667,6 +8784,12 @@
        "punycode": "^2.1.0"
      }
    },
    "node_modules/url-polyfill": {
      "version": "1.1.14",
      "resolved": "https://registry.npmjs.org/url-polyfill/-/url-polyfill-1.1.14.tgz",
      "integrity": "sha512-p4f3TTAG6ADVF3mwbXw7hGw+QJyw5CnNGvYh5fCuQQZIiuKUswqcznyV3pGDP9j0TSmC4UvRKm8kl1QsX1diiQ==",
      "license": "MIT"
    },
    "node_modules/use-callback-ref": {
      "version": "1.3.3",
      "resolved": "https://registry.npmjs.org/use-callback-ref/-/use-callback-ref-1.3.3.tgz",
@@ -37,10 +37,13 @@
    "lucide-react": "^1.16.0",
    "next": "14.2.35",
    "next-intl": "^4.12.0",
    "plyr": "^3.7.8",
    "plyr-react": "^5.3.0",
    "react": "^18",
    "react-dom": "^18",
    "react-hook-form": "^7.76.0",
    "react-konva": "^18.2.16",
    "react-multi-date-picker": "^4.5.2",
    "react-rnd": "^10.5.3",
    "tailwind-merge": "^3.6.0",
    "use-image": "^1.1.4",
--- a/Show More
+++ b/Show More