@topy-ai/maggie 0.8.11 → 0.8.12

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.11`,收尾 N 類影片功能:`maggie_video.py compile` 再補上視頻 clip ken-burns、sidechain ducking、以及非透明度 overlay 效果(move/slide、圖片 zoom),並新增 `autocut` 子命令(silencedetect 去靜音)。先前 0.8.10 新增圖片 ken-burns + 文字透明度關鍵幀與 `captions`(whisper)子命令。先前 0.8.9 新增 `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
+目前 npm 版本為 `0.8.12`,收尾其餘設計類:新增 `maggie-image`(影像處理 CLI:尺寸/OG/favicon/WebP-AVIF/svg/montage)與 web 動效、生成式視覺、圖像配方、字幕四個 reference。先前 0.8.11 收尾 N 類影片功能:`maggie_video.py compile` 再補上視頻 clip ken-burns、sidechain ducking、以及非透明度 overlay 效果(move/slide、圖片 zoom),並新增 `autocut` 子命令(silencedetect 去靜音)。先前 0.8.10 新增圖片 ken-burns + 文字透明度關鍵幀與 `captions`(whisper)子命令。先前 0.8.9 新增 `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 37 installable skills and a local-first MaggieDash foundation.
+package ships 38 installable skills and a local-first MaggieDash foundation.
 
-This package is `0.8.11` — `maggie_video.py compile` now also does video-clip ken-burns, sidechain ducking, and non-opacity overlay effects (move/slide, image zoom), and a new `autocut` subcommand removes silent gaps. `0.8.10` added image ken-burns + text opacity keyframes and the `captions` (whisper) subcommand. `0.8.9` added `compile` (declarative timeline JSON -> one ffmpeg command). `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.
+This package is `0.8.12` — adds `maggie-image` (process images via an ImageMagick recipe CLI) + references for web animation, generative visuals, image recipes, and captions. `0.8.11` - `maggie_video.py compile` now also does video-clip ken-burns, sidechain ducking, and non-opacity overlay effects (move/slide, image zoom), and a new `autocut` subcommand removes silent gaps. `0.8.10` added image ken-burns + text opacity keyframes and the `captions` (whisper) subcommand. `0.8.9` added `compile` (declarative timeline JSON -> one ffmpeg command). `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/captions-transcription.md

@@ -0,0 +1,41 @@
+# Captions and transcription
+
+Local, offline speech-to-text for video captions and transcripts, used by
+`maggie-video`'s `captions` subcommand. All engines run on the user's machine - **no
+paid API** - so transcription has no per-minute cost, only local CPU/GPU time.
+Distilled from the reference library's R-category projects.
+
+## Engines
+
+| Engine | What / how | License | Reach for it when |
+|---|---|---|---|
+| openai-whisper | The reference Python CLI: `whisper IN --model base --output_format srt --output_dir DIR` | MIT | the default; simplest install (`pip install openai-whisper`) |
+| whisper.cpp | C/C++ port, fast on CPU, GGML models: `whisper-cli -m model.bin -f IN -osrt -of OUTBASE` | MIT | no GPU / fastest CPU / embedding in a pipeline |
+| whisperX | whisper + forced alignment for **word-level timestamps** and diarization: `whisperx IN --model large-v3 --output_format srt --output_dir DIR` | BSD-4 | word-accurate caption timing or speaker labels |
+
+Model size trades speed for accuracy: `tiny` / `base` (fast, rough) -> `small` /
+`medium` -> `large-v3` (slow, best). Use `--lang` to skip auto-detect when known.
+
+## Workflow (voiceover -> captions -> on-screen)
+
+1. **Transcribe** the voiceover or the video's audio to SRT with a local engine
+   (`maggie_video.py captions --input vo.mp3 --output vo.srt --engine whisper
+   --model base`). A larger model is slower but more accurate.
+2. **Review** the SRT - never ship an unreviewed transcript; whisper mishears names,
+   numbers, and brand terms. A human edits it.
+3. **Put it on screen**, one of:
+   - burn in (`maggie_video.py subtitle --input video.mp4 --srt vo.srt --output out.mp4`),
+   - soft-mux a toggleable track (`subtitle --soft`), or
+   - a `captions` layer in a `maggie_video.py compile` timeline (see
+     [video timeline model](video-timeline-model.md)).
+
+## Rules
+
+- Captions lift watch time and serve sound-off viewing - caption every social video.
+- **Never fabricate a transcript**; generate it from the real audio and have a human
+  review before publishing (accuracy, names, and brand terms).
+- Local/offline: no audio leaves the machine, no paid API. If a hosted transcription
+  API is ever wired in instead, the global spend-first rule applies - state the cost.
+- Keep caption text inside the safe area (see `maggie-video` channel presets).
+
+See `maggie-video` for the subcommands and the burn-in / soft-mux / compile options.

package/bundled-references/generative-visuals.md

@@ -0,0 +1,90 @@
+# Generative visuals (creative coding)
+
+Patterns for generating marketing visuals in code - hero backgrounds, textures, 3D
+product shots, data-viz, and stylized images - distilled from the leading creative-
+coding libraries. We adopt **patterns, not code**. Output becomes a deliverable as a
+**still** (canvas/SVG export) or a **loop** (captured via
+[design-motion production](design-motion-production.md) Part C or
+[ffmpeg recipes](ffmpeg-recipes.md), then assembled in `maggie-video`). Determinism
+by seeding matches `maggie-spirit`'s philosophy: same seed -> same pixels.
+
+## Libraries
+
+| Library | What / model | Lang | License | Marketing fit |
+|---|---|---|---|---|
+| three.js | WebGL 3D: Scene + Camera + WebGLRenderer; `renderer.render(scene,camera)` in a loop | JS | MIT | 3D product spins, logo stings, depth-y hero backgrounds |
+| Babylon.js | Higher-level 3D engine (PBR, asset pipeline); heavier | JS/TS | Apache-2.0 | 3D product config; alt to three when its pipeline earns the weight |
+| react-three-fiber | three.js as React JSX (`<mesh><boxGeometry/>…`), `useFrame` | JS/TS | MIT | 3D on a React site |
+| p5.js | Canvas sketch: `setup()` once + `draw()` per frame; `random()/noise()` with `randomSeed()/noiseSeed()` | JS | **LGPL-2.1** | generative hero backgrounds, flow fields, noise art |
+| paper.js | Vector scene graph (Path/Group), boolean ops, hit-testing | JS | MIT | editable vector hero art, print-quality SVG |
+| two.js | One 2D API across SVG/Canvas/WebGL renderers | JS | MIT | vector art you want to export as SVG or capture from canvas |
+| rough.js | Hand-drawn/sketchy shapes; `{seed}` = reproducible | JS/TS | MIT | approachable hand-made brand style, doodle accents |
+| zdog | Pseudo-3D round/flat vector, designer-friendly | JS | MIT | cute 3D-ish icons, mascot/logo spins |
+| pts | Computational geometry (Space + Form + Pt) | TS/JS | Apache-2.0 | geometric/particle hero art |
+| hydra | Live-coded video synth (chained GLSL ops) | JS | **AGPL-3.0** | trippy animated backgrounds - **pattern only, do not ship its code** |
+| regl | Functional WebGL (stateless draw commands) | JS | MIT | custom shader backgrounds/gradients when three is overkill |
+| d3 | Data-driven SVG (scales + selections) | JS | ISC | bespoke infographics - but defer standard charts to the `dataviz` skill |
+| fogleman/primitive | Reproduce an image with N geometric primitives (CLI) | Go | MIT | stylize a product photo into abstract art (still or GIF) |
+| svg.js | Lightweight SVG DOM manipulation | JS | MIT | programmatic SVG icons/badges/dividers |
+| nannou | Rust creative framework (desktop) | Rust | MIT/Apache | note only - high-perf generative art in Rust |
+
+**License flags:** hydra is **AGPL-3.0**, p5 is **LGPL-2.1**, processing (non-core)
+is GPL - fine as *idea* sources, but do not vendor their code into shipped product;
+reimplement the pattern or use an MIT equivalent (two.js / pts / regl / svg.js).
+
+## Patterns and the deliverable path
+
+- **2D generative** (p5 / paper / two / rough / zdog / pts / svg.js): `setup()` once +
+  `draw()`/`update()` per frame. Use for brand-tinted hero/section backgrounds,
+  textures, doodle accents, geometric motifs. **Still:** SVG-capable libs serialize
+  their `<svg>` (crisp, editable, print-ready); canvas libs use `canvas.toDataURL()`
+  -> PNG. **Loop:** run the sketch headless and capture via design-motion Part C, or
+  in-browser with CCapture.js (MIT), then hand to `maggie-video`.
+- **3D** (three / babylon / r3f): Scene + Camera + Renderer; animate by frame index.
+  Product spins, 3D logo stings, depth-y backgrounds. **Still:**
+  `renderer.domElement.toDataURL()` (set `preserveDrawingBuffer:true`); **loop:** drive
+  by frame, capture as above. Prefer three/r3f (MIT); babylon only when needed.
+- **Data-viz** (d3): `d3-scale` + `d3-selection`; SVG is the native output. For
+  standard charts, **defer to the `dataviz` skill** (its palette/spec); pull in d3
+  only for bespoke marks (arc diagrams, force layouts, custom infographics).
+- **Live visuals** (hydra): chained feedback-graph ops -> animated GLSL. Renders to a
+  canvas -> capture -> `maggie-video`. **AGPL: idea only**; for an MIT shader
+  background use regl.
+- **Image -> primitives** (fogleman/primitive, MIT, Go CLI): stylize a photo into
+  abstract geometry.
+
+  ```bash
+  primitive -i input.png -o output.svg -n 100 -m 1
+  # -n shapes (50-200); -m mode (1 triangle,2 rect,3 ellipse,4 circle,6 beziers,8 polygon);
+  # output type by extension: PNG/JPG (raster), SVG (vector), GIF (animated, needs ImageMagick)
+  ```
+
+  **Still:** PNG/SVG directly; **loop:** `.gif` or `%d`-numbered PNG frames ->
+  `maggie-video`. It is randomized (no seed): generate once and **store the artifact**;
+  do not regenerate on every build.
+
+## Determinism
+
+p5 `randomSeed()/noiseSeed()`, rough.js `{seed}`, and a seeded PRNG in place of
+`Math.random` give byte-reproducible stills; the frame-index/virtual-clock rule from
+[programmatic video](programmatic-video.md) gives reproducible motion. `primitive`
+and `hydra` are non-deterministic - capture and store their output as a fixed asset.
+
+## Placement
+
+- **maggie-spirit** owns seeded brand marks/characters; borrow the 2D-canvas sketch
+  model and seed discipline for flat-vector mark construction (zdog/two.js/rough).
+  Generative *backgrounds/scenes* do not live here.
+- **maggie-design** owns generative hero backgrounds, section textures, 3D product
+  shots and image stylization as page/brand visuals; it points at this reference and
+  cross-links design-motion / `maggie-video` for capture-to-deliverable.
+- **Reference-only:** d3 (defer to `dataviz`), hydra (AGPL, idea only), regl, babylon,
+  nannou/processing/openFrameworks (desktop notes), svg.js.
+
+## Credits
+
+Patterns adapted (not code) from three.js, p5.js, d3, paper.js, two.js, rough.js,
+zdog, pts, hydra, regl, Babylon.js, react-three-fiber, fogleman/primitive, svg.js,
+nannou - licenses in the table above. Capture pipeline: see
+[programmatic video](programmatic-video.md), [design-motion production](design-motion-production.md),
+[ffmpeg recipes](ffmpeg-recipes.md).

package/bundled-references/image-recipes.md

@@ -0,0 +1,89 @@
+# Image recipes
+
+The distilled, correct image-processing command layer for marketing assets, used by
+`maggie-image`. These are the commands `maggie_image.py` generates. Distilled from
+ImageMagick, sharp, svgo, resvg, squoosh and imagemin (reference library category P).
+We **invoke binaries at arm's length** (adopt defaults, not code).
+
+**Tool posture.** ImageMagick (`magick` on IM7, else `convert`) is almost always
+present and covers nearly every raster op, so it is the **primary** path; dedicated
+tools (svgo, resvg, cwebp, avifenc, pngquant) are the **better-quality alternative
+used automatically when installed**. Web-delivery quality defaults follow sharp/
+squoosh: JPEG/WebP ~80, AVIF ~50. OG/social are **cover-cropped**; logos **pad**.
+Strip metadata on anything public (privacy + bytes).
+
+## Resize + fit (the most-used op)
+
+```bash
+# cover / crop to exactly WxH (fills the frame, center-crop)
+convert in.jpg -strip -resize 1200x630^ -gravity center -extent 1200x630 -quality 82 out.jpg
+# contain / letterbox with a pad color
+convert in.jpg -strip -resize 1200x630 -background '#ffffff' -gravity center -extent 1200x630 out.jpg
+# downscale-only (never enlarge): -resize 1200x630>
+```
+
+sharp's smart crop (`fit:'cover', position:attention`) avoids cutting off a face;
+ImageMagick has no equal, so for portraits prefer sharp when available.
+
+## WebP / AVIF (file-size wins)
+
+```bash
+convert in.png -strip -quality 80 -define webp:method=6 out.webp   # or: cwebp -q 80 -m 6 in.png -o out.webp
+convert in.png -strip -quality 50 out.avif                         # or: avifenc -s 6 --min 20 --max 40 in.png out.avif
+```
+
+## Channel / OG presets
+
+Cover-crop to the target: OG 1200x630, Twitter 1600x900, square 1080x1080, story/reel
+1080x1920, landscape 1920x1080, LinkedIn 1200x627, Pinterest 1000x1500. Same command
+as cover resize with the preset size, `-strip -quality 82`.
+
+## Favicon + OG set
+
+```bash
+convert in.png -define icon:auto-resize=64,48,32,16 favicon.ico      # multi-res .ico
+convert in.png -strip -resize 180x180 apple-touch-icon.png          # + 16/32/48/192/512 PNGs
+```
+
+## Strip metadata / compress
+
+```bash
+convert in.jpg -strip out.jpg                                        # drop EXIF/GPS/ICC
+convert in.jpg -strip -interlace Plane -quality 82 out.jpg           # progressive JPEG
+pngquant --quality 60-82 --strip --output out.png in.png            # lossy PNG (best); IM fallback: -colors 256 -define png:compression-level=9
+```
+
+## SVG optimize / render
+
+```bash
+svgo --multipass -i in.svg -o out.svg      # keeps viewBox + title (responsive + a11y). If svgo absent, leave the SVG alone - never rasterize as a substitute.
+resvg -w 512 in.svg out.png                # best-fidelity SVG -> PNG (or rsvg-convert -w 512); IM fallback (-background none -density 384) is lower fidelity
+```
+
+## Montage / contact sheet (carousels, screenshot grids)
+
+```bash
+montage a.png b.png c.png -tile 3x -geometry 400x400+10+10 -background '#ffffff' sheet.jpg
+```
+
+## The CLI
+
+`maggie_image.py` generates each command above (and runs it with `--run` when the
+tool is on PATH; `--force-im` forces the ImageMagick path). It detects IM6 `convert`
+vs IM7 `magick`:
+
+```bash
+maggie tool maggie_image.py social --input hero.png --output og.jpg --preset og
+maggie tool maggie_image.py --run webp --input hero.png --output hero.webp --quality 80
+maggie tool maggie_image.py --run favicon --input logo.png --out-dir public/
+maggie tool maggie_image.py svg2png --input logo.svg --output logo.png --width 512
+maggie tool maggie_image.py presets
+```
+
+## Licenses
+
+Invoked at arm's length: ImageMagick (permissive), SVGO (MIT), resvg (MIT/Apache),
+sharp (Apache-2.0), squoosh codecs (Apache-2.0), imagemin (MIT), cwebp/avifenc
+(BSD). **Avoid vendoring code from** Upscayl (AGPL-3.0) - for AI upscaling invoke the
+separate `realesrgan-ncnn-vulkan` binary instead. sharp/squoosh quality defaults are
+adopted as the preset numbers.

package/bundled-references/web-animation-patterns.md

@@ -0,0 +1,364 @@
+# Web / UI animation patterns
+
+Engine-neutral motion vocabulary for marketing web pages, distilled from the leading
+open-source animation libraries. We adopt **patterns and per-library guidance, not
+code** — we rarely ship these libraries; we copy the technique (the eases, the
+IntersectionObserver reveal, the spring config, the Lottie workflow). Feeds
+`maggie-landing-page` (B7 motion + the mandatory tagline reveal) and
+`maggie-design-motion` (its *website* context).
+
+Rule of thumb: a marketing page needs **CSS transitions + IntersectionObserver +
+one tiny helper** far more often than a 30KB animation engine. Reach for a library
+only when the pattern below says so. Default is zero-dependency.
+
+---
+
+## 1. The libraries
+
+Each entry: what it is · core API shape (real snippet) · license · when to reach for it.
+
+### GSAP (greensock/GSAP) — v3.15
+Framework-agnostic JS animation engine: tweens, timelines, eases, plugins
+(ScrollTrigger, SplitText, MorphSVG, Flip, MotionPath). The gold standard for
+sequenced, scroll-driven work.
+```js
+gsap.registerPlugin(ScrollTrigger);
+const tl = gsap.timeline({ defaults: { ease: "power3.out", duration: 0.6 } });
+tl.from(".hero h1", { y: 40, opacity: 0 })
+  .from(".hero p",  { y: 24, opacity: 0 }, "-=0.3");   // overlap previous by 0.3s
+gsap.from(".card", {
+  scrollTrigger: { trigger: ".card", start: "top 80%", once: true },
+  y: 32, opacity: 0, stagger: 0.08,
+});
+```
+**License: custom "Standard no-charge license" (NOT MIT/OSI).** As of 2024 (Webflow)
+GSAP including all former Club plugins is 100% free for commercial use, but it is a
+proprietary license, not open source — flag it before bundling. CDN:
+`cdn.jsdelivr.net/npm/gsap@3.15/dist/gsap.min.js`.
+**Reach for it when:** a page needs a real timeline (chained, overlapping steps) or
+scroll-scrubbed sequencing beyond a one-shot reveal. Overkill for simple fades.
+
+### Motion / framer-motion (motiondivision/motion)
+Hybrid engine: a tiny imperative `animate()` for vanilla JS plus declarative
+`<motion.div>` for React/Vue. Uses the native WAAPI where possible (GPU, 120fps),
+springs, `scroll()`, `inView()`, layout transitions.
+```js
+import { animate, inView, scroll, stagger } from "motion";
+animate("#box", { x: 100, opacity: 1 }, { type: "spring", stiffness: 300, damping: 30 });
+inView(".card", (el) => { animate(el, { opacity: 1, y: 0 }); }, { amount: 0.3 });
+// React: <motion.div initial={{opacity:0,y:24}} whileInView={{opacity:1,y:0}} viewport={{once:true}}/>
+```
+**License: MIT** (core; a paid "Motion+" add-on exists but isn't required).
+**Reach for it when:** the project is already React/Vue, or you want springs +
+scroll + inView from one small MIT lib. `inView` is a clean IntersectionObserver
+wrapper — our preferred engine when a dependency is acceptable.
+
+### anime.js (juliangarnier/anime) — v4
+Small, elegant timeline/stagger/easing lib. V4 is ESM tree-shakable.
+```js
+import { animate, stagger } from "animejs";
+animate(".square", {
+  x: 320, rotate: { from: -180 }, duration: 1250,
+  delay: stagger(65, { from: "center" }), ease: "inOutQuint",
+});
+```
+**License: MIT.** **Reach for it when:** you want expressive staggers/keyframes
+lighter than GSAP and don't need ScrollTrigger-grade scroll control.
+
+### lottie-web (airbnb/lottie-web)
+Plays **Lottie JSON** (vector animations exported from After Effects via Bodymovin)
+in the browser as SVG/canvas/HTML.
+```js
+const anim = lottie.loadAnimation({
+  container: el, renderer: "svg", loop: true, autoplay: true,
+  path: "hero.json",                       // or animationData: <obj>
+});
+anim.playSegments([0, 60], true);          // play part of the timeline
+anim.setSpeed(1); anim.pause();
+```
+**License: MIT.** **Reach for it when:** a designer delivers an AE/Lottie file and
+you need a crisp, scalable, small looped illustration (see §2 Lottie workflow).
+Default to `renderer: "svg"`; switch to `canvas` for heavy/many-layer files.
+
+### rlottie (Samsung/rlottie)
+Native (C++) Lottie renderer — the runtime behind Lottie on native/embedded (not a
+web lib). Category O. **License: MIT** (mostly; some vendored parts differ, see
+COPYING). **Reach for it when:** the same Lottie JSON must also play in a native app
+(our Expo/RN surfaces) — same asset, native renderer. On web it's lottie-web.
+
+### theatre.js (theatre-js/theatre)
+In-browser motion-design **editor**: scrub a timeline, keyframe any JS object's
+props, then play the saved sequence at runtime via `@theatre/core`.
+```js
+import { getProject } from "@theatre/core";
+const sheet = getProject("Hero").sheet("Intro");
+const obj = sheet.object("Logo", { x: 0, opacity: 0 });
+obj.onValuesChange((v) => { el.style.transform = `translateX(${v.x}px)`; el.style.opacity = v.opacity; });
+sheet.sequence.play({ iterationCount: 1 });
+```
+**License: Apache-2.0.** **Reach for it when:** a complex bespoke sequence is easier
+to hand-author on a timeline than in code. Niche for marketing pages; mostly a
+design-time tool. Note for `maggie-design-motion`, not landing pages.
+
+### auto-animate (formkit/auto-animate)
+Zero-config: one call and children added/removed/moved animate automatically.
+```js
+import autoAnimate from "@formkit/auto-animate";
+autoAnimate(document.getElementById("list"));   // React: const [ref] = useAutoAnimate()
+```
+**License: MIT.** **Reach for it when:** lists, filters, accordions, or reordering UI
+need smooth transitions with no keyframes. Great low-effort polish for interactive
+sections (pricing toggles, FAQ, filtered galleries).
+
+### AOS (michalsnik/aos)
+Animate-on-scroll via HTML data-attributes + a prebuilt CSS set.
+```html
+<div data-aos="fade-up" data-aos-delay="50" data-aos-duration="800"
+     data-aos-once="true" data-aos-anchor-placement="top-center"></div>
+<script>AOS.init({ once: true, duration: 800, easing: "ease-out-cubic" });</script>
+```
+**License: MIT.** Uses IntersectionObserver internally. **Reach for it when:** a
+no-JS-authoring team wants declarative scroll reveals fast. For our output we
+usually hand-roll the same effect (§2) rather than ship AOS, but its attribute
+vocabulary (`fade-up`, `once`, per-element delay/offset) is the pattern to copy.
+
+### typed.js (mattboldt/typed.js)
+Typewriter effect.
+```js
+const typed = new Typed("#el", { strings: ["First.", "& second."], typeSpeed: 50, backSpeed: 30, loop: true });
+```
+**License: GPL — flag it.** GNU GPL, not MIT. Do **not** bundle into proprietary
+output; reimplement the ~20-line effect yourself (or use a permissive alt) if you
+need typing. **Reach for the pattern when:** a hero rotates through phrases. Keep it
+short, respect reduced-motion (render the final string statically).
+
+### tsparticles (tsparticles/tsparticles)
+Config-driven particle backgrounds/confetti.
+```js
+await tsParticles.load({ id: "tsparticles", options: {
+  background: { color: "#0d1117" },
+  particles: { number: { value: 60 }, move: { enable: true } },
+}});
+```
+**License: MIT.** **Reach for it when:** a hero wants a subtle particle/constellation
+backdrop or a celebratory confetti burst. Use sparingly — it's a performance and
+taste liability; cap particle count, pause offscreen, disable on reduced-motion.
+
+### rive (rive-app/rive-runtime)
+Interactive vector animations driven by **state machines** (inputs → states), not
+just linear playback. `rive-runtime` is the C++ core; on web you use `@rive-app/canvas`.
+```js
+import { Rive } from "@rive-app/canvas";
+const r = new Rive({ src: "button.riv", canvas, autoplay: true,
+  stateMachines: "State Machine 1", onLoad: () => r.resizeDrawingSurfaceToCanvas() });
+r.stateMachineInputs("State Machine 1").find(i => i.name === "hover").value = true;
+```
+**License: MIT.** **Reach for it when:** an element must *react* (hover/click/scroll
+drives animation state) — interactive mascots, animated toggles. Heavier workflow
+(needs the Rive editor); overkill for passive decoration — prefer Lottie for that.
+
+### vivus (maxwellito/vivus)
+Animates SVG stroke draw-on ("self-drawing" line art).
+```js
+new Vivus("my-svg", { type: "oneByOne", duration: 200, start: "inViewport" }, cb);
+// type: delayed | sync | oneByOne | scenario ; start: inViewport | manual | autostart
+```
+**License: MIT.** **Reach for it when:** a logo/icon/diagram should draw itself in.
+The same effect is achievable with CSS `stroke-dasharray`/`stroke-dashoffset` — use
+that for one element, Vivus when orchestrating many paths.
+
+### lenis (darkroomengineering/lenis)
+Smooth-scroll normalizer (momentum/eased scrolling). Already referenced by
+`maggie-clone`.
+```js
+const lenis = new Lenis({ autoRaf: true });     // or drive lenis.raf(t) in your own rAF
+lenis.on("scroll", (e) => {/* sync scroll-linked effects */});
+```
+**License: MIT.** **Reach for it when:** the design calls for premium eased scrolling
+and you pair it with scroll-triggered motion (commonly `lenis.raf` + GSAP
+ScrollTrigger). Accessibility caveat: disable/reduce under `prefers-reduced-motion`;
+never trap or override scroll in a way that breaks keyboard/anchor jumps.
+
+### barba.js (barbajs/barba)
+SPA-style page transitions over MPAs: intercepts navigation, animates the old
+container out and the new one in (no full reload).
+```js
+barba.init({ transitions: [{
+  name: "fade",
+  leave: ({ current }) => gsap.to(current.container, { opacity: 0 }),
+  enter: ({ next })    => gsap.from(next.container, { opacity: 0 }),
+}]});
+// markup: <main data-barba="wrapper"><section data-barba="container" data-barba-namespace="home">
+```
+**License: MIT.** **Reach for it when:** a multi-page marketing site wants seamless
+cross-page transitions. Needs care for SEO/analytics/scroll-restore; often more than
+a landing page needs.
+
+### react-spring (pmndrs/react-spring)
+Spring-physics animation for React (hooks).
+```js
+import { animated, useSpring } from "@react-spring/web";
+const styles = useSpring({ from: { opacity: 0, y: 24 }, to: { opacity: 1, y: 0 } });
+return <animated.div style={styles}>…</animated.div>;
+```
+**License: MIT.** **Reach for it when:** a React project wants physics-based
+(not duration-based) motion. For non-React, Motion's `spring` covers the same need.
+
+### animate.css (animate-css/animate.css)
+Prebuilt CSS keyframe classes (`animate__animated animate__fadeInUp`).
+```html
+<h1 class="animate__animated animate__fadeInUp">Hi</h1>
+```
+**License: Hippocratic License 2.1 — flag it (NOT MIT).** An ethical-source license
+with use restrictions; not OSI-approved. Treat as a caution for commercial bundling;
+the keyframe recipes (`fadeInUp`, durations, timing) are fine to **reimplement**
+yourself. **Reach for the patterns when:** you want a quick named-entrance
+vocabulary — but author your own keyframes to stay license-clean.
+
+### Category O (offline / desktop, NOT web)
+- **synfig** (synfig/synfig) — desktop 2D vector animation studio. **GPL-3.0.**
+- **friction** (friction2d/friction) — desktop motion-graphics/vector animator.
+  **GPL-3.0.** Sparse docs.
+Both are authoring tools, not runtimes. Note as offline/GPL; they can *produce*
+assets (e.g. exported video/sequences) but nothing here ships to the web.
+
+---
+
+## 2. Engine-neutral pattern set (what we actually adopt)
+
+For each pattern: the technique, which libs embody it, and where it belongs
+(**LP** = `maggie-landing-page`, **DM** = `maggie-design-motion` website context).
+
+### Eased entrances — the good cubic-beziers
+Default to expressive ease-out curves, never browser defaults (`ease`, `linear`,
+`ease-in-out`). House base curve: `cubic-bezier(0.22, 1, 0.36, 1)` ("ease-out-quint",
+~500ms for layout/position; GSAP's `power3/power4.out` equivalent). Hover
+color/opacity 300ms (never < 200ms). Other good ones: `cubic-bezier(0.16,1,0.3,1)`
+(ease-out-expo), `cubic-bezier(0.34,1.56,0.64,1)` (gentle back/overshoot).
+Libs: GSAP eases, anime `inOut*`, Motion. **LP + DM.**
+
+### Spring physics
+Duration-less, physics-based motion — natural for interactive/hover and anything
+that should feel tactile. Config shape is universal: `{ stiffness, damping, mass }`
+(Motion: `type:"spring", stiffness:300, damping:30`; react-spring: `config.gentle`).
+Libs: Motion `spring`, react-spring, GSAP (via plugins). **DM;** light touch on LP
+(mostly micro-interactions).
+
+### Scroll-reveal via IntersectionObserver — never scroll listeners
+Elements rise ~32px and fade over 600–800ms, **once**, when they cross into view.
+Always IntersectionObserver (or a lib that wraps it); never an unthrottled `scroll`
+listener. Engine-neutral baseline (no dependency):
+```js
+const io = new IntersectionObserver((entries) => {
+  for (const e of entries) if (e.isIntersecting) {
+    e.target.classList.add("in");           // CSS transitions transform+opacity
+    io.unobserve(e.target);                 // once
+  }
+}, { threshold: 0.2, rootMargin: "0px 0px -10% 0px" });
+document.querySelectorAll("[data-reveal]").forEach((el) => io.observe(el));
+```
+Libs that embody it: Motion `inView`, AOS (`data-aos` + `once`), GSAP ScrollTrigger
+(`once:true`). **LP (core) + DM.**
+
+### Stagger
+Sequence a group so items arrive one after another (reading order), stepped
+~60–80ms, capped (~400ms total for menus). Libs: GSAP `stagger`, anime
+`stagger(65,{from:"center"})`, Motion `stagger`. Hand-rolled: per-item
+`transition-delay: calc(var(--i) * 60ms)`. **LP (menu entrance, card grids) + DM.**
+
+### SVG draw-on
+Line art draws itself via `stroke-dasharray`/`stroke-dashoffset` animated to 0.
+Libs: Vivus (`type:"oneByOne"`), or pure CSS for a single path. **DM (logos,
+diagrams);** occasional LP hero accent.
+
+### Typing
+Rotate/type phrases in a hero. Pattern: type → pause → delete → next, respect
+reduced-motion by rendering the final string. Lib: typed.js (**GPL — reimplement**,
+don't bundle). **LP (hero headline variants) + DM.**
+
+### Page transitions + smooth scroll
+Cross-page: animate container out/in instead of a hard reload (barba.js, or a
+framework's view-transitions). Smooth scroll: eased momentum scrolling (lenis),
+commonly paired with scroll-triggered motion (`lenis.raf` → GSAP ScrollTrigger).
+**DM / full-site builds;** a single landing page rarely needs barba. Lenis already
+used by `maggie-clone`.
+
+### Particles
+Subtle generative backdrop or confetti. Lib: tsparticles (config: `particles.number`,
+`move`, `background`). Use sparingly; cap count, pause offscreen, kill on
+reduced-motion. **LP hero (optional accent) + DM.**
+
+### The Lottie workflow
+Pipeline: **design in After Effects → export with Bodymovin → `.json` →** play with
+**lottie-web** on web / **rlottie** on native (same JSON asset, two renderers).
+```js
+lottie.loadAnimation({ container: el, renderer: "svg", loop: true, autoplay: true, path: "hero.json" });
+```
+**When to use Lottie vs code vs looped video:**
+- **Lottie** — designer-authored vector illustration/icon motion; scalable, crisp,
+  small, loopable, recolorable, interactive (segments/speed). The default for
+  "animated illustration." Prefer `renderer:"svg"`; use `canvas` for heavy files.
+- **Code (CSS/GSAP/Motion)** — UI motion tied to the DOM: entrances, hovers,
+  scroll reveals, state changes. Anything that must respond to layout/interaction.
+- **Looped video (mp4/webm)** — photographic/complex/3D content that isn't vector
+  and doesn't need interaction or recolor. Heaviest payload; provide a poster and
+  `prefers-reduced-motion` fallback. (See `references/programmatic-video.md`.)
+Libs: lottie-web (web), rlottie (native). **DM (primary);** LP for a hero/spot
+illustration when a designer supplies the JSON.
+
+---
+
+## 3. Performance & accessibility rules (shared by all of them)
+
+- **Animate only `transform` and `opacity`.** Never `top`/`left`/`width`/`height`/
+  `margin` (they trigger layout/paint and jank). Use `transform: translate/scale`
+  for position and size. Prefer the compositor; add `will-change` only on the
+  element about to animate, and remove it after.
+- **No scroll/resize listeners for reveal.** Use IntersectionObserver for visibility
+  and `requestAnimationFrame` for any per-frame work; throttle/debounce the rest.
+  Never run animation logic directly in a `scroll` handler.
+- **Respect `prefers-reduced-motion`.** Replace movement with a plain opacity change
+  (or show the final state instantly). Gate every nontrivial effect:
+  ```css
+  @media (prefers-reduced-motion: reduce) {
+    *, *::before, *::after { animation-duration:.01ms!important;
+      animation-iteration-count:1!important; transition-duration:.01ms!important; }
+  }
+  ```
+  In JS, branch on `matchMedia("(prefers-reduced-motion: reduce)").matches` before
+  typing, particles, smooth-scroll, or autoplay loops.
+- **Reveal once; don't re-fire** on scroll-back (`once:true` / `unobserve`).
+- **Pause offscreen / on hidden tab** (Lottie, particles, video): check
+  `document.hidden` / IntersectionObserver and stop rAF to save battery/CPU.
+- **Keep durations honest:** entrances 300–800ms; hovers 200–300ms; never block
+  interaction or delay content paint behind an animation. Don't animate above the
+  fold in a way that hides LCP text.
+
+---
+
+## License quick-reference
+
+| Library | License | Note |
+|---|---|---|
+| GSAP | Custom "no-charge" | **Not OSI/MIT.** Free (incl. all plugins) but proprietary — flag before bundling. |
+| Motion / framer-motion | MIT | Paid Motion+ add-on optional, not required. |
+| anime.js | MIT | |
+| lottie-web | MIT | |
+| rlottie | MIT | Some vendored parts differ (see COPYING). |
+| theatre.js | Apache-2.0 | |
+| auto-animate | MIT | |
+| AOS | MIT | |
+| typed.js | **GPL** | **Flag — don't bundle in proprietary output; reimplement.** |
+| tsparticles | MIT | |
+| rive-runtime | MIT | Web runtime is `@rive-app/canvas`. |
+| vivus | MIT | |
+| lenis | MIT | |
+| barba.js | MIT | |
+| react-spring | MIT | |
+| animate.css | **Hippocratic 2.1** | **Flag — ethical-source, not OSI. Reimplement keyframes.** |
+| synfig / friction | GPL-3.0 | Desktop authoring tools (category O), not web runtimes. |
+
+Most are MIT and safe to reference/learn from freely. The four to flag: **GSAP**
+(proprietary no-charge), **typed.js** (GPL), **animate.css** (Hippocratic 2.1), and
+**synfig/friction** (GPL desktop tools). For the flagged ones we adopt the *pattern*
+and author our own code.