@topy-ai/maggie 0.8.7 → 0.8.9

package/README-zh-TW.md

@@ -143,7 +143,7 @@ structure drift 或重複 treatment product 時 fail closed。
 deployment、memory、feedback 和 MaggieDash。內容先 draft/review，外部寫入、
 publish 與 production deployment 需要明確確認。
 
-目前 npm 版本為 `0.8.7`,把 redesign 稽核併入 `maggie-design`(改編自 MIT 的 `elayadesign/redesign-skill`):掃描 + 診斷 AI 通病/缺失狀態/雜亂程式碼,再經 in-place/verify 流程就地修正,因此「稽核/打磨/升級既有站點」會路由到 maggie-design。先前 0.8.6 補齊兩個設計技能:加入完整的生產 reference,並把設計來源明確為 Figma 非必需(實時 URL、既有程式碼、Figma、或純截圖)。先前 0.8.5 採納兩個設計技能(改編自 MIT 的 `elayadesign/ai-design-skills`):maggie-landing-page(轉化策略 + 視覺系統紀律,具體數值為可被專案 DESIGN.md 覆蓋的預設值;由 maggie-design 生產與驗證)與 maggie-design-motion(靜態設計→像素級動畫 HTML 複刻→匯出 MP4 + GIF)。先前 0.8.4 將技能庫擴展成完整的「一人用 AI 跑一家公司」C-suite,新增八條職能線:maggie-sales(CRM 中立的銷售管線)、maggie-finance(只解釋的 CFO 指標,含確定性 maggie_finance.py 計算器)、maggie-support(面向客戶的客戶成功)、maggie-product(路線圖 + 預註冊實驗)、maggie-fundraising(pitch deck、data room、投資人更新)、maggie-legal(ToS/隱私/DPA/SOC2 readiness)、maggie-monetization(定價/paywall/dunning,金錢操作需人工批准)、maggie-orchestrator(CEO 編排層:將目標拆成帶審批門的 mission 分派到各職能線,含 maggie_orchestrator.py 規劃器)。先前 0.8.3 將 cmo.so/www 開發經驗沉澱進技能庫:新增兩個技能 maggie-skill-authoring(依 catalog 與 MCP 工具白名單撰寫/校驗社區營銷 playbook 技能)與 maggie-feedback-triage(反饋的團隊接收端:決策/定級/分派、PRD + issue 流程、24/7 隊列守護);新增多個 reference(OAuth PKCE 登入、Expo 約定與 Router 骨架、MCP evals 測試框架、conversation cards、WordPress→Firebase 認證遷移手冊);並增補 maggie-assistant-tools(tool≤user 每輪工具過濾、agent loop 安全不變量、preview-only 橋接代理、MCP resources/prompts、注解加固、CLI 與 ChatGPT 插件打包)、maggie-auth-reference(自清理登入測試套件、自簽單次令牌)、maggie-mobile-app(OTA 開機拉取、live==built 部署守衛)、maggie-deployment(pm2 單包發布、live-hash 校驗)與 maggie-ops(template-as-code 郵件同步)。先前 0.8.2 新增 maggie-spirit(為 AI 品牌生成平面像素 spirit/sprite 系統)與 goal-led AI agent 設計參考;0.8.0 為安全優化 roadmap(scan、image-patch、標頭評分、SSVC、GDPR 日誌規則、新 MCP 工具)。先前 0.8.0 為安全優化 roadmap(scan、image-patch、標頭評分、SSVC、GDPR 日誌規則、新 MCP 工具),含 fix-plan 修補風險分級 T1–T4(判斷補丁是否安全套用)與 host-impact 補丁影響面量測(哪些服務需重啟、是否需重開機)、public-check、Maggie Security、batch 31 排程 agent routines、報告收件匣與無人值守 agent 限制、PHP runtime 盤點與主機鎖、pull 網站改寫、query 點子與社群佇列檢查，batch 30 MaggieDash 先裝核心、release privacy gate、feedback 備援、社群連結與圖片檢查、大量頁面產生與 app 檢查，batch 29 預約規則、部署、app QA、助理與社群功能，以及 batch 28 產品 app、assistant tools、mobile、product release、skills catalog 與 bridge host 功能、batch 26、27 feedback 修正與 idempotent `maggie update`與 Booking email-template 合約/CLI validator 同步。本版完成 2026-09-24 booking feedback batch：Calendar grid/free-slot entry 與 host modal focus-restoration evidence。本版新增 Starter marketplace provisioning plan；本版完成 feedback batches 22、23：加入 declarative browser interaction evidence、design markup/style/content-key gate、compiler source anchoring、entity double-escape protection、`update --help` read-only、noindex hypothetical indexability、可過期 baseline acknowledgement、DOM-only link extraction regression，以及 MaggieDash 0.2.10 的 content override、短期 browser session、CDN-safe public-session cache contracts。authentication 和 isolated dev server 仍由 host 負責。`maggie-booking` workflow、傳統 email/password、Stripe、Resend、public booking flow 及既有安全邊界維持不變；provider-bound video generation 與 transactional delivery 仍記錄在 issue #39，前一批延後功能仍在 issue #38，不會直接成為 active memory。0.7.33 記錄並審查一筆更正回饋；確認 0.7.32 已正確處理 batch index，沒有修改已驗證的 shared behavior。0.7.32 加入 feedback 一基索引支援、MaggieDash panel 的 source/freshness/error evidence、Consent Mode 與實際 write/no-op reconciliation、SEO baseline recapture、sitemap origin rebasing、content-diff scope、migration ledger reconciliation、deployment credential preflight、release provenance/runtime preflight、icon release gate、opt-in blog auto-publish gate，以及 least-privilege VPS deployer。也修復 top-level `maggie feedback` dispatcher parity。0.7.31 加入 update 差異摘要、atomic installer copy、subset install manifest merge，以及 inventory drift 時 doctor non-zero。0.7.30 補上 feedback tracking issue closeout gate 與 batch 14/15 audit ledger。0.7.29 修正 npm package landing page 使用英文 README；0.7.28 加入 versioned Gemini model policy、明確 fallback 與 provenance、bundled-first CLI
+目前 npm 版本為 `0.8.9`,為 `maggie_video.py` 新增 `compile` 子命令(把宣告式 timeline JSON 編譯成單一 ffmpeg 命令,已實測)。先前 0.8.8 新增 `maggie-video`(製作與處理行銷影片:剪輯、字幕、裁切成各渠道比例、浮水印、轉碼、響度正規化、clip 組裝、程式化動畫),附一個實測可用的 ffmpeg 配方 CLI(`maggie_video.py`),從參考庫的影片專案(moviepy/editly/ffmpeg 命令層、Revideo/Motion Canvas/CCapture 程式化渲染、MLT/OpenShot/Olive 的 timeline 資料形狀)提煉而來;另加 `ffmpeg-recipes`、`programmatic-video`、`video-timeline-model` 三個 reference。先前 0.8.7 把 redesign 稽核併入 `maggie-design`(改編自 MIT 的 `elayadesign/redesign-skill`):掃描 + 診斷 AI 通病/缺失狀態/雜亂程式碼,再經 in-place/verify 流程就地修正,因此「稽核/打磨/升級既有站點」會路由到 maggie-design。先前 0.8.6 補齊兩個設計技能:加入完整的生產 reference,並把設計來源明確為 Figma 非必需(實時 URL、既有程式碼、Figma、或純截圖)。先前 0.8.5 採納兩個設計技能(改編自 MIT 的 `elayadesign/ai-design-skills`):maggie-landing-page(轉化策略 + 視覺系統紀律,具體數值為可被專案 DESIGN.md 覆蓋的預設值;由 maggie-design 生產與驗證)與 maggie-design-motion(靜態設計→像素級動畫 HTML 複刻→匯出 MP4 + GIF)。先前 0.8.4 將技能庫擴展成完整的「一人用 AI 跑一家公司」C-suite,新增八條職能線:maggie-sales(CRM 中立的銷售管線)、maggie-finance(只解釋的 CFO 指標,含確定性 maggie_finance.py 計算器)、maggie-support(面向客戶的客戶成功)、maggie-product(路線圖 + 預註冊實驗)、maggie-fundraising(pitch deck、data room、投資人更新)、maggie-legal(ToS/隱私/DPA/SOC2 readiness)、maggie-monetization(定價/paywall/dunning,金錢操作需人工批准)、maggie-orchestrator(CEO 編排層:將目標拆成帶審批門的 mission 分派到各職能線,含 maggie_orchestrator.py 規劃器)。先前 0.8.3 將 cmo.so/www 開發經驗沉澱進技能庫:新增兩個技能 maggie-skill-authoring(依 catalog 與 MCP 工具白名單撰寫/校驗社區營銷 playbook 技能)與 maggie-feedback-triage(反饋的團隊接收端:決策/定級/分派、PRD + issue 流程、24/7 隊列守護);新增多個 reference(OAuth PKCE 登入、Expo 約定與 Router 骨架、MCP evals 測試框架、conversation cards、WordPress→Firebase 認證遷移手冊);並增補 maggie-assistant-tools(tool≤user 每輪工具過濾、agent loop 安全不變量、preview-only 橋接代理、MCP resources/prompts、注解加固、CLI 與 ChatGPT 插件打包)、maggie-auth-reference(自清理登入測試套件、自簽單次令牌)、maggie-mobile-app(OTA 開機拉取、live==built 部署守衛)、maggie-deployment(pm2 單包發布、live-hash 校驗)與 maggie-ops(template-as-code 郵件同步)。先前 0.8.2 新增 maggie-spirit(為 AI 品牌生成平面像素 spirit/sprite 系統)與 goal-led AI agent 設計參考;0.8.0 為安全優化 roadmap(scan、image-patch、標頭評分、SSVC、GDPR 日誌規則、新 MCP 工具)。先前 0.8.0 為安全優化 roadmap(scan、image-patch、標頭評分、SSVC、GDPR 日誌規則、新 MCP 工具),含 fix-plan 修補風險分級 T1–T4(判斷補丁是否安全套用)與 host-impact 補丁影響面量測(哪些服務需重啟、是否需重開機)、public-check、Maggie Security、batch 31 排程 agent routines、報告收件匣與無人值守 agent 限制、PHP runtime 盤點與主機鎖、pull 網站改寫、query 點子與社群佇列檢查，batch 30 MaggieDash 先裝核心、release privacy gate、feedback 備援、社群連結與圖片檢查、大量頁面產生與 app 檢查，batch 29 預約規則、部署、app QA、助理與社群功能，以及 batch 28 產品 app、assistant tools、mobile、product release、skills catalog 與 bridge host 功能、batch 26、27 feedback 修正與 idempotent `maggie update`與 Booking email-template 合約/CLI validator 同步。本版完成 2026-09-24 booking feedback batch：Calendar grid/free-slot entry 與 host modal focus-restoration evidence。本版新增 Starter marketplace provisioning plan；本版完成 feedback batches 22、23：加入 declarative browser interaction evidence、design markup/style/content-key gate、compiler source anchoring、entity double-escape protection、`update --help` read-only、noindex hypothetical indexability、可過期 baseline acknowledgement、DOM-only link extraction regression，以及 MaggieDash 0.2.10 的 content override、短期 browser session、CDN-safe public-session cache contracts。authentication 和 isolated dev server 仍由 host 負責。`maggie-booking` workflow、傳統 email/password、Stripe、Resend、public booking flow 及既有安全邊界維持不變；provider-bound video generation 與 transactional delivery 仍記錄在 issue #39，前一批延後功能仍在 issue #38，不會直接成為 active memory。0.7.33 記錄並審查一筆更正回饋；確認 0.7.32 已正確處理 batch index，沒有修改已驗證的 shared behavior。0.7.32 加入 feedback 一基索引支援、MaggieDash panel 的 source/freshness/error evidence、Consent Mode 與實際 write/no-op reconciliation、SEO baseline recapture、sitemap origin rebasing、content-diff scope、migration ledger reconciliation、deployment credential preflight、release provenance/runtime preflight、icon release gate、opt-in blog auto-publish gate，以及 least-privilege VPS deployer。也修復 top-level `maggie feedback` dispatcher parity。0.7.31 加入 update 差異摘要、atomic installer copy、subset install manifest merge，以及 inventory drift 時 doctor non-zero。0.7.30 補上 feedback tracking issue closeout gate 與 batch 14/15 audit ledger。0.7.29 修正 npm package landing page 使用英文 README；0.7.28 加入 versioned Gemini model policy、明確 fallback 與 provenance、bundled-first CLI
 dispatch、`maggie --version`、feedback batch review 聚合與重複偵測、marketplace enrichment evidence、booking
 worker/resolver evidence，以及 read-only migration preflight。它也包含 host-owned mobile app surface contract、signed-in
 camera-state QA、直接 Astro route resolution、correlated feedback batch，以及

package/README.md

@@ -87,9 +87,9 @@ Then invoke the installed skills from your coding agent, for example:
 
 Maggie keeps the existing project foundation and asks for decisions before
 shared routes, analytics, or publishing boundaries change. The current
-package ships 36 installable skills and a local-first MaggieDash foundation.
+package ships 37 installable skills and a local-first MaggieDash foundation.
 
-This package is `0.8.7` — it folds a redesign audit into `maggie-design` (from the MIT `elayadesign/redesign-skill`): scan + diagnose generic AI-design patterns/weak states/sloppy code, then fix in place via the in-place/verify flow, so "audit/polish/upgrade an existing site" routes to maggie-design. `0.8.6` completed the two adopted design skills with full production references and made the design source Figma-optional (live URL, existing code, Figma, or a screenshot). `0.8.5` adopted the two design skills (adapted, MIT, from `elayadesign/ai-design-skills`): `maggie-landing-page` (conversion strategy + a visual-system discipline whose values defer to the project's DESIGN.md) and `maggie-design-motion` (static design → pixel-exact animated HTML replica → MP4 + GIF export). `0.8.4` expanded the library into a full "one person runs a company with AI" C-suite with eight new function lanes: `maggie-sales` (CRM-neutral pipeline), `maggie-finance` (explain-only CFO metrics + a deterministic `maggie_finance.py` calculator), `maggie-support` (customer success), `maggie-product` (roadmap + pre-registered experiments), `maggie-fundraising` (deck, data room, investor updates), `maggie-legal` (ToS/privacy/DPA/SOC2 readiness), `maggie-monetization` (pricing/paywalls/dunning; money actions human-approved), and `maggie-orchestrator` (the CEO layer that decomposes a goal into gated missions across the lanes, with a `maggie_orchestrator.py` planner). `0.8.3` folded cmo.so/www development learnings in (maggie-skill-authoring, maggie-feedback-triage, and mobile/MCP/auth references); `0.8.2` added `maggie-spirit`; `0.8.0` was the security optimization roadmap.
+This package is `0.8.9` — it adds a `compile` subcommand to `maggie_video.py` (declarative timeline JSON -> one ffmpeg command, tested end-to-end). `0.8.8` added `maggie-video` (produce and process marketing video: cut, caption, resize to channel aspects, watermark, transcode, normalize loudness, assemble clips, render code-drawn animation) with a tested ffmpeg-recipe CLI, distilled from the reference library's video projects; plus references `ffmpeg-recipes`, `programmatic-video`, `video-timeline-model`. `0.8.7` folded a redesign audit into `maggie-design` (from the MIT `elayadesign/redesign-skill`): scan + diagnose generic AI-design patterns/weak states/sloppy code, then fix in place via the in-place/verify flow, so "audit/polish/upgrade an existing site" routes to maggie-design. `0.8.6` completed the two adopted design skills with full production references and made the design source Figma-optional (live URL, existing code, Figma, or a screenshot). `0.8.5` adopted the two design skills (adapted, MIT, from `elayadesign/ai-design-skills`): `maggie-landing-page` (conversion strategy + a visual-system discipline whose values defer to the project's DESIGN.md) and `maggie-design-motion` (static design → pixel-exact animated HTML replica → MP4 + GIF export). `0.8.4` expanded the library into a full "one person runs a company with AI" C-suite with eight new function lanes: `maggie-sales` (CRM-neutral pipeline), `maggie-finance` (explain-only CFO metrics + a deterministic `maggie_finance.py` calculator), `maggie-support` (customer success), `maggie-product` (roadmap + pre-registered experiments), `maggie-fundraising` (deck, data room, investor updates), `maggie-legal` (ToS/privacy/DPA/SOC2 readiness), `maggie-monetization` (pricing/paywalls/dunning; money actions human-approved), and `maggie-orchestrator` (the CEO layer that decomposes a goal into gated missions across the lanes, with a `maggie_orchestrator.py` planner). `0.8.3` folded cmo.so/www development learnings in (maggie-skill-authoring, maggie-feedback-triage, and mobile/MCP/auth references); `0.8.2` added `maggie-spirit`; `0.8.0` was the security optimization roadmap.
 
 The 0.7.59 release made `maggie security host-audit` (the deep
 lynis audit over SSH) robust on hosts where a storage test can stall: lynis runs

package/bundled-references/ffmpeg-recipes.md

@@ -0,0 +1,126 @@
+# ffmpeg recipes
+
+The distilled, correct ffmpeg command layer for marketing video, used by
+`maggie-video` (and shared with `maggie-design-motion`'s export). These are the
+commands `maggie_video.py` generates; this reference explains each so they can be
+adapted. Distilled from moviepy, editly, auto-editor, FFmpeg and HandBrake (see
+the design reference library category N). We **invoke the `ffmpeg` binary** (not
+link libav), so this stays license-clean; most ffmpeg builds bundle x264/x265 and
+are GPL binaries - fine to invoke, do not vendor a GPL build into a package.
+
+Common prefix: `ffmpeg -y -hide_banner -loglevel error`. Always force
+`-pix_fmt yuv420p` and `setsar=1` on output for universal playback (moviepy has a
+latent `yuva420p` typo - do not copy it).
+
+## Encode (web-safe MP4)
+
+```bash
+ffmpeg -y -i IN -c:v libx264 -profile:v high -preset medium -crf 20 \
+  -pix_fmt yuv420p -c:a aac -b:a 128k -movflags +faststart OUT.mp4
+```
+
+`+faststart` moves the moov atom to the front for web streaming. CRF 18-23 (lower =
+larger/better). WebM (VP9): `-c:v libvpx-vp9 -crf 32 -b:v 0 -row-mt 1 -pix_fmt
+yuv420p -c:a libopus -b:a 128k`.
+
+## High-quality GIF (one-pass palette)
+
+```bash
+ffmpeg -y -i IN -vf "fps=15,scale=480:-1:flags=lanczos,split[s0][s1];\
+[s0]palettegen[p];[s1][p]paletteuse" -loop 0 OUT.gif
+```
+
+Scale/fps down first to keep size sane; the palette pass avoids banding. Keep bayer
+dithering (`paletteuse=dither=bayer:bayer_scale=4`) when a photo is in frame.
+
+## Trim
+
+```bash
+# fast, no re-encode (cuts at the nearest keyframe)
+ffmpeg -y -ss START -i IN -t DURATION -map 0 -c copy -avoid_negative_ts make_zero OUT.mp4
+# frame-accurate: drop -c copy and re-encode with the MP4 recipe
+```
+
+## Concat
+
+```bash
+# same codec (fast): concat.txt has lines  file '/abs/clip1.mp4'
+ffmpeg -y -f concat -safe 0 -i concat.txt -c copy OUT.mp4
+# mixed sources (re-encode via filter)
+ffmpeg -y -i a.mp4 -i b.mp4 -filter_complex \
+  "[0:v][0:a][1:v][1:a]concat=n=2:v=1:a=1[v][a]" -map "[v]" -map "[a]" \
+  -c:v libx264 -crf 20 -pix_fmt yuv420p -movflags +faststart OUT.mp4
+```
+
+## Scale + pad or crop to a channel aspect
+
+```bash
+# 9:16 reel (1080x1920); use 1080x1080 square or 1920x1080 landscape likewise
+# pad (letterbox, no distortion):
+ffmpeg -y -i IN -vf "scale=1080:1920:force_original_aspect_ratio=decrease,\
+pad=1080:1920:(ow-iw)/2:(oh-ih)/2:color=black,setsar=1" \
+  -c:v libx264 -crf 20 -pix_fmt yuv420p -movflags +faststart OUT.mp4
+# crop (fill): force_original_aspect_ratio=increase,crop=1080:1920,setsar=1
+```
+
+## Overlay / watermark (logo bottom-right, scaled to 12% height, 24px margin)
+
+```bash
+ffmpeg -y -i IN -i logo.png -filter_complex \
+  "[1][0]scale2ref=w=oh*mdar:h=ih*0.12[logo][base];[base][logo]overlay=W-w-24:H-h-24" \
+  -c:a copy -c:v libx264 -crf 20 -pix_fmt yuv420p OUT.mp4
+```
+
+## Subtitles
+
+```bash
+# burn in (hardsub) from SRT
+ffmpeg -y -i IN -vf "subtitles=subs.srt:force_style='FontName=Inter,FontSize=24,BorderStyle=3'" \
+  -c:v libx264 -crf 20 -pix_fmt yuv420p -c:a copy OUT.mp4
+# soft-mux (toggleable track, MP4)
+ffmpeg -y -i IN -i subs.srt -c copy -c:s mov_text -metadata:s:s:0 language=eng OUT.mp4
+```
+
+## Loudness normalize (EBU R128; -14 LUFS = social/YouTube target)
+
+```bash
+# quick single pass
+ffmpeg -y -i IN -af loudnorm=I=-14:TP=-1.5:LRA=11 -c:v copy -c:a aac -b:a 128k OUT.mp4
+# accurate two pass: measure first (reads JSON from stderr), then apply measured_* values
+ffmpeg -i IN -af loudnorm=I=-14:TP=-1.5:LRA=11:print_format=json -f null -
+```
+
+editly's cheaper alternative is `dynaudnorm=g=5:maxgain=30`.
+
+## Thumbnail / poster
+
+```bash
+ffmpeg -y -ss 00:00:03 -i IN -frames:v 1 -q:v 2 OUT.jpg       # at a timestamp
+ffmpeg -y -i IN -vf "thumbnail,scale=1280:-1" -frames:v 1 OUT.jpg  # most representative frame
+```
+
+## Silence auto-cut (auto-editor's idea, via the CLI)
+
+```bash
+ffmpeg -i IN -af silencedetect=noise=-30dB:d=0.3 -f null -   # detect ranges
+# then build a select/concat of the kept ranges (pad each ~0.2s)
+```
+
+## Transitions (between two clips)
+
+`xfade=transition=fade:duration=0.5:offset=5.0` for video and `acrossfade=d=0.5`
+for audio. editly/gl-transitions names (`fade`, `dissolve`, `directional-left`, ...)
+map onto xfade's transition list.
+
+## The CLI
+
+`maggie_video.py` generates every command above (and runs it with `--run` when
+`ffmpeg` is on PATH). It prints the command so it is reviewable and loggable:
+
+```bash
+maggie tool maggie_video.py social --input in.mp4 --output reel.mp4 --aspect reel
+maggie tool maggie_video.py gif --input in.mp4 --output out.gif --fps 15 --width 480
+maggie tool maggie_video.py compile --spec timeline.json   # declarative timeline -> one command
+maggie tool maggie_video.py --run encode --input in.mov --output out.mp4   # actually runs
+maggie tool maggie_video.py presets
+```

package/bundled-references/programmatic-video.md

@@ -0,0 +1,80 @@
+# Programmatic video: the render-then-encode pattern
+
+How to produce video from code deterministically, distilled from the leading
+engines (Motion Canvas, Remotion, Revideo, CCapture). Used by `maggie-video`;
+`maggie-design-motion`'s Part C is one concrete implementation of this pattern (the
+DOM/Playwright case). Author your own code from this; adopt engines per the license
+table below.
+
+## The pattern (every engine agrees)
+
+1. **The frame is the unit of truth; the wall clock is the enemy.** Deterministic
+   output comes from driving content by an **absolute frame index or a virtual
+   clock**, never real time. Two techniques:
+   - **Seek by frame:** re-evaluate the scene at frame N (`playback.seek(frame)` in
+     Motion Canvas / Revideo; the current-frame hook in Remotion).
+   - **Fake the clock:** monkeypatch `performance.now`, `requestAnimationFrame`,
+     `Date`, timers and `currentTime`, and advance one fixed step per captured frame
+     (CCapture's `TimeWarp`; Playwright's `page.clock` + `__tick` in Part C).
+2. **Render then encode, decoupled.** Produce frames as fast as the machine allows
+   (not realtime) into a canvas/DOM, then feed an encoder as a separate stage.
+3. **Two encode routes.** (a) **Shell out to ffmpeg** via a pipe - `image2pipe`
+   base64 PNG (Revideo) or `rawvideo`/rgba (Motion Canvas), output
+   `-pix_fmt yuv420p -movflags +faststart` (the exact profile in
+   [ffmpeg recipes](ffmpeg-recipes.md)). (b) **In-browser WebCodecs** (CCapture) -
+   no ffmpeg dependency, hardware-accelerated.
+4. **Headless browser as the frame factory** when the composition is web tech:
+   Revideo = Puppeteer, Remotion = headless Chromium, Part C = Playwright. The page
+   renders; the driver screenshots or reads back each frame.
+5. **One source → preview + render + parameterized batch.** The same scene file
+   drives a live preview and the headless render; **variables/props** turn one
+   template into many videos (N brand variants, localized cuts, per-product reels).
+
+## Composition models
+
+- **React components** (Remotion, Revideo also supports React) - animation driven by
+  the current frame via hooks.
+- **Generator functions** (Motion Canvas, Revideo) - a scene is
+  `makeScene2D(function* (view) { view.add(<Rect/>); yield* all(rect().position.x(100, 1)); yield* waitFor(0.5); })`;
+  timing is the generator's control flow; signals (`createSignal`) provide
+  reactivity. These read cleanly for an LLM to author from a prompt.
+- **Canvas draw calls + a recorder** (CCapture) - any existing rAF canvas loop plus
+  one `capturer.capture(canvas)` line.
+
+## Choosing an engine (decision)
+
+- **Animating an existing rendered page/design** → stay in
+  `maggie-design-motion` Part C (Playwright fake-clock). No new engine needed; this
+  is the common Maggie case (social/hero motion from a design).
+- **Programmatic, data-driven video from scratch** (N variants from brand data,
+  charts, captions) → **Revideo** - MIT, headless-first, parameterizable
+  (`renderVideo({projectFile, variables, settings:{outFile, workers}})`),
+  parallelizable across workers, and it ships a `revideo serve` render endpoint
+  (with `callbackUrl` + SSE progress) for render-as-a-service.
+- **A pure canvas sketch already using rAF** that just needs recording → **CCapture**
+  (WebCodecs, no ffmpeg).
+- **Simple clip assembly / transcode / captions** (not code-drawn animation) → the
+  ffmpeg layer directly ([ffmpeg recipes](ffmpeg-recipes.md)) or the declarative
+  [timeline model](video-timeline-model.md).
+
+## Licenses (critical)
+
+| Engine | License | Adopt? |
+|---|---|---|
+| Motion Canvas | MIT | Yes (generators; editor-driven render) |
+| **Revideo** | MIT | **Yes - recommended programmatic default** (headless, parameterized, parallel) |
+| CCapture.js | MIT | Yes - the WebCodecs recorder / clock-faking reference |
+| video.js | Apache-2.0 | Playback only, not production |
+| **Remotion** | **Remotion License (source-available; paid Company License for for-profit orgs > 3 employees)** | **No hard dependency** - reference/option the end user may license; keep Maggie's default on the MIT stack |
+
+Rendering is a **local CPU/GPU cost** (ffmpeg, a headless browser), not a paid API -
+flag long renders as a time/resource cost, consistent with "local tools only". If
+any hosted or LLM video generation is wired in, the global BYOK + spend-first rules
+apply.
+
+## Shared encode profile
+
+`maggie-video` and `maggie-design-motion` share one profile:
+`libx264 -crf 14-20 -preset slow/medium -pix_fmt yuv420p -movflags +faststart`,
+even dimensions, plus 960px / 800x500 GIF deliverables. For transparent output,
+Revideo uses per-format pixel formats (`yuva420p` WebM, `yuva444p10le` ProRes).

package/bundled-references/video-timeline-model.md

@@ -0,0 +1,127 @@
+# Marketing-video timeline model
+
+An engine-neutral, provider-neutral data shape for "assemble these clips, images,
+text, captions and audio into a video", distilled from the open NLEs (MLT /
+Shotcut / Kdenlive, OpenShot, Olive). Used by `maggie-video`. We adopt the **data
+shape** (an uncopyrightable idea), never their code - MLT/Shotcut/Kdenlive/OpenShot/
+Olive are LGPL/GPL. It renders through the **ffmpeg binary** (the common
+denominator, arm's-length), or optionally through `melt` as a GPL external tool.
+
+## Conventions (chosen for LLM-friendliness)
+
+- **Seconds** (floats) at the authoring layer, not frames (OpenShot-style).
+- **`position`** = where a clip starts on the timeline; **`start`/`end`** = the trim
+  within its source (OpenShot's split; MLT calls the trim `in`/`out`).
+- **`z`** = track stacking; higher is on top (mirrors MLT `b_track` over `a_track`,
+  OpenShot's higher layer number).
+- **Keyframes** as `{t, v, ease}` arrays, ease in `linear | hold | smooth | bezier`
+  (MLT's linear/discrete/smooth + OpenShot's Linear/Constant/Bezier).
+- **Relative positions/sizes** (`"80%"`, 0..1) + named anchors, so it is
+  resolution-independent.
+
+## The model
+
+```jsonc
+{
+  "output": { "width": 1080, "height": 1920, "fps": 30, "format": "mp4",
+              "vcodec": "h264", "acodec": "aac", "duration": "auto" },
+  "assets": {
+    "shot1": { "type": "video", "src": "footage/a.mp4" },
+    "product": { "type": "image", "src": "footage/product.jpg" },
+    "logo": { "type": "image", "src": "brand/logo.png" },
+    "vo": { "type": "audio", "src": "audio/vo.mp3" },
+    "music": { "type": "audio", "src": "audio/track.mp3" }
+  },
+  "tracks": [
+    { "id": "main", "kind": "video", "z": 0, "clips": [
+      { "asset": "shot1", "start": 2.0, "end": 7.0, "position": 0.0, "fit": "cover",
+        "effects": [ { "type": "zoom", "keyframes": [
+          {"t":0.0,"v":1.0,"ease":"linear"}, {"t":5.0,"v":1.12,"ease":"smooth"} ] } ] },
+      { "asset": "product", "position": 5.0, "duration": 4.0, "fit": "cover" }
+    ] },
+    { "id": "overlay", "kind": "video", "z": 10, "clips": [
+      { "type": "text", "text": "50% OFF TODAY", "position": 1.0, "duration": 3.0,
+        "style": { "font": "Inter-Bold", "size": 96, "color": "#FFFFFF", "box": "#E11D48", "align": "center" },
+        "rect": { "x": "10%", "y": "70%", "w": "80%", "h": "15%" },
+        "effects": [ { "type": "opacity", "keyframes": [
+          {"t":0,"v":0}, {"t":0.4,"v":1}, {"t":2.6,"v":1}, {"t":3.0,"v":0} ] } ] },
+      { "asset": "logo", "position": 0.0, "duration": 9.0,
+        "rect": { "x": "80%", "y": "5%", "w": "15%", "h": "auto" } },
+      { "type": "captions", "src": "audio/vo.srt" }
+    ] }
+  ],
+  "transitions": [ { "type": "crossfade", "between": ["shot1","product"], "position": 5.0, "duration": 0.5 } ],
+  "audio": [
+    { "asset": "vo", "position": 0.5, "gain": 0 },
+    { "asset": "music", "position": 0.0, "gain": -18, "ducking": { "under": "vo", "amount": -12 },
+      "fade_out": { "at": 8.5, "duration": 0.5 } }
+  ]
+}
+```
+
+Minimal required: `output{width,height,fps,format}`, `assets{}`, one video track of
+`clips[]` each with `asset`+`position`+(`duration` or `start`/`end`). Everything
+else is additive.
+
+## Field crosswalk (stay compatible with any backend)
+
+| this model | MLT | OpenShot | Olive |
+|---|---|---|---|
+| asset `src` | producer `resource` | `files[].path` | footage node |
+| `start`/`end` (trim) | `in`/`out` (frames) | `start`/`end` (sec) | `kMediaInInput` |
+| `position` (timeline) | playlist order + `blank` | `position` (sec) | `ClipBlock.in()` |
+| track / `z` | playlist in multitrack | `layer` number | block in sequence |
+| overlay | `composite` transition | higher layer | graph edge |
+| keyframe ease | `linear`/`discrete`(`|`)/`smooth`(`~`) | Linear/Constant/Bezier | kLinear/kHold/kBezier |
+| time base | frames | seconds | rational |
+
+## Rendering through ffmpeg (default, no GPL linking)
+
+Compile the model to one `filter_complex`:
+
+- **trim / in-out:** `-ss start -t dur -i a.mp4`, or `trim=start=..:end=..,setpts=PTS-STARTPTS`.
+- **fit to canvas:** `"cover"` = `scale=W:H:force_original_aspect_ratio=increase,crop=W:H`;
+  `"contain"` = `...decrease,pad=...` (see [ffmpeg recipes](ffmpeg-recipes.md)).
+- **sequence:** `concat` back-to-back; `overlay=enable='between(t,P,P+D)'` for timed overlays.
+- **crossfade:** `xfade=transition=fade:duration=0.5:offset=5.0`; audio `acrossfade`.
+- **text / lower-thirds:** `drawtext=...:enable='between(t,1,4)'`; animate via `x=`/`alpha=` expressions in `t`.
+- **logo:** `overlay=W*0.8:H*0.05`. **captions:** `subtitles=vo.srt`.
+- **audio mix + ducking:** `amix`, `volume`, `sidechaincompress` (music under VO), `afade`.
+- **keyframes:** ffmpeg `t`-expressions (`alpha='if(lt(t,0.4),t/0.4,1)'`) or `zoompan`; for rich curves precompute per-frame values from the `{t,v,ease}` arrays.
+- **output:** `-c:v libx264 -r fps -pix_fmt yuv420p -c:a aac out.mp4`.
+
+`mifi/editly` (MIT) and `Zulko/moviepy` (MIT) are working prior art that this JSON
+shape renders through ffmpeg without any GPL engine.
+
+### maggie_video.py compile
+
+`maggie_video.py compile --spec timeline.json` compiles this model into one ffmpeg
+`filter_complex` command (printed; run with `--run`). Supported today: a main video
+track of clips (video/image) fit `cover`/`contain` to the canvas, hard-cut `concat`
+or sequential `crossfade` (from `transitions`), image/text/caption overlays with
+`position`+`duration` timing and `rect` placement, and an `audio[]` mix with
+per-track `position`/`gain` plus `loudnorm`. Output is bounded to the computed video
+duration and uses the shared web-safe profile. Not compiled yet (emitted as
+`# NOTE:` lines): keyframes, ken-burns, and sidechain ducking - set static values or
+use a programmatic engine for those.
+
+```bash
+maggie tool maggie_video.py compile --spec timeline.json          # print the command
+maggie tool maggie_video.py --run compile --spec timeline.json    # render it
+```
+
+## Optional higher-fidelity backend: melt (GPL, external)
+
+The same model can emit **MLT XML** and render with
+`melt project.mlt -consumer avformat:out.mp4` - keyframes map to MLT's
+`frame=value` animation strings and `composite`/`luma` transitions. Treat `melt` as
+an optional external tool behind a provider-adapter boundary (see
+[provider adapter contract](provider-adapter-contract.md)); it is GPL, invoked at
+arm's length, never linked or vendored.
+
+## What belongs where
+
+- **This reference:** the data model, the crosswalk, the ffmpeg compilation map, the
+  keyframe/ease vocabulary, the licensing note - stable and engine-neutral.
+- **`maggie-video` skill:** channel presets, caption/CTA safe-areas, the operational
+  ffmpeg command layer (via `maggie_video.py`), and tool wiring.

package/bundled-skills/catalog.json

@@ -145,6 +145,10 @@
     {
       "name": "maggie-template",
       "description": "Discover, recommend, inspect, and apply verified Astro homepage templates from the Maggie marketplace. Use when a user wants to start a site from a selected template, compare available designs, or choose a visual direction before maggie-clone or maggie-design."
+    },
+    {
+      "name": "maggie-video",
+      "description": "Produce and process marketing video - render a composition to MP4/GIF/WebM, assemble clips/images/text/captions/audio on a timeline, cut to channel aspects (reel/square/youtube), burn in captions, normalize loudness, watermark, transcode, and make social cuts. Engine-neutral over the renderer (ffmpeg for assembly/transcode, a programmatic engine for code-drawn animation). Use when the user wants to make, edit, cut, caption, resize, or export a video for marketing."
     }
   ]
 }

package/bundled-skills/maggie-video/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: maggie-video
+description: Produce and process marketing video - render a composition to MP4/GIF/WebM, assemble clips/images/text/captions/audio on a timeline, cut to channel aspects (reel/square/youtube), burn in captions, normalize loudness, watermark, transcode, and make social cuts. Engine-neutral over the renderer (ffmpeg for assembly/transcode, a programmatic engine for code-drawn animation). Use when the user wants to make, edit, cut, caption, resize, or export a video for marketing.
+metadata:
+  version: 0.1.1
+---
+
+# Maggie Video
+
+The video production lane: turn footage, images, text, captions and audio into a
+finished marketing video, and process existing video (cut, caption, resize,
+transcode, watermark, normalize). It is **engine-neutral** - the ffmpeg binary does
+assembly and transcode; a programmatic engine does code-drawn animation; it never
+links a GPL library or vendors GPL code.
+
+This complements [`maggie-design-motion`](../maggie-design-motion/SKILL.md), which
+animates a *static design* into a showcase and already implements the deterministic
+render-then-encode core (its Part C). `maggie-video` is broader: real footage,
+clip assembly, captions, platform cuts, and transcode. Finished videos publish
+through [`maggie-social-share`](../maggie-social-share/SKILL.md).
+
+Follow the [Maggie Memory Hook](../../references/memory-hook.md) at invocation and
+completion.
+
+## When to use
+
+- Cut, caption, resize, watermark, transcode, or normalize an existing video.
+- Assemble clips/images/text/VO/music into a video from a declarative spec.
+- Produce a data-driven or code-drawn animation as video (charts, kinetic type).
+- Make platform-correct social cuts (9:16 reel, 1:1 feed, 16:9 YouTube).
+
+## Pick the route
+
+- **Assembly / transcode / captions / resize of real footage** → the **ffmpeg
+  layer** directly. Every command is in [ffmpeg recipes](../../references/ffmpeg-recipes.md)
+  and generated by the CLI below.
+- **Declarative multi-clip composition** (clips + overlays + transitions + audio) →
+  author the [timeline model](../../references/video-timeline-model.md) JSON and run
+  `maggie_video.py compile --spec timeline.json`, which compiles it to one ffmpeg
+  `filter_complex` command (main track fit + concat/crossfade, image/text/caption
+  overlays with timing, audio mix + loudnorm; keyframes/ken-burns/ducking are flagged
+  as notes). For higher fidelity, emit MLT XML and render with `melt` as an optional
+  external GPL tool behind an adapter.
+- **Code-drawn animation** (kinetic type, charts, N data-driven variants) →
+  [programmatic video](../../references/programmatic-video.md): use **Revideo**
+  (MIT, headless, parameterized) by default; **CCapture** for an existing canvas
+  loop; **Remotion only as an option the end user licenses** (its license requires
+  a paid Company License for for-profit orgs over 3 employees - no hard dependency).
+- **Animating an existing rendered page/design** → stay in `maggie-design-motion`
+  Part C; do not reinvent it here.
+
+## The ffmpeg CLI
+
+`maggie_video.py` generates the correct ffmpeg command (printed, so it is reviewable
+and loggable) and runs it with `--run` when `ffmpeg` is on PATH:
+
+```bash
+maggie tool maggie_video.py social --input in.mp4 --output reel.mp4 --aspect reel        # 9:16, pad
+maggie tool maggie_video.py social --input in.mp4 --output feed.mp4 --aspect square --mode crop
+maggie tool maggie_video.py gif --input in.mp4 --output out.gif --fps 15 --width 480
+maggie tool maggie_video.py subtitle --input in.mp4 --srt vo.srt --output sub.mp4        # burn in
+maggie tool maggie_video.py loudnorm --input in.mp4 --output norm.mp4 --target -14       # social loudness
+maggie tool maggie_video.py overlay --input in.mp4 --logo logo.png --output branded.mp4
+maggie tool maggie_video.py trim --input in.mp4 --output cut.mp4 --start 5 --duration 10
+maggie tool maggie_video.py concat --inputs a.mp4 b.mp4 --output all.mp4 --reencode
+maggie tool maggie_video.py thumb --input in.mp4 --output poster.jpg --at 00:00:03
+maggie tool maggie_video.py compile --spec timeline.json                                 # declarative -> one command
+maggie tool maggie_video.py --run encode --input in.mov --output out.mp4                 # actually runs
+maggie tool maggie_video.py presets
+```
+
+Subcommands: `encode` (web-safe MP4 / VP9 WebM), `gif`, `trim`, `concat`, `social`,
+`overlay`, `subtitle` (burn or soft-mux), `loudnorm`, `thumb`, `compile` (timeline
+JSON -> ffmpeg), `presets`. `--run` (before the subcommand) executes when ffmpeg is
+on PATH; otherwise the command is printed for review.
+
+## Channel presets and safe areas
+
+- **9:16** (1080x1920) - Reels / Shorts / TikTok / Stories, <= 60s for feeds.
+- **1:1** (1080x1080) - feed posts.
+- **16:9** (1920x1080) - YouTube / landscape.
+- Keep captions and the CTA inside a safe area (roughly 10% margin top/bottom, more
+  at the bottom for platform UI). Logo in a fixed corner (see `overlay`). Default
+  loudness **-14 LUFS**. Prefer **crop (fill)** for full-bleed footage, **pad
+  (letterbox)** when the whole frame must be visible.
+
+## Output profile (shared with maggie-design-motion)
+
+H.264 high / `yuv420p` / `+faststart` / AAC 128k, even dimensions; GIF via
+`palettegen`+`paletteuse` (lanczos). Always force `-pix_fmt yuv420p` and `setsar=1`.
+
+## Quality bar
+
+- Output plays everywhere (yuv420p, faststart, even dimensions); aspect matches the
+  target channel with no distortion.
+- Captions are inside the safe area and readable; loudness normalized to target.
+- Every ffmpeg command is printed/logged before (or instead of) running.
+- No GPL library linked or vendored; ffmpeg/melt invoked at arm's length.
+
+## Guardrails
+
+- Rendering is a **local CPU/GPU/time cost**, not a paid API; flag long renders.
+  If any **hosted or LLM video generation** is wired in (e.g. a Q-category model),
+  the global BYOK rule (OpenRouter `provider.order` + `allow_fallbacks:false` +
+  explicit `max_tokens`) and the spend-first rule apply - state cost first.
+- Never claim a render ran unless `--run` executed and produced the file.
+- Licensing: adopt ideas/shape, not GPL code; invoke the `ffmpeg` binary (and
+  optionally `melt`) rather than linking libav. **Remotion** is reference-only (not
+  a free license for a commercial product).
+- Do not fabricate captions/transcripts; generate them from the real audio (see
+  the R-category caption tools, e.g. whisper) and let a human review.
+- Publishing a video is a separate approved step via `maggie-social-share`.
+
+## Related skills
+
+- `maggie-design-motion` - animate a static design into a showcase (shares the
+  render-then-encode core).
+- `maggie-social-share` - publish the finished video as platform-native posts.
+- `maggie-spirit` - brand marks/avatars that can appear in a video.
+- `maggie media generate` - AI image/video generation for b-roll (Q-category).
+
+## Boundaries
+
+- Engine-neutral production + processing; the data model and recipes live in the
+  references, channel presets and the ffmpeg layer live here. A human approves
+  publishing and any paid generation.
+
+## Credits
+
+Distilled (concepts and command shapes, not code) from the reference library's
+N-category video projects: moviepy, editly, auto-editor (MIT/Unlicense) for the
+ffmpeg command layer and timeline spec; Motion Canvas, Revideo, CCapture (MIT) for
+the programmatic render pattern; MLT / Shotcut / Kdenlive / OpenShot / Olive
+(LGPL/GPL) for the timeline data-model shape only; ffmpeg (LGPL/GPL) and HandBrake
+(GPL) invoked at arm's length.

package/bundled-tools/clis/maggie_video.py

@@ -0,0 +1,399 @@
+#!/usr/bin/env python3
+"""maggie_video - generate correct ffmpeg commands for marketing video tasks.
+
+A recipe generator distilled from moviepy, editly, auto-editor, FFmpeg and
+HandBrake (see references/ffmpeg-recipes.md). Each subcommand prints the exact
+ffmpeg command (so it is reviewable and loggable) and runs it only with --run,
+and only when `ffmpeg` is on PATH. It shells out to the ffmpeg binary (arm's-length
+LGPL/GPL use); it links no libav and vendors no GPL code. Output is always forced
+to a web-safe, platform-correct profile.
+
+Subcommands: encode, gif, trim, concat, social, overlay, subtitle, loudnorm,
+thumb, compile, presets.
+"""
+import argparse
+import json
+import shlex
+import shutil
+import subprocess
+import sys
+
+PREFIX = ["ffmpeg", "-y", "-hide_banner", "-loglevel", "error"]
+MP4_OUT = ["-c:v", "libx264", "-profile:v", "high", "-pix_fmt", "yuv420p",
+           "-movflags", "+faststart"]
+# channel aspect presets (name -> WxH)
+SOCIAL = {"reel": (1080, 1920), "story": (1080, 1920), "tiktok": (1080, 1920),
+          "square": (1080, 1080), "feed": (1080, 1080),
+          "youtube": (1920, 1080), "landscape": (1920, 1080)}
+OVERLAY_POS = {"br": "W-w-{m}:H-h-{m}", "bl": "{m}:H-h-{m}",
+               "tr": "W-w-{m}:{m}", "tl": "{m}:{m}"}
+
+
+def emit(args, run):
+    printable = " ".join(shlex.quote(a) for a in args)
+    print(printable)
+    if not run:
+        return 0
+    if not shutil.which("ffmpeg"):
+        sys.stderr.write("ffmpeg not found on PATH; printed the command only.\n")
+        return 3
+    return subprocess.run(args).returncode
+
+
+def c_encode(a):
+    out = ["-crf", str(a.crf), "-preset", a.preset]
+    if a.vcodec == "vp9":
+        v = ["-c:v", "libvpx-vp9", "-crf", str(a.crf), "-b:v", "0", "-row-mt", "1",
+             "-pix_fmt", "yuv420p", "-c:a", "libopus", "-b:a", "128k"]
+        return emit(PREFIX + ["-i", a.input] + v + [a.output], a.run)
+    cmd = PREFIX + ["-i", a.input, "-c:v", "libx264", "-profile:v", "high",
+                    "-preset", a.preset, "-crf", str(a.crf), "-pix_fmt", "yuv420p",
+                    "-c:a", "aac", "-b:a", "128k", "-movflags", "+faststart", a.output]
+    return emit(cmd, a.run)
+
+
+def c_gif(a):
+    vf = (f"fps={a.fps},scale={a.width}:-1:flags=lanczos,split[s0][s1];"
+          f"[s0]palettegen[p];[s1][p]paletteuse")
+    return emit(PREFIX + ["-i", a.input, "-vf", vf, "-loop", "0", a.output], a.run)
+
+
+def c_trim(a):
+    dur = ["-t", str(a.duration)] if a.duration else (["-to", str(a.end)] if a.end else [])
+    if a.reencode:
+        cmd = PREFIX + ["-ss", str(a.start), "-i", a.input] + dur + \
+            ["-c:v", "libx264", "-preset", "medium", "-crf", "20", "-pix_fmt",
+             "yuv420p", "-c:a", "aac", "-movflags", "+faststart", a.output]
+    else:
+        cmd = PREFIX + ["-ss", str(a.start), "-i", a.input] + dur + \
+            ["-map", "0", "-c", "copy", "-avoid_negative_ts", "make_zero", a.output]
+    return emit(cmd, a.run)
+
+
+def c_concat(a):
+    if a.reencode or len(a.inputs) < 1:
+        ins = []
+        for p in a.inputs:
+            ins += ["-i", p]
+        n = len(a.inputs)
+        streams = "".join(f"[{i}:v][{i}:a]" for i in range(n))
+        fc = f"{streams}concat=n={n}:v=1:a=1[v][a]"
+        cmd = PREFIX + ins + ["-filter_complex", fc, "-map", "[v]", "-map", "[a]"] + \
+            ["-c:v", "libx264", "-crf", "20", "-pix_fmt", "yuv420p",
+             "-c:a", "aac", "-movflags", "+faststart", a.output]
+        return emit(cmd, a.run)
+    # fast path: a concat list file (same codec). Print how to build it.
+    print("# same-codec fast concat: write a list file, then run ffmpeg:")
+    print("#   printf \"file '%s'\\n\" " + " ".join(shlex.quote(p) for p in a.inputs) + " > concat.txt")
+    return emit(PREFIX + ["-f", "concat", "-safe", "0", "-i", "concat.txt",
+                          "-c", "copy", a.output], a.run)
+
+
+def c_social(a):
+    w, h = SOCIAL[a.aspect]
+    if a.mode == "crop":
+        vf = (f"scale={w}:{h}:force_original_aspect_ratio=increase,"
+              f"crop={w}:{h},setsar=1")
+    else:
+        vf = (f"scale={w}:{h}:force_original_aspect_ratio=decrease,"
+              f"pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color={a.color},setsar=1")
+    cmd = PREFIX + ["-i", a.input, "-vf", vf, "-crf", str(a.crf)] + MP4_OUT + \
+        ["-c:a", "aac", "-b:a", "128k", a.output]
+    return emit(cmd, a.run)
+
+
+def c_overlay(a):
+    pos = OVERLAY_POS[a.position].format(m=a.margin)
+    fc = (f"[1][0]scale2ref=w=oh*mdar:h=ih*{a.scale}[logo][base];"
+          f"[base][logo]overlay={pos}")
+    cmd = PREFIX + ["-i", a.input, "-i", a.logo, "-filter_complex", fc,
+                    "-c:a", "copy", "-c:v", "libx264", "-crf", "20",
+                    "-pix_fmt", "yuv420p", "-movflags", "+faststart", a.output]
+    return emit(cmd, a.run)
+
+
+def c_subtitle(a):
+    if a.soft:
+        cmd = PREFIX + ["-i", a.input, "-i", a.srt, "-c", "copy", "-c:s",
+                        "mov_text", "-metadata:s:s:0", f"language={a.lang}", a.output]
+    else:
+        style = f"force_style='FontName={a.font},FontSize={a.size},BorderStyle=3'"
+        cmd = PREFIX + ["-i", a.input, "-vf", f"subtitles={a.srt}:{style}",
+                        "-c:v", "libx264", "-crf", "20", "-pix_fmt", "yuv420p",
+                        "-c:a", "copy", a.output]
+    return emit(cmd, a.run)
+
+
+def c_loudnorm(a):
+    cmd = PREFIX + ["-i", a.input, "-af",
+                    f"loudnorm=I={a.target}:TP=-1.5:LRA=11",
+                    "-c:v", "copy", "-c:a", "aac", "-b:a", "128k", a.output]
+    print("# quick single-pass loudnorm (I=-14 LUFS = social/YouTube target).")
+    print("# for accuracy, measure first: ffmpeg -i IN -af loudnorm=...:print_format=json -f null -")
+    return emit(cmd, a.run)
+
+
+def c_thumb(a):
+    if a.smart:
+        cmd = PREFIX + ["-i", a.input, "-vf", "thumbnail,scale=1280:-1",
+                        "-frames:v", "1", a.output]
+    else:
+        cmd = PREFIX + ["-ss", str(a.at), "-i", a.input, "-frames:v", "1",
+                        "-q:v", "2", a.output]
+    return emit(cmd, a.run)
+
+
+def _fit(w, h, mode, fps, color="black"):
+    """A filter chain that fits a source to WxH and normalizes it for concat/xfade."""
+    if mode == "contain":
+        scale = (f"scale={w}:{h}:force_original_aspect_ratio=decrease,"
+                 f"pad={w}:{h}:(ow-iw)/2:(oh-ih)/2:color={color}")
+    else:  # cover (fill)
+        scale = f"scale={w}:{h}:force_original_aspect_ratio=increase,crop={w}:{h}"
+    return f"{scale},fps={fps},format=yuv420p,setsar=1"
+
+
+def _clip_dur(clip, default):
+    if isinstance(clip.get("duration"), (int, float)):
+        return float(clip["duration"])
+    if isinstance(clip.get("start"), (int, float)) and isinstance(clip.get("end"), (int, float)):
+        return float(clip["end"]) - float(clip["start"])
+    return float(default)
+
+
+def _px(val, total):
+    """Resolve '80%' / 0.8 / 120 against a total dimension to an int pixel value."""
+    if isinstance(val, str) and val.strip().endswith("%"):
+        return int(round(float(val.strip()[:-1]) / 100.0 * total))
+    v = float(val)
+    return int(round(v * total)) if 0 < v <= 1 else int(round(v))
+
+
+def c_compile(a):
+    """Compile a timeline-model JSON (references/video-timeline-model.md) into one
+    ffmpeg command. Supports: a main video track of clips (video/image) fit to the
+    canvas, hard-cut concat or sequential crossfade, image/text/caption overlays
+    with timing, and an audio mix with per-track gain + optional loudnorm. Keyframes,
+    ken-burns, and sidechain ducking are not compiled yet (flagged as notes)."""
+    with open(a.spec, encoding="utf-8") as fh:
+        spec = json.load(fh)
+    out = spec.get("output", {})
+    W, H = int(out.get("width", 1080)), int(out.get("height", 1920))
+    FPS = int(out.get("fps", 30))
+    outfile = a.output or out.get("path") or "out.mp4"
+    assets = spec.get("assets", {})
+    defaults = spec.get("defaults", {})
+    def_dur = defaults.get("clipDuration", 4)
+    notes, inputs, filters = [], [], []
+
+    def add_input(opts, path):
+        inputs.extend(opts + ["-i", path])
+        return len([x for x in inputs if x == "-i"]) - 1  # index of this input
+
+    tracks = spec.get("tracks", [])
+    vtracks = [t for t in tracks if t.get("kind", "video") == "video"]
+    if not vtracks:
+        raise SystemExit("spec needs at least one video track")
+    main = sorted(vtracks, key=lambda t: t.get("z", 0))[0]
+    overlays = [t for t in sorted(vtracks, key=lambda t: t.get("z", 0))[1:]]
+
+    # --- main track: build each clip segment, then concat or crossfade ---
+    segs, durs = [], []
+    for i, clip in enumerate(main.get("clips", [])):
+        aid = clip.get("asset")
+        asset = assets.get(aid, {})
+        dur = _clip_dur(clip, def_dur)
+        fit = clip.get("fit", "cover")
+        if asset.get("type") == "image" or clip.get("type") == "image":
+            idx = add_input(["-loop", "1", "-t", f"{dur}"], asset.get("src", clip.get("src", "")))
+            filters.append(f"[{idx}:v]{_fit(W, H, fit, FPS)}[v{i}]")
+        elif asset.get("type") == "video":
+            idx = add_input([], asset.get("src", ""))
+            s = clip.get("start", 0)
+            trim = f"trim=start={s}:end={s + dur},setpts=PTS-STARTPTS,"
+            filters.append(f"[{idx}:v]{trim}{_fit(W, H, fit, FPS)}[v{i}]")
+        else:
+            notes.append(f"clip {i}: unsupported type (need asset of type image/video)")
+            continue
+        segs.append(f"[v{i}]")
+        durs.append(dur)
+
+    transitions = spec.get("transitions", [])
+    tdur0 = float(transitions[0].get("duration", 0.5)) if transitions else 0.0
+    video_dur = (sum(durs) - tdur0 * (len(segs) - 1)) if (transitions and len(segs) > 1) else sum(durs)
+    if len(segs) == 1:
+        filters.append(f"{segs[0]}copy[vbase]")
+    elif transitions:
+        # sequential crossfade; offset = cumulative shown time - transition dur
+        tdur = float(transitions[0].get("duration", 0.5))
+        tname = transitions[0].get("type", "fade")
+        if tname in ("crossfade",):
+            tname = "fade"
+        prev, off = segs[0], 0.0
+        for i in range(1, len(segs)):
+            off += durs[i - 1] - tdur
+            label = "[vbase]" if i == len(segs) - 1 else f"[vx{i}]"
+            filters.append(f"{prev}{segs[i]}xfade=transition={tname}:duration={tdur}:offset={off}{label}")
+            prev = label
+        notes.append(f"crossfade '{tname}' {tdur}s between all clips (first transition's settings)")
+    else:
+        filters.append(f"{''.join(segs)}concat=n={len(segs)}:v=1:a=0[vbase]")
+
+    # --- overlays (image / text / captions) ---
+    cur = "[vbase]"
+    step = 0
+    for t in overlays:
+        for clip in t.get("clips", []):
+            nxt = f"[vo{step}]"
+            pos = float(clip.get("position", 0))
+            dur = _clip_dur(clip, def_dur)
+            en = f"enable='between(t,{pos},{pos + dur})'"
+            if clip.get("effects"):
+                notes.append("overlay effects/keyframes (opacity/zoom) not compiled; shown at full opacity")
+            ctype = clip.get("type")
+            if ctype == "text":
+                st = clip.get("style", {})
+                rect = clip.get("rect", {})
+                x = _px(rect.get("x", "10%"), W)
+                y = _px(rect.get("y", "80%"), H)
+                txt = str(clip.get("text", "")).replace(":", r"\:").replace("'", "’")
+                box = f":box=1:boxcolor={st['box']}:boxborderw=12" if st.get("box") else ""
+                dt = (f"drawtext=text='{txt}':x={x}:y={y}:fontsize={st.get('size',48)}:"
+                      f"fontcolor={st.get('color','#FFFFFF')}{box}:{en}")
+                filters.append(f"{cur}{dt}{nxt}")
+            elif ctype == "captions":
+                src = clip.get("src", "")
+                filters.append(f"{cur}subtitles={src}{nxt}")
+            elif assets.get(clip.get("asset"), {}).get("type") == "image":
+                asset = assets[clip["asset"]]
+                rect = clip.get("rect", {})
+                ow = _px(rect.get("w", "15%"), W)
+                idx = add_input(["-loop", "1"], asset.get("src", ""))
+                filters.append(f"[{idx}:v]scale={ow}:-1[ov{step}]")
+                x = _px(rect.get("x", "80%"), W)
+                y = _px(rect.get("y", "5%"), H)
+                filters.append(f"{cur}[ov{step}]overlay={x}:{y}:{en}:eof_action=pass{nxt}")
+            else:
+                notes.append(f"overlay clip of type {ctype!r} not compiled")
+                continue
+            cur = nxt
+            step += 1
+    filters.append(f"{cur}format=yuv420p[vout]")
+
+    # --- audio: mix audio[] tracks with gain + optional loudnorm ---
+    aud = spec.get("audio", [])
+    alabels = []
+    for i, tr in enumerate(aud):
+        asset = assets.get(tr.get("asset"), {})
+        if not asset.get("src"):
+            continue
+        idx = add_input([], asset["src"])
+        chain = f"[{idx}:a]"
+        pos = float(tr.get("position", 0))
+        if pos > 0:
+            ms = int(pos * 1000)
+            chain += f"adelay={ms}|{ms},"
+        gain = tr.get("gain", 0)
+        if gain:
+            chain += f"volume={gain}dB,"
+        if tr.get("ducking"):
+            notes.append("audio ducking (sidechain) not compiled; set music gain lower instead")
+        chain = chain.rstrip(",") + f"[a{i}]"
+        filters.append(chain)
+        alabels.append(f"[a{i}]")
+    have_audio = bool(alabels)
+    if have_audio:
+        if len(alabels) == 1:
+            filters.append(f"{alabels[0]}aresample=async=1[amix]")
+        else:
+            filters.append(f"{''.join(alabels)}amix=inputs={len(alabels)}:duration=longest[amix]")
+        norm = next((t for t in aud if isinstance(t, dict)), {})  # master normalize lives on audio? use output
+        tgt = (spec.get("audio_normalize") or {}).get("I", -14)
+        filters.append(f"[amix]loudnorm=I={tgt}:TP=-1.5:LRA=11[aout]")
+
+    fc = ";".join(filters)
+    cmd = PREFIX + inputs + ["-filter_complex", fc, "-map", "[vout]"]
+    if have_audio:
+        cmd += ["-map", "[aout]", "-shortest", "-c:a", "aac", "-b:a", "128k"]
+    cmd += ["-t", f"{round(video_dur, 3)}", "-r", str(FPS)] + MP4_OUT + [outfile]
+    for n in notes:
+        print(f"# NOTE: {n}")
+    return emit(cmd, a.run)
+
+
+def c_presets(a):
+    print("Channel aspect presets (use with `social --aspect <name>`):")
+    for name, (w, h) in SOCIAL.items():
+        print(f"  {name:<10} {w}x{h}")
+    print("\nOutput profile: H.264 high / yuv420p / +faststart / AAC 128k (web-safe).")
+    print("GIF: palettegen+paletteuse, lanczos. Loudness target: -14 LUFS.")
+    return 0
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser(prog="maggie_video", description=__doc__,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    ap.add_argument("--run", action="store_true", help="execute (needs ffmpeg on PATH); default prints only")
+    sub = ap.add_subparsers(dest="cmd", required=True)
+
+    e = sub.add_parser("encode", help="transcode to a web-safe MP4 (or VP9 WebM)")
+    e.add_argument("--input", required=True); e.add_argument("--output", required=True)
+    e.add_argument("--crf", type=int, default=20); e.add_argument("--preset", default="medium")
+    e.add_argument("--vcodec", choices=["h264", "vp9"], default="h264"); e.set_defaults(fn=c_encode)
+
+    g = sub.add_parser("gif", help="high-quality palette GIF")
+    g.add_argument("--input", required=True); g.add_argument("--output", required=True)
+    g.add_argument("--fps", type=int, default=15); g.add_argument("--width", type=int, default=480)
+    g.set_defaults(fn=c_gif)
+
+    t = sub.add_parser("trim", help="cut a segment (copy by default, --reencode for frame-accurate)")
+    t.add_argument("--input", required=True); t.add_argument("--output", required=True)
+    t.add_argument("--start", required=True); t.add_argument("--duration"); t.add_argument("--end")
+    t.add_argument("--reencode", action="store_true"); t.set_defaults(fn=c_trim)
+
+    cc = sub.add_parser("concat", help="join clips (fast same-codec, or --reencode)")
+    cc.add_argument("--inputs", nargs="+", required=True); cc.add_argument("--output", required=True)
+    cc.add_argument("--reencode", action="store_true"); cc.set_defaults(fn=c_concat)
+
+    s = sub.add_parser("social", help="scale+pad or crop to a channel aspect")
+    s.add_argument("--input", required=True); s.add_argument("--output", required=True)
+    s.add_argument("--aspect", choices=list(SOCIAL), required=True)
+    s.add_argument("--mode", choices=["pad", "crop"], default="pad")
+    s.add_argument("--color", default="black"); s.add_argument("--crf", type=int, default=20)
+    s.set_defaults(fn=c_social)
+
+    o = sub.add_parser("overlay", help="overlay a logo/watermark")
+    o.add_argument("--input", required=True); o.add_argument("--logo", required=True)
+    o.add_argument("--output", required=True)
+    o.add_argument("--position", choices=list(OVERLAY_POS), default="br")
+    o.add_argument("--margin", type=int, default=24); o.add_argument("--scale", default="0.12")
+    o.set_defaults(fn=c_overlay)
+
+    sb = sub.add_parser("subtitle", help="burn in (default) or soft-mux an SRT")
+    sb.add_argument("--input", required=True); sb.add_argument("--srt", required=True)
+    sb.add_argument("--output", required=True); sb.add_argument("--soft", action="store_true")
+    sb.add_argument("--font", default="Inter"); sb.add_argument("--size", type=int, default=24)
+    sb.add_argument("--lang", default="eng"); sb.set_defaults(fn=c_subtitle)
+
+    ln = sub.add_parser("loudnorm", help="normalize loudness to a target LUFS")
+    ln.add_argument("--input", required=True); ln.add_argument("--output", required=True)
+    ln.add_argument("--target", default="-14"); ln.set_defaults(fn=c_loudnorm)
+
+    th = sub.add_parser("thumb", help="extract a poster/thumbnail frame")
+    th.add_argument("--input", required=True); th.add_argument("--output", required=True)
+    th.add_argument("--at", default="00:00:03"); th.add_argument("--smart", action="store_true")
+    th.set_defaults(fn=c_thumb)
+
+    cp = sub.add_parser("compile", help="compile a timeline-model JSON into one ffmpeg command")
+    cp.add_argument("--spec", required=True, help="timeline JSON (video-timeline-model.md)")
+    cp.add_argument("--output", help="override the output path from the spec")
+    cp.set_defaults(fn=c_compile)
+
+    sub.add_parser("presets", help="list channel aspect presets").set_defaults(fn=c_presets)
+
+    a = ap.parse_args(argv)
+    raise SystemExit(a.fn(a))
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topy-ai/maggie",
-  "version": "0.8.7",
+  "version": "0.8.9",
   "description": "Install and manage Maggie Skills for AI coding agents",
   "license": "MIT",
   "type": "module",

package/references/ffmpeg-recipes.md

@@ -0,0 +1,126 @@
+# ffmpeg recipes
+
+The distilled, correct ffmpeg command layer for marketing video, used by
+`maggie-video` (and shared with `maggie-design-motion`'s export). These are the
+commands `maggie_video.py` generates; this reference explains each so they can be
+adapted. Distilled from moviepy, editly, auto-editor, FFmpeg and HandBrake (see
+the design reference library category N). We **invoke the `ffmpeg` binary** (not
+link libav), so this stays license-clean; most ffmpeg builds bundle x264/x265 and
+are GPL binaries - fine to invoke, do not vendor a GPL build into a package.
+
+Common prefix: `ffmpeg -y -hide_banner -loglevel error`. Always force
+`-pix_fmt yuv420p` and `setsar=1` on output for universal playback (moviepy has a
+latent `yuva420p` typo - do not copy it).
+
+## Encode (web-safe MP4)
+
+```bash
+ffmpeg -y -i IN -c:v libx264 -profile:v high -preset medium -crf 20 \
+  -pix_fmt yuv420p -c:a aac -b:a 128k -movflags +faststart OUT.mp4
+```
+
+`+faststart` moves the moov atom to the front for web streaming. CRF 18-23 (lower =
+larger/better). WebM (VP9): `-c:v libvpx-vp9 -crf 32 -b:v 0 -row-mt 1 -pix_fmt
+yuv420p -c:a libopus -b:a 128k`.
+
+## High-quality GIF (one-pass palette)
+
+```bash
+ffmpeg -y -i IN -vf "fps=15,scale=480:-1:flags=lanczos,split[s0][s1];\
+[s0]palettegen[p];[s1][p]paletteuse" -loop 0 OUT.gif
+```
+
+Scale/fps down first to keep size sane; the palette pass avoids banding. Keep bayer
+dithering (`paletteuse=dither=bayer:bayer_scale=4`) when a photo is in frame.
+
+## Trim
+
+```bash
+# fast, no re-encode (cuts at the nearest keyframe)
+ffmpeg -y -ss START -i IN -t DURATION -map 0 -c copy -avoid_negative_ts make_zero OUT.mp4
+# frame-accurate: drop -c copy and re-encode with the MP4 recipe
+```
+
+## Concat
+
+```bash
+# same codec (fast): concat.txt has lines  file '/abs/clip1.mp4'
+ffmpeg -y -f concat -safe 0 -i concat.txt -c copy OUT.mp4
+# mixed sources (re-encode via filter)
+ffmpeg -y -i a.mp4 -i b.mp4 -filter_complex \
+  "[0:v][0:a][1:v][1:a]concat=n=2:v=1:a=1[v][a]" -map "[v]" -map "[a]" \
+  -c:v libx264 -crf 20 -pix_fmt yuv420p -movflags +faststart OUT.mp4
+```
+
+## Scale + pad or crop to a channel aspect
+
+```bash
+# 9:16 reel (1080x1920); use 1080x1080 square or 1920x1080 landscape likewise
+# pad (letterbox, no distortion):
+ffmpeg -y -i IN -vf "scale=1080:1920:force_original_aspect_ratio=decrease,\
+pad=1080:1920:(ow-iw)/2:(oh-ih)/2:color=black,setsar=1" \
+  -c:v libx264 -crf 20 -pix_fmt yuv420p -movflags +faststart OUT.mp4
+# crop (fill): force_original_aspect_ratio=increase,crop=1080:1920,setsar=1
+```
+
+## Overlay / watermark (logo bottom-right, scaled to 12% height, 24px margin)
+
+```bash
+ffmpeg -y -i IN -i logo.png -filter_complex \
+  "[1][0]scale2ref=w=oh*mdar:h=ih*0.12[logo][base];[base][logo]overlay=W-w-24:H-h-24" \
+  -c:a copy -c:v libx264 -crf 20 -pix_fmt yuv420p OUT.mp4
+```
+
+## Subtitles
+
+```bash
+# burn in (hardsub) from SRT
+ffmpeg -y -i IN -vf "subtitles=subs.srt:force_style='FontName=Inter,FontSize=24,BorderStyle=3'" \
+  -c:v libx264 -crf 20 -pix_fmt yuv420p -c:a copy OUT.mp4
+# soft-mux (toggleable track, MP4)
+ffmpeg -y -i IN -i subs.srt -c copy -c:s mov_text -metadata:s:s:0 language=eng OUT.mp4
+```
+
+## Loudness normalize (EBU R128; -14 LUFS = social/YouTube target)
+
+```bash
+# quick single pass
+ffmpeg -y -i IN -af loudnorm=I=-14:TP=-1.5:LRA=11 -c:v copy -c:a aac -b:a 128k OUT.mp4
+# accurate two pass: measure first (reads JSON from stderr), then apply measured_* values
+ffmpeg -i IN -af loudnorm=I=-14:TP=-1.5:LRA=11:print_format=json -f null -
+```
+
+editly's cheaper alternative is `dynaudnorm=g=5:maxgain=30`.
+
+## Thumbnail / poster
+
+```bash
+ffmpeg -y -ss 00:00:03 -i IN -frames:v 1 -q:v 2 OUT.jpg       # at a timestamp
+ffmpeg -y -i IN -vf "thumbnail,scale=1280:-1" -frames:v 1 OUT.jpg  # most representative frame
+```
+
+## Silence auto-cut (auto-editor's idea, via the CLI)
+
+```bash
+ffmpeg -i IN -af silencedetect=noise=-30dB:d=0.3 -f null -   # detect ranges
+# then build a select/concat of the kept ranges (pad each ~0.2s)
+```
+
+## Transitions (between two clips)
+
+`xfade=transition=fade:duration=0.5:offset=5.0` for video and `acrossfade=d=0.5`
+for audio. editly/gl-transitions names (`fade`, `dissolve`, `directional-left`, ...)
+map onto xfade's transition list.
+
+## The CLI
+
+`maggie_video.py` generates every command above (and runs it with `--run` when
+`ffmpeg` is on PATH). It prints the command so it is reviewable and loggable:
+
+```bash
+maggie tool maggie_video.py social --input in.mp4 --output reel.mp4 --aspect reel
+maggie tool maggie_video.py gif --input in.mp4 --output out.gif --fps 15 --width 480
+maggie tool maggie_video.py compile --spec timeline.json   # declarative timeline -> one command
+maggie tool maggie_video.py --run encode --input in.mov --output out.mp4   # actually runs
+maggie tool maggie_video.py presets
+```

package/references/programmatic-video.md

@@ -0,0 +1,80 @@
+# Programmatic video: the render-then-encode pattern
+
+How to produce video from code deterministically, distilled from the leading
+engines (Motion Canvas, Remotion, Revideo, CCapture). Used by `maggie-video`;
+`maggie-design-motion`'s Part C is one concrete implementation of this pattern (the
+DOM/Playwright case). Author your own code from this; adopt engines per the license
+table below.
+
+## The pattern (every engine agrees)
+
+1. **The frame is the unit of truth; the wall clock is the enemy.** Deterministic
+   output comes from driving content by an **absolute frame index or a virtual
+   clock**, never real time. Two techniques:
+   - **Seek by frame:** re-evaluate the scene at frame N (`playback.seek(frame)` in
+     Motion Canvas / Revideo; the current-frame hook in Remotion).
+   - **Fake the clock:** monkeypatch `performance.now`, `requestAnimationFrame`,
+     `Date`, timers and `currentTime`, and advance one fixed step per captured frame
+     (CCapture's `TimeWarp`; Playwright's `page.clock` + `__tick` in Part C).
+2. **Render then encode, decoupled.** Produce frames as fast as the machine allows
+   (not realtime) into a canvas/DOM, then feed an encoder as a separate stage.
+3. **Two encode routes.** (a) **Shell out to ffmpeg** via a pipe - `image2pipe`
+   base64 PNG (Revideo) or `rawvideo`/rgba (Motion Canvas), output
+   `-pix_fmt yuv420p -movflags +faststart` (the exact profile in
+   [ffmpeg recipes](ffmpeg-recipes.md)). (b) **In-browser WebCodecs** (CCapture) -
+   no ffmpeg dependency, hardware-accelerated.
+4. **Headless browser as the frame factory** when the composition is web tech:
+   Revideo = Puppeteer, Remotion = headless Chromium, Part C = Playwright. The page
+   renders; the driver screenshots or reads back each frame.
+5. **One source → preview + render + parameterized batch.** The same scene file
+   drives a live preview and the headless render; **variables/props** turn one
+   template into many videos (N brand variants, localized cuts, per-product reels).
+
+## Composition models
+
+- **React components** (Remotion, Revideo also supports React) - animation driven by
+  the current frame via hooks.
+- **Generator functions** (Motion Canvas, Revideo) - a scene is
+  `makeScene2D(function* (view) { view.add(<Rect/>); yield* all(rect().position.x(100, 1)); yield* waitFor(0.5); })`;
+  timing is the generator's control flow; signals (`createSignal`) provide
+  reactivity. These read cleanly for an LLM to author from a prompt.
+- **Canvas draw calls + a recorder** (CCapture) - any existing rAF canvas loop plus
+  one `capturer.capture(canvas)` line.
+
+## Choosing an engine (decision)
+
+- **Animating an existing rendered page/design** → stay in
+  `maggie-design-motion` Part C (Playwright fake-clock). No new engine needed; this
+  is the common Maggie case (social/hero motion from a design).
+- **Programmatic, data-driven video from scratch** (N variants from brand data,
+  charts, captions) → **Revideo** - MIT, headless-first, parameterizable
+  (`renderVideo({projectFile, variables, settings:{outFile, workers}})`),
+  parallelizable across workers, and it ships a `revideo serve` render endpoint
+  (with `callbackUrl` + SSE progress) for render-as-a-service.
+- **A pure canvas sketch already using rAF** that just needs recording → **CCapture**
+  (WebCodecs, no ffmpeg).
+- **Simple clip assembly / transcode / captions** (not code-drawn animation) → the
+  ffmpeg layer directly ([ffmpeg recipes](ffmpeg-recipes.md)) or the declarative
+  [timeline model](video-timeline-model.md).
+
+## Licenses (critical)
+
+| Engine | License | Adopt? |
+|---|---|---|
+| Motion Canvas | MIT | Yes (generators; editor-driven render) |
+| **Revideo** | MIT | **Yes - recommended programmatic default** (headless, parameterized, parallel) |
+| CCapture.js | MIT | Yes - the WebCodecs recorder / clock-faking reference |
+| video.js | Apache-2.0 | Playback only, not production |
+| **Remotion** | **Remotion License (source-available; paid Company License for for-profit orgs > 3 employees)** | **No hard dependency** - reference/option the end user may license; keep Maggie's default on the MIT stack |
+
+Rendering is a **local CPU/GPU cost** (ffmpeg, a headless browser), not a paid API -
+flag long renders as a time/resource cost, consistent with "local tools only". If
+any hosted or LLM video generation is wired in, the global BYOK + spend-first rules
+apply.
+
+## Shared encode profile
+
+`maggie-video` and `maggie-design-motion` share one profile:
+`libx264 -crf 14-20 -preset slow/medium -pix_fmt yuv420p -movflags +faststart`,
+even dimensions, plus 960px / 800x500 GIF deliverables. For transparent output,
+Revideo uses per-format pixel formats (`yuva420p` WebM, `yuva444p10le` ProRes).

package/references/video-timeline-model.md

@@ -0,0 +1,127 @@
+# Marketing-video timeline model
+
+An engine-neutral, provider-neutral data shape for "assemble these clips, images,
+text, captions and audio into a video", distilled from the open NLEs (MLT /
+Shotcut / Kdenlive, OpenShot, Olive). Used by `maggie-video`. We adopt the **data
+shape** (an uncopyrightable idea), never their code - MLT/Shotcut/Kdenlive/OpenShot/
+Olive are LGPL/GPL. It renders through the **ffmpeg binary** (the common
+denominator, arm's-length), or optionally through `melt` as a GPL external tool.
+
+## Conventions (chosen for LLM-friendliness)
+
+- **Seconds** (floats) at the authoring layer, not frames (OpenShot-style).
+- **`position`** = where a clip starts on the timeline; **`start`/`end`** = the trim
+  within its source (OpenShot's split; MLT calls the trim `in`/`out`).
+- **`z`** = track stacking; higher is on top (mirrors MLT `b_track` over `a_track`,
+  OpenShot's higher layer number).
+- **Keyframes** as `{t, v, ease}` arrays, ease in `linear | hold | smooth | bezier`
+  (MLT's linear/discrete/smooth + OpenShot's Linear/Constant/Bezier).
+- **Relative positions/sizes** (`"80%"`, 0..1) + named anchors, so it is
+  resolution-independent.
+
+## The model
+
+```jsonc
+{
+  "output": { "width": 1080, "height": 1920, "fps": 30, "format": "mp4",
+              "vcodec": "h264", "acodec": "aac", "duration": "auto" },
+  "assets": {
+    "shot1": { "type": "video", "src": "footage/a.mp4" },
+    "product": { "type": "image", "src": "footage/product.jpg" },
+    "logo": { "type": "image", "src": "brand/logo.png" },
+    "vo": { "type": "audio", "src": "audio/vo.mp3" },
+    "music": { "type": "audio", "src": "audio/track.mp3" }
+  },
+  "tracks": [
+    { "id": "main", "kind": "video", "z": 0, "clips": [
+      { "asset": "shot1", "start": 2.0, "end": 7.0, "position": 0.0, "fit": "cover",
+        "effects": [ { "type": "zoom", "keyframes": [
+          {"t":0.0,"v":1.0,"ease":"linear"}, {"t":5.0,"v":1.12,"ease":"smooth"} ] } ] },
+      { "asset": "product", "position": 5.0, "duration": 4.0, "fit": "cover" }
+    ] },
+    { "id": "overlay", "kind": "video", "z": 10, "clips": [
+      { "type": "text", "text": "50% OFF TODAY", "position": 1.0, "duration": 3.0,
+        "style": { "font": "Inter-Bold", "size": 96, "color": "#FFFFFF", "box": "#E11D48", "align": "center" },
+        "rect": { "x": "10%", "y": "70%", "w": "80%", "h": "15%" },
+        "effects": [ { "type": "opacity", "keyframes": [
+          {"t":0,"v":0}, {"t":0.4,"v":1}, {"t":2.6,"v":1}, {"t":3.0,"v":0} ] } ] },
+      { "asset": "logo", "position": 0.0, "duration": 9.0,
+        "rect": { "x": "80%", "y": "5%", "w": "15%", "h": "auto" } },
+      { "type": "captions", "src": "audio/vo.srt" }
+    ] }
+  ],
+  "transitions": [ { "type": "crossfade", "between": ["shot1","product"], "position": 5.0, "duration": 0.5 } ],
+  "audio": [
+    { "asset": "vo", "position": 0.5, "gain": 0 },
+    { "asset": "music", "position": 0.0, "gain": -18, "ducking": { "under": "vo", "amount": -12 },
+      "fade_out": { "at": 8.5, "duration": 0.5 } }
+  ]
+}
+```
+
+Minimal required: `output{width,height,fps,format}`, `assets{}`, one video track of
+`clips[]` each with `asset`+`position`+(`duration` or `start`/`end`). Everything
+else is additive.
+
+## Field crosswalk (stay compatible with any backend)
+
+| this model | MLT | OpenShot | Olive |
+|---|---|---|---|
+| asset `src` | producer `resource` | `files[].path` | footage node |
+| `start`/`end` (trim) | `in`/`out` (frames) | `start`/`end` (sec) | `kMediaInInput` |
+| `position` (timeline) | playlist order + `blank` | `position` (sec) | `ClipBlock.in()` |
+| track / `z` | playlist in multitrack | `layer` number | block in sequence |
+| overlay | `composite` transition | higher layer | graph edge |
+| keyframe ease | `linear`/`discrete`(`|`)/`smooth`(`~`) | Linear/Constant/Bezier | kLinear/kHold/kBezier |
+| time base | frames | seconds | rational |
+
+## Rendering through ffmpeg (default, no GPL linking)
+
+Compile the model to one `filter_complex`:
+
+- **trim / in-out:** `-ss start -t dur -i a.mp4`, or `trim=start=..:end=..,setpts=PTS-STARTPTS`.
+- **fit to canvas:** `"cover"` = `scale=W:H:force_original_aspect_ratio=increase,crop=W:H`;
+  `"contain"` = `...decrease,pad=...` (see [ffmpeg recipes](ffmpeg-recipes.md)).
+- **sequence:** `concat` back-to-back; `overlay=enable='between(t,P,P+D)'` for timed overlays.
+- **crossfade:** `xfade=transition=fade:duration=0.5:offset=5.0`; audio `acrossfade`.
+- **text / lower-thirds:** `drawtext=...:enable='between(t,1,4)'`; animate via `x=`/`alpha=` expressions in `t`.
+- **logo:** `overlay=W*0.8:H*0.05`. **captions:** `subtitles=vo.srt`.
+- **audio mix + ducking:** `amix`, `volume`, `sidechaincompress` (music under VO), `afade`.
+- **keyframes:** ffmpeg `t`-expressions (`alpha='if(lt(t,0.4),t/0.4,1)'`) or `zoompan`; for rich curves precompute per-frame values from the `{t,v,ease}` arrays.
+- **output:** `-c:v libx264 -r fps -pix_fmt yuv420p -c:a aac out.mp4`.
+
+`mifi/editly` (MIT) and `Zulko/moviepy` (MIT) are working prior art that this JSON
+shape renders through ffmpeg without any GPL engine.
+
+### maggie_video.py compile
+
+`maggie_video.py compile --spec timeline.json` compiles this model into one ffmpeg
+`filter_complex` command (printed; run with `--run`). Supported today: a main video
+track of clips (video/image) fit `cover`/`contain` to the canvas, hard-cut `concat`
+or sequential `crossfade` (from `transitions`), image/text/caption overlays with
+`position`+`duration` timing and `rect` placement, and an `audio[]` mix with
+per-track `position`/`gain` plus `loudnorm`. Output is bounded to the computed video
+duration and uses the shared web-safe profile. Not compiled yet (emitted as
+`# NOTE:` lines): keyframes, ken-burns, and sidechain ducking - set static values or
+use a programmatic engine for those.
+
+```bash
+maggie tool maggie_video.py compile --spec timeline.json          # print the command
+maggie tool maggie_video.py --run compile --spec timeline.json    # render it
+```
+
+## Optional higher-fidelity backend: melt (GPL, external)
+
+The same model can emit **MLT XML** and render with
+`melt project.mlt -consumer avformat:out.mp4` - keyframes map to MLT's
+`frame=value` animation strings and `composite`/`luma` transitions. Treat `melt` as
+an optional external tool behind a provider-adapter boundary (see
+[provider adapter contract](provider-adapter-contract.md)); it is GPL, invoked at
+arm's length, never linked or vendored.
+
+## What belongs where
+
+- **This reference:** the data model, the crosswalk, the ffmpeg compilation map, the
+  keyframe/ease vocabulary, the licensing note - stable and engine-neutral.
+- **`maggie-video` skill:** channel presets, caption/CTA safe-areas, the operational
+  ffmpeg command layer (via `maggie_video.py`), and tool wiring.